@pknx/waterfall-cli 0.1.0

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

@@ -0,0 +1,90 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export function buildNativePandocArgs(
+  markdownBasename: string,
+  pdfOutAbsolute: string,
+): string[] {
+  const extra = process.env.WATERFALL_PANDOC_ARGS?.trim();
+  /** XeLaTeX handles Unicode (e.g. ≥); default pdflatex often fails on those. */
+  const engine =
+    process.env.WATERFALL_PANDOC_PDF_ENGINE?.trim() || "xelatex";
+  const args = [
+    markdownBasename,
+    "-o",
+    pdfOutAbsolute,
+    "--toc",
+    "--toc-depth=4",
+    "--pdf-engine",
+    engine,
+  ];
+  if (extra) {
+    args.push(...extra.split(/\s+/).filter(Boolean));
+  }
+  return args;
+}
+
+/**
+ * Executable used when `use_native_pandoc=true`.
+ * Order: `WATERFALL_PANDOC` → `pandoc` on PATH → common Homebrew paths (macOS).
+ */
+export function resolvePandocExecutable(): string {
+  const fromEnv = process.env.WATERFALL_PANDOC?.trim();
+  if (fromEnv) {
+    if (!fs.existsSync(fromEnv)) {
+      throw new Error(
+        `WATERFALL_PANDOC is set but file not found: ${fromEnv}`,
+      );
+    }
+    return fromEnv;
+  }
+
+  try {
+    execFileSync("pandoc", ["--version"], { stdio: "ignore" });
+    return "pandoc";
+  } catch {
+    /* not on PATH */
+  }
+
+  const brew = process.env.HOMEBREW_PREFIX?.trim();
+  const candidates = [
+    "/opt/homebrew/bin/pandoc",
+    "/usr/local/bin/pandoc",
+    ...(brew ? [path.join(brew, "bin", "pandoc")] : []),
+  ];
+  for (const c of candidates) {
+    if (c && fs.existsSync(c)) return c;
+  }
+
+  throw new Error(
+    "pandoc not found. Install: https://pandoc.org/installing.html (macOS: brew install pandoc). " +
+      "Or set WATERFALL_PANDOC to the binary, or ensure /opt/homebrew/bin or /usr/local/bin is on PATH.",
+  );
+}
+
+/**
+ * Run system `pandoc` on `markdownBasename` inside `workDir` so relative `![](*.png)` resolve.
+ * Used when `use_native_pandoc=true` in `.waterfall` / `~/.waterfall` (LaTeX-quality PDF if pandoc + engine are installed).
+ * @param pandocExecutable optional; default {@link resolvePandocExecutable}
+ */
+export function runNativePandocPdf(
+  workDir: string,
+  markdownBasename: string,
+  pdfOutAbsolute: string,
+  pandocExecutable?: string,
+): void {
+  const bin = pandocExecutable ?? resolvePandocExecutable();
+  const args = buildNativePandocArgs(markdownBasename, pdfOutAbsolute);
+  try {
+    execFileSync(bin, args, { cwd: workDir, stdio: "inherit" });
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      throw new Error(
+        `pandoc executable missing: ${bin}. Install Pandoc or set WATERFALL_PANDOC.`,
+      );
+    }
+    throw e;
+  }
+}

package/lib/cli/export/pdf-bundled-worker.mjs

@@ -0,0 +1,73 @@
+/**
+ * ESM worker: pandoc-wasm (markdown → HTML) + puppeteer (HTML → PDF).
+ * node lib/cli/export/pdf-bundled-worker.mjs <workDir> <mdBasename> <pdfOutAbsolute>
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { convert } from "pandoc-wasm";
+import puppeteer from "puppeteer";
+
+const workDir = process.argv[2];
+const mdName = process.argv[3];
+const pdfOut = process.argv[4];
+
+if (!workDir || !mdName || !pdfOut) {
+  process.stderr.write(
+    "pdf-bundled-worker: expected argv: workDir markdownBasename pdfOutAbsolute\n",
+  );
+  process.exit(1);
+}
+
+async function main() {
+  const mdPath = path.join(workDir, mdName);
+  const md = fs.readFileSync(mdPath, "utf8");
+  const files = {};
+  for (const name of fs.readdirSync(workDir)) {
+    if (!name.endsWith(".png")) continue;
+    files[name] = new Blob([fs.readFileSync(path.join(workDir, name))]);
+  }
+
+  const result = await convert(
+    {
+      from: "markdown",
+      to: "html",
+      standalone: true,
+      "embed-resources": true,
+      "table-of-contents": true,
+      "toc-depth": 4,
+    },
+    md,
+    files,
+  );
+  if (result.stderr?.trim()) {
+    process.stderr.write(result.stderr);
+  }
+  const html = result.stdout;
+  if (!html?.trim()) {
+    process.stderr.write("pandoc-wasm produced empty HTML\n");
+    process.exit(1);
+  }
+
+  const browser = await puppeteer.launch({
+    headless: true,
+    args: ["--no-sandbox", "--disable-setuid-sandbox"],
+  });
+  try {
+    const page = await browser.newPage();
+    await page.setContent(html, { waitUntil: "networkidle0" });
+    await page.pdf({
+      path: pdfOut,
+      format: "A4",
+      printBackground: true,
+      margin: { top: "18mm", bottom: "18mm", left: "16mm", right: "16mm" },
+    });
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch((e) => {
+  process.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
+  process.exit(1);
+});

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

@@ -0,0 +1,36 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { WATERFALL_CLI_PACKAGE_ROOT } from "../paths";
+
+export function bundledPdfWorkerScriptPath(): string {
+  return path.join(
+    WATERFALL_CLI_PACKAGE_ROOT,
+    "lib/cli/export/pdf-bundled-worker.mjs",
+  );
+}
+
+/**
+ * Runs {@link ./pdf-bundled-worker.mjs} in a subprocess so the main CLI stays synchronous.
+ * Uses pandoc-wasm + bundled Chromium (puppeteer).
+ */
+export function runBundledMarkdownToPdf(
+  workDir: string,
+  markdownBasename: string,
+  pdfOutAbsolute: string,
+): void {
+  const worker = bundledPdfWorkerScriptPath();
+  const r = spawnSync(
+    process.execPath,
+    [worker, workDir, markdownBasename, pdfOutAbsolute],
+    {
+      stdio: "inherit",
+      cwd: process.cwd(),
+      env: process.env,
+    },
+  );
+  if (r.error) throw r.error;
+  if (r.status !== 0) {
+    throw new Error(`Bundled PDF generation failed (exit ${r.status})`);
+  }
+}

package/lib/cli/git/cr-agent-context.ts

@@ -0,0 +1,62 @@
+import { CR_FEATURE_BRANCH_RE, getCurrentGitBranch, specRootHasGit } from "./git-branch-guards";
+import { gitExecSync } from "./git-cli";
+
+/**
+ * Markdown block listing paths changed on the current branch vs `develop` (`develop...HEAD`).
+ * Empty string when not on a change-request branch, no git, or diff fails.
+ */
+export function formatCrBranchChangedFilesBlock(specRoot: string): string {
+  if (!specRootHasGit(specRoot)) {
+    return "";
+  }
+  const branch = getCurrentGitBranch(specRoot);
+  if (!CR_FEATURE_BRANCH_RE.test(branch)) {
+    return "";
+  }
+  try {
+    const out = gitExecSync(specRoot, ["diff", "develop...HEAD", "--name-only"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).toString();
+    const lines = out
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean);
+    const body = lines.length
+      ? lines.map((p) => `- ${p}`).join("\n")
+      : "No paths differ from develop in this range (develop...HEAD).";
+    return [
+      "CR branch — paths changed vs develop (develop...HEAD)",
+      "",
+      "The Waterfall CLI attached this list so you do not need to run git for scope discovery.",
+      "",
+      body,
+      "",
+      "---",
+      "",
+    ].join("\n");
+  } catch {
+    return [
+      "CR branch — paths changed vs develop",
+      "",
+      "Could not run git diff develop...HEAD --name-only (missing develop branch or not a git repo?).",
+      "",
+      "---",
+      "",
+    ].join("\n");
+  }
+}
+
+/**
+ * One-line / log-friendly hint: operator text then CR paths block.
+ * The agent wire payload uses separate `user` segments (see `buildWaterfallAgentMessage`);
+ * this concatenation is for dry-run traces and `describeBackendInvocation` only.
+ */
+export function augmentAgentHintWithCrFiles(specRoot: string, hint: string): string {
+  const block = formatCrBranchChangedFilesBlock(specRoot);
+  if (!block) {
+    return hint;
+  }
+  const t = hint.trim();
+  return t.length > 0 ? `${t}\n\n${block}` : block;
+}

package/lib/cli/git/git-branch-guards.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gitExecSync } from "./git-cli";
+
+/** Matches `feature/CR-001-slug`, `feature/CR-012`, etc. */
+export const CR_FEATURE_BRANCH_RE = /^feature\/CR-\d/;
+
+export function specRootHasGit(specRoot: string): boolean {
+  return fs.existsSync(path.join(specRoot, ".git"));
+}
+
+export function getCurrentGitBranch(specRoot: string): string {
+  return gitExecSync(specRoot, ["rev-parse", "--abbrev-ref", "HEAD"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+    .toString()
+    .trim();
+}
+
+/** `waterfall cr start`, `waterfall story close`, `waterfall comment add`, … — normative: only on `develop`. */
+export function assertBranchDevelop(specRoot: string, commandLabel: string): void {
+  if (!specRootHasGit(specRoot)) {
+    throw new Error(
+      `${commandLabel}: spec root must be a git repository (.git missing). Run git init or use a clone.`,
+    );
+  }
+  const b = getCurrentGitBranch(specRoot);
+  if (b !== "develop") {
+    throw new Error(
+      `${commandLabel}: must be on branch "develop" (current: "${b}"). Checkout develop first.`,
+    );
+  }
+}
+
+/** `waterfall cr start` — normative: start new CR work only from `develop`. */
+export function assertBranchForCrStart(specRoot: string): void {
+  assertBranchDevelop(specRoot, "cr start");
+}
+
+/**
+ * Change-request–scoped work: lifecycle prompts, sys start, horizontal create/update, cr finish — normative:
+ * on a branch matching `feature/CR-<NNN>-…` (inside an active change request).
+ */
+export function assertBranchForCrScopedCommand(
+  specRoot: string,
+  commandLabel: string,
+): void {
+  if (!specRootHasGit(specRoot)) {
+    throw new Error(
+      `${commandLabel}: spec root must be a git repository (.git missing).`,
+    );
+  }
+  const b = getCurrentGitBranch(specRoot);
+  if (!CR_FEATURE_BRANCH_RE.test(b)) {
+    throw new Error(
+      `${commandLabel}: must be on a change-request branch matching feature/CR-<NNN>-… (current: "${b}"). Run "waterfall cr start …" from develop first.`,
+    );
+  }
+}

package/lib/cli/git/git-cli-mock.ts

@@ -0,0 +1,191 @@
+/**
+ * In-process git simulation for `VITEST=true` (sandboxes often block the real `git` binary).
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+type MockRepo = {
+  branch: string;
+  commits: { branch: string; msg: string }[];
+};
+
+const repos = new Map<string, MockRepo>();
+
+function dirKey(cwd: string | URL): string {
+  return path.resolve(String(cwd));
+}
+
+function getRepo(cwd: string | URL): MockRepo {
+  const key = dirKey(cwd);
+  let r = repos.get(key);
+  if (!r) {
+    r = { branch: "develop", commits: [] };
+    repos.set(key, r);
+  }
+  return r;
+}
+
+function returnOut(
+  s: string,
+  options: { encoding?: string; stdio?: string | string[] } | undefined,
+): string | Buffer {
+  if (options?.encoding === "utf8" || options?.encoding === "utf-8") {
+    return s;
+  }
+  if (options?.stdio === "inherit") {
+    return "" as unknown as Buffer;
+  }
+  return Buffer.from(s);
+}
+
+function parseLogLimit(argv: string[]): number {
+  const hit = argv.find((a) => /^-\d+$/.test(a));
+  if (hit) return parseInt(hit.slice(1), 10);
+  return 5;
+}
+
+export function mockGitExecSync(
+  cwd: string | URL,
+  argv: string[],
+  options?: { encoding?: BufferEncoding; stdio?: "inherit" | ["ignore", "pipe", "pipe"] },
+): string | Buffer {
+  const r = getRepo(cwd);
+
+  if (argv[0] === "init") {
+    let branch = "develop";
+    const bi = argv.indexOf("-b");
+    if (bi >= 0 && argv[bi + 1]) branch = argv[bi + 1]!;
+    const base = dirKey(cwd);
+    repos.set(base, { branch, commits: [] });
+    const gitDir = path.join(base, ".git");
+    fs.mkdirSync(path.join(gitDir, "objects", "pack"), { recursive: true });
+    fs.mkdirSync(path.join(gitDir, "refs", "heads"), { recursive: true });
+    /* HEAD only — some sandboxes reject `.git/config` writes even from Node. */
+    fs.writeFileSync(path.join(gitDir, "HEAD"), `ref: refs/heads/${branch}\n`);
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "config") {
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "checkout") {
+    if (argv[1] === "-b") {
+      r.branch = argv[2]!;
+    } else {
+      r.branch = argv[1]!;
+    }
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "pull") {
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "mv") {
+    const from = argv[1]!;
+    const to = argv[2]!;
+    const base = dirKey(cwd);
+    fs.renameSync(path.join(base, from), path.join(base, to));
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "add") {
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "commit") {
+    const mi = argv.indexOf("-m");
+    const msg = mi >= 0 ? argv[mi + 1]! : "commit";
+    r.commits.push({ branch: r.branch, msg });
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "rev-parse" && argv.includes("--short=12") && argv[argv.length - 1] === "HEAD") {
+    return returnOut("abc123deadef\n", options);
+  }
+
+  if (
+    argv[0] === "tag" &&
+    argv.includes("--points-at") &&
+    argv.includes("HEAD")
+  ) {
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "rev-parse" && argv[1] === "--abbrev-ref" && argv[2] === "HEAD") {
+    return returnOut(`${r.branch}\n`, options);
+  }
+
+  if (argv[0] === "diff" && argv[1] === "--cached" && argv[2] === "--quiet") {
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "status" && argv[1] === "--porcelain") {
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "rev-list" && argv[1] === "--count" && argv[2] === "develop..HEAD") {
+    if (!r.branch.startsWith("feature/")) {
+      return returnOut("0\n", options);
+    }
+    const n = r.commits.filter((c) => c.branch === r.branch).length;
+    return returnOut(`${n}\n`, options);
+  }
+
+  if (argv[0] === "diff" && argv[1] === "develop...HEAD") {
+    if (argv.includes("--name-only")) {
+      if (!r.branch.startsWith("feature/")) {
+        return returnOut("", options);
+      }
+      const n = r.commits.filter((c) => c.branch === r.branch).length;
+      if (n === 0) return returnOut("", options);
+      return returnOut(
+        "changerequests/CR-001-stub/CR-001.md\ntechnical/SYS-001-x/agent/STORY-001-y/STORY-001.md\n",
+        options,
+      );
+    }
+    if (!r.branch.startsWith("feature/")) {
+      return returnOut("", options);
+    }
+    const n = r.commits.filter((c) => c.branch === r.branch).length;
+    if (n === 0) return returnOut("", options);
+    return returnOut("diff --git a/changerequests/x b/changerequests/x\n", options);
+  }
+
+  if (argv[0] === "merge") {
+    const source = argv[1]!;
+    const featureCommits = r.commits.filter((c) => c.branch === source);
+    for (const c of featureCommits) {
+      r.commits.push({ branch: "develop", msg: c.msg });
+    }
+    const mi = argv.indexOf("-m");
+    const mergeMsg = mi >= 0 ? argv[mi + 1]! : "merge";
+    if (argv.includes("--no-ff") || featureCommits.length > 0) {
+      r.commits.push({ branch: "develop", msg: mergeMsg });
+    }
+    r.branch = "develop";
+    return returnOut("", options);
+  }
+
+  if (argv[0] === "log") {
+    if (argv.includes("--oneline")) {
+      const branchArg = argv.find((a, i) => i >= 1 && !a.startsWith("-"));
+      const b = branchArg ?? r.branch;
+      const list = r.commits.filter((c) => c.branch === b);
+      const n = parseLogLimit(argv);
+      const slice = list.slice(-n).reverse();
+      const lines = slice.map(
+        (c, i) => `${(0x09abcf + i).toString(16).padStart(7, "0")} ${c.msg}`,
+      );
+      return returnOut(lines.join("\n") + (lines.length ? "\n" : ""), options);
+    }
+    if (argv.some((a) => a.startsWith("--pretty"))) {
+      const list = r.commits.filter((c) => c.branch === r.branch);
+      const last = list[list.length - 1];
+      return returnOut(last ? `${last.msg}\n` : "\n", options);
+    }
+  }
+
+  throw new Error(`git-cli-mock: unsupported: git ${argv.join(" ")}`);
+}

package/lib/cli/git/git-cli.ts

@@ -0,0 +1,24 @@
+import { execFileSync } from "node:child_process";
+import { mockGitExecSync } from "./git-cli-mock";
+
+/**
+ * Run `git` in `cwd`. Under Vitest, uses an in-process mock so unit tests do not rely
+ * on the real git binary (often blocked from writing `.git/` in sandboxes).
+ */
+export function gitExecSync(
+  cwd: string | URL,
+  args: string[],
+  options?: {
+    stdio?: "inherit" | ["ignore", "pipe", "pipe"];
+    encoding?: BufferEncoding;
+  },
+): string | Buffer {
+  if (process.env.VITEST === "true") {
+    return mockGitExecSync(cwd, args, options);
+  }
+  const wd = typeof cwd === "string" ? cwd : String(cwd);
+  return execFileSync("git", args, {
+    cwd: wd,
+    ...options,
+  } as Parameters<typeof execFileSync>[2]);
+}