dev-loops 0.2.5 → 0.2.7

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 { runChild, 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";
@@ -13,6 +13,8 @@ import {
   parseRecordedHandoffContract,
 } 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:
@@ -80,7 +82,6 @@ Exit codes:
   0  Success
   1  Argument error, gh failure, or indeterminate PR status`.trim();
 const parseError = buildParseError(USAGE);
-const OPEN_PR_LIST_LIMIT = 1000;
 const DEFAULT_SESSION_ROOT = path.join(os.homedir(), ".pi", "agent", "sessions");
 const RUN_STATE = {
   COMPLETED: "completed",
@@ -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>");
@@ -145,43 +161,6 @@ function parseCliArgs(argv) {
   }
   return options;
 }
-async function listOpenPrs({ repo }, { env, ghCommand }) {
-  const result = await runChild(
-    ghCommand,
-    [
-      "pr",
-      "list",
-      "--repo",
-      repo,
-      "--state",
-      "open",
-      "--limit",
-      String(OPEN_PR_LIST_LIMIT),
-      "--json",
-      "number,title,url,isDraft,headRefName,author",
-    ],
-    env,
-  );
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw new Error(`gh command failed: ${detail}`);
-  }
-  const payload = parseJsonText(result.stdout);
-  if (!Array.isArray(payload)) {
-    throw new Error("Invalid gh pr list payload: expected an array");
-  }
-  return payload
-    .map((pr) => ({
-      number: Number.isInteger(pr?.number) ? pr.number : null,
-      title: typeof pr?.title === "string" ? pr.title : "",
-      url: typeof pr?.url === "string" ? pr.url : null,
-      isDraft: Boolean(pr?.isDraft),
-      headRefName: typeof pr?.headRefName === "string" ? pr.headRefName : null,
-      authorLogin: typeof pr?.author?.login === "string" ? pr.author.login : null,
-    }))
-    .filter((pr) => pr.number !== null)
-    .sort((left, right) => left.number - right.number);
-}
 function summarizePrDisposition(loopDisposition) {
   switch (loopDisposition) {
     case "pending":

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

package/scripts/loop/detect-copilot-session-activity.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parsePositiveInteger, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: detect-copilot-session-activity.mjs --repo <owner/name> --branch <name> [--limit <number>]
 Detect Copilot GitHub Actions session activity on a branch.
 Required:
@@ -41,32 +42,48 @@ const COPILOT_RUN_NAME_PATTERNS = Object.freeze([
 ]);
 const parseError = buildParseError(USAGE);
 export function parseDetectCopilotSessionActivityCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     branch: undefined,
     limit: DEFAULT_LIMIT,
   };
-  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" },
+      branch: { type: "string" },
+      limit: { 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 === "--branch") {
-      options.branch = requireOptionValue(args, "--branch", parseError).trim();
+    if (token.name === "branch") {
+      options.branch = requireTokenValue(token, parseError).trim();
       continue;
     }
-    if (token === "--limit") {
-      options.limit = parsePositiveInteger(requireOptionValue(args, "--limit", parseError), "--limit", parseError);
+    if (token.name === "limit") {
+      options.limit = parsePositiveInteger(requireTokenValue(token, parseError), "--limit", parseError);
       continue;
     }
-    throw parseError(`Unknown argument: ${token}`);
+    throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.branch === undefined || options.branch.length === 0) {
     throw parseError("detect-copilot-session-activity requires both --repo <owner/name> and --branch <name>");

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

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { parseIssueNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseIssueNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectLinkedIssuePr } from "../github/detect-linked-issue-pr.mjs";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
+import { parseArgs } from "node:util";
 const USAGE = `Usage: detect-initial-copilot-pr-state.mjs --repo <owner/name> --issue <number>
 Detect whether an assigned issue is still on the bootstrap-only Copilot draft PR
 or has moved into normal linked-PR follow-up.
@@ -79,27 +80,42 @@ const INITIAL_COPILOT_PR_FACTS_QUERY = [
 ].join("\n");
 const parseError = buildParseError(USAGE);
 export function parseDetectInitialCopilotPrStateCliArgs(argv) {
-  const args = [...argv];
   const options = {
     help: false,
     repo: undefined,
     issue: 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" },
+      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 (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("detect-initial-copilot-pr-state requires both --repo <owner/name> and --issue <number>");