dev-loops 0.2.6 → 0.3.0

package/scripts/loop/steer-loop.mjs

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import process from "node:process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 import {
   STEERING_KIND,
   STEERING_RESULT,
@@ -31,7 +32,7 @@ import {
   withStateFileLock,
 } from "./_steering-state-file.mjs";
 import { formatCliError } from "../_core-helpers.mjs";
-import { requireOptionValue as readSharedOptionValue } from "../_cli-primitives.mjs";
+import { requireTokenValue as readSharedTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 const SUBMIT_USAGE = `Usage:
   steer-loop.mjs submit --repo <owner/name> --pr <number>
@@ -112,10 +113,9 @@ function runIdMismatchError(persistedRunId, requestedRunId) {
     `run-id mismatch: --state-file contains run ${JSON.stringify(persistedRunId)} but --run-id is ${JSON.stringify(requestedRunId)}. Use the correct --run-id or point --state-file at the right file.`
   );
 }
-function readRequiredOptionValue(args, flag, usage, { allowFlagLike = false } = {}) {
-  return readSharedOptionValue(
-    args,
-    flag,
+function readRequiredOptionValue(token, usage, { allowFlagLike = false } = {}) {
+  return readSharedTokenValue(
+    token,
     (message) => usageError(message, usage),
     { flagPattern: allowFlagLike ? /$^/u : /^--/u },
   );
@@ -139,7 +139,6 @@ function parsePositiveIntegerOption(raw, flag, usage) {
   return Number(raw);
 }
 export function parseSubmitCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -156,48 +155,74 @@ export function parseSubmitCliArgs(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" },
+      "run-id": { type: "string" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      kind: { type: "string" },
+      directive: { type: "string" },
+      seq: { type: "string" },
+      "state-file": { type: "string" },
+      "loop-state": { type: "string" },
+      "apply-mode": { type: "string" },
+      "event-id": { 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 usageError(`Unknown argument: ${token.value}`, SUBMIT_USAGE);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--run-id") {
-      options.runId = readRequiredOptionValue(args, "--run-id", SUBMIT_USAGE).trim();
+    if (token.name === "run-id") {
+      options.runId = readRequiredOptionValue(token, SUBMIT_USAGE).trim();
       validateSafeRunId(options.runId, SUBMIT_USAGE);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = readRequiredOptionValue(args, "--repo", SUBMIT_USAGE).trim();
+    if (token.name === "repo") {
+      options.repo = readRequiredOptionValue(token, SUBMIT_USAGE).trim();
       parseRepoSlugOption(options.repo, SUBMIT_USAGE);
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePositiveIntegerOption(readRequiredOptionValue(args, "--pr", SUBMIT_USAGE), "--pr", SUBMIT_USAGE);
+    if (token.name === "pr") {
+      options.pr = parsePositiveIntegerOption(readRequiredOptionValue(token, SUBMIT_USAGE), "--pr", SUBMIT_USAGE);
       continue;
     }
-    if (token === "--kind") {
-      const val = readRequiredOptionValue(args, "--kind", SUBMIT_USAGE);
+    if (token.name === "kind") {
+      const val = readRequiredOptionValue(token, SUBMIT_USAGE);
       if (!VALID_KINDS.has(val)) {
         throw usageError(`--kind must be one of: ${[...VALID_KINDS].join(", ")}`, SUBMIT_USAGE);
       }
       options.kind = val;
       continue;
     }
-    if (token === "--directive") {
-      options.directive = readRequiredOptionValue(args, "--directive", SUBMIT_USAGE, { allowFlagLike: true }).trim();
+    if (token.name === "directive") {
+      options.directive = readRequiredOptionValue(token, SUBMIT_USAGE, { allowFlagLike: true }).trim();
       continue;
     }
-    if (token === "--seq") {
-      options.seq = parsePositiveIntegerOption(readRequiredOptionValue(args, "--seq", SUBMIT_USAGE), "--seq", SUBMIT_USAGE);
+    if (token.name === "seq") {
+      options.seq = parsePositiveIntegerOption(readRequiredOptionValue(token, SUBMIT_USAGE), "--seq", SUBMIT_USAGE);
       continue;
     }
-    if (token === "--state-file") {
-      options.stateFile = readRequiredOptionValue(args, "--state-file", SUBMIT_USAGE);
+    if (token.name === "state-file") {
+      options.stateFile = readRequiredOptionValue(token, SUBMIT_USAGE);
       continue;
     }
-    if (token === "--loop-state") {
-      const val = readRequiredOptionValue(args, "--loop-state", SUBMIT_USAGE);
+    if (token.name === "loop-state") {
+      const val = readRequiredOptionValue(token, SUBMIT_USAGE);
       if (!VALID_LOOP_STATES.has(val)) {
         throw usageError(`--loop-state must be one of: ${[...VALID_LOOP_STATES].join(", ")}`, SUBMIT_USAGE);
       }
@@ -205,27 +230,27 @@ export function parseSubmitCliArgs(argv) {
       options.loopStateExplicit = true;
       continue;
     }
-    if (token === "--apply-mode") {
-      const val = readRequiredOptionValue(args, "--apply-mode", SUBMIT_USAGE);
+    if (token.name === "apply-mode") {
+      const val = readRequiredOptionValue(token, SUBMIT_USAGE);
       if (!VALID_APPLY_MODES.has(val)) {
         throw usageError(`--apply-mode must be one of: ${[...VALID_APPLY_MODES].join(", ")}`, SUBMIT_USAGE);
       }
       options.applyMode = val;
       continue;
     }
-    if (token === "--event-id") {
-      options.eventId = readRequiredOptionValue(args, "--event-id", SUBMIT_USAGE);
+    if (token.name === "event-id") {
+      options.eventId = readRequiredOptionValue(token, SUBMIT_USAGE);
       continue;
     }
-    if (token === "--copilot-input") {
-      options.copilotInputPath = readRequiredOptionValue(args, "--copilot-input", SUBMIT_USAGE);
+    if (token.name === "copilot-input") {
+      options.copilotInputPath = readRequiredOptionValue(token, SUBMIT_USAGE);
       continue;
     }
-    if (token === "--reviewer-input") {
-      options.reviewerInputPath = readRequiredOptionValue(args, "--reviewer-input", SUBMIT_USAGE);
+    if (token.name === "reviewer-input") {
+      options.reviewerInputPath = readRequiredOptionValue(token, SUBMIT_USAGE);
       continue;
     }
-    throw usageError(`Unknown argument: ${token}`, SUBMIT_USAGE);
+    throw usageError(`Unknown argument: ${token.rawName}`, SUBMIT_USAGE);
   }
   if (!options.help) {
     if ((options.repo === undefined) !== (options.pr === undefined)) {
@@ -250,7 +275,6 @@ export function parseSubmitCliArgs(argv) {
   return options;
 }
 export function parseStatusCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -258,31 +282,49 @@ export function parseStatusCliArgs(argv) {
     runId: undefined,
     stateFile: 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" },
+      "run-id": { type: "string" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "state-file": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw usageError(`Unknown argument: ${token.value}`, STATUS_USAGE);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--run-id") {
-      options.runId = readRequiredOptionValue(args, "--run-id", STATUS_USAGE).trim();
+    if (token.name === "run-id") {
+      options.runId = readRequiredOptionValue(token, STATUS_USAGE).trim();
       validateSafeRunId(options.runId, STATUS_USAGE);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = readRequiredOptionValue(args, "--repo", STATUS_USAGE).trim();
+    if (token.name === "repo") {
+      options.repo = readRequiredOptionValue(token, STATUS_USAGE).trim();
       parseRepoSlugOption(options.repo, STATUS_USAGE);
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePositiveIntegerOption(readRequiredOptionValue(args, "--pr", STATUS_USAGE), "--pr", STATUS_USAGE);
+    if (token.name === "pr") {
+      options.pr = parsePositiveIntegerOption(readRequiredOptionValue(token, STATUS_USAGE), "--pr", STATUS_USAGE);
       continue;
     }
-    if (token === "--state-file") {
-      options.stateFile = readRequiredOptionValue(args, "--state-file", STATUS_USAGE);
+    if (token.name === "state-file") {
+      options.stateFile = readRequiredOptionValue(token, STATUS_USAGE);
       continue;
     }
-    throw usageError(`Unknown argument: ${token}`, STATUS_USAGE);
+    throw usageError(`Unknown argument: ${token.rawName}`, STATUS_USAGE);
   }
   if (!options.help) {
     if ((options.repo === undefined) !== (options.pr === undefined)) {
@@ -298,7 +340,6 @@ export function parseStatusCliArgs(argv) {
   return options;
 }
 export function parsePromoteCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -307,39 +348,58 @@ export function parsePromoteCliArgs(argv) {
     stateFile: undefined,
     loopState: 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" },
+      "run-id": { type: "string" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      "state-file": { type: "string" },
+      "loop-state": { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw usageError(`Unknown argument: ${token.value}`, PROMOTE_USAGE);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
       options.help = true;
       return options;
     }
-    if (token === "--run-id") {
-      options.runId = readRequiredOptionValue(args, "--run-id", PROMOTE_USAGE).trim();
+    if (token.name === "run-id") {
+      options.runId = readRequiredOptionValue(token, PROMOTE_USAGE).trim();
       validateSafeRunId(options.runId, PROMOTE_USAGE);
       continue;
     }
-    if (token === "--repo") {
-      options.repo = readRequiredOptionValue(args, "--repo", PROMOTE_USAGE).trim();
+    if (token.name === "repo") {
+      options.repo = readRequiredOptionValue(token, PROMOTE_USAGE).trim();
       parseRepoSlugOption(options.repo, PROMOTE_USAGE);
       continue;
     }
-    if (token === "--pr") {
-      options.pr = parsePositiveIntegerOption(readRequiredOptionValue(args, "--pr", PROMOTE_USAGE), "--pr", PROMOTE_USAGE);
+    if (token.name === "pr") {
+      options.pr = parsePositiveIntegerOption(readRequiredOptionValue(token, PROMOTE_USAGE), "--pr", PROMOTE_USAGE);
       continue;
     }
-    if (token === "--state-file") {
-      options.stateFile = readRequiredOptionValue(args, "--state-file", PROMOTE_USAGE);
+    if (token.name === "state-file") {
+      options.stateFile = readRequiredOptionValue(token, PROMOTE_USAGE);
       continue;
     }
-    if (token === "--loop-state") {
-      const val = readRequiredOptionValue(args, "--loop-state", PROMOTE_USAGE);
+    if (token.name === "loop-state") {
+      const val = readRequiredOptionValue(token, PROMOTE_USAGE);
       if (!VALID_LOOP_STATES.has(val)) {
         throw usageError(`--loop-state must be one of: ${[...VALID_LOOP_STATES].join(", ")}`, PROMOTE_USAGE);
       }
       options.loopState = val;
       continue;
     }
-    throw usageError(`Unknown argument: ${token}`, PROMOTE_USAGE);
+    throw usageError(`Unknown argument: ${token.rawName}`, PROMOTE_USAGE);
   }
   if (!options.help) {
     if ((options.repo === undefined) !== (options.pr === undefined)) {

package/scripts/loop/watch-initial-copilot-pr.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { setTimeout as delay } from "node:timers/promises";
 import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parseIssueNumber, requireOptionValue } from "../_cli-primitives.mjs";
+import { parseIssueNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectInitialCopilotPrState, LINKED_PR_STATE } from "./detect-initial-copilot-pr-state.mjs";
 import { enforcePersistentInternalWaitTimeout } from "@dev-loops/core/loop/timeout-policy";
@@ -94,7 +95,6 @@ export async function watchCopilotRunUntilComplete(
   });
 }
 export function parseWatchInitialCopilotPrCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
@@ -102,24 +102,40 @@ export function parseWatchInitialCopilotPrCliArgs(argv) {
     pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
     timeoutMs: COPILOT_FIRST_DURABLE_WAIT_TIMEOUT_MS,
   };
-  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" },
+      issue: { 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 === "--issue") {
-      options.issue = parseIssueNumber(requireOptionValue(args, "--issue", parseError), parseError);
+    if (token.name === "issue") {
+      options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
     throw parseError("watch-initial-copilot-pr requires both --repo <owner/name> and --issue <number>");

package/scripts/projects/add-queue-item.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
 
 const USAGE = `Usage: dev-loops project add --repo <owner/name> --project <number|id> --item <number>
 
@@ -23,52 +24,68 @@ Exit codes:
   3 — project, field, column, or issue/PR not found
 `.trim();
 
-const VALID_ARGS = new Set(["--repo", "--project", "--item", "--status", "--help", "-h"]);
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
 
-function parseArgs(argv) {
   const args = {};
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (!VALID_ARGS.has(arg) && arg.startsWith("-")) {
-      throw Object.assign(
-        new Error(`Unknown flag: ${arg}`),
-        { code: "INVALID_ARGS", usage: USAGE },
-      );
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      item: { type: "string" },
+      status: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw Object.assign(new Error(`Unexpected argument: ${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
     }
-    if (arg === "--repo") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--repo requires a value (owner/name)"), { code: "INVALID_REPO" });
-      }
-      args.repo = argv[++i];
-    } else if (arg === "--project") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--project requires a value (number or node ID)"), { code: "INVALID_PROJECT" });
-      }
-      args.project = argv[++i];
-    } else if (arg === "--item") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--item requires a value (number)"), { code: "INVALID_ITEM" });
-      }
-      const val = Number(argv[++i]);
-      if (!Number.isInteger(val) || val < 1) {
-        throw Object.assign(
-          new Error(`--item must be a positive integer, got "${argv[i]}"`),
-          { code: "INVALID_ITEM" },
-        );
-      }
-      args.item = val;
-    } else if (arg === "--status") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--status requires a value"), { code: "INVALID_STATUS" });
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        if (token.value !== undefined) {
+          throw Object.assign(new Error(`Unknown flag: ${token.rawName}=${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
+        }
+        args.help = true;
+        break;
+      case "repo":
+        args.repo = requireValue(token, "--repo requires a value (owner/name)");
+        break;
+      case "project":
+        args.project = requireValue(token, "--project requires a value (number or node ID)");
+        break;
+      case "item": {
+        const raw = requireValue(token, "--item requires a value (number)");
+        const val = Number(raw);
+        if (!Number.isInteger(val) || val < 1) {
+          throw Object.assign(
+            new Error(`--item must be a positive integer, got "${raw}"`),
+            { code: "INVALID_ITEM" },
+          );
+        }
+        args.item = val;
+        break;
       }
-      args.status = argv[++i];
-    } else if (arg === "--help" || arg === "-h") {
-      args.help = true;
-    } else {
-      throw Object.assign(
-        new Error(`Unexpected argument: ${arg}`),
-        { code: "INVALID_ARGS", usage: USAGE },
-      );
+      case "status":
+        args.status = requireValue(token, "--status requires a value");
+        break;
+      default:
+        throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
     }
   }
   return args;
@@ -499,7 +516,7 @@ async function main(args, { env = process.env, runChild } = {}) {
 async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
   let args;
   try {
-    args = parseArgs(argv);
+    args = parseCliArgs(argv);
   } catch (err) {
     stderr.write(`${formatCliError(err)}\n`);
     process.exitCode = 1;