brain-dev 0.1.0

package/bin/lib/commands.cjs

@@ -0,0 +1,263 @@
+'use strict';
+
+const path = require('node:path');
+
+/**
+ * Command registry for all brain-dev CLI commands.
+ * Each entry defines name, description, usage, group, implemented status,
+ * whether it needs .brain/ state, and optional args documentation.
+ */
+const COMMANDS = [
+  // Setup
+  {
+    name: 'init',
+    description: 'Initialize brain in current project',
+    usage: 'brain-dev init [--force]',
+    group: 'Setup',
+    implemented: true,
+    needsState: false,
+    args: '  --force  Wipe and recreate existing .brain/ directory'
+  },
+  {
+    name: 'new-project',
+    description: 'Start a new project with guided questioning',
+    usage: 'brain-dev new-project [--answers <json>] [--synthesize] [--generate-roadmap] [--finalize]',
+    group: 'Setup',
+    implemented: true,
+    needsState: true,
+    args: '  --answers <json>      Provide user answers as JSON\n  --synthesize           Spawn synthesis agent\n  --generate-roadmap     Generate REQUIREMENTS.md and ROADMAP.md\n  --finalize             Finalize project setup\n  --project-name <name>  Project name (used with --finalize)'
+  },
+  {
+    name: 'help',
+    description: 'Show all available commands',
+    usage: 'brain-dev help [command]',
+    group: 'Setup',
+    implemented: true,
+    needsState: false,
+    args: '  [command]  Show detailed help for a specific command'
+  },
+
+  // Lifecycle
+  {
+    name: 'discuss',
+    description: 'Capture decisions before planning',
+    usage: 'brain-dev discuss [--phase <n>] [--save --decisions <json>]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --phase <n>            Target phase to discuss (default: current)\n  --save                 Save decisions to CONTEXT.md\n  --decisions <json>     Decisions JSON (used with --save)'
+  },
+  {
+    name: 'plan',
+    description: 'Create execution plans',
+    usage: 'brain-dev plan [--phase <n>] [--all]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --phase <n>  Target phase number to plan\n  --all        Plan all unplanned phases sequentially'
+  },
+  {
+    name: 'quick',
+    description: 'Quick task without full phase ceremony',
+    usage: 'brain-dev quick [--full] <description>',
+    group: 'Lifecycle',
+    implemented: true,
+    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: 'execute',
+    description: 'Execute plans with verification',
+    usage: 'brain-dev execute [--plan <id>]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --plan <id>  Specific plan to execute (e.g. 01-02)'
+  },
+  {
+    name: 'verify',
+    description: 'Run verification checks on completed work',
+    usage: 'brain-dev verify [--phase <n>]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --phase <n>  Phase to verify'
+  },
+  {
+    name: 'complete',
+    description: 'Mark phase or milestone as complete',
+    usage: 'brain-dev complete [--phase <n>]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --phase <n>  Phase to mark complete'
+  },
+  {
+    name: 'map',
+    description: 'Map codebase structure and patterns',
+    usage: 'brain-dev map [--focus tech|arch|quality|concerns]',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  --focus <area>  Focus on specific area: tech, arch, quality, or concerns'
+  },
+  {
+    name: 'phase',
+    description: 'Manage project phases (add, remove, reorder)',
+    usage: 'brain-dev phase <add|insert|remove|reorder|list>',
+    group: 'Lifecycle',
+    implemented: true,
+    needsState: true,
+    args: '  add       Add a new phase\n  insert    Insert decimal phase (e.g. 2.1)\n  remove    Remove a phase\n  reorder   Reorder phases\n  list      Show all phases (default)'
+  },
+
+  // Session
+  {
+    name: 'status',
+    description: 'Show project state (used by SessionStart hook)',
+    usage: 'brain-dev status [--json]',
+    group: 'Session',
+    implemented: true,
+    needsState: true,
+    args: '  --json  Output raw JSON (for hooks and piping)'
+  },
+  {
+    name: 'progress',
+    description: 'Show current progress and status',
+    usage: 'brain-dev progress [--verbose]',
+    group: 'Session',
+    implemented: true,
+    needsState: true,
+    args: '  --verbose  Show full dashboard with all phases'
+  },
+  {
+    name: 'pause',
+    description: 'Save session state for later resumption',
+    usage: 'brain-dev pause [--note <msg>]',
+    group: 'Session',
+    implemented: true,
+    needsState: true,
+    args: '  --note <msg>  Add a note about where you stopped'
+  },
+  {
+    name: 'resume',
+    description: 'Resume from last saved session state',
+    usage: 'brain-dev resume [--session <id>]',
+    group: 'Session',
+    implemented: true,
+    needsState: true,
+    args: '  --session <id>  Resume a specific session by timestamp ID'
+  },
+  // Tools
+  {
+    name: 'storm',
+    description: 'Launch visual brainstorming server',
+    usage: 'brain-dev storm <topic> [--stop] [--port <n>] [--finalize]',
+    group: 'Tools',
+    implemented: true,
+    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: 'adr',
+    description: 'Manage architecture decision records',
+    usage: 'brain-dev adr <create|list|search> [options]',
+    group: 'Tools',
+    implemented: true,
+    needsState: true,
+    args: '  create              Create new ADR interactively\n  list [--phase <n>]   List ADRs (optionally filtered by phase)\n  search <term>        Search ADR content'
+  },
+
+  // Config
+  {
+    name: 'config',
+    description: 'Manage brain configuration',
+    usage: 'brain-dev config [set|get|list|reset|docs|export|import] [args] [--global]',
+    group: 'Config',
+    implemented: true,
+    needsState: true,
+    args: '  set <key> <value>     Set a configuration value\n  get <key>             Get a configuration value\n  list [--category X]   List all settings grouped by category\n  reset [key|category]  Reset to defaults\n  docs                  Show full schema reference\n  export                Export config as portable JSON\n  import <file.json>    Import config from file\n  --global              Target ~/.brain/defaults.json'
+  },
+
+  // Meta
+  {
+    name: 'health',
+    description: 'Run health diagnostics and auto-repair safe issues',
+    usage: 'brain-dev health [--fix] [--quick] [--json]',
+    group: 'Meta',
+    implemented: true,
+    needsState: false,
+    args: '  --fix    Enable aggressive repair of hooks and templates\n  --quick  Run safe checks only (used by bootstrap)\n  --json   Force JSON output'
+  },
+  {
+    name: 'version',
+    description: 'Show brain-dev version',
+    usage: 'brain-dev version',
+    group: 'Meta',
+    implemented: true,
+    needsState: false,
+    args: ''
+  }
+];
+
+/**
+ * Group order for display purposes.
+ */
+const GROUP_ORDER = ['Setup', 'Lifecycle', 'Session', 'Tools', 'Config', 'Meta'];
+
+/**
+ * Get formatted help text for a single command.
+ * @param {string} name - Command name
+ * @returns {string|null} Formatted help text, or null if command not found
+ */
+function getCommandHelp(name) {
+  const cmd = COMMANDS.find(c => c.name === name);
+  if (!cmd) return null;
+
+  let text = `${cmd.name} -- ${cmd.description}\n\nUsage: ${cmd.usage}`;
+  if (cmd.args) {
+    text += `\n\nArguments:\n${cmd.args}`;
+  }
+  return text;
+}
+
+/**
+ * Generate full help text with commands grouped by lifecycle stage.
+ * @returns {string} Formatted help text
+ */
+function showHelp() {
+  const pkg = require(path.join(__dirname, '..', '..', 'package.json'));
+  const lines = [`[brain] v${pkg.version} - AI development workflow orchestrator`, ''];
+
+  for (const group of GROUP_ORDER) {
+    const cmds = COMMANDS.filter(c => c.group === group);
+    lines.push(`${group}:`);
+    for (const cmd of cmds) {
+      const padded = cmd.name.padEnd(14);
+      lines.push(`  ${padded}${cmd.description}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+/**
+ * Show detailed help for a single unimplemented command.
+ * Includes command name, description, usage, args, and status.
+ * @param {string} name - Command name
+ * @returns {string} Formatted help text
+ */
+function showCommandHelp(name) {
+  const cmd = COMMANDS.find(c => c.name === name);
+  if (!cmd) return null;
+
+  let text = `[brain] /brain:${cmd.name} -- ${cmd.description}\n\nUsage: ${cmd.usage}`;
+  if (cmd.args) {
+    text += `\n${cmd.args}`;
+  }
+  text += '\n\nStatus: Coming soon.';
+  return text;
+}
+
+module.exports = { COMMANDS, getCommandHelp, showHelp, showCommandHelp };

package/bin/lib/complexity.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * Complexity budget scoring module.
+ * Provides weighted scoring for plan complexity, budget checking,
+ * and estimation from plan frontmatter.
+ *
+ * No external dependencies.
+ */
+
+const WEIGHTS = {
+  fileCount: 1,
+  functionCount: 1.5,
+  dependencyDepth: 2,
+  nestingDepth: 2,
+  linesOfCode: 0.5
+};
+
+const BUDGETS = {
+  scaffolding: 80,
+  standard: 60,
+  production: 40
+};
+
+/**
+ * Calculate a weighted complexity score from metrics.
+ * @param {object} metrics - { fileCount, functionCount, dependencyDepth, nestingDepth, linesOfCode }
+ * @returns {number} Rounded weighted sum
+ */
+function calculateScore(metrics) {
+  if (!metrics || typeof metrics !== 'object') return 0;
+
+  let sum = 0;
+  for (const [key, weight] of Object.entries(WEIGHTS)) {
+    const value = metrics[key];
+    if (typeof value === 'number' && !Number.isNaN(value)) {
+      sum += value * weight;
+    }
+  }
+  return Math.round(sum);
+}
+
+/**
+ * Check whether a score exceeds a budget.
+ * @param {number} score - Calculated complexity score
+ * @param {number} budget - Budget threshold
+ * @returns {object} { exceeded, score, budget, remaining|overage }
+ */
+function checkBudget(score, budget) {
+  if (score > budget) {
+    return { exceeded: true, score, budget, overage: score - budget };
+  }
+  return { exceeded: false, score, budget, remaining: budget - score };
+}
+
+/**
+ * Generate a per-metric breakdown showing how each metric contributes.
+ * @param {object} metrics - Same shape as calculateScore input
+ * @returns {object} Per-metric { raw, weight, contribution }
+ */
+function generateBreakdown(metrics) {
+  if (!metrics || typeof metrics !== 'object') return {};
+
+  const result = {};
+  for (const [key, weight] of Object.entries(WEIGHTS)) {
+    const raw = typeof metrics[key] === 'number' ? metrics[key] : 0;
+    result[key] = {
+      raw,
+      weight,
+      contribution: raw * weight
+    };
+  }
+  return result;
+}
+
+/**
+ * Get the default complexity budget for a phase type.
+ * @param {string} phaseType - 'scaffolding' | 'standard' | 'production'
+ * @returns {number} Budget value
+ */
+function getDefaultBudget(phaseType) {
+  return BUDGETS[phaseType] ?? 60;
+}
+
+/**
+ * Estimate complexity metrics from plan content (frontmatter).
+ * Parses files_modified count and task count to produce heuristic estimates.
+ * @param {string} planContent - Raw plan file content
+ * @returns {object} { metrics, score }
+ */
+function estimateFromPlan(planContent) {
+  if (!planContent || typeof planContent !== 'string') {
+    return { metrics: { fileCount: 0, functionCount: 0, dependencyDepth: 2, nestingDepth: 2, linesOfCode: 0 }, score: 0 };
+  }
+
+  // Extract frontmatter
+  const fmMatch = planContent.match(/^---\n([\s\S]*?)\n---/);
+  const frontmatter = fmMatch ? fmMatch[1] : '';
+
+  // Count files_modified entries (lines starting with "  - " after files_modified:)
+  let fileCount = 0;
+  const fmLines = frontmatter.split('\n');
+  let inFilesModified = false;
+  for (const line of fmLines) {
+    if (line.startsWith('files_modified:')) {
+      inFilesModified = true;
+      continue;
+    }
+    if (inFilesModified) {
+      if (line.match(/^\s+-\s+/)) {
+        fileCount++;
+      } else {
+        inFilesModified = false;
+      }
+    }
+  }
+
+  const metrics = {
+    fileCount,
+    functionCount: fileCount * 3,
+    dependencyDepth: 2,
+    nestingDepth: 2,
+    linesOfCode: fileCount * 80
+  };
+
+  return {
+    metrics,
+    score: calculateScore(metrics)
+  };
+}
+
+module.exports = {
+  calculateScore,
+  checkBudget,
+  generateBreakdown,
+  getDefaultBudget,
+  estimateFromPlan
+};

package/bin/lib/complexity.test.cjs

@@ -0,0 +1,108 @@
+'use strict';
+
+const assert = require('node:assert');
+
+// Tests for complexity.cjs
+// RED phase: these should fail until implementation exists
+
+const c = require('./complexity.cjs');
+
+// calculateScore tests
+{
+  const score = c.calculateScore({
+    fileCount: 5,
+    functionCount: 10,
+    dependencyDepth: 3,
+    nestingDepth: 4,
+    linesOfCode: 200
+  });
+  assert.strictEqual(score, 134, `calculateScore full metrics: expected 134, got ${score}`);
+}
+
+{
+  const score = c.calculateScore({});
+  assert.strictEqual(score, 0, `calculateScore empty: expected 0, got ${score}`);
+}
+
+{
+  const score = c.calculateScore({ fileCount: 10 });
+  assert.strictEqual(score, 10, `calculateScore single metric: expected 10, got ${score}`);
+}
+
+// getDefaultBudget tests
+{
+  assert.strictEqual(c.getDefaultBudget('scaffolding'), 80);
+  assert.strictEqual(c.getDefaultBudget('standard'), 60);
+  assert.strictEqual(c.getDefaultBudget('production'), 40);
+  assert.strictEqual(c.getDefaultBudget('unknown'), 60);
+  assert.strictEqual(c.getDefaultBudget(), 60);
+}
+
+// checkBudget tests
+{
+  const under = c.checkBudget(50, 60);
+  assert.strictEqual(under.exceeded, false);
+  assert.strictEqual(under.score, 50);
+  assert.strictEqual(under.budget, 60);
+  assert.strictEqual(under.remaining, 10);
+  assert.strictEqual('overage' in under, false);
+}
+
+{
+  const over = c.checkBudget(70, 60);
+  assert.strictEqual(over.exceeded, true);
+  assert.strictEqual(over.score, 70);
+  assert.strictEqual(over.budget, 60);
+  assert.strictEqual(over.overage, 10);
+  assert.strictEqual('remaining' in over, false);
+}
+
+{
+  const exact = c.checkBudget(60, 60);
+  assert.strictEqual(exact.exceeded, false);
+  assert.strictEqual(exact.remaining, 0);
+}
+
+// generateBreakdown tests
+{
+  const breakdown = c.generateBreakdown({
+    fileCount: 5,
+    functionCount: 10,
+    dependencyDepth: 3,
+    nestingDepth: 4,
+    linesOfCode: 200
+  });
+  assert.strictEqual(breakdown.fileCount.raw, 5);
+  assert.strictEqual(breakdown.fileCount.weight, 1);
+  assert.strictEqual(breakdown.fileCount.contribution, 5);
+  assert.strictEqual(breakdown.functionCount.contribution, 15);
+  assert.strictEqual(breakdown.linesOfCode.contribution, 100);
+}
+
+// estimateFromPlan tests
+{
+  const planContent = `---
+phase: 01-foundation
+plan: 01
+files_modified:
+  - src/a.js
+  - src/b.js
+  - src/c.js
+---
+
+<tasks>
+<task type="auto">Task 1</task>
+<task type="auto">Task 2</task>
+</tasks>`;
+
+  const est = c.estimateFromPlan(planContent);
+  assert.strictEqual(est.metrics.fileCount, 3);
+  assert.strictEqual(est.metrics.functionCount, 9); // 3 * 3
+  assert.strictEqual(est.metrics.dependencyDepth, 2);
+  assert.strictEqual(est.metrics.nestingDepth, 2);
+  assert.strictEqual(est.metrics.linesOfCode, 240); // 3 * 80
+  assert.strictEqual(typeof est.score, 'number');
+  assert.ok(est.score > 0);
+}
+
+console.log('All complexity tests passed');