@connorbritain/roadmap 0.3.0

package/scripts/validate.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// roadmap — validate a roadmap.yaml.
+// Thin wrapper around lib/validate-core.mjs. Exits non-zero on any error.
+// Usage: node validate.mjs [path-to-roadmap.yaml]   (default: docs/roadmap/roadmap.yaml)
+
+import { loadGraph } from "./lib/graph.mjs";
+import { validateGraph } from "./lib/validate-core.mjs";
+
+const path = process.argv[2] || "docs/roadmap/roadmap.yaml";
+
+let graph;
+try {
+  graph = loadGraph(path);
+} catch (e) {
+  console.error(`✗ could not load ${path}: ${e.message}`);
+  process.exit(2);
+}
+
+const { errors, warnings, nodeCount } = validateGraph(graph);
+
+for (const w of warnings) console.warn(`⚠ ${w}`);
+if (errors.length) {
+  for (const e of errors) console.error(`✗ ${e}`);
+  console.error(`\n${errors.length} error(s) in ${path}`);
+  process.exit(1);
+}
+console.log(`✓ ${path} valid — ${(graph.pis || []).length} PIs, ${nodeCount} sprints, ${warnings.length} warning(s)`);
+process.exit(0);

package/scripts/watch-prs.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// roadmap — PR-watch monitor. Polls `gh pr list` for this roadmap's fanout branches and
+// prints one line per PR phase transition (draft -> ready, checks -> green, open -> merged, ...).
+// Bundled as a plugin monitor (monitors/monitors.json): each printed line becomes a notification
+// to the lead session. Also runnable as `roadmap watch` in a pane.
+//
+// Quiet by design: the first poll establishes a silent baseline; only changes after that print.
+// Degrades gracefully: if there's no roadmap or `gh` is missing/unauthenticated, it says so once
+// and exits 0 (never a crash loop).
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { findRepoRoot, REL } from "./lib/cli-core.mjs";
+import { loadGraph } from "./lib/graph.mjs";
+import { diffPrStates, roadmapBranches, checksOf } from "./lib/pr-watch-core.mjs";
+
+const POLL_MS = Number(process.env.ROADMAP_WATCH_INTERVAL_MS || 30000);
+const log = (m) => process.stdout.write(m + "\n");
+
+function loadRoadmap() {
+  const root = findRepoRoot(process.env.CODEX_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  if (!root) return null;
+  try {
+    return { root, graph: loadGraph(join(root, ...REL)) };
+  } catch {
+    return null;
+  }
+}
+
+const ghAvailable = () => {
+  try { return spawnSync("gh", ["--version"], { encoding: "utf8" }).status === 0; }
+  catch { return false; }
+};
+
+function fetchPrs(root) {
+  const r = spawnSync("gh", ["pr", "list", "--state", "all", "--limit", "100",
+    "--json", "number,title,headRefName,state,isDraft,mergeStateStatus,statusCheckRollup"],
+    { cwd: root, encoding: "utf8" });
+  if (r.status !== 0) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+function snapshot(prs, graph) {
+  const branches = roadmapBranches(graph);
+  const map = {};
+  for (const pr of prs) {
+    if (!branches.has(pr.headRefName)) continue; // only this roadmap's fanout branches
+    map[pr.number] = {
+      number: pr.number, title: pr.title, headRefName: pr.headRefName,
+      state: pr.state, isDraft: pr.isDraft, mergeStateStatus: pr.mergeStateStatus, checks: checksOf(pr),
+    };
+  }
+  return map;
+}
+
+const rm = loadRoadmap();
+if (!rm) { log("roadmap-prs: no docs/roadmap/roadmap.yaml found; PR watch idle."); process.exit(0); }
+if (!ghAvailable()) { log("roadmap-prs: `gh` CLI not found or not authenticated; PR watch disabled."); process.exit(0); }
+
+let prev = {};
+let primed = false;
+function tick() {
+  const prs = fetchPrs(rm.root);
+  if (!prs) return; // transient gh failure; try again next interval
+  const curr = snapshot(prs, rm.graph);
+  if (!primed) { prev = curr; primed = true; return; } // silent baseline on first poll
+  for (const ev of diffPrStates(prev, curr)) log(ev.message);
+  prev = curr;
+}
+
+tick();
+setInterval(tick, POLL_MS); // keep polling until the process is killed (monitor lifecycle / Ctrl-C)

package/scripts/wizard.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// roadmap — the interactive console (bare `roadmap` in a TTY, or `roadmap go`).
+// Hot-loads THIS repo's roadmap (cwd = repo root, set by cli.mjs), shows what's runnable, then
+// walks through a few prompts — terminal, max concurrency, wave, lead?, action — and hands the
+// choices to fanout.mjs. Worker permission mode is NOT surfaced here: it comes from
+// meta.worker_mode (or the --worker-mode flag). Nothing here merges; fanout enforces that.
+
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadGraph, flatten, computeWaves, readyNodes } from "./lib/graph.mjs";
+import { recommendConcurrency } from "./lib/recommend.mjs";
+import { terminalChoices, buildFanArgs, autoOutName } from "./lib/wizard-core.mjs";
+import { select, number, confirm } from "./prompt.mjs";
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+const INPATH = "docs/roadmap/roadmap.yaml";
+const S = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", cyan: "\x1b[36m", green: "\x1b[32m", red: "\x1b[31m" };
+
+const TERM_HINTS = {
+  wt: "Windows Terminal tabs",
+  warp: "Warp tab config + deeplink",
+  tmux: "tmux panes (WSL/macOS/Linux)",
+  print: "print the commands only",
+  background: "detached background sessions",
+};
+
+async function main() {
+  let graph;
+  try { graph = loadGraph(INPATH); }
+  catch (e) { console.error(`${S.red}Couldn't load ${INPATH}: ${e.message}${S.reset}`); process.exit(1); }
+
+  const model = flatten(graph);
+  const ready = readyNodes(model);
+  const rec = recommendConcurrency(ready, graph);
+  const program = (graph.meta && graph.meta.program) || "roadmap";
+
+  console.log(`\n${S.bold}${S.cyan}${program} — fanout${S.reset}  ${S.dim}${process.cwd()}${S.reset}`);
+
+  if (!ready.length) {
+    console.log(`\n${S.dim}No agent-runnable slices right now.${S.reset}`);
+    let held = null;
+    try { ({ held } = computeWaves(model, 1)); } catch { /* cycle — skip the held view */ }
+    if (held && held.onHuman.length) {
+      console.log("Held on a human:");
+      for (const n of held.onHuman) console.log(`  • ${n.invoke} — gated on ${n.gatedOn}`);
+    }
+    console.log(`\nRun ${S.bold}roadmap plan${S.reset} for the full picture.`);
+    process.exit(0);
+  }
+
+  console.log(`${ready.length} ready slice(s) · recommended cap ${S.bold}${rec.recommended}${S.reset} ${S.dim}(${rec.binding.why.split(" — ")[0]})${S.reset}\n`);
+
+  // 1) terminal — platform default first, or meta.terminal if set
+  const termIds = terminalChoices(os.platform());
+  const metaTerm = graph.meta && graph.meta.terminal;
+  const defTermIdx = Math.max(0, termIds.indexOf(metaTerm || termIds[0]));
+  const term = await select(
+    "Terminal",
+    termIds.map((t) => ({ label: t, value: t, hint: TERM_HINTS[t] })),
+    { defaultIdx: defTermIdx },
+  );
+
+  // 2) max concurrency — default = recommended, clamp to the ready count
+  const cap = await number("Max concurrent sessions", { def: rec.recommended, min: 1, max: ready.length });
+
+  // 3) wave — recompute under the chosen cap
+  let waves;
+  try { ({ waves } = computeWaves(model, cap)); }
+  catch (e) { console.error(`${S.red}✗ ${e.message}${S.reset}`); process.exit(1); }
+  if (!waves.length) { console.log(`${S.dim}No runnable waves at cap ${cap}.${S.reset}`); process.exit(0); }
+  const wave = await select(
+    "Which wave",
+    waves.map((w, i) => ({ label: `Wave ${i + 1} — ${w.length} concurrent`, value: i + 1, hint: w.map((n) => n.invoke).join(", ") })),
+    { defaultIdx: 0 },
+  );
+
+  // 4) lead coordinator session?
+  const lead = await confirm("Open a LEAD coordinator session too?", false);
+
+  // 5) action
+  const mode = await select("Action", [
+    { label: "Launch now", value: "launch", hint: "open the wave" },
+    { label: "Preview only", value: "dry", hint: "print the launch script, spawn nothing" },
+    { label: "Save script to a file", value: "save", hint: "write it, don't launch" },
+  ], { defaultIdx: 0 });
+
+  const outName = mode === "save" ? autoOutName(term, wave) : undefined;
+  const fanArgs = buildFanArgs({ term, cap, wave, lead, mode, outName });
+
+  console.log(`\n${S.green}▶${S.reset} roadmap fan ${fanArgs.join(" ")}\n`);
+  const r = spawnSync("node", [join(SCRIPTS, "fanout.mjs"), ...fanArgs], { stdio: "inherit", cwd: process.cwd() });
+  process.exit(r.status ?? 0);
+}
+
+main();