@holmes-lab/holmes-kit 0.35.0 → 0.35.2
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 +108 -0
- package/README.md +7 -0
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/approve.js +9 -2
- package/dist/holmes/cli/codex-oracle.js +36 -2
- package/dist/holmes/cli/doctor.d.ts +14 -1
- package/dist/holmes/cli/doctor.js +355 -72
- package/dist/holmes/cli/index.d.ts +1 -1
- package/dist/holmes/cli/index.js +38 -5
- package/dist/holmes/cli/init.d.ts +2 -0
- package/dist/holmes/cli/init.js +37 -1
- package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
- package/dist/holmes/cli/runtime-binding-approval.js +102 -0
- package/dist/holmes/cli/runtime-binding.d.ts +45 -0
- package/dist/holmes/cli/runtime-binding.js +630 -0
- package/dist/holmes/governance/approval-grants.d.ts +7 -0
- package/dist/holmes/governance/approval-grants.js +8 -2
- package/dist/holmes/governance/approval-queue.d.ts +2 -0
- package/dist/holmes/governance/approval-queue.js +11 -4
- package/dist/holmes/governance/autonomy.d.ts +9 -0
- package/dist/holmes/governance/autonomy.js +65 -13
- package/dist/holmes/guardrail/risk-classifier.js +76 -26
- package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
- package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
- package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
- package/dist/holmes/guardrail/shell-syntax.js +489 -0
- package/dist/holmes/guardrail/shell-words.d.ts +2 -18
- package/dist/holmes/guardrail/shell-words.js +15 -441
- package/dist/holmes/guardrail/write-target.d.ts +54 -0
- package/dist/holmes/guardrail/write-target.js +327 -1
- package/dist/holmes/guardrail/write-verb-word.d.ts +13 -0
- package/dist/holmes/guardrail/write-verb-word.js +55 -0
- package/dist/holmes/hooks/pre-tool-use.d.ts +14 -0
- package/dist/holmes/hooks/pre-tool-use.js +391 -66
- package/dist/holmes/mcp/handlers/spec-approval.js +14 -2
- package/dist/holmes/mcp/handlers.d.ts +9 -1
- package/dist/holmes/mcp/handlers.js +6 -4
- package/dist/holmes/mcp/harness-attestation.d.ts +10 -1
- package/dist/holmes/mcp/harness-attestation.js +70 -3
- package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
- package/dist/holmes/mcp/operator-recovery.js +66 -0
- package/dist/holmes/mcp/server.js +6 -3
- package/dist/holmes/runtime/binding.d.ts +30 -0
- package/dist/holmes/runtime/binding.js +164 -0
- package/dist/holmes/runtime/dispatch.d.ts +9 -0
- package/dist/holmes/runtime/dispatch.js +169 -0
- package/dist/holmes/runtime/hook-process.d.ts +11 -0
- package/dist/holmes/runtime/hook-process.js +130 -0
- package/docs/install-guide.md +65 -0
- package/package.json +1 -1
|
@@ -0,0 +1,209 @@
|
|
|
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.installerInvocationOf = installerInvocationOf;
|
|
37
|
+
exports.shellArgumentRoles = shellArgumentRoles;
|
|
38
|
+
// @implements A-SPEC-753
|
|
39
|
+
const path = __importStar(require("node:path"));
|
|
40
|
+
const shell_syntax_1 = require("./shell-syntax");
|
|
41
|
+
const LIMIT = 256 * 1024;
|
|
42
|
+
const nameOf = (text) => path.posix.basename(text.replace(/\\/g, '/')).replace(/\.exe$/i, '').toLowerCase();
|
|
43
|
+
const certain = (word) => word.known && !word.glob && word.sourceStart !== undefined && word.sourceEnd !== undefined;
|
|
44
|
+
const noValue = new Set(['--json', '--ephemeral', '--skip-git-repo-check', '--strict-config', '--worktree', '--oss']);
|
|
45
|
+
const withValue = new Set(['-m', '--model', '--local-provider', '--color', '--thread-source', '-C', '--cd', '--add-dir', '--output-schema', '-o', '--output-last-message']);
|
|
46
|
+
function mask(source, words) {
|
|
47
|
+
const sorted = words.filter(certain).sort((a, b) => a.sourceStart - b.sourceStart);
|
|
48
|
+
let out = '', at = 0;
|
|
49
|
+
for (const word of sorted) {
|
|
50
|
+
if (word.sourceStart < at)
|
|
51
|
+
continue;
|
|
52
|
+
out += source.slice(at, word.sourceStart) + '__holmes_literal_argument__';
|
|
53
|
+
at = word.sourceEnd;
|
|
54
|
+
}
|
|
55
|
+
return out + source.slice(at);
|
|
56
|
+
}
|
|
57
|
+
function optionValue(words, i) {
|
|
58
|
+
const text = words[i].text;
|
|
59
|
+
const equals = text.indexOf('=');
|
|
60
|
+
if (equals > 0 && withValue.has(text.slice(0, equals)))
|
|
61
|
+
return { option: text.slice(0, equals), value: text.slice(equals + 1), last: i };
|
|
62
|
+
if (/^-[mCo].+/.test(text))
|
|
63
|
+
return { option: text.slice(0, 2), value: text.slice(2), last: i };
|
|
64
|
+
if (!withValue.has(text) || !words[i + 1] || words[i + 1].text.startsWith('-'))
|
|
65
|
+
return null;
|
|
66
|
+
return { option: text, value: words[i + 1].text, last: i + 1 };
|
|
67
|
+
}
|
|
68
|
+
/** Narrow grammar, not a CLI allowlist. Unknown roles retain the untouched command. */
|
|
69
|
+
function codexPrompt(words, base) {
|
|
70
|
+
if (nameOf(words[0]?.text ?? '') !== 'codex' || words[1]?.text !== 'exec' || !words.every(certain))
|
|
71
|
+
return null;
|
|
72
|
+
let prompt, endOptions = false;
|
|
73
|
+
const directories = [], outputs = [];
|
|
74
|
+
for (let i = 2; i < words.length; i++) {
|
|
75
|
+
const word = words[i], text = word.text;
|
|
76
|
+
if (!endOptions && text === '--') {
|
|
77
|
+
endOptions = true;
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
if (!endOptions && noValue.has(text))
|
|
81
|
+
continue;
|
|
82
|
+
if (!endOptions && text.startsWith('-')) {
|
|
83
|
+
const value = optionValue(words, i);
|
|
84
|
+
if (!value || value.value.length === 0)
|
|
85
|
+
return null;
|
|
86
|
+
if (value.option === '-C' || value.option === '--cd')
|
|
87
|
+
directories.push(value.value);
|
|
88
|
+
if (value.option === '-o' || value.option === '--output-last-message')
|
|
89
|
+
outputs.push(value.value);
|
|
90
|
+
i = value.last;
|
|
91
|
+
continue;
|
|
92
|
+
}
|
|
93
|
+
if (prompt || text === '-' || (!endOptions && ['resume', 'fork', 'review', 'help'].includes(text)))
|
|
94
|
+
return null;
|
|
95
|
+
prompt = word;
|
|
96
|
+
}
|
|
97
|
+
// Multiple --cd semantics are not established; no exemption for ambiguous bases.
|
|
98
|
+
if (directories.length > 1 || (!base && outputs.some(p => !path.isAbsolute(p))))
|
|
99
|
+
return null;
|
|
100
|
+
const bases = base ? [base, ...directories.map(p => path.resolve(base, p))] : [];
|
|
101
|
+
return { prompt, outputs: outputs.flatMap(p => path.isAbsolute(p) ? [p] : bases.map(b => path.resolve(b, p))) };
|
|
102
|
+
}
|
|
103
|
+
function searchData(words) {
|
|
104
|
+
if (!['rg', 'grep', 'egrep', 'fgrep'].includes(nameOf(words[0]?.text ?? '')) || !words.every(certain))
|
|
105
|
+
return [];
|
|
106
|
+
const flags = /^(?:-[nrilHEFsvwox]+|--hidden|--line-number|--files-with-matches|--ignore-case|--fixed-strings)$/;
|
|
107
|
+
for (let i = 1; i < words.length; i++) {
|
|
108
|
+
const text = words[i].text;
|
|
109
|
+
if (flags.test(text))
|
|
110
|
+
continue;
|
|
111
|
+
if (text.startsWith('-'))
|
|
112
|
+
return [];
|
|
113
|
+
// Unknown options anywhere may introduce executable behavior, e.g. rg --pre.
|
|
114
|
+
if (words.slice(i + 1).some(w => w.text.startsWith('-')))
|
|
115
|
+
return [];
|
|
116
|
+
return [words[i]];
|
|
117
|
+
}
|
|
118
|
+
return [];
|
|
119
|
+
}
|
|
120
|
+
const INSTALLER_VALUED = new Set(['--workspace', '--package', '--release-package', '--registry', '--activate-hooks']);
|
|
121
|
+
/** The documented installer grammar over one command's words: its package operands and whether it only previews. */
|
|
122
|
+
function installerWords(words, operations, everySpelling = false) {
|
|
123
|
+
if (!words.every(certain))
|
|
124
|
+
return null;
|
|
125
|
+
// Node argv may itself be a runner's program. Only the documented Holmes setup grammar
|
|
126
|
+
// establishes data roles here; arbitrary scripts, startup options and runner CLIs retain text.
|
|
127
|
+
let at;
|
|
128
|
+
if (['node', 'nodejs'].includes(nameOf(words[0]?.text ?? ''))) {
|
|
129
|
+
if (!/(?:^|\/)bin\/holmes-kit\.js$/.test((words[1]?.text ?? '').replace(/\\/g, '/')))
|
|
130
|
+
return null;
|
|
131
|
+
at = 2;
|
|
132
|
+
}
|
|
133
|
+
else if (everySpelling && installerBinName(words[0]?.text ?? '') === 'holmes-kit') {
|
|
134
|
+
// @implements A-SPEC-753.2 — the installed bin is the same program under another spelling.
|
|
135
|
+
at = 1;
|
|
136
|
+
}
|
|
137
|
+
else
|
|
138
|
+
return null;
|
|
139
|
+
if (words[at]?.text !== 'runtime-binding' || !operations.includes(words[at + 1]?.text ?? ''))
|
|
140
|
+
return null;
|
|
141
|
+
const data = [];
|
|
142
|
+
let preview = false;
|
|
143
|
+
for (let i = at + 2; i < words.length; i++) {
|
|
144
|
+
const flag = words[i].text;
|
|
145
|
+
if (flag === '--dry-run') {
|
|
146
|
+
preview = true;
|
|
147
|
+
continue;
|
|
148
|
+
}
|
|
149
|
+
// @implements A-SPEC-753.2 — `--name=value` is the spelling the CLI also accepts; an empty value is not the grammar.
|
|
150
|
+
const eq = everySpelling ? flag.indexOf('=') : -1;
|
|
151
|
+
if (eq !== -1) {
|
|
152
|
+
if (!INSTALLER_VALUED.has(flag.slice(0, eq)) || eq === flag.length - 1)
|
|
153
|
+
return null;
|
|
154
|
+
continue;
|
|
155
|
+
}
|
|
156
|
+
if (!INSTALLER_VALUED.has(flag) || !words[i + 1] || words[i + 1].text.startsWith('-'))
|
|
157
|
+
return null;
|
|
158
|
+
const value = words[++i];
|
|
159
|
+
if (flag === '--package' || flag === '--release-package')
|
|
160
|
+
data.push(value);
|
|
161
|
+
}
|
|
162
|
+
return { data, preview };
|
|
163
|
+
}
|
|
164
|
+
/** The last path segment of a command word without a Windows launcher suffix. */
|
|
165
|
+
function installerBinName(text) {
|
|
166
|
+
const base = text.replace(/\\/g, '/').split('/').pop() ?? '';
|
|
167
|
+
const lower = base.toLowerCase();
|
|
168
|
+
return lower.endsWith('.cmd') || lower.endsWith('.exe') ? base.slice(0, -4) : base;
|
|
169
|
+
}
|
|
170
|
+
/** A-SPEC-753.2 rule 4: the data-role masking stays with the measured `node …` preview spelling. */
|
|
171
|
+
function nodeData(words) {
|
|
172
|
+
const installer = installerWords(words, ['setup']);
|
|
173
|
+
return installer?.preview ? installer.data : [];
|
|
174
|
+
}
|
|
175
|
+
/** @implements A-SPEC-753.2 — a longer command, or one with a line break, is not the installer grammar. */
|
|
176
|
+
const INSTALLER_COMMAND_MAX = 4096;
|
|
177
|
+
/**
|
|
178
|
+
* @implements A-SPEC-753.1 — whether a command is the documented installer, and whether it applies or only previews.
|
|
179
|
+
* Measured 2026-10-04: the apply form was refused as a server start (A-SPEC-732), which it is not; the caller needs to
|
|
180
|
+
* know the act to name it. One command, every word certain, no substitution and no redirect — anything else is null.
|
|
181
|
+
*/
|
|
182
|
+
function installerInvocationOf(command, cwd = null) {
|
|
183
|
+
if (command.length > LIMIT || command.length > INSTALLER_COMMAND_MAX || command.includes('\n') || command.includes('\r'))
|
|
184
|
+
return null;
|
|
185
|
+
const parsed = (0, shell_syntax_1.shellWords)(command, process.env, undefined, cwd, true);
|
|
186
|
+
if (parsed.overflow || parsed.subs.length || parsed.commands.length !== 1 || parsed.commands[0].redirects.length > 0)
|
|
187
|
+
return null;
|
|
188
|
+
const installer = installerWords(parsed.commands[0].words, ['setup', 'remove'], true);
|
|
189
|
+
return installer === null ? null : installer.preview ? 'preview' : 'apply';
|
|
190
|
+
}
|
|
191
|
+
function shellArgumentRoles(command, cwd = null) {
|
|
192
|
+
const original = { governanceText: command, serverText: command, outputPaths: [] };
|
|
193
|
+
if (command.length > LIMIT)
|
|
194
|
+
return original;
|
|
195
|
+
const parsed = (0, shell_syntax_1.shellWords)(command, process.env, undefined, cwd, true);
|
|
196
|
+
// A nested shell or substitution retains its complete original text. No flattened reparse can
|
|
197
|
+
// turn its executable payload into an inert argument. Unknown syntax likewise receives no mask.
|
|
198
|
+
if (parsed.overflow || parsed.subs.length || parsed.commands.some(c => !c.words.every(certain) || c.redirects.some(w => !certain(w))))
|
|
199
|
+
return original;
|
|
200
|
+
const serverData = parsed.commands.flatMap(c => [...searchData(c.words), ...nodeData(c.words)]);
|
|
201
|
+
// CLI path bases are currently certain only for a direct single invocation. Shell cd/wrappers
|
|
202
|
+
// keep existing conservative policy until their bases are explicitly modeled.
|
|
203
|
+
const codex = parsed.commands.length === 1 ? codexPrompt(parsed.commands[0].words, cwd) : null;
|
|
204
|
+
return {
|
|
205
|
+
governanceText: codex?.prompt ? mask(command, [codex.prompt]) : command,
|
|
206
|
+
serverText: mask(command, serverData),
|
|
207
|
+
outputPaths: codex?.outputs ?? [],
|
|
208
|
+
};
|
|
209
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
export interface Word {
|
|
2
|
+
text: string;
|
|
3
|
+
known: boolean;
|
|
4
|
+
glob: boolean;
|
|
5
|
+
sourceStart?: number;
|
|
6
|
+
sourceEnd?: number;
|
|
7
|
+
}
|
|
8
|
+
export interface SimpleCommand {
|
|
9
|
+
words: Word[];
|
|
10
|
+
redirects: Word[];
|
|
11
|
+
}
|
|
12
|
+
/** Bodies of `$(…)`, backticks and `<(…)`/`>(…)`: they RUN, so they are judged as commands too. */
|
|
13
|
+
export interface ParsedSegment {
|
|
14
|
+
commands: SimpleCommand[];
|
|
15
|
+
subs: string[];
|
|
16
|
+
overflow: boolean;
|
|
17
|
+
}
|
|
18
|
+
export declare function shellWords(src: string, env?: NodeJS.ProcessEnv, home?: string, pwd?: string | null, sourceRanges?: boolean): SimpleCommand & ParsedSegment;
|
|
19
|
+
/** The words from the real command word on, behind wrappers, assignments and grouping keywords. */
|
|
20
|
+
export declare function commandOf(input: Word[]): Word[];
|