@hasna/hooks 0.9.4 → 0.9.6

package/dist/sdk/registry-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `@hasna/hooks` — resolver-backed factory for the generated registry client.
+ *
+ * The generated {@link HooksRegistryApiClient} takes an explicit
+ * `baseUrl`/`apiKey` and has no environment surface of its own. This module is
+ * the ONE adapter from that client onto the @hasna/contracts credential chain
+ * (owner ruling 2026-09-04, hasna/apps#1720) so callers never write a private
+ * copy of the chain — the same rule `HooksClient` (src/sdk/index.ts) follows.
+ *
+ * FOUR PROPERTIES THIS ADAPTER EXISTS TO KEEP, matching `HooksClient`:
+ *
+ *   1. FAIL CLOSED. `resolveHooksSdkAuthority` refuses the local opt-in by
+ *      name and throws `REMOTE_API_*` (naming every tier it consulted) when
+ *      nothing resolves. A client is never built that would answer from a
+ *      local file, and an unauthenticated client is never built at all.
+ *
+ *   2. FRESH PER REQUEST. The credential is re-resolved on every dispatch
+ *      through `resolveHooksRequestAuthority`, so a rotation or a vault
+ *      pointer resolves again for each request instead of being frozen at
+ *      construction — and a changed authority binding refuses the request
+ *      rather than sending the previous credential to the new URL.
+ *
+ *   3. NEVER FOLLOW A REDIRECT. The generated client does not set `redirect`,
+ *      which would make fetch follow a 3xx and carry `x-api-key` to another
+ *      origin. The adapter forces `redirect: "manual"` for every dispatch,
+ *      after the caller's init, so it cannot be overridden.
+ *
+ *   4. STAY ON THE RESOLVED ORIGIN. The adapter refuses any dispatch whose
+ *      URL is not exactly the resolved registry origin, so a malformed path
+ *      can never turn the credential into a cross-origin request.
+ */
+import { type HooksRemoteAuthority } from "../lib/transport.js";
+import { type HooksClientOptions } from "./authority.js";
+import { HooksRegistryApiClient } from "./generated.js";
+/** The transport's fetch shape (Bun's global fetch carries extra static props). */
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** The fields a resolver-backed client exposes for diagnostics. Never a value. */
+export interface HooksRegistryApiClientAuthority {
+    /** Registry origin WITHOUT `/v1`; the registry routes hang off `<origin>/api/v1`. */
+    readonly authorityOrigin: string;
+    /** WHERE the credential came from (env NAME, Keychain reference, file PATH). Never a value. */
+    readonly apiKeySource: string | null;
+    /** WHERE the authority came from. Never a value. */
+    readonly apiUrlSource: string | null;
+}
+/** A generated registry client bound to a resolved authority. */
+export type ResolvedHooksRegistryApiClient = HooksRegistryApiClient & HooksRegistryApiClientAuthority;
+/**
+ * Bind an already-resolved authority to a fetch implementation: every dispatch
+ * re-resolves the credential, pins the origin and refuses to follow redirects.
+ *
+ * Exported so the two guards below are directly testable — they are
+ * defense-in-depth for a dispatch path the generated client does not otherwise
+ * let you reach with a foreign URL.
+ */
+export declare function bindAuthorityFetch(authority: HooksRemoteAuthority, baseFetch?: FetchLike): FetchLike;
+/**
+ * Bind the generated client to an already-resolved authority: every dispatch
+ * re-resolves the credential, pins the origin and refuses to follow redirects.
+ *
+ * Exported for callers that hold an authority (e.g. `HooksClient`'s
+ * `#authority`) rather than an env object.
+ */
+export declare function hooksRegistryApiClientFor(authority: HooksRemoteAuthority, options?: {
+    fetch?: typeof fetch;
+}): ResolvedHooksRegistryApiClient;
+/**
+ * Resolve the hosted registry authority (fail closed) and return a generated
+ * client bound to it.
+ *
+ * Throws — never returns a local fallback — when nothing resolves, and refuses
+ * the local opt-in by name: there is no SDK surface for the on-box store.
+ */
+export declare function createHooksRegistryApiClient(options?: HooksClientOptions): ResolvedHooksRegistryApiClient;
+export {};

package/hooks/native-safety-entry.ts

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
+import { evaluate as evaluateTrash, findTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
+import { evaluate as evaluateRepos } from "./hook-workspace-repos-guard/src/hook";
+import type { CodewithHookInput } from "./codewith-native-common";
+
+// Bundled with import.meta.main=false, so the original standalone run wrappers
+// cannot swallow exceptions or emit a second response. Only this entry runs.
+const name = process.argv[1];
+if (name !== "trash-guard" && name !== "workspace-repos-guard") throw new Error("Invalid safety capability");
+const input = JSON.parse(await Bun.stdin.text()) as CodewithHookInput;
+if (!input || Array.isArray(input) || input.hook_event_name !== "PreToolUse" || typeof input.tool_name !== "string"
+  || !input.tool_input || typeof input.tool_input !== "object" || Array.isArray(input.tool_input)
+  || typeof input.cwd !== "string" || !isAbsolute(input.cwd)) throw new Error("Invalid safety input");
+if (input.tool_name === "Bash" && typeof input.tool_input.command !== "string") throw new Error("Invalid shell input");
+if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name)) {
+  if (input.tool_input.command !== undefined && input.tool_input.patch !== undefined && input.tool_input.command !== input.tool_input.patch) throw new Error("Conflicting patch aliases");
+  const patch = input.tool_input.command ?? input.tool_input.patch;
+  if (typeof patch !== "string") throw new Error("Invalid patch input");
+  input.tool_input = { ...input.tool_input, command: patch, patch };
+}
+const repos = evaluateRepos(input).output;
+const handoff = input.tool_name === "Bash" && scanCommand(input.tool_input.command as string, { home: homedir(), cwd: input.cwd }).handoffHits.length > 0;
+const verdict = repos.decision === "block"
+  ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: repos.reason } }
+  : handoff ? { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "[workspace-repos-guard] Deletion under a protected repository checkout is refused." } }
+  : name === "trash-guard" ? evaluateTrash(input, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary }) : { continue: true };
+process.stdout.write(JSON.stringify({ verdict: "continue" in verdict ? null : verdict }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -25,8 +25,10 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:types",
+    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:native-safety && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
+    "generate:sdk": "bun run scripts/generate-sdk.ts",
+    "verify:generated": "bun run scripts/verify-generated-artifacts.ts",
     "dev": "bun run ./src/cli/index.tsx",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
@@ -34,7 +36,8 @@
     "prepublishOnly": "bun run validate:package",
     "postinstall": "node scripts/ensure-profiles-dir.mjs",
     "scan:artifact": "bun scripts/artifact-scan.ts",
-    "prepack": "bun run build && bun run scan:artifact"
+    "prepack": "bun run build && bun run scan:artifact",
+    "build:native-safety": "bun build ./hooks/native-safety-entry.ts --outdir ./bin --target bun --define import.meta.main=false"
   },
   "keywords": [
     "claude-code",
@@ -54,11 +57,11 @@
     "@types/react": "^18.2.0",
     "typescript": "^5",
     "bun-types": "1.3.14",
-    "@hasna/contracts": "1.0.2"
+    "@hasna/contracts": "~1.2.1"
   },
   "dependencies": {
     "@hasna/events": "^0.1.16",
-    "@hasna/secrets": "0.3.10",
+    "@hasna/secrets": "0.4.2",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",

package/scripts/generate-sdk.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+/**
+ * Regenerate the typed @hasna/hooks registry client from the serve OpenAPI
+ * document.
+ *
+ *   bun run generate:sdk
+ *
+ * Output: src/sdk/generated.ts — a dependency-free fetch client plus the
+ * interfaces derived from the document, produced by `@hasna/contracts`'
+ * `generateSdkFromOpenApi` (the fleet generator: apps/logs, apps/telephony
+ * and apps/todos use the same helper). Do not hand-edit the output; change
+ * `src/openapi.ts` and rerun this.
+ *
+ * THE SPEC IS THE SERVED ONE. `buildOpenApiDocument(version)` is the exact
+ * object `GET /openapi.json` returns (src/serve.ts), so the committed client
+ * and the served contract cannot describe different routes. That is what
+ * makes the `serviceSurfaces[3].generatedFrom` declaration in
+ * hasna.contract.json (`/openapi.json`) true rather than aspirational:
+ * `scripts/verify-generated-artifacts.ts` re-runs this script and
+ * byte-compares the result so the claim stays true (AGE11-00571).
+ *
+ * `@hasna/contracts` is a BUILD-TIME devDependency import; it is never a
+ * runtime dependency of the published bundle.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateSdkFromOpenApi } from "@hasna/contracts/sdk";
+import { buildOpenApiDocument } from "../src/openapi.js";
+
+const appRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The same value src/serve.ts's packageVersion() puts in the served document. */
+function packageVersion(): string {
+  const pkgPath = join(appRoot, "package.json");
+  if (!existsSync(pkgPath)) throw new Error(`generate-sdk: package.json not found at ${pkgPath}`);
+  const parsed = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string };
+  if (!parsed.version) throw new Error("generate-sdk: package.json carries no version");
+  return parsed.version;
+}
+
+const version = packageVersion();
+const generated = generateSdkFromOpenApi(buildOpenApiDocument(version), {
+  className: "HooksRegistryApiClient",
+  apiKeyHeader: "x-api-key",
+});
+
+const outFile = join(appRoot, "src", "sdk", "generated.ts");
+const header = [
+  `// @generated from the @hasna/hooks serve OpenAPI document (${version}) by scripts/generate-sdk.ts.`,
+  "// DO NOT EDIT. Regenerate: bun run generate:sdk",
+  "",
+  "",
+].join("\n");
+writeFileSync(outFile, header + generated.code, "utf8");
+
+console.log(
+  `generate-sdk: wrote src/sdk/generated.ts — ${generated.operations.length} operations from /openapi.json`,
+);
+for (const warning of generated.warnings) console.warn(`generate-sdk: warning: ${warning}`);

package/scripts/validate-package.ts

@@ -1,12 +1,14 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, realpath, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 type PackageJson = {
   name: string;
   types?: string;
   exports?: Record<string, unknown>;
+  version?: string;
+  dependencies?: Record<string, string>;
 };
 
 type PackEntry = {
@@ -142,7 +144,74 @@ async function main(): Promise<void> {
   await validateConsumerImports(pkg);
   await validateExtractedSmoke(pkg);
 
-  console.log("Package validation passed: packed declarations are present, Bundler/NodeNext TypeScript consumer imports resolve, and the extracted tarball smoke-tests CLI help, serve /health, MCP startup, SDK import and one bundled-hook run (P3-17).");
+  console.log("Package validation passed: packed declarations are present, Bundler/NodeNext TypeScript consumer imports resolve, and the extracted tarball smoke-tests CLI help, serve /health, MCP startup, SDK import, credential-file vault references and one bundled-hook run (P3-17).");
+}
+
+async function validatePackedCredentialReferences(pkg: PackageJson, packageDir: string, smokeDir: string): Promise<void> {
+  // Link the consumer's declared installed dependency, never the workspace's
+  // unrelated Secrets source. Bundling changes where the shared resolver finds it.
+  let parent = root;
+  let secretsDir: string | undefined;
+  for (;;) {
+    const candidate = join(parent, "node_modules", "@hasna", "secrets");
+    if (existsSync(candidate)) { secretsDir = await realpath(candidate); break; }
+    if (dirname(parent) === parent) throw new Error("Hooks Secrets dependency is not installed");
+    parent = dirname(parent);
+  }
+  const secretsPkg = await readPackageJson(join(secretsDir, "package.json"));
+  if (secretsPkg.name !== "@hasna/secrets" || secretsPkg.version !== pkg.dependencies?.["@hasna/secrets"]) {
+    throw new Error("Packed reference validation requires the exact declared Secrets dependency");
+  }
+  const peerDir = join(packageDir, "node_modules", "@hasna");
+  await mkdir(peerDir, { recursive: true });
+  await symlink(secretsDir, join(peerDir, "secrets"), "dir");
+  const fixture = join(smokeDir, "credential-reference-smoke.ts");
+  await writeFile(fixture, `
+import { strict as assert } from "node:assert";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHooksClient } from "@hasna/hooks/sdk";
+const home = join(import.meta.dir, "reference-home");
+for (const [name, body] of [
+  ["hooks", "HASNA_HOOKS_API_URL=https://hooks.example.test\\nHASNA_HOOKS_API_KEY_REF=fixture/hooks/key\\n"],
+  ["secrets", "HASNA_SECRETS_API_URL=https://secrets.example.test\\nHASNA_SECRETS_API_KEY=fixture-bootstrap-key\\n"],
+]) {
+  const folder = join(home, ".hasna", name, "config");
+  mkdirSync(folder, { recursive: true });
+  writeFileSync(join(folder, "credentials"), body, { mode: 0o600 });
+}
+
+
+let value = "fixture-first-key", vaultStatus = 200, reads = 0;
+const keys = [];
+globalThis.fetch = async (input, init) => {
+  const url = new URL(String(input)), headers = new Headers(init?.headers);
+  if (url.origin === "https://secrets.example.test") {
+    assert.equal(url.pathname, "/v1/secrets/get");
+    assert.equal(url.searchParams.get("key"), "fixture/hooks/key");
+    assert.equal(headers.get("x-api-key"), "fixture-bootstrap-key");
+    reads++;
+    return Response.json(vaultStatus === 200 ? { value } : { error: "fixture denial" }, { status: vaultStatus });
+  }
+  assert.equal(url.origin, "https://hooks.example.test");
+  assert.equal(init.redirect, "manual");
+  keys.push(headers.get("x-api-key"));
+  return Response.json({ hooks: [] });
+};
+const client = createHooksClient({ env: { HOME: home }, credentials: { keychain: { enabled: false } } });
+await client.catalog();
+value = "fixture-rotated-key";
+await client.catalog();
+vaultStatus = 401;
+await assert.rejects(client.catalog(), /vault.*unavailable/);
+assert.deepEqual(keys, ["fixture-first-key", "fixture-rotated-key"]);
+assert.equal(reads, 3);
+console.log("packed credential-file reference, rotation and terminal failure passed");
+`);
+  const result = spawnSync("bun", ["run", fixture], {
+    cwd: smokeDir, env: { PATH: process.env.PATH }, encoding: "utf8", timeout: 20000,
+  });
+  if (result.status !== 0) throw new Error(`Packed credential reference failed: ${result.stderr}`);
 }
 
 /**
@@ -154,6 +223,37 @@ async function main(): Promise<void> {
  * Lanes: CLI help, serve /health, MCP stdio startup (initialize handshake),
  * a runtime SDK import, and one bundled-hook run with an isolated data dir.
  */
+async function validatePackedNativeSafety(packageDir: string, smokeDir: string): Promise<void> {
+  const home = join(smokeDir, "native-safety-home");
+  await mkdir(home, { mode: 0o700 });
+  const settings = join(home, ".codex", "hooks.json");
+  const env: NodeJS.ProcessEnv = { ...process.env, HOME: home, HASNA_STATION: "no-such-station", HASNA_HOOKS_CODEX_SETTINGS_PATH: settings };
+  for (const key of Object.keys(env)) if (/^(HASNA_HOOKS_|HOOKS_)/.test(key) && key !== "HASNA_HOOKS_CODEX_SETTINGS_PATH") delete env[key];
+  const cli = join(packageDir, "bin/index.js");
+  const installed = spawnSync(process.execPath, [cli, "safety", "install", "trash-guard", "--target", "codex"], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
+  if (installed.status !== 0 || !JSON.parse(installed.stdout).success) throw new Error("Packed native safety registration failed");
+  if (existsSync(join(home, ".hasna", "hooks"))) throw new Error("Stateless safety registration created app state");
+  const native = JSON.parse(await readFile(settings, "utf8"));
+  const command = native.hooks.PreToolUse[0].hooks[0].command;
+  const input = (text: string) => JSON.stringify({ hook_event_name: "PreToolUse", tool_name: "Bash", cwd: home, tool_input: { command: text } });
+  const invoke = (text: string) => spawnSync("/bin/sh", ["-c", command], { cwd: home, env, input: input(text), encoding: "utf8", timeout: 9_000 });
+  const benign = invoke("pwd");
+  if (benign.status !== 0 || benign.stdout !== "" || benign.stderr !== "") throw new Error("Packed native benign verdict failed");
+  const refused = invoke(`rm -- ${join(home, "owned-fixture")}`);
+  if (refused.status !== 0 || JSON.parse(refused.stdout).hookSpecificOutput.permissionDecision !== "deny") throw new Error("Packed native missing-Trash refusal failed");
+  const probe = join(smokeDir, "native-registration.ts");
+  await writeFile(probe, `import { getRegisteredHooksForTarget } from "@hasna/hooks"; console.log(JSON.stringify(getRegisteredHooksForTarget("global", "codex")));`);
+  const listed = spawnSync(process.execPath, [probe], { cwd: smokeDir, env, encoding: "utf8", timeout: 15_000 });
+  if (listed.status !== 0 || JSON.stringify(JSON.parse(listed.stdout)) !== '["trash-guard"]') throw new Error("Packed SDK cannot recognize the compiled CLI safety registration");
+  const worker = join(packageDir, "bin/native-safety-entry.js");
+  const bytes = await readFile(worker);
+  try {
+    await writeFile(worker, Buffer.concat([bytes, Buffer.from("\n// changed fixture\n")]));
+    const changed = invoke("rm -- owned-fixture");
+    if (changed.status !== 2 || changed.stdout !== "" || !changed.stderr.includes("safety guard refused")) throw new Error("Packed native modified-bundle refusal failed");
+  } finally { await writeFile(worker, bytes); }
+}
+
 async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
   const tempRoot = join(root, "temp");
   await mkdir(tempRoot, { recursive: true });
@@ -284,6 +384,8 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
     const sdkOut = JSON.parse(sdk.stdout.trim()) as { count: number; backend: string; sdk: string; hasClient: boolean };
     if (typeof sdkOut.count !== "number" || sdkOut.count <= 0) throw new Error(`packed SDK import returned count ${sdkOut.count}`);
     if (sdkOut.sdk !== "fail-closed" || !sdkOut.hasClient) throw new Error(`packed ./sdk export did not fail closed with nothing configured: ${JSON.stringify(sdkOut)}`);
+    await validatePackedCredentialReferences(pkg, packageDir, smokeDir);
+    await validatePackedNativeSafety(packageDir, smokeDir);
 
     // 5. One bundled-hook run from the packed artifact (isolated data dir;
     // first run self-trusts, then executes).

package/scripts/verify-generated-artifacts.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env bun
+/**
+ * Verify that the committed generated registry client is byte-identical to what
+ * the current source produces — and that it is a real client, not an empty file
+ * that trivially matches itself.
+ *
+ * `src/sdk/generated.ts` is committed because `package.json`'s build bundles it
+ * into the published `./sdk` export, so a drifted file ships. The repo rule is
+ * explicit (".github/workflows/ci.yml", `verify-generated` job): a member that
+ * commits generated bundles adds its own step to that job, sharing the job's
+ * bun-version pin — "a committed bundle no job regenerates is drift by
+ * construction". This is that step for hooks.
+ *
+ * THE RULES THIS HOLDS TO (mirrors apps/telephony and apps/knowledge):
+ *
+ *   1. ONE ENTRY POINT. The regeneration happens inside this script via
+ *      `package.json`'s `generate:sdk`, so it cannot be run without the
+ *      regeneration and read as a sync check, and the two can never disagree.
+ *
+ *   2. THE REGENERATION MUST BE BYTE-STABLE, NOT ONLY MATCH THE INDEX. The
+ *      generator runs TWICE; the two outputs must be byte-identical before the
+ *      index comparison means anything. A nondeterministic generator would make
+ *      the byte gate pass on one run and fail on the next with no commit in
+ *      between — the vacuous-check class wearing a green gate.
+ *
+ *   3. THE CHECK PROVES THE ARTIFACT IS REAL BEFORE TRUSTING A CLEAN RESULT. A
+ *      generator that emitted nothing would be byte-stable and match its own
+ *      empty index forever. The artifact must carry the client class and one
+ *      method per operation in the SERVED document — the exact binding
+ *      `hasna.contract.json`'s `serviceSurfaces[3].generatedFrom` claims.
+ *
+ *   4. THE PRECONDITION IS CHECKED. `git diff` after a regeneration only means
+ *      something if the file matched the index BEFORE it; a file that was
+ *      already modified proves nothing afterwards.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { generateSdkFromOpenApi } from "@hasna/contracts/sdk";
+import { buildOpenApiDocument } from "../src/openapi.ts";
+
+const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The one committed-and-shipped file `generate:sdk` rewrites. */
+export const GENERATED_FILE = "src/sdk/generated.ts";
+
+/** The class the manifest's `./sdk` surface advertises as generated. */
+export const GENERATED_CLASS = "HooksRegistryApiClient";
+
+function fail(message: string): never {
+  console.error(`verify-generated-artifacts: ${message}`);
+  process.exit(1);
+}
+
+function git(args: string[]): { status: number; stdout: string; stderr: string } {
+  const run = spawnSync("git", args, { cwd: appRoot, encoding: "utf8" });
+  // A spawn that never started reports status null. Treat that as failure: this
+  // whole script is a control, and a control that cannot run must not pass.
+  return { status: run.status ?? 1, stdout: run.stdout ?? "", stderr: run.stderr ?? "" };
+}
+
+function sha256Of(relativePath: string): string {
+  return createHash("sha256").update(readFileSync(join(appRoot, relativePath))).digest("hex");
+}
+
+/* ------------------------------------------------------------------ *
+ * Rule 3: prove the committed artifact is a real generated client for *
+ * the served document — before any clean result is believed.          *
+ * ------------------------------------------------------------------ */
+
+/**
+ * The operations the SERVED document declares. Derived from
+ * `buildOpenApiDocument`, the same builder src/serve.ts answers
+ * `GET /openapi.json` with, so this is the binding the contract claims.
+ */
+export function servedOperations(): string[] {
+  const spec = buildOpenApiDocument("0.0.0") as {
+    paths?: Record<string, Record<string, unknown>>;
+  };
+  const methods = ["get", "put", "post", "delete", "patch", "options", "head"];
+  const found: string[] = [];
+  for (const [path, item] of Object.entries(spec.paths ?? {})) {
+    for (const method of methods) {
+      if (item[method]) found.push(`${method.toUpperCase()} ${path}`);
+    }
+  }
+  return found.sort();
+}
+
+/** Problems with the committed artifact, or [] when it looks generated. */
+export function artifactProblems(text: string): string[] {
+  const problems: string[] = [];
+  if (!text.includes("// @generated")) {
+    problems.push(`${GENERATED_FILE} carries no "@generated" header — it is not generator output`);
+  }
+  if (!text.includes(`export class ${GENERATED_CLASS}`)) {
+    problems.push(`${GENERATED_FILE} does not declare "export class ${GENERATED_CLASS}"`);
+  }
+  return problems;
+}
+
+/**
+ * The operations the committed artifact exposes, as `METHOD path` pairs. Read
+ * from the generated `this.request("METHOD", \`path\`)` call sites so this is
+ * about what was actually emitted, not about what the spec says. Emitted path
+ * templates interpolate path params (`\${encodeURIComponent(String(name))}`);
+ * they are normalized back to the OpenAPI `{name}` form so the comparison is
+ * against the served document's spelling.
+ */
+export function artifactOperations(text: string): string[] {
+  const found: string[] = [];
+  const re = /this\.request\(\s*"([A-Z]+)",\s*`([^`]+)`/g;
+  for (const match of text.matchAll(re)) {
+    found.push(`${match[1]} ${normalizePathTemplate(match[2]!)}`);
+  }
+  return found.sort();
+}
+
+/** `\${encodeURIComponent(String(name))}` -> `{name}`. */
+export function normalizePathTemplate(path: string): string {
+  return path.replace(
+    /\$\{encodeURIComponent\(String\(([A-Za-z_$][A-Za-z0-9_$]*)\)\)\}/g,
+    "{$1}",
+  );
+}
+
+/**
+ * A served-operation extractor that can no longer find call sites reports "all
+ * covered" forever. These fixtures prove the extraction still fires, and still
+ * normalizes, before a clean result is believed. The fixture is the exact
+ * emitted shape for the parameterized artifact route.
+ */
+export const EXTRACTION_FIXTURE =
+  'return this.request("GET", `/api/v1/hooks/${encodeURIComponent(String(name))}/${encodeURIComponent(String(version))}`, {';
+export const EXTRACTION_FIXTURE_EXPECTED = "GET /api/v1/hooks/{name}/{version}";
+// Must NOT match: a bare path with no request call site is not an operation.
+export const EXTRACTION_COUNTER_FIXTURE = 'const p = "/api/v1/hooks/{name}/{version}";';
+
+/** Problems with the extraction pattern itself; [] means it is worth believing. */
+export function patternSelfCheck(): string[] {
+  const problems: string[] = [];
+  const extracted = artifactOperations(EXTRACTION_FIXTURE);
+  if (extracted.length !== 1 || extracted[0] !== EXTRACTION_FIXTURE_EXPECTED) {
+    problems.push(
+      `the operation extractor no longer reads its own fixture (got ${JSON.stringify(extracted)} for ${EXTRACTION_FIXTURE_EXPECTED}) — the coverage check below cannot detect anything`,
+    );
+  }
+  if (artifactOperations(EXTRACTION_COUNTER_FIXTURE).length !== 0) {
+    problems.push("the operation extractor matches its counter-fixture — it is too loose to be meaningful");
+  }
+  return problems;
+}
+
+/**
+ * The served operations minus the ones the artifact emitted. Empty means the
+ * committed client covers the served document exactly.
+ */
+export function missingOperations(text: string): string[] {
+  const emitted = new Set(artifactOperations(text));
+  return servedOperations().filter((op) => !emitted.has(op));
+}
+
+function main(): void {
+  const committed = readFileSync(join(appRoot, GENERATED_FILE), "utf8");
+
+  // Rule 3 first: a clean regeneration of a broken artifact must not be read
+  // as a pass, and a dead extractor must not be read as full coverage.
+  const patternProblems = patternSelfCheck();
+  const problems = [...patternProblems, ...artifactProblems(committed)];
+  const missing = missingOperations(committed);
+  if (missing.length > 0) {
+    problems.push(
+      `${GENERATED_FILE} is missing ${missing.length} operation(s) the served /openapi.json declares: ${missing.join(", ")}`,
+    );
+  }
+  if (problems.length > 0) {
+    for (const problem of problems) console.error(`verify-generated-artifacts: ${problem}`);
+    process.exit(1);
+  }
+
+  // Rule 4: the precondition for the diff gate below.
+  const dirtyBefore = git(["status", "--porcelain", "--", GENERATED_FILE]);
+  if (dirtyBefore.status !== 0) fail(`git status failed: ${dirtyBefore.stderr.trim()}`);
+  if (dirtyBefore.stdout.trim() !== "") {
+    fail(
+      `${GENERATED_FILE} is already modified before the regeneration, so this check cannot tell drift from your edits:\n` +
+        `${dirtyBefore.stdout.trimEnd()}\nCommit or restore it, then re-run.`,
+    );
+  }
+
+  // Rule 1: regenerate through the package script, never a repeated command.
+  const generate = (pass: number): void => {
+    const run = spawnSync("bun", ["run", "generate:sdk"], { cwd: appRoot, stdio: "inherit" });
+    if ((run.status ?? 1) !== 0) {
+      fail(`\`bun run generate:sdk\` (pass ${pass}) exited ${run.status ?? "without a status"}`);
+    }
+  };
+
+  // Rule 2: two regenerations of the same source must be byte-identical.
+  generate(1);
+  const first = sha256Of(GENERATED_FILE);
+  generate(2);
+  const second = sha256Of(GENERATED_FILE);
+  if (first !== second) {
+    fail(
+      `regeneration is NOT byte-stable: two consecutive \`bun run generate:sdk\` runs of the same source produced different bytes for ${GENERATED_FILE}.\n` +
+        `This bun is ${process.versions?.bun ?? "unknown"}. A nondeterministic generator makes the byte gate vacuous — fix the generator (or the bun version) rather than committing either output.`,
+    );
+  }
+
+  // The gate: the regeneration must equal what is committed.
+  const drift = git(["diff", "--exit-code", "--", GENERATED_FILE]);
+  if (drift.status !== 0) {
+    console.error(
+      `verify-generated-artifacts: the committed registry client is not what the current source generates.\n` +
+        `Run \`bun run generate:sdk\` and commit the result. ${GENERATED_FILE} is bundled into the published\n` +
+        `\`./sdk\` export, so an uncommitted regeneration ships a client that disagrees with src/openapi.ts.`,
+    );
+    process.exit(drift.status ?? 1);
+  }
+
+  // Post-condition: the artifact survived the regeneration with its binding intact.
+  const finalText = readFileSync(join(appRoot, GENERATED_FILE), "utf8");
+  const finalProblems = [...artifactProblems(finalText), ...missingOperations(finalText).map((op) => `missing ${op}`)];
+  if (finalProblems.length > 0) {
+    fail(`regeneration rewrote ${GENERATED_FILE} but it is not usable: ${finalProblems.join("; ")}`);
+  }
+
+  console.log(
+    `verify-generated-artifacts: two consecutive regenerations of ${GENERATED_FILE} are byte-identical to each other and to the committed output; all ${servedOperations().length} operations in the served /openapi.json are covered.`,
+  );
+}
+
+// Run only when invoked directly, so the exports above are importable from tests.
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) main();