pr-shepherd 0.34.0 → 0.35.0

package/bin/types/report.d.mts

@@ -0,0 +1,176 @@
+import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, CheckConclusion, SuggestionBlock } from "./github.mts";
+import type { ClassifiedCheck, TriagedCheck } from "./check-classification.mts";
+import type { AgentThreadComment } from "./agent-thread.mts";
+import type { CheckAnnotation } from "./check-annotations.mts";
+import type { PrActivitySummary } from "./activity.mts";
+export interface FirstLookThread extends ReviewThread {
+    firstLookStatus: "outdated" | "resolved" | "minimized";
+    autoResolved?: boolean;
+    edited?: boolean;
+}
+export interface FirstLookComment extends PrComment {
+    firstLookStatus: "minimized";
+    edited?: boolean;
+}
+export type ActionableComment = PrComment & {
+    edited?: boolean;
+};
+export type ShepherdStatus = "MERGED" | "CLOSED" | "READY" | "FAILING" | "PENDING" | "IN_PROGRESS" | "UNRESOLVED_COMMENTS" | "UNKNOWN";
+export interface ShepherdReport {
+    pr: number;
+    /** GitHub node ID of the PR — used for mutations (e.g. markPullRequestReadyForReview). */
+    nodeId: string;
+    repo: string;
+    status: ShepherdStatus;
+    /** PR base branch from the GraphQL batch. */
+    baseBranch: string;
+    mergeStatus: MergeStatusResult;
+    checks: {
+        passing: ClassifiedCheck[];
+        failing: TriagedCheck[];
+        inProgress: ClassifiedCheck[];
+        skipped: ClassifiedCheck[];
+        /** Checks filtered out because they were triggered by a non-PR event (push, schedule, etc.). */
+        filtered: ClassifiedCheck[];
+        filteredNames: string[];
+        blockedByFilteredCheck: boolean;
+        ignoredNames?: string[];
+        supersededNames?: string[];
+    };
+    threads: {
+        actionable: ReviewThread[];
+        /** Unresolved threads that need a GitHub resolve mutation but do not require code edits. */
+        resolutionOnly: ReviewThread[];
+        autoResolved: ReviewThread[];
+        autoResolveErrors: string[];
+        /** First-look items — outdated/resolved/minimized threads not yet seen by the agent. */
+        firstLook: FirstLookThread[];
+        /** Thread IDs matched by user classification rules with autoResolve:true — routed to resolveThreadIds. */
+        ruleAutoResolveIds?: string[];
+    };
+    comments: {
+        actionable: ActionableComment[];
+        /** Visible PR comments that should be passed to `--minimize-comment-ids`. */
+        minimizeIds?: string[];
+        /** First-look items — minimized comments not yet seen by the agent. */
+        firstLook: FirstLookComment[];
+    };
+    changesRequestedReviews: Review[];
+    /** COMMENTED reviews already seen — eligible for `--minimize-comment-ids` without re-rendering. */
+    reviewSummaries: Review[];
+    /** COMMENTED reviews not yet seen — body must be surfaced before minimizing. */
+    firstLookSummaries: Review[];
+    /** COMMENTED reviews whose body changed since last seen — surface updated body, but do NOT re-add to `--minimize-comment-ids`. */
+    editedSummaries: Review[];
+    /** APPROVED reviews not yet minimized — opt-in minimize target. */
+    approvedReviews: Review[];
+    /** COMMENTED review summary IDs matched by user rules with autoResolve:true — minimized without surfacing to agent. */
+    ruleAutoResolveReviewSummaryIds?: string[];
+    /** Branch protection rule for the PR's base branch. Null when no rule exists or the base ref is unavailable. */
+    branchProtection: import("./github.mts").BranchProtection | null;
+    activity?: PrActivitySummary;
+}
+export interface ResolveOptions {
+    resolveThreadIds?: string[];
+    replyThreadIds?: string[];
+    minimizeCommentIds?: string[];
+    dismissReviewIds?: string[];
+    dismissMessage?: string;
+    /** When set, shepherd verifies GitHub has received this commit before resolving. */
+    requireSha?: string;
+}
+export interface AgentThread {
+    id: string;
+    reviewId?: string;
+    path: string | null;
+    line: number | null;
+    startLine?: number;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: import("./github.mts").CommentAuthorAssociation;
+    body: string;
+    url: string;
+    comments?: AgentThreadComment[];
+    suggestion?: SuggestionBlock;
+    edited?: boolean;
+}
+/** Comment shape emitted to the iterate agent — stripped of always-false flags. */
+export interface AgentComment {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: import("./github.mts").CommentAuthorAssociation;
+    body: string;
+    url: string;
+    edited?: boolean;
+}
+/** Check shape emitted to the iterate agent under `fix_code`. Cancelled checks
+ * should be handled from `name`/`runId`/`detailsUrl`/`conclusion`; optional
+ * workflow/job/step metadata may still be present when available. */
+export interface AgentCheck {
+    name: string;
+    runId: string | null;
+    /** Fallback for checks where runId is null (e.g. external status checks). */
+    detailsUrl: string | null;
+    /** Raw GitHub check conclusion; may be null for some completed checks from upstream data. */
+    conclusion: Exclude<CheckConclusion, "SKIPPED" | "NEUTRAL">;
+    /** Workflow display name (e.g. `"CI"`). Populated on a best-effort basis when available from the jobs API. */
+    workflowName?: string;
+    /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from check name for matrix builds. */
+    jobName?: string;
+    /** Name of the first failed step (e.g. `"Run tests"`, `"Set up job"`). */
+    failedStep?: string;
+    /** One-line status text shown in the GitHub UI (e.g. "67.68% of diff hit (target 85.00%)"). */
+    summary?: string;
+    logExcerpt?: string;
+    /** Marker-gated inline annotations from this failing check. */
+    annotations?: CheckAnnotation[];
+}
+/**
+ * A single CI check that is relevant to PR readiness — triggered by a PR event
+ * (or by a StatusContext with null event), completed, and not skipped/neutral.
+ *
+ * Included in every iterate result so the agent always sees the full CI picture
+ * regardless of which action fired.
+ */
+export interface RelevantCheck {
+    name: string;
+    conclusion: Exclude<CheckConclusion, "SKIPPED" | "NEUTRAL" | null>;
+    runId: string | null;
+    detailsUrl: string | null;
+    /** Workflow display name (e.g. `"CI"`). Available for all checks with a runId. */
+    workflowName?: string;
+    /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from check name for matrix builds. */
+    jobName?: string;
+    /** Name of the first failed step in the matched job. */
+    failedStep?: string;
+    /** One-line status text shown in the GitHub UI (e.g. "67.68% of diff hit (target 85.00%)"). */
+    summary?: string;
+    logExcerpt?: string;
+    /** 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";
+    verbose?: boolean;
+}

package/bin/types/review-thread.d.mts

@@ -0,0 +1,12 @@
+import type { AuthorType, CommentAuthorAssociation } from "./github.mts";
+export interface ReviewThreadComment {
+    id: string;
+    isMinimized: boolean;
+    reviewId?: string;
+    author: string;
+    authorType: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    url: string;
+    createdAtUnix: number;
+}

package/bin/types.d.mts

@@ -0,0 +1,9 @@
+/** Shared type definitions for the shepherd CLI. */
+export * from "./types/github.mts";
+export * from "./types/check-classification.mts";
+export * from "./types/activity.mts";
+export * from "./types/review-thread.mts";
+export * from "./types/agent-thread.mts";
+export * from "./types/check-annotations.mts";
+export * from "./types/report.mts";
+export * from "./types/iterate.mts";

package/bin/util/markdown.d.mts

@@ -0,0 +1 @@
+export declare function joinSections(sections: (string | null | undefined)[]): string;

package/bin/util/path-segment.d.mts

@@ -0,0 +1,2 @@
+/** Allowed characters: alphanumeric, hyphen, underscore, dot. Prevents path traversal. */
+export declare const SAFE_SEGMENT: RegExp;

package/bin/util/sleep.d.mts

@@ -0,0 +1 @@
+export declare function sleep(ms: number): Promise<void>;

package/bin/util/worktree.d.mts

@@ -0,0 +1,9 @@
+/** Returns the absolute path to the current git worktree root. Throws outside a git repo. */
+export declare function getWorktreeRoot(): Promise<string>;
+/**
+ * Returns a filesystem-safe key for the current worktree, unique across
+ * worktrees of the same repo. Format: `<basename>-<sha8>` where sha8 is
+ * the first 8 hex chars of sha256(toplevel). Falls back to sha8-only if
+ * the basename contains characters outside SAFE_SEGMENT.
+ */
+export declare function getWorktreeKey(): Promise<string>;

package/bin/util/worktree.mjs

@@ -3,10 +3,13 @@ import { promisify } from "node:util";
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
 import { SAFE_SEGMENT } from "./path-segment.mjs";
+import { getExecutionCwd } from "../execution-context.mjs";
 const execFile = promisify(execFileCb);
 /** Returns the absolute path to the current git worktree root. Throws outside a git repo. */
 export async function getWorktreeRoot() {
-    const { stdout } = await execFile("git", ["rev-parse", "--show-toplevel"]);
+    const { stdout } = await execFile("git", ["rev-parse", "--show-toplevel"], {
+        cwd: getExecutionCwd(),
+    });
     return stdout.trim();
 }
 /**

package/package.json

@@ -1,48 +1,60 @@
 {
   "name": "pr-shepherd",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
+  "keywords": [
+    "automation",
+    "ci",
+    "claude",
+    "claude-code",
+    "code-review",
+    "codex",
+    "github",
+    "pull-request"
+  ],
+  "homepage": "https://github.com/jonathanong/pr-shepherd",
+  "bugs": {
+    "url": "https://github.com/jonathanong/pr-shepherd/issues"
+  },
   "license": "MIT",
   "author": "Jonathan Ong",
-  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jonathanong/pr-shepherd.git"
+  },
   "bin": {
-    "pr-shepherd": "bin/index.mjs"
+    "pr-shepherd": "bin/index.mjs",
+    "pr-shepherd-mcp": "bin/mcp-stdio.mjs"
   },
   "files": [
     "bin/**",
+    "plugins/**/.mcp.json",
+    "plugins/**/.codex.mcp.json",
     "src/classify/types.mts",
     "plugins/**",
     "plugins/**/.codex-plugin/**",
     ".claude-plugin/**",
+    ".grok-plugin/**",
     ".agents/plugins/marketplace.json",
     "marketplace.json",
     "README.md",
     "LICENSE"
   ],
-  "engines": {
-    "node": ">=22.18.0"
-  },
-  "dependencies": {
-    "picomatch": "^4.0.4",
-    "yaml": "^2.7.0"
-  },
+  "type": "module",
   "exports": {
+    ".": {
+      "types": "./bin/api.d.mts",
+      "default": "./bin/api.mjs"
+    },
+    "./mcp": {
+      "types": "./bin/mcp/index.d.mts",
+      "default": "./bin/mcp/index.mjs"
+    },
     "./classify": {
       "types": "./src/classify/types.mts",
       "default": "./bin/classify/types.mjs"
     }
   },
-  "devDependencies": {
-    "@types/node": "^26.0.0",
-    "@types/picomatch": "^4.0.3",
-    "@vitest/coverage-v8": "^4.1.4",
-    "husky": "^9.1.7",
-    "knip": "^6.14.1",
-    "oxfmt": "^0.60.0",
-    "oxlint": "^1.60.0",
-    "typescript": "^7.0.2",
-    "vitest": "^4.1.4"
-  },
   "scripts": {
     "build": "node scripts/build.mjs",
     "prepare": "node scripts/install-husky.mjs && npm run build",
@@ -58,22 +70,24 @@
     "test:coverage": "vitest run --coverage && node scripts/strip-lcov-branches.mjs",
     "test:watch": "vitest"
   },
-  "keywords": [
-    "github",
-    "pull-request",
-    "ci",
-    "code-review",
-    "automation",
-    "codex",
-    "claude",
-    "claude-code"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jonathanong/pr-shepherd.git"
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "picomatch": "^4.0.4",
+    "yaml": "^2.7.0",
+    "zod": "^4.4.3"
   },
-  "bugs": {
-    "url": "https://github.com/jonathanong/pr-shepherd/issues"
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@types/picomatch": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.4",
+    "husky": "^9.1.7",
+    "knip": "^6.14.1",
+    "oxfmt": "^0.62.0",
+    "oxlint": "^1.60.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.4"
   },
-  "homepage": "https://github.com/jonathanong/pr-shepherd"
+  "engines": {
+    "node": ">=22.18.0"
+  }
 }

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",
@@ -11,7 +11,8 @@
   "repository": "https://github.com/jonathanong/pr-shepherd",
   "license": "MIT",
   "keywords": ["github", "pull-request", "ci", "code-review", "automation", "codex"],
-  "skills": "../skills/",
+  "skills": "./skills/",
+  "mcpServers": "./.codex.mcp.json",
   "interface": {
     "displayName": "pr-shepherd",
     "shortDescription": "Monitor PR CI and review comments from Codex",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "pr-shepherd": {
+      "command": "npx",
+      "args": ["--yes", "--package", "pr-shepherd@0.35.0", "pr-shepherd-mcp"]
+    }
+  }
+}

package/plugins/pr-shepherd/.mcp.json

@@ -0,0 +1,6 @@
+{
+  "pr-shepherd": {
+    "command": "npx",
+    "args": ["--yes", "--package", "pr-shepherd@0.35.0", "pr-shepherd-mcp"]
+  }
+}

package/plugins/pr-shepherd/skills/mark-files-as-viewed/SKILL.md

@@ -1,31 +1,17 @@
 ---
 name: mark-files-as-viewed
-description: 'Mark PR changed files as viewed in GitHub with pr-shepherd. Use for requests like "mark tests as viewed" or "mark these files as viewed".'
+description: "Mark changed pull-request files as viewed with pr-shepherd (MCP or CLI)."
 user-invocable: true
 argument-hint: "[PR number or URL] [files|tests|--tests|--match REGEX]"
-allowed-tools: ["Bash", "Read", "Grep", "Glob"]
+allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob"]
 ---
 
 # mark-files-as-viewed
 
-Thin dispatcher for marking GitHub PR changed files as viewed.
+Thin dispatcher for marking PR files viewed. Use the MCP server when it is available; otherwise use the CLI.
 
 ## Arguments: $ARGUMENTS
 
-## Steps
+1. Parse an optional PR number or GitHub PR URL. Treat standalone `tests` as `--tests`; preserve explicit paths and `--match <regex>` selectors.
 
-1. **Resolve arguments:**
-   - If `$ARGUMENTS` contains a PR number, use it.
-   - If `$ARGUMENTS` contains a GitHub PR URL, extract the number.
-   - Otherwise, infer: `gh pr view --json number --jq .number`
-   - Treat a standalone `tests` argument as `--tests`.
-   - Preserve explicit file paths, `--tests`, and `--match <regex>` arguments.
-   - If no PR found, report an error and stop.
-
-2. **Run `pr-shepherd`:**
-
-   ```bash
-   pr-shepherd mark-files-as-viewed <N> <selectors>
-   ```
-
-   Print the full output.
+2. If the `apply` MCP tool is available, call it with one `mark_files_viewed` operation, then print the full result. Otherwise run `pr-shepherd apply files` with the parsed PR and selectors and print the full result.

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -1,28 +1,19 @@
 ---
 name: pr-shepherd
-description: 'Iterate a GitHub pull request to completion with pr-shepherd. Use for requests like "use pr-shepherd", "iterate PR #123", or "run pr-shepherd until this PR is ready".'
+description: 'Iterate a GitHub pull request with pr-shepherd (MCP or CLI). Use for requests like "use pr-shepherd", "iterate PR #123", or "run pr-shepherd until this PR is ready".'
 user-invocable: true
 argument-hint: "[PR number or URL]"
-allowed-tools: ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill"]
+allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
 ---
 
 # pr-shepherd
 
-Poll dispatcher for iterating a PR to completion.
+Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only when the CLI is unavailable.
 
 ## Arguments: $ARGUMENTS
 
-## Steps
+1. Parse an optional PR number or GitHub PR URL from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR.
 
-1. **Resolve the PR number** (`$N`): use the number or URL in `$ARGUMENTS`; otherwise infer it with `gh pr view --json number --jq .number`. If none is found, report an error and stop.
+2. Run the poll command `pr-shepherd` with the optional PR argument and print its full result. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, call `iterate` and print its full result.
 
-2. **Define the poll command once:** `pr-shepherd $N --interval 60s --until-terminal --quiet-status`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
-
-3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. `[FIX_CODE]` is non-terminal: do its instructions, then poll again. The poll already waits between ticks via `--interval`; do not add manual `sleep`s between ticks.
-
-4. **Exit codes:** an exit code of `64` or higher means the `pr-shepherd` command itself failed (bad flag, GitHub auth/permission error, transient failure, etc.) — surface the error and stop instead of looping. Any other exit code (`0` or `10`–`19`) means the command ran and the output above is real PR state — proceed to step 5.
-
-5. **Terminal states (stop):**
-   - `[CANCEL]` — ready-delay completed, or PR merged/closed.
-   - `[ESCALATE]` — needs human direction (includes `stall-timeout` for repeated unchanged CI failures or CI that never starts).
-   - **Do NOT merge the pull request** unless the human has explicitly requested or allowed it.
+3. Follow the returned instructions exactly. If this tick used MCP `iterate`, use MCP `apply` and `build_suggestion_patch` for the returned review mutations and suggestion patches — do not run a `pr-shepherd apply` shell command. If this tick used the CLI poll, run the printed apply command. After completing an action, run `pr-shepherd` again (or call `iterate` if only MCP is available) until a terminal action or the human directs you to stop.

package/src/classify/types.mts

@@ -1,3 +1,14 @@
+/** Raw relationship between a comment author and the repository, as reported by GitHub. */
+export type CommentAuthorAssociation =
+  | "COLLABORATOR"
+  | "CONTRIBUTOR"
+  | "FIRST_TIMER"
+  | "FIRST_TIME_CONTRIBUTOR"
+  | "MANNEQUIN"
+  | "MEMBER"
+  | "NONE"
+  | "OWNER";
+
 export type ClassifyItemKind =
   | "review-thread"
   | "pr-comment"
@@ -9,6 +20,7 @@ export interface ClassifyItemBase {
   readonly id: string;
   readonly author: string;
   readonly authorType: "User" | "Bot" | "Unknown";
+  readonly authorAssociation?: CommentAuthorAssociation;
   readonly body: string;
   readonly url?: string;
 }