brain-dev 0.1.0

package/bin/lib/commands/pause.cjs

@@ -0,0 +1,142 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState, writeState, atomicWriteSync } = require('../state.cjs');
+const { output, prefix, success, error } = require('../core.cjs');
+
+/**
+ * Parse --note flag from args.
+ * @param {string[]} args
+ * @returns {string|null}
+ */
+function parseNote(args) {
+  const idx = args.indexOf('--note');
+  if (idx === -1 || idx + 1 >= args.length) return null;
+  return args[idx + 1];
+}
+
+/**
+ * Generate continue-here.md content from state.
+ * @param {object} state - brain.json state
+ * @param {string|null} note - Optional user note
+ * @returns {string} Markdown content
+ */
+function generateSnapshot(state, note) {
+  const phase = state.phase || {};
+  const phases = phase.phases || [];
+  const now = new Date().toISOString();
+
+  // YAML frontmatter
+  const lines = [
+    '---',
+    `phase: ${phase.current || 0}`,
+    `status: ${phase.status || 'initialized'}`,
+    `paused_at: ${now}`,
+    '---',
+    ''
+  ];
+
+  // Current State
+  lines.push('## Current State');
+  if (note) {
+    lines.push(note);
+  } else {
+    const phaseName = phases.find(p => p.number === phase.current)?.name || 'Unknown';
+    lines.push(`Phase ${phase.current} (${phaseName}): ${phase.status}`);
+  }
+  lines.push('');
+
+  // Completed Work
+  lines.push('## Completed Work');
+  const completedPhases = phases.filter(p => p.status === 'complete');
+  if (completedPhases.length > 0) {
+    for (const p of completedPhases) {
+      lines.push(`- Phase ${p.number} (${p.name}): ${p.plans?.done || 0}/${p.plans?.total || 0} plans`);
+    }
+  } else {
+    lines.push('- No phases completed yet');
+  }
+  lines.push('');
+
+  // Remaining Work
+  lines.push('## Remaining Work');
+  const remainingPhases = phases.filter(p => p.status !== 'complete');
+  if (remainingPhases.length > 0) {
+    for (const p of remainingPhases) {
+      const remaining = (p.plans?.total || 0) - (p.plans?.done || 0);
+      lines.push(`- Phase ${p.number} (${p.name}): ${remaining} plans remaining`);
+    }
+  } else {
+    lines.push('- All phases complete');
+  }
+  lines.push('');
+
+  // Decisions Made
+  lines.push('## Decisions Made');
+  lines.push('- See .brain/brain.json for full state');
+  lines.push('');
+
+  // Conversation Summary
+  lines.push('## Conversation Summary');
+  lines.push('<!-- Claude: summarize the current conversation context here when presenting to user -->');
+  lines.push('');
+
+  // Next Action
+  lines.push('## Next Action');
+  const { nextAction } = require('./progress.cjs');
+  lines.push(nextAction(state));
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Run the pause 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);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  const note = parseNote(args);
+  const snapshot = generateSnapshot(state, note);
+  const now = new Date().toISOString();
+
+  // Write continue-here.md
+  const snapshotPath = path.join(brainDir, 'continue-here.md');
+  atomicWriteSync(snapshotPath, snapshot);
+
+  // Archive to sessions/
+  const sessionsDir = path.join(brainDir, 'sessions');
+  if (!fs.existsSync(sessionsDir)) {
+    fs.mkdirSync(sessionsDir, { recursive: true });
+  }
+  const sessionFileName = now.replace(/:/g, '-').replace(/\.\d+Z$/, 'Z') + '.md';
+  // Simplify to safe filename
+  const safeFileName = now.slice(0, 19).replace(/:/g, '-') + '.md';
+  fs.copyFileSync(snapshotPath, path.join(sessionsDir, safeFileName));
+
+  // Update state
+  state.session = state.session || {};
+  state.session.lastPaused = now;
+  state.session.snapshotPath = '.brain/continue-here.md';
+  writeState(brainDir, state);
+
+  success('Session paused. Snapshot saved to .brain/continue-here.md');
+  output(
+    { paused: true, snapshot: snapshotPath, session: safeFileName },
+    prefix(`Archived to .brain/sessions/${safeFileName}`)
+  );
+
+  return { paused: true, snapshot: snapshotPath };
+}
+
+module.exports = { run };

package/bin/lib/commands/phase-manage.cjs

@@ -0,0 +1,357 @@
+'use strict';
+
+const path = require('node:path');
+const { readState, writeState } = require('../state.cjs');
+const { parseRoadmap, writeRoadmap, insertPhase, removePhase, reorderPhases } = require('../roadmap.cjs');
+const { output, error, success } = require('../core.cjs');
+
+/**
+ * Parse a named flag value from args array.
+ * @param {string[]} args
+ * @param {string} flag - Flag name (e.g. '--after')
+ * @returns {string|null}
+ */
+function getFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx === args.length - 1) return null;
+  return args[idx + 1];
+}
+
+/**
+ * Check if a flag exists in args (boolean flag).
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {boolean}
+ */
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+/**
+ * Map phase status to a display indicator type.
+ * @param {string} status
+ * @returns {string} 'done' | 'current' | 'pending'
+ */
+function statusIndicator(status) {
+  const s = (status || '').toLowerCase();
+  if (s === 'complete' || s === 'completed' || s === 'done') return 'done';
+  if (s === 'in progress' || s === 'executing' || s === 'current') return 'current';
+  return 'pending';
+}
+
+/**
+ * Format phase number for display.
+ * @param {number} n
+ * @returns {string}
+ */
+function fmtNum(n) {
+  return Number.isInteger(n) ? String(n) : n.toFixed(1);
+}
+
+/**
+ * Check if a phase is completed (read-only).
+ * @param {{ status: string }} phase
+ * @returns {boolean}
+ */
+function isComplete(phase) {
+  return statusIndicator(phase.status) === 'done';
+}
+
+/**
+ * Handle the 'list' subcommand.
+ */
+function handleList(roadmap) {
+  const phases = roadmap.phases.map(p => ({
+    number: p.number,
+    name: p.name,
+    goal: p.goal,
+    status: p.status,
+    indicator: statusIndicator(p.status),
+    dependsOn: p.dependsOn,
+    requirements: p.requirements
+  }));
+
+  // Human-readable table
+  const indicatorSymbol = { done: '[x]', current: '[>]', pending: '[ ]' };
+  const lines = ['Phases:', ''];
+  for (const p of phases) {
+    const sym = indicatorSymbol[p.indicator];
+    lines.push(`  ${sym} Phase ${fmtNum(p.number)}: ${p.name} (${p.status})`);
+  }
+
+  output({ phases }, lines.join('\n'));
+  return { phases };
+}
+
+/**
+ * Handle the 'add' subcommand.
+ */
+function handleAdd(args, roadmap, brainDir) {
+  const name = getFlag(args, '--name');
+  const goal = getFlag(args, '--goal');
+  const after = getFlag(args, '--after');
+
+  // If no name/goal provided, output instructions for Claude to ask user
+  if (!name || !goal) {
+    const questions = [
+      { id: 'name', question: 'What is the name of the new phase?' },
+      { id: 'goal', question: 'What is the goal of this phase?' },
+      { id: 'after', question: `After which phase should it be added? (current phases: ${roadmap.phases.map(p => `${fmtNum(p.number)}: ${p.name}`).join(', ')})` },
+      { id: 'requirements', question: 'Any requirements to assign? (comma-separated, or skip)' }
+    ];
+
+    const result = {
+      action: 'ask-user',
+      command: 'phase add',
+      questions,
+      instructions: 'Use AskUserQuestion to ask each question, then call: brain-dev phase add --name "<name>" --goal "<goal>" --after <N>'
+    };
+    output(result, 'To add a phase, please provide: name, goal, position, and optional requirements.');
+    return result;
+  }
+
+  // Name and goal provided -- execute the add
+  const afterNum = after ? parseFloat(after) : roadmap.phases[roadmap.phases.length - 1]?.number || 0;
+  const reqStr = getFlag(args, '--requirements');
+  const requirements = reqStr ? reqStr.split(',').map(s => s.trim()) : [];
+
+  const updatedRoadmap = insertPhase(roadmap, afterNum, { name, goal, requirements });
+  writeRoadmap(brainDir, updatedRoadmap);
+
+  // Find the newly created phase
+  const newPhase = updatedRoadmap.phases.find(p => p.name === name);
+
+  // Update state
+  const state = readState(brainDir);
+  if (state) {
+    state.phase.total = updatedRoadmap.phases.length;
+    writeState(brainDir, state);
+  }
+
+  success(`Phase ${fmtNum(newPhase.number)}: ${name} added.`);
+  return { action: 'added', phase: newPhase };
+}
+
+/**
+ * Handle the 'insert' subcommand.
+ */
+function handleInsert(args, roadmap, brainDir) {
+  const after = getFlag(args, '--after');
+  if (!after) {
+    error('Missing --after flag. Usage: brain-dev phase insert --after <N>');
+    return { error: 'missing-flag', message: 'Missing --after flag' };
+  }
+
+  const afterNum = parseFloat(after);
+  const afterPhase = roadmap.phases.find(p => p.number === afterNum);
+  if (!afterPhase) {
+    error(`Phase ${after} not found.`);
+    return { error: 'not-found', message: `Phase ${after} not found` };
+  }
+
+  const name = getFlag(args, '--name');
+  const goal = getFlag(args, '--goal');
+
+  // If no name/goal, output instructions for Claude
+  if (!name || !goal) {
+    const result = {
+      action: 'ask-user',
+      command: 'phase insert',
+      insertAfter: afterNum,
+      questions: [
+        { id: 'name', question: 'What is the name of the new phase?' },
+        { id: 'goal', question: 'What is the goal of this phase?' },
+        { id: 'requirements', question: 'Any requirements to assign? (comma-separated, or skip)' }
+      ],
+      instructions: `Use AskUserQuestion to ask each question, then call: brain-dev phase insert --after ${after} --name "<name>" --goal "<goal>"`
+    };
+    output(result, `To insert a phase after ${fmtNum(afterNum)}, please provide: name, goal, and optional requirements.`);
+    return result;
+  }
+
+  // Execute the insert
+  const reqStr = getFlag(args, '--requirements');
+  const requirements = reqStr ? reqStr.split(',').map(s => s.trim()) : [];
+
+  const updatedRoadmap = insertPhase(roadmap, afterNum, { name, goal, requirements });
+  writeRoadmap(brainDir, updatedRoadmap);
+
+  const newPhase = updatedRoadmap.phases.find(p => p.name === name);
+
+  // Update state
+  const state = readState(brainDir);
+  if (state) {
+    state.phase.total = updatedRoadmap.phases.length;
+    writeState(brainDir, state);
+  }
+
+  success(`Phase ${fmtNum(newPhase.number)}: ${name} inserted after phase ${fmtNum(afterNum)}.`);
+  return { action: 'inserted', phase: newPhase };
+}
+
+/**
+ * Handle the 'remove' subcommand.
+ */
+function handleRemove(args, roadmap, brainDir) {
+  const phaseStr = getFlag(args, '--phase');
+  if (!phaseStr) {
+    error('Missing --phase flag. Usage: brain-dev phase remove --phase <N>');
+    return { error: 'missing-flag', message: 'Missing --phase flag' };
+  }
+
+  const phaseNum = parseFloat(phaseStr);
+  const targetPhase = roadmap.phases.find(p => p.number === phaseNum);
+
+  if (!targetPhase) {
+    error(`Phase ${phaseStr} not found.`);
+    return { error: 'not-found', message: `Phase ${phaseStr} not found` };
+  }
+
+  // Completed phases are read-only
+  if (isComplete(targetPhase)) {
+    error(`Phase ${fmtNum(phaseNum)}: ${targetPhase.name} is complete and read-only. Create a new gap closure phase instead.`);
+    return {
+      error: 'read-only',
+      message: `Phase ${fmtNum(phaseNum)} is complete and cannot be modified. Create a new gap closure phase instead.`
+    };
+  }
+
+  const confirm = hasFlag(args, '--confirm');
+
+  // First call: show orphaned requirements and ask for confirmation
+  if (!confirm) {
+    const { orphanedRequirements } = removePhase(roadmap, phaseNum);
+    const result = {
+      action: 'ask-user',
+      command: 'phase remove',
+      phaseToRemove: phaseNum,
+      phaseName: targetPhase.name,
+      orphanedRequirements,
+      questions: orphanedRequirements.length > 0
+        ? orphanedRequirements.map(req => ({
+            id: `requirement-${req}`,
+            question: `Requirement ${req} will be orphaned. Reassign to another phase / Delete / Hold as unassigned?`
+          }))
+        : [],
+      instructions: orphanedRequirements.length > 0
+        ? `Phase ${fmtNum(phaseNum)} has ${orphanedRequirements.length} orphaned requirement(s). Ask user about each, then call: brain-dev phase remove --phase ${phaseStr} --confirm`
+        : `Phase ${fmtNum(phaseNum)} has no requirements. Confirm removal: brain-dev phase remove --phase ${phaseStr} --confirm`
+    };
+    output(result, `Phase ${fmtNum(phaseNum)}: ${targetPhase.name} will be removed.`);
+    return result;
+  }
+
+  // Confirmed: execute removal
+  const { roadmap: updatedRoadmap, orphanedRequirements } = removePhase(roadmap, phaseNum);
+  writeRoadmap(brainDir, updatedRoadmap);
+
+  // Update state
+  const state = readState(brainDir);
+  if (state) {
+    state.phase.total = updatedRoadmap.phases.length;
+    writeState(brainDir, state);
+  }
+
+  success(`Phase ${fmtNum(phaseNum)} removed. Dependencies updated.`);
+  return { action: 'removed', removed: phaseNum, orphanedRequirements };
+}
+
+/**
+ * Handle the 'reorder' subcommand.
+ */
+function handleReorder(args, roadmap, brainDir) {
+  const orderStr = getFlag(args, '--order');
+
+  // No order provided: show current order and ask
+  if (!orderStr) {
+    const currentOrder = roadmap.phases.map(p => ({
+      number: p.number,
+      name: p.name,
+      status: p.status,
+      indicator: statusIndicator(p.status)
+    }));
+
+    const result = {
+      action: 'ask-user',
+      command: 'phase reorder',
+      currentOrder,
+      instructions: `Current order: ${currentOrder.map(p => `${fmtNum(p.number)}: ${p.name}`).join(', ')}. Ask user for new order, then call: brain-dev phase reorder --order "N,N,N,..."`
+    };
+    output(result, 'Current phase order:\n' + currentOrder.map(p => `  ${fmtNum(p.number)}: ${p.name} (${p.status})`).join('\n'));
+    return result;
+  }
+
+  // Parse new order
+  const newOrder = orderStr.split(',').map(s => parseFloat(s.trim()));
+
+  // Validate: completed phases must remain in their original position
+  // Find completed phases and check they are in the same relative position
+  const completedPhases = roadmap.phases.filter(p => isComplete(p));
+  for (const cp of completedPhases) {
+    const originalIdx = roadmap.phases.indexOf(cp);
+    const newIdx = newOrder.indexOf(cp.number);
+    if (newIdx !== originalIdx) {
+      error(`Phase ${fmtNum(cp.number)}: ${cp.name} is complete and cannot be moved. Completed phases are read-only.`);
+      return {
+        error: 'read-only',
+        message: `Phase ${fmtNum(cp.number)} is complete and cannot be moved. Completed phases are read-only.`
+      };
+    }
+  }
+
+  const updatedRoadmap = reorderPhases(roadmap, newOrder);
+  writeRoadmap(brainDir, updatedRoadmap);
+
+  // Update state
+  const state = readState(brainDir);
+  if (state) {
+    state.phase.total = updatedRoadmap.phases.length;
+    writeState(brainDir, state);
+  }
+
+  success('Phases reordered. Dependencies updated.');
+  return { action: 'reordered', newOrder: updatedRoadmap.phases.map(p => ({ number: p.number, name: p.name })) };
+}
+
+/**
+ * Run the phase management command.
+ * @param {string[]} args - CLI arguments (subcommand + flags)
+ * @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 subcommand = args[0] || 'list';
+
+  // Read roadmap
+  let roadmap;
+  try {
+    roadmap = parseRoadmap(brainDir);
+  } catch (e) {
+    error(`Cannot read roadmap: ${e.message}`);
+    return { error: 'no-roadmap', message: e.message };
+  }
+
+  switch (subcommand) {
+    case 'list':
+      return handleList(roadmap);
+
+    case 'add':
+      return handleAdd(args, roadmap, brainDir);
+
+    case 'insert':
+      return handleInsert(args, roadmap, brainDir);
+
+    case 'remove':
+      return handleRemove(args, roadmap, brainDir);
+
+    case 'reorder':
+      return handleReorder(args, roadmap, brainDir);
+
+    default:
+      error(`Unknown subcommand: '${subcommand}'. Use: list, add, insert, remove, reorder`);
+      return { error: 'unknown-subcommand', message: `Unknown subcommand: ${subcommand}` };
+  }
+}
+
+module.exports = { run };