From 9168f629780101790f125c2b62e5f16088b17ba9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:08:21 -0800 Subject: [PATCH 01/10] chore(quest): claim quest/m0/github-quota/installation-token.md Quest-Claim: b64d41df3c92d367 From be2c722e2c2b982412737b992e7fd00695ee61ba Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:17:12 -0800 Subject: [PATCH 02/10] feat(github)!: read on an installation token from Kixel Quest Co-Authored-By: Claude Sonnet 5.5 --- README.md | 14 ++ quest/m0/github-quota/README.md | 47 ++-- quest/m0/github-quota/installation-token.md | 58 ----- src/cli/claims.ts | 9 +- src/cli/forge.ts | 103 +++++++- src/cli/installation.ts | 74 ++++++ src/cli/main.ts | 20 +- src/cli/review-record.ts | 2 +- src/cli/start.ts | 4 +- src/github/claims.ts | 10 +- src/github/client.ts | 100 ++++++-- src/github/duplicates.ts | 4 +- src/github/files.ts | 6 +- src/github/forge.ts | 18 +- src/github/hold.ts | 16 +- src/github/index.ts | 10 +- src/github/online-review.ts | 6 +- src/github/signals.ts | 6 +- src/github/status.ts | 20 +- src/github/view.ts | 4 +- src/github/wait.ts | 12 +- test/forge-writes.test.ts | 1 + test/forge.test.ts | 29 ++- test/installation.test.ts | 253 ++++++++++++++++++++ test/pull-files.test.ts | 2 + test/start.test.ts | 8 +- test/status-fakes.ts | 6 +- test/status.test.ts | 4 +- test/usage.test.ts | 1 + test/wait-fakes.ts | 8 +- 30 files changed, 657 insertions(+), 198 deletions(-) delete mode 100644 quest/m0/github-quota/installation-token.md create mode 100644 src/cli/installation.ts create mode 100644 test/installation.test.ts diff --git a/README.md b/README.md index cef4502f..17a735f7 100644 --- a/README.md +++ b/README.md @@ -636,6 +636,20 @@ command fails too, naming `QUEST_FORGE=github`, which reads GitHub instead. `QUEST_KIXEL_URL` names another Kixel Quest, such as one running locally, whose token the same file pairs with its URL. +A read that must come from GitHub itself, such as `quest pr view` or the +open-PR checks of `quest start`, uses a read-only App installation token Kixel +Quest mints for that repository, so it draws on the installation's rate limit, +not the person's. `POST /installation-token` takes `{"repository": +"owner/repo"}` and answers `{token, expiresAt, repository, login}`; a 404 means +Kixel Quest does not serve the repository, and `quest` reads it with the +person's own token. `quest` keeps each token in +`$XDG_CACHE_HOME/quest/installation` (else `~/.cache/quest/installation`) until +five minutes before it expires, since a person may mint only so many an hour, +and a 429 or any other failure fails the command, naming `QUEST_FORGE=github`. +Writes, such as comments, pushes, and merges, always use the person's own token, +so they are made in their name; `quest wait` takes the person from the mint's +`login`, because on an installation token GitHub names the App as the viewer. + Its read API lives under `/forge`, with the token as a bearer token: `GET /forge` answers `{"login", "repositories"}`, the person the token names and the lowercase `owner/repo` of each repository served to them, and diff --git a/quest/m0/github-quota/README.md b/quest/m0/github-quota/README.md index 5c49b25a..f69ae39d 100644 --- a/quest/m0/github-quota/README.md +++ b/quest/m0/github-quota/README.md @@ -1,12 +1,14 @@ -# Spend less of a person's GitHub quota +# [S] Record a day of GitHub quota use under the new reads ## Goal -Agents polling `quest status`, `quest wait`, and `quest unblocked` stop -draining the GitHub quota of the person running them. Three changes, each -useful alone: every REST GET revalidates with an ETag, reads use an App -installation token from Kixel Quest instead of the person's, and a forge -interface lets quest read pull request state from Kixel Quest's index. +Agents polling `quest status`, `quest wait`, and `quest unblocked` no longer +drain the GitHub quota of the person running them: every REST GET revalidates +with an ETag, reads use an App installation token from Kixel Quest, and a forge +interface reads pull request state from Kixel Quest's index. All three have +landed; what remains is the evidence. Record the person's REST `core` and +GraphQL use over a day of the maintainer's agents, from `gh api rate_limit`, +beside the outage day's, in this quest's PR, then delete this quest. Non-goals: emulating GitHub's API in Kixel Quest, and anything new for outside contributors, who keep reading GitHub with their own token. @@ -15,27 +17,12 @@ outside contributors, who keep reading GitHub with their own token. Decided 2026-11-15 (maintainer, `/quest-plan` in kixel-ai/kixel.quest, [kixel-ai/kixel.quest#48](https://github.com/kixel-ai/kixel.quest/pull/48), -"we're rate limited by github"): ✅ all three of reads from Kixel Quest, -ETags on every GET, and reads on an installation token (rejected: any one -alone). That day REST `core` sat at 0 of 5,000 on the maintainer's token -while about 20 agents checked PR status. - -Decided 2026-11-15 (maintainer, `/quest-plan` here): - -- ✅ quest has Kixel Quest's URL built in, overridable by an environment - variable for development, and names a repository by `owner/repo` from its - remote (rejected: a committed `.quest.json` naming the endpoint, which no - repository had committed yet and which could drift from what Kixel Quest - indexes). Kixel Quest says which repositories it serves; the rest use - GitHub. Session records route the same way. -- ✅ Kixel Quest is used only by a person holding a Kixel Quest token, which - its admin-managed allow-list gives out; outside contributors stay a - non-goal for now (rejected: a self-serve contributor role, picked and then - withdrawn in the same interview). -- ✅ A chosen Kixel Quest backend that errors fails the command and names the - setting that forces GitHub (rejected: falling back to GitHub, which hides - a broken index and spends the quota this saves). - -The epic's closing PR records the person's REST `core` and GraphQL use over a -day of the maintainer's agents, from `gh api rate_limit`, beside the outage -day's. +"we're rate limited by github"): all three of reads from Kixel Quest, ETags on +every GET, and reads on an installation token. That day REST `core` sat at 0 of +5,000 on the maintainer's token while about 20 agents checked PR status. + +An installation token serves only reads that go to GitHub itself, such as `quest +pr view` and the verifying reads of `quest start`; where Kixel Quest serves the +repository, its index answers the rest. Compare the person's own `core` and +GraphQL `used` per hour, from `gh api rate_limit`, on a day the maintainer's +agents ran as usual. diff --git a/quest/m0/github-quota/installation-token.md b/quest/m0/github-quota/installation-token.md deleted file mode 100644 index f161eeec..00000000 --- a/quest/m0/github-quota/installation-token.md +++ /dev/null @@ -1,58 +0,0 @@ -# [S] Read on an installation token from Kixel Quest - -## Goal - -A person signed in to Kixel Quest reads GitHub on a short-lived, read-only -App installation token that Kixel Quest mints, so their reads draw on the -installation's own rate-limit bucket, not their personal 5,000 an hour. -Writes, such as comments, pushes, and merges, stay on the person's token, -so they are made in that person's name. - -## Plan - -Decided 2026-11-15 (maintainer, `/quest-plan`): ✅ Kixel Quest mints the token -(rejected: the App's private key on every host, which would put a key that -writes to every installation on every agent host). - -- quest trades the person's Kixel Quest token for an installation token - scoped to one repository with read permissions, and caches it on disk - until shortly before it expires. -- The endpoint, from - [kixel-ai/kixel.quest#51](https://github.com/kixel-ai/kixel.quest/pull/51): - `POST /installation-token` with the person's Kixel Quest token as a bearer - token and `{"repository": "owner/repo"}`. A 200 answers - `{token, expiresAt, repository, login}`. A 404 means the repository is not - indexed or the person cannot read it; 429, with `Retry-After`, means the - person hit the per-person hourly cap; 502 and 503 mean GitHub or the App - refused the mint. -- Cache each token by repository until shortly before `expiresAt`: a host - then mints about once per repository an hour, and minting per command - would hit the cap within a minute. -- Without a Kixel Quest token, or on a 404, reads use the person's token as - today, since the answer says the repository is not served. Any other - error fails the command naming the setting that forces the person's - token, as the [epic](/quest/m0/github-quota/README.md) decided for the - Kixel Quest backend; a 429 never quietly spends the person's quota. -- Split the client's dependencies so a read and a write each say which token - they use; a write on the installation token must not compile. -- Keep the caller's identity apart from the read credential. `quest wait` - reads `viewer { login }` in the same query as the PR's activity - (`src/cli/wait.ts`) to ignore the person's own replies, reactions, labels, - and edits; on an installation token `viewer` is the App, so the person's - own activity would wake the waiter. Take the person from the mint - response's `login` and pass it in. - -Tests: with a fake Kixel Quest and a fake GitHub, a read goes out on the -minted token and a write on the person's; the token is minted once and -reused until near expiry; a 404 reads on the person's token and a 429 -fails naming the override; the person's own reply, reaction, label, and -edit still do not wake `quest wait` when its reads use the minted token; -and a repository Kixel Quest does not serve reads on the person's token. - -## Waiting - -- kixel-ai/kixel.quest: the endpoint above, in - [kixel-ai/kixel.quest#51](https://github.com/kixel-ai/kixel.quest/pull/51), - merged and deployed. Check that #51 merged and that `curl -X POST - https://kixel.quest/installation-token` without a token answers 401, not - 404. diff --git a/src/cli/claims.ts b/src/cli/claims.ts index a84fe294..322f1c51 100644 --- a/src/cli/claims.ts +++ b/src/cli/claims.ts @@ -6,7 +6,6 @@ import { type Remote, readRemote, remoteHost, remoteRepository, requireRemote } import { type GitHubDependencies, GitHub, object, repositoryPath, string } from "../github/client"; import type { Claim, Forge, ForgeWrites, Holdings, OpenPull, Repository } from "../core"; import { questBranches } from "../github/claims"; -import { GitHubForge } from "../github/forge"; import { landingCheck } from "./landed"; import { GitHubWrites } from "./writes"; import { type Snapshot, snapshot } from "./tree"; @@ -16,6 +15,8 @@ export interface ClaimDependencies { github(): GitHubDependencies; /** The forge answering reads of a repository on GitHub, such as its claims and open PRs. */ forge(repository: Repository): Promise; + /** The forge answering a read of a repository on GitHub from GitHub itself, never an index that may lag. */ + live(repository: Repository): Promise; /** Kixel Quest, for remotes on it; without it, no remote is. */ kixel?: { /** The repository `url` on Kixel Quest names, or null for none. */ @@ -38,7 +39,7 @@ export interface Hosting { /** The forge answering reads of `repository`, chosen on first use. */ forge(): Promise; /** The forge's own answers, never an index that may lag, for a read that verifies or rewrites what it read. */ - live(): Forge; + live(): Promise; /** The forge taking writes to `repository`, created on first use. */ writes(): ForgeWrites; /** A link to `path` on the default branch, where the forge shows files. */ @@ -91,7 +92,7 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen defaultBranch: defaultBranch(root, remote.name), prefix: git(root, ["rev-parse", "--show-prefix"]), forge: async () => forge(), - live: forge, + live: async () => forge(), writes: forge, link: () => null, }, @@ -121,7 +122,7 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen defaultBranch: up.defaultBranch, prefix, forge: () => (forge ??= deps.forge(up.repository)), - live: () => new GitHubForge(deps.github()), + live: () => deps.live(up.repository), writes: () => (writes ??= new GitHubWrites(deps.github(), landingCheck(root))), link: (path: string) => `https://github.com/${owner}/${repo}/blob/${up.defaultBranch}/${encodeURI(prefix + path)}`, diff --git a/src/cli/forge.ts b/src/cli/forge.ts index dc62b203..791d3a20 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -1,7 +1,9 @@ // Which forge answers a repository's reads and takes its writes. A repository Kixel Quest hosts, named by a remote or // PR URL on Kixel Quest, is read and written there alone. For one on GitHub, reads go to Kixel Quest's index for a // person holding its token when it serves the repository, else GitHub, and writes go to GitHub. A Kixel Quest failure -// fails the command, naming the setting that reads GitHub instead where that would help. +// fails the command, naming the setting that reads GitHub instead where that would help. A read that goes to GitHub +// anyway, to verify what an index said or because Kixel Quest does not serve the repository, runs on a read-only +// installation token Kixel Quest mints, so it draws on the installation's rate limit rather than the person's. import { type Answer, type ClaimSources, @@ -29,9 +31,10 @@ import { parseForgeInfo, Refusal, } from "../core"; -import type { GitHubDependencies } from "../github/client"; +import { type GitHubDependencies, reading } from "../github/client"; import { GitHubForge } from "../github/forge"; import { pullRequest, readRemote, remoteHost } from "./github"; +import { type Installation, REUSE_MARGIN, installationDirectory, keep, kept } from "./installation"; import { kixelUrl, tokenFor, tokensPath } from "./tokens"; /** The variable that, set to `github`, reads GitHub even where Kixel Quest serves the repository. */ @@ -84,7 +87,25 @@ export async function forgeFor( const kixel = kixelQuest(deps); return kixel !== null && (await kixel.serves(repository, deadline)) ? new KixelQuestForge(kixel) - : new GitHubForge(deps.github()); + : new GitHubForge(reading(deps.github())); +} + +/** + * The forge that answers `repository`'s reads from GitHub itself, never an index that may lag. For a person holding a + * Kixel Quest token it reads on the installation token Kixel Quest mints for the repository, and on the person's own + * where Kixel Quest does not serve it or the reads are forced onto GitHub. Minting gives up at `deadline`. + */ +export async function liveFor( + repository: Repository, + deps: ForgeDependencies, + deadline = Infinity, +): Promise { + const kixel = kixelQuest(deps); + const installation = kixel === null ? null : await kixel.installation(repository, deadline); + const person = reading(deps.github()); + return installation === null + ? new GitHubForge(person) + : new GitHubForge({ ...person, readToken: installation.token }, installation.login); } /** Kixel Quest refused the person's token, as a sender must tell from a failure that may pass. */ @@ -177,6 +198,66 @@ export class KixelQuest { ); } + /** + * A read-only token for `repository`, or null when Kixel Quest does not serve it to this person. Minted at most + * once an hour per repository: a kept token with time left is reused, so a command mints none. + */ + async installation(repository: Repository, deadline = Infinity): Promise { + const directory = installationDirectory(this.deps.env); + const instead = `set ${FORGE}=github to read GitHub with your own token`; + const keeping = (what: string, error: unknown) => + new Error( + `cannot ${what} installation tokens in ${directory}: ${error instanceof Error ? error.message : String(error)}; ${instead}`, + ); + try { + const have = kept(directory, this.url, this.token, repository, this.deps.now()); + if (have !== null) return have; + } catch (error) { + throw keeping("read", error); + } + const path = "/installation-token"; + const name = `${repository.owner}/${repository.repo}`; + const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); + if (response.status === 404) return null; + if (response.status === 429) { + const wait = Number(response.headers.get("retry-after")); + throw this.#failed( + "POST", + path, + `you have minted as many installation tokens this hour as one person may${Number.isFinite(wait) && wait > 0 ? `; try again in ${Math.ceil(wait)} seconds` : ""}`, + ); + } + if (!response.ok) throw this.#failed("POST", path, `HTTP ${response.status}${reason(text)}`); + const installation = this.#minted(text, name); + try { + keep(directory, this.url, this.token, repository, installation); + } catch (error) { + throw keeping("keep", error); + } + return installation; + } + + /** The token in a mint's answer, `{token, expiresAt, repository, login}`, for `name`. */ + #minted(text: string, name: string): Installation { + const path = "/installation-token"; + let json: unknown; + try { + json = JSON.parse(text); + } catch { + throw this.#failed("POST", path, "its answer is not JSON"); + } + const { token, expiresAt, repository, login } = (json ?? {}) as Record; + const at = typeof expiresAt === "string" ? Date.parse(expiresAt) : NaN; + if (typeof token !== "string" || token === "" || typeof login !== "string" || login === "" || Number.isNaN(at)) + throw this.#failed("POST", path, "its answer lacks a token, an expiry, or a login"); + if (typeof repository !== "string" || repository.toLowerCase() !== name.toLowerCase()) + throw this.#failed("POST", path, `it minted a token for ${String(repository)}, not ${name}`); + // A token that is already inside its reuse margin would be minted again by every command. + if (at - this.deps.now() <= REUSE_MARGIN) + throw this.#failed("POST", path, `its token expires at ${expiresAt}, too soon to reuse`); + return { token, expiresAt: at, login }; + } + /** The time now, epoch milliseconds. */ now(): number { return this.deps.now(); @@ -203,8 +284,13 @@ export class KixelQuest { return new Error(`Kixel Quest (${this.url}) failed ${method} ${path}: ${why}${instead}`); } - /** The JSON answer to a request, or an error naming the setting that reads GitHub instead. */ - async #send(method: "GET" | "POST", path: string, body: unknown, deadline: number): Promise { + /** The answer to a request, as text; Kixel Quest's refusal of the person's token and any network failure throw. */ + async #fetch( + method: "GET" | "POST", + path: string, + body: unknown, + deadline: number, + ): Promise<{ response: Response; text: string }> { const failed = (why: string) => this.#failed(method, path, why); const remaining = deadline - this.deps.now(); if (remaining <= 0) throw failed("its deadline passed"); @@ -238,6 +324,13 @@ export class KixelQuest { .message, response.status, ); + return { response, text }; + } + + /** The JSON answer to a request, or an error naming the setting that reads GitHub instead. */ + async #send(method: "GET" | "POST", path: string, body: unknown, deadline: number): Promise { + const failed = (why: string) => this.#failed(method, path, why); + const { response, text } = await this.#fetch(method, path, body, deadline); // A malformed wait point, token, thread, or body is the caller's to fix on any forge; the other reads take no // free-form argument, so their 400 means the CLI and Kixel Quest disagree on the wire, which reading GitHub // sidesteps. diff --git a/src/cli/installation.ts b/src/cli/installation.ts new file mode 100644 index 00000000..aa6923a3 --- /dev/null +++ b/src/cli/installation.ts @@ -0,0 +1,74 @@ +// The App installation tokens Kixel Quest mints for a person's reads, kept on disk until shortly before they expire: +// a person's hourly cap on minting is spent within a minute if each command mints its own. +import { createHash } from "node:crypto"; +import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"; +import { homedir } from "node:os"; +import { join } from "node:path"; + +import type { Repository } from "../core"; + +/** A read-only token for one repository, and the person it was minted for. */ +export interface Installation { + token: string; + /** Epoch milliseconds. */ + expiresAt: number; + /** The GitHub login of the person, who is not the token's own account. */ + login: string; +} + +/** How long before expiry a token stops being reused, so a command never starts its reads on one about to lapse. */ +export const REUSE_MARGIN = 5 * 60_000; + +/** Where tokens live: `$XDG_CACHE_HOME/quest/installation`, else `~/.cache/quest/installation`. */ +export function installationDirectory(env: NodeJS.ProcessEnv = process.env): string { + return join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "quest", "installation"); +} + +/** The file for a token: a hash of the Kixel Quest, the person's token for it, and the repository, so none is named. */ +function file(directory: string, url: string, kixelToken: string, repository: Repository): string { + const name = `${repository.owner}/${repository.repo}`.toLowerCase(); + return join(directory, createHash("sha256").update(`${url}\n${kixelToken}\n${name}`).digest("hex")); +} + +/** The kept token for `repository` that still has `REUSE_MARGIN` left at `now`, or null; a damaged file is a miss. */ +export function kept( + directory: string, + url: string, + kixelToken: string, + repository: Repository, + now: number, +): Installation | null { + let text: string; + try { + text = readFileSync(file(directory, url, kixelToken, repository), "utf8"); + } catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; + throw error; + } + let value: unknown; + try { + value = JSON.parse(text); + } catch { + return null; + } + if (typeof value !== "object" || value === null) return null; + const { token, expiresAt, login } = value as Record; + if (typeof token !== "string" || token === "" || typeof login !== "string" || typeof expiresAt !== "number") + return null; + return expiresAt - now > REUSE_MARGIN ? { token, expiresAt, login } : null; +} + +/** Keep `installation`, private to the user; a finished file is renamed into place, so no reader sees half of one. */ +export function keep( + directory: string, + url: string, + kixelToken: string, + repository: Repository, + installation: Installation, +): void { + mkdirSync(directory, { recursive: true, mode: 0o700 }); + const path = file(directory, url, kixelToken, repository); + const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`; + writeFileSync(temporary, JSON.stringify(installation), { mode: 0o600 }); + renameSync(temporary, path); +} diff --git a/src/cli/main.ts b/src/cli/main.ts index 98ea3b2c..107f025b 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -45,12 +45,12 @@ import { } from "./agent"; import type { ForgeWrites, Hold, Repository } from "../core"; import { GitHubWrites } from "./writes"; -import { GitHubForge } from "../github/forge"; import { type ClaimDependencies, held, openDrafts, reach, target, upstream, upstreamRefs } from "./claims"; import { type ForgeDependencies, type Located, forgeFor, + liveFor, hostedForge, hostedRepository, locate as locatePull, @@ -153,6 +153,7 @@ export function main(argv: string[], out: Output): number | Promise { const claimDependencies = (): ClaimDependencies => ({ github: () => gitHubDependencies(warn), forge: (repository) => forgeFor(repository, forgeDependencies()), + live: (repository) => liveFor(repository, forgeDependencies()), kixel: { hosted: (url) => hostedRepository(kixelUrl(process.env), url), forge: (repository) => hostedForge(repository, forgeDependencies()), @@ -968,11 +969,16 @@ export function main(argv: string[], out: Output): number | Promise { .option("--json", "Print a deterministic JSON object") .action((value: string, options: { json?: boolean }) => { const { pull, hosted } = locatePull(value, root(), process.env); - const forge = hosted ? hostedForge(pull, forgeDependencies()) : new GitHubForge(gitHubDependencies(warn)); - settle(forge.view(pull), ({ value: view }) => { - if (options.json) print(JSON.stringify(view)); - else for (const line of viewLines(view)) print(line); - }); + settle( + (async () => + (hosted ? hostedForge(pull, forgeDependencies()) : await liveFor(pull, forgeDependencies())).view( + pull, + ))(), + ({ value: view }) => { + if (options.json) print(JSON.stringify(view)); + else for (const line of viewLines(view)) print(line); + }, + ); }); pr.command("list") .description( @@ -990,7 +996,7 @@ export function main(argv: string[], out: Output): number | Promise { if (up.hosting === null) throw new InputError("origin names neither a github.com repository nor one on Kixel Quest"); // Verifies a search, so it reads GitHub itself, never an index that may lag. - return up.hosting.live().files(up.hosting.repository); + return (await up.hosting.live()).files(up.hosting.repository); })(), ({ value: pulls }) => { if (options.json) print(JSON.stringify(pulls)); diff --git a/src/cli/review-record.ts b/src/cli/review-record.ts index 30e5bf03..7ac5f180 100644 --- a/src/cli/review-record.ts +++ b/src/cli/review-record.ts @@ -314,7 +314,7 @@ async function openPull( if (hosting === null) return { skipped: `${remote} is not on GitHub or Kixel Quest` }; const { repository, head } = hosting; const name = `${head.owner}/${head.repo}`.toLowerCase(); - const pull = pullsFrom((await hosting.live().pulls(repository)).value, branch).find( + const pull = pullsFrom((await (await hosting.live()).pulls(repository)).value, branch).find( (each) => each.base === base && each.head?.toLowerCase() === name, ); if (pull === undefined) return { skipped: `no open PR from ${head.owner}:${branch} into ${base}` }; diff --git a/src/cli/start.ts b/src/cli/start.ts index 836abf43..beec8144 100644 --- a/src/cli/start.ts +++ b/src/cli/start.ts @@ -193,7 +193,7 @@ async function openDraft( } // Two claimers on different repositories, such as forks, both push; the earliest PR wins. - const open = pullsFrom((await hosting.live().pulls(repository)).value, branch); + const open = pullsFrom((await (await hosting.live()).pulls(repository)).value, branch); const first = pullsFrom([...open.filter((pull) => pull.number !== created.number), created], branch)[0]; if (first.number !== created.number) { deleteBranch(root, remote, branch, sha); @@ -241,7 +241,7 @@ export async function releaseQuest( const hosting = up.hosting; if (hosting) { const head = `${hosting.head.owner}/${hosting.head.repo}`.toLowerCase(); - const open = (await hosting.live().pulls(hosting.repository)).value; + const open = (await (await hosting.live()).pulls(hosting.repository)).value; pulls.push(...pullsFrom(open, branch).filter((pull) => pull.head?.toLowerCase() === head)); } // Deleting first means the lease decides: a push since the check keeps both the branch and its PR. diff --git a/src/github/claims.ts b/src/github/claims.ts index 055de43c..2010e631 100644 --- a/src/github/claims.ts +++ b/src/github/claims.ts @@ -10,10 +10,10 @@ import { handedBack, landed, } from "../core"; -import { type GitHub, object, repositoryPath, string } from "./client"; +import { type GitHubReader, object, repositoryPath, string } from "./client"; /** Every open PR in `repository`, from any head repository. */ -export async function openPullRequests(github: GitHub, repository: Repository): Promise { +export async function openPullRequests(github: GitHubReader, repository: Repository): Promise { const rows = await github.all(`${repositoryPath(repository)}/pulls?state=open&per_page=100`); return rows.map((row) => { const head = object(row.head); @@ -47,7 +47,7 @@ export function questBranches(refs: Map): Map { } /** The `quest/*` branches of `repository`, with their tips. */ -export async function claimBranches(github: GitHub, repository: Repository): Promise> { +export async function claimBranches(github: GitHubReader, repository: Repository): Promise> { const rows = await github.all(`${repositoryPath(repository)}/git/matching-refs/heads/quest/`); return questBranches(new Map(rows.map((row) => [string(row.ref), string(object(row.object).sha)]))); } @@ -58,7 +58,7 @@ export async function claimBranches(github: GitHub, repository: Repository): Pro * PR's branch still holds its quest, since that work may be wanted back. A fork's own branches and PRs * count, so a claim pushed there is seen before its PR opens. Tips a source leaves out are read here. */ -export async function held(github: GitHub, sources: ClaimSources, branches: string[]): Promise { +export async function held(github: GitHubReader, sources: ClaimSources, branches: string[]): Promise { const { upstream, fork } = sources; const read = async (source: ClaimSource) => ({ repository: source.repository, @@ -92,7 +92,7 @@ export async function held(github: GitHub, sources: ClaimSources, branches: stri /** The URL of the PR from `head`'s `branch` that merged into `repository` with `tip` as its head, or `null`. */ export async function mergedPull( - github: GitHub, + github: GitHubReader, repository: Repository, head: Repository, branch: string, diff --git a/src/github/client.ts b/src/github/client.ts index 93acb14f..126bc884 100644 --- a/src/github/client.ts +++ b/src/github/client.ts @@ -7,14 +7,15 @@ const API = "https://api.github.com"; const MAX_SLEEP = 2_147_483_647; /** - * What the client needs from its host: `fetch`, a clock, a way to pause, the token, where warnings - * go, and what to do once the token's hourly quota is spent. + * What a read-only client needs from its host: `fetch`, a clock, a way to pause, the token it reads + * with, where warnings go, and what to do once the token's hourly quota is spent. The read token may + * be an App installation's, which can read but never write; a write takes {@link GitHubDependencies}. */ -export interface GitHubDependencies { +export interface GitHubReadDependencies { fetch: typeof fetch; now(): number; sleep(milliseconds: number): Promise; - token: string; + readToken: string; warn(message: string): void; /** * `wait` sleeps until a spent quota resets, up to an hour, for a daemon or a waiter whose job is to @@ -25,6 +26,20 @@ export interface GitHubDependencies { cache?: ResponseCache; } +/** + * What a client that writes needs: the same, with the person's own token, so what it writes is in their + * name. It has no `readToken`, so it never stands in for read dependencies built on another token. + */ +export interface GitHubDependencies extends Omit { + token: string; +} + +/** `deps` as read dependencies, reading on the person's own token. */ +export function reading(deps: GitHubDependencies): GitHubReadDependencies { + const { token, ...rest } = deps; + return { ...rest, readToken: token }; +} + /** A 200 answer to a GET, kept to serve when GitHub answers its ETag with a 304. */ export interface CachedResponse { etag: string; @@ -95,16 +110,22 @@ function limited(response: Response, body: string): boolean { ); } -/** Authenticated REST and GraphQL requests that wait out rate limits, bounded by an optional deadline. */ -export class GitHub { +/** How {@link GitHubReader.request} reads: a GET, so it takes neither method nor body. */ +export type ReadOptions = Pick; + +/** + * Authenticated REST GETs and GraphQL queries that wait out rate limits, bounded by an optional deadline. It + * cannot write, so it may hold an installation token; {@link GitHub} writes too, on the person's own. + */ +export class GitHubReader { /** The longest X-Poll-Interval GitHub asked for since the caller last set this, in milliseconds. */ pollInterval = 0; /** The response cache, dropped after its first failure. */ private cache: ResponseCache | undefined; constructor( - private readonly deps: GitHubDependencies, - private readonly deadline = Infinity, + protected readonly deps: GitHubReadDependencies, + protected readonly deadline = Infinity, ) { this.cache = deps.cache; } @@ -132,6 +153,11 @@ export class GitHub { if (this.deps.now() >= this.deadline) throw new GitHubDeadline(); } + /** A GET: see {@link GitHubReader.send}. */ + request(path: string, options: ReadOptions = {}): Promise { + return this.send(path, options); + } + /** * A 2xx response, its body already read; anything else fails, with GitHub's reason when it gives * one, unless `allow` lists its status. A GET revalidates the cached answer by its ETag and serves @@ -140,7 +166,7 @@ export class GitHub { * retried with bounded backoff as `repeat` allows, then fails with the last error. `body` makes * it a POST unless `method` says otherwise. */ - async request(path: string, options: RequestOptions = {}): Promise { + protected async send(path: string, options: RequestOptions = {}): Promise { // Follow only same-origin pagination links; never send a token to another host. const url = new URL(path, API); if (url.origin !== API || url.username || url.password) throw new Error("invalid GitHub pagination URL"); @@ -149,7 +175,7 @@ export class GitHub { const accept = options.accept ?? "application/vnd.github+json"; const get = options.body === undefined && options.method === undefined; const cache = get ? this.cache : undefined; - const key = cache && (await cacheKey(this.deps.token, accept, url.href)); + const key = cache && (await cacheKey(this.deps.readToken, accept, url.href)); const cached = key === undefined ? undefined : await this.cached(() => cache!.get(key)); let limits = 0; let failures = 0; @@ -165,7 +191,7 @@ export class GitHub { : { method: options.method ?? "POST", body: JSON.stringify(options.body) }), headers: { Accept: accept, - Authorization: `Bearer ${this.deps.token}`, + Authorization: `Bearer ${this.deps.readToken}`, "X-GitHub-Api-Version": "2022-11-28", "User-Agent": "quest", ...(cached ? { "If-None-Match": cached.etag } : {}), @@ -359,15 +385,19 @@ export class GitHub { } /** - * Run a GraphQL query and return its data, failing on any reported error. A query repeats after - * a 5xx or a dropped connection; a mutation only once its effect is confirmed missing, and one - * confirmed to have taken effect returns no data. GitHub can report a rate limit as a 200 whose - * errors say `RATE_LIMITED`; that is waited out like a REST one. + * Run a GraphQL query and return its data, failing on any reported error, and on a mutation, which only + * {@link GitHub} runs. A query repeats after a 5xx or a dropped connection. GitHub can report a rate limit as a + * 200 whose errors say `RATE_LIMITED`; that is waited out like a REST one. */ async graphql(query: string, variables: ObjectValue): Promise { - const repeat = this.mutationRepeat(query, variables); + if (/^\s*mutation\b/.test(query)) throw new Error("a read-only GitHub client cannot run a mutation"); + return this.operate(query, variables, true); + } + + /** Run a GraphQL operation that repeats as `repeat` says. */ + protected async operate(query: string, variables: ObjectValue, repeat: Repeat): Promise { for (let limits = 0; ; limits++) { - const response = await this.request("/graphql", { body: { query, variables }, repeat }); + const response = await this.send("/graphql", { body: { query, variables }, repeat }); const body = object(await response.json()); if (body.errors === undefined) return object(body.data); const errors = array(body.errors); @@ -380,6 +410,26 @@ export class GitHub { await this.waitOut(response.headers, limits, "GitHub GraphQL rate limit persisted"); } } +} + +/** A client that reads and writes on the person's own token, so what it writes is in their name. */ +export class GitHub extends GitHubReader { + constructor(deps: GitHubDependencies, deadline = Infinity) { + super(reading(deps), deadline); + } + + /** A request of any method, with {@link GitHubReader.send}'s retries. */ + override request(path: string, options: RequestOptions = {}): Promise { + return this.send(path, options); + } + + /** + * Run a GraphQL query, or a mutation: it repeats only once its effect is confirmed missing, and one + * confirmed to have taken effect returns no data. + */ + override graphql(query: string, variables: ObjectValue): Promise { + return this.operate(query, variables, this.mutationRepeat(query, variables)); + } /** * Repeat a query; confirm a pull request mutation `PULL_MUTATIONS` knows; never repeat another. @@ -473,7 +523,7 @@ export interface Requirements { * Every rule a branch's active rulesets apply. GitHub Free offers no rulesets on a private repository and * answers 403 with an upgrade notice, so none apply there; any other refusal fails. */ -async function branchRules(github: GitHub, path: string): Promise { +async function branchRules(github: GitHubReader, path: string): Promise { const first = await github.request(path, { allow: [403] }); if (first.status !== 403) { const next = link(first, "next"); @@ -495,7 +545,7 @@ export function workflowKey(repository: string, path: string): string { } /** The workflow files `rules` require, each keyed by {@link workflowKey} from its rule's `repository_id`. */ -async function requiredWorkflows(github: GitHub, rules: ObjectValue[]): Promise { +async function requiredWorkflows(github: GitHubReader, rules: ObjectValue[]): Promise { const names = new Map(); const keys: string[] = []; for (const row of rules @@ -513,7 +563,11 @@ async function requiredWorkflows(github: GitHub, rules: ObjectValue[]): Promise< } /** What `branch` of `repository` requires, read with read access from branch protection and rulesets. */ -export async function requirements(github: GitHub, repository: Repository, branch: string): Promise { +export async function requirements( + github: GitHubReader, + repository: Repository, + branch: string, +): Promise { const base = `/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}`; const ref = encodeURIComponent(branch); const protection = object(object(await (await github.request(`${base}/branches/${ref}`)).json()).protection ?? {}); @@ -550,7 +604,7 @@ export async function requirements(github: GitHub, repository: Repository, branc } /** Every GitHub Actions workflow run on `head`. Reading them needs Actions read access. */ -export async function workflowRuns(github: GitHub, repository: Repository, head: string): Promise { +export async function workflowRuns(github: GitHubReader, repository: Repository, head: string): Promise { const runs: WorkflowRun[] = []; let path: string | undefined = `/repos/${encodeURIComponent(repository.owner)}/${encodeURIComponent(repository.repo)}/actions/runs?head_sha=${head}&per_page=100`; @@ -576,7 +630,7 @@ export async function workflowRuns(github: GitHub, repository: Repository, head: * report they can drop. */ export async function currentChecks( - github: GitHub, + github: GitHubReader, repository: Repository, head: string, contexts: T[], @@ -591,7 +645,7 @@ export async function currentChecks( * Whether a merged PR in `repository` had `commit` as its head or below it, as when `quest land` merged * the base into the head before squashing; false for a commit GitHub does not have. */ -export async function mergedHolds(github: GitHub, repository: Repository, commit: string): Promise { +export async function mergedHolds(github: GitHubReader, repository: Repository, commit: string): Promise { const data = await github.graphql( "query($owner: String!, $name: String!, $oid: GitObjectID!) { repository(owner: $owner, name: $name) { " + "object(oid: $oid) { ... on Commit { associatedPullRequests(first: 100) { nodes { merged headRefOid } } } } } }", diff --git a/src/github/duplicates.ts b/src/github/duplicates.ts index e61ebbd7..e905f06f 100644 --- a/src/github/duplicates.ts +++ b/src/github/duplicates.ts @@ -1,7 +1,7 @@ // Quests a PR adds that another open PR also adds, so a follow-up some other PR already owns is // caught before a pick round asks about it. import { type Duplicate, type PullRequest, isQuest, parse } from "../core"; -import { type GitHub, object } from "./client"; +import { type GitHubReader, object } from "./client"; import { openFiles } from "./files"; /** An open PR's added quest files, each with its title, or null when it has none. */ @@ -49,7 +49,7 @@ export function duplicates(self: number, pulls: Added[]): Duplicate[] { /** * The quests `pr` adds that another open PR in its repository also adds. Reads every open PR's files, then the titles of their quests at each PR's head, only when `pr` adds a quest. */ -export async function duplicateQuests(github: GitHub, pr: PullRequest): Promise { +export async function duplicateQuests(github: GitHubReader, pr: PullRequest): Promise { const pulls = (await openFiles(github, pr)).map(({ number, url, head, files }) => ({ number, url, diff --git a/src/github/files.ts b/src/github/files.ts index 332a9d5e..dcf0d61e 100644 --- a/src/github/files.ts +++ b/src/github/files.ts @@ -1,6 +1,6 @@ // Every open PR's changed files, as GitHub lists them: what `gh pr list --json files` gives, without its cap. import type { PullFiles, Repository } from "../core"; -import { type GitHub, array, object, repositoryPath, string } from "./client"; +import { type GitHubReader, array, object, repositoryPath, string } from "./client"; /** The most files GitHub's REST API lists for a PR. */ const REST_LIMIT = 3000; @@ -26,7 +26,7 @@ const OPEN = `query OpenFiles($owner: String!, $repo: String!, $after: String) { }`; /** Every open PR in `repository` with its changed files. */ -export async function openFiles(github: GitHub, repository: Repository): Promise { +export async function openFiles(github: GitHubReader, repository: Repository): Promise { const pulls: OpenFiles[] = []; for (let after: string | null = null, more = true; more;) { const data = await github.graphql(OPEN, { owner: repository.owner, repo: repository.repo, after }); @@ -60,7 +60,7 @@ export async function openFiles(github: GitHub, repository: Repository): Promise } /** `openFiles` as the paths each PR changes, by number. */ -export async function openPullFiles(github: GitHub, repository: Repository): Promise { +export async function openPullFiles(github: GitHubReader, repository: Repository): Promise { const pulls = await openFiles(github, repository); // Fail loud: a cut list would let the duplicate search miss a PR touching a path. const cut = pulls.find((pull) => pull.cut); diff --git a/src/github/forge.ts b/src/github/forge.ts index ce1c14da..6207bb8f 100644 --- a/src/github/forge.ts +++ b/src/github/forge.ts @@ -14,7 +14,7 @@ import type { WatchOptions, } from "../core"; import { held, openPullRequests } from "./claims"; -import { GitHub, type GitHubDependencies, object, string } from "./client"; +import { GitHubReader, type GitHubReadDependencies, object, string } from "./client"; import { openPullFiles } from "./files"; import { pullRequestStatus } from "./status"; import { pullView } from "./view"; @@ -27,18 +27,18 @@ export class GitHubForge implements Forge { /** `viewer` names the person reading when the token is not theirs, such as an App installation's. */ constructor( - private readonly deps: GitHubDependencies, + private readonly deps: GitHubReadDependencies, viewer?: string, ) { if (viewer !== undefined) this.#viewer = Promise.resolve(viewer); } viewer(): Promise { - return this.#viewerOn(new GitHub(this.deps)); + return this.#viewerOn(new GitHubReader(this.deps)); } /** The viewer, read on `github`, whose deadline then bounds the read; kept once read, and read again after a failure. */ - #viewerOn(github: GitHub): Promise { + #viewerOn(github: GitHubReader): Promise { const read = (this.#viewer ??= github .graphql("query { viewer { login } }", {}) .then((data) => string(object(data.viewer).login))); @@ -53,24 +53,24 @@ export class GitHubForge implements Forge { } async pulls(repository: Repository): Promise> { - return live(await openPullRequests(new GitHub(this.deps), repository)); + return live(await openPullRequests(new GitHubReader(this.deps), repository)); } async files(repository: Repository): Promise> { - return live(await openPullFiles(new GitHub(this.deps), repository)); + return live(await openPullFiles(new GitHubReader(this.deps), repository)); } async held(sources: ClaimSources, branches: string[]): Promise> { - return live(await held(new GitHub(this.deps), sources, branches)); + return live(await held(new GitHubReader(this.deps), sources, branches)); } watch(pull: PullRequest, options: WatchOptions): Watch { - const github = new GitHub(this.deps, options.deadline); + const github = new GitHubReader(this.deps, options.deadline); return watchPull(github, this.deps, pull, options.since, { viewer: () => this.#viewerOn(github) }); } async view(pull: PullRequest): Promise> { - return live(await pullView(new GitHub(this.deps), pull)); + return live(await pullView(new GitHubReader(this.deps), pull)); } } diff --git a/src/github/hold.ts b/src/github/hold.ts index 9d4b87f1..46a1db8d 100644 --- a/src/github/hold.ts +++ b/src/github/hold.ts @@ -1,7 +1,15 @@ // Reading who holds a PR: its `quest:*` labels, the events that added them, and a draft its starter still holds. // Taking and releasing holds stays in the CLI. import { type HoldFact, type PullRequest, type StarterHold, handedBack, isHoldLabel, latestHold } from "../core"; -import { GitHub, type GitHubDependencies, type ObjectValue, array, object, repositoryPath, string } from "./client"; +import { + GitHubReader, + type GitHubReadDependencies, + type ObjectValue, + array, + object, + repositoryPath, + string, +} from "./client"; import { lacksApproval } from "./merge"; /** The PR, its `quest:*` labels, and the timeline events that add a label. */ @@ -62,7 +70,7 @@ export interface HoldReport { } /** Read `pr` and its hold labels. */ -export async function readSnapshot(github: GitHub, pr: PullRequest): Promise { +export async function readSnapshot(github: GitHubReader, pr: PullRequest): Promise { const data = await github.graphql(READ, { owner: pr.owner, repo: pr.repo, @@ -98,8 +106,8 @@ export async function readSnapshot(github: GitHub, pr: PullRequest): Promise { - const github = new GitHub(deps); +export async function readHoldStatus(pr: PullRequest, deps: GitHubReadDependencies): Promise { + const github = new GitHubReader(deps); const snapshot = await readSnapshot(github, pr); const holds = snapshot.state !== "OPEN" diff --git a/src/github/index.ts b/src/github/index.ts index dde8a9f3..6b5e23bc 100644 --- a/src/github/index.ts +++ b/src/github/index.ts @@ -3,7 +3,15 @@ // decides them. The caller supplies `fetch` and the token through `GitHubDependencies`; the read types are // `quest/core`'s. -export { GitHub, GitHubDeadline, type GitHubDependencies, GitHubGraphQLError } from "./client"; +export { + GitHub, + GitHubDeadline, + type GitHubDependencies, + GitHubGraphQLError, + type GitHubReadDependencies, + GitHubReader, + reading, +} from "./client"; export { GitHubForge } from "./forge"; export { type BaseNeeds, type Needs, pullRequestStatus, requiredOf } from "./status"; export { type HoldReport } from "./hold"; diff --git a/src/github/online-review.ts b/src/github/online-review.ts index b1583f1e..e350600f 100644 --- a/src/github/online-review.ts +++ b/src/github/online-review.ts @@ -2,7 +2,7 @@ // thread, and any review whose // body opens with `Automated review by `, as a reviewer posting under a person's account does. A finding is a // review thread one opens, or a `[P]` line in its review body; whoever answers it says whether it was taken. -import { type GitHub, type ObjectValue, array, object } from "./client"; +import { type GitHubReader, type ObjectValue, array, object } from "./client"; import type { Repository } from "../core"; /** One online reviewer's record on one PR. */ @@ -87,7 +87,7 @@ export type Activity = Record, ObjectVal /** Each PR's reviews, review threads, and comments, and its head, read in batches and then in pages. */ export async function readActivity( - client: GitHub, + client: GitHubReader, repository: Repository, numbers: number[], extra: "userContentEdits"[] = [], @@ -302,7 +302,7 @@ export function onlineReviews(pull: Activity): OnlineReview[] { /** Each PR's online reviews, and every body its edits left, by number. */ export async function readOnlineReviews( - client: GitHub, + client: GitHubReader, repository: Repository, numbers: number[], ): Promise> { diff --git a/src/github/signals.ts b/src/github/signals.ts index 4ebbbc17..903f87e8 100644 --- a/src/github/signals.ts +++ b/src/github/signals.ts @@ -1,7 +1,7 @@ // What holds a PR's head from landing besides its checks: an online reviewer's finding on the head that no writer has // answered, and a maintainer decision recorded in a comment after the head was committed that nothing has answered. import type { Repository, Signal } from "../core"; -import { type GitHub, type ObjectValue, array, object, string } from "./client"; +import { type GitHubReader, type ObjectValue, array, object, string } from "./client"; import { type Activity, bodyFindings, isBot, login, readActivity, reviewerOf } from "./online-review"; /** The picked heads whose signals a later commit carries unread, and when the pick was made. */ @@ -143,7 +143,7 @@ export function signals(pull: Activity, writers: ReadonlySet, carried?: * read, so their permission is read; any other association cannot. */ async function writersOf( - client: GitHub, + client: GitHubReader, repository: Repository, actors: { actor: unknown; association: unknown }[], ): Promise> { @@ -168,7 +168,7 @@ async function writersOf( /** The signals on each PR's current head, by number, with the head they were read for, and those `carried` carries. */ export async function readSignals( - client: GitHub, + client: GitHubReader, repository: Repository, numbers: number[], carried?: ReadonlyMap, diff --git a/src/github/status.ts b/src/github/status.ts index 077b7323..87790ce6 100644 --- a/src/github/status.ts +++ b/src/github/status.ts @@ -3,9 +3,9 @@ import { actor, array, currentChecks, - GitHub, + GitHubReader, GitHubDeadline, - type GitHubDependencies, + type GitHubReadDependencies, link, object, type ObjectValue, @@ -91,13 +91,17 @@ export interface BaseNeeds extends Repository { * what it read of their base once, instead of each read fetching it again; it throws when the PR's repository or base * is another. */ -export async function pullRequestStatus(pr: PullRequest, deps: GitHubDependencies, base?: BaseNeeds): Promise { +export async function pullRequestStatus( + pr: PullRequest, + deps: GitHubReadDependencies, + base?: BaseNeeds, +): Promise { // GitHub's owner and repository names are case-insensitive. if (base !== undefined && `${base.owner}/${base.repo}`.toLowerCase() !== `${pr.owner}/${pr.repo}`.toLowerCase()) throw new Error( `the requirements passed for ${pr.owner}/${pr.repo}#${pr.number} were read for ${base.owner}/${base.repo}`, ); - const github = new GitHub(deps); + const github = new GitHubReader(deps); const cursors: Record<"checks" | "reviews" | "threads", string | null | undefined> = { checks: null, reviews: null, @@ -182,7 +186,7 @@ function risk(body: string, head: string, record: ReviewRecord | null): Status[" } async function reviewRecord( - github: GitHub, + github: GitHubReader, pr: PullRequest, pull: ObjectValue, warn: (message: string) => void, @@ -236,7 +240,7 @@ export const BRANCH_UPDATES = ["push", "force_push", "branch_creation", "pr_merg * `headRefName`, `headRepository { nameWithOwner }`, and `autoMergeRequest { enabledAt commitBody }`. */ export async function enabledHead( - github: GitHub, + github: GitHubReader, pull: ObjectValue, warn: (message: string) => void, ): Promise { @@ -255,7 +259,7 @@ export async function enabledHead( * `headRepository { nameWithOwner }`. */ export async function headBefore( - github: GitHub, + github: GitHubReader, pull: ObjectValue, time: number, what: string, @@ -298,7 +302,7 @@ export interface Needs { } /** What `branch` requires of a PR head. The gate's own check is never on one, so it is left out. */ -export async function requiredOf(github: GitHub, repository: Repository, branch: string): Promise { +export async function requiredOf(github: GitHubReader, repository: Repository, branch: string): Promise { const found = await requirements(github, repository, branch); return { checks: found.checks.filter((check) => check.name !== LAND_CHECK), workflows: found.workflows }; } diff --git a/src/github/view.ts b/src/github/view.ts index 40294e6d..cbdcab07 100644 --- a/src/github/view.ts +++ b/src/github/view.ts @@ -1,11 +1,11 @@ // A PR's title, body, and discussion as GitHub gives them: what `gh pr view --comments` shows, with its review // threads' comments too. import type { Comment, PullRequest, PullView } from "../core"; -import { type GitHub, type ObjectValue, actor, array, object, string } from "./client"; +import { type GitHubReader, type ObjectValue, actor, array, object, string } from "./client"; import { readActivity } from "./online-review"; /** `pull`'s title, body, comments, submitted reviews, and review threads. */ -export async function pullView(github: GitHub, pull: PullRequest): Promise { +export async function pullView(github: GitHubReader, pull: PullRequest): Promise { const data = await github.graphql( "query($owner: String!, $name: String!, $number: Int!) { repository(owner: $owner, name: $name) { " + "pullRequest(number: $number) { url title body state isDraft author { login } } } }", diff --git a/src/github/wait.ts b/src/github/wait.ts index dd208406..9902db62 100644 --- a/src/github/wait.ts +++ b/src/github/wait.ts @@ -4,8 +4,8 @@ import { actor, array, currentChecks, - type GitHub, - type GitHubDependencies, + type GitHubReader, + type GitHubReadDependencies, link, object, type ObjectValue, @@ -120,8 +120,8 @@ interface Viewer { * the person whose own label changes, replies, reactions, and edits never wake them. */ export function watchPull( - github: GitHub, - deps: GitHubDependencies, + github: GitHubReader, + deps: GitHubReadDependencies, pr: PullRequest, since: string | undefined, identity: Viewer, @@ -147,8 +147,8 @@ export function watchPull( /** Read the starting point, returning one poll from it. */ async function start( - github: GitHub, - deps: GitHubDependencies, + github: GitHubReader, + deps: GitHubReadDependencies, pr: PullRequest, from: string | undefined, identity: Viewer, diff --git a/test/forge-writes.test.ts b/test/forge-writes.test.ts index ac1795aa..5fa39d32 100644 --- a/test/forge-writes.test.ts +++ b/test/forge-writes.test.ts @@ -231,6 +231,7 @@ describe("where a PR lives", () => { const found = await upstream(work, remote, { github, forge: github, + live: github, kixel: { hosted: (url) => hostedRepository(KIXEL, url), forge: github }, warn: () => undefined, }); diff --git a/test/forge.test.ts b/test/forge.test.ts index 363e60e0..d9ece492 100644 --- a/test/forge.test.ts +++ b/test/forge.test.ts @@ -21,7 +21,7 @@ import { } from "../src/core"; import { type ForgeDependencies, forgeFor, KixelQuest, KixelQuestForge } from "../src/cli/forge"; import { waitForActivity, WaitTimeout } from "../src/cli/wait"; -import { type GitHubDependencies } from "../src/github/client"; +import { type GitHubReadDependencies } from "../src/github/client"; import { GitHubForge } from "../src/github/forge"; import * as status from "./status-fakes"; import * as wait from "./wait-fakes"; @@ -32,7 +32,7 @@ const repository = { owner: "example", repo: "project" }; /** A fake Kixel Quest serving `github`'s answers to the person `login`, at `asOf`. */ function kixelQuest( - github: () => GitHubDependencies, + github: () => GitHubReadDependencies, options: { login?: string; repositories?: string[]; asOf?: string | null; fail?: number; answer?: unknown } = {}, ) { const requests: { method: string; path: string; body: unknown }[] = []; @@ -94,7 +94,7 @@ afterEach(() => { /** Forge dependencies whose token file pairs `TOKEN` with Kixel Quest, unless `token` is false. */ function dependencies( fetch: ForgeDependencies["fetch"], - github: () => GitHubDependencies, + github: () => GitHubReadDependencies, env: NodeJS.ProcessEnv = {}, token = true, ): ForgeDependencies { @@ -103,11 +103,20 @@ function dependencies( mkdirSync(join(config, "quest")); writeFileSync(join(config, "quest", "records.json"), JSON.stringify({ [URL_]: TOKEN })); } - return { env: { XDG_CONFIG_HOME: config, ...env }, fetch, now: () => 0, github }; + return { + env: { XDG_CONFIG_HOME: config, XDG_CACHE_HOME: join(config, "cache"), ...env }, + fetch, + now: () => 0, + // The fake's token is the person's own here. + github: () => { + const { readToken, ...rest } = github(); + return { ...rest, token: readToken }; + }, + }; } /** Kixel Quest's backend over a fake serving `github`. */ -async function throughKixelQuest(github: () => GitHubDependencies, options?: Parameters[1]) { +async function throughKixelQuest(github: () => GitHubReadDependencies, options?: Parameters[1]) { const server = kixelQuest(github, options); // Kixel Quest's reads keep the fake GitHub's clock, which a wait's deadline is set by. const forge = await forgeFor(repository, { ...dependencies(server.fetch, github), now: () => github().now() }); @@ -236,7 +245,7 @@ describe("status", () => { }); /** A fake GitHub holding open PRs and a merged one, as the claim reads list them. */ -function claimsGitHub(): GitHubDependencies { +function claimsGitHub(): GitHubReadDependencies { const pull = (number: number, ref: string, extra: Record = {}) => ({ number, html_url: `https://github.com/example/project/pull/${number}`, @@ -251,7 +260,7 @@ function claimsGitHub(): GitHubDependencies { const open = [pull(1, "quest/m0/one"), pull(2, "quest/m0/two"), pull(3, "feature", { draft: false, body: null })]; const merged = [pull(4, "quest/m0/done", { head: { ref: "quest/m0/done", sha: "d".repeat(40) }, merged_at: "x" })]; return { - token: "test-token", + readToken: "test-token", quota: "fail", now: () => 0, sleep: async () => {}, @@ -431,7 +440,7 @@ describe("wait deadlines and arguments", () => { test("a viewer or Kixel Quest read that failed is read again, not kept", async () => { let viewers = 0; - const github: GitHubDependencies = { + const github: GitHubReadDependencies = { ...claimsGitHub(), fetch: async () => ++viewers === 1 @@ -474,12 +483,12 @@ describe("wait deadlines and arguments", () => { }); }); -const unreachableGitHub = (): GitHubDependencies => { +const unreachableGitHub = (): GitHubReadDependencies => { throw new Error("read GitHub"); }; describe("choosing the forge", () => { - const unreachable = (): GitHubDependencies => { + const unreachable = (): GitHubReadDependencies => { throw new Error("read GitHub"); }; diff --git a/test/installation.test.ts b/test/installation.test.ts new file mode 100644 index 00000000..fdd73c0a --- /dev/null +++ b/test/installation.test.ts @@ -0,0 +1,253 @@ +// Reads on the installation token Kixel Quest mints, and writes on the person's own, against a fake Kixel Quest and a +// fake GitHub that record the token each request carries. +import { existsSync, mkdirSync, mkdtempSync, readdirSync, statSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { beforeEach, describe, expect, test } from "vitest"; + +import { type ForgeDependencies, liveFor } from "../src/cli/forge"; +import { REUSE_MARGIN, installationDirectory } from "../src/cli/installation"; +import { waitForActivity } from "../src/cli/wait"; +import { GitHubWrites } from "../src/cli/writes"; +import { GitHub, type GitHubDependencies, GitHubReader, reading } from "../src/github/client"; +import * as wait from "./wait-fakes"; + +const KIXEL = "https://kixel.test"; +const KIXEL_TOKEN = "kq-token"; +const PERSON = "person-token"; +const repository = { owner: "example", repo: "project" }; +const START = Date.parse("2026-11-17T00:00:00Z"); + +let cache: string; +let config: string; +let clock: number; +beforeEach(() => { + config = mkdtempSync(join(tmpdir(), "quest-installation-config-")); + cache = mkdtempSync(join(tmpdir(), "quest-installation-cache-")); + mkdirSync(join(config, "quest")); + writeFileSync(join(config, "quest", "records.json"), JSON.stringify({ [KIXEL]: KIXEL_TOKEN })); + clock = START; +}); + +/** A fake Kixel Quest minting tokens, and the GitHub requests the person's reads and writes make, with their tokens. */ +function world(options: { mint?: (n: number, repository: string) => Response; github?: typeof fetch } = {}) { + const mints: { repository: string; authorization: string | null }[] = []; + const github: { method: string; path: string; token: string | null }[] = []; + const env = { XDG_CONFIG_HOME: config, XDG_CACHE_HOME: cache, QUEST_KIXEL_URL: KIXEL } as NodeJS.ProcessEnv; + const mint = + options.mint ?? + ((n: number, name: string) => + Response.json({ + token: `minted-${n}`, + expiresAt: new Date(clock + 3_600_000).toISOString(), + repository: name, + login: "waiter", + })); + const fetch = async (input: string | URL | Request, init?: RequestInit): Promise => { + const url = new URL(String(input)); + if (url.origin === KIXEL) { + if (url.pathname !== "/installation-token") throw new Error(`unexpected Kixel Quest ${url.pathname}`); + const { repository: name } = JSON.parse(String(init?.body)) as { repository: string }; + mints.push({ repository: name, authorization: new Headers(init?.headers).get("authorization") }); + return mint(mints.length, name); + } + const token = new Headers(init?.headers).get("authorization")?.replace(/^Bearer /, "") ?? null; + github.push({ method: init?.method ?? "GET", path: url.pathname, token }); + return options.github ? options.github(input, init) : Response.json([]); + }; + const person = (): GitHubDependencies => ({ + fetch: fetch as typeof globalThis.fetch, + now: () => clock, + sleep: async () => {}, + token: PERSON, + quota: "fail", + warn: () => {}, + }); + const deps: ForgeDependencies = { env, fetch: fetch as typeof globalThis.fetch, now: () => clock, github: person }; + return { deps, mints, github, person, env }; +} + +describe("reads on a minted installation token", () => { + test("a read goes out on the minted token and a write on the person's", async () => { + const w = world(); + const forge = await liveFor(repository, w.deps); + await forge.pulls(repository); + await new GitHubWrites(w.person(), null as never).close({ ...repository, number: 7 }); + expect(w.mints).toEqual([{ repository: "example/project", authorization: `Bearer ${KIXEL_TOKEN}` }]); + expect(w.github).toEqual([ + { method: "GET", path: "/repos/example/project/pulls", token: "minted-1" }, + { method: "PATCH", path: "/repos/example/project/pulls/7", token: PERSON }, + ]); + // The person is the mint's login, not the installation's account. + expect(await forge.viewer()).toBe("waiter"); + }); + + test("a read client cannot write: not in its types, and not at run time for a mutation", async () => { + const w = world(); + const reader = new GitHubReader({ ...reading(w.person()), readToken: "minted" }); + // @ts-expect-error a read has no method or body + const request = () => reader.request("/repos/example/project/pulls/7", { method: "PATCH", body: {} }); + void request; + // @ts-expect-error a write takes the person's token, not read dependencies + const write = () => new GitHub({ ...reading(w.person()), readToken: "minted" }); + void write; + // @ts-expect-error a client that writes is not made from a reader's dependencies + const forge = () => new GitHubWrites(reading(w.person()), null as never); + void forge; + await expect(reader.graphql("mutation { x }", {})).rejects.toThrow("cannot run a mutation"); + expect(w.github).toEqual([]); + }); + + test("the token is minted once and reused across runs until shortly before it expires", async () => { + const w = world(); + await liveFor(repository, w.deps); + clock += 30 * 60_000; + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.mints).toHaveLength(1); + expect(w.github.map((request) => request.token)).toEqual(["minted-1"]); + // Another repository has a token of its own. + await liveFor({ owner: "example", repo: "other" }, w.deps); + expect(w.mints.map((mint) => mint.repository)).toEqual(["example/project", "example/other"]); + // One that has `REUSE_MARGIN` left is not reused; the next mint replaces it. + clock = START + 3_600_000 - REUSE_MARGIN; + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.mints).toHaveLength(3); + expect(w.github.map((request) => request.token)).toEqual(["minted-1", "minted-3"]); + // The file is private to the person, and no name or token appears in its path. + const directory = installationDirectory(w.env); + for (const name of readdirSync(directory)) { + expect(name).toMatch(/^[0-9a-f]{64}$/); + expect(statSync(join(directory, name)).mode & 0o777).toBe(0o600); + } + expect(statSync(directory).mode & 0o777).toBe(0o700); + }); + + test("a person with another Kixel Quest token mints their own", async () => { + const w = world(); + await liveFor(repository, w.deps); + writeFileSync(join(config, "quest", "records.json"), JSON.stringify({ [KIXEL]: "other-token" })); + await liveFor(repository, w.deps); + expect(w.mints.map((mint) => mint.authorization)).toEqual([`Bearer ${KIXEL_TOKEN}`, "Bearer other-token"]); + }); + + test("a repository Kixel Quest does not serve reads on the person's token, minting nothing to keep", async () => { + const w = world({ mint: () => Response.json({ error: "not indexed" }, { status: 404 }) }); + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.github.map((request) => request.token)).toEqual([PERSON]); + expect(files(w.env)).toEqual([]); + }); + + test("without a Kixel Quest token, or with reads forced onto GitHub, none is minted", async () => { + const w = world(); + await (await liveFor(repository, { ...w.deps, env: { ...w.env, QUEST_FORGE: "github" } })).pulls(repository); + writeFileSync(join(config, "quest", "records.json"), "{}"); + await (await liveFor(repository, w.deps)).pulls(repository); + expect(w.mints).toEqual([]); + expect(w.github.map((request) => request.token)).toEqual([PERSON, PERSON]); + }); + + test.each([ + [ + "429", + () => new Response("{}", { status: 429, headers: { "retry-after": "1200" } }), + "try again in 1200 seconds", + ], + ["502", () => Response.json({ error: "GitHub refused" }, { status: 502 }), "HTTP 502, GitHub refused"], + ["503", () => Response.json({ error: "App down" }, { status: 503 }), "HTTP 503, App down"], + ["401", () => new Response("{}", { status: 401 }), "refused the token"], + ])("a %s fails the command, naming the setting that reads GitHub with the person's token", async (_, mint, why) => { + const w = world({ mint }); + const error = await liveFor(repository, w.deps).catch((error: Error) => error); + expect(error).toBeInstanceOf(Error); + expect((error as Error).message).toContain(why); + expect((error as Error).message).toContain("set QUEST_FORGE=github to read GitHub"); + // A refused mint never quietly spends the person's quota, and is asked again, not kept. + expect(w.github).toEqual([]); + expect(files(w.env)).toEqual([]); + }); + + test.each([ + ["names no login", { token: "t", expiresAt: "2026-11-17T01:00:00Z", repository: "example/project" }], + ["is for another repository", { token: "t", expiresAt: "2026-11-17T01:00:00Z", repository: "a/b", login: "x" }], + [ + "is about to expire", + { token: "t", expiresAt: "2026-11-17T00:01:00Z", repository: "example/project", login: "x" }, + ], + ])("a mint that %s fails rather than reads on it", async (_, answer) => { + const w = world({ mint: () => Response.json(answer) }); + await expect(liveFor(repository, w.deps)).rejects.toThrow("failed POST /installation-token"); + expect(w.github).toEqual([]); + }); + + test("a cache that cannot be written fails, since every command would mint", async () => { + const w = world(); + writeFileSync(join(cache, "quest"), "a file where the directory goes"); + await expect(liveFor(repository, w.deps)).rejects.toThrow(/cannot (read|keep) installation tokens/); + }); +}); + +/** The tokens kept on disk. */ +const files = (env: NodeJS.ProcessEnv) => + existsSync(installationDirectory(env)) ? readdirSync(installationDirectory(env)) : []; + +/** A comment its author edited after the wait began. */ +const edited = (id: number, login: string) => ({ + id, + body: "My reply", + created_at: "2026-10-06T12:00:00Z", + updated_at: "2026-10-07T12:05:00Z", + user: { login }, + html_url: `https://github.com/example/project/pull/1#issuecomment-${id}`, +}); + +describe("quest wait on a minted token", () => { + test("the person's own reply, reaction, label, and edit do not wake it, though the token's account is the App's", async () => { + const label = (event: string, id: number, name: string, login: string) => ({ + event, + id, + created_at: wait.POINT, + actor: { login }, + label: { name, color: "ffffff" }, + }); + const fixture = wait.setup( + [ + wait.pull(), + wait.response([wait.pushed()]), + wait.response([label("labeled", 1, "merge", "waiter")], { etag: '"t"' }), + wait.response([label("labeled", 1, "merge", "waiter"), label("labeled", 3, "needs review", "person")]), + ], + [wait.A], + { + comments: [ + wait.response([ + wait.replied(1, wait.POINT, "reviewer", null), + wait.replied(2, wait.POINT, "waiter"), + ]), + wait.response([ + wait.replied(1, wait.POINT, "reviewer", null), + wait.replied(2, wait.POINT, "waiter"), + ]), + ], + graphql: [wait.reactions([wait.reacted("r1", wait.POINT, "waiter")])], + edits: [wait.response([edited(1, "waiter")])], + // On an installation token GitHub says the viewer is the App. + viewer: wait.response({ data: { viewer: { login: "quest[bot]" } } }), + }, + ); + const w = world({ github: fixture.deps.fetch }); + const deps: ForgeDependencies = { + ...w.deps, + github: () => ({ ...fixture.deps, token: PERSON }) as GitHubDependencies, + }; + const lines = await waitForActivity(wait.pr, {}, { choose: async (pull) => liveFor(pull, deps) }, fixture.deps); + expect(lines.map((line) => line.split(" ").slice(1, 3).join(" "))).toEqual(["labeled:needs_review person"]); + const tokens = new Set( + [...fixture.calls, ...fixture.sideCalls, ...fixture.editCalls, ...fixture.checkCalls].map((call) => + call.headers.get("authorization"), + ), + ); + expect(tokens).toEqual(new Set(["Bearer minted-1"])); + expect(w.mints).toHaveLength(1); + }); +}); diff --git a/test/pull-files.test.ts b/test/pull-files.test.ts index 2429156b..5ce830f4 100644 --- a/test/pull-files.test.ts +++ b/test/pull-files.test.ts @@ -117,6 +117,8 @@ describe("quest pr list in a fork on GitHub", () => { vi.stubGlobal("fetch", async (input: URL | string, init?: { body?: string }) => { const url = new URL(input); asked.push(url.pathname); + // Kixel Quest does not serve this repository, so the person's own token reads it. + if (url.pathname === "/installation-token") return new Response("{}", { status: 404 }); if (url.pathname === "/repos/me/project") return json(info("me/project", { fork: true, parent: info("example/project") })); if (url.pathname === "/repos/example/project") return json(info("example/project")); diff --git a/test/start.test.ts b/test/start.test.ts index 799985ec..f04b22bc 100644 --- a/test/start.test.ts +++ b/test/start.test.ts @@ -10,7 +10,7 @@ import { afterEach, describe, expect, test, vi } from "vitest"; import { claims, openDrafts, target } from "../src/cli/claims"; import { githubRepository, readRemote, remoteRepository } from "../src/cli/github"; -import { type GitHubDependencies, type ObjectValue } from "../src/github/client"; +import { type GitHubDependencies, type ObjectValue, reading } from "../src/github/client"; import { GitHubForge } from "../src/github/forge"; import { type Output, main } from "../src/cli/main"; import { Refusal } from "../src/core"; @@ -202,7 +202,8 @@ class FakeGitHub { function deps(github: FakeGitHub, warnings: string[] = []) { return { github: () => github.deps(), - forge: async () => new GitHubForge(github.deps()), + forge: async () => new GitHubForge(reading(github.deps())), + live: async () => new GitHubForge(reading(github.deps())), warn: (message: string) => warnings.push(message), }; } @@ -849,7 +850,8 @@ test("openDrafts skips drafts with a warning when GitHub cannot be read", async github: () => { throw new Error("set GH_TOKEN or GITHUB_TOKEN, or sign in with gh auth login"); }, - forge: async () => new GitHubForge(offline.github()), + forge: async () => new GitHubForge(reading(offline.github())), + live: async () => new GitHubForge(reading(offline.github())), warn: (message: string) => warnings.push(message), }; expect(await openDrafts(work, "origin", offline)).toEqual([]); diff --git a/test/status-fakes.ts b/test/status-fakes.ts index 533289bd..8c2b924d 100644 --- a/test/status-fakes.ts +++ b/test/status-fakes.ts @@ -1,7 +1,7 @@ // A fake GitHub for `quest status`: recorded GraphQL answers and the REST reads around them. import { expect } from "vitest"; -import { type GitHubDependencies } from "../src/github/client"; +import { type GitHubReadDependencies } from "../src/github/client"; export const A = "a".repeat(40); export const B = "b".repeat(40); @@ -137,8 +137,8 @@ export function setup( const eventPages = [...(options.eventPages ?? [])]; const activityPages = [...(options.activity ?? [])]; const activityRequests: string[] = []; - const deps: GitHubDependencies = { - token: "test-token", + const deps: GitHubReadDependencies = { + readToken: "test-token", quota: "wait", now: () => options.now ?? 0, sleep: async () => {}, diff --git a/test/status.test.ts b/test/status.test.ts index b209760f..dbb394cc 100644 --- a/test/status.test.ts +++ b/test/status.test.ts @@ -1,6 +1,6 @@ import { describe, expect, test } from "vitest"; -import { GitHub } from "../src/github/client"; +import { GitHubReader } from "../src/github/client"; import { main } from "../src/cli/main"; import { statusLines } from "../src/cli/status"; import { pullRequestStatus, requiredOf } from "../src/github/status"; @@ -410,7 +410,7 @@ test("a base's requirements read once give the status a read of its own would, a expect(own.reads).not.toEqual([]); const shared = counted(); - const needs = await requiredOf(new GitHub(shared.deps), pr, "main"); + const needs = await requiredOf(new GitHubReader(shared.deps), pr, "main"); const before = shared.reads.length; expect(await pullRequestStatus(pr, shared.deps, { ...pr, branch: "main", needs })).toEqual(expected); expect(shared.reads).toHaveLength(before); diff --git a/test/usage.test.ts b/test/usage.test.ts index 8eec15c3..ce37d62e 100644 --- a/test/usage.test.ts +++ b/test/usage.test.ts @@ -823,6 +823,7 @@ describe("usage", () => { warn: () => {}, }), forge: () => Promise.reject(new Error("usage reads no forge")), + live: () => Promise.reject(new Error("usage reads no forge")), warn: () => {}, sessions: (since: Date, ssh: string[]) => { calls.push([since, ssh]); diff --git a/test/wait-fakes.ts b/test/wait-fakes.ts index aa1e4942..5426320e 100644 --- a/test/wait-fakes.ts +++ b/test/wait-fakes.ts @@ -1,5 +1,5 @@ // A fake GitHub for `quest wait`: scripted REST pages and GraphQL answers, and a clock that advances as it sleeps. -import { type CachedResponse, type GitHubDependencies } from "../src/github/client"; +import { type CachedResponse, type GitHubReadDependencies } from "../src/github/client"; import { GitHubForge } from "../src/github/forge"; import { waitForActivity, type WaitOptions } from "../src/cli/wait"; @@ -186,8 +186,8 @@ export function setup( const sleeps: number[] = []; const warnings: string[] = []; const stored = new Map(); - const deps: GitHubDependencies = { - token: "test-token", + const deps: GitHubReadDependencies = { + readToken: "test-token", quota: "wait", cache: { get: async (key) => stored.get(key), set: async (key, entry) => void stored.set(key, entry) }, now: () => now, @@ -264,7 +264,7 @@ export function setup( } /** Wait on GitHub, with the fixture's clock. */ -export function waitOn(pull: typeof pr, options: WaitOptions, deps: GitHubDependencies): Promise { +export function waitOn(pull: typeof pr, options: WaitOptions, deps: GitHubReadDependencies): Promise { return waitForActivity(pull, options, { choose: async () => new GitHubForge(deps) }, deps); } From 549fcac8653c90d67db21e3c7eabde95f7e2bf98 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:21:02 -0800 Subject: [PATCH 03/10] fix(github): mint an installation token once between parallel agents Co-Authored-By: Claude Sonnet 5.5 --- src/cli/forge.ts | 57 +++++++++++++++++++++++---------- src/cli/installation.ts | 67 ++++++++++++++++++++++++++++++++++++++- src/cli/main.ts | 1 + src/cli/send.ts | 9 +++++- test/forge.test.ts | 1 + test/installation.test.ts | 38 +++++++++++++++++++++- 6 files changed, 154 insertions(+), 19 deletions(-) diff --git a/src/cli/forge.ts b/src/cli/forge.ts index 791d3a20..6403369d 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -34,7 +34,15 @@ import { import { type GitHubDependencies, reading } from "../github/client"; import { GitHubForge } from "../github/forge"; import { pullRequest, readRemote, remoteHost } from "./github"; -import { type Installation, REUSE_MARGIN, installationDirectory, keep, kept } from "./installation"; +import { + type Installation, + LockDeadline, + REUSE_MARGIN, + exclusive, + installationDirectory, + keep, + kept, +} from "./installation"; import { kixelUrl, tokenFor, tokensPath } from "./tokens"; /** The variable that, set to `github`, reads GitHub even where Kixel Quest serves the repository. */ @@ -45,6 +53,7 @@ export interface ForgeDependencies { env: NodeJS.ProcessEnv; fetch: typeof fetch; now(): number; + sleep(milliseconds: number): Promise; /** Called only once a read goes to GitHub, so Kixel Quest's reads need no GitHub token. */ github(): GitHubDependencies; /** What a Kixel Quest failure tells the person to do; by default, to read GitHub instead. */ @@ -217,24 +226,40 @@ export class KixelQuest { } const path = "/installation-token"; const name = `${repository.owner}/${repository.repo}`; - const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); - if (response.status === 404) return null; - if (response.status === 429) { - const wait = Number(response.headers.get("retry-after")); - throw this.#failed( - "POST", - path, - `you have minted as many installation tokens this hour as one person may${Number.isFinite(wait) && wait > 0 ? `; try again in ${Math.ceil(wait)} seconds` : ""}`, - ); - } - if (!response.ok) throw this.#failed("POST", path, `HTTP ${response.status}${reason(text)}`); - const installation = this.#minted(text, name); + const mint = async (): Promise => { + // Another agent may have minted while this one waited for the lock. + try { + const have = kept(directory, this.url, this.token, repository, this.deps.now()); + if (have !== null) return have; + } catch (error) { + throw keeping("read", error); + } + const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); + if (response.status === 404) return null; + if (response.status === 429) { + const wait = Number(response.headers.get("retry-after")); + throw this.#failed( + "POST", + path, + `you have minted as many installation tokens this hour as one person may${Number.isFinite(wait) && wait > 0 ? `; try again in ${Math.ceil(wait)} seconds` : ""}`, + ); + } + if (!response.ok) throw this.#failed("POST", path, `HTTP ${response.status}${reason(text)}`); + const installation = this.#minted(text, name); + try { + keep(directory, this.url, this.token, repository, installation); + } catch (error) { + throw keeping("keep", error); + } + return installation; + }; try { - keep(directory, this.url, this.token, repository, installation); + return await exclusive(directory, this.url, this.token, repository, this.deps, deadline, mint); } catch (error) { - throw keeping("keep", error); + if (error instanceof LockDeadline) throw this.#failed("POST", path, error.message); + if ((error as NodeJS.ErrnoException).code !== undefined) throw keeping("lock", error); + throw error; } - return installation; } /** The token in a mint's answer, `{token, expiresAt, repository, login}`, for `name`. */ diff --git a/src/cli/installation.ts b/src/cli/installation.ts index aa6923a3..a2925cda 100644 --- a/src/cli/installation.ts +++ b/src/cli/installation.ts @@ -1,7 +1,7 @@ // The App installation tokens Kixel Quest mints for a person's reads, kept on disk until shortly before they expire: // a person's hourly cap on minting is spent within a minute if each command mints its own. import { createHash } from "node:crypto"; -import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"; +import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"; import { homedir } from "node:os"; import { join } from "node:path"; @@ -72,3 +72,68 @@ export function keep( writeFileSync(temporary, JSON.stringify(installation), { mode: 0o600 }); renameSync(temporary, path); } + +/** How long a lock may stand before it is taken for a crashed holder's, and how often a waiter looks again. */ +const STALE = 30_000; +const POLL = 100; + +/** The clock a lock waits on. */ +export interface Clock { + now(): number; + sleep(milliseconds: number): Promise; +} + +/** A lock was still held when the caller's deadline passed. */ +export class LockDeadline extends Error { + constructor() { + super("its deadline passed while another quest minted the token"); + } +} + +/** + * Run `run` while holding the one lock for `repository`'s token, so parallel agents on a cold or expiring cache mint + * once between them: each waits, then finds the winner's token. The lock is a file created exclusively, holding its + * time, so a holder that crashed is taken over after `STALE` milliseconds; two waiters that take over at once may + * mint twice, which only spends one more of the cap. Waits until `deadline`, epoch milliseconds. + */ +export async function exclusive( + directory: string, + url: string, + kixelToken: string, + repository: Repository, + clock: Clock, + deadline: number, + run: () => Promise, +): Promise { + mkdirSync(directory, { recursive: true, mode: 0o700 }); + const lock = `${file(directory, url, kixelToken, repository)}.lock`; + for (;;) { + try { + writeFileSync(lock, String(clock.now()), { flag: "wx", mode: 0o600 }); + break; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; + } + let since = Number.NaN; + try { + const text = readFileSync(lock, "utf8"); + // Created but not yet written: its holder has only just taken it. + since = text === "" ? clock.now() : Number(text); + } catch (error) { + // Released between the two reads: try to take it again. + if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; + throw error; + } + if (!(clock.now() - since <= STALE)) { + rmSync(lock, { force: true }); + continue; + } + if (clock.now() >= deadline) throw new LockDeadline(); + await clock.sleep(Math.min(POLL, deadline - clock.now())); + } + try { + return await run(); + } finally { + rmSync(lock, { force: true }); + } +} diff --git a/src/cli/main.ts b/src/cli/main.ts index 107f025b..23d0c5c8 100644 --- a/src/cli/main.ts +++ b/src/cli/main.ts @@ -148,6 +148,7 @@ export function main(argv: string[], out: Output): number | Promise { env: process.env, fetch: globalThis.fetch, now: Date.now, + sleep, github: () => gitHubDependencies(warn, quota), }); const claimDependencies = (): ClaimDependencies => ({ diff --git a/src/cli/send.ts b/src/cli/send.ts index 0b241e48..5dd7d5b6 100644 --- a/src/cli/send.ts +++ b/src/cli/send.ts @@ -324,7 +324,14 @@ async function sendOnce(deps: SendDependencies, dir: string): Promise { const kixel = new KixelQuest( url, token, - { env: deps.env, fetch: deps.fetch, now: deps.now, github: deps.github, remedy: "its records stay queued" }, + { + env: deps.env, + fetch: deps.fetch, + now: deps.now, + sleep: async () => {}, + github: deps.github, + remedy: "its records stay queued", + }, false, ); /** Kixel Quest refused the token, which every group shares: nothing more is sent, and what is queued is dropped. */ diff --git a/test/forge.test.ts b/test/forge.test.ts index d9ece492..6aa4afbb 100644 --- a/test/forge.test.ts +++ b/test/forge.test.ts @@ -107,6 +107,7 @@ function dependencies( env: { XDG_CONFIG_HOME: config, XDG_CACHE_HOME: join(config, "cache"), ...env }, fetch, now: () => 0, + sleep: async () => {}, // The fake's token is the person's own here. github: () => { const { readToken, ...rest } = github(); diff --git a/test/installation.test.ts b/test/installation.test.ts index fdd73c0a..52731ed8 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -1,5 +1,6 @@ // Reads on the installation token Kixel Quest mints, and writes on the person's own, against a fake Kixel Quest and a // fake GitHub that record the token each request carries. +import { createHash } from "node:crypto"; import { existsSync, mkdirSync, mkdtempSync, readdirSync, statSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -64,7 +65,13 @@ function world(options: { mint?: (n: number, repository: string) => Response; gi quota: "fail", warn: () => {}, }); - const deps: ForgeDependencies = { env, fetch: fetch as typeof globalThis.fetch, now: () => clock, github: person }; + const deps: ForgeDependencies = { + env, + fetch: fetch as typeof globalThis.fetch, + now: () => clock, + sleep: async (ms) => void (clock += ms), + github: person, + }; return { deps, mints, github, person, env }; } @@ -123,6 +130,35 @@ describe("reads on a minted installation token", () => { expect(statSync(directory).mode & 0o777).toBe(0o700); }); + test("agents starting on a cold cache mint once between them", async () => { + const w = world(); + // Each waiter lets the others run while it sleeps, as parallel processes do. + const slow: ForgeDependencies = { ...w.deps, sleep: async (ms) => void (await Promise.resolve((clock += ms))) }; + const forges = await Promise.all(Array.from({ length: 8 }, () => liveFor(repository, slow))); + await Promise.all(forges.map((forge) => forge.pulls(repository))); + expect(w.mints).toHaveLength(1); + expect(new Set(w.github.map((request) => request.token))).toEqual(new Set(["minted-1"])); + expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); + }); + + test("a lock a crashed agent left is taken over once stale, and a held one is waited for until the deadline", async () => { + const w = world(); + const lock = join( + installationDirectory(w.env), + `${createHash("sha256").update(`${KIXEL}\n${KIXEL_TOKEN}\nexample/project`).digest("hex")}.lock`, + ); + mkdirSync(installationDirectory(w.env), { recursive: true }); + writeFileSync(lock, String(clock)); + await expect(liveFor(repository, w.deps, clock + 1000)).rejects.toThrow( + "its deadline passed while another quest minted the token", + ); + expect(w.mints).toEqual([]); + clock += 60_000; + await liveFor(repository, w.deps); + expect(w.mints).toHaveLength(1); + expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); + }); + test("a person with another Kixel Quest token mints their own", async () => { const w = world(); await liveFor(repository, w.deps); From 466689da510218ac62e61a099a73f34e9b4ec7c9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 15:23:22 -0800 Subject: [PATCH 04/10] fix(github): keep a live minter's lock Co-Authored-By: Claude Sonnet 5.5 --- src/cli/forge.ts | 4 ++-- src/cli/installation.ts | 26 ++++++++++++++++++-------- test/installation.test.ts | 18 +++++++++++++++++- 3 files changed, 37 insertions(+), 11 deletions(-) diff --git a/src/cli/forge.ts b/src/cli/forge.ts index 6403369d..bbe7add3 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -226,7 +226,7 @@ export class KixelQuest { } const path = "/installation-token"; const name = `${repository.owner}/${repository.repo}`; - const mint = async (): Promise => { + const mint = async (until: number): Promise => { // Another agent may have minted while this one waited for the lock. try { const have = kept(directory, this.url, this.token, repository, this.deps.now()); @@ -234,7 +234,7 @@ export class KixelQuest { } catch (error) { throw keeping("read", error); } - const { response, text } = await this.#fetch("POST", path, { repository: name }, deadline); + const { response, text } = await this.#fetch("POST", path, { repository: name }, until); if (response.status === 404) return null; if (response.status === 429) { const wait = Number(response.headers.get("retry-after")); diff --git a/src/cli/installation.ts b/src/cli/installation.ts index a2925cda..52fa5f58 100644 --- a/src/cli/installation.ts +++ b/src/cli/installation.ts @@ -76,6 +76,8 @@ export function keep( /** How long a lock may stand before it is taken for a crashed holder's, and how often a waiter looks again. */ const STALE = 30_000; const POLL = 100; +/** The longest a holder works under its lock, well inside `STALE`, so a live holder is never taken over. */ +export const HOLD = 20_000; /** The clock a lock waits on. */ export interface Clock { @@ -92,9 +94,11 @@ export class LockDeadline extends Error { /** * Run `run` while holding the one lock for `repository`'s token, so parallel agents on a cold or expiring cache mint - * once between them: each waits, then finds the winner's token. The lock is a file created exclusively, holding its - * time, so a holder that crashed is taken over after `STALE` milliseconds; two waiters that take over at once may - * mint twice, which only spends one more of the cap. Waits until `deadline`, epoch milliseconds. + * once between them: each waits, then finds the winner's token. `run` gets the time, epoch milliseconds, it must + * finish by: the caller's `deadline`, or `HOLD` after it took the lock if sooner, so a live holder is never taken + * over. The lock is a file created exclusively, holding its time and its owner, so a holder that crashed is taken over + * after `STALE` milliseconds, and a holder releases only a lock still its own. Waits until `deadline`, epoch + * milliseconds; two waiters that take over a crashed holder's lock at once may mint twice. */ export async function exclusive( directory: string, @@ -103,13 +107,14 @@ export async function exclusive( repository: Repository, clock: Clock, deadline: number, - run: () => Promise, + run: (until: number) => Promise, ): Promise { mkdirSync(directory, { recursive: true, mode: 0o700 }); const lock = `${file(directory, url, kixelToken, repository)}.lock`; + const owner = crypto.randomUUID(); for (;;) { try { - writeFileSync(lock, String(clock.now()), { flag: "wx", mode: 0o600 }); + writeFileSync(lock, `${clock.now()} ${owner}`, { flag: "wx", mode: 0o600 }); break; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; @@ -118,7 +123,7 @@ export async function exclusive( try { const text = readFileSync(lock, "utf8"); // Created but not yet written: its holder has only just taken it. - since = text === "" ? clock.now() : Number(text); + since = text === "" ? clock.now() : Number(text.split(" ")[0]); } catch (error) { // Released between the two reads: try to take it again. if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; @@ -132,8 +137,13 @@ export async function exclusive( await clock.sleep(Math.min(POLL, deadline - clock.now())); } try { - return await run(); + return await run(Math.min(deadline, clock.now() + HOLD)); } finally { - rmSync(lock, { force: true }); + try { + if (readFileSync(lock, "utf8").endsWith(` ${owner}`)) rmSync(lock, { force: true }); + } catch (error) { + // Taken over and released by another, which owns the file's fate now. + if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; + } } } diff --git a/test/installation.test.ts b/test/installation.test.ts index 52731ed8..32670c52 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -8,7 +8,7 @@ import { join } from "node:path"; import { beforeEach, describe, expect, test } from "vitest"; import { type ForgeDependencies, liveFor } from "../src/cli/forge"; -import { REUSE_MARGIN, installationDirectory } from "../src/cli/installation"; +import { HOLD, REUSE_MARGIN, exclusive, installationDirectory } from "../src/cli/installation"; import { waitForActivity } from "../src/cli/wait"; import { GitHubWrites } from "../src/cli/writes"; import { GitHub, type GitHubDependencies, GitHubReader, reading } from "../src/github/client"; @@ -159,6 +159,22 @@ describe("reads on a minted installation token", () => { expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); }); + test("a holder gets less time than it takes to be taken over, and never releases another's lock", async () => { + const directory = installationDirectory({ XDG_CACHE_HOME: cache }); + const clockwork = { now: () => clock, sleep: async (ms: number) => void (clock += ms) }; + let until = 0; + await exclusive(directory, KIXEL, KIXEL_TOKEN, repository, clockwork, Infinity, async (limit) => { + until = limit; + }); + expect(until).toBe(START + HOLD); + // A holder that overran, whose lock another took over, leaves the new holder's lock be. + await exclusive(directory, KIXEL, KIXEL_TOKEN, repository, clockwork, Infinity, async () => { + const [held] = readdirSync(directory); + writeFileSync(join(directory, held!), `${clock} another`); + }); + expect(readdirSync(directory).filter((name) => name.endsWith(".lock"))).toHaveLength(1); + }); + test("a person with another Kixel Quest token mints their own", async () => { const w = world(); await liveFor(repository, w.deps); From 6740778aa3fe21bd0f4cbafa8fc3ceadcc41d37e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 00:59:37 -0800 Subject: [PATCH 05/10] fix(github): take over a lock left empty, and correct where the minted token reads Pullfrog found an empty lock never went stale and two doc claims overreached: quest wait never reads on a minted token, and an unserved repository reads on the person's own. Co-Authored-By: Claude Opus 5.5 --- README.md | 5 +++-- src/cli/forge.ts | 7 ++++--- src/cli/installation.ts | 12 +++++++++--- test/installation.test.ts | 17 +++++++++++++++++ 4 files changed, 33 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 17a735f7..5832bfcf 100644 --- a/README.md +++ b/README.md @@ -647,8 +647,9 @@ person's own token. `quest` keeps each token in five minutes before it expires, since a person may mint only so many an hour, and a 429 or any other failure fails the command, naming `QUEST_FORGE=github`. Writes, such as comments, pushes, and merges, always use the person's own token, -so they are made in their name; `quest wait` takes the person from the mint's -`login`, because on an installation token GitHub names the App as the viewer. +so they are made in their name. A forge reading on a minted token takes the +person from the mint's `login`, because on an installation token GitHub names +the App as the viewer. Its read API lives under `/forge`, with the token as a bearer token: `GET /forge` answers `{"login", "repositories"}`, the person the token names diff --git a/src/cli/forge.ts b/src/cli/forge.ts index bbe7add3..4d137888 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -1,9 +1,10 @@ // Which forge answers a repository's reads and takes its writes. A repository Kixel Quest hosts, named by a remote or // PR URL on Kixel Quest, is read and written there alone. For one on GitHub, reads go to Kixel Quest's index for a // person holding its token when it serves the repository, else GitHub, and writes go to GitHub. A Kixel Quest failure -// fails the command, naming the setting that reads GitHub instead where that would help. A read that goes to GitHub -// anyway, to verify what an index said or because Kixel Quest does not serve the repository, runs on a read-only -// installation token Kixel Quest mints, so it draws on the installation's rate limit rather than the person's. +// fails the command, naming the setting that reads GitHub instead where that would help. A live read of a repository +// Kixel Quest serves, which must come from GitHub itself rather than an index that may lag, runs on a read-only +// installation token Kixel Quest mints, so it draws on the installation's rate limit rather than the person's; one of +// a repository it does not serve runs on the person's own token. import { type Answer, type ClaimSources, diff --git a/src/cli/installation.ts b/src/cli/installation.ts index 52fa5f58..6aebc010 100644 --- a/src/cli/installation.ts +++ b/src/cli/installation.ts @@ -97,7 +97,7 @@ export class LockDeadline extends Error { * once between them: each waits, then finds the winner's token. `run` gets the time, epoch milliseconds, it must * finish by: the caller's `deadline`, or `HOLD` after it took the lock if sooner, so a live holder is never taken * over. The lock is a file created exclusively, holding its time and its owner, so a holder that crashed is taken over - * after `STALE` milliseconds, and a holder releases only a lock still its own. Waits until `deadline`, epoch + * after `STALE` milliseconds (one left empty, `STALE` after the waiter first found it empty), and a holder releases only a lock still its own. Waits until `deadline`, epoch * milliseconds; two waiters that take over a crashed holder's lock at once may mint twice. */ export async function exclusive( @@ -112,6 +112,8 @@ export async function exclusive( mkdirSync(directory, { recursive: true, mode: 0o700 }); const lock = `${file(directory, url, kixelToken, repository)}.lock`; const owner = crypto.randomUUID(); + // When this waiter first found the lock empty, so one whose holder died before writing it still goes stale. + let empty: number | undefined; for (;;) { try { writeFileSync(lock, `${clock.now()} ${owner}`, { flag: "wx", mode: 0o600 }); @@ -122,8 +124,12 @@ export async function exclusive( let since = Number.NaN; try { const text = readFileSync(lock, "utf8"); - // Created but not yet written: its holder has only just taken it. - since = text === "" ? clock.now() : Number(text.split(" ")[0]); + // Created but not yet written: date it from when it was first seen empty. + if (text === "") since = empty ??= clock.now(); + else { + empty = undefined; + since = Number(text.split(" ")[0]); + } } catch (error) { // Released between the two reads: try to take it again. if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; diff --git a/test/installation.test.ts b/test/installation.test.ts index 32670c52..45939c7b 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -159,6 +159,23 @@ describe("reads on a minted installation token", () => { expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); }); + test("a lock left empty by an agent that died before writing it is taken over once stale", async () => { + const w = world(); + const lock = join( + installationDirectory(w.env), + `${createHash("sha256").update(`${KIXEL}\n${KIXEL_TOKEN}\nexample/project`).digest("hex")}.lock`, + ); + mkdirSync(installationDirectory(w.env), { recursive: true }); + writeFileSync(lock, ""); + await expect(liveFor(repository, w.deps, clock + 1000)).rejects.toThrow( + "its deadline passed while another quest minted the token", + ); + expect(w.mints).toEqual([]); + await liveFor(repository, w.deps); + expect(w.mints).toHaveLength(1); + expect(files(w.env).filter((name) => name.endsWith(".lock"))).toEqual([]); + }); + test("a holder gets less time than it takes to be taken over, and never releases another's lock", async () => { const directory = installationDirectory({ XDG_CACHE_HOME: cache }); const clockwork = { now: () => clock, sleep: async (ms: number) => void (clock += ms) }; From d418b2e5d6885fc1ad8c6056e59034e7420a62d9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 01:21:11 -0800 Subject: [PATCH 06/10] fix(github): meet a cross-repository required workflow the token cannot see, and harden the read client CodeRabbit's findings on 6740778a: - A required workflow from a repository the installation token cannot see is met by its path from any repository but the base's, instead of staying pending forever. - quest start mints before opening its PR, so a refused mint takes the claim branch back rather than leaving a PR behind. - A lock holder's time to work counts from the time written in the lock. - reading() forwards each host member, so a class-instance host keeps its methods. - A read client refuses a mutation after a comment or fragment. Co-Authored-By: Claude Opus 5.5 --- src/cli/installation.ts | 7 +++++-- src/cli/start.ts | 5 ++++- src/github/client.ts | 29 ++++++++++++++++++++++++----- src/github/status.ts | 25 +++++++++++++++++++++++-- test/installation.test.ts | 25 +++++++++++++++++++++++++ test/start.test.ts | 17 +++++++++++++++++ test/status-fakes.ts | 3 ++- test/status.test.ts | 23 +++++++++++++++++++++++ 8 files changed, 123 insertions(+), 11 deletions(-) diff --git a/src/cli/installation.ts b/src/cli/installation.ts index 6aebc010..78fdad1c 100644 --- a/src/cli/installation.ts +++ b/src/cli/installation.ts @@ -114,9 +114,12 @@ export async function exclusive( const owner = crypto.randomUUID(); // When this waiter first found the lock empty, so one whose holder died before writing it still goes stale. let empty: number | undefined; + // When this holder took the lock, as written in it, so its time to work counts from what a waiter reads. + let taken = 0; for (;;) { + taken = clock.now(); try { - writeFileSync(lock, `${clock.now()} ${owner}`, { flag: "wx", mode: 0o600 }); + writeFileSync(lock, `${taken} ${owner}`, { flag: "wx", mode: 0o600 }); break; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; @@ -143,7 +146,7 @@ export async function exclusive( await clock.sleep(Math.min(POLL, deadline - clock.now())); } try { - return await run(Math.min(deadline, clock.now() + HOLD)); + return await run(Math.min(deadline, taken + HOLD)); } finally { try { if (readFileSync(lock, "utf8").endsWith(` ${owner}`)) rmSync(lock, { force: true }); diff --git a/src/cli/start.ts b/src/cli/start.ts index beec8144..01b5b478 100644 --- a/src/cli/start.ts +++ b/src/cli/start.ts @@ -176,7 +176,10 @@ async function openDraft( const body = link === null ? `Claims \`${path}\`.` : `Claims [${path}](${link}).`; const writes = hosting.writes(); let created: OpenPull; + let live: Awaited>; try { + // Before the PR exists, so a failed mint takes the branch back rather than leaving a PR behind. + live = await hosting.live(); created = await writes.open({ repository, head, @@ -193,7 +196,7 @@ async function openDraft( } // Two claimers on different repositories, such as forks, both push; the earliest PR wins. - const open = pullsFrom((await (await hosting.live()).pulls(repository)).value, branch); + const open = pullsFrom((await live.pulls(repository)).value, branch); const first = pullsFrom([...open.filter((pull) => pull.number !== created.number), created], branch)[0]; if (first.number !== created.number) { deleteBranch(root, remote, branch, sha); diff --git a/src/github/client.ts b/src/github/client.ts index 126bc884..c091ee6b 100644 --- a/src/github/client.ts +++ b/src/github/client.ts @@ -34,10 +34,29 @@ export interface GitHubDependencies extends Omit[0], init?: Parameters[1]) => + deps.fetch(input, init)) as typeof fetch, + now: () => deps.now(), + sleep: (milliseconds) => deps.sleep(milliseconds), + warn: (message) => deps.warn(message), + readToken: deps.token, + quota: deps.quota, + ...(deps.cache === undefined ? {} : { cache: deps.cache }), + }; +} + +/** + * Whether a GraphQL document defines a mutation: one starting the document, or following a fragment's closing brace, + * once comments are gone. It errs toward refusing, since a read-only client never needs to send one. + */ +function mutates(query: string): boolean { + return /(^|\})\s*mutation\b/.test(query.replace(/#[^\n]*/g, "")); } /** A 200 answer to a GET, kept to serve when GitHub answers its ETag with a 304. */ @@ -390,7 +409,7 @@ export class GitHubReader { * 200 whose errors say `RATE_LIMITED`; that is waited out like a REST one. */ async graphql(query: string, variables: ObjectValue): Promise { - if (/^\s*mutation\b/.test(query)) throw new Error("a read-only GitHub client cannot run a mutation"); + if (mutates(query)) throw new Error("a read-only GitHub client cannot run a mutation"); return this.operate(query, variables, true); } @@ -554,7 +573,7 @@ async function requiredWorkflows(github: GitHubReader, rules: ObjectValue[]): Pr const id = Number(row.repository_id); if (!names.has(id)) { const response = await github.request(`/repositories/${id}`, { allow: [404] }); - // A repository the token cannot see is still required; nothing on the head can match its name. + // A repository the token cannot see is still required, by its id; `unreported` matches it by path alone. names.set(id, response.ok ? string(object(await response.json()).full_name) : `repository ${id}`); } keys.push(workflowKey(names.get(id)!, string(row.path))); diff --git a/src/github/status.ts b/src/github/status.ts index 87790ce6..ff859984 100644 --- a/src/github/status.ts +++ b/src/github/status.ts @@ -299,12 +299,22 @@ export interface Needs { checks: { name: string; app: number | null }[]; /** Workflow files that must pass as a whole, from {@link workflowKey}. */ workflows: string[]; + /** + * The lowercase `owner/repo` whose base this is. A required workflow keyed `repository `, from a repository + * the token cannot see, such as an installation token scoped to this one, is met by a workflow at its path from any + * repository but this; without it, such a workflow is never met. + */ + repository?: string; } /** What `branch` requires of a PR head. The gate's own check is never on one, so it is left out. */ export async function requiredOf(github: GitHubReader, repository: Repository, branch: string): Promise { const found = await requirements(github, repository, branch); - return { checks: found.checks.filter((check) => check.name !== LAND_CHECK), workflows: found.workflows }; + return { + checks: found.checks.filter((check) => check.name !== LAND_CHECK), + workflows: found.workflows, + repository: `${repository.owner}/${repository.repo}`.toLowerCase(), + }; } /** A check as a requirement matches it: its name, its app, and the workflow file a GitHub Actions job runs in. */ @@ -339,10 +349,21 @@ export function unreported(found: Reported[], needs: Needs): string[] { !found.some((entry) => entry.name === need.name && (need.app === null || entry.app === need.app)), ) .map((need) => (need.app === null ? need.name : `${need.name} (from app ${need.app})`)), - ...needs.workflows.filter((key) => !found.some((entry) => entry.workflow === key)), + ...needs.workflows.filter((key) => !found.some((entry) => entry.workflow && meets(entry.workflow, key, needs))), ]; } +/** Whether a reported workflow `actual` meets the required `key`, both from {@link workflowKey}. */ +function meets(actual: string, key: string, needs: Needs): boolean { + if (actual === key) return true; + const split = (value: string) => [value.slice(0, value.indexOf(":")), value.slice(value.indexOf(":") + 1)]; + const [owner, path] = split(key); + const [from, file] = split(actual); + return ( + owner.startsWith("repository ") && needs.repository !== undefined && file === path && from !== needs.repository + ); +} + /** * The PR's state from its pages. `current` holds the head's checks that count, from {@link currentChecks}; a * check is required when the base requires it or its workflow, and a requirement nothing reports is pending. diff --git a/test/installation.test.ts b/test/installation.test.ts index 45939c7b..77e36d25 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -103,9 +103,34 @@ describe("reads on a minted installation token", () => { const forge = () => new GitHubWrites(reading(w.person()), null as never); void forge; await expect(reader.graphql("mutation { x }", {})).rejects.toThrow("cannot run a mutation"); + await expect(reader.graphql("# note\nmutation { x }", {})).rejects.toThrow("cannot run a mutation"); + await expect(reader.graphql("fragment f on X { y }\nmutation { x { ...f } }", {})).rejects.toThrow( + "cannot run a mutation", + ); expect(w.github).toEqual([]); }); + test("a host whose members are a class's methods keeps them as read dependencies", async () => { + const w = world(); + const person = w.person(); + class Host { + token = PERSON; + quota = "fail" as const; + fetch = person.fetch; + now() { + return person.now(); + } + sleep(milliseconds: number) { + return person.sleep(milliseconds); + } + warn(message: string) { + person.warn(message); + } + } + await new GitHub(new Host()).request("/repos/example/project/pulls"); + expect(w.github).toEqual([{ method: "GET", path: "/repos/example/project/pulls", token: PERSON }]); + }); + test("the token is minted once and reused across runs until shortly before it expires", async () => { const w = world(); await liveFor(repository, w.deps); diff --git a/test/start.test.ts b/test/start.test.ts index f04b22bc..2d44d0d1 100644 --- a/test/start.test.ts +++ b/test/start.test.ts @@ -261,6 +261,23 @@ describe("start on GitHub", () => { expect(github.pulls[0].body).toBe(`Claims [${ONE}](https://github.com/example/project/blob/main/${ONE}).`); }); + test("a live read that fails before the PR opens, such as a refused mint, takes the branch back and opens none", async () => { + const bare = upstream(); + const github = new FakeGitHub(); + const work = clone(UPSTREAM, { [UPSTREAM]: bare }); + const dependencies = { + ...deps(github), + live: async (): Promise => { + throw new Error("Kixel Quest refused the mint"); + }, + }; + await expect( + startQuest(work, await target(work, "origin", dependencies), ONE, "[S] One", dependencies), + ).rejects.toThrow("Kixel Quest refused the mint"); + expect(github.pulls).toEqual([]); + expect(tip(bare)).toBe(""); + }); + test("links the quest by its repository path when the tree is below the top level", async () => { const bare = initRepository(undefined, { bare: true }); const work = tempDir(); diff --git a/test/status-fakes.ts b/test/status-fakes.ts index 8c2b924d..d2f0cc61 100644 --- a/test/status-fakes.ts +++ b/test/status-fakes.ts @@ -153,9 +153,10 @@ export function setup( return Response.json({ message: "Resource not accessible by integration" }, { status: 403 }); return Response.json(page.rows, { headers: page.next ? { Link: `<${page.next}>; rel="next"` } : {} }); } - // Ruleset workflows name their repository by ID: 1 is this one, 2 another. + // Ruleset workflows name their repository by ID: 1 is this one, 2 another, 3 one the token cannot see. if (path.pathname === "/repositories/1") return Response.json({ full_name: "example/project" }); if (path.pathname === "/repositories/2") return Response.json({ full_name: "example/policies" }); + if (path.pathname === "/repositories/3") return Response.json({ message: "Not Found" }, { status: 404 }); if (path.pathname === "/repos/example/project/branches/main") return options.noBase ? Response.json({ message: "Branch not found" }, { status: 404 }) diff --git a/test/status.test.ts b/test/status.test.ts index dbb394cc..e6ed0701 100644 --- a/test/status.test.ts +++ b/test/status.test.ts @@ -506,6 +506,29 @@ test("a required workflow matches its repository as well as its path", async () expect(status.checks.pending.map((check) => check.name)).toEqual([`example/policies:${CI}`]); }); +test("a required workflow from a repository the token cannot see is met by its path from another repository", async () => { + const job = (repositoryName: string) => ({ + ...run("build", "COMPLETED", "SUCCESS", false), + databaseId: 1, + checkSuite: { + databaseId: 10, + app: { databaseId: 15368 }, + workflowRun: { file: { path: CI, repositoryName } }, + }, + }); + // Repository 3 answers 404, as an installation token scoped to example/project answers for example/policies. + const rules = [{ type: "workflows", parameters: { workflows: [{ path: CI, repository_id: 3 }] } }]; + const local = setup([pull({ checks: page([job("example/project")]), reviews: page([]), threads: page([]) })], { + rules, + }); + const unmet = await pullRequestStatus(pr, local.deps); + expect(unmet.checks.pending.map((check) => check.name)).toEqual([`repository 3:${CI}`]); + const policy = setup([pull({ checks: page([job("example/policies")]), reviews: page([]), threads: page([]) })], { + rules, + }); + expect((await pullRequestStatus(pr, policy.deps)).checks.state).toBe("success"); +}); + test("a required workflow counts as reported when another workflow's same-named job is the newer one", async () => { const build = (databaseId: number, path: string) => ({ ...run("build", "COMPLETED", "SUCCESS", false), From 3ae0adc1b9ec5636bce957160d8adcbdf8f4ab56 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 01:23:13 -0800 Subject: [PATCH 07/10] fix(github): let each unseen repository's report meet one required workflow Two required workflows at one path from two repositories the token cannot see now need two reports from distinct repositories, neither the base's nor one a requirement names. Co-Authored-By: Claude Opus 5.5 --- src/github/status.ts | 42 ++++++++++++++++++++++++++++++------------ test/status-fakes.ts | 5 +++-- test/status.test.ts | 10 ++++++++++ 3 files changed, 43 insertions(+), 14 deletions(-) diff --git a/src/github/status.ts b/src/github/status.ts index ff859984..b0396a88 100644 --- a/src/github/status.ts +++ b/src/github/status.ts @@ -301,8 +301,8 @@ export interface Needs { workflows: string[]; /** * The lowercase `owner/repo` whose base this is. A required workflow keyed `repository `, from a repository - * the token cannot see, such as an installation token scoped to this one, is met by a workflow at its path from any - * repository but this; without it, such a workflow is never met. + * the token cannot see, such as an installation token scoped to this one, is met by a workflow at its path from + * another repository, as {@link unmetWorkflows} matches it; without it, such a workflow is never met. */ repository?: string; } @@ -349,19 +349,37 @@ export function unreported(found: Reported[], needs: Needs): string[] { !found.some((entry) => entry.name === need.name && (need.app === null || entry.app === need.app)), ) .map((need) => (need.app === null ? need.name : `${need.name} (from app ${need.app})`)), - ...needs.workflows.filter((key) => !found.some((entry) => entry.workflow && meets(entry.workflow, key, needs))), + ...unmetWorkflows(found, needs), ]; } -/** Whether a reported workflow `actual` meets the required `key`, both from {@link workflowKey}. */ -function meets(actual: string, key: string, needs: Needs): boolean { - if (actual === key) return true; - const split = (value: string) => [value.slice(0, value.indexOf(":")), value.slice(value.indexOf(":") + 1)]; - const [owner, path] = split(key); - const [from, file] = split(actual); - return ( - owner.startsWith("repository ") && needs.repository !== undefined && file === path && from !== needs.repository - ); +/** A workflow key's repository and path. */ +function split(key: string): [string, string] { + return [key.slice(0, key.indexOf(":")), key.slice(key.indexOf(":") + 1)]; +} + +/** + * The required workflows nothing reports. One named by its repository is met by that repository's workflow at its + * path. One keyed `repository `, whose repository the token cannot see, is met by a workflow at its path from a + * repository other than the base's and every named one, each such repository meeting one requirement at most, so two + * unseen repositories' workflows at one path need two reports. + */ +function unmetWorkflows(found: Reported[], needs: Needs): string[] { + const reported = new Set(found.flatMap((entry) => (entry.workflow ? [entry.workflow] : []))); + const named = new Set(needs.workflows.filter((key) => !key.startsWith("repository ")).map((key) => split(key)[0])); + const spent = new Set(); + return needs.workflows.filter((key) => { + if (reported.has(key)) return false; + const [owner, path] = split(key); + if (!owner.startsWith("repository ") || needs.repository === undefined) return true; + const other = [...reported].find((actual) => { + const [from, file] = split(actual); + return file === path && from !== needs.repository && !named.has(from) && !spent.has(actual); + }); + if (other === undefined) return true; + spent.add(other); + return false; + }); } /** diff --git a/test/status-fakes.ts b/test/status-fakes.ts index d2f0cc61..e567d032 100644 --- a/test/status-fakes.ts +++ b/test/status-fakes.ts @@ -153,10 +153,11 @@ export function setup( return Response.json({ message: "Resource not accessible by integration" }, { status: 403 }); return Response.json(page.rows, { headers: page.next ? { Link: `<${page.next}>; rel="next"` } : {} }); } - // Ruleset workflows name their repository by ID: 1 is this one, 2 another, 3 one the token cannot see. + // Ruleset workflows name their repository by ID: 1 is this one, 2 another, 3 and 4 ones the token cannot see. if (path.pathname === "/repositories/1") return Response.json({ full_name: "example/project" }); if (path.pathname === "/repositories/2") return Response.json({ full_name: "example/policies" }); - if (path.pathname === "/repositories/3") return Response.json({ message: "Not Found" }, { status: 404 }); + if (/^\/repositories\/[34]$/.test(path.pathname)) + return Response.json({ message: "Not Found" }, { status: 404 }); if (path.pathname === "/repos/example/project/branches/main") return options.noBase ? Response.json({ message: "Branch not found" }, { status: 404 }) diff --git a/test/status.test.ts b/test/status.test.ts index e6ed0701..611118f6 100644 --- a/test/status.test.ts +++ b/test/status.test.ts @@ -527,6 +527,16 @@ test("a required workflow from a repository the token cannot see is met by its p rules, }); expect((await pullRequestStatus(pr, policy.deps)).checks.state).toBe("success"); + // Two unseen repositories' workflows at one path need two reports; one meets only one of them. + const both = [ + { type: "workflows", parameters: { workflows: [3, 4].map((id) => ({ path: CI, repository_id: id })) } }, + ]; + const once = setup([pull({ checks: page([job("example/policies")]), reviews: page([]), threads: page([]) })], { + rules: both, + }); + expect((await pullRequestStatus(pr, once.deps)).checks.pending.map((check) => check.name)).toEqual([ + `repository 4:${CI}`, + ]); }); test("a required workflow counts as reported when another workflow's same-named job is the newer one", async () => { From 4bd62942379328550f507bf7f8d75b4f3945da2e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 01:26:23 -0800 Subject: [PATCH 08/10] fix(github): name a required workflow's unseen repository on the person's token Replaces the path-only match: a minted read token scoped to one repository cannot resolve a ruleset's cross-repository workflow by id, so the forge liveFor builds names it on the person's own token, one ETag-revalidated GET, and requirements match by exact repository again. Co-Authored-By: Claude Opus 5.5 --- src/cli/forge.ts | 6 ++++-- src/github/client.ts | 25 +++++++++++++++++++---- src/github/status.ts | 43 ++------------------------------------- test/installation.test.ts | 31 +++++++++++++++++++++++++++- test/status-fakes.ts | 4 +--- test/status.test.ts | 33 ------------------------------ 6 files changed, 58 insertions(+), 84 deletions(-) diff --git a/src/cli/forge.ts b/src/cli/forge.ts index 4d137888..14714f11 100644 --- a/src/cli/forge.ts +++ b/src/cli/forge.ts @@ -103,7 +103,9 @@ export async function forgeFor( /** * The forge that answers `repository`'s reads from GitHub itself, never an index that may lag. For a person holding a * Kixel Quest token it reads on the installation token Kixel Quest mints for the repository, and on the person's own - * where Kixel Quest does not serve it or the reads are forced onto GitHub. Minting gives up at `deadline`. + * where Kixel Quest does not serve it or the reads are forced onto GitHub. A required workflow's repository the + * installation token cannot see is named on the person's own token, one request each, revalidated by ETag. Minting + * gives up at `deadline`. */ export async function liveFor( repository: Repository, @@ -115,7 +117,7 @@ export async function liveFor( const person = reading(deps.github()); return installation === null ? new GitHubForge(person) - : new GitHubForge({ ...person, readToken: installation.token }, installation.login); + : new GitHubForge({ ...person, readToken: installation.token, names: person }, installation.login); } /** Kixel Quest refused the person's token, as a sender must tell from a failure that may pass. */ diff --git a/src/github/client.ts b/src/github/client.ts index c091ee6b..b2f8f04d 100644 --- a/src/github/client.ts +++ b/src/github/client.ts @@ -24,13 +24,19 @@ export interface GitHubReadDependencies { quota: "wait" | "fail"; /** Where GET answers are kept to revalidate by ETag, so an unchanged read costs no quota; none when absent. */ cache?: ResponseCache; + /** + * Where to read a repository's name by its id when the read token cannot see that repository, such as the person's + * own dependencies behind an installation token scoped to one repository: a ruleset names a required workflow's + * repository only by id. None when the read token is the person's. + */ + names?: GitHubReadDependencies; } /** * What a client that writes needs: the same, with the person's own token, so what it writes is in their * name. It has no `readToken`, so it never stands in for read dependencies built on another token. */ -export interface GitHubDependencies extends Omit { +export interface GitHubDependencies extends Omit { token: string; } @@ -149,6 +155,18 @@ export class GitHubReader { this.cache = deps.cache; } + /** + * The `owner/name` of the repository with `id`, read on {@link GitHubReadDependencies.names} when the read token + * cannot see it; null when neither can. + */ + async repositoryName(id: number): Promise { + for (const github of [this, ...(this.deps.names ? [new GitHubReader(this.deps.names, this.deadline)] : [])]) { + const response = await github.request(`/repositories/${id}`, { allow: [404] }); + if (response.ok) return string(object(await response.json()).full_name); + } + return null; + } + /** * A cache operation's result, or undefined once it fails: the cache only saves quota, so a full * or unwritable disk warns once and leaves the client reading GitHub uncached. @@ -572,9 +590,8 @@ async function requiredWorkflows(github: GitHubReader, rules: ObjectValue[]): Pr .flatMap((rule) => array(object(rule.parameters).workflows))) { const id = Number(row.repository_id); if (!names.has(id)) { - const response = await github.request(`/repositories/${id}`, { allow: [404] }); - // A repository the token cannot see is still required, by its id; `unreported` matches it by path alone. - names.set(id, response.ok ? string(object(await response.json()).full_name) : `repository ${id}`); + // A repository no token can see is still required; nothing on the head can match its name. + names.set(id, (await github.repositoryName(id)) ?? `repository ${id}`); } keys.push(workflowKey(names.get(id)!, string(row.path))); } diff --git a/src/github/status.ts b/src/github/status.ts index b0396a88..87790ce6 100644 --- a/src/github/status.ts +++ b/src/github/status.ts @@ -299,22 +299,12 @@ export interface Needs { checks: { name: string; app: number | null }[]; /** Workflow files that must pass as a whole, from {@link workflowKey}. */ workflows: string[]; - /** - * The lowercase `owner/repo` whose base this is. A required workflow keyed `repository `, from a repository - * the token cannot see, such as an installation token scoped to this one, is met by a workflow at its path from - * another repository, as {@link unmetWorkflows} matches it; without it, such a workflow is never met. - */ - repository?: string; } /** What `branch` requires of a PR head. The gate's own check is never on one, so it is left out. */ export async function requiredOf(github: GitHubReader, repository: Repository, branch: string): Promise { const found = await requirements(github, repository, branch); - return { - checks: found.checks.filter((check) => check.name !== LAND_CHECK), - workflows: found.workflows, - repository: `${repository.owner}/${repository.repo}`.toLowerCase(), - }; + return { checks: found.checks.filter((check) => check.name !== LAND_CHECK), workflows: found.workflows }; } /** A check as a requirement matches it: its name, its app, and the workflow file a GitHub Actions job runs in. */ @@ -349,39 +339,10 @@ export function unreported(found: Reported[], needs: Needs): string[] { !found.some((entry) => entry.name === need.name && (need.app === null || entry.app === need.app)), ) .map((need) => (need.app === null ? need.name : `${need.name} (from app ${need.app})`)), - ...unmetWorkflows(found, needs), + ...needs.workflows.filter((key) => !found.some((entry) => entry.workflow === key)), ]; } -/** A workflow key's repository and path. */ -function split(key: string): [string, string] { - return [key.slice(0, key.indexOf(":")), key.slice(key.indexOf(":") + 1)]; -} - -/** - * The required workflows nothing reports. One named by its repository is met by that repository's workflow at its - * path. One keyed `repository `, whose repository the token cannot see, is met by a workflow at its path from a - * repository other than the base's and every named one, each such repository meeting one requirement at most, so two - * unseen repositories' workflows at one path need two reports. - */ -function unmetWorkflows(found: Reported[], needs: Needs): string[] { - const reported = new Set(found.flatMap((entry) => (entry.workflow ? [entry.workflow] : []))); - const named = new Set(needs.workflows.filter((key) => !key.startsWith("repository ")).map((key) => split(key)[0])); - const spent = new Set(); - return needs.workflows.filter((key) => { - if (reported.has(key)) return false; - const [owner, path] = split(key); - if (!owner.startsWith("repository ") || needs.repository === undefined) return true; - const other = [...reported].find((actual) => { - const [from, file] = split(actual); - return file === path && from !== needs.repository && !named.has(from) && !spent.has(actual); - }); - if (other === undefined) return true; - spent.add(other); - return false; - }); -} - /** * The PR's state from its pages. `current` holds the head's checks that count, from {@link currentChecks}; a * check is required when the base requires it or its workflow, and a requirement nothing reports is pending. diff --git a/test/installation.test.ts b/test/installation.test.ts index 77e36d25..6e20fa2a 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -11,7 +11,13 @@ import { type ForgeDependencies, liveFor } from "../src/cli/forge"; import { HOLD, REUSE_MARGIN, exclusive, installationDirectory } from "../src/cli/installation"; import { waitForActivity } from "../src/cli/wait"; import { GitHubWrites } from "../src/cli/writes"; -import { GitHub, type GitHubDependencies, GitHubReader, reading } from "../src/github/client"; +import { + GitHub, + type GitHubDependencies, + type GitHubReadDependencies, + GitHubReader, + reading, +} from "../src/github/client"; import * as wait from "./wait-fakes"; const KIXEL = "https://kixel.test"; @@ -110,6 +116,29 @@ describe("reads on a minted installation token", () => { expect(w.github).toEqual([]); }); + test("a required workflow's repository the minted token cannot see is named on the person's token", async () => { + const w = world({ + github: async (_input, init) => { + const token = new Headers(init?.headers).get("authorization"); + return token === `Bearer ${PERSON}` + ? Response.json({ full_name: "example/policies" }) + : Response.json({ message: "Not Found" }, { status: 404 }); + }, + }); + const forge = await liveFor(repository, w.deps); + // The forge's own dependencies, as its status read builds its reader from them. + const deps = (forge as unknown as { deps: GitHubReadDependencies }).deps; + expect(await new GitHubReader(deps).repositoryName(2)).toBe("example/policies"); + expect(w.github).toEqual([ + { method: "GET", path: "/repositories/2", token: "minted-1" }, + { method: "GET", path: "/repositories/2", token: PERSON }, + ]); + // Without a token to fall back on, a repository the read token cannot see has no name. + w.github.length = 0; + expect(await new GitHubReader({ ...deps, names: undefined }).repositoryName(2)).toBeNull(); + expect(w.github.map((request) => request.token)).toEqual(["minted-1"]); + }); + test("a host whose members are a class's methods keeps them as read dependencies", async () => { const w = world(); const person = w.person(); diff --git a/test/status-fakes.ts b/test/status-fakes.ts index e567d032..8c2b924d 100644 --- a/test/status-fakes.ts +++ b/test/status-fakes.ts @@ -153,11 +153,9 @@ export function setup( return Response.json({ message: "Resource not accessible by integration" }, { status: 403 }); return Response.json(page.rows, { headers: page.next ? { Link: `<${page.next}>; rel="next"` } : {} }); } - // Ruleset workflows name their repository by ID: 1 is this one, 2 another, 3 and 4 ones the token cannot see. + // Ruleset workflows name their repository by ID: 1 is this one, 2 another. if (path.pathname === "/repositories/1") return Response.json({ full_name: "example/project" }); if (path.pathname === "/repositories/2") return Response.json({ full_name: "example/policies" }); - if (/^\/repositories\/[34]$/.test(path.pathname)) - return Response.json({ message: "Not Found" }, { status: 404 }); if (path.pathname === "/repos/example/project/branches/main") return options.noBase ? Response.json({ message: "Branch not found" }, { status: 404 }) diff --git a/test/status.test.ts b/test/status.test.ts index 611118f6..dbb394cc 100644 --- a/test/status.test.ts +++ b/test/status.test.ts @@ -506,39 +506,6 @@ test("a required workflow matches its repository as well as its path", async () expect(status.checks.pending.map((check) => check.name)).toEqual([`example/policies:${CI}`]); }); -test("a required workflow from a repository the token cannot see is met by its path from another repository", async () => { - const job = (repositoryName: string) => ({ - ...run("build", "COMPLETED", "SUCCESS", false), - databaseId: 1, - checkSuite: { - databaseId: 10, - app: { databaseId: 15368 }, - workflowRun: { file: { path: CI, repositoryName } }, - }, - }); - // Repository 3 answers 404, as an installation token scoped to example/project answers for example/policies. - const rules = [{ type: "workflows", parameters: { workflows: [{ path: CI, repository_id: 3 }] } }]; - const local = setup([pull({ checks: page([job("example/project")]), reviews: page([]), threads: page([]) })], { - rules, - }); - const unmet = await pullRequestStatus(pr, local.deps); - expect(unmet.checks.pending.map((check) => check.name)).toEqual([`repository 3:${CI}`]); - const policy = setup([pull({ checks: page([job("example/policies")]), reviews: page([]), threads: page([]) })], { - rules, - }); - expect((await pullRequestStatus(pr, policy.deps)).checks.state).toBe("success"); - // Two unseen repositories' workflows at one path need two reports; one meets only one of them. - const both = [ - { type: "workflows", parameters: { workflows: [3, 4].map((id) => ({ path: CI, repository_id: id })) } }, - ]; - const once = setup([pull({ checks: page([job("example/policies")]), reviews: page([]), threads: page([]) })], { - rules: both, - }); - expect((await pullRequestStatus(pr, once.deps)).checks.pending.map((check) => check.name)).toEqual([ - `repository 4:${CI}`, - ]); -}); - test("a required workflow counts as reported when another workflow's same-named job is the newer one", async () => { const build = (databaseId: number, path: string) => ({ ...run("build", "COMPLETED", "SUCCESS", false), From 89249502d42a349d20e5d166a025324da6fb14b7 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 01:34:39 -0800 Subject: [PATCH 09/10] fix(github): treat any document naming mutation as one GraphQL ignores commas, so a mutation can follow one past a prefix test. A read client refuses, and the write client never blindly repeats, any document holding the word. Co-Authored-By: Claude Opus 5.5 --- src/github/client.ts | 9 +++++---- test/installation.test.ts | 1 + 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/github/client.ts b/src/github/client.ts index b2f8f04d..83a6ac80 100644 --- a/src/github/client.ts +++ b/src/github/client.ts @@ -58,11 +58,12 @@ export function reading(deps: GitHubDependencies): GitHubReadDependencies { } /** - * Whether a GraphQL document defines a mutation: one starting the document, or following a fragment's closing brace, - * once comments are gone. It errs toward refusing, since a read-only client never needs to send one. + * Whether a GraphQL document may define a mutation: whether it holds the word anywhere, since GraphQL lets one + * follow a comment, a comma, or a fragment. It errs toward a mutation, which is never repeated blindly and which a + * read-only client refuses, since no read needs the word. */ function mutates(query: string): boolean { - return /(^|\})\s*mutation\b/.test(query.replace(/#[^\n]*/g, "")); + return /\bmutation\b/.test(query); } /** A 200 answer to a GET, kept to serve when GitHub answers its ETag with a 304. */ @@ -474,7 +475,7 @@ export class GitHub extends GitHubReader { * GitHub's refusal for the caller. */ private mutationRepeat(query: string, variables: ObjectValue): Repeat { - if (!/^\s*mutation\b/.test(query)) return true; + if (!mutates(query)) return true; const call = /^\s*mutation\b[^{]*\{\s*(\w+)\s*\(\s*input:\s*\{\s*pullRequestId:\s*\$(\w+)\b/.exec(query); const effect = call && Object.hasOwn(PULL_MUTATIONS, call[1]) ? PULL_MUTATIONS[call[1]] : undefined; const id = call && variables[call[2]]; diff --git a/test/installation.test.ts b/test/installation.test.ts index 6e20fa2a..7a8d5a34 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -110,6 +110,7 @@ describe("reads on a minted installation token", () => { void forge; await expect(reader.graphql("mutation { x }", {})).rejects.toThrow("cannot run a mutation"); await expect(reader.graphql("# note\nmutation { x }", {})).rejects.toThrow("cannot run a mutation"); + await expect(reader.graphql(",mutation { x }", {})).rejects.toThrow("cannot run a mutation"); await expect(reader.graphql("fragment f on X { y }\nmutation { x { ...f } }", {})).rejects.toThrow( "cannot run a mutation", ); From 77765f677352454a60f55b36383772ab4df7631b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 19 Nov 2026 01:36:45 -0800 Subject: [PATCH 10/10] fix(github): find a mutation by lexing the document, not by the word Skips comments, strings, and block strings, and counts mutation only as a name outside every brace and parenthesis, so a read whose string, alias, or variable holds the word still runs. Co-Authored-By: Claude Opus 5.5 --- src/github/client.ts | 26 +++++++++++++++++++++----- test/installation.test.ts | 8 ++++++++ 2 files changed, 29 insertions(+), 5 deletions(-) diff --git a/src/github/client.ts b/src/github/client.ts index 83a6ac80..a1d56e59 100644 --- a/src/github/client.ts +++ b/src/github/client.ts @@ -57,13 +57,29 @@ export function reading(deps: GitHubDependencies): GitHubReadDependencies { }; } +/** A comment, block string, string, or name, possibly a variable's, at the start of a GraphQL document's rest. */ +const TOKEN = /^(?:#[^\n\r]*|"""(?:\\"""|[^])*?"""|"(?:\\.|[^"\\\n\r])*"|\$?[_A-Za-z][_0-9A-Za-z]*)/; + /** - * Whether a GraphQL document may define a mutation: whether it holds the word anywhere, since GraphQL lets one - * follow a comment, a comma, or a fragment. It errs toward a mutation, which is never repeated blindly and which a - * read-only client refuses, since no read needs the word. + * Whether a GraphQL document may define a mutation: whether `mutation` is a name outside every brace and parenthesis, + * skipping comments and strings, since GraphQL lets an operation follow a comment, a comma, or a fragment. It errs + * toward a mutation, as for a fragment or operation named `mutation`, which is never repeated blindly and which a + * read-only client refuses. */ -function mutates(query: string): boolean { - return /\bmutation\b/.test(query); +export function mutates(query: string): boolean { + let depth = 0; + for (let i = 0; i < query.length;) { + const token = TOKEN.exec(query.slice(i)); + if (token) { + if (depth === 0 && token[0] === "mutation") return true; + i += token[0].length; + continue; + } + const char = query[i++]; + if (char === "{" || char === "(") depth++; + else if ((char === "}" || char === ")") && depth > 0) depth--; + } + return false; } /** A 200 answer to a GET, kept to serve when GitHub answers its ETag with a 304. */ diff --git a/test/installation.test.ts b/test/installation.test.ts index 7a8d5a34..a661f1ee 100644 --- a/test/installation.test.ts +++ b/test/installation.test.ts @@ -16,6 +16,7 @@ import { type GitHubDependencies, type GitHubReadDependencies, GitHubReader, + mutates, reading, } from "../src/github/client"; import * as wait from "./wait-fakes"; @@ -111,6 +112,13 @@ describe("reads on a minted installation token", () => { await expect(reader.graphql("mutation { x }", {})).rejects.toThrow("cannot run a mutation"); await expect(reader.graphql("# note\nmutation { x }", {})).rejects.toThrow("cannot run a mutation"); await expect(reader.graphql(",mutation { x }", {})).rejects.toThrow("cannot run a mutation"); + // The word in a string, a block string, a comment, an alias, or a variable is no mutation. + for (const query of [ + 'query { search(query: "mutation } mutation") { x } }', + 'query { search(query: """a \\""" } mutation""") { x } } # mutation', + "query($mutation: String) { mutation: search(query: $mutation) { x } }", + ]) + expect(mutates(query)).toBe(false); await expect(reader.graphql("fragment f on X { y }\nmutation { x { ...f } }", {})).rejects.toThrow( "cannot run a mutation", );