docs(14): create phase plan

2026-02-08 20:22:11 -05:00
parent 00f0dcfd21
commit ff0773b84b
3 changed files with 424 additions and 4 deletions
@@ -0,0 +1,175 @@
+---
+phase: 14-unraid-api-access
+plan: 02
+type: execute
+wave: 2
+depends_on: ["14-01"]
+files_modified:
+  - ARCHITECTURE.md
+autonomous: false
+user_setup: []
+
+must_haves:
+  truths:
+    - "ARCHITECTURE.md documents the Unraid GraphQL API contract alongside existing Docker API contract"
+    - "Container ID format is documented based on actual test query results"
+    - "User has verified n8n can reach Unraid GraphQL API and receive valid container data"
+    - "GraphQL authentication pattern (x-api-key header) is documented"
+  artifacts:
+    - path: "ARCHITECTURE.md"
+      provides: "Unraid GraphQL API contract section"
+      contains: "GraphQL"
+  key_links:
+    - from: "ARCHITECTURE.md (GraphQL section)"
+      to: "n8n-workflow.json (Unraid API Test node)"
+      via: "Documents the API contract used by workflow nodes"
+      pattern: "graphql|GraphQL"
+---
+
+<objective>
+Document the Unraid GraphQL API contract in ARCHITECTURE.md and verify end-to-end connectivity with the user.
+
+Purpose: Completes Phase 14 by adding Unraid API documentation to the architecture reference (consistent with existing Docker API documentation style) and verifying that the test query actually works in the user's environment. The container ID format discovered during testing is critical for Phase 15 mutations.
+
+Output: Updated `ARCHITECTURE.md` with GraphQL API section, verified connectivity.
+</objective>
+
+<execution_context>
+@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luc/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/14-unraid-api-access/14-CONTEXT.md
+@.planning/phases/14-unraid-api-access/14-RESEARCH.md
+@.planning/phases/14-unraid-api-access/14-01-SUMMARY.md
+@ARCHITECTURE.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Document Unraid GraphQL API contract in ARCHITECTURE.md</name>
+  <files>ARCHITECTURE.md</files>
+  <action>
+Add a new section to ARCHITECTURE.md titled "## Unraid GraphQL API" placed after the "## System Overview" section (before "## Request Flow"). This keeps all external API documentation together. Style must match the existing Docker API documentation patterns in the file.
+
+The section should contain:
+
+**1. API Overview**
+- Endpoint: `{UNRAID_HOST}/graphql` (POST)
+- Authentication: `x-api-key` header with Unraid API key
+- Available in: Unraid 7.2+ (native) or 6.9-7.1 (Connect plugin)
+- Purpose: Sync container update status back to Unraid after bot-initiated updates
+
+**2. Authentication**
+- Header: `x-api-key: {api_key}`
+- Credential: n8n Header Auth credential named "Unraid API Key"
+- Permission required: `DOCKER:UPDATE_ANY`
+- Key creation: `unraid-api apikey --create --name "Docker Manager Bot" --permissions "DOCKER:UPDATE_ANY"`
+
+**3. Network Access**
+- Primary: `host.docker.internal` (requires `--add-host=host.docker.internal:host-gateway` in n8n container Extra Parameters)
+- Fallback: Direct Unraid IP/hostname (e.g., `http://192.168.1.100/graphql`)
+- SSL: Set "Ignore SSL Issues" for HTTPS with self-signed certs
+
+**4. Container Query (Phase 14 — read-only)**
+```graphql
+query { docker { containers { id names state isUpdateAvailable } } }
+```
+
+Document expected response structure:
+```json
+{
+  "data": {
+    "docker": {
+      "containers": [
+        { "id": "<PrefixedID>", "names": ["containername"], "state": "running", "isUpdateAvailable": false }
+      ]
+    }
+  }
+}
+```
+
+**5. Container ID Format**
+- Type: `PrefixedID` scalar
+- Format: TBD — to be updated after user runs test query in checkpoint below
+- Note: "Actual format discovered during Phase 14 testing. Phase 15 mutations use this format."
+
+**6. Update Mutation (Phase 15 — planned, not yet implemented)**
+```graphql
+mutation { docker { updateContainer(id: "<PrefixedID>") { id } } }
+```
+Mark as "Planned for Phase 15" — do not implement yet per phase boundary.
+
+**7. Error Patterns**
+- HTTP errors: Connection refused (network), 401 (bad API key), 404 (API not available)
+- GraphQL errors: `response.errors[]` array with message field
+- Error handling: Same pattern as Docker API errors (structured return, descriptive messages)
+
+Per user decision: Document only queries/mutations relevant to update sync, not the full Docker schema. Keep documentation style consistent with existing Docker API contract sections.
+  </action>
+  <verify>
+- ARCHITECTURE.md contains "## Unraid GraphQL API" section
+- Section documents: endpoint, authentication, network access, container query, container ID format, planned mutation, error patterns
+- Style is consistent with existing Docker API documentation in the file
+  </verify>
+  <done>ARCHITECTURE.md has a complete Unraid GraphQL API section documenting the contract for Phase 14 (queries) and Phase 15 (planned mutations), with container ID format marked as TBD pending test results.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Verify Unraid API connectivity end-to-end</name>
+  <files>ARCHITECTURE.md</files>
+  <action>
+Checkpoint: User verifies end-to-end Unraid API connectivity and reports container ID format.
+
+What was built: Plan 14-01 created credential infrastructure (.env.unraid-api, .gitignore) and added Unraid GraphQL test nodes to the main workflow (Keyword Router "unraid" branch -> HTTP Request -> Validate Response -> Telegram Send). Plan 14-02 Task 1 documented the GraphQL API contract in ARCHITECTURE.md.
+
+Setup steps (one-time):
+
+1. Create Unraid API key — SSH to Unraid and run:
+   unraid-api apikey --create --name "Docker Manager Bot" --permissions "DOCKER:UPDATE_ANY" --description "Container update status sync" --json
+   Or: Unraid WebGUI -> Settings -> Management Access -> API Keys -> Create key with DOCKER:UPDATE_ANY permission.
+
+2. Configure .env.unraid-api — Edit the file and replace template values with real UNRAID_HOST and UNRAID_API_KEY.
+
+3. Create n8n credential — In n8n UI: Credentials -> Add Credential -> Header Auth, Name: "Unraid API Key", Header Name: x-api-key, Header Value: paste your API key.
+
+4. Configure network access (if using host.docker.internal): Unraid WebGUI -> Docker -> n8n container -> Edit -> Extra Parameters: add --add-host=host.docker.internal:host-gateway -> Apply.
+
+5. Update HTTP Request node credential — Open "Unraid API Test" node in n8n editor and select the "Unraid API Key" credential.
+
+6. Send "unraid" to the Telegram bot.
+
+After user reports container ID format, update ARCHITECTURE.md to replace the TBD container ID format with the actual format observed.
+  </action>
+  <verify>
+- User confirms bot responds to "unraid" command with container list and count
+- Container ID format is reported and updated in ARCHITECTURE.md
+- No persistent connectivity or authentication errors
+  </verify>
+  <done>User has verified Unraid API connectivity works end-to-end, container ID format is documented in ARCHITECTURE.md, all three INFRA requirements validated.</done>
+</task>
+
+</tasks>
+
+<verification>
+- ARCHITECTURE.md contains Unraid GraphQL API documentation section
+- User confirms: Telegram bot responds to "unraid" command with container list
+- User confirms: Container ID format is documented
+- User confirms: No connectivity/auth errors
+</verification>
+
+<success_criteria>
+- ARCHITECTURE.md documents GraphQL API contract consistent with existing Docker API documentation style
+- User has verified end-to-end connectivity: n8n -> Unraid GraphQL API -> container data -> Telegram response
+- Container ID format is known and documented (Phase 15 can use it for mutations)
+- INFRA-01 validated (connectivity), INFRA-02 validated (API key works), INFRA-03 validated (container ID format documented)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/14-unraid-api-access/14-02-SUMMARY.md`
+</output>