brain-dev 0.1.0

package/bin/lib/commands/quick.cjs

@@ -0,0 +1,447 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { loadTemplate, interpolate } = require('../templates.cjs');
+const { resolveModel } = require('../agents.cjs');
+const { logEvent } = require('../logger.cjs');
+const { output, error, success } = require('../core.cjs');
+
+/**
+ * Generate a URL-safe slug from a description.
+ * @param {string} text
+ * @returns {string}
+ */
+function generateSlug(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .substring(0, 40);
+}
+
+/**
+ * Calculate the next quick task number by scanning .brain/quick/.
+ * @param {string} quickDir
+ * @returns {number}
+ */
+function calculateNextNum(quickDir) {
+  try {
+    const existing = fs.readdirSync(quickDir)
+      .filter(f => /^\d+-/.test(f))
+      .map(f => parseInt(f.split('-')[0], 10))
+      .filter(n => !isNaN(n));
+    return existing.length > 0 ? Math.max(...existing) + 1 : 1;
+  } catch {
+    return 1;
+  }
+}
+
+/**
+ * Find a quick task directory by number.
+ * @param {string} brainDir
+ * @param {number} taskNum
+ * @returns {string|null}
+ */
+function findTaskDir(brainDir, taskNum) {
+  const quickDir = path.join(brainDir, 'quick');
+  if (!fs.existsSync(quickDir)) return null;
+  const match = fs.readdirSync(quickDir).find(d => d.startsWith(`${taskNum}-`));
+  return match ? path.join(quickDir, match) : null;
+}
+
+/**
+ * Parse --task N from args.
+ * @param {string[]} args
+ * @returns {number|null}
+ */
+function getTaskNum(args) {
+  const idx = args.indexOf('--task');
+  if (idx >= 0 && args[idx + 1]) {
+    const num = parseInt(args[idx + 1], 10);
+    return isNaN(num) ? null : num;
+  }
+  return null;
+}
+
+/**
+ * Run the quick command.
+ *
+ * Steps (each triggered by flags):
+ *   (default)           → Init + planner instructions
+ *   --execute --task N  → Executor instructions
+ *   --verify --task N   → Verifier instructions (--full only)
+ *   --complete --task N → STATE.md update + commit instructions
+ *
+ * @param {string[]} args
+ * @param {object} [opts]
+ */
+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' };
+  }
+
+  if (!state.project || !state.project.initialized) {
+    error("Project not initialized. Run '/brain:new-project' first.");
+    return { error: 'not-initialized' };
+  }
+
+  // Route to step handlers
+  if (args.includes('--complete')) {
+    return handleComplete(args, brainDir, state);
+  }
+  if (args.includes('--verify')) {
+    return handleVerify(args, brainDir, state);
+  }
+  if (args.includes('--execute')) {
+    return handleExecute(args, brainDir, state);
+  }
+
+  // Default: init + planner
+  return handleInit(args, brainDir, state);
+}
+
+/**
+ * Step 1-2: Parse args, create task dir, generate planner instructions.
+ */
+function handleInit(args, brainDir, state) {
+  const isFull = args.includes('--full');
+
+  // Extract description (everything except flags)
+  const desc = args.filter(a => !a.startsWith('--')).join(' ').trim();
+
+  if (!desc) {
+    const humanText = [
+      '[brain] Quick Task',
+      '',
+      'IMPORTANT: Use AskUserQuestion to ask what the user wants to do.',
+      'Then run: npx brain-dev quick "description here"'
+    ].join('\n');
+
+    const result = {
+      action: 'ask-description',
+      tool: 'AskUserQuestion',
+      question: { question: 'What do you want to do?', header: 'Quick Task', options: [
+        { label: 'Fix a bug', description: 'Fix an existing issue or error' },
+        { label: 'Add a feature', description: 'Add new functionality' },
+        { label: 'Refactor', description: 'Improve code quality without changing behavior' },
+        { label: 'Update docs', description: 'Update documentation or README' }
+      ], multiSelect: false },
+      instruction: 'After getting description, run: npx brain-dev quick "user description here"'
+    };
+
+    output(result, humanText);
+    return result;
+  }
+
+  // Create quick task directory
+  const quickDir = path.join(brainDir, 'quick');
+  fs.mkdirSync(quickDir, { recursive: true });
+  const nextNum = calculateNextNum(quickDir);
+  const slug = generateSlug(desc);
+  const taskDir = path.join(quickDir, `${nextNum}-${slug}`);
+  fs.mkdirSync(taskDir, { recursive: true });
+
+  // Save task metadata
+  const taskMeta = { num: nextNum, slug, description: desc, full: isFull, created: new Date().toISOString() };
+  fs.writeFileSync(path.join(taskDir, 'task.json'), JSON.stringify(taskMeta, null, 2));
+
+  // Generate planner prompt using existing template + quick constraints
+  const template = loadTemplate('planner');
+  const prompt = interpolate(template, {
+    phase_number: nextNum,
+    phase_name: desc,
+    phase_goal: desc,
+    phase_requirements: 'Quick task — single focused deliverable',
+    phase_depends_on: 'None',
+    context_decisions: '_Quick mode: no CONTEXT.md required._',
+    research_summary: '_Quick mode: no research phase._',
+    output_dir: taskDir,
+    phase_number_padded: String(nextNum).padStart(3, '0'),
+    phase_slug: slug
+  });
+
+  const quickConstraints = [
+    '',
+    '## Quick Mode Constraints',
+    '',
+    '- Create a SINGLE plan file: PLAN-1.md',
+    '- Maximum 1-2 focused tasks',
+    '- Target ~30% context budget (keep it small and focused)',
+    '- No research or context gathering needed',
+    '- Task should be atomic and self-contained',
+    isFull ? '- MUST include must_haves in frontmatter (truths, artifacts, key_links)' : '',
+    isFull ? '- Each task MUST have files, action, verify, done fields' : '',
+    '',
+    `Write plan to: ${path.join(taskDir, 'PLAN-1.md')}`,
+    ''
+  ].filter(Boolean).join('\n');
+
+  const fullPrompt = prompt + quickConstraints;
+  const model = resolveModel('planner', state);
+
+  logEvent(brainDir, 0, { type: 'quick-init', task: nextNum, description: desc, full: isFull });
+
+  const humanText = [
+    `[brain] Quick Task ${nextNum}: ${desc}`,
+    isFull ? '[brain] Full mode: plan checking + verification enabled' : '',
+    `[brain] Directory: ${taskDir}`,
+    '',
+    'IMPORTANT: Use the Agent tool (subagent_type: "brain-planner") to spawn the planner.',
+    'Do NOT plan the task yourself.',
+    '',
+    `After planner completes, run: npx brain-dev quick --execute --task ${nextNum}`,
+    '',
+    fullPrompt
+  ].filter(Boolean).join('\n');
+
+  const result = {
+    action: 'spawn-quick-planner',
+    task: nextNum,
+    taskDir,
+    slug,
+    isFull,
+    prompt: fullPrompt,
+    model,
+    nextAction: `npx brain-dev quick --execute --task ${nextNum}`
+  };
+
+  output(result, humanText);
+  return result;
+}
+
+/**
+ * Step 5: Generate executor instructions for a quick task.
+ */
+function handleExecute(args, brainDir, state) {
+  const taskNum = getTaskNum(args);
+  if (!taskNum) {
+    error('--execute requires --task <number>');
+    return { error: 'missing-task-number' };
+  }
+
+  const taskDir = findTaskDir(brainDir, taskNum);
+  if (!taskDir) {
+    error(`Quick task ${taskNum} not found.`);
+    return { error: 'task-not-found' };
+  }
+
+  // Read plan
+  const planPath = path.join(taskDir, 'PLAN-1.md');
+  if (!fs.existsSync(planPath)) {
+    error(`Plan not found for task ${taskNum}. Run quick task init first.`);
+    return { error: 'no-plan' };
+  }
+
+  const planContent = fs.readFileSync(planPath, 'utf8');
+  const summaryPath = path.join(taskDir, 'SUMMARY-1.md');
+
+  // Load executor template
+  const template = loadTemplate('executor');
+  const prompt = interpolate(template, {
+    plan_path: planPath,
+    summary_path: summaryPath,
+    plan_content: planContent,
+    phase: `Q${taskNum}`,
+    plan_number: '1',
+    subsystem: `quick-${taskNum}`
+  });
+
+  const model = resolveModel('executor', state);
+
+  // Read task metadata for --full check
+  let isFull = false;
+  try {
+    const meta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+    isFull = meta.full === true;
+  } catch { /* ignore */ }
+
+  const nextCmd = isFull
+    ? `npx brain-dev quick --verify --task ${taskNum}`
+    : `npx brain-dev quick --complete --task ${taskNum}`;
+
+  logEvent(brainDir, 0, { type: 'quick-execute', task: taskNum });
+
+  const humanText = [
+    `[brain] Executing Quick Task ${taskNum}`,
+    `[brain] Plan: ${planPath}`,
+    `[brain] Summary: ${summaryPath}`,
+    '',
+    'IMPORTANT: Use the Agent tool (subagent_type: "brain-executor") to spawn the executor.',
+    'Do NOT execute the tasks yourself.',
+    '',
+    `After executor completes, run: ${nextCmd}`,
+    '',
+    prompt
+  ].join('\n');
+
+  const result = {
+    action: 'spawn-quick-executor',
+    task: taskNum,
+    planPath,
+    summaryPath,
+    prompt,
+    model,
+    nextAction: nextCmd
+  };
+
+  output(result, humanText);
+  return result;
+}
+
+/**
+ * Step 6: Generate verifier instructions (--full mode only).
+ */
+function handleVerify(args, brainDir, state) {
+  const taskNum = getTaskNum(args);
+  if (!taskNum) {
+    error('--verify requires --task <number>');
+    return { error: 'missing-task-number' };
+  }
+
+  const taskDir = findTaskDir(brainDir, taskNum);
+  if (!taskDir) {
+    error(`Quick task ${taskNum} not found.`);
+    return { error: 'task-not-found' };
+  }
+
+  const planPath = path.join(taskDir, 'PLAN-1.md');
+  const verificationPath = path.join(taskDir, 'VERIFICATION-1.md');
+
+  // Load verifier template
+  const template = loadTemplate('verifier');
+
+  // Extract must_haves from plan
+  let mustHaves = 'No must_haves found in plan.';
+  try {
+    const planContent = fs.readFileSync(planPath, 'utf8');
+    const truthsMatch = planContent.match(/truths:\s*\n((?:\s+-\s+"[^"]*"\n?)*)/);
+    if (truthsMatch) {
+      mustHaves = truthsMatch[0];
+    }
+  } catch { /* ignore */ }
+
+  const prompt = interpolate(template, {
+    must_haves: mustHaves,
+    output_path: verificationPath,
+    anti_pattern_results: 'No anti-pattern scan for quick tasks.',
+    nyquist_section: 'Nyquist validation not applicable for quick tasks.'
+  });
+
+  const model = resolveModel('verifier', state);
+
+  logEvent(brainDir, 0, { type: 'quick-verify', task: taskNum });
+
+  const humanText = [
+    `[brain] Verifying Quick Task ${taskNum}`,
+    '',
+    'IMPORTANT: Use the Agent tool (subagent_type: "brain-verifier") to spawn the verifier.',
+    '',
+    `After verification, run: npx brain-dev quick --complete --task ${taskNum}`,
+    '',
+    prompt
+  ].join('\n');
+
+  const result = {
+    action: 'spawn-quick-verifier',
+    task: taskNum,
+    prompt,
+    model,
+    verificationPath,
+    nextAction: `npx brain-dev quick --complete --task ${taskNum}`
+  };
+
+  output(result, humanText);
+  return result;
+}
+
+/**
+ * Step 7-8: Update STATE.md and output commit instructions.
+ */
+function handleComplete(args, brainDir, state) {
+  const taskNum = getTaskNum(args);
+  if (!taskNum) {
+    error('--complete requires --task <number>');
+    return { error: 'missing-task-number' };
+  }
+
+  const taskDir = findTaskDir(brainDir, taskNum);
+  if (!taskDir) {
+    error(`Quick task ${taskNum} not found.`);
+    return { error: 'task-not-found' };
+  }
+
+  // Read task metadata
+  let meta = { description: 'Unknown task', full: false };
+  try {
+    meta = JSON.parse(fs.readFileSync(path.join(taskDir, 'task.json'), 'utf8'));
+  } catch { /* ignore */ }
+
+  const date = new Date().toISOString().split('T')[0];
+  const slug = path.basename(taskDir).replace(/^\d+-/, '');
+
+  // Determine status
+  let status = 'Done';
+  if (meta.full) {
+    const verPath = path.join(taskDir, 'VERIFICATION-1.md');
+    if (fs.existsSync(verPath)) {
+      const content = fs.readFileSync(verPath, 'utf8');
+      if (content.includes('status: passed')) status = 'Verified';
+      else if (content.includes('status: human_needed')) status = 'Needs Review';
+      else if (content.includes('status: gaps_found')) status = 'Gaps';
+    }
+  }
+
+  // Update quick task count in state
+  if (!state.quick) state.quick = { count: 0 };
+  state.quick.count = taskNum;
+  writeState(brainDir, state);
+
+  logEvent(brainDir, 0, { type: 'quick-complete', task: taskNum, status });
+
+  // Build commit file list
+  const filesToCommit = [];
+  for (const f of ['PLAN-1.md', 'SUMMARY-1.md', 'VERIFICATION-1.md', 'task.json']) {
+    if (fs.existsSync(path.join(taskDir, f))) {
+      filesToCommit.push(path.relative(path.dirname(brainDir), path.join(taskDir, f)));
+    }
+  }
+  filesToCommit.push('.brain/brain.json');
+  filesToCommit.push('.brain/STATE.md');
+
+  const humanText = [
+    `[brain] Quick Task ${taskNum} Complete!`,
+    '',
+    `Task: ${meta.description}`,
+    `Status: ${status}`,
+    `Directory: ${taskDir}`,
+    '',
+    'Update STATE.md with a "Quick Tasks" section if not present, add this row:',
+    `| ${taskNum} | ${meta.description} | ${date} | ${status} | [${taskNum}-${slug}](./quick/${taskNum}-${slug}/) |`,
+    '',
+    `Then commit: git add ${filesToCommit.join(' ')} && git commit -m "quick(${taskNum}): ${meta.description}"`,
+    '',
+    'Ready for next: /brain:quick or /brain:progress'
+  ].join('\n');
+
+  const result = {
+    action: 'quick-complete',
+    task: taskNum,
+    description: meta.description,
+    status,
+    date,
+    filesToCommit,
+    commitMessage: `quick(${taskNum}): ${meta.description}`,
+    nextAction: '/brain:quick'
+  };
+
+  output(result, humanText);
+  return result;
+}
+
+module.exports = { run, generateSlug, calculateNextNum, findTaskDir };

package/bin/lib/commands/resume.cjs

@@ -0,0 +1,196 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState } = require('../state.cjs');
+const { output, prefix, error } = require('../core.cjs');
+
+/**
+ * Parse simple YAML frontmatter from markdown content.
+ * @param {string} content - Markdown with YAML frontmatter
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseFrontmatter(content) {
+  const fm = { frontmatter: {}, body: content };
+
+  if (!content.startsWith('---')) return fm;
+
+  const endIdx = content.indexOf('---', 3);
+  if (endIdx === -1) return fm;
+
+  const yamlBlock = content.slice(3, endIdx).trim();
+  const body = content.slice(endIdx + 3).trim();
+
+  const frontmatter = {};
+  for (const line of yamlBlock.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    // Try to parse numbers
+    if (/^\d+$/.test(value)) value = parseInt(value, 10);
+    frontmatter[key] = value;
+  }
+
+  fm.frontmatter = frontmatter;
+  fm.body = body;
+  return fm;
+}
+
+/**
+ * Extract named sections from markdown body.
+ * Sections start with ## heading.
+ * @param {string} body - Markdown body (after frontmatter)
+ * @returns {object} Map of camelCase section names to content
+ */
+function parseSections(body) {
+  const sections = {};
+  const lines = body.split('\n');
+  let currentKey = null;
+  let currentLines = [];
+
+  for (const line of lines) {
+    if (line.startsWith('## ')) {
+      // Save previous section
+      if (currentKey) {
+        sections[currentKey] = currentLines.join('\n').trim();
+      }
+      // New section
+      const heading = line.slice(3).trim();
+      currentKey = heading
+        .replace(/[^a-zA-Z0-9\s]/g, '')
+        .split(/\s+/)
+        .map((w, i) => i === 0 ? w.toLowerCase() : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join('');
+      currentLines = [];
+    } else if (currentKey) {
+      currentLines.push(line);
+    }
+  }
+
+  // Save last section
+  if (currentKey) {
+    sections[currentKey] = currentLines.join('\n').trim();
+  }
+
+  return sections;
+}
+
+/**
+ * Run the resume command.
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir for testing)
+ * @returns {object} Result
+ */
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  // Check --session flag
+  const sessionIdx = args.indexOf('--session');
+  const sessionId = sessionIdx !== -1 && sessionIdx + 1 < args.length ? args[sessionIdx + 1] : null;
+
+  let snapshotContent = null;
+  let snapshotSource = null;
+
+  if (sessionId) {
+    // Load specific session
+    const sessionPath = path.join(brainDir, 'sessions', `${sessionId}.md`);
+    if (fs.existsSync(sessionPath)) {
+      snapshotContent = fs.readFileSync(sessionPath, 'utf8');
+      snapshotSource = sessionPath;
+    } else {
+      error(`Session not found: ${sessionId}`);
+      return { error: `Session not found: ${sessionId}` };
+    }
+  } else {
+    // Check for continue-here.md
+    const defaultPath = path.join(brainDir, 'continue-here.md');
+    if (fs.existsSync(defaultPath) && fs.statSync(defaultPath).isFile()) {
+      snapshotContent = fs.readFileSync(defaultPath, 'utf8');
+      snapshotSource = defaultPath;
+    } else {
+      // Check if sessions directory has files
+      const sessionsDir = path.join(brainDir, 'sessions');
+      if (fs.existsSync(sessionsDir)) {
+        const sessionFiles = fs.readdirSync(sessionsDir)
+          .filter(f => f.endsWith('.md'))
+          .sort();
+
+        if (sessionFiles.length > 0) {
+          // List available sessions
+          const sessions = sessionFiles.map(f => {
+            const content = fs.readFileSync(path.join(sessionsDir, f), 'utf8');
+            const { body } = parseFrontmatter(content);
+            const sections = parseSections(body);
+            const firstLine = (sections.currentState || '').split('\n')[0] || '';
+            return {
+              id: f.replace('.md', ''),
+              file: f,
+              summary: firstLine
+            };
+          });
+
+          output(
+            { sessions },
+            [
+              prefix('Multiple sessions available. Use --session <id> to select:'),
+              ...sessions.map(s => `  ${s.id}  ${s.summary}`)
+            ].join('\n')
+          );
+          return { sessions };
+        }
+      }
+
+      error('No paused session found. Use /brain:pause to save a session first.');
+      return { error: 'No paused session found' };
+    }
+  }
+
+  // Parse snapshot
+  const { frontmatter, body } = parseFrontmatter(snapshotContent);
+  const sections = parseSections(body);
+
+  // Build briefing
+  const briefingLines = [
+    prefix('=== Session Briefing ==='),
+    '',
+    prefix(`Phase: ${frontmatter.phase || '?'} (${frontmatter.status || '?'})`),
+    prefix(`Paused at: ${frontmatter.paused_at || 'unknown'}`),
+    ''
+  ];
+
+  if (sections.currentState) {
+    briefingLines.push(prefix('Current State:'));
+    briefingLines.push(`  ${sections.currentState}`);
+    briefingLines.push('');
+  }
+  if (sections.completedWork) {
+    briefingLines.push(prefix('Completed:'));
+    for (const line of sections.completedWork.split('\n').filter(l => l.trim())) {
+      briefingLines.push(`  ${line}`);
+    }
+    briefingLines.push('');
+  }
+  if (sections.remainingWork) {
+    briefingLines.push(prefix('Remaining:'));
+    for (const line of sections.remainingWork.split('\n').filter(l => l.trim())) {
+      briefingLines.push(`  ${line}`);
+    }
+    briefingLines.push('');
+  }
+  if (sections.nextAction) {
+    briefingLines.push(prefix(`Next: ${sections.nextAction}`));
+  }
+
+  const result = {
+    briefing: true,
+    snapshot: { frontmatter, sections },
+    source: snapshotSource
+  };
+
+  output(result, briefingLines.join('\n'));
+  return result;
+}
+
+module.exports = { run };