dev-loops 0.2.6 → 0.3.0

package/scripts/github/post-gate-findings.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { loadDevLoopConfig, resolveGatePostFindingsComments } from "@dev-loops/core/config";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+
+const USAGE = `Usage: post-gate-findings.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --findings <json>
+Post (or idempotently update) a visible, marker-tagged PR issue comment that lists the
+consolidated gate fan-out findings, grouped by severity. The comment is idempotent
+per gate: there is exactly one comment per gate, updated in place on each run
+(the reviewed head is shown in the body) instead of duplicating it.
+
+The disposition ledger (write-gate-findings-log.mjs) is the durable source of truth and is
+written regardless of this comment. This helper only posts the auditable PR summary, and
+no-ops when gates.postFindingsComments is set to false in config.
+
+Required:
+  --repo <owner/name>
+  --pr <number>
+  --gate <draft_gate|pre_approval_gate>
+  --head-sha <sha>                 Current head SHA or hexadecimal prefix
+  --findings <json>                JSON array of findings in the findings-log shape
+                                   ([{severity, angle, summary, disposition?, files?}])
+Output (stdout, JSON):
+  { "ok": true, "action": "created"|"updated"|"noop"|"skipped", ... }
+Exit codes:
+  0  Success
+  1  Argument error or gh failure`.trim();
+
+const VALID_SEVERITIES = new Set(["must-fix", "worth-fixing-now", "defer"]);
+// Severity ordering for grouped rendering (most-blocking first).
+const SEVERITY_ORDER = ["must-fix", "worth-fixing-now", "defer"];
+const SEVERITY_LABELS = {
+  "must-fix": "Must fix",
+  "worth-fixing-now": "Worth fixing now",
+  "defer": "Defer",
+};
+
+function parseError(message) {
+  return Object.assign(new Error(message), { usage: USAGE });
+}
+
+function normalizeGate(value) {
+  const gates = new Set(["draft_gate", "pre_approval_gate"]);
+  const normalized = String(value).trim().toLowerCase();
+  return gates.has(normalized) ? normalized : null;
+}
+
+function normalizeHeadSha(value) {
+  const normalized = String(value).trim().toLowerCase();
+  return /^[0-9a-f]{7,64}$/i.test(normalized) ? normalized : null;
+}
+
+// Validate via the centralized repo-slug validator shared by sibling GitHub
+// scripts (parseRepoSlug). It enforces owner/name structure and rejects unsafe
+// segments (".", "..", slashes, whitespace); we re-throw as a parseError so the
+// CLI usage banner is preserved.
+function validateRepo(repo) {
+  try {
+    parseRepoSlug(repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return repo;
+}
+
+export function parseFindings(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw parseError("--findings must be valid JSON");
+  }
+  if (!Array.isArray(parsed)) {
+    throw parseError("--findings must be a JSON array");
+  }
+  return parsed.map((f, i) => {
+    if (!f || typeof f !== "object") {
+      throw parseError(`--findings[${i}] must be an object`);
+    }
+    if (!f.severity || !VALID_SEVERITIES.has(f.severity)) {
+      throw parseError(`--findings[${i}].severity must be one of: must-fix, worth-fixing-now, defer`);
+    }
+    if (!f.angle || typeof f.angle !== "string" || f.angle.trim().length === 0) {
+      throw parseError(`--findings[${i}].angle is required`);
+    }
+    if (!f.summary || typeof f.summary !== "string" || f.summary.trim().length === 0) {
+      throw parseError(`--findings[${i}].summary is required`);
+    }
+    const entry = {
+      severity: f.severity,
+      angle: f.angle.trim(),
+      summary: f.summary.trim(),
+    };
+    if ("disposition" in f && typeof f.disposition === "string" && f.disposition.trim().length > 0) {
+      entry.disposition = f.disposition.trim();
+    }
+    if (Array.isArray(f.files)) {
+      entry.files = f.files.filter(x => typeof x === "string" && x.trim().length > 0).map(x => x.trim());
+    }
+    return entry;
+  });
+}
+
+export function parsePostGateFindingsCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    gate: undefined,
+    headSha: undefined,
+    findings: undefined,
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--repo") {
+      options.repo = validateRepo(requireOptionValue(args, "--repo", parseError).trim());
+      continue;
+    }
+    if (token === "--pr") {
+      options.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError);
+      continue;
+    }
+    if (token === "--gate") {
+      const gate = normalizeGate(requireOptionValue(args, "--gate", 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 (!sha) throw parseError("--head-sha must be a 7-64 character hex SHA");
+      options.headSha = sha;
+      continue;
+    }
+    if (token === "--findings") {
+      options.findings = requireOptionValue(args, "--findings", parseError);
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  const missing = ["repo", "pr", "gate", "headSha", "findings"]
+    .filter(k => options[k] === undefined);
+  if (missing.length > 0) {
+    throw parseError(`Missing required arguments: ${missing.join(", ")}`);
+  }
+  return options;
+}
+
+// Hidden marker keyed by GATE ONLY. There is exactly one findings comment per
+// gate, updated in place each run. The marker deliberately does NOT include the
+// head SHA: --head-sha accepts any 7-64 hex prefix, so keying on its literal
+// value would let a different prefix length (or the full SHA) for the same head
+// miss the marker and post a duplicate. The reviewed head is still shown in the
+// comment body for context. The HTML comment is not rendered by GitHub but is
+// matched on the comment body.
+export function buildFindingsMarker({ gate }) {
+  return `<!-- dev-loops:gate-findings gate=${gate} -->`;
+}
+
+// Collapse any run of whitespace (newlines, tabs, repeated spaces) to a single
+// space and trim. LLM-generated free text often carries embedded newlines, which
+// would otherwise break a single Markdown list item across lines.
+//
+// Additionally neutralize any embedded HTML-comment delimiters (`<!--` / `-->`).
+// The findings comment is keyed by a hidden marker that IS an HTML comment
+// (buildFindingsMarker), and free text comes from scoped-review agents. Without
+// this, a finding field could inject a second `<!-- dev-loops:gate-findings ... -->`
+// marker (breaking idempotent comment matching) or otherwise smuggle an HTML
+// comment into the rendered body. We escape the opening/closing angle brackets so
+// the delimiter renders as visible literal text and cannot form a real comment.
+function sanitizeInline(value) {
+  return String(value)
+    .replace(/\s+/g, " ")
+    .replace(/<!--/g, "&lt;!--")
+    .replace(/-->/g, "--&gt;")
+    .trim();
+}
+
+// Sanitize free text that is rendered INSIDE an inline backtick code span
+// (`angle`, file refs). On top of sanitizeInline, strip any literal backtick:
+// a backtick inside the span would prematurely close it, breaking out into raw
+// Markdown (injection) for the remainder of the list item. Backticks are never
+// meaningful in an angle label or a file path, so dropping them is safe.
+function sanitizeCodeSpan(value) {
+  return sanitizeInline(String(value).replace(/`/g, ""));
+}
+
+export function renderFindingsCommentBody({ gate, headSha, findings }) {
+  const marker = buildFindingsMarker({ gate });
+  const lines = [
+    marker,
+    `### Gate fan-out findings: ${gate}`,
+    "",
+    // Plain text head SHA (no backticks) so GitHub autolinks the commit.
+    `Reviewed head: ${headSha}`,
+    "",
+  ];
+  if (findings.length === 0) {
+    lines.push("No findings. All review angles passed for this head.");
+    return lines.join("\n");
+  }
+  const grouped = new Map();
+  for (const sev of SEVERITY_ORDER) {
+    grouped.set(sev, []);
+  }
+  for (const finding of findings) {
+    grouped.get(finding.severity).push(finding);
+  }
+  for (const sev of SEVERITY_ORDER) {
+    const group = grouped.get(sev);
+    if (group.length === 0) continue;
+    lines.push(`#### ${SEVERITY_LABELS[sev]} (${group.length})`);
+    for (const finding of group) {
+      // Sanitize free-text fields so embedded newlines/whitespace don't break
+      // the single-line Markdown list item.
+      const summary = sanitizeInline(finding.summary);
+      const dispositionSuffix = finding.disposition ? ` — _${sanitizeInline(finding.disposition)}_` : "";
+      // angle is a code/label literal → backticks; summary is prose. angle is
+      // free text from a scoped-review agent and is rendered inside an inline
+      // code span, so it must be sanitized too: an embedded backtick or newline
+      // would otherwise break the code span (markdown injection) or split the
+      // list item. Use sanitizeCodeSpan (backtick-stripping) since it lives
+      // inside backticks, consistent with the file refs below.
+      const angle = sanitizeCodeSpan(finding.angle);
+      lines.push(`- \`${angle}\`: ${summary}${dispositionSuffix}`);
+      if (Array.isArray(finding.files) && finding.files.length > 0) {
+        // File refs go inside backticks; sanitize each so embedded whitespace,
+        // newlines, or backticks can't break the single Markdown list item /
+        // code span, and drop any that sanitize to empty.
+        const refs = finding.files
+          .map(f => sanitizeCodeSpan(f))
+          .filter(f => f.length > 0)
+          .map(f => `\`${f}\``)
+          .join(", ");
+        if (refs.length > 0) {
+          lines.push(`  - files: ${refs}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+  // Drop trailing blank line.
+  while (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop();
+  }
+  return lines.join("\n");
+}
+
+async function runGhJson(args, { env, ghCommand }) {
+  const result = await runChild(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  return parseJsonText(result.stdout, { label: `gh ${args.slice(0, 3).join(" ")}` });
+}
+
+async function listIssueComments({ repo, pr }, { env, ghCommand }) {
+  const payload = await runGhJson(
+    ["api", "--paginate", "--slurp", `repos/${repo}/issues/${pr}/comments?per_page=100`],
+    { env, ghCommand },
+  );
+  // --slurp returns an array of pages; flatten to a single comment list.
+  if (Array.isArray(payload) && payload.every(p => Array.isArray(p))) {
+    return payload.flat();
+  }
+  return Array.isArray(payload) ? payload : [];
+}
+
+function findMarkedComment(comments, marker) {
+  for (const comment of comments) {
+    if (comment && typeof comment.body === "string" && comment.body.includes(marker)) {
+      return comment;
+    }
+  }
+  return null;
+}
+
+function parseCommentMutationResponse(payload) {
+  const commentId = Number.isInteger(payload?.id) ? payload.id : null;
+  const commentUrl = typeof payload?.html_url === "string" && payload.html_url.trim().length > 0
+    ? payload.html_url.trim()
+    : null;
+  if (commentId === null || commentUrl === null) {
+    throw new Error("Gate findings comment mutation did not return a comment id and html_url");
+  }
+  return { commentId, commentUrl };
+}
+
+async function createComment({ repo, pr, body }, { env, ghCommand }) {
+  const payload = await runGhJson(
+    ["api", `repos/${repo}/issues/${pr}/comments`, "-f", `body=${body}`],
+    { env, ghCommand },
+  );
+  return parseCommentMutationResponse(payload);
+}
+
+async function updateComment({ repo, commentId, body }, { env, ghCommand }) {
+  const payload = await runGhJson(
+    ["api", "-X", "PATCH", `repos/${repo}/issues/comments/${commentId}`, "-f", `body=${body}`],
+    { env, ghCommand },
+  );
+  return parseCommentMutationResponse(payload);
+}
+
+export async function postGateFindings(options, { env = process.env, ghCommand = "gh", repoRoot = process.cwd() } = {}) {
+  const findings = parseFindings(options.findings);
+  // loadDevLoopConfig never throws: it returns { config, warnings, errors }.
+  // A non-empty errors array means the config could not be loaded/validated, so
+  // log it (stderr) and fall back to default behavior (config-unavailable →
+  // null → resolveGatePostFindingsComments defaults on → proceed to post),
+  // rather than trusting a malformed/partial config object. Mirrors how
+  // detect-checkpoint-evidence treats config-unavailable.
+  const { config: loadedConfig, errors: configErrors } = await loadDevLoopConfig({ repoRoot });
+  let config = loadedConfig;
+  if (Array.isArray(configErrors) && configErrors.length > 0) {
+    process.stderr.write(
+      `post-gate-findings: dev-loop config could not be loaded/validated; using default behavior. errors=${JSON.stringify(configErrors)}\n`,
+    );
+    config = null;
+  }
+  if (!resolveGatePostFindingsComments(config)) {
+    return {
+      ok: true,
+      action: "skipped",
+      reason: "gates.postFindingsComments is false",
+      repo: options.repo,
+      pr: options.pr,
+      gate: options.gate,
+      headSha: options.headSha,
+      findingsCount: findings.length,
+    };
+  }
+  const marker = buildFindingsMarker({ gate: options.gate });
+  const desiredBody = renderFindingsCommentBody({ gate: options.gate, headSha: options.headSha, findings });
+  const comments = await listIssueComments({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+  const existing = findMarkedComment(comments, marker);
+  const base = {
+    ok: true,
+    repo: options.repo,
+    pr: options.pr,
+    gate: options.gate,
+    headSha: options.headSha,
+    findingsCount: findings.length,
+  };
+  if (existing) {
+    if (typeof existing.body === "string" && existing.body === desiredBody) {
+      return {
+        ...base,
+        action: "noop",
+        commentId: Number.isInteger(existing.id) ? existing.id : null,
+        commentUrl: typeof existing.html_url === "string" ? existing.html_url : null,
+      };
+    }
+    const updated = await updateComment({ repo: options.repo, commentId: existing.id, body: desiredBody }, { env, ghCommand });
+    return { ...base, action: "updated", ...updated };
+  }
+  const created = await createComment({ repo: options.repo, pr: options.pr, body: desiredBody }, { env, ghCommand });
+  return { ...base, action: "created", ...created };
+}
+
+async function main() {
+  let options;
+  try {
+    options = parsePostGateFindingsCliArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${formatCliError(error, { usage: USAGE })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+  try {
+    const result = await postGateFindings(options);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  await main();
+}

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { setTimeout as delay } from "node:timers/promises";
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, parseJsonText, parseReviewThreads } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
   DEFAULT_POLL_INTERVAL_MS,
@@ -88,7 +89,13 @@ function rejectRemovedFlag(token) {
   );
 }
 export function parseWatchCliArgs(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,
@@ -96,24 +103,29 @@ export function parseWatchCliArgs(argv) {
     pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
     timeoutMs: COPILOT_REVIEW_WAIT_TIMEOUT_MS,
   };
-  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 = parsePositiveInteger(requireOptionValue(args, "--pr", parseError), "--pr", parseError);
+    if (token.name === "pr") {
+      options.pr = parsePositiveInteger(requireTokenValue(token, parseError), "--pr", parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("Watching Copilot review requires both --repo <owner/name> and --pr <number>");

package/scripts/github/ready-for-review.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText, summarizeGateReviewComments, summarizeGateReviewCommentMarkers } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadDevLoopConfig, resolveGateConfig } from "@dev-loops/core/config";
 import { findBlockingTitleMarkers } from "@dev-loops/core/loop/pr-title-markers";
@@ -10,13 +11,21 @@ const parseError = buildParseError(USAGE);
 const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state, mergeStateStatus, title } } }`;
 
 export function parseReadyForReviewCliArgs(argv) {
-  const args = [...argv], opts = { help: false, repo: undefined, pr: undefined };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") { opts.help = true; return opts; }
-    if (token === "--repo") { opts.repo = requireOptionValue(args, "--repo", parseError).trim(); continue; }
-    if (token === "--pr") { opts.pr = parsePrNumber(requireOptionValue(args, "--pr", parseError), parseError); continue; }
-    throw parseError(`Unknown argument: ${token}`);
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const opts = { help: false, repo: undefined, pr: undefined };
+  for (const token of tokens) {
+    if (token.kind === "positional") throw parseError(`Unknown argument: ${token.value}`);
+    if (token.kind !== "option") continue;
+    if (token.name === "help") { opts.help = true; return opts; }
+    if (token.name === "repo") { opts.repo = requireTokenValue(token, parseError).trim(); continue; }
+    if (token.name === "pr") { opts.pr = parsePrNumber(requireTokenValue(token, parseError), parseError); continue; }
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!opts.repo || opts.pr === undefined) throw parseError("ready-for-review requires --repo and --pr");
   parseRepoSlug(opts.repo);

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) {
@@ -112,7 +124,7 @@ async function resolvePrNodeId({ repo, pr }, { env, ghCommand }) {
   }
   return { id: prData.id, isDraft: prData.isDraft };
 }
-async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
+export async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
   const resolvedPr = await resolvePrNodeId({ repo, pr }, { env, ghCommand });
   if (resolvedPr.isDraft === true) {
     return {
@@ -142,7 +154,7 @@ async function convertPrToDraft({ repo, pr }, { env, ghCommand }) {
     alreadyDraft: false,
   };
 }
-async function markPrReady({ repo, pr }, { env, ghCommand }) {
+export async function markPrReady({ repo, pr }, { env, ghCommand }) {
   const result = await runChild(ghCommand, [
     "pr", "ready", String(pr),
     "--repo", repo,

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>");