@girardmedia/bootspring 2.0.21 → 2.0.22

package/src/core/checkpoint-engine.ts

@@ -0,0 +1,482 @@
+/**
+ * Bootspring Checkpoint Engine
+ * Detects and syncs project checkpoints based on file existence and criteria
+ *
+ * @package bootspring
+ * @module core/checkpoint-engine
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Module interfaces
+interface Utils {
+  print: {
+    success: (msg: string) => void;
+  };
+  COLORS: {
+    green: string;
+    yellow: string;
+    cyan: string;
+    dim: string;
+    reset: string;
+  };
+}
+
+interface CheckpointDefinition {
+  id: string;
+  label: string;
+  sourceFile: string;
+  criteria: string;
+}
+
+interface CheckpointState {
+  completed: boolean;
+  completedAt?: string | undefined;
+  completedBy?: string | undefined;
+}
+
+interface ProjectStateData {
+  projectType?: string | undefined;
+  checkpoints: Record<string, CheckpointState>;
+  github?: { connected?: boolean } | undefined;
+  content?: { published?: boolean } | undefined;
+  autoTagged?: boolean | undefined;
+  taggedBy?: string | undefined;
+  createdAt?: string | undefined;
+  updatedAt?: string | undefined;
+}
+
+interface ProjectState {
+  PROJECT_TYPES: { DEVELOPMENT: string };
+  getStateFilePath: (root: string) => string;
+  getPlanningDir: (root: string) => string;
+  loadState: (root: string) => ProjectStateData | null;
+  getOrCreateState: (root: string) => ProjectStateData;
+  saveState: (root: string, state: ProjectStateData) => void;
+  getCheckpointDefinitions: (projectType: string) => CheckpointDefinition[];
+  recordCheckpointHistory: (root: string, record: CheckpointHistoryRecord) => void;
+}
+
+interface CheckpointHistoryRecord {
+  checkpointId: string;
+  completedAt: string;
+  completedBy: string;
+  notes: string;
+}
+
+export interface CheckpointEvaluation {
+  id: string;
+  label: string;
+  sourceFile: string;
+  criteria: string;
+  completed: boolean;
+  reason: string | null;
+}
+
+export interface SyncChange {
+  id: string;
+  label: string;
+  type: 'completed' | 'uncompleted';
+  reason: string | null;
+}
+
+export interface SyncResult {
+  changes: SyncChange[];
+  unchanged: CheckpointEvaluation[];
+  total: number;
+  completed: number;
+  state: ProjectStateData;
+}
+
+export interface SyncOptions {
+  dryRun?: boolean | undefined;
+  verbose?: boolean | undefined;
+}
+
+export interface CheckpointStatus {
+  exists: boolean;
+  message?: string | undefined;
+  projectType?: string | undefined;
+  autoTagged?: boolean | undefined;
+  taggedBy?: string | undefined;
+  total?: number | undefined;
+  completed?: number | undefined;
+  pending?: number | undefined;
+  percentage?: number | undefined;
+  checkpoints?: CheckpointEvaluation[] | undefined;
+  createdAt?: string | undefined;
+  updatedAt?: string | undefined;
+}
+
+export interface NextStep {
+  id: string;
+  label: string;
+  sourceFile: string;
+  action: string;
+}
+
+// Lazy-loaded modules
+let _utils: Utils | null = null;
+let _projectState: ProjectState | null = null;
+
+function getUtils(): Utils {
+  if (!_utils) {
+    _utils = require('./utils') as Utils;
+  }
+  return _utils;
+}
+
+function getProjectState(): ProjectState {
+  if (!_projectState) {
+    _projectState = require('./project-state') as ProjectState;
+  }
+  return _projectState;
+}
+
+// ============================================================================
+// Criteria Evaluators
+// ============================================================================
+
+/**
+ * Check if a file exists
+ */
+export function criteriaFileExists(filePath: string): boolean {
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Check if a file exists and has minimum content length
+ */
+export function criteriaFileExistsMinLength(filePath: string, minLength: number = 500): boolean {
+  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
+ */
+export function criteriaContainsUrl(filePath: string): boolean {
+  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)
+ */
+export function criteriaConfigExists(projectRoot: string): boolean {
+  const projectState = getProjectState();
+  const stateFile = projectState.getStateFilePath(projectRoot);
+  return fs.existsSync(stateFile);
+}
+
+/**
+ * Check if GitHub is connected in state
+ */
+export function criteriaGitHubConnected(projectRoot: string): boolean {
+  const projectState = getProjectState();
+  const state = projectState.loadState(projectRoot);
+  return state?.github?.connected === true;
+}
+
+/**
+ * Check if content is published in state
+ */
+export function criteriaContentPublished(projectRoot: string): boolean {
+  const projectState = getProjectState();
+  const state = projectState.loadState(projectRoot);
+  return state?.content?.published === true;
+}
+
+// ============================================================================
+// Checkpoint Evaluation
+// ============================================================================
+
+/**
+ * Evaluate a single checkpoint
+ */
+export function evaluateCheckpoint(projectRoot: string, checkpoint: CheckpointDefinition): CheckpointEvaluation {
+  const projectState = getProjectState();
+  const planningDir = projectState.getPlanningDir(projectRoot);
+  const filePath = path.join(planningDir, checkpoint.sourceFile);
+
+  let completed = false;
+  let reason: string | null = 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
+ */
+export function evaluateAllCheckpoints(projectRoot: string, projectType: string | null = null): CheckpointEvaluation[] {
+  const projectState = getProjectState();
+
+  // 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
+ */
+export function syncCheckpoints(projectRoot: string, options: SyncOptions = {}): SyncResult {
+  const utils = getUtils();
+  const projectState = getProjectState();
+
+  const state = projectState.getOrCreateState(projectRoot);
+  const evaluations = evaluateAllCheckpoints(projectRoot, state.projectType || null);
+
+  const changes: SyncChange[] = [];
+  const unchanged: CheckpointEvaluation[] = [];
+
+  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'
+        };
+
+        const checkpointState = state.checkpoints[evaluation.id];
+        if (checkpointState?.completedAt) {
+          projectState.recordCheckpointHistory(projectRoot, {
+            checkpointId: evaluation.id,
+            completedAt: checkpointState.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
+ */
+export function getCheckpointStatus(projectRoot: string): CheckpointStatus {
+  const projectState = getProjectState();
+  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 || null);
+  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
+ */
+export function getNextSteps(projectRoot: string): NextStep[] {
+  const projectState = getProjectState();
+  const state = projectState.loadState(projectRoot);
+
+  if (!state) {
+    return [];
+  }
+
+  const evaluations = evaluateAllCheckpoints(projectRoot, state.projectType || null);
+  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
+ */
+export function getActionSuggestion(checkpoint: CheckpointEvaluation): string {
+  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
+ */
+export function generateProgressBar(percentage: number, width: number = 20): string {
+  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
+ */
+export function getColoredProgressBar(percentage: number, width: number = 20): string {
+  const utils = getUtils();
+  const bar = generateProgressBar(percentage, width);
+  let color: string;
+
+  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}`;
+}