@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/checkpoint-engine.js

@@ -0,0 +1,408 @@
+/**
+ * Bootspring Checkpoint Engine
+ * Detects and syncs project checkpoints based on file existence and criteria
+ *
+ * @package bootspring
+ * @module core/checkpoint-engine
+ */
+
+const fs = require('fs');
+const path = require('path');
+const utils = require('./utils');
+const projectState = require('./project-state');
+
+// ============================================================================
+// Criteria Evaluators
+// ============================================================================
+
+/**
+ * Check if a file exists
+ * @param {string} filePath - File path
+ * @returns {boolean} True if file exists
+ */
+function criteriaFileExists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Check if a file exists and has minimum content length
+ * @param {string} filePath - File path
+ * @param {number} minLength - Minimum content length
+ * @returns {boolean} True if file exists with minimum content
+ */
+function criteriaFileExistsMinLength(filePath, minLength = 500) {
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.length >= minLength;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a file contains a URL
+ * @param {string} filePath - File path
+ * @returns {boolean} True if file contains a URL
+ */
+function criteriaContainsUrl(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    // Match common URL patterns
+    const urlPattern = /https?:\/\/[^\s)\]"'`]+/i;
+    return urlPattern.test(content);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if PROJECT_STATE.json exists (config exists)
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean} True if state file exists
+ */
+function criteriaConfigExists(projectRoot) {
+  const stateFile = projectState.getStateFilePath(projectRoot);
+  return fs.existsSync(stateFile);
+}
+
+/**
+ * Check if GitHub is connected in state
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean} True if GitHub is connected
+ */
+function criteriaGitHubConnected(projectRoot) {
+  const state = projectState.loadState(projectRoot);
+  return state?.github?.connected === true;
+}
+
+/**
+ * Check if content is published in state
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean} True if content is published
+ */
+function criteriaContentPublished(projectRoot) {
+  const state = projectState.loadState(projectRoot);
+  return state?.content?.published === true;
+}
+
+// ============================================================================
+// Checkpoint Evaluation
+// ============================================================================
+
+/**
+ * Evaluate a single checkpoint
+ * @param {string} projectRoot - Project root directory
+ * @param {object} checkpoint - Checkpoint definition
+ * @returns {object} Evaluation result
+ */
+function evaluateCheckpoint(projectRoot, checkpoint) {
+  const planningDir = projectState.getPlanningDir(projectRoot);
+  const filePath = path.join(planningDir, checkpoint.sourceFile);
+
+  let completed = false;
+  let reason = null;
+
+  switch (checkpoint.criteria) {
+    case 'file_exists':
+      completed = criteriaFileExists(filePath);
+      reason = completed ? 'File exists' : 'File not found';
+      break;
+
+    case 'file_exists_min_500':
+      completed = criteriaFileExistsMinLength(filePath, 500);
+      reason = completed ? 'File exists with sufficient content' : 'File missing or too short (<500 chars)';
+      break;
+
+    case 'contains_url':
+      completed = criteriaContainsUrl(filePath);
+      reason = completed ? 'Deployment URL found' : 'No deployment URL found';
+      break;
+
+    case 'config_exists':
+      completed = criteriaConfigExists(projectRoot);
+      reason = completed ? 'Project initialized' : 'PROJECT_STATE.json not found';
+      break;
+
+    case 'github_connected':
+      completed = criteriaGitHubConnected(projectRoot);
+      reason = completed ? 'GitHub repository connected' : 'GitHub not connected';
+      break;
+
+    case 'content_published':
+      completed = criteriaContentPublished(projectRoot);
+      reason = completed ? 'Content published' : 'Content not yet published';
+      break;
+
+    default:
+      reason = `Unknown criteria: ${checkpoint.criteria}`;
+  }
+
+  return {
+    id: checkpoint.id,
+    label: checkpoint.label,
+    sourceFile: checkpoint.sourceFile,
+    criteria: checkpoint.criteria,
+    completed,
+    reason
+  };
+}
+
+/**
+ * Evaluate all checkpoints for a project
+ * @param {string} projectRoot - Project root directory
+ * @param {string} projectType - Optional project type override
+ * @returns {Array} Array of evaluation results
+ */
+function evaluateAllCheckpoints(projectRoot, projectType = null) {
+  // Get project type from state if not provided
+  if (!projectType) {
+    const state = projectState.loadState(projectRoot);
+    projectType = state?.projectType || projectState.PROJECT_TYPES.DEVELOPMENT;
+  }
+
+  const checkpointDefs = projectState.getCheckpointDefinitions(projectType);
+  return checkpointDefs.map(checkpoint => evaluateCheckpoint(projectRoot, checkpoint));
+}
+
+/**
+ * Sync checkpoints - detect completed checkpoints from files
+ * @param {string} projectRoot - Project root directory
+ * @param {object} options - Options
+ * @param {boolean} options.dryRun - If true, don't save changes
+ * @param {boolean} options.verbose - If true, log changes
+ * @returns {object} Sync result
+ */
+function syncCheckpoints(projectRoot, options = {}) {
+  const state = projectState.getOrCreateState(projectRoot);
+  const evaluations = evaluateAllCheckpoints(projectRoot, state.projectType);
+
+  const changes = [];
+  const unchanged = [];
+
+  for (const evaluation of evaluations) {
+    const currentState = state.checkpoints[evaluation.id];
+    const wasCompleted = currentState?.completed || false;
+
+    if (evaluation.completed && !wasCompleted) {
+      // Newly completed
+      changes.push({
+        id: evaluation.id,
+        label: evaluation.label,
+        type: 'completed',
+        reason: evaluation.reason
+      });
+
+      if (!options.dryRun) {
+        state.checkpoints[evaluation.id] = {
+          completed: true,
+          completedAt: new Date().toISOString(),
+          completedBy: 'sync'
+        };
+
+        projectState.recordCheckpointHistory(projectRoot, {
+          checkpointId: evaluation.id,
+          completedAt: state.checkpoints[evaluation.id].completedAt,
+          completedBy: 'sync',
+          notes: evaluation.reason
+        });
+      }
+    } else if (!evaluation.completed && wasCompleted) {
+      // Was completed but no longer meets criteria (rare case)
+      changes.push({
+        id: evaluation.id,
+        label: evaluation.label,
+        type: 'uncompleted',
+        reason: evaluation.reason
+      });
+
+      // Note: We don't uncomplete checkpoints automatically - they stay completed once done
+      unchanged.push(evaluation);
+    } else {
+      unchanged.push(evaluation);
+    }
+  }
+
+  // Save state if not dry run
+  if (!options.dryRun && changes.length > 0) {
+    projectState.saveState(projectRoot, state);
+  }
+
+  // Log if verbose
+  if (options.verbose) {
+    for (const change of changes) {
+      if (change.type === 'completed') {
+        utils.print.success(`Checkpoint completed: ${change.label}`);
+      }
+    }
+  }
+
+  return {
+    changes,
+    unchanged,
+    total: evaluations.length,
+    completed: evaluations.filter(e => e.completed).length,
+    state
+  };
+}
+
+// ============================================================================
+// Progress Reporting
+// ============================================================================
+
+/**
+ * Get checkpoint status with visual indicators
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Status report
+ */
+function getCheckpointStatus(projectRoot) {
+  const state = projectState.loadState(projectRoot);
+
+  if (!state) {
+    return {
+      exists: false,
+      message: 'Project state not initialized. Run `bootspring checkpoint init` to start.'
+    };
+  }
+
+  const evaluations = evaluateAllCheckpoints(projectRoot, state.projectType);
+  const completed = evaluations.filter(e => e.completed);
+  const pending = evaluations.filter(e => !e.completed);
+
+  return {
+    exists: true,
+    projectType: state.projectType,
+    autoTagged: state.autoTagged,
+    taggedBy: state.taggedBy,
+    total: evaluations.length,
+    completed: completed.length,
+    pending: pending.length,
+    percentage: Math.round((completed.length / evaluations.length) * 100),
+    checkpoints: evaluations,
+    createdAt: state.createdAt,
+    updatedAt: state.updatedAt
+  };
+}
+
+/**
+ * Get next steps - what checkpoints should be completed next
+ * @param {string} projectRoot - Project root directory
+ * @returns {Array} Array of suggested next checkpoints
+ */
+function getNextSteps(projectRoot) {
+  const state = projectState.loadState(projectRoot);
+
+  if (!state) {
+    return [];
+  }
+
+  const evaluations = evaluateAllCheckpoints(projectRoot, state.projectType);
+  const pending = evaluations.filter(e => !e.completed);
+
+  // Return first 3 incomplete checkpoints as suggestions
+  return pending.slice(0, 3).map(checkpoint => ({
+    id: checkpoint.id,
+    label: checkpoint.label,
+    sourceFile: checkpoint.sourceFile,
+    action: getActionSuggestion(checkpoint)
+  }));
+}
+
+/**
+ * Get action suggestion for a checkpoint
+ * @param {object} checkpoint - Checkpoint evaluation
+ * @returns {string} Suggested action
+ */
+function getActionSuggestion(checkpoint) {
+  switch (checkpoint.criteria) {
+    case 'file_exists':
+    case 'file_exists_min_500':
+      return `Create planning/${checkpoint.sourceFile}`;
+    case 'contains_url':
+      return `Add deployment URL to planning/${checkpoint.sourceFile}`;
+    case 'github_connected':
+      return 'Run `bootspring github connect`';
+    case 'content_published':
+      return 'Mark content as published';
+    default:
+      return 'Complete this checkpoint';
+  }
+}
+
+// ============================================================================
+// Progress Bar Generation
+// ============================================================================
+
+/**
+ * Generate a progress bar string
+ * @param {number} percentage - Progress percentage (0-100)
+ * @param {number} width - Bar width in characters
+ * @returns {string} Progress bar string
+ */
+function generateProgressBar(percentage, width = 20) {
+  const filled = Math.round((percentage / 100) * width);
+  const empty = width - filled;
+
+  const filledChar = '█';
+  const emptyChar = '░';
+
+  return filledChar.repeat(filled) + emptyChar.repeat(empty);
+}
+
+/**
+ * Get colored progress bar
+ * @param {number} percentage - Progress percentage
+ * @param {number} width - Bar width
+ * @returns {string} Colored progress bar
+ */
+function getColoredProgressBar(percentage, width = 20) {
+  const bar = generateProgressBar(percentage, width);
+  let color;
+
+  if (percentage >= 80) {
+    color = utils.COLORS.green;
+  } else if (percentage >= 50) {
+    color = utils.COLORS.yellow;
+  } else if (percentage >= 25) {
+    color = utils.COLORS.cyan;
+  } else {
+    color = utils.COLORS.dim;
+  }
+
+  return `${color}${bar}${utils.COLORS.reset}`;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+module.exports = {
+  // Criteria evaluators
+  criteriaFileExists,
+  criteriaFileExistsMinLength,
+  criteriaContainsUrl,
+  criteriaConfigExists,
+  criteriaGitHubConnected,
+  criteriaContentPublished,
+
+  // Evaluation
+  evaluateCheckpoint,
+  evaluateAllCheckpoints,
+  syncCheckpoints,
+
+  // Status
+  getCheckpointStatus,
+  getNextSteps,
+  getActionSuggestion,
+
+  // Progress
+  generateProgressBar,
+  getColoredProgressBar
+};