@holmes-lab/holmes-kit 0.30.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.
- package/CHANGELOG.md +494 -0
- package/README.md +10 -1
- package/bin/holmes-hook-antigravity.js +4 -0
- package/bin/holmes-kit.js +4 -0
- package/bin/holmes-pre-push.js +3 -0
- package/bin/holmes-stop-antigravity.js +4 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/agents.d.ts +41 -0
- package/dist/holmes/cli/agents.js +382 -2
- package/dist/holmes/cli/attest.d.ts +2 -0
- package/dist/holmes/cli/attest.js +66 -15
- package/dist/holmes/cli/ci-gate.js +16 -1
- package/dist/holmes/cli/claude-switches.d.ts +95 -0
- package/dist/holmes/cli/claude-switches.js +967 -0
- package/dist/holmes/cli/codex-hooks.d.ts +77 -0
- package/dist/holmes/cli/codex-hooks.js +802 -0
- package/dist/holmes/cli/codex-oracle.d.ts +194 -0
- package/dist/holmes/cli/codex-oracle.js +1245 -0
- package/dist/holmes/cli/codex-toml.d.ts +35 -0
- package/dist/holmes/cli/codex-toml.js +321 -52
- package/dist/holmes/cli/doctor.d.ts +98 -8
- package/dist/holmes/cli/doctor.js +1328 -94
- package/dist/holmes/cli/index.js +23 -11
- package/dist/holmes/cli/init.d.ts +11 -0
- package/dist/holmes/cli/init.js +736 -44
- package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
- package/dist/holmes/cli/mcp-launcher.js +189 -6
- package/dist/holmes/cli/mcp-version.js +13 -2
- package/dist/holmes/cli/settings-merge.js +8 -2
- package/dist/holmes/cli/upgrade.d.ts +13 -0
- package/dist/holmes/cli/upgrade.js +116 -23
- package/dist/holmes/cli/workspace-scope.d.ts +22 -0
- package/dist/holmes/cli/workspace-scope.js +375 -0
- package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
- package/dist/holmes/cpg/cpg-scanner.js +403 -3
- package/dist/holmes/cpg/cycle-detect.js +2 -1
- package/dist/holmes/cpg/forbidden-edges.js +9 -2
- package/dist/holmes/cpg/required-calls.js +8 -1
- package/dist/holmes/governance/constitution-debt.js +3 -2
- package/dist/holmes/governance/constitution.js +15 -3
- package/dist/holmes/governance/provenance-chain.js +3 -2
- package/dist/holmes/governance/push-gate-runner.js +4 -3
- package/dist/holmes/guardrail/dependency-delta.js +4 -3
- package/dist/holmes/guardrail/linear-match.d.ts +57 -0
- package/dist/holmes/guardrail/linear-match.js +256 -0
- package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
- package/dist/holmes/guardrail/risk-classifier.js +931 -44
- package/dist/holmes/guardrail/risk-types.d.ts +6 -0
- package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
- package/dist/holmes/guardrail/scope-judgment.js +100 -23
- package/dist/holmes/guardrail/shell-words.d.ts +42 -0
- package/dist/holmes/guardrail/shell-words.js +1720 -0
- package/dist/holmes/guardrail/write-target.d.ts +168 -3
- package/dist/holmes/guardrail/write-target.js +2379 -87
- package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
- package/dist/holmes/hooks/adapters/antigravity.js +115 -11
- package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
- package/dist/holmes/hooks/pre-tool-use.js +923 -87
- package/dist/holmes/hooks/rtm-refresh-child.js +3 -1
- package/dist/holmes/hooks/rtm-refresh.js +8 -4
- package/dist/holmes/hooks/session-start.d.ts +10 -0
- package/dist/holmes/hooks/session-start.js +31 -7
- package/dist/holmes/hooks/stop.d.ts +2 -1
- package/dist/holmes/hooks/stop.js +197 -91
- package/dist/holmes/mcp/approval-commit.d.ts +5 -6
- package/dist/holmes/mcp/approval-commit.js +18 -2
- package/dist/holmes/mcp/elicit-approval.js +4 -2
- package/dist/holmes/mcp/handlers/graph-operations.js +3 -2
- package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
- package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
- package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
- package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
- package/dist/holmes/mcp/handlers/requirement-triage.js +5 -3
- package/dist/holmes/mcp/handlers/review-evidence.js +8 -2
- package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +11 -0
- package/dist/holmes/mcp/handlers/slice-orchestration.js +115 -16
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +9 -0
- package/dist/holmes/mcp/handlers/spec-approval.js +110 -17
- package/dist/holmes/mcp/handlers/spec-authoring.js +17 -2
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
- package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
- package/dist/holmes/mcp/handlers/test-execution.js +9 -3
- package/dist/holmes/mcp/handlers.d.ts +81 -9
- package/dist/holmes/mcp/handlers.js +70 -23
- package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
- package/dist/holmes/mcp/harness-attestation.js +179 -0
- package/dist/holmes/mcp/requirement-triage-evidence.d.ts +36 -0
- package/dist/holmes/mcp/requirement-triage-evidence.js +160 -4
- package/dist/holmes/mcp/server.js +20 -1
- package/dist/holmes/mcp/tool-schemas.js +26 -9
- package/dist/holmes/mcp/validate-args.js +12 -0
- package/dist/holmes/project/bounded-io.d.ts +102 -0
- package/dist/holmes/project/bounded-io.js +212 -0
- package/dist/holmes/project/change-source.js +3 -1
- package/dist/holmes/project/ci-runs.js +3 -2
- package/dist/holmes/project/ignore.d.ts +31 -2
- package/dist/holmes/project/ignore.js +409 -50
- package/dist/holmes/project/regular-file-guard.d.ts +13 -0
- package/dist/holmes/project/regular-file-guard.js +149 -0
- package/dist/holmes/project/root.js +12 -3
- package/dist/holmes/reverse/anchor.js +4 -3
- package/dist/holmes/reverse/scan.js +6 -2
- package/dist/holmes/review/commit-text.js +3 -2
- package/dist/holmes/review/condition-hunk-replay.js +3 -2
- package/dist/holmes/review/failed-test-names.js +13 -10
- package/dist/holmes/review/findings.js +3 -1
- package/dist/holmes/review/kills-check.js +6 -1
- package/dist/holmes/review/point-in-time-replay.js +5 -4
- package/dist/holmes/review/replay-corpus.js +5 -4
- package/dist/holmes/review/run-replay.js +3 -2
- package/dist/holmes/review/temporal-prior.js +3 -2
- package/dist/holmes/review/test-evidence.js +3 -2
- package/dist/holmes/review/test-outcomes.js +3 -2
- package/dist/holmes/review/test-runner.d.ts +6 -0
- package/dist/holmes/review/test-runner.js +36 -15
- package/dist/holmes/rtm/advisory-outcomes.js +3 -2
- package/dist/holmes/rtm/anchor-ids.js +42 -2
- package/dist/holmes/rtm/file-anchors.js +4 -1
- package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
- package/dist/holmes/rtm/git-changes.js +3 -1
- package/dist/holmes/rtm/graph-store.js +3 -2
- package/dist/holmes/rtm/test-scope.js +9 -4
- package/dist/holmes/spec/compat-impact.d.ts +25 -4
- package/dist/holmes/spec/compat-impact.js +682 -11
- package/dist/holmes/spec/entity-git-snapshot.js +3 -2
- package/dist/holmes/spec/entity-integration.js +3 -2
- package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
- package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
- package/dist/holmes/spec/remote-spec-refs.js +3 -2
- package/dist/holmes/spec/renumber.js +25 -10
- package/dist/holmes/spec/spec-parser.js +9 -3
- package/dist/holmes/spec/yaml-scalar.js +2 -2
- package/dist/holmes/update/refresh.js +3 -1
- package/dist/holmes/update/update-notice.d.ts +6 -0
- package/dist/holmes/update/update-notice.js +18 -1
- package/package.json +11 -4
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
/** How to start codex: a command, leading arguments, whether it is a Windows shell shim, and (tests
|
|
2
|
+
* only) extra environment for it — the child otherwise sees an allowlist, never the caller's env. */
|
|
3
|
+
export interface CodexCommand {
|
|
4
|
+
command: string;
|
|
5
|
+
args: string[];
|
|
6
|
+
shell?: boolean;
|
|
7
|
+
env?: Record<string, string>;
|
|
8
|
+
}
|
|
9
|
+
export type FoundCodex = {
|
|
10
|
+
found: true;
|
|
11
|
+
codex: CodexCommand;
|
|
12
|
+
} | {
|
|
13
|
+
found: false;
|
|
14
|
+
reason: string;
|
|
15
|
+
};
|
|
16
|
+
export interface CodexHookSeen {
|
|
17
|
+
event: string;
|
|
18
|
+
command?: string;
|
|
19
|
+
matcher: string | null;
|
|
20
|
+
enabled: boolean;
|
|
21
|
+
}
|
|
22
|
+
export type CodexVerdict = {
|
|
23
|
+
available: true;
|
|
24
|
+
configError: string | null;
|
|
25
|
+
holmesTable: Record<string, unknown> | null;
|
|
26
|
+
hookErrors: string[];
|
|
27
|
+
hooks: CodexHookSeen[];
|
|
28
|
+
otherHookProblems?: string[];
|
|
29
|
+
/** A refusal Codex attributes to ANOTHER layer (a trusted project's .codex/config.toml): nothing loads in this workspace, but the user file is not at fault. */
|
|
30
|
+
otherConfigError?: string;
|
|
31
|
+
/** A-SPEC-738 (round 13): other `[mcp_servers.*]` entries that run a Holmes server (their own environment).
|
|
32
|
+
* Round 14: also every other enabled entry handed a `HOLMES_*` authority key; `holmes` says whether it
|
|
33
|
+
* was recognised as a Holmes server (absent = recognised). */
|
|
34
|
+
otherHolmesServers?: Array<{
|
|
35
|
+
name: string;
|
|
36
|
+
table: Record<string, unknown>;
|
|
37
|
+
holmes?: boolean;
|
|
38
|
+
}>;
|
|
39
|
+
} | {
|
|
40
|
+
available: false;
|
|
41
|
+
reason: string;
|
|
42
|
+
};
|
|
43
|
+
export interface AskCodexInput {
|
|
44
|
+
codex: CodexCommand;
|
|
45
|
+
/** The bytes as they are on disk (a BOM or a bare CR must reach Codex unchanged); null = no file. */
|
|
46
|
+
configBytes: Buffer | null;
|
|
47
|
+
hooksBytes: Buffer | null;
|
|
48
|
+
/** The target directory: project config layers and hooks are resolved from here. */
|
|
49
|
+
cwd: string;
|
|
50
|
+
timeoutMs?: number;
|
|
51
|
+
/** The user's real paths: messages quote these instead of the temporary copies. */
|
|
52
|
+
realConfigPath?: string;
|
|
53
|
+
realHooksPath?: string;
|
|
54
|
+
}
|
|
55
|
+
/** The MCP tools the governance procedure cannot do without (a table that disables one hollows the gate). */
|
|
56
|
+
export declare const GATE_TOOLS: readonly string[];
|
|
57
|
+
/**
|
|
58
|
+
* @implements A-SPEC-738 (round 12) — the gate tools a `[mcp_servers.holmes-kit]` table takes away: a
|
|
59
|
+
* `disabled_tools` naming one, or a non-empty `enabled_tools` lacking one (measured: a trusted layer's
|
|
60
|
+
* `disabled_tools` covering every Holmes tool passed doctor as "resolves"). Null when none.
|
|
61
|
+
*/
|
|
62
|
+
export declare function hollowedGateTools(table: Record<string, unknown> | null): string | null;
|
|
63
|
+
/**
|
|
64
|
+
* @implements A-SPEC-738 (round 13) — the server-environment variables that carry AUTHORITY: an approval
|
|
65
|
+
* key, autonomy, a ledger key, a role or profile, or a switch that weakens or bypasses the gate.
|
|
66
|
+
*/
|
|
67
|
+
export declare const AUTHORITY_ENV: readonly string[];
|
|
68
|
+
/**
|
|
69
|
+
* @implements A-SPEC-738 (round 14) — the egress-consent keys: the product treats the key AS consent to send
|
|
70
|
+
* data out (`semantic/credentials.ts`), the class of HOLMES_ROLE. The generic spellings count only on a
|
|
71
|
+
* Holmes server (another server may need its own Gemini key); the dedicated one counts everywhere.
|
|
72
|
+
*/
|
|
73
|
+
export declare const CONSENT_ENV: readonly string[];
|
|
74
|
+
/** Named in findings for an `env_vars` entry in neither form: unjudgeable, so it counts as authority. */
|
|
75
|
+
export declare const UNREADABLE_ENV_VAR = "an env_vars entry the oracle cannot read";
|
|
76
|
+
/** Whether a `[mcp_servers.*]` table runs a Holmes server, read from its words alone (every word, no cap). */
|
|
77
|
+
export declare function runsHolmesServer(t: Record<string, unknown>): boolean;
|
|
78
|
+
/**
|
|
79
|
+
* @implements A-SPEC-738 (round 15) — the two launches init writes: `node <path>/bin/holmes-mcp.js` (that one
|
|
80
|
+
* argument) and `npx -y -p @holmes-lab/holmes-kit@<version> holmes-mcp`. Anything else — an `env` wrapper,
|
|
81
|
+
* `--env-file`, `-r`/`--import`/`-e`, a shell `-c`, an extra argument — can set the server's environment.
|
|
82
|
+
*/
|
|
83
|
+
export declare function canonicalHolmesLaunch(t: Record<string, unknown>): boolean;
|
|
84
|
+
/** Round 18: one value in a message, clipped (a 900 KB env key made a 900 KB WARN — measured). */
|
|
85
|
+
/**
|
|
86
|
+
* @implements A-SPEC-251.2 (round 45) — a value from a file, clipped and made safe to print: a newline in a wiring value printed a
|
|
87
|
+
* forged `PASS` line (measured); control, line-separator and bidirectional characters are escaped.
|
|
88
|
+
*/
|
|
89
|
+
export declare const escapeForDisplay: (s: string) => string;
|
|
90
|
+
export declare const clipText: (s: string, max?: number) => string;
|
|
91
|
+
/**
|
|
92
|
+
* Round 17: a list for one message line — ten items, then a count (a 1 MB layer produced a 1.5 MB line — measured).
|
|
93
|
+
* @implements A-SPEC-738 (round 18) — each item clipped too (one second server's 40,000 keys were one 2.2 MB item).
|
|
94
|
+
*/
|
|
95
|
+
export declare function cappedList(items: readonly string[], max?: number): string;
|
|
96
|
+
/**
|
|
97
|
+
* @implements A-SPEC-738 (round 18) — the user file's OWN launch spelled as a path to `node`/`npx` or with
|
|
98
|
+
* `.exe`/`.cmd` is node/npx to doctor (the user's `/opt/homebrew/bin/node` was FAIL "does not run holmes-mcp" —
|
|
99
|
+
* measured). A layer's launch stays canonical only when bare (round 17).
|
|
100
|
+
*/
|
|
101
|
+
export declare function launcherBase(command: string): 'node' | 'npx' | null;
|
|
102
|
+
/** A launch as one line for a message, clipped (a 1 MiB argument list must not flood doctor). */
|
|
103
|
+
export declare function launchText(t: Record<string, unknown>): string;
|
|
104
|
+
/** The user file's own `[mcp_servers.<name>]` table (default `holmes-kit`), or null. */
|
|
105
|
+
export declare function ownHolmesTableOf(configText: string | null, name?: string): Record<string, unknown> | null;
|
|
106
|
+
/**
|
|
107
|
+
* @implements A-SPEC-738 (round 13) — the effective table's `env` and `env_vars` against the user file's own
|
|
108
|
+
* table. Codex deep-merges a trusted layer's env keys (measured: a layer's `HOLMES_APPROVAL` and
|
|
109
|
+
* `HOLMES_AUTONOMOUS_APPROVAL` reached the server while doctor said PASS). Keys the user file carries with
|
|
110
|
+
* the same value are OWN; the rest came from another layer.
|
|
111
|
+
* @implements A-SPEC-738 (round 14) — `env_vars` entries in both forms (a table form passed as PASS), keys
|
|
112
|
+
* without case, the consent keys (`holmes`: whether the generic spellings count), and any other name an
|
|
113
|
+
* `env_vars` forwards is an added key (WARN), never authority.
|
|
114
|
+
*/
|
|
115
|
+
/**
|
|
116
|
+
* @implements A-SPEC-738 (round 16) — the install a layer's node launch must resolve to, and the shared cap on
|
|
117
|
+
* how many launches one run resolves (the overflow is a FAIL, never a pass).
|
|
118
|
+
*/
|
|
119
|
+
export interface InstallCheck {
|
|
120
|
+
bin: string | null;
|
|
121
|
+
budget: {
|
|
122
|
+
left: number;
|
|
123
|
+
}; /** Round 18: the version a layer's npx pin must name. */
|
|
124
|
+
version?: string | null;
|
|
125
|
+
}
|
|
126
|
+
export declare const INSTALL_CHECKS_MAX = 64;
|
|
127
|
+
/** Round 16: a launch as Codex runs it — an absent `args` is `[]` (the user's own `command = "holmes-mcp"` read as a layer's). */
|
|
128
|
+
export declare const launchKey: (t: Record<string, unknown>) => string;
|
|
129
|
+
/** Why a layer's canonical node launch is not this install's, or null when it is (or the caller knows no install). */
|
|
130
|
+
/**
|
|
131
|
+
* @implements A-SPEC-738 (round 17) — the only paths the oracle's callers open to check an install: a drive-letter
|
|
132
|
+
* path or a `/` path. `\\?\`, `\??\`, `//`, `\\` (network or device namespaces) and `/net/` (an automounter root)
|
|
133
|
+
* are never opened — opening them can contact another host.
|
|
134
|
+
*/
|
|
135
|
+
export declare function openableLocalPath(p: string): boolean;
|
|
136
|
+
/**
|
|
137
|
+
* @implements A-SPEC-738 (round 18) — a path resolved one component at a time: a link is followed only when its
|
|
138
|
+
* target is itself an openable local path, so no network, device or automounter path is ever looked up (a
|
|
139
|
+
* workspace link to `/net/<host>` reached `realpath` — measured). `refused`: such a path was met; `path`: the
|
|
140
|
+
* real path, null when the file is missing.
|
|
141
|
+
*/
|
|
142
|
+
/** Round 19: no system opens a longer path (PATH_MAX); walking one is only cost (a 1 MB path took 47.9 s — measured). */
|
|
143
|
+
export declare const MAX_LAUNCH_PATH = 4096;
|
|
144
|
+
/**
|
|
145
|
+
* @implements A-SPEC-251.2 (round 43) — one walk follows at most this many components: 40 links of 300 components each made
|
|
146
|
+
* every walk ~12,000 look-ups, and 1,000 committed gate entries held doctor for 106 s (measured). Past it the walk is
|
|
147
|
+
* `exhausted` — not confirmed, never "missing".
|
|
148
|
+
*/
|
|
149
|
+
export declare const MAX_WALK_STEPS = 4096;
|
|
150
|
+
export declare function localRealpath(p: string): {
|
|
151
|
+
path: string | null;
|
|
152
|
+
refused: boolean;
|
|
153
|
+
exhausted?: true;
|
|
154
|
+
};
|
|
155
|
+
export declare function envFindings(effective: Record<string, unknown> | null, own: Record<string, unknown> | null, holmes?: boolean, install?: InstallCheck): {
|
|
156
|
+
authorityFromLayer: string[];
|
|
157
|
+
authorityOwn: string[];
|
|
158
|
+
addedFromLayer: string[];
|
|
159
|
+
envVarsFromLayer: string[];
|
|
160
|
+
envVarsOwn: string[];
|
|
161
|
+
};
|
|
162
|
+
/** Authority a server's own table carries (env keys or `env_vars` entries of the authority class). */
|
|
163
|
+
export declare function serverAuthority(t: Record<string, unknown>, holmes?: boolean): string[];
|
|
164
|
+
/**
|
|
165
|
+
* The effective table's settings that bind the spec store elsewhere: `env.HOLMES_SPECS` and (round 14)
|
|
166
|
+
* `env.CLAUDE_PROJECT_DIR`, which `resolveServerSpecsDir` reads, and `cwd`.
|
|
167
|
+
* @implements A-SPEC-738 (round 14) — a relative HOLMES_SPECS redirects too (measured: the store bound to
|
|
168
|
+
* `<project>/vendor/decoy/.ax/specs`); only the default `.ax/specs` and the user file's own value are not.
|
|
169
|
+
*/
|
|
170
|
+
export declare function tableRedirection(table: Record<string, unknown> | null, own?: Record<string, unknown> | null): {
|
|
171
|
+
specs: string | null;
|
|
172
|
+
cwd: string | null;
|
|
173
|
+
projectDir: string | null;
|
|
174
|
+
};
|
|
175
|
+
/**
|
|
176
|
+
* @implements A-SPEC-738 (round 6) — the layer file a refusal names (a path ending in `.codex/config.toml`,
|
|
177
|
+
* spaces included), or null when it names none: doctor's fix line points at it, not at the user file.
|
|
178
|
+
*/
|
|
179
|
+
export declare function layerFileNamed(message: string): string | null;
|
|
180
|
+
/** A PreToolUse command Codex lists that runs the Holmes pre-tool kernel (any quoting). */
|
|
181
|
+
export declare function isHolmesPreToolCommand(command: string | undefined): boolean;
|
|
182
|
+
/**
|
|
183
|
+
* @implements A-SPEC-738 (round 2, shared in round 5) — whether the user config's `[hooks.state]` disables
|
|
184
|
+
* the Holmes PreToolUse hook of `hooksText`. The state is keyed by the REAL hooks path, so a copy cannot
|
|
185
|
+
* show it (measured); init and doctor both read it here (round 5: init said "wired" while doctor FAILed).
|
|
186
|
+
* Only the Holmes group's own `pre_tool_use:<i>:<j>` counts; case-insensitive on Windows.
|
|
187
|
+
*/
|
|
188
|
+
export declare function holmesPreToolDisabled(configText: string | null, hooksText: string | null, hooksPath: string): boolean;
|
|
189
|
+
/** The first `codex` on PATH (PATHEXT on Windows), unless the oracle is switched off. */
|
|
190
|
+
export declare function findCodex(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): FoundCodex;
|
|
191
|
+
/** The worker source, for tests that drive it directly (A-SPEC-738 round 4: its signal handling). */
|
|
192
|
+
export declare const ORACLE_WORKER_SOURCE: string;
|
|
193
|
+
/** Ask the installed Codex whether these files load. Synchronous; never throws. */
|
|
194
|
+
export declare function askCodex(input: AskCodexInput): CodexVerdict;
|