dual-brain 0.2.7 → 0.2.9

package/src/integrity.mjs

@@ -0,0 +1,245 @@
+/**
+ * integrity.mjs — State integrity primitives for dual-brain
+ *
+ * Provides:
+ *   - atomicWriteJson / readJsonSafe   — safe JSON file I/O with schema versioning
+ *   - acquireLock / releaseLock / withLock — advisory file locks
+ *   - lockedUpdate                      — locked atomic read-modify-write
+ *   - atomicAppend                      — append-only ledger with lock
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// 1. Atomic JSON writes
+// ---------------------------------------------------------------------------
+
+/**
+ * Write JSON to filePath atomically via a temp file + rename.
+ * Adds _schemaVersion and _writtenAt to plain objects.
+ *
+ * @param {string} filePath  - Destination file path
+ * @param {*}      data      - Value to serialize
+ * @param {object} opts
+ * @param {number} [opts.schemaVersion=1] - Schema version stamped into data
+ * @param {boolean}[opts.backup=false]    - Keep a .bak copy of the previous file
+ */
+export function atomicWriteJson(filePath, data, opts = {}) {
+  const { schemaVersion = 1, backup = false } = opts;
+
+  // Stamp schema version onto plain objects
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    data._schemaVersion = schemaVersion;
+    data._writtenAt = new Date().toISOString();
+  }
+
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+
+  const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  const json = JSON.stringify(data, null, 2) + '\n';
+
+  // Write to temp file
+  writeFileSync(tmpPath, json);
+
+  // Validate the temp file is parseable before committing
+  try {
+    JSON.parse(readFileSync(tmpPath, 'utf8'));
+  } catch (err) {
+    unlinkSync(tmpPath);
+    throw new Error(`atomicWrite: validation failed for ${filePath}: ${err.message}`);
+  }
+
+  // Optionally back up the existing file
+  if (backup && existsSync(filePath)) {
+    const backupPath = filePath + '.bak';
+    try { renameSync(filePath, backupPath); } catch {}
+  }
+
+  // Atomic rename — either fully succeeds or the original is untouched
+  renameSync(tmpPath, filePath);
+}
+
+/**
+ * Read and parse a JSON file safely, with optional schema migration.
+ * Falls back to a .bak copy on parse failure.
+ * Returns null when the file is absent or unrecoverable.
+ *
+ * @param {string}   filePath
+ * @param {object}   opts
+ * @param {number}  [opts.expectedVersion]  - Schema version to verify
+ * @param {Function}[opts.migrate]           - (data, fromVersion, toVersion) => data
+ * @returns {*|null}
+ */
+export function readJsonSafe(filePath, opts = {}) {
+  const { expectedVersion, migrate } = opts;
+
+  if (!existsSync(filePath)) return null;
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    // Primary file corrupt — try backup
+    const bakPath = filePath + '.bak';
+    if (existsSync(bakPath)) {
+      try {
+        data = JSON.parse(readFileSync(bakPath, 'utf8'));
+      } catch { return null; }
+    } else {
+      return null;
+    }
+  }
+
+  // Schema version check with optional migration
+  if (expectedVersion !== undefined && data?._schemaVersion !== expectedVersion) {
+    if (migrate && typeof migrate === 'function') {
+      data = migrate(data, data?._schemaVersion, expectedVersion);
+    }
+    // Tolerant read: return data even without a migrator
+  }
+
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Advisory file locks
+// ---------------------------------------------------------------------------
+
+const LOCK_TIMEOUT_MS = 10_000; // stale lock threshold
+const LOCK_RETRY_MS   = 50;     // busy-wait interval
+const LOCK_MAX_RETRIES = 100;   // max retries (~5 s)
+
+/**
+ * Acquire an advisory lock for filePath by creating filePath.lock.
+ * Stale locks (> LOCK_TIMEOUT_MS old) are cleared automatically.
+ *
+ * @param {string} filePath
+ * @returns {{ acquired: boolean, lockPath: string, reason?: string }}
+ */
+export function acquireLock(filePath) {
+  const lockPath = filePath + '.lock';
+
+  // Clear stale or corrupt lock
+  if (existsSync(lockPath)) {
+    try {
+      const lockData = JSON.parse(readFileSync(lockPath, 'utf8'));
+      const age = Date.now() - (lockData.createdAt || 0);
+      if (age > LOCK_TIMEOUT_MS) {
+        unlinkSync(lockPath);
+      }
+    } catch {
+      try { unlinkSync(lockPath); } catch {}
+    }
+  }
+
+  // Spin-try to create the lock exclusively
+  let retries = 0;
+  while (retries < LOCK_MAX_RETRIES) {
+    try {
+      writeFileSync(lockPath, JSON.stringify({
+        pid: process.pid,
+        createdAt: Date.now(),
+        holder: process.argv[1] || 'unknown',
+      }), { flag: 'wx' }); // 'wx' = exclusive create, EEXIST if present
+      return { acquired: true, lockPath };
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        retries++;
+        // Synchronous busy-wait — intentional; only triggered under contention
+        const start = Date.now();
+        while (Date.now() - start < LOCK_RETRY_MS) {}
+        continue;
+      }
+      throw err; // Unexpected error — propagate
+    }
+  }
+
+  return { acquired: false, lockPath, reason: 'timeout' };
+}
+
+/**
+ * Release a previously acquired lock.
+ *
+ * @param {{ lockPath?: string }} lockResult - Return value of acquireLock
+ */
+export function releaseLock(lockResult) {
+  if (lockResult?.lockPath) {
+    try { unlinkSync(lockResult.lockPath); } catch {}
+  }
+}
+
+/**
+ * Run fn while holding an advisory lock on filePath.
+ * Throws if the lock cannot be acquired within the retry window.
+ *
+ * @param {string}   filePath
+ * @param {Function} fn
+ * @returns {*} Return value of fn
+ */
+export function withLock(filePath, fn) {
+  const lock = acquireLock(filePath);
+  if (!lock.acquired) {
+    throw new Error(`Could not acquire lock for ${filePath}: ${lock.reason}`);
+  }
+  try {
+    return fn();
+  } finally {
+    releaseLock(lock);
+  }
+}
+
+/**
+ * Locked atomic read-modify-write.
+ * Reads the current JSON, passes it to updateFn, then writes the result.
+ * If updateFn returns undefined the file is left unchanged.
+ *
+ * @param {string}   filePath
+ * @param {Function} updateFn   - (currentData: *|null) => updatedData | undefined
+ * @param {object}   opts       - Forwarded to readJsonSafe and atomicWriteJson
+ * @returns {*} Return value of updateFn
+ */
+export function lockedUpdate(filePath, updateFn, opts = {}) {
+  return withLock(filePath, () => {
+    const current = readJsonSafe(filePath, opts);
+    const updated = updateFn(current);
+    if (updated !== undefined) {
+      atomicWriteJson(filePath, updated, opts);
+    }
+    return updated;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 3. Append-only ledger with lock
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a NDJSON record to filePath under an advisory lock.
+ * On lock failure the write is attempted without a lock (best-effort).
+ *
+ * @param {string} filePath
+ * @param {*}      record   - Value to serialize as one JSON line
+ */
+export async function atomicAppend(filePath, record) {
+  const { appendFileSync } = await import('node:fs');
+  const line = JSON.stringify(record) + '\n';
+
+  const lock = acquireLock(filePath);
+  if (!lock.acquired) {
+    // Non-fatal: best-effort append without lock
+    try {
+      mkdirSync(dirname(filePath), { recursive: true });
+      appendFileSync(filePath, line);
+    } catch {}
+    return;
+  }
+
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    appendFileSync(filePath, line);
+  } finally {
+    releaseLock(lock);
+  }
+}

package/src/profile.mjs

@@ -26,7 +26,7 @@
  */
 
 import { createInterface } from 'readline';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { execSync } from 'child_process';
@@ -188,6 +188,71 @@ async function detectCapabilities(cwd) {
   const checkpointsBin = existsSync(join(replitToolsDir, 'checkpoints'))
     || existsSync('/usr/local/bin/replit-checkpoint');
 
+  // --- MCP servers: check Claude settings files ---
+  let mcpServers = [];
+  try {
+    const claudeSettings = join(homedir(), '.claude', 'settings.json');
+    if (existsSync(claudeSettings)) {
+      const settings = JSON.parse(readFileSync(claudeSettings, 'utf8'));
+      if (settings.mcpServers) {
+        mcpServers = Object.keys(settings.mcpServers);
+      }
+    }
+    // Also check project-local
+    const localSettings = join(root, '.claude', 'settings.json');
+    if (existsSync(localSettings)) {
+      const local = JSON.parse(readFileSync(localSettings, 'utf8'));
+      if (local.mcpServers) {
+        mcpServers.push(...Object.keys(local.mcpServers));
+      }
+    }
+  } catch {}
+
+  // --- Claude plugins: check installed plugin marketplaces ---
+  let claudePlugins = [];
+  try {
+    const pluginDir = join(root, '.replit-tools', '.claude-persistent', 'plugins', 'marketplaces');
+    if (existsSync(pluginDir)) {
+      const marketplaces = readdirSync(pluginDir);
+      for (const m of marketplaces) {
+        const mDir = join(pluginDir, m, 'plugins');
+        if (existsSync(mDir)) {
+          claudePlugins.push(...readdirSync(mDir));
+        }
+      }
+    }
+  } catch {}
+
+  // --- Codex plugins: check available plugins ---
+  let codexPlugins = [];
+  try {
+    const pluginDir = join(root, '.replit-tools', '.codex-persistent', '.tmp', 'plugins', 'plugins');
+    if (existsSync(pluginDir)) {
+      codexPlugins = readdirSync(pluginDir).filter(f => !f.startsWith('.'));
+    }
+  } catch {}
+
+  // --- Shell snapshots: count .sh files ---
+  let shellSnapshots = 0;
+  try {
+    const snapDir = join(root, '.replit-tools', '.claude-persistent', 'shell-snapshots');
+    if (existsSync(snapDir)) {
+      shellSnapshots = readdirSync(snapDir).filter(f => f.endsWith('.sh')).length;
+    }
+  } catch {}
+
+  // --- Configured hooks: count by type from settings.local.json ---
+  let configuredHooks = { PreToolUse: 0, PostToolUse: 0, Stop: 0, Notification: 0 };
+  try {
+    const localSettings = join(root, '.claude', 'settings.local.json');
+    if (existsSync(localSettings)) {
+      const s = JSON.parse(readFileSync(localSettings, 'utf8'));
+      for (const hookType of Object.keys(configuredHooks)) {
+        configuredHooks[hookType] = s.hooks?.[hookType]?.length || 0;
+      }
+    }
+  } catch {}
+
   return {
     claude: {
       available: claudeAvailable,
@@ -205,6 +270,11 @@ async function detectCapabilities(cwd) {
       available: replitToolsAvailable,
       checkpoints: checkpointsBin,
     },
+    mcpServers,
+    claudePlugins,
+    codexPlugins,
+    shellSnapshots,
+    configuredHooks,
   };
 }
 
@@ -998,6 +1068,9 @@ export async function getCapabilityManifest(cwd = process.cwd()) {
     return 'unknown';
   }
 
+  // ── Environment capabilities (MCP, plugins, hooks, snapshots) ─────────
+  const envCaps = await detectCapabilities(cwd);
+
   // ── Health states ──────────────────────────────────────────────────────
   let healthStates = {};
   try {
@@ -1158,6 +1231,14 @@ export async function getCapabilityManifest(cwd = process.cwd()) {
       recommendedAction,
       zeroProviderMode: !hasAnyProvider,
     },
+    environment: {
+      mcpServers:      envCaps.mcpServers,
+      claudePlugins:   envCaps.claudePlugins,
+      codexPlugins:    envCaps.codexPlugins,
+      shellSnapshots:  envCaps.shellSnapshots,
+      configuredHooks: envCaps.configuredHooks,
+      replitTools:     envCaps.replitTools,
+    },
     timestamp: new Date().toISOString(),
   };
 

package/src/prompt-audit.mjs

@@ -0,0 +1,231 @@
+import { existsSync, mkdirSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const AUDIT_DIR = join(process.cwd(), '.dualbrain', 'prompt-audit');
+
+/**
+ * Score a prompt for quality before sending to a provider.
+ * Returns score 0-100 and specific feedback.
+ */
+export function scorePrompt(prompt, opts = {}) {
+  const { type = 'think', maxTokenBudget = 2000 } = opts;
+
+  const issues = [];
+  const strengths = [];
+  let score = 100;
+
+  // Length efficiency
+  const words = prompt.split(/\s+/).length;
+  const chars = prompt.length;
+
+  if (words < 20) {
+    issues.push({ rule: 'too-short', msg: 'Prompt under 20 words — likely missing context', penalty: 15 });
+    score -= 15;
+  }
+  if (words > 500) {
+    issues.push({ rule: 'too-long', msg: `Prompt is ${words} words — consider trimming`, penalty: 10 });
+    score -= 10;
+  }
+
+  // Structure checks
+  if (type === 'think') {
+    if (!prompt.includes('?')) {
+      issues.push({ rule: 'no-question', msg: 'Think prompt has no question mark — unclear what decision is needed', penalty: 10 });
+      score -= 10;
+    }
+    if (!/\b(should|how|what|which|why|when|where|recommend|decide|choose|compare|tradeoff)\b/i.test(prompt)) {
+      issues.push({ rule: 'no-decision-language', msg: 'No decision-making language found', penalty: 5 });
+      score -= 5;
+    }
+    if (/\b(at least \d+ ideas|generate.*list|brainstorm)\b/i.test(prompt)) {
+      strengths.push('Requests specific output quantity');
+    }
+  }
+
+  // Context quality
+  if (/\b(this project|the codebase|our system)\b/i.test(prompt) && !/\b(module|file|function|export|import)\b/i.test(prompt)) {
+    issues.push({ rule: 'vague-context', msg: 'References "the project" without naming specific modules/files', penalty: 10 });
+    score -= 10;
+  }
+
+  if (/\b(src\/\w+|\.mjs|\.js|\.ts)\b/.test(prompt)) {
+    strengths.push('Names specific files/modules');
+  }
+
+  // Constraint quality
+  if (/\b(at least|minimum|maximum|no more than|ranked|ordered|prioritized)\b/i.test(prompt)) {
+    strengths.push('Includes output constraints');
+  }
+
+  // Anti-patterns
+  if (/\b(please|could you|would you mind)\b/i.test(prompt)) {
+    issues.push({ rule: 'politeness-waste', msg: 'Politeness tokens wasted on AI — be direct', penalty: 2 });
+    score -= 2;
+  }
+
+  if (/\b(I think|I believe|maybe|perhaps|possibly)\b/i.test(prompt) && type === 'think') {
+    issues.push({ rule: 'hedging', msg: 'Hedging language in think prompt — state positions directly', penalty: 5 });
+    score -= 5;
+  }
+
+  // Token efficiency estimate
+  const estimatedTokens = Math.ceil(chars / 4);
+  const efficiency = Math.min(100, Math.round((words / estimatedTokens) * 100));
+
+  // Duplication check
+  const sentences = prompt.split(/[.!?]+/).filter(s => s.trim().length > 10);
+  const unique = new Set(sentences.map(s => s.trim().toLowerCase()));
+  if (sentences.length > 3 && unique.size < sentences.length * 0.7) {
+    issues.push({ rule: 'repetitive', msg: `${sentences.length - unique.size} near-duplicate sentences`, penalty: 10 });
+    score -= 10;
+  }
+
+  score = Math.max(0, Math.min(100, score));
+
+  return {
+    score,
+    grade: score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F',
+    issues,
+    strengths,
+    stats: {
+      words,
+      chars,
+      estimatedTokens,
+      efficiency,
+      sentences: sentences.length,
+    },
+  };
+}
+
+/**
+ * Log a prompt exchange for auditing.
+ */
+export function logPromptExchange(exchange) {
+  const {
+    type = 'think',
+    round = 1,
+    prompt,
+    response,
+    provider = 'gpt',
+    model,
+    durationMs,
+    promptScore,
+  } = exchange;
+
+  mkdirSync(AUDIT_DIR, { recursive: true });
+
+  const entry = {
+    timestamp: new Date().toISOString(),
+    type,
+    round,
+    provider,
+    model,
+    durationMs,
+    promptScore: promptScore?.score,
+    promptGrade: promptScore?.grade,
+    promptWords: promptScore?.stats?.words,
+    promptTokens: promptScore?.stats?.estimatedTokens,
+    responseWords: response ? response.split(/\s+/).length : 0,
+    responseTokens: response ? Math.ceil(response.length / 4) : 0,
+    issues: promptScore?.issues?.map(i => i.rule) || [],
+  };
+
+  const logFile = join(AUDIT_DIR, 'exchanges.jsonl');
+  appendFileSync(logFile, JSON.stringify(entry) + '\n');
+
+  return entry;
+}
+
+/**
+ * Get prompt quality statistics over time.
+ */
+export function getPromptStats(opts = {}) {
+  const { days = 7 } = opts;
+  const logFile = join(AUDIT_DIR, 'exchanges.jsonl');
+
+  if (!existsSync(logFile)) return { available: false };
+
+  const cutoff = new Date(Date.now() - days * 86400000).toISOString();
+  const lines = readFileSync(logFile, 'utf8').trim().split('\n').filter(Boolean);
+
+  const entries = [];
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.timestamp >= cutoff) entries.push(entry);
+    } catch {}
+  }
+
+  if (entries.length === 0) return { available: true, count: 0 };
+
+  const avgScore = entries.reduce((s, e) => s + (e.promptScore || 0), 0) / entries.length;
+  const avgPromptTokens = entries.reduce((s, e) => s + (e.promptTokens || 0), 0) / entries.length;
+  const avgResponseTokens = entries.reduce((s, e) => s + (e.responseTokens || 0), 0) / entries.length;
+  const avgDuration = entries.reduce((s, e) => s + (e.durationMs || 0), 0) / entries.length;
+
+  const grades = {};
+  for (const e of entries) {
+    grades[e.promptGrade] = (grades[e.promptGrade] || 0) + 1;
+  }
+
+  const commonIssues = {};
+  for (const e of entries) {
+    for (const issue of (e.issues || [])) {
+      commonIssues[issue] = (commonIssues[issue] || 0) + 1;
+    }
+  }
+
+  const topIssues = Object.entries(commonIssues)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([rule, count]) => ({ rule, count, pct: Math.round(count / entries.length * 100) }));
+
+  return {
+    available: true,
+    count: entries.length,
+    avgScore: Math.round(avgScore),
+    avgPromptTokens: Math.round(avgPromptTokens),
+    avgResponseTokens: Math.round(avgResponseTokens),
+    avgDurationMs: Math.round(avgDuration),
+    totalPromptTokens: entries.reduce((s, e) => s + (e.promptTokens || 0), 0),
+    totalResponseTokens: entries.reduce((s, e) => s + (e.responseTokens || 0), 0),
+    grades,
+    topIssues,
+  };
+}
+
+/**
+ * Suggest improvements for a prompt.
+ */
+export function suggestImprovements(prompt, type = 'think') {
+  const score = scorePrompt(prompt, { type });
+  const suggestions = [];
+
+  for (const issue of score.issues) {
+    switch (issue.rule) {
+      case 'too-short':
+        suggestions.push('Add context: what modules are involved, what decision is needed, what constraints exist');
+        break;
+      case 'too-long':
+        suggestions.push('Trim: remove background the AI already knows from CLAUDE.md. Focus on what\'s unique to this question');
+        break;
+      case 'no-question':
+        suggestions.push('End with a clear question or decision point');
+        break;
+      case 'vague-context':
+        suggestions.push('Name specific files, functions, or modules instead of "the project"');
+        break;
+      case 'politeness-waste':
+        suggestions.push('Remove "please", "could you" — direct prompts produce better output');
+        break;
+      case 'hedging':
+        suggestions.push('State positions directly — "X is better because Y" not "I think maybe X"');
+        break;
+      case 'repetitive':
+        suggestions.push('Remove duplicate sentences — each sentence should add new information');
+        break;
+    }
+  }
+
+  return { score, suggestions };
+}