brain-dev 0.1.0

package/bin/lib/commands/config.cjs

@@ -0,0 +1,306 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { output, error, success } = require('../core.cjs');
+const {
+  CATEGORIES,
+  SCHEMA,
+  getConfig,
+  setConfig,
+  listConfig,
+  resetConfig,
+  exportConfig,
+  importConfig,
+  getSchema,
+  validateConfig,
+  suggestKey
+} = require('../config.cjs');
+
+/**
+ * Parse flags from args array (--global, --category).
+ * @param {string[]} args
+ * @returns {{ global: boolean, category: string|null, cleanArgs: string[] }}
+ */
+function parseFlags(args) {
+  let global = false;
+  let category = null;
+  const cleanArgs = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--global') {
+      global = true;
+    } else if (args[i] === '--category' && i + 1 < args.length) {
+      category = args[i + 1];
+      i++;
+    } else {
+      cleanArgs.push(args[i]);
+    }
+  }
+
+  return { global, category, cleanArgs };
+}
+
+/**
+ * Show usage help for all subcommands.
+ */
+function showUsage() {
+  const lines = [
+    'Usage: brain-dev config <subcommand> [args] [--global]',
+    '',
+    'Subcommands:',
+    '  set <key> <value>     Set a configuration value',
+    '  get <key>             Get a configuration value',
+    '  list [--category X]   List all settings grouped by category',
+    '  reset [key|category]  Reset to defaults',
+    '  docs                  Show full schema reference',
+    '  export                Export config as portable JSON',
+    '  import <file.json>    Import config from file',
+    '',
+    'Flags:',
+    '  --global              Target ~/.brain/defaults.json',
+    '  --category <name>     Filter by category'
+  ];
+  output(null, lines.join('\n'));
+}
+
+/**
+ * Run the config command.
+ * @param {string[]} args - CLI arguments after 'config'
+ * @param {string} brainDir - Path to .brain/ directory
+ * @returns {object} Structured result
+ */
+async function run(args = [], brainDir) {
+  if (!brainDir) {
+    brainDir = path.join(process.cwd(), '.brain');
+  }
+
+  const { global: isGlobal, category, cleanArgs } = parseFlags(args);
+  const subcommand = cleanArgs[0];
+
+  switch (subcommand) {
+    case undefined: {
+      // Interactive category menu
+      const categorySettings = {};
+      for (const cat of CATEGORIES) {
+        const keys = Object.entries(SCHEMA).filter(([, e]) => e.category === cat);
+        categorySettings[cat] = keys.length;
+      }
+
+      const lines = ['Configuration Categories:', ''];
+      let idx = 1;
+      for (const [cat, count] of Object.entries(categorySettings)) {
+        lines.push(`  ${idx}. ${cat} (${count} settings)`);
+        idx++;
+      }
+      lines.push('');
+      lines.push('Which category would you like to explore?');
+
+      output(null, lines.join('\n'));
+
+      return {
+        action: 'interactive',
+        categories: categorySettings
+      };
+    }
+
+    case 'set': {
+      const key = cleanArgs[1];
+      const value = cleanArgs[2];
+
+      if (!key || value === undefined) {
+        error('Usage: config set <key> <value>');
+        return { action: 'error', error: 'missing-args' };
+      }
+
+      const oldValue = getConfig(brainDir, key, { global: isGlobal });
+
+      try {
+        setConfig(brainDir, key, value, { global: isGlobal });
+      } catch (err) {
+        error(err.message);
+        return { action: 'error', error: err.message };
+      }
+
+      const newValue = getConfig(brainDir, key, { global: isGlobal });
+      success(`${key}: ${JSON.stringify(oldValue)} -> ${JSON.stringify(newValue)}`);
+
+      return {
+        action: 'set',
+        key,
+        oldValue,
+        newValue,
+        global: isGlobal || undefined
+      };
+    }
+
+    case 'get': {
+      const key = cleanArgs[1];
+
+      if (!key) {
+        error('Usage: config get <key>');
+        return { action: 'error', error: 'missing-key' };
+      }
+
+      const value = getConfig(brainDir, key, { global: isGlobal });
+
+      if (value === undefined) {
+        const suggestion = suggestKey(key, Object.keys(SCHEMA));
+        let msg = `Key "${key}" not found.`;
+        if (suggestion) msg += ` Did you mean: "${suggestion}"?`;
+        error(msg);
+        return { action: 'error', error: 'not-found', suggestion };
+      }
+
+      output(null, `${key} = ${JSON.stringify(value)}`);
+
+      return {
+        action: 'get',
+        key,
+        value,
+        global: isGlobal || undefined
+      };
+    }
+
+    case 'list': {
+      const opts = {};
+      if (category) opts.category = category;
+
+      const categories = listConfig(brainDir, opts);
+
+      const lines = [];
+      for (const [cat, entries] of Object.entries(categories)) {
+        lines.push(`[${cat}]`);
+        for (const entry of entries) {
+          const defaultMark = JSON.stringify(entry.value) === JSON.stringify(entry.default) ? '' : ` (default: ${JSON.stringify(entry.default)})`;
+          lines.push(`  ${entry.key} = ${JSON.stringify(entry.value)}${defaultMark}`);
+        }
+        lines.push('');
+      }
+
+      output(null, lines.join('\n'));
+
+      return {
+        action: 'list',
+        categories
+      };
+    }
+
+    case 'reset': {
+      const target = cleanArgs[1];
+
+      try {
+        if (!target) {
+          resetConfig(brainDir);
+          success('All configuration reset to defaults.');
+        } else if (target.includes('.')) {
+          // Key reset
+          resetConfig(brainDir, target);
+          success(`Reset "${target}" to default.`);
+        } else if (CATEGORIES.includes(target)) {
+          // Category reset
+          resetConfig(brainDir, { category: target });
+          success(`Reset all "${target}" settings to defaults.`);
+        } else {
+          // Try as key first, then category
+          const validation = validateConfig(target, '');
+          if (validation.valid || SCHEMA[target]) {
+            resetConfig(brainDir, target);
+            success(`Reset "${target}" to default.`);
+          } else {
+            error(`Unknown key or category: "${target}"`);
+            return { action: 'error', error: 'unknown-target' };
+          }
+        }
+      } catch (err) {
+        error(err.message);
+        return { action: 'error', error: err.message };
+      }
+
+      return { action: 'reset', target: target || 'all' };
+    }
+
+    case 'docs': {
+      const schema = getSchema();
+      const byCat = {};
+      for (const [key, entry] of Object.entries(schema)) {
+        if (!byCat[entry.category]) byCat[entry.category] = [];
+        byCat[entry.category].push({ key, ...entry });
+      }
+
+      const lines = ['# Configuration Reference', ''];
+      for (const [cat, entries] of Object.entries(byCat)) {
+        lines.push(`## ${cat}`, '');
+        lines.push('| Key | Type | Default | Description |');
+        lines.push('|-----|------|---------|-------------|');
+        for (const entry of entries) {
+          const defStr = JSON.stringify(entry.default);
+          const typeStr = entry.type === 'enum' ? `enum(${entry.values.join('/')})` : entry.type;
+          lines.push(`| ${entry.key} | ${typeStr} | ${defStr} | ${entry.description} |`);
+        }
+        lines.push('');
+      }
+
+      output(null, lines.join('\n'));
+
+      return { action: 'docs', schema };
+    }
+
+    case 'export': {
+      try {
+        const json = exportConfig(brainDir);
+        // Raw JSON output for piping
+        console.log(json);
+        return { action: 'export', json };
+      } catch (err) {
+        error(err.message);
+        return { action: 'error', error: err.message };
+      }
+    }
+
+    case 'import': {
+      const filePath = cleanArgs[1];
+
+      if (!filePath) {
+        error('Usage: config import <file.json>');
+        return { action: 'error', error: 'missing-file' };
+      }
+
+      const resolved = path.resolve(filePath);
+      if (!fs.existsSync(resolved)) {
+        error(`File not found: ${resolved}`);
+        return { action: 'error', error: 'file-not-found' };
+      }
+
+      try {
+        const jsonString = fs.readFileSync(resolved, 'utf8');
+        const result = importConfig(brainDir, jsonString);
+
+        const lines = [`Imported: ${result.imported} settings`];
+        if (result.skipped.length > 0) {
+          lines.push(`Skipped: ${result.skipped.length}`);
+          for (const s of result.skipped) {
+            lines.push(`  - ${s.key}: ${s.reason}`);
+          }
+        }
+        success(lines.join('\n'));
+
+        return {
+          action: 'import',
+          imported: result.imported,
+          skipped: result.skipped
+        };
+      } catch (err) {
+        error(err.message);
+        return { action: 'error', error: err.message };
+      }
+    }
+
+    default: {
+      showUsage();
+      return { action: 'usage' };
+    }
+  }
+}
+
+module.exports = { run };

package/bin/lib/commands/discuss.cjs

@@ -0,0 +1,237 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState, atomicWriteSync } = require('../state.cjs');
+const { parseRoadmap } = require('../roadmap.cjs');
+const { loadTemplate, interpolate } = require('../templates.cjs');
+const { output, error, success } = require('../core.cjs');
+
+/**
+ * Find the phase directory under .brain/phases/ matching a phase number.
+ * Looks for directories starting with "NN-" (zero-padded).
+ * Creates the directory if it doesn't exist.
+ * @param {string} brainDir - Path to .brain/
+ * @param {number} phaseNumber
+ * @param {string} phaseName
+ * @returns {string} Path to phase directory
+ */
+function ensurePhaseDir(brainDir, phaseNumber, phaseName) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    fs.mkdirSync(phasesDir, { recursive: true });
+  }
+
+  const padded = String(phaseNumber).padStart(2, '0');
+
+  // Look for existing directory with this number prefix
+  const existing = fs.readdirSync(phasesDir).find(d => d.startsWith(`${padded}-`));
+  if (existing) {
+    return path.join(phasesDir, existing);
+  }
+
+  // Create new directory
+  const dirName = `${padded}-${phaseName}`;
+  const dirPath = path.join(phasesDir, dirName);
+  fs.mkdirSync(dirPath, { recursive: true });
+  return dirPath;
+}
+
+/**
+ * Try to find and read a research SUMMARY.md for a phase.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @returns {string|null}
+ */
+function findResearchSummary(brainDir, phaseNumber) {
+  const phasesDir = path.join(brainDir, 'phases');
+  if (!fs.existsSync(phasesDir)) return null;
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const dirs = fs.readdirSync(phasesDir).filter(d => d.startsWith(`${padded}-`));
+
+  for (const dir of dirs) {
+    const summaryPath = path.join(phasesDir, dir, 'SUMMARY.md');
+    if (fs.existsSync(summaryPath)) {
+      return fs.readFileSync(summaryPath, 'utf8');
+    }
+  }
+  return null;
+}
+
+/**
+ * Run the discuss command.
+ *
+ * Analyze mode (default): Output gray-area analysis instructions for Claude.
+ * Save mode (--save --decisions <json>): Persist decisions to CONTEXT.md.
+ *
+ * @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' };
+  }
+
+  const isSave = args.includes('--save');
+
+  if (isSave) {
+    return handleSave(args, brainDir, state);
+  }
+
+  return handleAnalyze(args, brainDir, state);
+}
+
+/**
+ * Handle analyze mode: output gray-area analysis instructions.
+ */
+function handleAnalyze(args, brainDir, state) {
+  // Parse phase number: supports both `discuss 1` and `discuss --phase 1`
+  const phaseIdx = args.indexOf('--phase');
+  let phaseNumber;
+  if (phaseIdx >= 0) {
+    phaseNumber = parseInt(args[phaseIdx + 1], 10);
+  } else {
+    // Check for positional argument (first non-flag arg)
+    const positional = args.find(a => !a.startsWith('--') && !isNaN(parseInt(a, 10)));
+    phaseNumber = positional ? parseInt(positional, 10) : state.phase.current;
+  }
+
+  // Read roadmap for phase details
+  const roadmap = parseRoadmap(brainDir);
+  const phase = roadmap.phases.find(p => p.number === phaseNumber);
+
+  if (!phase) {
+    const available = roadmap.phases.map(p => p.number).join(', ') || 'none';
+    error(`Phase ${phaseNumber} not found in roadmap. Available phases: ${available}. Run /brain:progress to see current state.`);
+    return { error: 'phase-not-found' };
+  }
+
+  // Check for research summary
+  const researchSummary = findResearchSummary(brainDir, phaseNumber);
+
+  // Load and interpolate template
+  const template = loadTemplate('discuss');
+  const researchSection = researchSummary
+    ? `**Research Summary:**\n${researchSummary}`
+    : '_No research summary available for this phase._';
+
+  const prompt = interpolate(template, {
+    phase_number: phaseNumber,
+    phase_name: phase.name,
+    phase_goal: phase.goal,
+    phase_requirements: phase.requirements.join(', ') || 'None specified',
+    research_section: researchSection
+  });
+
+  // Update status to discussing
+  state.phase.status = 'discussing';
+  writeState(brainDir, state);
+
+  const result = {
+    action: 'discuss-phase',
+    phase: phaseNumber,
+    goal: phase.goal,
+    requirements: phase.requirements,
+    research_summary: researchSummary || null,
+    prompt,
+    nextAction: '/brain:plan'
+  };
+
+  // Human-readable output
+  const humanLines = [
+    `[brain] Discussion analysis for Phase ${phaseNumber}: ${phase.name}`,
+    '',
+    prompt
+  ];
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+/**
+ * Handle save mode: create CONTEXT.md with decisions.
+ */
+function handleSave(args, brainDir, state) {
+  const decisionsIdx = args.indexOf('--decisions');
+  if (decisionsIdx < 0 || !args[decisionsIdx + 1]) {
+    error('--save requires --decisions <json>');
+    return { error: 'missing-decisions' };
+  }
+
+  let decisionsData;
+  try {
+    decisionsData = JSON.parse(args[decisionsIdx + 1]);
+  } catch {
+    error('Invalid JSON for --decisions');
+    return { error: 'invalid-json' };
+  }
+
+  const phaseNumber = state.phase.current;
+  const roadmap = parseRoadmap(brainDir);
+  const phase = roadmap.phases.find(p => p.number === phaseNumber);
+  const phaseName = phase ? phase.name : `Phase-${phaseNumber}`;
+
+  // Ensure phase directory exists
+  const phaseDir = ensurePhaseDir(brainDir, phaseNumber, phaseName);
+
+  // Build CONTEXT.md content
+  const decisions = decisionsData.decisions || [];
+  const specifics = decisionsData.specifics || [];
+  const deferred = decisionsData.deferred || [];
+
+  const lines = [
+    `# Phase ${phaseNumber}: ${phaseName} -- Context`,
+    '',
+    '<decisions>',
+    '',
+    '## Locked Decisions',
+    '',
+    ...decisions.map(d => `- ${d}`),
+    '',
+    '</decisions>',
+    '',
+    '<specifics>',
+    '',
+    '## Specific Approaches',
+    '',
+    ...specifics.map(s => `- ${s}`),
+    '',
+    '</specifics>',
+    '',
+    '<deferred>',
+    '',
+    '## Deferred Ideas',
+    '',
+    ...deferred.map(d => `- ${d}`),
+    '',
+    '</deferred>',
+    ''
+  ];
+
+  const contextPath = path.join(phaseDir, 'CONTEXT.md');
+  atomicWriteSync(contextPath, lines.join('\n'));
+
+  // Update state: set phase status to "discussed"
+  state.phase.status = 'discussed';
+  writeState(brainDir, state);
+
+  const result = {
+    action: 'context-saved',
+    phase: phaseNumber,
+    path: contextPath,
+    nextAction: '/brain:plan'
+  };
+
+  success("Context captured. Run /brain:plan to create execution plans.");
+  output(result, '');
+
+  return result;
+}
+
+module.exports = { run };