@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/build-state.ts

@@ -0,0 +1,621 @@
+/**
+ * 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
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export const BUILD_STATE_FILE = 'BUILD_STATE.json';
+export const PLANNING_DIR = 'planning';
+
+// Type definitions
+export interface Task {
+  id: string;
+  title: string;
+  description?: string | undefined;
+  source?: string | undefined;
+  sourceSection?: string | null | undefined;
+  phase?: string | undefined;
+  status: 'pending' | 'in_progress' | 'completed' | 'blocked' | 'skipped';
+  acceptanceCriteria?: string[] | undefined;
+  dependencies?: string[] | undefined;
+  estimatedComplexity?: string | undefined;
+  createdAt?: string | undefined;
+  updatedAt?: string | undefined;
+  completedAt?: string | undefined;
+  error?: string | undefined;
+  lastOutput?: string | undefined;
+}
+
+export interface MvpFeature {
+  name: string;
+  status: 'pending' | 'completed';
+}
+
+export interface PhaseData {
+  status: 'pending' | 'in_progress' | 'completed';
+  tasks: { id: string; title: string; status: string }[];
+}
+
+export interface LoopSession {
+  sessionId: string | null;
+  currentIteration: number;
+  maxIterations: number;
+  startedAt: string | null;
+  lastUpdated: string | null;
+  pausedAt: string | null;
+  completedAt?: string | undefined;
+  failedAt?: string | undefined;
+  failureReason?: string | undefined;
+}
+
+export interface MvpCriteria {
+  features: MvpFeature[];
+  completionPercentage: number;
+  allCriteriaMet: boolean;
+}
+
+export interface BuildMetadata {
+  createdAt: string;
+  updatedAt: string;
+  seedSource: string | null;
+  preseedDocs: string[];
+}
+
+export interface BuildState {
+  version: string;
+  projectName: string;
+  status: 'pending' | 'in_progress' | 'paused' | 'completed' | 'failed';
+  currentPhase: string | null;
+  phases: Record<string, PhaseData>;
+  implementationQueue: Task[];
+  mvpCriteria: MvpCriteria;
+  loopSession: LoopSession;
+  metadata: BuildMetadata;
+}
+
+export interface BuildStats {
+  total: number;
+  completed: number;
+  pending: number;
+  inProgress: number;
+  blocked: number;
+  skipped: number;
+  progress: number;
+  currentPhase: string | null;
+  mvpProgress: number;
+  mvpComplete: boolean;
+  iteration: number;
+  maxIterations: number;
+  status: string;
+}
+
+export interface InitConfig {
+  projectName?: string | undefined;
+  phases?: Record<string, PhaseData> | undefined;
+  implementationQueue?: Task[] | undefined;
+  mvpCriteria?: Partial<MvpCriteria> | undefined;
+  maxIterations?: number | undefined;
+  seedSource?: string | undefined;
+  preseedDocs?: string[] | undefined;
+}
+
+export interface UpdateDetails {
+  completedAt?: string | undefined;
+  error?: string | undefined;
+  output?: string | undefined;
+}
+
+/**
+ * Default build state schema
+ */
+export function getDefaultState(projectName: string = 'Project'): BuildState {
+  return {
+    version: '1.0.0',
+    projectName,
+    status: 'pending',
+    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
+ */
+export function getPlanningDir(projectRoot: string): string {
+  return path.join(projectRoot, PLANNING_DIR);
+}
+
+/**
+ * Get the build state file path
+ */
+export function getStatePath(projectRoot: string): string {
+  return path.join(getPlanningDir(projectRoot), BUILD_STATE_FILE);
+}
+
+/**
+ * Check if build state exists
+ */
+export function exists(projectRoot: string): boolean {
+  return fs.existsSync(getStatePath(projectRoot));
+}
+
+/**
+ * Generate a unique session ID
+ */
+export function generateSessionId(): string {
+  return `build-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Initialize a new build state
+ */
+export function initialize(projectRoot: string, config: InitConfig = {}): BuildState {
+  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;
+}
+
+/**
+ * Load build state from disk
+ */
+export function load(projectRoot: string): BuildState | null {
+  const statePath = getStatePath(projectRoot);
+
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(statePath, 'utf-8');
+    return JSON.parse(content) as BuildState;
+  } catch (error) {
+    console.error(`Failed to load build state: ${(error as Error).message}`);
+    return null;
+  }
+}
+
+/**
+ * Save build state to disk
+ */
+export function save(projectRoot: string, state: BuildState): boolean {
+  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 as Error).message}`);
+    return false;
+  }
+}
+
+/**
+ * Update phase progress based on task statuses
+ */
+function updatePhaseProgress(state: BuildState, phaseName: string): void {
+  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;
+  const phase = state.phases[phaseName];
+
+  if (!phase) return;
+
+  if (progress === 0) {
+    phase.status = 'pending';
+  } else if (progress === 1) {
+    phase.status = 'completed';
+  } else {
+    phase.status = 'in_progress';
+  }
+
+  phase.tasks = phaseTasks.map(t => ({
+    id: t.id,
+    title: t.title,
+    status: t.status
+  }));
+}
+
+/**
+ * Update MVP criteria progress
+ */
+function updateMvpProgress(state: BuildState): void {
+  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' as const : 'pending' as const
+    };
+  });
+
+  // Check if all MVP criteria are met
+  state.mvpCriteria.allCriteriaMet =
+    state.mvpCriteria.completionPercentage === 100 ||
+    state.mvpCriteria.features.every(f => f.status === 'completed');
+}
+
+/**
+ * Update task progress
+ */
+export function updateProgress(
+  projectRoot: string,
+  taskId: string,
+  status: Task['status'],
+  details: UpdateDetails = {}
+): BuildState | null {
+  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;
+
+  const task = state.implementationQueue[taskIndex];
+  if (!task) return null;
+
+  // Update task status
+  task.status = status;
+  task.updatedAt = new Date().toISOString();
+
+  // Add any additional details
+  if (details.completedAt) {
+    task.completedAt = details.completedAt;
+  }
+  if (details.error) {
+    task.error = details.error;
+  }
+  if (details.output) {
+    task.lastOutput = details.output;
+  }
+
+  // Update phase progress
+  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;
+}
+
+/**
+ * Get the next pending task
+ */
+export function getNextTask(projectRoot: string): Task | null {
+  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
+ */
+export function addTask(projectRoot: string, task: Partial<Task>): BuildState | null {
+  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
+  const newTask: Task = {
+    id: task.id,
+    title: task.title || 'Untitled Task',
+    description: task.description,
+    source: task.source,
+    sourceSection: task.sourceSection,
+    phase: task.phase,
+    status: task.status || 'pending',
+    acceptanceCriteria: task.acceptanceCriteria,
+    dependencies: task.dependencies,
+    estimatedComplexity: task.estimatedComplexity,
+    createdAt: new Date().toISOString()
+  };
+
+  state.implementationQueue.push(newTask);
+  save(projectRoot, state);
+
+  return state;
+}
+
+/**
+ * Set tasks in batch
+ */
+export function setTasks(projectRoot: string, tasks: Partial<Task>[]): BuildState | null {
+  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 || 'Untitled Task',
+    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
+ */
+export function setMvpFeatures(projectRoot: string, features: (string | { name: string })[]): BuildState | null {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.mvpCriteria.features = features.map(f => ({
+    name: typeof f === 'string' ? f : f.name,
+    status: 'pending' as const
+  }));
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Update loop session
+ */
+export function updateSession(projectRoot: string, updates: Partial<LoopSession>): BuildState | null {
+  const state = load(projectRoot);
+  if (!state) return null;
+
+  state.loopSession = {
+    ...state.loopSession,
+    ...updates
+  };
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Pause the build loop
+ */
+export function pause(projectRoot: string): BuildState | null {
+  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
+ */
+export function resume(projectRoot: string): BuildState | null {
+  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.getTime() - pausedAt.getTime()) > 3600000) { // 1 hour
+    state.loopSession.sessionId = generateSessionId();
+  }
+
+  save(projectRoot, state);
+  return state;
+}
+
+/**
+ * Mark build as complete
+ */
+export function complete(projectRoot: string): BuildState | null {
+  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
+ */
+export function fail(projectRoot: string, reason: string): BuildState | null {
+  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
+ */
+export function getStats(projectRoot: string): BuildStats | null {
+  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
+ */
+export function reset(projectRoot: string): BuildState {
+  const state = load(projectRoot);
+  const projectName = state?.projectName || 'Project';
+
+  return initialize(projectRoot, { projectName });
+}