rungate 0.5.0 → 0.7.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/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,393 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* top-level-cd.ts — the decision behind TopLevelCdGuard (#992)
|
|
3
|
+
*
|
|
4
|
+
* One question: does this Bash command move the SESSION's working directory?
|
|
5
|
+
*
|
|
6
|
+
* `topLevelCdRefusal` is the only exported binding and the only decider, so
|
|
7
|
+
* there is one thing to mutate and one thing for a later caller to reuse —
|
|
8
|
+
* the grader, a conformity check, a transcript audit. A second copy of this
|
|
9
|
+
* parse anywhere would survive any mutation of this one and both would read
|
|
10
|
+
* as covered (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
11
|
+
*
|
|
12
|
+
* ## Why the question is "top level" and not "anywhere"
|
|
13
|
+
*
|
|
14
|
+
* A Bash tool call runs in a shell whose cwd PERSISTS between calls, and the
|
|
15
|
+
* agent runtime resolves `isolation: 'worktree'` against that directory. So a
|
|
16
|
+
* `cd` at the top level of one call can kill a peer agent's worktree creation
|
|
17
|
+
* hours later, and the failure names the session's directory rather than the
|
|
18
|
+
* command that moved it. A `cd` inside a subshell, a command substitution or
|
|
19
|
+
* a child interpreter cannot do that: the child exits and the parent's cwd is
|
|
20
|
+
* untouched.
|
|
21
|
+
*
|
|
22
|
+
* ## The direction this is allowed to be wrong in
|
|
23
|
+
*
|
|
24
|
+
* Toward REFUSAL. A false refusal costs one retyped command and teaches the
|
|
25
|
+
* habit; a false allow costs another agent half a day. Three forms are
|
|
26
|
+
* refused that bash would in fact fork — a pipeline element, a backgrounded
|
|
27
|
+
* command, and `exec cd` — because distinguishing them needs the shell's own
|
|
28
|
+
* semantics and the saving is one retype.
|
|
29
|
+
*
|
|
30
|
+
* An input this cannot READ is refused for the same reason and said out loud:
|
|
31
|
+
* a command that is absent, or not a string, has not been examined and found
|
|
32
|
+
* clean. See `unreadableMessage`, and the `|| ''` it replaced.
|
|
33
|
+
*
|
|
34
|
+
* ## KNOWN FALSE REFUSALS — the direction this is allowed to be wrong in
|
|
35
|
+
*
|
|
36
|
+
* A `#` comment is not parsed. `ls # cd /tmp` is allowed because `ls` is the
|
|
37
|
+
* segment's first token, but a comment carrying a separator —
|
|
38
|
+
* `make # fails; cd /x is not the fix` — splits and the tail reads as a
|
|
39
|
+
* top-level `cd`. Both forms are asserted in `test/top-level-cd.test.ts`.
|
|
40
|
+
*
|
|
41
|
+
* Stripping comments would fix it and was deliberately not done: a `#` inside
|
|
42
|
+
* `$(…)` on one line comments out the closing paren, so a stripper unbalances
|
|
43
|
+
* the depth counter and a later top-level `cd` falls INSIDE the unclosed
|
|
44
|
+
* subshell and is allowed. That trades a rare false refusal for a new
|
|
45
|
+
* false-allow path, which is the wrong direction.
|
|
46
|
+
*
|
|
47
|
+
* ## WHAT THIS DOES NOT COVER
|
|
48
|
+
*
|
|
49
|
+
* Every form below moves the session and is NOT refused. They are asserted as
|
|
50
|
+
* cases in `test/top-level-cd.test.ts` under AC-10, not merely listed here, so
|
|
51
|
+
* a later widening that closes one goes red rather than silently changing the
|
|
52
|
+
* behaviour of every session on the machine.
|
|
53
|
+
*
|
|
54
|
+
* - `eval "cd /x"` — the command is a string until the shell expands it.
|
|
55
|
+
* - `CMD=cd; $CMD /x` — a command built from a variable. The hook has no
|
|
56
|
+
* access to shell state and cannot know what `$CMD` holds.
|
|
57
|
+
* - A heredoc body sourced into the current shell (`source /dev/stdin <<EOF`).
|
|
58
|
+
* Heredoc bodies are stripped before the scan because they are data in
|
|
59
|
+
* every other case, and `cat <<EOF` carrying the word `cd` was a real false
|
|
60
|
+
* positive in the sibling guard (`lib/bash-file-read.ts`).
|
|
61
|
+
* - A function defined and called in one command: `goto() { cd "$1"; }; goto /x`.
|
|
62
|
+
* - A zsh function or alias from the user's rc — the token is not `cd` and
|
|
63
|
+
* nothing in the command says what it expands to.
|
|
64
|
+
* - A sourced script that cds: `. ./setup.sh`, `source ./setup.sh`.
|
|
65
|
+
* - A `trap 'cd /x' EXIT` body, which is quoted now and run later.
|
|
66
|
+
*
|
|
67
|
+
* Closing any of these needs a real shell parser plus the shell's runtime
|
|
68
|
+
* state. This is a habit-former, not a sandbox.
|
|
69
|
+
*
|
|
70
|
+
* Issue: #992
|
|
71
|
+
*/
|
|
72
|
+
|
|
73
|
+
export interface CdRefusal {
|
|
74
|
+
/** The top-level segment that moves the shell, trimmed. */
|
|
75
|
+
segment: string;
|
|
76
|
+
/** What the caller is told, naming the alternatives. */
|
|
77
|
+
message: string;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* THE refusal exit, declared once.
|
|
82
|
+
*
|
|
83
|
+
* `hooks/TopLevelCdGuard.hook.ts` emits this as its `decision` and has no
|
|
84
|
+
* literal of its own, so there is exactly one site to mutate and a case that
|
|
85
|
+
* observes a refusal can be proved to have observed THIS one
|
|
86
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, *For a script whose job is
|
|
87
|
+
* to exit non-zero*). A second inlined `'block'` anywhere in the hook would
|
|
88
|
+
* survive the mutation and the case would go green having witnessed nothing —
|
|
89
|
+
* `test/top-level-cd.test.ts` asserts the literal appears exactly once.
|
|
90
|
+
*/
|
|
91
|
+
export const CD_GUARD_DECISION = 'block';
|
|
92
|
+
|
|
93
|
+
/** Builtins that move the shell's own working directory. */
|
|
94
|
+
const SHELL_MOVERS = new Set(['cd', 'pushd', 'popd']);
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Wrappers that delegate to the real command. `command cd /x` and
|
|
98
|
+
* `builtin cd /x` both run the builtin. `exec`, `time` and `nohup` are here
|
|
99
|
+
* for the refusal direction: they would not in fact move the parent, and
|
|
100
|
+
* refusing them costs one retype.
|
|
101
|
+
*/
|
|
102
|
+
const PREFIXES = new Set(['command', 'builtin', 'exec', 'time', 'nohup']);
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Shell keywords that can be immediately followed by a command which runs in
|
|
106
|
+
* the CURRENT shell. `{ … }` is a group, not a subshell — it is in this list
|
|
107
|
+
* deliberately, and `(` is deliberately not.
|
|
108
|
+
*/
|
|
109
|
+
const LEADING_KEYWORDS = new Set([
|
|
110
|
+
'if', 'then', 'elif', 'else', 'fi',
|
|
111
|
+
'while', 'until', 'do', 'done',
|
|
112
|
+
'{', '}', '!',
|
|
113
|
+
]);
|
|
114
|
+
|
|
115
|
+
/** An inline `VAR=value` assignment preceding the command. */
|
|
116
|
+
const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Remove heredoc bodies before scanning. A heredoc body is data, and the hook
|
|
120
|
+
* sees the raw command string, so `cat <<EOF > f … cd /x … EOF` would
|
|
121
|
+
* otherwise read as a top-level `cd` on its own line.
|
|
122
|
+
*
|
|
123
|
+
* Unlike `lib/bash-file-read.ts` this drops the body even when the feeding
|
|
124
|
+
* command is a shell interpreter, because `bash <<EOF` runs the body in a
|
|
125
|
+
* CHILD and cannot move the session. The one form that can — `source
|
|
126
|
+
* /dev/stdin <<EOF` — is a declared gap above.
|
|
127
|
+
*/
|
|
128
|
+
function stripHeredocBodies(command: string): string {
|
|
129
|
+
if (!command.includes('<<')) return command;
|
|
130
|
+
|
|
131
|
+
const out: string[] = [];
|
|
132
|
+
let delim: string | null = null;
|
|
133
|
+
let allowIndent = false;
|
|
134
|
+
|
|
135
|
+
for (const line of command.split('\n')) {
|
|
136
|
+
if (delim !== null) {
|
|
137
|
+
if ((allowIndent ? line.trimStart() : line) === delim) delim = null;
|
|
138
|
+
continue; // drop body and terminator
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
const m = line.match(/<<(-?)\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\2/);
|
|
142
|
+
if (m) {
|
|
143
|
+
allowIndent = m[1] === '-';
|
|
144
|
+
delim = m[3];
|
|
145
|
+
out.push(line.slice(0, m.index) + line.slice(m.index! + m[0].length));
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
out.push(line);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
return out.join('\n');
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Split a command into the segments that run in the CURRENT shell.
|
|
157
|
+
*
|
|
158
|
+
* Quote-, paren- and backtick-aware by necessity. A naive split tears quoted
|
|
159
|
+
* strings apart (`git commit -m "cd into /x"` would yield a bogus `cd into
|
|
160
|
+
* /x"` segment) and, worse, cannot tell `(cd /x && make)` from `cd /x &&
|
|
161
|
+
* make` — which is the whole distinction this module exists for.
|
|
162
|
+
*
|
|
163
|
+
* Text inside `(` … `)`, `$(` … `)` and backticks is a child process, so no
|
|
164
|
+
* split happens there and the enclosing segment keeps its own first token:
|
|
165
|
+
* `(cd /x && make)` is one segment beginning `(cd`, which is not `cd`.
|
|
166
|
+
*
|
|
167
|
+
* This is deliberately NOT `splitSegments` from `lib/bash-file-read.ts`.
|
|
168
|
+
* That one answers a question where depth is irrelevant — a `cat` reading a
|
|
169
|
+
* file reads it in a subshell too — so it tracks quotes and nothing else.
|
|
170
|
+
*/
|
|
171
|
+
function topLevelSegments(command: string): string[] {
|
|
172
|
+
const segments: string[] = [];
|
|
173
|
+
let current = '';
|
|
174
|
+
let quote: "'" | '"' | null = null;
|
|
175
|
+
let depth = 0;
|
|
176
|
+
let backtick = false;
|
|
177
|
+
|
|
178
|
+
for (let i = 0; i < command.length; i++) {
|
|
179
|
+
const ch = command[i];
|
|
180
|
+
|
|
181
|
+
if (quote) {
|
|
182
|
+
current += ch;
|
|
183
|
+
if (ch === '\\' && quote === '"' && i + 1 < command.length) current += command[++i];
|
|
184
|
+
else if (ch === quote) quote = null;
|
|
185
|
+
continue;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
if (ch === "'" || ch === '"') {
|
|
189
|
+
quote = ch;
|
|
190
|
+
current += ch;
|
|
191
|
+
continue;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
if (ch === '\\' && i + 1 < command.length) {
|
|
195
|
+
current += ch + command[++i];
|
|
196
|
+
continue;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
if (ch === '`') {
|
|
200
|
+
backtick = !backtick;
|
|
201
|
+
current += ch;
|
|
202
|
+
continue;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
if (ch === '(') depth++;
|
|
206
|
+
else if (ch === ')') depth = Math.max(0, depth - 1);
|
|
207
|
+
|
|
208
|
+
if (depth === 0 && !backtick && (ch === '|' || ch === '&' || ch === ';' || ch === '\n')) {
|
|
209
|
+
if ((ch === '|' || ch === '&') && command[i + 1] === ch) i++; // consume || and &&
|
|
210
|
+
segments.push(current);
|
|
211
|
+
current = '';
|
|
212
|
+
continue;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
current += ch;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
segments.push(current);
|
|
219
|
+
return segments;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Resolve a token to the command name it invokes: quotes off, escapes off,
|
|
224
|
+
* directory off. `'cd'`, `\cd` and `/usr/bin/cd` all resolve to `cd`.
|
|
225
|
+
*/
|
|
226
|
+
function commandName(token: string): string {
|
|
227
|
+
let t = token;
|
|
228
|
+
if (t.length > 1 && (t[0] === "'" || t[0] === '"') && t[t.length - 1] === t[0]) {
|
|
229
|
+
t = t.slice(1, -1);
|
|
230
|
+
}
|
|
231
|
+
t = t.replace(/\\/g, '');
|
|
232
|
+
return t.split('/').pop() || t;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** Drop leading keywords, wrapper prefixes and inline assignments. */
|
|
236
|
+
function firstCommandName(segment: string): string | null {
|
|
237
|
+
const tokens = segment.trim().split(/\s+/).filter(Boolean);
|
|
238
|
+
for (const raw of tokens) {
|
|
239
|
+
if (ASSIGNMENT.test(raw)) continue;
|
|
240
|
+
const name = commandName(raw);
|
|
241
|
+
if (LEADING_KEYWORDS.has(name) || PREFIXES.has(name)) continue;
|
|
242
|
+
return name;
|
|
243
|
+
}
|
|
244
|
+
return null;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* The refusal text. It names `git -C <path>` and the subshell form, because a
|
|
249
|
+
* refusal that does not say what to do instead gets worked around rather than
|
|
250
|
+
* obeyed — which is how this started as prose and ended as a hook.
|
|
251
|
+
*/
|
|
252
|
+
function refusalMessage(segment: string): string {
|
|
253
|
+
return [
|
|
254
|
+
'#992: refusing a top-level `cd`.',
|
|
255
|
+
'',
|
|
256
|
+
`Offending segment: ${segment}`,
|
|
257
|
+
'',
|
|
258
|
+
'A top-level `cd` moves the SESSION\'s working directory, not just this',
|
|
259
|
+
'command\'s. Worktree isolation resolves against that directory, so a peer',
|
|
260
|
+
'agent\'s worktree creation dies hours later with no error naming the cause.',
|
|
261
|
+
'',
|
|
262
|
+
'Use one of these instead:',
|
|
263
|
+
' git -C <path> <subcommand> — for anything git, always',
|
|
264
|
+
' (cd <path> && <command>) — a subshell; the session does not move',
|
|
265
|
+
' bun --cwd <path> <args> — bun',
|
|
266
|
+
' make -C <path> / npm --prefix <path>',
|
|
267
|
+
'',
|
|
268
|
+
'If the session really must move, that is a deliberate decision — say so',
|
|
269
|
+
'out loud rather than reaching for `cd` by reflex.',
|
|
270
|
+
].join('\n');
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* What the caller is told when the command could not be read at all.
|
|
275
|
+
*
|
|
276
|
+
* A Bash tool call always carries a command string. If one arrives without
|
|
277
|
+
* one, the guard has not examined a command and found it clean — it has
|
|
278
|
+
* examined nothing, and `0`, `{}`, `null` and silence are indistinguishable
|
|
279
|
+
* from success (`.claude/rules/config-access.md`). The previous shape here
|
|
280
|
+
* was `payload.tool_input?.command || ''`, which is that defect exactly: an
|
|
281
|
+
* absent command became an empty one and the guard passed over it.
|
|
282
|
+
*/
|
|
283
|
+
function unreadableMessage(command: unknown): string {
|
|
284
|
+
return [
|
|
285
|
+
'#992: refusing a Bash command this guard could not read.',
|
|
286
|
+
'',
|
|
287
|
+
`Received: ${typeof command} ${JSON.stringify(command) ?? String(command)}`,
|
|
288
|
+
'',
|
|
289
|
+
'This is UNMEASURED, not clean. The guard refuses a top-level `cd`, and it',
|
|
290
|
+
'cannot tell whether this command carries one, so it refuses rather than',
|
|
291
|
+
'reporting a pass it did not earn.',
|
|
292
|
+
'',
|
|
293
|
+
'Re-send the call with a command string. If a Bash call legitimately has',
|
|
294
|
+
'no command, that is a bug in the caller, not in this guard.',
|
|
295
|
+
].join('\n');
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/**
|
|
299
|
+
* Does this command move the session's working directory at the top level?
|
|
300
|
+
*
|
|
301
|
+
* Returns the refusal, or null when the command is clean. THE one decider:
|
|
302
|
+
* every caller — the hook, any future grader — asks this and nothing else.
|
|
303
|
+
*
|
|
304
|
+
* Takes `unknown` deliberately. The hook's input is JSON off a pipe, so the
|
|
305
|
+
* command's type is an assumption until it is checked, and the check belongs
|
|
306
|
+
* with the decision rather than at the call site where a `|| ''` is one
|
|
307
|
+
* keystroke away.
|
|
308
|
+
*/
|
|
309
|
+
export function topLevelCdRefusal(command: unknown): CdRefusal | null {
|
|
310
|
+
if (typeof command !== 'string' || command.trim() === '') {
|
|
311
|
+
return { segment: '<unreadable>', message: unreadableMessage(command) };
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
for (const segment of topLevelSegments(stripHeredocBodies(command))) {
|
|
315
|
+
const name = firstCommandName(segment);
|
|
316
|
+
if (name === null) continue;
|
|
317
|
+
if (!SHELL_MOVERS.has(name)) continue;
|
|
318
|
+
const trimmed = segment.trim();
|
|
319
|
+
return { segment: trimmed, message: refusalMessage(trimmed) };
|
|
320
|
+
}
|
|
321
|
+
return null;
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* How loudly the guard speaks: the WARN→data→FAIL ladder
|
|
326
|
+
* `specs/harness-automation-matrix.md` prescribes (#992).
|
|
327
|
+
*
|
|
328
|
+
* ## Why a mode exists at all, with the number that decided it
|
|
329
|
+
*
|
|
330
|
+
* The parser is sound: **32.7% of 31,577 unique Bash commands** from this
|
|
331
|
+
* machine's transcript store since 2026-10-14 would be refused, with **zero
|
|
332
|
+
* false positives** — all three deliberate over-refusal classes clean, a
|
|
333
|
+
* 20-command spread hand-read and all 20 genuine, and the 245 `cd`-carrying
|
|
334
|
+
* commands it allows are subshells and heredoc bodies.
|
|
335
|
+
*
|
|
336
|
+
* The issue's original cost model was *"a false refusal costs one retyped
|
|
337
|
+
* command"*. At that rate it costs **10,332 retyped commands**, and a hook
|
|
338
|
+
* refusing a third of all Bash calls is the gets-disabled failure the issue
|
|
339
|
+
* itself warns about two paragraphs below its own recommendation. The
|
|
340
|
+
* premise was corrected on the issue; this is the code catching up to the
|
|
341
|
+
* correction.
|
|
342
|
+
*
|
|
343
|
+
* So `cd` is not an occasional lapse, it is the dominant navigation idiom,
|
|
344
|
+
* and most instances are harmless — a top-level `cd` costs something only in
|
|
345
|
+
* a session with concurrent agents holding worktrees.
|
|
346
|
+
*
|
|
347
|
+
* ## The default is `block`, and that is a decision, not a reading
|
|
348
|
+
*
|
|
349
|
+
* The paragraphs above are the argument for `warn` and they are left intact
|
|
350
|
+
* because they are the honest case against what this now does. **Jason took
|
|
351
|
+
* `block`** (#992), with the 32.7% in hand: the scoping to harnessed
|
|
352
|
+
* projects is the answer to "mis-scoped rather than mis-tuned", and a rung
|
|
353
|
+
* that costs a retype is preferred to one that costs a peer's half-day. The
|
|
354
|
+
* first rung of the ladder exists and was skipped deliberately.
|
|
355
|
+
*
|
|
356
|
+
* `RUNGATE_CD_GUARD=warn` and `=off` are both still reachable, so reversing
|
|
357
|
+
* this needs no code change — which is the property #1040 built the mode for.
|
|
358
|
+
*
|
|
359
|
+
* ## An unrecognised value is not silently a default
|
|
360
|
+
*
|
|
361
|
+
* It resolves to the default rung and the caller is TOLD which value it did
|
|
362
|
+
* not understand. `0`, `{}` and silence being indistinguishable from success
|
|
363
|
+
* is `.claude/rules/config-access.md`, and a typo'd
|
|
364
|
+
* `RUNGATE_CD_GUARD=blcok` degrading quietly is that shape exactly. Note the
|
|
365
|
+
* direction moved with the default: an unreadable value now refuses rather
|
|
366
|
+
* than warns, which is the same "err toward refusal" this module takes
|
|
367
|
+
* everywhere else.
|
|
368
|
+
*/
|
|
369
|
+
export type CdGuardMode = "warn" | "block" | "off";
|
|
370
|
+
|
|
371
|
+
/** The env var selecting the rung. Absent means `block` — see above. */
|
|
372
|
+
export const CD_GUARD_MODE_VAR = "RUNGATE_CD_GUARD";
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* The rung taken when nothing selects one. Declared once so the decision is
|
|
376
|
+
* a single site a mutation can move, and so `cdGuardMode`'s two default
|
|
377
|
+
* paths — absent value and unrecognised value — cannot drift apart.
|
|
378
|
+
*/
|
|
379
|
+
export const CD_GUARD_DEFAULT_MODE: CdGuardMode = "block";
|
|
380
|
+
|
|
381
|
+
export interface CdGuardModeReading {
|
|
382
|
+
mode: CdGuardMode;
|
|
383
|
+
/** Set when the configured value was not recognised, naming it. */
|
|
384
|
+
unrecognised?: string;
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
export function cdGuardMode(env: NodeJS.ProcessEnv = process.env): CdGuardModeReading {
|
|
388
|
+
const raw = env[CD_GUARD_MODE_VAR];
|
|
389
|
+
if (raw === undefined || raw === "") return { mode: CD_GUARD_DEFAULT_MODE };
|
|
390
|
+
const v = raw.trim().toLowerCase();
|
|
391
|
+
if (v === "warn" || v === "block" || v === "off") return { mode: v };
|
|
392
|
+
return { mode: CD_GUARD_DEFAULT_MODE, unrecognised: raw };
|
|
393
|
+
}
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A file that is both tracked and ignored (#471).
|
|
3
|
+
*
|
|
4
|
+
* A `.gitignore` rule written with a trailing slash — `node_modules/` — does
|
|
5
|
+
* not match a **symlink** named `node_modules`. `git add .` therefore tracks
|
|
6
|
+
* it, and what lands in the commit is a mode `120000` blob whose entire
|
|
7
|
+
* content is a machine-absolute path:
|
|
8
|
+
*
|
|
9
|
+
* ```
|
|
10
|
+
* $ git ls-files -s node_modules
|
|
11
|
+
* 120000 b8d92fe8221f2696f298301e01225ec1973e5336 0 node_modules
|
|
12
|
+
* $ git cat-file -p b8d92fe8
|
|
13
|
+
* /Users/<someone>/Projects/<their-project>/node_modules
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* Reported from a consumer repo with two such entries against a `.gitignore`
|
|
17
|
+
* that named both correctly. **`git status` was clean throughout**, and that
|
|
18
|
+
* is the whole problem: the rule is right, the mental model is right, and the
|
|
19
|
+
* only thing that reveals the divergence is `git ls-files`.
|
|
20
|
+
*
|
|
21
|
+
* Any worktree-isolated agent that symlinks `node_modules` instead of
|
|
22
|
+
* installing hits this, and the harness is what creates those worktrees.
|
|
23
|
+
*
|
|
24
|
+
* ## The obvious detector does not catch the reported case, measured
|
|
25
|
+
*
|
|
26
|
+
* The shape this was filed as is *fail when `git ls-files` returns a path
|
|
27
|
+
* that `git check-ignore` also matches*. That is a real contradiction and it
|
|
28
|
+
* is the first finding below — but run against the reported case it reports
|
|
29
|
+
* nothing, for the same reason the bug exists:
|
|
30
|
+
*
|
|
31
|
+
* ```
|
|
32
|
+
* $ git check-ignore --no-index -v node_modules
|
|
33
|
+
* $ echo $?
|
|
34
|
+
* 1
|
|
35
|
+
* ```
|
|
36
|
+
*
|
|
37
|
+
* `node_modules/` does not match a symlink named `node_modules`, and
|
|
38
|
+
* `check-ignore` says so just as faithfully as `git add` did. Asking it
|
|
39
|
+
* about a path below the link does not help either — `git check-ignore
|
|
40
|
+
* --no-index node_modules/anything` is `fatal: pathspec ... is beyond a
|
|
41
|
+
* symbolic link`. A detector built only on the agreement between those two
|
|
42
|
+
* commands is narrower than the thing it was written to detect, which is the
|
|
43
|
+
* second shape in `.claude/rules/checks-must-be-able-to-fail.md` arriving in
|
|
44
|
+
* the check rather than in the ignore rule.
|
|
45
|
+
*
|
|
46
|
+
* So there are two findings, and the second is the one that catches #471:
|
|
47
|
+
*
|
|
48
|
+
* 1. **tracked and ignored** — a statement of intent contradicting itself,
|
|
49
|
+
* whatever rule produced it. Catches a `git add -f` of an ignored file.
|
|
50
|
+
* 2. **a tracked symlink pointing at an absolute path** — which needs no
|
|
51
|
+
* ignore rule to be wrong. The blob's content is a path on one machine,
|
|
52
|
+
* so the checkout is broken for everyone else, and no `.gitignore` edit
|
|
53
|
+
* can make it right.
|
|
54
|
+
*
|
|
55
|
+
* ## `--no-index`, and why its absence would be a check that cannot fail
|
|
56
|
+
*
|
|
57
|
+
* `git check-ignore` SKIPS files in the index unless `--no-index` is given.
|
|
58
|
+
* Without it the command is asked about tracked paths and answers about
|
|
59
|
+
* untracked ones, so the comparison is between a list and the empty set and
|
|
60
|
+
* can never report anything. The one flag is the difference between this
|
|
61
|
+
* module and a green line in a report.
|
|
62
|
+
*
|
|
63
|
+
* ## Exit codes, and the fail-open that is one `catch` away
|
|
64
|
+
*
|
|
65
|
+
* `git check-ignore` exits 0 when something matched, **1 when nothing
|
|
66
|
+
* matched**, and 128 on an error. A `try { ... } catch { return [] }` around
|
|
67
|
+
* it reads the error case as the clean case, which is the first shape in
|
|
68
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`. So 1 is a result and
|
|
69
|
+
* anything else is a `failure` the caller must surface.
|
|
70
|
+
*
|
|
71
|
+
* ## It does not read `git status`
|
|
72
|
+
*
|
|
73
|
+
* Asserted by a test, not merely intended. `git status` was clean in the
|
|
74
|
+
* reported case, so a detector that consults it cannot see this at all.
|
|
75
|
+
*/
|
|
76
|
+
import { spawnSync } from "child_process";
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Why a tracked path is a finding. A path can be both.
|
|
80
|
+
*
|
|
81
|
+
* `absolute-symlink` deliberately does not mention ignore rules: a committed
|
|
82
|
+
* link to `/Users/<someone>/...` is wrong in a repository that never had a
|
|
83
|
+
* rule about it.
|
|
84
|
+
*/
|
|
85
|
+
export type FindingReason = "tracked-and-ignored" | "absolute-symlink" | "unreadable-symlink";
|
|
86
|
+
|
|
87
|
+
/** One tracked path that should not be tracked the way it is. */
|
|
88
|
+
export interface Finding {
|
|
89
|
+
path: string;
|
|
90
|
+
/** The index mode: `100644` a file, `100755` executable, `120000` a symlink. */
|
|
91
|
+
mode: string;
|
|
92
|
+
sha: string;
|
|
93
|
+
/**
|
|
94
|
+
* For a symlink, the blob's content — which IS the link target, and is
|
|
95
|
+
* usually an absolute path that means nothing on another machine. Null for
|
|
96
|
+
* anything else: the path and the mode are the finding there.
|
|
97
|
+
*/
|
|
98
|
+
linkTarget: string | null;
|
|
99
|
+
reasons: FindingReason[];
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export interface TrackedIgnoredReading {
|
|
103
|
+
findings: Finding[];
|
|
104
|
+
/**
|
|
105
|
+
* How many tracked paths were compared. An empty corpus and a clean one
|
|
106
|
+
* give the same verdict, and only this tells them apart.
|
|
107
|
+
*/
|
|
108
|
+
trackedCount: number;
|
|
109
|
+
/**
|
|
110
|
+
* Non-null when the comparison could not be made. Never conflated with
|
|
111
|
+
* "nothing found": that conflation is the defect this module is about,
|
|
112
|
+
* arriving in the detector instead of in the ignore rule.
|
|
113
|
+
*/
|
|
114
|
+
failure: string | null;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function run(root: string, args: string[], input?: string): { status: number; stdout: string; stderr: string } {
|
|
118
|
+
const r = spawnSync("git", args, {
|
|
119
|
+
cwd: root,
|
|
120
|
+
input,
|
|
121
|
+
encoding: "utf-8",
|
|
122
|
+
timeout: 120_000,
|
|
123
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
124
|
+
});
|
|
125
|
+
if (r.error) return { status: -1, stdout: "", stderr: r.error.message };
|
|
126
|
+
return { status: r.status ?? -1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** `<mode> <sha> <stage>\t<path>` per NUL-separated record. */
|
|
130
|
+
function parseLsFiles(out: string): Array<{ mode: string; sha: string; path: string }> {
|
|
131
|
+
const entries: Array<{ mode: string; sha: string; path: string }> = [];
|
|
132
|
+
for (const record of out.split("\0")) {
|
|
133
|
+
if (record === "") continue;
|
|
134
|
+
const tab = record.indexOf("\t");
|
|
135
|
+
if (tab === -1) continue;
|
|
136
|
+
const [mode, sha] = record.slice(0, tab).split(/\s+/);
|
|
137
|
+
if (!mode || !sha) continue;
|
|
138
|
+
entries.push({ mode, sha, path: record.slice(tab + 1) });
|
|
139
|
+
}
|
|
140
|
+
return entries;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Every tracked path this repository's ignore rules also match.
|
|
145
|
+
*
|
|
146
|
+
* `root` must be inside a git repository; anything else is a `failure`
|
|
147
|
+
* rather than an empty result.
|
|
148
|
+
*/
|
|
149
|
+
export function trackedAndIgnored(root: string): TrackedIgnoredReading {
|
|
150
|
+
const listed = run(root, ["ls-files", "-s", "-z"]);
|
|
151
|
+
if (listed.status !== 0) {
|
|
152
|
+
return {
|
|
153
|
+
findings: [],
|
|
154
|
+
trackedCount: 0,
|
|
155
|
+
failure: `git ls-files failed (${listed.status}): ${listed.stderr.trim() || "no output"}`,
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
const tracked = parseLsFiles(listed.stdout);
|
|
159
|
+
if (tracked.length === 0) {
|
|
160
|
+
return { findings: [], trackedCount: 0, failure: null };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// `--no-index` or this asks about the wrong set. `--stdin -z` because a
|
|
164
|
+
// path may contain anything, including a newline.
|
|
165
|
+
const checked = run(
|
|
166
|
+
root,
|
|
167
|
+
["check-ignore", "--no-index", "--stdin", "-z"],
|
|
168
|
+
tracked.map(t => t.path).join("\0") + "\0",
|
|
169
|
+
);
|
|
170
|
+
// 0: at least one matched. 1: none did, which is the clean answer and not
|
|
171
|
+
// an error. Anything else is an error, and reporting it as clean is the
|
|
172
|
+
// fail-open this whole module exists to be the opposite of.
|
|
173
|
+
if (checked.status !== 0 && checked.status !== 1) {
|
|
174
|
+
return {
|
|
175
|
+
findings: [],
|
|
176
|
+
trackedCount: tracked.length,
|
|
177
|
+
failure: `git check-ignore failed (${checked.status}): ${checked.stderr.trim() || "no output"}`,
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
const matched = new Set(checked.stdout.split("\0").filter(p => p !== ""));
|
|
182
|
+
const findings: Finding[] = [];
|
|
183
|
+
for (const entry of tracked) {
|
|
184
|
+
const reasons: FindingReason[] = [];
|
|
185
|
+
if (matched.has(entry.path)) reasons.push("tracked-and-ignored");
|
|
186
|
+
|
|
187
|
+
let linkTarget: string | null = null;
|
|
188
|
+
if (entry.mode === "120000") {
|
|
189
|
+
// The blob of a symlink IS its target. `node_modules` tracked as a
|
|
190
|
+
// directory of files is wasteful; `node_modules` tracked as a link to
|
|
191
|
+
// an absolute path is what breaks on another machine, and the mode is
|
|
192
|
+
// the only thing that tells the two apart.
|
|
193
|
+
const blob = run(root, ["cat-file", "-p", entry.sha]);
|
|
194
|
+
linkTarget = blob.status === 0 ? blob.stdout.trim() : null;
|
|
195
|
+
if (linkTarget === null) {
|
|
196
|
+
// A link whose target could not be read is a finding, not a pass.
|
|
197
|
+
// Treating it as "no target, therefore not absolute" would make a
|
|
198
|
+
// broken `cat-file` the cheapest way to clear this check — the
|
|
199
|
+
// fail-open this module's own docstring warns about, one branch
|
|
200
|
+
// below where it warns about it. Found by security review.
|
|
201
|
+
reasons.push("unreadable-symlink");
|
|
202
|
+
} else if (linkTarget.startsWith("/")) {
|
|
203
|
+
// A relative link is a repository making a statement about itself
|
|
204
|
+
// and is portable. An absolute one is a statement about one
|
|
205
|
+
// filesystem.
|
|
206
|
+
reasons.push("absolute-symlink");
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
if (reasons.length > 0) {
|
|
211
|
+
findings.push({ path: entry.path, mode: entry.mode, sha: entry.sha, linkTarget, reasons });
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
return { findings, trackedCount: tracked.length, failure: null };
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** The refusal text, naming the mode and — for a link — where it points. */
|
|
218
|
+
export function describeFindings(reading: TrackedIgnoredReading): string[] {
|
|
219
|
+
if (reading.failure !== null) return [`UNMEASURED: ${reading.failure}`];
|
|
220
|
+
return reading.findings.map(f => {
|
|
221
|
+
const kind = f.mode === "120000" ? "symlink" : `mode ${f.mode}`;
|
|
222
|
+
const target = f.linkTarget !== null ? ` -> ${f.linkTarget}` : "";
|
|
223
|
+
const why = f.reasons
|
|
224
|
+
.map(r => {
|
|
225
|
+
if (r === "tracked-and-ignored") return "matched by this repository's own ignore rules";
|
|
226
|
+
if (r === "absolute-symlink") {
|
|
227
|
+
return "a link to an absolute path, which resolves to nothing on another machine";
|
|
228
|
+
}
|
|
229
|
+
return "UNMEASURED: a link whose target could not be read, so it cannot be judged";
|
|
230
|
+
})
|
|
231
|
+
.join("; ");
|
|
232
|
+
return `${f.path} is tracked (${kind}${target}): ${why}`;
|
|
233
|
+
});
|
|
234
|
+
}
|