brain-dev 0.1.0

package/bin/lib/logger.cjs

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Log an execution event as a JSONL line.
+ * Auto-adds timestamp and creates logs/ directory if missing.
+ *
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {number} phaseNumber - Phase number (padded to 2 digits)
+ * @param {object} event - Event data to log
+ */
+function logEvent(brainDir, phaseNumber, event) {
+  const logsDir = path.join(brainDir, 'logs');
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+  }
+
+  const padded = String(phaseNumber).padStart(2, '0');
+  const logPath = path.join(logsDir, `phase-${padded}-execution.jsonl`);
+
+  const entry = {
+    ...event,
+    timestamp: new Date().toISOString()
+  };
+
+  fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+}
+
+/**
+ * Read all events from a phase execution log.
+ * Returns empty array if log file does not exist.
+ *
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {number} phaseNumber - Phase number
+ * @returns {object[]} Array of parsed event objects
+ */
+function readLog(brainDir, phaseNumber) {
+  const padded = String(phaseNumber).padStart(2, '0');
+  const logPath = path.join(brainDir, 'logs', `phase-${padded}-execution.jsonl`);
+
+  if (!fs.existsSync(logPath)) {
+    return [];
+  }
+
+  const content = fs.readFileSync(logPath, 'utf8').trim();
+  if (!content) return [];
+
+  return content.split('\n').reduce((entries, line) => {
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // Skip corrupted/incomplete log lines
+    }
+    return entries;
+  }, []);
+}
+
+/**
+ * Archive a phase log and clean up old archives beyond keepLast.
+ *
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {number} phaseNumber - Phase number to archive
+ * @param {number} [keepLast=3] - Maximum number of archived logs to keep
+ */
+function archiveLogs(brainDir, phaseNumber, keepLast = 3) {
+  const padded = String(phaseNumber).padStart(2, '0');
+  const logFileName = `phase-${padded}-execution.jsonl`;
+  const logPath = path.join(brainDir, 'logs', logFileName);
+
+  if (!fs.existsSync(logPath)) return;
+
+  const archiveDir = path.join(brainDir, 'logs', 'archive');
+  if (!fs.existsSync(archiveDir)) {
+    fs.mkdirSync(archiveDir, { recursive: true });
+  }
+
+  // Move log to archive
+  const archivePath = path.join(archiveDir, logFileName);
+  fs.renameSync(logPath, archivePath);
+
+  // Clean up old archives beyond keepLast
+  const archived = fs.readdirSync(archiveDir)
+    .filter(f => f.endsWith('.jsonl'))
+    .sort();
+
+  if (archived.length > keepLast) {
+    const toRemove = archived.slice(0, archived.length - keepLast);
+    for (const file of toRemove) {
+      fs.unlinkSync(path.join(archiveDir, file));
+    }
+  }
+}
+
+module.exports = {
+  logEvent,
+  readLog,
+  archiveLogs
+};

package/bin/lib/platform.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Detect which AI IDE platform is running.
+ * Checks environment variables and directory existence.
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - Working directory to check for platform indicators
+ * @returns {string} Platform identifier
+ */
+function detectPlatform(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+
+  // Claude Code: CLAUDE_CODE env var or .claude/ directory
+  if (process.env.CLAUDE_CODE || safeExists(path.join(cwd, '.claude'))) {
+    return 'claude-code';
+  }
+
+  // Codex CLI: CODEX_HOME env var
+  if (process.env.CODEX_HOME) {
+    return 'codex';
+  }
+
+  // OpenCode: opencode.json in project root
+  if (safeExists(path.join(cwd, 'opencode.json'))) {
+    return 'opencode';
+  }
+
+  // Gemini CLI: GEMINI_API_KEY env var
+  if (process.env.GEMINI_API_KEY) {
+    return 'gemini';
+  }
+
+  // Cursor: .cursor/ directory
+  if (safeExists(path.join(cwd, '.cursor'))) {
+    return 'cursor';
+  }
+
+  // Default to claude-code (primary platform)
+  return 'claude-code';
+}
+
+/**
+ * Safe existence check that does not throw on permission errors.
+ * @param {string} p - Path to check
+ * @returns {boolean}
+ */
+function safeExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { detectPlatform };

package/bin/lib/requirements.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { atomicWriteSync } = require('./state.cjs');
+
+/**
+ * Parse REQUIREMENTS.md from a directory into structured data.
+ * @param {string} brainDir - Path to directory containing REQUIREMENTS.md
+ * @returns {{ requirements: Array<{id: string, completed: boolean, description: string}>, traceability: Array<{id: string, phase: string, status: string}> }}
+ */
+function parseRequirements(brainDir) {
+  const mdPath = path.join(brainDir, 'REQUIREMENTS.md');
+
+  if (!fs.existsSync(mdPath)) {
+    return { requirements: [], traceability: [] };
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(mdPath, 'utf8');
+  } catch {
+    return { requirements: [], traceability: [] };
+  }
+
+  // Parse checkbox items: - [x] **ID**: Description or - [ ] **ID**: Description
+  const requirements = [];
+  const checkboxRegex = /^- \[([ x])\] \*\*(\S+)\*\*:?\s*(.+)$/gm;
+  let match;
+
+  while ((match = checkboxRegex.exec(content)) !== null) {
+    requirements.push({
+      id: match[2],
+      completed: match[1] === 'x',
+      description: match[3].trim()
+    });
+  }
+
+  // Parse traceability table
+  const traceability = [];
+  const traceIdx = content.indexOf('## Traceability');
+  if (traceIdx >= 0) {
+    const traceSection = content.slice(traceIdx);
+    const lines = traceSection.split('\n');
+
+    for (const line of lines) {
+      // Skip header row and separator row
+      if (!line.startsWith('|') || line.includes('---') || line.includes('Requirement')) {
+        continue;
+      }
+      const cells = line.split('|').map(c => c.trim()).filter(c => c.length > 0);
+      if (cells.length >= 3) {
+        traceability.push({
+          id: cells[0],
+          phase: cells[1],
+          status: cells[2]
+        });
+      }
+    }
+  }
+
+  return { requirements, traceability };
+}
+
+/**
+ * Toggle a requirement's checkbox status.
+ * @param {string} brainDir - Path to directory containing REQUIREMENTS.md
+ * @param {string} reqId - Requirement ID (e.g., 'FOUND-01')
+ * @param {boolean} completed - true for [x], false for [ ]
+ */
+function updateStatus(brainDir, reqId, completed) {
+  const mdPath = path.join(brainDir, 'REQUIREMENTS.md');
+  let content = fs.readFileSync(mdPath, 'utf8');
+
+  const oldChecked = `- [x] **${reqId}**`;
+  const oldUnchecked = `- [ ] **${reqId}**`;
+  const newMark = completed ? '- [x]' : '- [ ]';
+
+  if (completed && content.includes(oldUnchecked)) {
+    content = content.replace(oldUnchecked, `${newMark} **${reqId}**`);
+  } else if (!completed && content.includes(oldChecked)) {
+    content = content.replace(oldChecked, `${newMark} **${reqId}**`);
+  }
+
+  atomicWriteSync(mdPath, content);
+}
+
+/**
+ * Update a row in the traceability table.
+ * @param {string} brainDir - Path to directory containing REQUIREMENTS.md
+ * @param {string} reqId - Requirement ID
+ * @param {object} updates - Fields to update (e.g., { status: 'Complete', phase: 'Phase 2' })
+ */
+function updateTraceability(brainDir, reqId, updates) {
+  const mdPath = path.join(brainDir, 'REQUIREMENTS.md');
+  let content = fs.readFileSync(mdPath, 'utf8');
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.startsWith('|') || !line.includes(reqId)) continue;
+    // Skip header/separator
+    if (line.includes('---') || line.includes('Requirement')) continue;
+
+    const cells = line.split('|').map(c => c.trim()).filter(c => c.length > 0);
+    // cells: [id, phase, status]
+    if (cells.length >= 3 && cells[0] === reqId) {
+      if (updates.phase !== undefined) cells[1] = updates.phase;
+      if (updates.status !== undefined) cells[2] = updates.status;
+      lines[i] = `| ${cells[0]} | ${cells[1]} | ${cells[2]} |`;
+      break;
+    }
+  }
+
+  atomicWriteSync(mdPath, lines.join('\n'));
+}
+
+/**
+ * Get requirements for a specific phase number.
+ * @param {string} brainDir - Path to directory containing REQUIREMENTS.md
+ * @param {number} phaseNumber - Phase number to filter by
+ * @returns {Array<{id: string, completed: boolean, description: string}>}
+ */
+function getPhaseRequirements(brainDir, phaseNumber) {
+  const { requirements, traceability } = parseRequirements(brainDir);
+
+  // Find requirement IDs belonging to this phase
+  const phaseReqIds = new Set(
+    traceability
+      .filter(t => t.phase === `Phase ${phaseNumber}`)
+      .map(t => t.id)
+  );
+
+  return requirements.filter(r => phaseReqIds.has(r.id));
+}
+
+/**
+ * Get completion statistics for all requirements.
+ * @param {string} brainDir - Path to directory containing REQUIREMENTS.md
+ * @returns {{ total: number, completed: number, pending: number, percent: number }}
+ */
+function getCompletionStats(brainDir) {
+  const { requirements } = parseRequirements(brainDir);
+  const total = requirements.length;
+  const completed = requirements.filter(r => r.completed).length;
+  const pending = total - completed;
+  const percent = total === 0 ? 0 : Math.round((completed / total) * 100);
+
+  return { total, completed, pending, percent };
+}
+
+module.exports = {
+  parseRequirements,
+  updateStatus,
+  updateTraceability,
+  getPhaseRequirements,
+  getCompletionStats
+};

package/bin/lib/roadmap.cjs

@@ -0,0 +1,228 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { atomicWriteSync } = require('./state.cjs');
+
+/**
+ * Parse ROADMAP.md from a .brain directory into a structured object.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @returns {{ overview: string, phases: Array<{number: number, name: string, goal: string, dependsOn: number[], requirements: string[], plans: string, status: string}> }}
+ */
+function parseRoadmap(brainDir) {
+  const mdPath = path.join(brainDir, 'ROADMAP.md');
+  let content;
+  try {
+    content = fs.readFileSync(mdPath, 'utf8');
+  } catch {
+    return { overview: '', phases: [] };
+  }
+
+  // Extract overview: everything between first heading and first ## or ### Phase
+  const overviewMatch = content.match(/^# .+\n([\s\S]*?)(?=\n## |\n### Phase )/m);
+  const overview = overviewMatch ? overviewMatch[1].trim() : '';
+
+  // Extract phases section: try multiple heading patterns
+  // Supports: "## Phases", "## Milestone:", or fallback to whole content
+  let phasesIdx = content.indexOf('## Phases');
+  if (phasesIdx < 0) {
+    // Try to find first ### Phase heading directly
+    phasesIdx = content.search(/### Phase [\d.]+/);
+  }
+  const progressIdx = content.indexOf('\n## Progress');
+  const summaryIdx = content.indexOf('\n## Phase Summary');
+  const endIdx = progressIdx >= 0 ? progressIdx : (summaryIdx >= 0 ? summaryIdx : undefined);
+  const phasesSection = phasesIdx >= 0
+    ? content.slice(phasesIdx, endIdx)
+    : content; // fallback: parse entire content for ### Phase patterns
+
+  // Parse individual phases: ## Phase N: Name or ### Phase N: Name (both formats)
+  const phaseRegex = /#{2,3} Phase ([\d.]+):?\s+(.+)\n([\s\S]*?)(?=\n#{2,3} Phase |\n## (?!Phase)|$)/g;
+  const phases = [];
+  let match;
+
+  while ((match = phaseRegex.exec(phasesSection)) !== null) {
+    const number = parseFloat(match[1]);
+    const name = match[2].trim();
+    const body = match[3];
+
+    // Flexible matching: accept both "- **Goal:**" and "**Goal:**" formats
+    const goalMatch = body.match(/-?\s*\*\*Goal:\*\*\s*(.+)/);
+    const dependsMatch = body.match(/-?\s*\*\*Depends on:\*\*\s*(.+)/);
+    const reqMatch = body.match(/-?\s*\*\*Requirements:\*\*\s*(.+)/);
+    const plansMatch = body.match(/-?\s*\*\*Plans:\*\*\s*(.+)/);
+    const statusMatch = body.match(/-?\s*\*\*Status:\*\*\s*(.+)/);
+
+    const dependsStr = dependsMatch ? dependsMatch[1].trim() : 'None';
+    const dependsOn = (!dependsStr || dependsStr === 'None' || dependsStr === 'none')
+      ? []
+      : dependsStr.split(',').map(s => parseFloat(s.trim())).filter(n => !isNaN(n));
+
+    const reqStr = reqMatch ? reqMatch[1].trim() : '';
+    const requirements = (!reqStr || reqStr === 'None' || reqStr === 'none')
+      ? []
+      : reqStr.split(',').map(s => s.trim()).filter(s => s.length > 0);
+
+    phases.push({
+      number,
+      name,
+      goal: goalMatch ? goalMatch[1].trim() : '',
+      dependsOn,
+      requirements,
+      plans: plansMatch ? plansMatch[1].trim() : '',
+      status: statusMatch ? statusMatch[1].trim() : 'Pending'
+    });
+  }
+
+  // Sort numerically
+  phases.sort((a, b) => a.number - b.number);
+
+  return { overview, phases };
+}
+
+/**
+ * Write a structured roadmap object back to ROADMAP.md.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {{ overview: string, phases: Array }} roadmapData - Structured roadmap
+ */
+function writeRoadmap(brainDir, roadmapData) {
+  const lines = ['# Roadmap', '', roadmapData.overview, '', '## Phases', ''];
+
+  for (const phase of roadmapData.phases) {
+    lines.push(`### Phase ${formatPhaseNumber(phase.number)}: ${phase.name}`);
+    lines.push('');
+    lines.push(`- **Goal:** ${phase.goal}`);
+    lines.push(`- **Depends on:** ${phase.dependsOn.length === 0 ? 'None' : phase.dependsOn.map(n => formatPhaseNumber(n)).join(', ')}`);
+    lines.push(`- **Requirements:** ${phase.requirements.length === 0 ? 'None' : phase.requirements.join(', ')}`);
+    if (phase.plans) {
+      lines.push(`- **Plans:** ${phase.plans}`);
+    }
+    lines.push(`- **Status:** ${phase.status}`);
+    lines.push('');
+  }
+
+  // Progress table
+  lines.push('## Progress');
+  lines.push('');
+  lines.push('| Phase | Status | Plans |');
+  lines.push('|-------|--------|-------|');
+  for (const phase of roadmapData.phases) {
+    lines.push(`| ${formatPhaseNumber(phase.number)} | ${phase.status} | ${phase.plans || '0/0'} |`);
+  }
+  lines.push('');
+
+  const mdPath = path.join(brainDir, 'ROADMAP.md');
+  atomicWriteSync(mdPath, lines.join('\n'));
+}
+
+/**
+ * Format phase number: integers without decimal, decimals with one decimal place.
+ * @param {number} n
+ * @returns {string}
+ */
+function formatPhaseNumber(n) {
+  return Number.isInteger(n) ? String(n) : n.toFixed(1);
+}
+
+/**
+ * Insert a new phase after a given phase number.
+ * Assigns next decimal number (e.g., after 2 creates 2.1, if 2.1 exists creates 2.2).
+ * @param {{ overview: string, phases: Array }} roadmapData
+ * @param {number} afterNumber - Phase number to insert after
+ * @param {{ name: string, goal: string, requirements?: string[], status?: string }} phaseDef
+ * @returns {{ overview: string, phases: Array }}
+ */
+function insertPhase(roadmapData, afterNumber, phaseDef) {
+  const base = Math.floor(afterNumber);
+
+  // Find existing decimal phases for this base
+  const existing = roadmapData.phases
+    .filter(p => Math.floor(p.number) === base && p.number !== base)
+    .map(p => p.number);
+
+  // Calculate next decimal
+  let nextDecimal;
+  if (existing.length === 0) {
+    nextDecimal = base + 0.1;
+  } else {
+    const maxExisting = Math.max(...existing);
+    nextDecimal = Math.round((maxExisting + 0.1) * 10) / 10;
+  }
+
+  const newPhase = {
+    number: nextDecimal,
+    name: phaseDef.name,
+    goal: phaseDef.goal,
+    dependsOn: [afterNumber],
+    requirements: phaseDef.requirements || [],
+    plans: phaseDef.plans || '',
+    status: phaseDef.status || 'Pending'
+  };
+
+  const phases = [...roadmapData.phases, newPhase];
+  phases.sort((a, b) => a.number - b.number);
+
+  return { overview: roadmapData.overview, phases };
+}
+
+/**
+ * Remove a phase from the roadmap.
+ * @param {{ overview: string, phases: Array }} roadmapData
+ * @param {number} number - Phase number to remove
+ * @returns {{ roadmap: { overview: string, phases: Array }, orphanedRequirements: string[] }}
+ */
+function removePhase(roadmapData, number) {
+  const removed = roadmapData.phases.find(p => p.number === number);
+  const orphanedRequirements = removed ? removed.requirements : [];
+
+  const phases = roadmapData.phases
+    .filter(p => p.number !== number)
+    .map(p => {
+      // Update depends_on: remove references to deleted phase
+      const dependsOn = p.dependsOn.filter(d => d !== number);
+      return { ...p, dependsOn };
+    });
+
+  return { roadmap: { overview: roadmapData.overview, phases }, orphanedRequirements };
+}
+
+/**
+ * Reorder phases by providing the new order of original phase numbers.
+ * Renumbers all phases sequentially and updates depends_on references.
+ * @param {{ overview: string, phases: Array }} roadmapData
+ * @param {number[]} newOrder - Array of original phase numbers in desired order
+ * @returns {{ overview: string, phases: Array }}
+ */
+function reorderPhases(roadmapData, newOrder) {
+  // Build mapping: old number -> new number (1-based sequential)
+  const numberMap = {};
+  for (let i = 0; i < newOrder.length; i++) {
+    numberMap[newOrder[i]] = i + 1;
+  }
+
+  // Reorder and renumber
+  const phases = newOrder.map((oldNum, i) => {
+    const phase = roadmapData.phases.find(p => p.number === oldNum);
+    if (!phase) return null;
+
+    const dependsOn = phase.dependsOn
+      .map(d => numberMap[d])
+      .filter(d => d !== undefined);
+
+    return {
+      ...phase,
+      number: i + 1,
+      dependsOn
+    };
+  }).filter(Boolean);
+
+  return { overview: roadmapData.overview, phases };
+}
+
+module.exports = {
+  parseRoadmap,
+  writeRoadmap,
+  insertPhase,
+  removePhase,
+  reorderPhases
+};