@hasna/hooks 0.9.5 → 0.9.6

package/dist/lib/native-safety.d.ts

@@ -0,0 +1,15 @@
+export type NativeSafetyName = "trash-guard" | "workspace-repos-guard";
+export interface NativeSafetyBinding {
+    name: NativeSafetyName;
+    runtime: string;
+    runtimeSHA256: string;
+    worker: string;
+    workerSHA256: string;
+    home: string;
+    path: string;
+}
+export declare function isNativeSafetyName(name: string): name is NativeSafetyName;
+export declare function buildNativeSafetyCommand(binding: NativeSafetyBinding): string;
+export declare function nativeSafetyRegistration(command: string): NativeSafetyName | undefined;
+/** Built-in capability only: no registry, custom source, profile or app store. */
+export declare function installedNativeSafetyCommand(name: NativeSafetyName): string;

package/dist/openapi.d.ts

@@ -1,8 +1,8 @@
-export declare const openApiDocument: {
+export declare function buildOpenApiDocument(version: string): {
     readonly openapi: "3.1.0";
     readonly info: {
         readonly title: "Hooks Registry API";
-        readonly version: "0.1.0";
+        readonly version: string;
         readonly 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).";
     };
     readonly servers: readonly [{
@@ -19,8 +19,7 @@ export declare const openApiDocument: {
                         readonly content: {
                             readonly "application/json": {
                                 readonly schema: {
-                                    readonly type: "object";
-                                    readonly additionalProperties: true;
+                                    readonly $ref: "#/components/schemas/HooksHealth";
                                 };
                             };
                         };
@@ -35,9 +34,23 @@ export declare const openApiDocument: {
                 readonly responses: {
                     readonly "200": {
                         readonly description: "Lock store is readable";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksHealth";
+                                };
+                            };
+                        };
                     };
                     readonly "503": {
                         readonly description: "Lock store is not readable";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksHealth";
+                                };
+                            };
+                        };
                     };
                 };
             };
@@ -52,12 +65,7 @@ export declare const openApiDocument: {
                         readonly content: {
                             readonly "application/json": {
                                 readonly schema: {
-                                    readonly type: "object";
-                                    readonly properties: {
-                                        readonly version: {
-                                            readonly type: "string";
-                                        };
-                                    };
+                                    readonly $ref: "#/components/schemas/HooksVersion";
                                 };
                             };
                         };
@@ -72,6 +80,14 @@ export declare const openApiDocument: {
                 readonly responses: {
                     readonly "200": {
                         readonly description: "OpenAPI 3.1 document";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: true;
+                                };
+                            };
+                        };
                     };
                 };
             };
@@ -86,32 +102,7 @@ export declare const openApiDocument: {
                         readonly content: {
                             readonly "application/json": {
                                 readonly schema: {
-                                    readonly type: "object";
-                                    readonly properties: {
-                                        readonly hooks: {
-                                            readonly type: "array";
-                                            readonly items: {
-                                                readonly type: "object";
-                                                readonly properties: {
-                                                    readonly name: {
-                                                        readonly type: "string";
-                                                    };
-                                                    readonly version: {
-                                                        readonly type: "string";
-                                                    };
-                                                    readonly sha256: {
-                                                        readonly type: "string";
-                                                    };
-                                                    readonly events: {
-                                                        readonly type: "array";
-                                                        readonly items: {
-                                                            readonly type: "string";
-                                                        };
-                                                    };
-                                                };
-                                            };
-                                        };
-                                    };
+                                    readonly $ref: "#/components/schemas/HooksCatalog";
                                 };
                             };
                         };
@@ -126,6 +117,13 @@ export declare const openApiDocument: {
                 readonly responses: {
                     readonly "200": {
                         readonly description: "The lock file";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksLock";
+                                };
+                            };
+                        };
                     };
                 };
             };
@@ -152,12 +150,41 @@ export declare const openApiDocument: {
                 readonly responses: {
                     readonly "200": {
                         readonly description: "Hook artifact; x-hook-sha256 header carries the script hash";
+                        readonly headers: {
+                            readonly "x-hook-sha256": {
+                                readonly description: "sha256 of the served script, the same value the lock pins";
+                                readonly schema: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksArtifact";
+                                };
+                            };
+                        };
                     };
                     readonly "400": {
                         readonly description: "Invalid URL encoding or semver version";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksError";
+                                };
+                            };
+                        };
                     };
                     readonly "404": {
                         readonly description: "Hook not found locally";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksError";
+                                };
+                            };
+                        };
                     };
                 };
             };
@@ -171,15 +198,7 @@ export declare const openApiDocument: {
                     readonly content: {
                         readonly "application/json": {
                             readonly schema: {
-                                readonly type: "object";
-                                readonly properties: {
-                                    readonly name: {
-                                        readonly type: "string";
-                                    };
-                                    readonly version: {
-                                        readonly type: "string";
-                                    };
-                                };
+                                readonly $ref: "#/components/schemas/HooksPublishRequest";
                             };
                         };
                     };
@@ -187,15 +206,53 @@ export declare const openApiDocument: {
                 readonly responses: {
                     readonly "200": {
                         readonly description: "Hook retrusted and pin updated";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksPublishResponse";
+                                };
+                            };
+                        };
+                    };
+                    readonly "400": {
+                        readonly description: "Invalid JSON body";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksError";
+                                };
+                            };
+                        };
                     };
                     readonly "401": {
                         readonly description: "Missing or invalid API key";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksError";
+                                };
+                            };
+                        };
                     };
                     readonly "404": {
                         readonly description: "Hook not found in local store";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksError";
+                                };
+                            };
+                        };
                     };
                     readonly "409": {
                         readonly description: "Version mismatch with the local store";
+                        readonly content: {
+                            readonly "application/json": {
+                                readonly schema: {
+                                    readonly $ref: "#/components/schemas/HooksError";
+                                };
+                            };
+                        };
                     };
                 };
                 readonly security: readonly [{
@@ -212,5 +269,217 @@ export declare const openApiDocument: {
                 readonly description: "The registry API key — resolved by the client through the @hasna/contracts chain (HASNA_HOOKS_API_KEY, the Keychain item hasna.credentials.hooks.api-key, or ~/.hasna/hooks/config/credentials); the server compares the inbound bearer/x-api-key value.";
             };
         };
+        readonly schemas: {
+            readonly HooksHealth: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["status", "name"];
+                readonly properties: {
+                    readonly status: {
+                        readonly type: "string";
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly HooksVersion: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["version"];
+                readonly properties: {
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly HooksCatalogEntry: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["name", "version", "sha256", "events", "description", "source", "versions"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                    readonly sha256: {
+                        readonly type: "string";
+                    };
+                    readonly events: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly source: {
+                        readonly type: "string";
+                        readonly description: "bundled | custom | custom-overrides-bundled";
+                    };
+                    readonly versions: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly HooksCatalog: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["hooks"];
+                readonly properties: {
+                    readonly hooks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly $ref: "#/components/schemas/HooksCatalogEntry";
+                        };
+                    };
+                };
+            };
+            readonly HooksLockEntry: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["version", "sha256", "source"];
+                readonly properties: {
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                    readonly sha256: {
+                        readonly type: "string";
+                    };
+                    readonly source: {
+                        readonly type: "string";
+                    };
+                    readonly pinned: {
+                        readonly type: "boolean";
+                        readonly description: "True for an explicit install/update pin, absent for sync-maintained pins.";
+                    };
+                    readonly versions: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly HooksLock: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["hooks"];
+                readonly properties: {
+                    readonly hooks: {
+                        readonly type: "object";
+                        readonly additionalProperties: {
+                            readonly $ref: "#/components/schemas/HooksLockEntry";
+                        };
+                    };
+                };
+            };
+            readonly HooksManifest: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["name", "version", "events", "script"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly events: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly script: {
+                        readonly type: "string";
+                    };
+                    readonly script_kind: {
+                        readonly type: "string";
+                        readonly enum: readonly ["inline", "file"];
+                    };
+                    readonly args: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly timeout_ms: {
+                        readonly type: "number";
+                    };
+                };
+            };
+            readonly HooksArtifact: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["manifest", "script"];
+                readonly properties: {
+                    readonly manifest: {
+                        readonly $ref: "#/components/schemas/HooksManifest";
+                    };
+                    readonly script: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly HooksError: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["error"];
+                readonly properties: {
+                    readonly error: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly HooksPublishRequest: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["name"];
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly version: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly HooksPublishResponse: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["ok", "hook"];
+                readonly properties: {
+                    readonly ok: {
+                        readonly type: "boolean";
+                    };
+                    readonly hook: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["name", "version", "sha256"];
+                        readonly properties: {
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly version: {
+                                readonly type: "string";
+                            };
+                            readonly sha256: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
     };
 };

package/dist/sdk/authority.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@hasna/hooks/sdk` — the ONE hosted-authority resolver for this surface.
+ *
+ * Split out of `./index.ts` so the generated registry client's resolver-backed
+ * factory (`./registry-client.ts`) can share it without importing the module it
+ * is re-exported from (a module cycle between two SDK entry points).
+ *
+ * FAIL CLOSED (hasna/apps#1720): resolution goes through the ONE
+ * `@hasna/contracts` chain, as a strict URL+key pair, fresh on every call. With
+ * nothing resolved this THROWS the `REMOTE_API_*` diagnostic naming the tiers
+ * and the opt-in; it never returns an authority that would answer from a local
+ * file. The explicit local opt-in (`HASNA_HOOKS_LOCAL=1`, alias `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 { type HooksRemoteAuthority, type HooksTransportOptions } from "../lib/transport.js";
+import type { HooksCredentialOptions, HooksLocalOptInEnv } from "../lib/resolver-types.js";
+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;

package/dist/sdk/generated.d.ts

@@ -0,0 +1,97 @@
+export interface HooksHealth {
+    "status": string;
+    "name": string;
+}
+export interface HooksVersion {
+    "version": string;
+}
+export interface HooksCatalogEntry {
+    "name": string;
+    "version": string;
+    "sha256": string;
+    "events": Array<string>;
+    "description": string;
+    "source": string;
+    "versions": Array<string>;
+}
+export interface HooksCatalog {
+    "hooks": Array<HooksCatalogEntry>;
+}
+export interface HooksLockEntry {
+    "version": string;
+    "sha256": string;
+    "source": string;
+    "pinned"?: boolean;
+    "versions"?: Array<string>;
+}
+export interface HooksLock {
+    "hooks": Record<string, HooksLockEntry>;
+}
+export interface HooksManifest {
+    "name": string;
+    "version": string;
+    "description"?: string;
+    "events": Array<string>;
+    "script": string;
+    "script_kind"?: "inline" | "file";
+    "args"?: Array<string>;
+    "timeout_ms"?: number;
+}
+export interface HooksArtifact {
+    "manifest": HooksManifest;
+    "script": string;
+}
+export interface HooksError {
+    "error": string;
+}
+export interface HooksPublishRequest {
+    "name": string;
+    "version"?: string;
+}
+export interface HooksPublishResponse {
+    "ok": boolean;
+    "hook": {
+        "name": string;
+        "version": string;
+        "sha256": string;
+    };
+}
+export interface HooksRegistryApiClientOptions {
+    /** Base URL, e.g. process.env.APP_API_URL. */
+    baseUrl: string;
+    /** API key, e.g. process.env.APP_API_KEY. Sent as the 'x-api-key' header. */
+    apiKey?: string;
+    /** Custom fetch (defaults to global fetch). */
+    fetch?: typeof fetch;
+    /** Extra headers merged into every request. */
+    headers?: Record<string, string>;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+export declare class HooksRegistryApiClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly baseHeaders;
+    constructor(options: HooksRegistryApiClientOptions);
+    private request;
+    /** List the full hook catalog with versions and sha256 */
+    getCatalog(init?: RequestInit): Promise<HooksCatalog>;
+    /** Publish/retrust a hook (requires the API key) */
+    putHook(body: HooksPublishRequest, init?: RequestInit): Promise<HooksPublishResponse>;
+    /** Fetch one hook's manifest and script */
+    getHookArtifact(name: string, version: string, init?: RequestInit): Promise<HooksArtifact>;
+    /** Read the published hooks.lock with per-hook versions */
+    getLock(init?: RequestInit): Promise<HooksLock>;
+    /** Liveness probe */
+    getHealth(init?: RequestInit): Promise<HooksHealth>;
+    /** This OpenAPI document */
+    getOpenApi(init?: RequestInit): Promise<Record<string, unknown>>;
+    /** Readiness probe — the hooks.lock store is readable */
+    getReady(init?: RequestInit): Promise<HooksHealth>;
+    /** Package version */
+    getVersion(init?: RequestInit): Promise<HooksVersion>;
+}

package/dist/sdk/index.d.ts

@@ -16,10 +16,17 @@
  * 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 { hooksRegistryOrigin, type HooksRemoteAuthority } from "../lib/transport.js";
 import type { HooksCredentialOptions, HooksLocalOptInEnv } from "../lib/resolver-types.js";
+import { type HooksClientOptions } from "./authority.js";
 export type { HooksRemoteAuthority, HooksCredentialOptions, HooksLocalOptInEnv };
 export { hooksRegistryOrigin };
+export { resolveHooksSdkAuthority } from "./authority.js";
+export type { HooksClientOptions } from "./authority.js";
+export { HooksRegistryApiClient, ApiError as HooksRegistryApiError } from "./generated.js";
+export type { HooksRegistryApiClientOptions, HooksHealth, HooksVersion, HooksCatalogEntry, HooksCatalog, HooksLockEntry, HooksLock, HooksManifest, HooksArtifact, HooksError, HooksPublishRequest, HooksPublishResponse, } from "./generated.js";
+export { createHooksRegistryApiClient, hooksRegistryApiClientFor, } from "./registry-client.js";
+export type { HooksRegistryApiClientAuthority, ResolvedHooksRegistryApiClient, } from "./registry-client.js";
 /** One row of `GET /api/v1/catalog` — the registry's latest version of a hook. */
 export interface HooksRegistryCatalogEntry {
     name: string;
@@ -56,23 +63,15 @@ export interface HooksRegistryArtifact {
     /** 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 authority binding privately and resolves
  * its current credential for each request before dispatch to that authority.
+ *
+ * This is the hand-kept, stable surface: it pins the `REMOTE_API_*` error
+ * codes, the raw `x-hook-sha256` header on `artifact()`, and the
+ * never-follow-a-redirect rule. `HooksRegistryApiClient` (./generated.ts) is
+ * the generated counterpart over the same served routes; it is additive, not
+ * a replacement.
  */
 export declare class HooksClient {
     #private;