@davesheffer/hunch 1.32.3 → 1.32.5

package/dist/integrations/providers.d.ts

@@ -49,6 +49,13 @@ export declare function writeWindsurfRule(root: string, store: HunchStore): stri
  * registration remain the durable grounding path if a Cursor build suppresses
  * a hook's agent_message. */
 export declare function writeCursorHooks(root: string, inv: Invocation): string;
+/** Codex CLI hooks (0.153+): `.codex/hooks.json`, the same event names, stdin
+ * payload, and stdout contract as Claude Code, with `turn_id` as the per-prompt
+ * identity and `apply_patch` as the edit tool. Project-layer hooks load only for
+ * a trusted project and must be trusted once in Codex (`/hooks`), which the
+ * scaffold output says. Codex's PreToolUse rejects `continue:false`, so the
+ * strict gate answers with `permissionDecision` — the shape Hunch already emits. */
+export declare function writeCodexHooks(root: string, inv: Invocation): string;
 /** VS Code's native workspace hook location. It supports all lifecycle events
  * Hunch needs and uses the same stdout contract as Claude Code, with different
  * camelCase tool fields normalized in core/agenthook.ts. */

package/dist/integrations/providers.js

@@ -24,6 +24,7 @@ import { join, dirname } from "node:path";
 import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd } from "./claudemd.js";
 import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 import { parseJsonc } from "../core/jsonc.js";
+import { parse as parseToml } from "smol-toml";
 /** Read a JSON/JSONC object. Returns {} only for an ABSENT or empty file. A
  *  non-empty file we cannot parse THROWS — overwriting it would silently wipe the
  *  user's other MCP servers. */
@@ -65,6 +66,18 @@ function writeJson(file, obj) {
     writeFileAtomic(file, JSON.stringify(obj, null, 2) + "\n");
     return file;
 }
+/** A present managed container must have the object shape its host expects.
+ * Arrays and primitives are valid JSON/TOML values, but assigning properties to
+ * them either throws or silently disappears during JSON serialization. Refuse
+ * those shapes instead of claiming an install succeeded. */
+function objectField(json, key, file) {
+    const value = json[key];
+    if (value === undefined)
+        return {};
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return value;
+    throw new Error(`refusing to edit ${file}: ${key} must be a JSON object when present; fix it, then re-run.`);
+}
 /** Quote one argv token only when it needs quoting. These commands are run by
  * whatever shell the host assistant uses, which on Windows is PowerShell — and
  * PowerShell parses a QUOTED first token as a string expression, not a command,
@@ -89,6 +102,10 @@ function hookCommand(inv, provider) {
 }
 function isHunchProviderHook(entry) {
     const e = entry && typeof entry === "object" ? entry : null;
+    // Codex (like Claude Code) nests commands under a matcher entry: an entry
+    // whose every nested hook is ours is ours; a mixed entry stays foreign.
+    if (e && Array.isArray(e.hooks) && e.hooks.length && typeof e.command !== "string")
+        return e.hooks.every(isHunchProviderHook);
     const command = typeof e?.command === "string" ? e.command : "";
     // Anchored to the shapes hookCommand() writes — a Hunch launcher (the pinned
     // npm package spec, or a …/index.js|ts path for source installs) plus a tail
@@ -99,7 +116,10 @@ function isHunchProviderHook(entry) {
     // the bare tail must still carry --provider to match; only the LEGACY
     // fully-quoted form (written before this quoting fix, and by hunch versions
     // that predate --provider) may omit it, and its quotes keep it unambiguous.
-    const launcher = /@davesheffer\/hunch|[\\/]index\.(?:js|ts)(?=["\s]|$)/.test(command);
+    // Source-checkout invocations generated by resolveInvocation point at the
+    // CLI entry specifically. A generic `other-tool/index.js hook` is foreign
+    // even when it happens to use Hunch's old command tail.
+    const launcher = /@davesheffer\/hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)(?=["\s]|$)/.test(command);
     const legacyTail = /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
     const tail = /\s"?hook"?\s+"?--provider"?\s+"?[a-z]+"?\s*$/.test(command);
     return launcher && (legacyTail || tail);
@@ -108,11 +128,13 @@ function isHunchProviderHook(entry) {
  * We replace only old Hunch commands and leave every foreign hook in place. */
 function writeHookConfig(file, entries) {
     const json = readJsonObj(file);
-    const hooks = json.hooks && typeof json.hooks === "object" && !Array.isArray(json.hooks)
-        ? json.hooks
-        : {};
+    const hooks = objectField(json, "hooks", file);
     for (const [event, next] of Object.entries(entries)) {
-        const old = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const existing = hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new Error(`refusing to edit ${file}: hooks.${event} must be an array when present; fix it, then re-run.`);
+        }
+        const old = (existing ?? []);
         hooks[event] = [...old.filter((entry) => !isHunchProviderHook(entry)), ...next];
     }
     json.hooks = hooks;
@@ -122,7 +144,7 @@ function writeHookConfig(file, entries) {
 export function writeCursorMcp(root, inv) {
     const file = join(root, ".cursor", "mcp.json");
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -131,7 +153,7 @@ export function writeCursorMcp(root, inv) {
 export function writeVscodeMcp(root, inv) {
     const file = join(root, ".vscode", "mcp.json");
     const json = readJsonObj(file);
-    json.servers = json.servers ?? {};
+    json.servers = objectField(json, "servers", file);
     json.servers.hunch = { type: "stdio", command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -162,7 +184,7 @@ export function writeAntigravityMcp(inv, home = homedir()) {
     if (!file)
         return null;
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -172,7 +194,7 @@ export function writeAntigravityMcp(inv, home = homedir()) {
 export function writeAntigravityWorkspaceMcp(root, inv) {
     const file = join(root, ".agents", "mcp_config.json");
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -189,6 +211,8 @@ export function writeCodexConfig(root, inv) {
         "[mcp_servers.hunch]",
         `command = ${tomlStr(inv.command)}`,
         `args = [${argsToml}]`,
+        "# A cold npx install can exceed Codex's 10 s default; a slow start must not drop Hunch from the tool catalog.",
+        "startup_timeout_sec = 60",
         TOML_END,
     ].join("\n");
     // Strip any prior managed block first, so `base` is the user's own TOML.
@@ -207,9 +231,30 @@ export function writeCodexConfig(root, inv) {
     if (/^\s*\[mcp_servers\.hunch\]/m.test(base)) {
         throw new Error(`refusing to edit ${file}: it already defines [mcp_servers.hunch] outside Hunch's managed block. Remove it, then re-run.`);
     }
+    // Validate the complete original document before stripping any managed block.
+    // Even Hunch-owned malformed content must be preserved until the user reviews
+    // it; otherwise a repair can silently erase an unparseable configuration.
+    if (content.trim()) {
+        try {
+            parseToml(content);
+        }
+        catch (e) {
+            throw new Error(`refusing to overwrite ${file}: could not parse TOML (${e.message}). Fix it, then re-run.`);
+        }
+    }
     base = base.trimEnd();
+    const next = base ? `${base}\n\n${block}\n` : `${block}\n`;
+    // A syntactically valid parent value can still make the appended table
+    // illegal (`mcp_servers = 42` followed by `[mcp_servers.hunch]`). Validate
+    // the exact candidate before touching the user's file.
+    try {
+        parseToml(next);
+    }
+    catch (e) {
+        throw new Error(`refusing to overwrite ${file}: resulting TOML is invalid (${e.message}). Fix it, then re-run.`);
+    }
     mkdirSync(dirname(file), { recursive: true });
-    writeFileAtomic(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
+    writeFileAtomic(file, next);
     return file;
 }
 /** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
@@ -236,7 +281,7 @@ export function writeCursorRule(root, store) {
 export function writeWindsurfMcp(root, inv) {
     const file = join(root, ".windsurf", "mcp_config.json");
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -252,7 +297,7 @@ export function writeWindsurfGlobalMcp(inv, home = homedir()) {
     if (!file)
         return null;
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -286,6 +331,26 @@ export function writeCursorHooks(root, inv) {
     }
     return written;
 }
+/** Codex CLI hooks (0.153+): `.codex/hooks.json`, the same event names, stdin
+ * payload, and stdout contract as Claude Code, with `turn_id` as the per-prompt
+ * identity and `apply_patch` as the edit tool. Project-layer hooks load only for
+ * a trusted project and must be trusted once in Codex (`/hooks`), which the
+ * scaffold output says. Codex's PreToolUse rejects `continue:false`, so the
+ * strict gate answers with `permissionDecision` — the shape Hunch already emits. */
+export function writeCodexHooks(root, inv) {
+    const file = join(root, ".codex", "hooks.json");
+    const command = hookCommand(inv, "codex");
+    const entry = (matcher) => ({ ...(matcher ? { matcher } : {}), hooks: [{ type: "command", command }] });
+    return writeHookConfig(file, {
+        SessionStart: [entry()],
+        UserPromptSubmit: [entry()],
+        PreToolUse: [entry("apply_patch")],
+        PostToolUse: [entry("apply_patch|shell|local_shell")],
+        Stop: [entry()],
+        PreCompact: [entry()],
+        SubagentStart: [entry()],
+    });
+}
 /** VS Code's native workspace hook location. It supports all lifecycle events
  * Hunch needs and uses the same stdout contract as Claude Code, with different
  * camelCase tool fields normalized in core/agenthook.ts. */
@@ -321,9 +386,13 @@ function antigravityHandler(command) {
 export function writeAntigravityHooks(root, inv) {
     const file = join(root, ".agents", "hooks.json");
     const json = readJsonObj(file);
-    const group = json.hunch && typeof json.hunch === "object" && !Array.isArray(json.hunch)
-        ? json.hunch
-        : {};
+    const group = objectField(json, "hunch", file);
+    for (const event of ["PreInvocation", "PreToolUse", "Stop"]) {
+        const existing = group[event];
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new Error(`refusing to edit ${file}: hunch.${event} must be an array when present; fix it, then re-run.`);
+        }
+    }
     const command = hookCommand(inv, "antigravity");
     const keep = (event) => Array.isArray(group[event])
         ? group[event].filter((entry) => {
@@ -470,7 +539,7 @@ export function scaffoldProviders(root, inv, store, options = {}) {
     const tasks = [
         ["Cursor", () => runProvider([() => writeCursorMcp(root, inv), () => writeCursorRule(root, store), ...(hooks ? [() => writeCursorHooks(root, inv)] : [])])],
         ["VS Code (Copilot)", () => runProvider([() => writeVscodeMcp(root, inv), () => writeCopilotInstructions(root, store), ...(hooks ? [() => writeVscodeHooks(root, inv)] : [])])],
-        ["Codex CLI", () => runProvider([() => writeCodexConfig(root, inv)])],
+        ["Codex CLI", () => runProvider([() => writeCodexConfig(root, inv), ...(hooks ? [() => writeCodexHooks(root, inv)] : [])])],
         ["Windsurf", () => {
                 return runProvider([
                     () => writeWindsurfMcp(root, inv),

package/dist/integrations/registry.d.ts

@@ -0,0 +1,15 @@
+export type PublishedStatus = "published" | "unpublished" | "unknown";
+export interface NpmResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export type NpmRunner = (args: string[]) => NpmResult;
+export declare function defaultNpmRunner(timeoutMs: number): NpmRunner;
+/** Whether npm can serve `@davesheffer/hunch@<version>`. "unknown" covers offline,
+ * timeouts, and unexpected output; callers must never read it as unpublished. */
+export declare function publishedStatus(version: string, opts?: {
+    timeoutMs?: number;
+    run?: NpmRunner;
+}): PublishedStatus;

package/dist/integrations/registry.js

@@ -0,0 +1,41 @@
+/** Bounded npm registry lookups that never throw. A pin npm cannot serve makes
+ * every `npx --package=…` launcher (hooks and MCP) fail before Hunch runs, and
+ * the hosts report nothing — so the CLI must be able to name that state. */
+import { spawnSync } from "node:child_process";
+const exactVersion = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function defaultNpmRunner(timeoutMs) {
+    return (args) => {
+        const windows = process.platform === "win32";
+        const r = spawnSync(windows ? `npm ${args.join(" ")}` : "npm", windows ? [] : args, {
+            shell: windows, windowsHide: true, encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error };
+    };
+}
+/** Whether npm can serve `@davesheffer/hunch@<version>`. "unknown" covers offline,
+ * timeouts, and unexpected output; callers must never read it as unpublished. */
+export function publishedStatus(version, opts = {}) {
+    if (!exactVersion.test(version))
+        return "unknown";
+    const run = opts.run ?? defaultNpmRunner(opts.timeoutMs ?? 8000);
+    let r;
+    try {
+        r = run(["view", `@davesheffer/hunch@${version}`, "version", "--json"]);
+    }
+    catch {
+        return "unknown";
+    }
+    if (r.error)
+        return "unknown";
+    if (r.status === 0) {
+        try {
+            const v = JSON.parse(r.stdout.trim() || "null");
+            return v === version || (Array.isArray(v) && v.includes(version)) ? "published" : "unknown";
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    return /\b(?:ETARGET|E404|notarget)\b/.test(r.stderr) ? "unpublished" : "unknown";
+}
+//# sourceMappingURL=registry.js.map

package/dist/integrations/scaffold.js

@@ -27,7 +27,11 @@ export function writeMcpJson(root, inv) {
             }
         }
     }
-    json.mcpServers = json.mcpServers ?? {};
+    const servers = json.mcpServers;
+    if (servers !== undefined && (!servers || typeof servers !== "object" || Array.isArray(servers))) {
+        throw new Error(`refusing to edit ${file}: mcpServers must be a JSON object when present; fix it, then re-run.`);
+    }
+    json.mcpServers = servers ?? {};
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     // Atomic: .mcp.json holds the user's other servers — a torn write would leave
     // it unparseable, which this writer then refuses to touch (issue #43).
@@ -114,7 +118,7 @@ function isHunchHook(entry) {
         if (typeof h.command !== "string")
             return false;
         const command = h.command;
-        const nativeOrSource = /[\\/]index\.(js|ts)"?\s+hook\s*$/.test(command);
+        const nativeOrSource = /(?:dist|src)[\\/]+cli[\\/]+index\.(js|ts)"?\s+hook\s*$/.test(command);
         const publishedNpx = /^\s*"?npx(?:\.cmd)?"?\s+/i.test(command)
             && /--package=(?:hunch-exact@npm:)?@davesheffer\/hunch(?:@[^"\s]+)?/.test(command)
             && /\s"?hunch"?\s+"?hook"?\s*$/.test(command);
@@ -151,7 +155,17 @@ export function installClaudeHooks(root, hookCmd) {
             }
         }
     }
-    json.hooks = json.hooks ?? {};
+    const hooks = json.hooks;
+    if (hooks !== undefined && (!hooks || typeof hooks !== "object" || Array.isArray(hooks))) {
+        throw new Error(`refusing to edit ${file}: hooks must be a JSON object when present; fix it, then re-run.`);
+    }
+    json.hooks = hooks ?? {};
+    for (const event of ["PreToolUse", "UserPromptSubmit", "SessionStart", "SubagentStart", "PreCompact", "PostToolUse", "PostToolUseFailure", "Stop"]) {
+        const existing = json.hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new Error(`refusing to edit ${file}: hooks.${event} must be an array when present; fix it, then re-run.`);
+        }
+    }
     const keep = (arr) => (Array.isArray(arr) ? arr.filter((e) => !isHunchHook(e)) : []);
     json.hooks.PreToolUse = [
         ...keep(json.hooks.PreToolUse),

package/dist/mcp/server.d.ts

@@ -25,6 +25,10 @@ export interface RootControlOptions {
     /** Serve exactly `initialRoot`; never re-home to client roots or `cwd` hints. */
     pinned?: boolean;
 }
+/** Delivered to every MCP client at initialize — the one grounding channel that
+ * needs no host hook or instruction file. Host-neutral by design (con_e04226bd05);
+ * per-host prose (CLAUDE.md, AGENTS.md) and hooks add to it, never replace it. */
+export declare const MCP_INSTRUCTIONS: string;
 export declare function buildServerWithRootControl(initialRoot: string, options?: RootControlOptions): RootControlledServer;
 /** Back-compatible server construction for tests and callers that do not need
  *  to drive roots directly. The server still owns and closes its active store. */