dual-brain 0.1.22 → 0.2.0

package/src/ledger.mjs

@@ -0,0 +1,196 @@
+// Task ledger: append-only accountability store for HEAD's promises. Every tracked task has a full snapshot per state change.
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const LEDGER_PATH = '.dual-brain/ledger.jsonl';
+
+function ledgerPath(cwd) {
+  return join(cwd || process.cwd(), LEDGER_PATH);
+}
+
+function readAllEntries(cwd) {
+  const p = ledgerPath(cwd);
+  if (!existsSync(p)) return [];
+  const raw = readFileSync(p, 'utf8').trim();
+  if (!raw) return [];
+  return raw.split('\n').map(line => JSON.parse(line));
+}
+
+function appendEntry(entry, cwd) {
+  const p = ledgerPath(cwd);
+  mkdirSync(join(cwd || process.cwd(), '.dual-brain'), { recursive: true });
+  writeFileSync(p, JSON.stringify(entry) + '\n', { flag: 'a' });
+}
+
+function getCurrentTasks(cwd) {
+  const entries = readAllEntries(cwd);
+  const map = new Map();
+  for (const entry of entries) {
+    map.set(entry.id, entry);
+  }
+  return Array.from(map.values());
+}
+
+export function createTask(task, cwd) {
+  const entry = {
+    id: `task_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+    created: new Date().toISOString(),
+    updated: new Date().toISOString(),
+    intent: task.intent || '',
+    status: 'open',
+    owner: task.owner || 'head',
+    priority: task.priority || 'medium',
+    blockers: task.blockers || [],
+    proof: task.proof || null,
+    subtasks: task.subtasks || [],
+    parentTask: task.parentTask || null,
+    files: task.files || [],
+    result: task.result || null,
+    cost: task.cost || null,
+  };
+  appendEntry(entry, cwd);
+  return entry;
+}
+
+export function updateTask(taskId, updates, cwd) {
+  const current = getTask(taskId, cwd);
+  if (!current) throw new Error(`Task not found: ${taskId}`);
+
+  if (updates.status === 'done') {
+    const proof = updates.proof ?? current.proof;
+    const result = updates.result ?? current.result;
+    if (!proof) throw new Error(`Cannot mark task done without proof: ${taskId}`);
+    if (!result) throw new Error(`Cannot mark task done without result: ${taskId}`);
+  }
+
+  const updated = {
+    ...current,
+    ...updates,
+    id: taskId,
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updated, cwd);
+  return updated;
+}
+
+export function failTask(taskId, reason, cwd) {
+  const current = getTask(taskId, cwd);
+  if (!current) throw new Error(`Task not found: ${taskId}`);
+  const updated = {
+    ...current,
+    status: 'failed',
+    result: reason || 'failed',
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updated, cwd);
+  return updated;
+}
+
+export function blockTask(taskId, blocker, cwd) {
+  const current = getTask(taskId, cwd);
+  if (!current) throw new Error(`Task not found: ${taskId}`);
+  const updated = {
+    ...current,
+    status: 'blocked',
+    blockers: [...(current.blockers || []), blocker],
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updated, cwd);
+  return updated;
+}
+
+export function getTask(taskId, cwd) {
+  const entries = readAllEntries(cwd);
+  let latest = null;
+  for (const entry of entries) {
+    if (entry.id === taskId) latest = entry;
+  }
+  return latest;
+}
+
+export function getOpenTasks(cwd) {
+  return getCurrentTasks(cwd).filter(t =>
+    t.status === 'open' || t.status === 'in_progress' || t.status === 'blocked'
+  );
+}
+
+export function getTaskHistory(taskId, cwd) {
+  return readAllEntries(cwd).filter(e => e.id === taskId);
+}
+
+export function getTaskSummary(cwd) {
+  const tasks = getCurrentTasks(cwd);
+  const summary = { open: 0, inProgress: 0, blocked: 0, done: 0, failed: 0, total: tasks.length };
+  for (const t of tasks) {
+    if (t.status === 'open') summary.open++;
+    else if (t.status === 'in_progress') summary.inProgress++;
+    else if (t.status === 'blocked') summary.blocked++;
+    else if (t.status === 'done') summary.done++;
+    else if (t.status === 'failed') summary.failed++;
+  }
+  return summary;
+}
+
+export function formatTaskList(tasks) {
+  const all = tasks;
+  const open = all.filter(t => t.status === 'open' || t.status === 'in_progress').length;
+  const blocked = all.filter(t => t.status === 'blocked').length;
+  const done = all.filter(t => t.status === 'done').length;
+
+  const lines = [`TASKS (${open} open, ${blocked} blocked, ${done} done)`];
+
+  for (const t of all) {
+    const pri = t.priority === 'critical' ? 'crit' : t.priority === 'high' ? 'high' : t.priority === 'low' ? 'low' : 'med';
+    const label = t.intent.length > 48 ? t.intent.slice(0, 45) + '...' : t.intent;
+
+    if (t.status === 'done') {
+      lines.push(`  ✓ [${pri}]  ${label} (done)`);
+    } else if (t.status === 'failed') {
+      lines.push(`  ✗ [${pri}]  ${label} (failed)`);
+    } else if (t.status === 'blocked') {
+      const blockerNote = t.blockers && t.blockers.length ? `: ${t.blockers[t.blockers.length - 1]}` : '';
+      lines.push(`  ◌ [${pri}]  ${label} (blocked${blockerNote})`);
+    } else {
+      lines.push(`  ● [${pri}]  ${label} (${t.status})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function reconcile(cwd) {
+  const tasks = getCurrentTasks(cwd);
+  const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+  return tasks.filter(t =>
+    (t.status === 'open' || t.status === 'in_progress') &&
+    new Date(t.updated).getTime() < cutoff
+  );
+}
+
+export function decompose(taskId, subtasks, cwd) {
+  const parent = getTask(taskId, cwd);
+  if (!parent) throw new Error(`Task not found: ${taskId}`);
+
+  const created = subtasks.map(sub =>
+    createTask(
+      {
+        ...sub,
+        parentTask: taskId,
+        owner: sub.owner || parent.owner,
+        priority: sub.priority || parent.priority,
+      },
+      cwd
+    )
+  );
+
+  const subtaskIds = created.map(s => s.id);
+  const updatedParent = {
+    ...parent,
+    subtasks: [...(parent.subtasks || []), ...subtaskIds],
+    updated: new Date().toISOString(),
+  };
+  appendEntry(updatedParent, cwd);
+
+  return { parent: updatedParent, subtasks: created };
+}

package/src/living-docs.mjs

@@ -0,0 +1,210 @@
+// living-docs.mjs — Living document system for .dual-brain/.
+// Manages project.json, vision.md, roadmap.md, state.md, actions.jsonl, decisions.jsonl, checkpoints.jsonl.
+
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const DIR = '.dual-brain';
+
+function docsDir(cwd = process.cwd()) {
+  return join(cwd, DIR);
+}
+
+function ensureDir(cwd) {
+  mkdirSync(docsDir(cwd), { recursive: true });
+}
+
+function filePath(name, cwd) {
+  return join(docsDir(cwd), name);
+}
+
+function readFileSafe(name, cwd, fallback = '') {
+  try {
+    return readFileSync(filePath(name, cwd), 'utf8');
+  } catch {
+    return fallback;
+  }
+}
+
+function readJsonSafe(name, cwd, fallback = {}) {
+  try {
+    return JSON.parse(readFileSync(filePath(name, cwd), 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function readPackageJson(cwd) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function gitExec(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+  } catch {
+    return null;
+  }
+}
+
+export function initLivingDocs(cwd = process.cwd()) {
+  const dir = docsDir(cwd);
+  const existed = existsSync(dir);
+  ensureDir(cwd);
+
+  const pkg = readPackageJson(cwd);
+
+  if (!existsSync(filePath('project.json', cwd))) {
+    const project = {
+      name: pkg.name ?? '',
+      version: pkg.version ?? '0.0.1',
+      created: new Date().toISOString(),
+      workStyle: 'balanced',
+      userCalibration: { specificity: 3, corrections: 3, autonomy: 3 },
+      team: [],
+      providers: {},
+    };
+    writeFileSync(filePath('project.json', cwd), JSON.stringify(project, null, 2));
+  }
+
+  if (!existsSync(filePath('vision.md', cwd))) {
+    writeFileSync(filePath('vision.md', cwd), '# Vision\n\n_Not yet defined. Type your vision and HEAD will maintain this document._\n');
+  }
+
+  if (!existsSync(filePath('roadmap.md', cwd))) {
+    writeFileSync(filePath('roadmap.md', cwd), '# Roadmap\n\n_No roadmap yet. As you work, HEAD will build this from your actions._\n');
+  }
+
+  if (!existsSync(filePath('state.md', cwd))) {
+    writeFileSync(filePath('state.md', cwd), '# Current State\n\n_Fresh project. No history yet._\n');
+  }
+
+  for (const log of ['actions.jsonl', 'decisions.jsonl', 'checkpoints.jsonl']) {
+    if (!existsSync(filePath(log, cwd))) {
+      writeFileSync(filePath(log, cwd), '');
+    }
+  }
+
+  return { created: !existed, path: dir };
+}
+
+export function appendAction(action, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const entry = {
+    id: `act_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+    timestamp: new Date().toISOString(),
+    type: 'task',
+    intent: '',
+    status: 'started',
+    owner: 'head',
+    files: [],
+    proof: null,
+    cost: null,
+    result: null,
+    ...action,
+  };
+  appendFileSync(filePath('actions.jsonl', cwd), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function appendDecision(decision, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const entry = {
+    id: `dec_${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    question: '',
+    decision: '',
+    reasoning: '',
+    participants: [],
+    supersedes: null,
+    ...decision,
+  };
+  appendFileSync(filePath('decisions.jsonl', cwd), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function createCheckpoint(summary, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const gitRef = gitExec('git rev-parse HEAD', cwd) ?? 'unknown';
+  const branch = gitExec('git rev-parse --abbrev-ref HEAD', cwd) ?? 'unknown';
+  const stateSnapshot = readFileSafe('state.md', cwd, '');
+  const entry = {
+    id: `cp_${Date.now()}`,
+    timestamp: new Date().toISOString(),
+    gitRef,
+    branch,
+    summary,
+    stateSnapshot,
+  };
+  appendFileSync(filePath('checkpoints.jsonl', cwd), JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function updateState(newContent, cwd = process.cwd()) {
+  ensureDir(cwd);
+  writeFileSync(filePath('state.md', cwd), newContent);
+}
+
+export function updateRoadmap(newContent, cwd = process.cwd()) {
+  ensureDir(cwd);
+  writeFileSync(filePath('roadmap.md', cwd), newContent);
+}
+
+export function updateVision(newContent, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const prev = readFileSafe('vision.md', cwd, '');
+  writeFileSync(filePath('vision.md', cwd), newContent);
+  if (prev !== newContent) {
+    appendDecision({
+      question: 'What is the project vision?',
+      decision: newContent.slice(0, 200),
+      reasoning: 'Vision document updated.',
+      participants: ['head'],
+      supersedes: null,
+    }, cwd);
+  }
+}
+
+export function getProjectState(cwd = process.cwd()) {
+  const project = readJsonSafe('project.json', cwd, {});
+  const state = readFileSafe('state.md', cwd, '');
+  const actions = getRecentActions(cwd, 20);
+  const decisions = readLastLines('decisions.jsonl', cwd, 5);
+  const checkpoints = readLastLines('checkpoints.jsonl', cwd, 1);
+  return {
+    project,
+    state,
+    recentActions: actions,
+    recentDecisions: decisions,
+    lastCheckpoint: checkpoints[0] ?? null,
+  };
+}
+
+function readLastLines(name, cwd, n) {
+  const raw = readFileSafe(name, cwd, '');
+  const lines = raw.split('\n').filter(l => l.trim());
+  return lines.slice(-n).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+export function getRecentActions(cwd = process.cwd(), limit = 20) {
+  return readLastLines('actions.jsonl', cwd, limit);
+}
+
+export function getOpenTasks(cwd = process.cwd()) {
+  const raw = readFileSafe('actions.jsonl', cwd, '');
+  const lines = raw.split('\n').filter(l => l.trim());
+  const entries = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  return entries.filter(e => e.status === 'started' || e.status === 'blocked');
+}
+
+export function updateProject(updates, cwd = process.cwd()) {
+  ensureDir(cwd);
+  const current = readJsonSafe('project.json', cwd, {});
+  const merged = { ...current, ...updates };
+  writeFileSync(filePath('project.json', cwd), JSON.stringify(merged, null, 2));
+  return merged;
+}