rungate 0.8.12 → 0.8.13
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/bin/rungate.ts +14 -0
- package/gates/.gate-salt +1 -1
- package/lib/board-ready-fanout.ts +237 -0
- package/lib/github.ts +136 -15
- package/lib/harness-identity.ts +56 -0
- package/lib/scaffold/ai-review-findings.ts +39 -0
- package/package.json +1 -1
package/bin/rungate.ts
CHANGED
|
@@ -14,9 +14,23 @@ import { existsSync } from "fs";
|
|
|
14
14
|
import { dirname, join, resolve } from "path";
|
|
15
15
|
import { fileURLToPath } from "url";
|
|
16
16
|
import { CLI_COMMANDS, helpText, runCommandScript } from "../lib/cli-commands";
|
|
17
|
+
import { harnessVersionLine } from "../lib/harness-identity";
|
|
17
18
|
|
|
18
19
|
const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
|
19
20
|
|
|
21
|
+
// Say which version is running, before anything else can fail.
|
|
22
|
+
//
|
|
23
|
+
// On STDERR, and that is the whole design. `ai-review.yml` captures the
|
|
24
|
+
// adjudicator with `2>&1`, so this reaches the CI log either way and nothing
|
|
25
|
+
// is lost by keeping it off stdout — while stdout stays what a caller can
|
|
26
|
+
// parse. `--version` in particular exists to be read by a machine and must
|
|
27
|
+
// remain exactly one line.
|
|
28
|
+
//
|
|
29
|
+
// Emitted for every invocation including `--help` and an unknown command: the
|
|
30
|
+
// runs worth attributing are the ones that went wrong, and a banner that
|
|
31
|
+
// skips the failure paths is absent exactly when it is wanted.
|
|
32
|
+
console.error(harnessVersionLine(PACKAGE_ROOT));
|
|
33
|
+
|
|
20
34
|
const [name, ...rest] = process.argv.slice(2);
|
|
21
35
|
|
|
22
36
|
if (!name || name === "--help" || name === "-h" || name === "help") {
|
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
747398b3ddaddadd72ae597e21f050587654bc584d2f72286d66b4c2a921e001
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* When a blocking issue closes, which of the issues it was blocking should
|
|
3
|
+
* move to Ready — and which should be left exactly where they are.
|
|
4
|
+
*
|
|
5
|
+
* #1744. Moves Claim 7, whose third falsification reads *"a board state
|
|
6
|
+
* reachable only by someone running a command by hand"*. Ready is that today:
|
|
7
|
+
* `board-mirror --ready --write` is the only thing that writes it, and a
|
|
8
|
+
* person has to remember.
|
|
9
|
+
*
|
|
10
|
+
* ## Why an Action at all
|
|
11
|
+
*
|
|
12
|
+
* Researched against docs.github.com on 2026-11-03. GitHub has no built-in
|
|
13
|
+
* workflow keyed on dependencies; `actions/add-to-project` takes only
|
|
14
|
+
* `project-url`, `github-token`, `labeled` and `label-operator` and **cannot
|
|
15
|
+
* set a field**. GitHub's own documented answer for this is a self-written
|
|
16
|
+
* Action driving `updateProjectV2ItemFieldValue`.
|
|
17
|
+
*
|
|
18
|
+
* There is also **no "became unblocked" event**. `issue_dependencies` exists
|
|
19
|
+
* as a webhook but is not a valid Actions `on:` trigger, and
|
|
20
|
+
* `blocked_by_removed` fires when somebody unlinks a dependency, not when the
|
|
21
|
+
* blocker closes. So the trigger is `issues: [closed]` and the fan-out walks
|
|
22
|
+
* that issue's `blocking` list. No cron — a schedule is the thing this exists
|
|
23
|
+
* to remove.
|
|
24
|
+
*
|
|
25
|
+
* GitHub roadmap **#1336 "Granular issue status"** is in public preview and
|
|
26
|
+
* would make this module dead code. That is a reason to keep it small, not a
|
|
27
|
+
* reason to wait.
|
|
28
|
+
*
|
|
29
|
+
* ## What this file deliberately does NOT do
|
|
30
|
+
*
|
|
31
|
+
* **It does not decide readiness.** `isReady` does, and it carries the
|
|
32
|
+
* phase-frontier rule that stopped the Ready lane holding 36 of 46 open
|
|
33
|
+
* issues. A second decider here would agree with it on every input anybody
|
|
34
|
+
* thought to test, so no behavioural case could tell which was live and a
|
|
35
|
+
* mutation of either would leave the other holding the case up. `BR-7`
|
|
36
|
+
* asserts the agreement across a 48-row grid rather than trusting the import.
|
|
37
|
+
*
|
|
38
|
+
* **It does not add anything to the board.** Membership is `board-mirror`'s.
|
|
39
|
+
* An Action that added items would make the board's contents depend on which
|
|
40
|
+
* issues happened to close.
|
|
41
|
+
*/
|
|
42
|
+
import { isReady } from "./board-mirror";
|
|
43
|
+
|
|
44
|
+
/** One issue that the closed blocker was blocking. */
|
|
45
|
+
export interface Dependent {
|
|
46
|
+
readonly number: number;
|
|
47
|
+
/** `OPEN` or `CLOSED`, as GraphQL spells it. */
|
|
48
|
+
readonly state: string;
|
|
49
|
+
readonly phase: number | null;
|
|
50
|
+
/**
|
|
51
|
+
* OPEN blockers only — the lifetime count never goes back down.
|
|
52
|
+
*
|
|
53
|
+
* **`null` means the dependency summary could not be read**, which is not
|
|
54
|
+
* the same as zero. `issueDependenciesSummary` is absent on a response the
|
|
55
|
+
* token was not scoped for, and `?? 0` turned that into "nothing is
|
|
56
|
+
* blocking it" — a fail-open that moves a genuinely blocked issue to
|
|
57
|
+
* Ready. Caught in review of #1747.
|
|
58
|
+
*/
|
|
59
|
+
readonly blockedByOpen: number | null;
|
|
60
|
+
/**
|
|
61
|
+
* **`null` means the assignee count could not be read**, exactly as above.
|
|
62
|
+
* `?? 0` here says "nobody has claimed it", and that is the direction that
|
|
63
|
+
* MOVES — an issue somebody is already working on lands in Ready. The
|
|
64
|
+
* sibling field was fixed for this and this one was left; caught in review
|
|
65
|
+
* of #1747, round 7.
|
|
66
|
+
*/
|
|
67
|
+
readonly assignees: number | null;
|
|
68
|
+
/** Is this issue on the board at all? Membership is `board-mirror`'s. */
|
|
69
|
+
readonly onBoard: boolean;
|
|
70
|
+
/**
|
|
71
|
+
* The board column, or `null` when the item has no Status VALUE.
|
|
72
|
+
*
|
|
73
|
+
* Not the same question as `onBoard`, and the two were one field until
|
|
74
|
+
* review of #1747 round 6. GraphQL returns a
|
|
75
|
+
* `ProjectV2ItemFieldSingleSelectValue` node only for a field that already
|
|
76
|
+
* has a value, so an item added to the project and never given a Status
|
|
77
|
+
* returns no node — producing the same `null` as an issue that is not on
|
|
78
|
+
* the board. One of those means "board-mirror owns this, leave it"; the
|
|
79
|
+
* other means "it is here and I cannot see where".
|
|
80
|
+
*/
|
|
81
|
+
readonly boardStatus: string | null;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export type FanoutDecision =
|
|
85
|
+
| { readonly number: number; readonly move: true }
|
|
86
|
+
| { readonly number: number; readonly move: false; readonly why: string };
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Why `isReady` said no, for the log.
|
|
90
|
+
*
|
|
91
|
+
* **This explains a verdict; it never produces one.** It is only ever called
|
|
92
|
+
* after `isReady` has already returned false, so a wrong or incomplete reason
|
|
93
|
+
* costs a confusing log line and cannot move an issue. Keeping that ordering
|
|
94
|
+
* is what stops it becoming the second decider described above.
|
|
95
|
+
*/
|
|
96
|
+
function whyNotReady(d: Dependent, frontier: number | null): string {
|
|
97
|
+
if (d.state !== "OPEN") return `the issue is ${d.state}`;
|
|
98
|
+
if (d.blockedByOpen === null) return "UNMEASURED — the dependency summary could not be read";
|
|
99
|
+
if (d.blockedByOpen > 0) {
|
|
100
|
+
return `${d.blockedByOpen} open blocker${d.blockedByOpen === 1 ? "" : "s"} remain`;
|
|
101
|
+
}
|
|
102
|
+
if (d.assignees === null) return "UNMEASURED — the assignee count could not be read";
|
|
103
|
+
if (d.assignees > 0) return "somebody has claimed it";
|
|
104
|
+
if (frontier === null) return "no phase has open work, so nothing is next";
|
|
105
|
+
if (d.phase === null) return "no phase milestone — it serves no criterion (ADR-003)";
|
|
106
|
+
if (d.phase !== frontier) return `phase ${d.phase} is behind the frontier at phase ${frontier}`;
|
|
107
|
+
return "isReady said no and this reason list did not anticipate it";
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* One decision per dependent. Writes nothing; the caller performs the moves.
|
|
112
|
+
*/
|
|
113
|
+
export function fanoutDecisions(
|
|
114
|
+
dependents: readonly Dependent[],
|
|
115
|
+
frontier: number | null,
|
|
116
|
+
readyColumn: string,
|
|
117
|
+
): FanoutDecision[] {
|
|
118
|
+
return dependents.map((d): FanoutDecision => {
|
|
119
|
+
if (!d.onBoard) {
|
|
120
|
+
return { number: d.number, move: false, why: "not on the board — board-mirror owns membership" };
|
|
121
|
+
}
|
|
122
|
+
// On the board, and no Status value. Distinct from the line above on
|
|
123
|
+
// purpose: the caller resolves the Status FIELD ID from the item's own
|
|
124
|
+
// value node, so an item that has never had a Status has nothing to
|
|
125
|
+
// write through. Saying "not on the board" sent the reader to
|
|
126
|
+
// board-mirror to add an item that was already there.
|
|
127
|
+
if (d.boardStatus === null) {
|
|
128
|
+
return {
|
|
129
|
+
number: d.number,
|
|
130
|
+
move: false,
|
|
131
|
+
why:
|
|
132
|
+
"UNMEASURED — it is on the board with no Status value, so there is no Status field id " +
|
|
133
|
+
"to write through. This is NOT absent from the board.",
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
if (d.boardStatus === readyColumn) {
|
|
137
|
+
return { number: d.number, move: false, why: `already ${readyColumn}` };
|
|
138
|
+
}
|
|
139
|
+
// An unreadable blocker count is UNMEASURED, and UNMEASURED never moves.
|
|
140
|
+
// It cannot be handed to `isReady`, whose parameter is a number and whose
|
|
141
|
+
// honest answer here does not exist — the question is unanswerable, not
|
|
142
|
+
// answered false. Refusing before the decider is what keeps `isReady` the
|
|
143
|
+
// only thing that says yes.
|
|
144
|
+
if (d.blockedByOpen === null || d.assignees === null) {
|
|
145
|
+
return { number: d.number, move: false, why: whyNotReady(d, frontier) };
|
|
146
|
+
}
|
|
147
|
+
const measured = { ...d, blockedByOpen: d.blockedByOpen, assignees: d.assignees };
|
|
148
|
+
if (!isReady(measured, frontier)) {
|
|
149
|
+
return { number: d.number, move: false, why: whyNotReady(d, frontier) };
|
|
150
|
+
}
|
|
151
|
+
return { number: d.number, move: true };
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** A GraphQL connection, as far as truncation is concerned. */
|
|
156
|
+
interface MaybeTruncated {
|
|
157
|
+
readonly pageInfo?: { readonly hasNextPage?: boolean } | null;
|
|
158
|
+
readonly nodes?: readonly unknown[] | null;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Which dependents had their board membership read only in part.
|
|
163
|
+
*
|
|
164
|
+
* `projectItems` and `fieldValues` are sub-selections inside a paginated
|
|
165
|
+
* list, so cursoring them costs a round trip per node and both are bounded
|
|
166
|
+
* in practice. **"Bounded in practice" is the reasoning that has been wrong
|
|
167
|
+
* four times on this day's work**, so it is not trusted: each is asked for
|
|
168
|
+
* with a `pageInfo`, and a truncated page is UNMEASURED.
|
|
169
|
+
*
|
|
170
|
+
* It matters because a Status field on page two and no Status field at all
|
|
171
|
+
* produce the same `undefined`, and one of those means "leave it alone"
|
|
172
|
+
* while the other means "I could not look".
|
|
173
|
+
*/
|
|
174
|
+
export function truncatedReadings(
|
|
175
|
+
dependents: readonly { readonly number: number; readonly projectItems?: MaybeTruncated | null }[],
|
|
176
|
+
): number[] {
|
|
177
|
+
return dependents
|
|
178
|
+
.filter(d => {
|
|
179
|
+
const items = d.projectItems;
|
|
180
|
+
if (items?.pageInfo?.hasNextPage === true) return true;
|
|
181
|
+
return (items?.nodes ?? []).some(
|
|
182
|
+
(n: any) => n?.fieldValues?.pageInfo?.hasNextPage === true,
|
|
183
|
+
);
|
|
184
|
+
})
|
|
185
|
+
.map(d => d.number);
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* May the identity that triggered this run cause a board write?
|
|
190
|
+
*
|
|
191
|
+
* The first version of this gate was an Actions `if:` reading
|
|
192
|
+
* `github.event.issue.author_association`, and review was right that it
|
|
193
|
+
* checks the wrong person: that field describes whoever OPENED the issue,
|
|
194
|
+
* never whoever closed it. The two differ in both directions and the
|
|
195
|
+
* ordinary direction is the damaging one — a maintainer closing an outside
|
|
196
|
+
* contributor's issue would have been refused, so the feature would have
|
|
197
|
+
* quietly not worked for exactly the issues most likely to come from
|
|
198
|
+
* outside.
|
|
199
|
+
*
|
|
200
|
+
* `repos/{repo}/collaborators/{actor}/permission` answers about the ACTOR.
|
|
201
|
+
* Its `permission` field is one of `admin`, `write`, `read`, `none`, and an
|
|
202
|
+
* unreadable response is `null` — which is UNMEASURED and refuses, because
|
|
203
|
+
* a permission we could not read is not a permission we were granted.
|
|
204
|
+
*/
|
|
205
|
+
export const WRITING_PERMISSIONS: readonly string[] = ["admin", "write", "maintain"];
|
|
206
|
+
|
|
207
|
+
export function actorMayWrite(permission: string | null): boolean {
|
|
208
|
+
if (permission === null) return false;
|
|
209
|
+
return WRITING_PERMISSIONS.includes(permission);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** The credential, or the reason there is no reading to report. */
|
|
213
|
+
export type CredentialReading =
|
|
214
|
+
| { readonly kind: "present"; readonly token: string }
|
|
215
|
+
| { readonly kind: "UNMEASURED"; readonly why: string };
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* `GITHUB_TOKEN` cannot write ProjectsV2, so this needs a PAT or a GitHub
|
|
219
|
+
* App. A run without one has not found nothing to move — it has not looked,
|
|
220
|
+
* and those are different states (`.claude/rules/config-access.md`).
|
|
221
|
+
*
|
|
222
|
+
* Whitespace is absence. A secret that was declared and left empty produces
|
|
223
|
+
* `""`, and treating that as a token turns the refusal into a 401 three calls
|
|
224
|
+
* later, where it reads as GitHub's problem.
|
|
225
|
+
*/
|
|
226
|
+
export function readBoardCredential(env: Record<string, string | undefined>): CredentialReading {
|
|
227
|
+
const raw = (env.BOARD_PROJECT_TOKEN ?? "").trim();
|
|
228
|
+
if (raw === "") {
|
|
229
|
+
return {
|
|
230
|
+
kind: "UNMEASURED",
|
|
231
|
+
why:
|
|
232
|
+
"BOARD_PROJECT_TOKEN is not set. GITHUB_TOKEN cannot write ProjectsV2, " +
|
|
233
|
+
"so this run could not read or move anything — it is UNMEASURED, not clean.",
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
return { kind: "present", token: raw };
|
|
237
|
+
}
|
package/lib/github.ts
CHANGED
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
|
|
21
21
|
import { Octokit } from "@octokit/rest";
|
|
22
22
|
|
|
23
|
+
|
|
23
24
|
// ── Types ──────────────────────────────────────────────────────────────────
|
|
24
25
|
|
|
25
26
|
export interface GitHubClient {
|
|
@@ -193,31 +194,142 @@ export function createGitHubClient(): GitHubClient {
|
|
|
193
194
|
* name hidden in the userinfo (`https://127.0.0.1@evil.com`) are both
|
|
194
195
|
* refused. GitHub Enterprise needs a host outside this list and stays a
|
|
195
196
|
* separate, deliberate decision rather than a side effect of a test seam.
|
|
197
|
+
*
|
|
198
|
+
* **A second caller is coming, and is not here yet** — a paginating reader
|
|
199
|
+
* following `Link: rel="next"`, which is a **response** header, so the host it
|
|
200
|
+
* names is chosen by whoever answered rather than by us. Same question,
|
|
201
|
+
* second input. That reader is `restAll()` in `scripts/work-status.ts` and it
|
|
202
|
+
* lands with #1740; this tree does not contain it.
|
|
203
|
+
*
|
|
204
|
+
* The check is therefore `tokenRefusalReason` below, exported so one decider
|
|
205
|
+
* can answer both: two copies of an allowlist are one guard with a dead twin,
|
|
206
|
+
* and no behavioural case can tell which half it exercised. Written in the
|
|
207
|
+
* future tense on purpose — the earlier wording said "appeared" and "both" of
|
|
208
|
+
* a tree holding one caller, and a reader going to check found nothing and
|
|
209
|
+
* could not tell a split from a sentence nobody updated.
|
|
210
|
+
*
|
|
211
|
+
* It stays in THIS file rather than moving to a leaf module, and the three
|
|
212
|
+
* red checks that settled it are worth recording: SC-528 binds the literals
|
|
213
|
+
* `loopback` and `url.hostname` to `lib/github.ts`, and #827's fixed-point
|
|
214
|
+
* battery copies this file into an `mkdtemp` alone, where a new relative
|
|
215
|
+
* import dies on module resolution — a mutant that fails to load reads as a
|
|
216
|
+
* refusal (`.claude/rules/self-referential-tests.md`, Tier 1, last row).
|
|
196
217
|
*/
|
|
218
|
+
export function resolveApiBaseUrl(): string | undefined {
|
|
219
|
+
const raw = process.env.GITHUB_API_URL?.trim();
|
|
220
|
+
if (!raw) return undefined;
|
|
221
|
+
const reason = tokenRefusalReason(raw);
|
|
222
|
+
if (reason !== null) throw new Error(`GITHUB_API_URL ${reason}`);
|
|
223
|
+
return raw;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* GitHub itself, or a port on this machine. Nothing else.
|
|
228
|
+
*
|
|
229
|
+
* Hostname is compared **exactly**, and the userinfo fields are checked
|
|
230
|
+
* separately — `https://127.0.0.1@evil.com` has hostname `evil.com`, and
|
|
231
|
+
* `https://evil.com@api.github.com` has an allowed hostname while still
|
|
232
|
+
* sending credentials nobody wrote. Neither may pass.
|
|
233
|
+
*/
|
|
234
|
+
// BRACKETED ONLY. These are compared against `url.hostname`, and WHATWG
|
|
235
|
+
// always brackets an IPv6 host — `http://[::1]/x` and the longhand
|
|
236
|
+
// `http://[0:0:0:0:0:0:0:1]/x` both yield `"[::1]"`, and `http://::1/x` is
|
|
237
|
+
// not a parseable URL at all. An unbracketed `"::1"` was here and matched
|
|
238
|
+
// nothing; its removal changes no outcome, which is why the row that holds
|
|
239
|
+
// this is a source assertion rather than a behavioural case.
|
|
240
|
+
const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
|
|
241
|
+
|
|
197
242
|
const ALLOWED_API_HOSTS = new Set([
|
|
198
243
|
"api.github.com",
|
|
199
244
|
"github.com",
|
|
200
|
-
|
|
201
|
-
"127.0.0.1",
|
|
202
|
-
"[::1]",
|
|
203
|
-
"::1",
|
|
245
|
+
...LOOPBACK_HOSTS,
|
|
204
246
|
]);
|
|
205
247
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
248
|
+
/**
|
|
249
|
+
* Why this URL may not carry our bearer token, or `null` when it may.
|
|
250
|
+
*
|
|
251
|
+
* One decider, and these are its callers as this tree actually stands:
|
|
252
|
+
*
|
|
253
|
+
* | caller | where | passes `base` |
|
|
254
|
+
* |---|---|---|
|
|
255
|
+
* | `resolveApiBaseUrl` | ABOVE, over `GITHUB_API_URL` | no |
|
|
256
|
+
* | `assertTokenMayReach` | BELOW, the throwing wrapper | yes, passes through |
|
|
257
|
+
* | `test/token-host-allowlist.test.ts` | the suite | yes, directly |
|
|
258
|
+
*
|
|
259
|
+
* `assertTokenMayReach` has **no in-tree production caller**. It is the entry
|
|
260
|
+
* point `restAll()` in `scripts/work-status.ts` will use, and that lands with
|
|
261
|
+
* #1740 — so today only the suite reaches it, and only the suite exercises
|
|
262
|
+
* `base`, which resolves a relative `Link: rel="next"` against the page it
|
|
263
|
+
* arrived on.
|
|
264
|
+
*
|
|
265
|
+
* Spelled out as a table because prose got it wrong twice: once naming
|
|
266
|
+
* `scripts/work-status.ts` as a current input when this tree lacks the file,
|
|
267
|
+
* and once naming `assertTokenMayReach` as the `GITHUB_API_URL` caller — the
|
|
268
|
+
* wrong function, in the wrong direction, and the one with no caller at all.
|
|
269
|
+
*/
|
|
270
|
+
export function tokenRefusalReason(raw: string, base?: string): string | null {
|
|
209
271
|
let url: URL;
|
|
210
272
|
try {
|
|
211
|
-
url = new URL(raw);
|
|
273
|
+
url = new URL(raw, base);
|
|
212
274
|
} catch {
|
|
213
|
-
|
|
275
|
+
return `is not a valid URL: ${raw}`;
|
|
214
276
|
}
|
|
277
|
+
// **The host check is first, and the order is asserted.** Every refusal
|
|
278
|
+
// here is a refusal whatever the order, so this is about the REASON, and a
|
|
279
|
+
// reason is the only part of a refusal anybody reads. `http://evil.com` and
|
|
280
|
+
// `https://127.0.0.1@evil.com` are host problems that also happen to be a
|
|
281
|
+
// scheme problem and a userinfo problem; reporting the incidental one sends
|
|
282
|
+
// the reader to fix the wrong thing. The existing cases in
|
|
283
|
+
// `test/github-client.test.ts` match on `/loopback/` and caught exactly
|
|
284
|
+
// this when the scheme check was added above them.
|
|
215
285
|
if (!ALLOWED_API_HOSTS.has(url.hostname)) {
|
|
216
|
-
|
|
217
|
-
`GITHUB_API_URL may only point at GitHub or loopback — refusing to send a token to ${url.hostname}`,
|
|
218
|
-
);
|
|
286
|
+
return `may only point at GitHub or loopback — refusing to send a token to ${url.hostname}`;
|
|
219
287
|
}
|
|
220
|
-
|
|
288
|
+
// `https://evil.com@api.github.com` has an ALLOWED hostname and still sends
|
|
289
|
+
// credentials nobody wrote, so this cannot be folded into the check above.
|
|
290
|
+
if (url.username || url.password) {
|
|
291
|
+
return `refuses to send a token to a URL carrying userinfo: ${url.host}`;
|
|
292
|
+
}
|
|
293
|
+
// THE SCHEME IS CHECKED WITHOUT REFERENCE TO THE HOST, and the single
|
|
294
|
+
// condition below used to do both at once:
|
|
295
|
+
//
|
|
296
|
+
// url.protocol !== "https:" && !LOOPBACK_HOSTS.has(url.hostname)
|
|
297
|
+
//
|
|
298
|
+
// which is a conjunction, so a loopback host short-circuited the scheme
|
|
299
|
+
// test away entirely. `ftp://127.0.0.1/x`, `ws://localhost/x` and
|
|
300
|
+
// `gopher://[::1]/x` all returned null. The documented contract is "https
|
|
301
|
+
// everywhere, plain http only for loopback"; what was implemented was "any
|
|
302
|
+
// scheme at all for loopback".
|
|
303
|
+
//
|
|
304
|
+
// It survived six rounds of review on #1740 because the two cases around
|
|
305
|
+
// it each vary one axis and the gap sits on the pair neither visits: one
|
|
306
|
+
// tries a bad scheme on a REAL host, the other tries `http:` on LOOPBACK.
|
|
307
|
+
// Nothing tried a bad scheme on loopback until round 12 read the
|
|
308
|
+
// conjunction itself (`.claude/rules/checks-must-be-able-to-fail.md`, the
|
|
309
|
+
// seventh shape).
|
|
310
|
+
if (url.protocol !== "https:" && url.protocol !== "http:") {
|
|
311
|
+
return `refuses to send a token over ${url.protocol}// to ${url.hostname}`;
|
|
312
|
+
}
|
|
313
|
+
// An allowed hostname over cleartext still puts the token on the wire.
|
|
314
|
+
// `http://api.github.com/x` passes every check above. Loopback keeps
|
|
315
|
+
// `http:` on purpose — a local test server has no certificate and the
|
|
316
|
+
// token never leaves the machine.
|
|
317
|
+
if (url.protocol !== "https:" && !LOOPBACK_HOSTS.has(url.hostname)) {
|
|
318
|
+
return `refuses to send a token over ${url.protocol}// to ${url.hostname}`;
|
|
319
|
+
}
|
|
320
|
+
return null;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* Throw unless this URL may carry the token. `context` names where the URL
|
|
325
|
+
* came from, because "refused" is only actionable when the reader knows which
|
|
326
|
+
* input produced it — an environment variable and a response header are
|
|
327
|
+
* repaired differently.
|
|
328
|
+
*/
|
|
329
|
+
export function assertTokenMayReach(raw: string, context: string, base?: string): URL {
|
|
330
|
+
const reason = tokenRefusalReason(raw, base);
|
|
331
|
+
if (reason !== null) throw new Error(`${context} ${reason}`);
|
|
332
|
+
return new URL(raw, base);
|
|
221
333
|
}
|
|
222
334
|
|
|
223
335
|
/**
|
|
@@ -240,9 +352,18 @@ export function resolveApiBaseUrl(): string | undefined {
|
|
|
240
352
|
* exported-but-unset variable must produce the clear error here rather than
|
|
241
353
|
* an unauthenticated client that 401s somewhere less obvious.
|
|
242
354
|
*/
|
|
243
|
-
export function resolveGitHubToken(
|
|
355
|
+
export function resolveGitHubToken(
|
|
356
|
+
// Injectable so a second implementation can be asserted to AGREE with this
|
|
357
|
+
// one on the same inputs. `scripts/check-state-record-closes.ts` must stay
|
|
358
|
+
// import-free — `test/state-record-closes-mutation.test.ts` asserts it,
|
|
359
|
+
// because its mutants run from a temp directory and a relative import
|
|
360
|
+
// makes every one of them die on module resolution, which reads as a
|
|
361
|
+
// refusal on the merits. So that file cannot call this; the next best
|
|
362
|
+
// thing is that the two cannot silently disagree.
|
|
363
|
+
env: Record<string, string | undefined> = process.env,
|
|
364
|
+
): string | undefined {
|
|
244
365
|
for (const name of ["GITHUB_TOKEN", "GH_TOKEN"]) {
|
|
245
|
-
const v =
|
|
366
|
+
const v = env[name];
|
|
246
367
|
// Trimmed, not just tested: `GH_TOKEN=$(cat token)` carries a trailing
|
|
247
368
|
// newline, and Octokit sends it in the Authorization header, where it
|
|
248
369
|
// 401s with nothing pointing at the whitespace as the cause.
|
package/lib/harness-identity.ts
CHANGED
|
@@ -43,6 +43,62 @@ import { join } from "path";
|
|
|
43
43
|
/** The harness's own package name. The one fact this module knows. */
|
|
44
44
|
export const HARNESS_PACKAGE = "rungate";
|
|
45
45
|
|
|
46
|
+
/**
|
|
47
|
+
* What the CLI says about itself before it does anything (#1598 follow-up).
|
|
48
|
+
*
|
|
49
|
+
* ## The reading this exists to make possible
|
|
50
|
+
*
|
|
51
|
+
* CI invokes the adjudicator as `bunx rungate@<version>`, and the version in
|
|
52
|
+
* that command is **authored text**. It is written into
|
|
53
|
+
* `.github/workflows/ai-review.yml` by the scaffold at generation time, and
|
|
54
|
+
* it is written again into the `::notice` annotation that quotes the command
|
|
55
|
+
* back to the reader. So a log can carry the string `rungate@0.8.4` three
|
|
56
|
+
* times and still not contain a single resolved reading of which version ran.
|
|
57
|
+
*
|
|
58
|
+
* That is not hypothetical. On 2026-10-24 three consecutive attempts to
|
|
59
|
+
* establish a version from a run log were wrong in the same direction, each
|
|
60
|
+
* correction finding the next layer:
|
|
61
|
+
*
|
|
62
|
+
* | the reading | why it cannot attribute a version |
|
|
63
|
+
* |---|---|
|
|
64
|
+
* | grep the log for `rungate@0.8.x` | matches the PR body, echoed by the round-counting step |
|
|
65
|
+
* | the same grep with colour codes excluded | still matches the annotation, which is authored |
|
|
66
|
+
* | bun's resolve block above the adjudication | prints `Resolved, downloaded and extracted [76]` — a count, no name, no version |
|
|
67
|
+
*
|
|
68
|
+
* The version had to be recovered from outside the log entirely, by reading
|
|
69
|
+
* the pin out of `ai-review.yml` at main's commit as of the run's
|
|
70
|
+
* `createdAt`. That works and it is three readings, two of which are easy to
|
|
71
|
+
* take against the wrong tree — `refs/pull/<N>/merge` is recomputed when main
|
|
72
|
+
* moves, so it describes a tree the run never saw.
|
|
73
|
+
*
|
|
74
|
+
* One line printed by the running process collapses all three into one.
|
|
75
|
+
*
|
|
76
|
+
* ## Why the spelling is deliberately not the pin's
|
|
77
|
+
*
|
|
78
|
+
* `rungate-version:` rather than `rungate@<v>`. If the announcement used the
|
|
79
|
+
* pin's spelling, a grep for a resolved value would match authored text again
|
|
80
|
+
* and this would have bought nothing — the defect reproduced inside its own
|
|
81
|
+
* fix. The marker is the discriminator; the version is the payload.
|
|
82
|
+
*
|
|
83
|
+
* ## UNMEASURED rather than a plausible default
|
|
84
|
+
*
|
|
85
|
+
* An unreadable or version-less `package.json` returns `UNMEASURED`, not a
|
|
86
|
+
* guess and not an empty string. A version that could not be read must not be
|
|
87
|
+
* spelled the same as one that could — `.claude/rules/config-access.md`,
|
|
88
|
+
* *Silent Default Substitution*. It does not throw: a CLI that dies because
|
|
89
|
+
* it could not introduce itself is worse than one that cannot.
|
|
90
|
+
*/
|
|
91
|
+
export function harnessVersionLine(root: string): string {
|
|
92
|
+
let version: unknown;
|
|
93
|
+
try {
|
|
94
|
+
version = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"))?.version;
|
|
95
|
+
} catch {
|
|
96
|
+
version = undefined;
|
|
97
|
+
}
|
|
98
|
+
const resolved = typeof version === "string" && version.length > 0 ? version : "UNMEASURED";
|
|
99
|
+
return `rungate-version: ${resolved} (resolved at runtime, not the pin)`;
|
|
100
|
+
}
|
|
101
|
+
|
|
46
102
|
export function isHarnessItself(root: string): boolean {
|
|
47
103
|
try {
|
|
48
104
|
return JSON.parse(readFileSync(join(root, "package.json"), "utf-8"))?.name === HARNESS_PACKAGE;
|
|
@@ -1016,6 +1016,25 @@ export interface AiReviewThreadRequest {
|
|
|
1016
1016
|
* a hunk, which is a separate 422 the caller has to be able to fall back
|
|
1017
1017
|
* from. Dropping here would silently lose findings whose only defect is that
|
|
1018
1018
|
* the reviewer wrote no line number.
|
|
1019
|
+
*
|
|
1020
|
+
* **A finding whose file is not in the diff is not requested, blocking or
|
|
1021
|
+
* not.** `unlocatableReported` is populated by `readPayload`'s DEMOTION
|
|
1022
|
+
* branch, and that branch only runs for a finding that BLOCKS — so the
|
|
1023
|
+
* subtraction above cannot see a non-blocking finding carried forward onto a
|
|
1024
|
+
* path this branch has since stopped touching. It was sent, and GitHub
|
|
1025
|
+
* answered `422 pull_request_review_thread.path "could not be resolved"` at
|
|
1026
|
+
* the line AND again at file level, because the caller's demotion answers
|
|
1027
|
+
* "the line moved" and has no answer for "the file left". That lands in
|
|
1028
|
+
* `failed`, the one refusing outcome. Observed on #1740 head
|
|
1029
|
+
* `1d95e1da457cf5fc91298bd017a94087b8244d46`, run `41950364518`: two carried
|
|
1030
|
+
* findings on `lib/github.ts`, `0 of 2 posted`, exit 1, and a required check
|
|
1031
|
+
* permanently red over a branch with nothing wrong in it.
|
|
1032
|
+
*
|
|
1033
|
+
* The two skips are NOT the fourth shape in
|
|
1034
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`, because each has an input
|
|
1035
|
+
* the other cannot answer: a MEASURED scope with `unlocatableReported` null
|
|
1036
|
+
* is reachable only by the scope check, and a reading carrying no scope with
|
|
1037
|
+
* `unlocatableReported` set is reachable only by the subtraction.
|
|
1019
1038
|
*/
|
|
1020
1039
|
export function reviewThreadRequests(
|
|
1021
1040
|
reading: AiReviewFindingsReading,
|
|
@@ -1025,11 +1044,31 @@ export function reviewThreadRequests(
|
|
|
1025
1044
|
if (reading.reported === null) return [];
|
|
1026
1045
|
const unlocatable = new Set(reading.unlocatableReported ?? []);
|
|
1027
1046
|
|
|
1047
|
+
// Only a scope that was TAKEN can retire anything. `NOT_SUPPLIED` and
|
|
1048
|
+
// `UNMEASURED` leave `touched` null, which `findingPathScope` answers
|
|
1049
|
+
// `NOT_CHECKED` for every finding — a reading nobody took is not a pull
|
|
1050
|
+
// request that touched nothing, and must never become a blanket excuse for
|
|
1051
|
+
// posting less.
|
|
1052
|
+
const scope = reading.scope;
|
|
1053
|
+
let touched: ReadonlySet<string> | null = null;
|
|
1054
|
+
if (scope?.status === "MEASURED") {
|
|
1055
|
+
// The same conversion `readPayload` makes, through the same function, so
|
|
1056
|
+
// the skip here and the demotion there cannot disagree about one finding.
|
|
1057
|
+
const { readable } = partitionChangedFiles(scope.files);
|
|
1058
|
+
// Nothing readable left is the input `readPayload` refuses the whole
|
|
1059
|
+
// reading over, for the reason stated there: comparing against it would
|
|
1060
|
+
// retire every finding. Here the equivalent is to decide nothing.
|
|
1061
|
+
if (readable.length > 0) touched = new Set(readable);
|
|
1062
|
+
}
|
|
1063
|
+
|
|
1028
1064
|
const requests: AiReviewThreadRequest[] = [];
|
|
1029
1065
|
for (const item of reading.reported) {
|
|
1030
1066
|
if (unlocatable.has(item)) continue;
|
|
1031
1067
|
if (typeof item !== "object" || item === null) continue;
|
|
1032
1068
|
const finding = item as Record<string, unknown>;
|
|
1069
|
+
// `PRE_EXISTING` only. `UNDECIDABLE` is a path this reader could not
|
|
1070
|
+
// compare, and it keeps the behaviour the line below already gives it.
|
|
1071
|
+
if (findingPathScope(finding, touched) === "PRE_EXISTING") continue;
|
|
1033
1072
|
|
|
1034
1073
|
const raw = finding[f.file];
|
|
1035
1074
|
// Readability is asked of the normalised spelling; the answer is carried
|