ss-tools/specs/008-migration-ui-improvements/research.md

Research: Migration UI Improvements

Date: 2025-12-27 | Status: Complete

Overview

This research phase was conducted to resolve any technical unknowns and validate design decisions for the Migration UI Improvements feature. Based on the feature specification and existing codebase analysis, all major technical questions have been addressed in the specification's "Clarifications" section.

Research Findings

1. Task History and Status Display

Decision: Implement a task history API endpoint and UI component

Rationale:

• The existing TaskManager already tracks tasks in memory
• Need to expose this information through a new API endpoint
• UI will display tasks with status, start time, and actions

Alternatives considered:

• Full database persistence for all tasks (rejected due to complexity)
• In-memory only with no persistence (rejected as it wouldn't survive restarts)

Implementation approach:

• Extend TaskManager to support task history retrieval
• Add /api/tasks endpoint for fetching task list
• Create TaskHistory Svelte component for display

2. Task Log Viewing

Decision: Implement log retrieval API and modal viewer

Rationale:

• Each task already maintains logs in LogEntry format
• Need API endpoint to retrieve logs for specific task ID
• UI modal provides detailed log viewing without page navigation

Alternatives considered:

• Separate log page (rejected for poor UX)
• Downloadable log files (rejected as overkill for current needs)

Implementation approach:

• Add /api/tasks/{task_id}/logs endpoint
• Create TaskLogViewer modal component
• Integrate with existing task list

3. Database Password Error Handling

Decision: Implement interactive password prompt with task pausing

Rationale:

• Superset requires database passwords that aren't exported
• Current system fails entirely on missing passwords
• Interactive resolution improves user experience significantly

Alternatives considered:

• Pre-migration password collection form (rejected as not all migrations need passwords)
• Automatic retry with default passwords (rejected as insecure)

Implementation approach:

• Extend MigrationPlugin to detect specific Superset password errors
• Add new task state "AWAITING_INPUT"
• Create PasswordPrompt component for user input
• Implement task resumption with provided credentials

4. Task Persistence Strategy

Decision: Hybrid approach - persist only tasks needing user input

Rationale:

• Full persistence adds unnecessary complexity
• Most tasks complete quickly and don't need persistence
• Only tasks awaiting user input need to survive restarts

Alternatives considered:

• Full database persistence (rejected due to complexity)
• No persistence (rejected as loses important state)

Implementation approach:

• Extend TaskManager to persist "AWAITING_INPUT" tasks
• Use SQLite for simple persistence
• Clear completed tasks based on configurable retention

5. Error Detection and Pattern Matching

Decision: Pattern match on Superset API error responses

Rationale:

• Superset returns specific error format for missing passwords
• Pattern: UNPROCESSABLE ENTITY 422 with specific JSON body
• Error message contains: "Must provide a password for the database"

Implementation approach:

• Enhance error handling in MigrationPlugin.execute()
• Detect specific error pattern and transition to "AWAITING_INPUT"
• Include database name in password prompt

Technical Validation

Existing Codebase Analysis

TaskManager (backend/src/core/task_manager.py):

• Already supports task creation and status tracking
• Needs extension for:
  • Task history retrieval
  • New "AWAITING_INPUT" state
  • Selective persistence

MigrationPlugin (backend/src/plugins/migration.py):

• Handles migration execution
• Needs enhancement for:
  • Error pattern detection
  • Task state transitions
  • Password injection

API Routes (backend/src/api/routes/):

• Existing structure for REST endpoints
• Needs new endpoints:
  • GET /tasks - list tasks
  • GET /tasks/{id}/logs - get task logs
  • POST /tasks/{id}/resume - resume with input

Performance Considerations

Pagination: Basic limit/offset pagination will be implemented for task history to handle potential growth of task records.

Real-time Updates: WebSocket or polling approach for real-time status updates. Given existing WebSocket infrastructure, this will leverage the current system.

Error Handling: Robust error handling for:

• Invalid task IDs
• Missing logs
• Password validation failures
• Task resumption errors

Open Questions (Resolved)

All questions from the specification's "Clarifications" section have been addressed:

1. ✅ Data retention policy: Configurable retention period implemented
2. ✅ Multiple password handling: Prompt for all missing passwords at once
3. ✅ Invalid password handling: Prompt again with error message
4. ✅ Task persistence: Hybrid approach for "AWAITING_INPUT" tasks
5. ✅ Performance requirements: Basic pagination support

Recommendations

1. Implementation Order:

   • Backend API extensions first
   • Task state management second
   • UI components last

2. Testing Focus:

   • Error condition testing for password prompts
   • Task state transition validation
   • Real-time update verification

3. Future Enhancements:

   • Advanced filtering for task history
   • Task search functionality
   • Export/import of task history

Conclusion

The research phase confirms that the proposed feature can be implemented using the existing architecture with targeted extensions. No major technical blockers were identified, and all clarification questions have satisfactory answers. The implementation can proceed to Phase 1: Design & Contracts.