pr-shepherd 0.34.0 → 0.35.0

package/bin/config/load.mjs

@@ -1,8 +1,10 @@
+/* eslint-disable max-lines */
 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" };
+import { getEffectiveCwd } from "../execution-context.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
 function findRcFile(startDir) {
@@ -41,6 +43,10 @@ function isMinimizeCommentsPolicy(value) {
     return MINIMIZE_COMMENTS_POLICIES.some((policy) => policy === value);
 }
 function parseMinimizeCommentsPolicy(value) {
+    if (value === "users") {
+        process.stderr.write('pr-shepherd: config: iterate.minimizeComments: "users" is deprecated and is now treated as "none".\n');
+        return "none";
+    }
     if (isMinimizeCommentsPolicy(value))
         return value;
     throw new Error(`Invalid config: iterate.minimizeComments must be one of "all", "bots", "users", or "none", got ${JSON.stringify(value)}`);
@@ -63,10 +69,64 @@ function parseNeverCancelRuns(value) {
     }
     return value;
 }
+const KNOWN_CONFIG_KEYS = new Set([
+    "classify",
+    "botUsernames",
+    "ignoreChecks",
+    "iterate",
+    "watch",
+    "resolve",
+    "checks",
+    "mergeStatus",
+    "actions",
+]);
+const KNOWN_NESTED_KEYS = {
+    iterate: new Set([
+        "fixAttemptsPerThread",
+        "stallTimeoutMinutes",
+        "minimizeApprovals",
+        "minimizeComments",
+        "behindBaseHint",
+    ]),
+    watch: new Set(["readyDelayMinutes"]),
+    resolve: new Set(["shaPoll"]),
+    checks: new Set(["ciTriggerEvents"]),
+    mergeStatus: new Set(["blockingReviewerLogins"]),
+    actions: new Set([
+        "autoMinimizeSuppressed",
+        "autoMarkReady",
+        "neverCancelRuns",
+        "autoResolveOutdated",
+        "commitSuggestions",
+    ]),
+};
+function warnUnknownConfigKeys(config) {
+    for (const key of Object.keys(config)) {
+        if (!KNOWN_CONFIG_KEYS.has(key)) {
+            process.stderr.write(`pr-shepherd: config: unknown key "${key}" ignored.\n`);
+            delete config[key];
+            continue;
+        }
+        const value = config[key];
+        const nested = KNOWN_NESTED_KEYS[key];
+        if (nested === undefined ||
+            value === null ||
+            typeof value !== "object" ||
+            Array.isArray(value)) {
+            continue;
+        }
+        for (const child of Object.keys(value)) {
+            if (!nested.has(child)) {
+                process.stderr.write(`pr-shepherd: config: unknown key "${key}.${child}" ignored.\n`);
+                delete value[child];
+            }
+        }
+    }
+}
 const defaults = builtins;
 const configCache = new Map();
 export function loadConfig() {
-    const cwd = process.cwd();
+    const cwd = getEffectiveCwd();
     if (configCache.has(cwd))
         return configCache.get(cwd);
     const rcPath = findRcFile(cwd);
@@ -77,6 +137,17 @@ export function loadConfig() {
     try {
         const raw = readFileSync(rcPath, "utf8");
         const parsed = (parse(raw) ?? {});
+        const rawActions = parsed.actions;
+        if (rawActions !== null && typeof rawActions === "object" && !Array.isArray(rawActions)) {
+            const actions = rawActions;
+            for (const key of ["autoResolveOutdated", "commitSuggestions"]) {
+                if (key in actions) {
+                    process.stderr.write(`pr-shepherd: config: actions.${key} is deprecated and ignored.\n`);
+                    delete actions[key];
+                }
+            }
+        }
+        warnUnknownConfigKeys(parsed);
         const config = deepMerge(defaults, parsed);
         config.botUsernames = parseBotUsernames(config.botUsernames);
         config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);

package/bin/config.json

@@ -37,10 +37,8 @@
     "blockingReviewerLogins": ["copilot"]
   },
   "actions": {
-    "autoResolveOutdated": true,
     "autoMinimizeSuppressed": true,
     "autoMarkReady": true,
-    "commitSuggestions": true,
     "neverCancelRuns": []
   }
 }

package/bin/execution-context.d.mts

@@ -0,0 +1,9 @@
+/**
+ * Runs work with an optional working directory without changing Node's global
+ * process state. This keeps independent API/MCP requests safe to run together.
+ */
+export declare function runWithExecutionCwd<T>(cwd: string | undefined, work: () => T): T;
+/** The caller-scoped working directory, when one was supplied. */
+export declare function getExecutionCwd(): string | undefined;
+/** The caller-scoped working directory, falling back to the CLI process cwd. */
+export declare function getEffectiveCwd(): string;

package/bin/execution-context.mjs

@@ -0,0 +1,19 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const executionContext = new AsyncLocalStorage();
+/**
+ * Runs work with an optional working directory without changing Node's global
+ * process state. This keeps independent API/MCP requests safe to run together.
+ */
+export function runWithExecutionCwd(cwd, work) {
+    if (cwd === undefined)
+        return work();
+    return executionContext.run({ cwd }, work);
+}
+/** The caller-scoped working directory, when one was supplied. */
+export function getExecutionCwd() {
+    return executionContext.getStore()?.cwd;
+}
+/** The caller-scoped working directory, falling back to the CLI process cwd. */
+export function getEffectiveCwd() {
+    return getExecutionCwd() ?? process.cwd();
+}

package/bin/exit-codes.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Process exit codes for the pr-shepherd CLI.
+ *
+ * Three bands:
+ *   0        done — shepherd finished and the PR is in a good terminal state
+ *   10-19    shepherd RAN successfully; the code reports PR state
+ *   64-78    shepherd FAILED (BSD `sysexits.h` codes)
+ *
+ * Caller rule: `$? >= 64` means shepherd itself failed. `0` or `10-19` means it
+ * ran to completion and is reporting PR state. See docs/exit-codes.md.
+ */
+import type { IterateResult } from "./types.mts";
+export declare const EXIT: Readonly<{
+    /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
+    readonly OK: 0;
+    /** Nothing to do yet; CI still in progress. */
+    readonly WAIT: 10;
+    /** Draft PR converted to ready for review. */
+    readonly MARK_READY: 11;
+    /** Agent work required. */
+    readonly FIX_CODE: 12;
+    /** Human attention required. */
+    readonly ESCALATE: 13;
+    /** `cancel` + `closed` — PR closed without merging. */
+    readonly CLOSED: 14;
+    /** Bad/unknown flag, unknown subcommand, missing required arg, invalid duration. */
+    readonly USAGE: 64;
+    /** Malformed caller data: bad `--require-sha`, `PRRC_*` IDs, bad repo string. */
+    readonly DATAERR: 65;
+    /** Input file/stdin could not be read. */
+    readonly NOINPUT: 66;
+    /** Precondition unmet: no open PR for branch, thread not eligible, unclassified 4xx. */
+    readonly UNAVAILABLE: 69;
+    /** Unexpected/unclassified internal error — the fallback. */
+    readonly SOFTWARE: 70;
+    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, `Retry-After` present. */
+    readonly TEMPFAIL: 75;
+    /** GitHub 401/403 — missing token or insufficient PAT scopes. */
+    readonly NOPERM: 77;
+    /** `.pr-shepherdrc.yml` validation failure. */
+    readonly CONFIG: 78;
+}>;
+/** An error that carries its own exit code, so the top-level handler doesn't have to guess. */
+export declare class ShepherdError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number, opts?: {
+        cause?: unknown;
+    });
+}
+export declare function iterateResultToExitCode(result: IterateResult): number;
+export declare function errorToExitCode(err: unknown): number;

package/bin/github/activity.d.mts

@@ -0,0 +1,3 @@
+import type { PrActivitySummary, PrComment, Review, ReviewThread } from "../types.mts";
+import type { RawPr } from "./batch-raw-types.mts";
+export declare function buildPrActivitySummary(raw: RawPr, comments: PrComment[], reviewThreads: ReviewThread[], reviewSummaries: Review[], changesRequestedReviews: Review[], approvedReviews: Review[]): PrActivitySummary;

package/bin/github/activity.mjs

@@ -8,6 +8,7 @@ function reviewActivityItems(reviews, latestCommitCommittedAtUnix, kind) {
         id: r.id,
         author: r.author,
         authorType: r.authorType,
+        ...(r.authorAssociation !== undefined && { authorAssociation: r.authorAssociation }),
         body: r.body,
         createdAtUnix: r.createdAtUnix ?? 0,
     }));
@@ -26,6 +27,9 @@ export function buildPrActivitySummary(raw, comments, reviewThreads, reviewSumma
                 id: c.id,
                 author: c.author,
                 authorType: c.authorType,
+                ...(c.authorAssociation !== undefined && {
+                    authorAssociation: c.authorAssociation,
+                }),
                 body: c.body,
                 url: c.url,
                 createdAtUnix: c.createdAtUnix,
@@ -37,6 +41,9 @@ export function buildPrActivitySummary(raw, comments, reviewThreads, reviewSumma
                 id: c.id,
                 author: c.author,
                 authorType: c.authorType,
+                ...(c.authorAssociation !== undefined && {
+                    authorAssociation: c.authorAssociation,
+                }),
                 body: c.body,
                 url: c.url,
                 createdAtUnix: c.createdAtUnix,

package/bin/github/batch-parser-helpers.d.mts

@@ -0,0 +1,22 @@
+import type { AuthorType, CheckConclusion, CheckRun, CheckStatus, Review, ReviewThread } from "../types.mts";
+import type { RawContextNode } from "./batch-raw-types.mts";
+export declare function mapAuthorType(typeName: string | undefined | null, login?: string | undefined | null): AuthorType;
+export declare function parseCreatedAt(iso: string): number;
+/** Map a GraphQL CheckRun context node to a CheckRun. */
+export declare function mapCheckRunNode(node: Extract<RawContextNode, {
+    __typename: "CheckRun";
+}>): CheckRun;
+export declare function latestApprovedLogins(latest: Array<{
+    login: string;
+    state: string;
+}>): Set<string>;
+/**
+ * A CR review is stale when its commit.oid differs from the PR head AND every
+ * associated review thread is resolved or outdated. Reviews with no associated
+ * threads are treated conservatively (not marked stale).
+ */
+export declare function isReviewStale(review: Review, headRefOid: string, reviewThreads: ReviewThread[]): boolean;
+export declare function mapStatusContextState(state: string): {
+    status: CheckStatus;
+    conclusion: CheckConclusion;
+};

package/bin/github/batch-parsers.d.mts

@@ -0,0 +1,3 @@
+import type { BatchPrData } from "../types.mts";
+import type { RawPr, RawThread, RawComment, RawReview, RawReviewSummary, RawContextNode } from "./batch-raw-types.mts";
+export declare function parseRawPr(raw: RawPr, rawThreadPages: RawThread[], rawCommentNodes: RawComment[], rawReviewNodes: RawReview[], rawReviewSummaryNodes: RawReviewSummary[], rawApprovedReviewNodes: RawReviewSummary[], rawCheckNodes: RawContextNode[]): BatchPrData;

package/bin/github/batch-parsers.mjs

@@ -6,6 +6,7 @@ function parseReviewNode(r) {
         id: r.id,
         author: r.author?.login ?? "unknown",
         authorType: mapAuthorType(r.author?.__typename, r.author?.login),
+        ...(r.authorAssociation !== undefined && { authorAssociation: r.authorAssociation }),
         body: r.body,
         createdAtUnix: r.createdAt ? parseCreatedAt(r.createdAt) : 0,
     };
@@ -32,6 +33,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             ...(c.pullRequestReview?.id ? { reviewId: c.pullRequestReview.id } : undefined),
             author: c.author?.login ?? "unknown",
             authorType: mapAuthorType(c.author?.__typename, c.author?.login),
+            ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
             body: c.body,
             url: c.url,
             createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,
@@ -47,6 +49,9 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             ...(comment?.pullRequestReview?.id ? { reviewId: comment.pullRequestReview.id } : undefined),
             author: comment?.author?.login ?? "unknown",
             authorType: mapAuthorType(comment?.author?.__typename, comment?.author?.login),
+            ...(comment?.authorAssociation !== undefined && {
+                authorAssociation: comment.authorAssociation,
+            }),
             body: comment?.body ?? "",
             url: comment?.url ?? "",
             createdAtUnix: comment?.createdAt ? parseCreatedAt(comment.createdAt) : 0,
@@ -58,6 +63,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         isMinimized: c.isMinimized,
         author: c.author?.login ?? "unknown",
         authorType: mapAuthorType(c.author?.__typename, c.author?.login),
+        ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
         body: c.body,
         url: c.url,
         createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,

package/bin/github/batch-raw-types.d.mts

@@ -0,0 +1,207 @@
+import type { CommentAuthorAssociation } from "../types/github.mts";
+export interface RawBatchResponse {
+    repository: {
+        pullRequest: RawPr | null;
+    } | null;
+}
+export interface RawPr {
+    id: string;
+    number: number;
+    state: string;
+    isDraft: boolean;
+    mergeable: string;
+    mergeStateStatus: string;
+    reviewDecision: string | null;
+    headRefOid: string;
+    headRefName: string;
+    headRepository: {
+        nameWithOwner: string;
+    } | null;
+    baseRefName: string;
+    baseRef: {
+        branchProtectionRule: RawBranchProtectionRule | null;
+    } | null;
+    reviewRequests: {
+        nodes: Array<{
+            requestedReviewer: {
+                login?: string;
+                name?: string;
+            } | null;
+        }>;
+    };
+    latestReviews: {
+        nodes: Array<{
+            author: RawAuthor | null;
+            state: string;
+        }>;
+    };
+    reviewThreads: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawThread[];
+    };
+    comments: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawComment[];
+    };
+    changesRequestedReviews: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawReview[];
+    };
+    reviewSummaries: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawReviewSummary[];
+    };
+    allReviews?: {
+        totalCount: number;
+    };
+    approvedReviews: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawReviewSummary[];
+    };
+    commits: {
+        totalCount?: number;
+        nodes: Array<{
+            commit: {
+                oid: string;
+                committedDate?: string;
+                statusCheckRollup: {
+                    contexts: {
+                        pageInfo: {
+                            hasNextPage: boolean;
+                            endCursor: string | null;
+                        };
+                        nodes: Array<RawContextNode | null>;
+                    };
+                } | null;
+            };
+        }>;
+    };
+}
+interface RawAuthor {
+    __typename?: string;
+    login: string;
+}
+export interface RawThreadComment {
+    id: string;
+    isMinimized: boolean;
+    url: string;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    pullRequestReview?: {
+        id: string;
+    } | null;
+    body: string;
+    path: string | null;
+    line: number | null;
+    startLine: number | null;
+    createdAt?: string;
+}
+export interface RawThread {
+    id: string;
+    isResolved: boolean;
+    isOutdated: boolean;
+    path?: string | null;
+    line?: number | null;
+    startLine?: number | null;
+    comments: {
+        pageInfo?: {
+            hasNextPage: boolean;
+            endCursor: string | null;
+        };
+        nodes: RawThreadComment[];
+    };
+}
+export interface RawReviewThreadCommentsResponse {
+    node: {
+        __typename?: string;
+        comments: {
+            pageInfo: {
+                hasNextPage: boolean;
+                endCursor: string | null;
+            };
+            nodes: RawThreadComment[];
+        } | null;
+    } | null;
+}
+export interface RawComment {
+    id: string;
+    isMinimized: boolean;
+    url: string;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    body: string;
+    createdAt?: string;
+}
+export interface RawReview {
+    id: string;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    body: string;
+    createdAt?: string;
+    commit?: {
+        oid: string;
+    };
+}
+export interface RawReviewSummary {
+    id: string;
+    isMinimized: boolean;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    body: string;
+    createdAt?: string;
+}
+interface RawBranchProtectionRule {
+    requiresApprovingReviews: boolean;
+    requiredApprovingReviewCount: number;
+    requiresConversationResolution: boolean;
+    requiresStatusChecks: boolean;
+    requiredStatusCheckContexts: string[] | null;
+}
+export type RawContextNode = {
+    __typename: "CheckRun";
+    id: string;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    detailsUrl: string | null;
+    completedAt?: string | null;
+    startedAt?: string | null;
+    title: string | null;
+    summary: string | null;
+    checkSuite: {
+        createdAt?: string;
+        updatedAt?: string;
+        workflowRun: {
+            event: string;
+            createdAt?: string;
+            updatedAt?: string;
+            workflow?: {
+                name: string;
+                databaseId?: number | null;
+            } | null;
+        } | null;
+    } | null;
+} | {
+    __typename: "StatusContext";
+    context: string;
+    state: string;
+    createdAt?: string;
+    targetUrl: string | null;
+    description: string | null;
+};
+export {};

package/bin/github/batch-response.d.mts

@@ -0,0 +1,4 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawBatchResponse, RawContextNode, RawPr } from "./batch-raw-types.mts";
+export declare function requireRawPr(response: RawBatchResponse | null | undefined, pr: number, repo: RepoInfo): RawPr;
+export declare function requireContextNodes(nodes: Array<RawContextNode | null>): RawContextNode[];

package/bin/github/batch.d.mts

@@ -0,0 +1,22 @@
+import { type RateLimitInfo, type RepoInfo } from "./client.mts";
+import type { BatchPrData } from "../types.mts";
+interface BatchResult {
+    data: BatchPrData;
+    rateLimit?: RateLimitInfo;
+}
+interface FetchPrBatchOptions {
+    /**
+     * When false (default), the first-page approvedReviews are returned but
+     * backward pagination is skipped. Iterate's approvals-minimize flow sets this
+     * to true only when the user opts in, so long-lived PRs with > 50 approvals
+     * don't pay extra GraphQL round-trips per iterate call for data no consumer
+     * currently uses. The first page is free — already inside the one batch
+     * request — so there's no need to conditionally omit the field itself.
+     */
+    paginateApprovedReviews?: boolean;
+}
+/**
+ * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
+ */
+export declare function fetchPrBatch(pr: number, repo: RepoInfo, opts?: FetchPrBatchOptions): Promise<BatchResult>;
+export {};

package/bin/github/branch-protection.d.mts

@@ -0,0 +1,3 @@
+import type { BatchPrData } from "../types.mts";
+import type { RawPr } from "./batch-raw-types.mts";
+export declare function parseBranchProtection(raw: RawPr): BatchPrData["branchProtection"];

package/bin/github/check-annotations.d.mts

@@ -0,0 +1,2 @@
+import type { CheckAnnotation } from "../types.mts";
+export declare function fetchCheckRunAnnotations(checkRunId: string): Promise<CheckAnnotation[]>;

package/bin/github/client.d.mts

@@ -0,0 +1,46 @@
+/**
+ * High-level GitHub client — wraps http.mts for application-level concerns.
+ *
+ * All GitHub I/O goes through native fetch (via http.mts); the `gh` CLI is no
+ * longer used for GitHub API calls, but may be invoked as an auth-token
+ * fallback via `gh auth token` when neither GH_TOKEN nor GITHUB_TOKEN is set.
+ */
+import type { MergeableState, MergeStateStatus } from "../types.mts";
+export type { RateLimitInfo } from "./http.mts";
+export { graphql, graphqlWithRateLimit } from "./http.mts";
+export interface RepoInfo {
+    owner: string;
+    name: string;
+}
+/**
+ * Returns the current repo's owner and name by parsing `git remote get-url origin`.
+ * Handles https://, git@, and ssh:// remote URL formats.
+ */
+export declare function getRepoInfo(): Promise<RepoInfo>;
+/**
+ * Derives the PR number for the current HEAD branch.
+ * Returns null if no open PR is found.
+ */
+export declare function getCurrentPrNumber(): Promise<number | null>;
+/** Returns the PR number for a given branch, or null if no open PR is found. */
+export declare function getPrNumberForBranch(branch: string, owner: string, repo: string): Promise<number | null>;
+/** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
+export declare function getPrHeadSha(pr: number, owner: string, name: string): Promise<string>;
+/** Fetches the node ID and body text for a PR. GitHub returns null body for empty bodies — coerced to "". */
+export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
+    nodeId: string;
+    body: string;
+}>;
+/** Overwrites the PR body. */
+export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;
+/**
+ * Fetches `mergeable` and `mergeStateStatus` via the REST API.
+ *
+ * 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 declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+}>;
+export declare function getCurrentBranch(): Promise<string>;

package/bin/github/client.mjs

@@ -9,6 +9,7 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { graphql as httpGraphql, rest } from "./http.mjs";
 import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY, GET_PR_BODY_QUERY, UPDATE_PR_BODY_MUTATION, } from "./queries.mjs";
+import { getExecutionCwd } from "../execution-context.mjs";
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
 // GraphQL — thin re-exports so callers don't need to import http.mts directly
@@ -19,7 +20,9 @@ export { graphql, graphqlWithRateLimit } from "./http.mjs";
  * Handles https://, git@, and ssh:// remote URL formats.
  */
 export async function getRepoInfo() {
-    const { stdout } = await execFile("git", ["remote", "get-url", "origin"]);
+    const { stdout } = await execFile("git", ["remote", "get-url", "origin"], {
+        cwd: getExecutionCwd(),
+    });
     const url = stdout.trim();
     return parseRemoteUrl(url);
 }
@@ -95,7 +98,9 @@ export async function getMergeableState(pr, owner, repo) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 export async function getCurrentBranch() {
-    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: getExecutionCwd(),
+    });
     return stdout.trim();
 }
 function parseRemoteUrl(url) {

package/bin/github/errors.d.mts

@@ -0,0 +1,25 @@
+import { ShepherdError } from "../exit-codes.mts";
+import type { RateLimitInfo } from "./http.mts";
+export interface GitHubGraphQlError {
+    message: string;
+    path?: unknown;
+}
+export declare class GitHubRequestError extends ShepherdError {
+    readonly status: number;
+    readonly rateLimit?: RateLimitInfo;
+    readonly retryAfterSeconds?: number;
+    readonly graphqlErrors?: GitHubGraphQlError[];
+    constructor(message: string, opts: {
+        status: number;
+        rateLimit?: RateLimitInfo;
+        retryAfterSeconds?: number;
+        graphqlErrors?: GitHubGraphQlError[];
+        /**
+         * Bypasses status-based classification entirely — for callers that already
+         * know the failure kind better than the HTTP status can express (e.g. a
+         * response that failed to parse at all, which is an internal failure, not
+         * an availability or permission problem).
+         */
+        exitCodeOverride?: number;
+    });
+}