unraid-docker-manager/.planning/phases/09-batch-operations/09-02-PLAN.md

---
phase: 09-batch-operations
plan: 02
type: execute
wave: 2
depends_on: [09-01]
files_modified: [n8n-workflow.json]
autonomous: true

must_haves:
  truths:
    - "Batch operations execute sequentially, not in parallel"
    - "Each container shows progress as it completes"
    - "One container failure does not abort remaining batch"
    - "Final message shows summary with failures emphasized"
  artifacts:
    - path: "n8n-workflow.json"
      provides: "Sequential batch execution with error handling"
      contains: "Loop Over Items"
  key_links:
    - from: "Loop Over Items node"
      to: "Execute Container Action"
      via: "Single item per iteration (batch size 1)"
      pattern: "batchSize.*1"
    - from: "Error handler"
      to: "Continue loop"
      via: "Log failure, increment counter, proceed"
      pattern: "failureCount"
    - from: "Batch summary"
      to: "Telegram editMessageText"
      via: "Formatted result with failure details"
      pattern: "Failed.*reason"
---

<objective>
Implement sequential batch execution with per-container progress, error isolation, and failure-emphasized summaries.

Purpose: Enable multi-container operations that don't fail entirely when one container has issues.
Output: Loop Over Items execution pattern with progress updates and actionable error reporting.
</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/09-batch-operations/09-CONTEXT.md
@.planning/phases/09-batch-operations/09-RESEARCH.md
@.planning/phases/09-batch-operations/09-01-SUMMARY.md
@n8n-workflow.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add Loop Over Items for sequential batch execution</name>
  <files>n8n-workflow.json</files>
  <action>
Implement the sequential execution loop for batch operations.

1. After "Route Batch Action" (from Plan 01), add Code node "Initialize Batch State":
   - Input: matched containers array, action type, chat_id, message_id (for editing)
   - Output batch state object:
     ```javascript
     return {
       json: {
         containers: $json.allMatched, // Array of container objects
         action: $json.action, // 'update', 'start', 'stop', 'restart'
         totalCount: $json.allMatched.length,
         successCount: 0,
         failureCount: 0,
         warningCount: 0,
         results: [], // Array of { name, status: 'success'|'error'|'warning', reason? }
         chatId: $json.chatId,
         messageId: $json.messageId,
         currentIndex: 0
       }
     };
     ```

2. Add HTTP node "Send Batch Start Message":
   - POST to Telegram sendMessage (new message, not edit - we'll edit this one during progress)
   - Text: "Starting batch {action} for {N} containers..."
   - Save message_id from response for progress edits

3. Add Loop Over Items node "Batch Loop":
   - Input: containers array
   - Batch Size: 1 (critical - sequential execution)
   - Output: Single container per iteration

4. For each iteration, the loop should:
   - Edit progress message with current container name
   - Execute the action (reuse existing action execution nodes where possible)
   - Handle success or error
   - Update counters and results array
   - Continue to next item

5. Important: Use n8n's "Continue On Fail" option on HTTP Request nodes within the loop so one failure doesn't abort the whole batch.

Note from RESEARCH: n8n Loop Over Items with "Continue (using error output)" has known issues. Use HTTP Request's "Continue On Fail" and check status code in subsequent Code node instead.
  </action>
  <verify>
Test with mock batch of 3 containers:
- Loop executes 3 times (one per container)
- Batch state tracks progress correctly
- Initial message is sent before loop starts
  </verify>
  <done>Sequential loop executes containers one at a time with batch state tracking</done>
</task>

<task type="auto">
  <name>Task 2: Add per-container progress updates and action execution</name>
  <files>n8n-workflow.json</files>
  <action>
Wire action execution within the loop with progress feedback.

1. Inside the loop, add Code node "Build Progress Message":
   - Input: current container, batch state
   - Output message text:
     ```
     Batch {action} in progress...

     Current: {containerName}
     Progress: {current}/{total}

     Success: {successCount}
     Failed: {failureCount}
     ```
   - Rate limit consideration: Only edit message every container (small batches <5). For larger batches, research suggests editing every 3-5 items, but since typical batch is 2-5 containers, edit every time is fine.

2. Add HTTP node "Edit Progress Message":
   - POST to Telegram editMessageText
   - Use saved progress_message_id from batch start
   - parse_mode: HTML

3. Add Switch node "Route Batch Loop Action" (within loop):
   - update: Execute full update flow (pull image, check digest, stop, remove, create, start)
   - start: Execute container start
   - stop: Execute container stop
   - restart: Execute container restart

4. For each action type, wire to existing action execution nodes where possible:
   - Start: Can reuse "Execute Immediate Action" from Phase 8 or create dedicated "Execute Batch Start"
   - Stop/Restart: Similar reuse pattern
   - Update: This is complex - need to execute the full update sequence per container

5. Add Code node "Handle Action Result" after each action execution:
   - Check HTTP response status or exec output
   - Determine success/error/warning:
     - Success: Container action completed normally
     - Warning: "Already stopped", "No update available", "Already running"
     - Error: Network error, timeout, pull failed, etc.
   - Update batch state: increment appropriate counter, add to results array
   - Output updated batch state for next iteration

6. Key pattern for continue-on-error:
   - HTTP nodes: Enable "Continue On Fail"
   - After HTTP node, Code node checks `$json.error` or `$json.statusCode >= 400`
   - Log failure to results array but don't throw - return updated state to continue loop
  </action>
  <verify>
Test batch update with 2 containers where one has no update available:
- First container: pulls, updates, succeeds
- Second container: "No update available" -> warning
- Progress message updates for each container
- Both counted in results (1 success, 1 warning)
  </verify>
  <done>Per-container progress shown during execution; actions execute correctly; errors logged but don't abort batch</done>
</task>

<task type="auto">
  <name>Task 3: Add batch summary with failure emphasis</name>
  <files>n8n-workflow.json</files>
  <action>
Create the final summary message after batch completes.

1. After Loop Over Items completes, add Code node "Build Batch Summary":
   - Input: final batch state with all results
   - Build summary following pattern from CONTEXT: "Summary emphasizes failures over successes"
   - Format:
     ```html
     <b>Batch {action} Complete</b>

     {if errors exist:}
     <b>Failed ({errorCount}):</b>
     - {containerName}: {reason}
     - {containerName}: {reason}

     {if warnings exist AND Claude's discretion to show them:}
     <b>Warnings ({warningCount}):</b>
     - {containerName}: {reason}

     <b>Successful:</b> {successCount}/{totalCount}
     ```
   - Per CONTEXT, Claude's discretion on warnings. Recommendation: Show warning count but not individual warnings unless there are few: `Warnings: 2 (containers already in desired state)`

2. Add HTTP node "Send Batch Summary":
   - POST to Telegram editMessageText
   - Edit the progress message to show final summary
   - Add inline keyboard with "Back to List" button

3. Error classification in the result handler (Task 2):
   - ERROR (red, show in summary):
     - HTTP status 4xx/5xx from Docker API
     - "image pull failed", "timeout", "permission denied"
     - Container not found during execution
   - WARNING (yellow, optional in summary):
     - "Already stopped" (for stop action)
     - "Already running" (for start action)
     - "No update available" (for update action)
     - HTTP 304 Not Modified

4. Summary should be actionable - if something failed, user knows what and why, not just a count.
  </action>
  <verify>
Test batch with mixed results:
- 2 success, 1 error, 1 warning
- Summary shows: "Failed (1): containerX: Connection timeout"
- Summary shows: "Warnings: 1"
- Summary shows: "Successful: 2/4"
- "Back to List" button works
  </verify>
  <done>Final summary shows after batch; failures emphasized with names and reasons; warnings handled per discretion; navigation button returns to list</done>
</task>

</tasks>

<verification>
1. Workflow imports successfully in n8n
2. "update plex sonarr radarr" executes all three sequentially
3. Progress message updates for each container
4. One failure doesn't abort remaining containers
5. Final summary shows clear failure/success breakdown
6. Errors include container name and reason
</verification>

<success_criteria>
- Batch of 3 containers executes sequentially (not parallel)
- Each container shows progress as it completes
- If container 2 fails, container 3 still attempts
- Summary: "Failed (1): sonarr: image pull timeout" + "Successful: 2/3"
- User can navigate back to container list after batch
</success_criteria>

<output>
After completion, create `.planning/phases/09-batch-operations/09-02-SUMMARY.md`
</output>