pr-shepherd 0.44.0 → 0.45.0

package/bin/github/graphql-http.mjs

@@ -1,10 +1,14 @@
+/* eslint-disable max-lines */
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
+import { withGraphQlInternalRetry } from "./graphql-internal-retry.mjs";
 import { formatGraphQlErrors, parseGraphQlPayload } from "./graphql-response.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
+import { mergeGraphqlRateLimit, recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 async function graphqlInner(query, vars, opts) {
     const url = `${BASE_URL}/graphql`;
@@ -17,13 +21,26 @@ async function graphqlInner(query, vars, opts) {
         body: { query, variables: vars },
     }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
+    let authSource = "unknown";
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders();
+        authSource = auth.source;
+        return fetch(url, {
+            method: "POST",
+            headers: auth.headers,
+            body: JSON.stringify({ query, variables: vars }),
+        });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "GraphQL",
         method: "POST",
-        headers: await makeHeaders(),
-        body: JSON.stringify({ query, variables: vars }),
-    }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "GraphQL", method: "POST", url, status, durationMs })));
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
-    const rateLimit = parseRateLimit(res.headers);
+    const headerRateLimit = parseRateLimit(res.headers);
     const retryAfterSeconds = parseRetryAfter(res.headers);
     if (!res.ok) {
         const body = await res.text();
@@ -36,8 +53,22 @@ async function graphqlInner(query, vars, opts) {
             durationMs,
             textBody: redactToken(body),
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
         }));
-        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, { status: res.status, rateLimit: rateLimit ?? undefined, retryAfterSeconds });
+        recordApiTelemetry({
+            kind: "GraphQL",
+            method: "POST",
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+        });
+        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
+            status: res.status,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
+            authSource,
+        });
     }
     let parsed;
     try {
@@ -54,13 +85,27 @@ async function graphqlInner(query, vars, opts) {
             durationMs,
             textBody: `Invalid JSON response${detail}`,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({
+            kind: "GraphQL",
+            method: "POST",
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+        });
         throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
             status: res.status,
-            rateLimit: rateLimit ?? undefined,
+            rateLimit: headerRateLimit ?? undefined,
             retryAfterSeconds,
+            authSource,
         });
     }
+    const parsedData = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed["data"]
+        : undefined;
+    const rateLimit = mergeGraphqlRateLimit(headerRateLimit, parsedData);
     appendEntry(formatResponseEntry({
         n,
         kind: "GraphQL",
@@ -70,7 +115,16 @@ async function graphqlInner(query, vars, opts) {
         durationMs,
         body: parsed,
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit: rateLimit ?? undefined,
+        retryAfterSeconds,
     }));
+    recordApiTelemetry({
+        kind: "GraphQL",
+        method: "POST",
+        authSource,
+        rateLimit: rateLimit ?? undefined,
+    });
     const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);
     if (payload.data == null) {
         const detail = formatGraphQlErrors(payload.errors);
@@ -79,6 +133,7 @@ async function graphqlInner(query, vars, opts) {
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
             graphqlErrors: payload.errors,
+            authSource,
         });
     }
     if (payload.errors?.length && !opts.allowPartialData) {
@@ -87,6 +142,7 @@ async function graphqlInner(query, vars, opts) {
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
             graphqlErrors: payload.errors,
+            authSource,
         });
     }
     if (payload.errors?.length) {
@@ -96,10 +152,10 @@ async function graphqlInner(query, vars, opts) {
     return { data: payload.data, rateLimit, retryAfterSeconds, errors: payload.errors };
 }
 export async function graphql(query, vars = {}, opts = {}) {
-    const { data, errors } = await graphqlInner(query, vars, opts);
+    const { data, errors } = await withGraphQlInternalRetry(query, () => graphqlInner(query, vars, opts));
     return { data, errors };
 }
 export async function graphqlWithRateLimit(query, vars = {}, opts = {}) {
-    const { data, rateLimit, retryAfterSeconds, errors } = await graphqlInner(query, vars, opts);
+    const { data, rateLimit, retryAfterSeconds, errors } = await withGraphQlInternalRetry(query, () => graphqlInner(query, vars, opts));
     return { data, rateLimit: rateLimit ?? undefined, retryAfterSeconds, errors };
 }

package/bin/github/graphql-internal-retry.d.mts

@@ -0,0 +1,2 @@
+/** Retry GitHub GraphQL engine crashes (HTTP 200, data: null, INTERNAL) on reads. */
+export declare function withGraphQlInternalRetry<T>(document: string, run: () => Promise<T>): Promise<T>;

package/bin/github/graphql-internal-retry.mjs

@@ -0,0 +1,50 @@
+import { sleep } from "../util/sleep.mjs";
+import { GitHubRequestError, isRetryableGraphQlInternal } from "./errors.mjs";
+const GRAPHQL_INTERNAL_RETRY_DELAYS = [500, 1500];
+/** True when the root operation is a mutation. Anonymous `{...}` is a query. */
+function isGraphQlMutationDocument(document) {
+    let rest = document;
+    for (;;) {
+        rest = rest.replace(/^\s+/, "");
+        if (rest.startsWith("#")) {
+            const nl = rest.indexOf("\n");
+            rest = nl === -1 ? "" : rest.slice(nl + 1);
+            continue;
+        }
+        if (rest.startsWith('"""')) {
+            const end = rest.indexOf('"""', 3);
+            rest = end === -1 ? "" : rest.slice(end + 3);
+            continue;
+        }
+        break;
+    }
+    return /^mutation\b/i.test(rest);
+}
+function hasServerBackoff(err) {
+    if (err.retryAfterSeconds !== undefined)
+        return true;
+    return err.rateLimit !== undefined && err.rateLimit.remaining <= 0;
+}
+/** Retry GitHub GraphQL engine crashes (HTTP 200, data: null, INTERNAL) on reads. */
+export async function withGraphQlInternalRetry(document, run) {
+    let lastErr;
+    for (let attempt = 1; attempt <= GRAPHQL_INTERNAL_RETRY_DELAYS.length + 1; attempt++) {
+        try {
+            return await run();
+        }
+        catch (err) {
+            if (!(err instanceof GitHubRequestError) ||
+                !isRetryableGraphQlInternal(err.graphqlErrors) ||
+                isGraphQlMutationDocument(document) ||
+                hasServerBackoff(err)) {
+                throw err;
+            }
+            lastErr = err;
+            const delay = GRAPHQL_INTERNAL_RETRY_DELAYS[attempt - 1];
+            if (delay === undefined)
+                break;
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}

package/bin/github/graphql-response.mjs

@@ -13,7 +13,7 @@ export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds
                 typeof error["message"] === "string")) {
             throw malformedGraphQlResponse("errors field is not an array of GraphQL errors", status, rateLimit, retryAfterSeconds);
         }
-        errors = record["errors"];
+        errors = record["errors"].map((error) => parseGraphQlError(error));
     }
     if (!("data" in record)) {
         if (errors?.length)
@@ -26,6 +26,16 @@ export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds
     }
     return { data: record["data"] ?? null, errors };
 }
+function parseGraphQlError(error) {
+    const parsed = { message: error["message"] };
+    if ("path" in error)
+        parsed.path = error["path"];
+    if (typeof error["type"] === "string")
+        parsed.type = error["type"];
+    if (error["extensions"] !== undefined)
+        parsed.extensions = error["extensions"];
+    return parsed;
+}
 export function formatGraphQlErrors(errors) {
     return (errors ?? [])
         .map((error) => {

package/bin/github/http-auth.d.mts

@@ -1,4 +1,12 @@
+export type AuthSource = "GH_TOKEN" | "GITHUB_TOKEN" | "gh auth token" | "GITHUB_PERSONAL_ACCESS_TOKEN";
 export declare function _resetTokenCache(): void;
 export declare function hasCachedToken(): boolean;
 export declare function clearTokenCache(): void;
-export declare function makeHeaders(): Promise<Record<string, string>>;
+/**
+ * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
+ * conditional REST requests) on top of the standard auth/version headers.
+ */
+export declare function makeAuthHeaders(extra?: Record<string, string>): Promise<{
+    headers: Record<string, string>;
+    source: AuthSource;
+}>;

package/bin/github/http-auth.mjs

@@ -3,29 +3,40 @@ import { promisify } from "node:util";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const execFile = promisify(execFileCb);
 let _token;
+let _tokenSource;
 export function _resetTokenCache() {
     _token = undefined;
+    _tokenSource = undefined;
 }
 export function hasCachedToken() {
     return _token !== undefined;
 }
 export function clearTokenCache() {
     _token = undefined;
+    _tokenSource = undefined;
 }
 async function resolveToken() {
-    if (_token)
-        return _token;
-    const envToken = process.env["GH_TOKEN"] ?? process.env["GITHUB_TOKEN"];
-    if (envToken) {
-        _token = envToken;
-        return _token;
+    if (_token && _tokenSource)
+        return { token: _token, source: _tokenSource };
+    const ghToken = process.env["GH_TOKEN"];
+    if (ghToken) {
+        _token = ghToken;
+        _tokenSource = "GH_TOKEN";
+        return { token: _token, source: _tokenSource };
+    }
+    const githubToken = process.env["GITHUB_TOKEN"];
+    if (githubToken) {
+        _token = githubToken;
+        _tokenSource = "GITHUB_TOKEN";
+        return { token: _token, source: _tokenSource };
     }
     try {
         const { stdout } = await execFile("gh", ["auth", "token"]);
         const token = stdout.trim();
         if (token) {
             _token = token;
-            return _token;
+            _tokenSource = "gh auth token";
+            return { token: _token, source: _tokenSource };
         }
     }
     catch {
@@ -34,16 +45,26 @@ async function resolveToken() {
     const codexToken = process.env["GITHUB_PERSONAL_ACCESS_TOKEN"];
     if (codexToken) {
         _token = codexToken;
-        return _token;
+        _tokenSource = "GITHUB_PERSONAL_ACCESS_TOKEN";
+        return { token: _token, source: _tokenSource };
     }
     throw new ShepherdError("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.", EXIT.NOPERM);
 }
-export async function makeHeaders() {
+/**
+ * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
+ * conditional REST requests) on top of the standard auth/version headers.
+ */
+export async function makeAuthHeaders(extra) {
+    const { token, source } = await resolveToken();
     return {
-        Authorization: `Bearer ${await resolveToken()}`,
-        Accept: "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2022-11-28",
-        "User-Agent": "pr-shepherd",
-        "Content-Type": "application/json",
+        source,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "pr-shepherd",
+            "Content-Type": "application/json",
+            ...extra,
+        },
     };
 }

package/bin/github/http-intermediate.d.mts

@@ -0,0 +1,9 @@
+export declare function recordIntermediateResponse(opts: {
+    n: number;
+    kind: "GraphQL" | "REST" | "restText";
+    method: string;
+    url: string;
+    response: Response;
+    durationMs: number;
+    authSource: string;
+}): void;

package/bin/github/http-intermediate.mjs

@@ -0,0 +1,20 @@
+import { appendEntry } from "../log/log-file.mjs";
+import { formatResponseEntry } from "../log/session.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { parseRateLimit, parseRetryAfter } from "./http-utils.mjs";
+export function recordIntermediateResponse(opts) {
+    const rateLimit = parseRateLimit(opts.response.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(opts.response.headers);
+    appendEntry(formatResponseEntry({
+        ...opts,
+        status: opts.response.status,
+        rateLimit,
+        retryAfterSeconds,
+    }));
+    recordApiTelemetry({
+        kind: opts.kind === "GraphQL" ? "GraphQL" : "REST",
+        method: opts.method,
+        authSource: opts.authSource,
+        rateLimit,
+    });
+}

package/bin/github/http-request.d.mts

@@ -1,4 +1,4 @@
-type RetryLogFn = (status: number, durationMs: number) => void;
+type RetryLogFn = (response: Response, durationMs: number) => void;
 export declare function requestWithTokenRetry(fn: () => Promise<Response>, t0: number, onIntermediate?: RetryLogFn): Promise<{
     res: Response;
     attempt: number;

package/bin/github/http-request.mjs

@@ -23,7 +23,7 @@ async function fetchWithTransportRetry(fn) {
 export async function requestWithTokenRetry(fn, t0, onIntermediate) {
     const res = await fetchWithTransportRetry(fn);
     if (res.status === 401 && hasCachedToken()) {
-        onIntermediate?.(401, Math.round(performance.now() - t0));
+        onIntermediate?.(res, Math.round(performance.now() - t0));
         try {
             await res.arrayBuffer();
         }

package/bin/github/http-utils.d.mts

@@ -3,6 +3,12 @@ export interface RateLimitInfo {
     remaining: number;
     limit: number;
     resetAt: number;
+    used?: number;
+    resource?: string;
+    /** Exact GraphQL query cost when the operation selected rateLimit.cost. */
+    cost?: number;
+    /** Exact GraphQL node count when the operation selected rateLimit.nodeCount. */
+    nodeCount?: number;
 }
 export declare function sanitizeBody(body: string): string;
 export declare function redactToken(body: string): string;

package/bin/github/http-utils.mjs

@@ -45,7 +45,16 @@ export function parseRateLimit(headers) {
     const limit = Number(lRaw);
     const resetAt = Number(tRaw);
     if (Number.isFinite(remaining) && Number.isFinite(limit) && Number.isFinite(resetAt)) {
-        return { remaining, limit, resetAt };
+        const usedRaw = headers.get("x-ratelimit-used");
+        const used = usedRaw === null ? undefined : Number(usedRaw);
+        const resource = headers.get("x-ratelimit-resource") ?? undefined;
+        return {
+            remaining,
+            limit,
+            resetAt,
+            ...(Number.isFinite(used) && { used }),
+            ...(resource !== undefined && resource !== "" && { resource }),
+        };
     }
     return null;
 }

package/bin/github/rest-http.d.mts

@@ -1,7 +1,22 @@
+import { type StateKey } from "../state/rest-cache.mts";
 import { type RateLimitInfo } from "./http-utils.mts";
 export interface RestResult<T = unknown> {
     data: T;
     rateLimit?: RateLimitInfo;
 }
+/**
+ * Enables `If-None-Match` conditional requests for a REST call, backed by a
+ * per-PR on-disk cache (see `src/state/rest-cache.mts`). A 304 response
+ * returns the cached body and — unlike a normal request — does not consume
+ * the primary REST rate-limit quota.
+ */
+export interface RestRequestOptions {
+    conditional?: {
+        key: StateKey;
+        /** Logical cache name; must be unique per distinct resource + page. */
+        name: string;
+        headSha?: string;
+    };
+}
 export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
-export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown): Promise<RestResult<T>>;
+export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown, opts?: RestRequestOptions): Promise<RestResult<T>>;

package/bin/github/rest-http.mjs

@@ -1,9 +1,13 @@
+/* eslint-disable max-lines */
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { loadEtagEntry, storeEtagEntry } from "../state/rest-cache.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 const SAFE_GITHUB_REST_PATH = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]*$/;
 function githubApiUrl(path) {
@@ -24,19 +28,55 @@ export async function rest(method, path, body) {
     const { data } = await restWithRateLimit(method, path, body);
     return data;
 }
-export async function restWithRateLimit(method, path, body) {
+export async function restWithRateLimit(method, path, body, opts) {
     const url = githubApiUrl(path);
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "REST", method, url, body }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
+    let authSource = "unknown";
+    const cached = opts?.conditional
+        ? await loadEtagEntry(opts.conditional.key, opts.conditional.name)
+        : null;
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders(cached ? { "If-None-Match": cached.etag } : undefined);
+        authSource = auth.source;
+        return fetch(url, {
+            method,
+            headers: auth.headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "REST",
         method,
-        headers: await makeHeaders(),
-        body: body !== undefined ? JSON.stringify(body) : undefined,
-    }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "REST", method, url, status, durationMs })));
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
-    const ct = res.headers.get("content-type") ?? "";
     const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(res.headers);
+    // A 304 is not `res.ok` but is not an error either — and critically, does
+    // not consume the primary REST request quota — so it must be handled
+    // before the !res.ok branch below.
+    if (res.status === 304 && cached) {
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "REST",
+            method,
+            url,
+            status: res.status,
+            durationMs,
+            attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
+        }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
+        return { data: cached.body, rateLimit };
+    }
+    const ct = res.headers.get("content-type") ?? "";
     if (!res.ok) {
         const text = await res.text();
         appendEntry(formatResponseEntry({
@@ -48,11 +88,16 @@ export async function restWithRateLimit(method, path, body) {
             durationMs,
             textBody: redactToken(text),
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
         throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
             rateLimit,
-            retryAfterSeconds: parseRetryAfter(res.headers),
+            retryAfterSeconds,
+            authSource,
         });
     }
     if (ct.includes("application/json")) {
@@ -67,7 +112,21 @@ export async function restWithRateLimit(method, path, body) {
             contentType: ct,
             body: json,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
+        if (opts?.conditional) {
+            const etag = res.headers.get("etag");
+            if (etag) {
+                await storeEtagEntry(opts.conditional.key, opts.conditional.name, {
+                    etag,
+                    body: json,
+                    ...(opts.conditional.headSha !== undefined && { headSha: opts.conditional.headSha }),
+                });
+            }
+        }
         return { data: json, rateLimit };
     }
     appendEntry(formatResponseEntry({
@@ -79,6 +138,10 @@ export async function restWithRateLimit(method, path, body) {
         durationMs,
         contentType: ct || undefined,
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit,
+        retryAfterSeconds,
     }));
+    recordApiTelemetry({ kind: "REST", method, authSource, rateLimit });
     return { data: undefined, rateLimit };
 }

package/bin/github/rest-text.mjs

@@ -1,19 +1,45 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 export async function restText(path) {
     const url = `${BASE_URL}${path}`;
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, { method: "GET", headers: await makeHeaders(), redirect: "manual" }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "restText", method: "GET", url, status, durationMs })));
+    let authSource = "unknown";
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders();
+        authSource = auth.source;
+        return fetch(url, { method: "GET", headers: auth.headers, redirect: "manual" });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "restText",
+        method: "GET",
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
+    const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    const retryAfterSeconds = parseRetryAfter(res.headers);
+    recordApiTelemetry({ kind: "REST", method: "GET", authSource, rateLimit });
     if ([301, 302, 307, 308].includes(res.status)) {
-        const redirected = await followRestTextRedirect(res, { n, url, durationMs, attempt });
+        const redirected = await followRestTextRedirect(res, {
+            n,
+            url,
+            durationMs,
+            attempt,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
+        });
         if (redirected !== null)
             return redirected;
     }
@@ -27,11 +53,15 @@ export async function restText(path) {
             status: res.status,
             durationMs,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit,
+            retryAfterSeconds,
         }));
         throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
-            rateLimit: parseRateLimit(res.headers) ?? undefined,
-            retryAfterSeconds: parseRetryAfter(res.headers),
+            rateLimit,
+            retryAfterSeconds,
+            authSource,
         });
     }
     appendEntry(formatResponseEntry({
@@ -43,6 +73,9 @@ export async function restText(path) {
         durationMs,
         contentLength: parseContentLength(res.headers),
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit,
+        retryAfterSeconds,
     }));
     return res.text();
 }
@@ -55,6 +88,9 @@ async function followRestTextRedirect(res, entry) {
         status: res.status,
         durationMs: entry.durationMs,
         attempt: entry.attempt > 1 ? entry.attempt : undefined,
+        authSource: entry.authSource,
+        rateLimit: entry.rateLimit,
+        retryAfterSeconds: entry.retryAfterSeconds,
     }));
     const location = res.headers.get("location");
     if (!location)

package/bin/index.mjs

@@ -9,6 +9,7 @@
  */
 import { main } from "./cli-parser.mjs";
 import { errorToExitCode } from "./exit-codes.mjs";
+import { formatCliError } from "./cli/error-format.mjs";
 function formatCause(cause, seen = new Set(), depth = 0) {
     if (depth > 5 || seen.has(cause))
         return "[circular or deep cause chain]";
@@ -21,7 +22,7 @@ function formatCause(cause, seen = new Set(), depth = 0) {
     return String(cause);
 }
 main(process.argv).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = formatCliError(err);
     const causeStr = err instanceof Error && err.cause != null ? formatCause(err.cause) : null;
     process.stderr.write(`pr-shepherd error: ${msg}${causeStr !== null ? ` (cause: ${causeStr})` : ""}\n`);
     process.exit(errorToExitCode(err));