React 19 runtime migration complete, AI-assisted migration underway

2026-01-13 15:52:56 +01:00 · 2025-12-20 23:32:50 +01:00
parent 7d307066d8
commit 03a464f6ff
22 changed files with 3081 additions and 145 deletions
--- a/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/README.md
+++ b/dev-docs/tasks/phase-2/TASK-007-wire-ai-migration/README.md
@@ -0,0 +1,348 @@
+# TASK-007: Wire AI Migration Backend
+
+## Metadata
+
+| Field              | Value                        |
+| ------------------ | ---------------------------- |
+| **ID**             | TASK-007                     |
+| **Phase**          | Phase 2                      |
+| **Priority**       | 🟠 High                      |
+| **Difficulty**     | 🟡 Medium                    |
+| **Estimated Time** | 3-4 hours                    |
+| **Prerequisites**  | TASK-004 (complete)          |
+| **Branch**         | `task/007-wire-ai-migration` |
+
+## Objective
+
+Connect the fully-built AI migration infrastructure (AIMigrationOrchestrator, ClaudeClient, BudgetController) to the MigrationSession's `executeAIAssistedPhase()` stub to enable end-to-end AI-powered component migration.
+
+## Background
+
+TASK-004 implemented a comprehensive React 19 migration system with optional AI assistance. During development, all the AI infrastructure components were built and tested:
+
+- **ClaudeClient**: Handles Anthropic API communication with proper prompt engineering
+- **BudgetController**: Manages spending limits, pause increments, and approval flow
+- **AIMigrationOrchestrator**: Coordinates component migration with retry logic, verification, and decision points
+- **AIConfigPanel**: UI for configuring API key, budget, and preferences
+- **BudgetApprovalDialog**: UI for budget pause confirmations
+- **keyStorage**: Encrypted API key storage with Electron safeStorage
+
+However, the actual integration point in `MigrationSession.executeAIAssistedPhase()` was intentionally left as a stub with a TODO comment. This was done to:
+
+1. Allow the UI and scanning flow to be tested independently
+2. Avoid consuming API credits during development
+3. Defer the wiring work to a focused integration task
+
+**Current Behavior:**
+When a user clicks "Migrate with AI", the system:
+
+- Immediately marks all `needsReview` components as "AI migration not yet implemented"
+- Completes the migration instantly without calling Claude
+- Logs warnings instead of performing actual migrations
+
+**The Problem:**
+Users who configure an API key and budget cannot actually use AI migration, making the entire AI feature non-functional.
+
+## Current State
+
+### Working Components
+
+- ✅ AI configuration UI (AIConfigPanel)
+- ✅ API key validation and encrypted storage
+- ✅ Budget configuration UI
+- ✅ ClaudeClient with prompt engineering
+- ✅ BudgetController with spending tracking
+- ✅ AIMigrationOrchestrator with retry logic
+- ✅ BudgetApprovalDialog component
+- ✅ Scan results correctly identify `needsReview` components
+
+### Non-Working Code Path
+
+- ❌ `MigrationSession.executeAIAssistedPhase()` is a stub (lines ~500-520)
+- ❌ Orchestrator never initialized
+- ❌ Claude API never called
+- ❌ Budget approval dialog never shown
+- ❌ Decision dialog for failed retries doesn't exist
+- ❌ Migrated code never written to target files
+
+### Current Stub Implementation
+
+```typescript
+private async executeAIAssistedPhase(): Promise<void> {
+  if (!this.session?.scan || !this.session.ai?.enabled) return;
+
+  this.updateProgress({ phase: 'ai-assisted' });
+  this.addLogEntry({
+    level: 'info',
+    message: 'Starting AI-assisted migration...'
+  });
+
+  const { needsReview } = this.session.scan.categories;
+
+  for (let i = 0; i < needsReview.length; i++) {
+    const component = needsReview[i];
+
+    this.updateProgress({
+      currentComponent: component.name
+    });
+
+    // TODO: Implement actual AI migration using Claude API
+    await this.simulateDelay(200);
+
+    this.addLogEntry({
+      level: 'warning',
+      component: component.name,
+      message: 'AI migration not yet implemented - marked for manual review'
+    });
+  }
+}
+```
+
+## Desired State
+
+When a user clicks "Migrate with AI" after configuring their API key and budget:
+
+1. **Orchestrator Initialization**: AIMigrationOrchestrator is created with the user's API key and budget settings
+2. **Component Processing**: Each `needsReview` component is sent to Claude for migration
+3. **Budget Pauses**: BudgetApprovalDialog appears when spending reaches pause increments
+4. **Retry Logic**: Failed migrations are automatically retried with different approaches
+5. **Decision Points**: After max retries, user chooses to retry, skip, get help, or accept partial result
+6. **Result Application**: Successfully migrated code is written to target files
+7. **Accurate Reporting**: Final counts reflect actual migration outcomes, not stubs
+
+### User Experience Flow
+
+```
+[Click "Migrate with AI"]
+  ↓
+[Orchestrator initializes]
+  ↓
+[For each component needing AI:]
+  ├─ Read source code from original location
+  ├─ Send to Claude with migration request
+  ├─ [Budget pause?] → Show BudgetApprovalDialog
+  ├─ [Success?] → Write migrated code to target
+  └─ [Failed after retries?] → Show DecisionDialog
+  ↓
+[Display accurate results]
+```
+
+## Scope
+
+### In Scope
+
+- [x] Initialize AIMigrationOrchestrator in `executeAIAssistedPhase()`
+- [x] Read source code for each `needsReview` component
+- [x] Call `orchestrator.migrateComponent()` with proper callbacks
+- [x] Implement `onBudgetPause` callback to show approval dialog
+- [x] Implement `onDecisionRequired` callback for retry decisions
+- [x] Create DecisionDialog component for failed migrations
+- [x] Write successful migrations to target files
+- [x] Update progress log with real results
+- [x] Track actual budget spending
+- [x] Handle orchestrator abort on session cancel
+
+### Out of Scope
+
+- Improving Claude prompts (already done in TASK-004)
+- Changing budget UI (already done in TASK-004)
+- Adding new migration strategies (orchestrator already supports them)
+- Changing the scan logic (TASK-004 complete)
+- Optimizing API costs (can be a future task)
+
+## Technical Approach
+
+### Key Files to Modify
+
+| File                                                                           | Changes                                                                    |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `packages/noodl-editor/src/editor/src/models/migration/MigrationSession.ts`    | Replace `executeAIAssistedPhase()` stub with real orchestrator integration |
+| `packages/noodl-editor/src/editor/src/views/migration/MigrationWizard.tsx`     | Add state for budget/decision dialogs, wire callbacks                      |
+| `packages/noodl-editor/src/editor/src/views/migration/steps/MigratingStep.tsx` | Display budget approval and decision dialogs during migration              |
+
+### New Files to Create
+
+| File                                                                              | Purpose                                                   |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `packages/noodl-editor/src/editor/src/views/migration/DecisionDialog.tsx`         | UI for choosing what to do after failed migration retries |
+| `packages/noodl-editor/src/editor/src/views/migration/DecisionDialog.module.scss` | Styles for DecisionDialog                                 |
+
+### Dependencies
+
+- ✅ `AIMigrationOrchestrator` (already exists)
+- ✅ `ClaudeClient` (already exists)
+- ✅ `BudgetController` (already exists)
+- ✅ `BudgetApprovalDialog` (already exists)
+- ✅ API key storage (already exists)
+- ✅ Types for all interfaces (already exists in `types.ts`)
+
+## Implementation Steps
+
+### Step 1: Create DecisionDialog Component
+
+Create the UI for handling failed migration retries. User can choose to:
+
+- **Retry**: Start over with fresh retry attempts
+- **Skip**: Mark component for manual review
+- **Get Help**: Show AI's detailed manual migration instructions
+- **Accept Partial**: Use the last attempted migration (may need fixes)
+
+### Step 2: Wire Budget Approval Flow
+
+Modify MigrationWizard and MigratingStep to:
+
+- Store budget approval state
+- Show BudgetApprovalDialog when orchestrator pauses
+- Return approval decision to orchestrator
+- Resume or abort based on user choice
+
+### Step 3: Wire Decision Flow
+
+Modify MigrationWizard and MigratingStep to:
+
+- Store decision request state
+- Show DecisionDialog when retries exhausted
+- Handle user's choice (retry/skip/help/manual)
+- Display AI help text if requested
+
+### Step 4: Implement executeAIAssistedPhase()
+
+Replace the stub with real implementation:
+
+- Initialize AIMigrationOrchestrator with API key and budget
+- Loop through `needsReview` components
+- Read source code using filesystem
+- Call `orchestrator.migrateComponent()` with callbacks
+- Handle all possible result types (success/partial/failed/skipped)
+- Write successful migrations to target files
+- Update progress and logs accurately
+
+### Step 5: Handle Session Abort
+
+Ensure orchestrator stops cleanly if:
+
+- User cancels migration
+- Error occurs
+- Budget exhausted
+
+### Step 6: End-to-End Testing
+
+Test the complete flow with real API calls:
+
+- Small budget (e.g., $0.50) to test pause behavior
+- Component that should succeed
+- Component that might fail (to test retry/decision flow)
+- Verify budget tracking is accurate
+- Verify migrated code is written correctly
+
+## Testing Plan
+
+### Manual Testing Scenarios
+
+#### Scenario 1: Successful Migration
+
+- [ ] Configure API key and $2 budget
+- [ ] Scan project with 1-2 simple `needsReview` components
+- [ ] Click "Migrate with AI"
+- [ ] Verify Claude is called
+- [ ] Verify migrated code is written to target
+- [ ] Verify success log entries
+- [ ] Verify budget spending is tracked
+
+#### Scenario 2: Budget Pause
+
+- [ ] Configure API key with $2 budget and $0.50 pause increment
+- [ ] Scan project with 5+ components needing AI
+- [ ] Click "Migrate with AI"
+- [ ] Verify BudgetApprovalDialog appears after ~$0.50 spent
+- [ ] Click "Stop Here" and verify migration stops
+- [ ] Retry, click "Continue" and verify migration resumes
+
+#### Scenario 3: Failed Migration with Retry
+
+- [ ] Configure API key
+- [ ] Scan project with complex component likely to fail
+- [ ] Click "Migrate with AI"
+- [ ] Verify retry attempts are logged
+- [ ] Verify DecisionDialog appears after max retries
+- [ ] Test each decision option:
+  - "Retry" → migration starts over
+  - "Skip" → component marked for manual review
+  - "Get Help" → AI suggestions displayed
+  - "Accept Partial" → last attempt code is used
+
+#### Scenario 4: Abort During Migration
+
+- [ ] Start AI migration
+- [ ] Click cancel button mid-migration
+- [ ] Verify orchestrator stops cleanly
+- [ ] Verify partial results are saved
+- [ ] Verify budget tracking is correct
+
+#### Scenario 5: API Key Invalid
+
+- [ ] Configure invalid API key
+- [ ] Try to migrate
+- [ ] Verify clear error message
+- [ ] Verify session doesn't enter broken state
+
+### Integration Tests
+
+- [ ] Mock ClaudeClient and test orchestrator integration
+- [ ] Test budget controller callback flow
+- [ ] Test decision flow callback
+- [ ] Test file writing with mock filesystem
+
+## Success Criteria
+
+- [x] AIMigrationOrchestrator initializes with correct API key and budget
+- [x] Each `needsReview` component is sent to Claude API
+- [x] Budget approval dialog appears at spending thresholds
+- [x] User can approve/deny additional spending
+- [x] Decision dialog appears after failed retries
+- [x] All decision actions (retry/skip/help/manual) work
+- [x] Successful migrations are written to target files
+- [x] Migration log shows accurate results (not stub warnings)
+- [x] Budget spending is tracked accurately
+- [x] Orchestrator aborts cleanly on session cancel
+- [x] End-to-end test with real Claude API succeeds
+- [x] All TypeScript types are satisfied
+- [x] No console errors during migration
+
+## Risks & Mitigations
+
+| Risk                                        | Mitigation                                                     |
+| ------------------------------------------- | -------------------------------------------------------------- |
+| API costs during testing                    | Use small budgets ($0.50-$1.00), test with minimal projects    |
+| API rate limits                             | Implement exponential backoff in ClaudeClient (already exists) |
+| Invalid API key at runtime                  | Validate key before starting migration, clear error handling   |
+| Budget dialog blocks UI thread              | Use async callbacks, ensure dialogs are dismissible            |
+| Failed migrations corrupt files             | Write to target (copy) not source, verify before writing       |
+| Orchestrator memory leak on long migrations | Ensure orchestrator is disposed after migration                |
+
+## Rollback Plan
+
+If issues are discovered after wiring:
+
+1. **Immediate Rollback**:
+
+   ```typescript
+   // In executeAIAssistedPhase(), wrap in try-catch
+   try {
+     // New orchestrator code
+   } catch (error) {
+     // Fall back to stub behavior
+     this.addLogEntry({ level: 'error', message: error.message });
+   }
+   ```
+
+2. **File Restoration**: Target files are in a copy, source never modified
+3. **Re-disable AI**: Set `ai.enabled = false` in config if orchestrator fails
+4. **Revert Commits**: `git revert` the wiring changes
+
+## References
+
+- [TASK-004: Runtime Migration System](./TASK-004-runtime-migration-system/README.md) - Prerequisite task
+- [03-AI-MIGRATION.md](./TASK-004-runtime-migration-system/03-AI-MIGRATION.md) - Full AI architecture spec
+- [Anthropic API Documentation](https://docs.anthropic.com/claude/reference/getting-started-with-the-api)
+- [React 19 Migration Guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide)