# 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