rungate 0.6.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 +81 -16
- package/lib/behavioral-cache.ts +150 -2
- 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 +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- 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 +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- 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/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- 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 +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -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/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -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-id-cross-tree.ts +19 -7
- 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 +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- 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/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 +241 -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-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- 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/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One reading of the process table, for every caller that needs one (#690, #707).
|
|
3
|
+
*
|
|
4
|
+
* Two subsystems ask about running processes and they used to ask differently:
|
|
5
|
+
* `lib/test-suite-lock.ts` ran `ps -axo command` and pattern-matched the text,
|
|
6
|
+
* and `~/.pai/hooks/OrphanProcessCleanup.hook.ts` ran `pgrep -f "bun test"` and
|
|
7
|
+
* then `pkill -f "bun test"`. Neither could answer the only question that
|
|
8
|
+
* matters when processes belong to other people — **whose process is this** —
|
|
9
|
+
* because neither read a pid, a parent, or an age.
|
|
10
|
+
*
|
|
11
|
+
* ## A pattern is not a reading, and `pkill` is not a decision
|
|
12
|
+
*
|
|
13
|
+
* `pkill -f <pattern>` has no observation step at all: it matches and signals
|
|
14
|
+
* in one syscall sequence, against whatever the table holds at signal time,
|
|
15
|
+
* including processes that started after whoever ran it decided to run it.
|
|
16
|
+
* There is no pid to record, no list to report, and no way to exclude the
|
|
17
|
+
* shell that launched the thing being killed — `-f` matches the full command
|
|
18
|
+
* line, so the measuring wrapper dies with the measured suite and the exit
|
|
19
|
+
* code is never written. That is #690: two full suites died mid-run on
|
|
20
|
+
* 2026-10-19 leaving logs that end at 323 lines with no summary, which is
|
|
21
|
+
* byte-indistinguishable from a hang.
|
|
22
|
+
*
|
|
23
|
+
* So this module reads ROWS — pid, ppid, elapsed seconds, command — and every
|
|
24
|
+
* decision downstream is taken about a row and signalled to a pid. Nothing in
|
|
25
|
+
* this repository may signal by pattern; `test/orphan-reaper.test.ts` holds
|
|
26
|
+
* that population at zero over `lib`, `hooks`, `scripts`, `workflows`,
|
|
27
|
+
* `gates` and `bin`, with no exemption list.
|
|
28
|
+
*
|
|
29
|
+
* ## An unreadable table is UNMEASURED, and it has a control string
|
|
30
|
+
*
|
|
31
|
+
* `ps` exiting non-zero, printing nothing, or printing something this parser
|
|
32
|
+
* cannot read must NOT come back as "no processes are running" — `0`, `[]`
|
|
33
|
+
* and silence are indistinguishable from success
|
|
34
|
+
* (`.claude/rules/config-access.md`). The control is the cheapest one
|
|
35
|
+
* available and it cannot be absent from a real reading: **the reading must
|
|
36
|
+
* contain the pid of the process taking it.** A table that cannot see its own
|
|
37
|
+
* reader is an instrument failure, and `readProcessTable` throws rather than
|
|
38
|
+
* returning a short list that every caller would read as an idle machine.
|
|
39
|
+
*/
|
|
40
|
+
|
|
41
|
+
import { execFileSync } from "child_process";
|
|
42
|
+
|
|
43
|
+
/** One row of the process table. */
|
|
44
|
+
export interface ProcessRow {
|
|
45
|
+
pid: number;
|
|
46
|
+
ppid: number;
|
|
47
|
+
/** Wall-clock seconds since the process started, from `ps` `etime`. */
|
|
48
|
+
elapsedSeconds: number;
|
|
49
|
+
/** The full command line, `argv` joined by spaces, as `ps` reports it. */
|
|
50
|
+
command: string;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* The process table could not be read, or the reading failed its own control.
|
|
55
|
+
*
|
|
56
|
+
* A distinct type so a caller can report UNMEASURED by name instead of
|
|
57
|
+
* folding the failure into an empty list.
|
|
58
|
+
*/
|
|
59
|
+
export class ProcessTableUnreadable extends Error {
|
|
60
|
+
constructor(reason: string) {
|
|
61
|
+
super(`the process table is UNMEASURED: ${reason}`);
|
|
62
|
+
this.name = "ProcessTableUnreadable";
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The `ps` invocation, in one place so there is one thing to mutate. */
|
|
67
|
+
export const PS_ARGS = ["-axo", "pid=,ppid=,etime=,command="];
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* `etime` in seconds, from BSD `ps`'s four shapes: `SS`, `MM:SS`, `HH:MM:SS`
|
|
71
|
+
* and `DD-HH:MM:SS`.
|
|
72
|
+
*
|
|
73
|
+
* Returns `null` rather than 0 on anything it cannot read. Zero is a real age
|
|
74
|
+
* — a process that started this second — so returning it for a parse failure
|
|
75
|
+
* would make an unreadable row look like the youngest possible process, which
|
|
76
|
+
* is the one state an age floor treats as "definitely leave this alone". That
|
|
77
|
+
* is the safe direction for the floor and the wrong direction for honesty, so
|
|
78
|
+
* the caller is made to decide.
|
|
79
|
+
*/
|
|
80
|
+
export function parseEtime(raw: string): number | null {
|
|
81
|
+
const text = raw.trim();
|
|
82
|
+
if (!/^(\d+-)?(\d+:)?(\d+:)?\d+$/.test(text)) return null;
|
|
83
|
+
const [days, clock] = text.includes("-")
|
|
84
|
+
? [Number(text.slice(0, text.indexOf("-"))), text.slice(text.indexOf("-") + 1)]
|
|
85
|
+
: [0, text];
|
|
86
|
+
const parts = clock.split(":").map(Number);
|
|
87
|
+
if (parts.some((n) => !Number.isFinite(n))) return null;
|
|
88
|
+
let seconds = 0;
|
|
89
|
+
for (const part of parts) seconds = seconds * 60 + part;
|
|
90
|
+
return days * 86_400 + seconds;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Parse `ps -axo pid=,ppid=,etime=,command=` output into rows.
|
|
95
|
+
*
|
|
96
|
+
* Lines this cannot read are DROPPED and counted by the caller's control
|
|
97
|
+
* rather than guessed at — a row with an unparseable age is a row nobody can
|
|
98
|
+
* apply an age floor to.
|
|
99
|
+
*/
|
|
100
|
+
export function parseProcessTable(raw: string): ProcessRow[] {
|
|
101
|
+
const rows: ProcessRow[] = [];
|
|
102
|
+
for (const line of raw.split("\n")) {
|
|
103
|
+
const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(line);
|
|
104
|
+
if (!m) continue;
|
|
105
|
+
const elapsedSeconds = parseEtime(m[3]);
|
|
106
|
+
if (elapsedSeconds === null) continue;
|
|
107
|
+
const command = m[4].trim();
|
|
108
|
+
if (!command) continue;
|
|
109
|
+
rows.push({ pid: Number(m[1]), ppid: Number(m[2]), elapsedSeconds, command });
|
|
110
|
+
}
|
|
111
|
+
return rows;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** How the table is fetched. Injected so no test has to run `ps`. */
|
|
115
|
+
export type ProcessTableReader = () => string;
|
|
116
|
+
|
|
117
|
+
const defaultReader: ProcessTableReader = () =>
|
|
118
|
+
execFileSync("ps", PS_ARGS, { encoding: "utf-8", maxBuffer: 8 * 1024 * 1024 });
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Read the process table, or throw `ProcessTableUnreadable`.
|
|
122
|
+
*
|
|
123
|
+
* The control is applied here and not left to callers: a reading that does
|
|
124
|
+
* not contain `selfPid` is refused. Every caller then gets rows it can trust
|
|
125
|
+
* or an exception it has to name, and neither can be mistaken for an idle
|
|
126
|
+
* machine.
|
|
127
|
+
*/
|
|
128
|
+
export function readProcessTable(
|
|
129
|
+
options: { read?: ProcessTableReader; selfPid?: number } = {},
|
|
130
|
+
): ProcessRow[] {
|
|
131
|
+
const selfPid = options.selfPid ?? process.pid;
|
|
132
|
+
let raw: string;
|
|
133
|
+
try {
|
|
134
|
+
raw = (options.read ?? defaultReader)();
|
|
135
|
+
} catch (e) {
|
|
136
|
+
throw new ProcessTableUnreadable(`ps could not be run (${(e as Error).message})`);
|
|
137
|
+
}
|
|
138
|
+
const rows = parseProcessTable(raw);
|
|
139
|
+
if (!rows.some((r) => r.pid === selfPid)) {
|
|
140
|
+
throw new ProcessTableUnreadable(
|
|
141
|
+
`the reading does not contain the reader's own pid ${selfPid}, ` +
|
|
142
|
+
`so ${rows.length} rows is not a count of what is running`,
|
|
143
|
+
);
|
|
144
|
+
}
|
|
145
|
+
return rows;
|
|
146
|
+
}
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Does THIS project generate `PROJECT-STATE.md` from `project-state.json`?
|
|
3
|
+
* (#781)
|
|
4
|
+
*
|
|
5
|
+
* `.claude/rules/key-files.md` is generated, and one of its rows was a
|
|
6
|
+
* hardcoded literal in two places — `lib/scanner.ts` and
|
|
7
|
+
* `lib/scaffold/steps.ts` — reading *"Live status + handoff (generated from
|
|
8
|
+
* project-state.json — don't edit directly)"*. Every consumer got that
|
|
9
|
+
* sentence, whether or not it was true of them.
|
|
10
|
+
*
|
|
11
|
+
* Measured on one consumer at `e58ab6bb` (named on #781): **no generator exists there.**
|
|
12
|
+
* Nothing in `src/`, `scripts/`, `dashboard/src/` or the `Makefile` reads
|
|
13
|
+
* `project-state.json`, and the two files carry unrelated content — the JSON
|
|
14
|
+
* has priorities and sessions, the Markdown has 27 KB of page inventory, API
|
|
15
|
+
* groups and architecture. An agent that reads the rule, believes it, and
|
|
16
|
+
* regenerates destroys the only authoritative snapshot that repo has, and
|
|
17
|
+
* **the loss presents as a success**: exit 0, `git status` showing `M`, not
|
|
18
|
+
* `D`.
|
|
19
|
+
*
|
|
20
|
+
* ## The generator was asserting a relationship it had no way to check
|
|
21
|
+
*
|
|
22
|
+
* That is the part worth fixing rather than wording around. *"Generated from
|
|
23
|
+
* X"* is a claim about the CONSUMER's build. The sentence that authorises the
|
|
24
|
+
* destructive action was emitted unconditionally by a generator that had
|
|
25
|
+
* never looked.
|
|
26
|
+
*
|
|
27
|
+
* So the row is now a reading. A project with something that reads
|
|
28
|
+
* `project-state.json` is told the file is derived; a project with nothing
|
|
29
|
+
* that reads it is told it is maintained directly; and a scan that could not
|
|
30
|
+
* look at anything says so instead of defaulting to either
|
|
31
|
+
* (`.claude/rules/config-access.md`, *Silent Default Substitution* — `0`,
|
|
32
|
+
* `{}` and silence are indistinguishable from success).
|
|
33
|
+
*
|
|
34
|
+
* ## The cheapest wrong fix, named before the repair
|
|
35
|
+
*
|
|
36
|
+
* **Soften the literal.** Replace both copies with *"Live status + handoff.
|
|
37
|
+
* DA-owned."* and stop. It is one find-and-replace, it removes the
|
|
38
|
+
* authorisation, and #781 lists it as option 1.
|
|
39
|
+
*
|
|
40
|
+
* It is wrong because it is wrong in the other direction for everybody else:
|
|
41
|
+
* this repository DOES generate `PROJECT-STATE.md`, from
|
|
42
|
+
* `scripts/update-project-state.ts`, and a consumer told to edit it directly
|
|
43
|
+
* will have its edits overwritten on the next run. The derivation claim is
|
|
44
|
+
* not false — it is *conditional*, and a fix that deletes it trades one
|
|
45
|
+
* untrue sentence for another.
|
|
46
|
+
*
|
|
47
|
+
* The case that does not survive it is the GENERATOR_FOUND one: a fixture
|
|
48
|
+
* that does read `project-state.json` must still be told the file is
|
|
49
|
+
* derived. A battery with only the no-generator shape in it would have
|
|
50
|
+
* certified the softening.
|
|
51
|
+
*
|
|
52
|
+
* ## Why the scan reports its own coverage
|
|
53
|
+
*
|
|
54
|
+
* #492: a scan that reports a verdict should report how much it read. An
|
|
55
|
+
* empty tree and a tree with no generator produce the same `found: false`,
|
|
56
|
+
* and only one of them is a measurement. `filesScanned` and `bytesScanned`
|
|
57
|
+
* are both carried, and both must be non-zero — a byte count alone is
|
|
58
|
+
* walked past by a single newline, which is measured in that issue.
|
|
59
|
+
*/
|
|
60
|
+
|
|
61
|
+
import { existsSync, readFileSync, readdirSync, statSync } from "fs";
|
|
62
|
+
import { join } from "path";
|
|
63
|
+
|
|
64
|
+
/** The one spelling of the ownership fact, so no site states it twice. */
|
|
65
|
+
export const PROJECT_STATE_OWNERSHIP = "DA-owned (#296)";
|
|
66
|
+
|
|
67
|
+
export const PROJECT_STATE_DERIVED =
|
|
68
|
+
"Live status + handoff (generated from project-state.json — don't edit directly)";
|
|
69
|
+
|
|
70
|
+
export const PROJECT_STATE_UNDERIVED =
|
|
71
|
+
`Live status + handoff. ${PROJECT_STATE_OWNERSHIP} — nothing in this project reads ` +
|
|
72
|
+
"project-state.json, so this file is maintained directly and regenerating it would " +
|
|
73
|
+
"destroy its contents";
|
|
74
|
+
|
|
75
|
+
export const PROJECT_STATE_UNMEASURED =
|
|
76
|
+
`Live status + handoff. ${PROJECT_STATE_OWNERSHIP} — whether anything in this project ` +
|
|
77
|
+
"generates it could not be determined, so do not regenerate it";
|
|
78
|
+
|
|
79
|
+
export type DerivationVerdict = "GENERATOR_FOUND" | "NO_GENERATOR" | "UNMEASURED";
|
|
80
|
+
|
|
81
|
+
export interface DerivationReading {
|
|
82
|
+
verdict: DerivationVerdict;
|
|
83
|
+
/** Project-relative paths that read `project-state.json`. */
|
|
84
|
+
evidence: string[];
|
|
85
|
+
/** How many files the walk actually opened, so a PASS can report its coverage. */
|
|
86
|
+
filesScanned: number;
|
|
87
|
+
/** And how much of them it read — one empty file is not a scan. */
|
|
88
|
+
bytesScanned: number;
|
|
89
|
+
/** Present only on UNMEASURED, and never empty when it is. */
|
|
90
|
+
unmeasuredReason: string | null;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Where a generator could live. Deliberately wider than the source
|
|
95
|
+
* directories `scanner.ts` detects: `scripts/` and `bin/` are where this
|
|
96
|
+
* repository's own updater lives, and a walk that missed them would report
|
|
97
|
+
* NO_GENERATOR for the tree it is running in.
|
|
98
|
+
*/
|
|
99
|
+
const SEARCH_DIRS = ["src", "lib", "gates", "workflows", "hooks", "scripts", "bin", "dashboard/src"];
|
|
100
|
+
const SEARCH_FILES = ["Makefile", "package.json", "justfile", "Taskfile.yml"];
|
|
101
|
+
|
|
102
|
+
/** `.claude/` is excluded on purpose: the rule file naming the claim is not evidence for it. */
|
|
103
|
+
const SKIP_DIRS = new Set([".git", ".claude", "node_modules", "dist", "build", "coverage"]);
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* This module is excluded from its own walk.
|
|
107
|
+
*
|
|
108
|
+
* #646's trap, in the form that is easiest to ship by accident: the file that
|
|
109
|
+
* DECIDES whether a generator exists quotes both of the strings it looks for,
|
|
110
|
+
* so without this it is evidence for itself and every project carrying a copy
|
|
111
|
+
* of rungate's source reads GENERATOR_FOUND. The store quoting the subject
|
|
112
|
+
* back is not a witness.
|
|
113
|
+
*/
|
|
114
|
+
const SELF = "project-state-derivation.ts";
|
|
115
|
+
const TEXTLIKE = /\.(ts|tsx|js|jsx|mjs|cjs|py|rb|go|rs|sh|bash|zsh|json|ya?ml|toml|mk)$/;
|
|
116
|
+
|
|
117
|
+
function walk(dir: string, root: string, acc: { files: string[] }, depth = 0): void {
|
|
118
|
+
if (depth > 8) return;
|
|
119
|
+
let entries;
|
|
120
|
+
try {
|
|
121
|
+
entries = readdirSync(dir, { withFileTypes: true });
|
|
122
|
+
} catch {
|
|
123
|
+
return;
|
|
124
|
+
}
|
|
125
|
+
for (const e of entries) {
|
|
126
|
+
if (SKIP_DIRS.has(e.name)) continue;
|
|
127
|
+
const p = join(dir, e.name);
|
|
128
|
+
if (e.isDirectory()) walk(p, root, acc, depth + 1);
|
|
129
|
+
else if (TEXTLIKE.test(e.name) && e.name !== SELF) acc.files.push(p);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Read the project and say whether anything in it consumes
|
|
135
|
+
* `project-state.json`.
|
|
136
|
+
*
|
|
137
|
+
* One binding, so there is one thing to mutate and one answer. A second
|
|
138
|
+
* notion of "does this project generate it" would agree on every tree anyone
|
|
139
|
+
* has and diverge on the one that matters
|
|
140
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
|
|
141
|
+
*/
|
|
142
|
+
export function projectStateDerivation(root: string): DerivationReading {
|
|
143
|
+
const acc = { files: [] as string[] };
|
|
144
|
+
for (const d of SEARCH_DIRS) {
|
|
145
|
+
const full = join(root, d);
|
|
146
|
+
if (existsSync(full)) walk(full, root, acc);
|
|
147
|
+
}
|
|
148
|
+
for (const f of SEARCH_FILES) {
|
|
149
|
+
const full = join(root, f);
|
|
150
|
+
try {
|
|
151
|
+
if (existsSync(full) && statSync(full).isFile()) acc.files.push(full);
|
|
152
|
+
} catch {
|
|
153
|
+
/* unreadable is not present */
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
const evidence: string[] = [];
|
|
158
|
+
let filesScanned = 0;
|
|
159
|
+
let bytesScanned = 0;
|
|
160
|
+
for (const f of acc.files) {
|
|
161
|
+
let text: string;
|
|
162
|
+
try {
|
|
163
|
+
text = readFileSync(f, "utf-8");
|
|
164
|
+
} catch {
|
|
165
|
+
continue;
|
|
166
|
+
}
|
|
167
|
+
filesScanned++;
|
|
168
|
+
bytesScanned += text.length;
|
|
169
|
+
// BOTH names, not either. A generator reads the JSON and writes the
|
|
170
|
+
// Markdown, and that is the claim being made; a file that merely mentions
|
|
171
|
+
// `project-state.json` — a doc lint, a gitignore check, a path constant —
|
|
172
|
+
// is not one. The direction of a loose predicate matters here: a false
|
|
173
|
+
// GENERATOR_FOUND is the reading that re-authorises destroying the file.
|
|
174
|
+
if (text.includes("project-state.json") && text.includes("PROJECT-STATE.md")) {
|
|
175
|
+
evidence.push(f.startsWith(root) ? f.slice(root.length).replace(/^[/\\]/, "") : f);
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
if (filesScanned === 0 || bytesScanned === 0) {
|
|
180
|
+
return {
|
|
181
|
+
verdict: "UNMEASURED",
|
|
182
|
+
evidence: [],
|
|
183
|
+
filesScanned,
|
|
184
|
+
bytesScanned,
|
|
185
|
+
unmeasuredReason:
|
|
186
|
+
filesScanned === 0
|
|
187
|
+
? "no source file in this project could be read, so nothing was searched for a " +
|
|
188
|
+
"generator — which is not the same fact as there being none (#781)"
|
|
189
|
+
: `${filesScanned} file(s) were walked and none had any content, so the search ` +
|
|
190
|
+
"read nothing (#781)",
|
|
191
|
+
};
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
return {
|
|
195
|
+
verdict: evidence.length > 0 ? "GENERATOR_FOUND" : "NO_GENERATOR",
|
|
196
|
+
evidence: evidence.sort(),
|
|
197
|
+
filesScanned,
|
|
198
|
+
bytesScanned,
|
|
199
|
+
unmeasuredReason: null,
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* The `what` column of `key-files.md`'s PROJECT-STATE.md row.
|
|
205
|
+
*
|
|
206
|
+
* One binding for the three sentences, so the two generators cannot drift —
|
|
207
|
+
* #781's SC-2 is exactly that: a fix applied to one hardcoded copy leaves the
|
|
208
|
+
* other.
|
|
209
|
+
*/
|
|
210
|
+
export function projectStateKeyFileNote(reading: DerivationReading): string {
|
|
211
|
+
switch (reading.verdict) {
|
|
212
|
+
case "GENERATOR_FOUND":
|
|
213
|
+
return PROJECT_STATE_DERIVED;
|
|
214
|
+
case "NO_GENERATOR":
|
|
215
|
+
return PROJECT_STATE_UNDERIVED;
|
|
216
|
+
default:
|
|
217
|
+
return PROJECT_STATE_UNMEASURED;
|
|
218
|
+
}
|
|
219
|
+
}
|
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where `ProjectStateSync` is allowed to run a generator — and everywhere it
|
|
3
|
+
* is not (#1001).
|
|
4
|
+
*
|
|
5
|
+
* ## The defect this exists to close
|
|
6
|
+
*
|
|
7
|
+
* The hook took a `project-state.json` path out of a tool call, stripped the
|
|
8
|
+
* filename, and ran `scripts/update-project-state.ts` from whatever was left:
|
|
9
|
+
*
|
|
10
|
+
* const projectRoot = filePath.replace(/\/project-state\.json$/, "");
|
|
11
|
+
* const script = join(projectRoot, "scripts", "update-project-state.ts");
|
|
12
|
+
* if (!existsSync(script)) …decline…
|
|
13
|
+
* execFileSync("bun", [script, "--skip-tests"], { cwd: projectRoot });
|
|
14
|
+
*
|
|
15
|
+
* `projectRoot` is wherever the tool call pointed. Anything able to write two
|
|
16
|
+
* files — `<anywhere>/project-state.json` and
|
|
17
|
+
* `<anywhere>/scripts/update-project-state.ts` — got code execution as the
|
|
18
|
+
* user, on the next `Write` or `Edit`, in every session on this machine.
|
|
19
|
+
*
|
|
20
|
+
* **It is a permission-gate bypass, and that is the part that matters.**
|
|
21
|
+
* `Bash` is gated far more tightly than `Write`. The agent never runs a
|
|
22
|
+
* command; the hook runs it on the agent's behalf, with the agent's choice of
|
|
23
|
+
* directory. #971/#999 converted the spawn from a shell string to an argv,
|
|
24
|
+
* which closed metacharacter injection and left this untouched — the hook's
|
|
25
|
+
* own header says so: *"`existsSync(script)` above is a bar, not a wall — it
|
|
26
|
+
* only requires the payload to be a real directory, and /tmp is writable."*
|
|
27
|
+
*
|
|
28
|
+
* ## The cheapest wrong fix, named so it cannot be mistaken for this one
|
|
29
|
+
*
|
|
30
|
+
* *"Allow anything under `$HOME/Projects`."* It satisfies the symptom, it is
|
|
31
|
+
* a prefix test, and it is **a new list of trusted paths** — a fourth
|
|
32
|
+
* position declaring something this repo already decides elsewhere. It also
|
|
33
|
+
* does not work: a planted root inside the prefix passes it. `AC-4` is that
|
|
34
|
+
* input, and it is red against that fix.
|
|
35
|
+
*
|
|
36
|
+
* The cheapest wrong fix for the SECOND round is different and more
|
|
37
|
+
* tempting: *"also `realpath` the leaf."* It closes the symlinked-directory
|
|
38
|
+
* hole completely, reads like a security fix in a diff, and leaves the
|
|
39
|
+
* forged repository exactly as open as it was — a forgery's generator is a
|
|
40
|
+
* perfectly ordinary file. `AC-14` is the input it does not survive.
|
|
41
|
+
*
|
|
42
|
+
* ## What is checked instead, and why it delegates
|
|
43
|
+
*
|
|
44
|
+
* **The generator may only run at the root of a real git repository, and it
|
|
45
|
+
* must be a TRACKED file of that repository.** Neither is a list; both are
|
|
46
|
+
* questions something else already answers — `lib/paths.ts:repoRootFrom`
|
|
47
|
+
* resolves `--git-common-dir` and `realpathSync`es the result so callers can
|
|
48
|
+
* compare stable strings, and `git ls-files --error-unmatch` decides
|
|
49
|
+
* membership. No second definition of "trusted root" is declared here.
|
|
50
|
+
*
|
|
51
|
+
* ### Why the repo-root test alone was not enough
|
|
52
|
+
*
|
|
53
|
+
* The first version of this module shipped with only the root test, and its
|
|
54
|
+
* limits note claimed an attacker needed "to create a directory AND run
|
|
55
|
+
* `git init`". That is false, and measured false on this machine:
|
|
56
|
+
*
|
|
57
|
+
* mkdir -p $D/.git/objects $D/.git/refs/heads $D/scripts
|
|
58
|
+
* printf 'ref: refs/heads/main\n' > $D/.git/HEAD
|
|
59
|
+
* git -C $D rev-parse --show-toplevel → $D
|
|
60
|
+
* git -C $D rev-parse --git-common-dir → .git
|
|
61
|
+
*
|
|
62
|
+
* Three `mkdir`s and a 24-byte file, every one of them reachable with
|
|
63
|
+
* `Write` — the exact primitive this issue exists to contain. "Any writable
|
|
64
|
+
* directory" became "any writable directory plus three mkdirs", which is not
|
|
65
|
+
* a narrowing, and saying it was is worse than the gap: a reader checking
|
|
66
|
+
* the limits would have stopped there.
|
|
67
|
+
*
|
|
68
|
+
* The tracked test refuses it, because **the barrier is `.git/index`** — a
|
|
69
|
+
* binary file with a trailing checksum, not something a text write produces.
|
|
70
|
+
* It also asks the better question: *is this generator part of a project*
|
|
71
|
+
* rather than *is there a `.git` directory here*. `AC-14` is the forgery and
|
|
72
|
+
* `AC-15` is an untracked file dropped into a REAL repository, which is what
|
|
73
|
+
* an attacker gets from any checkout on the machine.
|
|
74
|
+
*
|
|
75
|
+
* ### Both sides must be resolved, and this machine is why
|
|
76
|
+
*
|
|
77
|
+
* The obvious spelling of the anchor is wrong:
|
|
78
|
+
*
|
|
79
|
+
* if (claimedRoot !== repoRootFrom(claimedRoot)) decline // WRONG
|
|
80
|
+
*
|
|
81
|
+
* `repoRootFrom` realpaths its answer and the claimed path has not been
|
|
82
|
+
* realpathed, so the two can never agree through a symlink. Measured:
|
|
83
|
+
* `/Users/jhorn/Projects/pai-harness` is a symlink to
|
|
84
|
+
* `/Users/jhorn/Projects/rungate`, and the live `project-state.json` is
|
|
85
|
+
* written through the former. That spelling **refuses the only real caller
|
|
86
|
+
* there is**, silently, as a security improvement. `AC-3` is that input.
|
|
87
|
+
*
|
|
88
|
+
* ### The whole path is resolved, not the leaf
|
|
89
|
+
*
|
|
90
|
+
* `lstat` on the last component sees a link AT the leaf and is blind to one
|
|
91
|
+
* above it: a `scripts` directory symlinked anywhere, with an ordinary file
|
|
92
|
+
* at the end of it, reports no link at all. `projectRoot` is already
|
|
93
|
+
* resolved, so comparing `realpathSync(script)` against the expected path
|
|
94
|
+
* catches a link at ANY depth. `AC-16` is that input, and it asserts the
|
|
95
|
+
* leaf-level `lstat` reads false on it so the arm cannot quietly become a
|
|
96
|
+
* duplicate of `AC-7`.
|
|
97
|
+
*
|
|
98
|
+
* ### A linked worktree is NOT the root of its repository
|
|
99
|
+
*
|
|
100
|
+
* `repoRootFrom` resolves `--git-common-dir`, so from a linked worktree it
|
|
101
|
+
* returns the MAIN checkout. A worktree therefore reads as `not-repo-root`
|
|
102
|
+
* and the generator does not run there. That is a behaviour change and it is
|
|
103
|
+
* deliberate: `PROJECT-STATE.md` is DA-owned and an agent in a worktree must
|
|
104
|
+
* never write it (#296), which #910's SC-3 raised as an open question while
|
|
105
|
+
* the hook was registered on `Write` **and** `Edit` and taking the other
|
|
106
|
+
* answer by default. The outcome is recorded distinctly so the decision is
|
|
107
|
+
* visible in the evidence rather than buried in a refusal count.
|
|
108
|
+
*
|
|
109
|
+
* ## WHAT THIS DOES NOT COVER
|
|
110
|
+
*
|
|
111
|
+
* - **A repository whose CONFIG is hostile.** `repoRootFrom` shells out to
|
|
112
|
+
* `git` in the candidate directory before the tracked-file test can run,
|
|
113
|
+
* and that call is not isolated. `rev-parse --git-common-dir` neither
|
|
114
|
+
* refreshes the index nor fires a hook, so `core.fsmonitor` and
|
|
115
|
+
* `core.hooksPath` do not execute on it — but that is a property of the
|
|
116
|
+
* subcommand, not a boundary. Isolating `repoRootFrom` itself is the right
|
|
117
|
+
* fix and is not done here: `test/harness-root.test.ts` stages
|
|
118
|
+
* `lib/paths.ts` into a scratch directory, so an import added to it fails
|
|
119
|
+
* to load there (`.claude/rules/self-referential-tests.md`, Tier 1).
|
|
120
|
+
* - **A real project someone else controls.** Tracked means part of a
|
|
121
|
+
* project, not part of YOUR project. An attacker who can commit to a
|
|
122
|
+
* repository on this machine can change what the generator does, which is
|
|
123
|
+
* the next item and not a smaller problem.
|
|
124
|
+
* - **A generator that is a regular file with hostile contents.** Confining
|
|
125
|
+
* WHERE is not reviewing WHAT.
|
|
126
|
+
* - **A race between the checks and the spawn.** Everything here resolves
|
|
127
|
+
* paths once; a component swapped for a symlink afterwards is not seen.
|
|
128
|
+
*
|
|
129
|
+
* Issue: #1001. Refs #971, #999, #910, #296.
|
|
130
|
+
*/
|
|
131
|
+
|
|
132
|
+
import { spawnSync } from "child_process";
|
|
133
|
+
import { realpathSync, statSync } from "fs";
|
|
134
|
+
import { isAbsolute, join } from "path";
|
|
135
|
+
import { repoRootFrom } from "./paths";
|
|
136
|
+
import { gitIsolatedArgs, gitIsolatedEnv } from "./git-isolation";
|
|
137
|
+
|
|
138
|
+
/** The generator this hook runs, relative to a project root. */
|
|
139
|
+
export const GENERATOR_RELPATH = join("scripts", "update-project-state.ts");
|
|
140
|
+
|
|
141
|
+
export type ProjectStateTarget =
|
|
142
|
+
| { ok: true; projectRoot: string; script: string }
|
|
143
|
+
/**
|
|
144
|
+
* `outcome` is the string the hook records. Every refusal has one: a
|
|
145
|
+
* decline and a hook that never ran are otherwise the same observation,
|
|
146
|
+
* which is #910.
|
|
147
|
+
*/
|
|
148
|
+
| { ok: false; outcome: string; detail: Record<string, unknown> };
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Resolve a `project-state.json` path to the generator that may run for it.
|
|
152
|
+
*
|
|
153
|
+
* Pure apart from the filesystem reads it is about, and separate from the
|
|
154
|
+
* hook so every refusal has an input that reaches it — a guard that only the
|
|
155
|
+
* hook can exercise is a guard whose ordering nothing can test.
|
|
156
|
+
*/
|
|
157
|
+
export function projectStateTarget(filePath: string): ProjectStateTarget {
|
|
158
|
+
const claimed = filePath.replace(/\/project-state\.json$/, "");
|
|
159
|
+
const detail: Record<string, unknown> = { filePath, claimedRoot: claimed };
|
|
160
|
+
|
|
161
|
+
// Resolve the CLAIMED side too. Without this the comparison below is a
|
|
162
|
+
// string match between a resolved and an unresolved path, which disagrees
|
|
163
|
+
// through any symlink — including the one the real caller arrives through.
|
|
164
|
+
let projectRoot: string;
|
|
165
|
+
try {
|
|
166
|
+
projectRoot = realpathSync(claimed);
|
|
167
|
+
} catch (e) {
|
|
168
|
+
return { ok: false, outcome: "declined-unresolvable-root", detail: { ...detail, error: (e as Error).message } };
|
|
169
|
+
}
|
|
170
|
+
detail.projectRoot = projectRoot;
|
|
171
|
+
|
|
172
|
+
const repoRoot = repoRootFrom(projectRoot);
|
|
173
|
+
if (repoRoot === null) {
|
|
174
|
+
// No repository at all: the planted-directory case this issue is about.
|
|
175
|
+
return { ok: false, outcome: "declined-outside-repo", detail };
|
|
176
|
+
}
|
|
177
|
+
if (repoRoot !== projectRoot) {
|
|
178
|
+
// A subdirectory, or a LINKED WORKTREE — `--git-common-dir` resolves to
|
|
179
|
+
// the main checkout from inside one. Recorded distinctly because of the
|
|
180
|
+
// #296 interaction; `repoRoot` in the detail tells the two apart.
|
|
181
|
+
return { ok: false, outcome: "declined-not-repo-root", detail: { ...detail, repoRoot } };
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
const script = join(projectRoot, GENERATOR_RELPATH);
|
|
185
|
+
// INVARIANT, not a guard. `realpathSync` returns an absolute path and
|
|
186
|
+
// `join` keeps it absolute, so `script` can never be read as a flag by the
|
|
187
|
+
// spawned `bun`. Stated because the pre-fix code had no such guarantee —
|
|
188
|
+
// a `file_path` of `-rf/project-state.json` built the argv
|
|
189
|
+
// `-rf/scripts/update-project-state.ts`, which `bun` parses as options.
|
|
190
|
+
// Asserted rather than branched on: a condition no input can satisfy is
|
|
191
|
+
// not a check (`.claude/rules/checks-must-be-able-to-fail.md`), and
|
|
192
|
+
// pretending otherwise would hide which mechanism actually closes this.
|
|
193
|
+
if (!isAbsolute(script)) {
|
|
194
|
+
throw new Error(`projectStateTarget produced a relative generator path: ${script}`);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// Resolve the WHOLE path, not the leaf. `lstat` on the last component is
|
|
198
|
+
// blind to a symlinked INTERMEDIATE: `scripts` may be a link to anywhere
|
|
199
|
+
// with a perfectly ordinary file at the end of it, and `lstat` reports no
|
|
200
|
+
// link. `projectRoot` is already resolved, so any disagreement here is a
|
|
201
|
+
// link at some depth below it.
|
|
202
|
+
let realScript: string;
|
|
203
|
+
try {
|
|
204
|
+
realScript = realpathSync(script);
|
|
205
|
+
} catch {
|
|
206
|
+
return { ok: false, outcome: "declined-no-generator", detail: { ...detail, script } };
|
|
207
|
+
}
|
|
208
|
+
if (realScript !== script) {
|
|
209
|
+
return {
|
|
210
|
+
ok: false,
|
|
211
|
+
outcome: "declined-symlinked-generator",
|
|
212
|
+
detail: { ...detail, script, resolved: realScript },
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
if (!statSync(realScript).isFile()) {
|
|
216
|
+
return { ok: false, outcome: "declined-no-generator", detail: { ...detail, script } };
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
if (!trackedInRepo(projectRoot, GENERATOR_RELPATH)) {
|
|
220
|
+
// THE ANCHOR. A `.git` directory is three `mkdir`s and a 24-byte `HEAD`
|
|
221
|
+
// away from any `Write`; a TRACKED file is not.
|
|
222
|
+
//
|
|
223
|
+
// LAST, so that every check above it stays reachable. Tracking is the
|
|
224
|
+
// strongest test here, and putting it first would make the symlink
|
|
225
|
+
// branches unreachable — git does not descend a symlinked directory, so
|
|
226
|
+
// a link would be refused as untracked and the branch that exists to
|
|
227
|
+
// name it could never be taken (`.claude/rules/checks-must-be-able-to-fail.md`).
|
|
228
|
+
// Order changes which refusal is RECORDED, never whether one happens:
|
|
229
|
+
// nothing is spawned until all of them pass.
|
|
230
|
+
return { ok: false, outcome: "declined-untracked-generator", detail: { ...detail, script } };
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
return { ok: true, projectRoot, script };
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* Is `relPath` a tracked file of the repository at `root`?
|
|
238
|
+
*
|
|
239
|
+
* `ls-files --error-unmatch` rather than a filesystem test, because the
|
|
240
|
+
* question is *is this part of a project* and only git can answer it. The
|
|
241
|
+
* barrier is the INDEX: `.git/index` is a binary file carrying a trailing
|
|
242
|
+
* checksum, so the three-`mkdir`s forgery that satisfies `rev-parse` has no
|
|
243
|
+
* index at all and this refuses it. Committed content raises the bar again,
|
|
244
|
+
* but the index alone is already past what writing text files can reach.
|
|
245
|
+
*
|
|
246
|
+
* ISOLATED, because this runs `git` in a directory the caller chose and git
|
|
247
|
+
* executes that repository's config — `lib/git-isolation.ts`. `--` so a
|
|
248
|
+
* relative path can never be read as a revision or a flag.
|
|
249
|
+
*/
|
|
250
|
+
function trackedInRepo(root: string, relPath: string): boolean {
|
|
251
|
+
const r = spawnSync("git", gitIsolatedArgs(["-C", root, "ls-files", "--error-unmatch", "--", relPath]), {
|
|
252
|
+
encoding: "utf-8",
|
|
253
|
+
timeout: 5000,
|
|
254
|
+
stdio: ["ignore", "ignore", "ignore"],
|
|
255
|
+
env: gitIsolatedEnv(),
|
|
256
|
+
});
|
|
257
|
+
return r.status === 0;
|
|
258
|
+
}
|