unraid-docker-manager/.planning/phases/02-docker-integration/02-02-PLAN.md

---
phase: 02-docker-integration
plan: 02
type: execute
wave: 2
depends_on: ["02-01"]
files_modified: [n8n-workflow.json]
autonomous: false

must_haves:
  truths:
    - "User can send 'status' and see running container summary"
    - "User can ask about specific container by name and see details"
    - "Fuzzy matching works (plex finds plex-server)"
    - "Multiple matches prompt for clarification"
    - "Docker connection failure shows clear error message"
  artifacts:
    - path: "n8n-workflow.json"
      provides: "Docker query workflow branch"
      contains: "Execute Command"
  key_links:
    - from: "n8n-workflow.json"
      to: "Docker API"
      via: "Execute Command node with curl"
      pattern: "curl.*unix-socket"
    - from: "Code node (parse)"
      to: "Container JSON"
      via: "JSON.parse"
      pattern: "JSON.parse"
    - from: "Code node (match)"
      to: "Container names"
      via: "fuzzy match function"
      pattern: "includes.*toLowerCase"
---

<objective>
Add Docker query capability to n8n workflow - list containers, match by name, format responses.

Purpose: Enable users to query container status through Telegram conversation.
Output: Updated n8n-workflow.json with Docker query branch that handles "status" and container-specific queries.
</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/02-docker-integration/02-RESEARCH.md
@.planning/phases/02-docker-integration/02-CONTEXT.md
@.planning/phases/02-docker-integration/02-01-SUMMARY.md
@n8n-workflow.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add Docker Query Branch to Workflow</name>
  <files>n8n-workflow.json</files>
  <action>
    Extend the existing n8n workflow with Docker query capability.

    **New nodes to add:**

    1. **Switch Node** (after IF User Authenticated, replaces direct connection to Format Echo):
       - Route based on message content
       - Case 1: Message contains "status" OR starts with container-related keywords -> Docker Query branch
       - Case 2: Default -> existing Echo branch (for now, will be replaced by Claude NLU in Phase 4)

    2. **Execute Command Node** (Docker List):
       - Command: `curl --unix-socket /var/run/docker.sock 'http://localhost/v1.53/containers/json?all=true'`
       - This fetches all containers (running and stopped)

    3. **Code Node** (Parse and Match):
       - Parse JSON response from curl
       - Extract container name from user message (simple: look for words that aren't "status", "show", "check", etc.)
       - Implement fuzzy matching per CONTEXT.md:
         - Case-insensitive
         - Strip common prefixes (linuxserver-, binhex-)
         - Substring match
       - Handle cases:
         - No container name -> return summary (count by state)
         - Single match -> return that container's details
         - Multiple matches -> return list and ask for clarification
         - No matches -> return "not found" message

    4. **Code Node** (Format Response):
       - Format per CONTEXT.md:
         - Emoji + text: "checkmark plex-server: Running (2 days)"
         - State emoji mapping: running=checkmark, exited=X, paused=pause, restarting=arrows, dead=skull
         - Summary shows counts: "25 running, 3 stopped"
         - Single container shows: name, state, uptime, image
       - Strip leading slash from container names
       - Calculate uptime from Status field (already human-readable like "Up 2 days")

    5. **Telegram Send** (reuse existing Send Echo node or create new for Docker responses)

    **Connection changes:**
    - IF User Authenticated -> Switch Node
    - Switch Node case "docker" -> Execute Command -> Parse and Match -> Format Response -> Telegram Send
    - Switch Node default -> Format Echo -> Send Echo (existing)

    **Error handling:**
    - If curl fails (non-zero exit), format error message: "Can't reach Docker - check if n8n has socket access"
    - If JSON parse fails, format error message: "Unexpected Docker response"

    **Important implementation notes from RESEARCH.md:**
    - Container names have leading slash: use `.replace(/^\//, '')`
    - Health status may not exist: use optional chaining `?.`
    - Use simple substring matching first (no external library needed)
  </action>
  <verify>
    - n8n-workflow.json contains Execute Command node with curl command
    - n8n-workflow.json contains Code nodes for parsing and formatting
    - Switch node routes "status" messages to Docker branch
    - JSON structure is valid (can be imported into n8n)
  </verify>
  <done>Workflow JSON updated with complete Docker query branch</done>
</task>

<task type="checkpoint:human-action" gate="blocking">
  <name>Task 2: Import Updated Workflow</name>
  <action>
    User imports the updated n8n-workflow.json into n8n:

    1. Open n8n in browser
    2. Go to the Docker Manager Bot workflow
    3. Delete existing workflow (or create new one)
    4. Import updated n8n-workflow.json
    5. Select Telegram API credential for both Telegram nodes
    6. Activate workflow
  </action>
  <resume-signal>Confirm workflow imported and activated</resume-signal>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 3: Verify Docker Query Flow</name>
  <what-built>Docker query capability via Telegram conversation</what-built>
  <how-to-verify>
    Test these scenarios in Telegram:

    1. **Summary query:**
       - Send: "status"
       - Expected: Summary like "Container summary: 15 running, 2 stopped"

    2. **Specific container (exact match):**
       - Send: "status plex" (or name of a container you have)
       - Expected: Detailed status with emoji, state, uptime

    3. **Fuzzy match:**
       - Send: "check plex" (partial name)
       - Expected: Same as above - finds plex-server or similar

    4. **Multiple matches (if applicable):**
       - Send a name that matches multiple containers
       - Expected: List of matches asking for clarification

    5. **Not found:**
       - Send: "status nonexistent123"
       - Expected: "No container found matching..." message

    6. **Fallback to echo (non-docker message):**
       - Send: "hello"
       - Expected: Echo response (existing behavior)
  </how-to-verify>
  <resume-signal>Confirm all test scenarios pass, or describe failures</resume-signal>
</task>

</tasks>

<verification>
- "status" returns container summary with counts
- Container name query returns detailed status with emoji
- Fuzzy matching works (partial names, case-insensitive)
- Multiple matches prompt for clarification
- Non-docker messages fall through to echo
- Docker errors show clear message
</verification>

<success_criteria>
- User sends "status" -> sees running container count/summary
- User sends "status plex" -> sees plex container details with emoji status
- User sends "hello" -> gets echo response (existing flow works)
- Invalid container name -> clear "not found" message
</success_criteria>

<output>
After completion, create `.planning/phases/02-docker-integration/02-02-SUMMARY.md`
</output>