@girardmedia/bootspring 1.2.0 → 2.0.3

package/cli/checkpoint.js

@@ -0,0 +1,639 @@
+/**
+ * Bootspring Checkpoint Command
+ * Manage project checkpoints and milestones
+ *
+ * Commands:
+ *   status              Show all checkpoints with status
+ *   complete <name>     Mark a checkpoint as complete manually
+ *   history             View checkpoint completion timeline
+ *   sync                Re-scan files to detect completed items
+ *   init                Initialize checkpoint tracking
+ *
+ * @package bootspring
+ * @command checkpoint
+ */
+
+const fs = require('fs');
+const path = require('path');
+const config = require('../core/config');
+const utils = require('../core/utils');
+const projectState = require('../core/project-state');
+const checkpointEngine = require('../core/checkpoint-engine');
+const telemetry = require('../core/telemetry');
+const { scanFilesForCheckpoints, pushCheckpointsToServer } = require('./checkpoint-utils');
+
+// ============================================================================
+// Command Handlers
+// ============================================================================
+
+/**
+ * Show checkpoint status
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options
+ */
+async function handleStatus(projectRoot, options = {}) {
+  // Auto-sync checkpoints before showing status
+  checkpointEngine.syncCheckpoints(projectRoot);
+
+  // Auto-push to server if authenticated (non-blocking)
+  pushCheckpointsToServer(projectRoot, { quiet: true, autoSync: true, skipMetrics: true }).catch(() => {});
+
+  const status = checkpointEngine.getCheckpointStatus(projectRoot);
+
+  if (!status.exists) {
+    console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Project Checkpoints${utils.COLORS.reset}
+
+${utils.COLORS.yellow}No checkpoint tracking found.${utils.COLORS.reset}
+
+${utils.COLORS.bold}Get started:${utils.COLORS.reset}
+  bootspring checkpoint init     Initialize checkpoint tracking
+  bootspring preseed init        Start with document generation
+`);
+    return;
+  }
+
+  // Output as JSON if requested
+  if (options.json) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+
+  // Type badge
+  const typeBadge = getTypeBadge(status.projectType);
+  const autoTagNote = status.autoTagged ? ` ${utils.COLORS.dim}(auto-tagged by ${status.taggedBy})${utils.COLORS.reset}` : '';
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Project Checkpoints${utils.COLORS.reset}
+
+${utils.COLORS.bold}Project Type:${utils.COLORS.reset} ${typeBadge}${autoTagNote}
+
+${utils.COLORS.bold}Progress:${utils.COLORS.reset} ${status.completed}/${status.total} (${status.percentage}%)
+${checkpointEngine.getColoredProgressBar(status.percentage, 30)}
+`);
+
+  // Show all checkpoints
+  console.log(`${utils.COLORS.bold}Checkpoints:${utils.COLORS.reset}`);
+
+  for (const checkpoint of status.checkpoints) {
+    const icon = checkpoint.completed
+      ? `${utils.COLORS.green}✓${utils.COLORS.reset}`
+      : `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+
+    const label = checkpoint.completed
+      ? checkpoint.label
+      : `${utils.COLORS.dim}${checkpoint.label}${utils.COLORS.reset}`;
+
+    const completedInfo = checkpoint.completed && status.checkpoints.find(c => c.id === checkpoint.id)
+      ? ` ${utils.COLORS.dim}(${checkpoint.reason})${utils.COLORS.reset}`
+      : '';
+
+    console.log(`  ${icon} ${label}${completedInfo}`);
+  }
+
+  // Show next steps
+  const nextSteps = checkpointEngine.getNextSteps(projectRoot);
+  if (nextSteps.length > 0) {
+    console.log(`\n${utils.COLORS.bold}Next Steps:${utils.COLORS.reset}`);
+    for (const step of nextSteps) {
+      console.log(`  ${utils.COLORS.cyan}→${utils.COLORS.reset} ${step.action}`);
+    }
+  }
+
+  console.log();
+
+  // Emit telemetry
+  telemetry.emitEvent('checkpoint:status', {
+    projectType: status.projectType,
+    completed: status.completed,
+    total: status.total,
+    percentage: status.percentage
+  }, { projectRoot });
+}
+
+/**
+ * Get type badge
+ * @param {string} projectType - Project type
+ * @returns {string} Formatted badge
+ */
+function getTypeBadge(projectType) {
+  const badges = {
+    development: `${utils.COLORS.cyan}[DEV]${utils.COLORS.reset}`,
+    content: `${utils.COLORS.magenta}[CONTENT]${utils.COLORS.reset}`,
+    business: `${utils.COLORS.yellow}[BUSINESS]${utils.COLORS.reset}`
+  };
+  return badges[projectType] || badges.development;
+}
+
+/**
+ * Initialize checkpoint tracking
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options
+ */
+function handleInit(projectRoot, options = {}) {
+  const existingState = projectState.loadState(projectRoot);
+
+  if (existingState && !options.force) {
+    utils.print.warning('Checkpoint tracking already initialized.');
+    utils.print.dim('Use --force to reinitialize.');
+    console.log();
+    handleStatus(projectRoot);
+    return;
+  }
+
+  // Determine project type
+  let projectType = options.type;
+  if (!projectType) {
+    projectType = projectState.detectProjectType(projectRoot);
+    utils.print.info(`Auto-detected project type: ${projectType}`);
+  }
+
+  // Initialize state
+  const state = projectState.initState(projectRoot, {
+    projectType,
+    autoTagged: false
+  });
+
+  // Run initial sync
+  const syncResult = checkpointEngine.syncCheckpoints(projectRoot, { verbose: true });
+
+  utils.print.success('Checkpoint tracking initialized!');
+  console.log();
+
+  // Show status
+  handleStatus(projectRoot);
+
+  // Emit telemetry
+  telemetry.emitEvent('checkpoint:init', {
+    projectType,
+    initialCompleted: syncResult.completed
+  }, { projectRoot });
+}
+
+/**
+ * Complete a checkpoint manually
+ * @param {string} projectRoot - Project root directory
+ * @param {string} checkpointId - Checkpoint ID
+ * @param {object} options - Options
+ */
+function handleComplete(projectRoot, checkpointId, options = {}) {
+  if (!checkpointId) {
+    utils.print.error('Please specify a checkpoint to complete.');
+    console.log(`\n${utils.COLORS.bold}Usage:${utils.COLORS.reset} bootspring checkpoint complete <checkpoint-id>`);
+    console.log(`\n${utils.COLORS.bold}Available checkpoints:${utils.COLORS.reset}`);
+
+    const state = projectState.loadState(projectRoot);
+    if (state) {
+      const defs = projectState.getCheckpointDefinitions(state.projectType);
+      for (const def of defs) {
+        const completed = state.checkpoints[def.id]?.completed;
+        const icon = completed ? `${utils.COLORS.green}✓${utils.COLORS.reset}` : `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+        console.log(`  ${icon} ${def.id} - ${def.label}`);
+      }
+    }
+    console.log();
+    return;
+  }
+
+  const state = projectState.loadState(projectRoot);
+  if (!state) {
+    utils.print.error('Checkpoint tracking not initialized.');
+    utils.print.dim('Run: bootspring checkpoint init');
+    return;
+  }
+
+  // Check if checkpoint exists
+  const defs = projectState.getCheckpointDefinitions(state.projectType);
+  const checkpoint = defs.find(c => c.id === checkpointId);
+
+  if (!checkpoint) {
+    utils.print.error(`Unknown checkpoint: ${checkpointId}`);
+    console.log(`\n${utils.COLORS.bold}Available checkpoints:${utils.COLORS.reset}`);
+    for (const def of defs) {
+      console.log(`  - ${def.id}`);
+    }
+    console.log();
+    return;
+  }
+
+  // Check if already completed
+  if (state.checkpoints[checkpointId]?.completed) {
+    utils.print.warning(`Checkpoint "${checkpoint.label}" is already completed.`);
+    return;
+  }
+
+  // Complete the checkpoint
+  const updatedState = projectState.completeCheckpoint(projectRoot, checkpointId, {
+    completedBy: 'manual',
+    notes: options.notes || 'Manually marked as complete'
+  });
+
+  if (updatedState) {
+    utils.print.success(`Completed: ${checkpoint.label}`);
+
+    // Show progress
+    const progress = projectState.getCheckpointProgress(projectRoot);
+    console.log(`\nProgress: ${progress.completed}/${progress.total} (${progress.percentage}%)`);
+    console.log(checkpointEngine.getColoredProgressBar(progress.percentage, 30));
+    console.log();
+
+    // Emit telemetry
+    telemetry.emitEvent('checkpoint:complete', {
+      checkpointId,
+      label: checkpoint.label,
+      method: 'manual'
+    }, { projectRoot });
+  } else {
+    utils.print.error('Failed to complete checkpoint.');
+  }
+}
+
+/**
+ * Show checkpoint history
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options
+ */
+function handleHistory(projectRoot, options = {}) {
+  const history = projectState.getCheckpointHistory(projectRoot);
+
+  if (history.length === 0) {
+    console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Checkpoint History${utils.COLORS.reset}
+
+${utils.COLORS.dim}No checkpoint completions recorded yet.${utils.COLORS.reset}
+`);
+    return;
+  }
+
+  // Output as JSON if requested
+  if (options.json) {
+    console.log(JSON.stringify(history, null, 2));
+    return;
+  }
+
+  const state = projectState.loadState(projectRoot);
+  const defs = state ? projectState.getCheckpointDefinitions(state.projectType) : [];
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Checkpoint History${utils.COLORS.reset}
+`);
+
+  // Group by date
+  const byDate = {};
+  for (const record of history) {
+    const date = new Date(record.timestamp).toLocaleDateString();
+    if (!byDate[date]) {
+      byDate[date] = [];
+    }
+    byDate[date].push(record);
+  }
+
+  // Display grouped
+  for (const [date, records] of Object.entries(byDate)) {
+    console.log(`${utils.COLORS.bold}${date}${utils.COLORS.reset}`);
+
+    for (const record of records) {
+      const checkpoint = defs.find(d => d.id === record.checkpointId);
+      const label = checkpoint?.label || record.checkpointId;
+      const time = new Date(record.timestamp).toLocaleTimeString();
+
+      console.log(`  ${utils.COLORS.green}✓${utils.COLORS.reset} ${time} - ${label}`);
+      if (record.notes) {
+        console.log(`    ${utils.COLORS.dim}${record.notes}${utils.COLORS.reset}`);
+      }
+    }
+    console.log();
+  }
+}
+
+/**
+ * Sync checkpoints from files
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options
+ */
+async function handleSync(projectRoot, options = {}) {
+  const spinner = utils.createSpinner('Scanning for completed checkpoints...');
+  spinner.start();
+
+  const result = checkpointEngine.syncCheckpoints(projectRoot, {
+    dryRun: options.dryRun,
+    verbose: false
+  });
+
+  if (result.changes.length === 0) {
+    spinner.info('No new checkpoints detected.');
+  } else {
+    spinner.succeed(`Found ${result.changes.length} new checkpoint(s)!`);
+    console.log();
+
+    for (const change of result.changes) {
+      if (change.type === 'completed') {
+        console.log(`  ${utils.COLORS.green}✓${utils.COLORS.reset} ${change.label}`);
+        console.log(`    ${utils.COLORS.dim}${change.reason}${utils.COLORS.reset}`);
+      }
+    }
+    console.log();
+  }
+
+  // Show progress
+  console.log(`${utils.COLORS.bold}Progress:${utils.COLORS.reset} ${result.completed}/${result.total} (${Math.round((result.completed / result.total) * 100)}%)`);
+  console.log(checkpointEngine.getColoredProgressBar(Math.round((result.completed / result.total) * 100), 30));
+  console.log();
+
+  if (options.dryRun) {
+    utils.print.dim('Dry run - no changes were saved.');
+  } else {
+    // Auto-push to server if authenticated
+    try {
+      const pushResult = await pushCheckpointsToServer(projectRoot, { quiet: true, autoSync: true });
+      if (pushResult.success) {
+        utils.print.success('Synced to dashboard automatically');
+      }
+    } catch {
+      // Silent fail - push is best-effort
+    }
+  }
+
+  // Emit telemetry
+  telemetry.emitEvent('checkpoint:sync', {
+    changes: result.changes.length,
+    completed: result.completed,
+    total: result.total
+  }, { projectRoot });
+}
+
+/**
+ * Set project type
+ * @param {string} projectRoot - Project root directory
+ * @param {string} type - Project type
+ */
+function handleType(projectRoot, type) {
+  const validTypes = Object.values(projectState.PROJECT_TYPES);
+
+  if (!type) {
+    // Show current type
+    const state = projectState.loadState(projectRoot);
+    if (!state) {
+      utils.print.error('Checkpoint tracking not initialized.');
+      return;
+    }
+
+    console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Project Type${utils.COLORS.reset}
+
+Current type: ${getTypeBadge(state.projectType)}
+`);
+
+    console.log(`${utils.COLORS.bold}Available types:${utils.COLORS.reset}`);
+    for (const t of validTypes) {
+      const badge = getTypeBadge(t);
+      const current = t === state.projectType ? ' (current)' : '';
+      console.log(`  ${badge} ${t}${current}`);
+    }
+    console.log();
+
+    console.log(`${utils.COLORS.bold}Change type:${utils.COLORS.reset}`);
+    console.log('  bootspring checkpoint type <type>');
+    console.log();
+    return;
+  }
+
+  if (!validTypes.includes(type)) {
+    utils.print.error(`Invalid project type: ${type}`);
+    console.log(`\n${utils.COLORS.bold}Valid types:${utils.COLORS.reset} ${validTypes.join(', ')}`);
+    return;
+  }
+
+  const updatedState = projectState.setProjectType(projectRoot, type);
+
+  if (updatedState) {
+    utils.print.success(`Project type changed to: ${type}`);
+
+    // Sync checkpoints for new type
+    const syncResult = checkpointEngine.syncCheckpoints(projectRoot, { verbose: true });
+    console.log(`\nCheckpoints: ${syncResult.completed}/${syncResult.total} complete`);
+
+    telemetry.emitEvent('checkpoint:type-change', {
+      newType: type
+    }, { projectRoot });
+  }
+}
+
+/**
+ * Push checkpoints to dashboard
+ * Sends raw file scan data - server evaluates checkpoints and calculates scores
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options
+ */
+async function handlePush(projectRoot, options = {}) {
+  const spinner = utils.createSpinner('Scanning and syncing to dashboard...');
+  spinner.start();
+
+  try {
+    const result = await pushCheckpointsToServer(projectRoot, { quiet: false });
+
+    if (!result.success) {
+      if (result.reason === 'not_authenticated') {
+        spinner.fail('Not authenticated. Run: bootspring auth login');
+      } else if (result.reason === 'no_project') {
+        spinner.fail('No project selected. Run: bootspring switch <project>');
+      } else {
+        spinner.fail('Failed to sync checkpoints');
+      }
+      return;
+    }
+
+    spinner.succeed('Checkpoints synced to dashboard!');
+
+    // Display server-evaluated results
+    console.log(`
+${utils.COLORS.bold}Sync Summary:${utils.COLORS.reset}
+  Project Type: ${result.projectType}
+  Checkpoints: ${result.progress?.completed}/${result.progress?.total} (${result.progress?.percentage}%)
+  Health Score: ${result.healthScore}%
+  Last Sync: ${result.lastSyncAt ? new Date(result.lastSyncAt).toLocaleString() : 'Now'}
+`);
+
+    // Show health breakdown
+    if (result.healthBreakdown) {
+      console.log(`${utils.COLORS.bold}Health Breakdown:${utils.COLORS.reset}`);
+      for (const [key, value] of Object.entries(result.healthBreakdown)) {
+        const label = key.charAt(0).toUpperCase() + key.slice(1).replace(/([A-Z])/g, ' $1');
+        console.log(`  ${label}: ${value}%`);
+      }
+      console.log();
+    }
+
+    // Emit telemetry
+    telemetry.emitEvent('checkpoint:push', {
+      healthScore: result.healthScore,
+      checkpointsCompleted: result.progress?.completed
+    }, { projectRoot });
+
+  } catch (error) {
+    spinner.fail(`Failed to sync: ${error.message}`);
+  }
+}
+
+/**
+ * Detect project type automatically
+ * @param {string} projectRoot - Project root directory
+ */
+function handleDetect(projectRoot) {
+  const detectedType = projectState.detectProjectType(projectRoot);
+  const state = projectState.loadState(projectRoot);
+  const currentType = state?.projectType;
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Project Type Detection${utils.COLORS.reset}
+
+Detected type: ${getTypeBadge(detectedType)}
+`);
+
+  if (currentType && currentType !== detectedType) {
+    console.log(`Current type: ${getTypeBadge(currentType)}`);
+    console.log(`\n${utils.COLORS.bold}To change:${utils.COLORS.reset} bootspring checkpoint type ${detectedType}`);
+  } else if (!currentType) {
+    console.log(`${utils.COLORS.bold}To initialize:${utils.COLORS.reset} bootspring checkpoint init --type=${detectedType}`);
+  } else {
+    console.log(`${utils.COLORS.dim}Current type matches detected type.${utils.COLORS.reset}`);
+  }
+  console.log();
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Checkpoints${utils.COLORS.reset}
+${utils.COLORS.dim}Track project milestones and progress${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring checkpoint [command] [options]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  status                 Show all checkpoints with status (default)
+  init                   Initialize checkpoint tracking
+  complete <id>          Mark a checkpoint as complete
+  history                View checkpoint completion timeline
+  sync                   Re-scan files to detect completed items
+  type [type]            Show or set project type
+  detect                 Auto-detect project type from files
+  push                   Sync checkpoints to dashboard
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --json                 Output as JSON
+  --force                Force reinitialize
+  --dry-run              Don't save changes (for sync)
+  --type=<type>          Set project type (dev, content, business)
+  --notes="..."          Add notes when completing
+
+${utils.COLORS.bold}Project Types:${utils.COLORS.reset}
+  development            Software development projects
+  content                Content/editorial projects
+  business               Business planning projects
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring checkpoint                    # Show status
+  bootspring checkpoint init               # Initialize tracking
+  bootspring checkpoint complete prd       # Complete the PRD checkpoint
+  bootspring checkpoint sync               # Detect completed items
+  bootspring checkpoint type business      # Change to business type
+`);
+}
+
+// ============================================================================
+// Main Runner
+// ============================================================================
+
+/**
+ * Run checkpoint command
+ * @param {Array} args - Command arguments
+ */
+async function run(args) {
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
+
+  // Parse arguments
+  const parsed = utils.parseArgs(args);
+  const subcommand = parsed._[0] || 'status';
+  const options = {
+    json: parsed.json || false,
+    force: parsed.force || false,
+    dryRun: parsed['dry-run'] || parsed.dryRun || false,
+    type: parsed.type || null,
+    notes: parsed.notes || null
+  };
+
+  switch (subcommand) {
+    case 'status':
+    case 'show':
+    case 's':
+      handleStatus(projectRoot, options);
+      break;
+
+    case 'init':
+    case 'initialize':
+      handleInit(projectRoot, options);
+      break;
+
+    case 'complete':
+    case 'done':
+    case 'c':
+      handleComplete(projectRoot, parsed._[1], options);
+      break;
+
+    case 'history':
+    case 'log':
+    case 'h':
+      handleHistory(projectRoot, options);
+      break;
+
+    case 'sync':
+    case 'scan':
+      handleSync(projectRoot, options);
+      break;
+
+    case 'type':
+    case 't':
+      handleType(projectRoot, parsed._[1] || options.type);
+      break;
+
+    case 'detect':
+    case 'd':
+      handleDetect(projectRoot);
+      break;
+
+    case 'push':
+    case 'upload':
+      await handlePush(projectRoot, options);
+      break;
+
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+
+    default:
+      utils.print.error(`Unknown subcommand: ${subcommand}`);
+      showHelp();
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+module.exports = {
+  run,
+  // Utility exports for programmatic use
+  handleStatus,
+  handleInit,
+  handleComplete,
+  handleHistory,
+  handleSync,
+  handleType,
+  handleDetect
+};