@pknx/waterfall-cli 0.1.0

package/lib/cli/commands/bug-start.ts

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { gitExecSync } from "../git/git-cli";
+import { assertSpecRoot } from "../spec/spec-root";
+import { scaffoldHeadingFromDescription, slugifyDescription } from "../core/slug";
+import { parseWorkItemCanonicalId } from "../comments/item-comments";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveBugParentSysDir, writeBugToSpec } from "../work-items/write-bug-to-spec";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+type NumberJson = { next: { BUG: number } };
+
+function git(specRoot: string, args: string[]): void {
+  gitExecSync(specRoot, args, { stdio: "inherit" });
+}
+
+function formatBugPad(n: number): string {
+  return String(n).padStart(3, "0");
+}
+
+/**
+ * Scaffold BUG under `technical/SYS-…/`, bump `number.json` `next.BUG`, commit.
+ * @param hint Resolved operator hint (same rules as `resolveOperatorHint`): steers the agent and supplies title/slug for the scaffold.
+ */
+export function runBugStart(
+  specRoot: string,
+  sysIdRaw: string,
+  hint: string,
+): { canonicalId: string; mdRel: string } {
+  assertSpecRoot(specRoot);
+  const { prefix, canonicalId: sysCanon } = parseWorkItemCanonicalId(sysIdRaw);
+  if (prefix !== "SYS") {
+    throw new Error(
+      `bug start: first argument must be SYS-NNN (got "${sysIdRaw.trim()}")`,
+    );
+  }
+
+  const parent = resolveBugParentSysDir(specRoot, sysCanon);
+  if (!parent) {
+    throw new Error(
+      `bug start: no folder matching ${sysCanon} under technical/ (create the subsystem with \`waterfall sys start\` first)`,
+    );
+  }
+
+  const slug = slugifyDescription(hint);
+  const numPath = path.join(specRoot, "number.json");
+  const raw = JSON.parse(fs.readFileSync(numPath, "utf8")) as NumberJson;
+  const n = raw.next.BUG;
+  if (typeof n !== "number") {
+    throw new Error(
+      "bug start: number.json missing next.BUG (re-run spec init or add BUG: 1)",
+    );
+  }
+  const pad = formatBugPad(n);
+  const canonicalId = `BUG-${pad}`;
+  const headingTitle = scaffoldHeadingFromDescription(hint, slug);
+
+  const steeringLines = hint
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => (line.length > 0 ? `> ${line}` : ">"));
+  const steeringBlock =
+    steeringLines.length > 0 ? steeringLines.join("\n") : "> _(empty)_";
+
+  const summaryBody = `*(Replace with defect summary, repro steps, expected vs actual, and links per \`prompts/items/bug-document-structure.md\`. **Synthesize** from **Draft steering (CLI)** below — remove that section when done.)*
+
+## Draft steering (CLI)
+
+The operator supplied this when running \`waterfall bug start\`. **Scratch input only**:
+
+${steeringBlock}
+`;
+
+  const { mdRel } = writeBugToSpec({
+    specRoot,
+    canonicalId,
+    title: headingTitle,
+    state: "draft",
+    sysId: sysCanon,
+    summaryBody,
+    parentDir: parent,
+  });
+
+  raw.next.BUG = n + 1;
+  fs.writeFileSync(numPath, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+
+  git(specRoot, ["add", mdRel, "number.json"]);
+  git(specRoot, ["commit", "-m", `feat(${canonicalId}): scaffold bug`]);
+
+  return { canonicalId, mdRel };
+}
+
+export const bugStartCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "bug" && r[1] === "start",
+  run(ctx, rest) {
+    const [, , sysRaw, a3, ...tail] = rest;
+    if (!sysRaw?.trim()) {
+      throw new Error("bug start: SYS-NNN is required (e.g. waterfall bug start SYS-001 …)");
+    }
+    const { text } = resolveOperatorHint([a3, ...tail].filter(Boolean), {
+      required: true,
+    });
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall bug start");
+    runBugStart(ctx.specRoot, sysRaw, text);
+    ctx.runAgentPrompt(
+      "prompts/commands/bug-start.md",
+      text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+      "waterfall bug start — refine BUG Summary",
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/comment-add.ts

@@ -0,0 +1,47 @@
+import { assertBranchDevelop } from "../git/git-branch-guards";
+import { assertSpecRoot } from "../spec/spec-root";
+import path from "node:path";
+import {
+  ITEM_COMMENT_PREFIXES,
+  addItemComment,
+  parseWorkItemCanonicalId,
+  resolveItemCommentStorage,
+} from "../comments/item-comments";
+import type { WaterfallCommand } from "./types";
+
+const LABEL = "waterfall comment add";
+
+export const commentAddCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "comment" && r[1] === "add",
+  run(ctx, rest) {
+    assertSpecRoot(ctx.specRoot);
+    assertBranchDevelop(ctx.specRoot, LABEL);
+    const item = rest[2];
+    const email = rest[3];
+    const from = rest[4];
+    const hintParts = rest.slice(5);
+    if (!item?.trim() || !email?.trim() || !from?.trim() || hintParts.length === 0) {
+      throw new Error(
+        `${LABEL}: usage: waterfall comment add <ITEM-ID> <email> <display-name> <hint…>  (ITEM-ID: ${ITEM_COMMENT_PREFIXES.join(", ")}-NNN)`,
+      );
+    }
+    const { canonicalId } = parseWorkItemCanonicalId(item);
+    const { commentsPath } = resolveItemCommentStorage(ctx.specRoot, canonicalId);
+    const hint = hintParts.join(" ").trim();
+    if (!hint) {
+      throw new Error(`${LABEL}: hint must not be empty`);
+    }
+    addItemComment({
+      commentsPath,
+      itemId: canonicalId,
+      email: email.trim(),
+      from: from.trim(),
+      hint,
+    });
+    const rel = path.relative(ctx.specRoot, commentsPath).split(path.sep).join("/");
+    process.stdout.write(
+      `[waterfall] Appended OPEN comment to ${canonicalId} → ${rel}\n`,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/cr-all.ts

@@ -0,0 +1,18 @@
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { ORCHESTRATE_CR_ALL_ORDER } from "../core/prompt-map";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const crAllCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "cr" && r[1] === "all",
+  run(ctx, rest) {
+    const tail = rest.slice(2);
+    ctx.runOrchestrate(
+      ORCHESTRATE_CR_ALL_ORDER,
+      "waterfall cr all",
+      resolveOperatorHint(tail, { required: false }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/cr-finish.ts

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { gitExecSync } from "../git/git-cli";
+import { assertSpecRoot } from "../spec/spec-root";
+import type { WaterfallCommand } from "./types";
+
+function gitInherit(specRoot: string, args: string[]): void {
+  gitExecSync(specRoot, args, { stdio: "inherit" });
+}
+
+function gitCapture(specRoot: string, args: string[]): string {
+  return gitExecSync(specRoot, args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).toString();
+}
+
+/** Parse `001` from `feature/CR-001-slug`. */
+export function parseCrBranchId(branch: string): string | undefined {
+  const m = branch.match(/^feature\/CR-(\d{3})(?:-.+)?$/);
+  return m?.[1];
+}
+
+function assertNumberJson(specRoot: string): void {
+  const p = path.join(specRoot, "number.json");
+  let raw: string;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch {
+    throw new Error(`cr finish: number.json missing (${p})`);
+  }
+  try {
+    const o = JSON.parse(raw) as { next?: Record<string, unknown> };
+    if (!o || typeof o !== "object" || !o.next || typeof o.next !== "object") {
+      throw new Error("cr finish: number.json must contain a next object");
+    }
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      throw new Error(`cr finish: number.json is not valid JSON (${e.message})`);
+    }
+    throw e;
+  }
+}
+
+/**
+ * True if `changerequests/CR-<digits>-<slug>/CR-<digits>.md` exists for this CR.
+ */
+export function crMarkdownPresentForFinish(specRoot: string, crDigits: string): boolean {
+  const dir = path.join(specRoot, "changerequests");
+  if (!fs.existsSync(dir)) {
+    return false;
+  }
+  const prefix = `CR-${crDigits}-`;
+  const innerName = `CR-${crDigits}.md`;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const ent of entries) {
+    if (!ent.isDirectory() || !ent.name.startsWith(prefix)) continue;
+    if (fs.existsSync(path.join(dir, ent.name, innerName))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function assertCrMarkdownPresent(specRoot: string, crDigits: string): void {
+  if (!crMarkdownPresentForFinish(specRoot, crDigits)) {
+    const prefix = `CR-${crDigits}-`;
+    throw new Error(
+      `cr finish: no changerequests/${prefix}*/CR-${crDigits}.md for CR-${crDigits}`,
+    );
+  }
+}
+
+function assertWorkingTreeClean(specRoot: string): void {
+  const s = gitCapture(specRoot, ["status", "--porcelain"]).trim();
+  if (s.length > 0) {
+    throw new Error(
+      "cr finish: working tree is not clean after commit; stash or commit remaining changes",
+    );
+  }
+}
+
+function assertAheadOfDevelop(specRoot: string): void {
+  const n = gitCapture(specRoot, ["rev-list", "--count", "develop..HEAD"]).trim();
+  const count = parseInt(n, 10);
+  if (!Number.isFinite(count) || count < 1) {
+    throw new Error(
+      "cr finish: branch has no commits ahead of develop; nothing to integrate",
+    );
+  }
+}
+
+function assertNonEmptyDiffVsDevelop(specRoot: string): void {
+  const diff = gitCapture(specRoot, ["diff", "develop...HEAD"]);
+  if (diff.trim().length === 0) {
+    throw new Error(
+      "cr finish: git diff develop...HEAD is empty (no file changes vs develop)",
+    );
+  }
+}
+
+function assertNoProtectedPathsInDiff(specRoot: string): void {
+  const names = gitCapture(specRoot, ["diff", "develop...HEAD", "--name-only"]);
+  const lines = names
+    .split("\n")
+    .map((l) => l.trim().replace(/\\/g, "/"))
+    .filter(Boolean);
+  const bad: string[] = [];
+  for (const line of lines) {
+    if (line === "CURSOR.md" || line.startsWith("schemas/")) {
+      bad.push(line);
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      `cr finish: diff vs develop touches ${bad.join(", ")} — revert or finish without those paths in this CR`,
+    );
+  }
+}
+
+/**
+ * Mechanical finish: validate branch and spec/git invariants, commit WIP, merge into develop.
+ * Substance (complete CR text, links, triage) is validated via prompts/commands/cr-finish.md only.
+ */
+export function runCrFinish(specRoot: string): void {
+  assertSpecRoot(specRoot);
+  const branch = gitCapture(specRoot, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+  if (!/^feature\/CR-\d/.test(branch)) {
+    throw new Error(
+      `cr finish: expected branch feature/CR-* on spec repo, got "${branch}"`,
+    );
+  }
+
+  const crDigits = parseCrBranchId(branch);
+  if (!crDigits) {
+    throw new Error(
+      `cr finish: branch must look like feature/CR-<NNN> or feature/CR-<NNN>-<slug>, got "${branch}"`,
+    );
+  }
+
+  assertNumberJson(specRoot);
+  assertCrMarkdownPresent(specRoot, crDigits);
+
+  gitInherit(specRoot, ["add", "-A"]);
+  try {
+    gitExecSync(specRoot, ["diff", "--cached", "--quiet"], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch {
+    gitInherit(specRoot, ["commit", "-m", `chore: finish ${branch}`]);
+  }
+
+  assertWorkingTreeClean(specRoot);
+  assertAheadOfDevelop(specRoot);
+  assertNonEmptyDiffVsDevelop(specRoot);
+  assertNoProtectedPathsInDiff(specRoot);
+
+  gitInherit(specRoot, ["checkout", "develop"]);
+  gitInherit(specRoot, [
+    "merge",
+    branch,
+    "--no-ff",
+    "-m",
+    `Merge branch '${branch}' into develop`,
+  ]);
+}
+
+export const crFinishCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "cr" && r[1] === "finish",
+  run(ctx) {
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall cr finish");
+    runCrFinish(ctx.specRoot);
+    return 0;
+  },
+};

package/lib/cli/commands/cr-start.ts

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertBranchForCrStart } from "../git/git-branch-guards";
+import { gitExecSync } from "../git/git-cli";
+import { assertSpecRoot } from "../spec/spec-root";
+import {
+  formatCrId,
+  scaffoldHeadingFromDescription,
+  slugifyDescription,
+} from "../core/slug";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+type NumberJson = { next: { CR: number } };
+
+function git(specRoot: string, args: string[]): void {
+  gitExecSync(specRoot, args, { stdio: "inherit" });
+}
+
+/**
+ * Implements waterfall-spec/prompts/cr-start.md on disk + git.
+ * Mutates spec repo: new branch, new CR files, number.json bump, commit.
+ */
+export function runCrStart(specRoot: string, description: string): void {
+  assertSpecRoot(specRoot);
+  assertBranchForCrStart(specRoot);
+  const slug = slugifyDescription(description);
+  const numPath = path.join(specRoot, "number.json");
+  const raw = JSON.parse(fs.readFileSync(numPath, "utf8")) as NumberJson;
+  const n = raw.next.CR;
+  const id = formatCrId(n);
+  const branch = `feature/CR-${id}-${slug}`;
+  const base = `CR-${id}-${slug}`;
+
+  try {
+    git(specRoot, ["pull", "--ff-only"]);
+  } catch {
+    /* optional remote */
+  }
+  git(specRoot, ["checkout", "-b", branch]);
+
+  const crDir = path.join(specRoot, "changerequests", base);
+  fs.mkdirSync(crDir, { recursive: true });
+  const mdPath = path.join(crDir, `CR-${id}.md`);
+  const headingTitle = scaffoldHeadingFromDescription(description, slug);
+  const steeringLines = description
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => (line.length > 0 ? `> ${line}` : ">"));
+  const steeringBlock =
+    steeringLines.length > 0 ? steeringLines.join("\n") : "> _(empty)_";
+
+  const md = `# CR-${id} — ${headingTitle}
+
+**Id:** CR-${id}  
+**Status:** draft
+
+## Summary
+
+*(Replace with a concise stakeholder summary per \`prompts/items/cr-document-structure.md\`. **Do not** treat the CLI text as final copy — synthesize product intent from **Draft steering (CLI)** below, then remove that section.)*
+
+## Proposed change
+
+*(Add subsections per the same structure guide — derived from draft steering, not a verbatim paste of it.)*
+
+## Draft steering (CLI)
+
+The operator supplied this when running \`waterfall cr start\`. **Scratch input only** — not canonical spec prose:
+
+${steeringBlock}
+
+## Links and dependencies
+
+### Downstream references
+
+- (add RQ/UC links when triaged)
+`;
+
+  fs.writeFileSync(mdPath, md, "utf8");
+
+  raw.next.CR = n + 1;
+  fs.writeFileSync(numPath, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+
+  git(specRoot, ["add", `changerequests/${base}/CR-${id}.md`, "number.json"]);
+  git(specRoot, ["commit", "-m", `feat(CR-${id}): scaffold change request`]);
+}
+
+export const crStartCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "cr" && r[1] === "start",
+  run(ctx, rest) {
+    const [, , a2, ...tail] = rest;
+    const { text } = resolveOperatorHint([a2, ...tail].filter(Boolean), {
+      required: true,
+    });
+    runCrStart(ctx.specRoot, text);
+    ctx.runAgentPrompt(
+      "prompts/commands/cr-start.md",
+      text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+      "waterfall cr start — refine CR prose",
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/cr-to-rq.ts

@@ -0,0 +1,18 @@
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const crToRqCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "cr" && r[1] === "to" && r[2] === "rq",
+  run(ctx, rest) {
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall cr to rq");
+    const tail = rest.slice(3);
+    ctx.runAgentPrompt(
+      "prompts/commands/cr-to-rq.md",
+      resolveOperatorHint(tail, { required: true }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/export-pdf.ts

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { traceExportPdfLine } from "../core/cli-log";
+import {
+  assertSpecRepoCleanForExport,
+  resolveExportPdfOutputPath,
+} from "../export/export-pdf-path";
+import {
+  DEFAULT_EXPORT_ITEMS,
+  filterMarkdownPathsByExportItems,
+  parseExportItemsList,
+  validateExportItemCodes,
+} from "../export/export-items";
+import { collectMarkdownFiles } from "../export/collect-md";
+import { mergeMarkdownFiles } from "../export/merge-md";
+import { readPomProjectTitle } from "../project/pom-json";
+import {
+  describeMmdcResolution,
+  renderMermaidBlocksToPng,
+} from "../export/mermaid-run";
+import {
+  bundledPdfWorkerScriptPath,
+  runBundledMarkdownToPdf,
+} from "../export/pdf-bundled";
+import {
+  buildNativePandocArgs,
+  resolvePandocExecutable,
+  runNativePandocPdf,
+} from "../export/pandoc-pdf";
+import type { WaterfallCommand } from "./types";
+
+function shellWords(argv: string[]): string {
+  return argv
+    .map((a) => (/[\s'"\\]/.test(a) ? JSON.stringify(a) : a))
+    .join(" ");
+}
+
+function parseExportPdfArgs(tail: string[]): {
+  output?: string;
+  items: string[];
+} {
+  let output: string | undefined;
+  let items: string[] | undefined;
+  for (let i = 0; i < tail.length; i++) {
+    const t = tail[i]!;
+    if (t === "--output" || t === "-o") {
+      const v = tail[++i];
+      if (!v || v.startsWith("-")) {
+        throw new Error("--output / -o requires a path");
+      }
+      output = v;
+      continue;
+    }
+    if (t === "--items" || t === "-items") {
+      const v = tail[++i];
+      if (!v || v.startsWith("-")) {
+        throw new Error("--items requires a comma-separated list (e.g. CR,RQ,UC,HOR,TST)");
+      }
+      items = parseExportItemsList(v);
+      continue;
+    }
+    if (/^--items=/i.test(t) || /^-items=/i.test(t)) {
+      const v = t.slice(t.indexOf("=") + 1).trim();
+      if (!v) {
+        throw new Error("--items= requires a comma-separated list");
+      }
+      items = parseExportItemsList(v);
+      continue;
+    }
+    if (t.startsWith("-")) {
+      throw new Error(`Unknown option: ${t}`);
+    }
+    throw new Error(
+      `Unexpected argument: ${t} (use --items CR,RQ,... and/or -o PATH; see waterfall help)`,
+    );
+  }
+  const resolvedItems = items ?? [...DEFAULT_EXPORT_ITEMS];
+  validateExportItemCodes(resolvedItems);
+  return { output, items: resolvedItems };
+}
+
+export const exportPdfCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "export" && r[1] === "pdf",
+  run(ctx, rest) {
+    let opts: { output?: string; items: string[] };
+    try {
+      opts = parseExportPdfArgs(rest.slice(2));
+    } catch (e) {
+      process.stderr.write(`${(e as Error).message}\n`);
+      return 1;
+    }
+
+    const specRoot = ctx.specRoot;
+    try {
+      assertSpecRepoCleanForExport(specRoot);
+    } catch (e) {
+      process.stderr.write(`${(e as Error).message}\n`);
+      return 1;
+    }
+
+    const allMd = collectMarkdownFiles(specRoot);
+    const itemSet = new Set(opts.items);
+    const mdFiles = filterMarkdownPathsByExportItems(allMd, specRoot, itemSet);
+    if (allMd.length === 0) {
+      process.stderr.write(`[waterfall] No .md files found under ${specRoot}\n`);
+      return 1;
+    }
+    if (mdFiles.length === 0) {
+      process.stderr.write(
+        `[waterfall] No markdown matched export --items ${opts.items.join(",")} (under ${specRoot})\n`,
+      );
+      return 1;
+    }
+
+    const docTitle = readPomProjectTitle(specRoot);
+    const merged = mergeMarkdownFiles(specRoot, mdFiles, docTitle);
+    let pdfOut: string;
+    try {
+      pdfOut = resolveExportPdfOutputPath(specRoot, ctx.g.cwd, opts.output);
+    } catch (e) {
+      process.stderr.write(`${(e as Error).message}\n`);
+      return 1;
+    }
+    fs.mkdirSync(path.dirname(pdfOut), { recursive: true });
+
+    const log = ctx.g.logLevel;
+    traceExportPdfLine(log, `export pdf · spec_root=${specRoot}`);
+    traceExportPdfLine(log, `export pdf · items=${opts.items.join(",")}`);
+    traceExportPdfLine(log, `export pdf · title=${docTitle}`);
+    traceExportPdfLine(log, `export pdf · output=${pdfOut}`);
+    traceExportPdfLine(
+      log,
+      `export pdf · use_native_pandoc=${ctx.g.useNativePandoc}`,
+    );
+    traceExportPdfLine(
+      log,
+      `export pdf · markdown files=${mdFiles.length} (matched) / ${allMd.length} (total .md under spec)`,
+    );
+
+    let workDir: string | undefined;
+    try {
+      workDir = fs.mkdtempSync(path.join(os.tmpdir(), "waterfall-export-"));
+      const mermaidBlocks = merged.match(/```mermaid/gi) ?? [];
+      traceExportPdfLine(
+        log,
+        `export pdf · mermaid: ${mermaidBlocks.length} fenced diagram(s) → PNG via mmdc (${describeMmdcResolution()})`,
+      );
+      if (log === "verbose") {
+        traceExportPdfLine(log, `export pdf · temp workdir=${workDir}`);
+      }
+      const { markdown: withImages } = renderMermaidBlocksToPng(merged, workDir);
+      const mdName = "consolidated.md";
+      fs.writeFileSync(path.join(workDir, mdName), withImages, "utf8");
+      if (ctx.g.useNativePandoc) {
+        const pandocBin = resolvePandocExecutable();
+        const pArgs = buildNativePandocArgs(mdName, pdfOut);
+        traceExportPdfLine(
+          log,
+          `export pdf · pdf tool: pandoc (system) ${shellWords([pandocBin, ...pArgs])}`,
+        );
+        traceExportPdfLine(log, `export pdf · pandoc cwd: ${workDir}`);
+        runNativePandocPdf(workDir, mdName, pdfOut, pandocBin);
+      } else {
+        const worker = bundledPdfWorkerScriptPath();
+        traceExportPdfLine(
+          log,
+          "export pdf · pdf tool: pandoc-wasm (npm) + puppeteer/Chromium → standalone HTML → print PDF",
+        );
+        traceExportPdfLine(
+          log,
+          `export pdf · worker: ${shellWords([process.execPath, worker, workDir, mdName, pdfOut])}`,
+        );
+        runBundledMarkdownToPdf(workDir, mdName, pdfOut);
+      }
+      process.stdout.write(
+        `[waterfall] Wrote PDF (${mdFiles.length} markdown files): ${pdfOut}\n`,
+      );
+      return 0;
+    } catch (e) {
+      process.stderr.write(`${(e as Error).message}\n`);
+      return 1;
+    } finally {
+      if (workDir && fs.existsSync(workDir)) {
+        try {
+          fs.rmSync(workDir, { recursive: true, force: true });
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  },
+};