@pknx/waterfall-cli 0.1.0

package/lib/cli/core/cli-log.ts

@@ -0,0 +1,124 @@
+/**
+ * Log / trace levels for agent invocation (driven by .waterfall `level` and flags).
+ */
+import type { BackendId } from "../agent/backends";
+
+export type LogLevel = "silent" | "normal" | "verbose";
+
+export function parseLogLevel(raw: string | undefined): LogLevel | undefined {
+  if (!raw?.trim()) return undefined;
+  const v = raw.trim().toLowerCase();
+  if (v === "silent" || v === "quiet" || v === "0") return "silent";
+  if (v === "normal" || v === "1") return "normal";
+  if (v === "verbose" || v === "debug" || v === "2") return "verbose";
+  return undefined;
+}
+
+export function defaultLogLevel(): LogLevel {
+  return "normal";
+}
+
+export type AgentTraceLabels = {
+  backend: BackendId;
+  /** e.g. cr-to-rq.md */
+  promptBasename: string;
+  /** e.g. prompts/commands/cr-to-rq.md */
+  promptRel: string;
+  specRoot: string;
+  hint: string;
+  orchestrationContext?: string;
+  /** Cline: WATERFALL_CLINE_MODEL when set */
+  model?: string;
+  promptByteLength?: number;
+};
+
+function wf(): string {
+  return "[waterfall]";
+}
+
+/** Full JSON wire string passed to the backend (`-p` payload). Verbose only (non-Cursor backends). */
+export function traceWireMessage(level: LogLevel, wire: string): void {
+  if (level !== "verbose") return;
+  process.stdout.write(`${wf()} agent wire message:\n${wire}`);
+}
+
+/**
+ * Echo the translated JSON payload to stdout before spawn.
+ * Cursor: printed whenever log level is not silent (so operators see what `agent -p` receives).
+ * Other backends: same as verbose-only `traceWireMessage`.
+ */
+export function traceTranslatedPayloadForBackend(
+  backend: BackendId,
+  level: LogLevel,
+  wire: string,
+): void {
+  if (level === "silent") return;
+  if (backend === "cursor") {
+    process.stdout.write(
+      `${wf()} cursor translated payload (JSON string passed as agent -p positional prompt):\n${wire}`,
+    );
+    return;
+  }
+  traceWireMessage(level, wire);
+}
+
+/** Dry-run plan line (describeBackendInvocation). Silent = no stdout. */
+export function traceDryRun(level: LogLevel, planLine: string): void {
+  if (level === "silent") return;
+  process.stdout.write(`[dry-run] ${planLine}\n`);
+  if (level === "verbose") {
+    process.stdout.write(`${wf()} log level: verbose (dry-run; no subprocess)\n`);
+  }
+}
+
+/** Before synchronous agent subprocess. */
+export function traceAgentInvokeStart(level: LogLevel, labels: AgentTraceLabels): void {
+  if (level === "silent") return;
+  const { backend, promptBasename, specRoot, orchestrationContext, hint } = labels;
+  if (level === "normal") {
+    const ctx = orchestrationContext ? ` · ${orchestrationContext}` : "";
+    process.stdout.write(`${wf()} ◐ agent · ${backend} · ${promptBasename}${ctx}\n`);
+    return;
+  }
+  const modelLine =
+    labels.model?.trim() ? `  cline model: ${labels.model.trim()}\n` : "";
+  const bytesLine =
+    labels.promptByteLength != null
+      ? `  prompt file: ${labels.promptRel} (${labels.promptByteLength} bytes)\n`
+      : `  prompt file: ${labels.promptRel}\n`;
+  const hintPreview =
+    hint.length > 220 ? `${hint.slice(0, 220)}…` : hint;
+  const orch = orchestrationContext ? `  ${orchestrationContext}\n` : "";
+  process.stdout.write(
+    `${wf()} invoking agent (verbose)\n` +
+      `  backend: ${backend}\n` +
+      bytesLine +
+      `  cwd: ${specRoot}\n` +
+      modelLine +
+      `  hint: ${JSON.stringify(hintPreview)}\n` +
+      orch,
+  );
+}
+
+/** After agent subprocess returns successfully. */
+export function traceAgentInvokeDone(
+  level: LogLevel,
+  labels: Pick<AgentTraceLabels, "promptBasename" | "backend">,
+): void {
+  if (level === "silent") return;
+  if (level === "normal") {
+    process.stdout.write(
+      `${wf()} ✓ agent · ${labels.backend} · ${labels.promptBasename}\n`,
+    );
+    return;
+  }
+  process.stdout.write(
+    `${wf()} subprocess finished · ${labels.backend} · ${labels.promptBasename}\n`,
+  );
+}
+
+/** `export pdf` pipeline tracing (respects silent / normal / verbose). */
+export function traceExportPdfLine(level: LogLevel, message: string): void {
+  if (level === "silent") return;
+  process.stdout.write(`${wf()} ${message}\n`);
+}

package/lib/cli/core/exec-file.ts

@@ -0,0 +1,8 @@
+import { execFileSync as nodeExecFileSync } from "node:child_process";
+
+/** Indirection so Vitest can mock backend spawns without affecting `git` in cr-*.ts */
+export function execFileSync(
+  ...args: Parameters<typeof nodeExecFileSync>
+): ReturnType<typeof nodeExecFileSync> {
+  return nodeExecFileSync(...args);
+}

package/lib/cli/core/prompt-map.ts

@@ -0,0 +1,64 @@
+/**
+ * Maps CLI argv to prompts/*.md paths (repo-relative to spec root).
+ * Align with waterfall-spec CR-005 §2.6 and prompts/workflows.md.
+ */
+export type LifecycleStep =
+  | "cr-to-rq"
+  | "rq-to-uc"
+  | "uc-to-story"
+  | "uc-to-test"
+  | "test-to-story";
+
+export const ORCHESTRATE_CR_ALL_ORDER: LifecycleStep[] = [
+  "cr-to-rq",
+  "rq-to-uc",
+  "uc-to-story",
+  "uc-to-test",
+  "test-to-story",
+];
+
+export const ORCHESTRATE_RQ_ALL_ORDER: LifecycleStep[] = [
+  "rq-to-uc",
+  "uc-to-story",
+  "uc-to-test",
+  "test-to-story",
+];
+
+export const ORCHESTRATE_UC_ALL_ORDER: LifecycleStep[] = [
+  "uc-to-story",
+  "uc-to-test",
+  "test-to-story",
+];
+
+export const ORCHESTRATE_TEST_ALL_ORDER: LifecycleStep[] = [
+  "test-to-story",
+  "uc-to-story",
+  "uc-to-test",
+];
+
+const STEP_TO_FILE: Record<LifecycleStep, string> = {
+  "cr-to-rq": "prompts/commands/cr-to-rq.md",
+  "rq-to-uc": "prompts/commands/rq-to-uc.md",
+  "uc-to-story": "prompts/commands/uc-to-story.md",
+  "uc-to-test": "prompts/commands/uc-to-test.md",
+  "test-to-story": "prompts/commands/test-to-story.md",
+};
+
+export function promptFileForStep(step: LifecycleStep): string {
+  return STEP_TO_FILE[step];
+}
+
+export type SingleCommand =
+  | { kind: "cr-to-rq"; hint: string }
+  | { kind: "rq-to-uc"; hint: string }
+  | { kind: "uc-to-story"; hint: string }
+  | { kind: "uc-to-test"; hint: string }
+  | { kind: "test-to-story"; hint: string };
+
+export function singleCommandToStep(cmd: SingleCommand): LifecycleStep {
+  return cmd.kind;
+}
+
+export function promptPathForSingleCommand(cmd: SingleCommand): string {
+  return promptFileForStep(singleCommandToStep(cmd));
+}

package/lib/cli/core/slug.ts

@@ -0,0 +1,44 @@
+/** Kebab-case slug for branch / CR folder names (STORY-018). */
+export function slugifyDescription(description: string): string {
+  const s = description
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return s || "change";
+}
+
+/** Zero-pad CR id to three digits. */
+export function formatCrId(n: number): string {
+  return String(n).padStart(3, "0");
+}
+
+/** Title case from a kebab slug (branch / folder slug) for scaffold headings — not full operator prose. */
+export function humanizeKebabSlug(slug: string): string {
+  if (!slug || slug === "change") return "New change request";
+  return slug
+    .split("-")
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+const SCAFFOLD_HEADING_MAX = 100;
+
+/**
+ * H1 line for CR/SYS scaffolds: first line of operator text (trimmed), length-capped at a word boundary.
+ * Avoids titles derived from {@link slugifyDescription}'s 48-char slug, which often cuts mid-word.
+ */
+export function scaffoldHeadingFromDescription(
+  description: string,
+  slug: string,
+): string {
+  const first = description.trim().split(/\r?\n/u)[0]?.trim() ?? "";
+  if (!first) return humanizeKebabSlug(slug);
+  if (first.length <= SCAFFOLD_HEADING_MAX) return first;
+  const cut = first.slice(0, SCAFFOLD_HEADING_MAX);
+  const lastSpace = cut.lastIndexOf(" ");
+  const base = lastSpace > 40 ? cut.slice(0, lastSpace) : cut;
+  return `${base}…`;
+}

package/lib/cli/entry.ts

@@ -0,0 +1,4 @@
+import process from "node:process";
+import { runWaterfallCli } from "./main";
+
+process.exit(runWaterfallCli(process.argv.slice(2)));

package/lib/cli/export/collect-md.ts

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const SKIP_DIR_NAMES = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+]);
+
+/**
+ * All `.md` files under `specRoot`, depth-first by sorted relative path.
+ * Skips hidden directories, `node_modules`, `.git`, and common build folders.
+ */
+export function collectMarkdownFiles(specRoot: string): string[] {
+  const absRoot = path.resolve(specRoot);
+  const results: string[] = [];
+
+  function walk(dir: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (e.name.startsWith(".")) continue;
+      if (SKIP_DIR_NAMES.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.isFile() && e.name.endsWith(".md")) results.push(full);
+    }
+  }
+
+  walk(absRoot);
+  return results.sort((a, b) =>
+    path.relative(absRoot, a).localeCompare(path.relative(absRoot, b)),
+  );
+}

package/lib/cli/export/export-items.ts

@@ -0,0 +1,104 @@
+import path from "node:path";
+
+/** Known spec artifact families for `export pdf --items`. */
+export const EXPORT_ITEM_CODES = [
+  "CR",
+  "RQ",
+  "UC",
+  "SYS",
+  "STORY",
+  "BUG",
+  "HOR",
+  "TST",
+  "CURSOR",
+] as const;
+
+export type ExportItemCode = (typeof EXPORT_ITEM_CODES)[number];
+
+/** Default: lifecycle + horizontals + tests; excludes CURSOR.md, SYS/STORY/BUG, prompts/doc. */
+export const DEFAULT_EXPORT_ITEMS: readonly ExportItemCode[] = [
+  "CR",
+  "RQ",
+  "UC",
+  "HOR",
+  "TST",
+];
+
+export function parseExportItemsList(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim().toUpperCase())
+    .filter(Boolean);
+}
+
+export function validateExportItemCodes(codes: string[]): void {
+  const allowed = new Set<string>(EXPORT_ITEM_CODES);
+  const bad = codes.filter((c) => !allowed.has(c));
+  if (bad.length > 0) {
+    throw new Error(
+      `[waterfall] Unknown --items code(s): ${bad.join(", ")}. Allowed: ${EXPORT_ITEM_CODES.join(", ")}`,
+    );
+  }
+}
+
+/**
+ * Map a markdown path relative to spec root (forward slashes) to one export code, or null if excluded
+ * (unknown layout, prompts/, doc/, docs/, etc.).
+ */
+export function classifyMarkdownExportItem(relPath: string): string | null {
+  const norm = relPath.split(path.sep).join("/");
+
+  if (/^CURSOR\.md$/i.test(norm)) return "CURSOR";
+
+  if (
+    norm.startsWith("prompts/") ||
+    norm.startsWith("doc/") ||
+    norm.startsWith("docs/")
+  ) {
+    return null;
+  }
+
+  if (norm.startsWith("changerequests/") && norm.toLowerCase().endsWith(".md")) {
+    return "CR";
+  }
+
+  if (norm.startsWith("tests/")) {
+    const base = path.posix.basename(norm);
+    if (/^TST-\d+/i.test(base)) return "TST";
+    return null;
+  }
+
+  if (norm.startsWith("technical/horizontals/")) {
+    const base = path.posix.basename(norm);
+    if (/^HOR-\d+/i.test(base)) return "HOR";
+    return null;
+  }
+
+  if (norm.startsWith("technical/")) {
+    if (/\/STORY-\d+[^/]*\/STORY-\d+\.md$/i.test(norm)) return "STORY";
+    if (/\/SYS-\d+[^/]*\/SYS-\d+\.md$/i.test(norm)) return "SYS";
+    if (/\/BUG-\d+[^/]*\/BUG-\d+\.md$/i.test(norm)) return "BUG";
+    return null;
+  }
+
+  if (norm.startsWith("requirements/")) {
+    if (/\/RQ-\d+[^/]*\/RQ-\d+\.md$/i.test(norm)) return "RQ";
+    if (/\/UC-\d+[^/]*\/UC-\d+\.md$/i.test(norm)) return "UC";
+    return null;
+  }
+
+  return null;
+}
+
+export function filterMarkdownPathsByExportItems(
+  absolutePaths: string[],
+  specRoot: string,
+  itemSet: Set<string>,
+): string[] {
+  const root = path.resolve(specRoot);
+  return absolutePaths.filter((abs) => {
+    const rel = path.relative(root, abs).split(path.sep).join("/");
+    const kind = classifyMarkdownExportItem(rel);
+    return kind !== null && itemSet.has(kind);
+  });
+}

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

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gitExecSync } from "../git/git-cli";
+
+function runGitText(specRoot: string, args: string[]): string {
+  try {
+    return String(
+      gitExecSync(specRoot, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      }),
+    ).trimEnd();
+  } catch (e) {
+    throw new Error(
+      `[waterfall] export pdf needs a git repo at the spec root: ${(e as Error).message}`,
+    );
+  }
+}
+
+/** Safe single path segment for PDF filename (basename, tag, or short hash). */
+export function sanitizePdfSegment(raw: string): string {
+  return raw
+    .trim()
+    .replace(/[/\\?*:|"<>]/g, "-")
+    .replace(/\s+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Fail if the spec repo has any staged/unstaged/untracked changes.
+ */
+export function assertSpecRepoCleanForExport(specRoot: string): void {
+  const porcelain = runGitText(specRoot, ["status", "--porcelain"]);
+  if (porcelain.length > 0) {
+    throw new Error(
+      "[waterfall] export pdf requires a clean working tree (commit or stash all changes, including untracked files you care about).",
+    );
+  }
+}
+
+/**
+ * Tag name if HEAD matches at least one tag (lexicographically first by refname);
+ * otherwise 12-char revision.
+ */
+export function resolveExportRevisionLabel(specRoot: string): string {
+  const tagsOut = runGitText(specRoot, [
+    "tag",
+    "--points-at",
+    "HEAD",
+    "--sort=refname",
+  ]);
+  const tags = tagsOut
+    .split("\n")
+    .map((t) => t.trim())
+    .filter(Boolean);
+  if (tags.length > 0) {
+    return sanitizePdfSegment(tags[0]!);
+  }
+  const short = runGitText(specRoot, ["rev-parse", "--short=12", "HEAD"]);
+  return sanitizePdfSegment(short) || "unknown";
+}
+
+/**
+ * Default PDF path: `<specRoot>/docs/<basename>-<tag|hash>.pdf` (creates `docs/`).
+ */
+export function resolveDefaultExportPdfPath(specRoot: string): string {
+  const abs = path.resolve(specRoot);
+  const base = sanitizePdfSegment(path.basename(abs)) || "spec";
+  const rev = resolveExportRevisionLabel(specRoot);
+  const docsDir = path.join(abs, "docs");
+  fs.mkdirSync(docsDir, { recursive: true });
+  return path.join(docsDir, `${base}-${rev}.pdf`);
+}
+
+/**
+ * `-o` override (resolved against `cwd`) or {@link resolveDefaultExportPdfPath}.
+ */
+export function resolveExportPdfOutputPath(
+  specRoot: string,
+  cwd: string,
+  explicitOutput: string | undefined,
+): string {
+  if (explicitOutput?.trim()) {
+    return path.resolve(cwd, explicitOutput.trim());
+  }
+  return resolveDefaultExportPdfPath(specRoot);
+}

package/lib/cli/export/merge-md.ts

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/** YAML `title` for Pandoc (PDF metadata, HTML `<title>`); value is JSON-quoted for safety. */
+function yamlTitleBlock(documentTitle: string): string {
+  return `---\ntitle: ${JSON.stringify(documentTitle)}\n---\n`;
+}
+
+/**
+ * Build one markdown document: each file becomes a section with a source path heading.
+ * @param documentTitle Shown as H1 and in PDF/HTML metadata via YAML front matter.
+ */
+export function mergeMarkdownFiles(
+  specRoot: string,
+  absolutePaths: string[],
+  documentTitle: string,
+): string {
+  const root = path.resolve(specRoot);
+  const title = documentTitle.trim() || "Waterfall specification";
+  const parts: string[] = [
+    yamlTitleBlock(title),
+    `# ${title}\n`,
+    "",
+    "_Generated by `waterfall export pdf`. Source files are merged in path order._",
+    "",
+    "---",
+    "",
+  ];
+
+  for (const abs of absolutePaths) {
+    const rel = path.relative(root, abs).split(path.sep).join("/");
+    const body = fs.readFileSync(abs, "utf8").replace(/\r\n/g, "\n");
+    parts.push(`## Source: \`${rel}\``, "", body, "", "---", "");
+  }
+
+  return parts.join("\n").trimEnd() + "\n";
+}

package/lib/cli/export/mermaid-run.ts

@@ -0,0 +1,104 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { WATERFALL_CLI_PACKAGE_ROOT } from "../paths";
+
+const MERMAID_BLOCK = /```mermaid\s*\r?\n([\s\S]*?)```/gi;
+
+/** Human-readable label for which `mmdc` invocation path will be used (no subprocess). */
+export function describeMmdcResolution(): string {
+  const envBin = process.env.WATERFALL_MMDC?.trim();
+  if (envBin) return `WATERFALL_MMDC (${envBin})`;
+  const win = process.platform === "win32";
+  const localBin = path.join(
+    WATERFALL_CLI_PACKAGE_ROOT,
+    "node_modules",
+    ".bin",
+    win ? "mmdc.cmd" : "mmdc",
+  );
+  if (fs.existsSync(localBin)) return `bundled (${localBin})`;
+  return "PATH mmdc, else npx -y @mermaid-js/mermaid-cli";
+}
+
+export type MermaidReplacement = {
+  /** Markdown with ```mermaid blocks replaced by image references. */
+  markdown: string;
+  /** Basenames of PNG files written under `workDir` (same order as replacements). */
+  imageFiles: string[];
+};
+
+/**
+ * Replace fenced `mermaid` blocks with `![](mermaid-N.png)` and write each diagram
+ * to `workDir` using the Mermaid CLI (`mmdc` ships with waterfall-cli dependencies).
+ *
+ * Resolution order: `WATERFALL_MMDC` → `waterfall-cli/node_modules/.bin/mmdc` → `mmdc` on PATH →
+ * `npx -y @mermaid-js/mermaid-cli` (fallback if node_modules was trimmed).
+ */
+export function renderMermaidBlocksToPng(
+  markdown: string,
+  workDir: string,
+): MermaidReplacement {
+  fs.mkdirSync(workDir, { recursive: true });
+  let index = 0;
+  const imageFiles: string[] = [];
+
+  const next = () => {
+    const name = `mermaid-${index}.png`;
+    index += 1;
+    imageFiles.push(name);
+    return name;
+  };
+
+  const outMd = markdown.replace(MERMAID_BLOCK, (_full, code: string) => {
+    const pngName = next();
+    const mmdPath = path.join(workDir, pngName.replace(/\.png$/, ".mmd"));
+    const pngPath = path.join(workDir, pngName);
+    const trimmed = String(code).trimEnd() + "\n";
+    fs.writeFileSync(mmdPath, trimmed, "utf8");
+    runMmdc(mmdPath, pngPath);
+    return `![mermaid diagram](${pngName})`;
+  });
+
+  return { markdown: outMd, imageFiles };
+}
+
+function runMmdc(inputPath: string, outputPath: string): void {
+  const args = ["-i", inputPath, "-o", outputPath, "-b", "white"];
+  const envBin = process.env.WATERFALL_MMDC?.trim();
+  if (envBin) {
+    execFileSync(envBin, args, { stdio: "inherit" });
+    return;
+  }
+
+  const win = process.platform === "win32";
+  const localBin = path.join(
+    WATERFALL_CLI_PACKAGE_ROOT,
+    "node_modules",
+    ".bin",
+    win ? "mmdc.cmd" : "mmdc",
+  );
+  if (fs.existsSync(localBin)) {
+    execFileSync(localBin, args, { stdio: "inherit" });
+    return;
+  }
+
+  try {
+    execFileSync("mmdc", args, { stdio: "inherit" });
+    return;
+  } catch {
+    /* try npx */
+  }
+
+  const npx = win ? "npx.cmd" : "npx";
+  const npxArgs = ["-y", "@mermaid-js/mermaid-cli", ...args];
+  const r = spawnSync(npx, npxArgs, {
+    stdio: "inherit",
+    shell: win,
+  });
+  if (r.error) throw r.error;
+  if (r.status !== 0) {
+    throw new Error(
+      `mmdc failed (exit ${r.status}). Install Mermaid CLI: npm i -g @mermaid-js/mermaid-cli, or set WATERFALL_MMDC to the mmdc binary.`,
+    );
+  }
+}