@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.
- package/CHANGELOG.md +89 -0
- package/README.md +6 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/codex-oracle.js +36 -2
- package/dist/holmes/cli/doctor.d.ts +14 -1
- package/dist/holmes/cli/doctor.js +335 -71
- package/dist/holmes/cli/index.d.ts +1 -1
- package/dist/holmes/cli/index.js +38 -5
- package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
- package/dist/holmes/cli/runtime-binding-approval.js +102 -0
- package/dist/holmes/cli/runtime-binding.d.ts +29 -0
- package/dist/holmes/cli/runtime-binding.js +570 -0
- package/dist/holmes/governance/approval-queue.d.ts +2 -0
- package/dist/holmes/governance/approval-queue.js +11 -4
- package/dist/holmes/guardrail/impact-gate.js +90 -5
- package/dist/holmes/guardrail/linear-match.js +8 -1
- package/dist/holmes/guardrail/risk-classifier.d.ts +6 -0
- package/dist/holmes/guardrail/risk-classifier.js +68 -23
- package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
- package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
- package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
- package/dist/holmes/guardrail/shell-syntax.js +489 -0
- package/dist/holmes/guardrail/shell-words.d.ts +2 -18
- package/dist/holmes/guardrail/shell-words.js +67 -442
- package/dist/holmes/guardrail/write-target.d.ts +54 -0
- package/dist/holmes/guardrail/write-target.js +327 -1
- package/dist/holmes/hooks/pre-tool-use.d.ts +12 -0
- package/dist/holmes/hooks/pre-tool-use.js +377 -66
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +4 -2
- package/dist/holmes/mcp/handlers/test-execution.js +6 -2
- package/dist/holmes/mcp/handlers.d.ts +9 -1
- package/dist/holmes/mcp/handlers.js +6 -4
- package/dist/holmes/mcp/maintenance-evidence.d.ts +16 -1
- package/dist/holmes/mcp/maintenance-evidence.js +29 -3
- package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
- package/dist/holmes/mcp/operator-recovery.js +63 -0
- package/dist/holmes/rtm/test-scope.d.ts +9 -0
- package/dist/holmes/rtm/test-scope.js +284 -14
- package/dist/holmes/runtime/binding.d.ts +30 -0
- package/dist/holmes/runtime/binding.js +164 -0
- package/dist/holmes/runtime/dispatch.d.ts +9 -0
- package/dist/holmes/runtime/dispatch.js +169 -0
- package/dist/holmes/runtime/hook-process.d.ts +11 -0
- package/dist/holmes/runtime/hook-process.js +130 -0
- package/docs/install-guide.md +65 -0
- package/package.json +1 -1
package/dist/holmes/cli/index.js
CHANGED
|
@@ -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
|
-
|
|
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;
|