brain-dev 0.1.2 → 0.2.0

package/bin/lib/dashboard-collector.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState } = require('./state.cjs');
+const { readMetrics, checkBudget } = require('./cost.cjs');
+const { readBridge } = require('./bridge.cjs');
+const { readLock, isLockStale } = require('./lock.cjs');
+const { tailLog } = require('./logger.cjs');
+const { checkTimeouts, detectProgress } = require('./stuck.cjs');
+
+/**
+ * Collect a full DashboardState snapshot from all data sources.
+ * Safe: all reads are wrapped so a single source failure does not
+ * break the entire snapshot.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @returns {object} DashboardState snapshot
+ */
+function collectState(brainDir) {
+  const state = safeRead(() => readState(brainDir), {});
+  const metrics = safeRead(() => readMetrics(brainDir), { totals: {} });
+  const contextBridge = readBridge(brainDir, 'context');
+  const stuckBridge = readBridge(brainDir, 'stuck');
+  const lock = readLock(brainDir);
+  const currentPhase = state.phase?.current || 1;
+  const events = safeRead(() => tailLog(brainDir, currentPhase, null), []);
+  const budgetStatus = safeRead(() => checkBudget(metrics), { status: 'ok', spent: 0 });
+  const timeoutStatus = safeRead(() => checkTimeouts(brainDir, state), { tier: 'none' });
+
+  return {
+    timestamp: new Date().toISOString(),
+    project: {
+      name: state.project?.name || 'Unknown',
+      mode: state.mode || 'interactive',
+      depth: state.depth || 'standard'
+    },
+    milestone: state.milestone || { current: 'v1.0' },
+    phases: {
+      current: currentPhase,
+      total: state.phase?.total || 0,
+      status: state.phase?.status || 'initialized',
+      list: (state.phase?.phases || []).map(p => ({
+        number: p.number || p,
+        name: p.name || `Phase ${p.number || p}`,
+        status: p.status || 'pending'
+      }))
+    },
+    auto: {
+      active: state.auto?.active || false,
+      started_at: state.auto?.started_at || null,
+      current_step: state.auto?.current_step || null,
+      phases_completed: state.auto?.phases_completed || 0
+    },
+    timing: {
+      phaseStart: state.phase?.execution_started_at || null,
+      phaseElapsed: state.phase?.execution_started_at
+        ? Math.round((Date.now() - new Date(state.phase.execution_started_at).getTime()) / 1000)
+        : 0
+    },
+    context: {
+      remainingPct: contextBridge?.remaining_pct || null,
+      level: contextBridge?.level || 'unknown'
+    },
+    cost: {
+      spent: metrics.totals?.estimated_cost_usd || 0,
+      ceiling: state.budget?.ceiling_usd || null,
+      pctUsed: budgetStatus.pct_used || 0,
+      status: budgetStatus.status || 'ok'
+    },
+    stuck: {
+      detected: stuckBridge?.timeout_tier === 'soft' ||
+                stuckBridge?.timeout_tier === 'idle' ||
+                stuckBridge?.timeout_tier === 'hard',
+      tier: stuckBridge?.timeout_tier || timeoutStatus.tier || 'none',
+      message: stuckBridge?.message || timeoutStatus.message || null,
+      idleMinutes: stuckBridge?.idle_minutes || 0
+    },
+    lock: {
+      active: !!lock,
+      operation: lock?.operation || null,
+      stale: lock ? isLockStale(lock).stale : false
+    },
+    events: events.slice(-50),
+    health: { stateValid: !!state.$schema }
+  };
+}
+
+/**
+ * Safely invoke a reader function, returning fallback on any error.
+ * @param {Function} fn - Reader function
+ * @param {*} fallback - Value to return on failure
+ * @returns {*}
+ */
+function safeRead(fn, fallback) {
+  try { return fn(); } catch { return fallback; }
+}
+
+module.exports = { collectState };

package/bin/lib/dashboard-server.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+// Dashboard web server - WebSocket-based real-time dashboard
+// Full implementation deferred - TUI mode (dashboard.cjs) is the primary interface
+
+const http = require('node:http');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Start a WebSocket-based dashboard server.
+ * TODO: Implement following storm.cjs pattern (parseFrame, buildFrame, findAvailablePort).
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {number} port - Port to listen on
+ * @param {boolean} autoOpen - Whether to open browser automatically
+ * @throws {Error} Always — not yet implemented
+ */
+async function startDashboardServer(brainDir, port, autoOpen) {
+  // TODO: Implement WebSocket server following storm.cjs pattern
+  // For now, return a stub
+  throw new Error('Web dashboard not yet implemented. Use brain-dev dashboard (TUI mode) instead.');
+}
+
+/**
+ * Stop a running dashboard server by removing its port file.
+ * @param {string} brainDir - Path to .brain/ directory
+ */
+function stopDashboardServer(brainDir) {
+  const portFile = path.join(brainDir, '.dashboard-port');
+  try { fs.unlinkSync(portFile); } catch {}
+}
+
+module.exports = { startDashboardServer, stopDashboardServer };

package/bin/lib/hook-dispatcher.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+const { readState } = require('./state.cjs');
+const { readBridge, writeBridge } = require('./bridge.cjs');
+const { checkTimeouts, updateStuckBridge } = require('./stuck.cjs');
+const { readLock } = require('./lock.cjs');
+const { readMetrics } = require('./cost.cjs');
+
+/**
+ * Handle StatusLine hook — aggregate state into a compact status string.
+ * Called on every status line refresh by the hook system.
+ * @param {object|null} inputJson - Parsed input from the hook (may contain context_window)
+ * @param {string} brainDir - Path to .brain/ directory
+ * @returns {string} Formatted status line text
+ */
+function onStatusLine(inputJson, brainDir) {
+  const state = readState(brainDir);
+  const results = {};
+
+  // 1. Context monitoring — determine level and persist to bridge
+  results.context = {
+    remaining_pct: inputJson?.context_window?.remaining_percentage || null,
+    level: determineContextLevel(inputJson?.context_window?.remaining_percentage)
+  };
+  writeBridge(brainDir, 'context', results.context);
+
+  // 2. Stuck detection — update bridge when phase is active
+  if (state.phase?.status === 'executing' || state.phase?.status === 'verifying') {
+    updateStuckBridge(brainDir, state);
+  }
+
+  // 3. Cost summary for statusline
+  try {
+    const metrics = readMetrics(brainDir);
+    results.cost = {
+      spent: metrics.totals?.estimated_cost_usd || 0,
+      ceiling: state.budget?.ceiling_usd || null
+    };
+  } catch {
+    results.cost = null;
+  }
+
+  // 4. Lock status
+  const lock = readLock(brainDir);
+  results.lock = lock
+    ? { active: true, operation: lock.operation }
+    : { active: false };
+
+  // Build statusline text
+  const parts = [];
+  parts.push('brain');
+  if (state.phase) parts.push(`P${state.phase.current}: ${state.phase.status}`);
+  if (results.cost?.spent > 0) {
+    let costStr = `$${results.cost.spent.toFixed(2)}`;
+    if (results.cost.ceiling) costStr += `/$${results.cost.ceiling}`;
+    parts.push(costStr);
+  }
+  if (lock) parts.push('auto');
+
+  return parts.join(' | ');
+}
+
+/**
+ * Handle PostToolUse hook — return warnings that should be injected.
+ * Called after each tool use by the hook system.
+ * @param {string} brainDir - Path to .brain/ directory
+ * @returns {string[]} Array of warning messages (may be empty)
+ */
+function onPostToolUse(brainDir) {
+  const warnings = [];
+
+  // Check stuck detection bridge
+  const stuckBridge = readBridge(brainDir, 'stuck');
+  if (stuckBridge?.message && stuckBridge.timeout_tier !== 'none') {
+    warnings.push(stuckBridge.message);
+  }
+
+  // Check context bridge
+  const contextBridge = readBridge(brainDir, 'context');
+  if (contextBridge?.level === 'critical') {
+    warnings.push('[brain] Context window critically low. Consider /brain:pause to save progress.');
+  }
+
+  return warnings;
+}
+
+/**
+ * Determine context window health level from remaining percentage.
+ * @param {number|null|undefined} remainingPct
+ * @returns {'normal'|'warning'|'critical'|'unknown'}
+ */
+function determineContextLevel(remainingPct) {
+  if (remainingPct === null || remainingPct === undefined) return 'unknown';
+  if (remainingPct <= 25) return 'critical';
+  if (remainingPct <= 50) return 'warning';
+  return 'normal';
+}
+
+module.exports = { onStatusLine, onPostToolUse, determineContextLevel };

package/bin/lib/lock.cjs

@@ -0,0 +1,163 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { atomicWriteSync } = require('./state.cjs');
+
+const LOCK_FILE = '.auto.lock';
+const DEFAULT_STALE_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Acquire the auto lock. Creates .brain/.auto.lock atomically.
+ * If a stale lock exists, it is cleared and re-acquired.
+ * @param {string} brainDir - Path to .brain/
+ * @param {object} context - { phase, plan, operation, agent }
+ * @returns {{ acquired: boolean, staleRecovered: boolean, previousLock: object|null }}
+ */
+function acquireLock(brainDir, context) {
+  const lockPath = path.join(brainDir, LOCK_FILE);
+  const existing = readLock(brainDir);
+
+  if (existing) {
+    const { stale } = isLockStale(existing);
+    if (!stale) {
+      return { acquired: false, staleRecovered: false, previousLock: existing };
+    }
+    // Stale lock — back it up and clear
+    clearStaleLock(brainDir);
+  }
+
+  const lockData = {
+    pid: process.pid,
+    sessionId: new Date().toISOString().replace(/:/g, '-').slice(0, 19),
+    phase: context.phase || null,
+    plan: context.plan || null,
+    operation: context.operation || null,
+    agent: context.agent || null,
+    acquiredAt: new Date().toISOString(),
+    heartbeat: new Date().toISOString()
+  };
+
+  atomicWriteSync(lockPath, JSON.stringify(lockData, null, 2));
+  return { acquired: true, staleRecovered: !!existing, previousLock: existing || null };
+}
+
+/**
+ * Release the lock. Only releases if PID matches current process.
+ * @param {string} brainDir
+ * @returns {boolean} true if released
+ */
+function releaseLock(brainDir) {
+  const lockPath = path.join(brainDir, LOCK_FILE);
+  const existing = readLock(brainDir);
+  if (!existing) return false;
+  if (existing.pid !== process.pid) return false;
+  try {
+    fs.unlinkSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the current lock file without modifying it.
+ * @param {string} brainDir
+ * @returns {object|null} Lock data or null
+ */
+function readLock(brainDir) {
+  try {
+    const lockPath = path.join(brainDir, LOCK_FILE);
+    return JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a lock is stale. Uses dual check: PID alive AND heartbeat fresh.
+ * @param {object} lockData - Parsed lock contents
+ * @param {number} [thresholdMs] - Staleness threshold (default 5 min)
+ * @returns {{ stale: boolean, reason: string }}
+ */
+function isLockStale(lockData, thresholdMs = DEFAULT_STALE_THRESHOLD_MS) {
+  if (!lockData || !lockData.pid) return { stale: true, reason: 'Invalid lock data' };
+
+  // Check 1: Is the PID still alive?
+  try {
+    process.kill(lockData.pid, 0); // Signal 0 = existence check
+  } catch (e) {
+    if (e.code === 'ESRCH') {
+      return { stale: true, reason: `PID ${lockData.pid} is not running` };
+    }
+    // EPERM means process exists but we can't signal it — treat as alive
+  }
+
+  // Check 2: Is the heartbeat fresh?
+  if (lockData.heartbeat) {
+    const heartbeatAge = Date.now() - new Date(lockData.heartbeat).getTime();
+    if (heartbeatAge > thresholdMs) {
+      return { stale: true, reason: `Heartbeat ${Math.round(heartbeatAge / 1000)}s old (threshold: ${Math.round(thresholdMs / 1000)}s)` };
+    }
+  }
+
+  return { stale: false, reason: '' };
+}
+
+/**
+ * Update heartbeat timestamp in the lock file.
+ * Only updates if lock is owned by current process.
+ * @param {string} brainDir
+ * @returns {boolean} true if updated
+ */
+function heartbeat(brainDir) {
+  const lockPath = path.join(brainDir, LOCK_FILE);
+  const existing = readLock(brainDir);
+  if (!existing || existing.pid !== process.pid) return false;
+  existing.heartbeat = new Date().toISOString();
+  try {
+    atomicWriteSync(lockPath, JSON.stringify(existing, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Force-remove a stale lock. Backs up to .auto.lock.stale first.
+ * @param {string} brainDir
+ * @returns {object|null} The stale lock data that was removed
+ */
+function clearStaleLock(brainDir) {
+  const lockPath = path.join(brainDir, LOCK_FILE);
+  const stalePath = lockPath + '.stale';
+  const existing = readLock(brainDir);
+  if (!existing) return null;
+  try {
+    // Backup stale lock for forensics
+    fs.copyFileSync(lockPath, stalePath);
+    fs.unlinkSync(lockPath);
+  } catch { /* best effort */ }
+  return existing;
+}
+
+/**
+ * Check if a lock currently exists (any state).
+ * @param {string} brainDir
+ * @returns {boolean}
+ */
+function isLocked(brainDir) {
+  return fs.existsSync(path.join(brainDir, LOCK_FILE));
+}
+
+module.exports = {
+  acquireLock,
+  releaseLock,
+  readLock,
+  isLockStale,
+  heartbeat,
+  clearStaleLock,
+  isLocked,
+  LOCK_FILE,
+  DEFAULT_STALE_THRESHOLD_MS
+};

package/bin/lib/logger.cjs

@@ -57,6 +57,23 @@ function readLog(brainDir, phaseNumber) {
   }, []);
 }
 
+/**
+ * Read log events newer than a given timestamp.
+ * Efficient: reads from end of file to avoid full-file scans.
+ * @param {string} brainDir
+ * @param {number} phaseNumber
+ * @param {string} [afterTimestamp] - ISO timestamp; returns events after this time. If null, returns last 20 events.
+ * @returns {Array<object>}
+ */
+function tailLog(brainDir, phaseNumber, afterTimestamp) {
+  const events = readLog(brainDir, phaseNumber);
+  if (!afterTimestamp) {
+    return events.slice(-20);
+  }
+  const afterTime = new Date(afterTimestamp).getTime();
+  return events.filter(e => e.timestamp && new Date(e.timestamp).getTime() > afterTime);
+}
+
 /**
  * Archive a phase log and clean up old archives beyond keepLast.
  *
@@ -96,5 +113,6 @@ function archiveLogs(brainDir, phaseNumber, keepLast = 3) {
 module.exports = {
   logEvent,
   readLog,
+  tailLog,
   archiveLogs
 };