@pknx/waterfall-cli 0.1.0

package/lib/cli/main.ts

@@ -0,0 +1,434 @@
+/**
+ * Waterfall CLI entry (STORY-018 / STORY-019).
+ * Run: npm run waterfall -- …   or   node --import tsx lib/cli/main.ts …
+ */
+import process from "node:process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSpecRoot, assertSpecRoot } from "./spec/spec-root";
+import { parseSpecInitCliArgs, runSpecInit } from "./spec/spec-init";
+import {
+  parseBackendId,
+  checkBackendAvailable,
+  describeBackendInvocation,
+} from "./agent/backends";
+import { buildAgentWireMessage, invokeAgentBackend } from "./agent/backend-invoke";
+import {
+  parsePromptDelivery,
+} from "./agent/agent-message";
+import {
+  defaultLogLevel,
+  parseLogLevel,
+  traceAgentInvokeDone,
+  traceAgentInvokeStart,
+  traceDryRun,
+  traceTranslatedPayloadForBackend,
+} from "./core/cli-log";
+import { promptFileForStep, type LifecycleStep } from "./core/prompt-map";
+import type { RunAgentPromptOptions } from "./commands/types";
+import { augmentAgentHintWithCrFiles } from "./git/cr-agent-context";
+import { assertBranchForCrScopedCommand } from "./git/git-branch-guards";
+import {
+  ensureDotWaterfallFile,
+  loadDotWaterfallConfig,
+  applyDotWaterfallEnvExports,
+  dotWaterfallPath,
+  type DotWaterfallParsed,
+} from "./config/dot-waterfall";
+import { dispatchSpecCommand } from "./commands/registry";
+import type { GlobalCli } from "./config/global-cli";
+import type { WaterfallGlobalPrompt } from "./agent/global-prompts";
+import {
+  formatCliHelpJson,
+  parseHelpFormat,
+} from "./core/cli-help-spec";
+import { WATERFALL_CLI_PACKAGE_ROOT } from "./paths";
+
+export type { GlobalCli } from "./config/global-cli";
+
+const CLI_ROOT = WATERFALL_CLI_PACKAGE_ROOT;
+
+/** Absolute path to shipped workflow + global markdown (`prompts/`). */
+const WATERFALL_PROMPTS_ROOT = path.join(CLI_ROOT, "prompts");
+
+function printHelp(): void {
+  process.stdout.write(`waterfall — CLI for waterfall-spec workflows
+
+Global options:
+  --spec-root PATH     Override waterfall-spec repository root
+  --backend ID         cline-ollama | cursor | claude-code (default: cline-ollama)
+  --dry-run            Print planned agent invocation only (default for prompt commands)
+  --execute-agent      Invoke backend: cline -y, agent|cursor -p --force, or claude -p (see README; not dry-run)
+  --log-level L        silent | normal | verbose (overrides WATERFALL_LOG_LEVEL / .waterfall level=)
+  --quiet              Same as --log-level silent (agent tracing only; subprocess output unchanged)
+  --prompt-delivery M  embed | reference — embed inlines the workflow .md in the agent message (default); reference sends absolute paths so the agent reads prompts from the CLI install (overrides .waterfall prompt_delivery)
+
+User config: .waterfall in the working directory, then ~/.waterfall (merged; cwd wins).
+~/.waterfall is created on first run when missing (commented examples).
+Precedence: flags > env (WATERFALL_*) > ./.waterfall > ~/.waterfall > defaults.
+Log/tracing: WATERFALL_LOG_LEVEL or level=silent|normal|verbose in .waterfall; default normal. With --backend cursor, the full translated JSON is also printed to stdout (unless silent) before agent runs or in dry-run.
+
+Operator hints (agent steering and scaffold descriptions): pass inline argv tokens (joined with spaces), a single - to read stdin (UTF-8), or a single @PATH to read a file (UTF-8; PATH relative to cwd unless absolute). On change-request branches, git diff paths vs develop appear in a separate "user" segment from your hint in the agent wire payload (see prompts/global/workflows-index.md). Dry-run logs still show one combined hint line for readability.
+
+Git branch (resolved spec repo; exact wording per command: waterfall help -o json → commands[].branchRequirement):
+  develop — cr start, story close, comment add …
+  feature/CR-<digits>-… — cr to rq, rq to uc, uc to story, uc to test, test to story, cr|rq|uc|test all, sys start, bug start, horizontal create|update, cr finish
+  (no spec-root branch check) — help, spec init, export pdf
+
+Commands:
+  waterfall help | -? | --help   (machine spec: waterfall help -o json)
+  waterfall spec init --title "…" [--full] [DIR]   New repo: pom.json, dirs, number.json, CURSOR.md, git develop. --full adds prompts/ + doc/ from spec-template/full (regeneratable). Default DIR=.
+  waterfall cr start <description>   (then prompts/commands/cr-start.md — use --execute-agent for AI Summary/Proposed change)
+  waterfall sys start <description>   (then prompts/commands/sys-start.md — AI Purpose)
+  waterfall bug start SYS-NNN <hint>   (then prompts/commands/bug-start.md — AI Summary)
+  waterfall horizontal create story <name-slug> <purpose>   (then prompts/commands/horizontal-create.md — AI Purpose)
+  waterfall horizontal update HOR-NNN [<hint>]
+  waterfall cr to rq <hint>
+  waterfall rq to uc <hint>
+  waterfall uc to story <hint>
+  waterfall uc to test <hint>
+  waterfall test to story <hint>
+  waterfall cr all [<hint>]
+  waterfall rq all [<hint>]
+  waterfall uc all [<hint>]
+  waterfall test all [<hint>]
+  waterfall story close STORY-NNN | waterfall story close all
+  waterfall comment add CR|RQ|UC|SYS|STORY|BUG|HOR|TST-NNN <email> <display-name> <hint…>   On develop: append remark to {ITEM-ID}.comments.json (author id = email)
+  waterfall cr finish        mechanical checks + merge feature/CR-* into develop (substance: prompts/commands/cr-finish.md)
+  waterfall sync stories [--dump-spec] [<hint…>]   Compare STORY-* meta vs remote (see .waterfall sync_story_*); --dump-spec prints canonical JSON from spec only; optional hint (inline, -, @PATH) for direct (JSON = dump-spec shape); sync applies remote comments to spec then diffs; direct appends spec snapshot JSON (source waterfall-direct-out) after each run
+  waterfall sync bugs [--dump-spec] [<hint…>]   BUG-* via sync_bug_*; remote-leading materializes new bugs (SYS from sysId or inferred), Draft steering + sync-bugs-refine-imports agent pass; direct appends waterfall-direct-out JSON
+  waterfall export pdf [--items CR,RQ,...] [-o PATH]   Clean git tree; default items CR,RQ,UC,HOR,TST (no CURSOR.md); default PDF under spec docs/; document title from pom.json (walk up from spec root); use_native_pandoc in .waterfall for system pandoc
+
+  Spec resolution order: --spec-root → WATERFALL_SPEC_ROOT → ./.waterfall / ~/.waterfall spec_root → waterfall.json → walk to CURSOR.md
+`);
+}
+
+function resolveSpecRootConfigValue(raw: string | undefined): string | undefined {
+  if (!raw?.trim()) return undefined;
+  const t = raw.trim();
+  return path.isAbsolute(t) ? t : path.resolve(process.cwd(), t);
+}
+
+function buildGlobalCliBase(dot: DotWaterfallParsed): GlobalCli {
+  let backend: GlobalCli["backend"] = "cline-ollama";
+  try {
+    if (dot.backend?.trim()) backend = parseBackendId(dot.backend.trim());
+    if (process.env.WATERFALL_BACKEND?.trim()) {
+      backend = parseBackendId(process.env.WATERFALL_BACKEND);
+    }
+  } catch (e) {
+    throw new Error(
+      `${(e as Error).message} (check .waterfall in cwd, ~/.waterfall, or WATERFALL_BACKEND)`,
+    );
+  }
+  let specRoot: string | undefined = resolveSpecRootConfigValue(dot.specRoot);
+  if (process.env.WATERFALL_SPEC_ROOT?.trim()) {
+    specRoot = resolveSpecRootConfigValue(process.env.WATERFALL_SPEC_ROOT);
+  }
+  let executeAgent = dot.executeAgent === true;
+  let dryRun = dot.dryRun !== false;
+  if (dot.dryRun === true) {
+    dryRun = true;
+    executeAgent = false;
+  }
+  if (executeAgent) dryRun = false;
+  const logLevel = parseLogLevel(dot.level) ?? defaultLogLevel();
+  let promptDelivery: GlobalCli["promptDelivery"] = "embed";
+  const fromDot = parsePromptDelivery(dot.promptDelivery);
+  if (fromDot !== undefined) promptDelivery = fromDot;
+  return {
+    cwd: process.cwd(),
+    specRoot,
+    backend,
+    dryRun,
+    executeAgent,
+    logLevel,
+    promptDelivery,
+    useNativePandoc: dot.useNativePandoc === true,
+    syncStory: dot.syncStory,
+    syncBug: dot.syncBug,
+  };
+}
+
+function parseGlobals(argv: string[], base: GlobalCli): { g: GlobalCli; rest: string[] } {
+  const g: GlobalCli = { ...base, cwd: process.cwd() };
+  const envLevel = parseLogLevel(process.env.WATERFALL_LOG_LEVEL);
+  if (envLevel !== undefined) g.logLevel = envLevel;
+  const rest: string[] = [];
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i]!;
+    if (a === "--spec-root") {
+      g.specRoot = resolveSpecRootConfigValue(argv[++i]);
+      i++;
+      continue;
+    }
+    if (a === "--backend") {
+      g.backend = parseBackendId(argv[++i]);
+      i++;
+      continue;
+    }
+    if (a === "--dry-run") {
+      g.dryRun = true;
+      i++;
+      continue;
+    }
+    if (a === "--execute-agent") {
+      g.executeAgent = true;
+      g.dryRun = false;
+      i++;
+      continue;
+    }
+    if (a === "--log-level") {
+      const raw = argv[++i];
+      if (!raw) {
+        throw new Error("--log-level requires silent | normal | verbose");
+      }
+      const lv = parseLogLevel(raw);
+      if (lv === undefined) {
+        throw new Error(
+          `Invalid --log-level "${raw}" (use silent | normal | verbose)`,
+        );
+      }
+      g.logLevel = lv;
+      i++;
+      continue;
+    }
+    if (a === "--quiet") {
+      g.logLevel = "silent";
+      i++;
+      continue;
+    }
+    if (a === "--prompt-delivery") {
+      const raw = argv[++i];
+      if (!raw) {
+        throw new Error(
+          "--prompt-delivery requires embed | reference (see help)",
+        );
+      }
+      const d = parsePromptDelivery(raw);
+      if (d === undefined) {
+        throw new Error(
+          `Invalid --prompt-delivery "${raw}" (use embed | reference)`,
+        );
+      }
+      g.promptDelivery = d;
+      i++;
+      continue;
+    }
+    rest.push(a);
+    i++;
+  }
+  return { g, rest };
+}
+
+function planAgent(
+  g: GlobalCli,
+  specRoot: string,
+  relPrompt: string,
+  hint: string,
+): string {
+  return describeBackendInvocation(
+    g.backend,
+    specRoot,
+    relPrompt,
+    hint,
+    g.promptDelivery,
+  );
+}
+
+export type MaybeRunAgentOptions = {
+  /** `prompts/global/*.md` segments in `system` (most important first). */
+  globalPrompts: WaterfallGlobalPrompt[];
+  orchestrationContext?: string;
+  /** @default true — set false when hint already includes develop...HEAD paths (horizontal update). */
+  attachCrBranchPaths?: boolean;
+};
+
+function maybeRunAgent(
+  g: GlobalCli,
+  specRoot: string,
+  relPrompt: string,
+  hint: string,
+  options: MaybeRunAgentOptions,
+): void {
+  const attachCr = options.attachCrBranchPaths !== false;
+  const hintForPlan = attachCr
+    ? augmentAgentHintWithCrFiles(specRoot, hint)
+    : hint;
+  const line = planAgent(g, specRoot, relPrompt, hintForPlan);
+  const absPrompt = path.join(CLI_ROOT, relPrompt);
+  if (!fs.existsSync(absPrompt)) {
+    throw new Error(`Prompt file missing: ${absPrompt}`);
+  }
+  if (!g.executeAgent || g.dryRun) {
+    if (
+      g.logLevel !== "silent" &&
+      (g.backend === "cursor" || g.logLevel === "verbose")
+    ) {
+      traceTranslatedPayloadForBackend(
+        g.backend,
+        g.logLevel,
+        buildAgentWireMessage(g.backend, specRoot, absPrompt, hint, {
+          orchestrationContext: options.orchestrationContext,
+          promptDelivery: g.promptDelivery,
+          waterfallPromptsRoot: WATERFALL_PROMPTS_ROOT,
+          globalPrompts: options.globalPrompts,
+          attachCrBranchPaths: attachCr,
+        }),
+      );
+    }
+    traceDryRun(g.logLevel, line);
+    return;
+  }
+  checkBackendAvailable(g.backend, {});
+  const promptBasename = path.basename(relPrompt);
+  const model =
+    g.backend === "cline-ollama"
+      ? process.env.WATERFALL_CLINE_MODEL?.trim()
+      : undefined;
+  let promptByteLength: number | undefined;
+  try {
+    promptByteLength = fs.statSync(absPrompt).size;
+  } catch {
+    promptByteLength = undefined;
+  }
+  traceAgentInvokeStart(g.logLevel, {
+    backend: g.backend,
+    promptBasename,
+    promptRel: relPrompt,
+    specRoot,
+    hint: hintForPlan,
+    orchestrationContext: options.orchestrationContext,
+    model,
+    promptByteLength,
+  });
+  invokeAgentBackend(g.backend, specRoot, absPrompt, hint, {
+    orchestrationContext: options.orchestrationContext,
+    promptDelivery: g.promptDelivery,
+    waterfallPromptsRoot: WATERFALL_PROMPTS_ROOT,
+    globalPrompts: options.globalPrompts,
+    attachCrBranchPaths: attachCr,
+    logLevel: g.logLevel,
+  });
+  traceAgentInvokeDone(g.logLevel, {
+    backend: g.backend,
+    promptBasename,
+  });
+}
+
+function orchestrate(
+  g: GlobalCli,
+  specRoot: string,
+  order: LifecycleStep[],
+  batchLabel: string,
+  hint: string,
+  globalPrompts: WaterfallGlobalPrompt[],
+): void {
+  assertBranchForCrScopedCommand(specRoot, batchLabel);
+  for (let i = 0; i < order.length; i++) {
+    const step = order[i]!;
+    const rel = promptFileForStep(step);
+    const orchestrationContext = `${batchLabel} — step ${i + 1}/${order.length}`;
+    maybeRunAgent(g, specRoot, rel, `[${step}] ${hint}`, {
+      globalPrompts,
+      orchestrationContext,
+    });
+  }
+}
+
+export function runWaterfallCli(argv: string[]): number {
+  const created = ensureDotWaterfallFile();
+  const dot = loadDotWaterfallConfig();
+  applyDotWaterfallEnvExports(dot.envExports);
+  const base = buildGlobalCliBase(dot);
+  const { g, rest } = parseGlobals(argv, base);
+  if (created) {
+    process.stderr.write(
+      `[waterfall] Created ${dotWaterfallPath()} with commented examples (user defaults). Per-project overrides: add .waterfall in the working directory (wins over ~/.waterfall).\n`,
+    );
+  }
+  if (rest.length === 0 || rest[0] === "-?" || rest[0] === "--help") {
+    printHelp();
+    return 0;
+  }
+
+  if (rest[0] === "help") {
+    try {
+      const { format } = parseHelpFormat(rest);
+      if (format === "json") {
+        process.stdout.write(formatCliHelpJson());
+        return 0;
+      }
+    } catch (e) {
+      process.stderr.write(`${(e as Error).message}\n`);
+      return 1;
+    }
+    printHelp();
+    return 0;
+  }
+
+  if (rest[0] === "spec" && rest[1] === "init") {
+    try {
+      const { full, title, targetDir } = parseSpecInitCliArgs(rest.slice(2));
+      runSpecInit(g.cwd, targetDir, { full, title });
+      process.stdout.write(
+        `[waterfall] Initialized spec scaffold${full ? " (full)" : ""}: ${path.resolve(g.cwd, targetDir)}\n`,
+      );
+      return 0;
+    } catch (e) {
+      process.stderr.write(`${(e as Error).message}\n`);
+      return 1;
+    }
+  }
+
+  let specRoot: string;
+  try {
+    specRoot = resolveSpecRoot({
+      cwd: g.cwd,
+      env: process.env,
+      explicitSpecRoot: g.specRoot,
+    });
+    assertSpecRoot(specRoot);
+  } catch (e) {
+    process.stderr.write(`${(e as Error).message}\n`);
+    return 1;
+  }
+
+  try {
+    const commandCtx = {
+      g,
+      specRoot,
+      runAgentPrompt: (
+        relPrompt: string,
+        hint: string,
+        globalPrompts: WaterfallGlobalPrompt[],
+        orchestrationContext?: string,
+        runOpts?: RunAgentPromptOptions,
+      ) =>
+        maybeRunAgent(g, specRoot, relPrompt, hint, {
+          globalPrompts,
+          orchestrationContext,
+          attachCrBranchPaths: runOpts?.attachCrBranchPaths,
+        }),
+      runOrchestrate: (
+        order: LifecycleStep[],
+        batchLabel: string,
+        hint: string,
+        globalPrompts: WaterfallGlobalPrompt[],
+      ) => orchestrate(g, specRoot, order, batchLabel, hint, globalPrompts),
+    };
+
+    const dispatched = dispatchSpecCommand(commandCtx, rest);
+    if (dispatched !== null) {
+      return dispatched;
+    }
+
+    process.stderr.write(`Unknown command: ${rest.join(" ")}\n`);
+    printHelp();
+    return 1;
+  } catch (e) {
+    process.stderr.write(`${(e as Error).message}\n`);
+    return 1;
+  }
+}

package/lib/cli/paths.ts

@@ -0,0 +1,9 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** `waterfall-cli` package root (contains `lib/`, `prompts/`, `node_modules/`). */
+export const WATERFALL_CLI_PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);

package/lib/cli/project/pom-json.ts

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const POM_JSON_BASENAME = "pom.json";
+
+export type PomJson = {
+  title: string;
+  [key: string]: unknown;
+};
+
+/** Walk upward from `startAbs` (typically spec root) until `pom.json` exists. */
+export function findPomJsonPath(startAbs: string): string | undefined {
+  let dir = path.resolve(startAbs);
+  const { root } = path.parse(dir);
+  for (;;) {
+    const candidate = path.join(dir, POM_JSON_BASENAME);
+    if (fs.existsSync(candidate)) return candidate;
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+/**
+ * Project title from `pom.json` for `export pdf` (PDF metadata and document H1).
+ * @throws Error if no file or invalid / missing `title`
+ */
+export function readPomProjectTitle(specRootAbs: string): string {
+  const pomPath = findPomJsonPath(specRootAbs);
+  if (!pomPath) {
+    throw new Error(
+      `[waterfall] export pdf: no ${POM_JSON_BASENAME} found (searching upward from the spec root). Add a ${POM_JSON_BASENAME} with a non-empty string "title" at the project root, or run: waterfall spec init --title "…" [DIR]`,
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(pomPath, "utf8"));
+  } catch (e) {
+    throw new Error(
+      `[waterfall] ${POM_JSON_BASENAME} is not valid JSON at ${pomPath}: ${(e as Error).message}`,
+    );
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(
+      `[waterfall] ${POM_JSON_BASENAME} must be a JSON object at ${pomPath}`,
+    );
+  }
+  const title = (raw as { title?: unknown }).title;
+  if (typeof title !== "string" || !title.trim()) {
+    throw new Error(
+      `[waterfall] ${POM_JSON_BASENAME} must include a non-empty string "title" at ${pomPath}`,
+    );
+  }
+  return title.trim();
+}