pr-shepherd 0.34.0 → 0.36.0

package/bin/github/queries.d.mts

@@ -0,0 +1,28 @@
+/**
+ * GraphQL query strings used by pr-shepherd.
+ *
+ * Static query strings live in src/github/gql/*.gql and are loaded here.
+ * Dynamic documents whose content varies per call (e.g. BulkApply in
+ * src/comments/resolve.mts) are built at runtime and are exempt — they
+ * cannot be expressed as static files.
+ */
+/** The primary batch query that fetches CI + comments + merge status in one round-trip. */
+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;
+/** 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. */
+export declare const CHECK_RUN_ANNOTATIONS_QUERY: string;
+/** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
+export declare const GET_PR_HEAD_SHA_QUERY: string;
+/** Look up PR number by branch name (for getCurrentPrNumber). */
+export declare const PR_NUMBER_BY_BRANCH_QUERY: string;
+/** Convert a draft PR to ready for review. */
+export declare const MARK_PR_READY_MUTATION: string;
+/** Fetch the PR body and node ID. */
+export declare const GET_PR_BODY_QUERY: string;
+/** Update the PR body. */
+export declare const UPDATE_PR_BODY_MUTATION: string;

package/bin/github/queries.mjs

@@ -11,6 +11,10 @@ import { join } from "node:path";
 const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 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");
 /** 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/rest-http.d.mts

@@ -0,0 +1,7 @@
+import { type RateLimitInfo } from "./http-utils.mts";
+export interface RestResult<T = unknown> {
+    data: T;
+    rateLimit?: RateLimitInfo;
+}
+export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+export declare function restWithRateLimit<T = unknown>(method: string, path: string, body?: unknown): Promise<RestResult<T>>;

package/bin/github/rest-http.mjs

@@ -3,10 +3,29 @@ import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
-import { parseRateLimit, parseRetryAfter, redactToken, redactUrl, sanitizeBody, } from "./http-utils.mjs";
+import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
 const BASE_URL = "https://api.github.com";
+const SAFE_GITHUB_REST_PATH = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/?-]*$/;
+function githubApiUrl(path) {
+    if (!SAFE_GITHUB_REST_PATH.test(path) || path.includes("://")) {
+        throw new Error(`Invalid GitHub REST path: ${path}`);
+    }
+    const url = new URL(path, `${BASE_URL}/`);
+    if (url.origin !== BASE_URL) {
+        throw new Error(`Invalid GitHub REST URL origin: ${url.origin}`);
+    }
+    const pathname = path.split("?")[0] ?? path;
+    if (pathname.split("/").some((seg) => seg === ".." || seg === ".")) {
+        throw new Error(`Invalid GitHub REST path: ${path}`);
+    }
+    return url.href;
+}
 export async function rest(method, path, body) {
-    const url = `${BASE_URL}${path}`;
+    const { data } = await restWithRateLimit(method, path, body);
+    return data;
+}
+export async function restWithRateLimit(method, path, body) {
+    const url = githubApiUrl(path);
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "REST", method, url, body }));
     const t0 = performance.now();
@@ -17,6 +36,7 @@ export async function rest(method, path, body) {
     }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "REST", method, url, status, durationMs })));
     const durationMs = Math.round(performance.now() - retryT0);
     const ct = res.headers.get("content-type") ?? "";
+    const rateLimit = parseRateLimit(res.headers) ?? undefined;
     if (!res.ok) {
         const text = await res.text();
         appendEntry(formatResponseEntry({
@@ -31,7 +51,7 @@ export async function rest(method, path, body) {
         }));
         throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
             status: res.status,
-            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            rateLimit,
             retryAfterSeconds: parseRetryAfter(res.headers),
         });
     }
@@ -48,7 +68,7 @@ export async function rest(method, path, body) {
             body: json,
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        return json;
+        return { data: json, rateLimit };
     }
     appendEntry(formatResponseEntry({
         n,
@@ -60,86 +80,5 @@ export async function rest(method, path, body) {
         contentType: ct || undefined,
         attempt: attempt > 1 ? attempt : undefined,
     }));
-    return undefined;
-}
-export async function restText(path) {
-    const url = `${BASE_URL}${path}`;
-    const n = nextEntry();
-    appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
-    const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, { method: "GET", headers: await makeHeaders(), redirect: "manual" }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "restText", method: "GET", url, status, durationMs })));
-    const durationMs = Math.round(performance.now() - retryT0);
-    if ([301, 302, 307, 308].includes(res.status)) {
-        const redirected = await followRestTextRedirect(res, { n, url, durationMs, attempt });
-        if (redirected !== null)
-            return redirected;
-    }
-    if (!res.ok) {
-        const text = await res.text();
-        appendEntry(formatResponseEntry({
-            n,
-            kind: "restText",
-            method: "GET",
-            url,
-            status: res.status,
-            durationMs,
-            attempt: attempt > 1 ? attempt : undefined,
-        }));
-        throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
-            status: res.status,
-            rateLimit: parseRateLimit(res.headers) ?? undefined,
-            retryAfterSeconds: parseRetryAfter(res.headers),
-        });
-    }
-    appendEntry(formatResponseEntry({
-        n,
-        kind: "restText",
-        method: "GET",
-        url,
-        status: res.status,
-        durationMs,
-        contentLength: parseContentLength(res.headers),
-        attempt: attempt > 1 ? attempt : undefined,
-    }));
-    return res.text();
-}
-async function followRestTextRedirect(res, entry) {
-    appendEntry(formatResponseEntry({
-        n: entry.n,
-        kind: "restText",
-        method: "GET",
-        url: entry.url,
-        status: res.status,
-        durationMs: entry.durationMs,
-        attempt: entry.attempt > 1 ? entry.attempt : undefined,
-    }));
-    const location = res.headers.get("location");
-    if (!location)
-        return null;
-    const n2 = nextEntry();
-    const logUrl = redactUrl(location);
-    appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
-    const t1 = performance.now();
-    const redirectRes = await fetch(location);
-    appendEntry(formatResponseEntry({
-        n: n2,
-        kind: "restText",
-        method: "GET",
-        url: logUrl,
-        status: redirectRes.status,
-        durationMs: Math.round(performance.now() - t1),
-        contentLength: parseContentLength(redirectRes.headers),
-    }));
-    if (!redirectRes.ok) {
-        throw new GitHubRequestError(`redirect target ${location} failed: ${redirectRes.status}`, {
-            status: redirectRes.status,
-            rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
-            retryAfterSeconds: parseRetryAfter(redirectRes.headers),
-        });
-    }
-    return redirectRes.text();
-}
-function parseContentLength(headers) {
-    const raw = headers.get("content-length");
-    return raw !== null && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+    return { data: undefined, rateLimit };
 }

package/bin/github/rest-text.d.mts

@@ -0,0 +1 @@
+export declare function restText(path: string): Promise<string>;

package/bin/github/rest-text.mjs

@@ -0,0 +1,88 @@
+import { appendEntry, nextEntry } from "../log/log-file.mjs";
+import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { makeHeaders } from "./http-auth.mjs";
+import { requestWithTokenRetry } from "./http-request.mjs";
+import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody } from "./http-utils.mjs";
+const BASE_URL = "https://api.github.com";
+export async function restText(path) {
+    const url = `${BASE_URL}${path}`;
+    const n = nextEntry();
+    appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
+    const t0 = performance.now();
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, { method: "GET", headers: await makeHeaders(), redirect: "manual" }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "restText", method: "GET", url, status, durationMs })));
+    const durationMs = Math.round(performance.now() - retryT0);
+    if ([301, 302, 307, 308].includes(res.status)) {
+        const redirected = await followRestTextRedirect(res, { n, url, durationMs, attempt });
+        if (redirected !== null)
+            return redirected;
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "restText",
+            method: "GET",
+            url,
+            status: res.status,
+            durationMs,
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
+        throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
+    }
+    appendEntry(formatResponseEntry({
+        n,
+        kind: "restText",
+        method: "GET",
+        url,
+        status: res.status,
+        durationMs,
+        contentLength: parseContentLength(res.headers),
+        attempt: attempt > 1 ? attempt : undefined,
+    }));
+    return res.text();
+}
+async function followRestTextRedirect(res, entry) {
+    appendEntry(formatResponseEntry({
+        n: entry.n,
+        kind: "restText",
+        method: "GET",
+        url: entry.url,
+        status: res.status,
+        durationMs: entry.durationMs,
+        attempt: entry.attempt > 1 ? entry.attempt : undefined,
+    }));
+    const location = res.headers.get("location");
+    if (!location)
+        return null;
+    const n2 = nextEntry();
+    const logUrl = redactUrl(location);
+    appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
+    const t1 = performance.now();
+    const redirectRes = await fetch(location);
+    appendEntry(formatResponseEntry({
+        n: n2,
+        kind: "restText",
+        method: "GET",
+        url: logUrl,
+        status: redirectRes.status,
+        durationMs: Math.round(performance.now() - t1),
+        contentLength: parseContentLength(redirectRes.headers),
+    }));
+    if (!redirectRes.ok) {
+        throw new GitHubRequestError(`redirect target ${logUrl} failed: ${redirectRes.status}`, {
+            status: redirectRes.status,
+            rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(redirectRes.headers),
+        });
+    }
+    return redirectRes.text();
+}
+function parseContentLength(headers) {
+    const raw = headers.get("content-length");
+    return raw !== null && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+}

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

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

package/bin/github/suggestion-thread.mjs

@@ -0,0 +1,45 @@
+import { graphql } from "./client.mjs";
+import { COMMIT_SUGGESTION_THREAD_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, {
+        owner: repo.owner,
+        repo: repo.name,
+        pr,
+        threadId,
+    });
+    const pull = result.data.repository.pullRequest;
+    if (!pull) {
+        throw new Error(`PR #${pr} not found`);
+    }
+    return {
+        headRefOid: pull.headRefOid,
+        headRefName: pull.headRefName,
+        headRepoWithOwner: pull.headRepository?.nameWithOwner ?? null,
+        thread: parseThread(result.data.node, pr, threadId),
+    };
+}
+function parseThread(raw, pr, threadId) {
+    if (!raw?.id || !raw.comments || raw.id !== threadId)
+        return null;
+    if (raw.pullRequest?.number !== pr)
+        return null;
+    const comment = raw.comments.nodes[0];
+    return {
+        id: raw.id,
+        isResolved: raw.isResolved,
+        isOutdated: raw.isOutdated,
+        isMinimized: comment?.isMinimized ?? false,
+        path: raw.path ?? comment?.path ?? null,
+        line: raw.line ?? comment?.line ?? null,
+        startLine: raw.startLine ?? comment?.startLine ?? null,
+        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,
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { RawThread } from "./batch-raw-types.mts";
+export declare function hydrateThreadCommentPages(threads: RawThread[]): Promise<RawThread[]>;

package/bin/github/thread-comments.mjs

@@ -1,22 +1,26 @@
-import { graphql } from "./client.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
 import { paginateForward } from "./pagination.mjs";
 import { REVIEW_THREAD_COMMENTS_QUERY } from "./queries.mjs";
+import { mapPool } from "../util/pool.mjs";
+const THREAD_COMMENT_PAGE_CONCURRENCY = 4;
 export async function hydrateThreadCommentPages(threads) {
-    const hydrated = [];
-    for (const thread of threads) {
-        hydrated.push(await hydrateThreadCommentPage(thread));
-    }
-    return hydrated;
+    const gate = {};
+    return mapPool(threads, THREAD_COMMENT_PAGE_CONCURRENCY, (thread) => hydrateThreadCommentPage(thread, gate));
 }
-async function hydrateThreadCommentPage(thread) {
+async function hydrateThreadCommentPage(thread, gate) {
     const pageInfo = thread.comments.pageInfo;
     if (!pageInfo?.hasNextPage || !pageInfo.endCursor)
         return thread;
     const extra = await paginateForward(async (cursor) => {
-        const res = await graphql(REVIEW_THREAD_COMMENTS_QUERY, {
+        if (gate.remaining === 0) {
+            throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; thread comment pagination incomplete", { status: 403 });
+        }
+        const res = await graphqlWithRateLimit(REVIEW_THREAD_COMMENTS_QUERY, {
             threadId: thread.id,
             ...(cursor ? { commentsCursor: cursor } : {}),
         });
+        gate.remaining = res.rateLimit?.remaining;
         const node = res.data.node;
         if (!node?.comments) {
             const nodeType = node?.__typename ?? "null";

package/bin/index.d.mts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * pr-shepherd — unified GitHub PR status + auto-resolve CLI
+ *
+ * Usage:
+ *   pr-shepherd [PR]
+ *   pr-shepherd apply review [PR]
+ *   pr-shepherd iterate [PR]
+ */
+export {};

package/bin/index.mjs

@@ -4,7 +4,7 @@
  *
  * Usage:
  *   pr-shepherd [PR]
- *   pr-shepherd resolve [PR]
+ *   pr-shepherd apply review [PR]
  *   pr-shepherd iterate [PR]
  */
 import { main } from "./cli-parser.mjs";

package/bin/log/log-file.d.mts

@@ -0,0 +1,28 @@
+/**
+ * Append-only per-worktree markdown log.
+ *
+ * Log path: $PR_SHEPHERD_STATE_DIR/<owner>-<repo>/worktrees/<basename>-<sha8>.md
+ *
+ * Always-on by default. Set PR_SHEPHERD_LOG_DISABLED=1 or CI=true to disable.
+ * Write failures flip an internal disabled flag so the CLI never crashes because
+ * logging failed.
+ */
+/** Returns the next monotonically-increasing entry number for the current session. */
+export declare function nextEntry(): number;
+interface RepoKey {
+    owner: string;
+    repo: string;
+}
+export declare function getLogFilePath(key: RepoKey): string;
+/**
+ * Initialize the log for this process. Must be called before appendEntry().
+ * Silently disables logging on any error (no git repo, bad repo name, etc.).
+ */
+export declare function initLog(repoKey: RepoKey): Promise<string | null>;
+/** Append a pre-formatted markdown chunk to the log. No-op if disabled. */
+export declare function appendEntry(markdown: string): void;
+/** Resolve the log path without initializing (for the log-file subcommand). */
+export declare function resolveLogPath(repoKey: RepoKey): Promise<string>;
+/** Exposed for tests to reset module state. */
+export declare function _resetLogState(): void;
+export {};

package/bin/log/session.d.mts

@@ -0,0 +1,31 @@
+/** Builds the session header markdown block. */
+export declare function buildSessionHeader(argv: string[]): {
+    markdown: string;
+};
+interface HttpRequestEntry {
+    n: number;
+    kind: "GraphQL" | "REST" | "restText";
+    method: string;
+    url: string;
+    body?: unknown;
+}
+interface HttpResponseEntry {
+    n: number;
+    kind: "GraphQL" | "REST" | "restText";
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    /** Parsed response body. Omit for restText. */
+    body?: unknown;
+    /** Raw text response body. Omit for restText. */
+    textBody?: string;
+    contentType?: string;
+    contentLength?: number;
+    /** Set on 401-retry invocations. */
+    attempt?: number;
+}
+export declare function formatRequestEntry(entry: HttpRequestEntry): string;
+export declare function formatResponseEntry(entry: HttpResponseEntry): string;
+export declare function formatOutputEntry(text: string, format: "text" | "json"): string;
+export {};

package/bin/log/setup.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Initialize the per-worktree log, write the session header, and install a
+ * stdout tee that routes all CLI output to the log. No-op after the first call.
+ * Silently skips logging when not in a git repo or on any other error.
+ */
+export declare function setupLog(argv: string[]): Promise<void>;

package/bin/mcp/index.d.mts

@@ -0,0 +1,5 @@
+import { type CreatePrShepherdMcpServerOptions } from "./server.mts";
+export { createPrShepherdMcpServer } from "./server.mts";
+export type { CreatePrShepherdMcpServerOptions } from "./server.mts";
+/** Starts the local stdio-only MCP transport. */
+export declare function runPrShepherdMcpStdio(options?: CreatePrShepherdMcpServerOptions): Promise<void>;

package/bin/mcp/index.mjs

@@ -0,0 +1,8 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createPrShepherdMcpServer } from "./server.mjs";
+export { createPrShepherdMcpServer } from "./server.mjs";
+/** Starts the local stdio-only MCP transport. */
+export async function runPrShepherdMcpStdio(options = {}) {
+    const server = createPrShepherdMcpServer(options);
+    await server.connect(new StdioServerTransport());
+}

package/bin/mcp/server.d.mts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type CreatePrShepherdOptions, type PrShepherd } from "../api.mts";
+export interface CreatePrShepherdMcpServerOptions extends CreatePrShepherdOptions {
+    /** Optional injection point for embedding hosts and focused tests. */
+    shepherd?: PrShepherd;
+}
+/** Creates a local-only MCP server with the three public Shepherd operations. */
+export declare function createPrShepherdMcpServer(options?: CreatePrShepherdMcpServerOptions): McpServer;

package/bin/mcp/server.mjs

@@ -0,0 +1,157 @@
+/* eslint-disable max-lines */
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
+import { formatJournalResult } from "../cli/journal-formatter.mjs";
+import { formatCommitSuggestionResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
+import { errorToExitCode, EXIT } from "../exit-codes.mjs";
+const pr = z.union([z.number().int().positive(), z.string().url()]).optional();
+const ids = z.array(z.string().min(1)).optional();
+const iterateInputSchema = z.object({
+    pr,
+    readyDelaySeconds: z.number().nonnegative().optional(),
+    stallTimeoutSeconds: z.number().nonnegative().optional(),
+    noAutoMarkReady: z.boolean().optional(),
+    noAutoCancelActionable: z.boolean().optional(),
+    neverCancelRuns: z.array(z.string()).optional(),
+});
+const reviewMutationsOperationSchema = z.object({
+    type: z.literal("review_mutations"),
+    resolveThreadIds: ids,
+    replyThreadIds: ids,
+    minimizeCommentIds: ids,
+    dismissReviewIds: ids,
+    message: z.string().optional(),
+    requireSha: z.string().optional(),
+});
+const markFilesViewedOperationSchema = z.object({
+    type: z.literal("mark_files_viewed"),
+    files: z.array(z.string().min(1)).optional(),
+    tests: z.boolean().optional(),
+    matchPatterns: z.array(z.string().min(1)).optional(),
+});
+const appendJournalOperationSchema = z.object({
+    type: z.literal("append_journal"),
+    item: z.string(),
+    dryRun: z.boolean().optional(),
+});
+const applyInputSchema = z.object({
+    pr,
+    operations: z
+        .array(z.discriminatedUnion("type", [
+        reviewMutationsOperationSchema,
+        markFilesViewedOperationSchema,
+        appendJournalOperationSchema,
+    ]))
+        .min(1),
+});
+const suggestionPatchInputSchema = z.object({
+    pr,
+    threadId: z.string().min(1),
+    message: z.string().min(1),
+    description: z.string().optional(),
+});
+/** Creates a local-only MCP server with the three public Shepherd operations. */
+export function createPrShepherdMcpServer(options = {}) {
+    const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
+    const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
+    server.registerTool("iterate", {
+        description: "Inspect the current pull request and return the next Shepherd state.",
+        inputSchema: iterateInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.iterate(input), formatIterateResult));
+    server.registerTool("apply", {
+        description: "Apply ordered review, file-view, and journal operations after prevalidation.",
+        inputSchema: applyInputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.apply(input), formatApplyResult));
+    server.registerTool("build_suggestion_patch", {
+        description: "Build, but never apply, a patch from an eligible review suggestion.",
+        inputSchema: suggestionPatchInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.buildSuggestionPatch(input), formatCommitSuggestionResult));
+    return server;
+}
+function readPackageVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    return packageJson.version;
+}
+function toolResult(result, text) {
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: result,
+    };
+}
+async function runTool(work, format) {
+    try {
+        const result = await work();
+        return toolResult(result, format(result));
+    }
+    catch (error) {
+        return toolError(error);
+    }
+}
+function formatApplyResult(result) {
+    return result.operations
+        .map((operation, index) => {
+        const heading = `## Operation ${index + 1}: ${operation.type}`;
+        switch (operation.type) {
+            case "review_mutations":
+                return `${heading}\n\n${formatMutateResult(operation.result)}`;
+            case "mark_files_viewed":
+                return `${heading}\n\n${formatMarkFilesAsViewedResult(operation.result)}`;
+            case "append_journal":
+                return `${heading}\n\n${formatJournalResult(operation.result)}`;
+        }
+    })
+        .join("\n\n");
+}
+function toolError(error) {
+    const code = error instanceof PrShepherdValidationError
+        ? EXIT.USAGE
+        : error instanceof PartialApplyError
+            ? errorToExitCode(error.cause)
+            : errorToExitCode(error);
+    const details = error instanceof PartialApplyError
+        ? { failedIndex: error.failedIndex, completed: redactValue(error.completed) }
+        : error instanceof PrShepherdValidationError
+            ? { validation: true }
+            : {};
+    const message = redactErrorMessage(error instanceof Error ? error.message : String(error));
+    return {
+        isError: true,
+        content: [{ type: "text", text: `pr-shepherd error (${code}): ${message}` }],
+        structuredContent: { code, message, details },
+    };
+}
+function redactErrorMessage(message) {
+    return message
+        .replace(/(?:ghp|github_pat)_[A-Za-z0-9_]+/g, "[redacted]")
+        .replace(/(authorization:\s*bearer\s+)[^\s]+/gi, "$1[redacted]");
+}
+function redactValue(value) {
+    if (typeof value === "string")
+        return redactErrorMessage(value);
+    if (Array.isArray(value))
+        return value.map(redactValue);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item)]));
+    }
+    return value;
+}

package/bin/mcp-stdio.d.mts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};