pr-shepherd 0.20.0 → 0.22.0

package/bin/github/gql/check-run-annotations.gql

@@ -0,0 +1,32 @@
+query CheckRunAnnotations($id: ID!, $cursor: String) {
+  node(id: $id) {
+    __typename
+    ... on CheckRun {
+      annotations(first: 100, after: $cursor) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          fullDatabaseId
+          path
+          annotationLevel
+          title
+          message
+          rawDetails
+          blobUrl
+          location {
+            start {
+              line
+              column
+            }
+            end {
+              line
+              column
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/review-thread-comments.gql

@@ -0,0 +1,27 @@
+query ReviewThreadComments($threadId: ID!, $commentsCursor: String) {
+  node(id: $threadId) {
+    __typename
+    ... on PullRequestReviewThread {
+      comments(first: 100, after: $commentsCursor) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          id
+          isMinimized
+          url
+          author {
+            __typename
+            login
+          }
+          body
+          path
+          line
+          startLine
+          createdAt
+        }
+      }
+    }
+  }
+}

package/bin/github/http.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 // ---------------------------------------------------------------------------
 // Stub fetch and child_process globally before any imports.
 // ---------------------------------------------------------------------------

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");
+/** 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. */
+export const CHECK_RUN_ANNOTATIONS_QUERY = gql("check-run-annotations.gql");
 /** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
 export const GET_PR_HEAD_SHA_QUERY = gql("get-pr-head-sha.gql");
 /** Look up PR number by branch name (for getCurrentPrNumber). */

package/bin/github/thread-comments.mjs

@@ -0,0 +1,34 @@
+import { graphql } from "./client.mjs";
+import { paginateForward } from "./pagination.mjs";
+import { REVIEW_THREAD_COMMENTS_QUERY } from "./queries.mjs";
+export async function hydrateThreadCommentPages(threads) {
+    const hydrated = [];
+    for (const thread of threads) {
+        hydrated.push(await hydrateThreadCommentPage(thread));
+    }
+    return hydrated;
+}
+async function hydrateThreadCommentPage(thread) {
+    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, {
+            threadId: thread.id,
+            ...(cursor ? { commentsCursor: cursor } : {}),
+        });
+        const node = res.data.node;
+        if (!node?.comments) {
+            const nodeType = node?.__typename ?? "null";
+            throw new Error(`Review thread ${thread.id} did not resolve to PullRequestReviewThread while paginating comments (node type: ${nodeType})`);
+        }
+        return node.comments;
+    }, pageInfo.endCursor);
+    return {
+        ...thread,
+        comments: {
+            pageInfo: { hasNextPage: false, endCursor: null },
+            nodes: [...thread.comments.nodes, ...extra],
+        },
+    };
+}

package/bin/reporters/agent.mjs

@@ -22,6 +22,15 @@ export function toAgentThread(t) {
         ...(t.authorType !== undefined && { authorType: t.authorType }),
         body: t.body,
         url: t.url,
+        ...(t.comments !== undefined && {
+            comments: t.comments.map((c) => ({
+                id: c.id,
+                author: c.author,
+                ...(c.authorType !== undefined && { authorType: c.authorType }),
+                body: c.body,
+                url: c.url,
+            })),
+        }),
         ...(suggestion !== undefined && { suggestion }),
     };
 }
@@ -48,6 +57,23 @@ export function toAgentCheck(c) {
         ...(c.jobName !== undefined && { jobName: c.jobName }),
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
+        ...(c.annotations !== undefined && { annotations: c.annotations }),
+    };
+}
+export function toAgentStalledCheck(c, nowSeconds) {
+    const createdAtUnix = c.createdAtUnix ?? nowSeconds;
+    const activityAtUnix = c.updatedAtUnix ?? createdAtUnix;
+    return {
+        name: c.name,
+        status: c.status,
+        source: c.source ?? "check_run",
+        runId: c.runId,
+        detailsUrl: c.detailsUrl || null,
+        ...(c.createdAtUnix !== undefined && { createdAtUnix: c.createdAtUnix }),
+        ...(c.startedAtUnix !== undefined && { startedAtUnix: c.startedAtUnix }),
+        ...(c.updatedAtUnix !== undefined && { updatedAtUnix: c.updatedAtUnix }),
+        ageSeconds: Math.max(0, nowSeconds - activityAtUnix),
+        ...(c.summary !== undefined && { summary: c.summary }),
     };
 }
 /**

package/bin/state/seen-comments.test-support.mjs

@@ -0,0 +1,19 @@
+import { beforeEach, afterEach } from "vitest";
+import { randomBytes, createHash } from "node:crypto";
+import { rm } from "node:fs/promises";
+export function idToFilename(id) {
+    return createHash("sha256").update(id, "utf8").digest("hex") + ".json";
+}
+export const testKey = { owner: "test-owner", repo: "test-repo", pr: 123 };
+export const testId = "PRRT_kwDOTest123";
+export let testStateDir;
+export function registerHooks() {
+    beforeEach(() => {
+        testStateDir = `${process.env["TMPDIR"] ?? "/tmp"}/shepherd-seen-test-${randomBytes(4).toString("hex")}`;
+        process.env["PR_SHEPHERD_STATE_DIR"] = testStateDir;
+    });
+    afterEach(async () => {
+        delete process.env["PR_SHEPHERD_STATE_DIR"];
+        await rm(testStateDir, { recursive: true, force: true });
+    });
+}

package/bin/suggestions/patch.test-support.mjs

@@ -1,4 +1,2 @@
-// @ts-nocheck
-import { describe, it, expect } from "vitest";
 import { buildUnifiedDiff } from "./patch.mjs";
 export { buildUnifiedDiff };

package/bin/threads/transcript.mjs

@@ -0,0 +1,31 @@
+export function threadComments(thread) {
+    if (thread.comments && thread.comments.length > 0) {
+        return thread.comments.map((c) => ({
+            id: c.id,
+            isMinimized: c.isMinimized ?? false,
+            author: c.author,
+            authorType: c.authorType ?? "Unknown",
+            body: c.body,
+            url: c.url,
+            createdAtUnix: c.createdAtUnix ?? 0,
+        }));
+    }
+    return [
+        {
+            id: "",
+            isMinimized: false,
+            author: thread.author,
+            authorType: thread.authorType ?? "Unknown",
+            body: thread.body,
+            url: thread.url ?? "",
+            createdAtUnix: thread.createdAtUnix ?? 0,
+        },
+    ];
+}
+export function threadTranscriptBody(thread) {
+    if (!thread.comments || thread.comments.length === 0)
+        return thread.body;
+    return threadComments(thread)
+        .map((c) => `${c.id}\n${c.body}`)
+        .join("\n\n--- thread comment ---\n\n");
+}

package/bin/types/agent-thread.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/check-annotations.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/review-thread.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types.mjs

@@ -1,4 +1,7 @@
 /** Shared type definitions for the shepherd CLI. */
 export * from "./types/github.mjs";
+export * from "./types/review-thread.mjs";
+export * from "./types/agent-thread.mjs";
+export * from "./types/check-annotations.mjs";
 export * from "./types/report.mjs";
 export * from "./types/iterate.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

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

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

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

@@ -20,24 +20,24 @@ Poll dispatcher for iterating a PR to completion.
    - Otherwise, infer: `gh pr view --json number --jq .number`
    - If no PR found, report an error and stop.
 
-2. **Run `pr-shepherd poll`:**
+2. **Run `pr-shepherd`:**
 
    ```bash
-   pr-shepherd poll <N>
+   pr-shepherd <N> --interval 45s --timeout 4m
    ```
 
-   Do not pass `$ARGUMENTS` through as extra flags. If you need to inspect supported options, run `pr-shepherd poll --help`.
+   Do not pass `$ARGUMENTS` through as extra flags. If you need to inspect supported options, run `pr-shepherd --help`.
 
-   Print the full output. Follow the `## Instructions` section exactly for the current action. When those instructions tell you to stop and recheck with `pr-shepherd <N>` after a delay, use `pr-shepherd poll <N>` as the next invocation instead; do not also run the one-shot command.
+   Print the full output. Follow the `## Instructions` section exactly for the current action.
 
-3. **Persistence:** Continuously call `pr-shepherd poll <N>` until the CLI returns `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action is non-terminal:
-   - `[WAIT]`: call `pr-shepherd poll <N>` again.
-   - `[MARK_READY]`: call `pr-shepherd poll <N>` again.
-   - `[FIX_CODE]`: follow the output's `## Instructions`, then call `pr-shepherd poll <N>` again.
+3. **Persistence:** Continuously call `pr-shepherd <N> --interval 45s --timeout 4m` until the CLI returns `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action is non-terminal:
+   - `[WAIT]`: call `pr-shepherd <N> --interval 45s --timeout 4m` again.
+   - `[MARK_READY]`: call `pr-shepherd <N> --interval 45s --timeout 4m` again.
+   - `[FIX_CODE]`: follow the output's `## Instructions`, then call `pr-shepherd <N> --interval 45s --timeout 4m` again.
 
    Treat a nonzero poll exit code as PR state only when the output contains a matching `# PR #N [ACTION]` heading. Exit code `1` can also mean a command or validation failure; if there is no `[FIX_CODE]` heading, surface the error and stop instead of looping.
 
 4. **Stop conditions (terminal states):**
    - Stop when the CLI emits `[CANCEL]` (ready-delay completed, or PR merged/closed).
-   - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures.
+   - Stop when the CLI emits `[ESCALATE]`, including `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.

package/bin/cli/default-iterate.mjs

@@ -1,50 +0,0 @@
-import { parsePrNumber } from "./args.mjs";
-import { USAGE } from "./help.mjs";
-const DEFAULT_ITERATE_FLAGS_WITH_VALUES = new Set(["--format", "--ready-delay", "--stall-timeout"]);
-const DEFAULT_ITERATE_BOOLEAN_FLAGS = new Set([
-    "--verbose",
-    "--no-auto-mark-ready",
-    "--no-auto-cancel-actionable",
-]);
-export function isDefaultIterateInvocation(subcommand) {
-    if (subcommand === "--help" || subcommand === "-h")
-        return false;
-    return (subcommand === undefined ||
-        parsePrNumber(subcommand) !== null ||
-        isDefaultIterateFlag(subcommand));
-}
-export function validateDefaultIterateArgs(args) {
-    let sawPr = false;
-    for (let i = 0; i < args.length; i += 1) {
-        const arg = args[i];
-        if (DEFAULT_ITERATE_FLAGS_WITH_VALUES.has(arg)) {
-            if (i + 1 >= args.length || args[i + 1].startsWith("--")) {
-                writeDefaultUsageError(arg);
-                return false;
-            }
-            i += 1;
-            continue;
-        }
-        const inlineFlag = arg.split("=", 1)[0];
-        if (DEFAULT_ITERATE_FLAGS_WITH_VALUES.has(inlineFlag))
-            continue;
-        if (DEFAULT_ITERATE_BOOLEAN_FLAGS.has(arg))
-            continue;
-        if (parsePrNumber(arg) !== null && !sawPr) {
-            sawPr = true;
-            continue;
-        }
-        writeDefaultUsageError(arg);
-        return false;
-    }
-    return true;
-}
-function isDefaultIterateFlag(arg) {
-    const name = arg.split("=", 1)[0];
-    return DEFAULT_ITERATE_FLAGS_WITH_VALUES.has(name) || DEFAULT_ITERATE_BOOLEAN_FLAGS.has(arg);
-}
-function writeDefaultUsageError(arg) {
-    process.stderr.write(`Unknown subcommand: ${arg}\n`);
-    process.stderr.write(`${USAGE.top}\n`);
-    process.exitCode = 1;
-}