pr-shepherd 0.2.0 → 0.4.0

package/bin/comments/resolve.mjs

@@ -0,0 +1,111 @@
+/**
+ * Batched mutations for resolving threads, minimizing comments, and dismissing reviews.
+ *
+ * The three mutation types (resolve / minimize / dismiss) are run sequentially so total
+ * in-flight mutations never exceed CONCURRENCY at once, keeping us well within GitHub's
+ * secondary rate-limit window.
+ *
+ * Push-before-resolve safety:
+ *   When `requireSha` is set, shepherd verifies that GitHub has received that
+ *   commit before issuing any resolve/dismiss mutations. It polls up to 20 seconds.
+ *   If the push hasn't landed, shepherd throws rather than resolving prematurely
+ *   (which could allow auto-merge before reviewers see the fix).
+ */
+import { graphql, getPrHeadSha } from "../github/client.mjs";
+import { RESOLVE_THREAD_MUTATION, MINIMIZE_COMMENT_MUTATION, DISMISS_REVIEW_MUTATION, } from "../github/queries.mjs";
+import { loadConfig } from "../config/load.mjs";
+/**
+ * Execute all requested resolve/minimize/dismiss mutations.
+ *
+ * @throws Error if `requireSha` is set and GitHub hasn't received that commit
+ *              within the polling window.
+ */
+export async function applyResolveOptions(pr, repo, opts) {
+    // Require --message when dismissing reviews.
+    if ((opts.dismissReviewIds?.length ?? 0) > 0 && !opts.dismissMessage) {
+        throw new Error("--message is required when dismissing reviews");
+    }
+    // Safety check: verify the push landed before resolving.
+    if (opts.requireSha) {
+        await waitForSha(pr, repo, opts.requireSha);
+    }
+    const result = {
+        resolvedThreads: [],
+        minimizedComments: [],
+        dismissedReviews: [],
+        errors: [],
+    };
+    await runBatched(opts.resolveThreadIds ?? [], (id) => resolveThread(id), result.resolvedThreads, result.errors);
+    await runBatched(opts.minimizeCommentIds ?? [], (id) => minimizeComment(id, "RESOLVED"), result.minimizedComments, result.errors);
+    await runBatched(opts.dismissReviewIds ?? [], (id) => dismissReview(id, opts.dismissMessage), result.dismissedReviews, result.errors);
+    return result;
+}
+/**
+ * Auto-resolve a batch of outdated threads via the resolveReviewThread mutation.
+ */
+export async function autoResolveOutdated(threadIds) {
+    const resolved = [];
+    const errors = [];
+    await runBatched(threadIds, (id) => resolveThread(id), resolved, errors);
+    return { resolved, errors };
+}
+// ---------------------------------------------------------------------------
+// Mutation helpers
+// ---------------------------------------------------------------------------
+async function resolveThread(threadId) {
+    await graphql(RESOLVE_THREAD_MUTATION, { threadId });
+}
+async function minimizeComment(commentId, classifier) {
+    await graphql(MINIMIZE_COMMENT_MUTATION, { commentId, classifier });
+}
+async function dismissReview(reviewId, message) {
+    await graphql(DISMISS_REVIEW_MUTATION, { reviewId, message });
+}
+// ---------------------------------------------------------------------------
+// Concurrency helper
+// ---------------------------------------------------------------------------
+async function runBatched(ids, fn, successList, errorList) {
+    const CONCURRENCY = loadConfig().resolve.concurrency;
+    // Process in chunks of CONCURRENCY.
+    for (let i = 0; i < ids.length; i += CONCURRENCY) {
+        const chunk = ids.slice(i, i + CONCURRENCY);
+        // eslint-disable-next-line no-await-in-loop
+        await Promise.all(chunk.map(async (id) => {
+            try {
+                await fn(id);
+                successList.push(id);
+            }
+            catch (err) {
+                errorList.push(`${id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }));
+    }
+}
+// ---------------------------------------------------------------------------
+// SHA polling
+// ---------------------------------------------------------------------------
+async function waitForSha(pr, repo, expectedSha) {
+    const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
+    for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const currentSha = await getPrHeadSha(pr, repo.owner, repo.name);
+            if (currentSha === expectedSha)
+                return;
+        }
+        catch (err) {
+            // Transient network / 5xx error — keep polling unless this is the last attempt.
+            if (attempt === SHA_POLL_MAX_ATTEMPTS - 1)
+                throw err;
+        }
+        if (attempt < SHA_POLL_MAX_ATTEMPTS - 1) {
+            // eslint-disable-next-line no-await-in-loop
+            await sleep(SHA_POLL_INTERVAL_MS);
+        }
+    }
+    // Total actual wait = (SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS (no sleep after last poll).
+    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/bin/config/load.mjs

@@ -0,0 +1,158 @@
+import { readFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { parse } from "yaml";
+import builtins from "../config.json" with { type: "json" };
+const RC_FILENAME = ".pr-shepherdrc.yml";
+function findRcFile(startDir) {
+    const home = homedir();
+    let current = startDir;
+    while (true) {
+        const candidate = join(current, RC_FILENAME);
+        if (statSync(candidate, { throwIfNoEntry: false })?.isFile()) {
+            return candidate;
+        }
+        if (current === home || current === dirname(current))
+            return null;
+        current = dirname(current);
+    }
+}
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        const overVal = override[key];
+        const baseVal = base[key];
+        if (overVal !== null &&
+            typeof overVal === "object" &&
+            !Array.isArray(overVal) &&
+            typeof baseVal === "object" &&
+            baseVal !== null &&
+            !Array.isArray(baseVal)) {
+            result[key] = deepMerge(baseVal, overVal);
+        }
+        else if (overVal !== undefined) {
+            result[key] = overVal;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Compatibility shim — maps old RC keys to new ones and emits deprecation warnings
+// ---------------------------------------------------------------------------
+function applyCompat(raw) {
+    const out = { ...raw };
+    // Removed keys — warn and strip.
+    for (const gone of ["baseBranch", "minimizeBots", "cancelCiOnFailure", "autoMinimize"]) {
+        if (gone in out) {
+            process.stderr.write(`pr-shepherd: config key "${gone}" has been removed and has no effect.\n`);
+            delete out[gone];
+        }
+    }
+    // Renamed top-level section keys — iterate
+    const iterate = out["iterate"];
+    if (iterate && "maxFixAttempts" in iterate) {
+        process.stderr.write(`pr-shepherd: config key "iterate.maxFixAttempts" renamed to "iterate.fixAttemptsPerThread".\n`);
+        out["iterate"] = {
+            ...iterate,
+            fixAttemptsPerThread: iterate["fixAttemptsPerThread"] ?? iterate["maxFixAttempts"],
+        };
+        delete out["iterate"]["maxFixAttempts"];
+    }
+    // Renamed watch keys
+    const watch = out["watch"];
+    if (watch) {
+        const watchOut = { ...watch };
+        if ("intervalDefault" in watch) {
+            process.stderr.write(`pr-shepherd: config key "watch.intervalDefault" renamed to "watch.interval".\n`);
+            watchOut["interval"] = watchOut["interval"] ?? watch["intervalDefault"];
+            delete watchOut["intervalDefault"];
+        }
+        if ("readyDelayMinutesDefault" in watch) {
+            process.stderr.write(`pr-shepherd: config key "watch.readyDelayMinutesDefault" renamed to "watch.readyDelayMinutes".\n`);
+            watchOut["readyDelayMinutes"] =
+                watchOut["readyDelayMinutes"] ?? watch["readyDelayMinutesDefault"];
+            delete watchOut["readyDelayMinutesDefault"];
+        }
+        if ("expiresHoursDefault" in watch) {
+            process.stderr.write(`pr-shepherd: config key "watch.expiresHoursDefault" renamed to "watch.expiresHours".\n`);
+            watchOut["expiresHours"] = watchOut["expiresHours"] ?? watch["expiresHoursDefault"];
+            delete watchOut["expiresHoursDefault"];
+        }
+        out["watch"] = watchOut;
+    }
+    // Renamed resolve keys (shaPollIntervalMs / shaPollMaxAttempts → shaPoll object)
+    const resolve = out["resolve"];
+    if (resolve) {
+        const resolveOut = { ...resolve };
+        const shaPollOut = {};
+        let shaPollChanged = false;
+        if ("shaPollIntervalMs" in resolve) {
+            process.stderr.write(`pr-shepherd: config key "resolve.shaPollIntervalMs" moved to "resolve.shaPoll.intervalMs".\n`);
+            shaPollOut["intervalMs"] =
+                resolve["shaPoll"]?.["intervalMs"] ??
+                    resolve["shaPollIntervalMs"];
+            delete resolveOut["shaPollIntervalMs"];
+            shaPollChanged = true;
+        }
+        if ("shaPollMaxAttempts" in resolve) {
+            process.stderr.write(`pr-shepherd: config key "resolve.shaPollMaxAttempts" moved to "resolve.shaPoll.maxAttempts".\n`);
+            shaPollOut["maxAttempts"] =
+                resolve["shaPoll"]?.["maxAttempts"] ??
+                    resolve["shaPollMaxAttempts"];
+            delete resolveOut["shaPollMaxAttempts"];
+            shaPollChanged = true;
+        }
+        if (shaPollChanged) {
+            resolveOut["shaPoll"] = {
+                ...resolveOut["shaPoll"],
+                ...shaPollOut,
+            };
+        }
+        out["resolve"] = resolveOut;
+    }
+    // Renamed checks keys
+    const checks = out["checks"];
+    if (checks) {
+        const checksOut = { ...checks };
+        if ("relevantEvents" in checks) {
+            process.stderr.write(`pr-shepherd: config key "checks.relevantEvents" renamed to "checks.ciTriggerEvents".\n`);
+            checksOut["ciTriggerEvents"] = checksOut["ciTriggerEvents"] ?? checks["relevantEvents"];
+            delete checksOut["relevantEvents"];
+        }
+        if ("logLinesKept" in checks) {
+            process.stderr.write(`pr-shepherd: config key "checks.logLinesKept" renamed to "checks.logMaxLines".\n`);
+            checksOut["logMaxLines"] = checksOut["logMaxLines"] ?? checks["logLinesKept"];
+            delete checksOut["logLinesKept"];
+        }
+        if ("logExcerptMaxChars" in checks) {
+            process.stderr.write(`pr-shepherd: config key "checks.logExcerptMaxChars" renamed to "checks.logMaxChars".\n`);
+            checksOut["logMaxChars"] = checksOut["logMaxChars"] ?? checks["logExcerptMaxChars"];
+            delete checksOut["logExcerptMaxChars"];
+        }
+        out["checks"] = checksOut;
+    }
+    return out;
+}
+const defaults = builtins;
+let cached = null;
+export function loadConfig() {
+    if (cached)
+        return cached;
+    const rcPath = findRcFile(process.cwd());
+    if (!rcPath) {
+        cached = defaults;
+        return cached;
+    }
+    try {
+        const raw = readFileSync(rcPath, "utf8");
+        const parsed = (parse(raw) ?? {});
+        const compat = applyCompat(parsed);
+        cached = deepMerge(defaults, compat);
+        return cached;
+    }
+    catch (err) {
+        process.stderr.write(`pr-shepherd: failed to parse ${rcPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+        cached = { ...defaults };
+        return cached;
+    }
+}

package/bin/github/batch.mjs

@@ -0,0 +1,208 @@
+/**
+ * Executes the primary batch GraphQL query and parses the raw GitHub response
+ * into shepherd's typed `BatchPrData` shape.
+ *
+ * The batch query fetches CI checks + review threads + PR comments + merge
+ * status in a single network round-trip, drastically reducing API call counts
+ * compared to the previous per-agent approach.
+ */
+import { graphql, graphqlWithRateLimit } from "./client.mjs";
+import { paginateForward, paginateBackward } from "./pagination.mjs";
+import { BATCH_PR_QUERY } from "./queries.mjs";
+/**
+ * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
+ */
+export async function fetchPrBatch(pr, repo) {
+    // First page: no cursor variables.
+    const result = await graphqlWithRateLimit(BATCH_PR_QUERY, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+    });
+    const raw = result.data.repository.pullRequest;
+    if (!raw) {
+        throw new Error(`PR #${pr} not found`);
+    }
+    // Paginate reviewThreads backward if the first page is incomplete.
+    let rawThreadPages = raw.reviewThreads.nodes;
+    if (raw.reviewThreads.pageInfo.hasPreviousPage && raw.reviewThreads.pageInfo.startCursor) {
+        // Pass startCursor so paginateBackward fetches pages *before* the already-
+        // fetched first page instead of re-fetching it from the start.
+        const extra = await paginateBackward(async (cursor) => {
+            const res = await graphql(BATCH_PR_QUERY, {
+                owner: repo.owner,
+                repo: repo.name,
+                pr,
+                ...(cursor ? { threadsCursor: cursor } : {}),
+            });
+            const pr2 = res.data.repository.pullRequest;
+            if (!pr2)
+                throw new Error(`PR #${pr} not found`);
+            return pr2.reviewThreads;
+        }, raw.reviewThreads.pageInfo.startCursor);
+        // extra contains pages before the first page.
+        rawThreadPages = [...extra, ...rawThreadPages];
+    }
+    // Paginate comments backward if the first page is incomplete.
+    let rawCommentNodes = raw.comments.nodes;
+    if (raw.comments.pageInfo.hasPreviousPage && raw.comments.pageInfo.startCursor) {
+        const extra = await paginateBackward(async (cursor) => {
+            const res = await graphql(BATCH_PR_QUERY, {
+                owner: repo.owner,
+                repo: repo.name,
+                pr,
+                ...(cursor ? { commentsCursor: cursor } : {}),
+            });
+            const pr2 = res.data.repository.pullRequest;
+            if (!pr2)
+                throw new Error(`PR #${pr} not found`);
+            return pr2.comments;
+        }, raw.comments.pageInfo.startCursor);
+        rawCommentNodes = [...extra, ...rawCommentNodes];
+    }
+    // Paginate reviews backward if the first page is incomplete.
+    let rawReviewNodes = raw.reviews.nodes;
+    if (raw.reviews.pageInfo.hasPreviousPage && raw.reviews.pageInfo.startCursor) {
+        const extra = await paginateBackward(async (cursor) => {
+            const res = await graphql(BATCH_PR_QUERY, {
+                owner: repo.owner,
+                repo: repo.name,
+                pr,
+                ...(cursor ? { reviewsCursor: cursor } : {}),
+            });
+            const pr2 = res.data.repository.pullRequest;
+            if (!pr2)
+                throw new Error(`PR #${pr} not found`);
+            return pr2.reviews;
+        }, raw.reviews.pageInfo.startCursor);
+        rawReviewNodes = [...extra, ...rawReviewNodes];
+    }
+    // Paginate check contexts forward if the first page is incomplete.
+    let rawCheckNodes = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.nodes ?? [];
+    const checksPageInfo = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.pageInfo;
+    if (checksPageInfo?.hasNextPage && checksPageInfo.endCursor) {
+        // Pass endCursor so paginateForward fetches pages *after* the already-
+        // fetched first page instead of re-fetching it from the start.
+        const extra = await paginateForward(async (cursor) => {
+            const res = await graphql(BATCH_PR_QUERY, {
+                owner: repo.owner,
+                repo: repo.name,
+                pr,
+                ...(cursor ? { checksCursor: cursor } : {}),
+            });
+            const pr2 = res.data.repository.pullRequest;
+            const ctxs = pr2?.commits.nodes[0]?.commit.statusCheckRollup?.contexts;
+            return ctxs ?? { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
+        }, checksPageInfo.endCursor);
+        rawCheckNodes = [...rawCheckNodes, ...extra];
+    }
+    const data = parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawCheckNodes);
+    return { data, rateLimit: result.rateLimit };
+}
+// ---------------------------------------------------------------------------
+// Parsers
+// ---------------------------------------------------------------------------
+function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawCheckNodes) {
+    const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
+        const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
+        return login ? [{ login }] : [];
+    });
+    const latestReviews = (raw.latestReviews?.nodes ?? []).map((n) => ({
+        login: n.author?.login ?? "unknown",
+        state: n.state,
+    }));
+    const reviewThreads = rawThreadPages.map((t) => {
+        const comment = t.comments.nodes[0];
+        return {
+            id: t.id,
+            isResolved: t.isResolved,
+            isOutdated: t.isOutdated,
+            path: comment?.path ?? null,
+            line: comment?.line ?? null,
+            author: comment?.author?.login ?? "unknown",
+            body: comment?.body ?? "",
+            createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
+        };
+    });
+    const comments = rawCommentNodes.map((c) => ({
+        id: c.id,
+        isMinimized: c.isMinimized,
+        author: c.author?.login ?? "unknown",
+        body: c.body,
+        createdAtUnix: parseCreatedAt(c.createdAt),
+    }));
+    const changesRequestedReviews = rawReviewNodes.map((r) => ({
+        id: r.id,
+        author: r.author?.login ?? "unknown",
+        body: r.body,
+    }));
+    const checks = rawCheckNodes.flatMap((node) => {
+        if (node.__typename === "CheckRun") {
+            const event = node.checkSuite?.workflowRun?.event ?? null;
+            const runId = extractRunId(node.detailsUrl);
+            return [
+                {
+                    name: node.name,
+                    status: node.status,
+                    conclusion: node.conclusion,
+                    detailsUrl: node.detailsUrl ?? "",
+                    event,
+                    runId,
+                },
+            ];
+        }
+        if (node.__typename === "StatusContext") {
+            const { status, conclusion } = mapStatusContextState(node.state);
+            return [
+                {
+                    name: node.context,
+                    status,
+                    conclusion,
+                    detailsUrl: node.targetUrl ?? "",
+                    event: null,
+                    runId: null,
+                },
+            ];
+        }
+        return [];
+    });
+    return {
+        number: raw.number,
+        state: raw.state,
+        isDraft: raw.isDraft,
+        mergeable: raw.mergeable,
+        mergeStateStatus: raw.mergeStateStatus,
+        reviewDecision: (raw.reviewDecision ?? null),
+        headRefOid: raw.headRefOid,
+        reviewRequests,
+        latestReviews,
+        reviewThreads,
+        comments,
+        changesRequestedReviews,
+        checks,
+    };
+}
+function parseCreatedAt(iso) {
+    const ms = new Date(iso).getTime();
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
+function extractRunId(url) {
+    if (!url)
+        return null;
+    const m = /\/runs\/(\d+)/.exec(url);
+    return m ? (m[1] ?? null) : null;
+}
+/** Maps a GitHub commit status `state` to CheckRun-compatible status + conclusion. */
+function mapStatusContextState(state) {
+    switch (state) {
+        case "SUCCESS":
+            return { status: "COMPLETED", conclusion: "SUCCESS" };
+        case "FAILURE":
+        case "ERROR":
+            return { status: "COMPLETED", conclusion: "FAILURE" };
+        case "PENDING":
+        case "EXPECTED":
+        default:
+            return { status: "IN_PROGRESS", conclusion: null };
+    }
+}

package/bin/github/client.mjs

@@ -0,0 +1,152 @@
+/**
+ * Thin wrapper around the `gh` CLI for GraphQL and REST calls.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { loadConfig } from "../config/load.mjs";
+const execFile = promisify(execFileCb);
+// ---------------------------------------------------------------------------
+// GraphQL
+// ---------------------------------------------------------------------------
+/**
+ * Execute a GraphQL query via `gh api graphql`.
+ *
+ * @param query   The full GraphQL query/mutation string.
+ * @param vars    Key-value pairs forwarded as `-f key=value` or `-F key=value`.
+ *                Numeric values are passed with `-F`; everything else with `-f`.
+ */
+export async function graphql(query, vars = {}) {
+    const args = buildGraphqlArgs(query, vars);
+    const raw = await runGh(args);
+    const parsed = JSON.parse(raw);
+    if (parsed.errors?.length) {
+        const messages = parsed.errors.map((e) => e.message).join("; ");
+        throw new Error(`GitHub GraphQL error: ${messages}`);
+    }
+    return { data: parsed.data };
+}
+/** Like {@link graphql} but also returns the `x-ratelimit-remaining` header. */
+export async function graphqlWithRateLimit(query, vars = {}) {
+    // --include must come after 'api' (it's a flag for `gh api`, not for `gh`).
+    const [api, ...extraArgs] = buildGraphqlArgs(query, vars);
+    const args = [api, "--include", ...extraArgs];
+    const raw = await runGh(args);
+    // `gh api -i` prepends HTTP headers before the JSON body.
+    // Handle both CRLF (\r\n\r\n) and LF-only (\n\n) header separators.
+    const crlfEnd = raw.indexOf("\r\n\r\n");
+    const lfEnd = raw.indexOf("\n\n");
+    const headerEnd = crlfEnd >= 0 ? crlfEnd : lfEnd;
+    const headerSection = headerEnd >= 0 ? raw.slice(0, headerEnd) : "";
+    const body = headerEnd >= 0 ? raw.slice(headerEnd + (crlfEnd >= 0 ? 4 : 2)) : raw;
+    const remaining = parseHeaderNumber(headerSection, "x-ratelimit-remaining");
+    const limit = parseHeaderNumber(headerSection, "x-ratelimit-limit");
+    const resetAt = parseHeaderNumber(headerSection, "x-ratelimit-reset");
+    const parsed = JSON.parse(body);
+    if (parsed.errors?.length) {
+        const messages = parsed.errors.map((e) => e.message).join("; ");
+        throw new Error(`GitHub GraphQL error: ${messages}`);
+    }
+    return {
+        data: parsed.data,
+        rateLimit: remaining !== null && limit !== null && resetAt !== null
+            ? { remaining, limit, resetAt }
+            : undefined,
+    };
+}
+/** Returns the current repo's owner and name from `gh repo view`. */
+export async function getRepoInfo() {
+    const raw = await runGh(["repo", "view", "--json", "owner,name"]);
+    const parsed = JSON.parse(raw);
+    return { owner: parsed.owner.login, name: parsed.name };
+}
+/**
+ * Derives the PR number for the current HEAD branch.
+ * Returns null if no open PR is found.
+ */
+export async function getCurrentPrNumber() {
+    try {
+        const branch = await getCurrentBranch();
+        // In detached HEAD state git returns "HEAD" — no branch name to look up.
+        if (branch === "HEAD")
+            return null;
+        const raw = await runGh([
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--json",
+            "number",
+            "--jq",
+            ".[0].number",
+        ]);
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed === "null")
+            return null;
+        return parseInt(trimmed, 10);
+    }
+    catch {
+        return null;
+    }
+}
+async function getCurrentBranch() {
+    // Use git directly for branch name — gh doesn't expose it.
+    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+    return stdout.trim();
+}
+/** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
+export async function getPrHeadSha(pr, owner, name) {
+    const raw = await runGh(["api", `repos/${owner}/${name}/pulls/${pr}`, "--jq", ".head.sha"]);
+    return raw.trim();
+}
+/**
+ * Fetches `mergeable` and `mergeStateStatus` via the REST API (`gh pr view`).
+ *
+ * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
+ * a known GitHub quirk where GraphQL lags behind the REST layer.
+ */
+export async function getMergeableState(pr, owner, repo) {
+    const raw = await runGh([
+        "pr",
+        "view",
+        String(pr),
+        "--repo",
+        `${owner}/${repo}`,
+        "--json",
+        "mergeable,mergeStateStatus",
+    ]);
+    const parsed = JSON.parse(raw);
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function buildGraphqlArgs(query, vars) {
+    const args = ["api", "graphql", "-f", `query=${query}`];
+    for (const [k, v] of Object.entries(vars)) {
+        if (typeof v === "number" || typeof v === "boolean") {
+            args.push("-F", `${k}=${String(v)}`);
+        }
+        else {
+            args.push("-f", `${k}=${v}`);
+        }
+    }
+    return args;
+}
+async function runGh(args) {
+    try {
+        const { stdout } = await execFile("gh", args, {
+            maxBuffer: loadConfig().execution.maxBufferMb * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (err) {
+        // Re-throw with a more useful message
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`gh ${args[0] ?? ""} failed: ${msg}`, { cause: err });
+    }
+}
+function parseHeaderNumber(headers, name) {
+    const re = new RegExp(`^${name}:\\s*(\\d+)`, "im");
+    const m = re.exec(headers);
+    return m ? parseInt(m[1], 10) : null;
+}