pr-shepherd 0.21.0 → 0.23.0

package/bin/github/check-annotations.mjs

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { graphql } from "./client.mjs";
+import { CHECK_RUN_ANNOTATIONS_QUERY } from "./queries.mjs";
+const ANNOTATIONS_PER_PAGE = 100;
+const MAX_ANNOTATION_PAGES = 10;
+export async function fetchCheckRunAnnotations(checkRunId) {
+    let cursor = null;
+    const nodes = [];
+    for (let page = 1; page <= MAX_ANNOTATION_PAGES; page++) {
+        // eslint-disable-next-line no-await-in-loop
+        const result = await fetchAnnotationPage(checkRunId, cursor);
+        nodes.push(...result.nodes);
+        if (!result.pageInfo.hasNextPage || !result.pageInfo.endCursor)
+            break;
+        if (page === MAX_ANNOTATION_PAGES) {
+            process.stderr.write(`pr-shepherd: annotation pagination cap (${MAX_ANNOTATION_PAGES * ANNOTATIONS_PER_PAGE} annotations) reached for check run ${checkRunId} — annotation output may be incomplete\n`);
+            break;
+        }
+        cursor = result.pageInfo.endCursor;
+    }
+    return nodes.map((node) => toCheckAnnotation(checkRunId, node));
+}
+async function fetchAnnotationPage(checkRunId, cursor) {
+    const res = await graphql(CHECK_RUN_ANNOTATIONS_QUERY, {
+        id: checkRunId,
+        ...(cursor ? { cursor } : {}),
+    });
+    const node = res.data.node;
+    if (node?.__typename !== "CheckRun" || node.annotations === undefined) {
+        return { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
+    }
+    return node.annotations;
+}
+function toCheckAnnotation(checkRunId, raw) {
+    const id = `check_annotation_${raw.fullDatabaseId ?? fallbackId(checkRunId, raw)}`;
+    const title = raw.title?.trim() || undefined;
+    const rawDetails = raw.rawDetails?.trim() || undefined;
+    const blobUrl = raw.blobUrl?.trim() || undefined;
+    return {
+        id,
+        path: raw.path,
+        startLine: raw.location?.start.line ?? null,
+        endLine: raw.location?.end.line ?? raw.location?.start.line ?? null,
+        ...(raw.location?.start.column !== undefined && {
+            startColumn: raw.location.start.column,
+        }),
+        ...(raw.location?.end.column !== undefined && {
+            endColumn: raw.location.end.column,
+        }),
+        level: raw.annotationLevel,
+        ...(title !== undefined && { title }),
+        message: raw.message,
+        ...(rawDetails !== undefined && { rawDetails }),
+        ...(blobUrl !== undefined && { blobUrl }),
+    };
+}
+function fallbackId(checkRunId, raw) {
+    const start = raw.location?.start;
+    const end = raw.location?.end;
+    const parts = [
+        checkRunId,
+        raw.path,
+        raw.annotationLevel,
+        raw.title ?? "",
+        raw.message,
+        raw.rawDetails ?? "",
+        raw.blobUrl ?? "",
+        String(start?.line ?? ""),
+        String(start?.column ?? ""),
+        String(end?.line ?? ""),
+        String(end?.column ?? ""),
+    ];
+    const input = parts.map((part) => `${part.length}:${part}`).join("|");
+    return createHash("sha256").update(input).digest("hex").slice(0, 24);
+}

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

@@ -0,0 +1,55 @@
+import { vi, beforeEach, afterEach } from "vitest";
+import { _resetTokenCache } from "./http.mjs";
+export const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+const { _mockExecFile } = vi.hoisted(() => ({ _mockExecFile: vi.fn() }));
+export const mockExecFile = _mockExecFile;
+vi.mock("node:child_process", () => ({
+    execFile: (cmd, args, optsOrCb, maybeCb) => {
+        const cb = typeof optsOrCb === "function" ? optsOrCb : maybeCb;
+        _mockExecFile(cmd, args)
+            .then((result) => cb(null, result))
+            .catch((err) => cb(err, { stdout: "", stderr: "" }));
+    },
+}));
+export function gqlOk(data) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve({ data }),
+        text: () => Promise.resolve(JSON.stringify({ data })),
+    };
+}
+export function restOk(data) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve(data),
+        text: () => Promise.resolve(JSON.stringify(data)),
+    };
+}
+export function gqlErrors(errors) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve({ data: null, errors }),
+        text: () => Promise.resolve(JSON.stringify({ data: null, errors })),
+    };
+}
+export function registerClientHooks() {
+    beforeEach(() => {
+        mockFetch.mockReset();
+        mockExecFile.mockReset();
+        _resetTokenCache();
+        delete process.env["GITHUB_TOKEN"];
+        delete process.env["GITHUB_PERSONAL_ACCESS_TOKEN"];
+        process.env["GH_TOKEN"] = "test-token";
+    });
+    afterEach(() => {
+        delete process.env["GH_TOKEN"];
+        _resetTokenCache();
+    });
+}

package/bin/github/gql/batch-pr.gql

@@ -67,8 +67,14 @@ query BatchPr(
           id
           isResolved
           isOutdated
-          # first: 1 — we want the reviewer's original comment, not the latest reply.
-          comments(first: 1) {
+          path
+          line
+          startLine
+          comments(first: 100) {
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
             nodes {
               id
               isMinimized
@@ -164,21 +170,28 @@ query BatchPr(
                 nodes {
                   __typename
                   ... on CheckRun {
+                    id
                     name
                     status
                     conclusion
                     detailsUrl
+                    startedAt
                     title
                     summary
                     checkSuite {
+                      createdAt
+                      updatedAt
                       workflowRun {
                         event
+                        createdAt
+                        updatedAt
                       }
                     }
                   }
                   ... on StatusContext {
                     context
                     state
+                    createdAt
                     targetUrl
                     description
                   }

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/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,16 @@ export function toAgentThread(t) {
         ...(t.authorType !== undefined && { authorType: t.authorType }),
         body: t.body,
         url: t.url,
+        ...(t.edited === true && { edited: true }),
+        ...(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 +58,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/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,
+        },
+    ];
+}
+const THREAD_COMMENT_SEPARATOR = "\n\n--- thread comment ---\n\n";
+export function threadTranscriptBody(thread, appendedBodies = []) {
+    const bodies = thread.comments && thread.comments.length > 0
+        ? threadComments(thread).map((c) => c.body)
+        : [thread.body];
+    return [...bodies, ...appendedBodies].join(THREAD_COMMENT_SEPARATOR);
+}

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.21.0",
+  "version": "0.23.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.21.0",
+  "version": "0.23.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

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

@@ -0,0 +1,31 @@
+---
+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".'
+user-invocable: true
+argument-hint: "[PR number or URL] [files|tests|--tests|--match REGEX]"
+allowed-tools: ["Bash", "Read", "Grep", "Glob"]
+---
+
+# mark-files-as-viewed
+
+Thin dispatcher for marking GitHub PR changed files as viewed.
+
+## Arguments: $ARGUMENTS
+
+## Steps
+
+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.

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

@@ -39,5 +39,5 @@ Poll dispatcher for iterating a PR to completion.
 
 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.