diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md index e653fe4..af92c9a 100644 --- a/.planning/MILESTONES.md +++ b/.planning/MILESTONES.md @@ -1,5 +1,30 @@ # Project Milestones: Unraid Docker Manager +## v1.1 n8n Integration & Polish (Shipped: 2026-02-04) + +**Delivered:** Inline keyboard UX and Docker security hardening — button-driven container control with filtered socket proxy. + +**Phases completed:** 6-9 (11 plans total) + +**Key accomplishments:** +- n8n API access for programmatic workflow management +- Docker socket proxy deployment removing direct socket exposure +- Inline keyboard with container list, pagination, and action buttons +- Batch operations with sequential execution and progress feedback +- Confirmation dialogs for dangerous actions (stop, update) + +**Stats:** +- 38 files modified (+14,062/-4,239 lines) +- 8,485 lines of JSON workflow +- 4 phases, 11 plans +- 2 days (2026-02-03 → 2026-02-04) + +**Git range:** `7e85697` → `fa7c603` + +**What's next:** v1.2 with workflow modularization, webhook fix, environment audit, and documentation. + +--- + ## v1.0 Docker Control via Telegram (Shipped: 2026-02-02) **Delivered:** Telegram bot for managing Docker containers on Unraid — status, start, stop, restart, update, logs via keyword commands. diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index ac2b4a0..f0079b3 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -2,7 +2,7 @@ ## What This Is -A Telegram bot that lets you manage Docker containers on your Unraid server. Control containers from your phone without needing to open a laptop — check status, view logs, start/stop/restart/update containers via simple keyword commands. +A Telegram bot that lets you manage Docker containers on your Unraid server via inline keyboard buttons and text commands. Control containers from your phone without needing to open a laptop — check status, view logs, start/stop/restart/update containers, batch operations on multiple containers at once. ## Core Value @@ -12,25 +12,32 @@ When you get a container update notification or notice a service is down, you ca ### Validated -- [x] Send a message to the bot and receive a response — v1.0 -- [x] Check container status ("status") — v1.0 -- [x] Start a container by name — v1.0 -- [x] Stop a container by name — v1.0 -- [x] Restart a container by name — v1.0 -- [x] Update a container (pull new image, recreate) — v1.0 -- [x] View container logs with configurable line count — v1.0 -- [x] Bot only responds to your Telegram user ID — v1.0 +**v1.0:** +- ✓ Send a message to the bot and receive a response — v1.0 +- ✓ Check container status ("status") — v1.0 +- ✓ Start a container by name — v1.0 +- ✓ Stop a container by name — v1.0 +- ✓ Restart a container by name — v1.0 +- ✓ Update a container (pull new image, recreate) — v1.0 +- ✓ View container logs with configurable line count — v1.0 +- ✓ Bot only responds to your Telegram user ID — v1.0 + +**v1.1:** +- ✓ n8n API access for Claude Code (programmatic workflow read/update/test/logs) — v1.1 +- ✓ Docker socket security (remove direct socket from internet-exposed n8n) — v1.1 +- ✓ Telegram inline keyboard buttons (container list with pagination and action buttons) — v1.1 +- ✓ Batch container operations (update/start/stop/restart multiple at once) — v1.1 +- ✓ Confirmation dialogs for dangerous actions (stop, update) — v1.1 +- ✓ Progress feedback during operations (message edits) — v1.1 ### Active -**Milestone v1.1: n8n Integration & Polish** +**Milestone v1.2: Modularization & Polish** -- [ ] n8n API access for Claude Code (programmatic workflow read/update/test/logs) -- [ ] Telegram inline keyboard buttons (work around n8n native node issues) -- [ ] Batch container updates (verify/fix multi-container update) -- [ ] Docker socket security (remove direct socket from internet-exposed n8n) +- [ ] Workflow modularization (break main workflow into sub-workflows) - [ ] Environment variable audit (verify TELEGRAM_USERID/BOT_TOKEN necessity) - [ ] Unraid update sync (clear "update available" when bot updates container) +- [ ] Telegram webhook fix (bot responds when workflow is published) ### Out of Scope @@ -42,16 +49,18 @@ When you get a container update notification or notice a service is down, you ca ## Current State -**Shipped:** v1.0 (2026-02-02) -**Tech stack:** n8n workflow + Telegram Bot API + Docker socket -**Files:** n8n-workflow.json (~3,200 lines), README.md +**Shipped:** v1.1 (2026-02-04) +**Tech stack:** n8n workflow + Telegram Bot API + Docker socket proxy +**Files:** n8n-workflow.json (~8,500 lines), README.md +**Architecture:** tecnativa/docker-socket-proxy filters Docker API access ## Context **Environment:** - Unraid server with Intel N100 CPU, 32GB RAM -- n8n container with Docker socket access +- n8n container with Docker socket proxy access (no direct socket mount) - Multiple Docker containers (Plex, Sonarr, lldap, etc.) +- docker-socket-proxy on dockernet network **Constraints:** - Platform: Unraid (Docker-based) @@ -59,6 +68,7 @@ When you get a container update notification or notice a service is down, you ca - Matching: Keyword/substring with exact-match priority - Auth: Single user via Telegram ID - Logs: Configurable line count, default 50, max 1000 +- Callback data: 64-byte Telegram limit (affects batch/selection features) ## Key Decisions @@ -72,19 +82,25 @@ When you get a container update notification or notice a service is down, you ca | Exact match priority | Prevents substring collisions (plex vs jellyplex) | ✓ Good | | Default to :latest tag | Prevents Docker API from pulling all tags | ✓ Good | | HTML escape logs | Log content may contain text | ✓ Good | -| Text menu over keyboard | Native Telegram node replyKeyboard had issues | ✓ Good | +| docker-socket-proxy for security | Filters dangerous APIs (exec, build, commit) at network level | ✓ Good | +| Container create API allowed | Update command needs container recreation | ✓ Good | +| Colon callback format | Compact format fits 64-byte limit | ✓ Good | +| editMessageText transitions | Clean UX with no message clutter | ✓ Good | +| 30-second confirmation timeout | Prevents stale confirmations | ✓ Good | +| Batch stop requires confirmation | Fuzzy matching risk for destructive operations | ✓ Good | +| Two-phase batch execution | Callbacks have names but no IDs - need lookup | ✓ Good | +| Update all filters to :latest | Performance optimization - full check would be slow | ✓ Good | -## Current Milestone: v1.1 n8n Integration & Polish +## Current Milestone: v1.2 Modularization & Polish -**Goal:** Enable faster development iteration via n8n API access, revisit UX improvements (buttons), and harden security (remove direct Docker socket exposure). +**Goal:** Complete remaining v1.1 scope — modularize workflow for maintainability, fix webhook, audit environment, sync Unraid badges. **Target features:** -- n8n API for Claude Code — programmatic workflow access -- Telegram inline keyboard buttons — better UX than text menus -- Batch container updates — update multiple at once -- Docker socket security — remove direct exposure -- Environment variable audit — verify what's needed -- Unraid update sync — clear notifications properly +- Workflow modularization (carried from Phase 9.1) +- Webhook fix (WEB-01) +- Environment audit (ENV-01, ENV-02) +- Unraid badge sync (UNR-01) +- Documentation overhaul --- -*Last updated: 2026-02-02 after starting v1.1 milestone* +*Last updated: 2026-02-04 after v1.1 milestone* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 85e0cf4..d7c9026 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -3,133 +3,46 @@ ## Milestones - **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) +- **v1.1 n8n Integration & Polish** — Phases 6-9 (shipped 2026-02-04) -> [Archive](milestones/v1.1-ROADMAP.md) +- **v1.2 Modularization & Polish** — Phases 10-12 (planned) --- -## v1.1: n8n Integration & Polish +## v1.2: Modularization & 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. +Complete remaining v1.1 scope: modularize workflow for maintainability, fix webhook issues, audit environment variables, and clear Unraid update badges. -### Phase 6: n8n API Access +### Phase 10: Workflow Modularization -**Goal:** Claude Code can programmatically read, update, and test workflows +**Goal:** Break main workflow into modular sub-workflows for maintainability -**Dependencies:** None (enables faster iteration on all subsequent phases) +**Dependencies:** None -**Requirements:** API-01, API-02, API-03, API-04 - -**Plans:** 1 plan - -Plans: -- [x] 06-01-PLAN.md — Enable API access (create key, verify CRUD, execution history) - -**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 - -**Plans:** 3 plans - -Plans: -- [x] 07-01-PLAN.md — Deploy docker-socket-proxy via Unraid CA -- [x] 07-02-PLAN.md — Migrate workflow curl commands to proxy -- [x] 07-03-PLAN.md — Verify dangerous APIs are blocked - -**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 - -**Plans:** 3 plans - -Plans: -- [x] 08-01-PLAN.md — Container list keyboard and submenu navigation -- [x] 08-02-PLAN.md — Action execution and confirmation flow -- [x] 08-03-PLAN.md — Progress feedback and completion messages - -**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, update) show a confirmation prompt before executing -4. During operation execution, the message updates to show progress (e.g., "Updating 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 - -**Plans:** 4 plans - -Plans: -- [ ] 09-01-PLAN.md — Batch command parsing and container matching -- [ ] 09-02-PLAN.md — Sequential batch execution with progress feedback -- [ ] 09-03-PLAN.md — "Update all" and inline multi-select -- [ ] 09-04-PLAN.md — Verification and testing - -**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 9.1: Explore Breaking Main Workflow into Modular Sub-Workflows (INSERTED) - -**Goal:** [Urgent work - to be planned] - -**Dependencies:** Phase 9 (batch operations complete before modularization) - -**Requirements:** TBD +**Requirements:** TBD (carried from Phase 9.1) **Plans:** 0 plans Plans: -- [ ] TBD (run /gsd:plan-phase 9.1 to break down) +- [ ] TBD (run /gsd:plan-phase 10 to break down) **Success Criteria:** [To be defined during planning] --- -### Phase 10: Polish & Audit +### Phase 11: Polish & Audit **Goal:** Clear Unraid update badges, fix webhook issues, and verify environment configuration -**Dependencies:** Phase 9.1 (workflow modularization complete before polish) +**Dependencies:** Phase 10 (modularization complete before polish) **Requirements:** UNR-01, ENV-01, ENV-02, WEB-01 +**Plans:** 0 plans + +Plans: +- [ ] TBD (run /gsd:plan-phase 11 to break down) + **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 @@ -138,18 +51,18 @@ Plans: --- -### Phase 11: Documentation Overhaul +### Phase 12: Documentation Overhaul **Goal:** [To be planned] -**Dependencies:** Phase 10 (core features complete before documentation) +**Dependencies:** Phase 11 (core features complete before documentation) **Requirements:** TBD **Plans:** 0 plans Plans: -- [ ] TBD (run /gsd:plan-phase 11 to break down) +- [ ] TBD (run /gsd:plan-phase 12 to break down) **Success Criteria:** [To be defined during planning] @@ -158,17 +71,18 @@ Plans: ## Progress -| Phase | Name | Requirements | Status | -|-------|------|--------------|--------| -| 6 | n8n API Access | API-01, API-02, API-03, API-04 | Complete | -| 7 | Socket Security | SEC-01, SEC-02, SEC-03, SEC-04 | Complete | -| 8 | Inline Keyboard Infrastructure | KEY-01, KEY-02, KEY-03, KEY-04, KEY-05 | Complete | -| 9 | Batch Operations | BAT-01, BAT-02, BAT-03, BAT-04, BAT-05, BAT-06 | Pending | -| 9.1 | Explore Modular Sub-Workflows | TBD | Pending | -| 10 | Polish & Audit | UNR-01, ENV-01, ENV-02, WEB-01 | Pending | -| 11 | Documentation Overhaul | TBD | Pending | +| Phase | Name | Milestone | Status | +|-------|------|-----------|--------| +| 1-5 | Foundation through Polish | v1.0 | Complete | +| 6 | n8n API Access | v1.1 | Complete | +| 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 | +| 11 | Polish & Audit | v1.2 | Pending | +| 12 | Documentation Overhaul | v1.2 | Pending | -**v1.1 Coverage:** 23/23 requirements mapped (Phase 11 TBD) +**v1.2 Coverage:** 4 requirements mapped (UNR-01, ENV-01, ENV-02, WEB-01), modularization TBD --- -*Updated: 2026-02-03* +*Updated: 2026-02-04 after v1.1 milestone* diff --git a/.planning/STATE.md b/.planning/STATE.md index 727ede8..ca70adb 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,101 +2,69 @@ ## Project Reference -See: .planning/PROJECT.md (updated 2026-02-02) +See: .planning/PROJECT.md (updated 2026-02-04) **Core value:** Immediate container control from your phone -**Current focus:** v1.1 Phase 9 in progress — batch execution and progress complete +**Current focus:** v1.2 — Planning next milestone ## Current Position -- **Milestone:** v1.1 — n8n Integration & Polish -- **Phase:** 9 of 11 (Batch Operations) -- **Plan:** 4 of 4 complete (including verification) -- **Status:** Phase complete and verified -- **Last activity:** 2026-02-04 — Completed 09-04 verification testing +- **Milestone:** v1.2 — Modularization & Polish +- **Phase:** 10 of 12 (Workflow Modularization) +- **Plan:** Not started +- **Status:** Ready to plan +- **Last activity:** 2026-02-04 — v1.1 milestone complete ## Progress ``` -v1.1: [████████░ ] 81% +v1.0: [██████████] 100% SHIPPED +v1.1: [██████████] 100% SHIPPED -Phase 6: n8n API Access [##########] Complete -Phase 7: Socket Security [##########] Complete (3/3) -Phase 8: Inline Keyboard Infra [##########] Complete (3/3) -Phase 9: Batch Operations [##########] Complete (3/3) -Phase 10: Polish & Audit [ ] Pending -Phase 11: Documentation Overhaul [ ] Pending +v1.2: [ ] 0% + +Phase 10: Workflow Modularization [ ] Pending +Phase 11: Polish & Audit [ ] Pending +Phase 12: Documentation Overhaul [ ] Pending ``` ## Accumulated Context ### Key Decisions -| Decision | Rationale | Phase | -|----------|-----------|-------| -| n8n API first | Enables faster iteration on all subsequent phases | 6 | -| n8n API key never expires | Development environment on private network, rotation not critical | 06-01 | -| .env.n8n-api filename | Specific purpose, won't conflict with future env files | 06-01 | -| docker-socket-proxy deployed via user action | Consistent with Unraid-native approach, user has direct GUI access | 07-01 | -| dockernet network for n8n and proxy | Custom bridge network provides DNS resolution between containers | 07-01 | -| Connectivity verified through network config | Docker DNS guarantees hostname resolution on same custom network | 07-01 | -| Container create API allowed despite security risk | Update command needs container recreation; workflow logic controls params | 07-03 | -| Verification via documented proxy behavior | Deployment environment constraints; tecnativa proxy behavior well-documented | 07-03 | -| Credential name "Telegram account" | Matches actual n8n credential; ID I0xTTiASl7C1NZhJ | 07-02 | -| docker.sock mount removed from n8n | All API calls now go through proxy; no direct socket access | 07-02 | -| Webhook issue deferred to Phase 10 | WEB-01 added; bot works via manual execute for now | 07-02 | -| Callback data colon format | Compact format (select:name, list:0) stays within 64-byte limit | 08-01 | -| 6 containers per page | Optimal mobile display without scrolling | 08-01 | -| Running containers first with green icon | Matches common Docker UI conventions | 08-01 | -| All keyboard transitions use editMessageText | Clean UX with no message clutter | 08-01 | -| Timestamp in confirmation callback_data | Unix seconds for 30-second timeout validation | 08-02 | -| Start/restart/logs immediate, stop/update confirm | Per user decision in context; dangerous actions need confirmation | 08-02 | -| $input.all() for Docker API responses | n8n HTTP Request splits arrays; Code nodes need to reassemble | 08-03 | -| Timestamp in logs header | Prevents Telegram "message not modified" error on refresh | 08-03 | -| Image cleanup after callback updates | Matches v1.0 text flow behavior; removes old images | 08-03 | -| Both text and button commands supported | Text commands still work alongside inline keyboard | 08-03 | -| Exact match has absolute priority | User typing exact name expects that container, not similar ones | 09-01 | -| Batch stop requires confirmation | Context specifies fuzzy matching risk for stop operations | 09-01 | -| Comma-separated names in callback | Fits within 64-byte callback_data limit for typical batch sizes | 09-01 | -| Two-phase execution for name-only containers | Callbacks from bstop/bexec have names but no IDs - need lookup first | 09-02 | -| onError: continueRegularOutput | Ensures one failure doesn't abort entire batch | 09-02 | -| Is Batch Complete IF node | Clean routing to summary instead of relying on loop second output | 09-02 | -| Warnings shown in detail for <= 3 | Per context discretion - show details when few, summary when many | 09-02 | -| Update all filters to :latest containers | Performance optimization - full image check would be slow; :latest is common case | 09-03 | -| Multi-select limited to ~8 containers | 64-byte callback_data limit with batch:toggle:{csv}:{name} format | 09-03 | -| Checkmark toggle UI pattern | Clear visual selection feedback; matches mobile UI conventions | 09-03 | +See PROJECT.md Key Decisions table for full history. + +Recent v1.1 decisions: +- docker-socket-proxy for filtered Docker API access +- Colon-separated callback format for 64-byte compliance +- Two-phase batch execution for name-only callbacks +- Update all filters to :latest containers only ### Todos -- [x] Plan Phase 6 (n8n API Access) - Complete -- [x] Execute Phase 7 (Socket Security) - Complete -- [x] Execute Phase 8 (Inline Keyboard Infrastructure) - Complete -- [x] Execute Phase 9 (Batch Operations) - Complete and verified (4/4) - -### Roadmap Evolution - -- Phase 11 added: Documentation Overhaul -- Phase 9.1 inserted after Phase 9: Explore breaking main workflow into modular sub-workflows (URGENT) +(none — fresh milestone) ### Blockers (none) -### Deferred to Phase 9.1 +### Known Limitations -- **Batch Update via inline keyboard** — Route Batch Loop Action "update" output is not connected. The update sequence (pull→stop→remove→create→start) is too complex to inline in the batch loop. Will be trivial once workflow is modularized into sub-workflows. +- **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 -### Known Limitations (64-byte callback_data) +### Technical Debt -- **Long container names** — Telegram's 64-byte callback_data limit causes issues with long container names in batch operations -- **Batch select limited to ~2 containers** — The `batch:toggle:{page}:{selected}:{name}` format hits the 64-byte limit quickly with multiple selections. Consider: short IDs instead of names, or storing selection state server-side in Phase 9.1 +- Update flow duplicated between single and batch paths +- Workflow at 8,485 lines (growing complexity) ## Session Continuity - **Last session:** 2026-02-04 -- **Stopped at:** Phase 9 verification complete +- **Stopped at:** v1.1 milestone completion - **Resume file:** None -- **Next step:** Phase 10 - Polish & Audit +- **Next step:** `/gsd:new-milestone` to define v1.2 requirements and roadmap --- *Auto-maintained by GSD workflow* diff --git a/.planning/REQUIREMENTS.md b/.planning/milestones/v1.1-REQUIREMENTS.md similarity index 58% rename from .planning/REQUIREMENTS.md rename to .planning/milestones/v1.1-REQUIREMENTS.md index e9c2a42..fc828fa 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/milestones/v1.1-REQUIREMENTS.md @@ -1,3 +1,13 @@ +# Requirements Archive: v1.1 n8n Integration & Polish + +**Archived:** 2026-02-04 +**Status:** ✅ SHIPPED + +This is the archived requirements specification for v1.1. +For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone). + +--- + # Requirements: Unraid Docker Manager **Defined:** 2026-02-02 @@ -23,33 +33,27 @@ Requirements for milestone v1.1 — n8n Integration & Polish. ### Telegram Keyboards -- [ ] **KEY-01**: Status command shows container list with inline action buttons -- [ ] **KEY-02**: Tapping action button performs start/stop/restart on container -- [ ] **KEY-03**: Dangerous actions (stop, restart, update) show confirmation dialog -- [ ] **KEY-04**: Progress shown via message edit during operations -- [ ] **KEY-05**: Buttons removed after action completes +- [x] **KEY-01**: Status command shows container list with inline action buttons +- [x] **KEY-02**: Tapping action button performs start/stop/restart on container +- [x] **KEY-03**: Dangerous actions (stop, restart, update) show confirmation dialog +- [x] **KEY-04**: Progress shown via message edit during operations +- [x] **KEY-05**: Buttons removed after action completes ### Batch Operations -- [ ] **BAT-01**: User can update multiple containers in one command -- [ ] **BAT-02**: Batch updates execute sequentially with per-container feedback -- [ ] **BAT-03**: "Update all" command updates all containers with updates available -- [ ] **BAT-04**: "Update all" requires confirmation before executing -- [ ] **BAT-05**: One container failure doesn't abort remaining batch -- [ ] **BAT-06**: Final summary shows success/failure count +- [x] **BAT-01**: User can update multiple containers in one command +- [x] **BAT-02**: Batch updates execute sequentially with per-container feedback +- [x] **BAT-03**: "Update all" command updates all containers with updates available +- [x] **BAT-04**: "Update all" requires confirmation before executing +- [x] **BAT-05**: One container failure doesn't abort remaining batch +- [x] **BAT-06**: Final summary shows success/failure count -### Unraid Sync +### Deferred to v1.2 - [ ] **UNR-01**: After bot updates a container, Unraid's update badge clears - -### Environment Audit - - [ ] **ENV-01**: Verify if TELEGRAM_USERID container var is needed (vs hardcoded) - [ ] **ENV-02**: Verify if TELEGRAM_BOT_TOKEN container var is needed (vs n8n credential) - -### Webhook - -- [ ] **WEB-01**: Fix Telegram webhook so workflow responds when published (currently only works with manual execute) +- [ ] **WEB-01**: Fix Telegram webhook so workflow responds when published ## v1.0 Requirements (Validated) @@ -87,27 +91,39 @@ Shipped 2026-02-02. | SEC-02 | Phase 7 | Complete | | SEC-03 | Phase 7 | Complete | | SEC-04 | Phase 7 | Complete | -| 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 | -| WEB-01 | Phase 10 | Pending | +| KEY-01 | Phase 8 | Complete | +| KEY-02 | Phase 8 | Complete | +| KEY-03 | Phase 8 | Complete | +| KEY-04 | Phase 8 | Complete | +| KEY-05 | Phase 8 | Complete | +| BAT-01 | Phase 9 | Complete | +| BAT-02 | Phase 9 | Complete | +| BAT-03 | Phase 9 | Complete | +| BAT-04 | Phase 9 | Complete | +| BAT-05 | Phase 9 | Complete | +| BAT-06 | Phase 9 | Complete | +| UNR-01 | Phase 10 | Deferred to v1.2 | +| ENV-01 | Phase 10 | Deferred to v1.2 | +| ENV-02 | Phase 10 | Deferred to v1.2 | +| WEB-01 | Phase 10 | Deferred to v1.2 | **Coverage:** - v1.1 requirements: 23 total -- Mapped to phases: 22 -- Unmapped: 0 +- Shipped: 19 +- Deferred: 4 --- -*Requirements defined: 2026-02-02* -*Last updated: 2026-02-02 after roadmap creation* + +## Milestone Summary + +**Shipped:** 19 of 23 v1.1 requirements + +**Adjusted:** +- KEY-03: Originally "stop, restart, update" but restart was changed to immediate (low risk) +- BAT-03/BAT-04: "Update all" implemented for :latest containers only (performance optimization) + +**Deferred:** +- UNR-01, ENV-01, ENV-02, WEB-01 — Moved to v1.2 Phase 10 + +--- +*Archived: 2026-02-04 as part of v1.1 milestone completion* diff --git a/.planning/milestones/v1.1-ROADMAP.md b/.planning/milestones/v1.1-ROADMAP.md new file mode 100644 index 0000000..7e86aa9 --- /dev/null +++ b/.planning/milestones/v1.1-ROADMAP.md @@ -0,0 +1,161 @@ +# Milestone v1.1: n8n Integration & Polish + +**Status:** ✅ SHIPPED 2026-02-04 +**Phases:** 6-9 +**Total Plans:** 11 + +## Overview + +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. + +## Phases + +### Phase 6: n8n API Access + +**Goal**: Claude Code can programmatically read, update, and test workflows + +**Depends on**: None (enables faster iteration on all subsequent phases) + +**Requirements:** API-01, API-02, API-03, API-04 + +**Plans:** 1 plan + +Plans: +- [x] 06-01-PLAN.md — Enable API access (create key, verify CRUD, execution history) + +**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 + +**Details:** +- n8n API authentication via X-N8N-API-KEY header +- Workflow ID: HmiXBlJefBRPMS0m4iNYc +- Credentials stored in .env.n8n-api (gitignored) +- Full CRUD operations verified + +--- + +### Phase 7: Socket Security + +**Goal**: Docker operations flow through a filtered proxy instead of direct socket access + +**Depends on**: Phase 6 (API access enables faster iteration on curl command migration) + +**Requirements:** SEC-01, SEC-02, SEC-03, SEC-04 + +**Plans:** 3 plans + +Plans: +- [x] 07-01-PLAN.md — Deploy docker-socket-proxy via Unraid CA +- [x] 07-02-PLAN.md — Migrate workflow curl commands to proxy +- [x] 07-03-PLAN.md — Verify dangerous APIs are blocked + +**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 + +**Details:** +- tecnativa/docker-socket-proxy deployed on dockernet network +- 16 curl commands migrated from unix socket to TCP proxy +- Exec, build, commit APIs blocked (403 Forbidden) +- Container create allowed for update command functionality +- docker.sock mount removed from n8n container + +--- + +### Phase 8: Inline Keyboard Infrastructure + +**Goal**: Users interact with containers via tappable buttons instead of typing commands + +**Depends on**: Phase 7 (security in place before adding new features) + +**Requirements:** KEY-01, KEY-02, KEY-03, KEY-04, KEY-05 + +**Plans:** 3 plans + +Plans: +- [x] 08-01-PLAN.md — Container list keyboard and submenu navigation +- [x] 08-02-PLAN.md — Action execution and confirmation flow +- [x] 08-03-PLAN.md — Progress feedback and completion messages + +**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, update) show a confirmation prompt before executing +4. ✅ During operation execution, the message updates to show progress (e.g., "Updating...") +5. ✅ After action completes, buttons are removed and final status is shown in the message + +**Details:** +- Callback data format: colon-separated for 64-byte compliance +- 6 containers per page with pagination +- Running containers first with green circle icon +- All transitions use editMessageText (no message clutter) +- 30-second confirmation timeout with cancel option +- 37 new nodes added for action execution and confirmation + +--- + +### Phase 9: Batch Operations + +**Goal**: Users can update multiple containers in a single command with clear feedback + +**Depends on**: Phase 8 (keyboard infrastructure supports confirmation dialogs) + +**Requirements:** BAT-01, BAT-02, BAT-03, BAT-04, BAT-05, BAT-06 + +**Plans:** 4 plans + +Plans: +- [x] 09-01-PLAN.md — Batch command parsing and container matching +- [x] 09-02-PLAN.md — Sequential batch execution with progress feedback +- [x] 09-03-PLAN.md — "Update all" and inline multi-select +- [x] 09-04-PLAN.md — Verification and testing + +**Success Criteria:** +1. ✅ User can type "stop container1 container2" and all containers stop 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 (testing deferred) +4. ✅ If one container fails mid-batch, remaining containers still attempt to execute +5. ✅ Final message shows summary: "3 updated, 1 failed" with details + +**Details:** +- Exact-match priority in container matching +- Two-phase execution for name-only callbacks +- onError: continueRegularOutput for non-aborting batch +- 64-byte callback_data limit enforced (~8 containers max in multi-select) +- Checkmark toggle UI for visual selection feedback + +--- + +## Milestone Summary + +**Key Decisions:** +- n8n API key with never-expire policy for development +- docker-socket-proxy for filtered Docker API access +- Colon-separated callback format for 64-byte compliance +- Exact match priority in container matching +- Stop/update require confirmation; start/restart/logs immediate + +**Issues Resolved:** +- Telegram webhook only works via manual execute (deferred to WEB-01) +- Array handling in n8n Code nodes ($input.all() pattern) +- Message edit conflicts with identical content (timestamp solution) + +**Issues Deferred:** +- Batch update via inline keyboard (complex sequence, needs modularization) +- Webhook fix (WEB-01 in Phase 10) +- Environment variable audit (Phase 10) +- Unraid update badge sync (Phase 10) + +**Technical Debt Incurred:** +- Update flow duplicated between single and batch paths +- Workflow now 8,485 lines (complexity growing) +- Long container names hit 64-byte callback limit + +--- + +_For current project status, see .planning/ROADMAP.md_