docs(08): create inline keyboard infrastructure plans

Phase 8: Inline Keyboard Infrastructure - 3 plans in 3 waves (sequential dependency) - Plan 01: Container list keyboard and submenu navigation - Plan 02: Action execution and confirmation flow - Plan 03: Progress feedback and completion messages Covers KEY-01 through KEY-05 requirements. Ready for execution. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 11:44:46 -05:00
parent fe4c19c7c6
commit ecd02a4b0e
4 changed files with 1013 additions and 2 deletions
@@ -0,0 +1,304 @@
+---
+phase: 08-inline-keyboard-infrastructure
+plan: 03
+type: execute
+wave: 3
+depends_on: [08-02]
+files_modified: [n8n-workflow.json]
+autonomous: false
+
+must_haves:
+  truths:
+    - "After action completes, message shows result with 'Back to menu' button"
+    - "Buttons are removed from completed action messages"
+    - "Update operations show progress message during execution"
+    - "Full keyboard flow works end-to-end"
+  artifacts:
+    - path: "n8n-workflow.json"
+      provides: "Completion message handlers"
+      contains: "Show Action Result"
+    - path: "n8n-workflow.json"
+      provides: "Progress feedback for updates"
+      contains: "Show Update Progress"
+  key_links:
+    - from: "container operation nodes"
+      to: "Show Action Result"
+      via: "completion flow"
+      pattern: "editMessageText"
+    - from: "Update Container flow"
+      to: "Show Update Progress"
+      via: "progress message"
+      pattern: "Updating"
+---
+
+<objective>
+Add progress feedback during operations and completion messages after actions finish.
+
+Purpose: Users see visual feedback during operations ("Updating plex...") and final results ("plex updated") with a button to return to the menu. This completes the inline keyboard UX.
+
+Output: Updated n8n-workflow.json with progress and completion handlers, plus full end-to-end verification.
+</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/08-inline-keyboard-infrastructure/08-CONTEXT.md
+@.planning/phases/08-inline-keyboard-infrastructure/08-RESEARCH.md
+@.planning/phases/08-inline-keyboard-infrastructure/08-01-SUMMARY.md
+@.planning/phases/08-inline-keyboard-infrastructure/08-02-SUMMARY.md
+@n8n-workflow.json
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add Completion Messages for Quick Actions</name>
+  <files>n8n-workflow.json</files>
+  <action>
+Add completion handlers that show results and "Back to menu" button after actions.
+
+Per user decision: Quick actions (start, stop, restart) show final result only, not progress.
+
+1. Create Code node "Build Action Success" that:
+   - Takes action result and context (chatId, messageId, containerName, actionType)
+   - Builds completion message based on action type
+   - Includes "Back to menu" button
+   - Removes action buttons (keyboard has only navigation)
+
+   ```javascript
+   const { chatId, messageId, containerName, actionType } = $json;
+
+   // Build success message based on action
+   const messages = {
+     start: `▶️ <b>${containerName}</b> started`,
+     stop: `⏹️ <b>${containerName}</b> stopped`,
+     restart: `🔄 <b>${containerName}</b> restarted`
+   };
+
+   const text = messages[actionType] || `Action completed on ${containerName}`;
+
+   const keyboard = {
+     inline_keyboard: [
+       [{ text: '◀️ Back to Containers', callback_data: 'list:0' }]
+     ]
+   };
+
+   return {
+     json: {
+       chatId,
+       messageId,
+       text,
+       reply_markup: keyboard
+     }
+   };
+   ```
+
+2. Create HTTP Request node "Show Action Result":
+   - Method: POST
+   - URL: editMessageText endpoint
+   - Body: chat_id, message_id, text, parse_mode, reply_markup
+
+3. Wire completion after each action:
+   - Start Container -> Build Action Success (with actionType='start') -> Show Action Result
+   - Stop Container -> Build Action Success (with actionType='stop') -> Show Action Result
+   - Restart Container -> Build Action Success (with actionType='restart') -> Show Action Result
+
+4. Handle action failures:
+   - Create Code node "Build Action Error":
+     ```javascript
+     const { chatId, messageId, containerName, actionType, error } = $json;
+
+     const text = `❌ Failed to ${actionType} <b>${containerName}</b>\n\n${error || 'Unknown error'}`;
+
+     const keyboard = {
+       inline_keyboard: [
+         [{ text: '🔄 Try Again', callback_data: `action:${actionType}:${containerName}` }],
+         [{ text: '◀️ Back to Containers', callback_data: 'list:0' }]
+       ]
+     };
+
+     return { json: { chatId, messageId, text, reply_markup: keyboard } };
+     ```
+   - Wire error outputs from container operations to error handler
+  </action>
+  <verify>
+    1. Start a stopped container via button
+    2. Verify: After start completes, message shows "plex started" with "Back to Containers" button
+    3. Stop a running container (confirm when prompted)
+    4. Verify: Shows "plex stopped" with back button
+    5. Restart a container
+    6. Verify: Shows "plex restarted" with back button
+    7. Tap "Back to Containers"
+    8. Verify: Returns to container list
+  </verify>
+  <done>
+    - Start shows completion message with back button
+    - Stop shows completion message with back button
+    - Restart shows completion message with back button
+    - Errors show retry and back buttons
+    - Action buttons removed after completion (only back button remains)
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add Progress Feedback for Update Operations</name>
+  <files>n8n-workflow.json</files>
+  <action>
+Add progress message for update operations (longer running than start/stop/restart).
+
+Per user decision: Updates show progress (simple status, not detailed steps).
+
+1. Create Code node "Build Update Progress" that shows in-progress state:
+   ```javascript
+   const { chatId, messageId, containerName } = $json;
+
+   return {
+     json: {
+       chatId,
+       messageId,
+       text: `⬆️ <b>Updating ${containerName}...</b>\n\nPulling latest image and recreating container.\nThis may take a few minutes.`,
+       reply_markup: { inline_keyboard: [] } // Remove buttons during update
+     }
+   };
+   ```
+
+2. Create HTTP Request "Show Update Progress":
+   - editMessageText with progress message
+   - Removes all buttons during operation
+
+3. Wire update flow:
+   - Route Confirmed Action (update) -> Answer Callback -> Build Update Progress -> Show Update Progress -> existing Update Container flow
+
+4. Create Code node "Build Update Success":
+   ```javascript
+   const { chatId, messageId, containerName } = $json;
+
+   const keyboard = {
+     inline_keyboard: [
+       [{ text: '◀️ Back to Containers', callback_data: 'list:0' }]
+     ]
+   };
+
+   return {
+     json: {
+       chatId,
+       messageId,
+       text: `✅ <b>${containerName}</b> updated successfully`,
+       reply_markup: keyboard
+     }
+   };
+   ```
+
+5. Wire update completion:
+   - After Update Container completes -> Build Update Success -> Show Action Result
+
+6. Handle update errors:
+   - Wire error path to Build Action Error with appropriate context
+  </action>
+  <verify>
+    1. Start update on a container (confirm when prompted)
+    2. Verify: Message immediately changes to "Updating plex..." with no buttons
+    3. Wait for update to complete
+    4. Verify: Message changes to "plex updated successfully" with back button
+    5. If update fails, verify error message appears with retry option
+  </verify>
+  <done>
+    - Update shows progress message during execution
+    - Buttons removed during update (prevents duplicate actions)
+    - Success message shown after update completes
+    - Error message with retry button if update fails
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 3: Full End-to-End Verification</name>
+  <what-built>
+    Complete inline keyboard infrastructure:
+    - Container list with tappable buttons
+    - Container submenu with action buttons
+    - Confirmation dialogs for dangerous actions
+    - Progress feedback for updates
+    - Completion messages with navigation
+  </what-built>
+  <how-to-verify>
+    **Flow 1: Basic Navigation**
+    1. Send "/status" to bot
+    2. Verify: Inline keyboard appears with container list
+    3. Tap a container name
+    4. Verify: Message edits to show container details and action buttons
+    5. Tap "Back to List"
+    6. Verify: Returns to container list
+
+    **Flow 2: Start Container**
+    1. From container list, tap a STOPPED container
+    2. Tap "Start" button
+    3. Verify: Container starts, message shows "started" with back button
+    4. Tap "Back to Containers"
+    5. Verify: Returns to list, container now shows as Running
+
+    **Flow 3: Stop Container (with confirmation)**
+    1. Tap a RUNNING container
+    2. Tap "Stop" button
+    3. Verify: Confirmation dialog appears "Stop container? Yes / No"
+    4. Tap "Cancel"
+    5. Verify: Returns to container submenu (not list)
+    6. Tap "Stop" again
+    7. Tap "Yes, Stop"
+    8. Verify: Container stops, message shows "stopped" with back button
+
+    **Flow 4: Update Container (with progress)**
+    1. Tap a container
+    2. Tap "Update" button
+    3. Verify: Confirmation dialog appears
+    4. Tap "Yes, Update"
+    5. Verify: Message shows "Updating..." with no buttons
+    6. Wait for completion
+    7. Verify: Message shows "updated successfully" with back button
+
+    **Flow 5: Confirmation Timeout**
+    1. Tap a container, tap "Stop"
+    2. Wait 35 seconds
+    3. Tap "Yes, Stop"
+    4. Verify: Shows "Confirmation expired" message
+
+    **Flow 6: Direct Access**
+    1. Send "/status plex" (or another container name)
+    2. Verify: Jumps directly to that container's submenu
+
+    **Flow 7: Pagination (if applicable)**
+    1. If you have >6 containers, verify pagination buttons work
+    2. If not, verify no pagination buttons appear
+  </how-to-verify>
+  <resume-signal>Type "approved" to mark Phase 8 complete, or describe any issues found</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+After completing all tasks:
+1. All KEY-01 through KEY-05 requirements met
+2. Full navigation flow works (list -> submenu -> action -> result -> list)
+3. Confirmations work with timeout
+4. Progress shown for updates
+5. Buttons removed after action completion
+6. No hanging loading indicators anywhere
+7. Direct access (/status name) works
+</verification>
+
+<success_criteria>
+- KEY-01: Status command shows container list with inline action buttons
+- KEY-02: Tapping action button performs start/stop/restart on container
+- KEY-03: Dangerous actions (stop, update) show confirmation dialog
+- KEY-04: Progress shown via message edit during operations
+- KEY-05: Buttons removed after action completes (only back button remains)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/08-inline-keyboard-infrastructure/08-03-SUMMARY.md`
+</output>