arcane-cli 0.34.2 → 0.35.1

package/dist/index.js

@@ -6,7 +6,7 @@ const require = __createRequire(import.meta.url);
 import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname4, join as join14 } from "path";
+import { dirname as dirname5, join as join17 } from "path";
 
 // src/commands/init.ts
 import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
@@ -758,7 +758,7 @@ var WORDMARK = [
 var INDENT = "  ";
 var LOCKUP_WIDTH = INDENT.length + Math.max(...WORDMARK.map((l) => l.length));
 function sleep(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 function isAnimatable() {
   return !!process.stdout.isTTY && process.env["TERM"] !== "dumb" && process.env["CI"] !== "true" && process.env["ARCANE_DISABLE_ANIMATION"] !== "true" && (process.stdout.columns ?? 80) >= LOCKUP_WIDTH;
@@ -2030,7 +2030,7 @@ function buildGitEnv() {
 function runGit(cwd, args, options = {}) {
   const commandClass = options.commandClass ?? classifyGitCommand(args);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUTS_MS[commandClass] ?? DEFAULT_TIMEOUTS_MS.write;
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = execFile(
       "git",
       args,
@@ -2064,7 +2064,7 @@ function runGit(cwd, args, options = {}) {
           reject(error);
           return;
         }
-        resolve3({ stdout, stderr });
+        resolve4({ stdout, stderr });
       }
     );
     child.stdin?.end();
@@ -4388,8 +4388,8 @@ async function checkVSCodeExtension(id, label) {
   ];
   for (const dir of extDirs) {
     try {
-      const { readdir: readdir7 } = await import("fs/promises");
-      const entries = await readdir7(dir);
+      const { readdir: readdir8 } = await import("fs/promises");
+      const entries = await readdir8(dir);
       const prefix = id.toLowerCase() + "-";
       const found = entries.some(
         (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
@@ -5097,11 +5097,676 @@ Name did not match ("${typed.trim()}" \u2260 "${repoName}"). Nothing changed.`);
   );
 }
 
+// src/commands/report.ts
+import { access as access5 } from "fs/promises";
+import { join as join16 } from "path";
+
+// src/modules/show-report/generate.ts
+import { mkdir as mkdir7, readdir as readdir7, readFile as readFile13, writeFile as writeFile10 } from "fs/promises";
+import { basename as basename3, dirname as dirname4, isAbsolute, join as join15, relative as relative3, resolve as resolve3 } from "path";
+
+// src/modules/show-report/model.ts
+import { readFile as readFile12 } from "fs/promises";
+import { join as join14 } from "path";
+
+// src/modules/show-report/plan-parser.ts
+function parseFrontmatter(content) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  if (!match) return {};
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = /^([a-zA-Z][\w-]*):\s*(.*)$/.exec(line);
+    if (kv) fields[kv[1]] = kv[2].trim();
+  }
+  return fields;
+}
+var EPIC_START = /^- \[([ x])\] \*\*([A-Z]+-\d+) — /gm;
+var EPIC_TITLE = /^- \[[ x]\] \*\*[A-Z]+-\d+ — ([\s\S]+?)\.\*\*/;
+var HEADING_LINE = /^(#{2,3}) (.+)$/gm;
+var REPORT_LINE = /\*\*Report:\*\*\s*([\s\S]*?)\s*·\s*category:\s*(\S+)\s*·\s*glyph:\s*(\S+)/;
+var TITLE_OVERRIDE_LINE = /^\s*title:\s*(.+)$/m;
+var PR_LINK = /\[PR #(\d+)\]\((https:\/\/github\.com\/[^)\s]+\/pull\/\d+)\)/g;
+function parseEpics(content) {
+  const markers = [];
+  EPIC_START.lastIndex = 0;
+  let epicMatch;
+  while ((epicMatch = EPIC_START.exec(content)) !== null) {
+    markers.push({ index: epicMatch.index, type: "epic", id: epicMatch[2], done: epicMatch[1] === "x" });
+  }
+  HEADING_LINE.lastIndex = 0;
+  let headingMatch;
+  while ((headingMatch = HEADING_LINE.exec(content)) !== null) {
+    if (headingMatch[1] === "##") {
+      markers.push({ index: headingMatch.index, type: "h2" });
+    } else {
+      markers.push({ index: headingMatch.index, type: "h3", waveTitle: headingMatch[2].trim() });
+    }
+  }
+  markers.sort((a, b) => a.index - b.index);
+  const epics = [];
+  let currentWave = null;
+  for (let i = 0; i < markers.length; i += 1) {
+    const marker = markers[i];
+    if (marker.type === "h2") {
+      currentWave = null;
+      continue;
+    }
+    if (marker.type === "h3") {
+      currentWave = marker.waveTitle;
+      continue;
+    }
+    const blockEnd = i + 1 < markers.length ? markers[i + 1].index : content.length;
+    const block = content.slice(marker.index, blockEnd);
+    const titleMatch = EPIC_TITLE.exec(block);
+    const reportMatch = REPORT_LINE.exec(block);
+    const titleOverrideMatch = TITLE_OVERRIDE_LINE.exec(block);
+    const prLinks = [...new Set([...block.matchAll(PR_LINK)].map((m) => m[2]))];
+    epics.push({
+      id: marker.id,
+      // A title that still fails to match (e.g. a malformed bullet with no
+      // closing `.**` at all) falls back to the raw id rather than throwing --
+      // an epic missing from the report is far more visible, and therefore
+      // more likely to get fixed, than a crashed report generator.
+      title: titleMatch ? titleMatch[1].replace(/\s+/g, " ").trim() : marker.id,
+      done: marker.done,
+      wave: currentWave,
+      report: reportMatch ? {
+        description: reportMatch[1].replace(/\s+/g, " ").trim(),
+        category: reportMatch[2],
+        glyph: reportMatch[3],
+        titleOverride: titleOverrideMatch ? titleOverrideMatch[1].trim() : void 0
+      } : null,
+      prLinks,
+      block
+    });
+  }
+  return epics;
+}
+function extractSection(content, headingPrefix) {
+  const lines = content.split(/\r?\n/);
+  const startIndex = lines.findIndex((line) => line.startsWith(headingPrefix));
+  if (startIndex === -1) return null;
+  let endIndex = lines.length;
+  for (let i = startIndex + 1; i < lines.length; i += 1) {
+    if (lines[i].startsWith("## ")) {
+      endIndex = i;
+      break;
+    }
+  }
+  return lines.slice(startIndex + 1, endIndex).join("\n");
+}
+function parseParkedSection(content) {
+  const body = extractSection(content, "## Parked \u2014 Needs Operator");
+  if (body === null) return [];
+  const tableRows = [...body.matchAll(/^\|(?!---)([^|]+)\|([^|]+)\|([^|]+)\|\s*$/gm)];
+  if (tableRows.length > 1) {
+    return tableRows.slice(1).map((m) => ({
+      title: stripMarkdown(m[1].trim()),
+      reason: stripMarkdown(m[3].trim())
+    }));
+  }
+  const bulletItems = [...body.matchAll(/^- \*\*(.+?)\*\*\s*(?:\([^)]*\))?\s*—\s*(.+)$/gm)];
+  return bulletItems.map((m) => ({
+    title: stripMarkdown(m[1].trim()),
+    reason: stripMarkdown(m[2].trim())
+  }));
+}
+function computeCoverageOutcome(content) {
+  const body = extractSection(content, "## Coverage Map");
+  if (body === null) return void 0;
+  const rows = [...body.matchAll(/^\|(.+)\|\s*$/gm)].filter((m) => !/^-+\s*\|/.test(m[1].trim()));
+  if (rows.length < 2) return void 0;
+  const dataRows = rows.slice(1);
+  const parkedCount = dataRows.filter((m) => /\*\*Park(?:ed)?\*\*/i.test(m[1])).length;
+  const total = dataRows.length;
+  const dispositioned = total - parkedCount;
+  return `${total} of ${total} items dispositioned \u2014 ${dispositioned} routed to an epic, ${parkedCount} parked`;
+}
+function stripMarkdown(text) {
+  return text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\*\*/g, "").replace(/`/g, "").trim();
+}
+
+// src/modules/show-report/queue-parser.ts
+var LINK = /\[[^\]]+\]\((https?:\/\/[^)\s]+)\)/;
+function parseOperatorQueue(content) {
+  const sections = content.split(/^## /m).slice(1);
+  const entries = [];
+  for (const section of sections) {
+    const headingMatch = /^(Q-\d+)\s*—\s*(.+?)\r?\n/.exec(section);
+    if (!headingMatch) continue;
+    const id = headingMatch[1];
+    const title = headingMatch[2].trim();
+    const statusMatch = /^-\s*\*\*Status:\*\*\s*\[([ x])\]/m.exec(section);
+    const done = statusMatch ? statusMatch[1] === "x" : false;
+    const whyMatch = /^-\s*\*\*Why:\*\*\s*([\s\S]*?)(?=\r?\n-\s*\*\*|\r?\n\r?\n|$)/m.exec(section);
+    const why = whyMatch ? whyMatch[1].replace(/\s+/g, " ").trim() : null;
+    const linkMatch = LINK.exec(section);
+    entries.push({ id, title, done, why, href: linkMatch ? linkMatch[1] : void 0 });
+  }
+  return entries;
+}
+
+// src/modules/show-report/ledger-parser.ts
+function parseVerificationLedgerSection(content, programNameWords) {
+  const sections = content.split(/^## /m).slice(1);
+  const rows = [];
+  for (const section of sections) {
+    const headingLine = section.slice(0, section.indexOf("\n"));
+    if (!headingLine.toLowerCase().includes(programNameWords.toLowerCase())) continue;
+    const tableRows = [...section.matchAll(/^\|([^|]+)\|([^|]+)\|([^|]+)\|([^|]+)\|\s*$/gm)];
+    for (const m of tableRows.slice(1)) {
+      const claimCell = m[1].trim();
+      const resultCell = m[3].trim().toLowerCase();
+      const correctionCell = m[4].trim();
+      if (claimCell === "---" || claimCell.startsWith("---")) continue;
+      if (resultCell !== "confirmed" && resultCell !== "corrected" && resultCell !== "unverifiable") continue;
+      rows.push({
+        claim: stripMarkdown2(claimCell),
+        result: resultCell,
+        correction: correctionCell === "\u2014" ? null : stripMarkdown2(correctionCell)
+      });
+    }
+  }
+  return rows;
+}
+function stripMarkdown2(text) {
+  return text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\*\*/g, "").replace(/`/g, "").trim();
+}
+
+// src/modules/show-report/decisions-parser.ts
+function parseAdrs(decisionsContent) {
+  const headingPattern = /^## ARC-(\d{3})\b/gm;
+  const positions = [];
+  let match;
+  while ((match = headingPattern.exec(decisionsContent)) !== null) {
+    positions.push({ id: `ARC-${match[1]}`, index: match.index });
+  }
+  return positions.map(({ id, index }, i) => {
+    const end = i + 1 < positions.length ? positions[i + 1].index : decisionsContent.length;
+    const section = decisionsContent.slice(index, end);
+    const dateMatch = /^\*\*Date:\*\*\s*(\d{4}-\d{2}-\d{2})/m.exec(section);
+    const statusMatch = /^\*\*Status:\*\*\s*(\S+)/m.exec(section);
+    return { id, date: dateMatch ? dateMatch[1] : null, status: statusMatch ? statusMatch[1] : null };
+  });
+}
+function countAcceptedAdrsInWindow(adrs, fromDate, toDate) {
+  return adrs.filter(
+    (adr) => adr.status === "Accepted" && adr.date !== null && adr.date >= fromDate && adr.date <= toDate
+  ).length;
+}
+
+// src/modules/show-report/sources.ts
+async function runGitTextOrNull(cwd, args) {
+  try {
+    const { stdout } = await runGit(cwd, args, { commandClass: "read" });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+async function isShallowRepository(cwd) {
+  const out = await runGitTextOrNull(cwd, ["rev-parse", "--is-shallow-repository"]);
+  return out === "true";
+}
+async function getVersionAtRef(cwd, ref) {
+  const content = await runGitTextOrNull(cwd, ["show", `${ref}:package.json`]);
+  if (content === null) return null;
+  try {
+    const parsed = JSON.parse(content);
+    const version = parsed.version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+async function getCloseCommit(cwd, completedDate) {
+  if (!completedDate) {
+    const head = await runGitTextOrNull(cwd, ["rev-parse", "HEAD"]);
+    return head === null || head === "" ? null : head;
+  }
+  const log = await runGitTextOrNull(cwd, ["log", "--format=%H%x09%cs", "HEAD"]);
+  if (log === null || log === "") return null;
+  for (const line of log.split("\n")) {
+    const [sha, landed] = line.split("	");
+    if (sha && landed && landed <= completedDate) return sha;
+  }
+  return null;
+}
+async function getCast(cwd, fromRef, toRef) {
+  const ETX = "";
+  const log = await runGitTextOrNull(cwd, [
+    "log",
+    "--no-merges",
+    `--format=%B${ETX}`,
+    `${fromRef}..${toRef}`
+  ]);
+  const cast = /* @__PURE__ */ new Map();
+  if (log === null || log === "") return cast;
+  for (const body of log.split(ETX)) {
+    const personaMatch = /^Persona:\s*(.+)$/m.exec(body);
+    const agentMatch = /^Agent:\s*(.+)$/m.exec(body);
+    const name = personaMatch?.[1]?.trim() || agentMatch?.[1]?.trim();
+    if (!name) continue;
+    cast.set(name, (cast.get(name) ?? 0) + 1);
+  }
+  return cast;
+}
+
+// src/modules/show-report/model.ts
+async function readOptional(path4) {
+  try {
+    return await readFile12(path4, "utf8");
+  } catch {
+    return null;
+  }
+}
+function extractSha(baselineField) {
+  return baselineField.trim().split(/\s+/)[0];
+}
+function epicToRow(epic) {
+  const category = epic.report?.category ?? "process";
+  const row = {
+    id: epic.id,
+    title: epic.report?.titleOverride ?? epic.title,
+    description: epic.report?.description ?? null,
+    descriptionState: epic.report ? "authored" : "unwritten",
+    category,
+    // Last-cited PR link is closest, in reading order, to the epic's actual
+    // completion note (earlier links in a long Done note are often an ADR's
+    // own PR or an intermediate fix, not the epic's own shipping PR).
+    href: epic.prLinks.length > 0 ? epic.prLinks[epic.prLinks.length - 1] : void 0,
+    refs: epic.prLinks
+  };
+  if (epic.report?.glyph) row.glyph = epic.report.glyph;
+  return row;
+}
+function buildSections(epics) {
+  const waveOrder = [];
+  const byWave = /* @__PURE__ */ new Map();
+  for (const epic of epics) {
+    const wave = epic.wave ?? "Epics";
+    if (!byWave.has(wave)) {
+      byWave.set(wave, []);
+      waveOrder.push(wave);
+    }
+    byWave.get(wave).push(epic);
+  }
+  return waveOrder.map((wave, i) => ({
+    id: `wave-${i + 1}`,
+    title: wave,
+    rows: byWave.get(wave).map(epicToRow)
+  }));
+}
+function buildStats(epics, versionSpan, adrsAccepted) {
+  const done = epics.filter((e) => e.done).length;
+  const allPrs = new Set(epics.flatMap((e) => e.prLinks));
+  const stats = [
+    { id: "epics", value: `${done}/${epics.length}`, label: "epics shipped", derived: true },
+    { id: "prs", value: allPrs.size, label: "pull requests", derived: true }
+  ];
+  if (versionSpan) {
+    stats.push({
+      id: "version-span",
+      value: `${versionSpan.from} \u2192 ${versionSpan.to}`,
+      label: "version span",
+      derived: true
+    });
+  }
+  if (adrsAccepted !== null) {
+    stats.push({ id: "adrs", value: adrsAccepted, label: "ADRs accepted", derived: true });
+  }
+  return stats;
+}
+function buildNeedsYou(queueEntries) {
+  return queueEntries.filter((e) => !e.done).map((e) => {
+    const entry = { id: e.id, title: e.title, reason: e.why ?? e.title };
+    if (e.href) entry.href = e.href;
+    return entry;
+  });
+}
+function buildCorrections(ledgerRows, programName) {
+  if (ledgerRows.length === 0) return void 0;
+  const corrected = ledgerRows.filter((r) => r.result === "corrected");
+  const unverifiable = ledgerRows.filter((r) => r.result === "unverifiable").length;
+  const highlights = corrected.slice(0, 3).map((row, i) => ({
+    id: `correction-${i + 1}`,
+    title: row.claim.length > 80 ? `${row.claim.slice(0, 77)}...` : row.claim,
+    description: row.correction,
+    descriptionState: row.correction ? "authored" : "unwritten",
+    category: "fix",
+    refs: []
+  }));
+  return {
+    checked: ledgerRows.length,
+    corrected: corrected.length,
+    unverifiable,
+    scopeNote: `${programName} corrections logged in docs/verification-ledger.md`,
+    highlights
+  };
+}
+async function buildShowReportModel(options) {
+  const planAbsPath = join14(options.rootDir, options.planRelPath);
+  const queueAbsPath = join14(options.rootDir, options.queueRelPath);
+  const ledgerRelPath = "docs/verification-ledger.md";
+  const ledgerAbsPath = join14(options.rootDir, ledgerRelPath);
+  const decisionsAbsPath = join14(options.rootDir, "DECISIONS.md");
+  const [planContent, queueContent, ledgerContent, decisionsContent] = await Promise.all([
+    readFile12(planAbsPath, "utf8"),
+    readOptional(queueAbsPath),
+    readOptional(ledgerAbsPath),
+    readOptional(decisionsAbsPath)
+  ]);
+  const frontmatter = parseFrontmatter(planContent);
+  const epics = parseEpics(planContent);
+  const parked = parseParkedSection(planContent);
+  const outcome = computeCoverageOutcome(planContent);
+  const queueEntries = queueContent ? parseOperatorQueue(queueContent) : [];
+  const ledgerRows = ledgerContent ? parseVerificationLedgerSection(ledgerContent, options.ledgerProgramName) : [];
+  const adrsAccepted = decisionsContent && frontmatter.created ? countAcceptedAdrsInWindow(
+    parseAdrs(decisionsContent),
+    frontmatter.created,
+    frontmatter.completed ?? options.compiledAt.slice(0, 10)
+  ) : null;
+  let versionSpan;
+  const cast = /* @__PURE__ */ new Map();
+  if (frontmatter.baseline) {
+    const baselineSha = extractSha(frontmatter.baseline);
+    const closeSha = await getCloseCommit(options.rootDir, frontmatter.completed);
+    if (closeSha) {
+      const [from, to, castMap] = await Promise.all([
+        getVersionAtRef(options.rootDir, baselineSha),
+        getVersionAtRef(options.rootDir, closeSha),
+        getCast(options.rootDir, baselineSha, closeSha)
+      ]);
+      if (from && to) versionSpan = { from, to };
+      for (const [name, count] of castMap) cast.set(name, count);
+    }
+  }
+  const done = epics.filter((e) => e.done).length;
+  const title = frontmatter.title ?? options.slug;
+  const corrections = buildCorrections(ledgerRows, options.ledgerProgramName);
+  return {
+    schemaVersion: 1,
+    program: {
+      id: options.slug,
+      slug: options.slug,
+      title,
+      status: frontmatter.status ?? "unknown",
+      baseline: frontmatter.baseline ?? "unknown",
+      started: frontmatter.created ?? "unknown",
+      ...frontmatter.completed ? { completed: frontmatter.completed } : {},
+      ...versionSpan ? { versionSpan } : {}
+    },
+    masthead: {
+      eyebrow: "Show Report",
+      title,
+      dek: `${frontmatter.status ?? "unknown"} \u2014 ${done} of ${epics.length} epics shipped`
+    },
+    stats: buildStats(epics, versionSpan, adrsAccepted),
+    ...outcome ? { outcome } : {},
+    needsYou: buildNeedsYou(queueEntries),
+    sections: buildSections(epics),
+    ...corrections ? { corrections } : {},
+    parked,
+    cast: [...cast.entries()].map(([name, commits]) => ({ name, commits, source: "commit-trailer" })),
+    colophon: {
+      sources: [options.planRelPath, options.queueRelPath, ledgerRelPath],
+      compiledAt: options.compiledAt,
+      templateVersion: options.templateVersion
+    }
+  };
+}
+
+// src/modules/show-report/render.ts
+import Mustache from "mustache";
+var CATEGORY_LABELS = {
+  spell: "New Spell",
+  feature: "New Feature",
+  governance: "Governance",
+  decision: "Decision (ADR)",
+  fix: "Bug Fix",
+  process: "Process",
+  docs: "Docs",
+  platform: "Platform"
+};
+var CATEGORY_ORDER = [
+  "spell",
+  "feature",
+  "governance",
+  "decision",
+  "fix",
+  "process",
+  "docs",
+  "platform"
+];
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function inlineMarkupToHtml(text) {
+  const escaped = escapeHtml(text);
+  const withLinks = escaped.replace(
+    /\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g,
+    '<a href="$2">$1</a>'
+  );
+  return withLinks.replace(/`([^`]+)`/g, "<code>$1</code>");
+}
+function toRowView(row) {
+  return {
+    ...row,
+    categoryLabel: CATEGORY_LABELS[row.category] ?? row.category,
+    descriptionHtml: row.description === null ? null : inlineMarkupToHtml(row.description),
+    isUnwritten: row.descriptionState === "unwritten",
+    hasHref: typeof row.href === "string" && row.href.length > 0,
+    hasGlyph: typeof row.glyph === "string" && row.glyph.length > 0
+  };
+}
+function buildShowReportView(model) {
+  const corrections = model.corrections ? { ...model.corrections, highlights: model.corrections.highlights.map(toRowView) } : void 0;
+  return {
+    ...model,
+    sections: model.sections.map((section) => ({
+      ...section,
+      hasNote: typeof section.note === "string" && section.note.length > 0,
+      rows: section.rows.map(toRowView)
+    })),
+    corrections,
+    hasCorrections: corrections !== void 0,
+    hasParked: model.parked.length > 0,
+    hasCast: model.cast.length > 0,
+    hasOutcome: typeof model.outcome === "string" && model.outcome.length > 0,
+    hasVersionSpan: model.program.versionSpan !== void 0,
+    needsYouCount: model.needsYou.length,
+    compiledAtDate: model.colophon.compiledAt.slice(0, 10),
+    legend: CATEGORY_ORDER.map((key) => ({ key, label: CATEGORY_LABELS[key] })),
+    sourcesJoined: model.colophon.sources.join(", ")
+  };
+}
+function renderShowReport(model, templateHtml) {
+  return Mustache.render(templateHtml, buildShowReportView(model), void 0, {
+    escape: (value) => escapeHtml(String(value))
+  });
+}
+
+// src/modules/show-report/generate.ts
+var TEMPLATE_VERSION = "v0-interim";
+var NO_EPICS_REASON = "no parseable `- [x] **ID \u2014 Title.**` epic bullets";
+function programNameFromTitle(title) {
+  return title.split(" \u2014 ")[0].trim();
+}
+function deterministicCompiledAt(frontmatter) {
+  return frontmatter.completed ?? frontmatter.activated ?? frontmatter.created ?? "unknown";
+}
+function toPosix(path4) {
+  return path4.replace(/\\/g, "/");
+}
+async function programFromPlan(rootDir, slug, planRelPath) {
+  let planContent;
+  try {
+    planContent = await readFile13(join15(rootDir, planRelPath), "utf8");
+  } catch {
+    return { skipped: { slug, reason: `no PLAN.md at ${planRelPath}` } };
+  }
+  if (parseEpics(planContent).length === 0) {
+    return { skipped: { slug, reason: NO_EPICS_REASON } };
+  }
+  const frontmatter = parseFrontmatter(planContent);
+  return {
+    program: {
+      slug,
+      planRelPath,
+      queueRelPath: toPosix(join15(dirname4(planRelPath), "OPERATOR-QUEUE.md")),
+      ledgerProgramName: programNameFromTitle(frontmatter.title ?? slug)
+    }
+  };
+}
+async function discoverPrograms(rootDir) {
+  const plansDir = join15(rootDir, "docs", "plans");
+  let entries;
+  try {
+    entries = (await readdir7(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
+  } catch (error) {
+    if (error.code === "ENOENT") return { programs: [], skipped: [] };
+    throw error;
+  }
+  const programs = [];
+  const skipped = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const result = await programFromPlan(rootDir, entry.name, `docs/plans/${entry.name}/PLAN.md`);
+    if (result.program) programs.push(result.program);
+    if (result.skipped) skipped.push(result.skipped);
+  }
+  return { programs, skipped };
+}
+async function programFromPlanPath(rootDir, planPath) {
+  const planAbs = isAbsolute(planPath) ? planPath : resolve3(rootDir, planPath);
+  const planRelPath = toPosix(relative3(rootDir, planAbs));
+  return programFromPlan(rootDir, basename3(dirname4(planAbs)), planRelPath);
+}
+function normalizeLineEndings(content) {
+  return content.replace(/\r\n?/g, "\n");
+}
+async function readOptionalFile(path4) {
+  try {
+    return await readFile13(path4, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function generateReport(rootDir, program2, templateHtml) {
+  const planContent = await readFile13(join15(rootDir, program2.planRelPath), "utf8");
+  const frontmatter = parseFrontmatter(planContent);
+  const model = await buildShowReportModel({
+    rootDir,
+    slug: program2.slug,
+    planRelPath: program2.planRelPath,
+    queueRelPath: program2.queueRelPath,
+    ledgerProgramName: program2.ledgerProgramName,
+    compiledAt: deterministicCompiledAt(frontmatter),
+    templateVersion: TEMPLATE_VERSION
+  });
+  return {
+    json: `${JSON.stringify(model, null, 2)}
+`,
+    html: renderShowReport(model, templateHtml)
+  };
+}
+async function runReportGeneration(options) {
+  const templateHtml = await readFile13(options.templatePath, "utf8");
+  const drifted = [];
+  const repaired = [];
+  const unwritten = [];
+  for (const program2 of options.programs) {
+    const generated = await generateReport(options.rootDir, program2, templateHtml);
+    const missing = JSON.parse(generated.json).sections.flatMap((section) => section.rows).filter((row) => row.descriptionState === "unwritten").map((row) => row.id);
+    if (missing.length > 0) unwritten.push({ slug: program2.slug, ids: missing });
+    const outAbs = options.outDir ? isAbsolute(options.outDir) ? options.outDir : resolve3(options.rootDir, options.outDir) : resolve3(options.rootDir, dirname4(program2.planRelPath));
+    const outRel = toPosix(relative3(options.rootDir, outAbs));
+    const outputs = [
+      [`${outRel}/show-report.json`, generated.json],
+      [`${outRel}/show-report.html`, generated.html]
+    ];
+    for (const [relPath, expected] of outputs) {
+      const actual = await readOptionalFile(join15(options.rootDir, relPath));
+      if (actual === null || normalizeLineEndings(actual) !== normalizeLineEndings(expected)) {
+        drifted.push(`${relPath} does not match a regeneration from its sources.`);
+        if (options.mode === "write") {
+          await mkdir7(outAbs, { recursive: true });
+          await writeFile10(join15(options.rootDir, relPath), expected, "utf8");
+          repaired.push(relPath);
+        }
+      }
+    }
+  }
+  return { drifted, repaired, unwritten };
+}
+
+// src/commands/report.ts
+async function runReport(targetDir, options = {}, assetsDir) {
+  const templatePath = join16(assetsDir, "report", "show-report.template.html");
+  try {
+    await access5(templatePath);
+  } catch {
+    console.error(
+      `\u2716 arcane: report template not found at ${templatePath} -- this arcane-cli build is missing dist/assets/report/. Reinstall the package (or run \`npm run build\` in a source checkout).`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (options.refresh) {
+    console.log(
+      "--refresh: external-data snapshotting (gh PR titles/merge dates) is not implemented yet; regenerating from local sources."
+    );
+  }
+  if (await isShallowRepository(targetDir)) {
+    console.warn(
+      "\u26A0 arcane: shallow clone -- the report's version span and cast are derived from git history and will be omitted. Run `git fetch --unshallow` for a complete report."
+    );
+  }
+  let programs;
+  let skipped;
+  if (options.plan) {
+    const result2 = await programFromPlanPath(targetDir, options.plan);
+    programs = result2.program ? [result2.program] : [];
+    skipped = result2.skipped ? [result2.skipped] : [];
+  } else {
+    const discovery = await discoverPrograms(targetDir);
+    programs = discovery.programs;
+    skipped = discovery.skipped;
+  }
+  for (const s of skipped) console.log(`Skipped ${s.slug} -- ${s.reason}.`);
+  if (programs.length === 0) {
+    console.error(
+      "\u2716 arcane: no program to report on -- expected docs/plans/<slug>/PLAN.md with `- [x] **ID \u2014 Title.**` epic bullets, or pass --plan <path>."
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const result = await runReportGeneration({
+    rootDir: targetDir,
+    templatePath,
+    mode: "write",
+    programs,
+    outDir: options.out
+  });
+  for (const u of result.unwritten) {
+    console.warn(
+      `\u26A0 arcane: ${u.slug} has ${u.ids.length} epic(s) with no \`**Report:**\` line in PLAN.md -- they render as "unwritten": ${u.ids.join(", ")}.`
+    );
+  }
+  if (result.repaired.length === 0) {
+    console.log(`Show report: ${programs.length} program(s) already up to date.`);
+    return;
+  }
+  console.log(`Show report: wrote ${result.repaired.length} file(s).`);
+  for (const path4 of result.repaired) console.log(`  ${path4}`);
+}
+
 // src/index.ts
 import { realpathSync } from "fs";
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
-var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join14(dirname4(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join17(dirname5(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 program.name("spell").description("Arcane framework CLI \u2014 scaffold and manage governance files").version(pkg.version).action(async () => {
   if (program.args.length > 0) {
@@ -5179,6 +5844,14 @@ program.command("ward").description("Scan the repo for leaked identifiers -- thi
 ).option("--gate", "Exit non-zero if any leak is found (for CI)").action(async (opts) => {
   await runWardCli(process.cwd(), opts);
 });
+program.command("report").description(
+  "Generate a program's Show Report (show-report.json + .html) from docs/plans/<slug>/PLAN.md, OPERATOR-QUEUE.md and the verification ledger -- offline, no network (ARC-042)"
+).option("--plan <path>", "Report on one PLAN.md instead of auto-discovering docs/plans/*/PLAN.md").option("--out <dir>", "Write show-report.{json,html} into this directory instead of next to the plan").option(
+  "--refresh",
+  "Accepted for forward compatibility; external-data snapshotting is not implemented yet, so this regenerates from local sources"
+).action(async (opts) => {
+  await runReport(process.cwd(), opts, ASSETS_DIR);
+});
 var agentsCommand = program.command("agents").description("Manage the portable agent system (init, sync, list)");
 agentsCommand.command("init").description(
   "Interactive agent roster setup \u2014 choose profile, naming strategy, and install definitions"