@dev-loops/core 0.1.0

package/src/loop/queue-board-ordering.mjs

@@ -0,0 +1,38 @@
+import { loadBoardConfig, resolveProjectNumber } from "./queue-board-sync.mjs";
+import { main as listQueueItemsMain } from "../../../../scripts/projects/list-queue-items.mjs";
+
+export async function resolveNextUpOrder(
+  repo,
+  repoRoot,
+  env = process.env,
+  dependencies = {},
+) {
+  const config = loadBoardConfig(repoRoot);
+  if (!config.enabled) {
+    return { ok: true, order: [], reason: config.reason ?? "board not configured" };
+  }
+
+  let projectNumber;
+  try {
+    projectNumber = await resolveProjectNumber(repo, config, env, dependencies.runChild);
+  } catch (err) {
+    return { ok: true, order: [], reason: err.message ?? "board lookup failed" };
+  }
+  if (!projectNumber) {
+    return { ok: true, order: [], reason: "could not resolve board project" };
+  }
+
+  const listItems = dependencies.listQueueItems ?? listQueueItemsMain;
+  try {
+    const result = await listItems(
+      { repo, project: projectNumber, column: "Next Up" },
+      { env, runChild: dependencies.runChild },
+    );
+    const order = (result?.items ?? [])
+      .map((it) => it.issueNumber ?? it.prNumber)
+      .filter((n) => typeof n === "number");
+    return { ok: true, order, reason: null };
+  } catch (err) {
+    return { ok: true, order: [], reason: err.message ?? "Next Up query failed" };
+  }
+}

package/src/loop/queue-board-sync.mjs

@@ -0,0 +1,223 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { runChild as coreRunChild } from "../cli/primitives.mjs";
+import { main as moveQueueItemMain } from "../../../../scripts/projects/move-queue-item.mjs";
+
+const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";
+
+// ── Local config loader ─────────────────────────────────────────────────
+
+function readDevloopsSettings(repoRoot) {
+  const base = path.join(repoRoot, ".devloops");
+  const extensions = ["", ".yaml", ".yml", ".json"];
+  let foundError = null;
+  for (const ext of extensions) {
+    try {
+      const raw = readFileSync(base + ext, "utf8");
+      const settings = ext === ".json" ? JSON.parse(raw) : parseYaml(raw);
+      return { settings: settings?.queue ?? null };
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        // try next extension
+      } else if (!foundError) {
+        foundError = err;
+      }
+    }
+  }
+  if (foundError) {
+    return { error: foundError.message };
+  }
+  return { settings: null };
+}
+
+export function loadBoardConfig(repoRoot) {
+  const { settings: queue, error } = readDevloopsSettings(repoRoot);
+  if (error) {
+    return { enabled: false, reason: `config read/parse error: ${error}` };
+  }
+  if (!queue) return { enabled: false };
+  if (typeof queue.projectNumber === "number" && queue.projectNumber > 0) {
+    return { enabled: true, projectNumber: queue.projectNumber };
+  }
+  if (typeof queue.boardTitle === "string" && queue.boardTitle.trim().length > 0) {
+    return { enabled: true, boardTitle: queue.boardTitle.trim() };
+  }
+  return { enabled: false };
+}
+
+// ── Minimal project lookup (read-only, no create/repair) ────────────────
+
+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");
+
+async function ghGraphql(query, vars, env, runChild) {
+  const child = runChild ?? coreRunChild;
+  const fieldArgs = [];
+  for (const [key, value] of Object.entries(vars)) {
+    fieldArgs.push("--field", `${key}=${value}`);
+  }
+  const result = await child(
+    "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 = JSON.parse(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;
+}
+
+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.filter((n) => n != null));
+    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;
+}
+
+const projectNumberCache = new Map();
+
+function projectCacheKey(repo, boardTitle) {
+  return `${repo}::${boardTitle}`;
+}
+
+export async function resolveProjectNumber(repo, config, env, runChild) {
+  if (config.projectNumber) return config.projectNumber;
+  if (config.boardTitle) {
+    const key = projectCacheKey(repo, config.boardTitle);
+    const cached = projectNumberCache.get(key);
+    if (cached) return cached;
+
+    const [owner] = repo.split("/");
+    const { kind } = await resolveOwner(owner, env, runChild);
+    const projects = await listAllProjects(owner, kind, env, runChild);
+    const match = projects.find((p) => p.title === config.boardTitle);
+    if (!match) {
+      throw Object.assign(
+        new Error(`Board title "${config.boardTitle}" not found under "${owner}"`),
+        { code: "BOARD_NOT_FOUND" },
+      );
+    }
+    projectNumberCache.set(key, match.number);
+    return match.number;
+  }
+  return null;
+}
+
+// ── Public API ──────────────────────────────────────────────────────────
+
+export async function syncBoardStatus(
+  repo,
+  repoRoot,
+  itemNumber,
+  targetColumn,
+  env = process.env,
+  dependencies = {},
+) {
+  const config = loadBoardConfig(repoRoot);
+  if (!config.enabled) {
+    return { ok: true, skipped: true, reason: config.reason ?? "board not configured" };
+  }
+
+  let projectNumber;
+  try {
+    projectNumber = await resolveProjectNumber(repo, config, env, dependencies.runChild);
+  } catch (err) {
+    return { ok: true, skipped: true, reason: err.message ?? "board lookup failed" };
+  }
+  if (!projectNumber) {
+    return { ok: true, skipped: true, reason: "could not resolve board project" };
+  }
+
+  const moveItem = dependencies.moveQueueItem ?? moveQueueItemMain;
+  try {
+    const result = await moveItem(
+      { repo, project: projectNumber, item: itemNumber, toColumn: targetColumn },
+      { env, runChild: dependencies.runChild },
+    );
+    return { ok: true, skipped: false, result };
+  } catch (err) {
+    return { ok: true, skipped: true, reason: err.message ?? "board sync failed" };
+  }
+}
+
+export function nonSuccessBoardColumn(repoRoot, fallback = DEFAULT_NON_SUCCESS_COLUMN) {
+  const { settings: queue } = readDevloopsSettings(repoRoot);
+  const configured = queue?.nonSuccessStatus;
+  return typeof configured === "string" && configured.trim().length > 0
+    ? configured.trim()
+    : fallback;
+}

package/src/loop/queue-driver.mjs

@@ -0,0 +1,164 @@
+/**
+ * Sequential queue driver — iterates entries, calls startup resolver per entry,
+ * routes through existing dev-loop strategies.
+ */
+
+import {
+  readQueue,
+  writeQueue,
+  transitionEntry,
+  snapshotEntry,
+  nextReadyEntry,
+  allDone,
+  RECOVERABLE_FAILURES,
+  appendBugIssue,
+} from "./queue-state.mjs";
+import { syncBoardStatus, nonSuccessBoardColumn } from "./queue-board-sync.mjs";
+import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
+
+export const DEFAULT_QUEUE_DRIVER_OPTIONS = {
+  mergeAuthorized: false,
+  reDispatchMaxRetries: 1,
+  maxAutoFiledIssues: 10,
+  env: process.env,
+};
+
+export function classifyFailure(error) {
+  if (!error) return "unknown";
+  const msg = typeof error === "string" ? error : error.message ?? "";
+  if (/parse|acceptance.report|unexpected token|JSON|malformed/i.test(msg)) return "acceptance_report_parse_failure";
+  if (/round.cap|max.*round|review.*limit/i.test(msg)) return "round_cap_reached";
+  if (/timeout|timed.out|watch.*expired/i.test(msg)) return "timeout";
+  if (/blocked|human.*comment|needs.*decision|needs.*user/i.test(msg)) return "blocked_needs_user_decision";
+  if (/ci.*fail|check.*fail|build.*fail|test.*fail/i.test(msg)) return "ci_failure";
+  return "unknown";
+}
+
+export function isRecoverable(failureKind) {
+  return RECOVERABLE_FAILURES.has(failureKind);
+}
+
+async function doTransition(entry, to, queue, repoRoot, opts, metadata) {
+  transitionEntry(entry, to, metadata);
+  await writeQueue(repoRoot, queue);
+  if (opts.onTransition) opts.onTransition(to, entry, queue);
+}
+
+/**
+ * Run the queue sequentially. Returns { ok, results, queue }.
+ * ok is true only when every entry succeeded; blocked entries count as failure.
+ */
+export async function runQueue(repoRoot, repo, options = {}) {
+  const opts = { ...DEFAULT_QUEUE_DRIVER_OPTIONS, ...options };
+  const queue = await readQueue(repoRoot);
+
+  // Optional board-aware ordering: fetch Next Up order before processing.
+  // Fail-open: if the board is unreachable, orderHint stays empty and the
+  // driver falls back to the existing queue order.
+  const ordering = opts.useBoardOrdering !== false && !allDone(queue)
+    ? await resolveNextUpOrder(repo, repoRoot, opts.env ?? process.env, opts.queueBoardSyncDependencies ?? {})
+    : { ok: true, order: [], reason: "board ordering disabled or queue idle" };
+  const orderHint = ordering.ok ? ordering.order : [];
+
+  let autoFiledCount = 0;
+  const results = [];
+  let incomplete = false;
+
+  while (!allDone(queue)) {
+    const entry = nextReadyEntry(queue, opts.reDispatchMaxRetries, orderHint);
+    if (!entry) {
+      const remaining = queue.entries.filter(
+        (e) => e.status !== "done" && e.status !== "blocked" && e.status !== "failed"
+      );
+      if (remaining.length > 0) {
+        incomplete = true;
+        results.push({
+          target: null, ok: false,
+          error: `Queue incomplete: ${remaining.length} entries blocked by unmet dependencies`,
+          pendingTargets: remaining.map((e) => e.target),
+        });
+      }
+      break;
+    }
+
+    const wasFailed = entry.status === "failed";
+    if (wasFailed) {
+      entry.retryCount = (entry.retryCount ?? 0) + 1;
+      await doTransition(entry, "queued", queue, repoRoot, opts);
+    }
+    await doTransition(entry, "running", queue, repoRoot, opts);
+
+    const boardSync = [];
+    const boardSyncDeps = opts.queueBoardSyncDependencies ?? {};
+    const recordBoardSync = async (promise) => {
+      const r = await promise;
+      boardSync.push(r);
+      return r;
+    };
+
+    await recordBoardSync(syncBoardStatus(
+      repo,
+      repoRoot,
+      entry.target,
+      "In Progress",
+      opts.env ?? process.env,
+      boardSyncDeps,
+    ));
+
+    try {
+      const entryResult = opts.runEntry
+        ? await opts.runEntry(entry, repo, opts)
+        : { ok: true, pr: null };
+
+      if (entryResult.ok) {
+        if (entryResult.pr) {
+          await doTransition(entry, "waiting_review", queue, repoRoot, opts, { pr: entryResult.pr });
+          await doTransition(entry, "gates_passing", queue, repoRoot, opts);
+          if (opts.mergeAuthorized) {
+            await doTransition(entry, "merging", queue, repoRoot, opts);
+            await doTransition(entry, "done", queue, repoRoot, opts, { retrospectiveWritten: true });
+            await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+          }
+          // else: stays at gates_passing for future merge run
+        } else {
+          await doTransition(entry, "done", queue, repoRoot, opts);
+          await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+        }
+        results.push({ target: entry.target, ok: true, entry: snapshotEntry(entry), boardSync });
+      } else {
+        throw new Error(entryResult.error || "Entry failed");
+      }
+    } catch (err) {
+      const fallbackColumn = nonSuccessBoardColumn(repoRoot, "Backlog");
+      await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, fallbackColumn, opts.env ?? process.env, boardSyncDeps));
+
+      const failureKind = classifyFailure(err);
+      const recoverable = isRecoverable(failureKind);
+
+      if (recoverable && (entry.retryCount ?? 0) < opts.reDispatchMaxRetries) {
+        await doTransition(entry, "failed", queue, repoRoot, opts, {
+          failureReason: err.message, failureKind,
+        });
+        results.push({
+          target: entry.target, ok: false, recoverable: true,
+          failureKind, entry: snapshotEntry(entry), boardSync,
+        });
+      } else {
+        await doTransition(entry, "blocked", queue, repoRoot, opts, {
+          failureReason: err.message, failureKind,
+        });
+        if (autoFiledCount < opts.maxAutoFiledIssues && failureKind !== "blocked_needs_user_decision") {
+          appendBugIssue(queue, entry.target + 1000, entry.target);
+          autoFiledCount++;
+        }
+        results.push({
+          target: entry.target, ok: false, recoverable: false,
+          failureKind, entry: snapshotEntry(entry), boardSync,
+        });
+      }
+    }
+  }
+
+  const allOk = results.every((r) => r.ok !== false) && !incomplete;
+  return { ok: allOk, results, queue, ordering };
+}

package/src/loop/queue-parallel.mjs

@@ -0,0 +1,190 @@
+/**
+ * Parallel execution helper for queue mode.
+ *
+ * When --parallel is set:
+ *   1. Compute file-touch overlap matrix for all queued items
+ *   2. Items with no overlap → dispatch in parallel (up to concurrency cap)
+ *   3. Items with overlapping files → serialize within overlap groups
+ *   4. Dependency chains (--after) → always serialize within chain
+ */
+
+import { topologicalOrder } from "./queue-state.mjs";
+
+/**
+ * Compute overlap groups from a set of entries and their file lists.
+ *
+ * @param {Array<{target: number, files: string[]}>} entryFiles
+ * @returns {Array<Array<number>>} Array of groups (each group is serialized internally)
+ */
+export function computeOverlapGroups(entryFiles) {
+  const n = entryFiles.length;
+  if (n === 0) return [];
+
+  // Build overlap matrix
+  const overlap = Array.from({ length: n }, () => Array(n).fill(false));
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      const filesI = new Set(entryFiles[i].files);
+      const filesJ = entryFiles[j].files;
+      const hasOverlap = filesJ.some((f) => filesI.has(f));
+      overlap[i][j] = hasOverlap;
+      overlap[j][i] = hasOverlap;
+    }
+  }
+
+  // Union-find to group overlapping entries
+  const parent = Array.from({ length: n }, (_, i) => i);
+  function find(x) {
+    while (parent[x] !== x) {
+      parent[x] = parent[parent[x]];
+      x = parent[x];
+    }
+    return x;
+  }
+  function union(a, b) {
+    const ra = find(a), rb = find(b);
+    if (ra !== rb) parent[rb] = ra;
+  }
+
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      if (overlap[i][j]) union(i, j);
+    }
+  }
+
+  // Collect groups preserving original order
+  const groups = new Map();
+  const groupOrder = [];
+  for (let i = 0; i < n; i++) {
+    const root = find(i);
+    if (!groups.has(root)) {
+      groups.set(root, []);
+      groupOrder.push(root);
+    }
+    groups.get(root).push(entryFiles[i].target);
+  }
+
+  return groupOrder.map((root) => groups.get(root));
+}
+
+/**
+ * Given overlap groups, compute which groups can run in parallel.
+ * Returns an array of "waves" where each wave contains groups that can run concurrently.
+ *
+ * @param {Array<Array<number>>} groups
+ * @param {number} maxParallel - Concurrency cap
+ * @returns {Array<Array<Array<number>>>} Array of waves
+ */
+export function scheduleParallelWaves(groups, maxParallel = 3) {
+  if (groups.length === 0) return [];
+
+  const waves = [];
+  let i = 0;
+
+  while (i < groups.length) {
+    const wave = [];
+    while (wave.length < maxParallel && i < groups.length) {
+      wave.push(groups[i]);
+      i++;
+    }
+    waves.push(wave);
+  }
+
+  return waves;
+}
+
+/**
+ * Compute the full parallel schedule for a queue.
+ *
+ * @param {Array<{target: number, files: string[], dependsOn: number[]}>} entries
+ * @param {number} maxParallel
+ * @returns {{waves: Array<Array<Array<number>>>, groups: Array<Array<number>>}}
+ */
+export function computeParallelSchedule(entries, maxParallel = 3) {
+  // First, topological sort for dependency ordering
+  const ordered = topologicalOrder(
+    entries.map((e) => ({
+      target: e.target,
+      dependsOn: e.dependsOn,
+    }))
+  );
+
+  // Map back to full entries in topological order
+  const orderedEntries = ordered.map((o) =>
+    entries.find((e) => e.target === o.target)
+  ).filter(Boolean);
+
+  // Build depChains: for each entry, collect ALL transitive ancestors
+  const allAncestors = new Map();
+  function getAncestors(target, visited = new Set()) {
+    if (allAncestors.has(target)) return allAncestors.get(target);
+    if (visited.has(target)) return new Set();
+    visited.add(target);
+    const entry = orderedEntries.find((e) => e.target === target);
+    const ancestors = new Set();
+    for (const dep of entry?.dependsOn || []) {
+      ancestors.add(dep);
+      for (const ancestor of getAncestors(dep, new Set(visited))) {
+        ancestors.add(ancestor);
+      }
+    }
+    allAncestors.set(target, ancestors);
+    return ancestors;
+  }
+  for (const entry of orderedEntries) {
+    getAncestors(entry.target);
+  }
+
+  // Compute file overlap groups
+  const entryFiles = orderedEntries.map((e) => ({
+    target: e.target,
+    files: e.files || [],
+    dependsOn: e.dependsOn || [],
+  }));
+
+  const groups = computeOverlapGroups(entryFiles);
+
+  // Merge dependency chains into overlap groups: for each group, add all
+  // ancestors of every member so dependency chains always serialize together
+  const expandedGroups = groups.map((group) => {
+    const expanded = new Set(group);
+    for (const target of group) {
+      const ancestors = allAncestors.get(target);
+      if (ancestors) {
+        for (const ancestor of ancestors) {
+          expanded.add(ancestor);
+        }
+      }
+    }
+    return [...expanded];
+  });
+
+  // Deduplicate: if a target appears in multiple groups, merge those groups
+  const merged = [];
+  for (const group of expandedGroups) {
+    // Check if any member is already in a previously emitted group
+    let mergedWith = -1;
+    for (let i = 0; i < merged.length; i++) {
+      for (const target of group) {
+        if (merged[i].has(target)) {
+          mergedWith = i;
+          break;
+        }
+      }
+      if (mergedWith >= 0) break;
+    }
+    if (mergedWith >= 0) {
+      for (const target of group) {
+        merged[mergedWith].add(target);
+      }
+    } else {
+      merged.push(new Set(group));
+    }
+  }
+
+  const dedupedGroups = merged.map((s) => [...s]);
+
+  const waves = scheduleParallelWaves(dedupedGroups, maxParallel);
+
+  return { waves, groups: dedupedGroups };
+}