pr-shepherd 0.2.0 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"
@@ -9,6 +9,12 @@
   "homepage": "https://github.com/jonathanong/pr-shepherd",
   "repository": "https://github.com/jonathanong/pr-shepherd",
   "license": "MIT",
-  "keywords": ["github", "pull-request", "ci", "code-review", "automation"],
+  "keywords": [
+    "github",
+    "pull-request",
+    "ci",
+    "code-review",
+    "automation"
+  ],
   "skills": "./skills/"
 }

package/README.md

@@ -2,98 +2,141 @@
 
 Autonomous PR CI monitor and review-comment resolver for Claude Code.
 
-## Goals
-
-- **Reduced context** — shifts more logic to the CLI instead of the agent
-- **Reduced GitHub rate limit exhaustion** — all GraphQL queries are batched
-- **Reduced agent tool calls** — batching comment resolutions means fewer tool calls and less context used
-- **No MCP** — less reasoning and much faster than using the GitHub MCP
-- **CI cancellation on failure** — avoids wasted CI runs when actionable failures exist
-- **Auto-resolution of all inline comments** — including bot and AI reviewer comments
-- **Automatic resolution of outdated comments** — happens before the agent is involved
-- **Automatic pagination and filtering** — resolved comments never reach the agent
-- **Aggressively hides bot comments** — keeps PR noise low
-- **Waits for pending Copilot reviews** — avoids premature marking as ready
-- **Rebases on conflict** — automatically rebases on the PR base branch when there are merge conflicts
-- **4-minute watch cadence** — keeps Claude's prompt cache warm (5-minute TTL)
-- **10-minute settle window** — waits after the PR is clean before exiting, in case of pending reviews
-- **Draft → ready-for-review** — automatically converts draft PRs when CI passes
-- **Skips non-PR CI checks** — only `pull_request` / `pull_request_target` events count toward readiness
-- **Intended as a PR merge blocker** — pair with a GitHub Actions required check that verifies all threads are resolved
+## Design principles
+
+- **Reduced agent context** — logic lives in the CLI, not the prompt
+- **Reduced GitHub rate-limit exhaustion** — primary PR state is fetched via a batched GraphQL query
+- **Fewer tool calls** — comment resolutions are batched; resolved threads never reach the agent
+- **No MCP** — smaller reasoning surface, much faster than the GitHub MCP
+- **No vendor lock-in** — runs against `gh` + `git`; no hosted service required
+- **Skills over subagents** — subagents reload all CLAUDE.md context on every turn; skills inject into the main conversation instead, keeping cost low
 
-## Why it's built this way
+## Features
 
-Claude's cloud autofix requires CI to verify changes for apps that can't run in the cloud. Running targeted tests locally and letting Claude Code drive is cheaper and avoids vendor lock-in. Skills are used (not subagents) because subagents load all CLAUDE.md context, increasing cost; skills inject into the main conversation instead.
+- **CI handling** — cancels runs on actionable failures, reruns on transient/infra failures, skips non-PR trigger events
+- **Comments** — resolves inline threads (including bot and AI reviewer comments), auto-resolves outdated threads before the agent sees them, aggressively hides bot comments, paginates and filters server-side
+- **Readiness** — converts draft → ready-for-review when CI passes, waits for pending Copilot reviews, settles for a configurable window (default 10 min) before exiting
+- **Rebases on conflict** — automatically rebases on the PR base branch when merge conflicts appear
+- **Intended as a PR merge blocker** — pair with a GitHub Actions required check that verifies all threads are resolved
 
 ## Install
 
+### As a Claude Code plugin (recommended)
+
 ```bash
-npm install pr-shepherd
+claude /plugin marketplace add jonathanong/pr-shepherd
+claude /plugin install pr-shepherd
 ```
 
-### As a Claude Code plugin
+See [Usage](#usage) below.
+
+### Without the plugin — custom slash command
+
+If you don't want the full plugin, create a project-local (or user-scope)
+slash command that wraps the CLI directly. This still requires `pr-shepherd`
+to be installed in the repository first (`npm install pr-shepherd`), so that
+`npx pr-shepherd ...` runs without prompting to install the package.
+
+1. **Create the command file:**
+   - Project-scope: `.claude/commands/pr-check.md`
+   - User-scope: `~/.claude/commands/pr-check.md`
+
+2. **Paste this as the file contents:**
+
+   ````markdown
+   ---
+   description: "Check GitHub CI status and review comments for the current PR"
+   argument-hint: "[PR number or URL ...]"
+   allowed-tools: ["Bash", "Read", "Grep"]
+   ---
+
+   # PR Status Check
+
+   ## Arguments: $ARGUMENTS
+
+   ## Resolve PR number(s)
+
+   1. If `$ARGUMENTS` contains PR numbers or GitHub PR URLs, extract the number(s).
+   2. Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
+   3. If no PR found, report an error and stop.
+
+   ## Run the check
+
+   ```bash
+   npx pr-shepherd check <PR_NUMBER> --format=json
+   ```
+
+   Parse the JSON and report:
+
+   - **Merge status** (`report.mergeStatus.status`): CLEAN | BEHIND | CONFLICTS | BLOCKED | UNSTABLE | DRAFT | UNKNOWN
+   - **CI check results** (`report.checks`): passing count, failing names, in-progress names
+   - **Unresolved review comments** (`report.threads.actionable` + `report.comments.actionable`): count + details
+   ````
+
+3. **Use it in Claude Code:**
+
+   ```
+   /pr-check
+   /pr-check 42
+   ```
+
+For `monitor` and `resolve` custom commands, do **not** copy the
+[`skills/`](skills/) files directly — those contain skill/plugin-specific
+frontmatter that is not valid for `.claude/commands/` files. Instead, create
+`.claude/commands/pr-monitor.md` and/or `.claude/commands/pr-resolve.md`
+using the same command-file structure as the `pr-check` example above, with
+the CLI invocation changed to `npx pr-shepherd iterate ...` or
+`npx pr-shepherd resolve ...`. To drive the CLI without Claude at all, see
+[docs/usage.md](docs/usage.md).
+
+### As a global CLI
 
 ```bash
-# Install from marketplace
-claude /plugin marketplace add jonathanong/pr-shepherd
-claude /plugin install pr-shepherd
+npm install -g pr-shepherd
 ```
 
-Then use:
+## Usage
 
-- `/pr-shepherd:monitor [PR]` — start continuous monitoring
-- `/pr-shepherd:check [PR]` — one-shot status check
-- `/pr-shepherd:resolve [PR]` — fetch, fix, and resolve review comments
+### Monitor a PR
 
-## Workflow
+Creates a cron loop that fires every 4 minutes, checks CI and review
+comments, fixes issues, and marks the PR ready for review when clean. The
+loop cancels automatically when the PR is merged or closed.
 
-```mermaid
-flowchart TD
-  U(["/pr-shepherd:monitor PR"]) --> SC["monitor skill"]
-  SC -->|CronList| EX{Loop exists<br/>for this PR?}
-  EX -->|yes| NOW[Run iterate once<br/>inline and act]
-  EX -->|no| CREATE["/loop 4m --max-turns 50 --expires 8h"]
-  CREATE --> CRON[(cron tick every 4m)]
-  NOW --> ITER
-  CRON --> ITER["pr-shepherd iterate PR --format=json"]
-
-  ITER --> S1{1. last commit<br/>age &lt; cooldown?}
-  S1 -->|yes| A_COOL([action: cooldown])
-  S1 -->|no| S2["2. runCheck — one GraphQL batch<br/>classify + deriveMergeStatus<br/>+ autoResolveOutdated"]
-
-  S2 --> S25{2.5 state != OPEN?}
-  S25 -->|yes| A_CAN([action: cancel])
-  S25 -->|no| S3["3. updateReadyDelay<br/>ready-since.txt"]
-  S3 --> S3C{shouldCancel?}
-  S3C -->|yes| A_CAN
-  S3C -->|no| S4{4. CONFLICTS or actionable<br/>threads/comments/CI/reviews?}
-  S4 -->|yes| S4X["gh run cancel actionable runIds"]
-  S4X --> A_FIX([action: fix_code])
-  S4 -->|no| S5{5. transient<br/>timeout/infra?}
-  S5 -->|yes| S5X["gh run rerun runId --failed"]
-  S5X --> A_RR([action: rerun_ci])
-  S5 -->|no| S6{6. flaky + BEHIND?}
-  S6 -->|yes| A_REB([action: rebase])
-  S6 -->|no| S7{7. READY + CLEAN<br/>+ isDraft + !copilot?}
-  S7 -->|yes| A_MR([action: mark_ready])
-  S7 -->|no| A_W([action: wait])
-
-  A_COOL --> DEC{skill acts on action}
-  A_CAN --> DEC
-  A_REB --> DEC
-  A_FIX --> DEC
-  A_RR --> DEC
-  A_MR --> DEC
-  A_W --> DEC
-
-  DEC -->|cancel| STOP["/loop cancel"]
-  DEC -->|rebase| REB["git fetch && rebase origin/BASE &&<br/>push --force-with-lease"]
-  DEC -->|fix_code| FIX["Edit files →<br/>git add + commit →<br/>fetch + rebase + push →<br/>pr-shepherd resolve --require-sha HEAD"]
-  FIX --> NEXT[Wait for next tick]
-  REB --> NEXT
-  DEC -->|other| NEXT
-  NEXT --> CRON
 ```
+/pr-shepherd:monitor                     # infer PR from current branch
+/pr-shepherd:monitor 42
+/pr-shepherd:monitor 42 every 8m
+/pr-shepherd:monitor 42 --ready-delay 15m
+```
+
+### Check a PR
+
+One-shot status snapshot — merge state, CI results, and unresolved comments.
+Accepts multiple PR numbers.
+
+```
+/pr-shepherd:check        # infer from branch
+/pr-shepherd:check 42
+/pr-shepherd:check 41 42 43
+```
+
+### Resolve review comments
+
+Fetches all actionable threads and comments, triages them, applies fixes,
+pushes, then resolves/minimizes/dismisses via `--require-sha` (waits until
+GitHub has seen the push before resolving).
+
+```
+/pr-shepherd:resolve       # infer from branch
+/pr-shepherd:resolve 42
+```
+
+See [docs/skills.md](docs/skills.md) for full argument reference.
+
+## Workflow
+
+On each 4-minute tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (fix code, rebase, rerun CI, mark ready, or wait). See [docs/flow.md](docs/flow.md) for the full decision tree.
 
 ## CLI
 
@@ -120,15 +163,11 @@ Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to
 ```yaml
 iterate:
   cooldownSeconds: 60 # wait longer after a push before reading CI
-  fixAttemptsPerThread: 5 # raise before escalating to manual review
 checks:
   ciTriggerEvents:
     - pull_request
     - pull_request_target
     - merge_group # add for merge-queue repos
-mergeStatus:
-  blockingReviewerLogins:
-    - copilot # add other review bots here
 actions:
   autoRebase: false # disable for repos that enforce merge commits
 ```
@@ -138,16 +177,20 @@ See [docs/configuration.md](docs/configuration.md) for all options.
 ## Requirements
 
 - Node.js ≥ 24.0.0
-- `gh` CLI authenticated (`gh auth login`)
+- `gh` CLI authenticated (`gh auth login`); `repo` scope is required for private repositories (public repositories may not need it)
 - `git`
 
+## Docs
+
+Full reference: [docs/README.md](docs/README.md) — CLI usage, skills, configuration, architecture, actions, debugging, and more.
+
 ## Architecture
 
-See [docs/architecture.md](docs/architecture.md) and [docs/](docs/) for full reference docs.
+See [docs/architecture.md](docs/architecture.md) for the module map and dependency rules.
 
 ## Forking
 
-If you want to customize pr-shepherd for your own use or team, see [docs/forking.md](docs/forking.md).
+See [docs/forking.md](docs/forking.md) if you want to customize pr-shepherd for your own use or team.
 
 ## License
 

package/dist/cache/file-cache.mjs

@@ -0,0 +1,78 @@
+/**
+ * Simple filesystem-based cache for shepherd batch reads.
+ *
+ * Cache entries live in `${TMPDIR}/pr-shepherd-cache/<owner>-<repo>/<pr>/<shape>.json`.
+ * TTL defaults to 5 minutes (configurable via PR_SHEPHERD_CACHE_TTL_SECONDS or --cache-ttl).
+ *
+ * Mutations are never cached — this module is read-path only.
+ */
+import { readFile, writeFile, rename, mkdir, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { loadConfig } from "../config/load.mjs";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+/**
+ * Read a value from the cache. Returns null on miss or expiry.
+ */
+export async function cacheGet(key, opts = {}) {
+    if (opts.disabled)
+        return null;
+    const ttl = opts.ttlSeconds ?? ttlFromEnv() ?? loadConfig().cache.ttlSeconds;
+    // A TTL of 0 (or negative) means "always expired" — skip the filesystem read entirely.
+    if (ttl <= 0)
+        return null;
+    try {
+        const path = resolvePath(key);
+        const stats = await stat(path);
+        const ageSeconds = (Date.now() - stats.mtimeMs) / 1000;
+        if (ageSeconds >= ttl)
+            return null;
+        const raw = await readFile(path, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a value to the cache (fire-and-forget — never throws).
+ */
+export async function cacheSet(key, value, opts = {}) {
+    if (opts.disabled)
+        return;
+    try {
+        const path = resolvePath(key);
+        const tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, JSON.stringify(value), "utf8");
+        // Atomic rename — prevents a partial read if two processes write concurrently.
+        await rename(tmp, path);
+    }
+    catch {
+        // Cache writes are best-effort.
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function resolvePath(key) {
+    for (const [field, value] of [
+        ["owner", key.owner],
+        ["repo", key.repo],
+        ["shape", key.shape],
+    ]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`Invalid cache key segment "${field}": ${value}`);
+        }
+    }
+    const base = process.env["PR_SHEPHERD_CACHE_DIR"] ?? join(tmpdir(), "pr-shepherd-cache");
+    return join(base, `${key.owner}-${key.repo}`, String(key.pr), `${key.shape}.json`);
+}
+function ttlFromEnv() {
+    const raw = process.env["PR_SHEPHERD_CACHE_TTL_SECONDS"];
+    if (!raw)
+        return undefined;
+    const parsed = parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}

package/dist/cache/fix-attempts.mjs

@@ -0,0 +1,67 @@
+/**
+ * Persistent attempt counter for the iterate escalation guard.
+ *
+ * Tracks how many times each review thread has been dispatched to the fix_code
+ * handler without being resolved. Counts are reset automatically when the HEAD
+ * commit SHA changes (i.e. a new push landed).
+ *
+ * State lives in `$TMPDIR/pr-shepherd-cache/<owner>-<repo>/<pr>/fix-attempts.json`.
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Read the current attempt state. Returns null on miss. */
+export async function readFixAttempts(key) {
+    try {
+        const raw = await readFile(resolvePath(key), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Write attempt state (fire-and-forget — never throws). */
+export async function writeFixAttempts(key, state) {
+    let tmp;
+    try {
+        const path = resolvePath(key);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, JSON.stringify(state), "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+    }
+    catch {
+        // Best-effort.
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolvePath(key) {
+    for (const [field, value] of [
+        ["owner", key.owner],
+        ["repo", key.repo],
+    ]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`Invalid cache key segment "${field}": ${value}`);
+        }
+    }
+    const base = process.env["PR_SHEPHERD_CACHE_DIR"] ?? join(tmpdir(), "pr-shepherd-cache");
+    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "fix-attempts.json");
+}

package/dist/checks/classify.mjs

@@ -0,0 +1,53 @@
+/**
+ * Classifies check runs into shepherd categories and filters out irrelevant ones.
+ *
+ * Rules:
+ *   1. Skip checks whose workflow event is NOT `pull_request` or `pull_request_target`.
+ *      Push-triggered, merge-queue, schedule, and workflow-dispatch runs are irrelevant
+ *      to PR readiness.
+ *   2. Drop checks with `conclusion == SKIPPED` or `conclusion == NEUTRAL` from the
+ *      pass/fail tally. Report them as "skipped" for transparency but don't block on them.
+ */
+import { loadConfig } from "../config/load.mjs";
+const RELEVANT_EVENTS = new Set(loadConfig().checks.ciTriggerEvents);
+/**
+ * Classify a list of raw check runs into shepherd categories.
+ *
+ * @param checks Raw check runs from the batch query.
+ * @returns Classified checks. "filtered" items were excluded from the tally.
+ */
+export function classifyChecks(checks) {
+    return checks.map((c) => classify(c));
+}
+function classify(check) {
+    // Filter: runs from non-PR events don't count toward PR readiness.
+    if (check.event !== null && !RELEVANT_EVENTS.has(check.event)) {
+        return { ...check, category: "filtered" };
+    }
+    const { status, conclusion } = check;
+    // Not yet finished.
+    if (status !== "COMPLETED") {
+        return { ...check, category: "in_progress" };
+    }
+    // Skipped / neutral — report but don't block.
+    if (conclusion === "SKIPPED" || conclusion === "NEUTRAL") {
+        return { ...check, category: "skipped" };
+    }
+    // Success.
+    if (conclusion === "SUCCESS") {
+        return { ...check, category: "passed" };
+    }
+    // Everything else (FAILURE, TIMED_OUT, CANCELLED, ACTION_REQUIRED, STARTUP_FAILURE, STALE).
+    return { ...check, category: "failing" };
+}
+/** Compute a high-level CI verdict from a list of classified checks. */
+export function getCiVerdict(classified) {
+    const relevant = classified.filter((c) => c.category !== "filtered" && c.category !== "skipped");
+    const anyInProgress = relevant.some((c) => c.category === "in_progress");
+    const anyFailing = relevant.some((c) => c.category === "failing");
+    // When there are no relevant checks (e.g. docs-only PR where all checks are filtered/skipped),
+    // treat as allPassed rather than blocking — there's nothing to fail.
+    const allPassed = !anyInProgress && !anyFailing;
+    const filteredNames = classified.filter((c) => c.category === "filtered").map((c) => c.name);
+    return { allPassed, anyInProgress, anyFailing, filteredNames };
+}

package/dist/checks/triage.mjs

@@ -0,0 +1,77 @@
+/**
+ * Triage failing check runs into four categories:
+ *   - timeout: conclusion is TIMED_OUT or logs contain timeout markers.
+ *   - infrastructure: conclusion is CANCELLED + infra-error log patterns.
+ *   - actionable: compile error, test failure, lint violation from the PR's changes.
+ *   - flaky: pre-existing or timing-dependent failures in untouched files.
+ *
+ * Shepherd computes and returns triage results, including `failureKind`, for
+ * downstream callers or slash-command logic to consume.
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { loadConfig } from "../config/load.mjs";
+const execFile = promisify(execFileCb);
+const config = loadConfig();
+const TIMEOUT_PATTERNS = config.checks.timeoutPatterns.map((p) => new RegExp(p, "i"));
+const INFRA_PATTERNS = config.checks.infraPatterns.map((p) => new RegExp(p, "i"));
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Fetch logs and triage each failing check.
+ *
+ * Fetching logs is skipped for checks that have no `runId` (e.g. StatusContext nodes).
+ */
+export function triageFailingChecks(failingChecks) {
+    return Promise.all(failingChecks.map((c) => triageCheck(c)));
+}
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+async function triageCheck(check) {
+    if (check.runId === null) {
+        return { ...check, failureKind: "actionable" };
+    }
+    const logExcerpt = await fetchFailedLogs(check.runId);
+    const failureKind = classifyLogs(check, logExcerpt);
+    return {
+        ...check,
+        failureKind,
+        logExcerpt: logExcerpt.slice(-config.checks.logMaxChars) || undefined,
+    };
+}
+async function fetchFailedLogs(runId) {
+    try {
+        const { stdout } = await execFile("gh", ["run", "view", runId, "--log-failed"], {
+            maxBuffer: config.execution.triageLogBufferMb * 1024 * 1024,
+        });
+        // Strip ANSI escape codes.
+        // eslint-disable-next-line no-control-regex
+        const ansiEscapes = /\u001B\[[0-9;]*m/g;
+        return stdout.replace(ansiEscapes, "").split("\n").slice(-config.checks.logMaxLines).join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+function classifyLogs(check, logs) {
+    // Timed out — check conclusion first, then logs.
+    if (check.conclusion === "TIMED_OUT")
+        return "timeout";
+    if (TIMEOUT_PATTERNS.some((re) => re.test(logs)))
+        return "timeout";
+    // Infrastructure error — typically CANCELLED with infra markers in logs.
+    if (check.conclusion === "CANCELLED" && INFRA_PATTERNS.some((re) => re.test(logs))) {
+        return "infrastructure";
+    }
+    // No logs at all — treat as infrastructure.
+    if (!logs.trim())
+        return "infrastructure";
+    // Heuristic: if the failure is in a file the PR likely didn't touch
+    // and the message contains "flaky" or timing language, call it flaky.
+    if (/flaky|timing|race condition|retry/i.test(logs))
+        return "flaky";
+    // Default: assume actionable.
+    return "actionable";
+}