@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/build-state.js

@@ -0,0 +1,577 @@
+/**
+ * Bootspring Build State Management
+ *
+ * Manages BUILD_STATE.json for continuous build loop persistence.
+ * Tracks phases, implementation queue, MVP criteria, and loop session.
+ *
+ * @package bootspring
+ * @module core/build-state
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BUILD_STATE_FILE = 'BUILD_STATE.json';
+const PLANNING_DIR = 'planning';
+
+/**
+ * Default build state schema
+ */
+function getDefaultState(projectName = 'Project') {
+  return {
+    version: '1.0.0',
+    projectName,
+    status: 'pending', // pending, in_progress, paused, completed, failed
+    currentPhase: null,
+
+    phases: {
+      foundation: { status: 'pending', tasks: [] },
+      mvp: { status: 'pending', tasks: [] },
+      launch: { status: 'pending', tasks: [] }
+    },
+
+    implementationQueue: [],
+
+    mvpCriteria: {
+      features: [],
+      completionPercentage: 0,
+      allCriteriaMet: false
+    },
+
+    loopSession: {
+      sessionId: null,
+      currentIteration: 0,
+      maxIterations: 50,
+      startedAt: null,
+      lastUpdated: null,
+      pausedAt: null
+    },
+
+    metadata: {
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      seedSource: null,
+      preseedDocs: []
+    }
+  };
+}
+
+/**
+ * Get the planning directory path
+ * @param {string} projectRoot - Project root path
+ * @returns {string} Planning directory path
+ */
+function getPlanningDir(projectRoot) {
+  return path.join(projectRoot, PLANNING_DIR);
+}
+
+/**
+ * Get the build state file path
+ * @param {string} projectRoot - Project root path
+ * @returns {string} Build state file path
+ */
+function getStatePath(projectRoot) {
+  return path.join(getPlanningDir(projectRoot), BUILD_STATE_FILE);
+}
+
+/**
+ * Check if build state exists
+ * @param {string} projectRoot - Project root path
+ * @returns {boolean} Whether build state exists
+ */
+function exists(projectRoot) {
+  return fs.existsSync(getStatePath(projectRoot));
+}
+
+/**
+ * Initialize a new build state
+ * @param {string} projectRoot - Project root path
+ * @param {object} config - Initial configuration
+ * @returns {object} Initialized build state
+ */
+function initialize(projectRoot, config = {}) {
+  const planningDir = getPlanningDir(projectRoot);
+
+  // Create planning directory if it doesn't exist
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+
+  const state = getDefaultState(config.projectName || 'Project');
+
+  // Apply config overrides
+  if (config.phases) {
+    state.phases = { ...state.phases, ...config.phases };
+  }
+
+  if (config.implementationQueue) {
+    state.implementationQueue = config.implementationQueue;
+  }
+
+  if (config.mvpCriteria) {
+    state.mvpCriteria = { ...state.mvpCriteria, ...config.mvpCriteria };
+  }
+
+  if (config.maxIterations) {
+    state.loopSession.maxIterations = config.maxIterations;
+  }
+
+  if (config.seedSource) {
+    state.metadata.seedSource = config.seedSource;
+  }
+
+  if (config.preseedDocs) {
+    state.metadata.preseedDocs = config.preseedDocs;
+  }
+
+  // Generate session ID
+  state.loopSession.sessionId = generateSessionId();
+
+  // Save initial state
+  save(projectRoot, state);
+
+  return state;
+}
+
+/**
+ * Generate a unique session ID
+ * @returns {string} Session ID
+ */
+function generateSessionId() {
+  return `build-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Load build state from disk
+ * @param {string} projectRoot - Project root path
+ * @returns {object|null} Build state or null if not found
+ */
+function load(projectRoot) {
+  const statePath = getStatePath(projectRoot);
+
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(statePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    console.error(`Failed to load build state: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save build state to disk
+ * @param {string} projectRoot - Project root path
+ * @param {object} state - Build state to save
+ * @returns {boolean} Success
+ */
+function save(projectRoot, state) {
+  const statePath = getStatePath(projectRoot);
+  const planningDir = getPlanningDir(projectRoot);
+
+  // Ensure planning directory exists
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+
+  // Update timestamp
+  state.metadata.updatedAt = new Date().toISOString();
+  state.loopSession.lastUpdated = new Date().toISOString();
+
+  try {
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    return true;
+  } catch (error) {
+    console.error(`Failed to save build state: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Update task progress
+ * @param {string} projectRoot - Project root path
+ * @param {string} taskId - Task ID
+ * @param {string} status - New status (pending, in_progress, completed, blocked, skipped)
+ * @param {object} details - Additional details
+ * @returns {object|null} Updated state or null on failure
+ */
+function updateProgress(projectRoot, taskId, status, details = {}) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  // Find task in queue
+  const taskIndex = state.implementationQueue.findIndex(t => t.id === taskId);
+  if (taskIndex === -1) return null;
+
+  // Update task status
+  state.implementationQueue[taskIndex].status = status;
+  state.implementationQueue[taskIndex].updatedAt = new Date().toISOString();
+
+  // Add any additional details
+  if (details.completedAt) {
+    state.implementationQueue[taskIndex].completedAt = details.completedAt;
+  }
+  if (details.error) {
+    state.implementationQueue[taskIndex].error = details.error;
+  }
+  if (details.output) {
+    state.implementationQueue[taskIndex].lastOutput = details.output;
+  }
+
+  // Update phase progress
+  const task = state.implementationQueue[taskIndex];
+  if (task.phase && state.phases[task.phase]) {
+    updatePhaseProgress(state, task.phase);
+  }
+
+  // Update MVP criteria progress
+  updateMvpProgress(state);
+
+  // Update iteration count if completing
+  if (status === 'completed' || status === 'skipped') {
+    state.loopSession.currentIteration++;
+  }
+
+  // Save updated state
+  save(projectRoot, state);
+
+  return state;
+}
+
+/**
+ * Update phase progress based on task statuses
+ * @param {object} state - Build state
+ * @param {string} phaseName - Phase name
+ */
+function updatePhaseProgress(state, phaseName) {
+  const phaseTasks = state.implementationQueue.filter(t => t.phase === phaseName);
+  const completedTasks = phaseTasks.filter(t => t.status === 'completed');
+
+  if (phaseTasks.length === 0) return;
+
+  const progress = completedTasks.length / phaseTasks.length;
+
+  if (progress === 0) {
+    state.phases[phaseName].status = 'pending';
+  } else if (progress === 1) {
+    state.phases[phaseName].status = 'completed';
+  } else {
+    state.phases[phaseName].status = 'in_progress';
+  }
+
+  state.phases[phaseName].tasks = phaseTasks.map(t => ({
+    id: t.id,
+    title: t.title,
+    status: t.status
+  }));
+}
+
+/**
+ * Update MVP criteria progress
+ * @param {object} state - Build state
+ */
+function updateMvpProgress(state) {
+  const mvpTasks = state.implementationQueue.filter(t => t.phase === 'mvp');
+  const completedMvpTasks = mvpTasks.filter(t => t.status === 'completed');
+
+  if (mvpTasks.length > 0) {
+    state.mvpCriteria.completionPercentage = Math.round(
+      (completedMvpTasks.length / mvpTasks.length) * 100
+    );
+  }
+
+  // Update feature completion status
+  state.mvpCriteria.features = state.mvpCriteria.features.map(feature => {
+    const relatedTasks = mvpTasks.filter(t =>
+      t.title.toLowerCase().includes(feature.name.toLowerCase()) ||
+      t.sourceSection?.toLowerCase().includes(feature.name.toLowerCase())
+    );
+
+    const allComplete = relatedTasks.length > 0 &&
+      relatedTasks.every(t => t.status === 'completed');
+
+    return {
+      ...feature,
+      status: allComplete ? 'completed' : 'pending'
+    };
+  });
+
+  // Check if all MVP criteria are met
+  state.mvpCriteria.allCriteriaMet =
+    state.mvpCriteria.completionPercentage === 100 ||
+    state.mvpCriteria.features.every(f => f.status === 'completed');
+}
+
+/**
+ * Get the next pending task
+ * @param {string} projectRoot - Project root path
+ * @returns {object|null} Next task or null if none
+ */
+function getNextTask(projectRoot) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  // First, check for any in_progress tasks
+  const inProgress = state.implementationQueue.find(t => t.status === 'in_progress');
+  if (inProgress) return inProgress;
+
+  // Then get next pending task (respecting dependencies)
+  const pendingTasks = state.implementationQueue.filter(t => t.status === 'pending');
+
+  for (const task of pendingTasks) {
+    // Check if all dependencies are completed
+    if (!task.dependencies || task.dependencies.length === 0) {
+      return task;
+    }
+
+    const depsCompleted = task.dependencies.every(depId => {
+      const depTask = state.implementationQueue.find(t => t.id === depId);
+      return depTask && depTask.status === 'completed';
+    });
+
+    if (depsCompleted) {
+      return task;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Add a task to the implementation queue
+ * @param {string} projectRoot - Project root path
+ * @param {object} task - Task to add
+ * @returns {object|null} Updated state or null on failure
+ */
+function addTask(projectRoot, task) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  // Generate task ID if not provided
+  if (!task.id) {
+    const count = state.implementationQueue.length + 1;
+    task.id = `task-${count.toString().padStart(3, '0')}`;
+  }
+
+  // Set defaults
+  task.status = task.status || 'pending';
+  task.createdAt = new Date().toISOString();
+
+  state.implementationQueue.push(task);
+  save(projectRoot, state);
+
+  return state;
+}
+
+/**
+ * Set tasks in batch
+ * @param {string} projectRoot - Project root path
+ * @param {array} tasks - Tasks to set
+ * @returns {object|null} Updated state or null on failure
+ */
+function setTasks(projectRoot, tasks) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  // Process tasks with defaults
+  state.implementationQueue = tasks.map((task, index) => ({
+    id: task.id || `task-${(index + 1).toString().padStart(3, '0')}`,
+    title: task.title,
+    description: task.description || '',
+    source: task.source || 'manual',
+    sourceSection: task.sourceSection || null,
+    phase: task.phase || 'mvp',
+    status: task.status || 'pending',
+    acceptanceCriteria: task.acceptanceCriteria || [],
+    dependencies: task.dependencies || [],
+    estimatedComplexity: task.estimatedComplexity || 'medium',
+    createdAt: new Date().toISOString()
+  }));
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Set MVP features
+ * @param {string} projectRoot - Project root path
+ * @param {array} features - MVP features
+ * @returns {object|null} Updated state or null on failure
+ */
+function setMvpFeatures(projectRoot, features) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.mvpCriteria.features = features.map(f => ({
+    name: typeof f === 'string' ? f : f.name,
+    status: 'pending'
+  }));
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Update loop session
+ * @param {string} projectRoot - Project root path
+ * @param {object} updates - Session updates
+ * @returns {object|null} Updated state or null on failure
+ */
+function updateSession(projectRoot, updates) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.loopSession = {
+    ...state.loopSession,
+    ...updates
+  };
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Pause the build loop
+ * @param {string} projectRoot - Project root path
+ * @returns {object|null} Updated state or null on failure
+ */
+function pause(projectRoot) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.status = 'paused';
+  state.loopSession.pausedAt = new Date().toISOString();
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Resume the build loop
+ * @param {string} projectRoot - Project root path
+ * @returns {object|null} Updated state or null on failure
+ */
+function resume(projectRoot) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.status = 'in_progress';
+  state.loopSession.pausedAt = null;
+
+  // Generate new session ID if resuming after long pause
+  const pausedAt = state.loopSession.pausedAt ? new Date(state.loopSession.pausedAt) : null;
+  const now = new Date();
+  if (pausedAt && (now - pausedAt) > 3600000) { // 1 hour
+    state.loopSession.sessionId = generateSessionId();
+  }
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Mark build as complete
+ * @param {string} projectRoot - Project root path
+ * @returns {object|null} Updated state or null on failure
+ */
+function complete(projectRoot) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.status = 'completed';
+  state.loopSession.completedAt = new Date().toISOString();
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Mark build as failed
+ * @param {string} projectRoot - Project root path
+ * @param {string} reason - Failure reason
+ * @returns {object|null} Updated state or null on failure
+ */
+function fail(projectRoot, reason) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.status = 'failed';
+  state.loopSession.failedAt = new Date().toISOString();
+  state.loopSession.failureReason = reason;
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Get build statistics
+ * @param {string} projectRoot - Project root path
+ * @returns {object|null} Statistics or null if no state
+ */
+function getStats(projectRoot) {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  const tasks = state.implementationQueue;
+  const completed = tasks.filter(t => t.status === 'completed').length;
+  const pending = tasks.filter(t => t.status === 'pending').length;
+  const inProgress = tasks.filter(t => t.status === 'in_progress').length;
+  const blocked = tasks.filter(t => t.status === 'blocked').length;
+  const skipped = tasks.filter(t => t.status === 'skipped').length;
+
+  return {
+    total: tasks.length,
+    completed,
+    pending,
+    inProgress,
+    blocked,
+    skipped,
+    progress: tasks.length > 0 ? Math.round((completed / tasks.length) * 100) : 0,
+    currentPhase: state.currentPhase,
+    mvpProgress: state.mvpCriteria.completionPercentage,
+    mvpComplete: state.mvpCriteria.allCriteriaMet,
+    iteration: state.loopSession.currentIteration,
+    maxIterations: state.loopSession.maxIterations,
+    status: state.status
+  };
+}
+
+/**
+ * Reset build state
+ * @param {string} projectRoot - Project root path
+ * @returns {object} Fresh state
+ */
+function reset(projectRoot) {
+  const state = load(projectRoot);
+  const projectName = state?.projectName || 'Project';
+
+  return initialize(projectRoot, { projectName });
+}
+
+module.exports = {
+  BUILD_STATE_FILE,
+  PLANNING_DIR,
+  getDefaultState,
+  getPlanningDir,
+  getStatePath,
+  exists,
+  initialize,
+  generateSessionId,
+  load,
+  save,
+  updateProgress,
+  getNextTask,
+  addTask,
+  setTasks,
+  setMvpFeatures,
+  updateSession,
+  pause,
+  resume,
+  complete,
+  fail,
+  getStats,
+  reset
+};