feat(plane): add Plane-TODO sync script

Add plane-sync.js one-way (Plane -> TODO.md) synchronization for the MITHOME project. Config reads from .mcp.json with .env override. CLI: --list, --dry-run, --yes, --project, --verbose, --help. Interactive discrepancy resolution (status mismatches, orphans, new issues), backup before write, rate limiting. Pure functions covered by node:test unit tests. Includes PLANE-SYNC-GUIDE.md and TODO.md changelog entry.
2026-08-17 12:18:55 +02:00
parent 3c79a64903
commit f918e300a6
11 changed files with 845 additions and 9 deletions
@@ -0,0 +1,130 @@
+# Plane Sync Guide
+
+## 🎯 **Cél**
+
+A `plane-sync.js` script a **Plane** (MITHOME projekt) és a **TODO.md** közötti egyirányú szinkronizációt biztosítja.
+
+- **Plane** = authoritative source (elsődleges forrás)
+- **TODO.md** = lokális tükörkép (csak referencia)
+- **Irány**: Plane → TODO.md (a Plane mindig nyer)
+
+---
+
+## 🚀 **Használat**
+
+### 1. Alap szinkron (interaktív)
+
+```bash
+node plane-sync.js
+```
+
+Ha eltérést talál, konzolon kérdez a feloldás módjáról.
+
+### 2. Előnézet (nem ír semmit)
+
+```bash
+node plane-sync.js --dry-run
+```
+
+### 3. Automatikus javítás (nem interaktív)
+
+```bash
+node plane-sync.js --yes
+```
+
+CI környezetben (nem TTY) automatikusan a `--yes` viselkedés aktív.
+
+### 4. Projektek listázása
+
+```bash
+node plane-sync.js --list
+```
+
+### 5. Egyéb opciók
+
+```bash
+node plane-sync.js --verbose      # részletes kimenet
+node plane-sync.js --project=<id> # projekt ID felülírása
+node plane-sync.js --help         # súgó
+```
+
+---
+
+## ⚙️ **Konfiguráció**
+
+**Precedencia**: `.env` > `.mcp.json` (`mcpServers.plane.env`)
+
+| Változó | Forrás | Leírás |
+| --- | --- | --- |
+| `PLANE_API_KEY` | `.mcp.json` / `.env` | Plane API kulcs |
+| `PLANE_API_HOST_URL` | `.mcp.json` / `.env` | Plane URL (alap: `https://pm.llmdev.mozdit.hu/`) |
+| `PLANE_WORKSPACE_SLUG` | `.mcp.json` / `.env` | Workspace slug (alap: `developments`) |
+| `PLANE_PROJECT_ID` | `.env` | Projekt ID (alap: MITHOME `643f7055-1237-4912-912f-99ec49fd0f0e`) |
+
+A kulcs elsődlegesen a `.mcp.json`-ban van (gitignore-olt) — a script ezt használja, így nincs duplikáció.
+
+---
+
+## 🔄 **Státusz Mapping**
+
+| Plane group | TODO.md szekció | Emoji |
+| --- | --- | --- |
+| `completed` | `## ✅ Befejezett` | ✅ |
+| `started` | `## 🔄 In Progress` | 🔄 |
+| `unstarted` | `## 🚀 TODO` | ⏳ |
+| `backlog` | `## 📋 Backlog` | 📋 |
+| `cancelled` | (nincs hely — csak riport) | — |
+
+---
+
+## ⚠️ **Eltérések Kezelése**
+
+A script háromféle eltérést ismer fel és interaktívan kérdez:
+
+1. **Státusz eltérés** (Plane ≠ TODO.md) — TODO.md frissítése a Plane szerint? *(ajánlott: igen)*
+2. **Orphan** (csak TODO.md-ben szerepel) — megtartás? *(ajánlott: igen)*
+3. **Új issue** (csak Plane-ben van) — hozzáadás a TODO.md-hez? *(ajánlott: igen)*
+
+---
+
+## 🔒 **Biztonsági Mentés**
+
+Írás előtt a script mindig biztonsági másolatot készít:
+
+```
+TODO.md.backup.<timestamp>
+```
+
+Ezek a fájlok a `.gitignore`-ban vannak.
+
+---
+
+## 🧪 **Tesztek**
+
+```bash
+node --test scripts/plane/plane-sync.test.js
+```
+
+Pure függvények (TODO.md parse, discrepancy detektálás, tábla generálás) natív `node:test`-tel teszteltek.
+
+---
+
+## 📂 **Kódstruktúra**
+
+```
+plane-sync.js               # CLI belépési pont (argok, help, sync flow)
+scripts/plane/config.js     # Config (.mcp.json + .env override)
+scripts/plane/client.js     # PlaneClient (API, rate limiting)
+scripts/plane/todo.js       # TODO.md parse + tábla generálás + regenerate
+scripts/plane/sync.js       # Discrepancy detektálás + final sections build
+scripts/plane/plane-sync.test.js  # Unit tesztek
+```
+
+---
+
+## 🔗 **Kapcsolódó Dokumentumok**
+
+- [README](./README.md)
+- [GitHub CI/CD Guide](./GITHUB-CICD-GUIDE.md)
+
+**Utolsó frissítés:** 2026-08-17