diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 2e66e1d..30fe623 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -75,34 +75,34 @@ Shipped 2026-02-02. | Requirement | Phase | Status | |-------------|-------|--------| -| SEC-01 | TBD | Pending | -| SEC-02 | TBD | Pending | -| SEC-03 | TBD | Pending | -| SEC-04 | TBD | Pending | -| API-01 | TBD | Pending | -| API-02 | TBD | Pending | -| API-03 | TBD | Pending | -| API-04 | TBD | Pending | -| KEY-01 | TBD | Pending | -| KEY-02 | TBD | Pending | -| KEY-03 | TBD | Pending | -| KEY-04 | TBD | Pending | -| KEY-05 | TBD | Pending | -| BAT-01 | TBD | Pending | -| BAT-02 | TBD | Pending | -| BAT-03 | TBD | Pending | -| BAT-04 | TBD | Pending | -| BAT-05 | TBD | Pending | -| BAT-06 | TBD | Pending | -| UNR-01 | TBD | Pending | -| ENV-01 | TBD | Pending | -| ENV-02 | TBD | Pending | +| API-01 | Phase 6 | Pending | +| API-02 | Phase 6 | Pending | +| API-03 | Phase 6 | Pending | +| API-04 | Phase 6 | Pending | +| SEC-01 | Phase 7 | Pending | +| SEC-02 | Phase 7 | Pending | +| SEC-03 | Phase 7 | Pending | +| SEC-04 | Phase 7 | Pending | +| KEY-01 | Phase 8 | Pending | +| KEY-02 | Phase 8 | Pending | +| KEY-03 | Phase 8 | Pending | +| KEY-04 | Phase 8 | Pending | +| KEY-05 | Phase 8 | Pending | +| BAT-01 | Phase 9 | Pending | +| BAT-02 | Phase 9 | Pending | +| BAT-03 | Phase 9 | Pending | +| BAT-04 | Phase 9 | Pending | +| BAT-05 | Phase 9 | Pending | +| BAT-06 | Phase 9 | Pending | +| UNR-01 | Phase 10 | Pending | +| ENV-01 | Phase 10 | Pending | +| ENV-02 | Phase 10 | Pending | **Coverage:** - v1.1 requirements: 22 total -- Mapped to phases: 0 (pending roadmap) -- Unmapped: 22 +- Mapped to phases: 22 +- Unmapped: 0 --- *Requirements defined: 2026-02-02* -*Last updated: 2026-02-02 after initial definition* +*Last updated: 2026-02-02 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 4903b46..867ed68 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -2,11 +2,107 @@ ## Milestones -- **v1.0 Docker Control via Telegram** — Phases 1-5 (shipped 2026-02-02) → [Archive](milestones/v1.0-ROADMAP.md) +- **v1.0 Docker Control via Telegram** — Phases 1-5 (shipped 2026-02-02) -> [Archive](milestones/v1.0-ROADMAP.md) +- **v1.1 n8n Integration & Polish** — Phases 6-10 (in progress) -## Next Milestone +--- -(Not yet planned — run `/gsd:new-milestone` to define v1.1) +## v1.1: n8n Integration & Polish + +Enable faster development iteration via n8n API access, improve UX with inline keyboard buttons, add batch operations, and harden security by removing direct Docker socket exposure from n8n. + +### Phase 6: n8n API Access + +**Goal:** Claude Code can programmatically read, update, and test workflows + +**Dependencies:** None (enables faster iteration on all subsequent phases) + +**Requirements:** API-01, API-02, API-03, API-04 + +**Success Criteria:** +1. n8n API key exists and Claude Code can authenticate against the n8n API +2. Claude Code can retrieve the current workflow JSON via API call +3. Claude Code can push workflow changes via API and they take effect immediately +4. Claude Code can view execution history showing recent runs with success/failure status + +--- + +### Phase 7: Socket Security + +**Goal:** Docker operations flow through a filtered proxy instead of direct socket access + +**Dependencies:** Phase 6 (API access enables faster iteration on curl command migration) + +**Requirements:** SEC-01, SEC-02, SEC-03, SEC-04 + +**Success Criteria:** +1. Socket proxy container runs on internal network with Docker socket mounted +2. n8n container connects to proxy via TCP instead of mounting docker.sock directly +3. Dangerous Docker APIs (exec, create, build) return blocked/forbidden responses +4. All existing bot commands (status, start, stop, restart, update, logs) work identically through proxy + +--- + +### Phase 8: Inline Keyboard Infrastructure + +**Goal:** Users interact with containers via tappable buttons instead of typing commands + +**Dependencies:** Phase 7 (security in place before adding new features) + +**Requirements:** KEY-01, KEY-02, KEY-03, KEY-04, KEY-05 + +**Success Criteria:** +1. Status command returns a message with inline buttons showing available actions per container +2. Tapping an action button (start/stop/restart) executes that action on the target container +3. Dangerous actions (stop, restart, update) show a confirmation prompt before executing +4. During operation execution, the message updates to show progress (e.g., "Stopping plex...") +5. After action completes, buttons are removed and final status is shown in the message + +--- + +### Phase 9: Batch Operations + +**Goal:** Users can update multiple containers in a single command with clear feedback + +**Dependencies:** Phase 8 (keyboard infrastructure supports confirmation dialogs) + +**Requirements:** BAT-01, BAT-02, BAT-03, BAT-04, BAT-05, BAT-06 + +**Success Criteria:** +1. User can type "update plex sonarr radarr" and all three containers update sequentially +2. Each container shows individual progress/result as it completes (not waiting until all finish) +3. "Update all" command shows confirmation with list of containers before executing +4. If one container fails mid-batch, remaining containers still attempt to update +5. Final message shows summary: "3 updated, 1 failed" with details + +--- + +### Phase 10: Polish & Audit + +**Goal:** Clear Unraid update badges and verify environment configuration + +**Dependencies:** Phase 9 (core features complete before polish) + +**Requirements:** UNR-01, ENV-01, ENV-02 + +**Success Criteria:** +1. After bot successfully updates a container, Unraid UI no longer shows "update available" for that container +2. Documentation clarifies whether TELEGRAM_USERID env var is required or can be hardcoded +3. Documentation clarifies whether TELEGRAM_BOT_TOKEN env var is required or if n8n credential suffices + +--- + +## Progress + +| Phase | Name | Requirements | Status | +|-------|------|--------------|--------| +| 6 | n8n API Access | API-01, API-02, API-03, API-04 | Pending | +| 7 | Socket Security | SEC-01, SEC-02, SEC-03, SEC-04 | Pending | +| 8 | Inline Keyboard Infrastructure | KEY-01, KEY-02, KEY-03, KEY-04, KEY-05 | Pending | +| 9 | Batch Operations | BAT-01, BAT-02, BAT-03, BAT-04, BAT-05, BAT-06 | Pending | +| 10 | Polish & Audit | UNR-01, ENV-01, ENV-02 | Pending | + +**v1.1 Coverage:** 22/22 requirements mapped --- *Updated: 2026-02-02* diff --git a/.planning/STATE.md b/.planning/STATE.md index b4c0548..a574b9d 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -5,29 +5,49 @@ See: .planning/PROJECT.md (updated 2026-02-02) **Core value:** Immediate container control from your phone -**Current focus:** v1.0 shipped — planning next milestone +**Current focus:** v1.1 n8n API Access — enabling faster development iteration ## Current Position - **Milestone:** v1.1 — n8n Integration & Polish -- **Phase:** Not started (defining requirements) -- **Plan:** — -- **Status:** Defining requirements -- **Last activity:** 2026-02-02 — Milestone v1.1 started +- **Phase:** 6 — n8n API Access +- **Plan:** Not started +- **Status:** Ready for planning +- **Last activity:** 2026-02-02 — Roadmap created ## Progress ``` v1.1: [ ] 0% -Phases: TBD (creating roadmap) +Phase 6: n8n API Access [ ] Pending +Phase 7: Socket Security [ ] Pending +Phase 8: Inline Keyboard Infra [ ] Pending +Phase 9: Batch Operations [ ] Pending +Phase 10: Polish & Audit [ ] Pending ``` +## Accumulated Context + +### Key Decisions + +| Decision | Rationale | Phase | +|----------|-----------|-------| +| n8n API first | Enables faster iteration on all subsequent phases | 6 | + +### Todos + +- [ ] Plan Phase 6 (n8n API Access) + +### Blockers + +(none) + ## Session Continuity - **Last session:** 2026-02-02 -- **Stopped at:** Defining v1.1 requirements -- **Next step:** Define requirements → create roadmap +- **Stopped at:** Roadmap created for v1.1 +- **Next step:** `/gsd:plan-phase 6` to plan n8n API Access --- *Auto-maintained by GSD workflow*