@gobing-ai/spur 0.4.10 → 0.4.11

package/spur.js

@@ -144167,10 +144167,333 @@ function runSpine(argv, rt) {
     return 2;
   }
 }
+function obj(value) {
+  return typeof value === "object" && value !== null ? value : {};
+}
+function text4(value) {
+  return typeof value === "string" ? value : "";
+}
+function list(value) {
+  return Array.isArray(value) ? value : [];
+}
+function word(payload, fallback = "FAIL") {
+  const verdict = payload?.verdict;
+  return typeof verdict === "string" && verdict !== "" ? verdict : fallback;
+}
+function findingsArg(value) {
+  return list(value);
+}
+function runVerbOp(argv, rt, sink) {
+  const out = [];
+  const previous = io;
+  io = { out: (line) => out.push(line), err: (line) => sink.err(line) };
+  try {
+    const code = runSpine(argv, rt);
+    let payload = null;
+    for (let i = out.length - 1;i >= 0; i--) {
+      const line = (out[i] ?? "").trim();
+      if (!line.startsWith("{"))
+        continue;
+      try {
+        payload = JSON.parse(line);
+      } catch {
+        payload = null;
+      }
+      break;
+    }
+    return { code, payload };
+  } finally {
+    io = previous;
+  }
+}
+function validPollBudget(opts, sink) {
+  if (opts.timeout !== undefined && !(Number.isFinite(Number(opts.timeout)) && Number(opts.timeout) >= 0)) {
+    sink.err("error: --timeout must be a non-negative number");
+    return false;
+  }
+  if (opts.interval !== undefined && !(Number.isFinite(Number(opts.interval)) && Number(opts.interval) > 0)) {
+    sink.err("error: --interval must be a positive number");
+    return false;
+  }
+  return true;
+}
+function writeVerbStatus(rt, opts, verdict) {
+  if (opts.statusFile !== undefined)
+    rt.writeStatus(opts.statusFile, `${verdict}
+`);
+}
+function currentHead(rt) {
+  const res = run3(rt, ["git", "rev-parse", "HEAD"]);
+  const head = res.stdout.trim();
+  return res.code === 0 && head !== "" ? head : undefined;
+}
+function composeStatus(rt, opts, sink) {
+  const flags = ["--json"];
+  if (opts.since !== undefined)
+    flags.push("--since", opts.since);
+  const head = opts.head ?? currentHead(rt);
+  if (head !== undefined)
+    flags.push("--head", head);
+  const status = runVerbOp(["status", ...flags], rt, sink);
+  if (status.code !== 0)
+    return { code: status.code, payload: { ...obj(status.payload), review: null } };
+  if (status.payload?.pr === null || status.payload?.pr === undefined) {
+    return { code: 0, payload: { ...obj(status.payload), review: null } };
+  }
+  const collect = runVerbOp(["collect", ...flags], rt, sink);
+  return { code: collect.code, payload: { ...obj(status.payload), review: collect.payload } };
+}
+function composeCheck(rt, opts, sink) {
+  const flags = ["--json"];
+  if (opts.statusFile !== undefined)
+    flags.push("--status-file", opts.statusFile);
+  if (opts.base !== undefined)
+    flags.push("--base", opts.base);
+  const preflight = opts.scanOnly === true ? null : runVerbOp(["preflight", ...flags], rt, sink);
+  if (preflight !== null && preflight.code !== 0) {
+    return {
+      code: preflight.code,
+      payload: { ok: false, verdict: "FAIL", preflight: preflight.payload, hygiene: null }
+    };
+  }
+  const hygiene = runVerbOp(["hygiene", ...flags], rt, sink);
+  const opWord = word(hygiene.payload, "PASS");
+  const verdict = hygiene.code === 0 ? opWord : opWord === "BLOCK" ? "BLOCK" : "FAIL";
+  return {
+    code: hygiene.code,
+    payload: { ok: hygiene.code === 0, verdict, preflight: preflight?.payload ?? null, hygiene: hygiene.payload }
+  };
+}
+function composeOpen(rt, opts, sink) {
+  const flags = ["--json"];
+  if (opts.statusFile !== undefined)
+    flags.push("--status-file", opts.statusFile);
+  const push = runVerbOp(["push", ...flags], rt, sink);
+  if (push.code !== 0) {
+    return { code: push.code, payload: { ok: false, verdict: "FAIL", push: push.payload, pr: null } };
+  }
+  const ensureFlags = [...flags];
+  if (opts.base !== undefined)
+    ensureFlags.push("--base", opts.base);
+  const ensure = runVerbOp(["ensure", ...ensureFlags], rt, sink);
+  const verdict = ensure.code === 0 ? ensure.payload?.created === true ? "CREATED" : "FOUND" : "FAIL";
+  return {
+    code: ensure.code,
+    payload: { ok: ensure.code === 0, verdict, push: push.payload, pr: ensure.payload?.pr ?? null }
+  };
+}
+function composeReview(rt, opts, sink) {
+  const statusFlags = opts.statusFile !== undefined ? ["--status-file", opts.statusFile] : [];
+  if (!validPollBudget(opts, sink)) {
+    return { code: 1, payload: { ok: false, verdict: "FAIL", request: null, findings: [] } };
+  }
+  const requestFlags = ["--json", ...statusFlags];
+  if (opts.force === true)
+    requestFlags.push("--force");
+  if (opts.focus !== undefined)
+    requestFlags.push("--focus", opts.focus);
+  const request = runVerbOp(["request", ...requestFlags], rt, sink);
+  if (request.code !== 0) {
+    return { code: request.code, payload: { ok: false, verdict: "FAIL", request: request.payload, findings: [] } };
+  }
+  const record = obj(request.payload);
+  const correlation = [];
+  if (text4(record.requestedAt) !== "")
+    correlation.push("--since", text4(record.requestedAt));
+  if (text4(record.head) !== "")
+    correlation.push("--head", text4(record.head));
+  const collected = () => {
+    const collect = runVerbOp(["collect", ...correlation, "--json", ...statusFlags], rt, sink);
+    return {
+      code: collect.code,
+      payload: {
+        ok: collect.code === 0,
+        verdict: collect.code === 0 ? word(collect.payload) : "FAIL",
+        request: request.payload,
+        findings: collect.code === 0 ? list(collect.payload?.findings) : []
+      }
+    };
+  };
+  const pending = (code) => {
+    writeVerbStatus(rt, opts, "PENDING");
+    return { code, payload: { ok: true, verdict: "PENDING", request: request.payload, findings: [] } };
+  };
+  if (record.alreadyReviewed === true)
+    return collected();
+  if (record.pending === true || record.requested === true && opts.noWait === true)
+    return pending(0);
+  const waitFlags = [...correlation, "--json", ...statusFlags];
+  if (opts.timeout !== undefined)
+    waitFlags.push("--timeout", opts.timeout);
+  if (opts.interval !== undefined)
+    waitFlags.push("--interval", opts.interval);
+  const waited = runVerbOp(["wait", ...waitFlags], rt, sink);
+  if (waited.code === 3)
+    return pending(3);
+  if (waited.code !== 0) {
+    return { code: waited.code, payload: { ok: false, verdict: "FAIL", request: request.payload, findings: [] } };
+  }
+  return collected();
+}
+function renderPrVerb(verb, payload) {
+  if (verb === "status") {
+    const pr = payload.pr === null || payload.pr === undefined ? null : obj(payload.pr);
+    const review = payload.review === null || payload.review === undefined ? null : obj(payload.review);
+    const lines = [
+      `Repository: ${text4(payload.repo) || "unknown"}`,
+      `PR:         ${pr === null ? "none" : `#${String(pr.number ?? "")} ${text4(pr.url)}`}`,
+      `Branch:     ${text4(payload.branch)}`,
+      `HEAD:       ${text4(payload.head)}`,
+      `Base:       ${text4(payload.base)}`,
+      `Local:      ${text4(payload.local)}`,
+      `CI:         ${text4(payload.ci)}`,
+      `Codex:      ${text4(payload.codex)}`
+    ];
+    if (review === null)
+      return [...lines, "Review:     no PR \u2014 nothing collected"];
+    lines.push(`Review:     ${text4(review.verdict) || "unknown"}`);
+    const findings = findingsArg(review.findings);
+    if (findings.length > 0)
+      lines.push("", renderFindings(findings));
+    return lines;
+  }
+  if (verb === "check") {
+    const preflight = payload.preflight === null || payload.preflight === undefined ? null : obj(payload.preflight);
+    const hygiene = payload.hygiene === null || payload.hygiene === undefined ? null : obj(payload.hygiene);
+    const lines = [
+      preflight === null ? "Preflight:  skipped (--scan-only)" : preflight.ok === true ? `Preflight:  ${text4(preflight.nameWithOwner)} ${text4(preflight.branch)} @ ${text4(preflight.shortHead)}` : `Preflight:  FAIL \u2014 ${text4(preflight.error) || "probe failed"}`
+    ];
+    if (hygiene === null)
+      return lines;
+    lines.push(`Hygiene:    ${text4(hygiene.verdict) || "FAIL"}`);
+    for (const blocker of list(hygiene.blockers))
+      lines.push(`  BLOCK ${String(blocker)}`);
+    for (const warning of list(hygiene.warnings))
+      lines.push(`  WARN  ${String(warning)}`);
+    return lines;
+  }
+  if (verb === "open") {
+    const push = obj(payload.push);
+    const pr = payload.pr === null || payload.pr === undefined ? null : obj(payload.pr);
+    return [
+      `Push:       ${push.pushed === true ? "PUSHED" : "UP_TO_DATE"} ${text4(push.head).slice(0, 7)}`,
+      `PR:         ${pr === null ? "none" : `#${String(pr.number ?? "")} ${text4(pr.url)} (${text4(payload.verdict)})`}`
+    ];
+  }
+  const request = obj(payload.request);
+  const outcome = request.requested === true ? "REQUESTED" : request.alreadyReviewed === true ? "ALREADY_REVIEWED" : request.pending === true ? "ALREADY_REQUESTED" : "FAIL";
+  const lines = [
+    `Request:    ${outcome} PR #${String(request.pr ?? "?")} ${text4(request.url)}`,
+    `HEAD:       ${text4(request.head).slice(0, 7)}`,
+    `Review:     ${text4(payload.verdict) || "unknown"}`
+  ];
+  const findings = findingsArg(payload.findings);
+  if (findings.length > 0)
+    lines.push("", renderFindings(findings));
+  return lines;
+}
+var PR_VERB_COMPOSERS = { status: composeStatus, check: composeCheck, open: composeOpen, review: composeReview };
+function runPrVerb(verb, opts, sink, context = {}) {
+  const rt = createRuntime(context);
+  const result = PR_VERB_COMPOSERS[verb](rt, opts, sink);
+  if (opts.json === true)
+    sink.out(JSON.stringify(result.payload));
+  else
+    for (const line of renderPrVerb(verb, result.payload))
+      sink.out(line);
+  return result.code;
+}
 
 // src/commands/builder/pr.ts
-function registerBuilderPrCommand(builder, context) {
-  builder.command("pr").summary("GitHub Codex PR-review loop (preflight | push | ensure | hygiene | request | wait | collect | status)").description(PR_REVIEW_HELP).allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", "subcommand and flags (see description)").action((argv) => {
+var PR_VERB_FOR_OP = {
+  preflight: "pr-check",
+  hygiene: "pr-check",
+  push: "pr-open",
+  ensure: "pr-open",
+  "ensure-pr": "pr-open",
+  request: "pr-review",
+  wait: "pr-review",
+  collect: "pr-status",
+  status: "pr-status"
+};
+function prDeprecationLine(op) {
+  const replacement = op === undefined ? undefined : PR_VERB_FOR_OP[op];
+  return replacement !== undefined ? `spur builder pr ${op} is deprecated; use spur builder ${replacement}` : "spur builder pr is deprecated; use spur builder pr-status | pr-check | pr-open | pr-review";
+}
+function registerBuilderPrCommands(builder, context) {
+  const io = () => ({
+    out: (line) => context.output.write(line),
+    err: (line) => context.output.error(line)
+  });
+  const ctx = () => ({ cwd: context.cwd, env: context.env });
+  const run = (verb, opts) => {
+    context.setExitCode(runPrVerb(verb, opts, io(), ctx()));
+  };
+  builder.command("pr-status").summary("read-only PR/CI/Codex status with the current-HEAD review as `review`").description([
+    "Read-only composition of the status and collect operations:",
+    "repository, branch, PR/base, local changes, CI and Codex state, plus",
+    "`review` \u2014 the current-HEAD Codex record when the branch has a PR,",
+    "else null. Writes no verdict: a status probe is not a gate.",
+    "Exit codes: 0 ok \xB7 2 probe failure."
+  ].join(`
+`)).option("--since <iso>", "only count review output submitted at or after this time").option("--head <sha>", "pin the reviewed commit (default: the current local HEAD)").option(...SHARED_OPTIONS.json).option("--status-file <path>", "accepted for symmetry; a read-only status writes no verdict").action((options) => {
+    run("status", {
+      ...options.since !== undefined ? { since: options.since } : {},
+      ...options.head !== undefined ? { head: options.head } : {},
+      ...options.json === true ? { json: true } : {},
+      ...options.statusFile !== undefined ? { statusFile: options.statusFile } : {}
+    });
+  });
+  builder.command("pr-check").summary("PR submission gate: preflight then hygiene (PASS | WARN | BLOCK | FAIL)").description([
+    "Preflight (git/gh/repo checks, clean tree, not the base branch) then",
+    "the hygiene scan of base...HEAD for secrets/.env/conflict markers",
+    "(BLOCK) and debug residue (WARN). A preflight FAIL stops before",
+    "hygiene. `--scan-only` runs hygiene alone, for a local review on a",
+    "dirty tree. Exit codes: 0 ok \xB7 2 BLOCK/preflight FAIL/probe failure."
+  ].join(`
+`)).option("--base <branch>", "base branch for the base...HEAD diff (default: the PR base, else the repo default)").option("--scan-only", "hygiene only; skip preflight (a dirty tree is expected)").option(...SHARED_OPTIONS.json).option("--status-file <path>", "write the one-word verdict (PASS | WARN | BLOCK | FAIL)").action((options) => {
+    run("check", {
+      ...options.base !== undefined ? { base: options.base } : {},
+      ...options.scanOnly === true ? { scanOnly: true } : {},
+      ...options.json === true ? { json: true } : {},
+      ...options.statusFile !== undefined ? { statusFile: options.statusFile } : {}
+    });
+  });
+  builder.command("pr-open").summary("publish the branch and reuse or create its pull request (FOUND | CREATED | FAIL)").description([
+    "Push the branch (normal push only \u2014 never force; sets upstream when",
+    "missing), then reuse the branch PR or create one with",
+    "`gh pr create --fill`. A rejected push stops before any PR work.",
+    "Exit codes: 0 ok \xB7 2 push rejected or ensure failed."
+  ].join(`
+`)).option("--base <branch>", "base for a newly created PR (default: the repo default branch)").option(...SHARED_OPTIONS.json).option("--status-file <path>", "write the one-word verdict (FOUND | CREATED | FAIL)").action((options) => {
+    run("open", {
+      ...options.base !== undefined ? { base: options.base } : {},
+      ...options.json === true ? { json: true } : {},
+      ...options.statusFile !== undefined ? { statusFile: options.statusFile } : {}
+    });
+  });
+  builder.command("pr-review").summary("request the GitHub Codex review and collect its result (CLEAN | FINDINGS | PENDING | FAIL)").description([
+    "Post the `@codex review` request (per-HEAD dedupe unless --force),",
+    "poll for the result, then collect it. An already-reviewed HEAD is",
+    "collected without a new request; an in-flight request or --no-wait",
+    "returns PENDING. Exit codes: 0 ok \xB7 2 hard failure \xB7 3 wait timeout",
+    "(verdict PENDING \u2014 pending, never failure)."
+  ].join(`
+`)).option("--force", "request a fresh review even when the current HEAD is already reviewed").option("--focus <text>", "extra review focus appended to the request").option("--no-wait", "post the request and return PENDING without polling").option("--timeout <s>", "wait budget in seconds (service default 600)").option("--interval <s>", "poll interval in seconds (service default 30)").option(...SHARED_OPTIONS.json).option("--status-file <path>", "write the one-word verdict (CLEAN | FINDINGS | PENDING | FAIL)").action((options) => {
+    run("review", {
+      ...options.force === true ? { force: true } : {},
+      ...options.focus !== undefined ? { focus: options.focus } : {},
+      ...options.wait === false ? { noWait: true } : {},
+      ...options.timeout !== undefined ? { timeout: options.timeout } : {},
+      ...options.interval !== undefined ? { interval: options.interval } : {},
+      ...options.json === true ? { json: true } : {},
+      ...options.statusFile !== undefined ? { statusFile: options.statusFile } : {}
+    });
+  });
+}
+function registerBuilderPrAliasCommand(builder, context) {
+  builder.command("pr", { hidden: true }).summary("deprecated alias for the flat pr-<verb> commands").description(PR_REVIEW_HELP).allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", "subcommand and flags (see description)").action((argv) => {
+    context.output.error(prDeprecationLine(argv[0]));
     context.setExitCode(main(argv, {
       out: (line) => context.output.write(line),
       err: (line) => context.output.error(line)
@@ -144178,9 +144501,574 @@ function registerBuilderPrCommand(builder, context) {
   });
 }
 
+// ../../packages/app/src/services/branch-topology/render.ts
+var INDENT = "    ";
+var MERMAID_DEFAULT_BRANCH = "main";
+var TABLE_HEADERS = ["branch", "ahead", "behind", "contained", "last commit", "worktree", "PR"];
+function renderMarkdown2(topology, graph) {
+  const lines = [
+    `## Branch topology vs \`${markdownCell(topology.base)}\``,
+    "",
+    `Generated ${topology.generatedAt}.`
+  ];
+  for (const warning of topology.warnings)
+    lines.push("", `> warning: ${warning}`);
+  lines.push("", ...markdownTable(topology.branches), ...omittedFooter(topology, "_", "_"));
+  lines.push("", "```mermaid", renderGitGraph(topology, graph), "```");
+  return `${lines.join(`
+`)}
+`;
+}
+function renderText(topology) {
+  const rows = [TABLE_HEADERS.map((header) => header), ...topology.branches.map(rowCells)];
+  const widths = TABLE_HEADERS.map((_, column) => Math.max(...rows.map((row) => (row[column] ?? "").length)));
+  const lines = [`base: ${topology.base}`, `generated: ${topology.generatedAt}`];
+  for (const warning of topology.warnings)
+    lines.push(`warning: ${warning}`);
+  lines.push("", ...rows.map((row) => alignRow(row, widths)), ...omittedFooter(topology, "", ""));
+  return `${lines.join(`
+`)}
+`;
+}
+function markdownTable(branches) {
+  const lines = [`| ${TABLE_HEADERS.join(" | ")} |`, `| ${TABLE_HEADERS.map(() => "---").join(" | ")} |`];
+  for (const row of branches) {
+    lines.push(`| ${rowCells(row).map(markdownCell).join(" | ")} |`);
+  }
+  return lines;
+}
+function rowCells(row) {
+  return [
+    row.name,
+    String(row.ahead),
+    String(row.behind),
+    row.contained ? "yes" : "no",
+    row.lastCommitAt.slice(0, 10),
+    row.worktree ?? "-",
+    row.pr === null ? "-" : `#${row.pr.number} ${row.pr.state}${row.pr.reviewDecision === null ? "" : ` ${row.pr.reviewDecision}`}`
+  ];
+}
+function alignRow(cells, widths) {
+  return cells.map((cell, column) => {
+    const width = widths[column] ?? cell.length;
+    return column === 0 ? cell.padEnd(width) : cell.padStart(width);
+  }).join("  ").trimEnd();
+}
+function omittedFooter(topology, open, close) {
+  if (topology.omitted === 0)
+    return [];
+  const noun = topology.omitted === 1 ? "branch" : "branches";
+  return ["", `${open}Omitted: ${topology.omitted} ${noun} beyond --limit.${close}`];
+}
+function markdownCell(value) {
+  return value.replaceAll("|", "\\|").replaceAll("`", "'");
+}
+function renderGitGraph(topology, graph) {
+  const lines = [];
+  if (graph.theme !== undefined && graph.theme.length > 0) {
+    lines.push(`%%{init: { 'theme': '${sanitizeId(graph.theme)}' } }%%`);
+  }
+  lines.push("gitGraph");
+  const baseId = sanitizeId(topology.base);
+  const usedRefs = new Set;
+  const base = refToken(topology.base, usedRefs);
+  const baseRow = baseRowOf(topology);
+  if (baseId !== MERMAID_DEFAULT_BRANCH)
+    lines.push(`${INDENT}branch ${base}`);
+  const tagsBySha = collectTags(topology.branches);
+  const usedIds = new Set;
+  const usedTags = new Set;
+  const window2 = (baseRow?.commits ?? []).slice(0, Math.max(graph.maxCommits, 0));
+  for (const { sha } of deepForkPoints(topology, baseRow, window2.length, graph.hideContained)) {
+    lines.push(`${INDENT}${commitStatement({ sha, subject: "", tags: tagsBySha.get(sha) ?? [] }, usedIds, usedTags, undefined)}`);
+  }
+  for (const [index, commit] of window2.slice().reverse().entries()) {
+    const isTip = index === window2.length - 1;
+    lines.push(`${INDENT}${commitStatement(commit, usedIds, usedTags, isTip ? "HIGHLIGHT" : commitType(commit))}`);
+  }
+  for (const row of topology.branches) {
+    if (row === baseRow)
+      continue;
+    if (row.contained && graph.hideContained)
+      continue;
+    lines.push(`${INDENT}checkout ${base}`);
+    const branch = refToken(row.name, usedRefs);
+    lines.push(branch === MERMAID_DEFAULT_BRANCH ? `${INDENT}checkout ${branch}` : `${INDENT}branch ${branch}`);
+    if (row.contained) {
+      lines.push(`${INDENT}${commitStatement({ sha: row.tip, subject: "", tags: tagsBySha.get(row.tip) ?? [] }, usedIds, usedTags, undefined)}`);
+      lines.push(`${INDENT}checkout ${base}`);
+      lines.push(`${INDENT}merge ${branch}`);
+      continue;
+    }
+    const shown = row.commits.slice(0, Math.max(Math.min(graph.maxCommits, row.ahead), 0)).reverse();
+    const hidden = Math.max(row.ahead - shown.length, 0);
+    if (hidden > 0) {
+      lines.push(`${INDENT}commit id:"${uniqueId(`+${hidden} earlier`, usedIds)}"`);
+    }
+    for (const [index, commit] of shown.entries()) {
+      const isTip = index === shown.length - 1;
+      lines.push(`${INDENT}${commitStatement(commit, usedIds, usedTags, isTip ? "HIGHLIGHT" : commitType(commit))}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function commitStatement(commit, usedIds, usedTags, type) {
+  const sha = short(commit.sha);
+  const id = uniqueId(sanitizeId(sha), usedIds);
+  const tag = claimTag(commit.tags[0], usedTags);
+  let line = `commit id:"${id}"`;
+  if (tag !== undefined)
+    line += ` tag:"${tag}"`;
+  if (type !== undefined)
+    line += ` type: ${type}`;
+  return line;
+}
+function claimTag(name, usedTags) {
+  if (name === undefined)
+    return;
+  const sanitized = sanitizeId(name);
+  if (usedTags.has(sanitized))
+    return;
+  usedTags.add(sanitized);
+  return sanitized;
+}
+function deepForkPoints(topology, baseRow, windowLength, hideContained) {
+  const behindBySha = new Map;
+  for (const row of topology.branches) {
+    if (row === baseRow)
+      continue;
+    if (row.contained && hideContained)
+      continue;
+    if (row.forkPoint.length === 0 || row.forkPoint === row.tip)
+      continue;
+    if (row.behind < windowLength)
+      continue;
+    if (!behindBySha.has(row.forkPoint))
+      behindBySha.set(row.forkPoint, row.behind);
+  }
+  return [...behindBySha].map(([sha, behind]) => ({ sha, behind })).sort((a, b) => b.behind - a.behind || (a.sha < b.sha ? -1 : 1));
+}
+function commitType(commit) {
+  return commit.subject.startsWith('Revert "') ? "REVERSE" : undefined;
+}
+function collectTags(branches) {
+  const tags = new Map;
+  for (const row of branches) {
+    for (const commit of row.commits)
+      tags.set(commit.sha, commit.tags);
+  }
+  return tags;
+}
+function isBaseRow(base, row) {
+  if (row.name === base)
+    return true;
+  if (row.kind !== "local")
+    return false;
+  return row.name === base.replace(/^[^/]+\//, "");
+}
+function short(sha) {
+  return sha.slice(0, 7);
+}
+function refToken(value, usedRefs) {
+  const id = uniqueId(sanitizeRef(value), usedRefs);
+  return /^[A-Za-z_]/.test(id) ? id : `"${id}"`;
+}
+function sanitizeId(value) {
+  return sanitizeRef(value).slice(0, 40);
+}
+function sanitizeRef(value) {
+  return value.replace(/[^A-Za-z0-9._/-]/g, "-");
+}
+function baseRowOf(topology) {
+  return topology.branches.find((row) => row.name === topology.base) ?? topology.branches.find((row) => isBaseRow(topology.base, row)) ?? null;
+}
+function uniqueId(id, usedIds) {
+  let candidate = id;
+  let suffix = 2;
+  while (usedIds.has(candidate)) {
+    candidate = `${id}-${suffix}`;
+    suffix += 1;
+  }
+  usedIds.add(candidate);
+  return candidate;
+}
+
+// ../../packages/app/src/services/branch-topology/index.ts
+var GRAPH_COMMIT_WINDOW = 10;
+var FIELD_SEP = "\x00";
+
+class BranchTopologyUsageError extends Error {
+}
+
+class BranchTopologyGitError extends Error {
+}
+function collectBranchTopology(runner, opts) {
+  const warnings = [];
+  const base = resolveBase(runner, opts.base);
+  const refs = listRefs(runner, opts.scope);
+  const worktrees = readWorktrees(runner, warnings);
+  const tagIndex = readTagIndex(runner, warnings);
+  const rows = refs.map((ref) => buildRow(runner, base.sha, ref));
+  const detached = detachedHead(runner, base.sha);
+  if (detached !== null && opts.scope !== "remote")
+    rows.push(detached);
+  for (const row of rows) {
+    row.worktree = row.kind === "detached" ? worktrees.bySha.get(row.tip) ?? null : worktrees.byBranch.get(row.name) ?? null;
+  }
+  if (opts.pr)
+    attachPullRequests(rows, readOpenPullRequests(runner, warnings));
+  const sorted = sortRows(rows);
+  const branches = sorted.slice(0, Math.max(opts.limit, 0));
+  const omitted = sorted.length - branches.length;
+  for (const row of branches) {
+    if (row.contained && !isBaseRow(base.name, row))
+      continue;
+    row.commits = readCommits(runner, row.tip, tagIndex, warnings);
+  }
+  return { base: base.name, generatedAt: new Date().toISOString(), branches, omitted, warnings };
+}
+function resolveBase(runner, explicit) {
+  const trimmed = explicit?.trim();
+  const requested = trimmed !== undefined && trimmed.length > 0 ? trimmed : undefined;
+  let candidate = requested ?? "";
+  if (candidate.length === 0) {
+    const originHead = runner(["git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+    const target = originHead.code === 0 ? originHead.stdout.trim() : "";
+    candidate = target.length > 0 ? target : "main";
+  }
+  const resolved = runner(["git", "rev-parse", "--verify", "--quiet", `${candidate}^{commit}`]);
+  if (resolved.code !== 0) {
+    if ((resolved.error ?? "").length > 0) {
+      throw new BranchTopologyGitError(`git is not available: ${resolved.error}`);
+    }
+    if (/not a git repository/i.test(resolved.stderr)) {
+      throw new BranchTopologyGitError(`not a git repository: ${failureDetail(resolved)}`);
+    }
+    throw new BranchTopologyUsageError(requested === undefined ? `unknown base ref '${candidate}' (no --base given; tried origin/HEAD, then main)` : `unknown base ref '${candidate}'`);
+  }
+  return { name: candidate, sha: resolved.stdout.trim() };
+}
+function listRefs(runner, scope) {
+  const namespaces = scope === "local" ? ["refs/heads"] : scope === "remote" ? ["refs/remotes"] : ["refs/heads", "refs/remotes"];
+  const res = runner(["git", "for-each-ref", "--format=%(refname)%00%(objectname)", ...namespaces]);
+  if (res.code !== 0)
+    throw gitFailure(res, "git for-each-ref");
+  const refs = [];
+  for (const line of res.stdout.split(`
+`)) {
+    if (line.length === 0)
+      continue;
+    const [refname, sha] = line.split(FIELD_SEP);
+    if (refname === undefined || sha === undefined || sha.length === 0)
+      continue;
+    if (refname.endsWith("/HEAD"))
+      continue;
+    if (refname.startsWith("refs/heads/")) {
+      refs.push({ name: refname.slice("refs/heads/".length), kind: "local", sha });
+    } else if (refname.startsWith("refs/remotes/")) {
+      refs.push({ name: refname.slice("refs/remotes/".length), kind: "remote", sha });
+    }
+  }
+  if (scope !== "all")
+    return refs;
+  const localTips = new Map(refs.filter((ref) => ref.kind === "local").map((ref) => [ref.name, ref.sha]));
+  return refs.filter((ref) => {
+    if (ref.kind !== "remote")
+      return true;
+    const twin = ref.name.slice(ref.name.indexOf("/") + 1);
+    return localTips.get(twin) !== ref.sha;
+  });
+}
+function buildRow(runner, baseSha, ref) {
+  const mergeBase = runner(["git", "merge-base", baseSha, ref.sha]);
+  const forkPoint = mergeBase.code === 0 ? mergeBase.stdout.trim() : "";
+  const counts = runner(["git", "rev-list", "--left-right", "--count", `${baseSha}...${ref.sha}`]);
+  if (counts.code !== 0)
+    throw gitFailure(counts, `git rev-list for ${ref.name}`);
+  const [behindRaw, aheadRaw] = counts.stdout.trim().split(/\s+/);
+  const behind = parseCount2(behindRaw, ref.name);
+  const ahead = parseCount2(aheadRaw, ref.name);
+  const log = runner(["git", "log", "-1", "--format=%H%x00%cI%x00%s", ref.sha]);
+  if (log.code !== 0)
+    throw gitFailure(log, `git log for ${ref.name}`);
+  const [tip, lastCommitAt, ...subjectParts] = log.stdout.replace(/\n$/, "").split(FIELD_SEP);
+  return {
+    name: ref.name,
+    kind: ref.kind,
+    tip: tip ?? ref.sha,
+    forkPoint,
+    ahead,
+    behind,
+    contained: ahead === 0,
+    lastCommitAt: lastCommitAt ?? "",
+    subject: subjectParts.join(FIELD_SEP),
+    worktree: null,
+    pr: null,
+    commits: []
+  };
+}
+function parseCount2(raw, ref) {
+  const parsed = Number.parseInt(raw ?? "", 10);
+  if (!Number.isInteger(parsed)) {
+    throw new BranchTopologyGitError(`git rev-list for ${ref} returned '${raw ?? ""}'`);
+  }
+  return parsed;
+}
+function detachedHead(runner, baseSha) {
+  const symbolic = runner(["git", "symbolic-ref", "--short", "-q", "HEAD"]);
+  if (symbolic.code === 0)
+    return null;
+  const head = runner(["git", "rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+  if (head.code !== 0)
+    return null;
+  const tip = head.stdout.trim();
+  return buildRow(runner, baseSha, { name: shortSha(tip), kind: "detached", sha: tip });
+}
+function sortRows(rows) {
+  const time = (row) => {
+    const parsed = Date.parse(row.lastCommitAt);
+    return Number.isFinite(parsed) ? parsed : 0;
+  };
+  return [...rows].sort((a, b) => {
+    const byTime = time(b) - time(a);
+    if (byTime !== 0)
+      return byTime;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+}
+function readWorktrees(runner, warnings) {
+  const index = { byBranch: new Map, bySha: new Map };
+  const res = runner(["git", "worktree", "list", "--porcelain"]);
+  if (res.code !== 0) {
+    warnings.push(`git worktree list failed: ${failureDetail(res)}`);
+    return index;
+  }
+  let path = "";
+  let head = "";
+  let detached = false;
+  const flush = () => {
+    if (detached && head.length > 0 && path.length > 0)
+      index.bySha.set(head, path);
+    path = "";
+    head = "";
+    detached = false;
+  };
+  for (const line of res.stdout.split(`
+`)) {
+    if (line.length === 0) {
+      flush();
+    } else if (line.startsWith("worktree ")) {
+      flush();
+      path = line.slice("worktree ".length).trim();
+    } else if (line.startsWith("HEAD ")) {
+      head = line.slice("HEAD ".length).trim();
+    } else if (line === "detached") {
+      detached = true;
+    } else if (line.startsWith("branch refs/heads/")) {
+      index.byBranch.set(line.slice("branch refs/heads/".length).trim(), path);
+    }
+  }
+  flush();
+  return index;
+}
+function readTagIndex(runner, warnings) {
+  const index = new Map;
+  const res = runner(["git", "for-each-ref", "--format=%(objectname) %(*objectname) %(refname:short)", "refs/tags"]);
+  if (res.code !== 0) {
+    warnings.push(`git for-each-ref refs/tags failed: ${failureDetail(res)}`);
+    return index;
+  }
+  for (const line of res.stdout.split(`
+`)) {
+    if (line.length === 0)
+      continue;
+    const [object, peeled, ...nameParts] = line.split(" ");
+    const name = nameParts.join(" ");
+    if (object === undefined || name.length === 0)
+      continue;
+    const target = (peeled ?? "").length > 0 ? peeled : object;
+    index.set(target, [...index.get(target) ?? [], name]);
+  }
+  return index;
+}
+function readCommits(runner, sha, tagIndex, warnings) {
+  const res = runner(["git", "log", "-n", String(GRAPH_COMMIT_WINDOW), "--format=%H%x00%s", sha]);
+  if (res.code !== 0) {
+    warnings.push(`git log for ${shortSha(sha)} failed: ${failureDetail(res)}`);
+    return [];
+  }
+  const commits = [];
+  for (const line of res.stdout.split(`
+`)) {
+    if (line.length === 0)
+      continue;
+    const [commitSha, ...subjectParts] = line.split(FIELD_SEP);
+    if (commitSha === undefined || commitSha.length === 0)
+      continue;
+    commits.push({
+      sha: commitSha,
+      subject: subjectParts.join(FIELD_SEP),
+      tags: tagIndex.get(commitSha) ?? []
+    });
+  }
+  return commits;
+}
+function readOpenPullRequests(runner, warnings) {
+  const index = new Map;
+  const res = runner([
+    "gh",
+    "pr",
+    "list",
+    "--state",
+    "open",
+    "--json",
+    "number,headRefName,state,reviewDecision",
+    "--limit",
+    "200"
+  ]);
+  if (res.code !== 0 || res.stdout.trim().length === 0) {
+    warnings.push(`--pr: gh pr list failed: ${failureDetail(res)}`);
+    return index;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.stdout);
+  } catch {
+    warnings.push("--pr: gh pr list returned unparseable JSON");
+    return index;
+  }
+  if (!Array.isArray(parsed)) {
+    warnings.push("--pr: gh pr list returned unparseable JSON");
+    return index;
+  }
+  for (const entry of parsed) {
+    const { number, headRefName, state, reviewDecision } = entry;
+    if (typeof number !== "number" || typeof headRefName !== "string")
+      continue;
+    const pr = {
+      number,
+      state: typeof state === "string" ? state : "",
+      reviewDecision: typeof reviewDecision === "string" && reviewDecision.length > 0 ? reviewDecision : null
+    };
+    const existing = index.get(headRefName);
+    if (existing === undefined || pr.number < existing.number)
+      index.set(headRefName, pr);
+  }
+  return index;
+}
+function attachPullRequests(rows, index) {
+  for (const row of rows) {
+    if (row.kind === "detached")
+      continue;
+    const keys = row.kind === "remote" ? [row.name, row.name.replace(/^[^/]+\//, "")] : [row.name];
+    row.pr = keys.map((key) => index.get(key)).find((pr) => pr !== undefined) ?? null;
+  }
+}
+function shortSha(sha) {
+  return sha.slice(0, 7);
+}
+function gitFailure(res, what) {
+  return new BranchTopologyGitError(`${what} failed: ${failureDetail(res)}`);
+}
+function failureDetail(res) {
+  const first = (res.stderr.trim() || res.stdout.trim()).split(`
+`)[0] ?? "";
+  if (first.length > 0)
+    return first;
+  return (res.error ?? "").length > 0 ? res.error : `exit ${res.code}`;
+}
+
+// src/commands/builder/show-branches.ts
+var FORMATS = ["markdown", "json", "text"];
+function registerBuilderShowBranchesCommand(builder, context) {
+  const command = builder.command("show-branches").summary("read-only branch topology report against a base (markdown | json | text)").description([
+    "Report every branch against a base ref, read-only: fork point, commits ahead/behind,",
+    "contained flag, last commit, worktree binding, and (with --pr) open pull-request state.",
+    "Base resolution: --base, else the origin/HEAD target, else main.",
+    "markdown (default) prints the summary table and one condensed mermaid gitGraph;",
+    "json prints the raw BranchTopology object; text prints the aligned table only.",
+    "Exit codes: 0 ok \xB7 1 usage (bad --format/--limit/--max-commits, unknown base ref,",
+    "--local with --remote) \xB7 2 git failure (not a repository, git missing)."
+  ].join(`
+`)).option("--format <format>", "output format: markdown | json | text (default markdown)", "markdown").option("--json", "alias of --format json (prints the raw BranchTopology object)").option("--base <ref>", "base ref to measure every branch against (default: origin/HEAD, else main)").option("--local", "only local branches").option("--remote", "only remote branches").option("--pr", "enrich rows with open pull-request state (one gh call; degrades with a warning)").option("--limit <n>", "maximum branch rows kept, most recent last-commit first (default 30)", "30").option("--max-commits <n>", "maximum commit nodes per branch line in the graph (default 3)", "3").option("--hide-contained", "drop contained branches from the graph instead of drawing their join").option("--theme <name>", "mermaid theme name for the graph init directive").action((options) => {
+    const format = resolveFormat(options.format, command.getOptionValueSource("format") === "cli", options.json === true, context);
+    if (format === null)
+      return;
+    const limit = positiveInteger(options.limit, "--limit", context);
+    if (limit === null)
+      return;
+    const maxCommits = positiveInteger(options.maxCommits, "--max-commits", context);
+    if (maxCommits === null)
+      return;
+    if (options.local === true && options.remote === true) {
+      usageError("--local and --remote are mutually exclusive", context);
+      return;
+    }
+    try {
+      const topology = collectBranchTopology(createSpawnRunner({ cwd: context.cwd, env: context.env }), {
+        ...options.base !== undefined ? { base: options.base } : {},
+        scope: options.local === true ? "local" : options.remote === true ? "remote" : "all",
+        pr: options.pr === true,
+        limit
+      });
+      if (format === "json") {
+        context.output.write(toJson2(topology));
+      } else if (format === "text") {
+        context.output.write(renderText(topology));
+      } else {
+        context.output.write(renderMarkdown2(topology, {
+          maxCommits,
+          hideContained: options.hideContained === true,
+          ...options.theme !== undefined ? { theme: options.theme } : {}
+        }));
+      }
+      context.setExitCode(0);
+    } catch (err) {
+      if (err instanceof BranchTopologyUsageError) {
+        usageError(err.message, context);
+        return;
+      }
+      if (err instanceof BranchTopologyGitError) {
+        context.output.error(err.message);
+        context.setExitCode(2);
+        return;
+      }
+      context.output.error(err instanceof Error ? err.message : String(err));
+      context.setExitCode(2);
+    }
+  });
+}
+function resolveFormat(requested, explicitFormat, json, context) {
+  if (!FORMATS.includes(requested)) {
+    usageError(`unknown --format '${requested}': expected ${FORMATS.join(" | ")}`, context);
+    return null;
+  }
+  if (!json)
+    return requested;
+  if (explicitFormat && requested !== "json") {
+    usageError(`--json conflicts with --format ${requested}`, context);
+    return null;
+  }
+  return "json";
+}
+function positiveInteger(value, flag, context) {
+  const trimmed = value.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!/^\d+$/.test(trimmed) || parsed < 1) {
+    usageError(`${flag} expects a positive integer, got '${value}'`, context);
+    return null;
+  }
+  return parsed;
+}
+function usageError(message, context) {
+  context.output.error(message);
+  context.setExitCode(1);
+}
+
 // src/commands/builder.ts
 function registerBuilderCommand(program, context) {
-  const noun = program.command("builder").summary("release plumbing: version bumps, tags, and PR-review ops");
+  const noun = program.command("builder").summary("release plumbing: version bumps, tags, branch topology, and PR-review ops");
   noun.command("bump-ver").summary("bump a package version, commit, tag, optionally push").description([
     "Bump one workspace package (or every released package with --all),",
     "rewrite workspace pins, commit, and tag. A bare version bumps all:",
@@ -144282,7 +145170,9 @@ function registerBuilderCommand(program, context) {
       context.setExitCode(1);
     }
   });
-  registerBuilderPrCommand(noun, context);
+  registerBuilderShowBranchesCommand(noun, context);
+  registerBuilderPrCommands(noun, context);
+  registerBuilderPrAliasCommand(noun, context);
 }
 
 // src/commands/decision.ts
@@ -145127,7 +146017,7 @@ import { createRequire as createRequire3 } from "module";
 var CLI_CONFIG = {
   binaryName: "spur",
   binaryLabel: "spur",
-  binaryVersion: "0.4.10",
+  binaryVersion: "0.4.11",
   configDir: ".spur",
   configFile: ".spur/config.yaml",
   databaseFile: ".spur/spur.db"
@@ -147264,7 +148154,7 @@ ${l}
   }).prompt();
 };
 var i2 = `${styleText2("gray", S_BAR)}  `;
-var text4 = (t) => new n3({
+var text5 = (t) => new n3({
   validate: t.validate,
   placeholder: t.placeholder,
   defaultValue: t.defaultValue,
@@ -147334,7 +148224,7 @@ class ClackHitlResponder {
         return { value: result };
       }
       case "input": {
-        const result = await text4({
+        const result = await text5({
           message: request.prompt
         });
         if (isCancel(result)) {
@@ -154915,7 +155805,7 @@ init_dist5();
 import { homedir as homedir16 } from "os";
 import { basename as basename20, join as join90, relative as relative19, resolve as resolve35 } from "path";
 // ../server/package.json
-var version3 = "0.4.10";
+var version3 = "0.4.11";
 
 // ../server/src/modules/health/index.ts
 var startedAt = Date.now();
@@ -162295,8 +163185,14 @@ function shouldRenderBanner(argv) {
     return false;
   if (argv[0] === "history" && argv[1] === "timeline")
     return false;
+  if (argv[0] === "builder" && argv[1] === "show-branches" && requestsJsonFormat(argv))
+    return false;
   return !argv.some((arg) => arg === "--no-logo" || arg === "--json" || arg === "--quiet" || arg === "--silent");
 }
+function requestsJsonFormat(argv) {
+  const index = argv.indexOf("--format");
+  return argv.includes("--format=json") || index !== -1 && argv[index + 1] === "json";
+}
 async function runCli() {
   const argv = process.argv.slice(2);
   if (shouldRenderBanner(argv)) {