unraid-docker-manager/.planning/phases/09-batch-operations/09-01-SUMMARY.md

Phase 9 Plan 01: Batch Command Parsing Summary

Completed: 2026-02-04 Duration: ~9 minutes

One-liner

Batch command detection with exact-match-priority container matching and batch stop confirmation flow.

What Was Built

Batch Command Detection

• Added "Detect Batch Command" code node that parses multi-container commands
• Pattern: {action} {name1} {name2} ... where action is update/start/stop/restart
• Single container (1 name) routes to existing single-container flow
• Multiple containers (2+ names) routes to new batch processing flow
• "Is Batch Command" IF node for routing decision

Container Matching with Exact-Match Priority

• Added "Match Batch Containers" code node with sophisticated matching algorithm:
  1. Exact match first: 'plex' matches 'plex' even when 'jellyplex' exists
  2. Single fuzzy match: Treated as found (no disambiguation needed)
  3. Multiple fuzzy matches: Triggers disambiguation with keyboard options
  4. No matches: Reported as not found with option to proceed with found containers
• "Needs Disambiguation" IF node routes to disambiguation or execution path

Disambiguation Flow

• "Build Disambiguation Message" code node creates inline keyboard with options
• Each ambiguous input shows matching container names as buttons
• User can select exact container to resolve ambiguity
• Callback format: bselect:{action}:{containerName}

Not Found Handling

• "Build Not Found Message" code node reports missing containers
• If some containers matched, offers to proceed with found containers
• Callback format for proceed: bexec:{action}:{names}:{timestamp}

Batch Stop Confirmation

• "Route Batch Action" switch routes by action type
• Batch stop requires confirmation (per context: fuzzy matching risk)
• "Build Batch Stop Confirmation" shows container list with Confirm/Cancel
• Callback format: bstop:confirm:{names}:{timestamp} or bstop:cancel
• 30-second timeout validation on confirmation
• Other batch actions (update/start/restart) proceed immediately

Callback Handling

• Updated "Parse Callback Data" to handle new prefixes: bstop:, bexec:, bselect:
• Added Route Callback outputs for batch operations
• Added callback handler nodes with proper answer/delete flows

Key Decisions Made

Decision	Rationale
Detect batch after Keyword Router	Minimal change to existing flow, single interception point for all action types
Route single action via switch	Clean separation between action types for future extension
Exact match has absolute priority	User typing exact name expects that container, not similar ones
Single fuzzy match treated as found	Reduces unnecessary confirmation for clear intent
Batch stop requires confirmation	Context specifies fuzzy matching risk for stop operations
30-second timeout on confirmations	Consistent with existing single-container confirmation behavior
Comma-separated names in callback	Fits within 64-byte callback_data limit for typical batch sizes

Technical Details

New Nodes Added (14 total)

1. Detect Batch Command (code)
2. Is Batch Command (if)
3. Route Single Action (switch)
4. Get Containers for Batch (executeCommand)
5. Match Batch Containers (code)
6. Needs Disambiguation (if)
7. Build Disambiguation Message (code)
8. Send Disambiguation (httpRequest)
9. Has Not Found (if)
10. Build Not Found Message (code)
11. Send Not Found Message (httpRequest)
12. Route Batch Action (switch)
13. Build Batch Stop Confirmation (code)
14. Send Batch Stop Confirmation (httpRequest)

Callback Handler Nodes (5 total)

1. Answer Batch Stop Confirm
2. Answer Batch Stop Cancel
3. Answer Batch Exec
4. Check Batch Stop Expired
5. Build/Send Batch Stop Expired

Callback Data Formats

• bstop:confirm:{comma-names}:{timestamp} - Batch stop confirmation
• bstop:cancel - Batch stop cancellation
• bexec:{action}:{comma-names}:{timestamp} - Batch execution
• bselect:{action}:{containerName} - Disambiguation selection

Commits

Commit	Description
9e7ff2a	Add batch command detection and parsing
f02f984	Add container matching with exact-match priority
feea06c	Wire batch routing and add batch stop confirmation

Next Phase Readiness

Ready for Plan 02: Batch execution and progress display.

The following are now available for Plan 02:

• Parsed batch data structure: { action, containerNames, allMatched, chatId, ... }
• Route Batch Action outputs for update/start/restart ready to connect to execution
• Callback formats defined for batch confirmation and execution
• Container matching resolves names to container objects with Id, Name, State

Note: Route Batch Action has empty outputs for update/start/restart - Plan 02 will connect these to batch execution flow.

Deviations from Plan

None - plan executed exactly as written.