@monoes/monomindcli 1.10.23 → 1.10.24

package/.claude/commands/monomind/understand.md

@@ -1,197 +1,139 @@
 ---
 name: monomind:understand
-description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph. No external plugin needed — the analysis engine ships with monomind."
+description: "Monomind — Run semantic enrichment on the current project's monograph knowledge graph. Uses the active Claude Code session for LLM work — no API key needed."
 ---
 
 # /monomind:understand — Semantic Enrichment
 
-Enriches the current project's monograph knowledge graph with LLM-generated summaries,
-architectural layers, and semantic relationships.
+Enriches the current project's monograph knowledge graph with summaries, architectural
+layers, and semantic relationships.
 
-The analysis engine is built into monomind — no external plugin installation required.
+**Designed to run inside Claude Code** — uses YOUR current session for LLM work via
+the Task tool. No `ANTHROPIC_API_KEY` required. The script handles layer detection
+and DB writes; you (Claude) handle per-file summarization.
 
 ## Parse Arguments
 
-Parse `$ARGUMENTS` for these optional flags:
-
-- `--dir <path>`      — project directory to analyze (default: current working directory)
-- `--db <path>`       — path to monograph.db (default: `<dir>/.monomind/monograph.db`)
-- `--import`          — import an existing graph.json only (skip analysis, run ua-import.mjs)
-- `--graph <path>`    — explicit path to a graph.json to import (implies `--import`)
-- `--full`            — force full re-analysis even if graph.json is recent
-- `--no-llm`          — heuristic-only mode: detect layers from file paths, no API calls
-- `--layers-only`     — skip per-file analysis, only (re-)detect architectural layers
-- `--incremental`     — re-analyze only files changed since the last run (uses git diff)
-- `--onboard`         — generate an ONBOARDING.md guide from the enriched graph
-- `--onboard-out <path>` — where to write the onboarding guide (default: `<dir>/ONBOARDING.md`)
-- `--batch-size <N>`  — files per LLM batch (default: 5, increase for faster analysis)
+Parse `$ARGUMENTS` for these flags:
+
+- `--dir <path>`      — project directory (default: cwd)
+- `--db <path>`       — monograph.db path (default: `<dir>/.monomind/monograph.db`)
+- `--full`            — force full re-analysis
+- `--no-llm`          — heuristic-only mode (no per-file summaries)
+- `--layers-only`     — skip per-file analysis, only re-detect layers
 - `--max-files <N>`   — stop after N files (0 = all)
-- `--dry-run`         — show what would happen without writing to DB
+- `--dry-run`         — show what would happen, don't write
 
-If no flags, treat any bare path argument as `--dir`.
+Bare path argument → `--dir`.
 
 ---
 
-## Step 1: Locate project and monograph DB
+## Step 1: Locate project, DB, and script
 
 ```bash
 DIR="${ARGUMENTS_dir:-$(pwd)}"
 DB="${ARGUMENTS_db:-$DIR/.monomind/monograph.db}"
-```
-
-1. Resolve `DIR` to an absolute path.
-2. Check that `$DB` exists. If not, tell the user:
-   > monograph.db not found at `$DB`. Build the graph first:
-   > ```bash
-   > npx monomind monograph build
-   > ```
-   > Then re-run `/monomind:understand`.
-   And STOP.
-
----
 
-## Step 2: Locate the built-in analysis engine
-
-The `understand-analyze.mjs` script ships with `@monomind/cli`. Find it:
-
-```bash
-# Try npm root (global install / homebrew)
+# Find understand-analyze.mjs (ships with monomind globally)
 GLOBAL_ROOT=$(npm root -g 2>/dev/null)
-SCRIPT="$GLOBAL_ROOT/@monomind/cli/scripts/understand-analyze.mjs"
-
-# If not found globally, try npx resolve
-if [ ! -f "$SCRIPT" ]; then
-  SCRIPT=$(node -e "try{console.log(require.resolve('@monomind/cli/scripts/understand-analyze.mjs'))}catch{}" 2>/dev/null)
-fi
-
-# Fallback: walk up from the running CLI's __dirname
-if [ ! -f "$SCRIPT" ]; then
-  SCRIPT=$(node -e "
-    const {createRequire} = require('module');
-    const r = createRequire(require.resolve('monomind'));
-    try { console.log(r.resolve('@monomind/cli/scripts/understand-analyze.mjs')); } catch {}
-  " 2>/dev/null)
-fi
+SCRIPT="$GLOBAL_ROOT/monomind/packages/@monomind/cli/scripts/understand-analyze.mjs"
+[ ! -f "$SCRIPT" ] && SCRIPT="$GLOBAL_ROOT/@monoes/monomindcli/scripts/understand-analyze.mjs"
 ```
 
-If the script is still not found:
-> The built-in understand engine (understand-analyze.mjs) was not found.
-> Update monomind: `npm install -g monomind@latest`
-
-And STOP.
+If `$DB` does not exist:
+> monograph.db not found at `$DB`. Build it first: `npx monomind monograph build`
 
----
+If `$SCRIPT` does not exist:
+> understand engine missing. Update: `npm install -g monomind@latest`
 
-## Step 3: Check for existing graph.json (unless `--full`)
+In either case, STOP.
 
-Look for (in order):
-- `$DIR/.understand/knowledge-graph.json`
-- `$DIR/.understand/graph.json`
-- `$DIR/.ua/graph.json`
+---
 
-If `--graph <path>` was supplied, use that path directly.
+## Step 2: Run the script in heuristic mode (always — fast and deterministic)
 
-**If a recent graph.json is found AND `--full` was NOT set:**
+This step is non-negotiable. The script handles:
+- File node discovery from monograph.db
+- Heuristic layer detection from file paths
+- DB writes (community_id + properties)
+- graph.json emission to `.understand/knowledge-graph.json`
+- Auto-shadowing the DB to `/tmp` when it lives on a network FS
 
-Report the file age and jump to **Step 5: Import**:
-```
-Found graph.json (X hours old) — importing into monograph…
+```bash
+node "$SCRIPT" --dir "$DIR" --db "$DB" --no-llm
 ```
 
-**If `--import` or `--graph` was set:**
-Jump directly to **Step 5: Import**.
-
-**Otherwise:**
-Proceed to **Step 4: Run analysis**.
+Wait for completion. Capture stdout. Note how many file nodes were found and how
+many layers were detected. Do NOT advise the user about API keys.
 
 ---
 
-## Step 4: Run built-in analysis
+## Step 3: Per-file summarization (ONLY if `--no-llm` and `--layers-only` are both UNSET)
 
-Run the built-in engine. Build the command from parsed flags:
+This is where YOU (the current Claude session) do the LLM work. The script left
+behind a fresh `.understand/knowledge-graph.json` with placeholder summaries.
 
-```bash
-node "$SCRIPT" \
-  --dir "$DIR" \
-  --db "$DB" \
-  [--no-llm]           # if --no-llm was set
-  [--layers-only]      # if --layers-only was set
-  [--incremental]      # if --incremental was set
-  [--onboard]          # if --onboard was set
-  [--onboard-out PATH] # if --onboard-out was set
-  [--dry-run]          # if --dry-run was set
-  [--batch-size N]     # if --batch-size was set
-  [--max-files N]      # if --max-files was set
-```
+1. Read `.understand/knowledge-graph.json`. For each node where `properties.fileSummary`
+   is empty or marked `[heuristic]`, do the following:
+   - Use the `Read` tool on `node.file_path` (relative to `$DIR`).
+   - Produce a JSON object: `{ id, fileSummary, tags, complexity, functionSummaries, classSummaries }`
+     where:
+     - `fileSummary`: 1-2 sentences explaining what the file does
+     - `tags`: array of 2-5 short tags
+     - `complexity`: "simple" | "moderate" | "complex"
+     - `functionSummaries`: top-5 functions → 1-sentence each
+     - `classSummaries`: classes → 1-sentence each
+2. Process files in batches of 5 for efficiency. Use `--max-files` to cap if set.
+3. Collect all analyses into an `analyses` array.
 
-The script will:
-1. Read all file nodes from the monograph DB
-2. Pick the best available LLM path automatically (no env vars to set):
-   - `claude -p` CLI passthrough — reuses the active Claude Code authentication
-   - direct Anthropic API — if `ANTHROPIC_API_KEY` happens to be set (faster for bulk runs)
-   - heuristic-only fallback — if neither is reachable
-3. For each file, generate summaries, tags, and complexity
-4. Detect architectural layers
-5. Write enrichment data back to `monograph.db` (community_id + properties JSON)
-6. Emit a `graph.json` to `$DIR/.understand/knowledge-graph.json`
-
-Wait for the script to complete before proceeding. Do NOT pre-check or advise about
-`ANTHROPIC_API_KEY` — the script picks its path silently and prints the chosen mode
-on stdout. Report only what the script actually reports.
+If `$ARGUMENTS` includes `--no-llm` or `--layers-only`, SKIP this step entirely.
 
 ---
 
-## Step 5: Import (only when using an existing graph.json)
+## Step 4: Write analyses back to the DB
 
-If jumping here from Step 3 (existing graph.json found):
+Pipe the collected analyses to a small re-import:
 
 ```bash
-REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
-IMPORT_SCRIPT="$REPO_ROOT/scripts/ua-import.mjs"
-# fallback: alongside understand-analyze.mjs
-[ ! -f "$IMPORT_SCRIPT" ] && IMPORT_SCRIPT="$(dirname $SCRIPT)/../../../scripts/ua-import.mjs"
-node "$IMPORT_SCRIPT" "$GRAPH_JSON" "$DB"
+echo "$ANALYSES_JSON" | node "$SCRIPT" --dir "$DIR" --db "$DB" --import-analyses-stdin
 ```
 
-If `--dry-run` was set, report what would be imported without writing to the DB.
+(If your `analyses` array is empty, skip this step.)
 
 ---
 
-## Step 6: Report results
-
-After the analysis or import completes, show a summary:
+## Step 5: Report
 
 ```
 ╔══════════════════════════════════════════════════╗
 ║  /monomind:understand — Enrichment Done           ║
 ╠══════════════════════════════════════════════════╣
 ║  DB:              .monomind/monograph.db          ║
-║  Nodes enriched:  <N>                             ║
-║  Communities:     <N> (layers detected)           ║
+║  Files analyzed:  <N>                             ║
+║  LLM summaries:   <N> (via active session)        ║
+║  Layers:          <N>                             ║
 ║  graph.json:      .understand/knowledge-graph.json║
 ╚══════════════════════════════════════════════════╝
 ```
 
-Then tell the user:
-> The monograph graph is now enriched with semantic summaries and architectural layers.
-> Open the Monomind control panel and click **Monograph → GRAPH** to see multi-color layers.
-> Each color represents an architectural layer (API, Service, Data, UI, etc.).
+If LLM summaries = 0 (because `--no-llm` was set), say "heuristic-only mode — no per-file summaries written".
+
+Then:
+> Open the Monomind control panel and click **Monograph → GRAPH** to see layers.
+> Each color = one architectural layer (API, Service, Data, UI, etc.).
 >
-> Common follow-ups:
-> - `/monomind:understand --full` — full re-analysis from scratch
-> - `/monomind:understand --layers-only` — refresh only layer detection
-> - `/monomind:understand --incremental` — re-analyze only changed files
-> - `/monomind:understand --onboard` — generate an onboarding guide
+> Follow-ups:
+> - `/monomind:understand --full` — re-run from scratch
+> - `/monomind:understand --layers-only` — refresh only layers
+> - `/monomind:understand --no-llm` — heuristic-only mode
 
 ---
 
 ## Error Handling
 
-- The script auto-selects an LLM path (`claude -p` CLI → API key → heuristic). Do not
-  prompt the user to set `ANTHROPIC_API_KEY`. Monomind is designed to run inside an
-  authenticated Claude Code session — the CLI passthrough is the default path.
-- If the script exits non-zero, show stderr and suggest `npm install -g monomind@latest`.
-- If monograph.db has no file nodes, tell the user to run `npx monomind monograph build` first.
-- All errors are non-fatal to the main session — report and return cleanly.
+- Do NOT prompt the user to set `ANTHROPIC_API_KEY`. LLM work happens in this session.
+- If the script exits non-zero: show stderr and suggest `npm install -g monomind@latest`.
+- If monograph.db has no file nodes: tell the user to run `npx monomind monograph build` first.
+- All errors are non-fatal — report and return cleanly.
 
-To repeat this command on a schedule, wrap it with `/monomind:repeat`.
+To re-run on a schedule: wrap with `/monomind:repeat`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monomindcli",
-  "version": "1.10.23",
+  "version": "1.10.24",
   "type": "module",
   "description": "Monomind CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",

package/scripts/understand-analyze.mjs

@@ -129,60 +129,16 @@ function detectLayersHeuristic(fileNodes) {
 }
 
 // ── Anthropic API helpers ─────────────────────────────────────────────────────
-// Two paths:
-//   1. Direct API via ANTHROPIC_API_KEY (fastest, parallel-safe, requires key)
-//   2. `claude -p` CLI passthrough (reuses Claude Code's auth — no key needed)
-//      Slower (CLI cold-start per call), but works inside any Claude Code
-//      session without extra setup.
+// LLM enrichment requires ANTHROPIC_API_KEY. When the script is invoked from
+// inside a Claude Code session via /monomind:understand, the slash command
+// orchestrates the LLM work inline (using the active session) — the script
+// itself runs in --no-llm heuristic mode in that flow. Attempting to spawn
+// `claude -p` from a nested subprocess does NOT work (the nested CLI hangs
+// indefinitely), so we no longer try that path.
 const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 const ANTHROPIC_URL     = 'https://api.anthropic.com/v1/messages';
 const MODEL             = 'claude-haiku-4-5-20251001'; // cheapest for bulk analysis
 
-// Detect `claude` CLI once at startup.
-let _claudeCliPath = null;
-function _detectClaudeCli() {
-  if (_claudeCliPath !== null) return _claudeCliPath;
-  try {
-    const out = execSync('command -v claude 2>/dev/null', { encoding: 'utf-8' }).trim();
-    _claudeCliPath = out || '';
-  } catch { _claudeCliPath = ''; }
-  return _claudeCliPath;
-}
-
-const USE_CLAUDE_CLI = !ANTHROPIC_API_KEY && !!_detectClaudeCli();
-
-async function callClaudeViaCli(systemPrompt, userPrompt, maxTokens = 1024) {
-  return new Promise((resolveP, reject) => {
-    // NOTE: do NOT pass --bare here. --bare disables OAuth/keychain reads
-    // and forces ANTHROPIC_API_KEY — which is exactly what we're avoiding.
-    // We want the CLI to use the user's logged-in Claude Code session.
-    const args = [
-      '-p',
-      '--model', 'haiku',
-      '--output-format', 'text',
-      '--disable-slash-commands', // skip skill auto-resolution overhead
-      `${systemPrompt}\n\n---\n\n${userPrompt}`,
-    ];
-    const child = spawn(_claudeCliPath, args, {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env },
-    });
-    let out = '', err = '';
-    child.stdout.on('data', d => out += d.toString());
-    child.stderr.on('data', d => err += d.toString());
-    const timeout = setTimeout(() => {
-      child.kill('SIGKILL');
-      reject(new Error('claude -p timed out after 120s'));
-    }, 120000);
-    child.on('close', code => {
-      clearTimeout(timeout);
-      if (code !== 0) return reject(new Error(`claude -p exited ${code}: ${err.slice(0, 200)}`));
-      resolveP(out.trim());
-    });
-    child.on('error', e => { clearTimeout(timeout); reject(e); });
-  });
-}
-
 async function callClaudeViaApi(systemPrompt, userPrompt, maxTokens = 1024) {
   const body = JSON.stringify({
     model: MODEL,
@@ -225,10 +181,7 @@ async function callClaude(systemPrompt, userPrompt, maxTokens = 1024) {
   if (ANTHROPIC_API_KEY) {
     return callClaudeViaApi(systemPrompt, userPrompt, maxTokens);
   }
-  if (USE_CLAUDE_CLI) {
-    return callClaudeViaCli(systemPrompt, userPrompt, maxTokens);
-  }
-  throw new Error('No LLM path available: set ANTHROPIC_API_KEY or install `claude` CLI');
+  throw new Error('No LLM path available: set ANTHROPIC_API_KEY (or use the /monomind:understand slash command, which orchestrates LLM work via the active Claude Code session)');
 }
 
 function parseJson(text) {
@@ -632,10 +585,36 @@ async function main() {
     process.exit(1);
   }
 
+  // Detect non-local filesystems where better-sqlite3 can't acquire file locks
+  // (NFS, SMB, FUSE volumes — typically /Volumes/* on macOS or /mnt/* on Linux).
+  // When detected, copy the DB to /tmp, work there, copy back atomically at end.
+  let workingDbPath = dbPathArg;
+  let dbWasShadowed = false;
+  let originalDbPath = dbPathArg;
+  const isNetworkFs = /^\/Volumes\//.test(dbPathArg) ||
+                       /^\/mnt\//.test(dbPathArg) ||
+                       /^\/media\//.test(dbPathArg) ||
+                       /^\\\\/.test(dbPathArg);  // UNC paths on Windows
+  if (isNetworkFs && !dryRun) {
+    const os = await import('node:os');
+    const crypto = await import('node:crypto');
+    const tmpName = 'monograph-work-' + crypto.randomBytes(6).toString('hex') + '.db';
+    workingDbPath = join(os.tmpdir(), tmpName);
+    try {
+      console.log(`[understand] DB is on a non-local filesystem (${dbPathArg}). Copying to ${workingDbPath} to avoid SQLite lock issues...`);
+      const { copyFileSync } = await import('node:fs');
+      copyFileSync(originalDbPath, workingDbPath);
+      dbWasShadowed = true;
+    } catch (e) {
+      console.warn(`[understand] Could not copy to /tmp (${e.message}). Trying in place...`);
+      workingDbPath = dbPathArg;
+    }
+  }
+
   // Retry openDb against SQLite BUSY when monograph is building in the background
   let db;
   for (let attempt = 0; attempt < 5; attempt++) {
-    try { db = mg.openDb(dbPathArg); break; }
+    try { db = mg.openDb(workingDbPath); break; }
     catch (e) {
       if (attempt === 4) throw e;
       const msg = String(e?.message || e);
@@ -699,22 +678,19 @@ async function main() {
   const batch = toAnalyze.slice(0, limit);
   console.log(`[understand] Analyzing ${batch.length} files (${toAnalyze.length - batch.length} skipped/already enriched)`);
 
-  // Prefer the CLI passthrough when available — monomind is designed to run
-  // inside an authenticated Claude Code session and the CLI reuses that auth
-  // without prompting for an API key. Direct API only takes precedence when
-  // explicitly opted into (MONOMIND_PREFER_API=1).
-  const preferApi = process.env.MONOMIND_PREFER_API === '1';
-  const llmPath = (preferApi && ANTHROPIC_API_KEY) ? 'api'
-                : USE_CLAUDE_CLI ? 'claude-cli'
-                : ANTHROPIC_API_KEY ? 'api'
-                : 'none';
+  // LLM path: direct Anthropic API only. The script does NOT try to spawn
+  // `claude -p` from within Claude Code subprocesses — that hangs because
+  // nested CLI sessions aren't supported. For LLM enrichment without an API
+  // key, use the /monomind:understand slash command which orchestrates LLM
+  // work via the active Claude Code session inline.
+  const llmPath = ANTHROPIC_API_KEY ? 'api' : 'none';
   if (llmPath === 'none' && !noLlm) {
-    console.warn('[understand] No LLM path available — `claude` CLI not found on PATH and ANTHROPIC_API_KEY not set. Running in heuristic mode.');
-    console.warn('[understand] Tip: install Claude Code or set ANTHROPIC_API_KEY to enable per-file summaries.');
-  } else if (llmPath === 'claude-cli' && !noLlm) {
-    console.log('[understand] LLM path: `claude -p` CLI passthrough (reusing Claude Code session, no key needed)');
+    console.log('[understand] No ANTHROPIC_API_KEY — running in heuristic mode for layer detection.');
+    console.log('[understand] For per-file summaries: either set ANTHROPIC_API_KEY for direct API,');
+    console.log('[understand] or use the /monomind:understand slash command from inside Claude Code');
+    console.log('[understand] (the slash command does inline analysis via the active session, no key needed).');
   } else if (llmPath === 'api' && !noLlm) {
-    console.log('[understand] LLM path: direct Anthropic API (ANTHROPIC_API_KEY set)');
+    console.log('[understand] LLM path: direct Anthropic API');
   }
   const useLlm = !noLlm && llmPath !== 'none';
 
@@ -863,13 +839,27 @@ async function main() {
     console.log(`║  ONBOARDING.md:   ${relative(CWD, onboardOut).padEnd(31)}║`);
   }
   console.log('╚══════════════════════════════════════════════════╝');
+
+  // Copy DB back if we shadowed it on /tmp due to network FS
+  if (dbWasShadowed && !dryRun) {
+    try {
+      const { copyFileSync, unlinkSync } = await import('node:fs');
+      try { db.close(); } catch {}
+      console.log(`[understand] Copying enriched DB back to ${originalDbPath}...`);
+      copyFileSync(workingDbPath, originalDbPath);
+      try { unlinkSync(workingDbPath); } catch {}
+    } catch (e) {
+      console.error(`[understand] Failed to copy DB back: ${e.message}`);
+      console.error(`[understand] Enriched DB is at ${workingDbPath} — copy manually if needed.`);
+    }
+  }
 }
 
 // ── Detect layers and write communities to DB ────────────────────────────────
 async function detectAndWriteLayers(db, fileNodes, forceHeuristic, dryRun, dir) {
   let layers;
 
-  if (!forceHeuristic && (ANTHROPIC_API_KEY || USE_CLAUDE_CLI)) {
+  if (!forceHeuristic && ANTHROPIC_API_KEY) {
     console.log('[understand] Detecting architectural layers via LLM...');
     const filePaths = fileNodes.map(n => n.file_path).filter(Boolean);
     try {