rungate 0.5.0 → 0.6.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/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +184 -88
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/owned-files.ts +42 -2
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +128 -73
- package/lib/scaffold/write-steps.ts +6 -4
- package/lib/scanner.ts +38 -12
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/suite-run-reading.ts +170 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/package.json +1 -1
- 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 +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +4 -1
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* scaffold/ai-review-step.ts — the ai-review job's auth-detect step (#630).
|
|
3
|
+
*
|
|
4
|
+
* One module, one decider. The generated bash is the ONLY place the mode is
|
|
5
|
+
* resolved: there is deliberately no TypeScript `resolveAuthMode(env)` beside
|
|
6
|
+
* it, because two deciders answering the same question about the same input
|
|
7
|
+
* are behaviourally one decider, and no behavioural test can tell them apart
|
|
8
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape). The
|
|
9
|
+
* tests run the script.
|
|
10
|
+
*
|
|
11
|
+
* ## The two traps this step exists to avoid
|
|
12
|
+
*
|
|
13
|
+
* 1. **`secrets` is not available in an `if:` expression** at job or step
|
|
14
|
+
* level — `${{ secrets.X != '' }}` fails workflow validation outright.
|
|
15
|
+
* `vars` is available in both, which makes a `vars`-based condition the
|
|
16
|
+
* tempting fix and the second trap.
|
|
17
|
+
* 2. **A job or step skipped by `if:` reports `skipped`, and a skipped
|
|
18
|
+
* required check can be treated as satisfied.** So nothing here is
|
|
19
|
+
* conditional from the outside: the step always runs, and it branches
|
|
20
|
+
* inside `run:` where it can emit an annotation and choose an exit code.
|
|
21
|
+
*
|
|
22
|
+
* ## The credential-less branch
|
|
23
|
+
*
|
|
24
|
+
* A tree with no credential has not passed an AI review; it has not had one.
|
|
25
|
+
* Those are different states and only one of them is reportable, so mode
|
|
26
|
+
* `none` emits a GitHub warning annotation naming the state UNMEASURED. `0`,
|
|
27
|
+
* `{}`, `null` and `SKIP` are indistinguishable from success; `UNMEASURED`
|
|
28
|
+
* is not. See `.claude/rules/config-access.md`.
|
|
29
|
+
*
|
|
30
|
+
* Whether UNMEASURED should also FAIL the job is the consumer's call, because
|
|
31
|
+
* the honest default for a tree that has never configured a credential is not
|
|
32
|
+
* a red pipeline on the first scaffold. `vars.RUNGATE_REQUIRE_AI_REVIEW` is
|
|
33
|
+
* how a consumer opts in, and it is matched against the exact string `true`
|
|
34
|
+
* — not `TRUE`, not `1`, not a prefix. A loose reading of a variable that
|
|
35
|
+
* turns a gate on is a gate that turns itself on by accident.
|
|
36
|
+
*/
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The exit code every refusal in the generated script routes through.
|
|
40
|
+
*
|
|
41
|
+
* Declared once, interpolated once, and asserted to be the only non-zero exit
|
|
42
|
+
* in this file by `test/ai-review-scaffold.test.ts`. The test builds a mutant
|
|
43
|
+
* copy of this module with it set to 0 and requires the refusal case to stop
|
|
44
|
+
* refusing — a later branch that inlined its own literal would survive that
|
|
45
|
+
* mutation and the case would go green having witnessed nothing.
|
|
46
|
+
*/
|
|
47
|
+
export const AI_REVIEW_REQUIRED_EXIT = 1;
|
|
48
|
+
|
|
49
|
+
/** The four states the step can resolve. Exactly one is reached per run. */
|
|
50
|
+
export type AiReviewAuthMode = "vertex" | "oauth" | "api-key" | "none";
|
|
51
|
+
|
|
52
|
+
export const AI_REVIEW_MODES: readonly AiReviewAuthMode[] = [
|
|
53
|
+
"vertex",
|
|
54
|
+
"oauth",
|
|
55
|
+
"api-key",
|
|
56
|
+
"none",
|
|
57
|
+
];
|
|
58
|
+
|
|
59
|
+
export interface AiReviewCredential {
|
|
60
|
+
/** The repository secret the runner interpolates into the step's env. */
|
|
61
|
+
secret: string;
|
|
62
|
+
/** The mode resolved when that secret is the first non-empty one. */
|
|
63
|
+
mode: Exclude<AiReviewAuthMode, "none">;
|
|
64
|
+
/** What the mode authenticates against, for the step's own log line. */
|
|
65
|
+
describes: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* The credentials, in the order the script tries them.
|
|
70
|
+
*
|
|
71
|
+
* Vertex first: it is the only one that bills a GCP project the consumer
|
|
72
|
+
* already owns, and a tree carrying both a service-account key and a personal
|
|
73
|
+
* OAuth token means the organisation credential, not the individual's.
|
|
74
|
+
*/
|
|
75
|
+
export const AI_REVIEW_AUTH_PRECEDENCE: readonly AiReviewCredential[] = [
|
|
76
|
+
{ secret: "GCP_SA_KEY", mode: "vertex", describes: "Vertex AI" },
|
|
77
|
+
{ secret: "CLAUDE_CODE_OAUTH_TOKEN", mode: "oauth", describes: "a Claude Code OAuth token" },
|
|
78
|
+
{ secret: "ANTHROPIC_API_KEY", mode: "api-key", describes: "the Anthropic API" },
|
|
79
|
+
];
|
|
80
|
+
|
|
81
|
+
/** The repository variable a consumer sets to make UNMEASURED a failure. */
|
|
82
|
+
export const AI_REVIEW_REQUIRE_VAR = "RUNGATE_REQUIRE_AI_REVIEW";
|
|
83
|
+
|
|
84
|
+
/** The exact value of that variable which turns the refusal on. */
|
|
85
|
+
export const AI_REVIEW_REQUIRE_VALUE = "true";
|
|
86
|
+
|
|
87
|
+
/** The step's `id:`, so a later step can read `steps.<id>.outputs.mode`. */
|
|
88
|
+
export const AI_REVIEW_AUTH_STEP_ID = "ai-review-auth";
|
|
89
|
+
|
|
90
|
+
export const AI_REVIEW_AUTH_STEP_NAME = "Detect AI review credentials";
|
|
91
|
+
|
|
92
|
+
/** The annotation title, shared by the warning and the refusal. */
|
|
93
|
+
export const AI_REVIEW_UNMEASURED_TITLE = "AI review UNMEASURED";
|
|
94
|
+
|
|
95
|
+
const SECRET_NAMES = AI_REVIEW_AUTH_PRECEDENCE.map(c => c.secret);
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* The bash the auth-detect step runs.
|
|
99
|
+
*
|
|
100
|
+
* No `set -e`: `[ -n ... ]` returning false is the ordinary control flow here,
|
|
101
|
+
* and a shell that exits on it would resolve `vertex` for every tree. `-u` is
|
|
102
|
+
* safe because every variable is read through `${X:-}` — an unset GitHub
|
|
103
|
+
* secret interpolates to the empty string, so absent and empty have to be the
|
|
104
|
+
* same case anyway.
|
|
105
|
+
*/
|
|
106
|
+
export function buildAuthDetectScript(): string {
|
|
107
|
+
const branches = AI_REVIEW_AUTH_PRECEDENCE.map((c, i) => {
|
|
108
|
+
const keyword = i === 0 ? "if" : "elif";
|
|
109
|
+
return `${keyword} [ -n "\${${c.secret}:-}" ]; then\n mode=${c.mode}`;
|
|
110
|
+
}).join("\n");
|
|
111
|
+
|
|
112
|
+
const warning =
|
|
113
|
+
`No Claude credential is configured ` +
|
|
114
|
+
`(${SECRET_NAMES.join(", ")}), so no AI review ran on this pull request. ` +
|
|
115
|
+
`This check is UNMEASURED, not a passing review. ` +
|
|
116
|
+
`Set the repository variable ${AI_REVIEW_REQUIRE_VAR} to ` +
|
|
117
|
+
`"${AI_REVIEW_REQUIRE_VALUE}" to make an unmeasured review fail instead.`;
|
|
118
|
+
|
|
119
|
+
const refusal =
|
|
120
|
+
`${AI_REVIEW_REQUIRE_VAR} is "${AI_REVIEW_REQUIRE_VALUE}" and no credential ` +
|
|
121
|
+
`is configured, so this pull request has no AI review. Failing rather than ` +
|
|
122
|
+
`reporting a green check for a review that never happened.`;
|
|
123
|
+
|
|
124
|
+
return `# Generated by rungate — lib/scaffold/ai-review-step.ts. Do not edit.
|
|
125
|
+
#
|
|
126
|
+
# Resolves exactly one of ${AI_REVIEW_MODES.length} modes: ${AI_REVIEW_MODES.join(", ")}.
|
|
127
|
+
# The decision is here and not in an \`if:\` expression on purpose — \`secrets\`
|
|
128
|
+
# is unavailable in \`if:\`, and a skipped step can satisfy a required check.
|
|
129
|
+
set -uo pipefail
|
|
130
|
+
|
|
131
|
+
mode=none
|
|
132
|
+
${branches}
|
|
133
|
+
fi
|
|
134
|
+
|
|
135
|
+
echo "ai-review auth mode: \${mode}"
|
|
136
|
+
if [ -n "\${GITHUB_OUTPUT:-}" ]; then
|
|
137
|
+
echo "mode=\${mode}" >> "\${GITHUB_OUTPUT}"
|
|
138
|
+
fi
|
|
139
|
+
|
|
140
|
+
if [ "\${mode}" != none ]; then
|
|
141
|
+
exit 0
|
|
142
|
+
fi
|
|
143
|
+
|
|
144
|
+
echo "::warning title=${AI_REVIEW_UNMEASURED_TITLE}::${warning}"
|
|
145
|
+
|
|
146
|
+
if [ "\${${AI_REVIEW_REQUIRE_VAR}:-}" = "${AI_REVIEW_REQUIRE_VALUE}" ]; then
|
|
147
|
+
echo "::error title=${AI_REVIEW_UNMEASURED_TITLE}::${refusal}" >&2
|
|
148
|
+
exit ${AI_REVIEW_REQUIRED_EXIT}
|
|
149
|
+
fi
|
|
150
|
+
|
|
151
|
+
exit 0
|
|
152
|
+
`;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* The step, as YAML, ready to be indented under a job's `steps:`.
|
|
157
|
+
*
|
|
158
|
+
* Every credential reaches the script through `env:` and nowhere else. That
|
|
159
|
+
* is not style: an expression is interpolated into the script text before
|
|
160
|
+
* bash sees it, so a `${{ secrets.X }}` inside `run:` is a value a crafted
|
|
161
|
+
* secret could break out of, and `${{ vars.X }}` inside `run:` is a shell
|
|
162
|
+
* injection a repository variable can carry.
|
|
163
|
+
*/
|
|
164
|
+
export function buildAuthDetectStep(indent = " "): string {
|
|
165
|
+
const env = [
|
|
166
|
+
...AI_REVIEW_AUTH_PRECEDENCE.map(c => `${c.secret}: \${{ secrets.${c.secret} }}`),
|
|
167
|
+
`${AI_REVIEW_REQUIRE_VAR}: \${{ vars.${AI_REVIEW_REQUIRE_VAR} }}`,
|
|
168
|
+
];
|
|
169
|
+
|
|
170
|
+
const lines = [
|
|
171
|
+
`- name: ${AI_REVIEW_AUTH_STEP_NAME}`,
|
|
172
|
+
` id: ${AI_REVIEW_AUTH_STEP_ID}`,
|
|
173
|
+
` env:`,
|
|
174
|
+
...env.map(e => ` ${e}`),
|
|
175
|
+
` run: |`,
|
|
176
|
+
...buildAuthDetectScript().trimEnd().split("\n").map(l => (l ? ` ${l}` : "")),
|
|
177
|
+
];
|
|
178
|
+
|
|
179
|
+
return lines.map(l => (l ? `${indent}${l}` : "")).join("\n") + "\n";
|
|
180
|
+
}
|
|
@@ -53,6 +53,8 @@
|
|
|
53
53
|
|
|
54
54
|
import { createHash } from "crypto";
|
|
55
55
|
|
|
56
|
+
import { preserveSections } from "../agents-md-sections";
|
|
57
|
+
|
|
56
58
|
/** How the generator writes one owned file. */
|
|
57
59
|
export type WriteStrategy =
|
|
58
60
|
/** Rewritten every run. Reported CHANGED only when the bytes differ. */
|
|
@@ -61,6 +63,8 @@ export type WriteStrategy =
|
|
|
61
63
|
| "provenance"
|
|
62
64
|
/** The harness owns named jobs inside a file a consumer also writes to. */
|
|
63
65
|
| "job-preserving"
|
|
66
|
+
/** The harness owns the file except for named sections, which carry forward (#568). */
|
|
67
|
+
| "section-preserving"
|
|
64
68
|
/** Seeded once and never rewritten. Someone else owns the content. */
|
|
65
69
|
| "create-only";
|
|
66
70
|
|
|
@@ -81,6 +85,16 @@ export interface OwnedFile {
|
|
|
81
85
|
* code does not have — which is the whole of #208.
|
|
82
86
|
*/
|
|
83
87
|
export const OWNED_FILES: OwnedFile[] = [
|
|
88
|
+
{
|
|
89
|
+
// Absent from this list until #568, which is how a run could delete 37
|
|
90
|
+
// lines of a consumer's Hard Constraints and report `REGENERATED`: the
|
|
91
|
+
// most-rewritten file in the tree was the one file with no declared
|
|
92
|
+
// strategy and no route through `decideOwnedWrite`.
|
|
93
|
+
path: "AGENTS.md",
|
|
94
|
+
strategy: "section-preserving",
|
|
95
|
+
customize: "Everything but `## Hard Constraints` is generated from the scan and `.claude/rungate/`; put non-inferable project rules in that section and they carry forward",
|
|
96
|
+
avoid: "Don't hand-edit the generated sections — a re-scaffold rewrites them without reporting it",
|
|
97
|
+
},
|
|
84
98
|
{
|
|
85
99
|
path: ".github/workflows/ci.yml",
|
|
86
100
|
strategy: "job-preserving",
|
|
@@ -206,9 +220,9 @@ export function stampComment(generated: string): string {
|
|
|
206
220
|
}
|
|
207
221
|
|
|
208
222
|
export interface WriteDecision {
|
|
209
|
-
action: "create" | "unchanged" | "changed" | "preserve";
|
|
223
|
+
action: "create" | "unchanged" | "changed" | "preserve" | "refuse";
|
|
210
224
|
reason: string;
|
|
211
|
-
/** The bytes to write. Absent for `unchanged` and `
|
|
225
|
+
/** The bytes to write. Absent for `unchanged`, `preserve` and `refuse`. */
|
|
212
226
|
content?: string;
|
|
213
227
|
}
|
|
214
228
|
|
|
@@ -249,6 +263,32 @@ export function decideOwnedWrite(
|
|
|
249
263
|
return { action: "unchanged", reason: "seeded once; its content is not the harness's" };
|
|
250
264
|
}
|
|
251
265
|
|
|
266
|
+
if (strategy === "section-preserving") {
|
|
267
|
+
// The merge is in `lib/agents-md-sections.ts`; what belongs HERE is the
|
|
268
|
+
// decision, so a strategy cannot be implemented at a call site and left
|
|
269
|
+
// out of the one binding every owned file routes through.
|
|
270
|
+
const merged = preserveSections(existing, generated);
|
|
271
|
+
if (merged.lost.length > 0) {
|
|
272
|
+
return {
|
|
273
|
+
action: "refuse",
|
|
274
|
+
reason:
|
|
275
|
+
`${merged.lost.length} line(s) of user-owned content would be lost, and the spec ` +
|
|
276
|
+
`guarantees they survive regeneration: ${merged.lost.join(" | ")}`,
|
|
277
|
+
};
|
|
278
|
+
}
|
|
279
|
+
if (bytesIdentical(existing, merged.content)) {
|
|
280
|
+
return { action: "unchanged", reason: "regenerated output is byte-identical" };
|
|
281
|
+
}
|
|
282
|
+
return {
|
|
283
|
+
action: "changed",
|
|
284
|
+
reason:
|
|
285
|
+
merged.preserved === null
|
|
286
|
+
? "regenerated output differs"
|
|
287
|
+
: `regenerated output differs; ${merged.preserved.lines.length} line(s) of user-owned content carried forward`,
|
|
288
|
+
content: merged.content,
|
|
289
|
+
};
|
|
290
|
+
}
|
|
291
|
+
|
|
252
292
|
if (strategy === "provenance") {
|
|
253
293
|
const stamped = stampComment(generated);
|
|
254
294
|
if (bytesIdentical(existing, stamped)) {
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
*/
|
|
49
49
|
|
|
50
50
|
import { spawnSync } from "child_process";
|
|
51
|
-
import { mkdtempSync, rmSync, lstatSync, readdirSync, readlinkSync, realpathSync } from "fs";
|
|
51
|
+
import { chmodSync, mkdirSync, mkdtempSync, rmSync, lstatSync, readdirSync, readlinkSync, realpathSync, statSync } from "fs";
|
|
52
52
|
import { tmpdir } from "os";
|
|
53
53
|
import { join, resolve, sep } from "path";
|
|
54
54
|
|
|
@@ -189,8 +189,16 @@ export function cloneForRehearsal(root: string): Rehearsal {
|
|
|
189
189
|
const parent = mkdtempSync(join(tmpdir(), "rungate-rehearsal-"));
|
|
190
190
|
const dir = join(parent, "tree");
|
|
191
191
|
const fail = (why: string): never => {
|
|
192
|
-
|
|
193
|
-
|
|
192
|
+
// Through `removeTree`: what a failed copy leaves behind is whatever
|
|
193
|
+
// made it fail, and a bare `rmSync` here throws that errno in place of
|
|
194
|
+
// the refusal below — so the caller is told the audit crashed rather
|
|
195
|
+
// than why it declined. A clone we cannot clean up is still a decline,
|
|
196
|
+
// so a leftover is appended to the sentence rather than replacing it.
|
|
197
|
+
const leaked = removeTree(parent);
|
|
198
|
+
throw new Error(
|
|
199
|
+
`audit did NOT run: ${why}` +
|
|
200
|
+
(leaked === null ? "" : ` (and the clone is still on disk: ${parent} — ${leaked})`),
|
|
201
|
+
);
|
|
194
202
|
};
|
|
195
203
|
|
|
196
204
|
// `-c` asks for an APFS clonefile. It fails on filesystems that cannot do
|
|
@@ -206,29 +214,13 @@ export function cloneForRehearsal(root: string): Rehearsal {
|
|
|
206
214
|
// on, so no test could ever reach the second branch. One shared helper
|
|
207
215
|
// removes the ordering rather than testing it.
|
|
208
216
|
let method: Rehearsal["method"] = "clone";
|
|
209
|
-
if (attemptCopy(
|
|
210
|
-
if (attemptCopy(
|
|
217
|
+
if (attemptCopy(root, dir, "-Rc", 300_000) !== 0) {
|
|
218
|
+
if (attemptCopy(root, dir, "-R", 600_000) !== 0) {
|
|
211
219
|
return fail("the tree could not be copied");
|
|
212
220
|
}
|
|
213
221
|
method = "copy";
|
|
214
222
|
}
|
|
215
223
|
|
|
216
|
-
// Pruning happens through `rmSync(..., { recursive: true })`, which
|
|
217
|
-
// follows a symlinked PARENT. `.claude/worktrees` in a tree where
|
|
218
|
-
// `.claude -> /real/.claude` therefore resolves outside the clone and
|
|
219
|
-
// deletes the consumer's real worktrees — a destructive path traversal
|
|
220
|
-
// performed by the mode that promises to write nothing. Found by the
|
|
221
|
-
// commit security review.
|
|
222
|
-
//
|
|
223
|
-
// So nothing is deleted through a symlink. Each excluded path is walked
|
|
224
|
-
// component by component; the moment a component is a link, the link
|
|
225
|
-
// itself is unlinked (never followed) and the walk stops. `node_modules`
|
|
226
|
-
// being a symlink is the common case — the pre-push hook makes one — and
|
|
227
|
-
// must stay cheap rather than refusing the audit.
|
|
228
|
-
for (const rel of REHEARSAL_EXCLUDES) {
|
|
229
|
-
prunePathWithoutFollowingLinks(dir, rel);
|
|
230
|
-
}
|
|
231
|
-
|
|
232
224
|
const missing = missingTopLevel(root, dir);
|
|
233
225
|
if (missing.length > 0) {
|
|
234
226
|
return fail(`the copy is incomplete — ${missing.length} top-level entr(ies) missing: ${missing.slice(0, 5).join(", ")}`);
|
|
@@ -248,15 +240,157 @@ export function cloneForRehearsal(root: string): Rehearsal {
|
|
|
248
240
|
}
|
|
249
241
|
|
|
250
242
|
/**
|
|
251
|
-
*
|
|
243
|
+
* One `cp` invocation. Injectable so a test can record what was copied
|
|
244
|
+
* rather than infer it from the result — "this path is absent from the
|
|
245
|
+
* clone" is true under BOTH orderings, so absence cannot witness the fix.
|
|
246
|
+
*/
|
|
247
|
+
export type CopyRunner = (args: string[], timeout: number) => number;
|
|
248
|
+
|
|
249
|
+
const realCp: CopyRunner = (args, timeout) =>
|
|
250
|
+
spawnSync("cp", args, { encoding: "utf-8", timeout }).status ?? 1;
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Copy `src` to `dst`, never reading an excluded path (#549).
|
|
254
|
+
*
|
|
255
|
+
* The exclusion used to be applied AFTER the clone: `cp -R` copied the whole
|
|
256
|
+
* tree and `prunePathWithoutFollowingLinks` then deleted
|
|
257
|
+
* `.claude/worktrees`. On this repository that directory is **737 MB across
|
|
258
|
+
* 104 worktrees**, and the recursive `rm` died with `EFAULT: bad address in
|
|
259
|
+
* system call argument`. So `bunx rungate scaffold .` could not run on
|
|
260
|
+
* rungate — the harness could not scaffold itself, which is SUCCESS.md
|
|
261
|
+
* claim 5 pointed inward. The exclude list was right the whole time; the
|
|
262
|
+
* ORDERING defeated it, and a consumer with a merely LARGE gitignored
|
|
263
|
+
* directory got a preview that silently spent minutes copying files it was
|
|
264
|
+
* about to delete.
|
|
265
|
+
*
|
|
266
|
+
* ## How the level walk works, and why it is not a full recursive copy
|
|
267
|
+
*
|
|
268
|
+
* Only directories that are an ANCESTOR of an exclude are walked. Everything
|
|
269
|
+
* else is handed to `cp` whole, so the APFS clonefile still applies to the
|
|
270
|
+
* subtree and the cost stays bounded by metadata. On this repo that is two
|
|
271
|
+
* walked directories — the root and `.claude` — and one `cp` per top-level
|
|
272
|
+
* entry.
|
|
273
|
+
*
|
|
274
|
+
* ## Symlinks keep the answers `prunePathWithoutFollowingLinks` worked out
|
|
275
|
+
*
|
|
276
|
+
* They were paid for by a commit security review and the reasons have not
|
|
277
|
+
* changed; what changed is that they are now decisions about what to COPY
|
|
278
|
+
* rather than about what to delete, which is strictly safer because a
|
|
279
|
+
* decision not to copy cannot escape the clone.
|
|
280
|
+
*
|
|
281
|
+
* - **An excluded path that is itself a link** (`node_modules -> /elsewhere`,
|
|
282
|
+
* which the pre-push hook creates): skipped. Previously it was copied and
|
|
283
|
+
* then unlinked; now it is never read. Same clone, one fewer traversal.
|
|
284
|
+
* - **A link that is an ANCESTOR of an exclude** (`.claude -> /real/.claude`
|
|
285
|
+
* while excluding `.claude/worktrees`): copied AS A LINK and not descended
|
|
286
|
+
* into. Descending would read the consumer's real tree, and deleting
|
|
287
|
+
* through it is what the old code's `rmSync(..., { recursive: true })`
|
|
288
|
+
* would have done. The link then reaches `escapingSymlinks`, which refuses
|
|
289
|
+
* the audit — which is what an ancestor pointing out of the clone is for.
|
|
290
|
+
*
|
|
291
|
+
* Returns the first non-zero `cp` status, or 0.
|
|
292
|
+
*/
|
|
293
|
+
/**
|
|
294
|
+
* Remove a tree we own, clearing what makes a removal refuse first.
|
|
295
|
+
* Returns `null` when the path is gone, or the reason it is not.
|
|
296
|
+
*
|
|
297
|
+
* Two things stop `rm` on a tree this module created, and neither is a
|
|
298
|
+
* permission the owner actually lacks:
|
|
252
299
|
*
|
|
253
|
-
*
|
|
254
|
-
*
|
|
300
|
+
* - **BSD file flags.** `cp -Rc` is a clonefile and a clonefile carries
|
|
301
|
+
* flags, so a clone of this repo holds the `uchg` files it sets on
|
|
302
|
+
* `gates/prompts/*.md`. `rm` answers "Operation not permitted" and bun
|
|
303
|
+
* reports it as `EFAULT: bad address in system call argument`, naming
|
|
304
|
+
* neither the file nor the flag. That is #549's error message.
|
|
305
|
+
* - **A directory with no owner-read or owner-execute bit.** An unreadable
|
|
306
|
+
* directory is one `cp` cannot copy, so it is exactly what a failed first
|
|
307
|
+
* attempt leaves behind — and `rmSync` cannot list it to empty it. The
|
|
308
|
+
* owner can always chmod it; `rm -rf` never does.
|
|
309
|
+
*
|
|
310
|
+
* Both are best-effort: `chflags` does not exist on Linux, where there are
|
|
311
|
+
* no BSD flags either, and a failing `chmod` is a tree we do not own, which
|
|
312
|
+
* the removal below will report in its own words.
|
|
255
313
|
*/
|
|
256
|
-
function
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
314
|
+
function removeTree(path: string): string | null {
|
|
315
|
+
spawnSync("chflags", ["-R", "nouchg,noschg", path], { timeout: 60_000 });
|
|
316
|
+
spawnSync("chmod", ["-R", "u+rwX", path], { timeout: 60_000 });
|
|
317
|
+
try {
|
|
318
|
+
rmSync(path, { recursive: true, force: true });
|
|
319
|
+
return null;
|
|
320
|
+
} catch (err) {
|
|
321
|
+
if (spawnSync("rm", ["-rf", path], { encoding: "utf-8", timeout: 120_000 }).status === 0) {
|
|
322
|
+
return null;
|
|
323
|
+
}
|
|
324
|
+
return (err as Error).message;
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
export function copyTreeExcluding(
|
|
329
|
+
src: string,
|
|
330
|
+
dst: string,
|
|
331
|
+
excludes: readonly string[],
|
|
332
|
+
cpFlag: string,
|
|
333
|
+
timeout: number,
|
|
334
|
+
run: CopyRunner = realCp,
|
|
335
|
+
): number {
|
|
336
|
+
// Unconditional, so there is one code path rather than two with an
|
|
337
|
+
// ordering between them: a failed `cp -Rc` may have copied part of the
|
|
338
|
+
// tree, and falling back on top of that leaves a PARTIAL clone whose
|
|
339
|
+
// steps report less than `--fix` will do.
|
|
340
|
+
//
|
|
341
|
+
// Through `removeTree`, not a bare `rmSync`. What the first attempt left
|
|
342
|
+
// behind is whatever made it fail — on Linux CI an unreadable directory
|
|
343
|
+
// `cp -R` could not copy and `rmSync` then cannot remove — and a throw
|
|
344
|
+
// here escapes `cloneForRehearsal` as a raw EACCES instead of its refusal
|
|
345
|
+
// sentence. That is the same defect as the one in `discardRehearsal`
|
|
346
|
+
// below, one function earlier.
|
|
347
|
+
if (removeTree(dst) !== null) return 1;
|
|
348
|
+
const paths = excludes.map(e => e.split("/").filter(Boolean)).filter(p => p.length > 0);
|
|
349
|
+
return copyLevel(src, dst, paths, cpFlag, timeout, run);
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
function copyLevel(
|
|
353
|
+
src: string,
|
|
354
|
+
dst: string,
|
|
355
|
+
excludes: string[][],
|
|
356
|
+
cpFlag: string,
|
|
357
|
+
timeout: number,
|
|
358
|
+
run: CopyRunner,
|
|
359
|
+
): number {
|
|
360
|
+
mkdirSync(dst, { recursive: true });
|
|
361
|
+
// The mode of a directory we created ourselves rather than let `cp`
|
|
362
|
+
// create. Without this an 0o700 `.claude` becomes 0o755 in the clone, and
|
|
363
|
+
// a step that reads permissions would see a tree that is not the
|
|
364
|
+
// consumer's.
|
|
365
|
+
try { chmodSync(dst, statSync(src).mode & 0o7777); } catch { /* best effort */ }
|
|
366
|
+
|
|
367
|
+
let entries;
|
|
368
|
+
try {
|
|
369
|
+
entries = readdirSync(src, { withFileTypes: true });
|
|
370
|
+
} catch {
|
|
371
|
+
return 1;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
for (const e of entries) {
|
|
375
|
+
if (excludes.some(p => p.length === 1 && p[0] === e.name)) continue;
|
|
376
|
+
const deeper = excludes.filter(p => p.length > 1 && p[0] === e.name).map(p => p.slice(1));
|
|
377
|
+
// `isDirectory()` is false for a symlink, which is the behaviour this
|
|
378
|
+
// relies on: an ancestor link falls through to the `cp` below and is
|
|
379
|
+
// copied as a link rather than walked.
|
|
380
|
+
if (deeper.length > 0 && e.isDirectory()) {
|
|
381
|
+
const st = copyLevel(join(src, e.name), join(dst, e.name), deeper, cpFlag, timeout, run);
|
|
382
|
+
if (st !== 0) return st;
|
|
383
|
+
continue;
|
|
384
|
+
}
|
|
385
|
+
const st = run([cpFlag, join(src, e.name), join(dst, e.name)], timeout);
|
|
386
|
+
if (st !== 0) return st;
|
|
387
|
+
}
|
|
388
|
+
return 0;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
/** Copy into `dir`, excluding what the clone does not want. */
|
|
392
|
+
function attemptCopy(root: string, dir: string, cpFlag: string, timeout: number): number {
|
|
393
|
+
return copyTreeExcluding(root, dir, REHEARSAL_EXCLUDES, cpFlag, timeout);
|
|
260
394
|
}
|
|
261
395
|
|
|
262
396
|
/**
|
|
@@ -281,54 +415,54 @@ export function missingTopLevel(root: string, dir: string): string[] {
|
|
|
281
415
|
}
|
|
282
416
|
|
|
283
417
|
/**
|
|
284
|
-
*
|
|
285
|
-
*
|
|
286
|
-
*
|
|
287
|
-
*
|
|
288
|
-
*
|
|
289
|
-
*
|
|
290
|
-
*
|
|
291
|
-
*
|
|
292
|
-
*
|
|
293
|
-
*
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
*
|
|
297
|
-
*
|
|
298
|
-
*
|
|
299
|
-
*
|
|
300
|
-
*
|
|
301
|
-
*
|
|
302
|
-
*
|
|
303
|
-
*
|
|
304
|
-
*
|
|
305
|
-
*
|
|
306
|
-
*
|
|
418
|
+
* Throw the clone away. Safe to call twice. Returns why it could not, or
|
|
419
|
+
* `null`.
|
|
420
|
+
*
|
|
421
|
+
* ## The clone can contain files that refuse to be deleted (#549)
|
|
422
|
+
*
|
|
423
|
+
* `cp -Rc` is a clonefile, and a clonefile carries the source's BSD FILE
|
|
424
|
+
* FLAGS. This repository sets `uchg` on `gates/prompts/*.md` — that is the
|
|
425
|
+
* prompt-immutability feature working as designed — so the clone contains
|
|
426
|
+
* immutable files and `rm` refuses them:
|
|
427
|
+
*
|
|
428
|
+
* ```
|
|
429
|
+
* rm: .../tree/gates/prompts/evidence-validator.md: Operation not permitted
|
|
430
|
+
* ```
|
|
431
|
+
*
|
|
432
|
+
* bun reports that as `EFAULT: bad address in system call argument, rm`,
|
|
433
|
+
* which names neither the file nor the flag, and the THROW took down a
|
|
434
|
+
* scaffold run whose report had already printed. That is the whole of #549's
|
|
435
|
+
* symptom: `bunx rungate scaffold .` could not complete on rungate itself.
|
|
436
|
+
* The 737 MB `.claude/worktrees` directory the issue identified made it
|
|
437
|
+
* slower and held most of the flagged copies, and excluding it from the copy
|
|
438
|
+
* is right and necessary — but the thing `rm` was actually refusing was a
|
|
439
|
+
* flag, not a size.
|
|
440
|
+
*
|
|
441
|
+
* So the flags are cleared in the CLONE before it is removed. Only in the
|
|
442
|
+
* clone: `r.parent` always comes from `mkdtemp`, the consumer's own files
|
|
443
|
+
* are never touched, and the flags are deliberately left intact DURING the
|
|
444
|
+
* rehearsal so the steps see the tree the consumer has rather than a more
|
|
445
|
+
* permissive one.
|
|
446
|
+
*
|
|
447
|
+
* ## A cleanup failure is reported, not thrown
|
|
448
|
+
*
|
|
449
|
+
* The report is already printed by the time this runs. Turning a leaked temp
|
|
450
|
+
* directory into a non-zero exit loses the audit; saying nothing loses the
|
|
451
|
+
* leak, which is #437. So it returns the sentence and the caller prints it.
|
|
307
452
|
*/
|
|
308
|
-
function
|
|
309
|
-
let current = root;
|
|
310
|
-
const parts = rel.split("/").filter(Boolean);
|
|
311
|
-
for (let i = 0; i < parts.length; i++) {
|
|
312
|
-
current = join(current, parts[i]!);
|
|
313
|
-
let st;
|
|
314
|
-
try { st = lstatSync(current); } catch { return; } // absent: nothing to prune
|
|
315
|
-
const last = i === parts.length - 1;
|
|
316
|
-
if (st.isSymbolicLink()) {
|
|
317
|
-
if (last) rmSync(current, { force: true });
|
|
318
|
-
return; // an ancestor link: prune nothing, and let the refusal catch it
|
|
319
|
-
}
|
|
320
|
-
if (!last && !st.isDirectory()) return;
|
|
321
|
-
}
|
|
322
|
-
rmSync(current, { recursive: true, force: true });
|
|
323
|
-
}
|
|
324
|
-
|
|
325
|
-
/** Throw the clone away. Safe to call twice. */
|
|
326
|
-
export function discardRehearsal(r: Rehearsal): void {
|
|
453
|
+
export function discardRehearsal(r: Rehearsal): string | null {
|
|
327
454
|
// `r.parent`, not `join(r.dir, "..")`. Deriving a deletion target by
|
|
328
455
|
// walking up from a path is how a cleanup ends up removing something it
|
|
329
456
|
// does not own; the owner is recorded at creation instead. Leaving the
|
|
330
457
|
// mkdtemp behind is the leak #437 is about, so it is the parent that goes.
|
|
331
|
-
|
|
458
|
+
//
|
|
459
|
+
// One binding with the copy's own cleanup, so the flag-clearing and the
|
|
460
|
+
// mode-clearing cannot drift apart between the two places that delete a
|
|
461
|
+
// tree this module made.
|
|
462
|
+
const why = removeTree(r.parent);
|
|
463
|
+
if (why === null) return null;
|
|
464
|
+
return `the rehearsal clone could not be removed and is still on disk: ${r.parent} — ` +
|
|
465
|
+
`${why}. Remove it by hand; nothing in the consumer's tree was touched.`;
|
|
332
466
|
}
|
|
333
467
|
|
|
334
468
|
/**
|