vexp-cli 3.1.3 → 3.2.0

package/README.md

@@ -62,7 +62,7 @@ vexp doctor
 
 ## Supported agents
 
-Claude Code · Cursor · Windsurf · GitHub Copilot · OpenAI Codex · Zed · Continue.dev · Cline · Aider · Kiro · Kilo Code · opencode · Augment · Antigravity
+Claude Code · Cursor · Windsurf · GitHub Copilot · OpenAI Codex · Zed · Continue.dev · Cline · Aider · Kiro · Kilo Code · opencode · Augment · Antigravity · ZCode · Friday Code
 
 ## Supported languages
 

package/dist/agent-config.js

@@ -246,6 +246,29 @@ const AGENT_DETECTORS = [
         // MCP is machine-global (~/.gemini/antigravity/mcp_config.json) — handled
         // by configureAntigravityGlobal(), not via mcpConfigFile.
     },
+    {
+        // ZCode (zcode.z.ai), Z.ai's desktop agentic IDE. It reads the
+        // cross-tool AGENTS.md; CLAUDE.md is a one-time onboarding import it
+        // never reads at runtime. MCP is `mcp.servers` inside .zcode/config.json
+        // — written by configureZcodeMcp(), not via mcpConfigFile, because the
+        // shape is not `mcpServers`. Hooks are user-level only; see the ZCode
+        // section below.
+        agent: "ZCode",
+        detectPath: ".zcode",
+        configFile: "AGENTS.md",
+        templateName: "agents-md",
+    },
+    {
+        // Friday Code (tryfriday.ai): reads `friday.md` at the project root — the
+        // same mandate every AGENTS.md agent gets, under a name of its own. It
+        // connects to vexp on its side, so there is no MCP file to write here:
+        // the instructions are the whole integration. Detected by the file
+        // itself, as Codex is by AGENTS.md.
+        agent: "Friday Code",
+        detectPath: "friday.md",
+        configFile: "friday.md",
+        templateName: "agents-md",
+    },
 ];
 // ---------------------------------------------------------------------------
 // Public API
@@ -320,6 +343,10 @@ export function plannedWrites(agent, guard = guardMode(), interventions = interv
         case "GitHub Copilot":
             out.push(".vscode/mcp.json  (MCP server entry)");
             break;
+        case "ZCode":
+            out.push(".zcode/config.json `mcp.servers`  (MCP server entry; .agents/mcp.json instead when the project keeps its servers there)");
+            out.push("~/.zcode/cli/config.json hooks.events.UserPromptSubmit  (orientation, user scope: ZCode runs no project hooks)");
+            break;
         default:
             break;
     }
@@ -507,6 +534,24 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             if (wrote)
                 mcpConfigs.push("~/.gemini/antigravity/mcp_config.json");
         }
+        // ZCode: `mcp.servers` in .zcode/config.json (or the .agents/mcp.json
+        // compatibility file when that is what the project uses) + the
+        // orientation hook in ZCode's USER config — see configureZcodeMcp.
+        if (detector.agent === "ZCode") {
+            const wrote = configureZcodeMcp(workspaceRoot, binaryPath);
+            if (wrote)
+                mcpConfigs.push(wrote);
+            const hint = installZcodeHintHook(binaryPath);
+            if (hint) {
+                results.push({
+                    agent: "ZCode Hint",
+                    configFile: "~/.zcode/cli/config.json",
+                    content: "",
+                    alreadyExists: hint === "updated",
+                    action: hint,
+                });
+            }
+        }
         // GitHub Copilot: VS Code format (.vscode/mcp.json with "servers" key)
         if (detector.agent === "GitHub Copilot") {
             const mcpPath = path.join(workspaceRoot, ".vscode/mcp.json");
@@ -831,6 +876,12 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (wrote)
                 mcpConfigs.push("~/.gemini/antigravity/mcp_config.json");
         }
+        if (detector.agent === "ZCode") {
+            const wrote = configureZcodeMcp(workspaceRoot, binaryPath);
+            if (wrote)
+                mcpConfigs.push(wrote);
+            installZcodeHintHook(binaryPath);
+        }
         if (detector.agent === "GitHub Copilot") {
             const mcpPath = path.join(workspaceRoot, ".vscode/mcp.json");
             if (writeVsCodeMcpConfig(mcpPath, binaryPath, mcpServerPath, workspaceRoot))
@@ -1150,7 +1201,7 @@ export function isEditorExecutable(entry) {
     // recognised when read from WSL/CI too (path.basename splits only on the
     // host's separator).
     const base = (command.split(/[\\/]/).pop() ?? "").toLowerCase().replace(/\.exe$/, "");
-    return ["code", "code-insiders", "code-oss", "cursor", "windsurf", "windsurf-next", "trae", "kiro", "zed", "antigravity", "electron", "devin"].includes(base);
+    return ["code", "code-insiders", "code-oss", "cursor", "windsurf", "windsurf-next", "trae", "kiro", "zed", "antigravity", "electron", "devin", "zcode"].includes(base);
 }
 export function isBareInterpreter(entry) {
     if (!entry || typeof entry !== "object")
@@ -1688,6 +1739,164 @@ approveKey = "alwaysAllow") {
     fs.writeFileSync(mcpConfigPath, JSON.stringify(existing, null, 2), "utf-8");
     return true;
 }
+// ---------------------------------------------------------------------------
+// ZCode (zcode.z.ai) — Z.ai's desktop agentic IDE, GLM-powered.
+//
+// Three facts from its docs (v3.11) shape everything below:
+//
+//   1. Instructions: it reads the cross-tool AGENTS.md at the workspace root
+//      (plus ~/.zcode/AGENTS.md). CLAUDE.md is a one-time onboarding import,
+//      never read at runtime — hence the agents-md template, like Codex.
+//   2. MCP: `mcp.servers.<name>` inside `<root>/.zcode/config.json`, with
+//      `<root>/.agents/mcp.json` (`mcpServers` shape) as a compatibility
+//      fallback read ONLY while no .zcode config exists. Creating the native
+//      file therefore silently unplugs every server a project keeps in the
+//      compatibility one — see zcodeMcpTarget.
+//   3. Hooks: user-level only (~/.zcode/cli/config.json); a `hooks` block in
+//      the workspace config is ignored by design. Payload and reply are
+//      Claude Code's (stdin JSON with `prompt` and `cwd`, stdout
+//      `hookSpecificOutput.additionalContext`), so `vexp-core prompt-hint`
+//      runs unchanged — as a `process` hook, argv without a shell, which
+//      sidesteps the bash-vs-cmd quoting every other hook here carries.
+//
+// It is a GUI app launched from a dock or Start menu, so the MCP command is
+// the vexp binary itself, never `node`: the Kiro lesson, where a
+// PATH-resolved `node` was not found and the server silently never started.
+// ---------------------------------------------------------------------------
+/**
+ * Where ZCode's project MCP entry goes: the native file, unless the project
+ * has none and keeps its servers in the `.agents/mcp.json` compatibility
+ * file. ZCode stops reading that file the moment `.zcode/config.json`
+ * exists, so writing the native one there would disconnect the user's other
+ * servers in order to connect ours.
+ */
+export function zcodeMcpTarget(workspaceRoot) {
+    const native = path.join(workspaceRoot, ".zcode", "config.json");
+    if (fs.existsSync(native))
+        return native;
+    const compat = path.join(workspaceRoot, ".agents", "mcp.json");
+    const read = readJsonConfigSafe(compat);
+    if (read.existed && read.ok) {
+        const servers = read.data.mcpServers;
+        if (servers && typeof servers === "object" && Object.keys(servers).length > 0)
+            return compat;
+    }
+    return native;
+}
+/**
+ * Register vexp with ZCode. Returns the workspace-relative path written, or
+ * null when nothing changed: already registered, a working entry adopted, or
+ * a file that would not parse (reported through warnUnparseable, never
+ * overwritten).
+ */
+export function configureZcodeMcp(workspaceRoot, binaryPath) {
+    const target = zcodeMcpTarget(workspaceRoot);
+    const rel = path.relative(workspaceRoot, target).replace(/\\/g, "/");
+    if (rel === ".agents/mcp.json") {
+        // The compatibility file has the mcpServers shape the shared writer
+        // knows; withholding mcpServerPath selects the binary transport.
+        return writeMcpConfig(target, binaryPath, undefined, undefined, workspaceRoot) ? rel : null;
+    }
+    const read = readJsonConfigSafe(target);
+    if (!read.ok) {
+        warnUnparseable(target);
+        return null;
+    }
+    const cfg = read.data;
+    const mcp = (cfg.mcp && typeof cfg.mcp === "object" ? cfg.mcp : {});
+    const servers = (mcp.servers && typeof mcp.servers === "object" ? mcp.servers : {});
+    const targetArgs = ["mcp"];
+    const targetEnv = { VEXP_WORKSPACE: workspaceRoot };
+    const prev = servers["vexp"];
+    const envMatches = JSON.stringify(prev?.env) === JSON.stringify(targetEnv);
+    const identical = prev?.command === binaryPath &&
+        JSON.stringify(prev?.args) === JSON.stringify(targetArgs) &&
+        envMatches;
+    if (identical)
+        return null;
+    // Another vexp install already left a working entry here — don't fight it.
+    // The VEXP_WORKSPACE pin still gates, so a moved project is repinned.
+    if (envMatches && adoptableEntry(prev))
+        return null;
+    servers["vexp"] = { command: binaryPath, args: targetArgs, env: targetEnv };
+    mcp.servers = servers;
+    cfg.mcp = mcp;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (read.existed)
+        backupConfig(target);
+    fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    return rel;
+}
+/** ZCode's user-level config — the only place it runs hooks from. */
+export function zcodeUserConfigPath() {
+    return path.join(os.homedir(), ".zcode", "cli", "config.json");
+}
+/** Does this UserPromptSubmit entry belong to us? Ours runs the vexp binary's `prompt-hint`. */
+function isVexpZcodeHookEntry(h) {
+    if (!h || typeof h !== "object")
+        return false;
+    const hks = h.hooks;
+    if (!Array.isArray(hks))
+        return false;
+    return hks.some((hook) => {
+        if (!hook || typeof hook !== "object")
+            return false;
+        const e = hook;
+        const cmd = typeof e.command === "string" ? e.command : "";
+        const args = Array.isArray(e.args) ? e.args.join(" ") : "";
+        return cmd.includes("vexp-hint") || (/vexp/i.test(cmd) && args.includes("prompt-hint"));
+    });
+}
+function noteZcodeHooksDisabled(cfgPath) {
+    const msg = `ZCode hooks are switched off in ${cfgPath} (hooks.enabled: false). ` +
+        "The vexp orientation hook is registered there but stays inert until hooks are enabled in ZCode.";
+    if (!unreachableTargets.includes(msg))
+        unreachableTargets.push(msg);
+}
+/**
+ * The orientation hook, user scope — ZCode runs no project-level hooks.
+ *
+ * One entry serves every workspace on the machine: `prompt-hint` takes the
+ * workspace from the `cwd` the payload carries, and is fail-open by
+ * construction — no daemon there, no index, no binary: nothing is injected
+ * and the session is vanilla. `hooks.enabled` is switched on only when that
+ * is not already a decision: a user who set it to false while keeping hooks
+ * of their own has turned hooks off on purpose, and that is honoured (the
+ * entry is still registered, so enabling hooks later activates it, and the
+ * setup summary says so).
+ */
+export function installZcodeHintHook(binaryPath) {
+    const cfgPath = zcodeUserConfigPath();
+    const read = readJsonConfigSafe(cfgPath);
+    if (!read.ok) {
+        warnUnparseable(cfgPath);
+        return null;
+    }
+    const cfg = read.data;
+    const before = JSON.stringify(cfg);
+    const hooks = (cfg.hooks && typeof cfg.hooks === "object" ? cfg.hooks : {});
+    const events = (hooks.events && typeof hooks.events === "object" ? hooks.events : {});
+    const existing = Array.isArray(events.UserPromptSubmit) ? events.UserPromptSubmit : [];
+    const filtered = existing.filter((h) => !isVexpZcodeHookEntry(h));
+    filtered.push({
+        hooks: [{ type: "process", command: binaryPath, args: ["prompt-hint"], timeoutMs: 5000 }],
+    });
+    events.UserPromptSubmit = filtered;
+    hooks.events = events;
+    const theirs = Object.entries(events).some(([event, list]) => Array.isArray(list) && list.some((h) => event !== "UserPromptSubmit" || !isVexpZcodeHookEntry(h)));
+    if (hooks.enabled === false && theirs)
+        noteZcodeHooksDisabled(cfgPath);
+    else
+        hooks.enabled = true;
+    cfg.hooks = hooks;
+    if (JSON.stringify(cfg) === before)
+        return null;
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+    if (read.existed)
+        backupConfig(cfgPath);
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    return read.existed ? "updated" : "created";
+}
 /**
  * Read or generate a bearer token for MCP HTTP auth.
  * Persists to ~/.vexp/mcp.token so the MCP server and Codex config share it.
@@ -2800,6 +3009,9 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
             {
                 type: "command",
                 command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-hint.sh"',
+                // The prompt-hint client's budget ceiling (HINT_BUDGET_CEILING_MS,
+                // main.rs) stays under these 5 s: past them the agent kills the
+                // hook while the daemon still believes the client is waiting.
                 timeout: 5,
             },
         ],

package/dist/doctor.js

@@ -373,6 +373,32 @@ export function workspaceCoverageFindings(root) {
     }
     return out;
 }
+/**
+ * The 7-day activity ledger as doctor lines. Zero calls is not "not
+ * working": silence on oriented prompts is vexp doing its job, so the OK
+ * line exists whenever prompts were analyzed. The WARN is the other half of
+ * the same ledger: orientations the daemon finished after the hook client
+ * (3 s) had stopped waiting were computed, counted by 3.1.x as served, and
+ * never read by the agent (field ledger, 3.1.3: up to 8 of 33).
+ */
+export function ledgerFindings(ledger) {
+    const out = [];
+    const analyzed = Number(ledger.prompts_analyzed) || 0;
+    if (analyzed > 0) {
+        out.push({
+            level: OK,
+            message: `savings ledger (7d): ${analyzed} prompt(s) analyzed — ${Number(ledger.silences) || 0} silences (task already oriented), ${Number(ledger.hints_served) || 0} hints served. Details: vexp savings`,
+        });
+    }
+    const late = Number(ledger.late) || 0;
+    if (late > 0) {
+        out.push({
+            level: WARN,
+            message: `${late} orientation(s) in the last 7 days finished after the hook client's budget (3 s by default) and never reached the agent - long prompts are slow on this index; vexp savings shows the count`,
+        });
+    }
+    return out;
+}
 export const SUPPORT_EMAIL = "staff@vexp.dev";
 export const DEFAULT_REPORT_FILE = path.join(".vexp", "vexp-report.md");
 // eslint-disable-next-line no-control-regex
@@ -703,9 +729,8 @@ async function doctorChecks(onWorkspace) {
             // support tickets ("is it working? it never got called").
             const ledger = (st.ledger ?? {});
             const analyzed = Number(ledger.prompts_analyzed) || 0;
-            if (analyzed > 0) {
-                line(OK, `savings ledger (7d): ${analyzed} prompt(s) analyzed — ${Number(ledger.silences) || 0} silences (task already oriented), ${Number(ledger.hints_served) || 0} hints served. Details: vexp savings`);
-            }
+            for (const f of ledgerFindings(ledger))
+                line(f.level, f.message);
             if (sessions.length > 0) {
                 const total = sessions.reduce((n, s) => n + (Number(s.pipeline_calls) || 0), 0);
                 line(OK, `sessions (4h): ${sessions.length} active, ${total} pipeline calls total`);

package/dist/serve.js

@@ -75,6 +75,14 @@ async function resurrectDaemon(workspaceRoot, socketPath) {
         return false;
     }
     try {
+        // `detached` stays. On Windows it is DETACHED_PROCESS: the daemon gets no
+        // console, which is what lets it outlive this supervisor — a non-detached
+        // child sits in libuv's kill-on-close job object and dies with `vexp
+        // serve`. A console-less parent's git children used to open a Windows
+        // Terminal window each (field report, 2026-09: 98 a minute); the cure is
+        // in vexp-core, which spawns every child with CREATE_NO_WINDOW
+        // (packages/vexp-core/src/proc.rs). `windowsHide` would not help here:
+        // Windows ignores it next to DETACHED_PROCESS.
         const child = spawn(binary, ["daemon", "--workspace", workspaceRoot, "--socket", socketPath], {
             detached: true,
             stdio: "ignore",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vexp-cli",
-  "version": "3.1.3",
+  "version": "3.2.0",
   "description": "Local-first context engine for AI coding agents. Pre-indexes your codebase into a dependency graph and feeds any MCP agent only the code that matters — 87% fewer tokens per call. New in 2.5: mechanical work verification and a PII/secret scanner. Works with Claude Code, Cursor, Codex, Copilot, Windsurf, Cline, Aider and 14 agents. Your code never leaves your machine.",
   "type": "module",
   "bin": {
@@ -105,10 +105,10 @@
   },
   "homepage": "https://vexp.dev",
   "optionalDependencies": {
-    "@vexp/core-linux-x64": "3.1.3",
-    "@vexp/core-linux-arm64": "3.1.3",
-    "@vexp/core-darwin-x64": "3.1.3",
-    "@vexp/core-darwin-arm64": "3.1.3",
-    "@vexp/core-win32-x64": "3.1.3"
+    "@vexp/core-linux-x64": "3.2.0",
+    "@vexp/core-linux-arm64": "3.2.0",
+    "@vexp/core-darwin-x64": "3.2.0",
+    "@vexp/core-darwin-arm64": "3.2.0",
+    "@vexp/core-win32-x64": "3.2.0"
   }
 }