dev-loops 0.2.5 → 0.2.7

package/scripts/loop/inspect-run.mjs

@@ -2,7 +2,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { buildParseError, formatCliError, parseJsonText, parseReviewThreads } from "../_core-helpers.mjs";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
@@ -22,6 +22,7 @@ import {
   STEERING_KIND,
 } from "@dev-loops/core/loop/steering";
 import { validateSteeringStateTarget } from "./_steering-state-file.mjs";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: inspect-run.mjs --repo <owner/name> --pr <number>
 Read-only run inspection for the Copilot PR outer-loop family.
 Produces a single JSON snapshot describing the current state of one
@@ -72,7 +73,6 @@ Exit codes:
   1  Argument error or unexpected runtime failure`.trim();
 const parseError = buildParseError(USAGE);
 export function parseInspectRunCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -81,33 +81,52 @@ export function parseInspectRunCliArgs(argv) {
     copilotInputPath: undefined,
     reviewerInputPath: 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" },
+      "steering-state-file": { type: "string" },
+      "copilot-input": { type: "string" },
+      "reviewer-input": { 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;
     }
-    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 === "--steering-state-file") {
-      options.steeringStateFile = requireOptionValue(args, "--steering-state-file", parseError);
+    if (token.name === "steering-state-file") {
+      options.steeringStateFile = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--copilot-input") {
-      options.copilotInputPath = requireOptionValue(args, "--copilot-input", parseError);
+    if (token.name === "copilot-input") {
+      options.copilotInputPath = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--reviewer-input") {
-      options.reviewerInputPath = requireOptionValue(args, "--reviewer-input", parseError);
+    if (token.name === "reviewer-input") {
+      options.reviewerInputPath = requireTokenValue(token, parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!options.help) {
     if (options.repo === undefined || options.pr === undefined) {

package/scripts/loop/outer-loop.mjs

@@ -2,7 +2,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { buildParseError, formatCliError, parseJsonText } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
@@ -25,6 +25,7 @@ import {
   resolveEffectiveAsyncStartMode,
 } from "@dev-loops/core/loop/async-start-contract";
 import { loadDevLoopConfig, resolveConductorModel, resolveAutonomyStopAt, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: outer-loop.mjs --repo <owner/name> --pr <number>
 Thin outer-loop wrapper for the Copilot PR remediation loop.
 Detects current PR state from both the Copilot inner loop and the reviewer
@@ -88,7 +89,6 @@ Exit codes:
   1  Argument error, gh/git failure, or indeterminate state`.trim();
 const parseError = buildParseError(USAGE);
 export function parseOuterLoopCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -97,33 +97,52 @@ export function parseOuterLoopCliArgs(argv) {
     copilotInputPath: undefined,
     reviewerInputPath: 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" },
+      "checkpoint-dir": { type: "string" },
+      "copilot-input": { type: "string" },
+      "reviewer-input": { 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;
     }
-    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 === "--checkpoint-dir") {
-      options.checkpointDir = requireOptionValue(args, "--checkpoint-dir", parseError);
+    if (token.name === "checkpoint-dir") {
+      options.checkpointDir = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--copilot-input") {
-      options.copilotInputPath = requireOptionValue(args, "--copilot-input", parseError);
+    if (token.name === "copilot-input") {
+      options.copilotInputPath = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--reviewer-input") {
-      options.reviewerInputPath = requireOptionValue(args, "--reviewer-input", parseError);
+    if (token.name === "reviewer-input") {
+      options.reviewerInputPath = requireTokenValue(token, parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!options.help) {
     if (options.repo === undefined || options.pr === undefined) {

package/scripts/loop/pr-runner-coordination.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import process from "node:process";
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
 import {
@@ -42,29 +43,47 @@ function parseCliArgs(argv) {
     return options;
   }
   options.command = command;
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") {
+  const { tokens } = parseArgs({
+    args,
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "run-id": { type: "string" },
+      "require-existing": { 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 === "--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 === "--run-id") {
-      options.runId = requireOptionValue(args, "--run-id", parseError).trim();
+    if (token.name === "run-id") {
+      options.runId = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--require-existing") {
+    if (token.name === "require-existing") {
       options.requireExisting = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const validCommands = new Set(["status", "claim", "takeover", "assert", "release"]);
   if (!validCommands.has(options.command)) {

package/scripts/loop/pre-commit-branch-guard.mjs

@@ -1,6 +1,7 @@
 #!/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";
 import {
   isUnderWorktreePath, parseMainWorktreePath, isMainCheckout,
 } from "@dev-loops/core/loop/worktree-guard";
@@ -13,15 +14,31 @@ Verify the current git branch identity and/or worktree isolation before local co
 const parseError = buildParseError(USAGE);
 
 export function parseBranchGuardCliArgs(argv) {
-  const args = [...argv];
   const options = { help: false, expectedBranch: undefined, requireWorktree: false, blockMainCheckout: false };
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--help" || token === "-h") { options.help = true; return options; }
-    if (token === "--expected-branch") { options.expectedBranch = requireOptionValue(args, "--expected-branch", parseError, { flagPattern: /^-/u }); continue; }
-    if (token === "--require-worktree") { options.requireWorktree = true; continue; }
-    if (token === "--block-main-checkout") { options.blockMainCheckout = true; continue; }
-    throw parseError(`Unknown argument: ${token}`);
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "expected-branch": { type: "string" },
+      "require-worktree": { type: "boolean" },
+      "block-main-checkout": { 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.name === "expected-branch") { options.expectedBranch = requireTokenValue(token, parseError, { flagPattern: /^-/u }); continue; }
+    if (token.name === "require-worktree") { options.requireWorktree = true; continue; }
+    if (token.name === "block-main-checkout") { options.blockMainCheckout = true; continue; }
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.expectedBranch === undefined) { throw parseError("--expected-branch <name> is required"); }
   return options;

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) {