vexp-cli 3.1.2 → 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/cli.js

@@ -74,6 +74,14 @@ program.hook("preAction", async (_thisCmd, actionCmd) => {
     // 2026-09-05). Doing nothing quietly is the one outcome that cannot be
     // told apart from success.
     if (!eff) {
+        // `index` and `init` are the commands that CREATE a workspace, so telling
+        // them to go run `vexp setup` first is advice the command is in the middle
+        // of superseding — and it read as a contradiction to a user watching one
+        // invocation warn that no workspace exists and the next one start a daemon
+        // for it (field report, 2026-09-08). The bootstrap still does nothing here;
+        // it just does not misdirect.
+        if (actionCmd.name() === "index" || actionCmd.name() === "init")
+            return;
         console.error(chalk.yellow(`  ⚠ no vexp workspace found from ${process.cwd()} — the daemon and the MCP server were NOT started or updated.`));
         console.error(chalk.dim(`     vexp walks up for .vexp/manifest.json; run 'vexp setup' in the workspace root.`));
         return;
@@ -645,8 +653,9 @@ program
 program
     .command("doctor")
     .description("Diagnose vexp MCP/daemon state — workspace drift, stale daemons, Codex transport, license (no daemon needed)")
-    .action(async () => {
-    await runDoctor();
+    .option("--report [file]", "Also write a shareable Markdown report: this diagnosis, the local tool-call ledger (counts and timings, never contents), daemon log warnings, config — secrets masked (default: .vexp/vexp-report.md)")
+    .action(async (opts) => {
+    await runDoctor({ report: opts.report });
 });
 program
     .command("setup [dir]")