brain-dev 0.1.2 → 0.3.0

package/bin/lib/commands/recover.cjs

@@ -0,0 +1,155 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+const path = require('node:path');
+const { output, error, success, prefix } = require('../core.cjs');
+const { readState } = require('../state.cjs');
+const { readLock, isLockStale } = require('../lock.cjs');
+const recovery = require('../recovery.cjs');
+
+/**
+ * Recover command handler.
+ * Detects and recovers from crashed/interrupted executions.
+ *
+ * Flags:
+ *   --fix       Attempt auto-resume from last checkpoint
+ *   --rollback  Revert state to pre-execution
+ *   --dismiss   Clear stale lock without recovery
+ *   --json      Force JSON output
+ *
+ * Default (no flags): check mode — show recovery briefing
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir override)
+ * @returns {object} Result object
+ */
+async function run(args = [], opts = {}) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      fix: { type: 'boolean', default: false },
+      rollback: { type: 'boolean', default: false },
+      dismiss: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false }
+    },
+    strict: false
+  });
+
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+
+  // Validate brainDir exists
+  const state = readState(brainDir);
+  if (!state) {
+    const result = { action: 'recover', status: 'error', message: 'No .brain directory or brain.json found' };
+    if (values.json) {
+      console.log(JSON.stringify(result));
+    } else {
+      error('No .brain directory found. Run `brain init` first.');
+    }
+    return result;
+  }
+
+  // Mutually exclusive flags check
+  const flagCount = [values.fix, values.rollback, values.dismiss].filter(Boolean).length;
+  if (flagCount > 1) {
+    const result = { action: 'recover', status: 'error', message: 'Use only one of --fix, --rollback, or --dismiss' };
+    if (values.json) {
+      console.log(JSON.stringify(result));
+    } else {
+      error('Use only one of --fix, --rollback, or --dismiss.');
+    }
+    return result;
+  }
+
+  // Dismiss mode: clear stale lock without recovery
+  if (values.dismiss) {
+    const result = recovery.recover(brainDir, { dismiss: true });
+    const resultObj = { action: 'recover', status: result.recovered ? 'dismissed' : 'no-action', ...result };
+
+    if (values.json) {
+      console.log(JSON.stringify(resultObj, null, 2));
+    } else if (result.recovered) {
+      success('Stale lock dismissed. No state changes made.');
+    } else {
+      output(resultObj, prefix(result.briefing));
+    }
+    return resultObj;
+  }
+
+  // Fix mode: auto-resume recovery
+  if (values.fix) {
+    const result = recovery.recover(brainDir, { fix: true });
+    const resultObj = { action: 'recover', status: result.recovered ? 'fixed' : 'no-action', ...result };
+
+    if (values.json) {
+      console.log(JSON.stringify(resultObj, null, 2));
+    } else if (result.recovered) {
+      // Show briefing then success
+      console.log('');
+      console.log(result.briefing);
+      console.log('');
+      success(`Recovery complete. ${result.nextAction}`);
+      if (result.result?.changes) {
+        for (const change of result.result.changes) {
+          console.log(prefix(`  - ${change}`));
+        }
+      }
+    } else {
+      output(resultObj, prefix(result.briefing));
+    }
+    return resultObj;
+  }
+
+  // Rollback mode: revert state
+  if (values.rollback) {
+    const result = recovery.recover(brainDir, { rollback: true });
+    const resultObj = { action: 'recover', status: result.recovered ? 'rolled-back' : 'no-action', ...result };
+
+    if (values.json) {
+      console.log(JSON.stringify(resultObj, null, 2));
+    } else if (result.recovered) {
+      console.log('');
+      console.log(result.briefing);
+      console.log('');
+      success(`Rollback complete. ${result.nextAction}`);
+      if (result.result?.changes) {
+        for (const change of result.result.changes) {
+          console.log(prefix(`  - ${change}`));
+        }
+      }
+    } else {
+      output(resultObj, prefix(result.briefing));
+    }
+    return resultObj;
+  }
+
+  // Default: check mode — show briefing without making changes
+  const result = recovery.recover(brainDir, {});
+  const resultObj = { action: 'recover', status: result.mode, ...result };
+
+  if (values.json) {
+    console.log(JSON.stringify(resultObj, null, 2));
+  } else {
+    console.log('');
+    console.log(result.briefing);
+    console.log('');
+
+    if (result.mode === 'clean' || result.mode === 'active' || result.mode === 'none') {
+      success(result.briefing);
+    } else {
+      // There is something to recover
+      const recommendation = result.result?.recommended;
+      if (recommendation === 'auto-resume') {
+        console.log(prefix('Suggested: brain recover --fix'));
+      } else if (recommendation === 'rollback') {
+        console.log(prefix('Suggested: brain recover --rollback'));
+      } else {
+        console.log(prefix('Review the briefing above and choose: --fix, --rollback, or --dismiss'));
+      }
+    }
+  }
+
+  return resultObj;
+}
+
+module.exports = { run };

package/bin/lib/commands/verify.cjs

@@ -9,6 +9,7 @@ const { logEvent } = require('../logger.cjs');
 const { output, error, success } = require('../core.cjs');
 const antiPatterns = require('../anti-patterns.cjs');
 const { buildDebuggerSpawnInstructions } = require('./execute.cjs');
+const { isPathWithinRoot } = require('../security.cjs');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -72,9 +73,10 @@ function extractMustHaves(content) {
  * Extract phase-modified file paths from PLAN and SUMMARY frontmatter.
  * @param {string[]} planFiles - Full paths to plan files
  * @param {string[]} summaryFiles - Full paths to summary files
+ * @param {string} [rootDir] - Project root directory for path traversal guard
  * @returns {string[]} Deduplicated array of file paths
  */
-function extractPhaseFiles(planFiles, summaryFiles) {
+function extractPhaseFiles(planFiles, summaryFiles, rootDir) {
   const files = new Set();
 
   for (const planPath of planFiles) {
@@ -90,7 +92,10 @@ function extractPhaseFiles(planFiles, summaryFiles) {
         for (const line of lines) {
           const itemMatch = line.match(/^\s+-\s+(.+)/);
           if (itemMatch) {
-            files.add(itemMatch[1].trim());
+            const filePath = itemMatch[1].trim();
+            // Guard against path traversal
+            if (rootDir && !isPathWithinRoot(filePath, rootDir)) continue;
+            files.add(filePath);
           } else if (line.trim() && !line.match(/^\s+-/) && !line.match(/^\s*$/)) {
             break; // Hit next YAML key
           }
@@ -117,7 +122,10 @@ function extractPhaseFiles(planFiles, summaryFiles) {
         for (const line of lines) {
           const itemMatch = line.match(/^\s+-\s+(.+)/);
           if (itemMatch) {
-            files.add(itemMatch[1].trim().replace(/^["']|["']$/g, ''));
+            const filePath = itemMatch[1].trim().replace(/^["']|["']$/g, '');
+            // Guard against path traversal
+            if (rootDir && !isPathWithinRoot(filePath, rootDir)) continue;
+            files.add(filePath);
           } else if (line.trim() && !line.match(/^\s+-/) && !line.match(/^\s*$/) && !line.match(/^\s+\w+:/)) {
             break;
           }
@@ -213,11 +221,11 @@ async function run(args = [], opts = {}) {
   const summaryPaths = summaryFiles.map(f => path.join(phaseDir, f));
 
   // Extract phase-modified files for anti-pattern scanning
+  const projectDir = path.dirname(brainDir);
   const planFullPaths = planFiles.map(f => path.join(phaseDir, f));
-  const phaseFiles = extractPhaseFiles(planFullPaths, summaryPaths);
+  const phaseFiles = extractPhaseFiles(planFullPaths, summaryPaths, projectDir);
 
   // Run anti-pattern scan on phase files
-  const projectDir = path.dirname(brainDir);
   const apResults = antiPatterns.scanFiles(projectDir, { files: phaseFiles });
 
   // Build Nyquist section based on state config
@@ -400,6 +408,8 @@ function handleSaveResults(args, saveIdx, brainDir, state) {
 
   // Update state
   state.phase.status = results.passed ? 'verified' : 'verification-failed';
+  // Clear execution timer after verification completes
+  state.phase.execution_started_at = null;
   writeState(brainDir, state);
 
   const msg = results.passed

package/bin/lib/commands.cjs

@@ -65,6 +65,15 @@ const COMMANDS = [
     needsState: true,
     args: '  --full            Enable plan checking + verification\n  --execute --task N  Execute task N\n  --verify --task N   Verify task N (--full only)\n  --complete --task N Complete and commit task N'
   },
+  {
+    name: 'new-task',
+    description: 'Create a significant task with full pipeline',
+    usage: 'brain-dev new-task "description" [--research] [--light]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --research     Include light research phase\n  --light        Skip discuss and verify (fast mode)\n  --continue     Resume the current active task\n  --list         List all tasks\n  --promote N    Promote task N to roadmap phase'
+  },
   {
     name: 'execute',
     description: 'Execute plans with verification',
@@ -148,6 +157,15 @@ const COMMANDS = [
     needsState: true,
     args: '  --session <id>  Resume a specific session by timestamp ID'
   },
+  {
+    name: 'recover',
+    description: 'Detect and recover from crashes',
+    usage: 'brain-dev recover [--fix|--rollback|--dismiss]',
+    group: 'Session',
+    implemented: true,
+    needsState: true,
+    args: '  --fix          Auto-resume from last checkpoint\n  --rollback     Revert to pre-crash state\n  --dismiss      Clear stale lock, move on'
+  },
   // Tools
   {
     name: 'storm',
@@ -158,6 +176,15 @@ const COMMANDS = [
     needsState: true,
     args: '  <topic>       Topic to brainstorm\n  --stop         Stop running server\n  --port <n>     Custom port number\n  --finalize     Generate output.md from fragments'
   },
+  {
+    name: 'dashboard',
+    description: 'Live monitoring dashboard',
+    usage: 'brain-dev dashboard [--browser|--stop|--status]',
+    group: 'Tools',
+    implemented: true,
+    needsState: true,
+    args: '  --browser      Open web dashboard in browser\n  --stop         Stop running dashboard server\n  --status       Show dashboard URL if running'
+  },
   {
     name: 'adr',
     description: 'Manage architecture decision records',

package/bin/lib/config.cjs

@@ -7,10 +7,10 @@ const { readState, writeState, atomicWriteSync } = require('./state.cjs');
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
-const CATEGORIES = ['Workflow', 'Models', 'Enforcement', 'Monitoring', 'Complexity', 'Storm', 'ADR'];
+const CATEGORIES = ['Workflow', 'Models', 'Enforcement', 'Monitoring', 'Complexity', 'Storm', 'ADR', 'Budget', 'Timeout', 'Dashboard'];
 
 const SCHEMA = {
-  'mode': { type: 'enum', values: ['interactive', 'yolo'], default: 'interactive', category: 'Workflow', description: 'Execution mode preset (sets multiple flags)' },
+  'mode': { type: 'enum', values: ['interactive', 'yolo', 'auto'], default: 'interactive', category: 'Workflow', description: 'Execution mode preset (sets multiple flags)' },
   'depth': { type: 'enum', values: ['shallow', 'standard', 'deep'], default: 'deep', category: 'Workflow', description: 'Verification depth (shallow=L1, standard=L1+L2, deep=L1+L2+L3)' },
   'workflow.parallelization': { type: 'boolean', default: false, category: 'Workflow', description: 'Enable parallel wave execution' },
   'workflow.mapper_parallelization': { type: 'boolean', default: true, category: 'Workflow', description: 'Enable parallel codebase mapping' },
@@ -29,6 +29,21 @@ const SCHEMA = {
   'storm.auto_open': { type: 'boolean', default: true, category: 'Storm', description: 'Auto-open browser on storm start', local: true },
   'adr.auto_create': { type: 'boolean', default: true, category: 'ADR', description: 'Auto-create ADRs for significant decisions' },
   'adr.status_lifecycle': { type: 'boolean', default: true, category: 'ADR', description: 'Enable ADR status transitions' },
+  'budget.ceiling_usd': { type: 'number', default: null, min: 0, category: 'Budget', description: 'Maximum spend in USD (null = unlimited)' },
+  'budget.warn_at_pct': { type: 'number', default: 80, min: 10, max: 100, category: 'Budget', description: 'Warn when this % of ceiling is reached' },
+  'budget.mode': { type: 'enum', values: ['warn', 'pause', 'hard-stop'], default: 'warn', category: 'Budget', description: 'Action when budget exceeded' },
+  'timeout.enabled': { type: 'boolean', default: true, category: 'Timeout', description: 'Enable stuck detection and timeouts' },
+  'timeout.soft': { type: 'number', default: 20, min: 5, max: 120, category: 'Timeout', description: 'Soft timeout in minutes (warning)' },
+  'timeout.idle': { type: 'number', default: 5, min: 1, max: 30, category: 'Timeout', description: 'Idle timeout in minutes (no progress)' },
+  'timeout.hard': { type: 'number', default: 45, min: 10, max: 180, category: 'Timeout', description: 'Hard timeout in minutes (force wrap-up)' },
+  'timeout.max_retries': { type: 'number', default: 1, min: 0, max: 3, category: 'Timeout', description: 'Max resume attempts after stuck timeout' },
+  'dashboard.port': { type: 'number', default: 3457, min: 1024, max: 65535, category: 'Dashboard', description: 'Dashboard server port' },
+  'dashboard.auto_open': { type: 'boolean', default: true, category: 'Dashboard', description: 'Auto-open browser on dashboard start' },
+  'auto.max_errors': { type: 'number', default: 3, min: 1, max: 10, category: 'Workflow', description: 'Max consecutive errors before auto mode pauses' },
+  'auto.max_phases': { type: 'number', default: 0, min: 0, max: 100, category: 'Workflow', description: 'Max phases to process in auto mode (0 = unlimited)' },
+  'auto.skip_discuss': { type: 'boolean', default: false, category: 'Workflow', description: 'Skip discuss step in auto mode when CONTEXT.md exists' },
+  'auto.max_operations': { type: 'number', default: 100, min: 10, max: 1000, category: 'Workflow', description: 'Max operations (commits/writes) per auto session' },
+  'auto.max_duration_minutes': { type: 'number', default: 120, min: 10, max: 480, category: 'Workflow', description: 'Max auto session duration in minutes' },
 };
 
 const PROFILES = {
@@ -69,6 +84,12 @@ const MODE_PRESETS = {
     'workflow.auto_recover': false,
     'workflow.parallelization': false,
     'enforcement.level': 'hard'
+  },
+  auto: {
+    'workflow.advocate': false,
+    'workflow.auto_recover': true,
+    'workflow.parallelization': false,
+    'enforcement.level': 'balanced'
   }
 };