dev-loops 0.2.5 → 0.2.7

package/scripts/github/reconcile-draft-gate.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { loadDevLoopConfig, resolveGateConfig } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectCheckpointEvidence } from "./detect-checkpoint-evidence.mjs";
@@ -36,27 +37,38 @@ Exit codes:
   1  Argument error, gh failure, or unrecoverable state`.trim();
 const parseError = buildParseError(USAGE);
 export function parseReconcileDraftGateCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
     pr: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const missing = ["repo", "pr"].filter((key) => options[key] === undefined);
   if (missing.length > 0) {

package/scripts/github/reply-resolve-review-threads.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import {
   parsePrNumber,
-  requireOptionValue,
+  requireTokenValue,
 } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
@@ -34,7 +35,20 @@ Exit codes:
   1  Argument error or gh/runtime failure`.trim();
 const parseError = buildParseError(USAGE);
 export function parseReplyResolveThreadsCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      author: { type: "string" },
+      message: { type: "string" },
+      resolve: { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
@@ -43,33 +57,38 @@ export function parseReplyResolveThreadsCliArgs(argv) {
     message: undefined,
     resolve: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--author") {
-      options.author = requireOptionValue(args, "--author", parseError).trim();
+    if (token.name === "author") {
+      options.author = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--message") {
-      options.message = requireOptionValue(args, "--message", parseError);
+    if (token.name === "message") {
+      options.message = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--resolve") {
+    if (token.name === "resolve") {
       options.resolve = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("Replying and resolving review threads requires both --repo <owner/name> and --pr <number>");

package/scripts/github/request-copilot-review.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import {
   buildParseError,
   formatCliError,
@@ -7,7 +8,7 @@ import {
   parseReviewThreads,
   summarizeCopilotReviews,
 } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState } from "@dev-loops/core/loop/copilot-loop-state";
@@ -52,32 +53,48 @@ Exit codes:
   1  Argument error or gh failure`.trim();
 const parseError = buildParseError(USAGE);
 export function parseRequestCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "force-rerequest-review": { type: "boolean" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
     pr: undefined,
     forceRerequestReview: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--force-rerequest-review") {
+    if (token.name === "force-rerequest-review") {
       options.forceRerequestReview = true;
       continue;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("Requesting Copilot review requires both --repo <owner/name> and --pr <number>");

package/scripts/github/resolve-tracker-local-spec.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parseIssueNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 const ISSUE_JSON_FIELDS = "number,title,body,url,state";
 const USAGE = `Usage: resolve-tracker-local-spec.mjs (--repo <owner/name> --issue <number> | --issue-url <github-issue-url>)
@@ -60,32 +61,48 @@ export function parseGitHubIssueUrl(value) {
   };
 }
 export function parseResolveTrackerLocalSpecCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      issue: { type: "string" },
+      "issue-url": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
     issue: undefined,
     issueUrl: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--issue") {
-      options.issue = parseIssueNumber(requireOptionValue(args, "--issue", parseError), parseError);
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--issue-url") {
-      options.issueUrl = requireOptionValue(args, "--issue-url", parseError).trim();
+    if (token.name === "issue-url") {
+      options.issueUrl = requireTokenValue(token, parseError).trim();
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const usingIssueUrl = typeof options.issueUrl === "string";
   const usingRepoIssue = options.repo !== undefined || options.issue !== undefined;

package/scripts/github/stage-reviewer-draft.mjs

@@ -3,7 +3,8 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePositiveInteger, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildDraftReviewPayload } from "@dev-loops/core/loop/reviewer-loop-state";
 const HELP = `Usage: stage-reviewer-draft.mjs --repo <owner/name> --pr <number> --review-file <path> [--local-state-output <path>]
@@ -19,7 +20,19 @@ Exit codes:
   1   Error
 `;
 export function parseStageDraftCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "review-file": { type: "string" },
+      "local-state-output": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     repo: undefined,
     pr: undefined,
@@ -27,29 +40,34 @@ export function parseStageDraftCliArgs(argv) {
     localStateOutput: undefined,
     help: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo").trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePositiveInteger(requireOptionValue(args, "--pr"), "--pr");
+    if (token.name === "pr") {
+      options.pr = parsePositiveInteger(requireTokenValue(token), "--pr");
       continue;
     }
-    if (token === "--review-file") {
-      options.reviewFile = requireOptionValue(args, "--review-file");
+    if (token.name === "review-file") {
+      options.reviewFile = requireTokenValue(token);
       continue;
     }
-    if (token === "--local-state-output") {
-      options.localStateOutput = requireOptionValue(args, "--local-state-output");
+    if (token.name === "local-state-output") {
+      options.localStateOutput = requireTokenValue(token);
       continue;
     }
-    throw new Error(`Unknown argument: ${token}`);
+    throw new Error(`Unknown argument: ${token.rawName}`);
   }
   if (!options.repo || !options.pr || !options.reviewFile) {
     throw new Error(

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -2,7 +2,8 @@
 import { readFile } from "node:fs/promises";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig } from "@dev-loops/core/config";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { truncateText } from "@dev-loops/core/bash-exit-one";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadPrGateCoordinationContext } from "../loop/detect-pr-gate-coordination-state.mjs";
@@ -198,7 +199,24 @@ export function summarizeCheckpointVerdictText(value, limit = MAX_GATE_COMMENT_T
   return smartTruncate(verboseSummary ?? flat, limit);
 }
 export function parseUpsertCheckpointVerdictCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      gate: { type: "string" },
+      "head-sha": { type: "string" },
+      verdict: { type: "string" },
+      "findings-summary": { type: "string" },
+      "findings-file": { type: "string" },
+      "next-action": { type: "string" },
+      "findings-severity-counts": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     help: false,
     repo: undefined,
@@ -211,65 +229,70 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
     nextAction: undefined,
     findingsSeverityCounts: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (REMOVED_FLAGS.has(token)) {
-      rejectRemovedFlag(token);
+    if (REMOVED_FLAGS.has(token.rawName)) {
+      rejectRemovedFlag(token.rawName);
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--gate") {
-      const gate = normalizeGateName(requireOptionValue(args, "--gate", parseError));
+    if (token.name === "gate") {
+      const gate = normalizeGateName(requireTokenValue(token, parseError));
       if (!gate) {
         throw parseError("--gate must be one of: draft_gate, pre_approval_gate");
       }
       options.gate = gate;
       continue;
     }
-    if (token === "--head-sha") {
-      const headSha = normalizeHeadSha(requireOptionValue(args, "--head-sha", parseError));
+    if (token.name === "head-sha") {
+      const headSha = normalizeHeadSha(requireTokenValue(token, parseError));
       if (!headSha) {
         throw parseError("--head-sha must be a 7-64 character hexadecimal SHA");
       }
       options.headSha = headSha;
       continue;
     }
-    if (token === "--verdict") {
-      const verdict = normalizeVerdict(requireOptionValue(args, "--verdict", parseError));
+    if (token.name === "verdict") {
+      const verdict = normalizeVerdict(requireTokenValue(token, parseError));
       if (!verdict) {
         throw parseError("--verdict must be one of: clean, findings_present, blocked");
       }
       options.verdict = verdict;
       continue;
     }
-    if (token === "--findings-summary") {
-      options.findingsSummary = normalizeRequiredText(requireOptionValue(args, "--findings-summary", parseError), "--findings-summary");
+    if (token.name === "findings-summary") {
+      options.findingsSummary = normalizeRequiredText(requireTokenValue(token, parseError), "--findings-summary");
       continue;
     }
-    if (token === "--findings-file") {
-      const rawPath = requireOptionValue(args, "--findings-file", parseError).trim();
+    if (token.name === "findings-file") {
+      const rawPath = requireTokenValue(token, parseError).trim();
       if (rawPath.length === 0) {
         throw parseError("--findings-file must be a non-empty path");
       }
       options.findingsFile = rawPath;
       continue;
     }
-    if (token === "--next-action") {
-      options.nextAction = normalizeRequiredText(requireOptionValue(args, "--next-action", parseError), "--next-action");
+    if (token.name === "next-action") {
+      options.nextAction = normalizeRequiredText(requireTokenValue(token, parseError), "--next-action");
       continue;
     }
-    if (token === "--findings-severity-counts") {
-      const raw = requireOptionValue(args, "--findings-severity-counts", parseError);
+    if (token.name === "findings-severity-counts") {
+      const raw = requireTokenValue(token, parseError);
       let parsed;
       try {
         parsed = JSON.parse(raw);
@@ -289,7 +312,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       options.findingsSeverityCounts = counts;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const missing = ["repo", "pr", "headSha", "verdict", "findingsSummary", "nextAction"]
     .filter((key) => options[key] === undefined);

package/scripts/github/write-gate-findings-log.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 const USAGE = `Usage: write-gate-findings-log.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --verdict <clean|findings_present|blocked> --findings <json> [--tmp-root <path>]
 Write a durable <gate>-<headSha>.json log under deterministic tmp/ paths.
@@ -89,7 +90,22 @@ function parseFindingsJson(raw) {
   });
 }
 export function parseWriteGateFindingsLogCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      gate: { type: "string" },
+      "head-sha": { type: "string" },
+      verdict: { type: "string" },
+      findings: { type: "string" },
+      "tmp-root": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
   const options = {
     repo: undefined,
     pr: undefined,
@@ -99,46 +115,51 @@ export function parseWriteGateFindingsLogCliArgs(argv) {
     findings: undefined,
     tmpRoot: "tmp",
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       return { help: true };
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError).trim();
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+    if (token.name === "pr") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    if (token === "--gate") {
-      const gate = normalizeGate(requireOptionValue(args, "--gate", parseError));
+    if (token.name === "gate") {
+      const gate = normalizeGate(requireTokenValue(token, parseError));
       if (!gate) throw parseError("--gate must be draft_gate or pre_approval_gate");
       options.gate = gate;
       continue;
     }
-    if (token === "--head-sha") {
-      const sha = normalizeHeadSha(requireOptionValue(args, "--head-sha", parseError));
+    if (token.name === "head-sha") {
+      const sha = normalizeHeadSha(requireTokenValue(token, parseError));
       if (!sha) throw parseError("--head-sha must be a 7-64 character hex SHA");
       options.headSha = sha;
       continue;
     }
-    if (token === "--verdict") {
-      const verdict = normalizeVerdict(requireOptionValue(args, "--verdict", parseError));
+    if (token.name === "verdict") {
+      const verdict = normalizeVerdict(requireTokenValue(token, parseError));
       if (!verdict) throw parseError("--verdict must be clean, findings_present, or blocked");
       options.verdict = verdict;
       continue;
     }
-    if (token === "--findings") {
-      options.findings = requireOptionValue(args, "--findings", parseError);
+    if (token.name === "findings") {
+      options.findings = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--tmp-root") {
-      options.tmpRoot = requireOptionValue(args, "--tmp-root", parseError).trim();
+    if (token.name === "tmp-root") {
+      options.tmpRoot = requireTokenValue(token, parseError).trim();
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const missing = ["repo", "pr", "gate", "headSha", "verdict", "findings"]
     .filter(k => options[k] === undefined);

package/scripts/loop/_loop-pr-aggregation.mjs

@@ -0,0 +1,45 @@
+// Shared loop PR-aggregation helpers used by both conductor-monitor.mjs and
+// run-conductor-cycle.mjs. Spawns `gh`, so this lives at the scripts level
+// rather than in @dev-loops/core.
+import { runChild } from "../_cli-primitives.mjs";
+import { parseJsonText } from "../_core-helpers.mjs";
+
+export const OPEN_PR_LIST_LIMIT = 1000;
+
+export async function listOpenPrs({ repo }, { env, ghCommand }) {
+  const result = await runChild(
+    ghCommand,
+    [
+      "pr",
+      "list",
+      "--repo",
+      repo,
+      "--state",
+      "open",
+      "--limit",
+      String(OPEN_PR_LIST_LIMIT),
+      "--json",
+      "number,title,url,isDraft,headRefName,author",
+    ],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout);
+  if (!Array.isArray(payload)) {
+    throw new Error("Invalid gh pr list payload: expected an array");
+  }
+  return payload
+    .map((pr) => ({
+      number: Number.isInteger(pr?.number) ? pr.number : null,
+      title: typeof pr?.title === "string" ? pr.title : "",
+      url: typeof pr?.url === "string" ? pr.url : null,
+      isDraft: Boolean(pr?.isDraft),
+      headRefName: typeof pr?.headRefName === "string" ? pr.headRefName : null,
+      authorLogin: typeof pr?.author?.login === "string" ? pr.author.login : null,
+    }))
+    .filter((pr) => pr.number !== null)
+    .sort((left, right) => left.number - right.number);
+}