@holmes-lab/holmes-kit 0.41.2 → 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.
Files changed (103) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +28 -5
  3. package/bin/holmes-mcp.js +36 -1
  4. package/dist/.build-id +1 -1
  5. package/dist/holmes/cli/claude-switches.d.ts +9 -0
  6. package/dist/holmes/cli/claude-switches.js +11 -8
  7. package/dist/holmes/cli/doctor.d.ts +7 -1
  8. package/dist/holmes/cli/doctor.js +63 -20
  9. package/dist/holmes/cli/holmes-hook-id.d.ts +9 -0
  10. package/dist/holmes/cli/holmes-hook-id.js +22 -0
  11. package/dist/holmes/cli/hook-failure-posture.d.ts +44 -0
  12. package/dist/holmes/cli/hook-failure-posture.js +65 -0
  13. package/dist/holmes/cli/index.js +3 -1
  14. package/dist/holmes/cli/init.d.ts +6 -0
  15. package/dist/holmes/cli/init.js +151 -3
  16. package/dist/holmes/cli/native-deps.d.ts +10 -4
  17. package/dist/holmes/cli/native-deps.js +30 -29
  18. package/dist/holmes/cli/run-wiring.js +4 -2
  19. package/dist/holmes/cli/runtime-binding.d.ts +24 -0
  20. package/dist/holmes/cli/runtime-binding.js +67 -25
  21. package/dist/holmes/cli/settings-merge.d.ts +3 -2
  22. package/dist/holmes/cli/settings-merge.js +11 -9
  23. package/dist/holmes/config/config.d.ts +6 -0
  24. package/dist/holmes/config/config.js +23 -3
  25. package/dist/holmes/config/judgement-keys.d.ts +20 -0
  26. package/dist/holmes/config/judgement-keys.js +100 -0
  27. package/dist/holmes/config/project-caps.js +3 -2
  28. package/dist/holmes/governance/autonomous-shell.js +1 -1
  29. package/dist/holmes/governance/autonomy.d.ts +27 -1
  30. package/dist/holmes/governance/autonomy.js +126 -6
  31. package/dist/holmes/governance/wiring-receipt.d.ts +7 -0
  32. package/dist/holmes/governance/wiring-receipt.js +84 -0
  33. package/dist/holmes/guardrail/cli-root.d.ts +31 -0
  34. package/dist/holmes/guardrail/cli-root.js +261 -0
  35. package/dist/holmes/guardrail/command-traits.d.ts +2 -0
  36. package/dist/holmes/guardrail/command-traits.js +26 -1
  37. package/dist/holmes/guardrail/impact-gate.d.ts +17 -1
  38. package/dist/holmes/guardrail/impact-gate.js +44 -5
  39. package/dist/holmes/guardrail/outward-acts.js +10 -3
  40. package/dist/holmes/guardrail/package-manager-acts.d.ts +41 -0
  41. package/dist/holmes/guardrail/package-manager-acts.js +1298 -0
  42. package/dist/holmes/guardrail/refusal-codes.js +9 -1
  43. package/dist/holmes/guardrail/shell-syntax.d.ts +3 -0
  44. package/dist/holmes/guardrail/shell-syntax.js +7 -2
  45. package/dist/holmes/guardrail/write-target.d.ts +20 -0
  46. package/dist/holmes/guardrail/write-target.js +168 -2
  47. package/dist/holmes/hooks/pre-tool-use.d.ts +110 -3
  48. package/dist/holmes/hooks/pre-tool-use.js +1208 -60
  49. package/dist/holmes/mcp/evidence-artifact.d.ts +112 -0
  50. package/dist/holmes/mcp/evidence-artifact.js +2 -0
  51. package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +2 -1
  52. package/dist/holmes/mcp/handlers/maintenance-evidence.js +24 -2
  53. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +1 -1
  54. package/dist/holmes/mcp/handlers/operator-inspection.js +2 -2
  55. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +1 -1
  56. package/dist/holmes/mcp/handlers/requirement-triage.js +3 -2
  57. package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
  58. package/dist/holmes/mcp/handlers/spec-approval.js +6 -6
  59. package/dist/holmes/mcp/handlers/test-execution.d.ts +8 -0
  60. package/dist/holmes/mcp/handlers/test-execution.js +12 -6
  61. package/dist/holmes/mcp/handlers.d.ts +16 -7
  62. package/dist/holmes/mcp/maintenance-evidence.d.ts +11 -82
  63. package/dist/holmes/mcp/maintenance-evidence.js +57 -2
  64. package/dist/holmes/mcp/outcome-replay.d.ts +18 -0
  65. package/dist/holmes/mcp/outcome-replay.js +85 -0
  66. package/dist/holmes/mcp/outcome-windows.d.ts +136 -0
  67. package/dist/holmes/mcp/outcome-windows.js +236 -0
  68. package/dist/holmes/mcp/tool-schemas.js +1 -1
  69. package/dist/holmes/project/hook-specs-arg.d.ts +4 -0
  70. package/dist/holmes/project/hook-specs-arg.js +39 -0
  71. package/dist/holmes/project/install-layout.d.ts +11 -0
  72. package/dist/holmes/project/install-layout.js +109 -0
  73. package/dist/holmes/project/install-scripts-policy.d.ts +4 -1
  74. package/dist/holmes/project/install-scripts-policy.js +6 -3
  75. package/dist/holmes/project/native-recovery.d.ts +29 -0
  76. package/dist/holmes/project/native-recovery.js +62 -0
  77. package/dist/holmes/project/root.d.ts +6 -0
  78. package/dist/holmes/project/root.js +15 -3
  79. package/dist/holmes/project/wiring-receipt-format.d.ts +20 -0
  80. package/dist/holmes/project/wiring-receipt-format.js +42 -0
  81. package/dist/holmes/project/workspace-preflight.d.ts +9 -0
  82. package/dist/holmes/project/workspace-preflight.js +40 -1
  83. package/dist/holmes/review/classification-replay.d.ts +53 -0
  84. package/dist/holmes/review/classification-replay.js +78 -0
  85. package/dist/holmes/review/head-worktree.js +5 -4
  86. package/dist/holmes/review/run-provenance.js +3 -2
  87. package/dist/holmes/review/test-evidence.js +2 -2
  88. package/dist/holmes/review/test-outcomes.js +3 -1
  89. package/dist/holmes/rtm/graph-store.d.ts +5 -0
  90. package/dist/holmes/rtm/graph-store.js +12 -4
  91. package/dist/holmes/rtm/native-driver.d.ts +42 -0
  92. package/dist/holmes/rtm/native-driver.js +147 -0
  93. package/dist/holmes/rtm/rtm-graph.js +11 -2
  94. package/dist/holmes/runtime/dispatch.d.ts +6 -0
  95. package/dist/holmes/runtime/dispatch.js +51 -2
  96. package/dist/holmes/runtime/hook-process.d.ts +6 -0
  97. package/dist/holmes/runtime/hook-process.js +3 -3
  98. package/dist/holmes/update/semver-strict.d.ts +3 -0
  99. package/dist/holmes/update/semver-strict.js +58 -0
  100. package/docs/install-guide.md +8 -1
  101. package/package.json +1 -1
  102. package/playbooks/tdd-slice/PLAYBOOK.md +1 -1
  103. package/release-history.json +36 -1
@@ -49,6 +49,9 @@ exports.principle7Context = principle7Context;
49
49
  exports.principle7OpenersIn = principle7OpenersIn;
50
50
  exports.principle7OpenersFor = principle7OpenersFor;
51
51
  exports.principle7Verdict = principle7Verdict;
52
+ exports.receiptExcusable = receiptExcusable;
53
+ exports.excuseByReceipt = excuseByReceipt;
54
+ exports.receiptExcuseRows = receiptExcuseRows;
52
55
  exports.recordWindowBlobs = recordWindowBlobs;
53
56
  exports.principle7RefusalText = principle7RefusalText;
54
57
  exports.recordBaseline = recordBaseline;
@@ -71,7 +74,7 @@ exports.autonomyBanner = autonomyBanner;
71
74
  exports.autonomyMarkerShouldPrune = autonomyMarkerShouldPrune;
72
75
  exports.versionBumpKind = versionBumpKind;
73
76
  exports.releaseAutonomy = releaseAutonomy;
74
- // @implements A-SPEC-794.126, A-SPEC-794.113, A-SPEC-794.111, A-SPEC-794.110, A-SPEC-794.107, A-SPEC-794.106, A-SPEC-794.97, A-SPEC-794.96, A-SPEC-794.95, A-SPEC-794.94, A-SPEC-794.91, A-SPEC-794.88, A-SPEC-794.55, A-SPEC-552.3, A-SPEC-552.4,A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4, A-SPEC-532.7, A-SPEC-792.7, A-SPEC-794.47, A-SPEC-794.49
77
+ // @implements A-SPEC-772.31, A-SPEC-794.133, A-SPEC-794.131, A-SPEC-794.126, A-SPEC-794.113, A-SPEC-794.111, A-SPEC-794.110, A-SPEC-794.107, A-SPEC-794.106, A-SPEC-794.97, A-SPEC-794.96, A-SPEC-794.95, A-SPEC-794.94, A-SPEC-794.91, A-SPEC-794.88, A-SPEC-794.55, A-SPEC-552.3, A-SPEC-552.4,A-SPEC-532.1, A-SPEC-718, A-SPEC-532.3, A-SPEC-532.4, A-SPEC-532.7, A-SPEC-792.7, A-SPEC-794.47, A-SPEC-794.49
75
78
  // Whether a spec approval may be sealed AUTONOMOUSLY by the agent, or must still ask a human through
76
79
  // the MCP elicitation TUI. The governance chain (REQ→H→A→T→CPG + RTM + taint + phase gate) already
77
80
  // forces quality structurally, so a low/mid-risk spec self-approving under an explicitly-enabled
@@ -684,9 +687,9 @@ function principle7OpenersFor(root, specs, nowMs, rel) {
684
687
  return { openers: [], events: [], hours: 12 };
685
688
  } // [no-substitution: unreadable → no window is open, and the write is refused]
686
689
  }
687
- function principle7Verdict(root, specs, nowMs) {
690
+ function principle7Verdict(root, specs, nowMs, opts = {}) {
688
691
  openPlaybooksNow = null;
689
- return inJudgement(() => principle7VerdictOf(root, specs, nowMs));
692
+ return inJudgement(() => principle7VerdictOf(root, specs, nowMs, opts.home ?? os.homedir()));
690
693
  }
691
694
  /**
692
695
  * A-SPEC-794.113 — the playbooks a person's window names as open, as the last judgement of this process found them:
@@ -694,7 +697,46 @@ function principle7Verdict(root, specs, nowMs) {
694
697
  * when its window is open then. Nothing but a judgement sets it, and each judgement clears it first.
695
698
  */
696
699
  let openPlaybooksNow = null;
697
- function principle7VerdictOf(root, specs, nowMs) {
700
+ /**
701
+ * @implements A-SPEC-794.132 — whether `f` changed in the working tree alone: present in the baseline, the index and HEAD,
702
+ * all three equal, and no conflict entry. A missing key (a git read that failed or did not list the file) is never equal.
703
+ */
704
+ function receiptExcusable(f, atBase, atIndex, atHead) {
705
+ const b = atBase.get(f);
706
+ const i = atIndex.get(f);
707
+ const h = atHead.get(f);
708
+ if (b === undefined || i === undefined || h === undefined)
709
+ return false;
710
+ // A-SPEC-794.133 — defensive, unreachable today: a conflict entry never equals the baseline blob, so the equality below
711
+ // already refuses it. Kept so a change to how conflicts are spelled cannot open the excuse.
712
+ if (i.startsWith('conflict:'))
713
+ return false;
714
+ return b === i && b === h;
715
+ }
716
+ /**
717
+ * @implements A-SPEC-794.133 — the excuse step the verdict calls: a local-only file leaves `unopened` and `localOnly` only
718
+ * when its three git reads are present and equal (receiptExcusable) and the injected receipt check says its bytes are the
719
+ * receipt's. Returns the excused files. The maps are passed unchanged, so an empty read excuses nothing.
720
+ */
721
+ function excuseByReceipt(localOnly, unopened, atBase, atIndex, atHead, root, home, recordsExactly) {
722
+ const excused = [];
723
+ for (const f of [...localOnly]) {
724
+ if (!receiptExcusable(f, atBase, atIndex, atHead))
725
+ continue;
726
+ if (!recordsExactly(path.join(root, f), home))
727
+ continue;
728
+ excused.push(f);
729
+ const u = unopened.indexOf(f);
730
+ if (u >= 0)
731
+ unopened.splice(u, 1);
732
+ // defensive, unreachable today: every file in localOnly came from unopened and is in it
733
+ const l = localOnly.indexOf(f);
734
+ if (l >= 0)
735
+ localOnly.splice(l, 1);
736
+ }
737
+ return excused;
738
+ }
739
+ function principle7VerdictOf(root, specs, nowMs, home) {
698
740
  if (!isHolmesKitOwnRepo(root))
699
741
  return null;
700
742
  // A-SPEC-794.114 — before anything is read from the ledger (the fast path included): this writer's chain must be the
@@ -850,6 +892,24 @@ function principle7VerdictOf(root, specs, nowMs) {
850
892
  localOnly = [];
851
893
  } // [no-substitution: the list only shapes the refusal's text; the files stay unopened]
852
894
  }
895
+ // @implements A-SPEC-794.131 — a local-only file changed in the working tree alone (index and HEAD at the baseline) whose
896
+ // whole bytes are exactly what the runtime binding receipt recorded last for it is the binding's write, not an edit
897
+ const receiptOwned = [];
898
+ const receiptDigests = {};
899
+ if (localOnly.length > 0) {
900
+ // A-SPEC-794.132/133 — all three reads present and equal: a failed git read (an empty map) excuses nothing
901
+ // A-SPEC-772.31 — the digest each file matched is kept with the verdict: the audit row records what was judged
902
+ const { receiptMatchDigest } = require('./wiring-receipt');
903
+ const matched = new Map();
904
+ const records = (abs, h) => { const d = receiptMatchDigest(abs, h); if (d !== null)
905
+ matched.set(abs, d); return d !== null; };
906
+ receiptOwned.push(...excuseByReceipt(localOnly, unopened, atBase, atIndex, atHead, root, home, records));
907
+ for (const f of receiptOwned) {
908
+ const d = matched.get(path.join(root, f));
909
+ if (d !== undefined)
910
+ receiptDigests[f] = d;
911
+ }
912
+ }
853
913
  // A-SPEC-794.113 — the playbooks a person's window names now (the record anchors only these), and those among
854
914
  // them whose bytes are not the recorded reference's: seen by that window, whether or not they differ from the baseline
855
915
  // commit (review B, medium 1: a change another replica's window saw arrives equal to the commit and was never recorded)
@@ -889,7 +949,7 @@ function principle7VerdictOf(root, specs, nowMs) {
889
949
  }
890
950
  catch { /* [no-substitution: unreadable → no playbook is named open, so nothing is anchored] */ }
891
951
  openPlaybooksNow = { root, nowMs, files: openFiles };
892
- return { unopened, byWindow, base, ctx, headSeen, localOnly, playbooks };
952
+ return { unopened, byWindow, base, ctx, headSeen, localOnly, playbooks, receiptOwned, receiptDigests };
893
953
  }
894
954
  /**
895
955
  * The window-blob rows that still open a file after their window closed: those recorded after the latest baseline row,
@@ -932,7 +992,7 @@ function windowBlobsAfter(events) {
932
992
  return blobs;
933
993
  }
934
994
  function ownChainRows(root) {
935
- const out = { id: null, broken: false, baselines: [], windows: [] };
995
+ const out = { id: null, broken: false, baselines: [], windows: [], excuses: [] };
936
996
  const dir = path.join(root, '.ax', 'ledger');
937
997
  if (!fs.existsSync(dir))
938
998
  return out;
@@ -964,6 +1024,9 @@ function ownChainRows(root) {
964
1024
  if (blob)
965
1025
  out.windows.push({ seq, file: i[0], seal: (i.find((x) => x.startsWith('seal:')) ?? '').slice(5), blob: blob.slice(5), sha256: (i.find((x) => x.startsWith('sha256:')) ?? '').slice(7) || null });
966
1026
  }
1027
+ else if (e.kind === 'principle7-receipt-excused' && e.actor === 'holmes-kit' && i.length === 2 && i[1].startsWith('sha256:')) {
1028
+ out.excuses.push({ seq, file: i[0], sha256: i[1].slice(7) });
1029
+ }
967
1030
  }
968
1031
  out.baselines.sort((a, b) => a.seq - b.seq);
969
1032
  }
@@ -975,11 +1038,68 @@ function ownChainRows(root) {
975
1038
  /** The one choice of "the row before" (review A, L3): the highest sequence of this writer's chain. */
976
1039
  const latestOf = (rows) => (rows.length === 0 ? null : rows.reduce((a, b) => (b.seq > a.seq ? b : a)));
977
1040
  const latestWithDigests = (rows) => latestOf(rows.filter((r) => r.playbooks.length > 0));
1041
+ /**
1042
+ * @implements A-SPEC-794.132, A-SPEC-794.133 — the audit trace of a receipt excuse, written only where the judgement
1043
+ * passes (nothing left unopened) at Stop, commit and build. A row is written when this writer's latest row for the file
1044
+ * since its latest baseline does not already carry these bytes: the same excuse judged again writes nothing, an A to B to
1045
+ * A change writes the third excuse, and a re-baseline records the excuse again.
1046
+ */
1047
+ function recordReceiptExcuses(root, nowIso, v) {
1048
+ const owned = v.receiptOwned ?? [];
1049
+ if (owned.length === 0 || v.unopened.length > 0)
1050
+ return; // a refused judgement excused nothing that stands
1051
+ inJudgement(() => {
1052
+ try {
1053
+ const own = ownChainRows(root);
1054
+ // a chain this repository did not write takes no row (A-SPEC-794.114). A-SPEC-772.31 (review of 772.29, M3): said,
1055
+ // not silent — the excuse stands without its row
1056
+ if (own.broken) {
1057
+ process.stderr.write(`[Holmes-Kit] principle 7: ${owned.join(', ')} matched the runtime binding receipt and was let through, but no audit row was written — this repository's ledger chain is not one it wrote (A-SPEC-794.114, A-SPEC-772.31)\n`);
1058
+ return;
1059
+ }
1060
+ const since = latestOf(own.baselines)?.seq ?? -1;
1061
+ const last = new Map();
1062
+ const seqOf = new Map();
1063
+ for (const x of own.excuses) {
1064
+ if (x.seq <= since)
1065
+ continue;
1066
+ if ((seqOf.get(x.file) ?? -Infinity) < x.seq) {
1067
+ seqOf.set(x.file, x.seq);
1068
+ last.set(x.file, x.sha256);
1069
+ }
1070
+ }
1071
+ const { FileLedgerStore } = require('./ledger-store');
1072
+ const store = new FileLedgerStore(path.join(root, '.ax', 'ledger'));
1073
+ for (const row of receiptExcuseRows(owned, v.receiptDigests ?? {}, last)) {
1074
+ store.append({ ts: nowIso, actor: 'holmes-kit', kind: 'principle7-receipt-excused',
1075
+ summary: `${row.file} matched the runtime binding receipt byte for byte (local-only) and was not judged as a gate change`,
1076
+ inputs: [row.file, `sha256:${row.sha256}`], rationale: 'principle 7 runtime binding receipt (A-SPEC-794.131, A-SPEC-794.132, A-SPEC-794.133, A-SPEC-772.31)' });
1077
+ }
1078
+ }
1079
+ catch { /* [no-substitution: an unwritten audit row does not change the verdict already given] */ }
1080
+ });
1081
+ }
1082
+ /**
1083
+ * @implements A-SPEC-772.31 — the audit rows for the excused files: the digest each matched when judged (review of 772.29,
1084
+ * M2: the row was the bytes read at record time, so a change in between wrote a match that was never judged), skipping a
1085
+ * file whose latest row already holds it. A file with no judged digest takes no row. Reads nothing.
1086
+ */
1087
+ function receiptExcuseRows(owned, judged, last) {
1088
+ const out = [];
1089
+ for (const file of owned) {
1090
+ const sha256 = judged[file];
1091
+ if (sha256 === undefined || last.get(file) === sha256)
1092
+ continue;
1093
+ out.push({ file, sha256 });
1094
+ }
1095
+ return out;
1096
+ }
978
1097
  /**
979
1098
  * @implements A-SPEC-794.97 — the content a window saw: one `principle7-window-blob` row per (file, spec, seal, blob) not
980
1099
  * yet recorded, written where a judgement passes because a window was open (Stop, commit, build).
981
1100
  */
982
1101
  function recordWindowBlobs(root, nowIso, v) {
1102
+ recordReceiptExcuses(root, nowIso, v);
983
1103
  if (v.byWindow.length === 0 && (v.playbooks ?? []).length === 0)
984
1104
  return;
985
1105
  inJudgement(() => {
@@ -0,0 +1,7 @@
1
+ export declare const WIRING_RECEIPT_DIR: (home: string) => string;
2
+ export declare function receiptRecordsExactly(absFile: string, home: string): boolean;
3
+ /**
4
+ * @implements A-SPEC-772.31 — the receipt digest these bytes matched, or null for every "no": the one read the excuse and
5
+ * its audit row both use (the row was a second read, review of 772.29 M2).
6
+ */
7
+ export declare function receiptMatchDigest(absFile: string, home: string): string | null;
@@ -0,0 +1,84 @@
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.WIRING_RECEIPT_DIR = void 0;
37
+ exports.receiptRecordsExactly = receiptRecordsExactly;
38
+ exports.receiptMatchDigest = receiptMatchDigest;
39
+ // @implements A-SPEC-794.131, A-SPEC-794.132, A-SPEC-772.31
40
+ /**
41
+ * Does the runtime binding receipt record exactly these bytes for this path? Principle 7 asks it about a local-only
42
+ * wiring file (`.mcp.json` rewritten by `runtime-binding`), so that a build's re-baseline does not turn the binding's own
43
+ * write into an unopened gate change. Whole bytes only (no settings view), the last row for the path only, a regular file
44
+ * only (a symlink is not the bytes the binding wrote there), and every doubt is "no".
45
+ *
46
+ * The receipt's format (file name, digest, row choice) is the one the writer uses: project/wiring-receipt-format.ts
47
+ * (A-SPEC-794.132). Governance imports nothing from the cli layer; a census pins WIRING_RECEIPT_DIR to the directory the
48
+ * runtime registry lives in.
49
+ *
50
+ * Known limitations: an agent that writes both the receipt and the file passes — forgery resistance is not verified (the
51
+ * 0.40 scope line). A receipt kept anywhere but `<home>/.holmes/runtime/` (a custom --registry, an injected registry path)
52
+ * gives no excuse: fail-closed.
53
+ */
54
+ const fs = __importStar(require("node:fs"));
55
+ const path = __importStar(require("node:path"));
56
+ const wiring_receipt_format_1 = require("../project/wiring-receipt-format");
57
+ const WIRING_RECEIPT_DIR = (home) => path.join(home, '.holmes', 'runtime');
58
+ exports.WIRING_RECEIPT_DIR = WIRING_RECEIPT_DIR;
59
+ function receiptRecordsExactly(absFile, home) {
60
+ return receiptMatchDigest(absFile, home) !== null;
61
+ }
62
+ /**
63
+ * @implements A-SPEC-772.31 — the receipt digest these bytes matched, or null for every "no": the one read the excuse and
64
+ * its audit row both use (the row was a second read, review of 772.29 M2).
65
+ */
66
+ function receiptMatchDigest(absFile, home) {
67
+ try {
68
+ if (!fs.lstatSync(absFile).isFile())
69
+ return null;
70
+ const files = JSON.parse(fs.readFileSync(path.join((0, exports.WIRING_RECEIPT_DIR)(home), wiring_receipt_format_1.RECEIPT_FILE), 'utf8')).files;
71
+ let real = absFile;
72
+ try {
73
+ real = fs.realpathSync.native(absFile);
74
+ }
75
+ catch { /* the raw path alone */ }
76
+ const row = (0, wiring_receipt_format_1.lastReceiptRow)(files, [absFile, real]);
77
+ if (row === null || row === 'malformed')
78
+ return null;
79
+ return (0, wiring_receipt_format_1.receiptDigest)(fs.readFileSync(absFile)) === row.digest ? row.digest : null;
80
+ }
81
+ catch {
82
+ return null;
83
+ }
84
+ }
@@ -0,0 +1,31 @@
1
+ /** Runner words that do not change which package runs (`npm exec`, `pnpm exec`) or are harmless options. */
2
+ export declare const SAFE_RUNNER_WORDS: ReadonlySet<string>;
3
+ /** The nearest ancestor (≤ 8) of a file's real path whose package.json names holmes-kit, or null. */
4
+ export declare function holmesRootOf(file: string): string | null;
5
+ /**
6
+ * @implements A-SPEC-772.28 — a text shim (npm's cmd-shim `.cmd`/`.ps1`/sh, pnpm's `.bin`) is no link: its real path is
7
+ * itself. Its quoted target paths relative to `$basedir`/`%dp0%` name the script it runs; all of them must lie in one
8
+ * holmes-kit root. Null when the file is no such shim, or its targets are none or in more than one root.
9
+ */
10
+ export declare function shimTarget(file: string): string | null;
11
+ export interface CliWordContext {
12
+ cwd: string;
13
+ env: NodeJS.ProcessEnv;
14
+ platform?: NodeJS.Platform;
15
+ /** The command's first word when the CLI word is not it (`npx`, `node`, `env` …), else undefined. */
16
+ runner?: string;
17
+ /** The words between the runner and the CLI word. */
18
+ between: readonly string[];
19
+ /** A `PATH=`/`NODE_PATH=` assignment before the command (or an `env` argument). */
20
+ pathAssigned: boolean;
21
+ /** A `cd`/`pushd`/`popd` earlier on the same line. */
22
+ cdBefore: boolean;
23
+ }
24
+ export type CliRoot = {
25
+ root: string;
26
+ } | {
27
+ unresolved: string;
28
+ } | {
29
+ packageReader: string;
30
+ };
31
+ export declare function resolveCliRoot(word: string, ctx: CliWordContext): CliRoot;
@@ -0,0 +1,261 @@
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.SAFE_RUNNER_WORDS = void 0;
37
+ exports.holmesRootOf = holmesRootOf;
38
+ exports.shimTarget = shimTarget;
39
+ exports.resolveCliRoot = resolveCliRoot;
40
+ // @implements A-SPEC-772.23, A-SPEC-772.28, A-SPEC-772.30, A-SPEC-772.31, A-SPEC-772.34
41
+ /**
42
+ * Which holmes-kit package a CLI word in a command would run — by real path, never by a version label. The governing gate
43
+ * compares it with its own package root: init or upgrade from another copy re-wires the gate (review A of 772.16–772.17:
44
+ * the downgrade rule lived in the copy doing the re-wiring, so an old copy had none, and labels are cheap to change).
45
+ * A form whose package cannot be known from the command and the file system (a PATH assignment, a cd first, a runner
46
+ * option outside a short list, a binary shim) is unresolved — the caller refuses it. A package name no local copy answers
47
+ * is the package reader's (A-SPEC-772.28: npx fetches it; the reader judges the version).
48
+ */
49
+ const fs = __importStar(require("node:fs"));
50
+ const os = __importStar(require("node:os"));
51
+ const path = __importStar(require("node:path"));
52
+ const PACKAGE_NAME = '@holmes-lab/holmes-kit';
53
+ const NPX_LIKE = new Set(['npx', 'pnpx', 'bunx', 'pnpm', 'yarn', 'npm']);
54
+ /** Runner words that do not change which package runs (`npm exec`, `pnpm exec`) or are harmless options. */
55
+ exports.SAFE_RUNNER_WORDS = new Set(['exec', '-y', '--yes', '-q', '--quiet', '--no-install',
56
+ // A-SPEC-772.30 (L-2): `npm exec --`, `npm x`, `bunx --bun` choose no package
57
+ '--', 'x', '--bun']);
58
+ /** @implements A-SPEC-772.28 — prefixes that run the next word as the command (unwrapped to find the runner). */
59
+ const PREFIX_RUNNERS = new Set(['env', 'nohup', 'time', 'command', 'exec']);
60
+ const FILE_RUNNERS = new Set(['node', 'bun', 'deno']);
61
+ const SHIM_LIMIT = 64 * 1024;
62
+ /** The nearest ancestor (≤ 8) of a file's real path whose package.json names holmes-kit, or null. */
63
+ function holmesRootOf(file) {
64
+ let real;
65
+ try {
66
+ real = fs.realpathSync.native(file);
67
+ }
68
+ catch {
69
+ return null;
70
+ }
71
+ let dir = path.dirname(real);
72
+ for (let hop = 0; hop < 8; hop++) {
73
+ try {
74
+ const j = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
75
+ if (j.name === PACKAGE_NAME)
76
+ return dir;
77
+ }
78
+ catch { /* no package.json here */ }
79
+ const parent = path.dirname(dir);
80
+ if (parent === dir)
81
+ break;
82
+ dir = parent;
83
+ }
84
+ return null;
85
+ }
86
+ /**
87
+ * @implements A-SPEC-772.28 — a text shim (npm's cmd-shim `.cmd`/`.ps1`/sh, pnpm's `.bin`) is no link: its real path is
88
+ * itself. Its quoted target paths relative to `$basedir`/`%dp0%` name the script it runs; all of them must lie in one
89
+ * holmes-kit root. Null when the file is no such shim, or its targets are none or in more than one root.
90
+ */
91
+ function shimTarget(file) {
92
+ const s = readShim(file);
93
+ return s !== 'not-a-shim' && s !== null ? s : null;
94
+ }
95
+ /** @implements A-SPEC-772.30 (L-1) — a file that is no text shim, a shim's one root, or null for a shim without one. */
96
+ function readShim(file) {
97
+ let text;
98
+ try {
99
+ const st = fs.lstatSync(file);
100
+ if (!st.isFile() || st.size > SHIM_LIMIT)
101
+ return 'not-a-shim';
102
+ text = fs.readFileSync(file, 'utf8');
103
+ }
104
+ catch {
105
+ return 'not-a-shim';
106
+ }
107
+ if (!/\$basedir|%~?dp0%?/i.test(text))
108
+ return 'not-a-shim';
109
+ const dir = path.dirname(file);
110
+ const roots = new Set();
111
+ for (const m of text.matchAll(/"(?:\$basedir|%~?dp0%?)[\\/]?([^"\r\n]*?\.(?:c|m)?js)"/gi)) {
112
+ const rel = m[1].replace(/\\/g, '/');
113
+ const root = holmesRootOf(path.resolve(dir, rel));
114
+ if (root === null)
115
+ return null;
116
+ roots.add(root);
117
+ }
118
+ return roots.size === 1 ? [...roots][0] : null;
119
+ }
120
+ /** npm's Windows shim (`<prefix>\holmes-kit.cmd`) is no link: its package sits in the global layout beside it. */
121
+ function shimRoot(dir) {
122
+ const p = path.join(dir, 'node_modules', '@holmes-lab', 'holmes-kit');
123
+ try {
124
+ const real = fs.realpathSync.native(p);
125
+ return holmesRootOf(path.join(real, 'package.json')) ?? null;
126
+ }
127
+ catch {
128
+ return null;
129
+ }
130
+ }
131
+ /**
132
+ * The holmes-kit root an executable found as the CLI runs: a text shim's target, else its real path's package. A recognised
133
+ * shim without one root is null — never judged by the package around the shim (A-SPEC-772.30, L-1).
134
+ */
135
+ function rootOfExecutable(file) {
136
+ const s = readShim(file);
137
+ return s === 'not-a-shim' ? holmesRootOf(file) : s;
138
+ }
139
+ function onPath(env, platform, cwd) {
140
+ const names = platform === 'win32' ? ['holmes-kit.cmd', 'holmes-kit.ps1', 'holmes-kit.exe', 'holmes-kit'] : ['holmes-kit'];
141
+ const delimiter = platform === 'win32' ? ';' : ':';
142
+ for (const entry of String(env.PATH ?? env.Path ?? '').split(delimiter)) {
143
+ if (entry === '')
144
+ continue;
145
+ // A-SPEC-772.28 (A-SPEC-149): a relative entry is where the command runs, not where the hook process runs
146
+ const dir = path.resolve(cwd, entry);
147
+ for (const n of names) {
148
+ const file = path.join(dir, n);
149
+ if (!fs.existsSync(file))
150
+ continue;
151
+ // A-SPEC-772.31 (review of 772.30, A-M3): a recognised text shim answers alone — the package beside it is asked only
152
+ // for a file that is no such shim (npm's layout beside a binary shim)
153
+ const shim = readShim(file);
154
+ const root = shim !== 'not-a-shim' ? shim : (holmesRootOf(file) ?? (platform === 'win32' ? shimRoot(dir) : null));
155
+ return root !== null ? { root } : { unresolved: `the holmes-kit on PATH (${file}) is not a holmes-kit install the gate can read (a binary shim, or no package)` };
156
+ }
157
+ }
158
+ return { unresolved: 'no holmes-kit on PATH' };
159
+ }
160
+ function upward(cwd, at) {
161
+ let dir = cwd;
162
+ for (let hop = 0; hop < 64; hop++) {
163
+ const found = at(dir);
164
+ if (found !== null)
165
+ return found;
166
+ const parent = path.dirname(dir);
167
+ if (parent === dir)
168
+ break;
169
+ dir = parent;
170
+ }
171
+ return null;
172
+ }
173
+ const localBin = (cwd) => upward(cwd, (d) => { const b = path.join(d, 'node_modules', '.bin', 'holmes-kit'); return fs.existsSync(b) ? b : null; });
174
+ /** @implements A-SPEC-772.28 — the package npm exec runs for a bare package name: a local dependency first. */
175
+ const localPackage = (cwd) => upward(cwd, (d) => { const p = path.join(d, 'node_modules', '@holmes-lab', 'holmes-kit', 'package.json'); return fs.existsSync(p) ? p : null; });
176
+ function resolveCliRoot(word, ctx) {
177
+ const platform = ctx.platform ?? process.platform;
178
+ if (ctx.pathAssigned)
179
+ return { unresolved: 'a PATH assignment before the command chooses which holmes-kit runs' };
180
+ // A-SPEC-772.30 (M-2): an absolute path names one file wherever the line moved to
181
+ const absolute = /[/\\]/.test(word) && path.isAbsolute(word.replace(/^~(?=[/\\]|$)/, os.homedir()));
182
+ if (ctx.cdBefore && !absolute)
183
+ return { unresolved: 'a cd earlier on the line moves where it runs' };
184
+ const base = (w) => (w.replace(/\\/g, '/').split('/').pop() ?? '').replace(/\.(?:cmd|exe)$/i, '').toLowerCase();
185
+ let runner = ctx.runner === undefined ? undefined : base(ctx.runner);
186
+ let between = [...ctx.between];
187
+ // A-SPEC-772.28: `time npx …`, `env npx …` — the prefix runs the next word, which is the runner
188
+ while (runner !== undefined && PREFIX_RUNNERS.has(runner)) {
189
+ if (runner === 'env') {
190
+ const opt = between.find((w) => w.startsWith('-'));
191
+ if (opt !== undefined)
192
+ return { unresolved: `env ${opt} changes the environment the command runs in` };
193
+ if (between.some((w) => /^(?:PATH|NODE_PATH|Path)=/.test(w)))
194
+ return { unresolved: 'a PATH assignment before the command chooses which holmes-kit runs' };
195
+ between = between.filter((w) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w));
196
+ }
197
+ else if (runner === 'time' || runner === 'command') {
198
+ between = between.filter((w, i) => !(i === 0 && w.startsWith('-')));
199
+ }
200
+ if (between.length === 0) {
201
+ runner = undefined;
202
+ break;
203
+ }
204
+ runner = base(between[0]);
205
+ between = between.slice(1);
206
+ }
207
+ if (runner === 'sudo' || runner === 'doas')
208
+ return { unresolved: `${runner} runs it with another PATH` };
209
+ // A-SPEC-772.28: `bun x` is bunx
210
+ if (runner === 'bun' && between[0] === 'x') {
211
+ runner = 'bunx';
212
+ between = between.slice(1);
213
+ }
214
+ // A-SPEC-772.30 (L-2): `npx -p <package> holmes-kit …` runs the bin of that package — read as the package name form
215
+ let spec = word;
216
+ if (runner !== undefined && NPX_LIKE.has(runner)) {
217
+ const p = between.findIndex((w) => w === '-p' || w === '--package' || w.startsWith('--package='));
218
+ if (p >= 0) {
219
+ const value = between[p].startsWith('--package=') ? between[p].slice('--package='.length) : between[p + 1];
220
+ if (value === undefined || !/^@holmes-lab\/holmes-kit(?:@.*)?$/i.test(value) || !/^holmes-kit$/i.test(word))
221
+ return { unresolved: `the runner's package \`${value ?? ''}\` may be another one` };
222
+ spec = value;
223
+ between = between.filter((_, i) => i !== p && !(between[p] !== undefined && !between[p].startsWith('--package=') && i === p + 1));
224
+ }
225
+ }
226
+ word = spec;
227
+ const isPackageSpec = /^@holmes-lab\/holmes-kit(?:@.*)?$/i.test(word);
228
+ // a path (or a bare file name after node): its real path decides
229
+ if (!isPackageSpec && (/[/\\]/.test(word) || (runner !== undefined && FILE_RUNNERS.has(runner)))) {
230
+ const file = path.resolve(ctx.cwd, word.replace(/^~(?=[/\\]|$)/, os.homedir()));
231
+ const root = rootOfExecutable(file);
232
+ return root !== null ? { root } : { unresolved: `${word} is not inside a holmes-kit install` };
233
+ }
234
+ if (runner !== undefined && NPX_LIKE.has(runner)) {
235
+ const odd = between.find((w) => !exports.SAFE_RUNNER_WORDS.has(w));
236
+ if (odd !== undefined)
237
+ return { unresolved: `the runner word \`${odd}\` may choose another package` };
238
+ if (isPackageSpec) {
239
+ // A-SPEC-772.28 (review A H1): a versioned or tagged name is resolved by npm — the reader judges it; an unversioned
240
+ // one runs the project's local copy when there is one (npm exec, measured), else npx fetches the latest
241
+ if (/^@holmes-lab\/holmes-kit@/i.test(word))
242
+ return { packageReader: 'a versioned package name' };
243
+ const local = localPackage(ctx.cwd);
244
+ if (local === null)
245
+ return { packageReader: 'no local copy; npx fetches the package' };
246
+ const root = holmesRootOf(local);
247
+ return root !== null ? { root } : { unresolved: `${path.dirname(local)} is not a holmes-kit install` };
248
+ }
249
+ const local = localBin(ctx.cwd);
250
+ if (local !== null) {
251
+ const root = rootOfExecutable(local);
252
+ return root !== null ? { root } : { unresolved: `${local} is not a holmes-kit install the gate can read (a binary shim, or no package)` };
253
+ }
254
+ return onPath(ctx.env, platform, ctx.cwd);
255
+ }
256
+ if (isPackageSpec)
257
+ return { unresolved: 'a package name runs only through a runner' };
258
+ if (runner !== undefined)
259
+ return { unresolved: `the runner \`${runner}\` is not read` };
260
+ return onPath(ctx.env, platform, ctx.cwd);
261
+ }
@@ -83,9 +83,11 @@ export declare const YARN_WRITES: Readonly<Record<string, WriteRule>>;
83
83
  export declare const YARN_NPM_WRITES: Readonly<Record<string, WriteRule>>;
84
84
  export declare function managerBuiltins(tool: string): ReadonlySet<string>;
85
85
  /** Release tools that publish: their dry-run flags, and the subcommand they need when they have one. */
86
+ /** `label`, when given, names what the refusal says was written (A-SPEC-794.147: `gh release create`, not "a release tool"). */
86
87
  export interface ReleaseTool {
87
88
  dry: readonly string[];
88
89
  needs?: (args: readonly string[]) => boolean;
90
+ label?: (args: readonly string[]) => string;
89
91
  }
90
92
  export declare const RELEASE_TOOLS: Readonly<Record<string, ReleaseTool>>;
91
93
  /** Runners that run a package script by name in every package: the script names they run, or null. */
@@ -41,7 +41,7 @@ exports.unwrapWith = unwrapWith;
41
41
  exports.commandStrings = commandStrings;
42
42
  exports.managerBuiltins = managerBuiltins;
43
43
  exports.runnerScripts = runnerScripts;
44
- // @implements A-SPEC-794.80, A-SPEC-794.78, A-SPEC-794.76, A-SPEC-794.75, A-SPEC-794.74, A-SPEC-794.72, A-SPEC-794.71, A-SPEC-794.70, A-SPEC-794.69
44
+ // @implements A-SPEC-794.147, A-SPEC-794.146, A-SPEC-794.80, A-SPEC-794.78, A-SPEC-794.76, A-SPEC-794.75, A-SPEC-794.74, A-SPEC-794.72, A-SPEC-794.71, A-SPEC-794.70, A-SPEC-794.69
45
45
  /**
46
46
  * What programs and subcommands do, in one table (A-SPEC-794.70): which subcommands of the package managers write to
47
47
  * a registry, which follow --dry-run, which run package scripts (and which), which release tools publish, and which
@@ -332,6 +332,26 @@ function managerBuiltins(tool) {
332
332
  return tool === 'yarn' || tool === 'pnpm' || tool === 'bun' ? BUILTINS[tool] : new Set();
333
333
  }
334
334
  const firstPositional = (args) => args.find((a) => !a.startsWith('-'));
335
+ /** A-SPEC-794.146 — `<forge> [opts] release [opts] <write>`: options taking a value skip that value (help is releaseTool's RELEASE_HELP). */
336
+ function forgePositionals(valued, args) {
337
+ const pos = [];
338
+ for (let k = 0; k < args.length && pos.length < 2; k++) {
339
+ const a = args[k];
340
+ if (valued.includes(a)) {
341
+ k++;
342
+ continue;
343
+ }
344
+ if (!a.startsWith('-'))
345
+ pos.push(a);
346
+ }
347
+ return pos;
348
+ }
349
+ function forgeRelease(valued, writes) {
350
+ return {
351
+ needs: (args) => { const pos = forgePositionals(valued, args); return pos[0] === 'release' && writes.includes(pos[1] ?? ''); },
352
+ label: (args) => forgePositionals(valued, args).join(' '),
353
+ };
354
+ }
335
355
  exports.RELEASE_TOOLS = {
336
356
  'semantic-release': { dry: ['--dry-run', '-d'] },
337
357
  np: { dry: ['--preview'] },
@@ -340,6 +360,11 @@ exports.RELEASE_TOOLS = {
340
360
  changeset: { dry: [], needs: (a) => firstPositional(a) === 'publish' },
341
361
  changesets: { dry: [], needs: (a) => firstPositional(a) === 'publish' },
342
362
  lerna: { dry: [], needs: (a) => firstPositional(a) === 'publish' },
363
+ // @implements A-SPEC-794.146 — a release write on a forge: the first positional word is `release`, the next the write
364
+ gh: { dry: [], ...forgeRelease(['-R', '--repo'], ['create', 'upload', 'edit', 'delete', 'delete-asset']) },
365
+ hub: { dry: [], ...forgeRelease(['-C', '-c'], ['create', 'edit', 'delete']) },
366
+ // `update` kept as a write though not confirmed against glab's docs (A-SPEC-794.147 honesty table)
367
+ glab: { dry: [], ...forgeRelease(['-R', '--repo'], ['create', 'upload', 'update', 'delete']) },
343
368
  };
344
369
  /** Runners that run a package script by name in every package: the script names they run, or null. */
345
370
  function runnerScripts(name, args) {