@holmes-lab/holmes-kit 0.41.1 → 0.41.3
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 +40 -0
- package/README.md +29 -5
- package/bin/holmes-mcp.js +36 -1
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/claude-switches.d.ts +9 -0
- package/dist/holmes/cli/claude-switches.js +11 -8
- package/dist/holmes/cli/doctor.d.ts +7 -1
- package/dist/holmes/cli/doctor.js +63 -20
- package/dist/holmes/cli/holmes-hook-id.d.ts +9 -0
- package/dist/holmes/cli/holmes-hook-id.js +22 -0
- package/dist/holmes/cli/hook-failure-posture.d.ts +44 -0
- package/dist/holmes/cli/hook-failure-posture.js +65 -0
- package/dist/holmes/cli/index.js +3 -1
- package/dist/holmes/cli/init.d.ts +6 -0
- package/dist/holmes/cli/init.js +151 -3
- package/dist/holmes/cli/native-deps.d.ts +10 -4
- package/dist/holmes/cli/native-deps.js +30 -29
- package/dist/holmes/cli/release-history.d.ts +21 -0
- package/dist/holmes/cli/release-history.js +116 -0
- package/dist/holmes/cli/run-wiring.js +4 -2
- package/dist/holmes/cli/runtime-binding.d.ts +24 -0
- package/dist/holmes/cli/runtime-binding.js +67 -25
- package/dist/holmes/cli/settings-merge.d.ts +3 -2
- package/dist/holmes/cli/settings-merge.js +11 -9
- package/dist/holmes/config/config.d.ts +6 -0
- package/dist/holmes/config/config.js +23 -3
- package/dist/holmes/config/judgement-keys.d.ts +20 -0
- package/dist/holmes/config/judgement-keys.js +100 -0
- package/dist/holmes/config/project-caps.js +3 -2
- package/dist/holmes/governance/autonomous-shell.js +1 -1
- package/dist/holmes/governance/autonomy.d.ts +27 -1
- package/dist/holmes/governance/autonomy.js +126 -6
- package/dist/holmes/governance/wiring-receipt.d.ts +7 -0
- package/dist/holmes/governance/wiring-receipt.js +84 -0
- package/dist/holmes/guardrail/cli-root.d.ts +31 -0
- package/dist/holmes/guardrail/cli-root.js +261 -0
- package/dist/holmes/guardrail/command-traits.d.ts +2 -0
- package/dist/holmes/guardrail/command-traits.js +26 -1
- package/dist/holmes/guardrail/impact-gate.d.ts +17 -1
- package/dist/holmes/guardrail/impact-gate.js +44 -5
- package/dist/holmes/guardrail/outward-acts.js +10 -3
- package/dist/holmes/guardrail/package-manager-acts.d.ts +41 -0
- package/dist/holmes/guardrail/package-manager-acts.js +1298 -0
- package/dist/holmes/guardrail/refusal-codes.js +9 -1
- package/dist/holmes/guardrail/shell-syntax.d.ts +3 -0
- package/dist/holmes/guardrail/shell-syntax.js +7 -2
- package/dist/holmes/guardrail/write-target.d.ts +20 -0
- package/dist/holmes/guardrail/write-target.js +168 -2
- package/dist/holmes/hooks/pre-tool-use.d.ts +110 -3
- package/dist/holmes/hooks/pre-tool-use.js +1208 -60
- package/dist/holmes/mcp/evidence-artifact.d.ts +112 -0
- package/dist/holmes/mcp/evidence-artifact.js +2 -0
- package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +2 -1
- package/dist/holmes/mcp/handlers/maintenance-evidence.js +24 -2
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +1 -1
- package/dist/holmes/mcp/handlers/operator-inspection.js +2 -2
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +1 -1
- package/dist/holmes/mcp/handlers/requirement-triage.js +3 -2
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
- package/dist/holmes/mcp/handlers/spec-approval.js +6 -6
- package/dist/holmes/mcp/handlers/test-execution.d.ts +8 -0
- package/dist/holmes/mcp/handlers/test-execution.js +12 -6
- package/dist/holmes/mcp/handlers.d.ts +16 -7
- package/dist/holmes/mcp/maintenance-evidence.d.ts +11 -82
- package/dist/holmes/mcp/maintenance-evidence.js +57 -2
- package/dist/holmes/mcp/outcome-replay.d.ts +18 -0
- package/dist/holmes/mcp/outcome-replay.js +85 -0
- package/dist/holmes/mcp/outcome-windows.d.ts +136 -0
- package/dist/holmes/mcp/outcome-windows.js +236 -0
- package/dist/holmes/mcp/tool-schemas.js +1 -1
- package/dist/holmes/project/hook-specs-arg.d.ts +4 -0
- package/dist/holmes/project/hook-specs-arg.js +39 -0
- package/dist/holmes/project/install-layout.d.ts +11 -0
- package/dist/holmes/project/install-layout.js +109 -0
- package/dist/holmes/project/install-scripts-policy.d.ts +4 -1
- package/dist/holmes/project/install-scripts-policy.js +6 -3
- package/dist/holmes/project/native-recovery.d.ts +29 -0
- package/dist/holmes/project/native-recovery.js +62 -0
- package/dist/holmes/project/root.d.ts +6 -0
- package/dist/holmes/project/root.js +15 -3
- package/dist/holmes/project/wiring-receipt-format.d.ts +20 -0
- package/dist/holmes/project/wiring-receipt-format.js +42 -0
- package/dist/holmes/project/workspace-preflight.d.ts +9 -0
- package/dist/holmes/project/workspace-preflight.js +40 -1
- package/dist/holmes/review/classification-replay.d.ts +53 -0
- package/dist/holmes/review/classification-replay.js +78 -0
- package/dist/holmes/review/head-worktree.js +5 -4
- package/dist/holmes/review/run-provenance.js +3 -2
- package/dist/holmes/review/test-evidence.js +2 -2
- package/dist/holmes/review/test-outcomes.js +3 -1
- package/dist/holmes/rtm/graph-store.d.ts +5 -0
- package/dist/holmes/rtm/graph-store.js +12 -4
- package/dist/holmes/rtm/native-driver.d.ts +42 -0
- package/dist/holmes/rtm/native-driver.js +147 -0
- package/dist/holmes/rtm/rtm-graph.js +11 -2
- package/dist/holmes/runtime/dispatch.d.ts +6 -0
- package/dist/holmes/runtime/dispatch.js +51 -2
- package/dist/holmes/runtime/hook-process.d.ts +6 -0
- package/dist/holmes/runtime/hook-process.js +3 -3
- package/dist/holmes/update/semver-strict.d.ts +3 -0
- package/dist/holmes/update/semver-strict.js +58 -0
- package/docs/install-guide.md +8 -1
- package/package.json +3 -2
- package/playbooks/tdd-slice/PLAYBOOK.md +1 -1
- package/release-history.json +181 -0
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
-
// @implements A-SPEC-794.83, A-SPEC-794.57, A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4, A-SPEC-792.1, A-SPEC-792.8, A-SPEC-792.9, A-SPEC-794.42, A-SPEC-794.43, A-SPEC-794.45, A-SPEC-794.50
|
|
2
|
+
// @implements A-SPEC-772.35, A-SPEC-772.37, A-SPEC-794.83, A-SPEC-794.57, A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4, A-SPEC-792.1, A-SPEC-792.8, A-SPEC-792.9, A-SPEC-794.42, A-SPEC-794.43, A-SPEC-794.45, A-SPEC-794.50
|
|
3
3
|
/**
|
|
4
4
|
* @implements A-SPEC-777 — a refusal's kind, readable by a program. An orchestrator retries a `retryable` refusal,
|
|
5
5
|
* pauses for a person on `needs_hitl`, and changes its plan on `permanent`. The prose stays for people; the line
|
|
@@ -158,6 +158,14 @@ exports.REFUSAL_CODES = [
|
|
|
158
158
|
remediation: ['write project code through the Edit or Write tool, not the shell'],
|
|
159
159
|
test: /shell write to a project code file/i,
|
|
160
160
|
},
|
|
161
|
+
{
|
|
162
|
+
// @implements A-SPEC-772.35 §4 — the governed CLI line contract (accident prevention): ahead of target.unresolvable,
|
|
163
|
+
// whose "name a readable path" does not fit a line that is refused for what it holds
|
|
164
|
+
code: 'line.unread', class: 'permanent',
|
|
165
|
+
// A-SPEC-772.37 §5 — and a heredoc's way to be text
|
|
166
|
+
remediation: ['run the holmes-kit call as a plain line of its own', 'put text that only mentions holmes-kit in a file (`git commit -F <file>`, `gh pr create --body-file <file>`)', "or quote the heredoc's tag (`<<'EOF'`) and feed it to a read-only program, so its body is text"],
|
|
167
|
+
test: /only a line the gate reads whole/i,
|
|
168
|
+
},
|
|
161
169
|
{
|
|
162
170
|
code: 'target.unresolvable', class: 'permanent',
|
|
163
171
|
remediation: ['name the target by a readable absolute or project-relative path'],
|
|
@@ -16,5 +16,8 @@ export interface ParsedSegment {
|
|
|
16
16
|
overflow: boolean;
|
|
17
17
|
}
|
|
18
18
|
export declare function shellWords(src: string, env?: NodeJS.ProcessEnv, home?: string, pwd?: string | null, sourceRanges?: boolean): SimpleCommand & ParsedSegment;
|
|
19
|
+
/** @implements A-SPEC-794.150 — past 64 unwraps: a limit a reader can tell from any other error (still an Error). */
|
|
20
|
+
export declare class NestingTooDeep extends Error {
|
|
21
|
+
}
|
|
19
22
|
/** The words from the real command word on, behind wrappers, assignments and grouping keywords. */
|
|
20
23
|
export declare function commandOf(input: Word[]): Word[];
|
|
@@ -33,9 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.NestingTooDeep = void 0;
|
|
36
37
|
exports.shellWords = shellWords;
|
|
37
38
|
exports.commandOf = commandOf;
|
|
38
|
-
// @implements A-SPEC-753
|
|
39
|
+
// @implements A-SPEC-753, A-SPEC-794.150
|
|
39
40
|
// Policy-independent shell lexical primitives; legacy exports remain in shell-words.
|
|
40
41
|
const os = __importStar(require("node:os"));
|
|
41
42
|
const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*/;
|
|
@@ -442,6 +443,10 @@ const WRAPPERS_WITH_ARG = {
|
|
|
442
443
|
timeout: /^-[sk]$|^--(?:signal|kill-after)$/,
|
|
443
444
|
};
|
|
444
445
|
const PLAIN_WRAPPERS = new Set(['(', '{', '!', 'then', 'do', 'else', 'elif', 'if', 'while', 'until', 'time', 'exec', 'nohup', 'command', 'builtin', 'busybox', 'sudo', 'env', 'nice', 'stdbuf', 'timeout', 'doas', 'coproc']);
|
|
446
|
+
/** @implements A-SPEC-794.150 — past 64 unwraps: a limit a reader can tell from any other error (still an Error). */
|
|
447
|
+
class NestingTooDeep extends Error {
|
|
448
|
+
}
|
|
449
|
+
exports.NestingTooDeep = NestingTooDeep;
|
|
445
450
|
/** The words from the real command word on, behind wrappers, assignments and grouping keywords. */
|
|
446
451
|
function commandOf(input) {
|
|
447
452
|
let words = input;
|
|
@@ -449,7 +454,7 @@ function commandOf(input) {
|
|
|
449
454
|
let unwraps = 0;
|
|
450
455
|
while (i < words.length) {
|
|
451
456
|
if (unwraps > 64)
|
|
452
|
-
throw new
|
|
457
|
+
throw new NestingTooDeep('wrapper nesting too deep to judge');
|
|
453
458
|
const t = words[i].text;
|
|
454
459
|
if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(t)) {
|
|
455
460
|
i++;
|
|
@@ -324,6 +324,26 @@ export declare function axClimbBases(root: string, keys: AxCandidateKeys, text:
|
|
|
324
324
|
* archive or copy extracted into `~/.codex` can replace its hooks). The project root and the home
|
|
325
325
|
* directory are not wiring directories.
|
|
326
326
|
*/
|
|
327
|
+
/**
|
|
328
|
+
* @implements A-SPEC-476.9 — a hard link to a protected wiring file IS that file: the label of the wiring file whose
|
|
329
|
+
* device and inode `abs` shares, when `abs` is a regular file with more than one link. Measured 2026-11-15 (review A1):
|
|
330
|
+
* `ln ax.config.json docs/notes.md` then `cp off.json docs/notes.md` changed the original, because identity was judged
|
|
331
|
+
* by path. The candidates are the known names of every wiring directory (ax.config.json included).
|
|
332
|
+
*/
|
|
333
|
+
export declare function hardLinkKindOf(root: string | null, abs: string, env?: NodeJS.ProcessEnv, home?: string): string | null;
|
|
334
|
+
/**
|
|
335
|
+
* @implements A-SPEC-476.9 — the protected wiring file an `ln`/`link` command names (by identity, a hard link included),
|
|
336
|
+
* or null. Every argument that is not an option counts: a source makes another name a later write goes through, and a
|
|
337
|
+
* destination replaces the file. A plain `ln a b` over ordinary files is null.
|
|
338
|
+
*/
|
|
339
|
+
export declare function lnProtectedSource(root: string, base: string, command: string, env?: NodeJS.ProcessEnv, home?: string): string | null;
|
|
340
|
+
/**
|
|
341
|
+
* @implements A-SPEC-794.136 (A-H1) — the protected file a link-making command reaches, or null. A link made and written
|
|
342
|
+
* in one command cannot be seen by dev+ino when the gate judges, so the command's form decides: `ln`/`link`/`gln`, `cp`
|
|
343
|
+
* with `-l`, `--link` or a short cluster holding `l` (`-al`), and `rsync --link-dest`. Every operand counts — `-t`'s
|
|
344
|
+
* target and `--link-dest`'s directory included — and so does a directory that holds a protected file.
|
|
345
|
+
*/
|
|
346
|
+
export declare function linkMakingProtected(root: string, base: string, command: string, env?: NodeJS.ProcessEnv, home?: string): string | null;
|
|
327
347
|
export declare function wiringWriteKindOf(root: string, base: string, arg: string, env?: NodeJS.ProcessEnv, home?: string): string | null;
|
|
328
348
|
export declare function protectedKindOf(root: string, raw: string): string | null;
|
|
329
349
|
/**
|
|
@@ -61,6 +61,9 @@ exports.globPatternRe = globPatternRe;
|
|
|
61
61
|
exports.wiringDeletionKindOf = wiringDeletionKindOf;
|
|
62
62
|
exports.axCandidateKeys = axCandidateKeys;
|
|
63
63
|
exports.axClimbBases = axClimbBases;
|
|
64
|
+
exports.hardLinkKindOf = hardLinkKindOf;
|
|
65
|
+
exports.lnProtectedSource = lnProtectedSource;
|
|
66
|
+
exports.linkMakingProtected = linkMakingProtected;
|
|
64
67
|
exports.wiringWriteKindOf = wiringWriteKindOf;
|
|
65
68
|
exports.protectedKindOf = protectedKindOf;
|
|
66
69
|
exports.reduceCdWord = reduceCdWord;
|
|
@@ -73,7 +76,7 @@ exports.commandBases = commandBases;
|
|
|
73
76
|
exports.shellSegments = shellSegments;
|
|
74
77
|
exports.resolvesInside = resolvesInside;
|
|
75
78
|
exports.foreignMcpPaths = foreignMcpPaths;
|
|
76
|
-
// @implements A-SPEC-794.73, A-SPEC-728, A-SPEC-733, A-SPEC-163, A-SPEC-627, A-SPEC-768.2, A-SPEC-768.3, A-SPEC-163.8, A-SPEC-476.3, A-SPEC-476.7, A-SPEC-792.3, A-SPEC-794.38, A-SPEC-794.40
|
|
79
|
+
// @implements A-SPEC-794.136, A-SPEC-476.9, A-SPEC-794.73, A-SPEC-728, A-SPEC-733, A-SPEC-163, A-SPEC-627, A-SPEC-768.2, A-SPEC-768.3, A-SPEC-163.8, A-SPEC-476.3, A-SPEC-476.7, A-SPEC-792.3, A-SPEC-794.38, A-SPEC-794.40
|
|
77
80
|
const fs = __importStar(require("node:fs"));
|
|
78
81
|
const path = __importStar(require("node:path"));
|
|
79
82
|
const os = __importStar(require("node:os"));
|
|
@@ -1479,6 +1482,168 @@ function globCoversPrefix(P, T) {
|
|
|
1479
1482
|
* archive or copy extracted into `~/.codex` can replace its hooks). The project root and the home
|
|
1480
1483
|
* directory are not wiring directories.
|
|
1481
1484
|
*/
|
|
1485
|
+
/**
|
|
1486
|
+
* @implements A-SPEC-476.9 — a hard link to a protected wiring file IS that file: the label of the wiring file whose
|
|
1487
|
+
* device and inode `abs` shares, when `abs` is a regular file with more than one link. Measured 2026-11-15 (review A1):
|
|
1488
|
+
* `ln ax.config.json docs/notes.md` then `cp off.json docs/notes.md` changed the original, because identity was judged
|
|
1489
|
+
* by path. The candidates are the known names of every wiring directory (ax.config.json included).
|
|
1490
|
+
*/
|
|
1491
|
+
function hardLinkKindOf(root, abs, env = process.env, home = os.homedir()) {
|
|
1492
|
+
let st;
|
|
1493
|
+
try {
|
|
1494
|
+
st = fs.statSync(abs, { throwIfNoEntry: false });
|
|
1495
|
+
}
|
|
1496
|
+
catch {
|
|
1497
|
+
return null;
|
|
1498
|
+
} // [no-substitution: unreadable → not judged here; the path rules still apply]
|
|
1499
|
+
if (st === undefined || !st.isFile() || st.nlink < 2)
|
|
1500
|
+
return null;
|
|
1501
|
+
for (const w of wiringDirsWithCaps(root, env, home)) {
|
|
1502
|
+
for (const name of w.known) {
|
|
1503
|
+
let c;
|
|
1504
|
+
try {
|
|
1505
|
+
c = fs.statSync(path.join(w.dir, name), { throwIfNoEntry: false });
|
|
1506
|
+
}
|
|
1507
|
+
catch {
|
|
1508
|
+
c = undefined;
|
|
1509
|
+
}
|
|
1510
|
+
if (c !== undefined && c.isFile() && c.dev === st.dev && c.ino === st.ino)
|
|
1511
|
+
return `${w.label(name)} (through a hard link)`;
|
|
1512
|
+
}
|
|
1513
|
+
}
|
|
1514
|
+
// @implements A-SPEC-794.136 (A-M1) — and the root manifests that can name the governing holmes-kit
|
|
1515
|
+
if (root !== null) {
|
|
1516
|
+
for (const name of ['package.json', ...require('./package-manager-acts').LOCKFILES]) {
|
|
1517
|
+
let c;
|
|
1518
|
+
try {
|
|
1519
|
+
c = fs.statSync(path.join(root, name), { throwIfNoEntry: false });
|
|
1520
|
+
}
|
|
1521
|
+
catch {
|
|
1522
|
+
c = undefined;
|
|
1523
|
+
}
|
|
1524
|
+
if (c !== undefined && c.isFile() && c.dev === st.dev && c.ino === st.ino)
|
|
1525
|
+
return `${name} (a manifest, through a hard link)`;
|
|
1526
|
+
}
|
|
1527
|
+
}
|
|
1528
|
+
return null;
|
|
1529
|
+
}
|
|
1530
|
+
/**
|
|
1531
|
+
* @implements A-SPEC-476.9 — the protected wiring file an `ln`/`link` command names (by identity, a hard link included),
|
|
1532
|
+
* or null. Every argument that is not an option counts: a source makes another name a later write goes through, and a
|
|
1533
|
+
* destination replaces the file. A plain `ln a b` over ordinary files is null.
|
|
1534
|
+
*/
|
|
1535
|
+
function lnProtectedSource(root, base, command, env = process.env, home = os.homedir()) {
|
|
1536
|
+
return linkMakingProtected(root, base, command, env, home);
|
|
1537
|
+
}
|
|
1538
|
+
/**
|
|
1539
|
+
* @implements A-SPEC-794.136 (A-H1) — the protected file a link-making command reaches, or null. A link made and written
|
|
1540
|
+
* in one command cannot be seen by dev+ino when the gate judges, so the command's form decides: `ln`/`link`/`gln`, `cp`
|
|
1541
|
+
* with `-l`, `--link` or a short cluster holding `l` (`-al`), and `rsync --link-dest`. Every operand counts — `-t`'s
|
|
1542
|
+
* target and `--link-dest`'s directory included — and so does a directory that holds a protected file.
|
|
1543
|
+
*/
|
|
1544
|
+
function linkMakingProtected(root, base, command, env = process.env, home = os.homedir()) {
|
|
1545
|
+
if (!/\b(?:ln|link|gln|cp|gcp|rsync)\b/.test(command))
|
|
1546
|
+
return null;
|
|
1547
|
+
let parsed;
|
|
1548
|
+
try {
|
|
1549
|
+
parsed = require('./shell-syntax').shellWords(command, env, home, base, true);
|
|
1550
|
+
}
|
|
1551
|
+
catch {
|
|
1552
|
+
return null;
|
|
1553
|
+
} // [no-substitution: unparsed → the wiring scan still judges the command]
|
|
1554
|
+
const knownFiles = () => wiringDirsWithCaps(root, env, home).flatMap((w) => w.known.map((n) => path.join(w.dir, n)));
|
|
1555
|
+
const holds = (arg) => {
|
|
1556
|
+
const kind = wiringWriteKindOf(root, base, arg, env, home);
|
|
1557
|
+
if (kind !== null)
|
|
1558
|
+
return kind;
|
|
1559
|
+
let abs;
|
|
1560
|
+
try {
|
|
1561
|
+
abs = pathFlavorFor(base, arg).resolve(base, arg);
|
|
1562
|
+
}
|
|
1563
|
+
catch {
|
|
1564
|
+
return null;
|
|
1565
|
+
}
|
|
1566
|
+
let st;
|
|
1567
|
+
try {
|
|
1568
|
+
st = fs.statSync(abs, { throwIfNoEntry: false });
|
|
1569
|
+
}
|
|
1570
|
+
catch {
|
|
1571
|
+
st = undefined;
|
|
1572
|
+
}
|
|
1573
|
+
if (st === undefined || !st.isDirectory())
|
|
1574
|
+
return null;
|
|
1575
|
+
const dir = (() => { try {
|
|
1576
|
+
return fs.realpathSync(abs);
|
|
1577
|
+
}
|
|
1578
|
+
catch {
|
|
1579
|
+
return abs;
|
|
1580
|
+
} })();
|
|
1581
|
+
const inside = knownFiles().find((f) => { const r = (() => { try {
|
|
1582
|
+
return fs.realpathSync(f);
|
|
1583
|
+
}
|
|
1584
|
+
catch {
|
|
1585
|
+
return f;
|
|
1586
|
+
} })(); return r.startsWith(dir + path.sep) && fs.existsSync(f); });
|
|
1587
|
+
return inside !== undefined ? `${path.relative(root, inside) || inside} (inside ${arg})` : null;
|
|
1588
|
+
};
|
|
1589
|
+
for (const one of parsed.commands) {
|
|
1590
|
+
let at = 0;
|
|
1591
|
+
while (at < one.words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(one.words[at].text))
|
|
1592
|
+
at++;
|
|
1593
|
+
const head = (one.words[at]?.text ?? '').replace(/\\/g, '/').split('/').pop() ?? '';
|
|
1594
|
+
const args = one.words.slice(at + 1).map((w) => w.text);
|
|
1595
|
+
const linking = head === 'ln' || head === 'link' || head === 'gln'
|
|
1596
|
+
|| ((head === 'cp' || head === 'gcp') && args.some((a) => a === '--link' || /^-[A-Za-z]*l[A-Za-z]*$/.test(a)))
|
|
1597
|
+
|| (head === 'rsync' && args.some((a) => a.startsWith('--link-dest')));
|
|
1598
|
+
if (!linking)
|
|
1599
|
+
continue;
|
|
1600
|
+
let options = true;
|
|
1601
|
+
for (let i = 0; i < args.length; i++) {
|
|
1602
|
+
const a = args[i];
|
|
1603
|
+
if (options && a === '--') {
|
|
1604
|
+
options = false;
|
|
1605
|
+
continue;
|
|
1606
|
+
}
|
|
1607
|
+
if (options && a.startsWith('--link-dest')) {
|
|
1608
|
+
const v = a.includes('=') ? a.slice(a.indexOf('=') + 1) : args[++i];
|
|
1609
|
+
const k = v === undefined ? null : holds(v);
|
|
1610
|
+
if (k !== null)
|
|
1611
|
+
return k;
|
|
1612
|
+
continue;
|
|
1613
|
+
}
|
|
1614
|
+
if (options && (a === '-t' || a === '--target-directory')) {
|
|
1615
|
+
const v = args[++i];
|
|
1616
|
+
const k = v === undefined ? null : holds(v);
|
|
1617
|
+
if (k !== null)
|
|
1618
|
+
return k;
|
|
1619
|
+
continue;
|
|
1620
|
+
}
|
|
1621
|
+
if (options && a.startsWith('--target-directory=')) {
|
|
1622
|
+
const k = holds(a.slice(a.indexOf('=') + 1));
|
|
1623
|
+
if (k !== null)
|
|
1624
|
+
return k;
|
|
1625
|
+
continue;
|
|
1626
|
+
}
|
|
1627
|
+
if (options && a.startsWith('-'))
|
|
1628
|
+
continue;
|
|
1629
|
+
const k = holds(a);
|
|
1630
|
+
if (k !== null)
|
|
1631
|
+
return k;
|
|
1632
|
+
}
|
|
1633
|
+
}
|
|
1634
|
+
return null;
|
|
1635
|
+
}
|
|
1636
|
+
/** The wiring directories with the caps file always in (a hard link is judged even while the caps act is set aside). */
|
|
1637
|
+
function wiringDirsWithCaps(root, env, home) {
|
|
1638
|
+
const was = capsOutOfScope;
|
|
1639
|
+
capsOutOfScope = false;
|
|
1640
|
+
try {
|
|
1641
|
+
return wiringDirs(root, env, home);
|
|
1642
|
+
}
|
|
1643
|
+
finally {
|
|
1644
|
+
capsOutOfScope = was;
|
|
1645
|
+
}
|
|
1646
|
+
}
|
|
1482
1647
|
function wiringWriteKindOf(root, base, arg, env = process.env, home = os.homedir()) {
|
|
1483
1648
|
const s = expandHomeSpelling(arg, env, home);
|
|
1484
1649
|
if (s === null || s === '' || /[*?[]/.test(s))
|
|
@@ -1514,7 +1679,8 @@ function wiringWriteKindOf(root, base, arg, env = process.env, home = os.homedir
|
|
|
1514
1679
|
return w.label(rest); // round 12
|
|
1515
1680
|
}
|
|
1516
1681
|
}
|
|
1517
|
-
|
|
1682
|
+
// @implements A-SPEC-476.9 — no wiring path: the target may still be a hard link to a wiring file
|
|
1683
|
+
return hardLinkKindOf(root, pathFlavorFor(base, s).resolve(base, s), env, home);
|
|
1518
1684
|
}
|
|
1519
1685
|
function protectedKindOf(root, raw) {
|
|
1520
1686
|
// @implements A-SPEC-220.2
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { Spec } from '../spec/spec-parser';
|
|
2
2
|
import { PatchTarget } from '../guardrail/write-target';
|
|
3
|
+
import { type Word } from '../guardrail/shell-syntax';
|
|
3
4
|
import { Approval } from '../guardrail/risk-gate';
|
|
4
5
|
import { GrantSettlement, type GrantSettlementPending, type GrantSettlementResult } from '../governance/approval-grants';
|
|
5
6
|
import { RiskAction, RiskAssessment, RmSignal, StagedStoreSignal } from '../guardrail/risk-types';
|
|
@@ -66,11 +67,111 @@ export type ReferenceInput = 'git' | 'package' | 'runtime';
|
|
|
66
67
|
* walk each (the hook's 2-second bound on a 120 KB command; measured 7.4 s before this).
|
|
67
68
|
*/
|
|
68
69
|
export declare function referenceInputJudge(projectRoot: string, home?: string): (written: string) => ReferenceInput | null;
|
|
69
|
-
|
|
70
|
+
/**
|
|
71
|
+
* What the root rule needs from the hook: where the command runs, which package governs, and the environment; and, for a
|
|
72
|
+
* nested command (a substitution, a `sh -c` string), whether the line before it moved the directory or assigned PATH.
|
|
73
|
+
*/
|
|
74
|
+
export interface GovernedCliContext {
|
|
75
|
+
cwd: string;
|
|
76
|
+
governingRoot: string;
|
|
77
|
+
env: NodeJS.ProcessEnv;
|
|
78
|
+
cdBefore?: boolean;
|
|
79
|
+
pathAssigned?: boolean;
|
|
80
|
+
/** A-SPEC-772.31 — a cd before this nested command went somewhere computed: no recovery command names a place. */
|
|
81
|
+
cdUnknown?: boolean;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* One verdict of the governed CLI rules (A-SPEC-772.30): `rule` says which rule gave it. `root` (772.23/772.28: init or
|
|
85
|
+
* upgrade from another copy, or one the gate cannot resolve) is approval-able and names the self-recovery command (null
|
|
86
|
+
* when the cd before it went somewhere computed); `option` (772.15/772.16) and `line` (the line cannot be read) are not.
|
|
87
|
+
*/
|
|
88
|
+
export type GovernedCliResult = ({
|
|
70
89
|
act: string;
|
|
71
90
|
} | {
|
|
72
91
|
unjudged: string;
|
|
73
|
-
}
|
|
92
|
+
}) & {
|
|
93
|
+
head: string;
|
|
94
|
+
rule: 'root' | 'option' | 'line';
|
|
95
|
+
root?: true;
|
|
96
|
+
recovery?: string | null;
|
|
97
|
+
/** A-SPEC-772.34 — the line contract refused it: returned at once, nothing to approve. */
|
|
98
|
+
contract?: true;
|
|
99
|
+
};
|
|
100
|
+
/**
|
|
101
|
+
* @implements A-SPEC-772.30 — a word for the shell the Bash tool runs (sh; Git Bash on Windows): bare when it holds only
|
|
102
|
+
* characters no shell reads specially, else single-quoted with each `'` as `'\''`. One function for every word of the
|
|
103
|
+
* self-recovery command — a root with a space, a `C:\…` root (backslashes kept inside single quotes) and an argument that
|
|
104
|
+
* held quotes come back as the same words (review of 772.28, H-2: the recovery command broke on each).
|
|
105
|
+
*/
|
|
106
|
+
export declare function shellWord(word: string): string;
|
|
107
|
+
/**
|
|
108
|
+
* @implements A-SPEC-772.34 §3 — the reader does not know heredocs (a body's lines became commands): each unquoted
|
|
109
|
+
* `<<TAG`/`<<-TAG` body is taken out of the text, and kept with the line that opened it.
|
|
110
|
+
*/
|
|
111
|
+
export type HeredocBody = {
|
|
112
|
+
opener: string;
|
|
113
|
+
body: string;
|
|
114
|
+
receiver: string;
|
|
115
|
+
expands: boolean;
|
|
116
|
+
tag: string;
|
|
117
|
+
at: number;
|
|
118
|
+
};
|
|
119
|
+
export declare function stripHeredocBodies(command: string): {
|
|
120
|
+
text: string;
|
|
121
|
+
bodies: HeredocBody[];
|
|
122
|
+
};
|
|
123
|
+
/**
|
|
124
|
+
* @implements A-SPEC-772.37 — one simple command per stage in every context (the top level, `$(…)`, backticks, `<(…)`,
|
|
125
|
+
* `>(…)`): its pipeline, its place in it, and the stage whose words hold its context. `;`, newline, `&&`, `||` and a lone
|
|
126
|
+
* `&` end a stage; `|` and `|&` join stages; the `&` of a redirection does not. `$((…))` is arithmetic, not a context.
|
|
127
|
+
*/
|
|
128
|
+
export type Stage = {
|
|
129
|
+
start: number;
|
|
130
|
+
end: number;
|
|
131
|
+
text: string;
|
|
132
|
+
pipe: number;
|
|
133
|
+
idx: number;
|
|
134
|
+
parent: number;
|
|
135
|
+
};
|
|
136
|
+
export declare function shellStages(src: string): Stage[];
|
|
137
|
+
/**
|
|
138
|
+
* @implements A-SPEC-772.37 — what the line runs, read once: the stages, which of them reach a code reader (itself, a later
|
|
139
|
+
* stage of its pipeline, or the stage that holds its context), which heredoc bodies are text, the words a reader receives,
|
|
140
|
+
* and the substitutions an unquoted tag's body runs.
|
|
141
|
+
*/
|
|
142
|
+
export type LineFlow = {
|
|
143
|
+
textBody: (b: HeredocBody) => boolean;
|
|
144
|
+
readerOf: (b: HeredocBody) => string | null;
|
|
145
|
+
readerWords: string[];
|
|
146
|
+
bodyRuns: string[];
|
|
147
|
+
};
|
|
148
|
+
export declare function lineFlow(text: string, bodies: readonly HeredocBody[]): LineFlow;
|
|
149
|
+
/**
|
|
150
|
+
* @implements A-SPEC-772.33 — the governed CLI line contract (owner decision 11/17, after the same defect recurred in
|
|
151
|
+
* 772.30, 772.31 and 772.32): null when the reader understood the whole line — every simple command starts with a word
|
|
152
|
+
* the allow list names (A-SPEC-772.33 §3) and the text holds no construct the reader drops — else the construct's name.
|
|
153
|
+
*/
|
|
154
|
+
export declare function unreadConstruct(command: string, parsed: {
|
|
155
|
+
commands: Array<{
|
|
156
|
+
words: Word[];
|
|
157
|
+
}>;
|
|
158
|
+
}, bodies?: readonly HeredocBody[], flow?: LineFlow): string | null;
|
|
159
|
+
/** The first verdict, as before 772.30 (callers that judge one verdict at a time). */
|
|
160
|
+
export declare function governedCliAct(command: string, depth?: number, ctx?: GovernedCliContext): GovernedCliResult | null;
|
|
161
|
+
/**
|
|
162
|
+
* @implements A-SPEC-772.30 — every verdict on the line, in order (review of 772.28, H-1: the first verdict alone let a
|
|
163
|
+
* root-rule approval for `node <old>/bin/holmes-kit.js init --force` lift the 772.15 option rule too; the hook combines
|
|
164
|
+
* them, and an approval lifts root verdicts only).
|
|
165
|
+
*/
|
|
166
|
+
export declare function governedCliActs(command: string, depth?: number, ctx?: GovernedCliContext): GovernedCliResult[];
|
|
167
|
+
/**
|
|
168
|
+
* @implements A-SPEC-772.30 — the command that runs `head` from the governing install, every word serialized for sh. After
|
|
169
|
+
* a cd, `dir` is where it moved: init's `--target` is named absolute — added when absent, a relative one made absolute
|
|
170
|
+
* against `dir`; a null `dir` (a cd to a computed place) leaves no recovery command. Without a cd (`undefined`) the words
|
|
171
|
+
* are kept as given (the recovery runs where the refused command would have).
|
|
172
|
+
*/
|
|
173
|
+
/** @implements A-SPEC-772.32 — the approval target of the root rule: a request of its own, apart from the command's. */
|
|
174
|
+
export declare const ROOT_RULE_TARGET: (command: string) => string;
|
|
74
175
|
/**
|
|
75
176
|
* @implements A-SPEC-794.96 (S2, S3) — a `git commit` (its staged principle 7 changes; with -a, its tracked ones too) and a
|
|
76
177
|
* build command from one table (npm, pnpm, yarn `run build` or `build`; tsc; npx tsc) are judged against the working
|
|
@@ -357,10 +458,16 @@ export declare function decideOnGateError(opts: {
|
|
|
357
458
|
export declare function isGovernedProject(specsDir: string, opts?: {
|
|
358
459
|
configured?: boolean;
|
|
359
460
|
}): boolean;
|
|
461
|
+
/**
|
|
462
|
+
* @implements A-SPEC-728.4 — whether `stdout` with exit `code` is one valid PreToolUse answer: one JSON object whose
|
|
463
|
+
* hookSpecificOutput names PreToolUse, a decision that is absent or allow/deny/ask, and a code that is 2 exactly for a
|
|
464
|
+
* deny. Measured 2026-11-15 (Claude Code 2.1.325): a malformed answer with exit 0 passes the call, onFailure or not.
|
|
465
|
+
*/
|
|
466
|
+
export declare function validHookAnswer(stdout: string, code: number): boolean;
|
|
360
467
|
/**
|
|
361
468
|
* The whole error-path decision, assembled from an environment.
|
|
362
469
|
*
|
|
363
|
-
* @implements A-SPEC-144
|
|
470
|
+
* @implements A-SPEC-144, A-SPEC-728.5 (the head line restored here)
|
|
364
471
|
* Exported and env-injected so the WIRING is tested rather than trusted. Mutation testing found the
|
|
365
472
|
* gap: hardcoding `bypass: true` and inverting the governance check both left every test green,
|
|
366
473
|
* because the tests exercised the pure helpers directly and nothing exercised the code that reads
|