@dev-loops/core 0.7.1 → 0.8.0

package/src/projects/move-queue-item.mjs

@@ -0,0 +1,394 @@
+import { runChild as _runChild } from "../cli/primitives.mjs";
+import { parseJsonText } from "../github/review-threads.mjs";
+import { resolveProjectSelector, findProject, parseItemRef } from "./resolve-project.mjs";
+
+// ── 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;
+}
+
+// ── 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_FIELDS = [
+  "query($projectId:ID!, $after:String) {",
+  "  node(id:$projectId) {",
+  "    ... on ProjectV2 {",
+  "      fields(first:50, after:$after) {",
+  "        pageInfo { hasNextPage endCursor }",
+  "        nodes {",
+  "          ... on ProjectV2SingleSelectField {",
+  "            id name",
+  "            options { id name }",
+  "          }",
+  "        }",
+  "      }",
+  "    }",
+  "  }",
+  "}"
+].join("\n");
+
+const GET_PROJECT_ITEMS_BY_CONTENT = [
+  "query($projectId:ID!, $after:String) {",
+  "  node(id:$projectId) {",
+  "    ... on ProjectV2 {",
+  "      items(first:100, after:$after, orderBy:{field:POSITION, direction:ASC}) {",
+  "        pageInfo { hasNextPage endCursor }",
+  "        nodes {",
+  "          id",
+  "          fieldValues(first:20) {",
+  "            nodes {",
+  "              ... on ProjectV2ItemFieldSingleSelectValue {",
+  "                field { ... on ProjectV2SingleSelectField { id name } }",
+  "                name",
+  "              }",
+  "            }",
+  "          }",
+  "          content {",
+  "            ... on Issue { __typename number repository { nameWithOwner } }",
+  "            ... on PullRequest { __typename number repository { nameWithOwner } }",
+  "          }",
+  "        }",
+  "      }",
+  "    }",
+  "  }",
+  "}"
+].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}}) {",
+  "    projectV2Item {",
+  "      id",
+  "    }",
+  "  }",
+  "}"
+].join("\n");
+
+// ── Owner 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" },
+  );
+}
+
+// ── Paginated project listing ────────────────────────────────────────────
+
+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 is true but endCursor is missing"),
+        { code: "GH_API_ERROR" },
+      );
+    }
+    after = pageInfo.endCursor;
+  }
+  return projects;
+}
+
+// ── Paginated field listing ──────────────────────────────────────────────
+
+async function listAllFields(projectId, env, runChild) {
+  const fields = [];
+  let after = null;
+  while (true) {
+    const vars = { projectId };
+    if (after) vars.after = after;
+    const payload = await ghGraphql(GET_PROJECT_FIELDS, vars, env, runChild);
+    const connection = payload?.data?.node?.fields;
+    const nodes = connection?.nodes ?? [];
+    fields.push(...nodes);
+    const pageInfo = connection?.pageInfo ?? {};
+    if (!pageInfo.hasNextPage) break;
+    if (!pageInfo.endCursor) {
+      throw Object.assign(
+        new Error("Invalid fields payload: hasNextPage is true but endCursor is missing"),
+        { code: "GH_API_ERROR" },
+      );
+    }
+    after = pageInfo.endCursor;
+  }
+  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) {
+  if (err.code === "INVALID_REPO" || err.code === "INVALID_PROJECT" || err.code === "INVALID_ITEM" ||
+      err.code === "INVALID_COLUMN" || err.code === "INVALID_ARGS") return 1;
+  if (err.code === "PROJECT_NOT_FOUND" || err.code === "FIELD_NOT_FOUND" || err.code === "COLUMN_NOT_FOUND" ||
+      err.code === "ITEM_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, repoName] = repo.split("/");
+  const selector = resolveProjectSelector(args);
+  const itemRef = parseItemRef(args.item);
+  const toColumn = (args.toColumn ?? "").trim();
+  if (!toColumn) {
+    throw Object.assign(new Error("--to-column is required"), { code: "INVALID_COLUMN" });
+  }
+
+  // 1. Resolve owner.
+  // URI refs encode owner+kind directly; skip the API round-trip for owner resolution.
+  const projectOwner = selector.projectRef?.kind === "uri" ? selector.projectRef.owner : owner;
+  const ownerKind = selector.projectRef?.kind === "uri"
+    ? selector.projectRef.ownerKind
+    : (await resolveOwner(owner, env, child)).kind;
+
+  // 2. Resolve project
+  const projects = await listAllProjects(projectOwner, ownerKind, env, child);
+  const project = findProject(projects, selector, projectOwner);
+
+  // 3. Resolve Status field and target column
+  const fieldNodes = await listAllFields(project.id, env, child);
+  const statusField = fieldNodes.find((f) => f.name === "Status" && f.options);
+  if (!statusField) {
+    throw Object.assign(
+      new Error(`Status field not found in project "${project.title}" (number ${project.number})`),
+      { code: "FIELD_NOT_FOUND" },
+    );
+  }
+
+  const targetOption = statusField.options.find((o) => o.name === toColumn);
+  if (!targetOption) {
+    const available = statusField.options.map((o) => o.name).join(", ");
+    throw Object.assign(
+      new Error(`Column "${toColumn}" not found in Status field. Available: ${available}`),
+      { code: "COLUMN_NOT_FOUND" },
+    );
+  }
+
+  // 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") {
+    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}" for repo "${repo}"`),
+        { code: "ITEM_NOT_FOUND" },
+      );
+    }
+  } else {
+    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" },
+      );
+    }
+  }
+
+  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;
+    }
+  }
+
+  // 5. No-op if already at target column
+  if (previousColumn === toColumn) {
+    return {
+      ok: true,
+      item: {
+        itemId,
+        issueNumber,
+        prNumber,
+        previousColumn,
+        newColumn: toColumn,
+        unchanged: true,
+      },
+    };
+  }
+
+  // 6. Update Status via mutation
+  const updatePayload = await ghGraphql(UPDATE_ITEM_FIELD, {
+    projectId: project.id,
+    itemId,
+    fieldId: statusField.id,
+    optionId: targetOption.id,
+  }, env, child);
+
+  const updated = updatePayload?.data?.updateProjectV2ItemFieldValue?.projectV2Item;
+  if (!updated) {
+    throw Object.assign(new Error("Failed to update item field value"), { code: "MUTATION_FAILED" });
+  }
+
+  return {
+    ok: true,
+    item: {
+      itemId,
+      issueNumber,
+      prNumber,
+      previousColumn,
+      newColumn: toColumn,
+      unchanged: false,
+    },
+  };
+}
+
+export { main, classifyExitCode };

package/src/projects/resolve-project.mjs

@@ -0,0 +1,183 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+// 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;
+}
+
+// Shape of the node IDs this tooling actually receives from the Projects V2
+// API (e.g. "PVT_…", "PVTI_…", "I_…", "PR_…"): a type prefix, "_", then a
+// base64url-ish payload. Intentionally narrower than an arbitrary GraphQL
+// global node ID (which is opaque and carries no guaranteed prefix_payload
+// shape). The payload alphabet includes "-" and "_" (base64url), which a
+// plain [A-Za-z0-9_] class rejects — the exact shape that broke real PVTI_
+// ids containing a hyphen.
+const NODE_ID_RE = /^[A-Za-z]+_[A-Za-z0-9_-]+$/;
+
+// Parse a --project value into { kind:"id"|"number"|"uri", ... }. Throws
+// INVALID_PROJECT on empty/malformed input (bare "0" is rejected too).
+//
+// Supported forms:
+//   <n>           positive integer  → { kind:"number", value:<n> }
+//   <NODE_ID>     project node ID (prefix_payload shape) → { kind:"id", value:<NODE_ID> }
+//   https://github.com/users/<login>/projects/<n>
+//   https://github.com/orgs/<login>/projects/<n>
+//                 board URI        → { kind:"uri", number:<n>, owner:<login>, ownerKind:"user"|"org" }
+
+// GitHub Projects V2 board URI pattern (user- or org-scoped boards).
+const BOARD_URI_RE = /^https:\/\/github\.com\/(users|orgs)\/([A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)\/projects\/(\d+)$/;
+
+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();
+
+  // Board URI: https://github.com/users/<login>/projects/<n>
+  //            https://github.com/orgs/<login>/projects/<n>
+  const uriMatch = BOARD_URI_RE.exec(trimmed);
+  if (uriMatch) {
+    const ownerKind = uriMatch[1] === "users" ? "user" : "org";
+    const owner = uriMatch[2];
+    const number = Number(uriMatch[3]);
+    if (number < 1) {
+      throw Object.assign(
+        new Error(`--project board URI must reference a positive project number, got "${raw}"`),
+        { code: "INVALID_PROJECT" },
+      );
+    }
+    return { kind: "uri", number, owner, ownerKind };
+  }
+
+  const asNum = Number(trimmed);
+  if (Number.isInteger(asNum) && asNum > 0 && String(asNum) === trimmed) {
+    return { kind: "number", value: asNum };
+  }
+  // Reject bare "0" — valid node ID character but not a meaningful project reference
+  if (trimmed === "0") {
+    throw Object.assign(
+      new Error(`--project must be a positive integer, a node ID, or a board URI, got "${raw}"`),
+      { code: "INVALID_PROJECT" },
+    );
+  }
+  if (NODE_ID_RE.test(trimmed)) {
+    return { kind: "id", value: trimmed };
+  }
+  throw Object.assign(
+    new Error(`--project must be a positive integer, a node ID, or a board URI, got "${raw}"`),
+    { code: "INVALID_PROJECT" },
+  );
+}
+
+// Parse an item ref into { kind:"id"|"number" }. Throws INVALID_ITEM on
+// empty/malformed input (bare "0" is rejected too). Shared by every item-ref
+// consumer (move-queue-item --item; reorder-queue-item --item/--after/
+// positionals) so the accepted node-ID alphabet is defined once. `label`
+// names the flag/argument in error messages.
+//
+// Supported forms:
+//   <n>           positive integer → { kind:"number", value:<n> }
+//   <NODE_ID>     item node ID      → { kind:"id", value:<NODE_ID> }
+function parseItemRef(raw, label = "--item") {
+  if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
+    throw Object.assign(new Error(`${label} is required`), { code: "INVALID_ITEM" });
+  }
+  const trimmed = raw.trim();
+  const asNum = Number(trimmed);
+  if (Number.isInteger(asNum) && asNum > 0 && String(asNum) === trimmed) {
+    return { kind: "number", value: asNum };
+  }
+  if (trimmed === "0") {
+    throw Object.assign(new Error(`${label} must be a positive integer or an item node ID, got "${raw}"`), { code: "INVALID_ITEM" });
+  }
+  if (NODE_ID_RE.test(trimmed)) {
+    return { kind: "id", value: trimmed };
+  }
+  throw Object.assign(new Error(`${label} must be a positive integer or an item node ID, got "${raw}"`), { code: "INVALID_ITEM" });
+}
+
+// Selector precedence: explicit --project ref wins; else resolve by board title
+// from .devloops (passed as args.projectTitle by runCli). Fail closed if neither.
+function resolveProjectSelector(args) {
+  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 set queue.projectNumber / queue.boardTitle in .devloops)"),
+      { code: "INVALID_PROJECT" },
+    );
+  }
+  return { projectRef, projectTitle };
+}
+
+// Find the project in `projects` matching the resolved selector; throws
+// PROJECT_NOT_FOUND (desc: "<id>" / number N / title "T" / URI number N under "<owner>").
+function findProject(projects, { projectRef, projectTitle }, owner) {
+  let project;
+  if (projectRef) {
+    if (projectRef.kind === "id") {
+      project = projects.find((p) => p.id === projectRef.value);
+    } else if (projectRef.kind === "uri") {
+      project = projects.find((p) => p.number === projectRef.number);
+    } else {
+      project = projects.find((p) => p.number === projectRef.value);
+    }
+  } else {
+    project = projects.find((p) => p.title === projectTitle);
+  }
+  if (!project) {
+    const desc = projectRef
+      ? (projectRef.kind === "id"
+          ? `"${projectRef.value}"`
+          : projectRef.kind === "uri"
+            ? `URI number ${projectRef.number} under "${projectRef.owner}"`
+            : `number ${projectRef.value}`)
+      : `title "${projectTitle}"`;
+    throw Object.assign(
+      new Error(`Project ${desc} not found under owner "${owner}"`),
+      { code: "PROJECT_NOT_FOUND" },
+    );
+  }
+  return project;
+}
+
+// Apply .devloops board settings when --project was not passed. Precedence:
+// explicit --project flag > queue.projectNumber/boardTitle. Mutates args.
+function applyDevloopsBoard(args, cwd) {
+  if (args.project === undefined) {
+    const settings = resolveSettings(cwd);
+    if (settings?.project) args.project = String(settings.project);
+    else if (settings?.title) args.projectTitle = settings.title;
+  }
+}
+
+export { resolveSettings, parseProjectRef, parseItemRef, resolveProjectSelector, findProject, applyDevloopsBoard };