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

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
02-docker-integration	02	execute	2	02-01	n8n-workflow.json	false	truths artifacts key_links 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 path provides contains n8n-workflow.json Docker query workflow branch Execute Command from to via pattern n8n-workflow.json Docker API Execute Command node with curl curl.*unix-socket from to via pattern Code node (parse) Container JSON JSON.parse JSON.parse from to via pattern Code node (match) Container names fuzzy match function includes.*toLowerCase

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.

<execution_context> @/home/luc/.claude/get-shit-done/workflows/execute-plan.md @/home/luc/.claude/get-shit-done/templates/summary.md </execution_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 Task 1: Add Docker Query Branch to Workflow n8n-workflow.json 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)

- 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) Workflow JSON updated with complete Docker query branch Task 2: Import Updated Workflow 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

Confirm workflow imported and activated Task 3: Verify Docker Query Flow Docker query capability via Telegram conversation 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)

Confirm all test scenarios pass, or describe failures - "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

<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>

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