@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/build-orchestrator.js

@@ -0,0 +1,480 @@
+/**
+ * Bootspring Build Orchestrator
+ *
+ * Main orchestration engine for the autonomous build loop.
+ * Coordinates between seed documents, task extraction, planning,
+ * and the continuous build loop.
+ *
+ * @package bootspring
+ * @module core/build-orchestrator
+ */
+
+const fs = require('fs');
+const path = require('path');
+const buildState = require('./build-state');
+const taskExtractor = require('./task-extractor');
+const planningTemplate = require('../generators/templates/build-planning.template');
+
+/**
+ * Build Orchestrator Class
+ */
+class BuildOrchestrator {
+  /**
+   * Create a new orchestrator instance
+   * @param {string} projectRoot - Project root path
+   * @param {object} options - Options
+   */
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.options = options;
+    this.state = null;
+    this.docs = {};
+  }
+
+  /**
+   * Initialize the build orchestrator
+   * Parses docs, extracts tasks, generates planning folder, initializes state
+   * @returns {object} Initialization result
+   */
+  async initialize() {
+    const result = {
+      success: false,
+      state: null,
+      files: {},
+      taskCount: 0,
+      error: null
+    };
+
+    try {
+      // Step 1: Load seed documents
+      this.docs = this.loadSeedDocuments();
+
+      if (Object.keys(this.docs).length === 0) {
+        result.error = 'No seed documents found. Run "bootspring preseed start" first.';
+        return result;
+      }
+
+      // Step 2: Extract project name
+      const projectName = this.extractProjectName();
+
+      // Step 3: Extract tasks from documents
+      const extracted = taskExtractor.extractFromDocs(this.docs, {
+        projectName
+      });
+
+      if (extracted.tasks.length === 0) {
+        result.error = 'No tasks could be extracted from seed documents.';
+        return result;
+      }
+
+      // Step 4: Initialize build state
+      this.state = buildState.initialize(this.projectRoot, {
+        projectName,
+        preseedDocs: Object.keys(this.docs),
+        seedSource: this.getSeedSource()
+      });
+
+      // Step 5: Set tasks in state
+      buildState.setTasks(this.projectRoot, extracted.tasks);
+
+      // Step 6: Set MVP features/criteria
+      if (extracted.mvpCriteria.length > 0) {
+        buildState.setMvpFeatures(this.projectRoot, extracted.mvpCriteria);
+      }
+
+      // Step 7: Generate planning artifacts
+      result.files = planningTemplate.generateAll(
+        this.projectRoot,
+        this.docs,
+        extracted.tasks,
+        {
+          projectName,
+          currentPhase: 'foundation'
+        }
+      );
+
+      // Step 8: Update state with planning info
+      this.state = buildState.load(this.projectRoot);
+      this.state.status = 'pending';
+      this.state.currentPhase = 'foundation';
+      buildState.save(this.projectRoot, this.state);
+
+      result.success = true;
+      result.state = this.state;
+      result.taskCount = extracted.tasks.length;
+
+      return result;
+
+    } catch (error) {
+      result.error = error.message;
+      return result;
+    }
+  }
+
+  /**
+   * Load seed documents from preseed directory and SEED.md
+   * @returns {object} Document contents
+   */
+  loadSeedDocuments() {
+    const docs = {};
+
+    // Load from preseed directory
+    const preseedDir = path.join(this.projectRoot, '.bootspring', 'preseed');
+    if (fs.existsSync(preseedDir)) {
+      const validDocs = [
+        'VISION.md', 'AUDIENCE.md', 'MARKET.md', 'COMPETITORS.md',
+        'BUSINESS_MODEL.md', 'PRD.md', 'TECHNICAL_SPEC.md', 'ROADMAP.md'
+      ];
+
+      for (const file of validDocs) {
+        const filePath = path.join(preseedDir, file);
+        if (fs.existsSync(filePath)) {
+          const docName = file.replace('.md', '');
+          docs[docName] = fs.readFileSync(filePath, 'utf-8');
+        }
+      }
+    }
+
+    // Load SEED.md if exists
+    const seedPath = path.join(this.projectRoot, 'SEED.md');
+    if (fs.existsSync(seedPath)) {
+      docs.SEED = fs.readFileSync(seedPath, 'utf-8');
+    }
+
+    return docs;
+  }
+
+  /**
+   * Get the seed source type
+   * @returns {string} Source type
+   */
+  getSeedSource() {
+    const hasPreseed = fs.existsSync(path.join(this.projectRoot, '.bootspring', 'preseed'));
+    const hasSeed = fs.existsSync(path.join(this.projectRoot, 'SEED.md'));
+
+    if (hasPreseed && hasSeed) return 'preseed+seed';
+    if (hasPreseed) return 'preseed';
+    if (hasSeed) return 'seed';
+    return 'none';
+  }
+
+  /**
+   * Extract project name from documents
+   * @returns {string} Project name
+   */
+  extractProjectName() {
+    // Try VISION first
+    const visionDoc = this.docs.VISION || this.docs.vision;
+    if (visionDoc) {
+      const nameMatch = visionDoc.match(/\*{0,2}Application\s+Name:?\*{0,2}\s*(.+)/i);
+      if (nameMatch) return nameMatch[1].trim();
+
+      const titleMatch = visionDoc.match(/^#\s+([^—\-\n]+)/m);
+      if (titleMatch) return titleMatch[1].trim();
+    }
+
+    // Try SEED
+    const seedDoc = this.docs.SEED || this.docs.seed;
+    if (seedDoc) {
+      const titleMatch = seedDoc.match(/^#\s+([^—\-\n]+)/m);
+      if (titleMatch) return titleMatch[1].trim();
+    }
+
+    // Try PRD
+    const prdDoc = this.docs.PRD || this.docs.prd;
+    if (prdDoc) {
+      const titleMatch = prdDoc.match(/^#\s+([^—\-\n]+)/m);
+      if (titleMatch) return titleMatch[1].trim();
+    }
+
+    return 'Project';
+  }
+
+  /**
+   * Get the next task to execute
+   * @returns {object|null} Next task or null
+   */
+  getNextTask() {
+    return buildState.getNextTask(this.projectRoot);
+  }
+
+  /**
+   * Get all tasks for the loop
+   * @returns {array} Tasks formatted for loop execution
+   */
+  getTasksForLoop() {
+    const state = buildState.load(this.projectRoot);
+    if (!state) return [];
+
+    return state.implementationQueue.map(task => ({
+      id: task.id,
+      title: task.title,
+      description: task.description || '',
+      status: task.status,
+      acceptance: task.acceptanceCriteria || [],
+      phase: task.phase,
+      source: task.source
+    }));
+  }
+
+  /**
+   * Complete a task
+   * @param {string} taskId - Task ID
+   * @param {object} details - Completion details
+   * @returns {object|null} Updated state
+   */
+  completeTask(taskId, details = {}) {
+    return buildState.updateProgress(this.projectRoot, taskId, 'completed', {
+      completedAt: new Date().toISOString(),
+      ...details
+    });
+  }
+
+  /**
+   * Mark task as blocked
+   * @param {string} taskId - Task ID
+   * @param {string} reason - Block reason
+   * @returns {object|null} Updated state
+   */
+  blockTask(taskId, reason) {
+    return buildState.updateProgress(this.projectRoot, taskId, 'blocked', {
+      error: reason
+    });
+  }
+
+  /**
+   * Skip a task
+   * @param {string} taskId - Task ID
+   * @param {string} reason - Skip reason
+   * @returns {object|null} Updated state
+   */
+  skipTask(taskId, reason) {
+    return buildState.updateProgress(this.projectRoot, taskId, 'skipped', {
+      error: reason
+    });
+  }
+
+  /**
+   * Start a task
+   * @param {string} taskId - Task ID
+   * @returns {object|null} Updated state
+   */
+  startTask(taskId) {
+    return buildState.updateProgress(this.projectRoot, taskId, 'in_progress');
+  }
+
+  /**
+   * Check if MVP criteria are met
+   * @returns {boolean} Whether MVP is complete
+   */
+  isMvpComplete() {
+    const state = buildState.load(this.projectRoot);
+    if (!state) return false;
+
+    return state.mvpCriteria.allCriteriaMet;
+  }
+
+  /**
+   * Check if should exit the loop
+   * @returns {object} Exit check result
+   */
+  shouldExit() {
+    const state = buildState.load(this.projectRoot);
+    if (!state) return { shouldExit: true, reason: 'no_state' };
+
+    // Check MVP completion
+    if (this.isMvpComplete()) {
+      return { shouldExit: true, reason: 'mvp_complete' };
+    }
+
+    // Check max iterations
+    if (state.loopSession.currentIteration >= state.loopSession.maxIterations) {
+      return { shouldExit: true, reason: 'max_iterations' };
+    }
+
+    // Check if all tasks are done
+    const pendingTasks = state.implementationQueue.filter(
+      t => t.status === 'pending' || t.status === 'in_progress'
+    );
+    if (pendingTasks.length === 0) {
+      return { shouldExit: true, reason: 'all_tasks_complete' };
+    }
+
+    // Check if paused
+    if (state.status === 'paused') {
+      return { shouldExit: true, reason: 'paused' };
+    }
+
+    // Check if failed
+    if (state.status === 'failed') {
+      return { shouldExit: true, reason: 'failed' };
+    }
+
+    return { shouldExit: false };
+  }
+
+  /**
+   * Generate a prompt for a specific task
+   * @param {object} task - Task to generate prompt for
+   * @returns {string} Task prompt
+   */
+  generateTaskPrompt(task) {
+    const state = buildState.load(this.projectRoot);
+    const projectName = state?.projectName || 'Project';
+
+    let prompt = `# Bootspring Build Task
+
+You are executing a single task from the autonomous build loop.
+
+## Project: ${projectName}
+
+## Current Task
+
+**ID:** ${task.id}
+**Title:** ${task.title}
+${task.description ? `**Description:** ${task.description}` : ''}
+**Phase:** ${task.phase || 'MVP'}
+**Source:** ${task.source || 'Manual'} ${task.sourceSection ? `(${task.sourceSection})` : ''}
+**Complexity:** ${task.estimatedComplexity || 'medium'}
+
+`;
+
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+      prompt += `## Acceptance Criteria
+
+${task.acceptanceCriteria.map(c => `- [ ] ${c}`).join('\n')}
+
+`;
+    }
+
+    prompt += `## Rules
+
+1. **Focus on THIS task only** - Do not work on other tasks
+2. **Read CLAUDE.md first** - Understand project patterns
+3. **Run quality checks** - \`npm run lint && npm run test\`
+4. **Commit when done** - Use conventional commits (feat:, fix:, etc.)
+5. **Update BUILD_STATE.json** - Mark task as completed
+
+## Exit Signals
+
+When you complete the task successfully, output:
+\`\`\`
+<loop-status>TASK_COMPLETE</loop-status>
+\`\`\`
+
+If you cannot complete the task, output:
+\`\`\`
+<loop-status>TASK_BLOCKED</loop-status>
+Reason: [explanation]
+\`\`\`
+
+## Session Info
+
+- Session: ${state?.loopSession?.sessionId || 'N/A'}
+- Iteration: ${(state?.loopSession?.currentIteration || 0) + 1} of ${state?.loopSession?.maxIterations || 50}
+- Timestamp: ${new Date().toISOString()}
+
+## Context Files
+
+Read these files for context:
+- \`CLAUDE.md\` - Project patterns and decisions
+- \`planning/CONTEXT.md\` - Build context
+- \`planning/BUILD_STATE.json\` - Current state
+
+Begin working on the task now.
+`;
+
+    return prompt;
+  }
+
+  /**
+   * Get build statistics
+   * @returns {object} Build statistics
+   */
+  getStats() {
+    return buildState.getStats(this.projectRoot);
+  }
+
+  /**
+   * Pause the build loop
+   * @returns {object|null} Updated state
+   */
+  pause() {
+    return buildState.pause(this.projectRoot);
+  }
+
+  /**
+   * Resume the build loop
+   * @returns {object|null} Updated state
+   */
+  resume() {
+    return buildState.resume(this.projectRoot);
+  }
+
+  /**
+   * Mark build as complete
+   * @returns {object|null} Updated state
+   */
+  complete() {
+    return buildState.complete(this.projectRoot);
+  }
+
+  /**
+   * Mark build as failed
+   * @param {string} reason - Failure reason
+   * @returns {object|null} Updated state
+   */
+  fail(reason) {
+    return buildState.fail(this.projectRoot, reason);
+  }
+
+  /**
+   * Reset the build state
+   * @returns {object} Fresh state
+   */
+  reset() {
+    return buildState.reset(this.projectRoot);
+  }
+
+  /**
+   * Update planning files from current state
+   */
+  updatePlanningFiles() {
+    const state = buildState.load(this.projectRoot);
+    if (state) {
+      planningTemplate.updateFromState(this.projectRoot, state);
+    }
+  }
+
+  /**
+   * Check if build state exists
+   * @returns {boolean}
+   */
+  hasState() {
+    return buildState.exists(this.projectRoot);
+  }
+
+  /**
+   * Load existing state
+   * @returns {object|null}
+   */
+  loadState() {
+    this.state = buildState.load(this.projectRoot);
+    return this.state;
+  }
+}
+
+/**
+ * Create a new build orchestrator
+ * @param {string} projectRoot - Project root path
+ * @param {object} options - Options
+ * @returns {BuildOrchestrator}
+ */
+function create(projectRoot, options = {}) {
+  return new BuildOrchestrator(projectRoot, options);
+}
+
+module.exports = {
+  BuildOrchestrator,
+  create
+};