co-maintainer 0.5.0 → 0.5.1-beta.2

package/dist/src/cli/review_github.js

@@ -0,0 +1,128 @@
+/** `review --output=github`.
+ *
+ * Findings become GitHub workflow commands (`::error` and `::warning`) so a
+ * pull request shows them as annotations, and a markdown table goes to the job
+ * summary. This file is pure apart from `appendStepSummary`.
+ *
+ * A finding's text comes from a model reading an untrusted pull request, so it
+ * is never printed raw: the runner reads a workflow command from any line that
+ * starts with `::`, and a body that carried such a line could mask a secret or
+ * end the step's commands. Every finding is one escaped line, and nothing else
+ * from the review is printed to stdout in this mode. */
+import { appendFileSync } from "node:fs";
+import { formatRunSummary } from "../util/run_summary.js";
+import { humanShortTitle, sortHumanFindings, } from "./review_result.js";
+/** GitHub shows at most this many error and this many warning annotations per
+ * step and drops the rest without a word. */
+export const MAX_ANNOTATIONS_PER_LEVEL = 10;
+/** The message part of a workflow command. GitHub's own toolkit escapes exactly
+ * these three, and a `:` or `,` here would show as `%3A` and `%2C` in the text. */
+export function escapeData(value) {
+    return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+/** A property value (`file`, `title`) also cannot hold `:` or `,`, which end it. */
+export function escapeProperty(value) {
+    return escapeData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function annotation(row) {
+    const properties = [];
+    if (row.path) {
+        properties.push(`file=${escapeProperty(row.path)}`);
+        const from = row.lineFrom ?? 0;
+        if (from > 0) {
+            properties.push(`line=${from}`);
+            const to = row.lineTo ?? from;
+            if (to > from)
+                properties.push(`endLine=${to}`);
+        }
+    }
+    const short = humanShortTitle(row);
+    properties.push(`title=${escapeProperty(short ? `${row.severity}: ${short}` : `${row.severity} finding`)}`);
+    const level = row.blocking ? "error" : "warning";
+    return `::${level} ${properties.join(",")}::${escapeData(row.body || row.title)}`;
+}
+function active(findings) {
+    return sortHumanFindings(findings).filter((row) => row.state !== "closed");
+}
+/** One workflow command per finding still standing, errors first. A finding
+ * that was closed since the last review needs no annotation. */
+export function githubAnnotations(findings) {
+    const rows = active(findings);
+    const errors = rows.filter((row) => row.blocking);
+    const warnings = rows.filter((row) => !row.blocking);
+    const shown = [
+        ...errors.slice(0, MAX_ANNOTATIONS_PER_LEVEL),
+        ...warnings.slice(0, MAX_ANNOTATIONS_PER_LEVEL),
+    ];
+    const lines = shown.map(annotation);
+    const left = rows.length - shown.length;
+    if (left > 0) {
+        lines.push(`::notice title=co-maintainer::${escapeData(`${left} more ${left === 1 ? "finding is" : "findings are"} not annotated, GitHub shows ${MAX_ANNOTATIONS_PER_LEVEL} errors and ${MAX_ANNOTATIONS_PER_LEVEL} warnings per step. The job summary lists all of them.`)}`);
+    }
+    return lines;
+}
+/** Markdown for a table cell: nothing the model wrote can become a link, an
+ * image, a tag or an extra column. */
+function cell(value, limit = 300) {
+    const flat = value.replace(/\s+/g, " ").trim();
+    const cut = flat.length > limit ? `${flat.slice(0, limit - 1)}…` : flat;
+    return cut.replace(/[\\`*_{}[\]<>|]/g, "\\$&");
+}
+function where(row) {
+    if (!row.path)
+        return "";
+    const from = row.lineFrom ?? 0;
+    const to = row.lineTo ?? from;
+    const span = from <= 0 ? "" : from === to ? `:${from}` : `:${from}-${to}`;
+    return cell(`${row.path}${span}`, 120);
+}
+export function githubSummary(input) {
+    const rows = active(input.findings);
+    const closed = input.findings.filter((row) => row.state === "closed").length;
+    const blocking = rows.filter((row) => row.blocking).length;
+    const lines = ["## co-maintainer review", "", cell(input.title, 200), ""];
+    if (rows.length === 0) {
+        lines.push("No actionable findings.");
+    }
+    else {
+        lines.push("| Severity | State | Where | Finding |", "|---|---|---|---|");
+        for (const row of rows) {
+            const short = humanShortTitle(row);
+            const text = [short, row.body.split("\n")[0] ?? ""]
+                .filter(Boolean)
+                .join(": ");
+            lines.push(`| ${cell(row.severity, 10)}${row.blocking ? " (blocking)" : ""} | ${row.state} | ${where(row)} | ${cell(text || row.title)} |`);
+        }
+    }
+    lines.push("", `**Summary:** ${rows.filter((r) => r.state === "new").length} new · ${rows.filter((r) => r.state === "open").length} open · ${closed} closed · ${blocking} blocking`);
+    if (input.run)
+        lines.push("", formatRunSummary(input.run));
+    return lines.join("\n");
+}
+/** Appends to `$GITHUB_STEP_SUMMARY` when it is set. A summary that cannot be
+ * written is reported on stderr and never fails the review. */
+export function appendStepSummary(markdown, path = process.env.GITHUB_STEP_SUMMARY) {
+    if (!path)
+        return;
+    try {
+        appendFileSync(path, `${markdown}\n`);
+    }
+    catch (error) {
+        console.error(`Could not write the job summary: ${String(error)}`);
+    }
+}
+/** The whole `--output=github` output of one finished review. */
+export function emitGithubOutput(input) {
+    for (const line of githubAnnotations(input.findings))
+        console.log(line);
+    appendStepSummary(githubSummary(input));
+}
+/** Progress lines that come from somewhere else (the server's job log) are
+ * printed on stderr, and the runner reads workflow commands from stderr too.
+ * A line that would start one is given a prefix so it stays plain text. */
+export function neutralizeCommands(text) {
+    return text
+        .split("\n")
+        .map((line) => (line.trimStart().startsWith("::") ? `[log] ${line}` : line))
+        .join("\n");
+}

package/dist/src/cli/review_result.d.ts

@@ -2,6 +2,7 @@ import { type ParsedFinding } from "../pr/findings.ts";
 import { type ResolvedFinding } from "../review/carry_over.ts";
 import { type ReviewBlocking } from "../review/blocking.ts";
 import type { Revision } from "../review/revision.ts";
+import type { BilledTo, CostReason, CostStatus } from "../util/cost.ts";
 export type ReviewWarning = {
     code: string;
     message: string;
@@ -44,7 +45,7 @@ export declare function summaryCounts(findings: ResolvedFinding[], mode?: Review
 export declare function reviewExitCodeFromResolved(findings: ResolvedFinding[], mode?: ReviewBlocking): number;
 /** One finding as the human renderer prints it. Local, PR and remote reviews
  * all normalize into this shape before printing, so the three modes cannot
- * drift into different products (CORE-43 / F21, F22). */
+ * drift into different products. */
 export type HumanFinding = {
     state: "new" | "open" | "closed";
     severity: string;
@@ -61,12 +62,20 @@ export type HumanFinding = {
     } | null;
 };
 /** Local and PR findings: blocking is decided here from the configured rule,
- * exactly as the exit code decides it (CORE-41). */
+ * exactly as the exit code decides it. */
 export declare function humanFindingsFromResolved(findings: ResolvedFinding[], mode?: ReviewBlocking): HumanFinding[];
 /** Remote findings already carry the server's blocking decision, so the label
  * uses that field rather than re-deriving the rule on a client that may not
- * share the server's config (CORE-41). */
+ * share the server's config. */
 export declare function humanFindingsFromJson(findings: JsonReviewFinding[]): HumanFinding[];
+/** The finding heading, as the shared header prints it. A parsed heading is
+ * `[P2 · non-blocking] \`path\`: \`symbol\``. The label and the location are
+ * already printed beside it, so only the symbol survives. An older heading
+ * that used an em dash is still accepted, so comments posted before 0.5.0
+ * stay readable. A heading with no symbol leaves nothing: printing the label
+ * or the path again would repeat what the line already says. */
+export declare function humanShortTitle(row: HumanFinding): string;
+export declare function sortHumanFindings(rows: HumanFinding[]): HumanFinding[];
 export type HumanReviewInput = {
     /** Header line: repo, subject and mode. */
     title: string;
@@ -74,13 +83,13 @@ export type HumanReviewInput = {
     stats?: string;
     guideBuiltAt: string | null;
     /** `null` when the run cannot say (a server older than 0.5.0 sends no
-     * codegraph block). A wrong "used" is what F23 was about, so unknown is
+     * codegraph block). A wrong "used" is misleading, so unknown is
      * reported as unknown rather than guessed. */
     codegraphState: "used" | "disabled" | "unavailable" | null;
     findings: HumanFinding[];
     warnings?: ReviewWarning[];
 };
-/** The single human-readable review format (CORE-43 / F21, F22, F23). Local,
+/** The single human-readable review format. Local,
  * PR and remote reviews print this: a header naming the guide build date and
  * the codegraph state, the findings grouped by state, then one summary line.
  *
@@ -90,11 +99,21 @@ export type HumanReviewInput = {
 export declare function formatHumanReview(input: HumanReviewInput): string;
 /** Local review output: the shared format plus the working-tree file stats. */
 export declare function formatHumanLocalReview(header: string, revision: Revision, guideBuiltAt: string | null, codegraphState: "used" | "disabled" | "unavailable", findings: ResolvedFinding[], warnings: ReviewWarning[], mode?: ReviewBlocking): string;
-/** The exit code for a remote review (CORE-41). The server already decided
+/** The exit code for a remote review. The server already decided
  * each finding's `blocking` under its own configured rule, so the client
  * trusts that field instead of re-deriving the rule from a title: the client
  * may not even have the same config as the server. */
 export declare function reviewExitCodeFromJsonFindings(findings: JsonReviewFinding[]): number;
+/** `costUsd` is `null` when the cost is unknown, and `costStatus` and
+ * `costNote` say why. */
+export type ReviewUsage = {
+    tokensIn: number;
+    tokensOut: number;
+    costUsd: number | null;
+    costStatus?: CostStatus;
+    costNote?: CostReason | null;
+    billedTo?: BilledTo;
+};
 export type LocalReviewJsonInput = {
     repo: string;
     branch: string;
@@ -105,11 +124,7 @@ export type LocalReviewJsonInput = {
     codegraphReason: string | null;
     findings: ResolvedFinding[];
     warnings: ReviewWarning[];
-    usage: {
-        tokensIn: number;
-        tokensOut: number;
-        costUsd: number | null;
-    };
+    usage: ReviewUsage;
     durationMs: number;
     reviewBlocking?: ReviewBlocking;
 };
@@ -120,11 +135,7 @@ export type PrReviewJsonInput = {
     guideBuiltAt: string | null;
     codegraphState: "used" | "disabled" | "unavailable";
     codegraphReason: string | null;
-    usage: {
-        tokensIn: number;
-        tokensOut: number;
-        costUsd: number | null;
-    };
+    usage: ReviewUsage;
     durationMs: number;
     reviewBlocking?: ReviewBlocking;
 };

package/dist/src/cli/review_result.js

@@ -106,7 +106,7 @@ export function reviewExitCodeFromResolved(findings, mode = DEFAULT_REVIEW_BLOCK
     return summaryCounts(findings, mode).blocking > 0 ? 1 : 0;
 }
 /** Local and PR findings: blocking is decided here from the configured rule,
- * exactly as the exit code decides it (CORE-41). */
+ * exactly as the exit code decides it. */
 export function humanFindingsFromResolved(findings, mode = DEFAULT_REVIEW_BLOCKING) {
     return findings.map((row) => {
         const suggestion = readSuggestion(row.bodyMd);
@@ -131,7 +131,7 @@ export function humanFindingsFromResolved(findings, mode = DEFAULT_REVIEW_BLOCKI
 }
 /** Remote findings already carry the server's blocking decision, so the label
  * uses that field rather than re-deriving the rule on a client that may not
- * share the server's config (CORE-41). */
+ * share the server's config. */
 export function humanFindingsFromJson(findings) {
     return findings.map((row) => ({
         state: row.state,
@@ -158,8 +158,8 @@ function humanLocation(row) {
  * already printed beside it, so only the symbol survives. An older heading
  * that used an em dash is still accepted, so comments posted before 0.5.0
  * stay readable. A heading with no symbol leaves nothing: printing the label
- * or the path again would repeat what the line already says (CORE-43). */
-function humanShortTitle(row) {
+ * or the path again would repeat what the line already says. */
+export function humanShortTitle(row) {
     const withoutLabel = row.title.replace(/^\[P\d\s*·\s*[^\]]*\]\s*/, "");
     const dash = withoutLabel.indexOf(" — ");
     const tail = dash === -1 ? withoutLabel : withoutLabel.slice(dash + 3);
@@ -168,7 +168,7 @@ function humanShortTitle(row) {
     const clean = symbol.replace(/^`|`$/g, "").trim();
     return clean === "" || clean === row.path ? "" : clean;
 }
-function sortHumanFindings(rows) {
+export function sortHumanFindings(rows) {
     const stateOrder = { new: 0, open: 1, closed: 2 };
     return [...rows].sort((a, b) => {
         const ds = stateOrder[a.state] - stateOrder[b.state];
@@ -185,7 +185,7 @@ function sortHumanFindings(rows) {
         return (a.lineFrom ?? 0) - (b.lineFrom ?? 0);
     });
 }
-/** The single human-readable review format (CORE-43 / F21, F22, F23). Local,
+/** The single human-readable review format. Local,
  * PR and remote reviews print this: a header naming the guide build date and
  * the codegraph state, the findings grouped by state, then one summary line.
  *
@@ -271,7 +271,7 @@ export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraph
         warnings,
     });
 }
-/** The exit code for a remote review (CORE-41). The server already decided
+/** The exit code for a remote review. The server already decided
  * each finding's `blocking` under its own configured rule, so the client
  * trusts that field instead of re-deriving the rule from a title: the client
  * may not even have the same config as the server. */

package/dist/src/config.d.ts

@@ -5,7 +5,7 @@ import { type Platform } from "./util/runtime.ts";
  * flags and no interactive prompts, reusing what `init` was told. */
 export type RepoConfig = {
     auth?: "gh" | "pat";
-    ai?: "none" | "openrouter" | "hetzner";
+    ai?: "none" | "openrouter" | "openai" | "anthropic" | "opencode-zen" | "opencode-go";
     lowModel?: string;
     highModel?: string;
     maxCommits?: number;
@@ -24,7 +24,7 @@ export type RepoConfig = {
 };
 export type UserConfig = {
     auth?: "gh" | "pat";
-    ai?: "none" | "openrouter" | "hetzner";
+    ai?: "none" | "openrouter" | "openai" | "anthropic" | "opencode-zen" | "opencode-go";
     lowModel?: string;
     highModel?: string;
     /** Written only by `co-maintainer set --token=...`. Every other write
@@ -61,22 +61,44 @@ export type UserConfig = {
     };
     /** Cap on jobs running at once across all types. Unset means no limit. */
     maxConcurrentJobs?: number;
-    /** What a review uses to decide a blocking finding (CORE-41). `model` lets
+    /** What a review uses to decide a blocking finding. `model` lets
      * the model's own severity decide, `severity` uses a fixed threshold. */
     reviewBlocking?: "model" | "severity";
     /** Remote review CLI target (`co-maintainer set`). */
     remoteHost?: string;
     /** Bearer token for `/api/remote/*`; only written by `set`. */
     remoteToken?: string;
-    /** Hosts for which the unpublished-code notice was shown (plan §14.1 G13). */
+    /** Hosts for which the unpublished-code notice was shown. */
     remoteNoticeShownFor?: string[];
-    /** Remote client watchdog timeout; dashboard may override (plan §19.6). */
+    /** Remote client watchdog timeout; dashboard may override. */
     remoteSyncTimeoutSeconds?: number;
     maxConcurrentRemoteReviewsPerToken?: number;
     remoteToolOutputMaxChars?: number;
+    /** Whether remote clients may bring their own AI key. `off`
+     * rejects one, `allow` accepts one and falls back to the server key when
+     * absent, `require` refuses a review that does not carry one. The
+     * `CM_REMOTE_BYOK_POLICY` env var overrides this, which is how a hosted
+     * deployment forces the setting. */
+    remoteByokPolicy?: ByokPolicy;
+    /** The review policy new repositories start with: a template
+     * name or a policy object. Unset means the old per repository switches. */
+    reviewPolicy?: string | Record<string, unknown>;
+    /** The client's own AI key for remote review, sent only when
+     * `--remote-byok` (or `remoteByokDefault`) turns it on for a run. Only
+     * ever written by `set`. */
+    remoteByok?: string;
+    /** Whether `co-maintainer review --remote` sends `remoteByok` by default.
+     * `--no-remote-byok` turns it off for one run without unsetting this. */
+    remoteByokDefault?: boolean;
     repos?: Record<string, RepoConfig>;
 };
-/** Platform/env injection keeps the OS branches testable (plan §0b): the
+export type ByokPolicy = "off" | "allow" | "require";
+/** Who pays for a remote review's AI calls. `CM_REMOTE_BYOK_POLICY`
+ * overrides the saved config, so a hosted server cannot be talked out of its
+ * policy by a config edit. An unset or unreadable value falls back to the
+ * config, then to `off`. */
+export declare function remoteByokPolicy(config?: Pick<UserConfig, "remoteByokPolicy">): ByokPolicy;
+/** Platform/env injection keeps the OS branches testable: the
  * migration's `"windows"` vs `"win32"` trap is invisible otherwise. */
 export declare function getConfigDir(os?: Platform, env?: (name: string) => string | undefined): string;
 export declare function getCacheDir(os?: Platform, env?: (name: string) => string | undefined): string;

package/dist/src/config.js

@@ -1,11 +1,25 @@
 import { chmod, currentPlatform, getEnv, isNotFound, mkdir, readTextFileSync, setEnv, writeTextFile, } from "./util/runtime.js";
+/** Who pays for a remote review's AI calls. `CM_REMOTE_BYOK_POLICY`
+ * overrides the saved config, so a hosted server cannot be talked out of its
+ * policy by a config edit. An unset or unreadable value falls back to the
+ * config, then to `off`. */
+export function remoteByokPolicy(config = readConfig()) {
+    // An env value that is not one of the three known policies is treated as
+    // unreadable and falls back to the config, so a typo cannot silently turn a
+    // configured `require` into `off`. An explicit `off` still overrides.
+    const env = getEnv("CM_REMOTE_BYOK_POLICY");
+    const raw = env === "off" || env === "allow" || env === "require"
+        ? env
+        : config.remoteByokPolicy;
+    return raw === "allow" || raw === "require" ? raw : "off";
+}
 function homeDir(env) {
     const home = env("HOME") ?? env("USERPROFILE");
     if (!home)
         throw new Error("Could not determine the home directory");
     return home;
 }
-/** Platform/env injection keeps the OS branches testable (plan §0b): the
+/** Platform/env injection keeps the OS branches testable: the
  * migration's `"windows"` vs `"win32"` trap is invisible otherwise. */
 export function getConfigDir(os = currentPlatform(), env = getEnv) {
     const home = homeDir(env);

package/dist/src/git/default_branch.d.ts

@@ -1,5 +1,5 @@
 import type { Run } from "../pr/checkout.ts";
-/** `refs/remotes/<remote>/…` for scope and PR algorithms (plan §10.5). */
+/** `refs/remotes/<remote>/…` for scope and PR algorithms. */
 export declare function detectDefaultBranchRef(cwd: string, remote: string, run: Run): Promise<string | undefined>;
 /** Short branch name (`main`) for `refs/remotes/<remote>/<branch>`. */
 export declare function resolveDefaultBranchName(cwd: string, remote: string, run: Run): Promise<string | undefined>;

package/dist/src/git/default_branch.js

@@ -1,4 +1,4 @@
-/** `refs/remotes/<remote>/…` for scope and PR algorithms (plan §10.5). */
+/** `refs/remotes/<remote>/…` for scope and PR algorithms. */
 export async function detectDefaultBranchRef(cwd, remote, run) {
     const symref = await run("git", ["symbolic-ref", "-q", `refs/remotes/${remote}/HEAD`], cwd);
     if (symref.code === 0 && symref.stdout.trim()) {

package/dist/src/github/app.js

@@ -1,4 +1,4 @@
-import { githubFetch, GitHubHttpError, paginate } from "./client.js";
+import { githubFetch, httpError, paginate } from "./client.js";
 import { importAppPrivateKey, signAppJwt } from "./jwt.js";
 const API = "https://api.github.com";
 function headers(token) {
@@ -14,7 +14,7 @@ async function call(endpoint, token, init = {}) {
         headers: { ...headers(token), ...(init.headers ?? {}) },
     });
     if (!response.ok) {
-        throw new GitHubHttpError(response.status, await response.text());
+        throw await httpError(response, init.method ?? "GET", endpoint, "App");
     }
     if (response.status === 204)
         return undefined;

package/dist/src/github/app_manifest.d.ts

@@ -1,10 +1,4 @@
-export declare const APP_MANIFEST_PERMISSIONS: {
-    readonly contents: "read";
-    readonly issues: "write";
-    readonly pull_requests: "write";
-    readonly checks: "write";
-    readonly metadata: "read";
-};
+export declare const APP_MANIFEST_PERMISSIONS: Record<string, import("./permissions.ts").Level>;
 export declare const APP_MANIFEST_EVENTS: readonly ["pull_request", "pull_request_review", "pull_request_review_comment", "issue_comment"];
 /** GitHub App names are globally unique and capped at 34 characters. */
 export declare const APP_NAME_MAX = 34;

package/dist/src/github/app_manifest.js

@@ -15,14 +15,9 @@
  * GitHub delivers both to every App without a subscription, which is why
  * `webhook.ts` handles them at all. */
 import { githubFetch } from "./client.js";
+import { APP_PERMISSIONS } from "./permissions.js";
 import { webhookReachabilityProblem } from "../util/webhook_reachability.js";
-export const APP_MANIFEST_PERMISSIONS = {
-    contents: "read",
-    issues: "write",
-    pull_requests: "write",
-    checks: "write",
-    metadata: "read",
-};
+export const APP_MANIFEST_PERMISSIONS = APP_PERMISSIONS;
 export const APP_MANIFEST_EVENTS = [
     "pull_request",
     "pull_request_review",

package/dist/src/github/client.d.ts

@@ -3,8 +3,11 @@
  * not use `githubFetch`; both paths share `paginate` and `waitForRateLimit`. */
 export declare class GitHubHttpError extends Error {
     readonly status: number;
-    constructor(status: number, body: string);
+    constructor(status: number, body: string, hint?: string);
 }
+/** A failed response as an error. A 403 or 404 names the endpoint and the
+ * permission it needs, because GitHub's own body rarely says which one. */
+export declare function httpError(response: Response, method: string, endpoint: string, who: "token" | "App"): Promise<GitHubHttpError>;
 export declare function isAccessDenied(error: unknown): boolean;
 /** Primary probes wake at the reset, but at least every half hour. */
 export declare const RATE_LIMIT_PROBE_MS: number;

package/dist/src/github/client.js

@@ -3,14 +3,26 @@
  * not use `githubFetch`; both paths share `paginate` and `waitForRateLimit`. */
 import { log } from "../util/log.js";
 import { networkFailure } from "../cli/error.js";
+import { missingHint, refusalHint } from "./permissions.js";
 export class GitHubHttpError extends Error {
     status;
-    constructor(status, body) {
-        super(`GitHub API ${status}: ${body}`);
+    constructor(status, body, hint) {
+        super(`GitHub API ${status}: ${body}${hint ? ` ${hint}` : ""}`);
         this.status = status;
         this.name = "GitHubHttpError";
     }
 }
+/** A failed response as an error. A 403 or 404 names the endpoint and the
+ * permission it needs, because GitHub's own body rarely says which one. */
+export async function httpError(response, method, endpoint, who) {
+    const body = await response.text();
+    const hint = response.status === 403
+        ? refusalHint(method, endpoint, who)
+        : response.status === 404
+            ? missingHint(method, endpoint, who)
+            : undefined;
+    return new GitHubHttpError(response.status, body, hint);
+}
 export function isAccessDenied(error) {
     return (error instanceof GitHubHttpError &&
         (error.status === 403 || error.status === 404));

package/dist/src/github/gh.js

@@ -17,12 +17,12 @@ function ghSpawn() {
     return { command: bin, prefix: script ? [script] : [] };
 }
 /** Turns a failed `gh api` call into a message that says what broke, why, and
- * what to do next (CORE-12, F09/F24/F28). The four shapes the DX research hit:
+ * what to do next. The four shapes that came up in practice:
  * `gh` missing from PATH, the repo missing or unreadable, an empty stderr, and
  * everything else. The first line is the only part a human reads, so it always
  * names the situation; the raw gh text moves to the hint so it stays available
  * without drowning the message. */
-function ghFailure(endpoint, stderr) {
+function ghFailure(method, endpoint, stderr) {
     if (/ENOENT|command not found|not recognized/i.test(stderr)) {
         return new CliError("gh_not_installed", "GitHub CLI (gh) was not found.", "Install it from https://cli.github.com or use --auth=pat.", EXIT_USAGE);
     }
@@ -32,6 +32,9 @@ function ghFailure(endpoint, stderr) {
         const subject = match ? `${match[1]}/${match[2]}` : endpoint;
         return new CliError("repo_not_found", `${subject} was not found, or your GitHub account cannot read it.`, "Check the name and run gh auth status.", EXIT_USAGE);
     }
+    if (/HTTP 403/i.test(stderr)) {
+        return new CliError("github_forbidden", `GitHub refused ${method} ${endpoint}.`, `Your gh login needs the repo scope. Run gh auth refresh -s repo. gh said: ${stderr}`, EXIT_USAGE);
+    }
     // An empty stderr used to collapse to just the endpoint, which told the user
     // nothing about what happened.
     if (stderr.length === 0) {
@@ -129,7 +132,7 @@ export class GhClient {
         this.debug = debug;
     }
     request(endpoint) {
-        return this.call(endpoint, () => {
+        return this.call("GET", endpoint, () => {
             const { command, prefix } = ghSpawn();
             return commandOutput(command, {
                 args: [...prefix, "api", endpoint],
@@ -151,7 +154,7 @@ export class GhClient {
         return paginate((e) => this.request(e), endpoint, limit, progress);
     }
     send(endpoint, method, body) {
-        return this.call(endpoint, () => {
+        return this.call(method, endpoint, () => {
             const { command, prefix } = ghSpawn();
             return commandWithInput(command, {
                 args: [...prefix, "api", "-X", method, endpoint, "--input", "-"],
@@ -161,13 +164,13 @@ export class GhClient {
             }, JSON.stringify(body));
         });
     }
-    async call(endpoint, run) {
+    async call(method, endpoint, run) {
         noteGhCall(this.debug);
         const started = Date.now();
         let spun = false;
         for (;;) {
             // A missing `gh` binary rejects the spawn instead of returning a failed
-            // result, so the ENOENT case has to be caught here too (CORE-12).
+            // result, so the ENOENT case has to be caught here too.
             let result;
             try {
                 result = await run();
@@ -193,7 +196,7 @@ export class GhClient {
                 ? bucket.remaining === 0
                 : /rate limit/i.test(error);
             if (!limited)
-                throw ghFailure(endpoint, error);
+                throw ghFailure(method, endpoint, error);
             const resetAt = bucket?.resetAt ?? new Date(Date.now() + RATE_LIMIT_PROBE_MS);
             const delay = probeDelay(resetAt, Date.now());
             if (delay === 0) {

package/dist/src/github/pat.js

@@ -1,4 +1,4 @@
-import { githubFetch, GitHubHttpError, paginate } from "./client.js";
+import { githubFetch, httpError, paginate } from "./client.js";
 export class PatClient {
     token;
     constructor(token) {
@@ -15,7 +15,7 @@ export class PatClient {
             },
         });
         if (!response.ok) {
-            throw new GitHubHttpError(response.status, await response.text());
+            throw await httpError(response, "GET", endpoint, "token");
         }
         return (await response.json());
     }
@@ -31,7 +31,7 @@ export class PatClient {
             body: JSON.stringify(body),
         });
         if (!response.ok) {
-            throw new GitHubHttpError(response.status, await response.text());
+            throw await httpError(response, "POST", endpoint, "token");
         }
         return (await response.json());
     }
@@ -50,7 +50,7 @@ export class PatClient {
             body: JSON.stringify(body),
         });
         if (!response.ok) {
-            throw new GitHubHttpError(response.status, await response.text());
+            throw await httpError(response, "PATCH", endpoint, "token");
         }
         return (await response.json());
     }

package/dist/src/github/permissions.d.ts

@@ -0,0 +1,36 @@
+/** The one list of GitHub calls this codebase makes and what each needs.
+ *
+ * The App manifest, the App permission check on save, the 403 and 404 hints
+ * and the permission tables in the docs are all read from `ENDPOINTS`.
+ * `permissions.test.ts` scans the source for every endpoint it calls and fails
+ * when one is missing here, so a new call cannot ship without its permission. */
+export type Level = "read" | "write";
+export type Permission = "metadata" | "contents" | "pull_requests" | "issues" | "checks";
+/** `gh` is a signed-in GitHub CLI, `pat` a personal access token, `app` a
+ * GitHub App installation token. */
+export type Identity = "gh" | "pat" | "app";
+export type Endpoint = {
+    method: "GET" | "POST" | "PATCH";
+    /** `{repo}` is `owner/name`, `{path}` may hold slashes, any other
+     * placeholder is one path segment. */
+    pattern: string;
+    permission?: Permission;
+    level?: Level;
+    identities: readonly Identity[];
+    feature: string;
+};
+/** Key order is the order the manifest and the doc tables list them in. */
+export declare const PERMISSION_LABEL: Record<Permission, string>;
+export declare const ENDPOINTS: readonly Endpoint[];
+/** What the App must be granted, in the shape the manifest and the save-time
+ * check want. */
+export declare const APP_PERMISSIONS: Record<string, Level>;
+/** The entry for a real request such as `repos/o/r/pulls/4/files?page=2`. */
+export declare function endpointFor(method: string, endpoint: string): Endpoint | undefined;
+/** `who` is what the failing credential is called in the sentence. */
+export declare function refusalHint(method: string, endpoint: string, who: "token" | "App"): string;
+export declare function missingHint(method: string, endpoint: string, who: "token" | "App"): string;
+export type TableKind = "app" | "pat-fine" | "pat-classic" | "gh" | "oauth";
+/** A markdown table for the docs. `build_docs.ts` writes it between the
+ * `permissions:<kind>` markers and a test fails when the page is stale. */
+export declare function permissionTable(kind: TableKind): string;