OpenNoodl/dev-docs/tasks/phase-2-react-migration/TASK-004-runtime-migration-system/00-OVERVIEW.md

React 19 Migration System - Implementation Overview

Feature Summary

A comprehensive migration system that allows users to safely upgrade legacy Noodl projects (React 17) to the new OpenNoodl runtime (React 19), with optional AI-assisted code migration.

Core Principles

1. Never modify originals - All migrations create a copy first
2. Transparent progress - Users see exactly what's happening and why
3. Graceful degradation - Partial success is still useful
4. Cost consent - AI assistance is opt-in with explicit budgets
5. No dead ends - Every failure state has a clear next step

Feature Components

Spec	Description	Priority
01-PROJECT-DETECTION	Detecting legacy projects and visual indicators	P0
02-MIGRATION-WIZARD	The migration flow UI and logic	P0
03-AI-MIGRATION	AI-assisted code migration system	P1
04-POST-MIGRATION-UX	Editor experience after migration	P0
05-NEW-PROJECT-NOTICE	Messaging for new project creation	P2

Implementation Order

Phase 1: Core Migration (No AI)

1. Project detection and version checking
2. Migration wizard UI (scan, report, execute)
3. Automatic migrations (no code changes needed)
4. Post-migration indicators in editor

Phase 2: AI-Assisted Migration

1. API key configuration and storage
2. Budget control system
3. Claude integration for code migration
4. Retry logic and failure handling

Phase 3: Polish

1. New project messaging
2. Migration log viewer
3. "Dismiss" functionality for warnings
4. Help documentation links

Data Structures

Project Manifest Addition

// Added to project.json
interface ProjectManifest {
  // Existing fields...
  
  // New migration tracking
  runtimeVersion?: 'react17' | 'react19';
  migratedFrom?: {
    version: 'react17';
    date: string;
    originalPath: string;
    aiAssisted: boolean;
  };
  migrationNotes?: {
    [componentId: string]: ComponentMigrationNote;
  };
}

interface ComponentMigrationNote {
  status: 'auto' | 'ai-migrated' | 'needs-review' | 'manually-fixed';
  issues?: string[];
  aiSuggestion?: string;
  dismissedAt?: string;
}

Migration Session State

interface MigrationSession {
  id: string;
  sourceProject: {
    path: string;
    name: string;
    version: 'react17';
  };
  targetPath: string;
  status: 'scanning' | 'reporting' | 'migrating' | 'complete' | 'failed';
  scan?: MigrationScan;
  progress?: MigrationProgress;
  result?: MigrationResult;
  aiConfig?: AIConfig;
}

interface MigrationScan {
  totalComponents: number;
  totalNodes: number;
  customJsFiles: number;
  categories: {
    automatic: ComponentInfo[];
    simpleFixes: ComponentInfo[];
    needsReview: ComponentInfo[];
  };
}

interface ComponentInfo {
  id: string;
  name: string;
  path: string;
  issues: MigrationIssue[];
}

interface MigrationIssue {
  type: 'componentWillMount' | 'componentWillReceiveProps' | 
        'componentWillUpdate' | 'stringRef' | 'legacyContext' | 
        'createFactory' | 'other';
  description: string;
  location: { file: string; line: number; };
  autoFixable: boolean;
  estimatedAiCost?: number;
}

File Structure

packages/noodl-editor/src/
├── editor/src/
│   ├── models/
│   │   └── migration/
│   │       ├── MigrationSession.ts
│   │       ├── ProjectScanner.ts
│   │       ├── MigrationExecutor.ts
│   │       └── AIAssistant.ts
│   ├── views/
│   │   └── migration/
│   │       ├── MigrationWizard.tsx
│   │       ├── ScanProgress.tsx
│   │       ├── MigrationReport.tsx
│   │       ├── AIConfigPanel.tsx
│   │       ├── MigrationProgress.tsx
│   │       └── MigrationComplete.tsx
│   └── utils/
│       └── migration/
│           ├── codeAnalyzer.ts
│           ├── codeTransformer.ts
│           └── costEstimator.ts

Dependencies

New Dependencies Needed

{
  "@anthropic-ai/sdk": "^0.24.0",
  "@babel/parser": "^7.24.0",
  "@babel/traverse": "^7.24.0",
  "@babel/generator": "^7.24.0"
}

Why These Dependencies

• @anthropic-ai/sdk - Official Anthropic SDK for Claude API calls
• @babel/* - Parse and transform JavaScript/JSX for code analysis and automatic fixes

Security Considerations

1. API Key Storage

   • Store in electron-store with encryption
   • Never log or transmit to OpenNoodl servers
   • Clear option to remove stored key

2. Cost Controls

   • Hard budget limits enforced client-side
   • Cannot be bypassed without explicit user action
   • Clear display of costs before and after

3. Code Execution

   • AI-generated code is shown to user before applying
   • Verification step before saving changes
   • Full undo capability via project copy

Testing Strategy

Unit Tests

• ProjectScanner correctly identifies all issue types
• Cost estimator accuracy within 20%
• Code transformer handles edge cases

Integration Tests

• Full migration flow with mock AI responses
• Budget controls enforce limits
• Project copy is byte-identical to original

Manual Testing

• Test with real legacy Noodl projects
• Test with projects containing various issue types
• Test AI migration with real API calls (budget: $5)

Success Metrics

• 95% of projects with only built-in nodes migrate automatically
• AI successfully migrates 80% of custom code on first attempt
• Zero data loss incidents
• Average migration time < 5 minutes for typical project