dev-loops 0.2.6 → 0.3.0

package/scripts/loop/pre-flight-gate.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { requireOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
 import { createPiAdapter } from "@dev-loops/core/harness";
+import { parseArgs } from "node:util";
 import {
   isUnderWorktreePath,
   parseMainWorktreePath,
@@ -30,27 +31,42 @@ Bypass:
   PI_PREFLIGHT_BYPASS=1   Skip all checks (for development/testing only).`.trim();
 const parseError = buildParseError(USAGE);
 export function parsePreFlightGateCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     expectedBranch: undefined,
     checkSubagents: false,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "expected-branch": { type: "string" },
+      "check-subagents": { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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 === "--expected-branch") {
-      options.expectedBranch = requireOptionValue(args, "--expected-branch", parseError, { flagPattern: /^-/u });
+    if (token.name === "expected-branch") {
+      options.expectedBranch = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    if (token === "--check-subagents") {
+    if (token.name === "check-subagents") {
       options.checkSubagents = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   return options;
 }

package/scripts/loop/pre-pr-ready-gate.mjs

@@ -7,8 +7,9 @@ import {
   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 { parseArgs } from "node:util";
 
 const USAGE = `Usage:
   pre-pr-ready-gate.mjs --repo <owner/name> --pr <number>
@@ -38,14 +39,29 @@ 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 } } }`;
 
 export function parsePrePrReadyGateCliArgs(argv) {
-  const args = [...argv];
   const options = { help: false, repo: undefined, pr: undefined };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") { options.help = true; return options; }
-    if (token === "--repo") { options.repo = requireOptionValue(args, "--repo", parseError).trim(); continue; }
-    if (token === "--pr") { options.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,
+  });
+  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.name === "repo") { options.repo = requireTokenValue(token, parseError).trim(); continue; }
+    if (token.name === "pr") { options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError); continue; }
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("pre-pr-ready-gate requires both --repo <owner/name> and --pr <number>");

package/scripts/loop/pre-push-main-guard.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createInterface } from "node:readline";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseArgs } from "node:util";
 
 const PI_PREPUSH_BYPASS_VAR = "PI_PREPUSH_BYPASS";
 const BLOCKED_REFS = ["refs/heads/main"];
@@ -61,11 +62,24 @@ function findBlockedRef(refs) {
 }
 
 export function parsePrePushGuardCliArgs(argv) {
-  const args = [...argv];
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") return { help: true };
-    throw parseError(`Unknown argument: ${token}`);
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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 };
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   return { help: false };
 }

package/scripts/loop/pre-write-remote-freshness-guard.mjs

@@ -1,17 +1,33 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { requireOptionValue, runCommand } from "../_cli-primitives.mjs";
+import { requireTokenValue, runCommand } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
 
 const USAGE = `Usage: pre-write-remote-freshness-guard.mjs --branch <name>\nRefresh remote branch state before starting local file writes.`;
 const parseError = buildParseError(USAGE);
 
 export function parseRemoteFreshnessGuardCliArgs(argv) {
-  const args = [...argv], options = { help: false, branch: undefined };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") { options.help = true; return options; }
-    if (token === "--branch") { options.branch = requireOptionValue(args, "--branch", parseError, { flagPattern: /^-/u }); continue; }
-    throw parseError(`Unknown argument: ${token}`);
+  const options = { help: false, branch: undefined };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      branch: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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.name === "branch") { options.branch = requireTokenValue(token, parseError, { flagPattern: /^-/u }); continue; }
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.branch === undefined) throw parseError("--branch <name> is required");
   return options;

package/scripts/loop/resolve-dev-loop-startup.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { resolveAuthoritativeStartupResumeBundle } from "@dev-loops/core/loop/public-dev-loop-routing";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { requireOptionValue, parsePositiveInteger } from "../_cli-primitives.mjs";
+import { requireTokenValue, parsePositiveInteger } from "../_cli-primitives.mjs";
 import { execFileSync } from "node:child_process";
 import {
   isUnderWorktreePath,
@@ -23,6 +23,7 @@ import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { isCopilotLogin } from "@dev-loops/core/github/copilot-helpers";
 import { loadDevLoopConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { createPiAdapter } from "@dev-loops/core/harness";
+import { parseArgs } from "node:util";
 const USAGE = `Usage:
   resolve-dev-loop-startup.mjs --issue <number>
   resolve-dev-loop-startup.mjs --pr <number>
@@ -96,32 +97,48 @@ const STRATEGY_ASYNC_DISPATCH = {
 };
 const parseError = buildParseError(USAGE);
 export function parseResolveDevLoopStartupCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     inputPath: undefined,
     issue: undefined,
     pr: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      input: { type: "string" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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 === "--input") {
-      options.inputPath = requireOptionValue(args, "--input", parseError);
+    if (token.name === "input") {
+      options.inputPath = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--issue") {
-      options.issue = parsePositiveInteger(requireOptionValue(args, "--issue", parseError), "--issue", parseError);
+    if (token.name === "issue") {
+      options.issue = parsePositiveInteger(requireTokenValue(token, parseError), "--issue", parseError);
       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}`);
   }
   const modeCount = [options.inputPath, options.issue, options.pr].filter(v => v !== undefined).length;
   if (modeCount > 1) {

package/scripts/loop/run-conductor-cycle.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { requireOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
 import {
   buildParseError,
   formatCliError,
@@ -14,6 +14,7 @@ import {
   buildHandoffContractForConductorAction,
 } from "./_handoff-contract.mjs";
 import { listOpenPrs } from "./_loop-pr-aggregation.mjs";
+import { parseArgs } from "node:util";
 export { listOpenPrs };
 const USAGE = `Usage: run-conductor-cycle.mjs --repo <owner/name>
 Poll all open PRs, detect state, and output an ordered action queue.`.trim();
@@ -63,22 +64,36 @@ export function actionRequiresApproval(action, autonomyStopAt = ["merge"]) {
 }
 const parseError = buildParseError(USAGE);
 export function parseCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined) {
     throw parseError("run-conductor-cycle requires --repo <owner/name>");

package/scripts/loop/run-queue.mjs

@@ -14,9 +14,11 @@
  */
 
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 import { runQueue, DEFAULT_QUEUE_DRIVER_OPTIONS } from "@dev-loops/core/loop/queue-driver";
 import { computeParallelSchedule } from "@dev-loops/core/loop/queue-parallel";
 import { readQueue } from "@dev-loops/core/loop/queue-state";
+import { reconcileBoardMembership } from "@dev-loops/core/loop/queue-membership";
 import { parsePositiveInteger } from "@dev-loops/core/cli/primitives";
 
 const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
@@ -27,7 +29,7 @@ const USAGE = `Usage:
 Run the dev-loop queue driver over entries in .pi/dev-loop-queue.json.
 Exit codes: 0 success, 1 error`.trim();
 
-function parseArgs(argv) {
+function parseCliArgs(argv) {
   const args = {
     repo: null,
     mergeAuthorized: false,
@@ -37,27 +39,58 @@ function parseArgs(argv) {
     help: false,
   };
 
-  for (let i = 0; i < argv.length; i++) {
-    switch (argv[i]) {
-      case "--repo":
-        args.repo = argv[++i];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      "merge-authorized": { type: "boolean" },
+      parallel: { type: "boolean" },
+      "redispatch-max-retries": { type: "string" },
+      "max-parallel": { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "repo":
+        args.repo = token.value;
         break;
-      case "--merge-authorized":
+      case "merge-authorized":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
         args.mergeAuthorized = true;
         break;
-      case "--parallel":
+      case "parallel":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
         args.parallel = true;
         break;
-      case "--redispatch-max-retries":
-        args.reDispatchMaxRetries = parsePositiveInteger(argv[++i], "--redispatch-max-retries");
+      case "redispatch-max-retries":
+        args.reDispatchMaxRetries = parsePositiveInteger(token.value, "--redispatch-max-retries");
         break;
-      case "--max-parallel":
-        args.maxParallel = parsePositiveInteger(argv[++i], "--max-parallel");
+      case "max-parallel":
+        args.maxParallel = parsePositiveInteger(token.value, "--max-parallel");
         break;
-      case "--help":
-      case "-h":
+      case "help":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
         args.help = true;
         break;
+      default:
+        throw new Error(`unknown argument: ${token.rawName}`);
     }
   }
 
@@ -65,7 +98,7 @@ function parseArgs(argv) {
 }
 
 async function main() {
-  const args = parseArgs(process.argv.slice(2));
+  const args = parseCliArgs(process.argv.slice(2));
 
   if (args.help) {
     console.log(USAGE);
@@ -79,7 +112,46 @@ async function main() {
 
   const queue = await readQueue(REPO_ROOT);
 
-  if (queue.entries.length === 0) {
+  // A configured GitHub Projects board is the authoritative queue MEMBERSHIP
+  // source (issue #864): fold its "Next Up" items into the queue before judging
+  // emptiness so a populated board with an empty local queue is no longer a
+  // silent no-op. Fail-open — a board hiccup falls back to the local queue.
+  // reconcileBoardMembership already logs an "added N ... from board Next Up"
+  // line to stderr (single source of truth); we deliberately do not duplicate
+  // it here to avoid noise for JSON consumers of stdout.
+  const membership = await reconcileBoardMembership(REPO_ROOT, args.repo, queue);
+
+  if (membership.emptiness === "board_empty") {
+    // Distinct from the legacy generic "Queue is empty": the board is the
+    // membership source and it currently has nothing in Next Up. This branch is
+    // only reached for a genuinely empty Next Up (reason == null), never for a
+    // resolution failure (which falls through to the local queue below).
+    console.log(JSON.stringify({
+      ok: true,
+      message: "Board configured but Next Up is empty; nothing to run",
+      boardConfigured: true,
+      reason: null,
+      results: [],
+    }));
+    return;
+  }
+
+  if (membership.emptiness === "board_unavailable") {
+    // The board IS configured but Next Up resolution failed (fail-open) and the
+    // local queue had nothing to fall back to. Do NOT claim "Next Up is empty";
+    // surface the real reason so consumers can distinguish an outage from an
+    // intentionally empty board.
+    console.log(JSON.stringify({
+      ok: true,
+      message: `Board configured but unavailable (${membership.reason}); nothing to run`,
+      boardConfigured: true,
+      reason: membership.reason ?? null,
+      results: [],
+    }));
+    return;
+  }
+
+  if (membership.emptiness === "queue_empty") {
     console.log(JSON.stringify({ ok: true, message: "Queue is empty", results: [] }));
     return;
   }

package/scripts/loop/run-refinement-audit.mjs

@@ -2,7 +2,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue, runCommand } from "../_cli-primitives.mjs";
+import { parsePositiveInteger, requireTokenValue, runCommand } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
 const DEFAULT_MAX_LINES = 1000;
 const DEFAULT_DUPLICATE_WINDOW_LINES = 4;
 const DEFAULT_BRANCH_THRESHOLD = 25;
@@ -43,7 +44,6 @@ const PRIORITY_ORDER = new Map([
   ["low", 2],
 ]);
 export function parseRefinementAuditCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     paths: undefined,
@@ -55,57 +55,79 @@ export function parseRefinementAuditCliArgs(argv) {
     thinWrapperMaxLines: DEFAULT_THIN_WRAPPER_MAX_LINES,
     output: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      paths: { type: "string" },
+      "paths-file": { type: "string" },
+      root: { type: "string" },
+      "max-lines": { type: "string" },
+      "duplicate-window-lines": { type: "string" },
+      "branch-threshold": { type: "string" },
+      "thin-wrapper-max-lines": { type: "string" },
+      output: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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 === "--paths") {
-      options.paths = requireOptionValue(args, "--paths", parseError, { flagPattern: /^-/u });
+    if (token.name === "paths") {
+      options.paths = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    if (token === "--paths-file") {
-      options.pathsFile = requireOptionValue(args, "--paths-file", parseError, { flagPattern: /^-/u });
+    if (token.name === "paths-file") {
+      options.pathsFile = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    if (token === "--root") {
-      options.root = requireOptionValue(args, "--root", parseError, { flagPattern: /^-/u });
+    if (token.name === "root") {
+      options.root = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    if (token === "--max-lines") {
-      options.maxLines = parsePositiveInteger(requireOptionValue(args, "--max-lines", parseError), "--max-lines", parseError);
+    if (token.name === "max-lines") {
+      options.maxLines = parsePositiveInteger(requireTokenValue(token, parseError), "--max-lines", parseError);
       continue;
     }
-    if (token === "--duplicate-window-lines") {
+    if (token.name === "duplicate-window-lines") {
       options.duplicateWindowLines = parsePositiveInteger(
-        requireOptionValue(args, "--duplicate-window-lines", parseError),
+        requireTokenValue(token, parseError),
         "--duplicate-window-lines",
         parseError,
       );
       continue;
     }
-    if (token === "--branch-threshold") {
+    if (token.name === "branch-threshold") {
       options.branchThreshold = parsePositiveInteger(
-        requireOptionValue(args, "--branch-threshold", parseError),
+        requireTokenValue(token, parseError),
         "--branch-threshold",
         parseError,
       );
       continue;
     }
-    if (token === "--thin-wrapper-max-lines") {
+    if (token.name === "thin-wrapper-max-lines") {
       options.thinWrapperMaxLines = parsePositiveInteger(
-        requireOptionValue(args, "--thin-wrapper-max-lines", parseError),
+        requireTokenValue(token, parseError),
         "--thin-wrapper-max-lines",
         parseError,
       );
       continue;
     }
-    if (token === "--output") {
-      options.output = requireOptionValue(args, "--output", parseError, { flagPattern: /^-/u });
+    if (token.name === "output") {
+      options.output = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.paths !== undefined && options.pathsFile !== undefined) {
     throw parseError("Specify exactly one of --paths or --paths-file");

package/scripts/loop/run-watch-cycle.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION } from "@dev-loops/core/loop/public-dev-loop-routing";
 import { watchCopilotReview } from "../github/probe-copilot-review.mjs";
 import { runHandoff } from "./copilot-pr-handoff.mjs";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
+import { parseArgs } from "node:util";
 import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
   enforceExternalHealthyWaitTimeout,
@@ -178,30 +179,45 @@ function buildWatchCycleContractTrace({
   };
 }
 export function parseWatchCycleCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     pr: undefined,
   };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  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;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
     throw parseError("run-watch-cycle requires both --repo <owner/name> and --pr <number>");