dev-loops 0.2.6 → 0.3.0

package/scripts/projects/archive-done-items.mjs

@@ -0,0 +1,506 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+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 archive-done --repo <owner/name> [--project <number|id>] [--older-than <duration>] [--dry-run]
+
+Archive GitHub Projects V2 items whose issue/PR has been closed for at least the
+given duration. Operator-triggered (no webhooks). Uses archiveProjectV2Item.
+
+Options:
+  --repo <owner/name>     Required. Repository to scope the project search.
+  --project <number|id>   Project number (integer) or node ID. When omitted,
+                          resolved from .devloops queue.projectNumber /
+                          queue.boardTitle.
+  --older-than <duration> Closed-for threshold. Format: <n><unit> where unit is
+                          h (hours), d (days), or w (weeks). Default resolves
+                          from .devloops queue.archiveOlderThanDays, else 7d.
+  --dry-run               Print the intended archive mutation(s) without executing.
+  --help, -h              Show this help.
+
+Output (stdout):
+  JSON: { ok: true, olderThan, scanned, archivable, archived: [{ itemId, issueNumber, prNumber, closedAt }] }
+  dry-run: { ok: true, dryRun: true, olderThan, scanned, archivable, mutations: [{ query, variables }] }
+  (scanned = all repo board items; archivable = items selected for archival)
+
+Exit codes:
+  0 — success
+  1 — usage or argument error
+  2 — GitHub API error
+  3 — project not found
+`.trim();
+
+function parseCliArgs(argv) {
+  const requireValue = (token, message, code) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw Object.assign(new Error(message), { code });
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      "older-than": { type: "string" },
+      "dry-run": { type: "boolean" },
+      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 (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)", "INVALID_REPO");
+        break;
+      case "project":
+        args.project = requireValue(token, "--project requires a value (number or node ID)", "INVALID_PROJECT");
+        break;
+      case "older-than":
+        args.olderThan = requireValue(token, "--older-than requires a value (e.g. 30d)", "INVALID_DURATION");
+        break;
+      case "dry-run":
+        if (token.value !== undefined) {
+          throw Object.assign(new Error(`Unknown flag: ${token.rawName}=${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
+        }
+        args.dryRun = true;
+        break;
+      default:
+        throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
+    }
+  }
+  return args;
+}
+
+// ── Validation ───────────────────────────────────────────────────────────
+
+const OWNER_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+const REPO_NAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9_.-]*[a-zA-Z0-9])?$/;
+const GLOBAL_NODE_ID_RE = /^[A-Za-z0-9_]+$/;
+
+function validateRepo(repo) {
+  if (!repo || typeof repo !== "string") {
+    throw Object.assign(new Error("--repo is required"), { code: "INVALID_REPO" });
+  }
+  const slashIdx = repo.indexOf("/");
+  if (slashIdx === -1) {
+    throw Object.assign(new Error(`--repo must be exactly owner/name, got "${repo}"`), { code: "INVALID_REPO" });
+  }
+  const owner = repo.slice(0, slashIdx);
+  const name = repo.slice(slashIdx + 1);
+  if (!owner || !name || !OWNER_RE.test(owner) || !REPO_NAME_RE.test(name)) {
+    throw Object.assign(new Error(`--repo must be exactly owner/name, got "${repo}"`), { code: "INVALID_REPO" });
+  }
+  return repo;
+}
+
+function parseProjectRef(raw) {
+  if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
+    throw Object.assign(new Error("--project is required"), { code: "INVALID_PROJECT" });
+  }
+  const trimmed = raw.trim();
+  const asNum = Number(trimmed);
+  if (Number.isInteger(asNum) && asNum > 0 && String(asNum) === trimmed) {
+    return { kind: "number", value: asNum };
+  }
+  if (GLOBAL_NODE_ID_RE.test(trimmed) && trimmed !== "0") {
+    return { kind: "id", value: trimmed };
+  }
+  throw Object.assign(new Error(`--project must be a positive integer or a node ID, got "${raw}"`), { code: "INVALID_PROJECT" });
+}
+
+const DURATION_RE = /^(\d+)(h|d|w)$/;
+const UNIT_MS = {
+  h: 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+  w: 7 * 24 * 60 * 60 * 1000,
+};
+
+function parseDuration(raw) {
+  if (!raw || typeof raw !== "string") {
+    throw Object.assign(new Error(`--older-than must be <n>(h|d|w), got "${raw}"`), { code: "INVALID_DURATION" });
+  }
+  const m = DURATION_RE.exec(raw.trim());
+  if (!m) {
+    throw Object.assign(new Error(`--older-than must be <n>(h|d|w), got "${raw}"`), { code: "INVALID_DURATION" });
+  }
+  const n = Number(m[1]);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw Object.assign(new Error(`--older-than must be a positive amount, got "${raw}"`), { code: "INVALID_DURATION" });
+  }
+  return n * UNIT_MS[m[2]];
+}
+
+// ── Settings fallback ──────────────────────────────────────────────────────
+
+// Read .devloops (and extension variants) queue settings, mirroring the
+// resolution used by ensure-queue-board.mjs. Returns { project }, { title },
+// and/or { olderThanDays } when configured; never throws on a missing/bad file.
+function resolveSettings(cwd) {
+  const basePath = path.join(cwd, ".devloops");
+  const extensions = ["", ".yaml", ".yml", ".json"];
+  for (const ext of extensions) {
+    try {
+      const raw = readFileSync(basePath + ext, "utf-8");
+      const settings = ext === ".json" ? JSON.parse(raw) : parseYaml(raw);
+      const queue = settings?.queue;
+      if (!queue) return null;
+      const out = {};
+      if (typeof queue.projectNumber === "number" && Number.isInteger(queue.projectNumber) && queue.projectNumber > 0) {
+        out.project = queue.projectNumber;
+      } else if (typeof queue.boardTitle === "string" && queue.boardTitle.trim().length > 0) {
+        out.title = queue.boardTitle.trim();
+      }
+      if (typeof queue.archiveOlderThanDays === "number" && Number.isInteger(queue.archiveOlderThanDays) && queue.archiveOlderThanDays > 0) {
+        out.olderThanDays = queue.archiveOlderThanDays;
+      }
+      return out;
+    } catch {
+      // extension not present or unparseable — try next
+    }
+  }
+  return null;
+}
+
+// ── API helpers ──────────────────────────────────────────────────────────
+
+async function ghGraphql(query, vars, env, runChild = _runChild) {
+  const fieldArgs = [];
+  for (const [key, value] of Object.entries(vars)) {
+    fieldArgs.push("--field", `${key}=${value}`);
+  }
+  const result = await runChild("gh", ["api", "graphql", "--field", `query=${query}`, ...fieldArgs], env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
+  }
+  const payload = parseJsonText(result.stdout);
+  if (payload.errors && payload.errors.length > 0) {
+    throw Object.assign(
+      new Error(`GraphQL errors: ${payload.errors.map((e) => e.message).join("; ")}`),
+      { code: "GRAPHQL_ERROR" },
+    );
+  }
+  return payload;
+}
+
+// ── GraphQL fragments ────────────────────────────────────────────────────
+
+const GET_USER_ID = ["query($login:String!) {", "  user(login:$login) { id }", "}"].join("\n");
+const GET_ORG_ID = ["query($login:String!) {", "  organization(login:$login) { id }", "}"].join("\n");
+
+const LIST_USER_PROJECTS = [
+  "query($login:String!, $after:String) {",
+  "  user(login:$login) {",
+  "    projectsV2(first:50, after:$after) {",
+  "      pageInfo { hasNextPage endCursor }",
+  "      nodes { id number title url }",
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+
+const LIST_ORG_PROJECTS = [
+  "query($login:String!, $after:String) {",
+  "  organization(login:$login) {",
+  "    projectsV2(first:50, after:$after) {",
+  "      pageInfo { hasNextPage endCursor }",
+  "      nodes { id number title url }",
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+
+const GET_PROJECT_ITEMS = [
+  "query($projectId:ID!, $after:String) {",
+  "  node(id:$projectId) {",
+  "    ... on ProjectV2 {",
+  "      items(first:50, after:$after, orderBy:{field:POSITION, direction:ASC}) {",
+  "        pageInfo { hasNextPage endCursor }",
+  "        nodes {",
+  "          id",
+  "          isArchived",
+  "          fieldValues(first:20) {",
+  "            nodes {",
+  "              ... on ProjectV2ItemFieldSingleSelectValue {",
+  "                field { ... on ProjectV2SingleSelectField { id name } }",
+  "                name",
+  "              }",
+  "            }",
+  "          }",
+  "          content {",
+  "            ... on Issue { __typename number closed closedAt repository { nameWithOwner } }",
+  "            ... on PullRequest { __typename number closed closedAt repository { nameWithOwner } }",
+  "          }",
+  "        }",
+  "      }",
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+
+const ARCHIVE_ITEM = [
+  "mutation($projectId:ID!, $itemId:ID!) {",
+  "  archiveProjectV2Item(input:{projectId:$projectId, itemId:$itemId}) {",
+  "    item { id }",
+  "  }",
+  "}",
+].join("\n");
+
+// ── Owner / project resolution ─────────────────────────────────────────────
+
+async function resolveOwner(login, env, runChild) {
+  const userPayload = await ghGraphql(GET_USER_ID, { login }, env, runChild);
+  if (userPayload?.data?.user?.id) return { id: userPayload.data.user.id, kind: "user" };
+  const orgPayload = await ghGraphql(GET_ORG_ID, { login }, env, runChild);
+  if (orgPayload?.data?.organization?.id) return { id: orgPayload.data.organization.id, kind: "org" };
+  throw Object.assign(new Error(`Could not resolve owner ID for "${login}"`), { code: "NO_USER_ID" });
+}
+
+async function listAllProjects(login, kind, env, runChild) {
+  const query = kind === "org" ? LIST_ORG_PROJECTS : LIST_USER_PROJECTS;
+  const projects = [];
+  let after = null;
+  while (true) {
+    const vars = { login };
+    if (after) vars.after = after;
+    const payload = await ghGraphql(query, vars, env, runChild);
+    const connection = kind === "org" ? payload?.data?.organization?.projectsV2 : payload?.data?.user?.projectsV2;
+    const nodes = connection?.nodes ?? [];
+    projects.push(...nodes);
+    const pageInfo = connection?.pageInfo ?? {};
+    if (!pageInfo.hasNextPage) break;
+    if (!pageInfo.endCursor) {
+      throw Object.assign(new Error("Invalid projects list payload: hasNextPage true but endCursor missing"), { code: "GH_API_ERROR" });
+    }
+    after = pageInfo.endCursor;
+  }
+  return projects;
+}
+
+async function fetchAllItems(projectId, env, runChild) {
+  const all = [];
+  let after = null;
+  while (true) {
+    const vars = { projectId };
+    if (after) vars.after = after;
+    const payload = await ghGraphql(GET_PROJECT_ITEMS, vars, env, runChild);
+    const connection = payload?.data?.node?.items;
+    const nodes = connection?.nodes ?? [];
+    all.push(...nodes);
+    const pageInfo = connection?.pageInfo ?? {};
+    if (!pageInfo.hasNextPage) break;
+    if (!pageInfo.endCursor) {
+      throw Object.assign(new Error("Invalid items payload: hasNextPage true but endCursor missing"), { code: "GH_API_ERROR" });
+    }
+    after = pageInfo.endCursor;
+  }
+  return all;
+}
+
+function statusOf(node) {
+  const fvs = node?.fieldValues?.nodes ?? [];
+  for (const fv of fvs) {
+    if (fv && fv.field && fv.field.name === "Status") return fv.name;
+  }
+  return null;
+}
+
+// Normalize a raw GraphQL item node into the shape selectArchivable expects.
+function normalizeItem(node) {
+  return {
+    id: node.id,
+    isArchived: Boolean(node.isArchived),
+    status: statusOf(node),
+    content: node.content
+      ? {
+          __typename: node.content.__typename,
+          number: node.content.number,
+          closed: Boolean(node.content.closed),
+          closedAt: node.content.closedAt ?? null,
+          repository: node.content.repository,
+        }
+      : null,
+  };
+}
+
+// ── Selection logic (pure) ────────────────────────────────────────────────
+
+// Select items whose issue/PR is closed and has been closed for >= olderThanMs.
+function selectArchivable(items, { now, olderThanMs }) {
+  return items.filter((it) => {
+    if (it.isArchived) return false;
+    // Only archive items in the Done column — a closed issue/PR parked in
+    // another column (Backlog/Next Up/In Progress) must be left untouched.
+    if (it.status !== "Done") return false;
+    const c = it.content;
+    if (!c || !c.closed || !c.closedAt) return false;
+    const closedAtMs = Date.parse(c.closedAt);
+    if (Number.isNaN(closedAtMs)) return false;
+    return now - closedAtMs >= olderThanMs;
+  });
+}
+
+// ── Exit code classification ────────────────────────────────────────────
+
+function classifyExitCode(err) {
+  if (err.code === "INVALID_REPO" || err.code === "INVALID_PROJECT" ||
+      err.code === "INVALID_DURATION" || err.code === "INVALID_ARGS") return 1;
+  if (err.code === "PROJECT_NOT_FOUND") return 3;
+  return 2;
+}
+
+// ── Main logic ──────────────────────────────────────────────────────────
+
+async function main(args, { env = process.env, runChild } = {}) {
+  const child = runChild ?? _runChild;
+  const repo = validateRepo(args.repo);
+  const [owner] = repo.split("/");
+  // Board: explicit --project ref wins; otherwise resolve by board title from
+  // .devloops (passed in as args.projectTitle by runCli). Fail closed if neither.
+  const hasProjectRef = typeof args.project === "string" && args.project.trim().length > 0;
+  const projectRef = hasProjectRef ? parseProjectRef(args.project) : null;
+  const projectTitle = !hasProjectRef && typeof args.projectTitle === "string" && args.projectTitle.trim().length > 0
+    ? args.projectTitle.trim()
+    : null;
+  if (!projectRef && !projectTitle) {
+    throw Object.assign(
+      new Error("--project is required (or configure queue.projectNumber / queue.boardTitle in .devloops)"),
+      { code: "INVALID_PROJECT" },
+    );
+  }
+  const olderThanRaw = args.olderThan ?? args.olderThanDefault ?? "7d";
+  const olderThanMs = parseDuration(olderThanRaw);
+  const now = args.now ?? Date.now();
+
+  const { kind: ownerKind } = await resolveOwner(owner, env, child);
+  const projects = await listAllProjects(owner, ownerKind, env, child);
+  const project = projectRef
+    ? (projectRef.kind === "id"
+        ? projects.find((p) => p.id === projectRef.value)
+        : projects.find((p) => p.number === projectRef.value))
+    : projects.find((p) => p.title === projectTitle);
+  if (!project) {
+    const desc = projectRef
+      ? (projectRef.kind === "id" ? `"${projectRef.value}"` : `number ${projectRef.value}`)
+      : `title "${projectTitle}"`;
+    throw Object.assign(
+      new Error(`Project ${desc} not found under owner "${owner}"`),
+      { code: "PROJECT_NOT_FOUND" },
+    );
+  }
+
+  const rawItems = await fetchAllItems(project.id, env, child);
+  // Only consider items whose content belongs to the target repo (single-repo scope).
+  const repoItems = rawItems
+    .filter((n) => n.content && n.content.repository?.nameWithOwner === repo)
+    .map(normalizeItem);
+
+  const archivable = selectArchivable(repoItems, { now, olderThanMs });
+
+  const mutations = archivable.map((it) => ({
+    query: ARCHIVE_ITEM,
+    variables: { projectId: project.id, itemId: it.id },
+  }));
+
+  if (args.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      olderThan: olderThanRaw,
+      scanned: repoItems.length,
+      archivable: archivable.length,
+      mutations,
+    };
+  }
+
+  const archived = [];
+  for (const it of archivable) {
+    const payload = await ghGraphql(ARCHIVE_ITEM, { projectId: project.id, itemId: it.id }, env, child);
+    if (!payload?.data?.archiveProjectV2Item?.item) {
+      throw Object.assign(new Error(`Failed to archive item ${it.id}`), { code: "MUTATION_FAILED" });
+    }
+    archived.push({
+      itemId: it.id,
+      issueNumber: it.content.__typename === "Issue" ? it.content.number : null,
+      prNumber: it.content.__typename === "PullRequest" ? it.content.number : null,
+      closedAt: it.content.closedAt,
+    });
+  }
+
+  return {
+    ok: true,
+    olderThan: olderThanRaw,
+    scanned: repoItems.length,
+    archivable: archivable.length,
+    archived,
+  };
+}
+
+// ── CLI entrypoint ──────────────────────────────────────────────────────
+
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd() } = {}) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    stdout.write(USAGE);
+    return;
+  }
+
+  // Resolve board + threshold defaults from .devloops when the flags are absent.
+  // Precedence: explicit --project flag > queue.projectNumber/boardTitle.
+  //             explicit --older-than flag > queue.archiveOlderThanDays > 7d.
+  const settings = resolveSettings(cwd);
+  if (args.project === undefined && settings) {
+    if (settings.project) args.project = String(settings.project);
+    else if (settings.title) args.projectTitle = settings.title;
+  }
+  if (args.olderThan === undefined && settings?.olderThanDays) {
+    args.olderThanDefault = `${settings.olderThanDays}d`;
+  }
+
+  try {
+    const result = await main(args, { env });
+    stdout.write(JSON.stringify(result) + "\n");
+  } catch (err) {
+    stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = classifyExitCode(err);
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(JSON.stringify({ ok: false, error: error.message, code: error.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = 2;
+  });
+}
+
+export { main, parseCliArgs, parseDuration, selectArchivable, resolveSettings, runCli };

package/scripts/projects/ensure-queue-board.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { parseArgs } from "node:util";
 import { parse as parseYaml } from "yaml";
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
@@ -32,76 +33,76 @@ Exit codes:
   3 — board schema/config mismatch (manual reconciliation needed)
 `;
 
-const VALID_ARGS = new Set(["--repo", "--project", "--title", "--link-repo", "--repair-rename", "--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 = {}; // title default applied in runCli after settings fallback
-  const consumed = new Set();
-  for (let i = 0; i < argv.length; i++) {
-    if (consumed.has(i)) continue;
-    const arg = argv[i];
-    if (!VALID_ARGS.has(arg) && arg.startsWith("-")) {
-      throw Object.assign(
-        new Error(`Unknown flag: ${arg}`),
-        { code: "INVALID_REPO", usage: USAGE },
-      );
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      title: { type: "string" },
+      "link-repo": { type: "string" },
+      "repair-rename": { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unexpected argument: ${token.value}`);
     }
-    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", usage: USAGE },
-        );
-      }
-      args.repo = argv[++i];
-      consumed.add(i);
-    } else if (arg === "--project") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--project requires a numeric value"),
-          { code: "INVALID_PROJECT", usage: USAGE },
-        );
-      }
-      const num = Number(argv[++i]);
-      if (!Number.isInteger(num) || num <= 0) {
-        throw Object.assign(
-          new Error(`--project must be a positive integer, got "${argv[i]}"`),
-          { code: "INVALID_PROJECT", usage: USAGE },
-        );
-      }
-      args.project = num;
-    } else if (arg === "--title") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--title requires a value"),
-          { code: "INVALID_REPO", usage: USAGE },
-        );
-      }
-      args.title = argv[++i];
-      consumed.add(i);
-    } else if (arg === "--link-repo") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--link-repo requires a value (owner/name)"),
-          { code: "INVALID_REPO", usage: USAGE },
-        );
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.help = true;
+        break;
+      case "repo":
+        args.repo = requireValue(token, "--repo requires a value (owner/name)");
+        break;
+      case "project": {
+        const raw = requireValue(token, "--project requires a numeric value");
+        const num = Number(raw);
+        if (!Number.isInteger(num) || num <= 0) {
+          throw parseError(`--project must be a positive integer, got "${raw}"`);
+        }
+        args.project = num;
+        break;
       }
-      args.linkRepo = argv[++i];
-      consumed.add(i);
-    } else if (arg === "--repair-rename") {
-      args.repairRename = true;
-    } else if (arg === "--help" || arg === "-h") {
-      args.help = true;
-    } else {
-      throw Object.assign(
-        new Error(`Unexpected argument: ${arg}`),
-        { code: "INVALID_REPO", usage: USAGE },
-      );
+      case "title":
+        args.title = requireValue(token, "--title requires a value");
+        break;
+      case "link-repo":
+        args.linkRepo = requireValue(token, "--link-repo requires a value (owner/name)");
+        break;
+      case "repair-rename":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.repairRename = true;
+        break;
+      default:
+        throw parseError(`Unknown flag: ${token.rawName}`);
     }
   }
   return args;
 }
-
 // ── Validation ───────────────────────────────────────────────────────────
 
 // GitHub slug rules: owner 1-39 chars (alnum/dash, no leading/trailing dash,
@@ -798,7 +799,7 @@ async function main(args, { env = process.env, runChild } = {}) {
 async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd() } = {}) {
   let args;
   try {
-    args = parseArgs(argv);
+    args = parseCliArgs(argv);
   } catch (err) {
     stderr.write(`${formatCliError(err)}\n`);
     process.exitCode = 1;