brain-dev 0.1.0

package/bin/lib/commands/execute.cjs

@@ -0,0 +1,415 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { loadTemplate, interpolate } = require('../templates.cjs');
+const { getAgent, resolveModel } = require('../agents.cjs');
+const { logEvent } = require('../logger.cjs');
+const { output, error } = require('../core.cjs');
+
+/**
+ * Find a phase directory under .brain/phases/ matching a phase number.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null}
+ */
+function findPhaseDir(brainDir, phaseNumber) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const match = fs.readdirSync(phasesDir).find(d => d.startsWith(`${padded}-`));
+  return match ? path.join(phasesDir, match) : null;
+}
+
+/**
+ * Scan a phase directory for PLAN-*.md files and return them sorted.
+ * @param {string} phaseDir
+ * @returns {Array<{num: number, path: string, hasSummary: boolean}>}
+ */
+function scanPlans(phaseDir) {
+  if (!phaseDir || !fs.existsSync(phaseDir)) return [];
+
+  const files = fs.readdirSync(phaseDir);
+  const plans = [];
+
+  for (const f of files) {
+    const match = f.match(/^PLAN-(\d+)\.md$/);
+    if (match) {
+      const num = parseInt(match[1], 10);
+      const padded = String(num).padStart(2, '0');
+      const hasSummary = files.includes(`SUMMARY-${padded}.md`);
+      plans.push({
+        num,
+        path: path.join(phaseDir, f),
+        hasSummary
+      });
+    }
+  }
+
+  plans.sort((a, b) => a.num - b.num);
+  return plans;
+}
+
+/**
+ * Extract task names from plan content.
+ * @param {string} content - Plan file content
+ * @returns {string[]}
+ */
+function extractTasks(content) {
+  const tasks = [];
+  const taskRegex = /<name>(.*?)<\/name>/g;
+  let match;
+  while ((match = taskRegex.exec(content)) !== null) {
+    tasks.push(match[1].trim());
+  }
+  return tasks;
+}
+
+/**
+ * Spot-check a completed plan by verifying SUMMARY.md content.
+ * Checks key files exist and Self-Check marker is present.
+ *
+ * @param {string} phaseDir - Phase directory path
+ * @param {number} planNum - Plan number
+ * @param {string} summaryPath - Path to SUMMARY.md
+ * @returns {{ passed: boolean, checks: Array<{check: string, file?: string, passed: boolean}> }}
+ */
+function spotCheckPlan(phaseDir, planNum, summaryPath) {
+  const checks = [];
+
+  // Check SUMMARY.md exists
+  if (!fs.existsSync(summaryPath)) {
+    checks.push({ check: 'summary-exists', file: summaryPath, passed: false });
+    return { passed: false, checks };
+  }
+
+  const content = fs.readFileSync(summaryPath, 'utf8');
+  checks.push({ check: 'summary-exists', file: summaryPath, passed: true });
+
+  // Check summary is non-empty
+  const isNonEmpty = content.trim().length > 0;
+  checks.push({ check: 'summary-non-empty', file: summaryPath, passed: isNonEmpty });
+
+  // Parse "Key Files" section and verify each file exists
+  const keyFilesMatch = content.match(/## Key Files[\s\S]*?(?=\n## |\n---|\Z)/);
+  if (keyFilesMatch) {
+    const filePathRegex = /[-*]\s+`?([^\s`]+\.\w+)`?/g;
+    let fileMatch;
+    while ((fileMatch = filePathRegex.exec(keyFilesMatch[0])) !== null) {
+      const filePath = fileMatch[1];
+      // Only check paths that look like real file paths (not headers or descriptions)
+      if (filePath.includes('/') || filePath.includes('.')) {
+        const projectRoot = path.dirname(path.dirname(phaseDir));
+        const fullPath = path.isAbsolute(filePath) ? filePath : path.resolve(projectRoot, filePath);
+        // Guard against path traversal: resolved path must be within project root
+        if (!fullPath.startsWith(projectRoot + path.sep) && fullPath !== projectRoot) {
+          checks.push({ check: 'key-file-exists', file: filePath, passed: false });
+          continue;
+        }
+        const exists = fs.existsSync(fullPath);
+        checks.push({ check: 'key-file-exists', file: filePath, passed: exists });
+      }
+    }
+  }
+
+  // Check for Self-Check: PASSED marker
+  const hasSelfCheck = content.includes('Self-Check: PASSED');
+  checks.push({ check: 'self-check-marker', passed: hasSelfCheck });
+
+  const passed = checks.every(c => c.passed);
+  return { passed, checks };
+}
+
+/**
+ * Build failure handling instructions for the executor prompt.
+ * Describes auto-fix scope, escalation scope, retry behavior, and debugger spawning.
+ *
+ * @returns {string} Markdown text block
+ */
+function buildFailureInstructions() {
+  return [
+    '## Failure Handling',
+    '',
+    '### Auto-fix Scope (retry automatically)',
+    '- Test failures in code you wrote',
+    '- Import errors and missing module references',
+    '- Type mismatches and incorrect function signatures',
+    '- Missing files that should have been created',
+    '- Lint and formatting issues',
+    '',
+    '### Escalate Scope (do NOT retry, output EXECUTION FAILED)',
+    '- API contract changes that affect other plans',
+    '- New dependencies not in the plan',
+    '- Database schema changes',
+    '- Architectural deviations from plan',
+    '- Changes to shared interfaces',
+    '',
+    '### Retry Behavior',
+    '- On failure from auto-fix scope: retry once automatically',
+    '- If auto-retry fails: output EXECUTION FAILED with error context',
+    '- The orchestrator will then spawn a debugger agent with the error context',
+    '',
+    '### Debugger Path',
+    '- Debug sessions are stored at: `.brain/debug/issue-{task-slug}.md`',
+    '- If a debugger agent is spawned, it will receive the error context, task context, and attempted fixes'
+  ].join('\n');
+}
+
+/**
+ * Build debugger spawn instructions by interpolating the debugger template with runtime values.
+ * Called by the orchestrator when auto-retry fails and a debugger agent must be spawned.
+ *
+ * @param {string} taskSlug - Slug for the failed task
+ * @param {string} errorContext - Error message and stack trace
+ * @param {string} taskContext - Description of what the task was doing
+ * @param {string} attemptedFixes - What was already tried
+ * @param {object} [state] - brain.json state for model resolution
+ * @returns {{ action: string, prompt: string, model: string, session_path: string }}
+ */
+function buildDebuggerSpawnInstructions(taskSlug, errorContext, taskContext, attemptedFixes, state) {
+  const tpl = loadTemplate('debugger');
+  const sessionPath = '.brain/debug/issue-' + taskSlug + '.md';
+
+  const interpolatedPrompt = interpolate(tpl, {
+    error_context: errorContext,
+    task_context: taskContext,
+    attempted_fixes: attemptedFixes,
+    debug_session_path: sessionPath
+  });
+
+  return {
+    action: 'spawn-debugger',
+    prompt: interpolatedPrompt,
+    model: resolveModel('debugger', state || null),
+    session_path: sessionPath
+  };
+}
+
+/**
+ * Build checkpoint protocol instructions for the executor prompt.
+ * Describes how to handle non-autonomous plans with checkpoint gates.
+ *
+ * @returns {string} Markdown text block
+ */
+function buildCheckpointInstructions() {
+  return [
+    '## Checkpoint Protocol',
+    '',
+    'For non-autonomous plans, checkpoints pause execution for human input.',
+    '',
+    '### checkpoint:human-verify',
+    'After completing automated work, present what was built for visual/functional verification.',
+    'Output a structured checkpoint block:',
+    '```',
+    '## CHECKPOINT REACHED',
+    'Type: human-verify',
+    'Progress: {completed}/{total} tasks',
+    'What was built: [description]',
+    'Verification steps: [URLs, commands, expected behavior]',
+    '```',
+    '',
+    '### checkpoint:decision',
+    'When implementation requires a choice between options.',
+    'Output a structured checkpoint block with options table.',
+    '',
+    '### checkpoint:human-action',
+    'When a truly unavoidable manual step is needed (email link, 2FA code).',
+    'Output what automation was attempted and the single manual step needed.'
+  ].join('\n');
+}
+
+/**
+ * Run the execute command.
+ *
+ * Default: Find the next unexecuted plan in current phase and output executor instructions.
+ * --plan NN: Target a specific plan.
+ * --phase N: Target a specific phase.
+ * --spot-check NN: Run spot-check verification for plan NN.
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir for testing)
+ * @returns {object} Structured result
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  // Determine phase
+  const phaseIdx = args.indexOf('--phase');
+  const phaseNumber = phaseIdx >= 0
+    ? parseInt(args[phaseIdx + 1], 10)
+    : state.phase.current;
+
+  // Handle --spot-check flag
+  const spotCheckIdx = args.indexOf('--spot-check');
+  if (spotCheckIdx >= 0) {
+    const planNum = parseInt(args[spotCheckIdx + 1], 10);
+    const phaseDir = findPhaseDir(brainDir, phaseNumber);
+    if (!phaseDir) {
+      error(`Phase ${phaseNumber} directory not found.`);
+      return { error: 'phase-not-found' };
+    }
+    const padded = String(planNum).padStart(2, '0');
+    const summaryPath = path.join(phaseDir, `SUMMARY-${padded}.md`);
+    const checkResult = spotCheckPlan(phaseDir, planNum, summaryPath);
+
+    logEvent(brainDir, phaseNumber, {
+      type: 'spot-check',
+      plan: padded,
+      passed: checkResult.passed,
+      checks: checkResult.checks.length
+    });
+
+    const msg = checkResult.passed
+      ? `Spot-check PASSED for plan ${padded}`
+      : `Spot-check FAILED for plan ${padded}`;
+    output({ action: 'spot-check', ...checkResult }, `[brain] ${msg}`);
+    return { action: 'spot-check', ...checkResult };
+  }
+
+  // Find phase directory
+  const phaseDir = findPhaseDir(brainDir, phaseNumber);
+  const plans = scanPlans(phaseDir);
+
+  if (plans.length === 0) {
+    error(`No plans found for phase ${phaseNumber}. Run '/brain:plan' first.`);
+    return { error: 'no-plans' };
+  }
+
+  // Determine which plan to execute
+  const planFlag = args.indexOf('--plan');
+  let targetPlan;
+
+  if (planFlag >= 0) {
+    const planNum = parseInt(args[planFlag + 1], 10);
+    targetPlan = plans.find(p => p.num === planNum);
+    if (!targetPlan) {
+      error(`Plan ${planNum} not found in phase ${phaseNumber}.`);
+      return { error: 'plan-not-found' };
+    }
+  } else {
+    // Find next unexecuted plan (no SUMMARY)
+    targetPlan = plans.find(p => !p.hasSummary);
+  }
+
+  // All plans executed
+  if (!targetPlan) {
+    state.phase.status = 'executed';
+    writeState(brainDir, state);
+    const msg = "All plans executed. Run /brain:verify to check the work.";
+    output({ action: 'all-executed', message: msg, nextAction: '/brain:verify' }, `[brain] ${msg}`);
+    return { action: 'all-executed', message: msg, nextAction: '/brain:verify' };
+  }
+
+  // Read plan content
+  const planContent = fs.readFileSync(targetPlan.path, 'utf8');
+  const tasks = extractTasks(planContent);
+
+  // Build summary path
+  const padded = String(targetPlan.num).padStart(2, '0');
+  const summaryPath = path.join(phaseDir, `SUMMARY-${padded}.md`);
+
+  // Extract phase/plan info from plan frontmatter
+  const phaseMatch = planContent.match(/^phase:\s*(.+)$/m);
+  const planNumMatch = planContent.match(/^plan:\s*(.+)$/m);
+
+  // Check autonomous flag from frontmatter
+  const autonomousMatch = planContent.match(/^autonomous:\s*(true|false)/m);
+  const autonomous = autonomousMatch ? autonomousMatch[1] === 'true' : true;
+
+  // Get executor agent metadata and resolve model
+  const executorAgent = getAgent('executor');
+  const model = resolveModel('executor', state);
+
+  // Log spawn event
+  logEvent(brainDir, phaseNumber, {
+    type: 'spawn',
+    agent: 'executor',
+    plan: padded,
+    autonomous,
+    model
+  });
+
+  // Build failure and checkpoint instructions
+  const failureInstructions = buildFailureInstructions();
+  const checkpointInstructions = autonomous ? '' : buildCheckpointInstructions();
+
+  const spotCheckInstruction = 'After completing all tasks, the orchestrator will verify SUMMARY.md, file existence, and commit count.';
+  const debuggerSpawnInstruction = 'If auto-retry fails, a debugger agent will be spawned with the error context.';
+
+  // Load executor template and interpolate
+  const template = loadTemplate('executor');
+  const prompt = interpolate(template, {
+    plan_path: targetPlan.path,
+    summary_path: summaryPath,
+    plan_content: planContent,
+    phase: phaseMatch ? phaseMatch[1].trim() : String(phaseNumber),
+    plan_number: planNumMatch ? planNumMatch[1].trim() : String(targetPlan.num),
+    subsystem: phaseMatch ? phaseMatch[1].trim() : String(phaseNumber)
+  });
+
+  // Append orchestration instructions to prompt
+  const fullPrompt = [
+    prompt,
+    '',
+    failureInstructions,
+    checkpointInstructions ? '\n' + checkpointInstructions : '',
+    '',
+    `> ${spotCheckInstruction}`,
+    `> ${debuggerSpawnInstruction}`
+  ].join('\n');
+
+  // Update state to executing
+  state.phase.status = 'executing';
+  writeState(brainDir, state);
+
+  // Check auto-recover config
+  const autoRecover = state.workflow?.auto_recover === true;
+
+  const result = {
+    action: 'execute-plan',
+    plan_path: targetPlan.path,
+    summary_path: summaryPath,
+    tasks,
+    prompt: fullPrompt,
+    model,
+    autonomous,
+    spot_check: true,
+    failure_handling: 'retry-then-debugger',
+    auto_recover: autoRecover,
+    debugger_spawn: (taskSlug, errorCtx, taskCtx, attemptedFixes) =>
+      buildDebuggerSpawnInstructions(taskSlug, errorCtx, taskCtx, attemptedFixes, state)
+  };
+
+  // Build verify command with optional --auto-recover
+  const verifyCmd = autoRecover
+    ? `brain-dev verify --phase ${phaseNumber} --auto-recover`
+    : `brain-dev verify --phase ${phaseNumber}`;
+
+  const humanLines = [
+    `[brain] Executor instructions generated for Plan ${padded} in Phase ${phaseNumber}`,
+    `[brain] Plan: ${targetPlan.path}`,
+    `[brain] Summary output: ${summaryPath}`,
+    `[brain] Tasks: ${tasks.length}`,
+    `[brain] Model: ${model}`,
+    `[brain] Autonomous: ${autonomous}`,
+  ];
+  if (autoRecover) {
+    humanLines.push('[brain] Auto-recovery: enabled (verify will auto-diagnose failures)');
+  }
+  humanLines.push(`[brain] Verify with: ${verifyCmd}`);
+  humanLines.push('');
+  humanLines.push(fullPrompt);
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+module.exports = { run, spotCheckPlan, buildDebuggerSpawnInstructions, buildFailureInstructions, buildCheckpointInstructions };

package/bin/lib/commands/health.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+const path = require('node:path');
+const { runChecks, autoRepair, generateReport, quickCheck, FIX_MODE_REPAIRS } = require('../health.cjs');
+const { output, error, success } = require('../core.cjs');
+
+/**
+ * Health command handler.
+ * Runs health diagnostics and auto-repairs safe issues.
+ *
+ * Flags:
+ *   --fix   Enable aggressive repair (FIX_MODE_REPAIRS)
+ *   --quick Run quickCheck only (for bootstrap)
+ *   --json  Force JSON output
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir override)
+ * @returns {object} Result object
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const fix = args.includes('--fix');
+  const quick = args.includes('--quick');
+  const json = args.includes('--json');
+
+  // Quick mode: run safe checks only, output pass/fail
+  if (quick) {
+    const ok = quickCheck(brainDir);
+    const result = { action: 'health-quick', passed: ok };
+    if (json) {
+      console.log(JSON.stringify(result));
+    } else {
+      if (ok) {
+        success('Health: all safe checks passed');
+      } else {
+        error('Health: some safe checks failed (auto-repaired)');
+      }
+    }
+    return result;
+  }
+
+  // Full mode
+  const results = runChecks(brainDir);
+
+  // Auto-repair safe-category failures
+  const repaired = autoRepair(brainDir, results);
+
+  // Aggressive fix mode: run FIX_MODE_REPAIRS for fixable report-category failures
+  const fixRepaired = [];
+  if (fix) {
+    for (const r of results) {
+      if (r.status === 'fail' && r.category === 'report' && FIX_MODE_REPAIRS[r.name]) {
+        try {
+          FIX_MODE_REPAIRS[r.name](brainDir);
+          fixRepaired.push(r.name);
+          r.status = 'repaired';
+        } catch (e) {
+          r.fixError = e.message;
+        }
+      }
+    }
+  }
+
+  const report = generateReport(results);
+  const allPassed = report.failed === 0;
+
+  const resultObj = {
+    action: 'health-check',
+    passed: allPassed,
+    results: report,
+    repaired: [...repaired, ...fixRepaired]
+  };
+
+  if (json) {
+    console.log(JSON.stringify(resultObj, null, 2));
+  } else {
+    // Human-readable table
+    const lines = ['', '[brain] Health Check Results', ''];
+    const nameWidth = Math.max(...report.checks.map(c => c.name.length), 4);
+    lines.push(`  ${'Check'.padEnd(nameWidth)}  Status    Category  Message`);
+    lines.push(`  ${''.padEnd(nameWidth, '-')}  --------  --------  -------`);
+    for (const c of report.checks) {
+      const statusIcon = c.status === 'pass' ? 'PASS' :
+        c.status === 'repaired' ? 'FIXED' : 'FAIL';
+      lines.push(`  ${c.name.padEnd(nameWidth)}  ${statusIcon.padEnd(8)}  ${c.category.padEnd(8)}  ${c.message}`);
+    }
+    lines.push('');
+    lines.push(`  Total: ${report.total}  Passed: ${report.passed}  Failed: ${report.failed}`);
+    if (repaired.length > 0) {
+      lines.push(`  Auto-repaired: ${repaired.join(', ')}`);
+    }
+    if (fixRepaired.length > 0) {
+      lines.push(`  Fix-repaired: ${fixRepaired.join(', ')}`);
+    }
+    lines.push('');
+
+    output(resultObj, lines.join('\n'));
+  }
+
+  return resultObj;
+}
+
+module.exports = { run };

package/bin/lib/commands/map.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getAgent, resolveModel } = require('../agents.cjs');
+const { loadTemplate, interpolate } = require('../templates.cjs');
+const { readState } = require('../state.cjs');
+const { scanFiles } = require('../security.cjs');
+
+/**
+ * Focus area to output file mapping.
+ * Each mapper focus produces specific structured documents.
+ */
+const FOCUS_OUTPUT_MAP = {
+  tech: ['STACK.md', 'INTEGRATIONS.md'],
+  arch: ['ARCHITECTURE.md', 'STRUCTURE.md'],
+  quality: ['CONVENTIONS.md', 'TESTING.md'],
+  concerns: ['CONCERNS.md']
+};
+
+/**
+ * Run the /brain:map command.
+ * Generates mapper agent spawn instructions for codebase analysis.
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options
+ * @param {string} [opts.brainDir] - Path to .brain/ directory
+ * @returns {object} Spawn instructions or error
+ */
+function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    return { error: 'no-state' };
+  }
+
+  const mapper = getAgent('mapper');
+  const codebaseRoot = process.cwd();
+  const outputDir = path.join(codebaseRoot, '.brain', 'codebase');
+
+  // Parse --focus flag
+  let focusAreas = mapper.focus;
+  const focusIdx = args.indexOf('--focus');
+  if (focusIdx !== -1 && args[focusIdx + 1]) {
+    const requested = args[focusIdx + 1];
+    if (!FOCUS_OUTPUT_MAP[requested]) {
+      return { error: 'invalid-focus', message: `Unknown focus: ${requested}. Valid: ${Object.keys(FOCUS_OUTPUT_MAP).join(', ')}` };
+    }
+    focusAreas = [requested];
+  }
+
+  // Load mapper template
+  let template;
+  try {
+    template = loadTemplate(mapper.template);
+  } catch {
+    return { error: 'template-missing', message: `Could not load mapper template` };
+  }
+
+  // Build spawn instructions for each focus area
+  const focusAgents = focusAreas.map(focus => {
+    const prompt = interpolate(template, {
+      focus,
+      codebase_root: codebaseRoot,
+      output_dir: outputDir
+    });
+
+    const model = resolveModel('mapper', state);
+
+    return {
+      focus,
+      prompt,
+      model,
+      output_files: FOCUS_OUTPUT_MAP[focus]
+    };
+  });
+
+  // Read parallelization setting
+  const parallel = state.workflow?.mapper_parallelization ?? true;
+
+  // Run security scan on output directory
+  let scan_results = null;
+  try {
+    if (fs.existsSync(outputDir)) {
+      scan_results = scanFiles(outputDir);
+    }
+  } catch {
+    // Scan failure is non-fatal; leave scan_results as null
+  }
+
+  return {
+    action: 'spawn-mapper',
+    focus_agents: focusAgents,
+    parallel,
+    scan_results,
+    security_note: 'Security scan runs on .brain/codebase/ output directory. On first run scan_results will be null since mapper agents have not produced output yet.'
+  };
+}
+
+module.exports = { run };