dev-loops 0.2.7 → 0.4.0

package/scripts/projects/archive-done-items.mjs

@@ -1,17 +1,25 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
 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 archive-done --repo <owner/name> --project <number|id> [--older-than <duration>] [--dry-run]
+const USAGE = `Usage: dev-loops queue archive-done --repo <owner/name> [--project <number|id>] [--older-than <duration>] [--dry-run]
+       (dev-loops project archive-done … is a back-compat alias)
 
 Archive GitHub Projects V2 items whose issue/PR has been closed for at least the
 given duration. Operator-triggered (no webhooks). Uses archiveProjectV2Item.
 
 Options:
   --repo <owner/name>     Required. Repository to scope the project search.
-  --project <number|id>   Required. Project number (integer) or node ID.
+  --project <number|id>   Project number (integer) or node ID. When omitted,
+                          resolved from .devloops queue.projectNumber /
+                          queue.boardTitle.
   --older-than <duration> Closed-for threshold. Format: <n><unit> where unit is
-                          h (hours), d (days), or w (weeks). Default: 30d.
+                          h (hours), d (days), or w (weeks). Default resolves
+                          from .devloops queue.archiveOlderThanDays, else 7d.
   --dry-run               Print the intended archive mutation(s) without executing.
   --help, -h              Show this help.
 
@@ -27,36 +35,61 @@ Exit codes:
   3 — project not found
 `.trim();
 
-const VALID_ARGS = new Set(["--repo", "--project", "--older-than", "--dry-run", "--help", "-h"]);
+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 });
+    }
+    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" },
+      "older-than": { 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") {
+      throw Object.assign(new Error(`Unexpected argument: ${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
     }
-    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 === "--older-than") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--older-than requires a value (e.g. 30d)"), { code: "INVALID_DURATION" });
-      }
-      args.olderThan = 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 });
+    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 "project":
+        args.project = requireValue(token, "--project requires a value (number or node ID)", "INVALID_PROJECT");
+        break;
+      case "older-than":
+        args.olderThan = requireValue(token, "--older-than requires a value (e.g. 30d)", "INVALID_DURATION");
+        break;
+      case "dry-run":
+        if (token.value !== undefined) {
+          throw Object.assign(new Error(`Unknown flag: ${token.rawName}=${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
+        }
+        args.dryRun = true;
+        break;
+      default:
+        throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
     }
   }
   return args;
@@ -121,6 +154,37 @@ function parseDuration(raw) {
   return n * UNIT_MS[m[2]];
 }
 
+// ── Settings fallback ──────────────────────────────────────────────────────
+
+// 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;
+}
+
 // ── API helpers ──────────────────────────────────────────────────────────
 
 async function ghGraphql(query, vars, env, runChild = _runChild) {
@@ -289,6 +353,9 @@ function normalizeItem(node) {
 function selectArchivable(items, { now, olderThanMs }) {
   return items.filter((it) => {
     if (it.isArchived) return false;
+    // Only archive items in the Done column — a closed issue/PR parked in
+    // another column (Backlog/Next Up/In Progress) must be left untouched.
+    if (it.status !== "Done") return false;
     const c = it.content;
     if (!c || !c.closed || !c.closedAt) return false;
     const closedAtMs = Date.parse(c.closedAt);
@@ -312,19 +379,36 @@ async function main(args, { env = process.env, runChild } = {}) {
   const child = runChild ?? _runChild;
   const repo = validateRepo(args.repo);
   const [owner] = repo.split("/");
-  const projectRef = parseProjectRef(args.project);
-  const olderThanRaw = args.olderThan ?? "30d";
+  // Board: explicit --project ref wins; otherwise resolve by board title from
+  // .devloops (passed in as args.projectTitle by runCli). Fail closed if neither.
+  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 configure queue.projectNumber / queue.boardTitle in .devloops)"),
+      { code: "INVALID_PROJECT" },
+    );
+  }
+  const olderThanRaw = args.olderThan ?? args.olderThanDefault ?? "7d";
   const olderThanMs = parseDuration(olderThanRaw);
   const now = args.now ?? Date.now();
 
   const { kind: ownerKind } = await resolveOwner(owner, env, child);
   const projects = await listAllProjects(owner, ownerKind, env, child);
-  const project = projectRef.kind === "id"
-    ? projects.find((p) => p.id === projectRef.value)
-    : projects.find((p) => p.number === projectRef.value);
+  const project = projectRef
+    ? (projectRef.kind === "id"
+        ? projects.find((p) => p.id === projectRef.value)
+        : projects.find((p) => p.number === projectRef.value))
+    : projects.find((p) => p.title === projectTitle);
   if (!project) {
+    const desc = projectRef
+      ? (projectRef.kind === "id" ? `"${projectRef.value}"` : `number ${projectRef.value}`)
+      : `title "${projectTitle}"`;
     throw Object.assign(
-      new Error(`Project ${projectRef.kind === "id" ? `"${projectRef.value}"` : `number ${projectRef.value}`} not found under owner "${owner}"`),
+      new Error(`Project ${desc} not found under owner "${owner}"`),
       { code: "PROJECT_NOT_FOUND" },
     );
   }
@@ -378,10 +462,10 @@ async function main(args, { env = process.env, runChild } = {}) {
 
 // ── CLI entrypoint ──────────────────────────────────────────────────────
 
-async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd() } = {}) {
   let args;
   try {
-    args = parseArgs(argv);
+    args = parseCliArgs(argv);
   } catch (err) {
     stderr.write(`${formatCliError(err)}\n`);
     process.exitCode = 1;
@@ -391,6 +475,19 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
     stdout.write(USAGE);
     return;
   }
+
+  // Resolve board + threshold defaults from .devloops when the flags are absent.
+  // Precedence: explicit --project flag > queue.projectNumber/boardTitle.
+  //             explicit --older-than flag > queue.archiveOlderThanDays > 7d.
+  const settings = resolveSettings(cwd);
+  if (args.project === undefined && settings) {
+    if (settings.project) args.project = String(settings.project);
+    else if (settings.title) args.projectTitle = settings.title;
+  }
+  if (args.olderThan === undefined && settings?.olderThanDays) {
+    args.olderThanDefault = `${settings.olderThanDays}d`;
+  }
+
   try {
     const result = await main(args, { env });
     stdout.write(JSON.stringify(result) + "\n");
@@ -407,4 +504,4 @@ if (isDirectCliRun(import.meta.url)) {
   });
 }
 
-export { main, parseDuration, selectArchivable };
+export { main, parseCliArgs, parseDuration, selectArchivable, resolveSettings, runCli };

package/scripts/projects/ensure-queue-board.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { parseArgs } from "node:util";
 import { parse as parseYaml } from "yaml";
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 
-const USAGE = `Usage: dev-loops project ensure --repo <owner/name> [--project <number>] [--title <title>] [--link-repo <owner/name>] [--repair-rename]
+const USAGE = `Usage: dev-loops queue ensure --repo <owner/name> [--project <number>] [--title <title>] [--link-repo <owner/name>] [--repair-rename]
+       (dev-loops project ensure … is a back-compat alias)
 
 --repair-rename    Rename semantically equivalent Status columns to the standard names
                    (e.g. "Ready" -> "Next Up"). Without this flag the helper only
@@ -32,76 +34,76 @@ Exit codes:
   3 — board schema/config mismatch (manual reconciliation needed)
 `;
 
-const VALID_ARGS = new Set(["--repo", "--project", "--title", "--link-repo", "--repair-rename", "--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 = {}; // title default applied in runCli after settings fallback
-  const consumed = new Set();
-  for (let i = 0; i < argv.length; i++) {
-    if (consumed.has(i)) continue;
-    const arg = argv[i];
-    if (!VALID_ARGS.has(arg) && arg.startsWith("-")) {
-      throw Object.assign(
-        new Error(`Unknown flag: ${arg}`),
-        { code: "INVALID_REPO", usage: USAGE },
-      );
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      title: { type: "string" },
+      "link-repo": { type: "string" },
+      "repair-rename": { type: "boolean" },
+      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", usage: USAGE },
-        );
-      }
-      args.repo = argv[++i];
-      consumed.add(i);
-    } else if (arg === "--project") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--project requires a numeric value"),
-          { code: "INVALID_PROJECT", usage: USAGE },
-        );
-      }
-      const num = Number(argv[++i]);
-      if (!Number.isInteger(num) || num <= 0) {
-        throw Object.assign(
-          new Error(`--project must be a positive integer, got "${argv[i]}"`),
-          { code: "INVALID_PROJECT", usage: USAGE },
-        );
-      }
-      args.project = num;
-    } else if (arg === "--title") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--title requires a value"),
-          { code: "INVALID_REPO", usage: USAGE },
-        );
-      }
-      args.title = argv[++i];
-      consumed.add(i);
-    } else if (arg === "--link-repo") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--link-repo requires a value (owner/name)"),
-          { code: "INVALID_REPO", 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": {
+        const raw = requireValue(token, "--project requires a numeric value");
+        const num = Number(raw);
+        if (!Number.isInteger(num) || num <= 0) {
+          throw parseError(`--project must be a positive integer, got "${raw}"`);
+        }
+        args.project = num;
+        break;
       }
-      args.linkRepo = argv[++i];
-      consumed.add(i);
-    } else if (arg === "--repair-rename") {
-      args.repairRename = true;
-    } else if (arg === "--help" || arg === "-h") {
-      args.help = true;
-    } else {
-      throw Object.assign(
-        new Error(`Unexpected argument: ${arg}`),
-        { code: "INVALID_REPO", usage: USAGE },
-      );
+      case "title":
+        args.title = requireValue(token, "--title requires a value");
+        break;
+      case "link-repo":
+        args.linkRepo = requireValue(token, "--link-repo requires a value (owner/name)");
+        break;
+      case "repair-rename":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.repairRename = true;
+        break;
+      default:
+        throw parseError(`Unknown flag: ${token.rawName}`);
     }
   }
   return args;
 }
-
 // ── Validation ───────────────────────────────────────────────────────────
 
 // GitHub slug rules: owner 1-39 chars (alnum/dash, no leading/trailing dash,
@@ -798,7 +800,7 @@ async function main(args, { env = process.env, runChild } = {}) {
 async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd() } = {}) {
   let args;
   try {
-    args = parseArgs(argv);
+    args = parseCliArgs(argv);
   } catch (err) {
     stderr.write(`${formatCliError(err)}\n`);
     process.exitCode = 1;

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

@@ -1,8 +1,10 @@
 #!/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 list --repo <owner/name> --project <number|id> [--column <name>] [--limit <n>]
+const USAGE = `Usage: dev-loops queue list --repo <owner/name> --project <number|id> [--column <name>] [--limit <n>]
+       (dev-loops project list … is a back-compat alias)
 
 List GitHub Projects V2 items filtered by Status column, ordered by position
 ascending. Returns machine-readable JSON.
@@ -24,69 +26,69 @@ Exit codes:
   3 — project, field, or column not found
 `.trim();
 
-const VALID_ARGS = new Set(["--repo", "--project", "--column", "--limit", "--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" },
+      column: { type: "string" },
+      limit: { 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_ARGS", usage: USAGE },
-        );
-      }
-      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_ARGS", usage: USAGE },
-        );
-      }
-      args.project = argv[++i];
-    } else if (arg === "--column") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--column requires a value"),
-          { code: "INVALID_ARGS", usage: USAGE },
-        );
-      }
-      args.column = argv[++i];
-    } else if (arg === "--limit") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(
-          new Error("--limit requires a positive integer"),
-          { code: "INVALID_ARGS", usage: USAGE },
-        );
-      }
-      const val = Number(argv[++i]);
-      if (!Number.isInteger(val) || val < 1) {
-        throw Object.assign(
-          new Error(`--limit must be a positive integer, got "${argv[i]}"`),
-          { 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 "column":
+        args.column = requireValue(token, "--column requires a value");
+        break;
+      case "limit": {
+        const raw = requireValue(token, "--limit requires a positive integer");
+        const val = Number(raw);
+        if (!Number.isInteger(val) || val < 1) {
+          throw parseError(`--limit must be a positive integer, got "${raw}"`);
+        }
+        args.limit = val;
+        break;
       }
-      args.limit = val;
-    } else if (arg === "--help" || arg === "-h") {
-      args.help = true;
-    } else {
-      throw Object.assign(
-        new Error(`Unexpected argument: ${arg}`),
-        { code: "INVALID_ARGS", usage: USAGE },
-      );
+      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])?$/;
@@ -460,7 +462,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;