@holmes-lab/holmes-kit 0.34.0 → 0.35.1

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 (46) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +6 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/codex-oracle.js +36 -2
  5. package/dist/holmes/cli/doctor.d.ts +14 -1
  6. package/dist/holmes/cli/doctor.js +335 -71
  7. package/dist/holmes/cli/index.d.ts +1 -1
  8. package/dist/holmes/cli/index.js +38 -5
  9. package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
  10. package/dist/holmes/cli/runtime-binding-approval.js +102 -0
  11. package/dist/holmes/cli/runtime-binding.d.ts +29 -0
  12. package/dist/holmes/cli/runtime-binding.js +570 -0
  13. package/dist/holmes/governance/approval-queue.d.ts +2 -0
  14. package/dist/holmes/governance/approval-queue.js +11 -4
  15. package/dist/holmes/guardrail/impact-gate.js +90 -5
  16. package/dist/holmes/guardrail/linear-match.js +8 -1
  17. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -0
  18. package/dist/holmes/guardrail/risk-classifier.js +68 -23
  19. package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
  20. package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
  21. package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
  22. package/dist/holmes/guardrail/shell-syntax.js +489 -0
  23. package/dist/holmes/guardrail/shell-words.d.ts +2 -18
  24. package/dist/holmes/guardrail/shell-words.js +67 -442
  25. package/dist/holmes/guardrail/write-target.d.ts +54 -0
  26. package/dist/holmes/guardrail/write-target.js +327 -1
  27. package/dist/holmes/hooks/pre-tool-use.d.ts +12 -0
  28. package/dist/holmes/hooks/pre-tool-use.js +377 -66
  29. package/dist/holmes/mcp/handlers/maintenance-analysis.js +4 -2
  30. package/dist/holmes/mcp/handlers/test-execution.js +6 -2
  31. package/dist/holmes/mcp/handlers.d.ts +9 -1
  32. package/dist/holmes/mcp/handlers.js +6 -4
  33. package/dist/holmes/mcp/maintenance-evidence.d.ts +16 -1
  34. package/dist/holmes/mcp/maintenance-evidence.js +29 -3
  35. package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
  36. package/dist/holmes/mcp/operator-recovery.js +63 -0
  37. package/dist/holmes/rtm/test-scope.d.ts +9 -0
  38. package/dist/holmes/rtm/test-scope.js +284 -14
  39. package/dist/holmes/runtime/binding.d.ts +30 -0
  40. package/dist/holmes/runtime/binding.js +164 -0
  41. package/dist/holmes/runtime/dispatch.d.ts +9 -0
  42. package/dist/holmes/runtime/dispatch.js +169 -0
  43. package/dist/holmes/runtime/hook-process.d.ts +11 -0
  44. package/dist/holmes/runtime/hook-process.js +130 -0
  45. package/docs/install-guide.md +65 -0
  46. package/package.json +1 -1
@@ -37,7 +37,7 @@ exports.isBrokenPipe = void 0;
37
37
  exports.packageRoot = packageRoot;
38
38
  exports.main = main;
39
39
  exports.installPipeGuard = installPipeGuard;
40
- // @implements A-SPEC-704, A-SPEC-709, A-SPEC-734
40
+ // @implements A-SPEC-704, A-SPEC-709, A-SPEC-734, A-SPEC-751, A-SPEC-752
41
41
  // @implements A-SPEC-549.2
42
42
  // @implements A-SPEC-591, A-SPEC-626
43
43
  const cli_execution_1 = require("./cli-execution");
@@ -56,7 +56,7 @@ const bounded_io_1 = require("../project/bounded-io");
56
56
  *
57
57
  * Commands:
58
58
  * init [--mode guardrail|governed] [--target dir] [--dry-run] [--remove] [--force] ...
59
- * doctor [--target dir] [--json]
59
+ * doctor [--target dir] [--registry file] [--json]
60
60
  * attest [--target dir] [--exclude a,b] [--json] [--badge] [--readme]
61
61
  */
62
62
  /**
@@ -78,10 +78,11 @@ function packageRoot() {
78
78
  * REQ-144's "cannot decide is not permission", applied to CLI arguments.
79
79
  */
80
80
  const KNOWN_FLAGS = {
81
+ 'runtime-binding': ['help', 'workspace', 'package', 'release-package', 'registry', 'dry-run', 'activate-hooks'],
81
82
  guidance: ['help', 'target', 'dry-run'],
82
83
  init: ['help', 'target', 'mode', 'specs-dir', 'settings', 'matcher', 'dry-run', 'no-mcp', 'remove', 'force', 'agent', 'mcp-launcher', 'autonomy', 'no-autonomy'],
83
84
  autonomy: ['help', 'target', 'for'],
84
- doctor: ['help', 'target', 'json', 'agent'],
85
+ doctor: ['help', 'target', 'json', 'agent', 'registry'],
85
86
  // @implements A-SPEC-702 — a statement, not a gate: how many source files trace to an approved spec.
86
87
  attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
87
88
  skills: ['help', 'target'],
@@ -193,6 +194,12 @@ function readApproval() {
193
194
  }
194
195
  const USAGE = `holmes-kit — deterministic ASE governance for a project
195
196
 
197
+ holmes-kit runtime-binding setup|status|remove --workspace <root> [--registry <file>]
198
+ setup --package <checkout> --release-package <install> [--dry-run]
199
+ Explicit operator runtime selection; preserves native hook trust and enable state.
200
+ --activate-hooks <claude,codex,antigravity|all> explicitly restores selected Holmes hooks;
201
+ native trust and global disable switches still require native review.
202
+
196
203
  holmes-kit init [flags] wire holmes-kit into a target project
197
204
  --mode guardrail|governed guardrail (default): gates only dangerous shell commands; safe on a
198
205
  spec-less project. governed: adds the No-Spec-No-Code Write/Edit gate
@@ -303,7 +310,7 @@ async function main(argv) {
303
310
  }
304
311
  // Positionals these commands do not take are refused, not dropped: `skills refresh <dir>`
305
312
  // silently wrote into CWD while the named target stayed stale (round-3 HIGH).
306
- const expected = cmd === 'guidance' ? ['check', 'refresh'] : cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
313
+ const expected = cmd === 'runtime-binding' ? ['setup', 'status', 'remove'] : cmd === 'guidance' ? ['check', 'refresh'] : cmd === 'skills' ? ['refresh'] : cmd === 'ledger' ? ['rechain']
307
314
  : cmd === 'semantic-key' ? ['set', 'unset', 'status']
308
315
  : cmd === 'autonomy' ? ['status', 'on', 'off'] : [];
309
316
  const unexpected = positionals.filter((p) => !expected.includes(p));
@@ -326,6 +333,27 @@ async function main(argv) {
326
333
  process.stdout.write(USAGE);
327
334
  return 0;
328
335
  }
336
+ if (cmd === 'runtime-binding') {
337
+ const { runRuntimeBinding, defaultRuntimeRegistry } = await Promise.resolve().then(() => __importStar(require('./runtime-binding')));
338
+ try {
339
+ if (positionals.length !== 1)
340
+ throw new Error('runtime-binding expects exactly one operation: setup, status or remove');
341
+ const activate = flags['activate-hooks'];
342
+ if (activate !== undefined && typeof activate !== 'string')
343
+ throw new Error('--activate-hooks requires harness selectors');
344
+ const report = runRuntimeBinding({ operation: positionals[0], workspace: typeof flags.workspace === 'string' ? flags.workspace : process.cwd(),
345
+ registryPath: typeof flags.registry === 'string' ? flags.registry : defaultRuntimeRegistry(),
346
+ packageRoot: typeof flags.package === 'string' ? flags.package : undefined,
347
+ releasePackageRoot: typeof flags['release-package'] === 'string' ? flags['release-package'] : undefined, dryRun: flags['dry-run'] === true, approval: readApproval(),
348
+ activateHooks: typeof activate === 'string' ? (activate === 'all' ? ['claude', 'codex', 'antigravity'] : activate.split(',')) : undefined });
349
+ process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
350
+ return 0;
351
+ }
352
+ catch (e) {
353
+ process.stderr.write(`${e.message}\n`);
354
+ return 1;
355
+ }
356
+ }
329
357
  if (cmd === '--version' || cmd === '-v') {
330
358
  let v = '0.0.0';
331
359
  try {
@@ -436,7 +464,12 @@ async function main(argv) {
436
464
  process.stderr.write(`unknown --agent ${String(flags.agent)} (${AGENTS.join('|')})\n\n${USAGE}`);
437
465
  return 2;
438
466
  }
439
- const checks = await (0, doctor_1.runDoctor)(packageRoot(), typeof flags.target === 'string' ? path.resolve(flags.target) : undefined, { agent: flags.agent });
467
+ if (flags.registry !== undefined && typeof flags.registry !== 'string') {
468
+ process.stderr.write('--registry requires a file path\n');
469
+ return 2;
470
+ }
471
+ const checks = await (0, doctor_1.runDoctor)(packageRoot(), typeof flags.target === 'string' ? path.resolve(flags.target) : undefined, { agent: flags.agent,
472
+ runtimeRegistryPath: typeof flags.registry === 'string' ? path.resolve(flags.registry) : undefined });
440
473
  process.stdout.write(flags.json ? (0, doctor_1.checksJson)(checks) + '\n' : (0, doctor_1.formatChecks)(checks) + '\n');
441
474
  return checks.some((c) => c.level === 'FAIL') ? 1 : 0;
442
475
  }
@@ -0,0 +1,7 @@
1
+ import type { Approval } from '../guardrail/risk-gate';
2
+ export declare function runtimePlanDigest(identity: unknown, changes: {
3
+ path: string;
4
+ before: string | null;
5
+ after: string;
6
+ }[]): string;
7
+ export declare function applyApprovedRuntimePlan(root: string, subject: string, envApproval: Approval | undefined, check: () => void, apply: () => void): void;
@@ -0,0 +1,102 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.runtimePlanDigest = runtimePlanDigest;
37
+ exports.applyApprovedRuntimePlan = applyApprovedRuntimePlan;
38
+ // @implements A-SPEC-752
39
+ const path = __importStar(require("node:path"));
40
+ const node_crypto_1 = require("node:crypto");
41
+ const risk_gate_1 = require("../guardrail/risk-gate");
42
+ const approval_grants_1 = require("../governance/approval-grants");
43
+ const approval_queue_1 = require("../governance/approval-queue");
44
+ const ledger_store_1 = require("../governance/ledger-store");
45
+ const provenance_chain_1 = require("../governance/provenance-chain");
46
+ const ledger_lock_1 = require("../governance/ledger-lock");
47
+ function runtimePlanDigest(identity, changes) {
48
+ const hash = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
49
+ const files = changes.map((c) => ({ path: c.path, before: c.before === null ? null : hash(c.before), after: hash(c.after) }))
50
+ .sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
51
+ return `sha256:${hash(JSON.stringify({ identity, files }))}`;
52
+ }
53
+ function applyApprovedRuntimePlan(root, subject, envApproval, check, apply) {
54
+ const ledgerDir = path.join(root, '.ax/ledger');
55
+ const ledger = new ledger_store_1.FileLedgerStore(ledgerDir);
56
+ // Official grants use request ids as nonces. A new plan, or retry after an attempted
57
+ // application, needs a distinct request identity; revoking never erases spent history.
58
+ let target = `${root}#runtime-plan=${subject}`;
59
+ for (let attempt = 1; ledger.isNonceConsumed((0, approval_queue_1.approvalRequestId)('governance-wiring', target)); attempt++) {
60
+ if (attempt > 1000)
61
+ throw new Error('Runtime plan recovery limit reached; inspect installation history');
62
+ target = `${root}#runtime-plan=${subject}:retry=${attempt}`;
63
+ }
64
+ const action = { kind: 'governance-wiring', target, subject };
65
+ const resolve = () => {
66
+ const now = new Date().toISOString();
67
+ if (envApproval && (0, risk_gate_1.approvalCovers)(envApproval, { kind: action.kind, target: root }, now))
68
+ return { approval: envApproval, source: 'env' };
69
+ const refused = new Set((0, approval_grants_1.refusedGrantReasons)(root, action, now).map((r) => r.nonce));
70
+ const approval = (0, approval_grants_1.readGrants)(root).grants.find((g) => g.subject === subject
71
+ && !refused.has(g.nonce) && (0, risk_gate_1.approvalCovers)(g, action, now));
72
+ return approval ? { approval, source: 'grant' } : undefined;
73
+ };
74
+ const request = () => {
75
+ const result = (0, approval_queue_1.enqueueApprovalRequestDetailed)(root, { ...action, risk: 'high',
76
+ why: `Review runtime-binding --dry-run for plan ${subject}; approve this exact wiring plan and retry the same command. Native trust is separate.` });
77
+ const id = (0, approval_queue_1.approvalRequestId)(action.kind, target);
78
+ if (result.reason !== 'written' && result.reason !== 'duplicate')
79
+ throw new Error(`Cannot queue governance-wiring approval: ${result.reason}; nothing installed`);
80
+ throw new Error(`governance-wiring approval required for plan ${subject}; request ${id}. In this workspace run holmes-kit approve --list, then holmes-kit approve --grant ${id} and retry the same runtime-binding command. If an old decision remains, revoke it and retry to request the current plan.`);
81
+ };
82
+ check();
83
+ if (!resolve())
84
+ request();
85
+ const file = (0, ledger_store_1.writerChainFile)(ledgerDir);
86
+ (0, ledger_lock_1.withLedgerLock)(file, () => {
87
+ check();
88
+ const resolved = resolve();
89
+ if (!resolved)
90
+ throw new Error('Runtime plan approval expired or changed before application; retry for a fresh request');
91
+ const nonce = resolved.approval.nonce;
92
+ if (nonce !== undefined) {
93
+ if (typeof nonce !== 'string' || !nonce.trim() || ledger.isNonceConsumed(nonce))
94
+ throw new Error('Runtime plan approval nonce is invalid or already consumed; obtain a fresh approval');
95
+ new provenance_chain_1.ProvenanceChain(file).appendInsideLock({ ts: new Date().toISOString(), actor: resolved.approval.actor,
96
+ kind: 'nonce-consumed', inputs: [(0, provenance_chain_1.nonceFingerprint)(nonce)], summary: `Authorized runtime wiring plan ${subject}` });
97
+ }
98
+ apply();
99
+ if (resolved.source === 'grant' && nonce)
100
+ (0, approval_grants_1.consumeGrantFile)(root, nonce);
101
+ });
102
+ }
@@ -0,0 +1,29 @@
1
+ import type { RuntimeHarness, RuntimeEntry } from '../runtime/binding';
2
+ import type { Approval } from '../guardrail/risk-gate';
3
+ export declare const defaultRuntimeRegistry: () => string;
4
+ export interface RuntimeBindingOptions {
5
+ operation: string;
6
+ workspace: string;
7
+ registryPath: string;
8
+ packageRoot?: string;
9
+ releasePackageRoot?: string;
10
+ dryRun: boolean;
11
+ home?: string;
12
+ installerPackageRoot?: string;
13
+ approval?: Approval;
14
+ activateHooks?: string[];
15
+ }
16
+ export declare function runtimeHookCommand(registryPath: string, harness: RuntimeHarness, entry: RuntimeEntry): string;
17
+ /**
18
+ * @implements A-SPEC-752.5 — what the receipt records about a file. Claude Code rewrites its own settings file (measured
19
+ * 2026-10-04: a model switch), so a whole-byte digest called an unrelated edit changed wiring and gave a reviewed plan
20
+ * another digest. For that file the receipt is about a view of the document; every other file is recorded whole.
21
+ * A list of keys to keep missed ones that switch Holmes off, so the view names what it drops (A-SPEC-752.6).
22
+ */
23
+ export declare function wiringViewOf(file: string, content: string): string;
24
+ export declare function runtimeBindingStatus(registryPath: string, workspace: string): {
25
+ selection: import("../runtime/binding").RuntimeSelection;
26
+ conflicts: string[];
27
+ activation: "unverified";
28
+ };
29
+ export declare function runRuntimeBinding(opts: RuntimeBindingOptions): unknown;