pr-shepherd 0.28.0 → 0.30.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -181,6 +181,7 @@ checks:
     - pull_request_target
     - merge_group
 actions:
+  autoMinimizeSuppressed: true
   autoMarkReady: false
 ```
 
@@ -208,13 +209,15 @@ const rule: ClassifyRule = (item) => {
 export default rule;
 ```
 
-`suppress: true` hides the item from agent output. `autoResolve: true` queues it for the minimize/resolve mutation. Both can apply together.
+`suppress: true` hides the item from agent output. `autoResolve: true` queues it for the minimize/resolve mutation. When both apply together, Shepherd performs that mutation silently during `iterate` by default (`actions.autoMinimizeSuppressed: true`) so repetitive bot noise does not create a `fix_code` handoff.
+
+TypeScript rules are loaded by the runtime's native TypeScript support; keep them to erasable syntax such as type annotations and `import type`. Runtime TypeScript features that need transpilation, such as enums, namespaces, parameter properties, and decorators, are not supported. Use `.mts` for portable ESM rules across Node, Bun, and Deno.
 
 Ready-to-use examples for common patterns are in [`examples/classification/`](examples/classification/).
 
 ## Requirements
 
-- Node.js >= 22.0.0
+- Node.js >= 22.18.0, Bun, or Deno
 - A GitHub token or authenticated `gh` CLI; private repositories require `repo` scope.
 - `git`
 

package/bin/checks/triage.mjs

@@ -1,5 +1,11 @@
-import { rest } from "../github/http.mjs";
+/* eslint-disable max-lines */
+import { rest, restText } from "../github/http.mjs";
 const STARTUP_FAILURE_STATUS = "startup_failure";
+const LOG_EXCERPT_CONTEXT_LINES = 16;
+const LOG_EXCERPT_TAIL_LINES = 28;
+const LOG_EXCERPT_MAX_CHARS = 4_000;
+const TRUNCATED_SUFFIX = "\n[truncated]";
+const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
 export function triageFailingChecks(failingChecks, repo) {
     const jobsCache = new Map();
     return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
@@ -12,11 +18,13 @@ async function triageCheck(check, repo, jobsCache) {
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache);
     const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
+    const logExcerpt = jobInfo?.jobId ? await fetchJobLogExcerpt(jobInfo.jobId, repo) : undefined;
     return {
         ...check,
         ...(jobInfo?.workflowName !== undefined && { workflowName: jobInfo.workflowName }),
         ...(jobInfo?.jobName !== undefined && { jobName: jobInfo.jobName }),
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
+        ...(logExcerpt !== undefined && { logExcerpt }),
     };
 }
 export async function fetchStartupFailureChecks(repo, headSha, prNumber) {
@@ -107,8 +115,122 @@ function pickJobInfo(jobs, checkName) {
         s.conclusion !== "skipped" &&
         s.conclusion !== "neutral")?.name;
     return {
+        ...(job.id !== undefined && { jobId: job.id }),
         workflowName: job.workflow_name,
         jobName: job.name,
         failedStep,
     };
 }
+async function fetchJobLogExcerpt(jobId, repo) {
+    const { owner, name } = repo;
+    try {
+        return buildLogExcerpt(await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`));
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildLogExcerpt(raw) {
+    const lines = raw
+        .split(/\r?\n/)
+        .map(cleanLogLine)
+        .filter((line) => line.trim() !== "");
+    if (lines.length === 0)
+        return undefined;
+    const aggregateExcerpt = buildAggregateJobResultsExcerpt(lines);
+    if (aggregateExcerpt !== undefined)
+        return aggregateExcerpt;
+    const errorIndex = findLogExcerptAnchor(lines);
+    if (errorIndex === -1)
+        return truncateLogExcerpt(lines.slice(-LOG_EXCERPT_TAIL_LINES).join("\n"));
+    const start = Math.max(0, errorIndex - LOG_EXCERPT_CONTEXT_LINES);
+    const excerpt = lines.slice(start, Math.min(lines.length, errorIndex + LOG_EXCERPT_CONTEXT_LINES + 1));
+    return truncateAnchoredExcerpt(excerpt, errorIndex - start);
+}
+function findLogExcerptAnchor(lines) {
+    const explicitError = lines.findIndex((line) => line.includes("##[error]"));
+    if (explicitError !== -1)
+        return explicitError;
+    return lines.findIndex((line) => /\b(error|failed|cancelled)\b/i.test(line));
+}
+function buildAggregateJobResultsExcerpt(lines) {
+    const jobResults = extractJobResults(lines);
+    if (jobResults === undefined)
+        return undefined;
+    const failed = Object.entries(jobResults)
+        .map(([name, value]) => ({ name, result: extractJobResult(value) }))
+        .filter((entry) => entry.result !== undefined && !["success", "skipped"].includes(entry.result));
+    if (failed.length === 0)
+        return undefined;
+    const output = [
+        ...lines.filter((line) => /required jobs failed|exit code \d+/i.test(line)),
+        "Job results (non-success):",
+        ...failed.map((entry) => `${entry.name}: ${entry.result}`),
+    ];
+    return truncateLogExcerpt(output.join("\n"));
+}
+function extractJobResults(lines) {
+    const startIndex = lines.findIndex((line) => line.includes("Job results:"));
+    if (startIndex === -1)
+        return undefined;
+    const block = collectJsonBlock(lines, startIndex);
+    if (block === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(block);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectJsonBlock(lines, startIndex) {
+    const startLine = lines[startIndex] ?? "";
+    const objectStart = startLine.indexOf("{");
+    if (objectStart === -1)
+        return undefined;
+    const collected = [startLine.slice(objectStart)];
+    let depth = braceDepth(collected[0]);
+    for (let i = startIndex + 1; i < lines.length && depth > 0; i++) {
+        const line = lines[i] ?? "";
+        collected.push(line);
+        depth += braceDepth(line);
+    }
+    return depth === 0 ? collected.join("\n") : undefined;
+}
+function braceDepth(line) {
+    return [...line].reduce((depth, ch) => {
+        if (ch === "{")
+            return depth + 1;
+        if (ch === "}")
+            return depth - 1;
+        return depth;
+    }, 0);
+}
+function extractJobResult(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const result = value.result;
+    return typeof result === "string" ? result : undefined;
+}
+function truncateLogExcerpt(text) {
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    return `${text.slice(0, LOG_EXCERPT_MAX_CHARS - TRUNCATED_SUFFIX.length).trimEnd()}${TRUNCATED_SUFFIX}`;
+}
+function truncateAnchoredExcerpt(lines, anchorIndex) {
+    const text = lines.join("\n");
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    return truncateLogExcerpt(`${TRUNCATED_SUFFIX.trim()}\n${lines.slice(anchorIndex).join("\n")}`);
+}
+function cleanLogLine(line) {
+    return line
+        .replace(/^\uFEFF/, "")
+        .replace(ANSI_SGR_RE, "")
+        .replace(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\s*/, "")
+        .replace(/##\[(?:group|endgroup)\]/g, "")
+        .trimEnd();
+}

package/bin/classify/loader.mjs

@@ -32,22 +32,6 @@ function collectRuleFiles(dir) {
         .map((name) => join(dir, name))
         .sort();
 }
-let tsxAttempted = false;
-async function ensureTsxRegistered() {
-    if (tsxAttempted)
-        return;
-    tsxAttempted = true;
-    try {
-        const { register } = await import("tsx/esm/api");
-        register();
-        /* c8 ignore start */
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`pr-shepherd: failed to register tsx — .ts/.mts classification rules will not load: ${msg}\n`);
-    }
-    /* c8 ignore stop */
-}
 const ruleCache = new Map();
 export async function loadRules(files) {
     if (files.length === 0)
@@ -56,9 +40,6 @@ export async function loadRules(files) {
     const cached = ruleCache.get(cacheKey);
     if (cached !== undefined)
         return cached;
-    const hasTs = files.some((f) => f.endsWith(".ts") || f.endsWith(".mts"));
-    if (hasTs)
-        await ensureTsxRegistered();
     const rules = [];
     for (const file of files) {
         try {

package/bin/cli/fix-formatter.mjs

@@ -53,6 +53,8 @@ export function formatFixCodeResult(header, result) {
                     lines.push(`  > ${ch.failedStep}`);
                 if (ch.summary)
                     lines.push(`  > ${ch.summary}`);
+                if (ch.logExcerpt)
+                    lines.push(indentBlockquote(ch.logExcerpt, "  "));
             }
             return lines.join("\n");
         });
@@ -141,6 +143,12 @@ function renderCheckAnnotation(a) {
         lines.push(blockquote(a.rawDetails));
     return lines.join("\n");
 }
+function indentBlockquote(body, indent) {
+    return blockquote(body)
+        .split("\n")
+        .map((line) => `${indent}${line}`)
+        .join("\n");
+}
 function renderAnnotationRange(a) {
     if (a.startLine === null && a.endLine === null)
         return "?";

package/bin/commands/check.mjs

@@ -14,6 +14,7 @@ import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs"
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
+import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { normalizeBotUsernames } from "../comments/authors.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
@@ -98,6 +99,7 @@ export async function runCheck(opts) {
             .map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
     await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
+    const { threadIds: ruleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(partition, opts.autoMinimizeSuppressed);
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
     const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
     const approvedReviews = approvedReviewVisibility.visible;
@@ -132,16 +134,13 @@ export async function runCheck(opts) {
             autoResolved: [],
             autoResolveErrors: [],
             firstLook: threadVisibility.firstLookThreads,
-            ...(partition.ruleAutoResolveThreadIds.length > 0
-                ? { ruleAutoResolveIds: partition.ruleAutoResolveThreadIds }
+            ...(ruleAutoResolveThreadIds.length > 0
+                ? { ruleAutoResolveIds: ruleAutoResolveThreadIds }
                 : undefined),
         },
         comments: {
             actionable: visibleCommentClassification.actionable,
-            minimizeIds: [
-                ...visibleCommentClassification.minimizeIds,
-                ...partition.ruleAutoResolveCommentIds,
-            ],
+            minimizeIds: [...visibleCommentClassification.minimizeIds, ...ruleAutoResolveCommentIds],
             firstLook: firstLookComments,
         },
         changesRequestedReviews,
@@ -149,10 +148,39 @@ export async function runCheck(opts) {
         firstLookSummaries,
         editedSummaries,
         approvedReviews,
-        ...(partition.ruleAutoResolveReviewSummaryIds.length > 0
-            ? { ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds }
+        ...(ruleAutoResolveReviewSummaryIds.length > 0
+            ? { ruleAutoResolveReviewSummaryIds }
             : undefined),
         branchProtection: batchData.branchProtection,
         activity: batchData.activity,
     };
 }
+async function remainingRuleAutoResolveIds(partition, autoMinimizeSuppressed = false) {
+    const consumedIds = autoMinimizeSuppressed
+        ? await selfApplySuppressedRuleAutoResolve(partition)
+        : { minimized: new Set(), resolvedThreads: new Set() };
+    return {
+        threadIds: partition.ruleAutoResolveThreadIds.filter((id) => !consumedIds.resolvedThreads.has(id)),
+        commentIds: partition.ruleAutoResolveCommentIds.filter((id) => !consumedIds.minimized.has(id)),
+        reviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => !consumedIds.minimized.has(id)),
+    };
+}
+async function selfApplySuppressedRuleAutoResolve(partition) {
+    const minimizeIds = [
+        ...partition.ruleAutoResolveCommentIds.filter((id) => partition.suppressedCommentIds.has(id)),
+        ...partition.ruleAutoResolveReviewSummaryIds.filter((id) => partition.suppressedReviewSummaryIds.has(id)),
+    ];
+    const threadIds = partition.ruleAutoResolveThreadIds.filter((id) => partition.suppressedThreadIds.has(id));
+    const [minimized, resolved] = await Promise.all([
+        minimizeIds.length > 0
+            ? autoMinimizeComments(minimizeIds)
+            : Promise.resolve({ minimized: [], errors: [] }),
+        threadIds.length > 0
+            ? autoResolveThreads(threadIds)
+            : Promise.resolve({ resolved: [], errors: [] }),
+    ]);
+    return {
+        minimized: new Set(minimized.minimized),
+        resolvedThreads: new Set(resolved.resolved),
+    };
+}

package/bin/commands/iterate/check-instructions.mjs

@@ -18,7 +18,7 @@ export function buildFailingCheckInstructions(checks) {
     const hasBare = checks.some((c) => !c.runId && !c.detailsUrl);
     const parts = [];
     if (hasRunId) {
-        parts.push("fetch the log with `gh run view <runId> --log-failed` and decide: rerun with `gh run rerun <runId> --failed` for transient infrastructure failures (network timeout, OOM kill, runner crash), or apply a code fix for real test/build failures");
+        parts.push("read any included log excerpt first; fetch the full log with `gh run view <runId> --log-failed` when the excerpt is insufficient; decide whether to rerun with `gh run rerun <runId> --failed` for transient infrastructure failures (network timeout, OOM kill, runner crash), or apply a code fix for real test/build failures; if GitHub omits workflow-evaluation details from API/log output, open the run URL in the GitHub UI");
     }
     if (hasCancelled) {
         parts.push("for `[conclusion: CANCELLED]` entries: rerun with `gh run rerun <runId>` if the cancellation looks unintended (not superseded by a newer push or concurrency-group eviction); otherwise treat as resolved — do NOT confuse with IDs under `## Cancelled runs`");

package/bin/commands/iterate/helpers.mjs

@@ -53,6 +53,7 @@ export function buildRelevantChecks(report) {
                 ...(c.jobName !== undefined && { jobName: c.jobName }),
                 ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
                 ...(c.summary !== undefined && { summary: c.summary }),
+                ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
                 ...(c.annotations !== undefined && { annotations: c.annotations }),
             },
         ];

package/bin/commands/iterate/index.mjs

@@ -23,6 +23,7 @@ export async function runIterate(opts) {
     const report = await runCheck({
         ...optsWithPr,
         autoResolve: config.actions.autoResolveOutdated,
+        autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
     });
     const [repoOwner, repoName] = report.repo.split("/");
     if (!repoOwner || !repoName) {

package/bin/comments/resolve.mjs

@@ -57,6 +57,11 @@ export async function applyResolveOptions(pr, repo, opts) {
     return result;
 }
 export async function autoResolveOutdated(threadIds) {
+    return autoResolveThreads(threadIds);
+}
+export async function autoResolveThreads(threadIds) {
+    if (threadIds.length === 0)
+        return { resolved: [], errors: [] };
     const result = {
         repliedThreads: [],
         resolvedThreads: [],
@@ -67,6 +72,19 @@ export async function autoResolveOutdated(threadIds) {
     await bulkApply([], threadIds, [], [], "", result);
     return { resolved: result.resolvedThreads, errors: result.errors };
 }
+export async function autoMinimizeComments(minimizeIds) {
+    if (minimizeIds.length === 0)
+        return { minimized: [], errors: [] };
+    const result = {
+        repliedThreads: [],
+        resolvedThreads: [],
+        minimizedComments: [],
+        dismissedReviews: [],
+        errors: [],
+    };
+    await bulkApply([], [], minimizeIds, [], "", result);
+    return { minimized: result.minimizedComments, errors: result.errors };
+}
 // Keep mutation batches small so rate-limit stops leave a precise pending list.
 const BULK_CHUNK_SIZE = 10;
 function buildBulkMutation(replyIds, resolveIds, minimizeIds, dismissIds, dismissMessage) {

package/bin/config.json

@@ -37,6 +37,7 @@
   },
   "actions": {
     "autoResolveOutdated": true,
+    "autoMinimizeSuppressed": true,
     "autoMarkReady": true,
     "commitSuggestions": true
   }

package/bin/github/check-annotations.mjs

@@ -3,6 +3,8 @@ import { graphql } from "./client.mjs";
 import { CHECK_RUN_ANNOTATIONS_QUERY } from "./queries.mjs";
 const ANNOTATIONS_PER_PAGE = 100;
 const MAX_ANNOTATION_PAGES = 10;
+const ANNOTATION_TEXT_MAX_CHARS = 4_000;
+const TRUNCATED_SUFFIX = "\n[truncated]";
 export async function fetchCheckRunAnnotations(checkRunId) {
     let cursor = null;
     const nodes = [];
@@ -49,11 +51,16 @@ function toCheckAnnotation(checkRunId, raw) {
         }),
         level: raw.annotationLevel,
         ...(title !== undefined && { title }),
-        message: raw.message,
-        ...(rawDetails !== undefined && { rawDetails }),
+        message: truncateAnnotationText(raw.message),
+        ...(rawDetails !== undefined && { rawDetails: truncateAnnotationText(rawDetails) }),
         ...(blobUrl !== undefined && { blobUrl }),
     };
 }
+function truncateAnnotationText(text) {
+    if (text.length <= ANNOTATION_TEXT_MAX_CHARS)
+        return text;
+    return `${text.slice(0, ANNOTATION_TEXT_MAX_CHARS - TRUNCATED_SUFFIX.length).trimEnd()}${TRUNCATED_SUFFIX}`;
+}
 function fallbackId(checkRunId, raw) {
     const start = raw.location?.start;
     const end = raw.location?.end;

package/bin/reporters/agent.mjs

@@ -59,6 +59,7 @@ export function toAgentCheck(c) {
         ...(c.jobName !== undefined && { jobName: c.jobName }),
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
+        ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
         ...(c.annotations !== undefined && { annotations: c.annotations }),
     };
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "pr-shepherd",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
   "type": "module",
   "bin": {
-    "pr-shepherd": "bin/pr-shepherd"
+    "pr-shepherd": "bin/index.mjs"
   },
   "files": [
     "bin/**",
@@ -20,11 +20,10 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.18.0"
   },
   "dependencies": {
     "picomatch": "^4.0.4",
-    "tsx": "^4.22.4",
     "yaml": "^2.7.0"
   },
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/bin/pr-shepherd

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import("./index.mjs")