dev-loops 0.2.7 → 0.3.0

package/scripts/projects/move-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 move --repo <owner/name> --project <number|id> --item <number|node-id> --to-column <name>
 
@@ -23,47 +24,63 @@ Exit codes:
   3 — project, field, column, or item not found
 `.trim();
 
-const VALID_ARGS = new Set(["--repo", "--project", "--item", "--to-column", "--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" },
+      "to-column": { type: "string" },
+      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" });
-      }
-      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 or node ID)"), { code: "INVALID_ITEM" });
-      }
-      args.item = argv[++i];
-    } else if (arg === "--to-column") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--to-column requires a value"), { code: "INVALID_COLUMN" });
-      }
-      args.toColumn = 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 });
+    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":
+        args.project = requireValue(token, "--project requires a value (number or node ID)");
+        break;
+      case "item":
+        args.item = requireValue(token, "--item requires a value (number or node ID)");
+        break;
+      case "to-column":
+        args.toColumn = requireValue(token, "--to-column requires a value");
+        break;
+      default:
+        throw parseError(`Unknown flag: ${token.rawName}`);
     }
   }
   return args;
 }
-
 // ── Validation ───────────────────────────────────────────────────────────
 
 const OWNER_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
@@ -210,7 +227,7 @@ const GET_PROJECT_ITEMS_BY_CONTENT = [
   "query($projectId:ID!, $after:String) {",
   "  node(id:$projectId) {",
   "    ... on ProjectV2 {",
-  "      items(first:10, after:$after, orderBy:{field:POSITION, direction:ASC}) {",
+  "      items(first:100, after:$after, orderBy:{field:POSITION, direction:ASC}) {",
   "        pageInfo { hasNextPage endCursor }",
   "        nodes {",
   "          id",
@@ -223,8 +240,8 @@ const GET_PROJECT_ITEMS_BY_CONTENT = [
   "            }",
   "          }",
   "          content {",
-  "            ... on Issue { number repository { nameWithOwner } }",
-  "            ... on PullRequest { number repository { nameWithOwner } }",
+  "            ... on Issue { __typename number repository { nameWithOwner } }",
+  "            ... on PullRequest { __typename number repository { nameWithOwner } }",
   "          }",
   "        }",
   "      }",
@@ -233,30 +250,6 @@ const GET_PROJECT_ITEMS_BY_CONTENT = [
   "}"
 ].join("\n");
 
-const GET_PROJECT_ITEM = [
-  "query($projectId:ID!, $itemId:ID!) {",
-  "  node(id:$projectId) {",
-  "    ... on ProjectV2 {",
-  "      item: item(id:$itemId) {",
-  "        id",
-  "        fieldValues(first:20) {",
-  "          nodes {",
-  "            ... on ProjectV2ItemFieldSingleSelectValue {",
-  "              field { ... on ProjectV2SingleSelectField { id name } }",
-  "              name",
-  "            }",
-  "          }",
-  "        }",
-  "        content {",
-  "          ... on Issue { number title url }",
-  "          ... on PullRequest { number title url }",
-  "        }",
-  "      }",
-  "    }",
-  "  }",
-  "}"
-].join("\n");
-
 const UPDATE_ITEM_FIELD = [
   "mutation($projectId:ID!, $itemId:ID!, $fieldId:ID!, $optionId:String!) {",
   "  updateProjectV2ItemFieldValue(input:{projectId:$projectId, itemId:$itemId, fieldId:$fieldId, value:{singleSelectOptionId:$optionId}}) {",
@@ -337,6 +330,39 @@ async function listAllFields(projectId, env, runChild) {
   return fields;
 }
 
+// ── Paginated item listing (position order) ──────────────────────────────
+
+async function fetchAllItems(projectId, env, runChild) {
+  const items = [];
+  let after = null;
+  while (true) {
+    const vars = { projectId };
+    if (after) vars.after = after;
+    const payload = await ghGraphql(GET_PROJECT_ITEMS_BY_CONTENT, vars, env, runChild);
+    const connection = payload?.data?.node?.items;
+    const nodes = connection?.nodes ?? [];
+    items.push(...nodes);
+    const pageInfo = connection?.pageInfo ?? {};
+    if (!pageInfo.hasNextPage) break;
+    if (!pageInfo.endCursor) {
+      throw Object.assign(
+        new Error("Invalid items payload: hasNextPage is true but endCursor is missing"),
+        { code: "GH_API_ERROR" },
+      );
+    }
+    after = pageInfo.endCursor;
+  }
+  return items;
+}
+
+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;
+}
+
 // ── Exit code classification ────────────────────────────────────────────
 
 function classifyExitCode(err) {
@@ -397,80 +423,53 @@ async function main(args, { env = process.env, runChild } = {}) {
     );
   }
 
-  // 4. Find the item
-  let itemId;
-  let previousColumn = null;
-  let issueNumber = null;
-  let prNumber = null;
-
+  // 4. Find the item.
+  //
+  // Fetch the full board item list ONCE (paginated, position order) and resolve
+  // BOTH ref kinds against it. This reuses the proven pattern from
+  // reorder-queue-item / list-queue-items: a node-id ref matches by item.id, a
+  // number ref matches by content.number. Both are scoped to the requested repo
+  // so a cross-project ref fails closed with ITEM_NOT_FOUND. (The previous code
+  // used `ProjectV2.item` — a field that does not exist — for the node-id path,
+  // and a single non-paginated `items(first:10)` page for the number path, so it
+  // could not find items beyond the first page.)
+  const allItems = await fetchAllItems(project.id, env, child);
+
+  let match;
   if (itemRef.kind === "id") {
-    // Direct item node ID lookup
-    const itemPayload = await ghGraphql(GET_PROJECT_ITEM, {
-      projectId: project.id,
-      itemId: itemRef.value,
-    }, env, child);
-    const item = itemPayload?.data?.node?.item;
-    if (!item) {
+    match = allItems.find(
+      (it) => it.id === itemRef.value && it.content?.repository?.nameWithOwner === repo,
+    );
+    if (!match) {
       throw Object.assign(
-        new Error(`Item "${itemRef.value}" not found in project "${project.title}"`),
+        new Error(`Item "${itemRef.value}" not found in project "${project.title}" for repo "${repo}"`),
         { code: "ITEM_NOT_FOUND" },
       );
     }
-    itemId = item.id;
-    const fvs = item.fieldValues?.nodes ?? [];
-    for (const fv of fvs) {
-      if (fv && fv.field && fv.field.name === "Status") {
-        previousColumn = fv.name;
-        break;
-      }
-    }
-    if (item.content) {
-      if (item.content.__typename === "Issue") {
-        issueNumber = item.content.number;
-      } else {
-        prNumber = item.content.number;
-      }
-    }
   } else {
-    // Look up by issue/PR number in the project
-    const itemsPayload = await ghGraphql(GET_PROJECT_ITEMS_BY_CONTENT, {
-      projectId: project.id,
-    }, env, child);
-    const items = itemsPayload?.data?.node?.items?.nodes ?? [];
-
-    // Filter by matching repo exactly and item number (when known)
-    const matchingItems = items.filter((it) => {
-      if (!it.content) return false;
-      const repoMatch = it.content.repository?.nameWithOwner === repo;
-      if (itemRef.kind === "number") {
-        return repoMatch && it.content.number === itemRef.value;
-      }
-      return repoMatch;
-    });
-
-    if (matchingItems.length === 0) {
+    match = allItems.find(
+      (it) =>
+        it.content &&
+        it.content.repository?.nameWithOwner === repo &&
+        it.content.number === itemRef.value,
+    );
+    if (!match) {
       throw Object.assign(
         new Error(`Item #${itemRef.value} not found in project "${project.title}" for repo "${repo}"`),
         { code: "ITEM_NOT_FOUND" },
       );
     }
+  }
 
-    // Use the first match (by position order)
-    const match = matchingItems[0];
-    itemId = match.id;
-    const fvs = match.fieldValues?.nodes ?? [];
-    for (const fv of fvs) {
-      if (fv && fv.field && fv.field.name === "Status") {
-        previousColumn = fv.name;
-        break;
-      }
-    }
-    if (match.content) {
-      if (match.content.__typename === "Issue") {
-        issueNumber = match.content.number;
-      } else {
-        prNumber = match.content.number;
-      }
+  const itemId = match.id;
+  const previousColumn = statusOf(match);
+  let issueNumber = null;
+  let prNumber = null;
+  if (match.content) {
+    if (match.content.__typename === "PullRequest") {
+      prNumber = match.content.number;
+    } else {
+      issueNumber = match.content.number;
     }
   }
 
@@ -520,7 +519,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;

package/scripts/projects/reorder-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 reorder --repo <owner/name> --project <number|id> --item <number|node-id> [--after <number|node-id>]
@@ -40,62 +41,79 @@ Exit codes:
 `.trim();
 
 const SUBCOMMANDS = new Set(["move-to-top", "move-after", "order"]);
-const VALID_ARGS = new Set(["--repo", "--project", "--item", "--after", "--dry-run", "--help", "-h"]);
 
-function parseArgs(argv) {
+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;
+  };
+
   const args = { _positional: [] };
-  let i = 0;
+  let rest = argv;
 
-  // Optional leading positional subcommand.
   if (argv.length > 0 && SUBCOMMANDS.has(argv[0])) {
     args._subcommand = argv[0];
-    i = 1;
-  }
+    rest = argv.slice(1);
+  }
+
+  const { tokens } = parseArgs({
+    args: [...rest],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      item: { type: "string" },
+      after: { type: "string" },
+      "dry-run": { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
 
-  for (; i < argv.length; i++) {
-    const arg = argv[i];
-    if (!arg.startsWith("-")) {
-      // Positional ref (only meaningful with a subcommand).
-      args._positional.push(arg);
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      args._positional.push(token.value);
       continue;
     }
-    if (!VALID_ARGS.has(arg)) {
-      throw Object.assign(
-        new Error(`Unknown flag: ${arg}`),
-        { code: "INVALID_ARGS", usage: USAGE },
-      );
+    if (token.kind !== "option") {
+      continue;
     }
-    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 or node ID)"), { code: "INVALID_ITEM" });
-      }
-      args.item = argv[++i];
-    } else if (arg === "--after") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--after requires a value (number or node ID)"), { code: "INVALID_AFTER" });
-      }
-      args.after = argv[++i];
-    } else if (arg === "--dry-run") {
-      args.dryRun = true;
-    } else if (arg === "--help" || arg === "-h") {
-      args.help = true;
-    } else {
-      throw Object.assign(new Error(`Unexpected argument: ${arg}`), { code: "INVALID_ARGS", usage: USAGE });
+    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":
+        args.project = requireValue(token, "--project requires a value (number or node ID)");
+        break;
+      case "item":
+        args.item = requireValue(token, "--item requires a value (number or node ID)");
+        break;
+      case "after":
+        args.after = requireValue(token, "--after requires a value (number or node ID)");
+        break;
+      case "dry-run":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.dryRun = true;
+        break;
+      default:
+        throw parseError(`Unknown flag: ${token.rawName}`);
     }
   }
   return args;
 }
-
 // ── Validation ───────────────────────────────────────────────────────────
 
 const OWNER_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
@@ -747,7 +765,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;

package/scripts/projects/sync-item-status.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { runChild as _runChild } from "../_cli-primitives.mjs";
+import { syncBoardStatus } from "@dev-loops/core/loop/queue-board-sync";
+import { parseArgs } from "node:util";
+
+const USAGE = `Usage: dev-loops project sync-status --repo <owner/name> --item <number> --to-column <name>
+
+Sync a queued issue/PR's board Status column on a dev-loop transition (e.g.
+PR opened → "In Progress", merged → "Done"). Resolves the board from .devloops
+and uses local gh auth.
+
+This command is BEST-EFFORT and NON-FATAL: a board that is not configured, an
+item that is not on the board, or any GitHub API failure exits 0 with a JSON
+result describing the skip/failure. It never fails the caller.
+
+Options:
+  --repo <owner/name>     Required. Repository to scope the project search.
+  --item <number>         Required. Linked issue/PR number (positive integer).
+  --to-column <name>      Required. Target Status column (e.g. "In Progress", "Done").
+  --help, -h              Show this help.
+
+Output (stdout):
+  JSON: the syncBoardStatus result, e.g.
+    { ok: true, skipped: false, result: { item: { newColumn } } }
+    { ok: true, skipped: true, reason: "board not configured" }
+
+Exit codes:
+  0 — always on a parsed command (best-effort sync; skips/failures are reported in JSON)
+  1 — usage or argument error
+`.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, usage: USAGE });
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      item: { type: "string" },
+      "to-column": { 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 (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 "item":
+        args.item = requireValue(token, "--item requires a value (positive integer)", "INVALID_ITEM");
+        break;
+      case "to-column":
+        args.toColumn = requireValue(token, "--to-column requires a value", "INVALID_COLUMN");
+        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])?$/;
+
+function validateRepo(repo) {
+  if (!repo || typeof repo !== "string") {
+    throw Object.assign(new Error("--repo is required"), { code: "INVALID_REPO" });
+  }
+  const trimmed = repo.trim();
+  if (trimmed !== repo) {
+    throw Object.assign(
+      new Error(`--repo must not have leading/trailing whitespace, got "${repo}"`),
+      { 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 parseItemNumber(raw) {
+  if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
+    throw Object.assign(new Error("--item is required"), { code: "INVALID_ITEM" });
+  }
+  const trimmed = raw.trim();
+  const asNum = Number(trimmed);
+  if (Number.isInteger(asNum) && asNum > 0 && String(asNum) === trimmed) {
+    return asNum;
+  }
+  throw Object.assign(new Error(`--item must be a positive integer, got "${raw}"`), { code: "INVALID_ITEM" });
+}
+
+// ── Main logic ──────────────────────────────────────────────────────────
+
+async function main(args, { env = process.env, runChild, cwd = process.cwd() } = {}) {
+  const child = runChild ?? _runChild;
+  const repo = validateRepo(args.repo);
+  const item = parseItemNumber(args.item);
+  const toColumn = (args.toColumn ?? "").trim();
+  if (!toColumn) {
+    throw Object.assign(new Error("--to-column is required"), { code: "INVALID_COLUMN" });
+  }
+
+  // syncBoardStatus owns the fail-open contract: a not-configured board, an
+  // item not on the board, or any gh/API failure resolves to a skipped/failure
+  // result rather than throwing. We surface that result verbatim and exit 0.
+  return syncBoardStatus(repo, cwd, item, toColumn, env, { runChild: child });
+}
+
+// ── 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);
+    // Help is a success path: clear any pre-existing non-zero process.exitCode
+    // so help output can't inherit a leaked failure code.
+    process.exitCode = 0;
+    return;
+  }
+
+  // Argument validation errors (bad --repo / --item / missing --to-column) are
+  // genuine usage errors → exit 1. Everything past validation is best-effort:
+  // syncBoardStatus never throws for board/API conditions, so a parsed command
+  // always reports its result on stdout and exits 0.
+  let result;
+  try {
+    result = await main(args, { env, cwd });
+  } catch (err) {
+    if (err.code === "INVALID_REPO" || err.code === "INVALID_ITEM" || err.code === "INVALID_COLUMN" || err.code === "INVALID_ARGS") {
+      stderr.write(`${formatCliError(err)}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    // Defensive: any unexpected error stays best-effort/non-fatal — report it
+    // as a skip and keep exit 0 so it never blocks the PR/merge caller.
+    stdout.write(JSON.stringify({ ok: true, skipped: true, reason: err.message ?? "board sync failed" }) + "\n");
+    // Explicitly assert success: a pre-existing non-zero process.exitCode from a
+    // long-lived caller must not leak through this best-effort path.
+    process.exitCode = 0;
+    return;
+  }
+  stdout.write(JSON.stringify(result) + "\n");
+  // Best-effort contract: a parsed command always reports success. Explicitly
+  // clear any pre-existing non-zero process.exitCode so it cannot leak.
+  process.exitCode = 0;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    // Best-effort: even an unexpected failure must not fail the caller.
+    process.stdout.write(JSON.stringify({ ok: true, skipped: true, reason: error.message ?? "board sync failed" }) + "\n");
+    // Force the documented exit-0 contract even on this last-resort path.
+    process.exitCode = 0;
+  });
+}
+
+export { main, parseCliArgs, parseItemNumber, runCli };