elsabro 2.3.0 → 3.8.0

package/references/time-travel.md

@@ -0,0 +1,802 @@
+---
+name: time-travel
+description: Sistema de time-travel debugging para análisis y replay de sesiones
+version: 1.0.0
+---
+
+# ELSABRO Time-Travel Debugging System
+
+## Vision General
+
+El sistema de Time-Travel Debugging permite navegar por la historia de ejecución, analizar decisiones pasadas, y explorar caminos alternativos ("what-if" analysis).
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    TIME-TRAVEL ARCHITECTURE                               │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   TIMELINE                                                               │
+│   ═══════════════════════════════════════════════════════════════       │
+│   │                                                                      │
+│   ▼                                                                      │
+│   [CP1]────[CP2]────[CP3]────[CP4]────[CP5]────[CURRENT]                │
+│    │        │        │        │        │                                 │
+│    │        │        │        │        └── Review complete               │
+│    │        │        │        └── Implementation done                    │
+│    │        │        └── Plan approved                                   │
+│    │        └── Analysis complete                                        │
+│    └── Session started                                                   │
+│                                                                          │
+│   OPERATIONS                                                             │
+│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
+│   │  REPLAY  │  │  JUMP    │  │  BRANCH  │  │  COMPARE │               │
+│   │ (watch)  │  │ (goto)   │  │ (fork)   │  │ (diff)   │               │
+│   └──────────┘  └──────────┘  └──────────┘  └──────────┘               │
+│                                                                          │
+│   WHAT-IF ANALYSIS                                                       │
+│   ┌──────────────────────────────────────────────────────────────┐      │
+│   │  Original: CP3 ─── [Decision A] ─── CP4 ─── CP5              │      │
+│   │                         │                                     │      │
+│   │  Branch:   CP3 ─── [Decision B] ─── CP4' ─── ?               │      │
+│   │                    (alternative)                              │      │
+│   └──────────────────────────────────────────────────────────────┘      │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Componentes del Sistema
+
+### 1. Timeline Manager
+
+Gestiona la línea de tiempo de ejecución.
+
+```javascript
+/**
+ * TimelineManager
+ * Gestiona la línea de tiempo de ejecución para time-travel
+ */
+class TimelineManager {
+  constructor(checkpointManager) {
+    this.checkpointManager = checkpointManager;
+    this.timeline = [];
+    this.currentPosition = -1;
+    this.branches = new Map();
+    this.mainBranch = 'main';
+    this.activeBranch = 'main';
+  }
+
+  /**
+   * Construye timeline desde checkpoints
+   */
+  async buildTimeline(sessionId) {
+    const checkpoints = await this.checkpointManager.listCheckpoints(sessionId, {
+      limit: 1000
+    });
+
+    this.timeline = checkpoints.map((cp, index) => ({
+      index,
+      checkpointId: cp.checkpointId,
+      timestamp: cp.createdAt,
+      event: cp.event,
+      phase: cp.phase,
+      summary: this.generateSummary(cp),
+      branch: 'main'
+    }));
+
+    this.currentPosition = this.timeline.length - 1;
+
+    return this.timeline;
+  }
+
+  /**
+   * Genera resumen legible de un checkpoint
+   */
+  generateSummary(checkpoint) {
+    const summaries = {
+      'FLOW_START': 'Session started',
+      'PHASE_START': `Started phase: ${checkpoint.phase}`,
+      'PHASE_COMPLETE': `Completed phase: ${checkpoint.phase}`,
+      'NODE_COMPLETE': `Completed node: ${checkpoint.nodeId}`,
+      'AGENT_COMPLETE': `Agent finished: ${checkpoint.agentId}`,
+      'INTERRUPT': `Waiting for input: ${checkpoint.reason}`,
+      'DECISION': `Decision made: ${checkpoint.decision}`,
+      'ERROR': `Error occurred: ${checkpoint.error}`,
+      'ROLLBACK': `Rolled back to: ${checkpoint.targetId}`
+    };
+
+    return summaries[checkpoint.event] || checkpoint.event;
+  }
+
+  /**
+   * Obtiene posición actual en timeline
+   */
+  getCurrentPosition() {
+    return {
+      index: this.currentPosition,
+      checkpoint: this.timeline[this.currentPosition],
+      total: this.timeline.length,
+      isLatest: this.currentPosition === this.timeline.length - 1,
+      branch: this.activeBranch
+    };
+  }
+
+  /**
+   * Salta a una posición específica
+   */
+  async jumpTo(position) {
+    if (position < 0 || position >= this.timeline.length) {
+      throw new Error(`Invalid position: ${position}`);
+    }
+
+    const checkpoint = this.timeline[position];
+    await this.checkpointManager.loadCheckpoint(checkpoint.checkpointId);
+
+    this.currentPosition = position;
+
+    return {
+      position: this.currentPosition,
+      checkpoint,
+      state: await this.checkpointManager.getStateAt(checkpoint.checkpointId)
+    };
+  }
+
+  /**
+   * Avanza un paso
+   */
+  async stepForward() {
+    if (this.currentPosition >= this.timeline.length - 1) {
+      return { atEnd: true };
+    }
+
+    return this.jumpTo(this.currentPosition + 1);
+  }
+
+  /**
+   * Retrocede un paso
+   */
+  async stepBackward() {
+    if (this.currentPosition <= 0) {
+      return { atBeginning: true };
+    }
+
+    return this.jumpTo(this.currentPosition - 1);
+  }
+
+  /**
+   * Crea una rama alternativa desde la posición actual
+   */
+  async createBranch(branchName) {
+    if (this.branches.has(branchName)) {
+      throw new Error(`Branch ${branchName} already exists`);
+    }
+
+    const branchPoint = this.timeline[this.currentPosition];
+
+    this.branches.set(branchName, {
+      name: branchName,
+      createdAt: new Date().toISOString(),
+      branchPoint: branchPoint.checkpointId,
+      branchPosition: this.currentPosition,
+      timeline: []
+    });
+
+    this.activeBranch = branchName;
+
+    return {
+      branch: branchName,
+      branchPoint: branchPoint,
+      position: this.currentPosition
+    };
+  }
+
+  /**
+   * Cambia a una rama
+   */
+  async switchBranch(branchName) {
+    if (branchName === 'main') {
+      this.activeBranch = 'main';
+      return { branch: 'main', timeline: this.timeline };
+    }
+
+    if (!this.branches.has(branchName)) {
+      throw new Error(`Branch ${branchName} not found`);
+    }
+
+    const branch = this.branches.get(branchName);
+    this.activeBranch = branchName;
+
+    // Combinar timeline principal hasta branch point + branch timeline
+    const combinedTimeline = [
+      ...this.timeline.slice(0, branch.branchPosition + 1),
+      ...branch.timeline
+    ];
+
+    return {
+      branch: branchName,
+      timeline: combinedTimeline,
+      branchPoint: branch.branchPosition
+    };
+  }
+
+  /**
+   * Lista todas las ramas
+   */
+  listBranches() {
+    const branches = [
+      {
+        name: 'main',
+        isActive: this.activeBranch === 'main',
+        length: this.timeline.length,
+        branchPoint: null
+      }
+    ];
+
+    for (const [name, branch] of this.branches) {
+      branches.push({
+        name,
+        isActive: this.activeBranch === name,
+        length: branch.timeline.length,
+        branchPoint: branch.branchPosition,
+        createdAt: branch.createdAt
+      });
+    }
+
+    return branches;
+  }
+}
+```
+
+### 2. Replay Engine
+
+Motor para reproducir ejecuciones pasadas.
+
+```javascript
+/**
+ * ReplayEngine
+ * Reproduce ejecuciones pasadas step-by-step
+ */
+class ReplayEngine {
+  constructor(timelineManager, options = {}) {
+    this.timeline = timelineManager;
+    this.config = {
+      speed: options.speed || 1.0, // 1.0 = tiempo real
+      autoPlay: options.autoPlay || false,
+      pauseOnDecision: options.pauseOnDecision || true,
+      pauseOnError: options.pauseOnError || true
+    };
+
+    this.state = {
+      isPlaying: false,
+      isPaused: false,
+      currentStep: 0,
+      totalSteps: 0
+    };
+
+    this.listeners = new Set();
+  }
+
+  /**
+   * Inicia replay desde posición actual
+   */
+  async startReplay(options = {}) {
+    const startPosition = options.from || 0;
+    const endPosition = options.to || this.timeline.timeline.length - 1;
+
+    this.state = {
+      isPlaying: true,
+      isPaused: false,
+      currentStep: startPosition,
+      totalSteps: endPosition - startPosition + 1,
+      startPosition,
+      endPosition
+    };
+
+    await this.timeline.jumpTo(startPosition);
+    this.emit('replay_started', { position: startPosition });
+
+    if (this.config.autoPlay) {
+      await this.play();
+    }
+
+    return this.state;
+  }
+
+  /**
+   * Reproduce automáticamente
+   */
+  async play() {
+    while (this.state.isPlaying && !this.state.isPaused) {
+      const result = await this.step();
+
+      if (result.atEnd) {
+        this.state.isPlaying = false;
+        this.emit('replay_complete', { steps: this.state.currentStep });
+        break;
+      }
+
+      // Pausa en decisiones si está configurado
+      if (this.config.pauseOnDecision && result.checkpoint.event === 'DECISION') {
+        this.pause();
+        this.emit('paused_on_decision', result);
+        break;
+      }
+
+      // Pausa en errores si está configurado
+      if (this.config.pauseOnError && result.checkpoint.event === 'ERROR') {
+        this.pause();
+        this.emit('paused_on_error', result);
+        break;
+      }
+
+      // Delay basado en velocidad
+      const delay = this.calculateDelay(result);
+      await this.sleep(delay);
+    }
+  }
+
+  /**
+   * Avanza un paso en el replay
+   */
+  async step() {
+    if (this.state.currentStep >= this.state.endPosition) {
+      return { atEnd: true };
+    }
+
+    const result = await this.timeline.stepForward();
+    this.state.currentStep++;
+
+    this.emit('step', {
+      step: this.state.currentStep,
+      total: this.state.totalSteps,
+      checkpoint: result.checkpoint,
+      state: result.state
+    });
+
+    return result;
+  }
+
+  /**
+   * Retrocede un paso
+   */
+  async stepBack() {
+    if (this.state.currentStep <= this.state.startPosition) {
+      return { atBeginning: true };
+    }
+
+    const result = await this.timeline.stepBackward();
+    this.state.currentStep--;
+
+    this.emit('step_back', {
+      step: this.state.currentStep,
+      checkpoint: result.checkpoint
+    });
+
+    return result;
+  }
+
+  /**
+   * Pausa el replay
+   */
+  pause() {
+    this.state.isPaused = true;
+    this.emit('paused', { step: this.state.currentStep });
+  }
+
+  /**
+   * Reanuda el replay
+   */
+  async resume() {
+    this.state.isPaused = false;
+    this.emit('resumed', { step: this.state.currentStep });
+    await this.play();
+  }
+
+  /**
+   * Detiene el replay
+   */
+  stop() {
+    this.state.isPlaying = false;
+    this.state.isPaused = false;
+    this.emit('stopped', { step: this.state.currentStep });
+  }
+
+  /**
+   * Cambia velocidad de replay
+   */
+  setSpeed(speed) {
+    this.config.speed = speed;
+    this.emit('speed_changed', { speed });
+  }
+
+  /**
+   * Calcula delay entre pasos
+   */
+  calculateDelay(result) {
+    // Base delay de 500ms, ajustado por velocidad
+    const baseDelay = 500;
+    return baseDelay / this.config.speed;
+  }
+
+  /**
+   * Event emitter
+   */
+  on(event, callback) {
+    this.listeners.add({ event, callback });
+    return () => this.listeners.delete({ event, callback });
+  }
+
+  emit(event, data) {
+    for (const listener of this.listeners) {
+      if (listener.event === event) {
+        listener.callback(data);
+      }
+    }
+  }
+
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+### 3. What-If Analyzer
+
+Analizador de escenarios alternativos.
+
+```javascript
+/**
+ * WhatIfAnalyzer
+ * Analiza escenarios alternativos ("what-if")
+ */
+class WhatIfAnalyzer {
+  constructor(timelineManager, flowEngine) {
+    this.timeline = timelineManager;
+    this.flowEngine = flowEngine;
+    this.scenarios = new Map();
+  }
+
+  /**
+   * Crea un escenario what-if desde un punto
+   */
+  async createScenario(name, options = {}) {
+    const { fromPosition, alternativeDecision, alternativeInputs } = options;
+
+    // Crear branch
+    await this.timeline.jumpTo(fromPosition);
+    await this.timeline.createBranch(`whatif_${name}`);
+
+    const scenario = {
+      id: `scenario_${Date.now()}`,
+      name,
+      createdAt: new Date().toISOString(),
+      branchPoint: fromPosition,
+      originalDecision: this.timeline.timeline[fromPosition],
+      alternativeDecision,
+      alternativeInputs,
+      status: 'created',
+      results: null
+    };
+
+    this.scenarios.set(scenario.id, scenario);
+
+    return scenario;
+  }
+
+  /**
+   * Ejecuta un escenario what-if
+   */
+  async runScenario(scenarioId) {
+    const scenario = this.scenarios.get(scenarioId);
+
+    if (!scenario) {
+      throw new Error(`Scenario ${scenarioId} not found`);
+    }
+
+    scenario.status = 'running';
+    scenario.startedAt = new Date().toISOString();
+
+    try {
+      // Restaurar estado en branch point
+      const state = await this.timeline.checkpointManager.getStateAt(
+        this.timeline.timeline[scenario.branchPoint].checkpointId
+      );
+
+      // Aplicar decisión/inputs alternativos
+      const modifiedState = this.applyAlternatives(state, scenario);
+
+      // Ejecutar flow desde ese punto
+      const result = await this.flowEngine.executeFromState(modifiedState, {
+        branchName: `whatif_${scenario.name}`,
+        dryRun: false
+      });
+
+      scenario.status = 'completed';
+      scenario.completedAt = new Date().toISOString();
+      scenario.results = result;
+
+      return scenario;
+
+    } catch (error) {
+      scenario.status = 'failed';
+      scenario.error = error.message;
+      throw error;
+    }
+  }
+
+  /**
+   * Aplica alternativas al estado
+   */
+  applyAlternatives(state, scenario) {
+    const modified = JSON.parse(JSON.stringify(state));
+
+    if (scenario.alternativeDecision) {
+      // Reemplazar decisión
+      modified.decisions = modified.decisions || [];
+      modified.decisions.push({
+        original: scenario.originalDecision,
+        alternative: scenario.alternativeDecision,
+        appliedAt: new Date().toISOString()
+      });
+    }
+
+    if (scenario.alternativeInputs) {
+      // Merge inputs alternativos
+      modified.variables = {
+        ...modified.variables,
+        ...scenario.alternativeInputs
+      };
+    }
+
+    return modified;
+  }
+
+  /**
+   * Compara dos escenarios
+   */
+  async compareScenarios(scenarioId1, scenarioId2) {
+    const s1 = this.scenarios.get(scenarioId1);
+    const s2 = this.scenarios.get(scenarioId2);
+
+    if (!s1 || !s2) {
+      throw new Error('One or both scenarios not found');
+    }
+
+    if (s1.status !== 'completed' || s2.status !== 'completed') {
+      throw new Error('Both scenarios must be completed');
+    }
+
+    return {
+      scenario1: {
+        id: s1.id,
+        name: s1.name,
+        decision: s1.alternativeDecision || 'original'
+      },
+      scenario2: {
+        id: s2.id,
+        name: s2.name,
+        decision: s2.alternativeDecision || 'original'
+      },
+      comparison: {
+        filesCreated: this.compareLists(
+          s1.results.filesCreated,
+          s2.results.filesCreated
+        ),
+        filesModified: this.compareLists(
+          s1.results.filesModified,
+          s2.results.filesModified
+        ),
+        duration: {
+          scenario1: s1.results.duration,
+          scenario2: s2.results.duration,
+          difference: s2.results.duration - s1.results.duration
+        },
+        success: {
+          scenario1: s1.results.success,
+          scenario2: s2.results.success
+        },
+        errors: {
+          scenario1: s1.results.errors?.length || 0,
+          scenario2: s2.results.errors?.length || 0
+        }
+      }
+    };
+  }
+
+  /**
+   * Compara dos listas
+   */
+  compareLists(list1, list2) {
+    const set1 = new Set(list1?.map(f => f.path || f) || []);
+    const set2 = new Set(list2?.map(f => f.path || f) || []);
+
+    return {
+      onlyIn1: [...set1].filter(x => !set2.has(x)),
+      onlyIn2: [...set2].filter(x => !set1.has(x)),
+      inBoth: [...set1].filter(x => set2.has(x))
+    };
+  }
+
+  /**
+   * Lista todos los escenarios
+   */
+  listScenarios() {
+    return Array.from(this.scenarios.values()).map(s => ({
+      id: s.id,
+      name: s.name,
+      status: s.status,
+      branchPoint: s.branchPoint,
+      createdAt: s.createdAt
+    }));
+  }
+}
+```
+
+---
+
+## Interfaz de Usuario
+
+### Timeline Visualization
+
+```
+╔══════════════════════════════════════════════════════════════════════════╗
+║                      TIME-TRAVEL DEBUGGER                                 ║
+╠══════════════════════════════════════════════════════════════════════════╣
+║                                                                          ║
+║  TIMELINE (Branch: main)                                                 ║
+║  ═══════════════════════════════════════════════════════════════════    ║
+║                                                                          ║
+║  [1]──[2]──[3]──[4]──[5]──[6]──[7]──►[8]                               ║
+║   │    │    │    │    │    │    │     │                                 ║
+║   │    │    │    │    │    │    │     └─ Current: Review complete        ║
+║   │    │    │    │    │    │    └─────── Implementation done             ║
+║   │    │    │    │    │    └──────────── Tests written                   ║
+║   │    │    │    │    └───────────────── Code generated                  ║
+║   │    │    │    └────────────────────── Plan approved                   ║
+║   │    │    └─────────────────────────── Analysis complete               ║
+║   │    └──────────────────────────────── Started analysis                ║
+║   └───────────────────────────────────── Session started                 ║
+║                                                                          ║
+║  Position: 8/8 (latest)                                                  ║
+║                                                                          ║
+╠══════════════════════════════════════════════════════════════════════════╣
+║  CONTROLS                                                                 ║
+║  [◄◄] First  [◄] Back  [▶] Forward  [►►] Last  [▶▶] Play  [⏸] Pause    ║
+║                                                                          ║
+║  BRANCHES                                                                 ║
+║  • main (active) - 8 checkpoints                                         ║
+║  • whatif_different_auth - 5 checkpoints (branched from #4)             ║
+║                                                                          ║
+╠══════════════════════════════════════════════════════════════════════════╣
+║  CHECKPOINT #8 DETAILS                                                   ║
+║  ┌────────────────────────────────────────────────────────────────────┐ ║
+║  │ Event: PHASE_COMPLETE                                               │ ║
+║  │ Phase: review                                                       │ ║
+║  │ Timestamp: 2024-01-20T15:45:32.123Z                                │ ║
+║  │ Duration since start: 2m 34s                                        │ ║
+║  │                                                                     │ ║
+║  │ State:                                                              │ ║
+║  │ • Files created: 3                                                  │ ║
+║  │ • Files modified: 2                                                 │ ║
+║  │ • Tests: 12 passing                                                 │ ║
+║  │ • Review: approved                                                  │ ║
+║  └────────────────────────────────────────────────────────────────────┘ ║
+║                                                                          ║
+╚══════════════════════════════════════════════════════════════════════════╝
+```
+
+### Comparison View
+
+```
+╔══════════════════════════════════════════════════════════════════════════╗
+║                      SCENARIO COMPARISON                                  ║
+╠══════════════════════════════════════════════════════════════════════════╣
+║                                                                          ║
+║  Scenario A: Original (NextAuth)    │  Scenario B: Alternative (Clerk)  ║
+║  ─────────────────────────────────  │  ─────────────────────────────────║
+║                                     │                                    ║
+║  Decision at checkpoint #4:         │  Decision at checkpoint #4:        ║
+║  "Use NextAuth.js for auth"         │  "Use Clerk for auth"              ║
+║                                     │                                    ║
+║  Files Created: 5                   │  Files Created: 3                  ║
+║  • src/auth/[...nextauth].ts       │  • src/middleware.ts               ║
+║  • src/auth/providers.ts           │  • src/lib/clerk.ts                ║
+║  • src/auth/callbacks.ts           │  • src/components/ClerkProvider.tsx║
+║  • src/lib/auth.ts                 │                                    ║
+║  • src/types/next-auth.d.ts        │                                    ║
+║                                     │                                    ║
+║  Duration: 45s                      │  Duration: 28s                     ║
+║  Tests: 8 passing                   │  Tests: 5 passing                  ║
+║  Complexity: Medium                 │  Complexity: Low                   ║
+║                                     │                                    ║
+╠══════════════════════════════════════════════════════════════════════════╣
+║  ANALYSIS                                                                 ║
+║  • Clerk approach is 38% faster to implement                             ║
+║  • NextAuth has more flexibility but more boilerplate                    ║
+║  • Clerk has better DX but vendor lock-in                                ║
+╚══════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:timetravel
+
+```bash
+/elsabro:timetravel show              # Mostrar timeline actual
+/elsabro:timetravel goto <position>   # Saltar a posición
+/elsabro:timetravel back              # Retroceder un paso
+/elsabro:timetravel forward           # Avanzar un paso
+/elsabro:timetravel replay [from] [to]  # Replay de rango
+/elsabro:timetravel branch <name>     # Crear branch alternativo
+/elsabro:timetravel branches          # Listar branches
+/elsabro:timetravel switch <branch>   # Cambiar de branch
+/elsabro:timetravel whatif <name>     # Crear escenario what-if
+/elsabro:timetravel compare <s1> <s2> # Comparar escenarios
+/elsabro:timetravel diff <cp1> <cp2>  # Diff entre checkpoints
+```
+
+---
+
+## Integración con Checkpointing
+
+El sistema de time-travel se construye sobre el sistema de checkpointing existente:
+
+```javascript
+// Inicialización
+const checkpointManager = new CheckpointManager();
+const timelineManager = new TimelineManager(checkpointManager);
+const replayEngine = new ReplayEngine(timelineManager);
+const whatIfAnalyzer = new WhatIfAnalyzer(timelineManager, flowEngine);
+
+// Construir timeline desde sesión
+await timelineManager.buildTimeline(sessionId);
+
+// Navegar
+await timelineManager.jumpTo(5);
+await timelineManager.stepBackward();
+
+// Replay
+await replayEngine.startReplay({ from: 0, to: 10 });
+
+// What-if analysis
+const scenario = await whatIfAnalyzer.createScenario('try_clerk', {
+  fromPosition: 4,
+  alternativeDecision: 'Use Clerk instead of NextAuth'
+});
+await whatIfAnalyzer.runScenario(scenario.id);
+```
+
+---
+
+## Configuración
+
+### .planning/timetravel-config.json
+
+```json
+{
+  "timeTravel": {
+    "enabled": true,
+    "maxTimelineLength": 1000,
+    "maxBranches": 10,
+    "replay": {
+      "defaultSpeed": 1.0,
+      "pauseOnDecision": true,
+      "pauseOnError": true,
+      "autoPlay": false
+    },
+    "whatIf": {
+      "enabled": true,
+      "maxScenarios": 20,
+      "autoCompare": true
+    },
+    "visualization": {
+      "showTimestamps": true,
+      "showDurations": true,
+      "compactMode": false
+    }
+  }
+}
+```