dev-loops 0.2.6 → 0.3.0

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);
@@ -147,7 +168,7 @@ export function parseWriteGateFindingsLogCliArgs(argv) {
   }
   return options;
 }
-function buildLogPath({ repo, pr, gate, headSha, tmpRoot }) {
+export function buildLogPath({ repo, pr, gate, headSha, tmpRoot }) {
   const parts = repo.split("/");
   if (parts.length !== 2 || parts.some(p => p.length === 0)) {
     throw new Error(`--repo must be in owner/name format, got: ${JSON.stringify(repo)}`);

package/scripts/loop/build-handoff-envelope.mjs

@@ -18,10 +18,11 @@ import { readFile } from "node:fs/promises";
 import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
 import path from "node:path";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { requireOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
 import { buildDevLoopHandoffEnvelope } from "@dev-loops/core/loop/handoff-envelope";
 import { loadDevLoopConfig } from "@dev-loops/core/config";
 import { createPiAdapter } from "@dev-loops/core/harness";
+import { parseArgs } from "node:util";
 
 const USAGE = `Usage: build-handoff-envelope.mjs --input <path>
 Build a deterministic handoff envelope from startup resolver output and settings.
@@ -56,7 +57,6 @@ function parseFlagJson(raw, flagName, parseErrorFn) {
 }
 
 export function parseBuildHandoffEnvelopeCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     inputPath: undefined,
@@ -65,29 +65,47 @@ export function parseBuildHandoffEnvelopeCliArgs(argv) {
     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" },
+      input: { type: "string" },
+      "gate-state": { type: "string" },
+      overrides: { type: "string" },
+      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 === "--input") {
-      options.inputPath = requireOptionValue(args, "--input", parseError);
+    if (token.name === "input") {
+      options.inputPath = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--gate-state") {
-      options.gateState = requireOptionValue(args, "--gate-state", parseError);
+    if (token.name === "gate-state") {
+      options.gateState = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--overrides") {
-      options.overrides = requireOptionValue(args, "--overrides", parseError);
+    if (token.name === "overrides") {
+      options.overrides = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError);
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
 
   if (!options.inputPath) {

package/scripts/loop/conductor-monitor.mjs

@@ -3,7 +3,7 @@ import { existsSync } from "node:fs";
 import { access, open, readFile, readdir } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { requireOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { autoDetectSnapshot } from "./detect-copilot-loop-state.mjs";
@@ -14,6 +14,7 @@ import {
 } from "./_handoff-contract.mjs";
 import { interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { listOpenPrs } from "./_loop-pr-aggregation.mjs";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: conductor-monitor.mjs --repo <owner/name> [--auto-resume]
 Aggregate Copilot-loop status across all open PRs in one repo.
 Required:
@@ -113,27 +114,42 @@ const MANUAL_REASON = {
   HANDOFF_CONTRACT_MISMATCH: "handoff_contract_mismatch",
 };
 function parseCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     autoResume: 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" },
+      repo: { type: "string" },
+      "auto-resume": { 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 === "--auto-resume") {
+    if (token.name === "auto-resume") {
       options.autoResume = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined) {
     throw parseError("conductor-monitor requires --repo <owner/name>");

package/scripts/loop/conductor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { runConductorCycle } from "./run-conductor-cycle.mjs";
 import { runConductorMonitor } from "./conductor-monitor.mjs";
-import { requireOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
@@ -12,6 +12,7 @@ import {
 } from "@dev-loops/core/config";
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: conductor.mjs --repo <owner/name> [--auto-resume] [--cycle-only] [--monitor-only] [--require-retrospective]
 Unified conductor entrypoint for dev-loop lifecycle orchestration.`.trim();
 const parseError = buildParseError(USAGE);
@@ -43,7 +44,6 @@ function checkRetrospectiveGate(cwd, requireRetrospective) {
   }
 }
 function parseCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -52,33 +52,52 @@ function parseCliArgs(argv) {
     monitorOnly: false,
     requireRetrospective: 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" },
+      repo: { type: "string" },
+      "auto-resume": { type: "boolean" },
+      "cycle-only": { type: "boolean" },
+      "monitor-only": { type: "boolean" },
+      "require-retrospective": { 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 === "--auto-resume") {
+    if (token.name === "auto-resume") {
       options.autoResume = true;
       continue;
     }
-    if (token === "--cycle-only") {
+    if (token.name === "cycle-only") {
       options.cycleOnly = true;
       continue;
     }
-    if (token === "--monitor-only") {
+    if (token.name === "monitor-only") {
       options.monitorOnly = true;
       continue;
     }
-    if (token === "--require-retrospective") {
+    if (token.name === "require-retrospective") {
       options.requireRetrospective = true;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined) {
     throw parseError("conductor requires --repo <owner/name>");

package/scripts/loop/copilot-pr-handoff.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, normalizeTimestamp } from "../_core-helpers.mjs";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { resolveRunId } from "@dev-loops/core/loop/run-context";
 import path from "node:path";
@@ -16,6 +16,7 @@ import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
   enforceExternalHealthyWaitTimeout,
 } from "@dev-loops/core/loop/timeout-policy";
+import { parseArgs } from "node:util";
 import {
   DEFAULT_POLL_INTERVAL_MS,
   COPILOT_REVIEW_WAIT_TIMEOUT_MS,
@@ -128,39 +129,55 @@ function rejectRemovedFlag(token) {
   );
 }
 export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     pr: undefined,
     watchStatus: 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" },
+      "watch-status": { 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;
     }
-    if (token === "--watch-status") {
-      const watchStatus = requireOptionValue(args, "--watch-status", parseError).trim().toLowerCase();
+    if (token.name === "watch-status") {
+      const watchStatus = requireTokenValue(token, parseError).trim().toLowerCase();
       if (!VALID_WATCH_STATUSES.has(watchStatus)) {
         throw parseError(`--watch-status must be one of: ${[...VALID_WATCH_STATUSES].join(", ")}`);
       }
       options.watchStatus = watchStatus;
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.pr === undefined) {
     throw parseError("copilot-pr-handoff requires --pr <number>");

package/scripts/loop/debt-remediate.mjs

@@ -15,9 +15,10 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
 
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { requireOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { DebtSignalSchema } from "@dev-loops/core/debt/signal";
 import { clusterSignalsEnriched } from "@dev-loops/core/debt/cluster";
@@ -150,28 +151,44 @@ function buildReport(signalsCount, findingsCount, results) {
 // ============================================================================
 
 export async function runCli(argv) {
-  const args = [...argv];
   const options = { input: undefined, repo: undefined, dryRun: false, help: 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" },
+      input: { type: "string" },
+      repo: { type: "string" },
+      "dry-run": { type: "boolean" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown flag: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       break;
     }
-    if (token === "--input") {
-      options.input = requireOptionValue(args, "--input", parseError);
+    if (token.name === "input") {
+      options.input = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = requireOptionValue(args, "--repo", parseError);
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError);
       continue;
     }
-    if (token === "--dry-run") {
+    if (token.name === "dry-run") {
       options.dryRun = true;
       continue;
     }
-    throw parseError(`Unknown flag: ${token}`);
+    throw parseError(`Unknown flag: ${token.rawName}`);
   }
 
   if (options.help) {

package/scripts/loop/detect-change-scope.mjs

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import process from "node:process";
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const opts = { base: null, head: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") {
-      process.stdout.write(`Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
+import { parseArgs } from "node:util";
+
+const USAGE = `Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
 Detect change scope from git diff for light-mode eligibility.
 Options:
   --base <ref>   Override base ref (default: HEAD~1)
@@ -15,11 +12,39 @@ Options:
 Exit codes:
   0   Success
   1   Error
-`);
-      process.exit(0);
+`;
+
+function parseCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      base: { type: "string" },
+      head: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  const opts = { base: null, head: null };
+  for (const token of tokens) {
+    if (token.kind === "option") {
+      if (token.name === "help") {
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        process.stdout.write(USAGE);
+        process.exit(0);
+      }
+      if (token.name === "base") {
+        opts.base = token.value ?? null;
+        continue;
+      }
+      if (token.name === "head") {
+        opts.head = token.value ?? null;
+      }
     }
-    if (args[i] === "--base" && i + 1 < args.length) opts.base = args[++i];
-    else if (args[i] === "--head" && i + 1 < args.length) opts.head = args[++i];
   }
   return opts;
 }
@@ -64,7 +89,7 @@ function isEligibleForLightMode(scope, threshold) {
   return scope.filesChanged <= threshold.maxFiles && scope.linesChanged <= threshold.maxLines;
 }
 async function main() {
-  const opts = parseArgs();
+  const opts = parseCliArgs(process.argv.slice(2));
   const scope = detectScope(opts);
   let threshold = { maxFiles: 3, maxLines: 200 };
   let eligible = false;

package/scripts/loop/detect-copilot-loop-state.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import {
   buildParseError,
   formatCliError,
@@ -58,32 +59,48 @@ Exit codes:
 const VALID_OVERRIDE_STATUSES = new Set(["requested", "already-requested", "unavailable", "none", "failed"]);
 const parseError = buildParseError(USAGE);
 export function parseDetectCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     inputPath: undefined,
     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" },
+      input: { type: "string" },
+      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 === "--input") {
-      options.inputPath = requireOptionValue(args, "--input", parseError);
+    if (token.name === "input") {
+      options.inputPath = requireTokenValue(token, parseError);
       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.inputPath !== undefined) {
     if (options.repo !== undefined || options.pr !== undefined) {