docs(05-02): complete error hardening and credential migration plan

Tasks completed: 2/2 - Standardize error messages to terse format - Migrate user ID to n8n credentials system SUMMARY: .planning/phases/05-polish-deploy/05-02-SUMMARY.md
2026-01-31 21:16:36 -05:00
parent 1e6c31f790
commit 09a4c9ba07
2 changed files with 113 additions and 9 deletions
@@ -0,0 +1,102 @@
+---
+phase: 05-polish-deploy
+plan: 02
+subsystem: error-handling
+tags: [n8n, error-messages, credentials, security]
+
+# Dependency graph
+requires:
+  - phase: 05-01
+    provides: keyword-router, nlu-removal
+provides:
+  - terse-error-messages
+  - credential-based-auth
+  - exportable-workflow
+affects: [deployment-readme]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [terse-errors, credential-references]
+
+key-files:
+  created: []
+  modified: [n8n-workflow.json]
+
+key-decisions:
+  - "Terse error format: 'Failed to {action} {container}' without technical details"
+  - "Docker socket errors: 'Cannot connect to Docker' regardless of underlying error"
+  - "Credential type: telegramAuth with userId field for user authentication"
+
+patterns-established:
+  - "Error messages single-line: no stack traces, no HTTP codes in user-facing text"
+  - "Credential references via $credentials.telegramAuth.userId in IF nodes"
+
+# Metrics
+duration: 3min
+completed: 2026-02-01
+---
+
+# Phase 5 Plan 02: Error Hardening & Credential Migration Summary
+
+**Terse error messages ("Cannot connect to Docker", "Failed to X Y") and user ID moved to n8n credentials system**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-02-01T02:12:51Z
+- **Completed:** 2026-02-01T02:15:32Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+- All Docker socket errors now show "Cannot connect to Docker" (4 locations)
+- Action failures show "Failed to {action} {container}" without verbose details
+- User ID removed from workflow JSON - now uses `$credentials.telegramAuth.userId`
+- Workflow can be safely exported and shared without exposing sensitive data
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Standardize error messages** - `cab0914` (chore)
+2. **Task 2: Migrate user ID to credentials** - `1e6c31f` (feat)
+
+## Files Created/Modified
+- `n8n-workflow.json` - Updated error messages and auth node credential references
+
+## Decisions Made
+- **Terse error format:** "Failed to {action} {container}" without HTTP codes or technical details
+- **Docker socket errors:** Unified to "Cannot connect to Docker" message
+- **Credential naming:** `telegramAuth` credential type with `userId` field (per RESEARCH.md pattern)
+- **Removed switch/case error handling:** All action errors now use single terse message
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## User Setup Required
+
+**External services require manual configuration.** During deployment:
+
+1. Create "Telegram Auth" credential in n8n:
+   - Type: Header Auth (or generic credential)
+   - Name: `Telegram Auth`
+   - Field: `userId` = your Telegram user ID
+
+2. After importing workflow, map credentials:
+   - `Telegram API` -> your bot token credential
+   - `Telegram Auth` -> your user ID credential
+
+## Next Phase Readiness
+- Error messages production-ready (terse, user-friendly)
+- Workflow exportable without sensitive data
+- Ready for Plan 03: Deployment README
+
+---
+*Phase: 05-polish-deploy*
+*Completed: 2026-02-01*