@monoes/monomindcli 1.10.29 → 1.10.31

package/.claude/helpers/auto-memory-hook.mjs

@@ -11,7 +11,7 @@
  *   node auto-memory-hook.mjs status   # Show bridge status
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, openSync, closeSync, unlinkSync, readFileSync, writeFileSync, renameSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -34,6 +34,37 @@ const dim = (msg) => console.log(`  ${DIM}${msg}${RESET}`);
 // Ensure data dir
 if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
 
+// ============================================================================
+// File-lock helper for concurrent hook coordination
+// Uses O_EXCL exclusive-create as a spin lock.
+// A 10ms synchronous wait (via Atomics.wait) is used between retries to avoid
+// pegging the CPU. Acceptable for low-contention hook processes.
+// ============================================================================
+
+function withFileLock(lockPath, fn, timeoutMs = 5000) {
+  const start = Date.now();
+  const sharedBuf = new Int32Array(new SharedArrayBuffer(4));
+  while (true) {
+    try {
+      // O_EXCL: exclusive create — fails atomically if file already exists
+      const fd = openSync(lockPath, 'wx');
+      closeSync(fd);
+      break; // acquired lock
+    } catch {
+      if (Date.now() - start > timeoutMs) {
+        // Timeout: proceed without lock rather than deadlocking hook processes
+        try { fn(); } catch { /* best effort */ }
+        return;
+      }
+      // Synchronous 10ms sleep via Atomics.wait (avoids busy-spin CPU peg)
+      Atomics.wait(sharedBuf, 0, 0, 10);
+    }
+  }
+  try { fn(); } finally {
+    try { unlinkSync(lockPath); } catch { /* ignore */ }
+  }
+}
+
 // ============================================================================
 // Simple JSON File Backend (implements IMemoryBackend interface)
 // ============================================================================
@@ -120,9 +151,13 @@ class JsonFileBackend {
   }
 
   _persist() {
-    try {
-      writeFileSync(this.filePath, JSON.stringify([...this.entries.values()], null, 2), 'utf-8');
-    } catch { /* best effort */ }
+    const lockPath = this.filePath + '.lock';
+    withFileLock(lockPath, () => {
+      const data = JSON.stringify([...this.entries.values()], null, 2);
+      const tmpPath = this.filePath + '.tmp';
+      writeFileSync(tmpPath, data, 'utf-8');
+      renameSync(tmpPath, this.filePath);
+    });
   }
 }
 

package/.claude/helpers/handlers/adr-draft-handler.cjs

@@ -0,0 +1,64 @@
+'use strict';
+// Extracted from hook-handler.cjs — handles 'adr-draft' command.
+// Drafts an ADR from accumulated decision markers in .monomind/decisions.jsonl.
+// Receives hCtx from dispatcher. See route-handler.cjs for hCtx field docs.
+
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  handle: function(hCtx) {
+    var CWD = hCtx.CWD;
+
+    var jsonl = path.join(CWD, '.monomind', 'decisions.jsonl');
+    if (!fs.existsSync(jsonl)) {
+      console.log('[ADR] No decisions recorded yet. Type prompts containing markers like "let\'s go with X", "we chose Y", "decision: Z" to populate the log.');
+      return;
+    }
+    var lines = fs.readFileSync(jsonl, 'utf-8').trim().split('\n').filter(Boolean);
+    if (lines.length === 0) {
+      console.log('[ADR] decisions.jsonl is empty.');
+      return;
+    }
+    // Group decisions captured in the last 7 days.
+    var cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    var recent = lines
+      .map(function(l) { try { return JSON.parse(l); } catch (_) { return null; } })
+      .filter(function(d) { return d && d.ts >= cutoff; });
+    if (recent.length === 0) {
+      console.log('[ADR] No decisions in the last 7 days. Older entries: ' + lines.length + '.');
+      return;
+    }
+
+    var adrsDir = path.join(CWD, 'docs', 'adrs');
+    try { fs.mkdirSync(adrsDir, { recursive: true }); } catch (_) {}
+    var existing = [];
+    try { existing = fs.readdirSync(adrsDir).filter(function(f) { return /^ADR-\d{4}/.test(f); }); } catch (_) {}
+    var nextNum = existing.length + 1;
+    var num = String(nextNum).padStart(4, '0');
+    var stamp = new Date().toISOString().slice(0, 10);
+    var fname = 'ADR-' + num + '-' + stamp + '-session-decisions.md';
+    var outPath = path.join(adrsDir, fname);
+
+    var body = '# ADR-' + num + ': Session decisions (' + stamp + ')\n\n' +
+               '**Status:** Proposed\n**Date:** ' + stamp + '\n\n' +
+               '## Context\n\n' +
+               'During recent sessions, the following decision markers were captured ' +
+               'from user prompts. Each excerpt is the surrounding sentence at the time.\n\n' +
+               '## Decisions\n\n';
+    for (var i = 0; i < recent.length; i++) {
+      var d = recent[i];
+      var date = new Date(d.ts).toISOString().slice(0, 16).replace('T', ' ');
+      body += '### ' + (i + 1) + '. ' + date + '\n\n';
+      for (var j = 0; j < d.excerpts.length; j++) {
+        body += '> ' + d.excerpts[j].trim() + '\n\n';
+      }
+      if (d.prompt) body += '_Prompt:_ ' + d.prompt.slice(0, 200) + (d.prompt.length > 200 ? '…' : '') + '\n\n';
+    }
+    body += '## Consequences\n\n_(fill in after review)_\n\n' +
+            '## Status\n\nProposed — awaiting human review and refinement.\n';
+    fs.writeFileSync(outPath, body);
+    console.log('[ADR_DRAFT] Wrote ' + recent.length + ' decision(s) to ' + outPath);
+    console.log('  Edit the file to fill in Context and Consequences, then change Status to Accepted/Rejected.');
+  },
+};

package/.claude/helpers/handlers/agent-start-handler.cjs

@@ -0,0 +1,99 @@
+'use strict';
+// Extracted from hook-handler.cjs — handles 'agent-start' (SubagentStart) hook event.
+// Receives hCtx from dispatcher. See route-handler.cjs for hCtx field docs.
+
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  handle: function(hCtx) {
+    var hookInput = hCtx.hookInput;
+    var CWD = hCtx.CWD;
+    var _openMonographDb = hCtx._openMonographDb;
+    var getMonographSuggestions = hCtx.getMonographSuggestions;
+
+    // Register this agent so the statusline can count active agents.
+    const regDir = path.join(CWD, '.monomind', 'agents', 'registrations');
+    try {
+      fs.mkdirSync(regDir, { recursive: true });
+      const id = Date.now() + '-' + Math.random().toString(36).slice(2, 6);
+      const regFile = path.join(regDir, 'agent-' + id + '.json');
+      fs.writeFileSync(regFile, JSON.stringify({
+        agentId: id,
+        startedAt: new Date().toISOString(),
+        pid: process.pid,
+      }));
+      // Refresh swarm-activity.json within the 5-min staleness window.
+      const activityDir = path.join(CWD, '.monomind', 'metrics');
+      fs.mkdirSync(activityDir, { recursive: true });
+      const activityPath = path.join(activityDir, 'swarm-activity.json');
+      const active = fs.readdirSync(regDir).filter(f => f.endsWith('.json')).length;
+      // Preserve lastActive (peak) so statusline shows non-zero after completion.
+      let prevLastActive = 0;
+      try { prevLastActive = (JSON.parse(fs.readFileSync(activityPath, 'utf-8'))?.swarm?.lastActive) || 0; } catch { /* ignore */ }
+      fs.writeFileSync(activityPath, JSON.stringify({
+        timestamp: new Date().toISOString(),
+        swarm: {
+          active: active > 0,
+          agent_count: active,
+          coordination_active: active > 0,
+          lastActive: Math.max(active, prevLastActive),
+        },
+      }));
+
+      // Write last-dispatch.json so the route handler can suppress redundant
+      // suggestions on the next turn when the same agent type is recommended.
+      const agentType = hookInput.subagent_type || hookInput.agentType || hookInput.agent_type || hookInput.agentSlug || 'unknown';
+      const agentDesc = hookInput.description || hookInput.prompt_description || '';
+      fs.writeFileSync(
+        path.join(CWD, '.monomind', 'last-dispatch.json'),
+        JSON.stringify({
+          agentType: agentType,
+          description: agentDesc.substring(0, 120),
+          dispatchedAt: new Date().toISOString(),
+        }),
+        'utf-8'
+      );
+    } catch (e) { /* non-fatal — never block a subagent from starting */ }
+
+    // Subagent context inheritance — inject graph god nodes + parent's last
+    // pre-resolved suggestions so the spawned agent inherits spatial map.
+    try {
+      var subDb = _openMonographDb();
+      if (subDb) {
+        try {
+          var godRows = subDb.prepare(
+            "SELECT n.name, n.label, n.file_path AS file, " +
+            "(SELECT COUNT(*) FROM edges WHERE source_id=n.id OR target_id=n.id) AS deg " +
+            "FROM nodes n " +
+            "WHERE n.label NOT IN ('Concept') AND n.file_path IS NOT NULL AND n.file_path != '' " +
+            "ORDER BY deg DESC LIMIT 5"
+          ).all();
+          if (godRows.length > 0) {
+            console.log('[MONOGRAPH_SUBAGENT_CTX] Graph map inherited from parent:');
+            for (var gi = 0; gi < godRows.length; gi++) {
+              var gr = godRows[gi];
+              console.log('  · ' + gr.name + ' [' + gr.label + '] — ' + (gr.file || '') + ' (deg ' + gr.deg + ')');
+            }
+            try {
+              var subAgentDesc = hookInput.description || hookInput.prompt_description || '';
+              if (subAgentDesc && subAgentDesc.length > 8) {
+                var subHints = getMonographSuggestions(subAgentDesc, 3);
+                if (subHints.length > 0) {
+                  console.log('  Top files for this subagent task:');
+                  for (var si2 = 0; si2 < subHints.length; si2++) {
+                    var sh = subHints[si2];
+                    console.log('    · ' + sh.name + ' [' + sh.label + '] — ' + (sh.file || ''));
+                  }
+                }
+              }
+            } catch (_) {}
+            console.log('  Use mcp__monomind__monograph_suggest / monograph_query in this subagent before grepping.');
+          }
+        } catch (e) { /* non-fatal */ }
+      }
+    } catch (e) { /* non-fatal */ }
+
+    console.log('[OK] Agent registered');
+  },
+};

package/.claude/helpers/handlers/edit-handler.cjs

@@ -0,0 +1,145 @@
+'use strict';
+// Extracted from hook-handler.cjs — receives hCtx from dispatcher.
+// Handles the 'post-edit' hook event.
+// See route-handler.cjs for full hCtx field documentation.
+
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  handle: async function(hCtx) {
+    var hookInput = hCtx.hookInput;
+    var toolInput = hCtx.toolInput;
+    var args = hCtx.args;
+    var session = hCtx.session;
+    var intelligence = hCtx.intelligence;
+    var CWD = hCtx.CWD;
+
+    if (session && session.metric) {
+      try { session.metric('edits'); } catch (e) { /* no active session */ }
+    }
+    if (intelligence && intelligence.recordEdit) {
+      try {
+        var file = hookInput.file_path || toolInput.file_path
+          || process.env.TOOL_INPUT_file_path || args[0] || '';
+        intelligence.recordEdit(file);
+      } catch (e) { /* non-fatal */ }
+    }
+    // Track recently-edited files for compact injection and pre-resolve boosting.
+    try {
+      var editedForRecent = hookInput.file_path || toolInput.file_path
+        || process.env.TOOL_INPUT_file_path || args[0] || '';
+      if (editedForRecent) hCtx._recordRecentEdit(editedForRecent);
+    } catch (e) { /* non-fatal */ }
+    // Increment write counter and rebuild monograph when threshold hit.
+    hCtx._maybeRebuildMonograph();
+
+    // Test feedback (detection-only): when editing a source file, list tests
+    // that import it so the LLM/user knows what to verify next.
+    try {
+      var editedFile = hookInput.file_path || toolInput.file_path
+        || process.env.TOOL_INPUT_file_path || args[0] || '';
+      if (editedFile && !editedFile.match(/\.(test|spec)\./) && !editedFile.includes('__tests__')) {
+        var affectedTests = hCtx._findAffectedTests(editedFile);
+        if (affectedTests.length > 0) {
+          console.log('[AFFECTED_TESTS] ' + affectedTests.length + ' test(s) cover this file:');
+          for (var ti = 0; ti < Math.min(5, affectedTests.length); ti++) {
+            console.log('  · ' + affectedTests[ti]);
+          }
+        }
+      }
+    } catch (e) {}
+    // ── Security-Sensitive File Auto-Alert ────────────────────────────────────
+    // When editing auth, security, crypto, or env-related files, flag it
+    try {
+      var editFile = (hookInput.file_path || toolInput.file_path
+        || process.env.TOOL_INPUT_file_path || args[0] || '').toLowerCase();
+      var securityPatterns = /\b(auth|security|crypto|secret|credential|token|password|\.env|permission|acl|rbac|jwt|oauth|session|cookie)\b/;
+      if (securityPatterns.test(editFile) || editFile.includes('/security/') || editFile.includes('/auth/')) {
+        console.log('[SECURITY_EDIT] Security-sensitive file modified: ' + path.basename(editFile));
+        console.log('[SECURITY_EDIT] INSTRUCTION: Consider running a security review. Invoke Skill("code-review:code-review") with security focus, or run: npx monomind security scan --path "' + editFile + '"');
+      }
+    } catch (e) { /* non-fatal */ }
+
+    // ── Smart Test/Build Suggestions (PE-001) ───────────────────────────
+    try {
+      var editFile2 = (hookInput.file_path || toolInput.file_path
+        || process.env.TOOL_INPUT_file_path || args[0] || '');
+      var editBase = path.basename(editFile2).toLowerCase();
+      if (/\.(test|spec)\.(ts|js|tsx|jsx)$/.test(editBase)) {
+        console.log('[AUTO_SUGGEST] Test file modified — run: npm test -- --testPathPattern="' + path.basename(editFile2) + '"');
+      } else if (editBase === 'package.json') {
+        console.log('[AUTO_SUGGEST] package.json changed — consider running: npm install');
+      } else if (editBase === 'tsconfig.json' || editBase === 'tsconfig.base.json') {
+        console.log('[AUTO_SUGGEST] TypeScript config changed — consider running: npm run build');
+      }
+    } catch (e) { /* non-fatal */ }
+
+    // ── Monograph Incremental Rebuild ─────────────────────────────────────
+    // After every code file edit, trigger a background monograph rebuild so
+    // the knowledge graph stays current. Debounced via a lock file (5s cooldown).
+    try {
+      var editedFile2 = (hookInput.file_path || toolInput.file_path
+        || process.env.TOOL_INPUT_file_path || args[0] || '');
+      var codeExts = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|cpp|c|rb|swift|php)$/i;
+      if (editedFile2 && codeExts.test(editedFile2)) {
+        var lockFile = path.join(CWD, '.monomind', 'graph', '.rebuild-lock');
+        var now = Date.now();
+        var lastBuild = 0;
+        try { lastBuild = parseInt(fs.readFileSync(lockFile, 'utf-8').trim(), 10) || 0; } catch (e) {}
+        var COOLDOWN_MS = 5000; // 5-second debounce
+        if (now - lastBuild > COOLDOWN_MS) {
+          fs.writeFileSync(lockFile, String(now), 'utf-8');
+          var { spawn: spawnRebuild } = require('child_process');
+          var rebuildScript = "import { buildAsync } from '@monoes/monograph'; await buildAsync(" + JSON.stringify(CWD) + ");";
+          var graphDir = path.join(CWD, '.monomind', 'graph');
+          var logPath = path.join(graphDir, 'build.log');
+          var logFd;
+          try { logFd = fs.openSync(logPath, 'a'); } catch(e) { logFd = 'ignore'; }
+          var child = spawnRebuild(process.execPath, ['--input-type=module', '--eval', rebuildScript], {
+            detached: true, stdio: ['ignore', logFd, logFd], cwd: CWD,
+          });
+          child.unref();
+          console.log('[MONOGRAPH] Incremental rebuild triggered for ' + path.basename(editedFile2));
+
+          // Option C: fire ua-enrich.mjs in background after monograph rebuild
+          var uaEnrichScript = path.join(CWD, 'scripts', 'ua-enrich.mjs');
+          if (fs.existsSync(uaEnrichScript)) {
+            var uaChild = spawnRebuild(process.execPath, [uaEnrichScript, '--dir', CWD, '--file', editedFile2, '--db', path.join(CWD, '.monomind', 'monograph.db')], {
+              detached: true, stdio: 'ignore', cwd: CWD,
+            });
+            uaChild.unref();
+          }
+        }
+        // Show importers of the edited file so Claude sees blast radius
+        try {
+          var mgDbPath4 = path.join(CWD, '.monomind', 'monograph.db');
+          if (fs.existsSync(mgDbPath4)) {
+            var mgMod4 = null;
+            var _requireMonograph4 = hCtx._requireMonograph;
+            mgMod4 = _requireMonograph4 ? _requireMonograph4() : null;
+            if (mgMod4 && mgMod4.openDb) {
+              var db4 = mgMod4.openDb(mgDbPath4);
+              try {
+                var editedBase4 = path.basename(editedFile2).replace(/\.[^.]+$/, '');
+                var editNode4 = db4.prepare("SELECT id, name, label FROM nodes WHERE file_path LIKE ? OR name = ? LIMIT 1")
+                  .get('%' + path.sep + path.basename(editedFile2), editedBase4);
+                if (editNode4) {
+                  var editImporters4 = db4.prepare(
+                    'SELECT n2.name FROM edges e JOIN nodes n2 ON n2.id = e.source_id WHERE e.target_id = ? LIMIT 8'
+                  ).all(editNode4.id);
+                  if (editImporters4.length > 0) {
+                    console.log('[MONOGRAPH_IMPACT] ' + editNode4.name + ' (' + editNode4.label + ') is depended on by: ' +
+                      editImporters4.map(function(i) { return i.name; }).join(', '));
+                  }
+                }
+              } finally { if (mgMod4.closeDb) mgMod4.closeDb(db4); }
+            }
+          }
+        } catch(e) { /* non-fatal */ }
+      }
+    } catch (e) { /* non-fatal */ }
+
+    console.log('[OK] Edit recorded');
+  }
+};

package/.claude/helpers/handlers/graph-status-handler.cjs

@@ -0,0 +1,38 @@
+'use strict';
+// Extracted from hook-handler.cjs — handles 'graph-status' command.
+// Shows monograph node/edge counts and graph-vs-grep usage ratio.
+// Receives hCtx from dispatcher. See route-handler.cjs for hCtx field docs.
+
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  handle: function(hCtx) {
+    var CWD = hCtx.CWD;
+    var _openMonographDb = hCtx._openMonographDb;
+
+    var db = _openMonographDb();
+    if (!db) {
+      console.log('No monograph.db found. Run /monomind:understand to build.');
+      return;
+    }
+    try {
+      var n = db.prepare("SELECT COUNT(*) AS c FROM nodes").get().c;
+      var e = db.prepare("SELECT COUNT(*) AS c FROM edges").get().c;
+      var usage = (function() {
+        try { return JSON.parse(fs.readFileSync(path.join(CWD, '.monomind', 'metrics', 'graph-usage.json'), 'utf-8')); }
+        catch (_) { return {}; }
+      })();
+      var wins = (usage.monograph_call || 0) + (usage.preresolve_hit || 0)
+               + (usage.graph_assist_search || 0) + (usage.graph_assist_neighbors || 0);
+      var search = (usage.grep_call || 0) + (usage.glob_call || 0)
+                 + (usage.bash_grep_call || 0) + (usage.bash_find_call || 0);
+      var pct = (wins + search) > 0 ? Math.round((wins / (wins + search)) * 100) : 0;
+      var saved = usage.dollars_saved || 0;
+      console.log('Monograph: ' + n.toLocaleString() + ' nodes · ' + e.toLocaleString() + ' edges');
+      console.log('Usage: ' + pct + '% graph · ' + (100 - pct) + '% grep · ' +
+                  'wins=' + wins + ' search=' + search +
+                  (saved > 0 ? ' · saved $' + saved.toFixed(2) : ''));
+    } catch (err) { console.log('Error: ' + err.message); }
+  },
+};