vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/missions/checkpoint.js

@@ -0,0 +1,753 @@
+// bin/runners/lib/missions/checkpoint.js
+// ═══════════════════════════════════════════════════════════════════════════════
+// MISSION CHECKPOINTS - Named checkpoints for instant rollback
+// Each mission gets a checkpoint before execution for safe, reversible operations
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+const {
+  CheckpointError,
+  RollbackError,
+  ValidationError,
+  isValidMissionId,
+  isValidCheckpointId,
+  isValidFilePath,
+  safeReadFile,
+  safeWriteFile,
+  safeReadJson,
+  safeWriteJson,
+  getAuditTrail,
+} = require('./hardening');
+
+/**
+ * Checkpoint directory within .vibecheck
+ */
+const CHECKPOINT_DIR = '.vibecheck/checkpoints/missions';
+
+/**
+ * Mission history file
+ */
+const HISTORY_FILE = '.vibecheck/checkpoints/mission-history.json';
+
+/**
+ * Generate a checkpoint ID for a mission
+ * @param {string} missionId - Mission ID
+ * @returns {string} Checkpoint ID
+ */
+function generateCheckpointId(missionId) {
+  const timestamp = Date.now().toString(36);
+  return `cp_${missionId}_${timestamp}`;
+}
+
+/**
+ * Ensure directory exists
+ * @param {string} dir - Directory path
+ */
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Get git status for checkpoint metadata
+ * @param {string} repoRoot - Repository root
+ * @returns {object} Git status info
+ */
+function getGitStatus(repoRoot) {
+  try {
+    const status = execSync('git status --porcelain', { 
+      cwd: repoRoot, 
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    
+    const commit = execSync('git rev-parse HEAD', {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    
+    return {
+      branch,
+      commit,
+      dirty: status.length > 0,
+      changes: status.split('\n').filter(Boolean).length,
+    };
+  } catch (e) {
+    return { branch: 'unknown', commit: 'unknown', dirty: false, changes: 0 };
+  }
+}
+
+/**
+ * Create a hash of file contents
+ * @param {string} content - File content
+ * @returns {string} SHA256 hash
+ */
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+/**
+ * Create a checkpoint before a mission
+ * @param {string} repoRoot - Repository root
+ * @param {object} mission - Mission object
+ * @param {string[]} files - Files to snapshot
+ * @returns {object} Checkpoint object
+ * @throws {CheckpointError} If checkpoint creation fails
+ */
+function createCheckpoint(repoRoot, mission, files) {
+  const audit = getAuditTrail();
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // INPUT VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    throw new ValidationError('repoRoot is required and must be a string', 'repoRoot', repoRoot);
+  }
+  
+  if (!fs.existsSync(repoRoot)) {
+    throw new ValidationError('repoRoot does not exist', 'repoRoot', repoRoot);
+  }
+  
+  if (!mission || typeof mission !== 'object') {
+    throw new ValidationError('mission is required and must be an object', 'mission', mission);
+  }
+  
+  if (!mission.id) {
+    throw new ValidationError('mission.id is required', 'mission.id', null);
+  }
+  
+  if (!Array.isArray(files)) {
+    throw new ValidationError('files must be an array', 'files', files);
+  }
+  
+  // Validate and sanitize file paths
+  const validFiles = files.filter(f => {
+    if (!isValidFilePath(f)) {
+      audit.warn('checkpoint_invalid_file_skipped', { file: f, missionId: mission.id });
+      return false;
+    }
+    return true;
+  });
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // CHECKPOINT CREATION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  const checkpointId = generateCheckpointId(mission.id);
+  const checkpointDir = path.join(repoRoot, CHECKPOINT_DIR, checkpointId);
+  
+  audit.info('checkpoint_create_start', { checkpointId, missionId: mission.id, fileCount: validFiles.length });
+  
+  try {
+    ensureDir(checkpointDir);
+  } catch (e) {
+    throw new CheckpointError(`Failed to create checkpoint directory: ${e.message}`, 'create', checkpointId, { dir: checkpointDir });
+  }
+  
+  // Snapshot files
+  const snapshots = [];
+  const errors = [];
+  
+  for (const relPath of validFiles) {
+    const absPath = path.join(repoRoot, relPath);
+    
+    try {
+      if (fs.existsSync(absPath)) {
+        const stats = fs.statSync(absPath);
+        
+        // Skip directories
+        if (stats.isDirectory()) {
+          audit.warn('checkpoint_skip_directory', { path: relPath });
+          continue;
+        }
+        
+        // Skip files that are too large (5MB max for checkpoints)
+        const MAX_FILE_SIZE = 5 * 1024 * 1024;
+        if (stats.size > MAX_FILE_SIZE) {
+          audit.warn('checkpoint_skip_large_file', { path: relPath, size: stats.size });
+          snapshots.push({
+            path: relPath,
+            existed: true,
+            hash: null,
+            size: stats.size,
+            skipped: true,
+            reason: 'File too large',
+          });
+          continue;
+        }
+        
+        const content = fs.readFileSync(absPath, 'utf8');
+        const hash = hashContent(content);
+        
+        // Save snapshot
+        const snapshotPath = path.join(checkpointDir, relPath);
+        ensureDir(path.dirname(snapshotPath));
+        fs.writeFileSync(snapshotPath, content, 'utf8');
+        
+        snapshots.push({
+          path: relPath,
+          existed: true,
+          hash,
+          size: content.length,
+        });
+      } else {
+        // File doesn't exist - record this so we can delete it on rollback
+        snapshots.push({
+          path: relPath,
+          existed: false,
+          hash: null,
+          size: 0,
+        });
+      }
+    } catch (e) {
+      errors.push({ path: relPath, error: e.message });
+      audit.error('checkpoint_file_error', { path: relPath, error: e.message });
+    }
+  }
+  
+  // If too many errors, fail the checkpoint
+  if (errors.length > validFiles.length / 2) {
+    // Clean up partial checkpoint
+    try {
+      fs.rmSync(checkpointDir, { recursive: true, force: true });
+    } catch (e) {
+      // Ignore cleanup errors
+    }
+    throw new CheckpointError(`Too many file errors: ${errors.length}/${validFiles.length} failed`, 'create', checkpointId, { errors });
+  }
+  
+  // Create checkpoint metadata
+  const checkpoint = {
+    id: checkpointId,
+    missionId: mission.id,
+    missionType: mission.type,
+    createdAt: new Date().toISOString(),
+    gitStatus: getGitStatus(repoRoot),
+    snapshots,
+    files: validFiles.length,
+    successfulSnapshots: snapshots.filter(s => !s.skipped).length,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+  
+  // Save checkpoint metadata
+  const metadataPath = path.join(checkpointDir, '_checkpoint.json');
+  const writeResult = safeWriteJson(metadataPath, checkpoint);
+  
+  if (!writeResult.ok) {
+    throw new CheckpointError(`Failed to write checkpoint metadata: ${writeResult.error}`, 'create', checkpointId);
+  }
+  
+  // Update mission history
+  addToHistory(repoRoot, {
+    checkpointId,
+    missionId: mission.id,
+    missionType: mission.type,
+    missionTitle: mission.objective?.title || mission.title,
+    createdAt: checkpoint.createdAt,
+    status: 'created',
+  });
+  
+  audit.info('checkpoint_create_success', { 
+    checkpointId, 
+    missionId: mission.id, 
+    snapshotCount: snapshots.length,
+    errorCount: errors.length,
+  });
+  
+  return checkpoint;
+}
+
+/**
+ * Rollback to a checkpoint
+ * @param {string} repoRoot - Repository root
+ * @param {string} checkpointId - Checkpoint ID
+ * @returns {object} Rollback result
+ */
+function rollbackToCheckpoint(repoRoot, checkpointId) {
+  const audit = getAuditTrail();
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // INPUT VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return { 
+      ok: false, 
+      error: 'repoRoot is required',
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  if (!checkpointId || typeof checkpointId !== 'string') {
+    return { 
+      ok: false, 
+      error: 'checkpointId is required',
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // CHECKPOINT VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  const checkpointDir = path.join(repoRoot, CHECKPOINT_DIR, checkpointId);
+  const metadataPath = path.join(checkpointDir, '_checkpoint.json');
+  
+  if (!fs.existsSync(checkpointDir)) {
+    audit.warn('rollback_checkpoint_not_found', { checkpointId });
+    return { 
+      ok: false, 
+      error: `Checkpoint not found: ${checkpointId}`,
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  const metadataResult = safeReadJson(metadataPath);
+  if (!metadataResult.ok) {
+    audit.error('rollback_metadata_read_failed', { checkpointId, error: metadataResult.error });
+    return { 
+      ok: false, 
+      error: `Checkpoint metadata corrupted: ${metadataResult.error}`,
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  const checkpoint = metadataResult.data;
+  
+  // Validate checkpoint structure
+  if (!checkpoint.snapshots || !Array.isArray(checkpoint.snapshots)) {
+    audit.error('rollback_invalid_checkpoint', { checkpointId });
+    return { 
+      ok: false, 
+      error: 'Checkpoint has invalid structure (missing snapshots)',
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  audit.info('rollback_start', { 
+    checkpointId, 
+    missionId: checkpoint.missionId,
+    snapshotCount: checkpoint.snapshots.length,
+  });
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // ROLLBACK EXECUTION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  const restored = [];
+  const deleted = [];
+  const errors = [];
+  const skipped = [];
+  
+  for (const snapshot of checkpoint.snapshots) {
+    // Skip invalid paths
+    if (!snapshot.path || !isValidFilePath(snapshot.path)) {
+      skipped.push({ path: snapshot.path, reason: 'Invalid path' });
+      continue;
+    }
+    
+    // Skip snapshots that were skipped during creation
+    if (snapshot.skipped) {
+      skipped.push({ path: snapshot.path, reason: snapshot.reason || 'Skipped during checkpoint' });
+      continue;
+    }
+    
+    const absPath = path.join(repoRoot, snapshot.path);
+    
+    try {
+      if (snapshot.existed) {
+        // Restore file from snapshot
+        const snapshotPath = path.join(checkpointDir, snapshot.path);
+        if (fs.existsSync(snapshotPath)) {
+          ensureDir(path.dirname(absPath));
+          fs.copyFileSync(snapshotPath, absPath);
+          
+          // Verify restoration
+          const restoredContent = fs.readFileSync(absPath, 'utf8');
+          const restoredHash = hashContent(restoredContent);
+          
+          if (snapshot.hash && restoredHash !== snapshot.hash) {
+            audit.warn('rollback_hash_mismatch', { path: snapshot.path });
+          }
+          
+          restored.push(snapshot.path);
+        } else {
+          errors.push(`Snapshot missing: ${snapshot.path}`);
+          audit.error('rollback_snapshot_missing', { path: snapshot.path, checkpointId });
+        }
+      } else {
+        // File didn't exist before - delete it if it exists now
+        if (fs.existsSync(absPath)) {
+          fs.rmSync(absPath, { force: true });
+          deleted.push(snapshot.path);
+        }
+      }
+    } catch (e) {
+      errors.push(`Failed to restore ${snapshot.path}: ${e.message}`);
+      audit.error('rollback_file_error', { path: snapshot.path, error: e.message });
+    }
+  }
+  
+  // Update history
+  updateHistoryStatus(repoRoot, checkpointId, 'rolled_back');
+  
+  const success = errors.length === 0;
+  
+  audit.info('rollback_complete', { 
+    checkpointId, 
+    success,
+    restored: restored.length,
+    deleted: deleted.length,
+    errors: errors.length,
+    skipped: skipped.length,
+  });
+  
+  return {
+    ok: success,
+    checkpointId,
+    missionId: checkpoint.missionId,
+    restored,
+    deleted,
+    skipped,
+    errors,
+  };
+}
+
+/**
+ * Rollback a mission by its ID
+ * Finds the most recent checkpoint for the mission and rolls back
+ * @param {string} repoRoot - Repository root
+ * @param {string} missionId - Mission ID
+ * @returns {object} Rollback result
+ */
+function rollbackMission(repoRoot, missionId) {
+  const audit = getAuditTrail();
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // INPUT VALIDATION
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return {
+      ok: false,
+      error: 'repoRoot is required',
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  if (!missionId || typeof missionId !== 'string') {
+    return {
+      ok: false,
+      error: 'missionId is required',
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  audit.info('rollback_mission_start', { missionId });
+  
+  // ═══════════════════════════════════════════════════════════════════════════════
+  // FIND CHECKPOINT
+  // ═══════════════════════════════════════════════════════════════════════════════
+  
+  const history = loadHistory(repoRoot);
+  
+  // Find most recent checkpoint for this mission
+  const missionCheckpoints = history
+    .filter(h => h.missionId === missionId && h.status !== 'rolled_back')
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+  
+  if (missionCheckpoints.length === 0) {
+    audit.warn('rollback_mission_no_checkpoint', { missionId });
+    return {
+      ok: false,
+      error: `No checkpoint found for mission: ${missionId}`,
+      restored: [],
+      deleted: [],
+    };
+  }
+  
+  const checkpointId = missionCheckpoints[0].checkpointId;
+  audit.debug('rollback_mission_using_checkpoint', { missionId, checkpointId });
+  
+  return rollbackToCheckpoint(repoRoot, checkpointId);
+}
+
+/**
+ * Delete a checkpoint
+ * @param {string} repoRoot - Repository root
+ * @param {string} checkpointId - Checkpoint ID
+ * @returns {object} Delete result
+ */
+function deleteCheckpoint(repoRoot, checkpointId) {
+  const checkpointDir = path.join(repoRoot, CHECKPOINT_DIR, checkpointId);
+  
+  if (!fs.existsSync(checkpointDir)) {
+    return { ok: false, error: `Checkpoint not found: ${checkpointId}` };
+  }
+  
+  try {
+    fs.rmSync(checkpointDir, { recursive: true, force: true });
+    updateHistoryStatus(repoRoot, checkpointId, 'deleted');
+    return { ok: true, checkpointId };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * List all checkpoints
+ * @param {string} repoRoot - Repository root
+ * @returns {object[]} Array of checkpoint metadata
+ */
+function listCheckpoints(repoRoot) {
+  const baseDir = path.join(repoRoot, CHECKPOINT_DIR);
+  
+  if (!fs.existsSync(baseDir)) {
+    return [];
+  }
+  
+  const checkpoints = [];
+  const dirs = fs.readdirSync(baseDir, { withFileTypes: true });
+  
+  for (const dir of dirs) {
+    if (!dir.isDirectory() || dir.name.startsWith('.')) continue;
+    
+    const metadataPath = path.join(baseDir, dir.name, '_checkpoint.json');
+    if (fs.existsSync(metadataPath)) {
+      try {
+        const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+        checkpoints.push(metadata);
+      } catch (e) {
+        // Skip invalid checkpoints
+      }
+    }
+  }
+  
+  // Sort by creation date, newest first
+  return checkpoints.sort((a, b) => 
+    new Date(b.createdAt) - new Date(a.createdAt)
+  );
+}
+
+/**
+ * Get checkpoint by ID
+ * @param {string} repoRoot - Repository root
+ * @param {string} checkpointId - Checkpoint ID
+ * @returns {object|null} Checkpoint metadata or null
+ */
+function getCheckpoint(repoRoot, checkpointId) {
+  const metadataPath = path.join(repoRoot, CHECKPOINT_DIR, checkpointId, '_checkpoint.json');
+  
+  if (!fs.existsSync(metadataPath)) {
+    return null;
+  }
+  
+  return JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+}
+
+/**
+ * Get checkpoints for a specific mission
+ * @param {string} repoRoot - Repository root
+ * @param {string} missionId - Mission ID
+ * @returns {object[]} Array of checkpoints for the mission
+ */
+function getCheckpointsForMission(repoRoot, missionId) {
+  return listCheckpoints(repoRoot).filter(cp => cp.missionId === missionId);
+}
+
+/**
+ * Load mission history
+ * @param {string} repoRoot - Repository root
+ * @returns {object[]} History entries
+ */
+function loadHistory(repoRoot) {
+  const historyPath = path.join(repoRoot, HISTORY_FILE);
+  
+  if (!fs.existsSync(historyPath)) {
+    return [];
+  }
+  
+  try {
+    return JSON.parse(fs.readFileSync(historyPath, 'utf8'));
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * Add entry to mission history
+ * @param {string} repoRoot - Repository root
+ * @param {object} entry - History entry
+ */
+function addToHistory(repoRoot, entry) {
+  const history = loadHistory(repoRoot);
+  history.push(entry);
+  
+  // Keep only last 100 entries
+  const trimmed = history.slice(-100);
+  
+  const historyPath = path.join(repoRoot, HISTORY_FILE);
+  ensureDir(path.dirname(historyPath));
+  fs.writeFileSync(historyPath, JSON.stringify(trimmed, null, 2), 'utf8');
+}
+
+/**
+ * Update history entry status
+ * @param {string} repoRoot - Repository root
+ * @param {string} checkpointId - Checkpoint ID
+ * @param {string} status - New status
+ */
+function updateHistoryStatus(repoRoot, checkpointId, status) {
+  const history = loadHistory(repoRoot);
+  
+  for (const entry of history) {
+    if (entry.checkpointId === checkpointId) {
+      entry.status = status;
+      entry.updatedAt = new Date().toISOString();
+    }
+  }
+  
+  const historyPath = path.join(repoRoot, HISTORY_FILE);
+  fs.writeFileSync(historyPath, JSON.stringify(history, null, 2), 'utf8');
+}
+
+/**
+ * Get mission history
+ * @param {string} repoRoot - Repository root
+ * @param {object} options - Filter options
+ * @returns {object[]} Filtered history entries
+ */
+function getMissionHistory(repoRoot, options = {}) {
+  const { missionId, missionType, status, limit = 50 } = options;
+  let history = loadHistory(repoRoot);
+  
+  if (missionId) {
+    history = history.filter(h => h.missionId === missionId);
+  }
+  
+  if (missionType) {
+    history = history.filter(h => h.missionType === missionType);
+  }
+  
+  if (status) {
+    history = history.filter(h => h.status === status);
+  }
+  
+  // Sort by creation date, newest first
+  history.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+  
+  return history.slice(0, limit);
+}
+
+/**
+ * Clean up old checkpoints
+ * @param {string} repoRoot - Repository root
+ * @param {object} options - Cleanup options
+ * @returns {object} Cleanup result
+ */
+function cleanupOldCheckpoints(repoRoot, options = {}) {
+  const { maxAge = 7 * 24 * 60 * 60 * 1000, maxCount = 50 } = options; // 7 days default
+  const checkpoints = listCheckpoints(repoRoot);
+  const now = Date.now();
+  const deleted = [];
+  
+  // Delete checkpoints older than maxAge
+  for (const cp of checkpoints) {
+    const age = now - new Date(cp.createdAt).getTime();
+    if (age > maxAge) {
+      const result = deleteCheckpoint(repoRoot, cp.id);
+      if (result.ok) deleted.push(cp.id);
+    }
+  }
+  
+  // If still over maxCount, delete oldest
+  const remaining = listCheckpoints(repoRoot);
+  if (remaining.length > maxCount) {
+    const toDelete = remaining.slice(maxCount);
+    for (const cp of toDelete) {
+      const result = deleteCheckpoint(repoRoot, cp.id);
+      if (result.ok) deleted.push(cp.id);
+    }
+  }
+  
+  return { deleted, count: deleted.length };
+}
+
+/**
+ * Mark checkpoint as applied (mission completed successfully)
+ * @param {string} repoRoot - Repository root
+ * @param {string} checkpointId - Checkpoint ID
+ */
+function markCheckpointApplied(repoRoot, checkpointId) {
+  updateHistoryStatus(repoRoot, checkpointId, 'applied');
+}
+
+/**
+ * Mark checkpoint as failed
+ * @param {string} repoRoot - Repository root
+ * @param {string} checkpointId - Checkpoint ID
+ * @param {string} reason - Failure reason
+ */
+function markCheckpointFailed(repoRoot, checkpointId, reason) {
+  const history = loadHistory(repoRoot);
+  
+  for (const entry of history) {
+    if (entry.checkpointId === checkpointId) {
+      entry.status = 'failed';
+      entry.failureReason = reason;
+      entry.updatedAt = new Date().toISOString();
+    }
+  }
+  
+  const historyPath = path.join(repoRoot, HISTORY_FILE);
+  fs.writeFileSync(historyPath, JSON.stringify(history, null, 2), 'utf8');
+}
+
+module.exports = {
+  // Core functions
+  createCheckpoint,
+  rollbackToCheckpoint,
+  rollbackMission,
+  deleteCheckpoint,
+  
+  // Query functions
+  listCheckpoints,
+  getCheckpoint,
+  getCheckpointsForMission,
+  
+  // History functions
+  getMissionHistory,
+  loadHistory,
+  
+  // Status updates
+  markCheckpointApplied,
+  markCheckpointFailed,
+  
+  // Maintenance
+  cleanupOldCheckpoints,
+  
+  // Utilities
+  generateCheckpointId,
+  getGitStatus,
+  
+  // Constants
+  CHECKPOINT_DIR,
+  HISTORY_FILE,
+};