pr-shepherd 0.41.0 → 0.42.0

package/bin/commands/commit-suggestion.d.mts

@@ -4,5 +4,5 @@ export interface CommitSuggestionOptions extends GlobalOptions {
     message: string;
     description?: string;
 }
-/** @deprecated Hidden implementation for `commit-suggestion`; use `build-suggestion-patch`. */
+/** @deprecated Use runSuggestionPatches. */
 export declare function runCommitSuggestion(opts: CommitSuggestionOptions): Promise<CommitSuggestionResult>;

package/bin/commands/commit-suggestion.mjs

@@ -1,143 +1,24 @@
-import { execFile as execFileCb } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
-import { promisify } from "node:util";
-import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
-import { fetchSuggestionThread } from "../github/suggestion-thread.mjs";
-import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
-import { buildUnifiedDiff } from "../suggestions/patch.mjs";
-import { getUnsafeSuggestionRangeReason } from "../suggestions/range.mjs";
-import { EXIT, ShepherdError } from "../exit-codes.mjs";
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
-import { getEffectiveCwd, getExecutionCwd } from "../execution-context.mjs";
-const execFile = promisify(execFileCb);
-/** @deprecated Hidden implementation for `commit-suggestion`; use `build-suggestion-patch`. */
+import { buildSingularInstructions } from "./suggestion-patch-item.mjs";
+import { runSuggestionPatches } from "./suggestion-patches.mjs";
+/** @deprecated Use runSuggestionPatches. */
 export async function runCommitSuggestion(opts) {
-    if (!opts.threadId) {
-        throw new ShepherdError("--thread-id is required", EXIT.USAGE);
-    }
-    if (!opts.message || opts.message.trim() === "") {
-        throw new ShepherdError("--message is required and must be non-empty", EXIT.USAGE);
-    }
-    const repo = await getRepoInfo();
-    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (prNumber === null) {
-        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
-    }
-    const currentBranch = await getCurrentBranch();
-    const { stdout: localHeadOut } = await execFile("git", ["rev-parse", "HEAD"], {
-        cwd: getExecutionCwd(),
+    const result = await runSuggestionPatches({
+        prNumber: opts.prNumber,
+        format: opts.format,
+        verbose: opts.verbose,
+        suggestions: [
+            {
+                threadId: opts.threadId,
+                message: opts.message,
+                ...(opts.description !== undefined && { description: opts.description }),
+            },
+        ],
     });
-    const localHeadSha = localHeadOut.trim();
-    const data = await fetchSuggestionThread(prNumber, repo, opts.threadId);
-    if (!data.headRepoWithOwner) {
-        throw new ShepherdError(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`, EXIT.UNAVAILABLE);
-    }
-    if (currentBranch !== data.headRefName) {
-        throw new ShepherdError(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
-            `Check out "${data.headRefName}" before applying suggestions.`, EXIT.UNAVAILABLE);
-    }
-    if (localHeadSha !== data.headRefOid) {
-        throw new ShepherdError(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
-            `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`, EXIT.UNAVAILABLE);
-    }
-    const thread = data.thread;
-    if (!thread) {
-        throw new ShepherdError(`Thread ${opts.threadId} not found on PR #${prNumber}.`, EXIT.UNAVAILABLE);
-    }
-    if (thread.isResolved) {
-        throw new ShepherdError(`Thread ${opts.threadId} is already resolved.`, EXIT.UNAVAILABLE);
-    }
-    if (thread.isOutdated) {
-        throw new ShepherdError(`Thread ${opts.threadId} is outdated.`, EXIT.UNAVAILABLE);
-    }
-    if (thread.isMinimized) {
-        throw new ShepherdError(`Thread ${opts.threadId} is minimized.`, EXIT.UNAVAILABLE);
-    }
-    if (!thread.path || thread.line === null) {
-        throw new ShepherdError(`Thread ${opts.threadId} has no file/line anchor.`, EXIT.UNAVAILABLE);
-    }
-    // Validate the target file is clean before generating the patch, so the emitted
-    // `git add -- <file>` instruction cannot accidentally stage unrelated local edits.
-    const { stdout: fileStatus } = await execFile("git", ["status", "--porcelain", "--", thread.path], { cwd: getExecutionCwd() });
-    if (fileStatus.trim() !== "") {
-        throw new ShepherdError(`${thread.path} has uncommitted changes. Commit or stash them before running build-suggestion-patch.`, EXIT.UNAVAILABLE);
-    }
-    const parsed = parseSuggestion(thread.body);
-    if (!parsed) {
-        throw new ShepherdError(`Thread ${opts.threadId} has no suggestion block in the comment body.`, EXIT.UNAVAILABLE);
-    }
-    if (!isCommittableSuggestion(parsed)) {
-        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
-            `3+ backtick fences — refusing to apply (could silently truncate).`, EXIT.UNAVAILABLE);
-    }
-    const startLine = thread.startLine ?? thread.line;
-    const endLine = thread.line;
-    const filePath = thread.path;
-    const cwd = getEffectiveCwd();
-    const resolvedPath = resolve(cwd, filePath);
-    const rel = relative(cwd, resolvedPath);
-    if (rel.startsWith("..") || rel === "") {
-        throw new ShepherdError(`Thread ${opts.threadId} path escapes the working tree.`, EXIT.UNAVAILABLE);
-    }
-    const originalContent = await readFile(resolvedPath, "utf8");
-    const unsafeRangeReason = getUnsafeSuggestionRangeReason({
-        originalContent,
-        startLine,
-        endLine,
-        replacementLines: parsed.lines,
-    });
-    if (unsafeRangeReason) {
-        const range = startLine === endLine ? `${startLine}` : `${startLine}-${endLine}`;
-        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion does not safely fit GitHub's anchored range ` +
-            `${filePath}:${range}: ${unsafeRangeReason} Refusing to build a patch; inspect the surrounding ` +
-            `source and reviewer intent, then apply the change manually.`, EXIT.UNAVAILABLE);
-    }
-    const patch = buildUnifiedDiff({
-        path: filePath,
-        originalContent,
-        startLine,
-        endLine,
-        replacementLines: parsed.lines,
-    });
-    const coAuthor = `Co-authored-by: ${thread.author} <${thread.author}@users.noreply.github.com>`;
-    const commitBody = opts.description ? `${opts.description}\n\n${coAuthor}` : coAuthor;
-    const commitMessageArg = opts.message;
-    const commitBodyArg = commitBody;
-    const quotedPath = `'${filePath.replace(/'/g, "'\\''")}'`;
-    const range = startLine === endLine ? `line ${startLine}` : `lines ${startLine}–${endLine}`;
-    const sq = (s) => `'${s.replace(/'/g, "'\\''")}'`;
-    const commitCmd = [
-        "git commit",
-        `-m ${sq(commitMessageArg)}`,
-        ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
-    ].join(" ");
-    const resolveCommand = buildPrShepherdCommand([
-        "apply",
-        "review",
-        String(prNumber),
-        "--resolve-thread-ids",
-        opts.threadId,
-    ]).text;
-    const postActionInstructions = [
-        `Apply the patch to \`${filePath}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
-        `Stage the file: \`git add -- ${quotedPath}\``,
-        `Commit: \`${commitCmd}\``,
-        `Resolve the thread on GitHub: \`${resolveCommand}\``,
-        `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
-    ];
+    const patch = result.patches[0];
     return {
-        pr: prNumber,
-        repo: `${repo.owner}/${repo.name}`,
-        threadId: opts.threadId,
-        path: filePath,
-        startLine,
-        endLine,
-        author: thread.author,
-        patch,
-        commitMessage: commitMessageArg,
-        commitBody: commitBodyArg,
-        filesToStage: [filePath],
-        postActionInstructions,
+        ...patch,
+        pr: result.pr,
+        repo: result.repo,
+        postActionInstructions: buildSingularInstructions(patch, result.pr),
     };
 }

package/bin/commands/suggestion-patch-git.d.mts

@@ -0,0 +1,6 @@
+export declare function getLocalHeadSha(): Promise<string>;
+export declare function isAncestor(ancestor: string, descendant: string): Promise<boolean>;
+export declare function readPrHeadFile(headSha: string, path: string): Promise<string>;
+export declare function getPathsStatus(paths: readonly string[]): Promise<string>;
+/** Dry-run an ordered patch stream against the current worktree. */
+export declare function checkPatchesApply(patches: readonly string[]): Promise<void>;

package/bin/commands/suggestion-patch-git.mjs

@@ -0,0 +1,54 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { getExecutionCwd } from "../execution-context.mjs";
+const execFile = promisify(execFileCb);
+export async function getLocalHeadSha() {
+    const { stdout } = await execFile("git", ["rev-parse", "HEAD"], {
+        cwd: getExecutionCwd(),
+    });
+    return stdout.trim();
+}
+export async function isAncestor(ancestor, descendant) {
+    try {
+        await execFile("git", ["merge-base", "--is-ancestor", ancestor, descendant], {
+            cwd: getExecutionCwd(),
+        });
+        return true;
+    }
+    catch (error) {
+        if (isExitCode(error, 1) || isExitCode(error, 128))
+            return false;
+        throw error;
+    }
+}
+export async function readPrHeadFile(headSha, path) {
+    const { stdout } = await execFile("git", ["show", `${headSha}:${path}`], {
+        cwd: getExecutionCwd(),
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    return stdout;
+}
+export async function getPathsStatus(paths) {
+    const { stdout } = await execFile("git", ["status", "--porcelain", "--", ...paths], {
+        cwd: getExecutionCwd(),
+    });
+    return stdout.trim();
+}
+/** Dry-run an ordered patch stream against the current worktree. */
+export function checkPatchesApply(patches) {
+    const input = patches.join("\n");
+    return new Promise((resolve, reject) => {
+        const child = execFileCb("git", // NOSONAR -- resolve git through PATH consistently with all CLI git helpers.
+        ["apply", "--check"], { cwd: getExecutionCwd() }, (error, _stdout, stderr) => {
+            if (!error) {
+                resolve();
+                return;
+            }
+            reject(new Error(stderr.trim() || error.message));
+        });
+        child.stdin.end(input);
+    });
+}
+function isExitCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}

package/bin/commands/suggestion-patch-item.d.mts

@@ -0,0 +1,15 @@
+import type { ReviewThread, SuggestionPatchResult } from "../types.mts";
+export interface SuggestionPatchRequest {
+    threadId: string;
+    message: string;
+    description?: string;
+}
+export declare function validateSuggestionThread(thread: ReviewThread | null, request: SuggestionPatchRequest): ReviewThread;
+export declare function buildSuggestionPatchItem({ thread, request, originalContent, }: {
+    thread: ReviewThread;
+    request: SuggestionPatchRequest;
+    originalContent: string;
+}): SuggestionPatchResult;
+export declare function buildSingularInstructions(patch: SuggestionPatchResult, prNumber: number): string[];
+export declare function buildCommitCommand(patch: SuggestionPatchResult): string;
+export declare function quotePath(path: string): string;

package/bin/commands/suggestion-patch-item.mjs

@@ -0,0 +1,106 @@
+import { relative, resolve } from "node:path";
+import { getEffectiveCwd } from "../execution-context.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
+import { buildUnifiedDiff } from "../suggestions/patch.mjs";
+import { getUnsafeSuggestionRangeReason } from "../suggestions/range.mjs";
+const SINGLE_QUOTE_ESCAPE = String.raw `'\''`;
+export function validateSuggestionThread(thread, request) {
+    if (!thread)
+        unavailable(`Thread ${request.threadId} not found on PR.`);
+    if (thread.isResolved)
+        unavailable(`Thread ${request.threadId} is already resolved.`);
+    if (thread.isOutdated)
+        unavailable(`Thread ${request.threadId} is outdated.`);
+    if (thread.isMinimized)
+        unavailable(`Thread ${request.threadId} is minimized.`);
+    if (!thread.path || thread.line === null) {
+        unavailable(`Thread ${request.threadId} has no file/line anchor.`);
+    }
+    ensureSafePath(thread.path);
+    return thread;
+}
+export function buildSuggestionPatchItem({ thread, request, originalContent, }) {
+    const parsed = parseSuggestion(thread.body);
+    if (!parsed)
+        unavailable(`Thread ${request.threadId} has no suggestion block in the comment body.`);
+    if (!isCommittableSuggestion(parsed)) {
+        unavailable(`Thread ${request.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
+            `3+ backtick fences — refusing to apply (could silently truncate).`);
+    }
+    const startLine = thread.startLine ?? thread.line;
+    const endLine = thread.line;
+    const unsafeRangeReason = getUnsafeSuggestionRangeReason({
+        originalContent,
+        startLine,
+        endLine,
+        replacementLines: parsed.lines,
+    });
+    if (unsafeRangeReason) {
+        const range = startLine === endLine ? `${startLine}` : `${startLine}-${endLine}`;
+        unavailable(`Thread ${request.threadId}'s suggestion does not safely fit GitHub's anchored range ` +
+            `${thread.path}:${range}: ${unsafeRangeReason} Refusing to build a patch; inspect the ` +
+            `surrounding source and reviewer intent, then apply the change manually.`);
+    }
+    const coAuthor = `Co-authored-by: ${thread.author} <${thread.author}@users.noreply.github.com>`;
+    return {
+        threadId: request.threadId,
+        path: thread.path,
+        startLine,
+        endLine,
+        author: thread.author,
+        patch: buildUnifiedDiff({
+            path: thread.path,
+            originalContent,
+            startLine,
+            endLine,
+            replacementLines: parsed.lines,
+        }),
+        commitMessage: request.message,
+        commitBody: request.description ? `${request.description}\n\n${coAuthor}` : coAuthor,
+        filesToStage: [thread.path],
+    };
+}
+export function buildSingularInstructions(patch, prNumber) {
+    const range = patch.startLine === patch.endLine
+        ? `line ${patch.startLine}`
+        : `lines ${patch.startLine}–${patch.endLine}`;
+    const resolveCommand = buildPrShepherdCommand([
+        "apply",
+        "review",
+        String(prNumber),
+        "--resolve-thread-ids",
+        patch.threadId,
+    ]).text;
+    return [
+        `Apply the patch to \`${patch.path}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
+        `Stage the file: \`git add -- ${quotePath(patch.path)}\``,
+        `Commit: \`${buildCommitCommand(patch)}\``,
+        `Resolve the thread on GitHub: \`${resolveCommand}\``,
+        `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
+    ];
+}
+export function buildCommitCommand(patch) {
+    return [
+        "git commit",
+        `-m ${shellQuote(patch.commitMessage)}`,
+        ...patch.commitBody.split("\n\n").map((part) => `-m ${shellQuote(part)}`),
+    ].join(" ");
+}
+export function quotePath(path) {
+    return shellQuote(path);
+}
+function shellQuote(value) {
+    return "'" + value.replaceAll("'", SINGLE_QUOTE_ESCAPE) + "'";
+}
+function ensureSafePath(path) {
+    const cwd = getEffectiveCwd();
+    const rel = relative(cwd, resolve(cwd, path));
+    if (rel.startsWith("..") || rel === "") {
+        unavailable(`Thread path escapes the working tree: ${path}.`);
+    }
+}
+function unavailable(message) {
+    throw new ShepherdError(message, EXIT.UNAVAILABLE);
+}

package/bin/commands/suggestion-patches.d.mts

@@ -0,0 +1,6 @@
+import type { BuildSuggestionPatchesResult, GlobalOptions } from "../types.mts";
+import { type SuggestionPatchRequest } from "./suggestion-patch-item.mts";
+export interface SuggestionPatchesOptions extends GlobalOptions {
+    suggestions: readonly SuggestionPatchRequest[];
+}
+export declare function runSuggestionPatches(opts: SuggestionPatchesOptions): Promise<BuildSuggestionPatchesResult>;

package/bin/commands/suggestion-patches.mjs

@@ -0,0 +1,108 @@
+import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/client.mjs";
+import { fetchSuggestionThreads } from "../github/suggestion-thread.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { buildCommitCommand, buildSuggestionPatchItem, quotePath, validateSuggestionThread, } from "./suggestion-patch-item.mjs";
+import { checkPatchesApply, getLocalHeadSha, getPathsStatus, isAncestor, readPrHeadFile, } from "./suggestion-patch-git.mjs";
+export async function runSuggestionPatches(opts) {
+    validateRequests(opts.suggestions);
+    const repo = await getRepoInfo();
+    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
+    if (prNumber === null) {
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
+    }
+    const [currentBranch, localHeadSha, data] = await Promise.all([
+        getCurrentBranch(),
+        getLocalHeadSha(),
+        fetchSuggestionThreads(prNumber, repo, opts.suggestions.map((suggestion) => suggestion.threadId)),
+    ]);
+    await validateHead({ currentBranch, localHeadSha, prNumber, data });
+    const threads = data.threads.map((thread, index) => validateSuggestionThread(thread, opts.suggestions[index]));
+    const paths = [...new Set(threads.map((thread) => thread.path))];
+    const status = await getPathsStatus(paths);
+    if (status !== "") {
+        throw new ShepherdError(`Suggestion target files have uncommitted changes:\n${status}\n` +
+            "Commit or stash them before running build-suggestion-patches.", EXIT.UNAVAILABLE);
+    }
+    const originals = await readOriginals(data.headRefOid, paths);
+    const patches = threads.map((thread, index) => buildSuggestionPatchItem({
+        thread,
+        request: opts.suggestions[index],
+        originalContent: originals.get(thread.path),
+    }));
+    try {
+        await checkPatchesApply(patches.map((patch) => patch.patch));
+    }
+    catch (error) {
+        throw new ShepherdError(`Ordered suggestion patches built from PR head ${data.headRefOid} do not apply to ` +
+            `local HEAD ${localHeadSha}: ${errorMessage(error)} No patches were returned; inspect the ` +
+            "current source and reviewer intent.", EXIT.UNAVAILABLE);
+    }
+    return {
+        pr: prNumber,
+        repo: `${repo.owner}/${repo.name}`,
+        patches,
+        postActionInstructions: buildBatchInstructions(patches),
+    };
+}
+function validateRequests(requests) {
+    if (requests.length === 0)
+        usage("At least one suggestion is required.");
+    const seen = new Set();
+    for (const request of requests) {
+        if (!request.threadId || request.threadId.trim() === "")
+            usage("Each --thread-id is required.");
+        if (!request.message || request.message.trim() === "") {
+            usage(`--message is required and must be non-empty for thread ${request.threadId}.`);
+        }
+        if (seen.has(request.threadId))
+            usage(`Duplicate thread ID: ${request.threadId}.`);
+        seen.add(request.threadId);
+    }
+}
+async function validateHead({ currentBranch, localHeadSha, prNumber, data, }) {
+    if (!data.headRepoWithOwner) {
+        throw new ShepherdError(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`, EXIT.UNAVAILABLE);
+    }
+    if (currentBranch !== data.headRefName) {
+        throw new ShepherdError(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
+            `Check out "${data.headRefName}" before applying suggestions.`, EXIT.UNAVAILABLE);
+    }
+    if (localHeadSha === data.headRefOid)
+        return;
+    await ensureDescendant(data.headRefOid, localHeadSha, data.headRefName);
+}
+async function ensureDescendant(prHeadSha, localHeadSha, branch) {
+    if (await isAncestor(prHeadSha, localHeadSha))
+        return;
+    throw new ShepherdError(`Local HEAD ${localHeadSha} is not PR head ${prHeadSha} or its descendant. ` +
+        `Pull/rebase "${branch}" to the latest PR head and try again.`, EXIT.UNAVAILABLE);
+}
+async function readOriginals(headSha, paths) {
+    const entries = await Promise.all(paths.map(async (path) => {
+        try {
+            return [path, await readPrHeadFile(headSha, path)];
+        }
+        catch (error) {
+            throw new ShepherdError(`Could not read ${path} at PR head ${headSha}: ${errorMessage(error)}`, EXIT.UNAVAILABLE);
+        }
+    }));
+    return new Map(entries);
+}
+function buildBatchInstructions(patches) {
+    const patchInstructions = patches.flatMap((patch, index) => [
+        `Apply patch ${index + 1} to \`${patch.path}\` using \`git apply\`.`,
+        `Stage patch ${index + 1}: \`git add -- ${quotePath(patch.path)}\``,
+        `Commit patch ${index + 1}: \`${buildCommitCommand(patch)}\``,
+    ]);
+    return [
+        ...patchInstructions,
+        "Push once after every patch is committed: `git push` (or `git push --force-with-lease` after rebasing).",
+        `Then continue with the originating iterate output's \`apply review\` instructions for thread IDs: ${patches.map((patch) => patch.threadId).join(", ")}.`,
+    ];
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function usage(message) {
+    throw new ShepherdError(message, EXIT.USAGE);
+}

package/bin/github/gql/{commit-suggestion-thread.gql → suggestion-threads.gql}

@@ -1,4 +1,4 @@
-query CommitSuggestionThread($owner: String!, $repo: String!, $pr: Int!, $threadId: ID!) {
+query SuggestionThreads($owner: String!, $repo: String!, $pr: Int!, $threadIds: [ID!]!) {
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       headRefOid
@@ -8,7 +8,7 @@ query CommitSuggestionThread($owner: String!, $repo: String!, $pr: Int!, $thread
       }
     }
   }
-  node(id: $threadId) {
+  nodes(ids: $threadIds) {
     ... on PullRequestReviewThread {
       id
       isResolved

package/bin/github/queries.d.mts

@@ -11,7 +11,7 @@ export declare const BATCH_PR_QUERY: string;
 /** Slim @include follow-up for outstanding batch-query connections. */
 export declare const BATCH_PR_PAGE_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
-export declare const COMMIT_SUGGESTION_THREAD_QUERY: string;
+export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;
 /** Fetch inline annotations for a single CheckRun by node ID. */

package/bin/github/queries.mjs

@@ -14,7 +14,7 @@ export const BATCH_PR_QUERY = gql("batch-pr.gql");
 /** Slim @include follow-up for outstanding batch-query connections. */
 export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
 /** PR head fields plus a single review thread for `commit-suggestion`. */
-export const COMMIT_SUGGESTION_THREAD_QUERY = gql("commit-suggestion-thread.gql");
+export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");
 /** Fetch inline annotations for a single CheckRun by node ID. */

package/bin/github/suggestion-thread.d.mts

@@ -1,9 +1,9 @@
 import type { ReviewThread } from "../types.mts";
 import type { RepoInfo } from "./client.mts";
-export interface SuggestionThreadResult {
+export interface SuggestionThreadsResult {
     headRefOid: string;
     headRefName: string;
     headRepoWithOwner: string | null;
-    thread: ReviewThread | null;
+    threads: (ReviewThread | null)[];
 }
-export declare function fetchSuggestionThread(pr: number, repo: RepoInfo, threadId: string): Promise<SuggestionThreadResult>;
+export declare function fetchSuggestionThreads(pr: number, repo: RepoInfo, threadIds: readonly string[]): Promise<SuggestionThreadsResult>;

package/bin/github/suggestion-thread.mjs

@@ -1,12 +1,12 @@
 import { graphql } from "./client.mjs";
-import { COMMIT_SUGGESTION_THREAD_QUERY } from "./queries.mjs";
+import { SUGGESTION_THREADS_QUERY } from "./queries.mjs";
 import { mapAuthorType, parseCreatedAt } from "./batch-parser-helpers.mjs";
-export async function fetchSuggestionThread(pr, repo, threadId) {
-    const result = await graphql(COMMIT_SUGGESTION_THREAD_QUERY, {
+export async function fetchSuggestionThreads(pr, repo, threadIds) {
+    const result = await graphql(SUGGESTION_THREADS_QUERY, {
         owner: repo.owner,
         repo: repo.name,
         pr,
-        threadId,
+        threadIds,
     });
     const pull = result.data.repository.pullRequest;
     if (!pull) {
@@ -16,7 +16,10 @@ export async function fetchSuggestionThread(pr, repo, threadId) {
         headRefOid: pull.headRefOid,
         headRefName: pull.headRefName,
         headRepoWithOwner: pull.headRepository?.nameWithOwner ?? null,
-        thread: parseThread(result.data.node, pr, threadId),
+        threads: threadIds.map((threadId) => {
+            const raw = result.data.nodes.find((candidate) => candidate?.id === threadId) ?? null;
+            return parseThread(raw, pr, threadId);
+        }),
     };
 }
 function parseThread(raw, pr, threadId) {

package/bin/mcp/server.d.mts

@@ -4,5 +4,5 @@ export interface CreatePrShepherdMcpServerOptions extends CreatePrShepherdOption
     /** Optional injection point for embedding hosts and focused tests. */
     shepherd?: PrShepherd;
 }
-/** Creates a local-only MCP server with the three public Shepherd operations. */
+/** Creates a local-only MCP server with Shepherd's public operations. */
 export declare function createPrShepherdMcpServer(options?: CreatePrShepherdMcpServerOptions): McpServer;

package/bin/mcp/server.mjs

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
 import { isRepositoryQualifiedPrReference } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
-import { formatCommitSuggestionResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
+import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
 const pr = z
@@ -57,7 +57,17 @@ const suggestionPatchInputSchema = z.object({
     message: z.string().min(1),
     description: z.string().optional(),
 });
-/** Creates a local-only MCP server with the three public Shepherd operations. */
+const suggestionPatchesInputSchema = z.object({
+    pr,
+    suggestions: z
+        .array(z.object({
+        threadId: z.string().min(1),
+        message: z.string().min(1),
+        description: z.string().optional(),
+    }))
+        .min(1),
+});
+/** Creates a local-only MCP server with Shepherd's public operations. */
 export function createPrShepherdMcpServer(options = {}) {
     const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
@@ -81,8 +91,18 @@ export function createPrShepherdMcpServer(options = {}) {
             openWorldHint: true,
         },
     }, async (input) => runTool(() => shepherd.apply(requireRepositoryQualifiedPr(input)), formatApplyResult));
+    server.registerTool("build_suggestion_patches", {
+        description: "Build, but never apply, an ordered list of eligible review suggestion patches.",
+        inputSchema: suggestionPatchesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
     server.registerTool("build_suggestion_patch", {
-        description: "Build, but never apply, a patch from an eligible review suggestion.",
+        description: "Deprecated: use build_suggestion_patches with a one-item suggestions array.",
         inputSchema: suggestionPatchInputSchema,
         annotations: {
             readOnlyHint: true,

package/bin/types/report.d.mts

@@ -150,25 +150,6 @@ export interface RelevantCheck {
     /** Marker-gated inline annotations from this check. */
     annotations?: CheckAnnotation[];
 }
-export interface CommitSuggestionResult {
-    pr: number;
-    repo: string;
-    threadId: string;
-    path: string;
-    startLine: number;
-    endLine: number;
-    author: string;
-    /** The unified diff generated for this suggestion. */
-    patch: string;
-    /** The commit subject line (user-supplied --message). */
-    commitMessage: string;
-    /** The commit body (optional description + Co-authored-by trailer). */
-    commitBody: string;
-    /** Files the agent should stage before committing. */
-    filesToStage: string[];
-    /** Numbered steps the agent must execute to apply, commit, resolve, and push. */
-    postActionInstructions: string[];
-}
 export interface GlobalOptions {
     prNumber?: number;
     format: "text" | "json";