@holmes-lab/holmes-kit 0.35.24 → 0.35.25
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 +65 -0
- package/README.md +3 -2
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/approve.js +4 -4
- package/dist/holmes/cli/doctor.d.ts +6 -0
- package/dist/holmes/cli/doctor.js +52 -1
- package/dist/holmes/cli/index.js +17 -1
- package/dist/holmes/cli/runtime-binding-approval.js +3 -2
- package/dist/holmes/cli/runtime-binding.js +21 -5
- package/dist/holmes/cli/scratch.d.ts +12 -0
- package/dist/holmes/cli/scratch.js +20 -0
- package/dist/holmes/governance/approval-queue.js +4 -3
- package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
- package/dist/holmes/guardrail/impact-gate.js +34 -11
- package/dist/holmes/guardrail/risk-classifier.js +14 -2
- package/dist/holmes/guardrail/risk-types.d.ts +1 -0
- package/dist/holmes/hooks/pre-tool-use.d.ts +1 -1
- package/dist/holmes/hooks/pre-tool-use.js +40 -2
- package/dist/holmes/hooks/stop.d.ts +3 -1
- package/dist/holmes/hooks/stop.js +14 -4
- package/dist/holmes/mcp/elicit-approval.js +4 -4
- package/dist/holmes/mcp/handlers/spec-approval.js +3 -2
- package/dist/holmes/project/npx-bin.d.ts +26 -0
- package/dist/holmes/project/npx-bin.js +272 -2
- package/dist/holmes/project/scratch-root.d.ts +12 -0
- package/dist/holmes/project/scratch-root.js +132 -0
- package/dist/holmes/runtime/dispatch.js +6 -3
- package/package.json +1 -1
|
@@ -3,7 +3,7 @@ import { PatchTarget } from '../guardrail/write-target';
|
|
|
3
3
|
import { Approval } from '../guardrail/risk-gate';
|
|
4
4
|
import { RiskAction, RiskAssessment, RmSignal } from '../guardrail/risk-types';
|
|
5
5
|
import { type PreEditEvidenceMode } from '../guardrail/impact-gate';
|
|
6
|
-
export declare function resolveRmSignals(command: string, cwd: string, projectRoot?: string, specsDir?: string): Record<string, RmSignal> | undefined;
|
|
6
|
+
export declare function resolveRmSignals(command: string, cwd: string, projectRoot?: string, specsDir?: string, scratchTmpdir?: string): Record<string, RmSignal> | undefined;
|
|
7
7
|
/**
|
|
8
8
|
* @implements A-SPEC-149
|
|
9
9
|
* The out-of-band approval channel, read at the ENTRY only. `evaluateHook` no longer calls this on
|
|
@@ -48,7 +48,7 @@ exports.gateErrorDecision = gateErrorDecision;
|
|
|
48
48
|
exports.wiredSpecsDir = wiredSpecsDir;
|
|
49
49
|
exports.evaluateHook = evaluateHook;
|
|
50
50
|
exports.readSpecsSync = readSpecsSync;
|
|
51
|
-
// @implements A-SPEC-753.3, A-SPEC-
|
|
51
|
+
// @implements A-SPEC-753.3, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-134.2,A-SPEC-278,A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7, A-SPEC-768.2, A-SPEC-772.1
|
|
52
52
|
const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
|
|
53
53
|
// @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
|
|
54
54
|
// evaluateHook in this file to prove it.
|
|
@@ -57,6 +57,7 @@ const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
|
|
|
57
57
|
// @implements A-SPEC-194, A-SPEC-195
|
|
58
58
|
const registry_1 = require("../messages/registry");
|
|
59
59
|
const root_1 = require("../project/root");
|
|
60
|
+
const scratch_root_1 = require("../project/scratch-root");
|
|
60
61
|
const fs = __importStar(require("node:fs"));
|
|
61
62
|
const path = __importStar(require("node:path"));
|
|
62
63
|
const os = __importStar(require("node:os"));
|
|
@@ -119,7 +120,44 @@ function unanswered(targets) {
|
|
|
119
120
|
}
|
|
120
121
|
return Object.keys(out).length ? out : undefined;
|
|
121
122
|
}
|
|
122
|
-
|
|
123
|
+
/**
|
|
124
|
+
* @implements A-SPEC-773 — the git signals, plus `scratch: true` for each literal absolute target whose real path lies
|
|
125
|
+
* strictly under the trusted Holmes scratch root (owner decision 2026-10-17). Added whether or not the cwd is in a
|
|
126
|
+
* repository; the trust check runs once per call. `scratchTmpdir` is the temporary directory to read the root under
|
|
127
|
+
* (tests; the hook passes nothing and reads os.tmpdir()).
|
|
128
|
+
*/
|
|
129
|
+
/** `rm`, option words, an optional `--`, then absolute targets — no separator, redirection, expansion or escape. */
|
|
130
|
+
const SCRATCH_TARGETS_MAX = 64;
|
|
131
|
+
const PLAIN_RM = /^rm(?:[ \t]+-[A-Za-z]+)*(?:[ \t]+--)?(?:[ \t]+\/[A-Za-z0-9._/-]+)+$/;
|
|
132
|
+
function resolveRmSignals(command, cwd, projectRoot, specsDir, scratchTmpdir) {
|
|
133
|
+
const signals = gitRmSignals(command, cwd, projectRoot, specsDir);
|
|
134
|
+
// @implements A-SPEC-773.1 — only a command that IS one plain rm. Round 1 (2026-10-17): `xargs`/`parallel` add
|
|
135
|
+
// targets at run time, an alias does, and a link or move earlier in the same command changes the real path after it
|
|
136
|
+
// was judged — 15 harmful commands were allowed with the root and refused without it.
|
|
137
|
+
if (!PLAIN_RM.test(command.trim()))
|
|
138
|
+
return signals;
|
|
139
|
+
const absolute = [...new Set([...(0, risk_classifier_1.rmCommandTargets)(command), ...(0, risk_classifier_1.rmCommandTargets)((0, write_target_1.joinShellText)(command))])]
|
|
140
|
+
.filter((raw) => { const t = raw.replace(/^["']/, '').replace(/["']$/, ''); return path.isAbsolute(t) && !/[^A-Za-z0-9._/-]/.test(t) && !t.split('/').includes('..'); });
|
|
141
|
+
// @implements A-SPEC-773.2 — bounded like the git signals (round 8 of A-SPEC-728): at most 64 targets, each at most
|
|
142
|
+
// 4,096 characters and 256 components; past that, no target gets the signal and today's verdict stands.
|
|
143
|
+
if (absolute.length === 0 || absolute.length > SCRATCH_TARGETS_MAX)
|
|
144
|
+
return signals;
|
|
145
|
+
if (absolute.some((t) => t.length > 4096 || t.split('/').length > 256))
|
|
146
|
+
return signals;
|
|
147
|
+
const root = (0, scratch_root_1.trustedScratchRoot)(scratchTmpdir);
|
|
148
|
+
if (root === null)
|
|
149
|
+
return signals;
|
|
150
|
+
const out = { ...(signals ?? {}) };
|
|
151
|
+
let added = false;
|
|
152
|
+
for (const raw of absolute) {
|
|
153
|
+
if (!(0, scratch_root_1.isUnderScratchRoot)(raw.replace(/^["']/, '').replace(/["']$/, ''), root))
|
|
154
|
+
continue;
|
|
155
|
+
out[raw] = { ...(out[raw] ?? {}), scratch: true };
|
|
156
|
+
added = true;
|
|
157
|
+
}
|
|
158
|
+
return added ? out : signals;
|
|
159
|
+
}
|
|
160
|
+
function gitRmSignals(command, cwd, projectRoot, specsDir) {
|
|
123
161
|
// A-SPEC-728 (round 24): the text as the shell joins it (`r\m -rf .git`, `eval rm\ -rf\ src`).
|
|
124
162
|
const targets = [...new Set([...(0, risk_classifier_1.rmCommandTargets)(command), ...(0, risk_classifier_1.rmCommandTargets)((0, write_target_1.joinShellText)(command))])];
|
|
125
163
|
if (targets.length === 0)
|
|
@@ -44,7 +44,7 @@ export interface StopEvidence {
|
|
|
44
44
|
* printed under; absent means every line is printed as the session's. Never read for the verdict.
|
|
45
45
|
*/
|
|
46
46
|
pendingRequests?: Pick<PendingRequest, 'id' | 'target'>[];
|
|
47
|
-
/** The
|
|
47
|
+
/** The holmes-kit command the block text prints before `approve` (default: the issuing version, A-SPEC-770.3). */
|
|
48
48
|
launcher?: string;
|
|
49
49
|
/** A-SPEC id -> number of real test cases (`it(`/`test(`) found in test files anchored to it. */
|
|
50
50
|
testCasesByAspec?: Record<string, number>;
|
|
@@ -355,6 +355,8 @@ export declare function decideStopGuard(wantsBlock: boolean, priorConsecutiveBlo
|
|
|
355
355
|
};
|
|
356
356
|
/** Test seam for the same reason as the two exports below — the CLI sets this on a real run. */
|
|
357
357
|
export declare function __setWiredSpecsForTest(v: string | undefined): void;
|
|
358
|
+
/** @implements A-SPEC-770.7 — the approval command from this project's root (round 2: the Stop block passed none). */
|
|
359
|
+
export declare function stopLauncher(): string;
|
|
358
360
|
/**
|
|
359
361
|
* `readGuardCount`, degraded to 0 if it throws.
|
|
360
362
|
*
|
|
@@ -56,13 +56,14 @@ exports.acknowledgeStop = acknowledgeStop;
|
|
|
56
56
|
exports.describeTokenHealth = describeTokenHealth;
|
|
57
57
|
exports.decideStopGuard = decideStopGuard;
|
|
58
58
|
exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
|
|
59
|
+
exports.stopLauncher = stopLauncher;
|
|
59
60
|
exports.guardCountOrZero = guardCountOrZero;
|
|
60
61
|
exports.readGuardCount = readGuardCount;
|
|
61
62
|
exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
|
|
62
63
|
exports.stopSharedScan = stopSharedScan;
|
|
63
64
|
exports.scanCodeCycles = scanCodeCycles;
|
|
64
65
|
exports.writeGuardCount = writeGuardCount;
|
|
65
|
-
// @implements A-SPEC-734, A-SPEC-772.1
|
|
66
|
+
// @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7
|
|
66
67
|
// @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
|
|
67
68
|
const fs = __importStar(require("node:fs"));
|
|
68
69
|
// @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
|
|
@@ -875,7 +876,7 @@ function evaluateStop(specs, evidence) {
|
|
|
875
876
|
violations: structured,
|
|
876
877
|
...(tracked ? { tracked } : {}),
|
|
877
878
|
// @implements A-SPEC-247.1 — the same lines, each under the heading that says who acts next. Text only.
|
|
878
|
-
reason: stopBlockText(structured, evidence?.pendingRequests ?? [], evidence?.launcher ?? (
|
|
879
|
+
reason: stopBlockText(structured, evidence?.pendingRequests ?? [], evidence?.launcher ?? stopLauncher()),
|
|
879
880
|
};
|
|
880
881
|
}
|
|
881
882
|
/** The leading document id of an ART-4 detail (`T-SPEC-752.4: declared coverage …`). */
|
|
@@ -912,7 +913,7 @@ function stopBlockText(violations, pending, launcher) {
|
|
|
912
913
|
: v.article === 'ART-7' ? v.findingId : undefined;
|
|
913
914
|
const request = subject === undefined ? undefined : requestFor.get(subject);
|
|
914
915
|
if (request !== undefined) {
|
|
915
|
-
operator.push(`${line} — request ${request} is pending: the operator decides it, in the session's approval dialog or with ${launcher}
|
|
916
|
+
operator.push(`${line} — request ${request} is pending: the operator decides it, in the session's approval dialog or with ${launcher} approve`);
|
|
916
917
|
}
|
|
917
918
|
else if (v.article === 'ART-4') {
|
|
918
919
|
session.push(`${line} — anchor real covering tests, or, when the design is withdrawn, retire the spec with spec_retire`);
|
|
@@ -1109,6 +1110,15 @@ function __setWiredSpecsForTest(v) { WIRED_SPECS = v; }
|
|
|
1109
1110
|
* `git rev-parse --show-toplevel`, and the ART-4 loop called it per test file (1,000 tests: 16.7 s — measured).
|
|
1110
1111
|
*/
|
|
1111
1112
|
let STOP_ROOT = null;
|
|
1113
|
+
/** @implements A-SPEC-770.7 — the approval command from this project's root (round 2: the Stop block passed none). */
|
|
1114
|
+
function stopLauncher() {
|
|
1115
|
+
try {
|
|
1116
|
+
return (0, npx_bin_1.holmesKitCommand)(stopProjectRoot());
|
|
1117
|
+
}
|
|
1118
|
+
catch {
|
|
1119
|
+
return (0, npx_bin_1.holmesKitCommand)();
|
|
1120
|
+
}
|
|
1121
|
+
}
|
|
1112
1122
|
function stopProjectRoot() {
|
|
1113
1123
|
const cwd = process.cwd();
|
|
1114
1124
|
if (STOP_ROOT === null || STOP_ROOT.cwd !== cwd)
|
|
@@ -1743,7 +1753,7 @@ if (require.main === module) {
|
|
|
1743
1753
|
else if (ackWaiting.length > 0) {
|
|
1744
1754
|
// @implements A-SPEC-247 — acknowledged, not clean: name what is waiting so the user sees
|
|
1745
1755
|
// the standing approval debt exactly once, and the agent knows the ball is not in its court.
|
|
1746
|
-
process.stderr.write(`[Holmes-Kit] awaiting approval — items waiting on the owner's decision: ${ackWaiting.join(', ')}. Decide them at ${(
|
|
1756
|
+
process.stderr.write(`[Holmes-Kit] awaiting approval — items waiting on the owner's decision: ${ackWaiting.join(', ')}. Decide them at ${stopLauncher()} approve. (This debt does not re-block.)\n`);
|
|
1747
1757
|
}
|
|
1748
1758
|
else if (guard.capped) {
|
|
1749
1759
|
process.stderr.write(`[Holmes-Kit] governance gate YIELDING after ${exports.MAX_CONSECUTIVE_BLOCKS} consecutive blocks — issues remain UNRESOLVED:\n${out.reason ?? ''}\n`);
|
|
@@ -9,7 +9,7 @@ exports.buildDecisionForm = buildDecisionForm;
|
|
|
9
9
|
exports.buildReasonForm = buildReasonForm;
|
|
10
10
|
exports.runElicitFlow = runElicitFlow;
|
|
11
11
|
exports.interpretElicitResult = interpretElicitResult;
|
|
12
|
-
// @implements A-SPEC-718.2, A-SPEC-718, A-SPEC-263.1, A-SPEC-732
|
|
12
|
+
// @implements A-SPEC-718.2, A-SPEC-718, A-SPEC-263.1, A-SPEC-732, A-SPEC-770.3, A-SPEC-770.6
|
|
13
13
|
const npx_bin_1 = require("../project/npx-bin");
|
|
14
14
|
/**
|
|
15
15
|
* The decision comes INTO the session (REQ-263): an approval-shaped refusal (spec_approve without a
|
|
@@ -91,7 +91,7 @@ function classifyElicitError(e, timeoutMs = exports.ELICIT_TIMEOUT_MS) {
|
|
|
91
91
|
* Template-owned text with no interpolated attacker data.
|
|
92
92
|
*/
|
|
93
93
|
function expiredNotice(waitedMs) {
|
|
94
|
-
return `[세션 승인 다이얼로그 만료 — ${Math.round(waitedMs / 1000)}초 무응답] 요청은 승인 큐로 회송되었습니다. 결정: ${(0, npx_bin_1.
|
|
94
|
+
return `[세션 승인 다이얼로그 만료 — ${Math.round(waitedMs / 1000)}초 무응답] 요청은 승인 큐로 회송되었습니다. 결정: ${(0, npx_bin_1.holmesKitCommand)()} approve. `;
|
|
95
95
|
}
|
|
96
96
|
// FLATTEN attacker-influenced text (round-1): the model chooses spec titles and finding ids, and
|
|
97
97
|
// interpolating them raw let a crafted title inject fake lines ("[시스템] … approve.") into the
|
|
@@ -110,7 +110,7 @@ const flat = (s, max) => s.replace(/[\u0000-\u001f\u007f\u0085\u2028\u2029\u200b
|
|
|
110
110
|
function buildDecisionForm(req, attempt, timeoutMs) {
|
|
111
111
|
const redisplay = attempt > 1 ? `⚠ 재표시 ${attempt}/${exports.MAX_PRESENTATIONS} — 이전 다이얼로그는 만료되어 무효입니다\n` : '';
|
|
112
112
|
// @implements A-SPEC-718.2 — one outcome for silence, in every mode: the request returns to the queue.
|
|
113
|
-
const timeoutNotice = `⏱ ${timeoutMs / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: ${(0, npx_bin_1.
|
|
113
|
+
const timeoutNotice = `⏱ ${timeoutMs / 1000}초 내 미결정 시 승인 큐로 회송됩니다(운영자: ${(0, npx_bin_1.holmesKitCommand)()} approve).`;
|
|
114
114
|
return {
|
|
115
115
|
// @implements A-SPEC-497.1 — the forewarning is the LAST line and template-owned: it survives a
|
|
116
116
|
// cap-filling summary (appended after the caps) and tells the human, before the clock runs out,
|
|
@@ -217,7 +217,7 @@ function interpretElicitResult(r) {
|
|
|
217
217
|
// @implements A-SPEC-732 — the protocol cannot tell a person's decline from a client that declines
|
|
218
218
|
// forms automatically (codex exec, measured 2026-09-24), so the reason names both and the fallback.
|
|
219
219
|
if (r.action === 'decline')
|
|
220
|
-
return { granted: false, reason: 'the session client declined the approval form (decline) — a person declined, or a client that cannot show forms (e.g. codex exec) declined automatically. If nobody saw the form, set HOLMES_ELICIT=off in the holmes-kit MCP server environment and decide with
|
|
220
|
+
return { granted: false, reason: 'the session client declined the approval form (decline) — a person declined, or a client that cannot show forms (e.g. codex exec) declined automatically. If nobody saw the form, set HOLMES_ELICIT=off in the holmes-kit MCP server environment and decide with ' + `${(0, npx_bin_1.holmesKitCommand)()} approve` }; // A-SPEC-770.6
|
|
221
221
|
if (r.action !== 'accept')
|
|
222
222
|
return null; // cancel, absent, anything else: no decision
|
|
223
223
|
const content = r.content;
|
|
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.createSpecApprovalHandlers = createSpecApprovalHandlers;
|
|
37
37
|
exports.readProjectFile = readProjectFile;
|
|
38
|
-
// @implements A-SPEC-718.3, A-SPEC-718.1,
|
|
38
|
+
// @implements A-SPEC-718.3, A-SPEC-770.6, A-SPEC-718.1,A-SPEC-718.2, A-SPEC-718, A-SPEC-551.1, A-SPEC-551.2, A-SPEC-627.1, A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245, A-SPEC-729
|
|
39
39
|
// @implements A-SPEC-631, A-SPEC-733
|
|
40
40
|
const fs = __importStar(require("node:fs"));
|
|
41
41
|
const compat_impact_1 = require("../../spec/compat-impact");
|
|
@@ -56,6 +56,7 @@ const review_targets_1 = require("../../review/review-targets");
|
|
|
56
56
|
const requirement_triage_evidence_1 = require("../requirement-triage-evidence");
|
|
57
57
|
const approval_policy_1 = require("../approval-policy");
|
|
58
58
|
const approval_blockers_1 = require("../../spec/approval-blockers");
|
|
59
|
+
const npx_bin_1 = require("../../project/npx-bin");
|
|
59
60
|
function createSpecApprovalHandlers(context) {
|
|
60
61
|
const { store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval } = context;
|
|
61
62
|
return {
|
|
@@ -365,7 +366,7 @@ function createSpecApprovalHandlers(context) {
|
|
|
365
366
|
const bound = approveResolved.approval;
|
|
366
367
|
if (typeof bound.subject === 'string' && bound.subject !== '' && bound.subject !== (0, spec_digest_1.specDigest)(cur.spec)) {
|
|
367
368
|
const current = (0, spec_digest_1.specDigest)(cur.spec);
|
|
368
|
-
return { ok: false, reason: `[grant ${bound.nonce ?? '?'} refused: stale-subject] the grant was minted for another content of ${a.id}; the operator must read the current content and decide again (revoke the stale grant with
|
|
369
|
+
return { ok: false, reason: `[grant ${bound.nonce ?? '?'} refused: stale-subject] the grant was minted for another content of ${a.id}; the operator must read the current content and decide again (revoke the stale grant with ${(0, npx_bin_1.holmesKitCommand)(a.root)} approve --revoke).`
|
|
369
370
|
+ context.refusalQueueHint(a.root, { kind: 'spec-approve', target: a.id, why: '스펙 봉인 승인', subject: current }) };
|
|
370
371
|
}
|
|
371
372
|
}
|
|
@@ -1,3 +1,29 @@
|
|
|
1
|
+
/** @implements A-SPEC-770.6 — the running package's CLI (src/holmes/project and dist/holmes/project share a depth). */
|
|
2
|
+
export declare function runningCli(): string;
|
|
3
|
+
export interface ShadowCopy {
|
|
4
|
+
link: string;
|
|
5
|
+
packageDir: string | null;
|
|
6
|
+
version: string;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* @implements A-SPEC-770.7 — the holmes-kit npx would run from `dir`, when it is not this install; null otherwise.
|
|
10
|
+
* npx walks every ancestor `node_modules/.bin` and takes the first entry that `stat` says is a FILE (a dangling link or
|
|
11
|
+
* a directory is skipped). Round 2 measured npm-on-Windows and pnpm `.bin` entries as shim files, not links: the
|
|
12
|
+
* package is therefore found as `node_modules/{@holmes-lab/holmes-kit,holmes-kit}` beside the `.bin`, and only for a
|
|
13
|
+
* link with neither beside it through the link's target — never past a node_modules boundary (that read the consumer
|
|
14
|
+
* project's own package.json). Not memoized: a copy installed later is seen (the MCP server lives long).
|
|
15
|
+
*/
|
|
16
|
+
export declare function binEntryNames(platform?: string): string[];
|
|
17
|
+
export declare function shadowCopy(dir: string, platform?: string): ShadowCopy | null;
|
|
18
|
+
/** @implements A-SPEC-770.7 — a PowerShell single-quoted literal: PowerShell also treats U+2018–U+201B as quotes. */
|
|
19
|
+
export declare function powershellLiteral(value: string): string;
|
|
20
|
+
export declare function posixLiteral(value: string): string;
|
|
21
|
+
/**
|
|
22
|
+
* @implements A-SPEC-770.3
|
|
23
|
+
* The holmes-kit command an approval hint names, so that the install that issued it is the one that answers. Field
|
|
24
|
+
* incident 2026-10-17: ~/node_modules 0.19.3 answered a 0.35.23 hint with "no pending request matches".
|
|
25
|
+
*/
|
|
26
|
+
export declare function holmesKitCommand(root?: string, platform?: string, home?: string): string;
|
|
1
27
|
/**
|
|
2
28
|
* @implements A-SPEC-542.1
|
|
3
29
|
* The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
|
|
@@ -1,9 +1,279 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
-
|
|
3
|
-
|
|
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
|
+
})();
|
|
4
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.runningCli = runningCli;
|
|
37
|
+
exports.binEntryNames = binEntryNames;
|
|
38
|
+
exports.shadowCopy = shadowCopy;
|
|
39
|
+
exports.powershellLiteral = powershellLiteral;
|
|
40
|
+
exports.posixLiteral = posixLiteral;
|
|
41
|
+
exports.holmesKitCommand = holmesKitCommand;
|
|
5
42
|
exports.npxBin = npxBin;
|
|
6
43
|
exports.npmBin = npmBin;
|
|
44
|
+
// @implements A-SPEC-542.1
|
|
45
|
+
// @implements A-SPEC-580
|
|
46
|
+
// @implements A-SPEC-770.3, A-SPEC-770.4, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.8, A-SPEC-770.9, A-SPEC-770.10
|
|
47
|
+
const fs = __importStar(require("node:fs"));
|
|
48
|
+
const os = __importStar(require("node:os"));
|
|
49
|
+
const path = __importStar(require("node:path"));
|
|
50
|
+
/** @implements A-SPEC-770.6 — the running package's CLI (src/holmes/project and dist/holmes/project share a depth). */
|
|
51
|
+
function runningCli() {
|
|
52
|
+
const cli = path.resolve(__dirname, '../../..', 'bin', 'holmes-kit.js');
|
|
53
|
+
try {
|
|
54
|
+
return fs.realpathSync.native(cli);
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
return cli;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
function runningPackageRoot() {
|
|
61
|
+
const root = path.resolve(__dirname, '../../..');
|
|
62
|
+
try {
|
|
63
|
+
return fs.realpathSync.native(root);
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
return root;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
const realOrNull = (p) => { try {
|
|
70
|
+
return fs.realpathSync.native(p);
|
|
71
|
+
}
|
|
72
|
+
catch {
|
|
73
|
+
return null;
|
|
74
|
+
} };
|
|
75
|
+
/** The package directory that holds `file`: the nearest ancestor with a package.json, never climbing past node_modules. */
|
|
76
|
+
function packageOf(file, real = false) {
|
|
77
|
+
for (let up = path.dirname(file);; up = path.dirname(up)) {
|
|
78
|
+
if (path.basename(up) === 'node_modules' || path.dirname(up) === up)
|
|
79
|
+
return null;
|
|
80
|
+
if (fs.existsSync(path.join(up, 'package.json')))
|
|
81
|
+
return real ? realOrNull(up) : up;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* @implements A-SPEC-770.7 — the holmes-kit npx would run from `dir`, when it is not this install; null otherwise.
|
|
86
|
+
* npx walks every ancestor `node_modules/.bin` and takes the first entry that `stat` says is a FILE (a dangling link or
|
|
87
|
+
* a directory is skipped). Round 2 measured npm-on-Windows and pnpm `.bin` entries as shim files, not links: the
|
|
88
|
+
* package is therefore found as `node_modules/{@holmes-lab/holmes-kit,holmes-kit}` beside the `.bin`, and only for a
|
|
89
|
+
* link with neither beside it through the link's target — never past a node_modules boundary (that read the consumer
|
|
90
|
+
* project's own package.json). Not memoized: a copy installed later is seen (the MCP server lives long).
|
|
91
|
+
*/
|
|
92
|
+
function binEntryNames(platform = process.platform) {
|
|
93
|
+
// @implements A-SPEC-770.8 — npx runs `.cmd` only on Windows (round 3: a lone .cmd shadowed on POSIX).
|
|
94
|
+
return platform === 'win32' ? ['holmes-kit', 'holmes-kit.cmd'] : ['holmes-kit'];
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* @implements A-SPEC-770.9 — npx first runs the localPrefix package's OWN bin (npm 11.17 libnpmexec `hasPkgBin`, before
|
|
98
|
+
* the .bin walk): the nearest ancestor holding package.json or node_modules. Round 4: a holmes-kit checkout or fork
|
|
99
|
+
* answered every bare hint issued by the global install.
|
|
100
|
+
*/
|
|
101
|
+
/** @implements A-SPEC-770.10 — npx derives localPrefix from the physical cwd (round 5: a symlinked cwd into a fork). */
|
|
102
|
+
const physical = (dir) => realOrNull(path.resolve(dir)) ?? path.resolve(dir);
|
|
103
|
+
const isDir = (p) => { try {
|
|
104
|
+
return fs.statSync(p).isDirectory();
|
|
105
|
+
}
|
|
106
|
+
catch {
|
|
107
|
+
return false;
|
|
108
|
+
} };
|
|
109
|
+
function ownPackageBin(dir, own) {
|
|
110
|
+
for (let at = physical(dir);; at = path.dirname(at)) {
|
|
111
|
+
const pj = path.join(at, 'package.json');
|
|
112
|
+
// @implements A-SPEC-770.10 — npm counts node_modules as a localPrefix marker only when it is a directory.
|
|
113
|
+
if (fs.existsSync(pj) || isDir(path.join(at, 'node_modules'))) {
|
|
114
|
+
let pkg = {};
|
|
115
|
+
// @implements A-SPEC-770.10 — read as pacote normalises it: a BOM, a scoped string-bin name, a `./name` key.
|
|
116
|
+
try {
|
|
117
|
+
pkg = JSON.parse(fs.readFileSync(pj, 'utf8').replace(/^/, ''));
|
|
118
|
+
}
|
|
119
|
+
catch {
|
|
120
|
+
return undefined;
|
|
121
|
+
}
|
|
122
|
+
const declares = (typeof pkg.bin === 'object' && pkg.bin !== null
|
|
123
|
+
&& Object.entries(pkg.bin).some(([k, v]) => path.posix.basename(k.replace(/\\/g, '/')) === 'holmes-kit' && typeof v === 'string'))
|
|
124
|
+
|| (typeof pkg.bin === 'string' && typeof pkg.name === 'string' && pkg.name.split('/').pop() === 'holmes-kit');
|
|
125
|
+
if (!declares)
|
|
126
|
+
return undefined;
|
|
127
|
+
if (realOrNull(at) === own)
|
|
128
|
+
return null;
|
|
129
|
+
return { link: UNSAFE_DISPLAY.test(pj) ? '(unprintable path)' : pj, packageDir: null, version: safe(String(pkg.version ?? '')) };
|
|
130
|
+
}
|
|
131
|
+
if (path.dirname(at) === at)
|
|
132
|
+
return undefined;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
const safe = (v) => (UNSAFE_DISPLAY.test(v) ? '' : v);
|
|
136
|
+
function shadowCopy(dir, platform = process.platform) {
|
|
137
|
+
const own = runningPackageRoot();
|
|
138
|
+
const first = ownPackageBin(dir, own);
|
|
139
|
+
if (first !== undefined)
|
|
140
|
+
return first;
|
|
141
|
+
const names = binEntryNames(platform);
|
|
142
|
+
for (let at = physical(dir);; at = path.dirname(at)) {
|
|
143
|
+
const nm = path.join(at, 'node_modules');
|
|
144
|
+
for (const name of names) {
|
|
145
|
+
const link = path.join(nm, '.bin', name);
|
|
146
|
+
let isFile = false;
|
|
147
|
+
try {
|
|
148
|
+
isFile = fs.statSync(link).isFile();
|
|
149
|
+
}
|
|
150
|
+
catch {
|
|
151
|
+
isFile = false;
|
|
152
|
+
}
|
|
153
|
+
if (!isFile)
|
|
154
|
+
continue;
|
|
155
|
+
// @implements A-SPEC-770.8 — the ENTRY decides which package runs (round 3: the package beside .bin decided, and a
|
|
156
|
+
// scoped link to this install hid the unscoped 0.1.0 npx actually ran). `lexical` is where the entry points under
|
|
157
|
+
// node_modules; identity compares real paths only.
|
|
158
|
+
let lexical = null;
|
|
159
|
+
let identity = null;
|
|
160
|
+
let isLink = false;
|
|
161
|
+
try {
|
|
162
|
+
isLink = fs.lstatSync(link).isSymbolicLink();
|
|
163
|
+
}
|
|
164
|
+
catch {
|
|
165
|
+
isLink = false;
|
|
166
|
+
}
|
|
167
|
+
if (isLink) {
|
|
168
|
+
let text = '';
|
|
169
|
+
try {
|
|
170
|
+
text = fs.readlinkSync(link);
|
|
171
|
+
lexical = path.resolve(path.dirname(link), text);
|
|
172
|
+
}
|
|
173
|
+
catch {
|
|
174
|
+
lexical = null;
|
|
175
|
+
}
|
|
176
|
+
// @implements A-SPEC-770.9 — `..` after the first segment can cross an intermediate link the lexical fold hides.
|
|
177
|
+
if (text.split(/[\\/]/).slice(1).includes('..'))
|
|
178
|
+
lexical = null;
|
|
179
|
+
const real = realOrNull(link);
|
|
180
|
+
identity = real ? packageOf(real, true) : null;
|
|
181
|
+
}
|
|
182
|
+
else {
|
|
183
|
+
let text = '';
|
|
184
|
+
try {
|
|
185
|
+
const fd = fs.openSync(link, 'r');
|
|
186
|
+
try {
|
|
187
|
+
const buf = Buffer.alloc(4096);
|
|
188
|
+
text = buf.subarray(0, fs.readSync(fd, buf, 0, 4096, 0)).toString('utf8');
|
|
189
|
+
}
|
|
190
|
+
finally {
|
|
191
|
+
fs.closeSync(fd);
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
catch {
|
|
195
|
+
text = '';
|
|
196
|
+
}
|
|
197
|
+
// @implements A-SPEC-770.9 — only a path to the package's bin/holmes-kit.js decides (round 4: a comment line,
|
|
198
|
+
// `..` and `.pnpm` captures named other packages); the capture must exist.
|
|
199
|
+
const m = /(?:\$basedir|%~?dp0%?)[\\/]\.\.[\\/]((?:@[^\\/\s"']+[\\/])?[^\\/\s"']+)[\\/]bin[\\/]holmes-kit\.js/.exec(text);
|
|
200
|
+
const captured = m && !['.', '..', '.pnpm'].includes(m[1].split(/[\\/]/)[0]) && !UNSAFE_DISPLAY.test(m[1])
|
|
201
|
+
? path.join(nm, ...m[1].split(/[\\/]/)) : null;
|
|
202
|
+
if (m && captured === null)
|
|
203
|
+
lexical = null;
|
|
204
|
+
else if (captured !== null)
|
|
205
|
+
lexical = fs.existsSync(captured) ? captured : null;
|
|
206
|
+
else {
|
|
207
|
+
const beside = ['@holmes-lab/holmes-kit', 'holmes-kit'].map((p) => path.join(nm, ...p.split('/'))).filter((p) => fs.existsSync(p));
|
|
208
|
+
lexical = beside.length === 1 ? beside[0] : null;
|
|
209
|
+
}
|
|
210
|
+
identity = lexical ? realOrNull(lexical) : null;
|
|
211
|
+
}
|
|
212
|
+
if (identity !== null && identity === own)
|
|
213
|
+
return null;
|
|
214
|
+
// @implements A-SPEC-770.9 — nothing with a control or bidi character reaches the doctor text.
|
|
215
|
+
const entry = lexical ? nodeModulesEntry(nm, lexical) : null;
|
|
216
|
+
const packageDir = entry !== null && !UNSAFE_DISPLAY.test(entry) ? entry : null;
|
|
217
|
+
let version = '';
|
|
218
|
+
const versionFrom = identity ?? packageDir;
|
|
219
|
+
if (versionFrom) {
|
|
220
|
+
try {
|
|
221
|
+
version = String(JSON.parse(fs.readFileSync(path.join(versionFrom, 'package.json'), 'utf8')).version ?? '');
|
|
222
|
+
}
|
|
223
|
+
catch {
|
|
224
|
+
version = '';
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
// @implements A-SPEC-770.10 — the link text is filtered too (A-SPEC-770.9 Behavior 5).
|
|
228
|
+
return { link: UNSAFE_DISPLAY.test(link) ? '(unprintable path)' : link, packageDir, version: safe(version) };
|
|
229
|
+
}
|
|
230
|
+
if (path.dirname(at) === at)
|
|
231
|
+
return null;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* @implements A-SPEC-770.8 — the package entry `node_modules/<name>` or `node_modules/@scope/<name>` that `target` lies
|
|
236
|
+
* in, lexically; null outside `nm`, or for `.bin`/`.pnpm` (removing those breaks other packages).
|
|
237
|
+
*/
|
|
238
|
+
function nodeModulesEntry(nm, target) {
|
|
239
|
+
const rel = path.relative(nm, target);
|
|
240
|
+
if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
|
|
241
|
+
return null;
|
|
242
|
+
const segs = rel.split(path.sep);
|
|
243
|
+
if (segs[0] === '.bin' || segs[0] === '.pnpm')
|
|
244
|
+
return null;
|
|
245
|
+
if (segs[0].startsWith('@'))
|
|
246
|
+
return segs.length >= 2 ? path.join(nm, segs[0], segs[1]) : null;
|
|
247
|
+
return path.join(nm, segs[0]);
|
|
248
|
+
}
|
|
249
|
+
/** @implements A-SPEC-770.7 — a PowerShell single-quoted literal: PowerShell also treats U+2018–U+201B as quotes. */
|
|
250
|
+
function powershellLiteral(value) {
|
|
251
|
+
return `'${value.replace(/['‘’‚‛]/g, (q) => q + q)}'`;
|
|
252
|
+
}
|
|
253
|
+
function posixLiteral(value) {
|
|
254
|
+
return `'${value.replace(/'/g, `'\\''`)}'`;
|
|
255
|
+
}
|
|
256
|
+
/**
|
|
257
|
+
* @implements A-SPEC-770.3
|
|
258
|
+
* The holmes-kit command an approval hint names, so that the install that issued it is the one that answers. Field
|
|
259
|
+
* incident 2026-10-17: ~/node_modules 0.19.3 answered a 0.35.23 hint with "no pending request matches".
|
|
260
|
+
*/
|
|
261
|
+
function holmesKitCommand(root, platform = process.platform, home = os.homedir()) {
|
|
262
|
+
// @implements A-SPEC-770.6 — the bare command where nothing shadows it: it reaches a global or local install with no
|
|
263
|
+
// network. The pinned `npx -p …@<version>` of 770.3/770.4 skipped the global install (round 1: ENOTCACHED offline,
|
|
264
|
+
// 703 MB and a y/n prompt on a cold cache, ETARGET for an unpublished version). Where a shadow sits on the path, the
|
|
265
|
+
// running install itself, quoted as A-SPEC-754's operator-recovery line is.
|
|
266
|
+
// @implements A-SPEC-770.7 — the home directory is checked too: an operator often pastes from `~`.
|
|
267
|
+
const bare = `${npxBin(platform)} holmes-kit`;
|
|
268
|
+
if (shadowCopy(root ?? process.cwd(), platform) === null && shadowCopy(home, platform) === null)
|
|
269
|
+
return bare;
|
|
270
|
+
const exe = process.execPath;
|
|
271
|
+
const cli = runningCli();
|
|
272
|
+
if (![exe, cli].every((v) => v.length > 0 && v.length <= 2048 && !UNSAFE_DISPLAY.test(v)))
|
|
273
|
+
return bare;
|
|
274
|
+
return platform === 'win32' ? `& ${powershellLiteral(exe)} ${powershellLiteral(cli)}` : `${posixLiteral(exe)} ${posixLiteral(cli)}`;
|
|
275
|
+
}
|
|
276
|
+
const UNSAFE_DISPLAY = /[\u0000-\u001f\u007f-\u009f--]/;
|
|
7
277
|
/**
|
|
8
278
|
* @implements A-SPEC-542.1
|
|
9
279
|
* The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import * as fs from 'node:fs';
|
|
2
|
+
export declare function scratchRootPath(tmpdir?: string): string;
|
|
3
|
+
type Lstat = (p: string) => fs.Stats;
|
|
4
|
+
/** The root's real path when it is this user's own directory, not a link, with no group or other bits; else null. */
|
|
5
|
+
export declare function trustedScratchRoot(tmpdir?: string, lstat?: Lstat, platform?: string): string | null;
|
|
6
|
+
/** Makes the root (0700) when missing and returns its real path; throws when an existing root is not trusted. */
|
|
7
|
+
export declare function ensureScratchRoot(tmpdir?: string): string;
|
|
8
|
+
/** A fresh subdirectory `<root>/<label>-XXXXXX`. */
|
|
9
|
+
export declare function newScratchDir(label?: string, tmpdir?: string): string;
|
|
10
|
+
/** True when the target exists and its real path lies strictly under `root` (a real path). */
|
|
11
|
+
export declare function isUnderScratchRoot(target: string, root: string): boolean;
|
|
12
|
+
export {};
|