vexp-cli 2.3.0 → 2.3.1

package/dist/agent-config.js

@@ -1613,40 +1613,58 @@ export function installClaudeCodeHook(workspaceRoot) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
     const hookPath = path.join(hookDir, "vexp-guard.sh");
     const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
-    // 1. Write hook script
+    // 1. Write hook script. An identical script must NOT short-circuit the
+    // settings merge below: the 2.3.0→2.3.1 fix changed only the settings
+    // ENTRY (shell form → exec form), so skipping on identical script would
+    // leave every existing install on the broken word-splitting entry forever.
     fs.mkdirSync(hookDir, { recursive: true });
     const existed = fs.existsSync(hookPath);
-    if (existed) {
-        const current = fs.readFileSync(hookPath, "utf-8");
-        if (current === VEXP_GUARD_HOOK)
-            return null; // identical - skip
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === VEXP_GUARD_HOOK;
+    if (!scriptIdentical) {
+        fs.writeFileSync(hookPath, VEXP_GUARD_HOOK, { mode: 0o755 });
     }
-    fs.writeFileSync(hookPath, VEXP_GUARD_HOOK, { mode: 0o755 });
     // 2. Merge hook config into .claude/settings.json
     const read = readJsonConfigSafe(settingsPath);
     if (!read.ok) {
         warnUnparseable(settingsPath);
-        return existed ? "updated" : "created";
+        return scriptIdentical ? null : existed ? "updated" : "created";
     }
     const settings = read.data;
     const hooks = (settings.hooks ?? {});
     const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
     // Aggressively remove ALL vexp-related hook entries (old format, stale matchers, malformed)
     const filtered = existingPreToolUse.filter((h) => !isVexpGuardHookEntry(h));
+    // Exec form (`args` present → direct spawn, no `sh -c`): the old shell-form
+    // `$CLAUDE_PROJECT_DIR/...` word-split on project paths containing spaces,
+    // so sh tried to exec the path's first fragment and the guard NEVER ran —
+    // non-blocking failure, every search went through unguarded. In exec form
+    // Claude Code substitutes `${CLAUDE_PROJECT_DIR}` itself (brace form
+    // required) before spawning. `timeout` is SECONDS (default 600), not ms:
+    // 3000 configured a 50-minute hook timeout.
     filtered.push({
         matcher: "Grep|Glob|Regex",
         hooks: [
             {
                 type: "command",
-                command: "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh",
-                timeout: 3000,
+                command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/vexp-guard.sh",
+                args: [],
+                timeout: 5,
             },
         ],
     });
-    settings.hooks = { ...hooks, PreToolUse: filtered };
-    if (read.existed)
-        backupConfig(settingsPath);
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    // Idempotence check AFTER the merge is computed: skip the write (and the
+    // backup) only when settings already contain exactly the entry we would
+    // write AND the script was already current.
+    const merged = { ...hooks, PreToolUse: filtered };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    if (!settingsIdentical) {
+        if (read.existed)
+            backupConfig(settingsPath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
     return existed ? "updated" : "created";
 }
 // ---------------------------------------------------------------------------

package/dist/doctor.js

@@ -2,6 +2,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as net from "net";
+import { spawnSync } from "child_process";
 import chalk from "chalk";
 import { socketPathFor } from "./socket-path.js";
 // `vexp doctor` — audit the vexp MCP/daemon state WITHOUT connecting to a daemon.
@@ -158,7 +159,12 @@ export async function runDoctor() {
                 line(OK, `sessions (4h): ${sessions.length} active, ${total} pipeline calls total`);
             }
             else if (Number(st.daemon_uptime_s) > 600) {
-                line(WARN, `no agent session has called vexp since daemon start — if an agent is working here, it is not using vexp (check its MCP config)`);
+                // Embedded caveat: a stdio MCP server (`vexp-core mcp`) spawned while
+                // the daemon was unreachable serves from its own in-process index and
+                // never attaches to the daemon later — its calls are real but
+                // invisible to these counters. Don't tell that user "the agent is not
+                // using vexp"; tell them how to converge on the daemon.
+                line(WARN, `no agent session has called vexp through this daemon since it started — either no agent is using vexp here (check its MCP config), or the agent's vexp MCP server started BEFORE the daemon and is running embedded (in-process). If calls do succeed in the agent, restart the agent (with the daemon already up) so its MCP server attaches to the daemon.`);
             }
             else {
                 line(OK, `no session calls yet (daemon just started)`);
@@ -220,32 +226,44 @@ export async function runDoctor() {
             line(OK, `${name}: valid, ~${days}d remaining`);
         }
     }
-    // 4) Codex MCP transport stanza.
-    console.log(chalk.bold("\nCodex (~/.codex/config.toml)"));
-    const codexPath = path.join(os.homedir(), ".codex", "config.toml");
-    if (!fs.existsSync(codexPath)) {
-        line(OK, "no ~/.codex/config.toml (Codex not configured)");
-    }
-    else {
-        const toml = fs.readFileSync(codexPath, "utf-8");
+    // 4) Codex MCP transport stanza — global AND project-level. Codex supports
+    // per-project `.codex/config.toml`; checking only the global file made
+    // doctor report "[OK] no stanza" to users whose (working) config lives in
+    // the workspace.
+    console.log(chalk.bold("\nCodex (config.toml)"));
+    const codexConfigs = [
+        { label: "~/.codex/config.toml", file: path.join(os.homedir(), ".codex", "config.toml") },
+        { label: `${ws.root}/.codex/config.toml (project)`, file: path.join(ws.root, ".codex", "config.toml") },
+    ];
+    let codexStanzaSeen = false;
+    for (const { label, file } of codexConfigs) {
+        if (!fs.existsSync(file)) {
+            line(OK, `${label}: absent`);
+            continue;
+        }
+        const toml = fs.readFileSync(file, "utf-8");
         const m = toml.match(/\n?\[mcp_servers\.vexp\][\s\S]*?(?=\n\[[A-Za-z_]|$)/);
         const section = m ? m[0] : "";
-        if (!section)
-            line(OK, "no [mcp_servers.vexp] stanza");
-        else {
-            const hasUrl = /^\s*url\s*=/m.test(section);
-            const hasCmd = /^\s*command\s*=/m.test(section);
-            if (hasUrl && hasCmd)
-                line(BAD, "stanza has BOTH 'url' and 'command' → 'url is not supported for stdio'. Re-run setup to rewrite cleanly.");
-            else if (hasUrl)
-                line(OK, "transport: http (url)");
-            else if (hasCmd) {
-                const wsm = section.match(/VEXP_WORKSPACE\s*=\s*['"]([^'"]+)['"]/);
-                line(OK, `transport: stdio (command)${wsm ? `, VEXP_WORKSPACE=${wsm[1]}` : ""}`);
-            }
-            else
-                line(WARN, "stanza present but neither url nor command found");
+        if (!section) {
+            line(OK, `${label}: no [mcp_servers.vexp] stanza`);
+            continue;
+        }
+        codexStanzaSeen = true;
+        const hasUrl = /^\s*url\s*=/m.test(section);
+        const hasCmd = /^\s*command\s*=/m.test(section);
+        if (hasUrl && hasCmd)
+            line(BAD, `${label}: stanza has BOTH 'url' and 'command' → 'url is not supported for stdio'. Re-run setup to rewrite cleanly.`);
+        else if (hasUrl)
+            line(OK, `${label}: transport http (url)`);
+        else if (hasCmd) {
+            const wsm = section.match(/VEXP_WORKSPACE\s*=\s*['"]([^'"]+)['"]/);
+            line(OK, `${label}: transport stdio (command)${wsm ? `, VEXP_WORKSPACE=${wsm[1]}` : ""}`);
         }
+        else
+            line(WARN, `${label}: stanza present but neither url nor command found`);
+    }
+    if (!codexStanzaSeen) {
+        console.log(chalk.dim("        → no vexp stanza in either file (Codex not configured for vexp)"));
     }
     // 5) Claude Code entry (should be UNPINNED after the multi-session fix).
     console.log(chalk.bold("\nClaude Code (~/.claude.json)"));
@@ -263,6 +281,144 @@ export async function runDoctor() {
     catch {
         line(OK, "no ~/.claude.json");
     }
+    // 5b) Claude Code guard hook — EXECUTE it the way Claude Code would, don't
+    // just check presence. A shell-form command that word-splits on a project
+    // path containing a space fails non-blocking on every call: the guard never
+    // denies anything while the config "looks correct" and presence-only checks
+    // report healthy (Nathan, 2026-07).
+    console.log(chalk.bold("\nClaude Code guard hook (.claude/settings.json)"));
+    {
+        const sPath = path.join(ws.root, ".claude", "settings.json");
+        let guardHooks = [];
+        let settingsReadable = false;
+        try {
+            const settings = JSON.parse(fs.readFileSync(sPath, "utf-8"));
+            settingsReadable = true;
+            const pre = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+            for (const m of pre) {
+                const hks = Array.isArray(m?.hooks) ? m.hooks : [];
+                for (const h of hks) {
+                    if (typeof h?.command === "string" && h.command.includes("vexp-guard"))
+                        guardHooks.push(h);
+                }
+            }
+        }
+        catch { /* absent or unparseable */ }
+        if (!settingsReadable) {
+            line(OK, "no .claude/settings.json (guard not installed)");
+        }
+        else if (guardHooks.length === 0) {
+            line(OK, "no vexp guard configured (2.3 default — enable with 'vexp setup --guard-strict')");
+        }
+        else if (process.platform === "win32") {
+            line(OK, `guard configured (${guardHooks.length} entry) — live execution check skipped on Windows`);
+        }
+        else {
+            for (const h of guardHooks) {
+                const cmd = h.command;
+                const execForm = Array.isArray(h.args);
+                const timeoutS = typeof h.timeout === "number" ? h.timeout : 600;
+                if (!execForm && /\$\{?CLAUDE_PROJECT_DIR\}?\//.test(cmd) && !cmd.includes('"')) {
+                    line(ws.root.includes(" ") ? BAD : WARN, `shell-form hook command ('args' missing) — unquoted $CLAUDE_PROJECT_DIR word-splits on paths with spaces${ws.root.includes(" ") ? ` and THIS project path has one: the guard never runs` : ""}. Re-run 'vexp setup --guard-strict' to rewrite in exec form.`);
+                }
+                if (timeoutS > 600) {
+                    line(WARN, `hook timeout ${timeoutS} is in SECONDS (${Math.round(timeoutS / 60)} minutes) — likely meant milliseconds. Re-run 'vexp setup --guard-strict' to fix.`);
+                }
+                // Run it exactly as Claude Code would: exec form = direct spawn with
+                // the placeholder substituted by the host; shell form = sh -c with
+                // CLAUDE_PROJECT_DIR in the environment.
+                const substituted = cmd.replace(/\$\{CLAUDE_PROJECT_DIR\}/g, ws.root);
+                const r = execForm
+                    ? spawnSync(substituted, h.args.map((a) => String(a).replace(/\$\{CLAUDE_PROJECT_DIR\}/g, ws.root)), {
+                        env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                        timeout: 5000,
+                        encoding: "utf-8",
+                    })
+                    : spawnSync("sh", ["-c", cmd], {
+                        env: { ...process.env, CLAUDE_PROJECT_DIR: ws.root },
+                        timeout: 5000,
+                        encoding: "utf-8",
+                    });
+                if (r.error) {
+                    line(BAD, `guard hook DID NOT RUN: ${r.error.code ?? r.error.message} spawning '${substituted}' — the guard is enforcing nothing. Re-run 'vexp setup --guard-strict'.`);
+                }
+                else if (r.status !== 0) {
+                    line(BAD, `guard hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 200)}` : ""} — Claude Code treats this as a non-blocking failure, so searches proceed unguarded.`);
+                }
+                else {
+                    const decision = /"permissionDecision"\s*:\s*"(\w+)"/.exec(String(r.stdout ?? ""))?.[1];
+                    if (decision)
+                        line(OK, `guard hook runs (live decision here: ${decision})`);
+                    else
+                        line(WARN, `guard hook ran (exit 0) but produced no permissionDecision output — check ${path.join(".claude", "hooks", "vexp-guard.sh")}`);
+                }
+            }
+        }
+    }
+    // 5c) Cursor guard hook — same live-execution philosophy as 5b. Cursor's
+    // hooks fail OPEN too (`failClosed` defaults to false), so a guard that
+    // cannot spawn silently enforces nothing there as well. The guard's stdin
+    // protocol: JSON {tool_name, tool_input, workspace_roots, cwd}; a healthy
+    // run answers {"permission":"allow"} with exit 0 OR a deny verdict with
+    // exit 2 — BOTH mean "the hook works", anything else is a failure.
+    console.log(chalk.bold("\nCursor guard hook (.cursor/hooks.json)"));
+    {
+        const cursorCfgPath = path.join(ws.root, ".cursor", "hooks.json");
+        let cursorCmds = [];
+        let cursorReadable = false;
+        try {
+            const cfg = JSON.parse(fs.readFileSync(cursorCfgPath, "utf-8"));
+            cursorReadable = true;
+            const pre = Array.isArray(cfg?.hooks?.preToolUse) ? cfg.hooks.preToolUse : [];
+            for (const h of pre) {
+                if (typeof h?.command === "string" && h.command.includes("vexp-guard"))
+                    cursorCmds.push(h.command);
+            }
+        }
+        catch { /* absent or unparseable */ }
+        if (!cursorReadable) {
+            line(OK, "no .cursor/hooks.json (guard not installed)");
+        }
+        else if (cursorCmds.length === 0) {
+            line(OK, "no vexp guard configured (enable with 'vexp setup --guard-strict')");
+        }
+        else if (process.platform === "win32") {
+            line(OK, `guard configured (${cursorCmds.length} entry) — live execution check skipped on Windows`);
+        }
+        else {
+            // A benign Grep probe: with a healthy daemon the guard denies (exit 2),
+            // without one it allows (exit 0) — either proves the hook executes.
+            const probe = JSON.stringify({
+                tool_name: "Grep",
+                tool_input: {},
+                workspace_roots: [ws.root],
+                cwd: ws.root,
+            });
+            for (const cmd of cursorCmds) {
+                // Cursor runs project hooks from the project root; emulate that.
+                const r = spawnSync("sh", ["-c", cmd], {
+                    cwd: ws.root,
+                    input: probe,
+                    timeout: 5000,
+                    encoding: "utf-8",
+                });
+                if (r.error) {
+                    line(BAD, `guard hook DID NOT RUN: ${r.error.code ?? r.error.message} spawning '${cmd}' — Cursor hooks fail open, so the guard is enforcing nothing. Re-run 'vexp setup --guard-strict'.`);
+                    continue;
+                }
+                const decision = /"permission"\s*:\s*"(\w+)"/.exec(String(r.stdout ?? ""))?.[1];
+                if ((r.status === 0 || r.status === 2) && decision) {
+                    line(OK, `guard hook runs (live decision here: ${decision})`);
+                }
+                else if (r.status !== 0 && r.status !== 2) {
+                    line(BAD, `guard hook exited ${r.status}${r.stderr ? ` — ${String(r.stderr).trim().slice(0, 200)}` : ""} — Cursor treats hook failures as allow, so searches proceed unguarded.`);
+                }
+                else {
+                    line(WARN, `guard hook ran (exit ${r.status}) but produced no permission verdict — check ${path.join(".cursor", "hooks", "vexp-guard.js")}`);
+                }
+            }
+        }
+    }
     // 6) HTTP MCP supervisor.
     console.log(chalk.bold("\nHTTP MCP supervisor (~/.vexp/mcp.pid)"));
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexp-cli",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Vexp — Context Engine for AI Coding Agents. Pre-indexes your codebase into a dependency graph and delivers ranked context to any MCP-compatible agent. 58% lower cost per task, 90% fewer tool calls (SWE-bench Verified). Works with Claude Code, Cursor, Copilot, Windsurf, Codex, Cline, Aider, and 12+ agents. Local-first. Your code never leaves your machine.",
   "type": "module",
   "bin": {
@@ -100,10 +100,10 @@
     "node": ">=20.0.0"
   },
   "optionalDependencies": {
-    "@vexp/core-linux-x64": "2.3.0",
-    "@vexp/core-linux-arm64": "2.3.0",
-    "@vexp/core-darwin-x64": "2.3.0",
-    "@vexp/core-darwin-arm64": "2.3.0",
-    "@vexp/core-win32-x64": "2.3.0"
+    "@vexp/core-linux-x64": "2.3.1",
+    "@vexp/core-linux-arm64": "2.3.1",
+    "@vexp/core-darwin-x64": "2.3.1",
+    "@vexp/core-darwin-arm64": "2.3.1",
+    "@vexp/core-win32-x64": "2.3.1"
   }
 }