@pknx/waterfall-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Waterfall CLI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @pknx/waterfall-cli
+
+Command-line tool for **waterfall-spec** workflows: change requests, stories, agent prompts (Cursor / Cline / Claude Code), sync with work trackers, and PDF export.
+
+The executable name on your PATH is **`waterfall`** (not the last segment of the package name).
+
+> **Unscoped name:** [`waterfall-cli`](https://www.npmjs.com/package/waterfall-cli) on npm is a different package. This project publishes as **`@pknx/waterfall-cli`**.
+
+## Requirements
+
+- **Node.js** 20 or newer (22 recommended)
+- Git (for branch workflows and `spec init`)
+
+Heavy features (diagrams, PDF) pull in optional tooling such as Puppeteer and Pandoc-related packages; first install may take a moment.
+
+## Install
+
+```bash
+npm install -g @pknx/waterfall-cli
+```
+
+Then:
+
+```bash
+waterfall --help
+```
+
+One-off run without a global install:
+
+```bash
+npx @pknx/waterfall-cli --help
+```
+
+## Quick start
+
+Inside or above your spec repo:
+
+```bash
+waterfall help
+waterfall spec init --title "My product" ./my-spec
+```
+
+Configure defaults with a `.waterfall` file in the project (see `waterfall help` and built-in comments when the file is created).
+
+## Publish checklist (maintainers)
+
+1. Bump **`version`** in `package.json` (semver). Current line: **0.1.0**.
+2. Update this README if install or behavior changed.
+3. Run **`npm test`** and **`npm run pack:check`**.
+4. **`npm login`** (one-time per machine) then from this directory:
+
+   ```bash
+   npm publish
+   ```
+
+   Scoped package **`@pknx/waterfall-cli`** uses `"publishConfig": { "access": "public" }` so the first publish does not require passing `--access public` manually.
+
+5. Optional: enable **GitHub Actions** publish by adding an npm automation token as repository secret **`NPM_TOKEN`** and using the workflow in `.github/workflows/publish-npm.yml` (on release publish).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/waterfall.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const entry = path.join(root, "lib/cli/entry.ts");
+// Preserve invoking cwd so ./.waterfall and spec walk-up resolve like other CLIs (not forced to package root).
+const r = spawnSync(
+  process.execPath,
+  ["--import", "tsx", entry, ...process.argv.slice(2)],
+  { stdio: "inherit", cwd: process.cwd(), env: process.env },
+);
+process.exit(r.status === null ? 1 : r.status);

package/lib/cli/agent/agent-message.ts

@@ -0,0 +1,71 @@
+/**
+ * Intermediate agent message: paths + metadata only (no backend-specific wire format).
+ * Translators in `agent-translators.ts` turn this into strings or argv for each CLI.
+ */
+import { formatCrBranchChangedFilesBlock } from "../git/cr-agent-context";
+import type { WaterfallGlobalPrompt } from "./global-prompts";
+
+/** How workflow markdown is supplied to the agent (translator reads file when embed). */
+export type PromptDelivery = "embed" | "reference";
+
+export function parsePromptDelivery(
+  raw: string | undefined,
+): PromptDelivery | undefined {
+  if (!raw?.trim()) return undefined;
+  const v = raw.trim().toLowerCase().replace(/_/g, "-");
+  if (v === "embed" || v === "inline") return "embed";
+  if (v === "reference" || v === "ref" || v === "path") return "reference";
+  return undefined;
+}
+
+export type WaterfallAgentMessage = {
+  /** Spec repository root (agent workspace). */
+  specRoot: string;
+  /** Primary workflow markdown (absolute path under waterfall-cli `prompts/`). */
+  workflowAbsolutePath: string;
+  /** `<waterfall-cli>/prompts` — sibling trees: global/, commands/, items/. */
+  waterfallPromptsRoot: string;
+  promptDelivery: PromptDelivery;
+  /** Raw operator hint (may be empty). */
+  operatorHint: string;
+  /**
+   * When on a CR feature branch, git diff path list for scope (separate `user` segment from `operatorHint`).
+   */
+  crBranchChangedPathsBlock?: string;
+  /** `prompts/global/*.md` to cite in `system` (most important first). */
+  globalPrompts: WaterfallGlobalPrompt[];
+  orchestrationContext?: string;
+};
+
+export type BuildAgentMessageOpts = {
+  orchestrationContext?: string;
+  promptDelivery?: PromptDelivery;
+  waterfallPromptsRoot: string;
+  globalPrompts: WaterfallGlobalPrompt[];
+  /**
+   * When false, omit the CR-branch `develop...HEAD` path list — use when the operator hint
+   * already embeds that scope (e.g. `horizontal update`).
+   * @default true
+   */
+  attachCrBranchPaths?: boolean;
+};
+
+export function buildWaterfallAgentMessage(
+  specRoot: string,
+  absPromptPath: string,
+  hint: string,
+  opts: BuildAgentMessageOpts,
+): WaterfallAgentMessage {
+  const attachCr = opts.attachCrBranchPaths !== false;
+  const crBlock = attachCr ? formatCrBranchChangedFilesBlock(specRoot) : "";
+  return {
+    specRoot,
+    workflowAbsolutePath: absPromptPath,
+    waterfallPromptsRoot: opts.waterfallPromptsRoot,
+    promptDelivery: opts.promptDelivery ?? "embed",
+    operatorHint: hint,
+    crBranchChangedPathsBlock: crBlock.trim() ? crBlock : undefined,
+    globalPrompts: [...opts.globalPrompts],
+    orchestrationContext: opts.orchestrationContext,
+  };
+}

package/lib/cli/agent/agent-translators.ts

@@ -0,0 +1,145 @@
+/**
+ * Translators: WaterfallAgentMessage → wire format for a specific agent CLI.
+ * Each backend has its own entry point (`translateCursor`, `translateClaudeCode`, …)
+ * so you can change one tool’s payload without touching the others.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import type { BackendId } from "./backends";
+import type { PromptDelivery, WaterfallAgentMessage } from "./agent-message";
+import {
+  GLOBAL_PROMPT_DESCRIPTION,
+  type WaterfallGlobalPrompt,
+} from "./global-prompts";
+
+/** One piece of system or user content: inline text and/or a file to read (absolute path). */
+export type AgentPromptSegment =
+  | { kind: "text"; text: string }
+  | { kind: "file"; path: string; description: string };
+
+/** Structured payload before a backend flattens or forwards it (e.g. JSON on the CLI argv). */
+export type WaterfallAgentPayload = {
+  system: AgentPromptSegment[];
+  user: AgentPromptSegment[];
+};
+
+export type AgentTranslator = (msg: WaterfallAgentMessage) => string;
+
+function globalFile(
+  promptsRoot: string,
+  name: string,
+  description: string,
+): AgentPromptSegment {
+  return {
+    kind: "file",
+    path: path.join(promptsRoot, "global", name),
+    description,
+  };
+}
+
+/** `prompts/global/*` from `msg.globalPrompts` order, then the spec repo’s CURSOR.md. */
+function globalPromptSegments(msg: WaterfallAgentMessage): AgentPromptSegment[] {
+  const fromCommands: AgentPromptSegment[] = msg.globalPrompts.map(
+    (gp: WaterfallGlobalPrompt) =>
+      globalFile(
+        msg.waterfallPromptsRoot,
+        gp,
+        GLOBAL_PROMPT_DESCRIPTION[gp],
+      ),
+  );
+  const specLaw: AgentPromptSegment = {
+    kind: "file",
+    path: path.join(msg.specRoot, "CURSOR.md"),
+    description:
+      "This repository: layout, branching, artifact graph — normative spec law",
+  };
+  return [...fromCommands, specLaw];
+}
+
+function buildWaterfallAgentPayload(msg: WaterfallAgentMessage): WaterfallAgentPayload {
+  const delivery: PromptDelivery = msg.promptDelivery;
+  const hint = msg.operatorHint;
+  const hintBlock = hint.trim() ? hint : "(none)";
+
+  const system: AgentPromptSegment[] = [
+    {
+      kind: "text",
+      text: `Repository root (spec workspace): ${msg.specRoot}`,
+    },
+    {
+      kind: "file",
+      path: msg.workflowAbsolutePath,
+      description:
+        "Primary workflow for this CLI command — execute its steps and scope",
+    },
+    {
+      kind: "text",
+      text: `Waterfall CLI prompts root: ${msg.waterfallPromptsRoot}`,
+    },
+    ...globalPromptSegments(msg),
+  ];
+
+  if (msg.orchestrationContext) {
+    system.push({
+      kind: "text",
+      text: msg.orchestrationContext,
+    });
+    system.push({
+      kind: "text",
+      text: 'Follow the "CLI orchestration" section in the primary workflow markdown.',
+    });
+  }
+
+  const user: AgentPromptSegment[] = [{ kind: "text", text: hintBlock }];
+  if (msg.crBranchChangedPathsBlock?.trim()) {
+    user.push({
+      kind: "text",
+      text: msg.crBranchChangedPathsBlock.trimEnd(),
+    });
+  }
+
+  if (delivery !== "reference") {
+    const body = fs.readFileSync(msg.workflowAbsolutePath, "utf8");
+    user.push({ kind: "text", text: body });
+  }
+
+  return { system, user };
+}
+
+/**
+ * JSON wire string with structured `system` / `user` segment arrays.
+ * Wire-format framing (if any) belongs in backend translators; this payload stays data-oriented.
+ */
+function jsonStructuredWire(msg: WaterfallAgentMessage): string {
+  const payload = buildWaterfallAgentPayload(msg);
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}
+
+/** Cursor CLI (`agent` / `cursor -p`): one positional prompt after flags. */
+export function translateCursor(msg: WaterfallAgentMessage): string {
+  return jsonStructuredWire(msg);
+}
+
+/** Claude Code CLI (`claude -p`): one positional prompt; swap implementation for `--input-format` etc. */
+export function translateClaudeCode(msg: WaterfallAgentMessage): string {
+  return jsonStructuredWire(msg);
+}
+
+/** Cline CLI (`cline -y`): one positional prompt after optional `-m`. */
+export function translateClineOllama(msg: WaterfallAgentMessage): string {
+  return jsonStructuredWire(msg);
+}
+
+export const agentTranslators: Record<BackendId, AgentTranslator> = {
+  cursor: translateCursor,
+  "claude-code": translateClaudeCode,
+  "cline-ollama": translateClineOllama,
+};
+
+export function translateAgentPrompt(
+  backend: BackendId,
+  msg: WaterfallAgentMessage,
+): string {
+  const t = agentTranslators[backend];
+  return t(msg);
+}

package/lib/cli/agent/backend-invoke.ts

@@ -0,0 +1,133 @@
+/**
+ * CR-005: spawn the selected agent backend after building an intermediate message
+ * and running it through a backend-specific translator.
+ */
+import * as exec from "../core/exec-file";
+import type { BackendId } from "./backends";
+import * as backends from "./backends";
+import {
+  buildWaterfallAgentMessage,
+  type PromptDelivery,
+} from "./agent-message";
+import type { WaterfallGlobalPrompt } from "./global-prompts";
+import type { LogLevel } from "../core/cli-log";
+import { traceTranslatedPayloadForBackend } from "../core/cli-log";
+import { translateAgentPrompt } from "./agent-translators";
+
+export type { PromptDelivery, WaterfallAgentMessage } from "./agent-message";
+export { parsePromptDelivery } from "./agent-message";
+
+export type {
+  AgentPromptSegment,
+  WaterfallAgentPayload,
+} from "./agent-translators";
+
+export type InvokeAgentBackendOpts = {
+  orchestrationContext?: string;
+  promptDelivery?: PromptDelivery;
+  waterfallPromptsRoot: string;
+  globalPrompts: WaterfallGlobalPrompt[];
+  attachCrBranchPaths?: boolean;
+  /**
+   * Tracing: defaults to `normal`. Cursor also echoes the full JSON wire to stdout when not `silent`.
+   * Other backends echo only when `verbose`.
+   */
+  logLevel?: LogLevel;
+};
+
+/** Build the same JSON string passed to the backend as the positional prompt. */
+export function buildAgentWireMessage(
+  backend: BackendId,
+  specRoot: string,
+  absPromptPath: string,
+  hint: string,
+  opts: InvokeAgentBackendOpts,
+): string {
+  const messageModel = buildWaterfallAgentMessage(specRoot, absPromptPath, hint, {
+    orchestrationContext: opts.orchestrationContext,
+    promptDelivery: opts.promptDelivery,
+    waterfallPromptsRoot: opts.waterfallPromptsRoot,
+    globalPrompts: opts.globalPrompts,
+    attachCrBranchPaths: opts.attachCrBranchPaths,
+  });
+  return translateAgentPrompt(backend, messageModel);
+}
+
+/**
+ * Run the backend process with stdio inherited (operator sees streaming output).
+ * Caller must ensure the prompt file exists and backend is on PATH.
+ */
+export function invokeAgentBackend(
+  backend: BackendId,
+  specRoot: string,
+  absPromptPath: string,
+  hint: string,
+  opts: InvokeAgentBackendOpts,
+): void {
+  const message = buildAgentWireMessage(
+    backend,
+    specRoot,
+    absPromptPath,
+    hint,
+    opts,
+  );
+  traceTranslatedPayloadForBackend(
+    backend,
+    opts.logLevel ?? "normal",
+    message,
+  );
+
+  switch (backend) {
+    case "cursor": {
+      const bin = backends.resolveCursorCliBinary();
+      // Flags must come before the positional prompt (otherwise --output-format can be misparsed or swallowed).
+      // --approve-mcps: headless MCP consent; --sandbox disabled: avoid sandbox waits on git/file tools.
+      exec.execFileSync(
+        bin,
+        [
+          "-p",
+          "--force",
+          "--approve-mcps",
+          "--sandbox",
+          "disabled",
+          "--output-format",
+          "text",
+          "--workspace",
+          specRoot,
+          message,
+        ],
+        {
+          cwd: specRoot,
+          stdio: "inherit",
+          env: process.env,
+        },
+      );
+      break;
+    }
+    case "claude-code": {
+      exec.execFileSync("claude", ["-p", message, "--output-format", "text"], {
+        cwd: specRoot,
+        stdio: "inherit",
+        env: process.env,
+      });
+      break;
+    }
+    case "cline-ollama": {
+      // Cline is the agent; Ollama is the in-Cline provider (CR-005). -y: headless auto-approve.
+      // Large argv payloads must still pass -m: Cline may not apply saved model id to every task.
+      const model = process.env.WATERFALL_CLINE_MODEL?.trim();
+      const argv = model ? ["-y", "-m", model, message] : ["-y", message];
+      exec.execFileSync("cline", argv, {
+        cwd: specRoot,
+        stdio: "inherit",
+        env: process.env,
+      });
+      break;
+    }
+    default: {
+      const _exhaustive: never = backend;
+      void _exhaustive;
+      throw new Error("Unknown backend");
+    }
+  }
+}

package/lib/cli/agent/backends.ts

@@ -0,0 +1,100 @@
+import { execSync } from "node:child_process";
+import type { PromptDelivery } from "./agent-message";
+
+export type BackendId = "cline-ollama" | "cursor" | "claude-code";
+
+/** Cursor ships the `agent` CLI; some installs expose `cursor` instead (CR-005). */
+export function resolveCursorCliBinary(): string {
+  try {
+    execSync("command -v agent", { stdio: "ignore" });
+    return "agent";
+  } catch {
+    try {
+      execSync("command -v cursor", { stdio: "ignore" });
+      return "cursor";
+    } catch {
+      throw new Error(
+        "Cursor backend: neither `agent` nor `cursor` found on PATH. Install Cursor CLI: https://cursor.com/docs/cli/overview",
+      );
+    }
+  }
+}
+
+export type BackendCheckOptions = {
+  /** When true, skip PATH probes (unit tests). */
+  skipPathCheck?: boolean;
+};
+
+export function parseBackendId(s: string | undefined): BackendId {
+  const v = (s ?? "cline-ollama").toLowerCase().replace(/_/g, "-");
+  if (v === "cline" || v === "cline-ollama") return "cline-ollama";
+  if (v === "ollama") {
+    throw new Error(
+      'Backend id "ollama" is invalid. Use --backend cline-ollama (Cline CLI). Configure Ollama as a provider inside Cline (`cline auth`), not as a separate waterfall backend.',
+    );
+  }
+  if (v === "cursor" || v === "cursor-cli") return "cursor";
+  if (v === "claude" || v === "claude-code" || v === "anthropic")
+    return "claude-code";
+  throw new Error(
+    `Unknown backend "${s}". Use: cline-ollama | cursor | claude-code`,
+  );
+}
+
+/** Fail fast when the underlying tool is not on PATH (unless skipPathCheck). */
+export function checkBackendAvailable(
+  id: BackendId,
+  opts: BackendCheckOptions = {},
+): void {
+  if (opts.skipPathCheck) return;
+  switch (id) {
+    case "cline-ollama":
+      try {
+        execSync("command -v cline", { stdio: "ignore" });
+      } catch {
+        throw new Error(
+          "Backend cline-ollama: `cline` CLI not on PATH. Install: npm install -g cline — https://docs.cline.bot/cline-cli/getting-started (configure Ollama or other models via `cline auth`).",
+        );
+      }
+      break;
+    case "cursor":
+      try {
+        resolveCursorCliBinary();
+      } catch (e) {
+        throw new Error(
+          (e as Error).message ||
+            "Backend cursor: install Cursor CLI (`agent` or `cursor` on PATH).",
+        );
+      }
+      break;
+    case "claude-code":
+      try {
+        execSync("command -v claude", { stdio: "ignore" });
+      } catch {
+        throw new Error(
+          "Backend claude-code: `claude` CLI not found on PATH. Install Claude Code or use another --backend.",
+        );
+      }
+      break;
+  }
+}
+
+export function describeBackendInvocation(
+  id: BackendId,
+  specRoot: string,
+  promptRelativePath: string,
+  hint: string,
+  promptDelivery: PromptDelivery = "embed",
+): string {
+  const promptPath = promptRelativePath;
+  const delivery =
+    promptDelivery === "reference" ? " prompt_delivery=reference" : "";
+  switch (id) {
+    case "cline-ollama":
+      return `[cline-ollama] specRoot=${specRoot} prompt=${promptPath}${delivery} hint=${JSON.stringify(hint)} (invoke: cline -y … headless; Ollama = provider in Cline, not raw ollama run)`;
+    case "cursor":
+      return `[cursor] specRoot=${specRoot} prompt=${promptPath}${delivery} hint=${JSON.stringify(hint)} (invoke: agent -p --force --approve-mcps --sandbox disabled --output-format text --workspace <specRoot> <payload>)`;
+    case "claude-code":
+      return `[claude-code] specRoot=${specRoot} prompt=${promptPath}${delivery} hint=${JSON.stringify(hint)} (invoke: claude -p … --output-format text)`;
+  }
+}

package/lib/cli/agent/global-prompts.ts

@@ -0,0 +1,55 @@
+/**
+ * Files under `waterfall-cli/prompts/global/`. Each agent run lists an ordered subset
+ * (most important first) for `system` file segments.
+ */
+export enum WaterfallGlobalPrompt {
+  BeforeChangingSpec = "before-changing-spec.md",
+  WorkflowsIndex = "workflows-index.md",
+  CursorOverview = "cursor-overview.md",
+  GitUsage = "git-usage.md",
+  ContentRequirementsVsUseCases = "content-requirements-vs-use-cases.md",
+  HorizontalStructure = "horizontal-structure.md",
+}
+
+/** Short labels for `kind: "file"` segments (agent reads path on disk). */
+export const GLOBAL_PROMPT_DESCRIPTION: Record<WaterfallGlobalPrompt, string> = {
+  [WaterfallGlobalPrompt.BeforeChangingSpec]:
+    "Cross-artifact rules, operator hint policy (interpret for judgment; never paste verbatim into Summary/Purpose/titles), prompts are not spec filler",
+  [WaterfallGlobalPrompt.WorkflowsIndex]:
+    "Lifecycle edges, CLI wire embed vs reference delivery, operator-hint behavior, command → prompt map",
+  [WaterfallGlobalPrompt.CursorOverview]:
+    "How CURSOR.md relates to prompts and the spec tree",
+  [WaterfallGlobalPrompt.GitUsage]:
+    "Git baseline develop, diffs, and review habits for spec work",
+  [WaterfallGlobalPrompt.ContentRequirementsVsUseCases]:
+    "Requirements vs use cases — content shape and layering",
+  [WaterfallGlobalPrompt.HorizontalStructure]:
+    "Horizontal (HOR) kinds, sections, and aggregation rules",
+};
+
+/**
+ * Default for lifecycle edges and `* all` orchestration: edit rules, RQ/UC content
+ * shape, workflow map, then CURSOR’s role.
+ */
+export const AGENT_GLOBAL_PROMPTS_LIFECYCLE: WaterfallGlobalPrompt[] = [
+  WaterfallGlobalPrompt.BeforeChangingSpec,
+  WaterfallGlobalPrompt.ContentRequirementsVsUseCases,
+  WaterfallGlobalPrompt.WorkflowsIndex,
+  WaterfallGlobalPrompt.CursorOverview,
+];
+
+/** `horizontal update`: add HOR shape after workflow index. */
+export const AGENT_GLOBAL_PROMPTS_HORIZONTAL_UPDATE: WaterfallGlobalPrompt[] = [
+  WaterfallGlobalPrompt.BeforeChangingSpec,
+  WaterfallGlobalPrompt.WorkflowsIndex,
+  WaterfallGlobalPrompt.HorizontalStructure,
+  WaterfallGlobalPrompt.CursorOverview,
+];
+
+/** `horizontal create`: refine scaffold Purpose (Aggregated definitions follow `horizontal update`). */
+export const AGENT_GLOBAL_PROMPTS_HORIZONTAL_CREATE: WaterfallGlobalPrompt[] = [
+  WaterfallGlobalPrompt.BeforeChangingSpec,
+  WaterfallGlobalPrompt.WorkflowsIndex,
+  WaterfallGlobalPrompt.HorizontalStructure,
+  WaterfallGlobalPrompt.CursorOverview,
+];