pr-shepherd 0.40.0 → 0.42.0

package/bin/cli/suggestion-patch-flags.mjs

@@ -0,0 +1,83 @@
+export function parseSuggestionPatchGroups(args) {
+    const parsed = parseFlags(args);
+    if (!parsed.ok)
+        return parsed;
+    return groupFlags(parsed.flags);
+}
+function parseFlags(args) {
+    const flags = [];
+    for (let index = 0; index < args.length;) {
+        const parsed = parseFlag(args, index);
+        if (!parsed)
+            return { ok: false, error: `Unknown argument: ${args[index]}` };
+        flags.push(parsed);
+        index += parsed.consumed;
+    }
+    return { ok: true, flags };
+}
+function groupFlags(flags) {
+    const suggestions = [];
+    let current = null;
+    for (const flag of flags) {
+        if (flag.name === "--thread-id") {
+            const finalized = finalize(current);
+            if (!finalized.ok)
+                return finalized;
+            if (finalized.suggestion)
+                suggestions.push(finalized.suggestion);
+            current = { threadId: flag.value };
+            continue;
+        }
+        const updated = setMetadata(current, flag);
+        if (!updated.ok)
+            return updated;
+        current = updated.current;
+    }
+    const finalized = finalize(current);
+    if (!finalized.ok)
+        return finalized;
+    if (finalized.suggestion)
+        suggestions.push(finalized.suggestion);
+    if (suggestions.length === 0)
+        return { ok: false, error: "At least one --thread-id is required." };
+    return { ok: true, suggestions };
+}
+function setMetadata(current, flag) {
+    if (!current)
+        return { ok: false, error: `${flag.name} must follow --thread-id.` };
+    const property = flag.name === "--message" ? "message" : "description";
+    if (current[property] !== undefined) {
+        return { ok: false, error: `${flag.name} may appear only once per suggestion.` };
+    }
+    return { ok: true, current: { ...current, [property]: flag.value } };
+}
+function parseFlag(args, index) {
+    const arg = args[index];
+    for (const name of ["--thread-id", "--message", "--description"]) {
+        if (arg.startsWith(`${name}=`)) {
+            return { name, value: arg.slice(name.length + 1), consumed: 1 };
+        }
+        if (arg === name && index + 1 < args.length) {
+            return { name, value: args[index + 1], consumed: 2 };
+        }
+    }
+    return null;
+}
+function finalize(current) {
+    if (!current)
+        return { ok: true, suggestion: null };
+    if (!current.threadId || current.threadId.trim() === "") {
+        return { ok: false, error: "--thread-id must be non-empty." };
+    }
+    if (!current.message || current.message.trim() === "") {
+        return { ok: false, error: `--message is required for thread ${current.threadId}.` };
+    }
+    return {
+        ok: true,
+        suggestion: {
+            threadId: current.threadId,
+            message: current.message,
+            ...(current.description !== undefined && { description: current.description }),
+        },
+    };
+}

package/bin/cli-parser.mjs

@@ -8,7 +8,7 @@ import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
-import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
+import { handleClean, handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
@@ -54,7 +54,8 @@ export async function main(argv) {
         resolve: "apply review",
         "mark-files-as-viewed": "apply files",
         journal: "apply journal",
-        "commit-suggestion": "build-suggestion-patch",
+        "build-suggestion-patch": "build-suggestion-patches",
+        "commit-suggestion": "build-suggestion-patches",
     };
     if (subcommand !== undefined && legacyReplacement[subcommand] !== undefined) {
         warnLegacyAlias(subcommand, legacyReplacement[subcommand]);
@@ -71,6 +72,9 @@ export async function main(argv) {
         case "apply":
             await handleApply(args.slice(1));
             break;
+        case "build-suggestion-patches":
+            await handleSuggestionPatches(args.slice(1));
+            break;
         case "build-suggestion-patch":
             await handleCommitSuggestion(args.slice(1));
             break;

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

@@ -1,5 +1,5 @@
 /**
- * Build the `build-suggestion-patch` instruction step for agent consumers.
+ * Build the `build-suggestion-patches` instruction step for agent consumers.
  * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook

package/bin/commands/commit-suggestion-instruction.mjs

@@ -1,6 +1,6 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
- * Build the `build-suggestion-patch` instruction step for agent consumers.
+ * Build the `build-suggestion-patches` instruction step for agent consumers.
  * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
@@ -11,7 +11,7 @@ import { buildPrShepherdCommand } from "../cli/runner.mjs";
  */
 export function buildCommitSuggestionInstruction(prNumber, sectionName) {
     const command = buildPrShepherdCommand([
-        "build-suggestion-patch",
+        "build-suggestion-patches",
         String(prNumber),
         "--thread-id",
         "<id>",
@@ -19,5 +19,5 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName) {
         "<one-sentence headline>",
         "--format=json",
     ]).text;
-    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`, run \`${command}\` and apply the returned patch. See "Suggestion patches" in the pr-shepherd skill for refusals and drift.`;
+    return `For all threads marked \`[suggestion]\` under \`${sectionName}\`, run one \`${command}\` command, repeating the \`--thread-id <id> --message <one-sentence headline>\` group in displayed order, then apply the returned patches in order. See "Suggestion patches" in the pr-shepherd skill for refusals and drift.`;
 }

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. */