@holmes-lab/holmes-kit 0.29.0 → 0.31.0

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 (169) hide show
  1. package/CHANGELOG.md +556 -0
  2. package/README.md +15 -5
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  9. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  10. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  11. package/dist/holmes/cli/agents-guidance.js +11 -8
  12. package/dist/holmes/cli/agents.d.ts +41 -0
  13. package/dist/holmes/cli/agents.js +382 -2
  14. package/dist/holmes/cli/attest.d.ts +2 -0
  15. package/dist/holmes/cli/attest.js +66 -15
  16. package/dist/holmes/cli/ci-gate.js +16 -1
  17. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  18. package/dist/holmes/cli/claude-switches.js +967 -0
  19. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  20. package/dist/holmes/cli/codex-hooks.js +802 -0
  21. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  22. package/dist/holmes/cli/codex-oracle.js +1245 -0
  23. package/dist/holmes/cli/codex-toml.d.ts +58 -1
  24. package/dist/holmes/cli/codex-toml.js +456 -40
  25. package/dist/holmes/cli/doctor.d.ts +108 -8
  26. package/dist/holmes/cli/doctor.js +1408 -98
  27. package/dist/holmes/cli/index.js +23 -11
  28. package/dist/holmes/cli/init.d.ts +13 -0
  29. package/dist/holmes/cli/init.js +749 -77
  30. package/dist/holmes/cli/interactive-prompt.js +2 -2
  31. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  32. package/dist/holmes/cli/mcp-launcher.js +189 -6
  33. package/dist/holmes/cli/mcp-version.js +13 -2
  34. package/dist/holmes/cli/settings-merge.js +8 -2
  35. package/dist/holmes/cli/upgrade.d.ts +13 -0
  36. package/dist/holmes/cli/upgrade.js +116 -23
  37. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  38. package/dist/holmes/cli/workspace-scope.js +375 -0
  39. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  40. package/dist/holmes/cli/worktree-readiness.js +17 -3
  41. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  42. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  43. package/dist/holmes/cpg/cycle-detect.js +2 -1
  44. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  45. package/dist/holmes/cpg/required-calls.js +8 -1
  46. package/dist/holmes/governance/autonomy.d.ts +9 -0
  47. package/dist/holmes/governance/autonomy.js +28 -1
  48. package/dist/holmes/governance/constitution-debt.js +3 -2
  49. package/dist/holmes/governance/constitution.js +15 -3
  50. package/dist/holmes/governance/provenance-chain.js +3 -2
  51. package/dist/holmes/governance/push-gate-runner.js +4 -3
  52. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  53. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  54. package/dist/holmes/guardrail/linear-match.js +256 -0
  55. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  56. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  57. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  58. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  59. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  60. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  61. package/dist/holmes/guardrail/shell-words.js +1720 -0
  62. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  63. package/dist/holmes/guardrail/write-target.js +2379 -87
  64. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  65. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  66. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  67. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  68. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  69. package/dist/holmes/hooks/rtm-refresh-child.js +102 -18
  70. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  71. package/dist/holmes/hooks/rtm-refresh.js +60 -15
  72. package/dist/holmes/hooks/session-start.d.ts +10 -0
  73. package/dist/holmes/hooks/session-start.js +31 -7
  74. package/dist/holmes/hooks/stop.d.ts +2 -1
  75. package/dist/holmes/hooks/stop.js +197 -91
  76. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  77. package/dist/holmes/mcp/approval-adapters.js +21 -0
  78. package/dist/holmes/mcp/approval-commit.d.ts +20 -0
  79. package/dist/holmes/mcp/approval-commit.js +108 -0
  80. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  81. package/dist/holmes/mcp/approval-intent.js +67 -0
  82. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  83. package/dist/holmes/mcp/approval-policy.js +18 -0
  84. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  85. package/dist/holmes/mcp/elicit-approval.js +8 -3
  86. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  87. package/dist/holmes/mcp/handlers/graph-operations.js +15 -6
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  89. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  90. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  91. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  92. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  93. package/dist/holmes/mcp/handlers/requirement-triage.js +48 -11
  94. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  95. package/dist/holmes/mcp/handlers/review-evidence.js +15 -5
  96. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +18 -0
  97. package/dist/holmes/mcp/handlers/slice-orchestration.js +122 -16
  98. package/dist/holmes/mcp/handlers/spec-approval.d.ts +35 -2
  99. package/dist/holmes/mcp/handlers/spec-approval.js +175 -57
  100. package/dist/holmes/mcp/handlers/spec-authoring.js +36 -3
  101. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  102. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  103. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  104. package/dist/holmes/mcp/handlers.d.ts +126 -8
  105. package/dist/holmes/mcp/handlers.js +109 -18
  106. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  107. package/dist/holmes/mcp/harness-attestation.js +179 -0
  108. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  109. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  110. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +72 -2
  111. package/dist/holmes/mcp/requirement-triage-evidence.js +227 -1
  112. package/dist/holmes/mcp/server.js +24 -3
  113. package/dist/holmes/mcp/supervisor.js +7 -3
  114. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  115. package/dist/holmes/mcp/tool-schemas.js +54 -7
  116. package/dist/holmes/mcp/validate-args.js +12 -0
  117. package/dist/holmes/project/bounded-io.d.ts +102 -0
  118. package/dist/holmes/project/bounded-io.js +212 -0
  119. package/dist/holmes/project/change-source.js +3 -1
  120. package/dist/holmes/project/ci-runs.js +3 -2
  121. package/dist/holmes/project/ignore.d.ts +31 -2
  122. package/dist/holmes/project/ignore.js +409 -50
  123. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  124. package/dist/holmes/project/regular-file-guard.js +149 -0
  125. package/dist/holmes/project/root.js +12 -3
  126. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  127. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  128. package/dist/holmes/reverse/anchor.js +4 -3
  129. package/dist/holmes/reverse/scan.js +6 -2
  130. package/dist/holmes/review/commit-text.js +3 -2
  131. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  132. package/dist/holmes/review/condition-hunk-replay.js +13 -2
  133. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  134. package/dist/holmes/review/failed-test-names.js +13 -10
  135. package/dist/holmes/review/findings.js +3 -1
  136. package/dist/holmes/review/kills-check.js +6 -1
  137. package/dist/holmes/review/point-in-time-replay.js +5 -4
  138. package/dist/holmes/review/replay-corpus.js +5 -4
  139. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  140. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  141. package/dist/holmes/review/run-replay.js +3 -2
  142. package/dist/holmes/review/scope.js +6 -1
  143. package/dist/holmes/review/temporal-prior.js +3 -2
  144. package/dist/holmes/review/test-evidence.js +3 -2
  145. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  146. package/dist/holmes/review/test-outcomes.js +92 -2
  147. package/dist/holmes/review/test-runner.d.ts +6 -0
  148. package/dist/holmes/review/test-runner.js +36 -15
  149. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  150. package/dist/holmes/rtm/anchor-ids.js +42 -2
  151. package/dist/holmes/rtm/file-anchors.js +4 -1
  152. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  153. package/dist/holmes/rtm/git-changes.js +3 -1
  154. package/dist/holmes/rtm/graph-store.js +3 -2
  155. package/dist/holmes/rtm/test-scope.js +9 -4
  156. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  157. package/dist/holmes/spec/compat-impact.js +682 -11
  158. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  159. package/dist/holmes/spec/entity-integration.js +3 -2
  160. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  161. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  162. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  163. package/dist/holmes/spec/renumber.js +25 -10
  164. package/dist/holmes/spec/spec-parser.js +9 -3
  165. package/dist/holmes/spec/yaml-scalar.js +2 -2
  166. package/dist/holmes/update/refresh.js +3 -1
  167. package/dist/holmes/update/update-notice.d.ts +6 -0
  168. package/dist/holmes/update/update-notice.js +18 -1
  169. package/package.json +11 -4
@@ -1,14 +1,319 @@
1
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
+ })();
2
35
  Object.defineProperty(exports, "__esModule", { value: true });
3
36
  exports.CODEX_TABLE = void 0;
37
+ exports.parseCodexConfig = parseCodexConfig;
38
+ exports.codexHolmesDisabled = codexHolmesDisabled;
39
+ exports.readCodexConfigBytes = readCodexConfigBytes;
40
+ exports.codexConfigLoadProblem = codexConfigLoadProblem;
41
+ exports.codexConfigWriteProblem = codexConfigWriteProblem;
42
+ exports.defaultCodexConfigPath = defaultCodexConfigPath;
4
43
  exports.codexMcpBlock = codexMcpBlock;
5
44
  exports.mergeCodexToml = mergeCodexToml;
6
45
  exports.removeCodexToml = removeCodexToml;
7
46
  exports.readCodexHolmesEntry = readCodexHolmesEntry;
47
+ exports.hasCodexHolmesTable = hasCodexHolmesTable;
48
+ exports.mentionsHolmes = mentionsHolmes;
49
+ exports.unownedHolmesShape = unownedHolmesShape;
50
+ exports.readCodexFixedSpecs = readCodexFixedSpecs;
8
51
  exports.invalidTomlEscape = invalidTomlEscape;
52
+ // @implements A-SPEC-733, A-SPEC-731, A-SPEC-721
53
+ // @implements A-SPEC-266
54
+ // Codex reads default MCP servers from `$CODEX_HOME/config.toml` (normally
55
+ // `~/.codex/config.toml`), not from a repository-local `.codex/config.toml`. This module owns only
56
+ // Holmes' TOML table there and preserves the rest byte-for-byte. The launched server deliberately
57
+ // has no HOLMES_SPECS binding: it resolves its governed workspace from the active Codex session cwd.
58
+ const path = __importStar(require("node:path"));
59
+ const os = __importStar(require("node:os"));
60
+ // @implements A-SPEC-731 (round 4) — READ with a real TOML 1.0 parser (owner decision 2026-09-24): three
61
+ // review rounds kept finding the hand scanner reading values out of strings and subtables. Writes stay
62
+ // textual (only our region changes) and are re-parsed before they happen.
63
+ const smol_toml_1 = require("smol-toml");
64
+ const linear_match_1 = require("../guardrail/linear-match");
65
+ const isTable = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
66
+ /** The parsed document, or the parser's reason for refusing it (Codex refuses such a file whole). */
67
+ function parseCodexConfig(raw) {
68
+ // CRLF reads as LF inside multi-line strings, as tomllib reads it (TOML lets a parser normalize).
69
+ // Round 5: integers beyond 2^53 load as BigInt (Codex loads them); impossible dates are refused,
70
+ // which the parser alone would roll over (`1979-02-30` → March 2).
71
+ if (raw.startsWith('\uFEFF\uFEFF'))
72
+ return { ok: false, reason: 'the file starts with two byte-order marks (Codex: invalid unquoted key)' };
73
+ const text = raw.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
74
+ let doc;
75
+ try {
76
+ doc = (0, smol_toml_1.parse)(text, { integersAsBigInt: 'asNeeded' });
77
+ }
78
+ catch (e) {
79
+ return { ok: false, reason: String(e instanceof Error ? e.message : e).split('\n')[0].slice(0, 300) };
80
+ }
81
+ const badDate = impossibleDateLiteral(text);
82
+ if (badDate !== null)
83
+ return { ok: false, reason: `invalid date ${badDate} (that day does not exist in its month)` };
84
+ return { ok: true, doc };
85
+ }
86
+ const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
87
+ /** The first date literal OUTSIDE strings and comments whose day does not exist, or null (linear). */
88
+ function impossibleDateLiteral(text) {
89
+ let i = 0;
90
+ while (i < text.length) {
91
+ const c = text[i];
92
+ if (c === '#') {
93
+ const nl = text.indexOf('\n', i);
94
+ i = nl < 0 ? text.length : nl;
95
+ continue;
96
+ }
97
+ if (c === '"' || c === "'") {
98
+ const triple = text.startsWith(c.repeat(3), i);
99
+ const delim = triple ? c.repeat(3) : c;
100
+ let j = i + delim.length;
101
+ while (j < text.length && !text.startsWith(delim, j) && !(!triple && text[j] === '\n')) {
102
+ if (c === '"' && text[j] === '\\')
103
+ j++;
104
+ j++;
105
+ }
106
+ i = j + delim.length;
107
+ continue;
108
+ }
109
+ if (/[0-9]/.test(c) && (i === 0 || !/[\w.-]/.test(text[i - 1]))) {
110
+ const m = /^(\d{4})-(\d{2})-(\d{2})(?![\d-])/.exec(text.slice(i, i + 11));
111
+ if (m) {
112
+ // Round 7: a date-shaped KEY (`2023-02-30 = 1`, `[2023-02-30]`, `2023-02-30.a`) is a key.
113
+ const after = /^[ \t]*(.?)/.exec(text.slice(i + 10, i + 40))?.[1] ?? '';
114
+ const lineStart = text.lastIndexOf('\n', i) + 1;
115
+ const beforeOnLine = text.slice(lineStart, i);
116
+ if (after === '=' || after === '.' || (after === ']' && !beforeOnLine.includes('=')) || (/[{,][ \t]*$/.test(beforeOnLine) && after === '=')) {
117
+ i += 10;
118
+ continue;
119
+ }
120
+ const y = +m[1], mo = +m[2], d = +m[3];
121
+ const leap = (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
122
+ const max = mo >= 1 && mo <= 12 ? (mo === 2 && leap ? 29 : DAYS[mo - 1]) : 0;
123
+ if (d < 1 || d > max)
124
+ return m[0];
125
+ i += 10;
126
+ continue;
127
+ }
128
+ }
129
+ i++;
130
+ }
131
+ return null;
132
+ }
133
+ /** @implements A-SPEC-727 (round 10) — whether the holmes-kit table sets `enabled = false`. */
134
+ function codexHolmesDisabled(raw) {
135
+ const p = parseCodexConfig(raw);
136
+ if (!p.ok)
137
+ return false;
138
+ const entry = holmesEntryOf(p.doc);
139
+ return entry !== null && entry.enabled === false;
140
+ }
141
+ /** `mcp_servers["holmes-kit"]` of a parsed document, when it is a table. */
142
+ function holmesEntryOf(doc) {
143
+ const servers = Object.prototype.hasOwnProperty.call(doc, 'mcp_servers') ? doc.mcp_servers : undefined;
144
+ if (!isTable(servers) || !Object.prototype.hasOwnProperty.call(servers, 'holmes-kit'))
145
+ return null;
146
+ const entry = servers['holmes-kit'];
147
+ return isTable(entry) ? entry : null;
148
+ }
149
+ /** Why Codex cannot load this config, or null when it parses. */
150
+ /**
151
+ * @implements A-SPEC-731 (round 6) — bytes → text only when they are valid UTF-8: Codex refuses the
152
+ * whole file otherwise, and a lenient read rewrote the bytes (and the backup) with U+FFFD (measured).
153
+ */
154
+ function readCodexConfigBytes(bytes) {
155
+ // Round 7: keep the BOM in the text (parseCodexConfig strips exactly one; two is a load problem).
156
+ try {
157
+ return { ok: true, text: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes) };
158
+ }
159
+ catch {
160
+ return { ok: false, reason: 'the file is not valid UTF-8 (Codex refuses it whole)' };
161
+ }
162
+ }
163
+ const I64_MIN = -(BigInt(2) ** BigInt(63));
164
+ const I64_MAX = BigInt(2) ** BigInt(63) - BigInt(1);
165
+ const ARRAY_DEPTH_LIMIT = 80;
166
+ const isStr = (v) => typeof v === 'string';
167
+ const isStrArray = (v) => Array.isArray(v) && v.every(isStr);
168
+ const isStrTable = (v) => isTable(v) && Object.values(v).every(isStr);
169
+ const isEnvVar = (v) => isStr(v) || (isTable(v) && isStr(v.name)
170
+ && Object.keys(v).every((k) => k === 'name' || k === 'source') && (v.source === undefined || v.source === 'local' || v.source === 'remote'));
171
+ const isNonNegNumber = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0) || (typeof v === 'bigint' && v >= BigInt(0));
172
+ /** Values Codex refuses anywhere: integers outside i64, arrays nested past its recursion limit. */
173
+ function valueProblem(v, where, depth = 0) {
174
+ if (typeof v === 'bigint' && (v < I64_MIN || v > I64_MAX))
175
+ return `${where} is an integer outside the signed 64-bit range`;
176
+ // Round 7 (measured): Codex's recursion limit counts tables (inline or by header/dotted key) as well
177
+ // as arrays.
178
+ if (Array.isArray(v) || isTable(v)) {
179
+ if (depth + 1 > ARRAY_DEPTH_LIMIT)
180
+ return `${where} nests tables/arrays deeper than Codex reads (${ARRAY_DEPTH_LIMIT})`;
181
+ const entries = Array.isArray(v) ? v.map((x, i) => [`[${i}]`, x]) : Object.entries(v).map(([k, x]) => [`.${k}`, x]);
182
+ for (const [k, x] of entries) {
183
+ const p = valueProblem(x, `${where}${k}`, depth + 1);
184
+ if (p)
185
+ return p;
186
+ }
187
+ }
188
+ return null;
189
+ }
190
+ /** One `[mcp_servers.<name>]` table as Codex deserializes it (measured refusals only). */
191
+ function serverProblem(name, t) {
192
+ const at = `mcp_servers.${name}`;
193
+ if (!isTable(t))
194
+ return `${at} is not a table (Codex expects one server table)`;
195
+ const hasCommand = t.command !== undefined, hasUrl = t.url !== undefined;
196
+ if (!hasCommand && !hasUrl)
197
+ return `${at} has neither command nor url (Codex: invalid transport)`;
198
+ if (hasCommand && hasUrl)
199
+ return `${at} has both command and url (Codex: invalid transport)`;
200
+ if (hasCommand && !isStr(t.command))
201
+ return `${at}.command is not a string`;
202
+ if (hasUrl && !isStr(t.url))
203
+ return `${at}.url is not a string`;
204
+ if (t.args !== undefined && !isStrArray(t.args))
205
+ return `${at}.args is not an array of strings`;
206
+ // Round 7 (measured): an env_vars entry is a string or { name, source = "local"|"remote" }.
207
+ if (t.env_vars !== undefined && !(Array.isArray(t.env_vars) && t.env_vars.every(isEnvVar)))
208
+ return `${at}.env_vars entries are not strings or { name, source } tables`;
209
+ if (t.env !== undefined && !isStrTable(t.env))
210
+ return `${at}.env is not a table of strings`;
211
+ if (t.enabled !== undefined && typeof t.enabled !== 'boolean')
212
+ return `${at}.enabled is not a boolean`;
213
+ if (t.required !== undefined && typeof t.required !== 'boolean')
214
+ return `${at}.required is not a boolean`;
215
+ if (t.cwd !== undefined && !isStr(t.cwd))
216
+ return `${at}.cwd is not a string`;
217
+ for (const k of ['startup_timeout_sec', 'tool_timeout_sec']) {
218
+ if (t[k] !== undefined && !(isNonNegNumber(t[k]) && Number(t[k]) < 1e19))
219
+ return `${at}.${k} is not a non-negative number below 1e19`;
220
+ }
221
+ if (t.startup_timeout_ms !== undefined && !((typeof t.startup_timeout_ms === 'number' && Number.isInteger(t.startup_timeout_ms) && t.startup_timeout_ms >= 0) || (typeof t.startup_timeout_ms === 'bigint' && t.startup_timeout_ms >= BigInt(0)))) {
222
+ return `${at}.startup_timeout_ms is not a non-negative integer`;
223
+ }
224
+ for (const k of ['enabled_tools', 'disabled_tools'])
225
+ if (t[k] !== undefined && !isStrArray(t[k]))
226
+ return `${at}.${k} is not an array of strings`;
227
+ for (const k of ['http_headers', 'env_http_headers'])
228
+ if (t[k] !== undefined && !isStrTable(t[k]))
229
+ return `${at}.${k} is not a table of strings`;
230
+ for (const k of ['bearer_token_env_var', 'environment_id'])
231
+ if (t[k] !== undefined && !isStr(t[k]))
232
+ return `${at}.${k} is not a string`;
233
+ // Transport-specific fields (measured: "… is not supported for streamable_http / stdio").
234
+ const notFor = hasUrl ? ['args', 'env', 'env_vars', 'cwd', 'bearer_token'] : ['http_headers', 'env_http_headers', 'bearer_token_env_var', 'bearer_token', 'oauth_resource'];
235
+ for (const k of notFor)
236
+ if (t[k] !== undefined)
237
+ return `${at}.${k} is not supported for ${hasUrl ? 'a url (streamable_http)' : 'a command (stdio)'} server`;
238
+ return null;
239
+ }
240
+ function codexConfigLoadProblem(raw) {
241
+ const p = parseCodexConfig(raw);
242
+ if (!p.ok)
243
+ return p.reason;
244
+ // @implements A-SPEC-731 (round 6) — what Codex refuses OUTSIDE the holmes-kit table refuses the
245
+ // whole file too; doctor had said PASS and init "active" for such files (measured).
246
+ const anywhere = valueProblem(p.doc, 'the config', -1);
247
+ if (anywhere)
248
+ return anywhere;
249
+ if (p.doc.model !== undefined && !isStr(p.doc.model))
250
+ return 'model is not a string';
251
+ if (p.doc.mcp_servers !== undefined) {
252
+ if (!isTable(p.doc.mcp_servers))
253
+ return 'mcp_servers is not a table';
254
+ for (const [name, t] of Object.entries(p.doc.mcp_servers)) {
255
+ if (name === 'holmes-kit')
256
+ continue; // judged below with its own messages
257
+ const sp = serverProblem(name, t);
258
+ if (sp)
259
+ return sp;
260
+ }
261
+ }
262
+ // Round 5: an entry Codex cannot deserialize makes it refuse the whole shared file.
263
+ if (!hasHolmesKey(p.doc))
264
+ return null;
265
+ const servers = p.doc.mcp_servers;
266
+ const entry = servers['holmes-kit'];
267
+ if (!isTable(entry))
268
+ return 'mcp_servers.holmes-kit is not a table (Codex expects one server table)';
269
+ if (entry.command !== undefined && typeof entry.command !== 'string')
270
+ return 'mcp_servers.holmes-kit.command is not a string';
271
+ if (entry.args !== undefined && (!Array.isArray(entry.args) || !entry.args.every((a) => typeof a === 'string')))
272
+ return 'mcp_servers.holmes-kit.args is not an array of strings';
273
+ if (entry.env !== undefined && !isTable(entry.env))
274
+ return 'mcp_servers.holmes-kit.env is not a table';
275
+ return serverProblem('holmes-kit', entry);
276
+ }
277
+ /**
278
+ * @implements A-SPEC-731 (round 4) — the write a caller is about to make, judged by the parser: null
279
+ * when `after` loads and its holmes-kit entry is exactly `want` (or absent when `want` is null), else
280
+ * the reason to write nothing.
281
+ */
282
+ function codexConfigWriteProblem(after, want) {
283
+ const p = parseCodexConfig(after);
284
+ if (!p.ok)
285
+ return `the result would not load as TOML (${p.reason})`;
286
+ const entry = holmesEntryOf(p.doc);
287
+ if (want === null)
288
+ return entry === null && !hasHolmesKey(p.doc) ? null : 'holmes-kit would still be configured after removal';
289
+ if (entry === null)
290
+ return 'the result would not carry a [mcp_servers.holmes-kit] table (is mcp_servers a closed inline table?)';
291
+ let same = false;
292
+ try {
293
+ same = entry.command === want.command && JSON.stringify(entry.args) === JSON.stringify(want.args)
294
+ && JSON.stringify(entry.env ?? null) === JSON.stringify(want.env ?? null)
295
+ && Object.keys(entry).every((k) => ['command', 'args', 'env'].includes(k));
296
+ }
297
+ catch {
298
+ same = false;
299
+ } // a BigInt value is not the entry holmes-kit writes
300
+ return same ? null : 'the holmes-kit entry in the result would not be exactly the one holmes-kit writes';
301
+ }
302
+ const hasHolmesKey = (doc) => {
303
+ const servers = Object.prototype.hasOwnProperty.call(doc, 'mcp_servers') ? doc.mcp_servers : undefined;
304
+ return isTable(servers) && Object.prototype.hasOwnProperty.call(servers, 'holmes-kit');
305
+ };
9
306
  /** The one table holmes-kit owns in a Codex config.toml. */
10
307
  exports.CODEX_TABLE = 'mcp_servers.holmes-kit';
11
308
  const HEADER = `[${exports.CODEX_TABLE}]`;
309
+ /**
310
+ * The default configuration location actually loaded by Codex CLI. A named profile may layer a
311
+ * different config, but it is invocation state and cannot be inferred by an offline doctor run.
312
+ * Injectable values keep this platform-sensitive path rule deterministic in tests.
313
+ */
314
+ function defaultCodexConfigPath(env = process.env, home = os.homedir()) {
315
+ return path.join(env.CODEX_HOME || path.join(home, '.codex'), 'config.toml');
316
+ }
12
317
  /** TOML basic-string escape — backslash and quote, the named whitespace escapes, then any remaining
13
318
  * C0 control character as \uXXXX. Built by code point so no literal control byte lives in the source. */
14
319
  function tomlStr(s) {
@@ -37,13 +342,13 @@ function tomlStr(s) {
37
342
  * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary
38
343
  * unambiguous: our region runs from the header to the next table header. Ends with a trailing newline.
39
344
  */
40
- function codexMcpBlock(entry, specsDir) {
345
+ function codexMcpBlock(entry, _legacySpecsDir) {
41
346
  const args = entry.args.map(tomlStr).join(', ');
42
347
  return [
43
348
  HEADER,
44
349
  `command = ${tomlStr(entry.command)}`,
45
350
  `args = [${args}]`,
46
- `env = { HOLMES_SPECS = ${tomlStr(specsDir)} }`,
351
+ 'env = { HOLMES_MCP_AUTORELOAD = "1" }',
47
352
  '',
48
353
  ].join('\n');
49
354
  }
@@ -134,7 +439,10 @@ function lineStartStates(lines) {
134
439
  * append a duplicate table and invalidate the whole file — round-1 quoted-key, round-2 whitespace).
135
440
  * Returns null when the line is not a table header.
136
441
  */
137
- function tableKeyPath(line) {
442
+ function tableKeyPath(rawLine) {
443
+ // @implements A-SPEC-731 (round 1) — a CRLF file leaves `\r` on every line, and `.` never matches it:
444
+ // `[mcp_servers.holmes-kit] # mine\r` was not our table and init refused it as an unowned shape.
445
+ const line = rawLine.replace(/\r$/, '');
138
446
  const m = line.match(/^\s*\[\[?([^\]]*)\]\]?\s*(#.*)?$/);
139
447
  if (!m)
140
448
  return null;
@@ -142,30 +450,49 @@ function tableKeyPath(line) {
142
450
  const segs = [];
143
451
  let cur = '';
144
452
  let q = null;
453
+ // @implements A-SPEC-731 — basic-string ("…") segments are decoded as TOML decodes them:
454
+ // `[mcp_servers."holmes\u002dkit"]` IS `[mcp_servers.holmes-kit]` (tomllib agrees). An invalid escape
455
+ // makes the header unparsed — never ours.
456
+ const quotedBasic = new Set();
145
457
  for (let i = 0; i < inner.length; i++) {
146
458
  const c = inner[i];
147
459
  if (q) {
148
460
  if (c === q)
149
461
  q = null;
462
+ else if (c === '\\' && q === '"') {
463
+ cur += c + (inner[i + 1] ?? '');
464
+ i++;
465
+ } // keep the escape; decoded below
150
466
  else
151
467
  cur += c;
152
468
  continue;
153
469
  }
154
470
  if (c === '"' || c === "'") {
155
471
  q = c;
472
+ if (c === '"')
473
+ quotedBasic.add(segs.length);
156
474
  continue;
157
475
  }
158
476
  if (c === '.') {
159
- segs.push(cur.trim());
477
+ segs.push(cur);
160
478
  cur = '';
161
479
  continue;
162
480
  }
481
+ // Whitespace OUTSIDE quotes separates tokens and is dropped; inside quotes it is part of the key
482
+ // (`" holmes-kit"` is another server — A-SPEC-721), so segments are never trimmed.
483
+ if (c === ' ' || c === '\t')
484
+ continue;
163
485
  cur += c;
164
486
  }
165
- segs.push(cur.trim());
487
+ segs.push(cur);
166
488
  if (q !== null)
167
489
  return null; // unbalanced quote — not a clean header
168
- return segs;
490
+ try {
491
+ return segs.map((seg, i) => (quotedBasic.has(i) && seg.includes('\\') ? unescapeToml(seg) : seg));
492
+ }
493
+ catch {
494
+ return null;
495
+ }
169
496
  }
170
497
  const isOurTable = (kp) => kp.length === 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
171
498
  const isOurPrefix = (kp) => kp.length >= 2 && kp[0] === 'mcp_servers' && kp[1] === 'holmes-kit';
@@ -201,6 +528,10 @@ function ourRegion(lines) {
201
528
  break;
202
529
  } // any non-our (incl. unparseable) header closes us
203
530
  }
531
+ // @implements A-SPEC-731 (round 6) — comments and blank lines before the next header belong to what
532
+ // follows: rewiring deleted "# ---- my other server (keep!) ----" (measured).
533
+ while (end > start + 1 && states[end - 1].ml === null && /^\s*(#[^\n]*)?$/.test(lines[end - 1].replace(/\r$/, '')))
534
+ end--;
204
535
  return { start, end };
205
536
  }
206
537
  /**
@@ -217,11 +548,11 @@ function mergeCodexToml(existing, block) {
217
548
  if (region) {
218
549
  const after = lines.slice(region.end);
219
550
  const merged = [...lines.slice(0, region.start), ...blockLines, ...after];
220
- return merged.join('\n').replace(/\n*$/, '\n');
551
+ return `${(0, linear_match_1.trimTrailing)(merged.join('\n'), '\n')}\n`;
221
552
  }
222
553
  // Append: exactly one blank line between the user's content and our block.
223
- const base = existing.replace(/\n*$/, '');
224
- return `${base}\n\n${block.replace(/\n*$/, '')}\n`;
554
+ const base = (0, linear_match_1.trimTrailing)(existing, '\n');
555
+ return `${base}\n\n${(0, linear_match_1.trimTrailing)(block, '\n')}\n`;
225
556
  }
226
557
  /** Strip our region from `existing`, preserving everything else. Absent → returned unchanged. */
227
558
  function removeCodexToml(existing) {
@@ -238,7 +569,7 @@ function removeCodexToml(existing) {
238
569
  const joined = merged.join('\n');
239
570
  if (joined.trim() === '')
240
571
  return '';
241
- return joined.replace(/\n*$/, '\n');
572
+ return `${(0, linear_match_1.trimTrailing)(joined, '\n')}\n`;
242
573
  }
243
574
  /**
244
575
  * Read `{command,args}` from our table in a config.toml — for doctor's drift check. Parses only the
@@ -246,30 +577,121 @@ function removeCodexToml(existing) {
246
577
  * translating an unreadable wiring into a pass).
247
578
  */
248
579
  function readCodexHolmesEntry(raw) {
249
- const lines = raw.split('\n');
250
- const region = ourRegion(lines);
251
- if (!region)
580
+ // @implements A-SPEC-731 (round 4) — what the parser loads, nothing else.
581
+ const parsed = parseCodexConfig(raw);
582
+ if (!parsed.ok)
252
583
  return null;
253
- let command = null;
254
- let args = null;
255
- try {
256
- for (let i = region.start + 1; i < region.end; i++) {
257
- const cmd = lines[i].match(/^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"\s*(#.*)?$/);
258
- if (cmd)
259
- command = unescapeToml(cmd[1]);
260
- const arr = lines[i].match(/^\s*args\s*=\s*\[(.*)\]\s*(#.*)?$/);
261
- if (arr)
262
- args = parseTomlStringArray(arr[1]);
584
+ const entry = holmesEntryOf(parsed.doc);
585
+ if (entry === null || typeof entry.command !== 'string' || !Array.isArray(entry.args) || !entry.args.every((a) => typeof a === 'string'))
586
+ return null;
587
+ return { command: entry.command, args: entry.args };
588
+ }
589
+ /** @implements A-SPEC-721 — whether the config carries Holmes's table at all (well-formed or not). */
590
+ function hasCodexHolmesTable(raw) {
591
+ return ourRegion(raw.split('\n')) !== null;
592
+ }
593
+ /** A line with its trailing comment removed — `#` inside a quoted string is not a comment. */
594
+ function stripComment(line) {
595
+ let q = null;
596
+ for (let i = 0; i < line.length; i++) {
597
+ const c = line[i];
598
+ if (q) {
599
+ if (c === '\\' && q === '"')
600
+ i++;
601
+ else if (c === q)
602
+ q = null;
603
+ continue;
263
604
  }
605
+ if (c === '"' || c === "'")
606
+ q = c;
607
+ else if (c === '#')
608
+ return line.slice(0, i);
264
609
  }
265
- catch (e) {
266
- if (e instanceof InvalidTomlEscape)
267
- return null; // @implements A-SPEC-585 — unreadable, not mangled
268
- throw e;
610
+ return line;
611
+ }
612
+ /**
613
+ * @implements A-SPEC-721 — every line that configures the Holmes server, in any TOML spelling: a
614
+ * `[mcp_servers.holmes-kit…]` header, or a key whose full dotted path starts `mcp_servers.holmes-kit`
615
+ * (`holmes-kit = {…}` / `holmes-kit.command = …` under `[mcp_servers]`, or any key inside our table).
616
+ * Lines inside multi-line strings and arrays, and comments, are never counted.
617
+ */
618
+ function holmesLines(raw) {
619
+ const lines = raw.split('\n');
620
+ const states = lineStartStates(lines);
621
+ const out = [];
622
+ let table = [];
623
+ for (let i = 0; i < lines.length; i++) {
624
+ if (states[i].ml !== null || states[i].depth !== 0)
625
+ continue;
626
+ const text = stripComment(lines[i]);
627
+ if (/^\s*\[/.test(text)) {
628
+ table = tableKeyPath(text) ?? ['<unparsed>'];
629
+ if (isOurPrefix(table))
630
+ out.push({ i, header: true, text });
631
+ continue;
632
+ }
633
+ // A-SPEC-731 (round 2): the key ends at the first `=` OUTSIDE quotes (`"a=b"` is one key).
634
+ const eq = firstUnquoted(text, '=');
635
+ if (eq <= 0)
636
+ continue;
637
+ const key = tableKeyPath(`[${text.slice(0, eq).trim()}]`);
638
+ if (!key)
639
+ continue;
640
+ if (isOurPrefix([...table, ...key]))
641
+ out.push({ i, header: false, text });
269
642
  }
270
- if (command === null || args === null)
271
- return null;
272
- return { command, args };
643
+ return out;
644
+ }
645
+ /** @implements A-SPEC-721 — whether the shared config configures the Holmes server at all. */
646
+ function mentionsHolmes(raw) {
647
+ const parsed = parseCodexConfig(raw);
648
+ return parsed.ok ? hasHolmesKey(parsed.doc) : holmesLines(raw).length > 0;
649
+ }
650
+ /**
651
+ * @implements A-SPEC-721 — Holmes settings outside the one region init owns (dotted keys, an inline
652
+ * table under `[mcp_servers]`, a subtable without its parent). Merging our block into such a file
653
+ * would declare the table twice and Codex would reject the whole shared config.
654
+ */
655
+ function unownedHolmesShape(raw) {
656
+ const region = ourRegion(raw.split('\n'));
657
+ // Round 4: holmes-kit configured without our table region (a root inline `mcp_servers = { … }`).
658
+ const parsed = parseCodexConfig(raw);
659
+ if (parsed.ok && hasHolmesKey(parsed.doc) && region === null)
660
+ return true;
661
+ return holmesLines(raw).some(({ i }) => !region || i < region.start || i >= region.end);
662
+ }
663
+ /**
664
+ * @implements A-SPEC-721 — a `HOLMES_SPECS` value set on any Holmes line (inline env, env subtable,
665
+ * quoted key; basic or literal string). Null when absent or unreadable. Doctor decides whether the
666
+ * value binds one fixed project.
667
+ */
668
+ function readCodexFixedSpecs(raw) {
669
+ // @implements A-SPEC-731 (round 4) — `env.HOLMES_SPECS` of the loaded entry; nothing else is a pin.
670
+ const parsed = parseCodexConfig(raw);
671
+ if (parsed.ok) {
672
+ const env = holmesEntryOf(parsed.doc)?.env;
673
+ return isTable(env) && typeof env.HOLMES_SPECS === 'string' ? env.HOLMES_SPECS : null;
674
+ }
675
+ return null;
676
+ }
677
+ /** Index of the first `ch` in `line` outside basic/literal strings, or -1. */
678
+ function firstUnquoted(line, ch) {
679
+ let q = null;
680
+ for (let i = 0; i < line.length; i++) {
681
+ const c = line[i];
682
+ if (q) {
683
+ if (c === '\\' && q === '"')
684
+ i++;
685
+ else if (c === q)
686
+ q = null;
687
+ continue;
688
+ }
689
+ if (c === '"' || c === "'")
690
+ q = c;
691
+ else if (c === ch)
692
+ return i;
693
+ }
694
+ return -1;
273
695
  }
274
696
  /**
275
697
  * @implements A-SPEC-585
@@ -314,7 +736,10 @@ function firstInvalidEscape(s) {
314
736
  continue;
315
737
  }
316
738
  const width = e === 'u' ? 4 : e === 'U' ? 8 : 0;
317
- if (width > 0 && new RegExp(`^[0-9a-fA-F]{${width}}$`).test(s.slice(i + 2, i + 2 + width))) {
739
+ const hex = s.slice(i + 2, i + 2 + width);
740
+ // Round 4: a scalar value only — beyond U+10FFFF or a surrogate is not a TOML escape (it threw).
741
+ const cp = width > 0 && new RegExp(`^[0-9a-fA-F]{${width}}$`).test(hex) ? parseInt(hex, 16) : -1;
742
+ if (cp >= 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff)) {
318
743
  i += 1 + width;
319
744
  continue;
320
745
  }
@@ -335,12 +760,3 @@ function unescapeToml(s) {
335
760
  return SIMPLE_ESCAPES[e];
336
761
  });
337
762
  }
338
- /** Parse a TOML inline array of basic strings: `"a", "b"` → ['a','b']. Non-conforming → []. */
339
- function parseTomlStringArray(inner) {
340
- const out = [];
341
- const re = /"((?:[^"\\]|\\.)*)"/g;
342
- let mm;
343
- while ((mm = re.exec(inner)) !== null)
344
- out.push(unescapeToml(mm[1]));
345
- return out;
346
- }