Commit Graph

330 Commits

Author SHA1 Message Date
Lucas Berger 4e29bdeb56 docs(15-01): complete Container ID Registry and Callback Token Encoding plan
- Added 15-01-SUMMARY.md documenting implementation and deviations
- Updated STATE.md: Phase 15 complete (2/2 plans), 52 total plans, v1.4 at 20%
- Task 1 (Container ID Registry) was pre-existing in baseline
- Task 2 (Token Encoder/Decoder) implemented and pushed to n8n
- All utility nodes standalone, ready for Phase 16 wiring

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 08:56:03 -05:00
Lucas Berger d25fc1b13f docs(15-02): complete GraphQL utility nodes plan 2026-02-09 08:55:01 -05:00
Lucas Berger 1b61343528 feat(15-01): add Callback Token Encoder and Decoder utility nodes
- Callback Token Encoder: compress 129-char Unraid PrefixedID to 8-char hex token
- SHA-256 hashing with 7-window collision detection (56 chars / 8-char windows)
- Callback Token Decoder: resolve 8-char token back to PrefixedID
- Both use JSON serialization for static data persistence (_callbackTokens)
- Standalone utility nodes at [600,2400] and [1000,2400]
- Not connected - Phase 16 will wire into active flow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 08:53:38 -05:00
Lucas Berger e6ac219212 feat(15-02): add GraphQL Error Handler and HTTP Template utility nodes
- GraphQL Error Handler maps ALREADY_IN_STATE to HTTP 304 (matches Docker API pattern)
- Handles NOT_FOUND, FORBIDDEN, UNAUTHORIZED error codes
- HTTP Template pre-configured with 15s timeout for myunraid.net cloud relay
- Environment variable auth (UNRAID_HOST, UNRAID_API_KEY headers)
- continueRegularOutput error handling for downstream processing
- Standalone utility nodes at [600,2600] and [1000,2600] for Phase 16 wiring
- Fix: removed invalid notesDisplayMode from Container ID Registry
2026-02-09 08:52:23 -05:00
Lucas Berger 1b4b596e05 feat(15-02): add GraphQL Response Normalizer utility node
- Transforms Unraid GraphQL response to Docker API contract
- Maps id->Id, state (UPPERCASE)->State (lowercase), names->Names
- STOPPED->exited conversion (Docker convention)
- Validates response.errors[] and data.docker.containers structure
- Standalone utility node at [200, 2600] for Phase 16 wiring
2026-02-09 08:47:58 -05:00
Lucas Berger a352b15954 docs(15): create phase plan — 2 plans for infrastructure foundation 2026-02-09 08:42:39 -05:00
Lucas Berger 62eaa4b1ec docs(15): research infrastructure foundation domain 2026-02-09 08:36:44 -05:00
Lucas Berger 16034bbdb8 docs: create milestone v1.4 roadmap (4 phases)
Phases 15-18: Infrastructure Foundation, API Migration, Cleanup, Documentation
23 requirements mapped across 4 phases with 0 gaps.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 08:29:16 -05:00
Lucas Berger 7eab41eaba docs: define milestone v1.4 requirements 2026-02-09 08:11:54 -05:00
Lucas Berger bab819f6c8 docs: complete v1.4 project research synthesis 2026-02-09 08:08:25 -05:00
Lucas Berger bb47664188 docs: start milestone v1.4 Unraid API Native 2026-02-09 07:52:53 -05:00
Lucas Berger 903e73d616 feat: v1.3 Unraid Update Status Sync
Unraid GraphQL API foundation — connectivity, authentication, and
container ID format verified for native Unraid API integration.

Phase 14: Unraid API Access (2 plans, 4 tasks)
- Established Unraid GraphQL API connectivity via myunraid.net cloud relay
- Dual credential storage (.env.unraid-api + n8n env vars)
- Container ID format: {server_hash}:{container_hash} (128-char SHA256 pair)
- Complete API contract documented in ARCHITECTURE.md
- "unraid" test command added to Telegram bot

Phases 15-16 dropped (superseded by v1.4 Unraid API Native).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 07:47:31 -05:00
Lucas Berger ff0773b84b docs(14): create phase plan 2026-02-08 20:22:11 -05:00
Lucas Berger 00f0dcfd21 docs(14): research Unraid GraphQL API access patterns 2026-02-08 20:16:06 -05:00
Lucas Berger 9385deb0da docs(14): capture phase context 2026-02-08 20:10:58 -05:00
Lucas Berger be66f01815 chore: persist research preference in config
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 20:02:00 -05:00
Lucas Berger 96c293f8f4 docs: create milestone v1.3 roadmap (3 phases) 2026-02-08 20:01:15 -05:00
Lucas Berger 59a97d1847 docs: define milestone v1.3 requirements 2026-02-08 19:57:10 -05:00
Lucas Berger 07cde0490a docs: complete v1.3 project research (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY) 2026-02-08 19:52:57 -05:00
Lucas Berger c071b890ef docs: start milestone v1.3 Unraid Update Status Sync 2026-02-08 19:35:46 -05:00
Lucas Berger 1e84472efd chore: set git branching strategy to per-milestone
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 19:26:28 -05:00
Lucas Berger 328442554c docs: rename DEPLOY-SUBWORKFLOWS.md to ARCHITECTURE.md and rewrite
Restructured as a proper technical architecture document:
- Added Observability section (correlation IDs, structured errors, debugging)
- Reorganized into logical flow: overview, request flow, contracts, internals
- Removed stale rollback/backup references
- Updated all references in README, CLAUDE.md, PROJECT.md, STATE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 19:15:56 -05:00
Lucas Berger e7eadd088c chore: complete v1.2 milestone — archive and tag
Archive v1.2 Modularization & Polish milestone:
- Archive ROADMAP.md, REQUIREMENTS.md, and audit to milestones/
- Evolve PROJECT.md with v1.2 validated requirements and decisions
- Reorganize ROADMAP.md with collapsed milestone groupings
- Delete REQUIREMENTS.md (fresh for next milestone)
- Update STATE.md and MILESTONES.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger 4b82044031 docs(phase-13): complete phase execution 2026-02-08 18:56:44 -05:00
Lucas Berger 4228cca9a3 docs(13-01): complete documentation overhaul plan
- README expanded from 139 to 264 lines (+90%)
- Added Architecture, Configuration, and Troubleshooting sections
- Documented all v1.2 features (batch selection, Update All button, inline keyboard)
- Removed outdated DEPLOYMENT_GUIDE.md (Phase 10-05, 3 sub-workflows)
- Consolidated to single technical reference: DEPLOY-SUBWORKFLOWS.md
- Updated STATE.md: Phase 13 complete, v1.2 milestone 100% COMPLETE
- Created 13-01-SUMMARY.md with full execution record

Phase 13-01 duration: 113 seconds
Tasks: 2/2 complete
Commits: 54437aa, a483bfb
2026-02-08 18:56:44 -05:00
Lucas Berger 062e096cd4 docs(13-01): remove outdated DEPLOYMENT_GUIDE.md
- File written during Phase 10-05 for 3 sub-workflows (now 7)
- References 199 nodes (now 166 in main workflow)
- Fully superseded by DEPLOY-SUBWORKFLOWS.md (725 lines, current)
- README now links only to DEPLOY-SUBWORKFLOWS.md for technical details
- Remaining references in .planning/ are historical records (expected)
2026-02-08 18:56:44 -05:00
Lucas Berger 6cdb9581a1 docs(13-01): overhaul README with architecture, configuration, and troubleshooting sections
- Add dedicated Architecture section with ASCII diagram (main workflow + 7 sub-workflows)
- Add dedicated Configuration section (separated from installation steps)
- Add dedicated Troubleshooting section (5 common issues with fixes)
- Document batch selection workflow (toggle checkmarks, multi-select UI)
- Document inline keyboard Update All button location and usage
- Expand Usage section with inline keyboard and batch operations subsections
- Document infrastructure container exclusion from batch updates
- Link to DEPLOY-SUBWORKFLOWS.md for technical details
- Remove outdated DEPLOYMENT_GUIDE.md reference
- Expand from 139 to 264 lines (comprehensive, not over-documented)
2026-02-08 18:56:44 -05:00
Lucas Berger 70115f7cd6 docs(13): create phase plan 2026-02-08 18:56:44 -05:00
Lucas Berger 820dff47f4 docs(13): research documentation overhaul requirements and best practices 2026-02-08 18:56:44 -05:00
Lucas Berger afddb6130a docs(12-02): complete Phase 12 — all v1.2 requirements closed
BATCH-04 and BATCH-05 UAT passed. 9 bugs fixed during testing.
All 12 v1.2 requirements now complete. Phase 13 (docs overhaul) next.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger c2c2ce7092 fix(12-02): Update All flow — 9 bug fixes from UAT
Fixes discovered during BATCH-04/BATCH-05 UAT testing:

- Convert confirmation to HTTP Request (editMessageText for inline kb,
  sendMessage for text command) with dynamic endpoint selection
- Fix data chain breaks: use named node refs ($('Parse Callback Data'),
  $('Get Update All Data')) instead of $json after API calls
- Add infrastructure container exclusion (n8n, socket-proxy) by image
  and container name to prevent bot self-destruction during updates
- Add batch responseMode to update sub-workflow (skip Telegram messages)
- Reorder infra check before :latest filter so sha256-digest images
  appear in skipped list
- Add onError:continueRegularOutput to Answer Update All Start for
  expired callback queries
- Show "Back to List" button in batch summary for update-all flow
- Add Prepare Update All Batch fallback in Prepare Batch Loop

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger b3909f00e5 docs(12-01): complete documentation audit plan
- Create 12-01-SUMMARY.md with execution metrics and decisions
- Update STATE.md: Phase 12 complete (1/1 plan)
- Record decision: Document Unraid limitation vs programmatic fix
- Closed 4 requirements: ENV-01, ENV-02, DEBT-01, DEBT-02
- Resolved UNR-01 as documented limitation
- Duration: 140 seconds, 2 tasks completed, 3 files modified

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger 7601e245a9 docs(12-01): document Unraid update badge limitation
- Add Known Limitations section to DEPLOY-SUBWORKFLOWS.md
- Document UNR-01: Unraid shows "apply update" after bot updates a container
- Explain root cause: bot bypasses Unraid's XML template system
- Provide workaround: click Apply Update in Unraid (instant, image cached)
- Clarify "Check for Updates" does NOT clear badge, may create new ones
- Mark UNR-01 as complete (documented limitation with workaround)
2026-02-08 18:56:44 -05:00
Lucas Berger e6e5df8754 docs(12-01): update environment and architecture documentation
- Update README to document docker-socket-proxy architecture instead of direct socket mount
- Clarify TELEGRAM_BOT_TOKEN needs both n8n credential AND env var
- Clarify user ID is hardcoded in IF nodes (no env var needed)
- Add missing commands to usage table (update all, /list)
- Document all 8 workflow files (main + 7 sub-workflows)
- Mark ENV-01, ENV-02, DEBT-01, DEBT-02 as complete in REQUIREMENTS.md
- Verify DEBT-02 is fixed (single --max-time 600 flag, no duplicates)
2026-02-08 18:56:44 -05:00
Lucas Berger 1ef726942a docs(12): plan phase with Unraid badge research and UAT
Research found Unraid badge issue is architectural (bot bypasses
Unraid's XML template system). Updated plans to document limitation
with workaround instead of attempting programmatic fix. Plan 01
covers docs/env/debt, Plan 02 covers deferred Update All UAT.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger 510b7d50dc docs(12): create phase plan 2026-02-08 18:56:44 -05:00
Lucas Berger c1d988f0e7 docs(12): research phase domain 2026-02-08 18:56:44 -05:00
Lucas Berger 732f692544 docs(12): capture phase context 2026-02-08 18:56:44 -05:00
Lucas Berger 16ae0b8bc0 docs(quick-1-1): complete orphan node removal task 2026-02-08 18:56:44 -05:00
Lucas Berger d153453aa9 refactor(workflow): remove orphan callback node chain (172→166 nodes) 2026-02-08 18:56:44 -05:00
Lucas Berger db3df53800 docs(quick-1): create plan to remove orphan node chain 2026-02-08 18:56:44 -05:00
Lucas Berger a15df26b7b docs(phase-11): complete phase execution — bitmap encoding + Update All
Verification: 7/9 must-haves pass, 2 deferred (Update All UAT → Phase 12).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger 642d1ec73d docs(11-02): complete plan — Update All button, deployment, UAT
UAT results: tests 1-3,6 pass (bitmap, long names, batch exec, regression).
Tests 4-5 (Update All UAT) deferred to after Phase 12.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger 0810c0919a fix(11-01): fix bitmap node references to use Parse Callback Data
Is Bitmap Batch Stop and Resolve Batch Stop Names were checking $json.bitmap
which contains the Telegram API response, not the parsed callback data. Changed
both to reference $("Parse Callback Data").item.json directly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger 551a69f1f3 fix(11-01): fix batch stop bitmap resolution wiring and parser return
Three bugs from plan 11-01 execution:
1. Parse Callback Data bstop return missing bitmap/isBitmapBatchStop fields
2. Is Bitmap Batch Stop wired to expired branch [0] instead of not-expired [1]
3. Is Bitmap Batch Stop false branch went to Initialize Batch State, bypassing Prepare Batch Stop Exec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 18:56:44 -05:00
Lucas Berger 3275e190c4 feat(11-02): add Update All button to container list with callback routing
- Add 'Update All :latest' button to Build Container List and Build Paginated List
- Add uall:start parser to Parse Callback Data (sets isUpdateAllStart flag)
- Add updateallstart rule to Route Callback (index 2)
- Add Answer Update All Start node with 'Checking for updates...' callback response
- Wire Route Callback [updateallstart] -> Answer Update All Start -> Get All Containers For Update All
- Fix Check Available Updates to support both text and callback origins (try/catch for Keyword Router vs Parse Callback Data)
2026-02-08 18:56:44 -05:00
Lucas Berger 339b366bcc docs(11-01): complete bitmap encoding plan -- unlimited container selection
- Created 11-01-SUMMARY.md with technical details and verification results
- Updated STATE.md: Phase 11 plan 1/2 complete, 50% progress
- Key metrics: 5m 16s duration, 2 tasks, 4 nodes added (1 batch-ui + 3 main workflow)
- Node counts: n8n-batch-ui.json 17 nodes, n8n-workflow.json 171 nodes
- Decisions: base36 BigInt encoding, graceful migration via dual parsers
2026-02-08 18:56:44 -05:00
Lucas Berger bac38634a3 feat(11-01): update main workflow for bitmap-encoded batch callbacks
- Add new parsers for b: (toggle), bn: (nav), be: (exec) formats in Parse Callback Data
- Update Prepare Batch UI Input to forward bitmap field instead of selectedCsv
- Retain old batch:toggle/nav/exec parsers for backward compatibility with in-flight messages
- Add bitmap detection in bstop:confirm parser (detects alphanumeric vs CSV format)
- Add 3 new nodes for bitmap resolution flow:
  - Is Bitmap Batch Stop (IF node)
  - Fetch Containers For Bitmap Stop (HTTP)
  - Resolve Batch Stop Names (Code node with decodeBitmap)
- Wire bitmap resolution flow: Check Batch Stop Expired -> Is Bitmap -> [true] Fetch -> Resolve -> Initialize
- Legacy CSV format routes directly to Initialize Batch State (false path)
- Total: 171 nodes (168 + 3 new)
2026-02-08 18:56:44 -05:00
Lucas Berger cea467f493 feat(11-01): implement bitmap encoding in batch UI sub-workflow
- Replace CSV-in-callback with base36 bitmap encoding
- Add Fetch Containers For Exec node for bitmap->name resolution
- Update all code nodes to use BigInt bitmap operations
- New callback formats: b:{page}:{bitmap}:{index}, bn:{bitmap}:{page}, be:{action}:{bitmap}
- Remove 64-byte limit check (bitmap encoding ~20 bytes max for 50 containers)
- Update trigger schema: selectedCsv -> bitmap, add containerIndex field
- Total: 17 nodes (16 original + 1 new)
2026-02-08 18:56:44 -05:00
Lucas Berger 1245aeed4f docs(11): create phase plan — bitmap batch selection + update all button 2026-02-08 18:56:44 -05:00