brain-dev 0.1.0

package/bin/lib/adr.cjs

@@ -0,0 +1,283 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { atomicWriteSync } = require('./state.cjs');
+
+/**
+ * Get the next available ADR ID by scanning existing ADR files.
+ * @param {string} adrsDir - Path to .brain/adrs/ directory
+ * @returns {number} Next available ID (1 if empty or dir missing)
+ */
+function getNextId(adrsDir) {
+  if (!fs.existsSync(adrsDir)) return 1;
+
+  const files = fs.readdirSync(adrsDir).filter(f => /^ADR-\d+\.md$/.test(f));
+  if (files.length === 0) return 1;
+
+  const ids = files.map(f => parseInt(f.match(/ADR-(\d+)\.md/)[1], 10));
+  return Math.max(...ids) + 1;
+}
+
+/**
+ * Create a new Architecture Decision Record.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {object} options
+ * @param {string} options.title - ADR title
+ * @param {string} options.context - Why this decision came up
+ * @param {string} options.decision - What was chosen
+ * @param {string} options.alternatives - What was rejected
+ * @param {string} options.consequences - Impact of the decision
+ * @param {string} options.phase - Phase number
+ * @param {string} options.plan - Plan number
+ * @param {string} [options.deciders] - Who made the decision
+ * @returns {{ id: string, path: string }}
+ */
+function createADR(brainDir, options) {
+  const adrsDir = path.join(brainDir, 'adrs');
+  fs.mkdirSync(adrsDir, { recursive: true });
+
+  const nextId = getNextId(adrsDir);
+  const paddedId = String(nextId).padStart(3, '0');
+  const adrId = `ADR-${paddedId}`;
+  const filePath = path.join(adrsDir, `${adrId}.md`);
+  const date = new Date().toISOString().slice(0, 10);
+
+  const content = [
+    '---',
+    `id: ${nextId}`,
+    `date: "${date}"`,
+    'status: proposed',
+    `phase: "${options.phase}"`,
+    `plan: "${options.plan}"`,
+    `deciders: "${options.deciders || 'unknown'}"`,
+    'supersedes: null',
+    'superseded_by: null',
+    '---',
+    '',
+    `# ${adrId}: ${options.title}`,
+    '',
+    '## Context',
+    '',
+    options.context || '',
+    '',
+    '## Decision',
+    '',
+    options.decision || '',
+    '',
+    '## Alternatives',
+    '',
+    options.alternatives || '',
+    '',
+    '## Consequences',
+    '',
+    options.consequences || '',
+    ''
+  ].join('\n');
+
+  atomicWriteSync(filePath, content);
+
+  return { id: adrId, path: filePath };
+}
+
+/**
+ * Parse YAML-ish frontmatter from ADR file content.
+ * @param {string} content - File content
+ * @returns {object} Parsed frontmatter fields
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    // Remove quotes (preserve as string if originally quoted)
+    let wasQuoted = false;
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+      wasQuoted = true;
+    }
+    if (value === 'null') value = null;
+    else if (!wasQuoted && /^\d+$/.test(value)) value = parseInt(value, 10);
+    fm[key] = value;
+  }
+  return fm;
+}
+
+/**
+ * Extract title from first # heading in ADR content.
+ * @param {string} content - File content
+ * @returns {string} Title
+ */
+function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1] : 'Untitled';
+}
+
+/**
+ * List all ADRs, optionally filtered by phase.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {object} [options]
+ * @param {string} [options.phase] - Filter by phase
+ * @returns {Array<{id: number, date: string, status: string, title: string, path: string}>}
+ */
+function listADRs(brainDir, options) {
+  const adrsDir = path.join(brainDir, 'adrs');
+  if (!fs.existsSync(adrsDir)) return [];
+
+  const files = fs.readdirSync(adrsDir).filter(f => /^ADR-\d+\.md$/.test(f));
+  if (files.length === 0) return [];
+
+  const adrs = files.map(f => {
+    const filePath = path.join(adrsDir, f);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fm = parseFrontmatter(content);
+    return {
+      id: fm.id || parseInt(f.match(/ADR-(\d+)\.md/)[1], 10),
+      date: fm.date || '',
+      status: fm.status || 'unknown',
+      title: extractTitle(content),
+      phase: fm.phase || '',
+      path: filePath
+    };
+  });
+
+  // Sort by ID ascending
+  adrs.sort((a, b) => a.id - b.id);
+
+  // Filter by phase if provided
+  if (options && options.phase) {
+    return adrs.filter(a => String(a.phase) === String(options.phase));
+  }
+
+  return adrs;
+}
+
+/**
+ * Search ADRs by keyword (case-insensitive).
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {string} keyword - Search term
+ * @returns {Array<{id: number, date: string, status: string, title: string, path: string}>}
+ */
+function searchADRs(brainDir, keyword) {
+  const adrsDir = path.join(brainDir, 'adrs');
+  if (!fs.existsSync(adrsDir)) return [];
+
+  const files = fs.readdirSync(adrsDir).filter(f => /^ADR-\d+\.md$/.test(f));
+  const lowerKeyword = keyword.toLowerCase();
+
+  const results = [];
+  for (const f of files) {
+    const filePath = path.join(adrsDir, f);
+    const content = fs.readFileSync(filePath, 'utf8');
+    if (content.toLowerCase().includes(lowerKeyword)) {
+      const fm = parseFrontmatter(content);
+      results.push({
+        id: fm.id || parseInt(f.match(/ADR-(\d+)\.md/)[1], 10),
+        date: fm.date || '',
+        status: fm.status || 'unknown',
+        title: extractTitle(content),
+        phase: fm.phase || '',
+        path: filePath
+      });
+    }
+  }
+
+  results.sort((a, b) => a.id - b.id);
+  return results;
+}
+
+/**
+ * Update the status of an existing ADR.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {number} adrId - ADR numeric ID
+ * @param {string} newStatus - New status (proposed, accepted, deprecated, superseded)
+ * @param {object} [opts]
+ * @param {number} [opts.superseded_by] - ID of superseding ADR (when status is 'superseded')
+ * @param {number} [opts.supersedes] - ID of superseded ADR (when this is the new ADR)
+ */
+function updateADRStatus(brainDir, adrId, newStatus, opts) {
+  const adrsDir = path.join(brainDir, 'adrs');
+  const paddedId = String(adrId).padStart(3, '0');
+  const filePath = path.join(adrsDir, `ADR-${paddedId}.md`);
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`ADR-${paddedId} not found`);
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8');
+
+  // Update status
+  content = content.replace(/^status:\s*.+$/m, `status: ${newStatus}`);
+
+  // Update superseded_by if provided
+  if (opts && opts.superseded_by != null) {
+    content = content.replace(/^superseded_by:\s*.+$/m, `superseded_by: ${opts.superseded_by}`);
+  }
+
+  // Update supersedes if provided
+  if (opts && opts.supersedes != null) {
+    content = content.replace(/^supersedes:\s*.+$/m, `supersedes: ${opts.supersedes}`);
+  }
+
+  atomicWriteSync(filePath, content);
+}
+
+/**
+ * ADR-worthy detection keywords.
+ */
+const ADR_KEYWORDS = [
+  'chose',
+  'decided to use',
+  'instead of',
+  'alternative was',
+  'trade-off',
+  'trade off',
+  'because of',
+  'rejected approach'
+];
+
+/**
+ * ADR-worthy context indicators.
+ */
+const ADR_CONTEXTS = [
+  'dependency',
+  'dependencies',
+  'pattern',
+  'architecture',
+  'architectural',
+  'api contract',
+  'module structure',
+  'performance',
+  'simplicity'
+];
+
+/**
+ * Check if text contains an ADR-worthy decision.
+ * Requires BOTH a keyword match AND a context indicator match.
+ * @param {string} text - Text to check
+ * @returns {boolean}
+ */
+function isADRWorthy(text) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+
+  const hasKeyword = ADR_KEYWORDS.some(kw => lower.includes(kw));
+  const hasContext = ADR_CONTEXTS.some(ctx => lower.includes(ctx));
+
+  return hasKeyword && hasContext;
+}
+
+module.exports = {
+  getNextId,
+  createADR,
+  listADRs,
+  searchADRs,
+  updateADRStatus,
+  isADRWorthy
+};

package/bin/lib/agents.cjs

@@ -0,0 +1,152 @@
+'use strict';
+
+/**
+ * Agent registry for brain orchestration.
+ * Defines the 7 core agents and their metadata.
+ * Constant registry with discovery and validation functions.
+ */
+
+const MAX_AGENTS = 8;
+
+const AGENTS = {
+  researcher: {
+    template: 'researcher',
+    inputs: ['phase_context', 'project_info', 'focus_areas'],
+    outputs: ['RESEARCH.md'],
+    model: 'inherit',
+    description: 'Researches phase domain: codebase patterns, library docs, risks, and recommendations'
+  },
+  planner: {
+    template: 'planner',
+    inputs: ['phase_context', 'research', 'context_decisions'],
+    outputs: ['PLAN-*.md'],
+    model: 'inherit',
+    description: 'Creates execution plans with tasks, verification criteria, and dependency graphs'
+  },
+  'plan-checker': {
+    template: 'plan-checker',
+    modes: { advocate: { template: 'advocate', max_iterations: 2 } },
+    inputs: ['plan_content', 'phase_requirements', 'context_decisions'],
+    outputs: ['checker_result'],
+    model: 'inherit',
+    description: 'Validates plans across 8 dimensions: coverage, completeness, dependencies, ownership, scope, verification, context, testing'
+  },
+  executor: {
+    template: 'executor',
+    inputs: ['plan_content', 'summary_path'],
+    outputs: ['SUMMARY-*.md'],
+    model: 'inherit',
+    description: 'Executes plan tasks with per-task commits, deviation handling, and checkpoint protocol'
+  },
+  verifier: {
+    template: 'verifier',
+    inputs: ['must_haves', 'summaries'],
+    outputs: ['VERIFICATION.md'],
+    model: 'inherit',
+    description: 'Verifies plan outputs against must_haves with 3-level depth checks'
+  },
+  debugger: {
+    template: 'debugger',
+    inputs: ['error_context', 'task_context', 'attempted_fixes'],
+    outputs: ['debug_session'],
+    model: 'inherit',
+    description: 'Diagnoses and fixes failures using 4-phase method with hypothesis tracking'
+  },
+  synthesizer: {
+    template: 'synthesis',
+    inputs: ['research_dir'],
+    outputs: ['SUMMARY.md'],
+    model: 'inherit',
+    description: 'Combines findings from parallel research agents into a unified SUMMARY.md'
+  },
+  mapper: {
+    template: 'mapper',
+    inputs: ['focus', 'codebase_root'],
+    outputs: ['codebase/*.md'],
+    model: 'inherit',
+    description: 'Maps codebase across focus areas producing structured Markdown documentation',
+    focus: ['tech', 'arch', 'quality', 'concerns']
+  }
+};
+
+/**
+ * Get agent metadata by name.
+ * @param {string} name - Agent name
+ * @returns {object} Agent metadata with name field added
+ * @throws {Error} If agent name is unknown
+ */
+function getAgent(name) {
+  const agent = AGENTS[name];
+  if (!agent) {
+    throw new Error(`Unknown agent: ${name}`);
+  }
+  return { name, ...agent };
+}
+
+/**
+ * List all registered agent names.
+ * @returns {string[]}
+ */
+function listAgents() {
+  return Object.keys(AGENTS);
+}
+
+/**
+ * Validate that agent count does not exceed MAX_AGENTS.
+ * @returns {boolean}
+ */
+function validateAgentCount() {
+  return Object.keys(AGENTS).length <= MAX_AGENTS;
+}
+
+/**
+ * Resolve the model for an agent using 4-level priority:
+ * 1. Per-agent override (brainConfig.agents.models[agentName])
+ * 2. Active profile preset (custom profiles > built-in PROFILES)
+ * 3. Global default (brainConfig.agents.model)
+ * 4. Fallback to 'inherit' (use session model)
+ *
+ * @param {string} agentName - Agent name
+ * @param {object|null} brainConfig - brain.json config object
+ * @returns {string} Resolved model identifier
+ */
+function resolveModel(agentName, brainConfig) {
+  if (!brainConfig || !brainConfig.agents) {
+    return 'inherit';
+  }
+
+  const agentsCfg = brainConfig.agents;
+
+  // Priority 1: per-agent override
+  if (agentsCfg.models && agentsCfg.models[agentName]) {
+    return agentsCfg.models[agentName];
+  }
+
+  // Priority 2: active profile preset
+  if (agentsCfg.profile) {
+    const { PROFILES } = require('./config.cjs');
+    // Check custom profiles first (user-defined), then built-in
+    const profile = (agentsCfg.profiles && agentsCfg.profiles[agentsCfg.profile])
+      || PROFILES[agentsCfg.profile];
+    if (profile && profile.models && profile.models[agentName]) {
+      return profile.models[agentName];
+    }
+  }
+
+  // Priority 3: global default
+  if (agentsCfg.model) {
+    return agentsCfg.model;
+  }
+
+  // Priority 4: inherit session model
+  return 'inherit';
+}
+
+module.exports = {
+  AGENTS,
+  MAX_AGENTS,
+  getAgent,
+  listAgents,
+  validateAgentCount,
+  resolveModel
+};

package/bin/lib/anti-patterns.cjs

@@ -0,0 +1,183 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Anti-pattern detection patterns for JS/CJS source files.
+ * Each pattern has a name, regex, and severity level.
+ */
+const JS_PATTERNS = [
+  {
+    name: 'Empty Function Body',
+    regex: /function\s+\w+\s*\([^)]*\)\s*\{\s*\}/,
+    severity: 'block'
+  },
+  {
+    name: 'TODO/FIXME Comment',
+    regex: /\/\/\s*(TODO|FIXME|HACK)\b/,
+    severity: 'block'
+  },
+  {
+    name: 'Log-Only Error Handler',
+    regex: /catch\s*\([^)]*\)\s*\{\s*console\.(log|error|warn)\([^)]*\);\s*\}/,
+    severity: 'warning'
+  },
+  {
+    name: 'Not Implemented',
+    regex: /throw\s+new\s+Error\s*\(\s*['"]not\s+implemented['"]\s*\)/i,
+    severity: 'block'
+  },
+  {
+    name: 'Empty Return',
+    regex: /return\s+(null|undefined|\[\s*\]|\{\s*\})\s*;/,
+    severity: 'warning'
+  },
+  {
+    name: 'Placeholder Content',
+    regex: /['"`](placeholder|coming soon|lorem ipsum|sample data|test data|dummy)['"`]/i,
+    severity: 'warning'
+  }
+];
+
+/**
+ * Anti-pattern detection patterns for test files.
+ */
+const TEST_PATTERNS = [
+  {
+    name: 'Skipped Test',
+    regex: /(?:it\.skip|xit|xdescribe|describe\.skip)\s*\(/,
+    severity: 'block'
+  },
+  {
+    name: 'Empty Test Body',
+    regex: /it\s*\(\s*['"][^'"]*['"]\s*,\s*\(\s*\)\s*=>\s*\{\s*\}\s*\)/,
+    severity: 'block'
+  }
+];
+
+/**
+ * Anti-pattern detection patterns for Markdown files.
+ */
+const MD_PATTERNS = [
+  {
+    name: 'TBD/TODO Placeholder',
+    regex: /^(TBD|TODO)\s*$/m,
+    severity: 'block'
+  },
+  {
+    name: 'Empty Section',
+    regex: /^##\s+.+\n\s*\n(?=##\s|$)/m,
+    severity: 'warning'
+  }
+];
+
+/**
+ * Get the appropriate pattern set for a file path.
+ * @param {string} filePath - File path to determine patterns for
+ * @returns {Array} Pattern array for the file type
+ */
+function getPatterns(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const base = path.basename(filePath).toLowerCase();
+
+  // Test files get test patterns (check before JS patterns)
+  if (base.includes('.test.') || base.includes('.spec.')) {
+    return TEST_PATTERNS;
+  }
+
+  // JS/CJS files
+  if (ext === '.js' || ext === '.cjs' || ext === '.mjs') {
+    return JS_PATTERNS;
+  }
+
+  // Markdown files
+  if (ext === '.md') {
+    return MD_PATTERNS;
+  }
+
+  return [];
+}
+
+/**
+ * Scan content string for anti-patterns.
+ * @param {string} content - Content to scan
+ * @param {string} [filePath] - Optional file path for pattern selection and findings context
+ * @returns {{ findings: Array<{ name: string, severity: string, file?: string, line?: number, match: string }> }}
+ */
+function scanContent(content, filePath) {
+  const findings = [];
+  const patterns = filePath ? getPatterns(filePath) : JS_PATTERNS;
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern.regex);
+    if (match) {
+      const finding = {
+        name: pattern.name,
+        severity: pattern.severity,
+        match: match[0]
+      };
+      if (filePath) {
+        finding.file = filePath;
+      }
+      // Calculate line number
+      if (content.includes('\n')) {
+        const beforeMatch = content.slice(0, match.index);
+        finding.line = (beforeMatch.match(/\n/g) || []).length + 1;
+      }
+      findings.push(finding);
+    }
+  }
+
+  return { findings };
+}
+
+/**
+ * Scan files for anti-patterns.
+ * @param {string} rootDir - Root directory
+ * @param {object} [options] - Scan options
+ * @param {string[]} [options.files] - Array of relative file paths to scan (phase-scoped)
+ * @returns {{ findings: object[], blockers: object[], warnings: object[] }}
+ */
+function scanFiles(rootDir, options = {}) {
+  const filesToScan = options.files || [];
+
+  const allFindings = [];
+  const blockers = [];
+  const warnings = [];
+
+  for (const relPath of filesToScan) {
+    const fullPath = path.join(rootDir, relPath);
+
+    let content;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      // Skip files that don't exist or can't be read
+      continue;
+    }
+
+    const result = scanContent(content, relPath);
+
+    for (const finding of result.findings) {
+      allFindings.push(finding);
+
+      if (finding.severity === 'block') {
+        blockers.push(finding);
+      } else {
+        warnings.push(finding);
+      }
+    }
+  }
+
+  return { findings: allFindings, blockers, warnings };
+}
+
+module.exports = {
+  JS_PATTERNS,
+  TEST_PATTERNS,
+  MD_PATTERNS,
+  scanContent,
+  scanFiles,
+  getPatterns
+};