pr-shepherd 0.56.6 → 0.57.0

package/bin/github/rest-merge.mjs

@@ -0,0 +1,56 @@
+import { restWithRateLimit } from "./rest-http.mjs";
+import { restRepoPath } from "./rest-reader-core.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { sanitizeBody } from "./http-utils.mjs";
+function parseRestMergeResponse(raw) {
+    if (raw === null || typeof raw !== "object")
+        throw new Error("Invalid asynchronous merge response");
+    const value = raw;
+    if (!["pending", "enqueued", "merged", "failed"].includes(String(value["status"])) ||
+        value["details"] === null ||
+        typeof value["details"] !== "object" ||
+        Array.isArray(value["details"])) {
+        throw new Error("Invalid asynchronous merge response");
+    }
+    return value;
+}
+/** This named mutation is never retried after a network failure or server error. */
+export async function requestRestMerge(repo, pr, options) {
+    const { data, status, rateLimit } = await restWithRateLimit("PUT", `${restRepoPath(repo)}/pulls/${pr}/merge-async`, {
+        sha: options.requireSha,
+        merge_action: options.mergeAction,
+        bypass_rules: false,
+        ...(options.mergeAction === "direct_merge" && options.mergeMethod
+            ? { merge_method: options.mergeMethod }
+            : {}),
+    }, { acceptStatuses: [400, 409] });
+    try {
+        return parseRestMergeResponse(data);
+    }
+    catch (error) {
+        // Accepted 400/409 responses may contain an ordinary API error envelope,
+        // rather than merge state. Retain their definite refusal for intent recovery.
+        if (status !== undefined && status >= 400 && status < 500) {
+            const responseMessage = sanitizeBody(JSON.stringify(data) ?? "");
+            throw new GitHubRequestError(`Invalid asynchronous merge response: ${status} ${responseMessage}`, { status, rateLimit, responseMessage });
+        }
+        // A malformed acknowledgement may follow a successful submission.
+        throw error;
+    }
+}
+export async function getRestMerge(repo, pr, uuid) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid))
+        throw new Error("Invalid asynchronous merge UUID");
+    const { data } = await restWithRateLimit("GET", `${restRepoPath(repo)}/pulls/${pr}/merge-async/${uuid}`);
+    return parseRestMergeResponse(data);
+}
+/** Conflict requests must match the caller's guarded options before their UUID can be adopted. */
+export function matchesRestMergeRequest(result, options) {
+    const details = result.details;
+    return (details.expected_head_sha === options.requireSha &&
+        details.merge_action === options.mergeAction &&
+        details.bypass_rules === false &&
+        (options.mergeMethod === undefined || details.merge_method === options.mergeMethod) &&
+        typeof details.uuid === "string" &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(details.uuid));
+}

package/bin/github/rest-merged-base-read.d.mts

@@ -0,0 +1,9 @@
+import type { MergedBasePullRequest } from "../types.mts";
+export interface MergedBaseLookupInput {
+    owner: string;
+    repo: string;
+    baseRefName: string;
+    baseRefOid: string;
+}
+/** A reused branch name or a fork is insufficient evidence of a merged parent. */
+export declare function readRestMergedBasePullRequests(input: MergedBaseLookupInput): Promise<MergedBasePullRequest[]>;

package/bin/github/rest-merged-base-read.mjs

@@ -0,0 +1,48 @@
+import { readRestPages, restRepoPath, restObject, restString, restNumber, malformedRest, } from "./rest-reader-core.mjs";
+/** A reused branch name or a fork is insufficient evidence of a merged parent. */
+export async function readRestMergedBasePullRequests(input) {
+    const repo = { owner: input.owner, name: input.repo };
+    const head = encodeURIComponent(`${input.owner}:${input.baseRefName}`);
+    const pulls = await readRestPages(`${restRepoPath(repo)}/pulls?state=closed&head=${head}&sort=updated&direction=desc`);
+    const candidates = [];
+    const ids = new Set();
+    for (const value of pulls.nodes) {
+        const pull = restObject(value, "closed pull request");
+        const number = restNumber(pull.number, "closed pull number");
+        if (number === 0 || ids.has(number))
+            malformedRest("closed pull number missing or repeated");
+        ids.add(number);
+        const state = restString(pull.state, "closed pull state");
+        if (!["open", "closed"].includes(state))
+            malformedRest("closed pull state");
+        if (pull.merged_at !== null && typeof pull.merged_at !== "string")
+            malformedRest("closed pull merged_at");
+        if (state !== "closed" || pull.merged_at === null)
+            continue;
+        if (!Number.isFinite(Date.parse(pull.merged_at)))
+            malformedRest("closed pull merged_at");
+        const source = restObject(pull.head, "closed pull head");
+        const headRefName = restString(source.ref, "closed pull head ref");
+        const headRefOid = restString(source.sha, "closed pull head SHA");
+        if (headRefName !== input.baseRefName || headRefOid !== input.baseRefOid)
+            continue;
+        if (source.repo === null)
+            continue;
+        const headRepository = restObject(source.repo, "closed pull head repository");
+        const nameWithOwner = restString(headRepository.full_name, "closed pull head repository name");
+        if (nameWithOwner.toLowerCase() !== `${input.owner}/${input.repo}`.toLowerCase())
+            continue;
+        const base = restObject(pull.base, "closed pull base");
+        candidates.push({
+            number,
+            url: restString(pull.html_url, "closed pull URL"),
+            state: "MERGED",
+            headRefName,
+            headRefOid,
+            baseRefName: restString(base.ref, "closed pull base ref"),
+            mergedAt: pull.merged_at,
+            headRepository: { nameWithOwner },
+        });
+    }
+    return candidates;
+}

package/bin/github/rest-pr-core.d.mts

@@ -0,0 +1,52 @@
+import type { RepoInfo } from "./client.mts";
+export interface RestPull {
+    id: number;
+    node_id: string;
+    number: number;
+    title: string;
+    body: string | null;
+    html_url: string;
+    state: string;
+    merged_at: string | null;
+    draft: boolean;
+    mergeable: boolean | null;
+    mergeable_state: string;
+    updated_at: string;
+    user: {
+        login: string;
+        type?: string;
+    } | null;
+    head: {
+        ref: string;
+        sha: string;
+        repo: {
+            full_name: string;
+        } | null;
+    };
+    base: {
+        ref: string;
+        sha: string;
+    };
+    requested_reviewers: Array<{
+        login: string;
+    }>;
+    requested_teams: Array<{
+        name: string;
+    }>;
+    auto_merge?: {
+        enabled_by?: {
+            login: string;
+        };
+        merge_method: string;
+    } | null;
+}
+export declare function readRestPull(pr: number, repo: RepoInfo): Promise<RestPull>;
+export declare function restPullRefs(pull: RestPull): {
+    number: number;
+    state: string;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    baseRefOid: string;
+};
+export declare function restPullRevision(pull: RestPull): string;

package/bin/github/rest-pr-core.mjs

@@ -0,0 +1,60 @@
+import { readRest as rest } from "./rest-reader-core.mjs";
+import { restRepoPath, restObject, restString, restNumber, restBoolean, restArray, malformedRest, } from "./rest-reader-core.mjs";
+import { recordRestIdentity } from "./rest-identities.mjs";
+export async function readRestPull(pr, repo) {
+    const value = await rest("GET", `${restRepoPath(repo)}/pulls/${pr}`);
+    const data = restObject(value, "pull request");
+    const head = restObject(data.head, "pull request head");
+    const base = restObject(data.base, "pull request base");
+    restNumber(data.id, "pull request id");
+    restString(data.node_id, "pull request node_id");
+    if (restNumber(data.number, "pull request number") !== pr)
+        throw new Error("REST pull request identity changed");
+    restString(data.title, "pull request title");
+    restString(data.html_url, "pull request html_url");
+    if (data.body !== null && typeof data.body !== "string")
+        malformedRest("pull request body");
+    if (data.merged_at !== null && typeof data.merged_at !== "string")
+        malformedRest("pull request merged_at");
+    restArray(data.requested_reviewers, "requested reviewers");
+    restArray(data.requested_teams, "requested teams");
+    restString(data.state, "pull request state");
+    restBoolean(data.draft, "pull request draft");
+    restString(head.sha, "pull request head SHA");
+    restString(head.ref, "pull request head ref");
+    restString(base.sha, "pull request base SHA");
+    restString(base.ref, "pull request base ref");
+    restString(data.updated_at, "pull request updated_at");
+    if (!Number.isFinite(Date.parse(data.updated_at)))
+        malformedRest("pull request revision timestamp");
+    restString(data.mergeable_state, "pull request mergeable_state");
+    if (data.mergeable !== null)
+        restBoolean(data.mergeable, "pull request mergeable");
+    await recordRestIdentity(repo, pr, data.node_id, String(data.id), "pull");
+    return data;
+}
+export function restPullRefs(pull) {
+    return {
+        number: pull.number,
+        state: pull.merged_at ? "MERGED" : pull.state.toUpperCase(),
+        headRefName: pull.head.ref,
+        headRefOid: pull.head.sha,
+        baseRefName: pull.base.ref,
+        baseRefOid: pull.base.sha,
+    };
+}
+export function restPullRevision(pull) {
+    return JSON.stringify([
+        pull.head.ref,
+        pull.head.sha,
+        pull.base.ref,
+        pull.base.sha,
+        pull.updated_at,
+        pull.state,
+        pull.draft,
+        pull.merged_at,
+        pull.mergeable,
+        pull.mergeable_state,
+        pull.auto_merge ?? null,
+    ]);
+}

package/bin/github/rest-reader-core.d.mts

@@ -0,0 +1,16 @@
+import type { RepoInfo, RateLimitInfo } from "./client.mts";
+export declare function restRepoPath(repo: RepoInfo): string;
+export declare function malformedRest(detail: string): never;
+export declare function restObject(value: unknown, label: string): Record<string, unknown>;
+export declare function restString(value: unknown, label: string): string;
+export declare function restNumber(value: unknown, label: string): number;
+export declare function restBoolean(value: unknown, label: string): boolean;
+export declare function restArray(value: unknown, label: string): unknown[];
+/** Counted REST envelopes must include the count as well as their list. */
+export declare function restCollection(value: unknown, key: string): unknown[];
+/** Complete REST connections; follow GitHub's Link, never infer completeness from a short page. */
+export declare function readRestPages<T>(path: string, select?: (body: unknown) => T[]): Promise<{
+    nodes: T[];
+    rateLimit?: RateLimitInfo;
+}>;
+export declare function readRest<T>(method: string, path: string, body?: unknown): Promise<T>;

package/bin/github/rest-reader-core.mjs

@@ -0,0 +1,154 @@
+import { restWithRateLimit } from "./http.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { EXIT } from "../exit-codes.mjs";
+import { currentRestConditionalKey, recordRestConditionalRead } from "./rest-conditional-scope.mjs";
+export function restRepoPath(repo) {
+    return `/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.name)}`;
+}
+export function malformedRest(detail) {
+    throw new GitHubRequestError(`Malformed or incomplete GitHub REST response: ${detail}`, {
+        status: 200,
+        exitCodeOverride: EXIT.SOFTWARE,
+    });
+}
+export function restObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        malformedRest(label);
+    return value;
+}
+export function restString(value, label) {
+    if (typeof value !== "string" || !value)
+        malformedRest(label);
+    return value;
+}
+export function restNumber(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        malformedRest(label);
+    return value;
+}
+export function restBoolean(value, label) {
+    if (typeof value !== "boolean")
+        malformedRest(label);
+    return value;
+}
+export function restArray(value, label) {
+    if (!Array.isArray(value))
+        malformedRest(label);
+    return value;
+}
+/** Counted REST envelopes must include the count as well as their list. */
+export function restCollection(value, key) {
+    const record = restObject(value, key);
+    restNumber(record.total_count, `${key}.total_count`);
+    return restArray(record[key], key);
+}
+const REST_PAGE_SIZE = 100;
+/** Complete REST connections; follow GitHub's Link, never infer completeness from a short page. */
+export async function readRestPages(path, select = (body) => restArray(body, path)) {
+    let next = `${path}${path.includes("?") ? "&" : "?"}per_page=${REST_PAGE_SIZE}`;
+    const visited = new Set();
+    const nodes = [];
+    let rateLimit;
+    let total;
+    while (next) {
+        if (visited.has(next) || visited.size >= 1_000)
+            malformedRest(`pagination cycle or limit at ${next}`);
+        visited.add(next);
+        let result = await readRestRequest("GET", next);
+        let page = select(result.data);
+        if (!Array.isArray(page))
+            malformedRest(`missing page at ${next}`);
+        // A full page's body (and ETag) stays the same when an item is appended past it; only its
+        // Link gains rel="next". A 304 can't prove the cached terminal Link is still current, so a
+        // full page without a next link is re-read fresh rather than hiding items on a later page.
+        if (result.status === 304 &&
+            page.length >= REST_PAGE_SIZE &&
+            nextRestPage(result.link, path) === undefined) {
+            result = await readRestRequest("GET", next, undefined, true);
+            page = select(result.data);
+            if (!Array.isArray(page))
+                malformedRest(`missing page at ${next}`);
+        }
+        rateLimit = result.rateLimit ?? rateLimit;
+        nodes.push(...page);
+        if (result.data &&
+            typeof result.data === "object" &&
+            !Array.isArray(result.data) &&
+            "total_count" in result.data) {
+            const count = restNumber(result.data.total_count, `${path}.total_count`);
+            if (total !== undefined && total !== count)
+                malformedRest(`${path} changed during pagination`);
+            total = count;
+        }
+        next = nextRestPage(result.link, path);
+        if (next && page.length === 0)
+            malformedRest(`${path}: empty page with next link`);
+    }
+    if (total !== undefined && nodes.length !== total)
+        malformedRest(`${path}: ${nodes.length} of ${total} items`);
+    return { nodes, rateLimit };
+}
+function nextRestPage(link, original) {
+    if (!link)
+        return undefined;
+    const entries = link.split(",");
+    const nextEntries = entries.filter((entry) => /rel="next"/.test(entry));
+    if (nextEntries.length === 0)
+        return undefined;
+    if (nextEntries.length !== 1)
+        malformedRest(`multiple next links for ${original}`);
+    const match = /^\s*<([^>]+)>;\s*rel="next"\s*$/.exec(nextEntries[0]);
+    if (!match)
+        malformedRest(`invalid pagination link for ${original}`);
+    const url = new URL(match[1], "https://api.github.com");
+    if (url.origin !== "https://api.github.com" || url.pathname !== original.split("?")[0])
+        malformedRest(`unsafe pagination link for ${original}`);
+    if (url.searchParams.get("per_page") !== "100")
+        malformedRest(`changed page size for ${original}`);
+    const source = new URL(original, "https://api.github.com");
+    for (const key of new Set(source.searchParams.keys())) {
+        if (key !== "page" &&
+            key !== "per_page" &&
+            JSON.stringify(url.searchParams.getAll(key)) !==
+                JSON.stringify(source.searchParams.getAll(key)))
+            malformedRest(`changed pagination filter for ${original}`);
+    }
+    return `${url.pathname}${url.search}`;
+}
+/** A pull request whose mergeability GitHub is still computing must be re-read, never replayed. */
+function isSettledBody(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return true;
+    const record = body;
+    return record.mergeable !== null && record.mergeable_state !== "unknown";
+}
+let activeRequests = 0;
+const pendingRequests = [];
+/** Bound independent snapshots and nested connection reads to four HTTP requests together. */
+async function readRestRequest(method, path, body, revalidate = false) {
+    if (activeRequests >= 4)
+        await new Promise((resolve) => pendingRequests.push(resolve));
+    else
+        activeRequests++;
+    try {
+        const key = method === "GET" ? currentRestConditionalKey() : undefined;
+        if (key === undefined)
+            return await restWithRateLimit(method, path, body);
+        const result = await restWithRateLimit(method, path, body, {
+            conditional: { key, name: path, shouldStore: isSettledBody, revalidate },
+        });
+        const unvalidated = result.status !== 304 && result.etag === undefined && isSettledBody(result.data);
+        recordRestConditionalRead(path, result.status === 304, result.etag, unvalidated ? result.data : undefined);
+        return result;
+    }
+    finally {
+        const waiting = pendingRequests.shift();
+        if (waiting)
+            waiting();
+        else
+            activeRequests--;
+    }
+}
+export async function readRest(method, path, body) {
+    return (await readRestRequest(method, path, body)).data;
+}

package/bin/github/rest-review-read.d.mts

@@ -0,0 +1,11 @@
+import type { RestReview } from "./rest-feedback-read.mts";
+export declare function validateRestReviews(reviews: RestReview[]): void;
+/** Draft reviews carry no submitted decision and cannot replace earlier submitted evidence. */
+export declare function restLatestReviews(reviews: RestReview[]): Map<string, {
+    login: string;
+    state: string;
+}>;
+export declare function restPendingReviews(reviews: RestReview[]): {
+    login: string;
+    state: string;
+}[];

package/bin/github/rest-review-read.mjs

@@ -0,0 +1,47 @@
+import { malformedRest, restString } from "./rest-reader-core.mjs";
+const REVIEW_STATES = new Set([
+    "APPROVED",
+    "CHANGES_REQUESTED",
+    "COMMENTED",
+    "DISMISSED",
+    "PENDING",
+]);
+export function validateRestReviews(reviews) {
+    for (const review of reviews) {
+        if (!REVIEW_STATES.has(restString(review.state, "review state")))
+            malformedRest("unknown review state");
+        restString(review.commit_id, "review commit_id");
+        if (review.state === "PENDING")
+            continue;
+        const submitted = restString(review.submitted_at, "review submitted_at");
+        if (!Number.isFinite(Date.parse(submitted)))
+            malformedRest("review submitted_at");
+    }
+}
+/** Draft reviews carry no submitted decision and cannot replace earlier submitted evidence. */
+export function restLatestReviews(reviews) {
+    const latest = new Map();
+    const submitted = reviews.filter((review) => review.state !== "PENDING");
+    submitted.sort((a, b) => Date.parse(a.submitted_at) - Date.parse(b.submitted_at) || a.id - b.id);
+    for (const review of submitted) {
+        if (!review.user?.login)
+            continue;
+        latest.set(review.user.login.toLowerCase(), {
+            login: review.user.login,
+            state: review.state,
+        });
+    }
+    return latest;
+}
+export function restPendingReviews(reviews) {
+    const pending = new Map();
+    for (const review of reviews) {
+        if (review.state !== "PENDING" || !review.user?.login)
+            continue;
+        pending.set(review.user.login.toLowerCase(), {
+            login: review.user.login,
+            state: review.state,
+        });
+    }
+    return [...pending.values()];
+}

package/bin/github/rest-rules-read.d.mts

@@ -0,0 +1,9 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawBaseRef } from "./batch-raw-rules.mts";
+export declare function readRestBranchRules(repo: RepoInfo, branch: string): Promise<{
+    baseRef?: RawBaseRef;
+    unavailable: Array<{
+        field: string;
+        reason: string;
+    }>;
+}>;

package/bin/github/rest-rules-read.mjs

@@ -0,0 +1,154 @@
+import { readRest as rest } from "./rest-reader-core.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { rateLimitKind } from "./rate-limit-kind.mjs";
+import { isRestSessionRefusal } from "./rest-session-refusal.mjs";
+import { recordRestConditionalRead } from "./rest-conditional-scope.mjs";
+import { readRestPages, restRepoPath, restObject, restString, restArray, restNumber, } from "./rest-reader-core.mjs";
+export async function readRestBranchRules(repo, branch) {
+    const path = `${restRepoPath(repo)}/branches/${encodeURIComponent(branch)}/protection`;
+    let classic = null;
+    const unavailable = [];
+    if (!(await classicProtectionDisabled(repo, branch))) {
+        try {
+            const data = restObject(await rest("GET", path), "branch protection");
+            const approvals = data.required_pull_request_reviews == null
+                ? null
+                : restObject(data.required_pull_request_reviews, "required reviews");
+            const checks = data.required_status_checks == null
+                ? null
+                : restObject(data.required_status_checks, "required checks");
+            classic = {
+                requiresApprovingReviews: approvals !== null,
+                requiredApprovingReviewCount: approvals
+                    ? restNumber(approvals.required_approving_review_count, "required approval count")
+                    : 0,
+                requiresConversationResolution: enabled(data.required_conversation_resolution),
+                requiresStatusChecks: checks !== null,
+                requiredStatusCheckContexts: checks
+                    ? restArray(checks.contexts, "check contexts").map((context) => restString(context, "check context"))
+                    : [],
+                requiresCodeOwnerReviews: approvals?.require_code_owner_reviews === true,
+                requireLastPushApproval: approvals?.require_last_push_approval === true,
+                requiresCommitSignatures: enabled(data.required_signatures),
+                requiresLinearHistory: enabled(data.required_linear_history),
+                requiresStrictStatusChecks: checks?.strict === true,
+            };
+        }
+        catch (error) {
+            if (!isUnavailablePolicy(error))
+                throw error;
+            // Only GitHub's explicit unprotected response proves absence. A generic
+            // 404 may hide protection from a token without administration access.
+            if (!isUnprotectedBranch(error))
+                unavailable.push({
+                    field: "branchProtection",
+                    reason: `Classic branch protection unavailable (HTTP ${error.status})`,
+                });
+        }
+    }
+    let rules;
+    try {
+        const data = await readRestPages(`${restRepoPath(repo)}/rules/branches/${encodeURIComponent(branch)}`);
+        rules = data.nodes.map((rule) => {
+            const type = restString(rule.type, "branch rule type").toUpperCase();
+            const p = rule.parameters == null ? {} : restObject(rule.parameters, "branch rule parameters");
+            return {
+                type,
+                parameters: {
+                    ...(p.required_approving_review_count !== undefined && {
+                        requiredApprovingReviewCount: restNumber(p.required_approving_review_count, "ruleset approval count"),
+                    }),
+                    ...(p.required_review_thread_resolution !== undefined && {
+                        requiredReviewThreadResolution: p.required_review_thread_resolution === true,
+                    }),
+                    ...(p.require_code_owner_review !== undefined && {
+                        requireCodeOwnerReview: p.require_code_owner_review === true,
+                    }),
+                    ...(p.require_last_push_approval !== undefined && {
+                        requireLastPushApproval: p.require_last_push_approval === true,
+                    }),
+                    ...(p.strict_required_status_checks_policy !== undefined && {
+                        strictRequiredStatusChecksPolicy: p.strict_required_status_checks_policy === true,
+                    }),
+                    ...(p.required_status_checks !== undefined && {
+                        requiredStatusChecks: restArray(p.required_status_checks, "ruleset status checks").map((check) => ({
+                            context: restString(restObject(check, "status check").context, "required context"),
+                        })),
+                    }),
+                    ...(p.required_deployment_environments !== undefined && {
+                        requiredDeploymentEnvironments: restArray(p.required_deployment_environments, "required deployments").map((environment) => restString(environment, "deployment environment")),
+                    }),
+                },
+            };
+        });
+    }
+    catch (error) {
+        if (!isUnavailablePolicy(error))
+            throw error;
+        unavailable.push({
+            field: "branchRules",
+            reason: `Branch rules unavailable (HTTP ${error.status})`,
+        });
+    }
+    // Preserve partial known policy, but keep incompleteness explicit to READY consumers.
+    const baseRef = classic !== null || rules !== undefined
+        ? {
+            branchProtectionRule: classic,
+            rules: rules === undefined ? null : { pageInfo: { hasNextPage: false }, nodes: rules },
+        }
+        : undefined;
+    return { ...(baseRef && { baseRef }), unavailable };
+}
+/**
+ * The branch summary is conditional (a 304 costs no quota) while an unprotected branch's
+ * `/protection` 404 is charged on every read. Its `commit.sha` also makes a base push visible
+ * to REST snapshot reuse. `protection.enabled: false` is GitHub's own
+ * "Branch not protected" answer, so the charged read is skipped. Any other shape, including a
+ * summary hidden from the token, falls through to the authoritative `/protection` read.
+ */
+async function classicProtectionDisabled(repo, branch) {
+    const path = `${restRepoPath(repo)}/branches/${encodeURIComponent(branch)}`;
+    let summary;
+    try {
+        summary = await rest("GET", path);
+    }
+    catch (error) {
+        if (!isUnavailablePolicy(error))
+            throw error;
+        // The summary's `commit.sha` is what tells snapshot reuse the base moved; without it, an
+        // unchanged pull body cannot prove mergeability, so the snapshot must not be replayed.
+        recordRestConditionalRead(path, false, undefined);
+        return false;
+    }
+    if (!summary || typeof summary !== "object" || Array.isArray(summary))
+        return false;
+    const protection = summary.protection;
+    if (!protection || typeof protection !== "object" || Array.isArray(protection))
+        return false;
+    return protection.enabled === false;
+}
+function isUnavailablePolicy(error) {
+    return (error instanceof GitHubRequestError &&
+        [403, 404].includes(error.status) &&
+        rateLimitKind(error) === null &&
+        !isRestSessionRefusal(error));
+}
+function isUnprotectedBranch(error) {
+    if (error.status !== 404)
+        return false;
+    try {
+        const body = JSON.parse(error.responseMessage ?? "");
+        return (body !== null &&
+            typeof body === "object" &&
+            !Array.isArray(body) &&
+            body["message"] === "Branch not protected");
+    }
+    catch {
+        return false;
+    }
+}
+function enabled(value) {
+    return (value !== null &&
+        value !== undefined &&
+        restObject(value, "protection requirement").enabled === true);
+}

package/bin/github/rest-session-refusal.d.mts

@@ -0,0 +1,5 @@
+import { GitHubRequestError } from "./errors.mts";
+/** A cloud proxy refusal says nothing about the viewer's GitHub authorization. */
+export declare function isRestSessionRefusal(error: unknown): error is GitHubRequestError;
+/** Inspect the response before normal error-message truncation hides its evidence. */
+export declare function isRestSessionRefusalResponse(status: number, raw: string): boolean;

package/bin/github/rest-session-refusal.mjs

@@ -0,0 +1,21 @@
+import { GitHubRequestError } from "./errors.mjs";
+/** A cloud proxy refusal says nothing about the viewer's GitHub authorization. */
+export function isRestSessionRefusal(error) {
+    return (error instanceof GitHubRequestError &&
+        isRestSessionRefusalResponse(error.status, error.responseMessage ?? error.message));
+}
+/** Inspect the response before normal error-message truncation hides its evidence. */
+export function isRestSessionRefusalResponse(status, raw) {
+    if (status !== 403)
+        return false;
+    if (/not enabled for this session|sessions are bound/i.test(raw))
+        return true;
+    try {
+        const payload = JSON.parse(raw);
+        return (typeof payload?.documentation_url === "string" &&
+            new URL(payload.documentation_url).hostname === "docs.anthropic.com");
+    }
+    catch {
+        return false;
+    }
+}

package/bin/github/rest-snapshot-context.d.mts

@@ -0,0 +1,10 @@
+import type { readRestStackMembership } from "./rest-stack-read.mts";
+import type { readRestBranchRules } from "./rest-rules-read.mts";
+/** Shared evidence belongs to one stack summary read, never to a later polling tick. */
+export interface RestSnapshotContext {
+    stack: Awaited<ReturnType<typeof readRestStackMembership>>;
+    repository: Record<string, unknown>;
+    viewerLogin: string | null;
+    readBranchRules(branch: string): ReturnType<typeof readRestBranchRules>;
+    recordPullRevision(pr: number, revision: string): void;
+}

package/bin/github/rest-snapshot-context.mjs

@@ -0,0 +1 @@
+export {};