vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/checkpoint.js

@@ -0,0 +1,941 @@
+/**
+ * Checkpoint System - Time Machine for Fearless Experimentation
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * "Checkpoint is the time machine. Let users experiment fearlessly."
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Features:
+ * - Delta storage (only modified files, not full repo)
+ * - Git-aware (captures branch, commit, dirty state)
+ * - Manifest with "why" (auto vs manual, command context)
+ * - Storage-aware with auto-cleanup
+ * - Fast create/restore operations
+ * 
+ * Storage Model:
+ * ~/.vibecheck/checkpoints/
+ * ├── index.json                    # Checkpoint registry
+ * └── CP_<timestamp>_<hash>/
+ *     ├── manifest.json             # What, why, when
+ *     ├── files/                    # Changed files (delta storage)
+ *     │   └── <relative-path>.bak
+ *     └── metadata.json             # Git state, env info
+ * 
+ * @module lib/checkpoint
+ */
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const { execSync } = require("child_process");
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const CHECKPOINT_DIR = path.join(os.homedir(), ".vibecheck", "checkpoints");
+const INDEX_FILE = "index.json";
+const MANIFEST_FILE = "manifest.json";
+const METADATA_FILE = "metadata.json";
+const FILES_DIR = "files";
+
+/** Max checkpoints to keep (default) */
+const DEFAULT_MAX_CHECKPOINTS = 20;
+
+/** Max total storage size in bytes (100MB default) */
+const DEFAULT_MAX_STORAGE_BYTES = 100 * 1024 * 1024;
+
+/** Checkpoint ID prefix */
+const CHECKPOINT_PREFIX = "CP";
+
+/** Auto-checkpoint reasons */
+const AUTO_REASONS = {
+  FIX_APPLY: "fix --apply",
+  FIX_MISSION: "fix mission",
+  POLISH_APPLY: "polish --apply",
+  SHIELD_ENFORCE: "shield enforce",
+  FORGE_OVERWRITE: "forge overwrite",
+  MANUAL: "manual",
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// STORAGE MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Ensure checkpoint directory exists.
+ */
+function ensureCheckpointDir() {
+  if (!fs.existsSync(CHECKPOINT_DIR)) {
+    fs.mkdirSync(CHECKPOINT_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+/**
+ * Get checkpoint index path.
+ */
+function getIndexPath() {
+  return path.join(CHECKPOINT_DIR, INDEX_FILE);
+}
+
+/**
+ * Read checkpoint index.
+ * @returns {object}
+ */
+function readIndex() {
+  ensureCheckpointDir();
+  const indexPath = getIndexPath();
+  
+  if (!fs.existsSync(indexPath)) {
+    return {
+      version: 1,
+      checkpoints: [],
+      settings: {
+        maxCheckpoints: DEFAULT_MAX_CHECKPOINTS,
+        maxStorageBytes: DEFAULT_MAX_STORAGE_BYTES,
+      },
+    };
+  }
+  
+  try {
+    return JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  } catch {
+    return {
+      version: 1,
+      checkpoints: [],
+      settings: {
+        maxCheckpoints: DEFAULT_MAX_CHECKPOINTS,
+        maxStorageBytes: DEFAULT_MAX_STORAGE_BYTES,
+      },
+    };
+  }
+}
+
+/**
+ * Write checkpoint index.
+ * @param {object} index
+ */
+function writeIndex(index) {
+  ensureCheckpointDir();
+  fs.writeFileSync(getIndexPath(), JSON.stringify(index, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Generate checkpoint ID.
+ * @param {string} [tag]
+ * @returns {string}
+ */
+function generateCheckpointId(tag) {
+  const timestamp = Date.now();
+  const hash = crypto.randomBytes(4).toString("hex");
+  const base = `${CHECKPOINT_PREFIX}_${timestamp}_${hash}`;
+  return tag ? `${base}_${sanitizeTag(tag)}` : base;
+}
+
+/**
+ * Sanitize tag for filesystem.
+ * @param {string} tag
+ * @returns {string}
+ */
+function sanitizeTag(tag) {
+  return tag
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]/g, "-")
+    .replace(/-+/g, "-")
+    .slice(0, 32);
+}
+
+/**
+ * Get checkpoint directory path.
+ * @param {string} checkpointId
+ * @returns {string}
+ */
+function getCheckpointPath(checkpointId) {
+  return path.join(CHECKPOINT_DIR, checkpointId);
+}
+
+/**
+ * Calculate directory size recursively.
+ * @param {string} dir
+ * @returns {number}
+ */
+function getDirectorySize(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  
+  let size = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      size += getDirectorySize(fullPath);
+    } else {
+      try {
+        size += fs.statSync(fullPath).size;
+      } catch {
+        // Skip inaccessible files
+      }
+    }
+  }
+  
+  return size;
+}
+
+/**
+ * Get total checkpoint storage size.
+ * @returns {number}
+ */
+function getTotalStorageSize() {
+  return getDirectorySize(CHECKPOINT_DIR);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// GIT INTEGRATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get current git state.
+ * @param {string} cwd
+ * @returns {object|null}
+ */
+function getGitState(cwd) {
+  try {
+    // Check if in git repo
+    execSync("git rev-parse --git-dir", { cwd, stdio: "pipe" });
+    
+    const branch = execSync("git branch --show-current", { cwd, encoding: "utf8" }).trim();
+    const commit = execSync("git rev-parse HEAD", { cwd, encoding: "utf8" }).trim().slice(0, 8);
+    const dirty = execSync("git status --porcelain", { cwd, encoding: "utf8" }).trim().length > 0;
+    
+    let stashCount = 0;
+    try {
+      const stashList = execSync("git stash list", { cwd, encoding: "utf8" });
+      stashCount = stashList.split("\n").filter(Boolean).length;
+    } catch {
+      // No stash
+    }
+    
+    return {
+      branch,
+      commit,
+      dirty,
+      stashCount,
+      timestamp: new Date().toISOString(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get list of modified files from git.
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function getGitModifiedFiles(cwd) {
+  try {
+    const output = execSync("git status --porcelain", { cwd, encoding: "utf8" });
+    return output
+      .split("\n")
+      .filter(Boolean)
+      .map(line => line.slice(3).trim())
+      .filter(f => !f.includes(" -> ")); // Exclude renames for now
+  } catch {
+    return [];
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CHECKPOINT CREATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a checkpoint.
+ * 
+ * @param {object} options
+ * @param {string} options.cwd - Working directory
+ * @param {string[]} options.files - Files to checkpoint (relative paths)
+ * @param {string} options.reason - Why checkpoint was created
+ * @param {string} [options.tag] - Optional tag
+ * @param {string} [options.command] - Command that triggered checkpoint
+ * @param {object} [options.context] - Additional context
+ * @returns {object} - Checkpoint info
+ */
+function createCheckpoint({
+  cwd = process.cwd(),
+  files = [],
+  reason = AUTO_REASONS.MANUAL,
+  tag,
+  command,
+  context = {},
+}) {
+  ensureCheckpointDir();
+  
+  const checkpointId = generateCheckpointId(tag);
+  const checkpointPath = getCheckpointPath(checkpointId);
+  const filesPath = path.join(checkpointPath, FILES_DIR);
+  
+  // Create checkpoint directory
+  fs.mkdirSync(filesPath, { recursive: true, mode: 0o700 });
+  
+  // Get git state
+  const gitState = getGitState(cwd);
+  
+  // If no files specified, get modified files from git
+  let filesToBackup = files.length > 0 ? files : getGitModifiedFiles(cwd);
+  
+  // Filter to only existing files
+  filesToBackup = filesToBackup.filter(f => {
+    const fullPath = path.isAbsolute(f) ? f : path.join(cwd, f);
+    return fs.existsSync(fullPath) && fs.statSync(fullPath).isFile();
+  });
+  
+  // Backup files
+  const backedUpFiles = [];
+  let totalSize = 0;
+  
+  for (const file of filesToBackup) {
+    try {
+      const fullPath = path.isAbsolute(file) ? file : path.join(cwd, file);
+      const relativePath = path.isAbsolute(file) ? path.relative(cwd, file) : file;
+      const backupPath = path.join(filesPath, relativePath.replace(/[/\\]/g, "__"));
+      
+      // Copy file
+      fs.copyFileSync(fullPath, backupPath);
+      
+      const stats = fs.statSync(backupPath);
+      totalSize += stats.size;
+      
+      backedUpFiles.push({
+        original: relativePath,
+        backup: path.basename(backupPath),
+        size: stats.size,
+        hash: hashFile(fullPath),
+      });
+    } catch (err) {
+      // Skip files that can't be backed up
+      console.warn(`Warning: Could not backup ${file}: ${err.message}`);
+    }
+  }
+  
+  // Create manifest
+  const manifest = {
+    id: checkpointId,
+    version: 1,
+    created: new Date().toISOString(),
+    reason,
+    tag: tag || null,
+    command: command || null,
+    context,
+    files: backedUpFiles,
+    totalSize,
+    cwd,
+  };
+  
+  fs.writeFileSync(
+    path.join(checkpointPath, MANIFEST_FILE),
+    JSON.stringify(manifest, null, 2),
+    { mode: 0o600 }
+  );
+  
+  // Create metadata
+  const metadata = {
+    git: gitState,
+    env: {
+      platform: process.platform,
+      nodeVersion: process.version,
+      user: os.userInfo().username,
+      hostname: os.hostname(),
+    },
+    created: new Date().toISOString(),
+  };
+  
+  fs.writeFileSync(
+    path.join(checkpointPath, METADATA_FILE),
+    JSON.stringify(metadata, null, 2),
+    { mode: 0o600 }
+  );
+  
+  // Update index
+  const index = readIndex();
+  index.checkpoints.unshift({
+    id: checkpointId,
+    created: manifest.created,
+    reason,
+    tag: tag || null,
+    fileCount: backedUpFiles.length,
+    totalSize,
+    command: command || null,
+  });
+  writeIndex(index);
+  
+  // Auto-cleanup if needed
+  autoCleanup();
+  
+  return {
+    id: checkpointId,
+    path: checkpointPath,
+    files: backedUpFiles.length,
+    size: totalSize,
+    tag,
+    reason,
+  };
+}
+
+/**
+ * Hash file contents.
+ * @param {string} filePath
+ * @returns {string}
+ */
+function hashFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+  } catch {
+    return "unknown";
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CHECKPOINT RESTORATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Restore a checkpoint.
+ * 
+ * @param {string} checkpointId - Checkpoint ID or "latest"
+ * @param {object} options
+ * @param {boolean} [options.dryRun] - Preview without restoring
+ * @param {string[]} [options.onlyFiles] - Only restore specific files
+ * @returns {object} - Restore result
+ */
+function restoreCheckpoint(checkpointId, { dryRun = false, onlyFiles = [] } = {}) {
+  const index = readIndex();
+  
+  // Handle "latest"
+  if (checkpointId === "latest") {
+    if (index.checkpoints.length === 0) {
+      throw new Error("No checkpoints available");
+    }
+    checkpointId = index.checkpoints[0].id;
+  }
+  
+  // Handle tag lookup
+  if (!checkpointId.startsWith(CHECKPOINT_PREFIX)) {
+    const found = index.checkpoints.find(c => c.tag === checkpointId);
+    if (found) {
+      checkpointId = found.id;
+    } else {
+      throw new Error(`Checkpoint not found: ${checkpointId}`);
+    }
+  }
+  
+  const checkpointPath = getCheckpointPath(checkpointId);
+  
+  if (!fs.existsSync(checkpointPath)) {
+    throw new Error(`Checkpoint not found: ${checkpointId}`);
+  }
+  
+  // Read manifest
+  const manifestPath = path.join(checkpointPath, MANIFEST_FILE);
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const filesPath = path.join(checkpointPath, FILES_DIR);
+  
+  const results = {
+    id: checkpointId,
+    restored: [],
+    skipped: [],
+    errors: [],
+    dryRun,
+  };
+  
+  for (const file of manifest.files) {
+    // Filter by onlyFiles if specified
+    if (onlyFiles.length > 0 && !onlyFiles.includes(file.original)) {
+      results.skipped.push({ file: file.original, reason: "not in filter" });
+      continue;
+    }
+    
+    const backupPath = path.join(filesPath, file.backup);
+    const targetPath = path.join(manifest.cwd, file.original);
+    
+    if (!fs.existsSync(backupPath)) {
+      results.errors.push({ file: file.original, reason: "backup file missing" });
+      continue;
+    }
+    
+    if (dryRun) {
+      results.restored.push({
+        file: file.original,
+        action: fs.existsSync(targetPath) ? "overwrite" : "create",
+      });
+    } else {
+      try {
+        // Ensure directory exists
+        const targetDir = path.dirname(targetPath);
+        if (!fs.existsSync(targetDir)) {
+          fs.mkdirSync(targetDir, { recursive: true });
+        }
+        
+        // Copy file back
+        fs.copyFileSync(backupPath, targetPath);
+        
+        results.restored.push({
+          file: file.original,
+          action: "restored",
+        });
+      } catch (err) {
+        results.errors.push({ file: file.original, reason: err.message });
+      }
+    }
+  }
+  
+  return results;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CHECKPOINT LISTING & INFO
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * List all checkpoints.
+ * @param {object} [options]
+ * @param {number} [options.limit]
+ * @returns {object[]}
+ */
+function listCheckpoints({ limit } = {}) {
+  const index = readIndex();
+  let checkpoints = index.checkpoints;
+  
+  if (limit && limit > 0) {
+    checkpoints = checkpoints.slice(0, limit);
+  }
+  
+  return checkpoints.map(cp => ({
+    ...cp,
+    age: getAge(cp.created),
+    sizeFormatted: formatBytes(cp.totalSize),
+  }));
+}
+
+/**
+ * Get checkpoint details.
+ * @param {string} checkpointId
+ * @returns {object|null}
+ */
+function getCheckpoint(checkpointId) {
+  const index = readIndex();
+  
+  // Handle tag lookup
+  if (!checkpointId.startsWith(CHECKPOINT_PREFIX)) {
+    const found = index.checkpoints.find(c => c.tag === checkpointId);
+    if (found) {
+      checkpointId = found.id;
+    }
+  }
+  
+  const checkpointPath = getCheckpointPath(checkpointId);
+  
+  if (!fs.existsSync(checkpointPath)) {
+    return null;
+  }
+  
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(checkpointPath, MANIFEST_FILE), "utf8")
+    );
+    const metadata = JSON.parse(
+      fs.readFileSync(path.join(checkpointPath, METADATA_FILE), "utf8")
+    );
+    
+    return {
+      ...manifest,
+      metadata,
+      age: getAge(manifest.created),
+      sizeFormatted: formatBytes(manifest.totalSize),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get latest checkpoint.
+ * @returns {object|null}
+ */
+function getLatestCheckpoint() {
+  const index = readIndex();
+  if (index.checkpoints.length === 0) return null;
+  return getCheckpoint(index.checkpoints[0].id);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CHECKPOINT DIFF
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compare checkpoint with current state.
+ * @param {string} checkpointId
+ * @returns {object}
+ */
+function diffCheckpoint(checkpointId) {
+  const checkpoint = getCheckpoint(checkpointId);
+  
+  if (!checkpoint) {
+    throw new Error(`Checkpoint not found: ${checkpointId}`);
+  }
+  
+  const filesPath = path.join(getCheckpointPath(checkpoint.id), FILES_DIR);
+  const results = {
+    id: checkpoint.id,
+    created: checkpoint.created,
+    changes: [],
+    summary: { modified: 0, deleted: 0, unchanged: 0 },
+  };
+  
+  for (const file of checkpoint.files) {
+    const backupPath = path.join(filesPath, file.backup);
+    const currentPath = path.join(checkpoint.cwd, file.original);
+    
+    if (!fs.existsSync(currentPath)) {
+      results.changes.push({
+        file: file.original,
+        status: "deleted",
+        checkpointHash: file.hash,
+        currentHash: null,
+      });
+      results.summary.deleted++;
+    } else {
+      const currentHash = hashFile(currentPath);
+      if (currentHash === file.hash) {
+        results.changes.push({
+          file: file.original,
+          status: "unchanged",
+          hash: file.hash,
+        });
+        results.summary.unchanged++;
+      } else {
+        results.changes.push({
+          file: file.original,
+          status: "modified",
+          checkpointHash: file.hash,
+          currentHash,
+        });
+        results.summary.modified++;
+      }
+    }
+  }
+  
+  return results;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CHECKPOINT DELETION & CLEANUP
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Delete a checkpoint.
+ * @param {string} checkpointId
+ * @returns {boolean}
+ */
+function deleteCheckpoint(checkpointId) {
+  const index = readIndex();
+  
+  // Handle tag lookup
+  if (!checkpointId.startsWith(CHECKPOINT_PREFIX)) {
+    const found = index.checkpoints.find(c => c.tag === checkpointId);
+    if (found) {
+      checkpointId = found.id;
+    }
+  }
+  
+  const checkpointPath = getCheckpointPath(checkpointId);
+  
+  if (!fs.existsSync(checkpointPath)) {
+    return false;
+  }
+  
+  // Remove directory recursively
+  fs.rmSync(checkpointPath, { recursive: true, force: true });
+  
+  // Update index
+  index.checkpoints = index.checkpoints.filter(c => c.id !== checkpointId);
+  writeIndex(index);
+  
+  return true;
+}
+
+/**
+ * Prune old checkpoints.
+ * @param {object} options
+ * @param {number} [options.keep] - Number to keep
+ * @param {number} [options.olderThanDays] - Delete older than N days
+ * @returns {object}
+ */
+function pruneCheckpoints({ keep, olderThanDays } = {}) {
+  const index = readIndex();
+  const results = { deleted: [], kept: [] };
+  
+  let toDelete = [];
+  
+  if (keep !== undefined && keep >= 0) {
+    // Keep N most recent
+    toDelete = index.checkpoints.slice(keep);
+  } else if (olderThanDays !== undefined && olderThanDays > 0) {
+    // Delete older than N days
+    const cutoff = Date.now() - (olderThanDays * 24 * 60 * 60 * 1000);
+    toDelete = index.checkpoints.filter(c => new Date(c.created).getTime() < cutoff);
+  }
+  
+  for (const cp of toDelete) {
+    if (deleteCheckpoint(cp.id)) {
+      results.deleted.push(cp.id);
+    }
+  }
+  
+  // Re-read index after deletions
+  const newIndex = readIndex();
+  results.kept = newIndex.checkpoints.map(c => c.id);
+  
+  return results;
+}
+
+/**
+ * Auto-cleanup based on settings.
+ */
+function autoCleanup() {
+  const index = readIndex();
+  const settings = index.settings || {
+    maxCheckpoints: DEFAULT_MAX_CHECKPOINTS,
+    maxStorageBytes: DEFAULT_MAX_STORAGE_BYTES,
+  };
+  
+  // Check count limit
+  if (index.checkpoints.length > settings.maxCheckpoints) {
+    pruneCheckpoints({ keep: settings.maxCheckpoints });
+  }
+  
+  // Check storage limit
+  const totalSize = getTotalStorageSize();
+  if (totalSize > settings.maxStorageBytes) {
+    // Delete oldest checkpoints until under limit
+    const newIndex = readIndex();
+    while (newIndex.checkpoints.length > 1 && getTotalStorageSize() > settings.maxStorageBytes) {
+      const oldest = newIndex.checkpoints[newIndex.checkpoints.length - 1];
+      deleteCheckpoint(oldest.id);
+      newIndex.checkpoints = newIndex.checkpoints.slice(0, -1);
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// AUTO-CHECKPOINT INTEGRATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create auto-checkpoint before risky operation.
+ * Returns checkpoint ID for rollback reference.
+ * 
+ * @param {object} options
+ * @param {string} options.command - Command name (fix, polish, shield, forge)
+ * @param {string} options.reason - Specific reason
+ * @param {string[]} options.files - Files to be modified
+ * @param {object} [options.context] - Additional context
+ * @returns {object}
+ */
+function autoCheckpoint({ command, reason, files, context = {} }) {
+  return createCheckpoint({
+    cwd: process.cwd(),
+    files,
+    reason: `auto:${command}`,
+    command,
+    context: {
+      ...context,
+      auto: true,
+      timestamp: new Date().toISOString(),
+    },
+  });
+}
+
+/**
+ * Rollback to checkpoint (alias for restore).
+ * @param {string} checkpointId
+ * @returns {object}
+ */
+function rollback(checkpointId) {
+  return restoreCheckpoint(checkpointId, { dryRun: false });
+}
+
+/**
+ * Register a mission checkpoint in the global checkpoint index.
+ * This bridges the mission checkpoint system with the CLI checkpoint system.
+ * 
+ * @param {object} missionCheckpoint - Checkpoint from mission system
+ * @param {string} repoRoot - Repository root
+ */
+function registerMissionCheckpoint(missionCheckpoint, repoRoot) {
+  try {
+    const index = readIndex();
+    
+    // Check if already registered
+    const exists = index.checkpoints.some(c => c.id === missionCheckpoint.id);
+    if (exists) return;
+    
+    index.checkpoints.unshift({
+      id: missionCheckpoint.id,
+      created: missionCheckpoint.createdAt || new Date().toISOString(),
+      reason: `auto:fix mission ${missionCheckpoint.missionId || ""}`,
+      tag: null,
+      fileCount: missionCheckpoint.snapshots?.length || 0,
+      totalSize: missionCheckpoint.snapshots?.reduce((sum, s) => sum + (s.size || 0), 0) || 0,
+      command: "fix --apply",
+      missionId: missionCheckpoint.missionId,
+      repoRoot,
+    });
+    
+    writeIndex(index);
+  } catch {
+    // Non-critical - mission checkpoint still works
+  }
+}
+
+/**
+ * Bulk restore from mission checkpoint.
+ * Used when user wants to restore from a fix mission checkpoint via CLI.
+ * 
+ * @param {string} checkpointId - Mission checkpoint ID
+ * @param {string} repoRoot - Repository root
+ * @returns {object}
+ */
+function restoreMissionCheckpoint(checkpointId, repoRoot) {
+  try {
+    // Try mission checkpoint system first
+    const missionCheckpointModule = require("./missions/checkpoint");
+    const result = missionCheckpointModule.rollbackToCheckpoint(repoRoot, checkpointId);
+    return {
+      id: checkpointId,
+      restored: result.restored || [],
+      errors: result.errors || [],
+      dryRun: false,
+      source: "mission",
+    };
+  } catch {
+    // Fall back to standard checkpoint
+    return restoreCheckpoint(checkpointId);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Format bytes to human readable.
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+
+/**
+ * Get age string from ISO date.
+ * @param {string} isoDate
+ * @returns {string}
+ */
+function getAge(isoDate) {
+  const ms = Date.now() - new Date(isoDate).getTime();
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  
+  if (days > 0) return `${days}d ago`;
+  if (hours > 0) return `${hours}h ago`;
+  if (minutes > 0) return `${minutes}m ago`;
+  return "just now";
+}
+
+/**
+ * Get storage status.
+ * @returns {object}
+ */
+function getStorageStatus() {
+  const index = readIndex();
+  const totalSize = getTotalStorageSize();
+  const settings = index.settings || {
+    maxCheckpoints: DEFAULT_MAX_CHECKPOINTS,
+    maxStorageBytes: DEFAULT_MAX_STORAGE_BYTES,
+  };
+  
+  return {
+    checkpointCount: index.checkpoints.length,
+    maxCheckpoints: settings.maxCheckpoints,
+    totalSize,
+    totalSizeFormatted: formatBytes(totalSize),
+    maxSize: settings.maxStorageBytes,
+    maxSizeFormatted: formatBytes(settings.maxStorageBytes),
+    usagePercent: Math.round((totalSize / settings.maxStorageBytes) * 100),
+  };
+}
+
+/**
+ * Update settings.
+ * @param {object} newSettings
+ */
+function updateSettings(newSettings) {
+  const index = readIndex();
+  index.settings = { ...index.settings, ...newSettings };
+  writeIndex(index);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  // Constants
+  AUTO_REASONS,
+  CHECKPOINT_PREFIX,
+  CHECKPOINT_DIR,
+  
+  // Core operations
+  createCheckpoint,
+  restoreCheckpoint,
+  deleteCheckpoint,
+  
+  // Listing & info
+  listCheckpoints,
+  getCheckpoint,
+  getLatestCheckpoint,
+  diffCheckpoint,
+  
+  // Cleanup
+  pruneCheckpoints,
+  autoCleanup,
+  
+  // Auto-integration
+  autoCheckpoint,
+  rollback,
+  
+  // Mission integration
+  registerMissionCheckpoint,
+  restoreMissionCheckpoint,
+  
+  // Status & settings
+  getStorageStatus,
+  updateSettings,
+  
+  // Helpers
+  formatBytes,
+  getAge,
+  getCheckpointPath,
+  ensureCheckpointDir,
+  readIndex,
+  writeIndex,
+};