@hasna/hooks 0.6.8 → 0.7.2

package/bin/serve.js

@@ -368,6 +368,16 @@ var HOOKS = [
     matcher: "",
     tags: ["errors", "failures", "logging", "debugging"]
   },
+  {
+    name: "spiral-detector",
+    displayName: "Spiral Detector",
+    description: "Interrupts sessions after five consecutive identical command failures",
+    version: "0.1.0",
+    category: "Observability",
+    event: "PostToolUse",
+    matcher: "",
+    tags: ["spiral", "failures", "retries", "safety", "interrupt"]
+  },
   {
     name: "stylescheck",
     displayName: "Styles Check",
@@ -524,8 +534,8 @@ function getHook(name) {
 }
 
 // src/lib/manifest.ts
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "fs";
-import { basename, dirname, isAbsolute, join as join2, normalize, resolve, sep } from "path";
+import { existsSync, mkdirSync, readFileSync as readFileSync2, readdirSync, realpathSync, writeFileSync } from "fs";
+import { basename, dirname, isAbsolute, join as join3, normalize, resolve, sep } from "path";
 
 // ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v3/external.js
 var exports_external = {};
@@ -4500,26 +4510,303 @@ var coerce = {
   date: (arg) => ZodDate.create({ ...arg, coerce: true })
 };
 var NEVER = INVALID;
-// src/config.ts
+// ../contracts/dist/client/transport.js
+import { readFileSync, statSync } from "fs";
 import { join } from "path";
+function envToken(name) {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+function clientTransportEnvKeys(name) {
+  const envSegment = envToken(name);
+  return {
+    apiUrlKeys: [`HASNA_${envSegment}_API_URL`, `${envSegment}_API_URL`],
+    apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
+  };
+}
+function credentialOverrideEnvKey(name) {
+  return `HASNA_${envToken(name)}_API_KEY_OVERRIDE`;
+}
+var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE";
+
+class CredentialResolutionError extends Error {
+  appName;
+  attempted;
+  constructor(appName, message, attempted) {
+    super(message);
+    this.name = "CredentialResolutionError";
+    this.appName = appName;
+    this.attempted = attempted;
+  }
+}
+var HASNA_STATE_DIR = ".hasna";
+var FLEET_CREDENTIAL_DIR = "cloud";
+var CONFIG_DIR = ".config";
+var CONFIG_NAMESPACE = "hasna";
+var MAX_CREDENTIAL_FILE_BYTES = 64 * 1024;
+var SAFE_APP_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+var SAFE_PROFILE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+var ILLEGAL_IN_HEADER_VALUE = /[^\t\x20-\x7e]/;
+function homeDir(env) {
+  const home = env.HOME?.trim();
+  return home ? home : null;
+}
+function credentialDiskSources(name, env) {
+  return profileDiskSources(name, env, null);
+}
+function profileDiskSources(name, env, profile) {
+  const home = homeDir(env);
+  if (!home || !SAFE_APP_SLUG.test(name))
+    return [];
+  const stem = profile ? `${name}.${profile}` : name;
+  const configStem = profile ? `${name}-${profile}` : name;
+  return [
+    join(home, HASNA_STATE_DIR, FLEET_CREDENTIAL_DIR, `${stem}.env`),
+    join(home, CONFIG_DIR, CONFIG_NAMESPACE, `${configStem}-cloud.env`)
+  ];
+}
+function parseEnvFile(text) {
+  const values = new Map;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#"))
+      continue;
+    const withoutExport = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const equals = withoutExport.indexOf("=");
+    if (equals <= 0)
+      continue;
+    const key = withoutExport.slice(0, equals).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+      continue;
+    let value = withoutExport.slice(equals + 1).trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+      if (value.length < 2 || !value.endsWith(quote))
+        continue;
+      value = value.slice(1, -1);
+    }
+    if (value.length === 0)
+      continue;
+    values.set(key, value);
+  }
+  return values;
+}
+function readAppConfigFile(path) {
+  let text;
+  try {
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size > MAX_CREDENTIAL_FILE_BYTES)
+      return null;
+    text = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  return parseEnvFile(text);
+}
+function readCredentialFile(path, apiKeyKeys) {
+  const values = readAppConfigFile(path);
+  if (!values)
+    return null;
+  for (const key of apiKeyKeys) {
+    const value = values.get(key)?.trim();
+    if (value)
+      return value;
+  }
+  return null;
+}
+function assertUsableCredential(appName, source, value) {
+  if (!ILLEGAL_IN_HEADER_VALUE.test(value))
+    return;
+  throw new CredentialResolutionError(appName, `The credential from ${source} contains characters that cannot be sent in an HTTP header ` + `(a control character or non-ASCII byte). A file written with CR-only line endings is the usual ` + `cause. Rewrite that credential file with one LF-terminated KEY=value line. ` + `The value is not shown here, and is deliberately never logged.`, [source]);
+}
+var INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
+var CREDENTIAL_SEAL = Symbol.for("hasna:contracts:sealedCredential");
+function sealCredential(fields) {
+  const { apiKey } = fields;
+  const visible = {
+    tier: fields.tier,
+    source: fields.source,
+    deliberate: fields.deliberate,
+    deprecated: fields.deprecated,
+    diskCandidates: Object.freeze([...fields.diskCandidates]),
+    warning: fields.warning
+  };
+  const sealed = { ...visible };
+  Object.defineProperty(sealed, "apiKey", {
+    value: apiKey,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(sealed, INSPECT_CUSTOM, {
+    value: () => ({ ...visible, apiKey: "[redacted]" }),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(sealed, CREDENTIAL_SEAL, {
+    value: true,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  return Object.freeze(sealed);
+}
+function firstEnvValue(env, keys) {
+  for (const key of keys) {
+    const value = env[key]?.trim();
+    if (value)
+      return { key, value };
+  }
+  return null;
+}
+var DEPRECATION_REGISTRY = Symbol.for("hasna:contracts:credentialDeprecationNotices");
+function deprecationNotified() {
+  const host = globalThis;
+  const existing = host[DEPRECATION_REGISTRY];
+  if (existing instanceof Set)
+    return existing;
+  const created = new Set;
+  host[DEPRECATION_REGISTRY] = created;
+  return created;
+}
+function defaultDeprecationSink(message) {
+  if (typeof process !== "undefined" && process.stderr) {
+    process.stderr.write(`${message}
+`);
+  }
+}
+function resolveCredential(name, env, options = {}) {
+  const { apiKeyKeys } = clientTransportEnvKeys(name);
+  const diskPaths = credentialDiskSources(name, env);
+  const explicitKey = options.apiKey?.trim();
+  if (explicitKey) {
+    assertUsableCredential(name, "the explicit apiKey argument", explicitKey);
+    return sealCredential({
+      apiKey: explicitKey,
+      tier: "argument",
+      source: "explicit apiKey argument",
+      deliberate: true,
+      deprecated: false,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  const overrideKeyName = credentialOverrideEnvKey(name);
+  const overrideRaw = env[overrideKeyName];
+  if (overrideRaw !== undefined) {
+    const override = overrideRaw.trim();
+    if (!override) {
+      throw new CredentialResolutionError(name, `${overrideKeyName} is set but empty. It is a deliberate override, so it is not resolved around: ` + `either give it a real key or unset it to fall back to the credential on disk.`, [overrideKeyName]);
+    }
+    assertUsableCredential(name, overrideKeyName, override);
+    return sealCredential({
+      apiKey: override,
+      tier: "override",
+      source: overrideKeyName,
+      deliberate: true,
+      deprecated: false,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  const profile = options.profile?.trim() || env[CREDENTIAL_PROFILE_ENV_KEY]?.trim();
+  if (profile) {
+    const profileSource = options.profile?.trim() ? "explicit profile argument" : CREDENTIAL_PROFILE_ENV_KEY;
+    if (!SAFE_PROFILE.test(profile)) {
+      throw new CredentialResolutionError(name, `Profile name from ${profileSource} is not usable in a path. ` + `Use letters, digits, dot, dash, or underscore.`, [profileSource]);
+    }
+    const paths = profileDiskSources(name, env, profile);
+    for (const path of paths) {
+      const value = readCredentialFile(path, apiKeyKeys);
+      if (value) {
+        assertUsableCredential(name, path, value);
+        return sealCredential({
+          apiKey: value,
+          tier: "profile",
+          source: path,
+          deliberate: true,
+          deprecated: false,
+          diskCandidates: paths,
+          warning: null
+        });
+      }
+    }
+    throw new CredentialResolutionError(name, `Profile '${profile}' (from ${profileSource}) has no ${apiKeyKeys[0]} for '${name}'. ` + `Looked in: ${paths.join(", ") || "<no HOME in this environment>"}. ` + `A profile names WHICH identity to use, so it is never resolved around \u2014 ` + `create the profile's credential file or unset ${CREDENTIAL_PROFILE_ENV_KEY}.`, paths);
+  }
+  const diskHits = diskPaths.map((path) => ({ path, value: readCredentialFile(path, apiKeyKeys) })).filter((hit) => hit.value !== null);
+  if (diskHits.length > 0) {
+    const winner = diskHits[0];
+    assertUsableCredential(name, winner.path, winner.value);
+    const divergentSources = [
+      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.path),
+      ...(() => {
+        const legacyHit = firstEnvValue(env, apiKeyKeys);
+        return legacyHit && legacyHit.value !== winner.value ? [legacyHit.key] : [];
+      })()
+    ];
+    const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.path} wins, because a file on ` + `disk is re-read on every call while an environment variable is a snapshot. Reconcile them \u2014 ` + `a rotation that updated only one leaves the other to fail 401 wherever it is loaded first.` : null;
+    return sealCredential({
+      apiKey: winner.value,
+      tier: "disk",
+      source: winner.path,
+      deliberate: false,
+      deprecated: false,
+      diskCandidates: diskPaths,
+      warning
+    });
+  }
+  const legacy = firstEnvValue(env, apiKeyKeys);
+  if (legacy) {
+    assertUsableCredential(name, legacy.key, legacy.value);
+    const where = diskPaths.length > 0 ? `Put the current key in ${diskPaths[0]} \u2014 it is re-read on every call, so rotations take effect immediately.` : `This environment has no HOME, so no credential file could be consulted at all; the disk tier is ` + `unavailable here and this process will keep using the environment snapshot.`;
+    const message = `[${name}] DEPRECATED: the API key came from ${legacy.key} in this process's environment. ` + `Environment variables are a snapshot taken when this process started, so a shell that started ` + `before a key rotation keeps using the old key until it exits. ${where}`;
+    const sink = options.onDeprecation ?? defaultDeprecationSink;
+    const notified = deprecationNotified();
+    if (!notified.has(name)) {
+      notified.add(name);
+      sink(message);
+    }
+    return sealCredential({
+      apiKey: legacy.value,
+      tier: "legacy-env",
+      source: legacy.key,
+      deliberate: false,
+      deprecated: true,
+      diskCandidates: diskPaths,
+      warning: message
+    });
+  }
+  return null;
+}
+var IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+var AUTHORITY_OVERRIDE_HEADERS = new Set([
+  "host",
+  ":authority",
+  "forwarded",
+  "x-forwarded-host",
+  "x-original-host"
+]);
+
+// src/config.ts
+import { join as join2 } from "path";
 import { homedir } from "os";
 function getHooksDataDir() {
   const explicit = process.env.HASNA_HOOKS_DATA_DIR ?? process.env.HOOKS_DATA_DIR;
   if (explicit)
     return explicit;
-  return join(homedir(), ".hasna", "hooks");
+  return join2(homedir(), ".hasna", "hooks");
 }
 function getCustomHooksDir() {
-  return join(getHooksDataDir(), "hooks");
+  return join2(getHooksDataDir(), "hooks");
 }
 function getLockPath() {
   const explicit = process.env.HASNA_HOOKS_LOCK_PATH ?? process.env.HOOKS_LOCK_PATH;
   if (explicit)
     return explicit;
-  return join(getHooksDataDir(), "hooks.lock");
+  return join2(getHooksDataDir(), "hooks.lock");
 }
 function resolveApiKey() {
-  return process.env.HASNA_HOOKS_API_KEY ?? process.env.HOOKS_API_KEY;
+  return resolveCredential("hooks", process.env)?.apiKey;
 }
 
 // src/lib/semver.ts
@@ -4575,7 +4862,7 @@ function realpathNearest(path) {
     tail.unshift(basename(cur));
     cur = parent;
   }
-  return join2(realpathSync(cur), ...tail);
+  return join3(realpathSync(cur), ...tail);
 }
 function assertContainedReal(root, target, raw) {
   const rootReal = realpathSync(root);
@@ -4608,25 +4895,25 @@ function resolveScript(manifest, manifestDir) {
   if (isInlineScript(manifest))
     return { path: scriptRelFor(manifest), content: manifest.script };
   const rel = scriptRelFor(manifest);
-  const resolved = assertContained(join2(manifestDir, rel), manifestDir, manifest.script);
+  const resolved = assertContained(join3(manifestDir, rel), manifestDir, manifest.script);
   if (!existsSync(resolved)) {
     throw new Error(`manifest script file not found: ${resolved}`);
   }
-  return { path: rel, content: readFileSync(resolved, "utf-8") };
+  return { path: rel, content: readFileSync2(resolved, "utf-8") };
 }
 function customHookDir(name) {
-  return join2(getCustomHooksDir(), shortManifestName(name));
+  return join3(getCustomHooksDir(), shortManifestName(name));
 }
 function readCustomManifest(name) {
   const dir = customHookDir(name);
-  const manifestPath = join2(dir, "manifest.json");
+  const manifestPath = join3(dir, "manifest.json");
   if (!existsSync(manifestPath))
     return;
   try {
-    const manifest = parseManifest(readFileSync(manifestPath, "utf-8"));
+    const manifest = parseManifest(readFileSync2(manifestPath, "utf-8"));
     const script = resolveScript(manifest, dir);
     const scriptIsInline = isInlineScript(manifest);
-    return { manifest, scriptPath: join2(dir, script.path), scriptContent: script.content, scriptIsInline };
+    return { manifest, scriptPath: join3(dir, script.path), scriptContent: script.content, scriptIsInline };
   } catch (err) {
     if (err instanceof ScriptContainmentError)
       throw err;
@@ -4655,13 +4942,13 @@ function readdirSafe(dir) {
 
 // src/lib/store.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2, renameSync } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync2, renameSync } from "fs";
 import { readFile } from "fs/promises";
 
 // src/db/index.ts
 import { Database } from "bun:sqlite";
 import { existsSync as existsSync3, mkdirSync as mkdirSync2, cpSync } from "fs";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { homedir as homedir3 } from "os";
 
 // src/db/schema.ts
@@ -4834,8 +5121,8 @@ function runMigrations(db) {
 }
 
 // src/db/legacy-import.ts
-import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "fs";
+import { join as join4 } from "path";
 import { homedir as homedir2 } from "os";
 var META_KEY = "legacy_import_done";
 function ensureMetaTable(db) {
@@ -4860,7 +5147,7 @@ function nanoid() {
 function importJsonlFile(db, filePath) {
   let count = 0;
   try {
-    const lines = readFileSync2(filePath, "utf-8").split(`
+    const lines = readFileSync3(filePath, "utf-8").split(`
 `).filter(Boolean);
     for (const line of lines) {
       try {
@@ -4886,7 +5173,7 @@ function importJsonlFile(db, filePath) {
 function importErrorsLog(db, filePath) {
   let count = 0;
   try {
-    const lines = readFileSync2(filePath, "utf-8").split(`
+    const lines = readFileSync3(filePath, "utf-8").split(`
 `).filter(Boolean);
     const linePattern = /^\[(.+?)\]\s+(?:\[session:(\S+)\]\s+)?(.+?)\s+\u2014\s+(.+)$/;
     for (const line of lines) {
@@ -4911,25 +5198,25 @@ function importErrorsLog(db, filePath) {
   } catch {}
   return count;
 }
-function runLegacyImport(db, homeDir = homedir2()) {
+function runLegacyImport(db, homeDir2 = homedir2()) {
   try {
     if (isAlreadyDone(db))
       return;
     let total = 0;
-    const claudeProjectsDir = join3(homeDir, ".claude", "projects");
+    const claudeProjectsDir = join4(homeDir2, ".claude", "projects");
     if (existsSync2(claudeProjectsDir)) {
       try {
         const projectDirs = readdirSync2(claudeProjectsDir);
         for (const dir of projectDirs) {
-          const projectDir = join3(claudeProjectsDir, dir);
+          const projectDir = join4(claudeProjectsDir, dir);
           try {
             const files = readdirSync2(projectDir);
             for (const file of files) {
               if (file.match(/^session-log-\d{4}-\d{2}-\d{2}\.jsonl$/)) {
-                total += importJsonlFile(db, join3(projectDir, file));
+                total += importJsonlFile(db, join4(projectDir, file));
               }
               if (file === "errors.log") {
-                total += importErrorsLog(db, join3(projectDir, file));
+                total += importErrorsLog(db, join4(projectDir, file));
               }
             }
           } catch {}
@@ -4967,10 +5254,10 @@ function resolveDataDir() {
   const explicit = process.env.HASNA_HOOKS_DATA_DIR ?? process.env.HOOKS_DATA_DIR;
   if (explicit)
     return explicit;
-  const newDir = join4(homedir3(), ".hasna", "hooks");
-  const oldDir = join4(homedir3(), ".hooks");
+  const newDir = join5(homedir3(), ".hasna", "hooks");
+  const oldDir = join5(homedir3(), ".hooks");
   if (!existsSync3(newDir) && existsSync3(oldDir)) {
-    mkdirSync2(join4(homedir3(), ".hasna"), { recursive: true });
+    mkdirSync2(join5(homedir3(), ".hasna"), { recursive: true });
     cpSync(oldDir, newDir, { recursive: true });
   }
   return newDir;
@@ -4980,7 +5267,7 @@ function getDbPath() {
   if (explicitDb)
     return explicitDb;
   const dataDir = resolveDataDir();
-  return join4(dataDir, "hooks.db");
+  return join5(dataDir, "hooks.db");
 }
 function ensureDir(dbPath) {
   const dir = dbPath.substring(0, dbPath.lastIndexOf("/"));
@@ -5079,7 +5366,7 @@ function readLock() {
     return { hooks: {} };
   let raw;
   try {
-    raw = readFileSync3(path, "utf-8");
+    raw = readFileSync4(path, "utf-8");
   } catch {
     throw new LockFileError(`hooks.lock (${path}) could not be read. Repair: fix permissions or move the file aside and run 'hooks sync'.`);
   }
@@ -5111,7 +5398,7 @@ function setPinnedHook(name, entry) {
   return writeLock(lock);
 }
 function retrustHook(name, scriptPath, version, source) {
-  const actual = sha256Of(readFileSync3(scriptPath));
+  const actual = sha256Of(readFileSync4(scriptPath));
   const db = getDb();
   upsertHookRecord(db, {
     name,
@@ -5125,14 +5412,14 @@ function retrustHook(name, scriptPath, version, source) {
 }
 
 // src/lib/resolve.ts
-import { dirname as dirname2, join as join5 } from "path";
+import { dirname as dirname2, join as join6 } from "path";
 import { existsSync as existsSync5 } from "fs";
 import { fileURLToPath } from "url";
 function resolveBundledHooksDir(moduleDir = dirname2(fileURLToPath(import.meta.url))) {
-  const sourceLayout = join5(moduleDir, "..", "..", "hooks");
-  if (existsSync5(join5(sourceLayout, "hook-gitguard")))
+  const sourceLayout = join6(moduleDir, "..", "..", "hooks");
+  if (existsSync5(join6(sourceLayout, "hook-gitguard")))
     return sourceLayout;
-  return join5(moduleDir, "..", "hooks");
+  return join6(moduleDir, "..", "hooks");
 }
 function resolveHookDir(name) {
   const custom2 = readCustomManifest(name);
@@ -5143,10 +5430,10 @@ function resolveHookDir(name) {
     return;
   const short = shortManifestName(name);
   const bundledBase = resolveBundledHooksDir();
-  const direct = join5(bundledBase, short);
+  const direct = join6(bundledBase, short);
   if (existsSync5(direct))
     return direct;
-  const prefixed = join5(bundledBase, `hook-${short}`);
+  const prefixed = join6(bundledBase, `hook-${short}`);
   return existsSync5(prefixed) ? prefixed : undefined;
 }
 function resolveScriptPath(name) {
@@ -5156,7 +5443,7 @@ function resolveScriptPath(name) {
   const dir = resolveHookDir(name);
   if (!dir)
     return;
-  const script = join5(dir, "src", "hook.ts");
+  const script = join6(dir, "src", "hook.ts");
   return existsSync5(script) ? script : undefined;
 }
 function resolveHookMeta(name) {
@@ -5208,6 +5495,11 @@ function resolveHook(name) {
   };
 }
 
+// src/serve.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname3, join as join7 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+
 // src/lib/secure-compare.ts
 function secureEqual(a, b) {
   const enc = new TextEncoder;
@@ -5221,10 +5513,169 @@ function secureEqual(a, b) {
   return diff === 0;
 }
 
+// src/openapi.ts
+var openApiDocument = {
+  openapi: "3.1.0",
+  info: {
+    title: "Hooks Registry API",
+    version: "0.1.0",
+    description: "Local registry HTTP API for @hasna/hooks: catalog, lock, and artifact reads are open; publishing (PUT /api/v1/hooks) requires the API key (authorization: Bearer or x-api-key)."
+  },
+  servers: [{ url: "/" }],
+  paths: {
+    "/health": {
+      get: {
+        summary: "Liveness probe",
+        operationId: "getHealth",
+        responses: {
+          "200": {
+            description: "Service is alive",
+            content: {
+              "application/json": {
+                schema: { type: "object", additionalProperties: true }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/ready": {
+      get: {
+        summary: "Readiness probe \u2014 the hooks.lock store is readable",
+        operationId: "getReady",
+        responses: {
+          "200": { description: "Lock store is readable" },
+          "503": { description: "Lock store is not readable" }
+        }
+      }
+    },
+    "/version": {
+      get: {
+        summary: "Package version",
+        operationId: "getVersion",
+        responses: {
+          "200": {
+            description: "The installed @hasna/hooks version",
+            content: {
+              "application/json": {
+                schema: { type: "object", properties: { version: { type: "string" } } }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/openapi.json": {
+      get: {
+        summary: "This OpenAPI document",
+        operationId: "getOpenApi",
+        responses: { "200": { description: "OpenAPI 3.1 document" } }
+      }
+    },
+    "/api/v1/catalog": {
+      get: {
+        summary: "List the full hook catalog with versions and sha256",
+        operationId: "getCatalog",
+        responses: {
+          "200": {
+            description: "Catalog entries",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    hooks: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        properties: {
+                          name: { type: "string" },
+                          version: { type: "string" },
+                          sha256: { type: "string" },
+                          events: { type: "array", items: { type: "string" } }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/lock": {
+      get: {
+        summary: "Read the published hooks.lock with per-hook versions",
+        operationId: "getLock",
+        responses: { "200": { description: "The lock file" } }
+      }
+    },
+    "/api/v1/hooks/{name}/{version}": {
+      get: {
+        summary: "Fetch one hook's manifest and script",
+        operationId: "getHookArtifact",
+        parameters: [
+          { name: "name", in: "path", required: true, schema: { type: "string" } },
+          { name: "version", in: "path", required: true, schema: { type: "string" } }
+        ],
+        responses: {
+          "200": {
+            description: "Hook artifact; x-hook-sha256 header carries the script hash"
+          },
+          "400": { description: "Invalid URL encoding or semver version" },
+          "404": { description: "Hook not found locally" }
+        }
+      }
+    },
+    "/api/v1/hooks": {
+      put: {
+        summary: "Publish/retrust a hook (requires the API key)",
+        operationId: "putHook",
+        requestBody: {
+          required: true,
+          content: {
+            "application/json": {
+              schema: {
+                type: "object",
+                properties: { name: { type: "string" }, version: { type: "string" } }
+              }
+            }
+          }
+        },
+        responses: {
+          "200": { description: "Hook retrusted and pin updated" },
+          "401": { description: "Missing or invalid API key" },
+          "404": { description: "Hook not found in local store" },
+          "409": { description: "Version mismatch with the local store" }
+        },
+        security: [{ apiKey: [] }]
+      }
+    }
+  },
+  components: {
+    securitySchemes: {
+      apiKey: {
+        type: "http",
+        scheme: "bearer",
+        description: "The registry API key (HASNA_HOOKS_API_KEY / HOOKS_API_KEY)."
+      }
+    }
+  }
+};
+
 // src/serve.ts
 var DEFAULT_SERVE_PORT = 39428;
 var SERVE_HOST = "127.0.0.1";
 var SERVE_SERVICE_NAME = "hooks-registry";
+function packageVersion() {
+  try {
+    const pkgPath = join7(dirname3(fileURLToPath2(import.meta.url)), "..", "package.json");
+    return JSON.parse(readFileSync5(pkgPath, "utf-8")).version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 async function buildCatalog() {
   const byName = new Map;
   for (const meta of HOOKS) {
@@ -5297,6 +5748,20 @@ function handleServeRequest(req, apiKey) {
   if (url.pathname === "/health" && req.method === "GET") {
     return Promise.resolve(json({ status: "ok", name: SERVE_SERVICE_NAME }));
   }
+  if (url.pathname === "/ready" && req.method === "GET") {
+    try {
+      readLock();
+      return Promise.resolve(json({ status: "ready", name: SERVE_SERVICE_NAME }));
+    } catch {
+      return Promise.resolve(json({ status: "not-ready", name: SERVE_SERVICE_NAME }, 503));
+    }
+  }
+  if (url.pathname === "/version" && req.method === "GET") {
+    return Promise.resolve(json({ version: packageVersion() }));
+  }
+  if (url.pathname === "/openapi.json" && req.method === "GET") {
+    return Promise.resolve(json(openApiDocument));
+  }
   if (url.pathname === "/api/v1/catalog" && req.method === "GET") {
     return buildCatalog().then((catalog) => json({ hooks: catalog }));
   }