brain-dev 0.1.1 → 0.2.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/update.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState, migrateState } = require('../state.cjs');
+const { detectPlatform } = require('../platform.cjs');
+const { packagePath, registerClaudeHooks, registerAgents, registerCommands, cleanupLegacySkills } = require('../init.cjs');
+const { output, error, success, prefix } = require('../core.cjs');
+
+/**
+ * Copy hook scripts from package to .brain/hooks/.
+ * Preserves executable permissions.
+ * @param {string} brainDir
+ */
+function copyHooks(brainDir) {
+  const hooksDir = path.join(brainDir, 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  const hookFiles = ['bootstrap.sh', 'statusline.sh', 'post-tool-use.sh'];
+  for (const file of hookFiles) {
+    const src = packagePath('hooks', file);
+    if (fs.existsSync(src)) {
+      const dest = path.join(hooksDir, file);
+      fs.copyFileSync(src, dest);
+      try { fs.chmodSync(dest, 0o755); } catch { /* skip on unsupported FS */ }
+    }
+  }
+}
+
+/**
+ * Update .brain/.gitignore with current patterns.
+ * @param {string} brainDir
+ */
+function updateGitignore(brainDir) {
+  const content = [
+    '*.tmp',
+    '*.lock',
+    'storm/fragments/',
+    'storm/events.jsonl',
+    ''
+  ].join('\n');
+  fs.writeFileSync(path.join(brainDir, '.gitignore'), content, 'utf8');
+}
+
+/**
+ * Run the update command.
+ * Updates tool files (hooks, agents, commands) while preserving project state.
+ *
+ * brain-dev update          → Update tool files + migrate state
+ * brain-dev update --check  → Only check version, don't update
+ *
+ * @param {string[]} args
+ * @param {object} [opts]
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const cwd = opts.cwd || process.cwd();
+
+  // 1. Validate .brain/ exists
+  if (!fs.existsSync(brainDir)) {
+    error("No brain project found. Run 'npx brain-dev init' first.");
+    return { error: 'no-project' };
+  }
+
+  // 2. Read current state
+  const state = readState(brainDir);
+  if (!state) {
+    error("Corrupted brain.json. Run 'npx brain-dev init --force' to reset.");
+    return { error: 'corrupted-state' };
+  }
+
+  // 3. Get versions
+  const installedVersion = state.version || '0.0.0';
+  const packageVersion = require(path.join(__dirname, '..', '..', '..', 'package.json')).version;
+
+  // --check mode
+  if (args.includes('--check')) {
+    const upToDate = installedVersion === packageVersion;
+    const msg = upToDate
+      ? `brain-dev v${installedVersion} is up to date.`
+      : `Update available: v${installedVersion} → v${packageVersion}. Run: npx brain-dev update`;
+
+    output({
+      action: 'version-check',
+      installed: installedVersion,
+      package: packageVersion,
+      upToDate
+    }, prefix(msg));
+
+    return { action: 'version-check', installed: installedVersion, package: packageVersion, upToDate };
+  }
+
+  // 4. Backup state before update
+  const backupPath = path.join(brainDir, 'brain.json.pre-update');
+  try {
+    fs.copyFileSync(path.join(brainDir, 'brain.json'), backupPath);
+  } catch (e) {
+    error(`Could not backup brain.json: ${e.message}`);
+    return { error: 'backup-failed' };
+  }
+
+  // 5. Ensure required directories exist
+  const requiredDirs = ['hooks', 'debug', 'specs', 'codebase'];
+  for (const dir of requiredDirs) {
+    fs.mkdirSync(path.join(brainDir, dir), { recursive: true });
+  }
+
+  // 6. Update hook scripts
+  copyHooks(brainDir);
+
+  // 7. Platform-specific updates
+  const platform = detectPlatform({ cwd });
+  if (platform === 'claude-code') {
+    registerClaudeHooks(cwd);
+    cleanupLegacySkills(cwd);
+    registerCommands(cwd);
+    registerAgents(cwd);
+  }
+
+  // 8. Migrate state (adds new fields, preserves all existing data)
+  const migrated = migrateState(state);
+  writeState(brainDir, migrated);
+
+  // 9. Update .gitignore
+  updateGitignore(brainDir);
+
+  // 10. Report
+  const isUpgrade = installedVersion !== packageVersion;
+  const msg = isUpgrade
+    ? `Updated brain-dev v${installedVersion} → v${packageVersion}. State preserved. Backup: brain.json.pre-update`
+    : `brain-dev v${packageVersion} tool files refreshed. State preserved.`;
+
+  success(msg);
+
+  const result = {
+    action: 'updated',
+    from: installedVersion,
+    to: packageVersion,
+    backup: backupPath,
+    statePreserved: true,
+    nextAction: '/brain:progress'
+  };
+
+  output(result, '');
+  return result;
+}
+
+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

@@ -148,6 +148,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 +167,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',
@@ -180,6 +198,15 @@ const COMMANDS = [
   },
 
   // Meta
+  {
+    name: 'update',
+    description: 'Update tool files while preserving project state',
+    usage: 'brain-dev update [--check]',
+    group: 'Meta',
+    implemented: true,
+    needsState: false,
+    args: '  --check  Only check for new version, don\'t update'
+  },
   {
     name: 'health',
     description: 'Run health diagnostics and auto-repair safe issues',

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'
   }
 };