@hasna/hooks 0.8.0 → 0.9.1

package/dist/lib/db-writer.d.ts

@@ -1,8 +1,37 @@
 /**
  * Shared hook DB writer — single write path for all observability hooks.
  * Never throws: errors are written to stderr only.
+ *
+ * GATED (hasna/apps#1720 fail-closed ruling, W6 2026-09-11). This used to be
+ * the one ungated path to ~/.hasna/hooks/hooks.db: every `hooks run`, every
+ * MCP run tool and four bundled hook runtimes called it, and it created the
+ * store on first write with no credential decision at all — a silent local
+ * default. It now writes ONLY when the environment selects the on-box store
+ * through the explicit opt-in (HASNA_HOOKS_LOCAL=1 / HOOKS_LOCAL=1, answered
+ * from the env dictionary alone — no Keychain or disk read on the per-event
+ * hot path). On the hosted route (a process-wide refusal installed by the CLI
+ * gate / MCP startup, or any authority variable set in the env) and in an
+ * unconfigured environment it prints ONE stderr line naming the opt-in and
+ * writes nothing: the hosted registry has no event route to port to.
+ */
+import type { HookEventRow } from "../db/schema.js";
+import type { HooksLocalOptInEnv } from "./resolver-types.js";
+/** Where a hook event may land: the on-box store, or nowhere (with the reason). */
+export type HookEventSink = {
+    kind: "local";
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Decide the event sink from the env dictionary and the process-wide store
+ * refusal ONLY — never the resolver, so agents' per-event `hooks run` and the
+ * bundled hook children never pay a `security` spawn here (the CLI gate
+ * already decided the route for the parent process).
  */
-import type { HookEventRow } from "../db/schema";
+export declare function resolveHookEventSink(env?: HooksLocalOptInEnv): HookEventSink;
+/** Reset the once-per-process sink refusal notice. Test seam only. */
+export declare function __resetHookEventSinkNotice(): void;
 export type HookEventInput = Omit<HookEventRow, "id" | "timestamp"> & {
     timestamp?: string;
 };

package/dist/lib/installer.d.ts

@@ -9,7 +9,8 @@
  * Hooks run directly from the globally installed @hasna/hooks package.
  * No files are copied. The settings entry points to `hooks run <name>`.
  */
-import { type HookEvent } from "./registry.js";
+import { type HookEvent, type HookMeta } from "./registry.js";
+import { type StaleRegistration } from "./registration.js";
 export type Scope = "global" | "project";
 export type Target = "claude" | "gemini" | "codewith" | "all";
 type SingleTarget = Exclude<Target, "all">;
@@ -47,6 +48,18 @@ export declare function hookExists(name: string): boolean;
 /** Whether a hook's event can be registered for the given target */
 export declare function isEventSupported(internalEvent: HookEvent, target: SingleTarget): boolean;
 export declare function buildCodewithTomlFragment(name: string, profile?: string): string;
+/**
+ * The one conflict class that BLOCKS an install: two PreToolUse hooks on
+ * overlapping matchers that both rewrite the tool input
+ * (`hookSpecificOutput.updatedInput`). The harness keeps ONE rewrite per tool
+ * call — last writer wins — so whichever guard loses is silently disarmed
+ * with no error anywhere. `trash-guard` is the first such hook.
+ *
+ * Every other conflict stays advisory: it still installs, with the warning.
+ */
+export declare function detectRewriteConflict(name: string, scope: Scope, target: SingleTarget, 
+/** Injected for tests: the rewrite claim is a registry concern, the overlap is not. */
+lookup?: (hookName: string) => HookMeta | undefined): string | undefined;
 export declare function installHook(name: string, options?: InstallOptions): InstallResult;
 export declare function installHooks(names: string[], options?: InstallOptions): InstallResult[];
 export declare function getRegisteredHooksForTarget(scope?: Scope, target?: SingleTarget): string[];
@@ -54,6 +67,32 @@ export declare function getRegisteredHooks(scope?: Scope): string[];
 /** @deprecated Use getRegisteredHooks instead */
 export declare const getInstalledHooks: typeof getRegisteredHooks;
 export declare function removeHook(name: string, scope?: Scope, target?: Target): boolean;
+/**
+ * Every settings registration for the scope whose hook name does not resolve.
+ *
+ * A stale registration makes the agent spawn `hooks run <name>` on every event
+ * it is wired to, and each spawn fails — the failure is invisible to `hooks
+ * install`/`hooks remove` because nothing re-checks names already written.
+ */
+export declare function scanStaleRegistrations(scope?: Scope): StaleRegistration[];
+export interface PruneStaleResult {
+    /** Settings file edited. */
+    file: string;
+    /** The registrations removed from it. */
+    removed: StaleRegistration[];
+    /** Sibling backup of the pre-edit bytes (`<settings>.bak`). */
+    backupPath: string;
+}
+/**
+ * Remove every stale registration the scope carries, and nothing else.
+ *
+ * Edits only the entries whose own command is stale: sibling hooks in the same
+ * entry, unrelated event keys, matchers and every non-hook settings key are
+ * preserved, the file stays valid JSON, and a `.bak` sibling is written before
+ * the edit. Idempotent — a second call finds nothing stale and writes nothing.
+ * A registration whose hook resolves is never touched.
+ */
+export declare function pruneStaleRegistrations(scope?: Scope): PruneStaleResult[];
 export interface UninstallResult {
     name: string;
     removed: boolean;

package/dist/lib/local-opt-in.d.ts

@@ -22,6 +22,32 @@ export declare function hooksAuthorityEnvKeys(): string[];
 export declare function hasHooksEnvAuthorityIntent(env?: HooksLocalOptInEnv): boolean;
 /** True when this environment should be served by the on-box bundled store. */
 export declare function selectsHooksLocalStore(env?: HooksLocalOptInEnv): boolean;
+/** The credential tiers every fail-closed line names, in chain order. Never a value. */
+export declare const HOOKS_CREDENTIAL_TIERS = "the Keychain item hasna.credentials.hooks.api-key, ~/.hasna/hooks/config/credentials, or HASNA_HOOKS_API_KEY";
+/** The opt-in every refusal names, canonical spelling first. */
+export declare const HOOKS_LOCAL_OPT_IN_HINT = "HASNA_HOOKS_LOCAL=1 (alias HOOKS_LOCAL=1)";
+/**
+ * The ONE line an unconfigured client surface prints before exiting non-zero
+ * (hasna/apps#1720 ruling, W6 target state): the stable code, the tiers
+ * consulted, the opt-in, and the refusal — no credential value, no local
+ * default. The CLI gate, the MCP server and the SDK all print this spelling.
+ */
+export declare function hooksFailClosedLine(detail?: string): string;
+/**
+ * The refusal every local-only verb / tool returns on the HOSTED route: the
+ * on-box SQLite store is a different dataset from the registry authority the
+ * run is routed to, so it is never opened — not even to answer an empty
+ * result. Installed process-wide through `refuseLocalStore()` in
+ * `src/db/index.ts`. Mirrors todos' `REMOTE_COMMAND_UNSUPPORTED`.
+ */
+export declare function hooksHostedRouteLocalStoreRefusal(authority: string): string;
+/**
+ * The line the hook-event writer prints (once per process) when it has no
+ * sink: the hosted registry has no event route, so without the explicit
+ * local opt-in there is nowhere to record the event — and it is NOT written
+ * to a silently created hooks.db.
+ */
+export declare function hooksEventSinkRefusal(): string;
 /**
  * The environment as the resolver should see it: every authority/credential
  * variable that is DECLARED BUT BLANK removed.

package/dist/lib/registration.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Settings registration checks shared by the CLI doctor and the MCP
+ * hooks_doctor.
+ *
+ * Event and matcher are separate settings fields — settings.hooks[event] is
+ * an array of { matcher?, hooks: [...] } entries — so a composite event such
+ * as 'PreToolUse:Bash' must be split before lookup, never used as a key.
+ */
+/** A settings registration whose hook name cannot resolve. */
+export interface StaleRegistration {
+    /** Settings file the registration lives in. */
+    file: string;
+    /** Settings event key holding the entry (PreToolUse, …). */
+    event: string;
+    /** The registered hook name that does not resolve. */
+    hook: string;
+    /** The raw command string from the settings entry. */
+    command: string;
+}
+/**
+ * Find settings registrations whose hook does not resolve.
+ *
+ * A registration is a `hooks run <name>` (or legacy `hook-<name>`) command;
+ * it is stale when `resolveHook(name)` finds no bundled, custom or stored
+ * hook — exactly the lookup `hooks run` performs, so a stale registration
+ * fails on every tool call it is wired to. Direct-path wiring outside the
+ * installer's own command forms is reported by `countSettingsWiring`, never
+ * treated as a hook registration.
+ */
+export declare function findStaleRegistrations(settings: Record<string, unknown>, file: string, resolves?: (name: string) => boolean): StaleRegistration[];
+/**
+ * Whether two tool matchers can select the same tool call. Deliberately loose
+ * (identical, or one a substring of the other) — a false positive costs one
+ * advisory warning, a false negative costs a silently disarmed guard.
+ */
+export declare function matchersOverlap(a: string, b: string): boolean;
+/** The metadata slice `findRewriteOverlaps` needs from a hook. */
+export interface RewriteHookInfo {
+    matcher?: string;
+    event?: string;
+    events?: string[];
+    rewritesInput?: boolean;
+}
+/** Two installed hooks that both rewrite the tool input on the same tool. */
+export interface RewriteOverlap {
+    hooks: [string, string];
+    event: string;
+    matchers: [string, string];
+}
+/**
+ * Installed hooks that both rewrite the tool input
+ * (`hookSpecificOutput.updatedInput`) on an overlapping PreToolUse matcher.
+ *
+ * This is a real defect, not a style nit: the harness applies ONE rewrite per
+ * tool call, so one of the two guards is silently disarmed. The installer
+ * refuses the pairing up front; doctor reports it for settings files it did
+ * not write (hand-edited, or written before the rule existed).
+ */
+export declare function findRewriteOverlaps(names: string[], lookup: (name: string) => RewriteHookInfo | undefined): RewriteOverlap[];
+/**
+ * Whether a hook is registered in a settings file.
+ *
+ * An entry matches when it carries a `hooks run <name>` command and, when the
+ * hook declares a matcher, the entry's matcher is absent (fires on all tools)
+ * or consistent with the hook's matcher (equal, or one regex matches the
+ * other).
+ */
+/**
+ * Count every raw hook entry wired in a settings file — including
+ * direct-path entries that never went through the CLI (`command` values that
+ * are not `hooks run <name>`). Doctor reports this count alongside the
+ * registered count so its "healthy" verdict names its bounds (P2-16b).
+ */
+export declare function countSettingsWiring(settings: Record<string, unknown>): number;
+export declare function hookRegisteredInSettings(settings: Record<string, unknown>, name: string, eventSpec: string, hookMatcher: string): boolean;

package/dist/lib/registry.d.ts

@@ -13,6 +13,20 @@ export interface HookMeta {
     events?: HookEvent[];
     matcher: string;
     tags: string[];
+    /**
+     * This hook rewrites the tool input (`hookSpecificOutput.updatedInput`).
+     * The agent harness keeps ONE rewrite per tool call — last writer wins — so
+     * two input-rewriting hooks on overlapping PreToolUse matchers silently
+     * disarm each other. Install refuses that pairing, and `hooks doctor`
+     * reports it.
+     */
+    rewritesInput?: boolean;
+    /**
+     * Timeout (seconds) written into the agent's settings entry for this hook.
+     * The harness default is 600s, and a TIMED-OUT HOOK DOES NOT BLOCK: a guard
+     * that needs a verdict on stdout must declare a timeout it can meet.
+     */
+    timeoutSeconds?: number;
 }
 export declare const CATEGORIES: readonly ["Git Safety", "Code Quality", "Security", "Notifications", "Context Management", "Workflow Automation", "Environment", "Permissions", "Observability", "Agent Teams"];
 export type Category = (typeof CATEGORIES)[number];

package/dist/lib/sync.d.ts

@@ -92,7 +92,8 @@ export interface PinnedHookInstall {
     sha256: string;
     source: string;
     source_ref: string;
-    artifact: ArtifactResponse;
+    /** The registry artifact for remote pins; null for bundled-registry pins. */
+    artifact: ArtifactResponse | null;
     scriptPath: string;
 }
 /**
@@ -107,4 +108,19 @@ export interface PinnedHookInstall {
  * are first-class, never rejected as "not the latest".
  */
 export declare function fetchPinnedHook(name: string, version: string, apiUrl: string, apiKey: string): Promise<PinnedHookInstall>;
+/**
+ * Pin an exact hook version from the BUNDLED registry (the on-box catalog).
+ * Powers `hooks install <name>@<version>` / `hooks update <name>@<version>`
+ * under the explicit local opt-in (HASNA_HOOKS_LOCAL=1) — the only route on
+ * which `resolveHooksTransport` returns `mode: "local"`; with nothing
+ * configured the CLI gate has already failed closed, and on the hosted route
+ * the remote registry answers the pin. The exact version named must be the
+ * bundled one, and the script stays at its bundled path — the pin (lock + DB
+ * record) is the trust anchor, exactly as local `hooks sync` pins the catalog.
+ * Carried from hasna/apps#1888 (its good half).
+ *
+ * A name or version the bundled registry does not carry is a DATA error with
+ * the available version named — the same shape as a remote pin miss.
+ */
+export declare function installPinnedFromBundled(name: string, version: string): Promise<PinnedHookInstall>;
 export {};

package/dist/sdk/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `@hasna/hooks/sdk` — the hosted hooks registry client (package-surfaces
+ * rule: one package, four surfaces; this is the importable one).
+ *
+ * SELF-CONTAINED. The built bundle (`dist/sdk/index.js`, `bun build --target
+ * bun`) imports node builtins only: the `@hasna/contracts/client` credential
+ * seam is inlined at build time, and nothing here reaches `bun:sqlite` or the
+ * on-box store — the SDK has no local mode. `src/sdk/index.test.ts` pins both.
+ *
+ * FAIL CLOSED (hasna/apps#1720). `createHooksClient()` resolves the registry
+ * authority and credential through the ONE @hasna/contracts chain (env pair →
+ * Keychain item `hasna.credentials.hooks.api-key` → `~/.hasna/hooks/config/
+ * credentials`), as a strict pair, fresh per call. With nothing resolved it
+ * THROWS the `REMOTE_API_*` diagnostic naming the tiers and the opt-in; it
+ * never returns a client that answers from a local file. The explicit local
+ * opt-in (`HASNA_HOOKS_LOCAL=1`) is refused here by name: the SDK is a hosted
+ * client and the on-box store is the CLI's, opt-in only.
+ */
+import { hooksRegistryOrigin, type HooksRemoteAuthority, type HooksTransportOptions } from "../lib/transport.js";
+import type { HooksCredentialOptions, HooksLocalOptInEnv } from "../lib/resolver-types.js";
+export type { HooksRemoteAuthority, HooksCredentialOptions, HooksLocalOptInEnv };
+export { hooksRegistryOrigin };
+/** One row of `GET /api/v1/catalog` — the registry's latest version of a hook. */
+export interface HooksRegistryCatalogEntry {
+    name: string;
+    version: string;
+    sha256: string;
+    events: string[];
+    description: string;
+    source: string;
+    versions: string[];
+}
+/** One pin of `GET /api/v1/lock` — the exact version the registry wants clients on. */
+export interface HooksRegistryLockEntry {
+    version: string;
+    sha256: string;
+    source?: string;
+    versions?: string[];
+}
+export interface HooksRegistryLock {
+    hooks: Record<string, HooksRegistryLockEntry>;
+}
+/** `GET /api/v1/hooks/:name/:version` — a versioned artifact (manifest + script). */
+export interface HooksRegistryArtifact {
+    manifest: {
+        name: string;
+        version: string;
+        description?: string;
+        events: string[];
+        script: string;
+        script_kind?: "inline" | "file";
+        args?: string[];
+        timeout_ms?: number;
+    };
+    script: string;
+    /** The registry's `x-hook-sha256` header for the served row, when present. */
+    sha256: string | null;
+}
+export interface HooksClientOptions {
+    /** Injectable environment (tests). Defaults to `process.env`. */
+    env?: HooksLocalOptInEnv;
+    /** Tier-1 credential inputs and the injectable `security` runner. */
+    credentials?: HooksCredentialOptions;
+    /** Injectable fetch (tests). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Resolve the hosted authority the SDK will talk to. 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 resolveHooksSdkAuthority(env?: HooksLocalOptInEnv, options?: Omit<HooksTransportOptions, "notice">): HooksRemoteAuthority;
+/**
+ * Hosted registry client. Holds the resolved credential privately and sends
+ * it only to the authority it was resolved together with (strict pair).
+ */
+export declare class HooksClient {
+    #private;
+    /** Registry origin WITHOUT `/v1` — the registry routes hang off `<origin>/api/v1`. */
+    readonly origin: string;
+    /** The resolver's `<origin>/v1` authority, for diagnostics. */
+    readonly v1BaseUrl: 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;
+    constructor(authority: HooksRemoteAuthority, options?: {
+        fetch?: typeof fetch;
+    });
+    /** Build the request URL for a registry route (exposed so callers can log WHERE without a key). */
+    urlFor(path: string): string;
+    health(): Promise<{
+        status: string;
+        name: string;
+    }>;
+    catalog(): Promise<HooksRegistryCatalogEntry[]>;
+    lock(): Promise<HooksRegistryLock>;
+    artifact(name: string, version: string): Promise<HooksRegistryArtifact>;
+    private request;
+    private getJson;
+}
+/** Resolve the hosted authority (fail closed) and return a client bound to it. */
+export declare function createHooksClient(options?: HooksClientOptions): HooksClient;