@hasna/hooks 0.12.9 → 0.12.14

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.
Files changed (58) hide show
  1. package/README.md +69 -6
  2. package/bin/hooks/stop-review.js +1235 -0
  3. package/bin/hooks-mcp.js +298 -85
  4. package/bin/index.js +3309 -1086
  5. package/bin/native-readiness-entry.js +5 -1
  6. package/bin/native-safety-entry.js +27 -25
  7. package/bin/native-safety-worker.cjs +27 -25
  8. package/bin/serve.js +1362 -70
  9. package/dist/db/remote-storage.d.ts +7 -1
  10. package/dist/index.d.ts +4 -1
  11. package/dist/index.js +1665 -257
  12. package/dist/lib/codex-safety-check.d.ts +1 -1
  13. package/dist/lib/hosted-registry.d.ts +70 -0
  14. package/dist/lib/legacy-registry-artifact.d.ts +23 -0
  15. package/dist/lib/manifest.d.ts +7 -0
  16. package/dist/lib/native-safety.d.ts +1 -0
  17. package/dist/lib/native-target.d.ts +7 -0
  18. package/dist/lib/opencode-stop-plugin.d.ts +55 -0
  19. package/dist/lib/registry-artifact.d.ts +36 -0
  20. package/dist/lib/registry.d.ts +4 -0
  21. package/dist/lib/stop-review-context.d.ts +12 -0
  22. package/dist/lib/store.d.ts +4 -0
  23. package/dist/lib/sumi-stop-plugin.d.ts +129 -0
  24. package/dist/lib/sync.d.ts +10 -0
  25. package/dist/lib/transport.d.ts +1 -1
  26. package/dist/native-readiness.d.ts +1 -1
  27. package/dist/native-readiness.js +5 -1
  28. package/dist/openapi.d.ts +160 -16
  29. package/dist/opencode-stop-plugin.js +384 -0
  30. package/dist/registry-auth.d.ts +5 -0
  31. package/dist/registry-http.d.ts +4 -0
  32. package/dist/sdk/generated.d.ts +32 -12
  33. package/dist/sdk/index.d.ts +28 -5
  34. package/dist/sdk/index.js +49 -24
  35. package/dist/sdk/registry-client.d.ts +1 -1
  36. package/dist/serve.d.ts +4 -4
  37. package/dist/storage.js +33 -2
  38. package/dist/sumi-stop-plugin.js +380 -0
  39. package/hooks/hook-scanoutput/src/hook.ts +33 -3
  40. package/hooks/hook-stop-review/README.md +109 -0
  41. package/hooks/hook-stop-review/manifest.json +10 -0
  42. package/hooks/hook-stop-review/package.json +11 -0
  43. package/hooks/hook-stop-review/src/hook.ts +59 -0
  44. package/hooks/hook-stop-review/src/index.ts +3 -0
  45. package/hooks/hook-stop-review/src/jev.ts +121 -0
  46. package/hooks/hook-stop-review/src/native.ts +246 -0
  47. package/hooks/hook-stop-review/src/policy.ts +145 -0
  48. package/hooks/hook-stop-review/src/runtime.ts +309 -0
  49. package/hooks/hook-stop-review/src/types.ts +121 -0
  50. package/hooks/hook-trash-guard/src/hook.ts +96 -0
  51. package/hooks/hook-workspace-repos-guard/src/hook.ts +231 -3
  52. package/hooks/local-executors.ts +841 -0
  53. package/package.json +22 -4
  54. package/scripts/build-bundled-hooks.ts +40 -0
  55. package/scripts/validate-bundled-hooks.ts +78 -0
  56. package/scripts/validate-opencode-stop-plugin.ts +42 -0
  57. package/scripts/validate-package.ts +9 -0
  58. 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
- **Registry server.** `hooks serve` exposes the local store over HTTP — catalog, artifacts, and the published lock:
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 serve --port 39428 # publish key resolves from the @hasna/contracts chain per request
497
- # GET /health, GET /api/v1/catalog, GET /api/v1/hooks/:name/:version,
498
- # PUT /api/v1/hooks (publish, requires the key), GET /api/v1/lock
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>/api/v1/catalog
533
- const lock = await registry.lock(); // GET <origin>/api/v1/lock
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