unraid-docker-manager/.planning/phases/16-api-migration/16-04-PLAN.md

---
phase: 16-api-migration
plan: 04
type: execute
wave: 1
depends_on: []
files_modified: [n8n-batch-ui.json]
autonomous: true

must_haves:
  truths:
    - "Batch selection keyboard displays all containers with correct names and states"
    - "Toggling container selection updates bitmap and keyboard correctly"
    - "Navigation between pages works with correct container ordering"
    - "Batch exec resolves bitmap to correct container names"
    - "Clear selection resets to empty state"
  artifacts:
    - path: "n8n-batch-ui.json"
      provides: "Batch container selection UI via Unraid GraphQL API"
      contains: "graphql"
  key_links:
    - from: "n8n-batch-ui.json HTTP Request nodes"
      to: "Unraid GraphQL API"
      via: "POST container list queries"
      pattern: "UNRAID_HOST.*graphql"
    - from: "GraphQL Response Normalizer"
      to: "Existing Code nodes (Build Batch Keyboard, Handle Toggle, etc.)"
      via: "Docker API contract format (Names, State, Image)"
      pattern: "Names.*State"
---

<objective>
Migrate n8n-batch-ui.json from Docker socket proxy to Unraid GraphQL API for all 5 container listing queries.

Purpose: The batch UI sub-workflow fetches the container list 5 times (once per action path: mode selection, toggle update, exec, navigation, clear). All 5 are identical GET queries to Docker API. Replace with GraphQL queries plus normalizer for Docker API contract compatibility.

Output: n8n-batch-ui.json with all Docker API HTTP Request nodes replaced by Unraid GraphQL queries, wired through normalizer. All existing Code nodes (bitmap encoding, keyboard building, toggle handling) unchanged.
</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/16-api-migration/16-RESEARCH.md
@.planning/phases/15-infrastructure-foundation/15-02-SUMMARY.md
@n8n-batch-ui.json
@n8n-workflow.json (for Phase 15 utility node code — GraphQL Response Normalizer)
@ARCHITECTURE.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Replace all 5 Docker API container queries with Unraid GraphQL queries in n8n-batch-ui.json</name>
  <files>n8n-batch-ui.json</files>
  <action>
Replace all 5 Docker API HTTP Request nodes with Unraid GraphQL query equivalents. All 5 nodes are identical GET requests to `docker-socket-proxy:2375/containers/json?all=true`. Each one:

**Nodes to migrate:**
1. "Fetch Containers For Mode" — used when entering batch selection
2. "Fetch Containers For Update" — used after toggling a container
3. "Fetch Containers For Exec" — used when executing batch action
4. "Fetch Containers For Nav" — used when navigating pages
5. "Fetch Containers For Clear" — used after clearing selection

**For EACH of the 5 nodes, apply the same transformation:**

a. Change HTTP Request configuration:
   - Method: POST
   - URL: `={{ $env.UNRAID_HOST }}/graphql`
   - Body: `{"query": "query { docker { containers { id names state image } } }"}`
   - Headers: `Content-Type: application/json`, `x-api-key: ={{ $env.UNRAID_API_KEY }}`
   - Timeout: 15000ms
   - Error handling: `continueRegularOutput`

b. Add a **GraphQL Response Normalizer** Code node between each HTTP Request and its downstream Code node consumer. Copy normalizer logic from n8n-workflow.json's "GraphQL Response Normalizer" utility node.

   The normalizer transforms:
   - `{data: {docker: {containers: [...]}}}` → flat array `[{Id, Names, State, Image}]`
   - State mapping: RUNNING→running, STOPPED→exited, PAUSED→paused

**Wiring for each of the 5 paths:**
```
[upstream] → HTTP Request (GraphQL) → Normalizer (Code) → [existing downstream Code node]
```

Specifically:
1. Route Batch UI Action → Fetch Containers For Mode → **Normalizer** → Build Batch Keyboard
2. Needs Keyboard Update? (true) → Fetch Containers For Update → **Normalizer** → Rebuild Keyboard After Toggle
3. [exec path] → Fetch Containers For Exec → **Normalizer** → Handle Exec
4. Handle Nav → Fetch Containers For Nav → **Normalizer** → Rebuild Keyboard For Nav
5. Handle Clear → Fetch Containers For Clear → **Normalizer** → Rebuild Keyboard After Clear

**All downstream Code nodes remain UNCHANGED.** They use bitmap encoding with container arrays and reference `Names[0]`, `State`, `Image` — the normalizer ensures these fields exist in the correct format.

**Implementation optimization:** Since all 5 normalizers do the exact same thing, consider creating them as 5 identical Code nodes (n8n sub-workflows cannot share nodes across paths — each path needs its own node instance). Keep the Code identical across all 5 to simplify future maintenance.

Rename HTTP Request nodes to remove Docker-specific naming:
- "Fetch Containers For Mode" → keep name (not Docker-specific)
- "Fetch Containers For Update" → keep name
- "Fetch Containers For Exec" → keep name
- "Fetch Containers For Nav" → keep name
- "Fetch Containers For Clear" → keep name
  </action>
  <verify>
Load n8n-batch-ui.json with python3 and verify:
1. Zero HTTP Request nodes contain "docker-socket-proxy" in URL
2. All 5 HTTP Request nodes use POST to `$env.UNRAID_HOST/graphql`
3. 5 GraphQL Response Normalizer Code nodes exist (one per query path)
4. All downstream Code nodes (Build Batch Keyboard, Handle Toggle, Handle Exec, etc.) are UNCHANGED
5. Node count increased from 17 to 22 (5 normalizer nodes added)
6. All connections valid
7. Push to n8n via API and verify HTTP 200
  </verify>
  <done>
All 5 container queries in n8n-batch-ui.json use Unraid GraphQL API. Normalizer transforms responses to Docker API contract. All bitmap encoding and keyboard building Code nodes unchanged. Workflow pushed to n8n successfully.
  </done>
</task>

</tasks>

<verification>
1. Zero "docker-socket-proxy" references in n8n-batch-ui.json
2. All 5 HTTP Request nodes point to `$env.UNRAID_HOST/graphql`
3. Normalizer nodes present on all 5 query paths
4. Downstream Code nodes byte-for-byte identical to pre-migration
5. Push to n8n with HTTP 200
</verification>

<success_criteria>
- n8n-batch-ui.json has zero Docker socket proxy references
- All container data flows through GraphQL Response Normalizer
- Batch selection keyboard, toggle, exec, nav, clear all work with normalized data
- Downstream Code nodes unchanged (zero-change migration for consumers)
- Workflow valid and pushed to n8n
</success_criteria>

<output>
After completion, create `.planning/phases/16-api-migration/16-04-SUMMARY.md`
</output>