dev-loops 0.7.1 → 0.8.0

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

@@ -4,7 +4,8 @@ import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { resolveProjectSelector, findProject, applyDevloopsBoard } from "./_resolve-project.mjs";
 import { parseArgs } from "node:util";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
-import { loadStateColumnMap, LOGICAL_COLUMN } from "@dev-loops/core/loop/queue-board-sync";
+import { loadStateColumnMap, LOGICAL_COLUMN, nonSuccessBoardColumn } from "@dev-loops/core/loop/queue-board-sync";
+import { decideEnqueueRefinementGate, detectIssueRefinementArtifact } from "@dev-loops/core/loop/issue-refinement-artifact";
 
 const USAGE = `Usage: dev-loops queue add --repo <owner/name> [--project <number|id>] --item <number>
        dev-loops project add … (back-compat alias for "queue add")
@@ -24,10 +25,20 @@ Options:
                               default, honors queue.statusColumns.next_up). Sugar
                               for --column <that column>; cannot be combined with
                               a conflicting --column/--status.
+  --auto                      Headless mode. When an issue targets the pickup
+                              (next_up) column without a refinement artifact
+                              (Acceptance criteria/DoD/linked doc), divert it
+                              to the non-pickup park column instead of failing.
+                              Without --auto, the same case throws
+                              MISSING_REFINEMENT_ARTIFACT.
   --help, -h                  Show this help.
 
 Output (stdout):
-  JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, alreadyPresent } }
+  JSON: { ok: true, item: { itemId, issueNumber, prNumber, status, alreadyPresent },
+          refinement? }
+  refinement (present only when the pickup-column gate ran): either
+    { refined: true } or, on a headless --auto divert,
+    { refined: false, diverted: true, requestedColumn, parkedColumn, reason, missing }.
 
 ${JQ_OUTPUT_USAGE}
 
@@ -36,6 +47,8 @@ Exit codes:
   1 — usage or argument error
   2 — GitHub API error / invalid --jq filter
   3 — project, field, column, or issue/PR not found
+  4 — issue targets the pickup column without a refinement artifact
+      (MISSING_REFINEMENT_ARTIFACT; interactive only, --auto diverts instead)
 `.trim();
 
 function parseCliArgs(argv) {
@@ -58,6 +71,7 @@ function parseCliArgs(argv) {
       column: { type: "string" },
       status: { type: "string" },
       "next-up": { type: "boolean" },
+      auto: { type: "boolean" },
       help: { type: "boolean", short: "h" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
@@ -113,6 +127,12 @@ function parseCliArgs(argv) {
         }
         args.nextUp = true;
         break;
+      case "auto":
+        if (token.value !== undefined) {
+          throw Object.assign(new Error(`Unknown flag: ${token.rawName}=${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
+        }
+        args.auto = true;
+        break;
       default: {
         if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
         throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
@@ -367,6 +387,7 @@ function classifyExitCode(err) {
       err.code === "INVALID_STATUS" || 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" || err.code === "CONTENT_NOT_FOUND") return 3;
+  if (err.code === "MISSING_REFINEMENT_ARTIFACT") return 4;
   return 2;
 }
 
@@ -502,6 +523,67 @@ async function main(args, { env = process.env, runChild, cwd = process.cwd() } =
   let issueNumber = fullResult.__typename === "Issue" ? itemNumber : null;
   let prNumber = fullResult.__typename === "PullRequest" ? itemNumber : null;
 
+  // 5b. Refinement-artifact gate: shift the draft-gate check
+  // LEFT to enqueue time so an un-refined issue never lands in the Next Up
+  // pickup column. Scoped to issues (not PRs) targeting the pickup column —
+  // create-pr.mjs auto-enqueues PRs into In Progress, which never trips this.
+  let refinement;
+  let effectiveTargetOption = targetOption;
+  let effectiveTargetStatus = targetStatus;
+  if (issueNumber !== null && targetStatus === nextUpColumn) {
+    const bodyResult = await child(
+      "gh",
+      ["issue", "view", String(issueNumber), "--repo", repo, "--json", "body"],
+      env,
+    );
+    if (bodyResult.code !== 0) {
+      const detail = bodyResult.stderr.trim() || `exit code ${bodyResult.code}`;
+      throw Object.assign(new Error(`gh issue view failed: ${detail}`), { code: "GH_API_ERROR" });
+    }
+    const bodyPayload = parseJsonText(bodyResult.stdout, { label: "gh issue view" });
+    const body = typeof bodyPayload?.body === "string" ? bodyPayload.body : "";
+    const artifact = detectIssueRefinementArtifact({ body, issueNumber });
+    const decision = decideEnqueueRefinementGate({ artifact, targetIsPickup: true, auto: !!args.auto });
+    if (decision.action === "block") {
+      throw Object.assign(new Error(decision.reason), {
+        code: "MISSING_REFINEMENT_ARTIFACT",
+        missing: decision.missing,
+      });
+    }
+    if (decision.action === "divert") {
+      const parkedColumn = nonSuccessBoardColumn(cwd);
+      if (parkedColumn === nextUpColumn) {
+        // A non-success park column equal to the pickup column would divert the
+        // un-refined item straight back into Next Up, defeating the gate. Fail
+        // closed on that misconfiguration rather than parking into pickup.
+        throw Object.assign(
+          new Error(`Park column "${parkedColumn}" (queue.nonSuccessStatus) is the pickup column; cannot divert an un-refined item into Next Up.`),
+          { code: "INVALID_STATUS" },
+        );
+      }
+      const parkedOption = statusField.options.find((o) => o.name === parkedColumn);
+      if (!parkedOption) {
+        const available = statusField.options.map((o) => o.name).join(", ");
+        throw Object.assign(
+          new Error(`Park column "${parkedColumn}" (queue.nonSuccessStatus) not found in Status field. Available: ${available}`),
+          { code: "COLUMN_NOT_FOUND" },
+        );
+      }
+      effectiveTargetOption = parkedOption;
+      effectiveTargetStatus = parkedColumn;
+      refinement = {
+        refined: false,
+        diverted: true,
+        requestedColumn: nextUpColumn,
+        parkedColumn,
+        reason: decision.reason,
+        missing: decision.missing,
+      };
+    } else {
+      refinement = { refined: true };
+    }
+  }
+
   // 6. Add item to project
   const addPayload = await ghGraphql(ADD_PROJECT_ITEM, {
     projectId: project.id,
@@ -518,7 +600,7 @@ async function main(args, { env = process.env, runChild, cwd = process.cwd() } =
     projectId: project.id,
     itemId: newItem.id,
     fieldId: statusField.id,
-    optionId: targetOption.id,
+    optionId: effectiveTargetOption.id,
   }, env, child);
 
   const updated = updatePayload?.data?.updateProjectV2ItemFieldValue?.projectV2Item;
@@ -532,9 +614,10 @@ async function main(args, { env = process.env, runChild, cwd = process.cwd() } =
       itemId: newItem.id,
       issueNumber,
       prNumber,
-      status: targetStatus,
+      status: effectiveTargetStatus,
       alreadyPresent: false,
     },
+    ...(refinement ? { refinement } : {}),
   };
 }
 

package/scripts/projects/list-queue-items.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { runChild as _runChild } from "../_cli-primitives.mjs";
-import { resolveProjectSelector, findProject, applyDevloopsBoard } from "./_resolve-project.mjs";
+import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { applyDevloopsBoard } from "./_resolve-project.mjs";
 import { parseArgs } from "node:util";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+import { main, classifyExitCode } from "@dev-loops/core/projects/list-queue-items";
 
 const USAGE = `Usage: dev-loops queue list --repo <owner/name> [--project <number|id>] [--column <name>] [--limit <n>]
        dev-loops queue list --repo <owner/name> [--project <number|id>] --summary [--done-limit <n>]
@@ -139,380 +139,6 @@ function parseCliArgs(argv) {
   }
   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;
-}
-
-// ── 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 = [
-  "query($projectId:ID!, $after:String) {",
-  "  node(id:$projectId) {",
-  "    ... on ProjectV2 {",
-  "      items(first:100, after:$after) {",
-  "        pageInfo { hasNextPage endCursor }",
-  "        nodes {",
-  "          id",
-  "          fieldValues(first:20) {",
-  "            nodes {",
-  "              ... on ProjectV2ItemFieldSingleSelectValue {",
-  "                field { ... on ProjectV2SingleSelectField { id name } }",
-  "                name",
-  "              }",
-  "            }",
-  "          }",
-  "          content {",
-  "            ... on Issue { number title url id }",
-  "            ... on PullRequest { number title url 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 ───────────────────────────────────────────────
-
-async function listAllItems(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, 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;
-}
-
-// ── Exit code classification ────────────────────────────────────────────
-
-function classifyExitCode(err) {
-  if (err.code === "INVALID_REPO" || err.code === "INVALID_PROJECT" || err.code === "INVALID_ARGS") return 1;
-  if (err.code === "PROJECT_NOT_FOUND" || err.code === "FIELD_NOT_FOUND" || err.code === "COLUMN_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("/");
-  const selector = resolveProjectSelector(args);
-
-  // Mutual exclusion: --summary is the whole-board grouped view; --column/--limit
-  // are flat-mode knobs. Combining them is ambiguous.
-  if (args.summary && args.column) {
-    throw Object.assign(
-      new Error("--summary and --column are mutually exclusive (--column filters to one status; --summary groups the whole board)"),
-      { code: "INVALID_ARGS" },
-    );
-  }
-  if (args.summary && args.limit) {
-    throw Object.assign(
-      new Error("--summary and --limit are mutually exclusive; use --done-limit to cap the Done group (or terminal column if no Done column exists)"),
-      { code: "INVALID_ARGS" },
-    );
-  }
-  if (args.doneLimit !== undefined && !args.summary) {
-    throw Object.assign(
-      new Error("--done-limit only applies with --summary"),
-      { code: "INVALID_ARGS" },
-    );
-  }
-
-  // 1. Resolve owner (user or org).
-  // 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" },
-    );
-  }
-
-  let targetOption = null;
-  if (args.column) {
-    targetOption = statusField.options.find(
-      (o) => o.name === args.column,
-    );
-    if (!targetOption) {
-      const available = statusField.options.map((o) => o.name).join(", ");
-      throw Object.assign(
-        new Error(
-          `Column "${args.column}" not found in Status field. Available: ${available}`,
-        ),
-        { code: "COLUMN_NOT_FOUND" },
-      );
-    }
-  }
-
-  // 4. List and filter items (ordered by position ascending, GraphQL default)
-  const rawItems = await listAllItems(project.id, env, child);
-
-  const results = [];
-  for (const item of rawItems) {
-    const content = item.content;
-    if (!content) continue;
-
-    // Determine status from field values
-    let status = null;
-    const fieldValues = item.fieldValues?.nodes ?? [];
-    for (const fv of fieldValues) {
-      if (fv && fv.field && fv.field.name === "Status") {
-        status = fv.name;
-        break;
-      }
-    }
-
-    // Filter by column
-    if (args.column && status !== args.column) continue;
-
-    const isPr = content.__typename === "PullRequest";
-
-    results.push({
-      issueNumber: isPr ? null : content.number,
-      prNumber: isPr ? content.number : null,
-      title: content.title ?? null,
-      url: content.url ?? null,
-      itemId: item.id,
-      contentId: content.id ?? null,
-      status: status ?? null,
-    });
-  }
-
-  // 5a. Summary mode: group by Status column in board option order.
-  if (args.summary) {
-    // Object.create(null): board option names are free text, so a column named
-    // "__proto__"/"constructor" must be an own key, not touch Object.prototype.
-    const groups = Object.create(null);
-    for (const option of statusField.options) {
-      groups[option.name] = { count: 0, items: [] };
-    }
-    for (const r of results) {
-      // Items with null status belong to no Status option, so they are excluded here — matches --column filtering behavior.
-      if (r.status === null) continue;
-      const group = groups[r.status];
-      if (!group) continue; // status value not among current board options
-      group.count += 1;
-      group.items.push(r);
-    }
-    if (args.doneLimit !== undefined) {
-      // Cap "Done" per the issue AC; if no column is literally named "Done",
-      // fall back to the last board option (conventionally the terminal column)
-      // so --done-limit is honest instead of a silent no-op.
-      const doneGroup = groups.Done ?? groups[statusField.options.at(-1)?.name];
-      if (doneGroup) {
-        doneGroup.items = doneGroup.items.slice(0, args.doneLimit);
-      }
-    }
-    return { ok: true, groups };
-  }
-
-  // 5b. Flat mode: items are returned in position order from GraphQL. Apply limit.
-  const limited = args.limit ? results.slice(0, args.limit) : results;
-
-  return {
-    ok: true,
-    items: limited,
-  };
-}
 
 // ── CLI entrypoint ──────────────────────────────────────────────────────