Do Siki
f918e300a6
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.
131 lines
3.2 KiB
Markdown
131 lines
3.2 KiB
Markdown
# 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
|