@hasna/hooks 0.12.10 → 0.12.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -6
- package/bin/hooks/stop-review.js +1235 -0
- package/bin/hooks-mcp.js +298 -85
- package/bin/index.js +3348 -1086
- package/bin/native-readiness-entry.js +5 -1
- package/bin/native-safety-entry.js +27 -25
- package/bin/native-safety-worker.cjs +27 -25
- package/bin/serve.js +1362 -70
- package/dist/db/remote-storage.d.ts +7 -1
- package/dist/index.d.ts +4 -1
- package/dist/index.js +1665 -257
- package/dist/lib/codex-safety-check.d.ts +1 -1
- package/dist/lib/hosted-registry.d.ts +70 -0
- package/dist/lib/legacy-registry-artifact.d.ts +23 -0
- package/dist/lib/manifest.d.ts +7 -0
- package/dist/lib/native-safety.d.ts +1 -0
- package/dist/lib/native-target.d.ts +7 -0
- package/dist/lib/opencode-stop-plugin.d.ts +55 -0
- package/dist/lib/registry-artifact.d.ts +36 -0
- package/dist/lib/registry.d.ts +4 -0
- package/dist/lib/stop-review-context.d.ts +12 -0
- package/dist/lib/store.d.ts +4 -0
- package/dist/lib/sumi-stop-plugin.d.ts +129 -0
- package/dist/lib/sync.d.ts +10 -0
- package/dist/lib/transport.d.ts +1 -1
- package/dist/native-readiness.d.ts +1 -1
- package/dist/native-readiness.js +5 -1
- package/dist/openapi.d.ts +160 -16
- package/dist/opencode-stop-plugin.js +384 -0
- package/dist/registry-auth.d.ts +5 -0
- package/dist/registry-http.d.ts +4 -0
- package/dist/sdk/generated.d.ts +32 -12
- package/dist/sdk/index.d.ts +28 -5
- package/dist/sdk/index.js +49 -24
- package/dist/sdk/registry-client.d.ts +1 -1
- package/dist/serve.d.ts +4 -4
- package/dist/storage.js +33 -2
- package/dist/sumi-stop-plugin.js +380 -0
- package/hooks/hook-stop-review/README.md +109 -0
- package/hooks/hook-stop-review/manifest.json +10 -0
- package/hooks/hook-stop-review/package.json +11 -0
- package/hooks/hook-stop-review/src/hook.ts +59 -0
- package/hooks/hook-stop-review/src/index.ts +3 -0
- package/hooks/hook-stop-review/src/jev.ts +121 -0
- package/hooks/hook-stop-review/src/native.ts +246 -0
- package/hooks/hook-stop-review/src/policy.ts +145 -0
- package/hooks/hook-stop-review/src/runtime.ts +309 -0
- package/hooks/hook-stop-review/src/types.ts +121 -0
- package/hooks/hook-trash-guard/src/hook.ts +96 -0
- package/hooks/hook-workspace-repos-guard/src/hook.ts +116 -3
- package/hooks/local-executors.ts +841 -0
- package/package.json +22 -4
- package/scripts/build-bundled-hooks.ts +40 -0
- package/scripts/validate-bundled-hooks.ts +78 -0
- package/scripts/validate-opencode-stop-plugin.ts +42 -0
- package/scripts/validate-package.ts +9 -0
- package/scripts/validate-sumi-stop-plugin.ts +47 -0
package/README.md
CHANGED
|
@@ -490,14 +490,76 @@ hooks update # re-register hooks and refresh pins
|
|
|
490
490
|
|
|
491
491
|
A hook's first run writes its pin, and so do `hooks sync` (in local mode it pins every bundled hook without running any of them), `hooks update`, `hooks install <name>@<version>`, `hooks update <name>@<version>` and `hooks trust`. A station can therefore hold a pin for a hook that has never run there. After any upgrade that changes the script of a hook registered as `hooks run <hook>`, run `hooks trust <hook>` with the new CLI on every station. Run it as the same user and with the same hooks environment that the harness's `hooks run` sees: the local opt-in or registry credential, and any data directory, DB or lock path override. Otherwise it can write a pin that `hooks run` does not read. Where the hook is not pinned yet, it pins the same sha256 that the first run would have pinned, so it is harmless there.
|
|
492
492
|
|
|
493
|
-
|
|
493
|
+
### Hosted publication and station sync
|
|
494
|
+
|
|
495
|
+
Publishing, selecting a version, downloading it and registering a native event
|
|
496
|
+
are separate operations. The hosted registry stores immutable artifacts and
|
|
497
|
+
append-only selection revisions. Clients use `/v1`; the default authority is
|
|
498
|
+
`https://api.hasna.com/hooks/v1`.
|
|
494
499
|
|
|
495
500
|
```bash
|
|
496
|
-
hooks
|
|
497
|
-
|
|
498
|
-
|
|
501
|
+
hooks publish ./my-hook/manifest.json --dry-run --json
|
|
502
|
+
hooks publish ./my-hook/manifest.json --json
|
|
503
|
+
hooks selection coding --json
|
|
504
|
+
hooks selection coding --file ./reviewed-selection.json --json
|
|
505
|
+
hooks sync --selection-profile coding --expected-revision 1 --dry-run --json
|
|
506
|
+
hooks sync --selection-profile coding --expected-revision 1 --json
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
Publication bundles a file entry and its dependency closure before hashing it.
|
|
510
|
+
Re-publishing identical bytes is idempotent; changing an existing name/version
|
|
511
|
+
is refused. Secrets must be references consumed at execution, never manifest
|
|
512
|
+
environment values. A selection request contains `expected_revision` (zero for
|
|
513
|
+
a new profile) and a complete `hooks` map of exact version and digest pins;
|
|
514
|
+
preserve existing selections when preparing a replacement. Read back the
|
|
515
|
+
returned revision before syncing it.
|
|
516
|
+
|
|
517
|
+
Sync verifies the selected artifacts before updating execution files and pins.
|
|
518
|
+
Unselected hooks remain untouched. A failed remote sync cannot authorize an
|
|
519
|
+
unpinned executable through first-use trust. A successful sync does not prove
|
|
520
|
+
that a native harness has registered or executed the hook.
|
|
521
|
+
|
|
522
|
+
The bundled [stop-review hook](hooks/hook-stop-review/README.md) uses a pinned
|
|
523
|
+
Instructions source and a Secrets reference for TypeSafe Jev. Its native adapters
|
|
524
|
+
keep cancellation, current-turn checks and continuation limits in the harness.
|
|
525
|
+
Registration alone is not proof of adoption by a running agent.
|
|
526
|
+
|
|
527
|
+
For a compatible OpenCode build, the package exports the self-contained
|
|
528
|
+
`@hasna/hooks/opencode-stop-plugin` transport. Plan registration from an installed,
|
|
529
|
+
retained runtime, then apply with the exact configuration digest from that plan:
|
|
530
|
+
|
|
531
|
+
```sh
|
|
532
|
+
hooks install stop-review --target opencode --dry-run --json
|
|
533
|
+
hooks install stop-review --target opencode --expected-config-sha256 <planned-digest-or-absent> --json
|
|
534
|
+
hooks install stop-review --target opencode --verify --json
|
|
499
535
|
```
|
|
500
536
|
|
|
537
|
+
The installer preserves and reads back the previous configuration, retains
|
|
538
|
+
unrelated settings and plugins, and refuses JSONC or conflicting entries.
|
|
539
|
+
It uses the global OpenCode configuration by default; `--project` selects
|
|
540
|
+
the current project's configuration. Verify any additional OpenCode configuration
|
|
541
|
+
overrides on the intended consumer. A stock OpenCode build has no guarded stop
|
|
542
|
+
capability: this plugin refuses registration there. Disk verification reports
|
|
543
|
+
`nativeAdoptionVerified: false` until a real native invocation proves adoption.
|
|
544
|
+
|
|
545
|
+
**Registry server.** `hooks serve` exposes the configured registry over HTTP:
|
|
546
|
+
|
|
547
|
+
```bash
|
|
548
|
+
hooks migrate --registry-only --check --json
|
|
549
|
+
hooks migrate --registry-only --json
|
|
550
|
+
hooks serve --port 39428
|
|
551
|
+
# GET /health, GET /ready, GET /v1/catalog, GET /v1/hooks/:name/:version,
|
|
552
|
+
# PUT /v1/hooks, GET/PUT /v1/selections/:profile, GET /v1/lock
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
Hosted PostgreSQL storage requires the configured database and signing key.
|
|
556
|
+
Signed keys are checked against their application, scopes and lifecycle state:
|
|
557
|
+
reads require `hooks:read`, publication and selection require `hooks:write`.
|
|
558
|
+
Missing hosted configuration fails closed, including legacy `/api/v1` aliases.
|
|
559
|
+
Static-key/local serving requires an explicit local opt-in; it is never a
|
|
560
|
+
fallback for a missing signer or database. The registry-only migration adds its
|
|
561
|
+
own tables without running the older event-store migration.
|
|
562
|
+
|
|
501
563
|
**Registry selection (fail closed, strict pair).** The remote-registry authority and its credential resolve through the ONE `@hasna/contracts` client chain (2026-09-04 adoption, hasna/apps#1720), fresh on every call, as a STRICT pair: a URL without a key is a refusal, never half-open progress, and a key alone is a complete configuration (it resolves the fleet gateway `https://api.hasna.com/hooks`). The chain, in order: an explicit `--api-key`/`--profile` argument; `HASNA_HOOKS_API_KEY_OVERRIDE` / `HASNA_PROFILE` / `HASNA_HOOKS_API_KEY_REF`; the macOS Keychain items `hasna.credentials.hooks.api-key` / `.api-url`; `~/.hasna/hooks/config/credentials` (owner-only 0400/0600); then `HASNA_HOOKS_API_URL` / `HASNA_HOOKS_API_KEY` (the unprefixed `HOOKS_*` spellings remain only as the resolver's silent alias fallback). The retired locations (`~/.hasna/fleet-env`, `~/.hasna/cloud`, `~/.config/hasna`, `$XDG_CONFIG_HOME`) and the retired `~/.hasna/hooks/config.json` key store are never read, and no `*_MODE` switch exists. Without a resolved credential, the CLI **fails closed**: registry commands refuse to run rather than silently serving the bundled catalog and local SQLite store, and they name every tier they consulted in the error. Local mode (bundled registry + local store) is an explicit opt-in:
|
|
502
564
|
|
|
503
565
|
```bash
|
|
@@ -529,9 +591,10 @@ hooks mcp --stdio # same server through the CLI; --sse / --ht
|
|
|
529
591
|
import { createHooksClient } from "@hasna/hooks/sdk";
|
|
530
592
|
|
|
531
593
|
const registry = createHooksClient(); // throws REMOTE_API_CONFIG_MISSING with nothing configured
|
|
532
|
-
const catalog = await registry.catalog(); // GET <origin>/
|
|
533
|
-
const lock = await registry.lock(); // GET <origin>/
|
|
594
|
+
const catalog = await registry.catalog(); // GET <origin>/v1/catalog
|
|
595
|
+
const lock = await registry.lock(); // GET <origin>/v1/lock
|
|
534
596
|
const artifact = await registry.artifact("gitguard", lock.hooks.gitguard.version);
|
|
597
|
+
const selected = await registry.selection("coding");
|
|
535
598
|
```
|
|
536
599
|
|
|
537
600
|
```bash
|