dev-loops 0.2.6 → 0.3.0

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

@@ -1,21 +1,37 @@
 #!/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>]
+const USAGE = `Usage:
+  dev-loops project reorder --repo <owner/name> --project <number|id> --item <number|node-id> [--after <number|node-id>]
+  dev-loops project reorder move-to-top <ref> --repo <owner/name> --project <number|id>
+  dev-loops project reorder move-after <ref> <after-ref> --repo <owner/name> --project <number|id>
+  dev-loops project reorder order <ref1> <ref2> ... --repo <owner/name> --project <number|id>
 
-Reorder a GitHub Projects V2 item by board position via updateProjectV2ItemPosition.
-Moves item to top when no --after is provided, or after the specified item.
+Reorder GitHub Projects V2 items by board position via updateProjectV2ItemPosition.
+
+Forms:
+  (no subcommand)   Flag form. Moves --item to top, or after --after when provided.
+  move-to-top <ref> Move <ref> to the first position in its current Status column.
+  move-after <ref> <after-ref>
+                    Move <ref> immediately after <after-ref>.
+  order <ref1> ...  Set explicit ordering: ref1 first, ref2 after ref1, and so on.
+
+A <ref> is an issue/PR number OR a project item node ID. Works for both issues and PRs.
 
 Options:
   --repo <owner/name>         Required. Repository to scope the project search.
   --project <number|id>       Required. Project number (integer) or node ID.
-  --item <number|node-id>     Required. Item to reorder: issue/PR number, or project item node ID.
-  --after <number|node-id>    Position after this item. When omitted, move to top.
+  --item <number|node-id>     Flag form: item to reorder.
+  --after <number|node-id>    Flag form: position after this item. When omitted, move to top.
+  --dry-run                   Print the intended GraphQL mutation(s) without executing.
   --help, -h                  Show this help.
 
 Output (stdout):
-  JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, position }, after: { itemId, issueNumber, prNumber } | null }
+  JSON. Move/move-to-top: { ok, item, after_ref|null, before, after }.
+        order: { ok, moves: [...], before, after }.
+        dry-run: { ok, dryRun: true, mutations: [{ query, variables }], before }.
 
 Exit codes:
   0 — success
@@ -24,47 +40,80 @@ Exit codes:
   3 — project, item, or after-item not found
 `.trim();
 
-const VALID_ARGS = new Set(["--repo", "--project", "--item", "--after", "--help", "-h"]);
+const SUBCOMMANDS = new Set(["move-to-top", "move-after", "order"]);
 
-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 },
-      );
+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);
     }
-    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 === "--help" || arg === "-h") {
-      args.help = true;
-    } else {
-      throw Object.assign(new Error(`Unexpected argument: ${arg}`), { code: "INVALID_ARGS", usage: USAGE });
+    return v;
+  };
+
+  const args = { _positional: [] };
+  let rest = argv;
+
+  if (argv.length > 0 && SUBCOMMANDS.has(argv[0])) {
+    args._subcommand = argv[0];
+    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 (const token of tokens) {
+    if (token.kind === "positional") {
+      args._positional.push(token.value);
+      continue;
+    }
+    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 "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])?$/;
@@ -296,6 +345,94 @@ async function listAllProjects(login, kind, env, runChild) {
   return projects;
 }
 
+// ── Fetch all project items (paginated, position order) ────────────────
+
+async function fetchAllItems(projectId, env, runChild) {
+  const allItems = [];
+  let after = null;
+  while (true) {
+    const vars = { projectId };
+    if (after) vars.after = after;
+    const itemsPayload = await ghGraphql(GET_PROJECT_ITEMS_BY_CONTENT, vars, env, runChild);
+    const connection = itemsPayload?.data?.node?.items;
+    const nodes = connection?.nodes ?? [];
+    allItems.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 allItems;
+}
+
+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;
+}
+
+function describeItem(node) {
+  return {
+    itemId: node.id,
+    issueNumber: node.content?.__typename === "Issue" ? node.content.number : null,
+    prNumber: node.content?.__typename === "PullRequest" ? node.content.number : null,
+    status: statusOf(node),
+  };
+}
+
+// Build a diff-friendly snapshot of items in `repo` (optionally a single Status
+// column), in board position order, from a pre-fetched item list.
+function snapshotFromItems(items, repo, statusFilter) {
+  return items
+    .filter((it) => it.content && it.content.repository?.nameWithOwner === repo)
+    .filter((it) => (statusFilter == null ? true : statusOf(it) === statusFilter))
+    .map(describeItem);
+}
+
+async function snapshotOrder(projectId, repo, statusFilter, env, runChild) {
+  const items = await fetchAllItems(projectId, env, runChild);
+  return snapshotFromItems(items, repo, statusFilter);
+}
+
+// Resolve a ref (number or item node ID) against a pre-fetched item list,
+// enforcing the same repo scope for BOTH number and id refs so a cross-project
+// ref fails closed with ITEM_NOT_FOUND.
+function resolveFromItems(items, itemRef, repo) {
+  let match;
+  if (itemRef.kind === "id") {
+    match = items.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 for repo "${repo}"`),
+        { code: "ITEM_NOT_FOUND" },
+      );
+    }
+  } else {
+    match = items.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 for repo "${repo}"`),
+        { code: "ITEM_NOT_FOUND" },
+      );
+    }
+  }
+  return describeItem(match);
+}
+
 // ── Resolve an item in a project by reference (number or node ID) ──────
 
 async function resolveProjectItem(projectId, itemRef, owner, repoName, repo, env, runChild) {
@@ -335,25 +472,7 @@ async function resolveProjectItem(projectId, itemRef, owner, repoName, repo, env
   } else {
     // Look up by issue/PR number in the project (paginated)
     const targetNumber = itemRef.value;
-    let allItems = [];
-    let after = null;
-    while (true) {
-      const vars = { projectId };
-      if (after) vars.after = after;
-      const itemsPayload = await ghGraphql(GET_PROJECT_ITEMS_BY_CONTENT, vars, env, runChild);
-      const connection = itemsPayload?.data?.node?.items;
-      const nodes = connection?.nodes ?? [];
-      allItems.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;
-    }
+    const allItems = await fetchAllItems(projectId, env, runChild);
 
     // Filter by matching repo AND number exactly
     const matchingItems = allItems.filter((it) => {
@@ -400,70 +519,68 @@ function classifyExitCode(err) {
   return 2;
 }
 
-// ── Main logic ──────────────────────────────────────────────────────────
-
-async function main(args, { env = process.env, runChild } = {}) {
-  const child = runChild ?? _runChild;
-  const repo = validateRepo(args.repo);
-  const [owner, repoName] = repo.split("/");
-  const projectRef = parseProjectRef(args.project);
-  const itemRef = parseItemRef(args.item);
-
-  // --after is optional
-  let afterRef = null;
-  if (args.after !== undefined) {
-    afterRef = parseItemRef(args.after);
-  }
-
-  // 1. Resolve owner
-  const { id: ownerId, kind: ownerKind } = await resolveOwner(owner, env, child);
+// ── Resolve owner + project (shared) ──────────────────────────────────────
 
-  // 2. Resolve project
+async function resolveProject(owner, projectRef, env, child) {
+  const { kind: ownerKind } = await resolveOwner(owner, env, child);
   const projects = await listAllProjects(owner, ownerKind, env, child);
-  let project;
-  if (projectRef.kind === "id") {
-    project = projects.find((p) => p.id === projectRef.value);
-  } else {
-    project = projects.find((p) => p.number === projectRef.value);
-  }
+  const project = projectRef.kind === "id"
+    ? projects.find((p) => p.id === projectRef.value)
+    : projects.find((p) => p.number === projectRef.value);
   if (!project) {
     throw Object.assign(
       new Error(`Project ${projectRef.kind === "id" ? `"${projectRef.value}"` : `number ${projectRef.value}`} not found under owner "${owner}"`),
       { code: "PROJECT_NOT_FOUND" },
     );
   }
+  return project;
+}
+
+function executePosition(projectId, itemId, afterId) {
+  return {
+    query: UPDATE_ITEM_POSITION,
+    variables: afterId
+      ? { projectId, itemId, afterId }
+      : { projectId, itemId },
+  };
+}
+
+// ── Legacy flag form: --item [--after] ────────────────────────────────────
+
+async function mainFlagForm(args, { env, child, repo, owner, repoName, project }) {
+  const itemRef = parseItemRef(args.item);
+  let afterRef = null;
+  if (args.after !== undefined) afterRef = parseItemRef(args.after);
 
-  // 3. Resolve the item to move
   const item = await resolveProjectItem(project.id, itemRef, owner, repoName, repo, env, child);
 
-  // 4. Resolve the after-item (if provided)
   let afterItem = null;
   if (afterRef) {
     afterItem = await resolveProjectItem(project.id, afterRef, owner, repoName, repo, env, child);
-
-    // Fail closed: cannot reorder after itself
     if (afterItem.itemId === item.itemId) {
-      throw Object.assign(
-        new Error("Cannot reorder an item after itself"),
-        { code: "INVALID_AFTER" },
-      );
+      throw Object.assign(new Error("Cannot reorder an item after itself"), { code: "INVALID_AFTER" });
     }
   }
 
-  // 5. Execute reorder mutation
-  const mutationVars = {
-    projectId: project.id,
-    itemId: item.itemId,
-    afterId: afterItem ? afterItem.itemId : null,
-  };
-
-  const mutationPayload = await ghGraphql(UPDATE_ITEM_POSITION, mutationVars, env, child);
+  const mutation = executePosition(project.id, item.itemId, afterItem ? afterItem.itemId : null);
+
+  if (args.dryRun) {
+    // Include the before snapshot for parity with the subcommand dry-run form.
+    const before = await snapshotOrder(project.id, repo, item.status ?? null, env, child);
+    return {
+      ok: true,
+      dryRun: true,
+      mutations: [mutation],
+      before,
+    };
+  }
 
+  const mutationPayload = await ghGraphql(mutation.query, mutation.variables, env, child);
   if (!mutationPayload?.data?.updateProjectV2ItemPosition) {
     throw Object.assign(new Error("Failed to reorder item"), { code: "MUTATION_FAILED" });
   }
 
-  const result = {
+  return {
     ok: true,
     item: {
       itemId: item.itemId,
@@ -473,15 +590,174 @@ async function main(args, { env = process.env, runChild } = {}) {
       position: afterItem ? "after" : "top",
     },
     after: afterItem
-      ? {
-          itemId: afterItem.itemId,
-          issueNumber: afterItem.issueNumber,
-          prNumber: afterItem.prNumber,
-        }
+      ? { itemId: afterItem.itemId, issueNumber: afterItem.issueNumber, prNumber: afterItem.prNumber }
       : null,
   };
+}
+
+// ── Subcommand forms: move-to-top / move-after / order ────────────────────
 
-  return result;
+function requirePositionals(subcommand, positional) {
+  if (subcommand === "move-to-top") {
+    if (positional.length !== 1) {
+      throw Object.assign(new Error("move-to-top requires exactly one <ref>"), { code: "INVALID_ARGS", usage: USAGE });
+    }
+  } else if (subcommand === "move-after") {
+    if (positional.length !== 2) {
+      throw Object.assign(new Error("move-after requires <ref> <after-ref>"), { code: "INVALID_ARGS", usage: USAGE });
+    }
+  } else if (subcommand === "order") {
+    if (positional.length < 2) {
+      throw Object.assign(new Error("order requires at least two <ref> values"), { code: "INVALID_ARGS", usage: USAGE });
+    }
+  }
+}
+
+async function mainSubcommand(args, { env, child, repo, project }) {
+  const subcommand = args._subcommand;
+  const positional = args._positional ?? [];
+  requirePositionals(subcommand, positional);
+
+  // Fetch the board item list ONCE, then resolve every ref (number or id) from
+  // that single list — avoids N full-board scans for N refs and enforces the
+  // same repo scope for both ref kinds (cross-project refs fail closed).
+  const items = await fetchAllItems(project.id, env, child);
+
+  // Resolve all referenced items up-front (fail closed before any mutation).
+  const refs = positional.map((p) => parseItemRef(p));
+  const resolved = refs.map((ref) => resolveFromItems(items, ref, repo));
+
+  // Reordering positions within a single Status column. The before/after snapshot is scoped
+  // to one column, and a cross-column move plan is misleading/invalid — so fail closed unless
+  // every resolved ref shares the first ref's Status (multi-ref subcommands only).
+  if (resolved.length > 1) {
+    const primaryStatus = resolved[0].status ?? null;
+    const offender = resolved.find((it) => (it.status ?? null) !== primaryStatus);
+    if (offender) {
+      throw Object.assign(
+        new Error(
+          `All reordered items must be in the same Status column as the first item (${primaryStatus ?? "(none)"}); ` +
+            `${offender.itemId} is in ${offender.status ?? "(none)"}.`,
+        ),
+        { code: "MIXED_STATUS" },
+      );
+    }
+  }
+
+  // Build the ordered list of position moves, each { item, afterItem|null }.
+  let plan;
+  if (subcommand === "move-to-top") {
+    plan = [{ item: resolved[0], afterItem: null }];
+  } else if (subcommand === "move-after") {
+    const [item, afterItem] = resolved;
+    if (item.itemId === afterItem.itemId) {
+      throw Object.assign(new Error("Cannot reorder an item after itself"), { code: "INVALID_AFTER" });
+    }
+    plan = [{ item, afterItem }];
+  } else {
+    // order: ref1 to top, then each subsequent ref after its predecessor.
+    plan = resolved.map((item, idx) => ({
+      item,
+      afterItem: idx === 0 ? null : resolved[idx - 1],
+    }));
+  }
+
+  const mutations = plan.map((m) => executePosition(project.id, m.item.itemId, m.afterItem ? m.afterItem.itemId : null));
+
+  // Status column for the diff snapshot: use the primary moved item's status.
+  // Reuse the already-fetched list for the before-snapshot (no extra fetch).
+  const statusFilter = resolved[0].status ?? null;
+  const before = snapshotFromItems(items, repo, statusFilter);
+
+  if (args.dryRun) {
+    return { ok: true, dryRun: true, mutations, before };
+  }
+
+  // NOTE: `order` applies N sequential position mutations and is NOT atomic. A
+  // mid-sequence failure leaves the board partially reordered; re-running the
+  // same `order` command is idempotent and is the supported recovery path. The
+  // thrown error reports how many moves were applied before failing.
+  for (let i = 0; i < mutations.length; i++) {
+    const mutation = mutations[i];
+    let payload;
+    try {
+      payload = await ghGraphql(mutation.query, mutation.variables, env, child);
+    } catch (err) {
+      if (subcommand === "order") {
+        err.message = `${err.message} (order partially applied: ${i} of ${mutations.length} moves completed; re-run the same order command to recover)`;
+        err.appliedMoves = i;
+        err.totalMoves = mutations.length;
+      }
+      throw err;
+    }
+    if (!payload?.data?.updateProjectV2ItemPosition) {
+      const detail = subcommand === "order"
+        ? ` (order partially applied: ${i} of ${mutations.length} moves completed; re-run the same order command to recover)`
+        : "";
+      throw Object.assign(new Error(`Failed to reorder item${detail}`), {
+        code: "MUTATION_FAILED",
+        ...(subcommand === "order" ? { appliedMoves: i, totalMoves: mutations.length } : {}),
+      });
+    }
+  }
+
+  const after = await snapshotOrder(project.id, repo, statusFilter, env, child);
+
+  const moves = plan.map((m) => ({
+    itemId: m.item.itemId,
+    issueNumber: m.item.issueNumber,
+    prNumber: m.item.prNumber,
+    status: m.item.status,
+    position: m.afterItem ? "after" : "top",
+    afterId: m.afterItem ? m.afterItem.itemId : null,
+  }));
+
+  if (subcommand === "order") {
+    return { ok: true, moves, before, after };
+  }
+
+  // move-to-top / move-after: single move, richer shape.
+  const m = plan[0];
+  return {
+    ok: true,
+    item: {
+      itemId: m.item.itemId,
+      issueNumber: m.item.issueNumber,
+      prNumber: m.item.prNumber,
+      status: m.item.status,
+      position: m.afterItem ? "after" : "top",
+    },
+    after_ref: m.afterItem
+      ? { itemId: m.afterItem.itemId, issueNumber: m.afterItem.issueNumber, prNumber: m.afterItem.prNumber }
+      : null,
+    before,
+    after,
+  };
+}
+
+// ── Main logic ──────────────────────────────────────────────────────────
+
+async function main(args, { env = process.env, runChild } = {}) {
+  const child = runChild ?? _runChild;
+  const repo = validateRepo(args.repo);
+  const [owner, repoName] = repo.split("/");
+  const projectRef = parseProjectRef(args.project);
+
+  // Fail closed: the legacy flag form takes no positional arguments. A stray
+  // token (e.g. `reorder 630 --item ...`) must not be silently ignored.
+  if (!args._subcommand && (args._positional?.length ?? 0) > 0) {
+    throw Object.assign(
+      new Error(`Unexpected argument: ${args._positional[0]}`),
+      { code: "INVALID_ARGS", usage: USAGE },
+    );
+  }
+
+  const project = await resolveProject(owner, projectRef, env, child);
+
+  if (args._subcommand) {
+    return mainSubcommand(args, { env, child, repo, project });
+  }
+  return mainFlagForm(args, { env, child, repo, owner, repoName, project });
 }
 
 // ── CLI entrypoint ──────────────────────────────────────────────────────
@@ -489,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;