diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index f0079b3..bd6710b 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -35,9 +35,11 @@ When you get a container update notification or notice a service is down, you ca **Milestone v1.2: Modularization & Polish** - [ ] Workflow modularization (break main workflow into sub-workflows) -- [ ] Environment variable audit (verify TELEGRAM_USERID/BOT_TOKEN necessity) +- [ ] Update all containers via text command and inline keyboard +- [ ] Fix callback data limits (batch selection >2 containers, long names) - [ ] Unraid update sync (clear "update available" when bot updates container) -- [ ] Telegram webhook fix (bot responds when workflow is published) +- [ ] Environment variable audit (verify TELEGRAM_USERID/BOT_TOKEN necessity) +- [ ] Documentation update (proxy architecture, new features) ### Out of Scope @@ -93,14 +95,15 @@ When you get a container update notification or notice a service is down, you ca ## Current Milestone: v1.2 Modularization & Polish -**Goal:** Complete remaining v1.1 scope — modularize workflow for maintainability, fix webhook, audit environment, sync Unraid badges. +**Goal:** Modularize workflow for maintainability, add "update all" functionality, fix callback limits, and polish remaining issues. **Target features:** -- Workflow modularization (carried from Phase 9.1) -- Webhook fix (WEB-01) -- Environment audit (ENV-01, ENV-02) +- Workflow modularization into sub-workflows +- "Update all" command (text and inline keyboard) +- Callback data limit fix (batch selection, long names) - Unraid badge sync (UNR-01) -- Documentation overhaul +- Environment audit (ENV-01, ENV-02) +- Documentation overhaul (proxy architecture) --- *Last updated: 2026-02-04 after v1.1 milestone* diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..0b83564 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,118 @@ +# Requirements: Unraid Docker Manager + +**Defined:** 2026-02-04 +**Core Value:** When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone. + +## v1.0 Requirements (Validated) + +### Core Commands + +- ✓ **CMD-01**: User can send a message to the bot and receive a response — v1.0 +- ✓ **CMD-02**: User can check container status via "status" command — v1.0 +- ✓ **CMD-03**: User can start a container by name — v1.0 +- ✓ **CMD-04**: User can stop a container by name — v1.0 +- ✓ **CMD-05**: User can restart a container by name — v1.0 +- ✓ **CMD-06**: User can update a container (pull new image, recreate) — v1.0 +- ✓ **CMD-07**: User can view container logs with configurable line count — v1.0 + +### Security + +- ✓ **SEC-01**: Bot only responds to configured Telegram user ID — v1.0 + +## v1.1 Requirements (Validated) + +### n8n API + +- ✓ **API-01**: n8n API access for programmatic workflow management — v1.1 + +### Docker Security + +- ✓ **SEC-02**: Docker socket access via filtered proxy (no direct socket mount) — v1.1 + +### Inline Keyboard UX + +- ✓ **UX-01**: Container list with pagination via inline keyboard — v1.1 +- ✓ **UX-02**: Action buttons for container operations — v1.1 +- ✓ **UX-03**: Confirmation dialogs for dangerous actions (stop, update) — v1.1 +- ✓ **UX-04**: Progress feedback via message edits during operations — v1.1 + +### Batch Operations + +- ✓ **BATCH-01**: Batch start multiple containers at once — v1.1 +- ✓ **BATCH-02**: Batch stop multiple containers at once — v1.1 +- ✓ **BATCH-03**: Batch restart multiple containers at once — v1.1 + +## v1.2 Requirements (Active) + +### Modularization + +- [ ] **MOD-01**: Main workflow broken into logical sub-workflows for maintainability +- [ ] **MOD-02**: Sub-workflows callable from main workflow without duplication + +### Batch Updates + +- [ ] **BATCH-04**: User can update all containers with :latest tag via text command ("update all") +- [ ] **BATCH-05**: User can update all containers with :latest tag via inline keyboard +- [ ] **BATCH-06**: Batch selection keyboard supports selecting more than 2 containers +- [ ] **BATCH-07**: Batch selection keyboard supports containers with long names + +### Unraid Integration + +- [ ] **UNR-01**: After bot updates a container, Unraid UI no longer shows "update available" for that container + +### Environment & Config + +- [ ] **ENV-01**: Documentation clarifies TELEGRAM_USERID env var necessity (required vs hardcoded) +- [ ] **ENV-02**: Documentation clarifies TELEGRAM_BOT_TOKEN env var necessity (env var vs n8n credential) + +### Technical Debt + +- [ ] **DEBT-01**: README documents proxy architecture (not direct docker.sock mounting) +- [ ] **DEBT-02**: Fix duplicate --max-time flags in image pull command +- [ ] **DEBT-03**: Consolidate duplicated update flow between single and batch paths + +## v2+ Requirements (Deferred) + +### Resource Monitoring + +- **RES-01**: User can query resource usage ("what's using the most memory?") + +### Notifications + +- **NOTF-01**: Bot proactively notifies when containers have updates available + +## Out of Scope + +| Feature | Reason | +|---------|--------| +| Take over Unraid notifications | Keep existing notification system, bot is for control | +| Deploy new containers | Manage existing only, not create new ones | +| Natural language understanding | Simple keyword matching sufficient, Claude API adds complexity | +| Proactive monitoring | Bot is reactive (you ask, it answers) | +| Mobile app | Telegram is the interface | + +## Traceability + +| Requirement | Phase | Status | +|-------------|-------|--------| +| MOD-01 | Phase 10 | Pending | +| MOD-02 | Phase 10 | Pending | +| BATCH-04 | Phase 10 | Pending | +| BATCH-05 | Phase 10 | Pending | +| BATCH-06 | Phase 10 | Pending | +| BATCH-07 | Phase 10 | Pending | +| UNR-01 | Phase 11 | Pending | +| ENV-01 | Phase 11 | Pending | +| ENV-02 | Phase 11 | Pending | +| DEBT-01 | Phase 12 | Pending | +| DEBT-02 | Phase 11 | Pending | +| DEBT-03 | Phase 10 | Pending | + +**Coverage:** +- v1.2 requirements: 12 total +- Mapped to phases: 12 +- Unmapped: 0 ✓ + +--- +*Requirements defined: 2026-02-04* +*Last updated: 2026-02-04 after v1.2 milestone initialization* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index c7f7ad0..f1eaa0a 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -10,15 +10,15 @@ ## v1.2: Modularization & Polish -Complete remaining v1.1 scope: modularize workflow for maintainability, fix webhook issues, audit environment variables, and clear Unraid update badges. +Modularize the workflow for maintainability, add "update all" functionality, fix callback data limits, and polish remaining issues. -### Phase 10: Workflow Modularization +### Phase 10: Workflow Modularization & Update All -**Goal:** Break main workflow into modular sub-workflows for maintainability +**Goal:** Break main workflow into modular sub-workflows and add "update all" functionality with improved callback data handling **Dependencies:** None -**Requirements:** TBD (carried from Phase 9.1) +**Requirements:** MOD-01, MOD-02, BATCH-04, BATCH-05, BATCH-06, BATCH-07, DEBT-03 **Plans:** 0 plans @@ -26,17 +26,23 @@ Plans: - [ ] TBD (run /gsd:plan-phase 10 to break down) **Success Criteria:** -[To be defined during planning] +1. Workflow split into logical sub-workflows (command routing, container operations, keyboard generation, etc.) +2. Sub-workflows callable from main without code duplication +3. User can type "update all" to update all :latest containers with confirmation +4. User can tap "Update All" in inline keyboard to update all :latest containers +5. Batch selection keyboard allows selecting 5+ containers without hitting callback limit +6. Containers with long names (20+ chars) can be selected in batch keyboard +7. Update flow consolidated between single and batch paths --- ### Phase 11: Polish & Audit -**Goal:** Clear Unraid update badges, fix webhook issues, verify environment configuration, and address v1.1 tech debt +**Goal:** Clear Unraid update badges, fix webhook issues, verify environment configuration, and fix remaining tech debt **Dependencies:** Phase 10 (modularization complete before polish) -**Requirements:** UNR-01, ENV-01, ENV-02, WEB-01 +**Requirements:** UNR-01, ENV-01, ENV-02, DEBT-02 **Plans:** 0 plans @@ -47,22 +53,17 @@ Plans: 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 -4. Telegram webhook works when workflow is published (bot responds without manual execute) - -**Tech Debt from v1.1 (to address):** -- README.md lines 14-34: Still documents direct docker.sock mounting (should document proxy architecture) -- Duplicate --max-time flags in image pull command (600 then 5, last wins — should keep only 600s) -- Update flow duplicated between single and batch paths (consolidation opportunity) +4. Image pull command has single --max-time flag (600s) --- ### Phase 12: Documentation Overhaul -**Goal:** [To be planned] +**Goal:** Update README and documentation to reflect current architecture and features **Dependencies:** Phase 11 (core features complete before documentation) -**Requirements:** TBD +**Requirements:** DEBT-01 **Plans:** 0 plans @@ -70,7 +71,9 @@ Plans: - [ ] TBD (run /gsd:plan-phase 12 to break down) **Success Criteria:** -[To be defined during planning] +1. README documents docker-socket-proxy architecture (not direct socket mount) +2. README documents all v1.2 features (update all, batch selection improvements) +3. Setup instructions verified accurate for clean install --- @@ -83,11 +86,11 @@ Plans: | 7 | Socket Security | v1.1 | Complete | | 8 | Inline Keyboard Infrastructure | v1.1 | Complete | | 9 | Batch Operations | v1.1 | Complete | -| 10 | Workflow Modularization | v1.2 | Pending | +| 10 | Workflow Modularization & Update All | v1.2 | Pending | | 11 | Polish & Audit | v1.2 | Pending | | 12 | Documentation Overhaul | v1.2 | Pending | -**v1.2 Coverage:** 4 requirements mapped (UNR-01, ENV-01, ENV-02, WEB-01), modularization TBD +**v1.2 Coverage:** 12 requirements mapped across 3 phases --- *Updated: 2026-02-04 after v1.1 milestone* diff --git a/.planning/STATE.md b/.planning/STATE.md index 87041d1..4b064bb 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -10,10 +10,10 @@ See: .planning/PROJECT.md (updated 2026-02-04) ## Current Position - **Milestone:** v1.2 — Modularization & Polish -- **Phase:** 10 of 12 (Workflow Modularization) +- **Phase:** 10 of 12 (Workflow Modularization & Update All) - **Plan:** Not started - **Status:** Ready to plan -- **Last activity:** 2026-02-04 — v1.1 milestone archived, tech debt added to Phase 11 +- **Last activity:** 2026-02-04 — v1.2 requirements formalized (12 requirements across 3 phases) ## Progress @@ -51,8 +51,8 @@ Recent v1.1 decisions: ### Known Limitations - **64-byte callback_data limit** — Affects batch selection and long container names -- **Batch update via inline keyboard** — Deferred to Phase 10 (needs modularization) -- **Webhook only works via manual execute** — WEB-01 in Phase 11 +- **Batch update via inline keyboard** — BATCH-05 in Phase 10 +- **Batch selection limited to 2 containers** — BATCH-06/07 in Phase 10 (callback data limit) ### Technical Debt @@ -67,7 +67,7 @@ Tracked in Phase 11: - **Last session:** 2026-02-04 - **Stopped at:** v1.1 milestone completion - **Resume file:** None -- **Next step:** `/gsd:new-milestone` to define v1.2 requirements and roadmap +- **Next step:** `/gsd:plan-phase 10` to break down modularization and update all --- *Auto-maintained by GSD workflow*