pr-shepherd 0.32.5 → 0.34.0

package/bin/github/graphql-http.mjs

@@ -1,11 +1,12 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
+import { formatGraphQlErrors, parseGraphQlPayload } from "./graphql-response.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
 const BASE_URL = "https://api.github.com";
-async function graphqlInner(query, vars) {
+async function graphqlInner(query, vars, opts) {
     const url = `${BASE_URL}/graphql`;
     const n = nextEntry();
     appendEntry(formatRequestEntry({
@@ -38,7 +39,28 @@ async function graphqlInner(query, vars) {
         }));
         throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, { status: res.status, rateLimit: rateLimit ?? undefined, retryAfterSeconds });
     }
-    const parsed = (await res.json());
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch (err) {
+        const detail = err instanceof Error ? `: ${err.message}` : "";
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "GraphQL",
+            method: "POST",
+            url,
+            status: res.status,
+            durationMs,
+            textBody: `Invalid JSON response${detail}`,
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
+        throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
+            status: res.status,
+            rateLimit: rateLimit ?? undefined,
+            retryAfterSeconds,
+        });
+    }
     appendEntry(formatResponseEntry({
         n,
         kind: "GraphQL",
@@ -49,25 +71,35 @@ async function graphqlInner(query, vars) {
         body: parsed,
         attempt: attempt > 1 ? attempt : undefined,
     }));
-    if (parsed.data == null) {
-        const messages = (parsed.errors ?? []).map((e) => e.message).join("; ");
-        throw new GitHubRequestError(`GitHub GraphQL error (no data): ${messages}`, {
+    const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);
+    if (payload.data == null) {
+        const detail = formatGraphQlErrors(payload.errors);
+        throw new GitHubRequestError(`GitHub GraphQL error (no data)${detail ? `: ${detail}` : ""}`, {
+            status: res.status,
+            rateLimit: rateLimit ?? undefined,
+            retryAfterSeconds,
+            graphqlErrors: payload.errors,
+        });
+    }
+    if (payload.errors?.length && !opts.allowPartialData) {
+        throw new GitHubRequestError(`GitHub GraphQL error: ${formatGraphQlErrors(payload.errors)}`, {
             status: res.status,
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
+            graphqlErrors: payload.errors,
         });
     }
-    if (parsed.errors?.length) {
-        const messages = parsed.errors.map((e) => e.message).join("; ");
+    if (payload.errors?.length) {
+        const messages = payload.errors.map((e) => e.message).join("; ");
         process.stderr.write(`pr-shepherd: GraphQL non-fatal errors: ${messages}\n`);
     }
-    return { data: parsed.data, rateLimit, retryAfterSeconds, errors: parsed.errors };
+    return { data: payload.data, rateLimit, retryAfterSeconds, errors: payload.errors };
 }
-export async function graphql(query, vars = {}) {
-    const { data } = await graphqlInner(query, vars);
-    return { data };
+export async function graphql(query, vars = {}, opts = {}) {
+    const { data, errors } = await graphqlInner(query, vars, opts);
+    return { data, errors };
 }
-export async function graphqlWithRateLimit(query, vars = {}) {
-    const { data, rateLimit, retryAfterSeconds, errors } = await graphqlInner(query, vars);
+export async function graphqlWithRateLimit(query, vars = {}, opts = {}) {
+    const { data, rateLimit, retryAfterSeconds, errors } = await graphqlInner(query, vars, opts);
     return { data, rateLimit: rateLimit ?? undefined, retryAfterSeconds, errors };
 }

package/bin/github/graphql-response.mjs

@@ -0,0 +1,47 @@
+import { EXIT } from "../exit-codes.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds) {
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw malformedGraphQlResponse("expected a JSON object", status, rateLimit, retryAfterSeconds);
+    }
+    const record = parsed;
+    let errors;
+    if (record["errors"] !== undefined) {
+        if (!Array.isArray(record["errors"]) ||
+            !record["errors"].every((error) => typeof error === "object" &&
+                error !== null &&
+                typeof error["message"] === "string")) {
+            throw malformedGraphQlResponse("errors field is not an array of GraphQL errors", status, rateLimit, retryAfterSeconds);
+        }
+        errors = record["errors"];
+    }
+    if (!("data" in record)) {
+        if (errors?.length)
+            return { data: null, errors };
+        throw malformedGraphQlResponse("missing data field", status, rateLimit, retryAfterSeconds);
+    }
+    if (record["data"] !== null &&
+        (typeof record["data"] !== "object" || Array.isArray(record["data"]))) {
+        throw malformedGraphQlResponse("data field is not an object or null", status, rateLimit, retryAfterSeconds);
+    }
+    return { data: record["data"] ?? null, errors };
+}
+export function formatGraphQlErrors(errors) {
+    return (errors ?? [])
+        .map((error) => {
+        const path = Array.isArray(error.path) ? error.path.map(String).join(".") : "";
+        return path ? `${error.message} (path: ${path})` : error.message;
+    })
+        .join("; ");
+}
+function malformedGraphQlResponse(detail, status, rateLimit, retryAfterSeconds) {
+    // A response that fails to parse as valid GraphQL shape is an internal/unexpected
+    // failure, not a precondition or permission problem — force EX_SOFTWARE rather
+    // than letting the (likely 200) status fall through to EX_UNAVAILABLE.
+    return new GitHubRequestError(`Malformed GitHub GraphQL response: ${detail}`, {
+        status,
+        rateLimit: rateLimit ?? undefined,
+        retryAfterSeconds,
+        exitCodeOverride: EXIT.SOFTWARE,
+    });
+}

package/bin/github/http-auth.mjs

@@ -1,5 +1,6 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const execFile = promisify(execFileCb);
 let _token;
 export function _resetTokenCache() {
@@ -35,7 +36,7 @@ async function resolveToken() {
         _token = codexToken;
         return _token;
     }
-    throw new Error("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.");
+    throw new ShepherdError("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.", EXIT.NOPERM);
 }
 export async function makeHeaders() {
     return {

package/bin/github/rest-http.mjs

@@ -1,8 +1,9 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { GitHubRequestError } from "./errors.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
-import { redactToken, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { parseRateLimit, parseRetryAfter, redactToken, redactUrl, sanitizeBody, } from "./http-utils.mjs";
 const BASE_URL = "https://api.github.com";
 export async function rest(method, path, body) {
     const url = `${BASE_URL}${path}`;
@@ -28,7 +29,11 @@ export async function rest(method, path, body) {
             textBody: redactToken(text),
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        throw new Error(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`);
+        throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
     }
     if (ct.includes("application/json")) {
         const json = (await res.json());
@@ -80,7 +85,11 @@ export async function restText(path) {
             durationMs,
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        throw new Error(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`);
+        throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
     }
     appendEntry(formatResponseEntry({
         n,
@@ -121,8 +130,13 @@ async function followRestTextRedirect(res, entry) {
         durationMs: Math.round(performance.now() - t1),
         contentLength: parseContentLength(redirectRes.headers),
     }));
-    if (!redirectRes.ok)
-        throw new Error(`redirect target ${location} failed: ${redirectRes.status}`);
+    if (!redirectRes.ok) {
+        throw new GitHubRequestError(`redirect target ${location} failed: ${redirectRes.status}`, {
+            status: redirectRes.status,
+            rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(redirectRes.headers),
+        });
+    }
     return redirectRes.text();
 }
 function parseContentLength(headers) {

package/bin/index.mjs

@@ -8,6 +8,7 @@
  *   pr-shepherd iterate [PR]
  */
 import { main } from "./cli-parser.mjs";
+import { errorToExitCode } from "./exit-codes.mjs";
 function formatCause(cause, seen = new Set(), depth = 0) {
     if (depth > 5 || seen.has(cause))
         return "[circular or deep cause chain]";
@@ -23,5 +24,5 @@ main(process.argv).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
     const causeStr = err instanceof Error && err.cause != null ? formatCause(err.cause) : null;
     process.stderr.write(`pr-shepherd error: ${msg}${causeStr !== null ? ` (cause: ${causeStr})` : ""}\n`);
-    process.exit(1);
+    process.exit(errorToExitCode(err));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.32.5",
+  "version": "0.34.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -38,9 +38,9 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.57.0",
+    "oxfmt": "^0.60.0",
     "oxlint": "^1.60.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.4"
   },
   "scripts": {

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.32.5",
+  "version": "0.34.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,7 +20,7 @@ Poll dispatcher for iterating a PR to completion.
 
 3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. `[FIX_CODE]` is non-terminal: do its instructions, then poll again. The poll already waits between ticks via `--interval`; do not add manual `sleep`s between ticks.
 
-4. **Nonzero exit codes:** Treat a nonzero poll exit as PR state only when the output contains a matching `# PR #$N [ACTION]` heading. Exit `1` can also mean a command or validation failure; if there is no `[ACTION]` heading, surface the error and stop instead of looping.
+4. **Exit codes:** an exit code of `64` or higher means the `pr-shepherd` command itself failed (bad flag, GitHub auth/permission error, transient failure, etc.) — surface the error and stop instead of looping. Any other exit code (`0` or `10`–`19`) means the command ran and the output above is real PR state — proceed to step 5.
 
 5. **Terminal states (stop):**
    - `[CANCEL]` — ready-delay completed, or PR merged/closed.