pr-shepherd 0.8.1 → 0.10.0

package/bin/reporters/text.mjs

@@ -1,158 +1,146 @@
 import { buildCheckInstructions } from "./check-instructions.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "../cli/list-formatters.mjs";
+import { joinSections } from "../util/markdown.mjs";
 export function formatText(report) {
-    const parts = [];
-    // Header — scan-friendly status lines for quick at-a-glance review
-    parts.push(`\nPR #${report.pr} — ${report.repo}`);
-    parts.push(`Status: ${report.status}`);
-    parts.push(`Base: ${report.baseBranch}`);
-    parts.push("");
-    // Merge status
+    const header = [
+        `# PR #${report.pr} [CHECK] — ${report.repo}`,
+        `Status: ${report.status}`,
+        `Base: ${report.baseBranch}`,
+    ].join("\n");
     const ms = report.mergeStatus;
-    parts.push("## Merge Status");
-    parts.push("");
-    parts.push(`${ms.status}`);
-    parts.push(`  mergeStateStatus:        ${ms.mergeStateStatus}`);
-    parts.push(`  mergeable:               ${ms.mergeable}`);
-    parts.push(`  reviewDecision:          ${ms.reviewDecision ?? "(none)"}`);
-    parts.push(`  isDraft:                 ${ms.isDraft}`);
-    parts.push(`  copilotReviewInProgress: ${ms.copilotReviewInProgress}`);
-    parts.push("");
-    // CI checks
+    const mergeStatusSection = [
+        "## Merge Status",
+        "",
+        `- status: \`${ms.status}\``,
+        `- mergeStateStatus: \`${ms.mergeStateStatus}\``,
+        `- mergeable: \`${ms.mergeable}\``,
+        `- reviewDecision: \`${ms.reviewDecision ?? "(none)"}\``,
+        `- isDraft: \`${ms.isDraft}\``,
+        `- copilotReviewInProgress: \`${ms.copilotReviewInProgress}\``,
+    ].join("\n");
     const { passing, failing, inProgress, skipped } = report.checks;
     const total = passing.length + failing.length + inProgress.length + skipped.length;
-    parts.push("## CI Checks");
-    parts.push("");
-    parts.push(`${passing.length}/${total} passed`);
-    parts.push("");
+    const ciSubsections = [`${passing.length}/${total} passed`];
     if (failing.length > 0) {
-        parts.push(`### Failed (${failing.length})`);
-        parts.push("");
+        const lines = [`### Failed (${failing.length})`, ""];
         for (const c of failing) {
             const triaged = c;
             const prefix = triaged.workflowName ? `${triaged.workflowName} › ` : "";
-            parts.push(`- ${prefix}${c.name}: ${c.conclusion ?? c.status}`);
+            lines.push(`- ${prefix}${c.name}: ${c.conclusion ?? c.status}`);
             if (triaged.failedStep) {
-                parts.push(`    failed step: ${triaged.failedStep}`);
+                lines.push(`    failed step: ${triaged.failedStep}`);
             }
             if (triaged.summary) {
-                parts.push(`    summary: ${triaged.summary}`);
+                lines.push(`    summary: ${triaged.summary}`);
             }
         }
-        parts.push("");
+        ciSubsections.push(lines.join("\n"));
     }
     if (inProgress.length > 0) {
-        parts.push(`### In Progress (${inProgress.length})`);
-        parts.push("");
+        const lines = [`### In Progress (${inProgress.length})`, ""];
         for (const c of inProgress) {
-            parts.push(`- ${c.name}: ${c.status}`);
+            lines.push(`- ${c.name}: ${c.status}`);
         }
-        parts.push("");
+        ciSubsections.push(lines.join("\n"));
     }
     if (skipped.length > 0) {
-        parts.push(`### Skipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
-        parts.push("");
+        ciSubsections.push(`### Skipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
     }
     if (report.checks.filtered.length > 0) {
-        parts.push(`### Filtered non-PR-trigger (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`);
-        parts.push("");
+        const lines = [
+            `### Filtered non-PR-trigger (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`,
+            "",
+        ];
         if (report.checks.blockedByFilteredCheck) {
-            parts.push("  Note: PR is BLOCKED and all filtered checks are non-PR-trigger — one of these filtered checks may be a required status check blocking merge.");
+            lines.push("> Note: PR is BLOCKED and all filtered checks are non-PR-trigger — one of these filtered checks may be a required status check blocking merge.");
         }
         else if (report.mergeStatus.status === "BLOCKED") {
-            parts.push("  Note: one or more of these filtered checks may be a required status check blocking merge.");
+            lines.push("> Note: one or more of these filtered checks may be a required status check blocking merge.");
         }
-        parts.push("");
+        ciSubsections.push(lines.join("\n"));
     }
-    // Review threads
-    const { actionable: actionableThreads, autoResolved, autoResolveErrors } = report.threads;
+    const ciSection = `## CI Checks\n\n${ciSubsections.join("\n\n")}`;
+    const { actionable: actionableThreads, autoResolved, autoResolveErrors, firstLook: firstLookThreads, } = report.threads;
     const hasThreadSection = autoResolved.length > 0 || autoResolveErrors.length > 0 || actionableThreads.length > 0;
+    let threadsSection = null;
     if (hasThreadSection) {
-        parts.push("## Review Threads");
-        parts.push("");
+        const subparts = [];
         if (autoResolved.length > 0) {
-            parts.push(`Auto-resolved outdated (${autoResolved.length}):`);
+            const lines = [`Auto-resolved outdated (${autoResolved.length}):`];
             for (const t of autoResolved) {
-                parts.push(`- threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
+                lines.push(renderThreadBullet(t));
             }
-            parts.push("");
+            subparts.push(lines.join("\n"));
         }
         if (autoResolveErrors.length > 0) {
-            parts.push(`Auto-resolve errors (${autoResolveErrors.length}):`);
+            const lines = [`Auto-resolve errors (${autoResolveErrors.length}):`];
             for (const e of autoResolveErrors) {
-                parts.push(`- ${e}`);
+                lines.push(`- ${e}`);
             }
-            parts.push("");
+            subparts.push(lines.join("\n"));
         }
         if (actionableThreads.length > 0) {
-            parts.push(`### Actionable (${actionableThreads.length})`);
-            parts.push("");
+            const lines = [`### Actionable (${actionableThreads.length})`, ""];
             for (const t of actionableThreads) {
-                const label = t.path ? `${t.path}:${t.line ?? "?"}` : "(general)";
-                parts.push(`- threadId=${t.id} ${label} (@${t.author})`);
-                parts.push(`  ${firstLine(t.body)}`);
+                lines.push(renderThreadBullet(t));
             }
-            parts.push("");
+            subparts.push(lines.join("\n"));
         }
+        threadsSection = `## Review Threads\n\n${subparts.join("\n\n")}`;
     }
-    // PR comments
-    const { actionable: actionableComments } = report.comments;
+    const { actionable: actionableComments, firstLook: firstLookComments } = report.comments;
+    let commentsSection = null;
     if (actionableComments.length > 0) {
-        parts.push("## PR Comments");
-        parts.push("");
-        parts.push(`### Actionable (${actionableComments.length})`);
-        parts.push("");
+        const lines = [`### Actionable (${actionableComments.length})`, ""];
         for (const c of actionableComments) {
-            parts.push(`- commentId=${c.id} (@${c.author}): ${firstLine(c.body)}`);
+            lines.push(renderCommentBullet(c));
         }
-        parts.push("");
+        commentsSection = `## PR Comments\n\n${lines.join("\n")}`;
     }
-    // CHANGES_REQUESTED reviews
-    if (report.changesRequestedReviews.length > 0) {
-        parts.push("## CHANGES_REQUESTED Reviews");
-        parts.push("");
-        for (const r of report.changesRequestedReviews) {
-            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
+    const changesRequestedSection = reviewListSection("CHANGES_REQUESTED Reviews", report.changesRequestedReviews);
+    const reviewSummariesSection = reviewListSection("Review Summaries", report.reviewSummaries);
+    const approvedReviewsSection = reviewListSection("Approved Reviews", report.approvedReviews);
+    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
+    let firstLookSection = null;
+    if (firstLookTotal > 0) {
+        const lines = [
+            `## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`,
+            "",
+        ];
+        for (const t of firstLookThreads) {
+            lines.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
         }
-        parts.push("");
-    }
-    // Review summaries
-    if (report.reviewSummaries.length > 0) {
-        parts.push("## Review Summaries");
-        parts.push("");
-        for (const r of report.reviewSummaries) {
-            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
-        }
-        parts.push("");
-    }
-    // Approved reviews
-    if (report.approvedReviews.length > 0) {
-        parts.push("## Approved Reviews");
-        parts.push("");
-        for (const r of report.approvedReviews) {
-            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
+        for (const c of firstLookComments) {
+            lines.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
         }
-        parts.push("");
+        firstLookSection = lines.join("\n");
     }
-    // Summary
     const totalActionable = actionableThreads.length + actionableComments.length + report.changesRequestedReviews.length;
-    parts.push("## Summary");
-    parts.push("");
-    parts.push(totalActionable === 0
-        ? "0 actionable — all threads resolved/minimized"
-        : `${totalActionable} actionable item(s) remaining`);
-    parts.push("");
-    // Instructions
-    parts.push("## Instructions");
-    parts.push("");
+    const counts = [];
+    if (totalActionable > 0)
+        counts.push(`${totalActionable} actionable`);
+    if (firstLookTotal > 0)
+        counts.push(`${firstLookTotal} first-look`);
+    const summaryLine = counts.join(", ") || "0 actionable — all threads resolved/minimized";
+    const summarySection = `## Summary\n\n${summaryLine}`;
     const instructions = buildCheckInstructions(report);
-    instructions.forEach((step, i) => {
-        parts.push(`${i + 1}. ${step}`);
-    });
-    return parts.join("\n");
+    const instructionsSection = `## Instructions\n\n${instructions.map((step, i) => `${i + 1}. ${step}`).join("\n")}`;
+    return joinSections([
+        header,
+        mergeStatusSection,
+        ciSection,
+        threadsSection,
+        commentsSection,
+        changesRequestedSection,
+        reviewSummariesSection,
+        approvedReviewsSection,
+        firstLookSection,
+        summarySection,
+        instructionsSection,
+    ]);
 }
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function firstLine(text) {
-    return (text.split("\n")[0] ?? "").trim().slice(0, 120);
+function reviewListSection(heading, items) {
+    if (items.length === 0)
+        return null;
+    return `## ${heading}\n\n${items.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n")}`;
 }

package/bin/state/base.mjs

@@ -0,0 +1,5 @@
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+export function resolveStateBase() {
+    return process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+}

package/bin/state/fix-attempts.mjs

@@ -10,8 +10,8 @@
 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";
+import { resolveStateBase } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -62,6 +62,6 @@ function resolvePath(key) {
             throw new Error(`Invalid state key segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const base = resolveStateBase();
     return join(base, `${key.owner}-${key.repo}`, String(key.pr), "fix-attempts.json");
 }

package/bin/state/iterate-stall.mjs

@@ -10,8 +10,8 @@
 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";
+import { resolveStateBase } from "./base.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -69,6 +69,6 @@ function resolvePath(key) {
             throw new Error(`Invalid state key segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const base = resolveStateBase();
     return join(base, `${key.owner}-${key.repo}`, String(key.pr), "iterate-stall.json");
 }

package/bin/state/seen-comments.mjs

@@ -0,0 +1,76 @@
+import { readFile, writeFile, mkdir, access, readdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+import { resolveStateBase } from "./base.mjs";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read the seen/ directory once and return a Set of already-seen IDs.
+ * Prefer this over repeated hasSeen() calls to avoid EMFILE on large PRs.
+ * Returns an empty Set if the directory does not yet exist.
+ */
+export async function loadSeenSet(key) {
+    try {
+        const dir = resolveDir(key);
+        const entries = await readdir(dir);
+        return new Set(entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5)));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Return true if a "seen" marker exists for this id. */
+export async function hasSeen(key, id) {
+    try {
+        await access(resolvePath(key, id));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Write a "seen" marker for this id. Idempotent — preserves original seenAt on double-write. */
+export async function markSeen(key, id) {
+    try {
+        const path = resolvePath(key, id);
+        await mkdir(dirname(path), { recursive: true });
+        // O_EXCL: create-only — EEXIST means already marked, which is the idempotent success case.
+        // seenAt is unix milliseconds (Date.now()), matching JS convention for this module.
+        await writeFile(path, JSON.stringify({ seenAt: Date.now() }), { flag: "wx", encoding: "utf8" });
+    }
+    catch {
+        // EEXIST = already seen. All other errors are best-effort.
+    }
+}
+/** Read the full marker for inspection (returns null on miss or error). */
+export async function readSeenMarker(key, id) {
+    try {
+        const raw = await readFile(resolvePath(key, id), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveDir(key) {
+    for (const [field, value] of [
+        ["owner", key.owner],
+        ["repo", key.repo],
+    ]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`Invalid state key segment "${field}": ${value}`);
+        }
+    }
+    const base = resolveStateBase();
+    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "seen");
+}
+function resolvePath(key, id) {
+    if (!SAFE_SEGMENT.test(id)) {
+        throw new Error(`Invalid state key segment "id": ${id}`);
+    }
+    return join(resolveDir(key), `${id}.json`);
+}

package/bin/suggestions/extract.mjs

@@ -0,0 +1,15 @@
+import { parseSuggestion } from "./parse.mjs";
+export function extractSuggestion(thread) {
+    if (!thread.path || thread.line === null)
+        return null;
+    const parsed = parseSuggestion(thread.body);
+    if (!parsed)
+        return null;
+    const startLine = thread.startLine ?? thread.line;
+    return {
+        startLine,
+        endLine: thread.line,
+        lines: parsed.lines,
+        author: thread.author,
+    };
+}

package/bin/suggestions/parse.mjs

@@ -3,8 +3,7 @@
  *
  * GitHub's "Commit suggestion" UI button treats the first ```suggestion fenced
  * block in a review comment as a replacement for the commented line range.
- * This module extracts that block from the comment body, plus applies a
- * parsed suggestion to a file's contents.
+ * This module extracts that block from the comment body.
  *
  * There is no GitHub API for applying suggestions — tools that reproduce the
  * button (this one included) must parse + commit themselves.
@@ -93,27 +92,3 @@ export function isCommittableSuggestion(parsed) {
     const fenceRuns = (replacement.match(/`{3,}/g) ?? []).length;
     return fenceRuns % 2 === 0;
 }
-/**
- * Apply a suggestion to a file's full contents by replacing lines
- * [startLine..endLine] (1-indexed, inclusive) with the given replacement lines.
- *
- * Pass `[]` to delete the range, `[""]` to replace with a single blank line,
- * or `["a", "b", ...]` for arbitrary replacements. The file's trailing-newline
- * state is preserved exactly.
- */
-export function applySuggestionToFile(fileContent, startLine, endLine, replacementLines) {
-    if (startLine < 1 || endLine < startLine) {
-        throw new Error(`Invalid line range: start=${startLine}, end=${endLine}`);
-    }
-    const endsWithNewline = fileContent.endsWith("\n");
-    // Strip a single trailing \n so split/join round-trips exactly.
-    const body = endsWithNewline ? fileContent.slice(0, -1) : fileContent;
-    const lines = body.split("\n");
-    if (endLine > lines.length) {
-        throw new Error(`Line ${endLine} is out of range (file has ${lines.length} line(s))`);
-    }
-    const before = lines.slice(0, startLine - 1);
-    const after = lines.slice(endLine);
-    const result = [...before, ...replacementLines, ...after].join("\n");
-    return endsWithNewline ? `${result}\n` : result;
-}

package/bin/types/report.mjs

@@ -1,2 +1 @@
-// Shepherd-specific report types, agent projections, and CLI options.
 export {};

package/bin/util/markdown.mjs

@@ -0,0 +1,7 @@
+export function joinSections(sections) {
+    return sections
+        .filter((s) => s != null)
+        .map((s) => s.replace(/^[\r\n]+|[\r\n]+$/g, ""))
+        .filter((s) => s !== "")
+        .join("\n\n");
+}

package/bin/util/worktree.mjs

@@ -0,0 +1,23 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { SAFE_SEGMENT } from "./path-segment.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"]);
+    return stdout.trim();
+}
+/**
+ * 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 async function getWorktreeKey() {
+    const root = await getWorktreeRoot();
+    const sha8 = createHash("sha256").update(root).digest("hex").slice(0, 8);
+    const base = basename(root);
+    return SAFE_SEGMENT.test(base) ? `${base}-${sha8}` : sha8;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -24,7 +24,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "oxfmt": "^0.45.0",
+    "oxfmt": "^0.46.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4",

package/bin/commands/iterate/steps.mjs

@@ -1,31 +0,0 @@
-import { applyStallGuard } from "./stall.mjs";
-export async function buildRerunCiResult(transientChecks, base, prNumber, stallKey, stallTimeoutSeconds, headSha, report, reviewSummaryIds) {
-    const runMap = new Map();
-    for (const c of transientChecks) {
-        if (c.runId === null)
-            continue;
-        const existing = runMap.get(c.runId);
-        if (existing) {
-            existing.checkNames.push(c.name);
-        }
-        else {
-            runMap.set(c.runId, {
-                runId: c.runId,
-                checkNames: [c.name],
-                failureKind: c.failureKind,
-                workflowName: c.workflowName,
-            });
-        }
-    }
-    const reran = [...runMap.values()];
-    const runSummaries = reran.map(({ runId, checkNames, failureKind, workflowName }) => {
-        const prefix = workflowName ? `${workflowName} › ` : "";
-        return `${runId} (${prefix}${checkNames.join(", ")} — ${failureKind})`;
-    });
-    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
-        ...base,
-        action: "rerun_ci",
-        reran,
-        log: `RERUN NEEDED — ${reran.length} CI run${reran.length === 1 ? "" : "s"}: ${runSummaries.join(", ")}`,
-    }, report, reviewSummaryIds);
-}

package/bin/github/gql/dismiss-review.gql

@@ -1,7 +0,0 @@
-mutation DismissReview($reviewId: ID!, $message: String!) {
-  dismissPullRequestReview(input: { pullRequestReviewId: $reviewId, message: $message }) {
-    pullRequestReview {
-      state
-    }
-  }
-}

package/bin/github/gql/minimize-comment.gql

@@ -1,7 +0,0 @@
-mutation MinimizeComment($commentId: ID!, $classifier: ReportedContentClassifiers!) {
-  minimizeComment(input: { subjectId: $commentId, classifier: $classifier }) {
-    minimizedComment {
-      isMinimized
-    }
-  }
-}

package/bin/github/gql/multi-pr-status.gql

@@ -1,32 +0,0 @@
-query MultiPrStatus($owner: String!, $repo: String!, $pr: Int!) {
-  repository(owner: $owner, name: $repo) {
-    pullRequest(number: $pr) {
-      number
-      state
-      isDraft
-      title
-      mergeStateStatus
-      reviewDecision
-      # totalCount lets callers detect truncation; pageInfo enables backward pagination.
-      reviewThreads(last: 100) {
-        totalCount
-        pageInfo {
-          hasPreviousPage
-          startCursor
-        }
-        nodes {
-          isResolved
-        }
-      }
-      commits(last: 1) {
-        nodes {
-          commit {
-            statusCheckRollup {
-              state
-            }
-          }
-        }
-      }
-    }
-  }
-}

package/bin/github/gql/resolve-thread.gql

@@ -1,7 +0,0 @@
-mutation ResolveThread($threadId: ID!) {
-  resolveReviewThread(input: { threadId: $threadId }) {
-    thread {
-      isResolved
-    }
-  }
-}