cortad 0.2.2 → 0.3.0-rc.10

package/lib/register.mjs

@@ -1,17 +1,23 @@
 import { execFile } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { cliSpec, npxArgs } from "./spec.mjs";
 
 // Making Cortad known to the coding agents on this machine: an MCP entry in each client that is
 // here, and the skill that teaches the loop. Nothing is written into the repository; everything
 // lands in the client's own home folders, the way the client's own `add` command would put it.
-// Idempotent: run twice, it adds nothing twice.
+// Idempotent: run twice, it adds nothing twice. An entry naming another spec (lib/spec.mjs) is
+// replaced, so a connect with a newer package moves every client to it.
 const exec = promisify(execFile);
-const SERVER = { command: "npx", args: ["-y", "cortad@latest", "mcp"] };
 const SKILL_SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "skill");
+// The skill's shell examples name the spec in place of this.
+const PLACEHOLDER = "{{cortad}}";
+
+export const serverFor = (spec) => ({ command: "npx", args: [...npxArgs(spec), "mcp"] });
+const same = (entry, server) => entry?.command === server.command && JSON.stringify(entry?.args) === JSON.stringify(server.args);
 
 export const onPath = (bin, env = process.env) =>
   (env.PATH ?? "").split(delimiter).some((dir) => dir && existsSync(join(dir, bin)));
@@ -21,68 +27,96 @@ export function detectClients({ home = homedir(), env = process.env } = {}) {
     claude: onPath("claude", env) || existsSync(join(home, ".claude")),
     codex: onPath("codex", env) || existsSync(join(home, ".codex")),
     cursor: existsSync(join(home, ".cursor")),
+    copilot: onPath("copilot", env) || existsSync(join(home, ".copilot")),
   };
 }
 
 // Returns the names of the clients that now know Cortad, for the one line the command prints.
-export async function registerAll({ home = homedir(), env = process.env, run = exec, skillSrc = SKILL_SRC } = {}) {
+export async function registerAll({ home = homedir(), env = process.env, run = exec, skillSrc = SKILL_SRC, spec = cliSpec({ env }) } = {}) {
   const found = detectClients({ home, env });
+  const server = serverFor(spec);
+  const skill = (dir) => installSkill(dir, { src: skillSrc, spec });
   const added = [];
   if (found.claude) {
-    await registerClaude({ home, env, run });
-    installSkill(join(home, ".claude", "skills", "cortad"), skillSrc);
+    await registerClaude({ home, env, run, server });
+    skill(join(home, ".claude", "skills", "cortad"));
     added.push("Claude Code");
   }
   if (found.codex) {
-    await registerCodex({ home, env, run });
-    installSkill(join(home, ".agents", "skills", "cortad"), skillSrc);
+    await registerCodex({ home, env, run, server });
     added.push("Codex");
   }
   if (found.cursor) {
-    registerCursor({ home });
+    registerJson(join(home, ".cursor", "mcp.json"), { type: "stdio", ...server });
     added.push("Cursor");
   }
+  if (found.copilot) {
+    // Copilot CLI keeps its servers in its own home, in its own shape: a "local" server with every tool.
+    registerJson(join(home, ".copilot", "mcp-config.json"), { type: "local", ...server, tools: ["*"] });
+    skill(join(home, ".copilot", "skills", "cortad"));
+    added.push("Copilot");
+  }
+  // The one skills folder Codex, Cursor and Copilot all read.
+  if (found.codex || found.cursor || found.copilot) skill(join(home, ".agents", "skills", "cortad"));
   return added;
 }
 
 // The client's own command when it is here, so its config is written the way it writes it; the file
-// itself only when the folder exists without the binary on this PATH.
-async function registerClaude({ home, env, run }) {
+// itself only when the folder exists without the binary on this PATH, or the command failed.
+async function registerClaude({ home, env, run, server }) {
+  const file = join(home, ".claude.json");
   if (onPath("claude", env)) {
-    try { await run("claude", ["mcp", "add", "--scope", "user", "cortad", "--", SERVER.command, ...SERVER.args], { env }); return; }
-    catch (err) { if (/already exists/i.test(String(err?.stderr ?? err?.message))) return; }
+    const add = () => run("claude", ["mcp", "add", "--scope", "user", "cortad", "--", server.command, ...server.args], { env });
+    try { await add(); return; } catch (err) {
+      if (/already exists/i.test(String(err?.stderr ?? err?.message))) {
+        if (same(readJson(file)?.mcpServers?.cortad, server)) return;
+        try { await run("claude", ["mcp", "remove", "--scope", "user", "cortad"], { env }); await add(); return; } catch { /* the file below */ }
+      }
+    }
   }
-  const file = join(home, ".claude.json");
   const config = readJson(file) ?? {};
-  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...SERVER } };
+  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...server } };
   writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
 }
 
-async function registerCodex({ home, env, run }) {
-  if (onPath("codex", env)) {
-    try { await run("codex", ["mcp", "add", "cortad", "--", SERVER.command, ...SERVER.args], { env }); return; }
-    catch (err) { if (/already exists/i.test(String(err?.stderr ?? err?.message))) return; }
-  }
+const CODEX_BLOCK = /^\[mcp_servers\.cortad\]\n(?:(?!\[).*(?:\n|$))*/m;
+
+async function registerCodex({ home, env, run, server }) {
   const file = join(home, ".codex", "config.toml");
   const text = existsSync(file) ? readFileSync(file, "utf8") : "";
-  if (/^\[mcp_servers\.cortad\]/m.test(text)) return;
+  const block = text.match(CODEX_BLOCK)?.[0] ?? "";
+  const args = block.match(/^args\s*=\s*(\[.*\])\s*$/m)?.[1];
+  const current = (() => { try { return args ? { command: block.match(/^command\s*=\s*"(.*)"\s*$/m)?.[1], args: JSON.parse(args) } : null; } catch { return null; } })();
+  if (same(current, server)) return;
+  if (onPath("codex", env)) {
+    try {
+      if (block) await run("codex", ["mcp", "remove", "cortad"], { env });
+      await run("codex", ["mcp", "add", "cortad", "--", server.command, ...server.args], { env });
+      return;
+    } catch { /* the file below */ }
+  }
+  const entry = `[mcp_servers.cortad]\ncommand = "${server.command}"\nargs = ${JSON.stringify(server.args)}\n`;
   mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, `${text}${text && !text.endsWith("\n") ? "\n" : ""}\n[mcp_servers.cortad]\ncommand = "${SERVER.command}"\nargs = ${JSON.stringify(SERVER.args)}\n`);
+  // The blank lines after the old block stay, so the rest of the file keeps its layout.
+  const replaced = () => text.replace(CODEX_BLOCK, (old) => `${entry}${(old.match(/\n+$/)?.[0] ?? "\n").slice(1)}`);
+  writeFileSync(file, block ? replaced() : `${text}${text && !text.endsWith("\n") ? "\n" : ""}\n${entry}`);
 }
 
-function registerCursor({ home }) {
-  const file = join(home, ".cursor", "mcp.json");
+function registerJson(file, entry) {
   const config = readJson(file) ?? {};
-  if (config.mcpServers?.cortad) return;
-  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...SERVER } };
+  if (same(config.mcpServers?.cortad, entry)) return;
+  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: entry };
+  mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
 }
 
-// SKILL.md and its references, copied whole so a newer package refreshes the words.
-export function installSkill(dir, src = SKILL_SRC) {
+// SKILL.md and its references, copied whole so a newer package refreshes the words, with the
+// shell examples naming the spec this machine runs.
+export function installSkill(dir, { src = SKILL_SRC, spec = cliSpec() } = {}) {
   mkdirSync(join(dir, "references"), { recursive: true });
-  copyFileSync(join(src, "SKILL.md"), join(dir, "SKILL.md"));
-  copyFileSync(join(src, "references", "results.md"), join(dir, "references", "results.md"));
+  for (const rel of ["SKILL.md", join("references", "results.md")]) {
+    writeFileSync(join(dir, rel), readFileSync(join(src, rel), "utf8").replaceAll(PLACEHOLDER, spec));
+  }
 }
 
 function readJson(file) {

package/lib/replay.mjs

@@ -11,7 +11,7 @@ const HOOK = join(HERE, "trace.cjs");
 const PYHOOK = join(HERE, "pyhook");
 export const CAPTURED = "captured";
 // Never replayed: they describe one connection, not the caller.
-const HOP = /^(?:host|content-length|connection|keep-alive|transfer-encoding|upgrade|expect|te|trailer|accept-encoding|x-cortad-as)$/i;
+const HOP = /^(?:host|content-length|connection|keep-alive|transfer-encoding|upgrade|expect|te|trailer|accept-encoding|x-cortad-as|x-cortad-turn)$/i;
 
 export function makeCapture({ work, keepSecret, onDoor }) {
   const file = join(work, "trace.jsonl");
@@ -21,6 +21,9 @@ export function makeCapture({ work, keepSecret, onDoor }) {
   // The ports a hooked process listens on. Loading is not listening: turbo's own Node launcher loads
   // the hook, and one app was told we would see its messages while its API on Bun carried none.
   const ports = new Set();
+  // The route table each listening process read off its own app, newest per port.
+  const tables = new Map();
+  let newestTable = null;
   // Bun reads BUN_OPTIONS and splits it on spaces, quotes included, and only the `--preload=` form
   // leaves `bun run <script>` working. A hook path with a space in it is copied to one without.
   const bunHook = /\s/.test(HOOK) ? (() => { const at = join(mkdtempSync(join(tmpdir(), "cortad-")), "trace.cjs"); copyFileSync(HOOK, at); return at; })() : HOOK;
@@ -29,6 +32,9 @@ export function makeCapture({ work, keepSecret, onDoor }) {
   // ponytail: Node, Bun and Python. Go, Ruby, Java and PHP apps are asked for their route on the screen.
   const env = (base) => ({
     CORTAD_TRACE_FILE: file,
+    // The run writes the customer's rule sentences here (the engine's /tmp/rules.json lands in this
+    // folder), and the hook reads which of them each model call's prompt carried.
+    CORTAD_RULES_FILE: join(work, "rules.json"),
     NODE_OPTIONS: `${base.NODE_OPTIONS ?? ""} --require ${JSON.stringify(HOOK)}`.trim(),
     BUN_OPTIONS: `${base.BUN_OPTIONS ?? ""} --preload=${bunHook}`.trim(),
     PYTHONPATH: [PYHOOK, base.PYTHONPATH].filter(Boolean).join(":"),
@@ -45,6 +51,7 @@ export function makeCapture({ work, keepSecret, onDoor }) {
       let row; try { row = JSON.parse(line); } catch { continue; }
       if (row.hello) { alive = true; continue; }
       if (Number.isInteger(row.listen)) { ports.add(row.listen); continue; }
+      if (row.routes) { const t = routeTable(row.routes); if (t) { tables.set(t.port, t); newestTable = t; } continue; }
       if (row.call) { meter.add(row.call); continue; }
       if (row.dep) { meter.dep(row.dep); continue; }
       let body; try { body = JSON.parse(row.body); } catch { continue; }
@@ -67,11 +74,41 @@ export function makeCapture({ work, keepSecret, onDoor }) {
     // What your app spent on its model providers since it started, as the hook saw each call. Null
     // when no hook is in your app (an app this command did not start): absent, never zero.
     usage: () => { poll(); return alive ? meter.report() : null; },
+    // The app's routes as its framework holds them: the table of the process on `port`, else the
+    // newest any hooked process wrote. Empty when no hook read one.
+    registry: (port) => { poll(); return tables.get(port) ?? newestTable ?? {}; },
   };
 }
 
+const FRAMEWORKS = new Set(["fastapi", "starlette", "flask", "django", "quart", "litestar", "aiohttp", "express", "fastify", "hono", "koa", "elysia", "nest", "unknown"]);
+const OPENAPI_MAX = 8 * 1024 * 1024;
+const text = (v, max) => (typeof v === "string" ? v.slice(0, max) : "");
+// The row comes from inside a process this command does not control: every field is checked.
+const routeTable = (r) => {
+  if (!r || typeof r !== "object" || !Array.isArray(r.routes)) return null;
+  const openapi = r.openapi && typeof r.openapi === "object" && !Array.isArray(r.openapi) && JSON.stringify(r.openapi).length <= OPENAPI_MAX ? r.openapi : null;
+  return {
+    framework: FRAMEWORKS.has(r.framework) ? r.framework : "unknown",
+    port: Number.isInteger(r.port) && r.port > 0 && r.port < 65536 ? r.port : null,
+    routes: r.routes
+      .filter((x) => x && /^[A-Za-z]{1,10}$/.test(x.method) && typeof x.path === "string" && x.path.startsWith("/"))
+      .slice(0, 400)
+      .map((x) => ({ method: x.method.toUpperCase(), path: x.path.slice(0, 1024), file: text(x.file, 512), handler: text(x.handler, 200) })),
+    openapi,
+  };
+};
+
 // Every model call the hook wrote down, kept here: totals per host and model, and the newest rows.
 const ROWS = 5000;
+// The turn a row was pinned to by the run's own tag, and the rule ids the call's prompt carried.
+const TURN = /^[A-Za-z0-9:_.-]{1,80}$/;
+const RULE_ID = /^[\w:-]{1,64}$/;
+const turnOf = (v) => (typeof v === "string" && TURN.test(v) ? { turn: v } : {});
+const rulesOf = (v) => (Array.isArray(v) ? { rules: v.filter((id) => typeof id === "string" && RULE_ID.test(id)).slice(0, 300) } : {});
+// What the app's tools answered behind a call, as the hook read them off the next prompt.
+const toolsOf = (v) => (Array.isArray(v) && v.length
+  ? { tools: v.filter((t) => t && typeof t.text === "string" && t.text.trim()).slice(0, 12).map((t) => ({ name: String(t.name ?? "").slice(0, 80), text: t.text.slice(0, 3000) })) }
+  : {});
 const meter = (() => {
   const rows = [];
   const deps = [];
@@ -82,14 +119,15 @@ const meter = (() => {
       rows.push({
         at: count(call.at), host: call.host.slice(0, 253), model: String(call.model ?? "").slice(0, 160), status: count(call.status),
         promptTokens: count(call.promptTokens), cachedTokens: count(call.cachedTokens), completionTokens: count(call.completionTokens),
-        usage: call.usage === true,
+        usage: call.usage === true, ...turnOf(call.turn), ...rulesOf(call.rules), ...toolsOf(call.tools),
       });
       if (rows.length > ROWS) rows.splice(0, rows.length - ROWS);
     },
     // A service their settings name: only its setting, host and status travel, never a byte of it.
     dep(d) {
-      if (!d || typeof d.env !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(d.env) || typeof d.host !== "string") return;
-      deps.push({ at: count(d.at), env: d.env, host: d.host.slice(0, 253), status: count(d.status), ...(typeof d.code === "string" ? { code: d.code.slice(0, 40) } : {}) });
+      if (!d || typeof d.host !== "string" || !d.host) return;
+      const env = typeof d.env === "string" && /^[A-Z_][A-Z0-9_]*$/.test(d.env) ? d.env : undefined;
+      deps.push({ at: count(d.at), ...(env ? { env } : {}), host: d.host.slice(0, 253), status: count(d.status), ...(typeof d.code === "string" ? { code: d.code.slice(0, 40) } : {}), ...turnOf(d.turn) });
       if (deps.length > ROWS) deps.splice(0, deps.length - ROWS);
     },
     report() {
@@ -107,7 +145,7 @@ const meter = (() => {
       }
       return {
         totals: [...totals.values()].sort((a, b) => b.calls - a.calls),
-        rows: rows.slice(-200).reverse().map(({ at, host, model, status }) => ({ at, host, model, status })),
+        rows: rows.slice(-400).reverse().map(({ at, host, model, status, turn, rules, tools }) => ({ at, host, model, status, ...(turn ? { turn } : {}), ...(rules ? { rules } : {}), ...(tools ? { tools } : {}) })),
         deps: deps.slice(-400).reverse(),
       };
     },

package/lib/spec.mjs

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+// Which cortad the coding agents on this machine start, and the skill and stick name: the
+// CORTAD_CLI_SPEC the connect ran with (cortad@next, or an absolute folder for an unpublished
+// build), else cortad@next while this package is a prerelease, else cortad@latest. The spec ends up
+// in a shell line in the repository (lib/stick.mjs), so anything else in the variable is ignored.
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const SAFE = /^(?:cortad(?:@[A-Za-z0-9._-]+)?|\/[A-Za-z0-9._/-]+)$/;
+
+export function cliSpec({ env = process.env, version = VERSION } = {}) {
+  if (env.CORTAD_CLI_SPEC && SAFE.test(env.CORTAD_CLI_SPEC)) return env.CORTAD_CLI_SPEC;
+  return version.includes("-") ? "cortad@next" : "cortad@latest";
+}
+
+// npx needs -y to fetch a package without asking; a local folder is not fetched.
+export const npxArgs = (spec) => (isAbsolute(spec) ? [spec] : ["-y", spec]);
+
+// How a line a person reads names the command: plain `cortad` when that is what npx resolves anyway.
+export const npxName = (spec) => (spec === "cortad@latest" ? "cortad" : spec);

package/lib/start.mjs

@@ -55,6 +55,7 @@ function pythonStart(dir, onPath) {
   const py = venv ? JSON.stringify(venv) : existsSync(join(dir, "uv.lock")) && onPath("uv") ? "uv run python" : existsSync(join(dir, "poetry.lock")) && onPath("poetry") ? "poetry run python" : "python3";
   if (existsSync(join(dir, "manage.py"))) return { cmd: `${py} manage.py runserver`, serves: true };
   const named = [...new Set([...ENTRIES, ...entriesIn(dir)])].map((entry) => [entry, read(join(dir, entry))]).filter(([, text]) => text);
+  const manifest = `${read(join(dir, "requirements.txt"))}\n${read(join(dir, "pyproject.toml"))}\n${read(join(dir, "Pipfile"))}`;
   // The file that serves before the file that merely runs: src/run_agent.py runs a conversation in
   // the terminal and src/run_service.py is the app, and they sit in one folder.
   for (const [entry, text] of [...named.filter(([, text]) => SERVES.test(text)), ...named]) {
@@ -65,10 +66,19 @@ function pythonStart(dir, onPath) {
     if (fast) return { cmd: `${py} -m uvicorn ${module}:${fast[1]} --host 127.0.0.1 --port 8000`, serves: true };
     const flask = /^(\w+)\s*=\s*Flask\(/m.exec(text);
     if (flask) return { cmd: `${py} -m flask --app ${module} run --port 5000`, serves: true };
+    // The app object built elsewhere and only bound or re-exported here: resumeforge's
+    // backend/app/main.py is `from .application import (app, ...)`, and the server the manifest
+    // names says what serves it.
+    const bound = BOUND_APP.exec(text)?.[1] ?? IMPORTED_APP.exec(text)?.slice(1).find(Boolean);
+    if (bound && /\b(?:fastapi|starlette|litestar|quart)\b/i.test(manifest)) return { cmd: `${py} -m uvicorn ${module}:${bound} --host 127.0.0.1 --port 8000`, serves: true };
+    if (bound && /\bflask\b/i.test(manifest)) return { cmd: `${py} -m flask --app ${module}:${bound} run --port 5000`, serves: true };
   }
   return null;
 }
 
+// `app = create_app()` at the top of the file, or `from .application import app`.
+const BOUND_APP = /^(app|application)\s*=\s*[\w.]+\(/m;
+const IMPORTED_APP = /^from\s+[\w.]+\s+import\s+(?:\(\s*[^)]*?\b(app|application)\b[^)]*\)|[^\n(]*\b(app|application)\b)/m;
 const KNOWN = ["package.json", "pyproject.toml", "requirements.txt", "manage.py", "Pipfile", "uv.lock"];
 
 const startOf = (dir, onPath) => nodeStart(dir, onPath) ?? pythonStart(dir, onPath);

package/lib/stick.mjs

@@ -0,0 +1,99 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { cliSpec, npxName } from "./spec.mjs";
+
+// `npx cortad stick`: one line in each coding agent's own instructions file in this repository, and
+// a hook in the two clients that run one after an edit. `unstick` takes out exactly what stick put
+// in. Both are idempotent, print what they changed, and never touch git.
+//
+// The hook command carries --hook: Claude Code and Codex both drop plain stdout from a PostToolUse
+// hook, and read only hookSpecificOutput.additionalContext. The command follows lib/spec.mjs, and
+// unstick knows the line and the hook under any spec.
+export const lineFor = (name) => `After changing prompts, tools, models or retrieval, check with Cortad before committing: npx ${name} status`;
+export const hookFor = (name) => `npx ${name} status --changed --hook`;
+const IS_LINE = /^After changing prompts, tools, models or retrieval, check with Cortad before committing: npx \S+ status$/;
+const IS_HOOK = /^npx \S+ status --changed --hook$/;
+const hasLine = (text) => text.split("\n").some((l) => IS_LINE.test(l.trim()));
+const ours = (entry) => entry?.hooks?.some((h) => IS_HOOK.test(h.command ?? ""));
+const LINE_FILES = ["AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"];
+const HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
+const RULE_FILE = ".cursor/rules/cortad.mdc";
+
+export const hookOutput = (text) => JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text } });
+
+export function stick(root, { spec = cliSpec() } = {}) {
+  const line = lineFor(npxName(spec));
+  const hook = hookFor(npxName(spec));
+  const rule = `---\ndescription: Checking AI behavior with Cortad\nalwaysApply: true\n---\n${line}\n`;
+  const said = LINE_FILES.map((rel, i) => write(root, rel, (text) => {
+    if (hasLine(text)) return null;
+    return `${text}${text && !text.endsWith("\n") ? "\n" : ""}${text ? "\n" : ""}${line}\n`;
+  }, i === 0 ? `added "${line}"` : "added the same line"));
+  said.push(write(root, RULE_FILE, (text) => (hasLine(text) ? null : rule), "written, with the same line, applied always"));
+  said.push(...HOOK_FILES.map((rel, i) => write(root, rel, (text) => {
+    const config = parse(text);
+    if (config === undefined) return undefined;
+    const list = config.hooks?.PostToolUse ?? [];
+    if (list.some(ours)) return null;
+    config.hooks = { ...config.hooks, PostToolUse: [...list, { matcher: "Edit|Write", hooks: [{ type: "command", command: hook }] }] };
+    return `${JSON.stringify(config, null, 2)}\n`;
+  }, i === 0 ? `added a PostToolUse hook on Edit|Write that runs ${hook}` : "added the same hook")));
+  return said;
+}
+
+export function unstick(root) {
+  const said = LINE_FILES.map((rel) => write(root, rel, (text) => {
+    if (!hasLine(text)) return null;
+    return text.split("\n").filter((l) => !IS_LINE.test(l.trim())).join("\n").replace(/\n+$/, "\n");
+  }, "removed the line"));
+  said.push(write(root, RULE_FILE, (text) => (text ? "" : null), "removed"));
+  said.push(...HOOK_FILES.map((rel) => write(root, rel, (text) => {
+    const config = parse(text);
+    if (config === undefined) return undefined;
+    const list = config.hooks?.PostToolUse;
+    if (!list?.some(ours)) return null;
+    const kept = list.map((e) => ({ ...e, hooks: (e.hooks ?? []).filter((h) => !IS_HOOK.test(h.command ?? "")) })).filter((e) => e.hooks.length);
+    if (kept.length) config.hooks.PostToolUse = kept;
+    else delete config.hooks.PostToolUse;
+    if (!Object.keys(config.hooks).length) delete config.hooks;
+    return Object.keys(config).length ? `${JSON.stringify(config, null, 2)}\n` : "";
+  }, "removed the hook")));
+  return said;
+}
+
+// One file: `change` gets its text ("" when absent) and returns the new text, null for nothing to
+// do, or undefined when it cannot be read. An empty result removes the file, and the folders it
+// leaves empty. A path that leaves the repository, through a symbolic link or otherwise, is left alone.
+function write(root, rel, change, done) {
+  const file = resolve(root, rel);
+  if (!inside(root, file)) return `${rel}: left alone, it points outside this repository`;
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const next = change(text);
+  if (next === undefined) return `${rel}: left alone, it is not valid JSON`;
+  if (next === null) return `${rel}: nothing to change`;
+  if (next.trim() === "") {
+    rmSync(file);
+    for (let dir = dirname(file); dir.startsWith(`${resolve(root)}${sep}`) && !readdirSync(dir).length; dir = dirname(dir)) rmdirSync(dir);
+    return `${rel}: removed, it held only what stick wrote`;
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, next);
+  return `${rel}: ${done}`;
+}
+
+function inside(root, file) {
+  const base = realpathSync(root);
+  let dir = dirname(file);
+  while (!existsSync(dir)) dir = dirname(dir);
+  const real = realpathSync(dir);
+  if (real !== base && !real.startsWith(base + sep)) return false;
+  try { return !lstatSync(file).isSymbolicLink(); } catch { return true; }
+}
+
+function parse(text) {
+  if (!text.trim()) return {};
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+  } catch { return undefined; }
+}