@pknx/waterfall-cli 0.1.0

package/lib/cli/config/dot-waterfall.ts

@@ -0,0 +1,404 @@
+/**
+ * CLI config: `.waterfall` in the working directory and `~/.waterfall` (key=value, # comments).
+ * File merge: cwd wins over home for each key. Full precedence:
+ * argv flags > process.env (WATERFALL_*) > ./.waterfall > ~/.waterfall > defaults.
+ * Log level: WATERFALL_LOG_LEVEL or `level=` in .waterfall; flags --log-level / --quiet override.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { SyncWorkItemBlock } from "./sync-work-item-config";
+import { emptySyncWorkItemBlock, parseSyncLead } from "./sync-work-item-config";
+
+export const DOT_WATERFALL_BASENAME = ".waterfall";
+
+/** Real home, or WATERFALL_TEST_HOME when set (Vitest setup). */
+export function waterfallConfigHome(): string {
+  const t = process.env.WATERFALL_TEST_HOME?.trim();
+  if (t) return t;
+  return os.homedir();
+}
+
+export function dotWaterfallPath(home: string = waterfallConfigHome()): string {
+  return path.join(home, DOT_WATERFALL_BASENAME);
+}
+
+/** Project-local config: `<cwd>/.waterfall` */
+export function dotWaterfallPathCwd(cwd: string = process.cwd()): string {
+  return path.join(path.resolve(cwd), DOT_WATERFALL_BASENAME);
+}
+
+export type DotWaterfallParsed = {
+  backend?: string;
+  specRoot?: string;
+  /** CLI trace: silent | normal | verbose */
+  level?: string;
+  dryRun?: boolean;
+  executeAgent?: boolean;
+  /** embed | reference — how workflow markdown is passed to the agent (see --prompt-delivery) */
+  promptDelivery?: string;
+  /** true: `export pdf` uses system pandoc; false/omit: bundled pandoc-wasm + puppeteer */
+  useNativePandoc?: boolean;
+  /** `waterfall sync stories` — see sync_story_* keys in .waterfall */
+  syncStory?: SyncWorkItemBlock;
+  /** `waterfall sync bugs` — see sync_bug_* keys in .waterfall */
+  syncBug?: SyncWorkItemBlock;
+  /** UPPER_SNAKE=value merged into env for backend child processes */
+  envExports: Record<string, string>;
+};
+
+function parseBool(raw: string): boolean | undefined {
+  const v = raw.trim().toLowerCase();
+  if (v === "true" || v === "1" || v === "yes" || v === "on") return true;
+  if (v === "false" || v === "0" || v === "no" || v === "off") return false;
+  return undefined;
+}
+
+/** Known keys are stripped; remaining UPPER_SNAKE keys go to envExports. */
+export function parseDotWaterfallContent(content: string): DotWaterfallParsed {
+  const out: DotWaterfallParsed = { envExports: {} };
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let val = trimmed.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    const lower = key.toLowerCase().replace(/-/g, "_");
+    if (lower === "backend") {
+      out.backend = val;
+      continue;
+    }
+    if (lower === "spec_root" || lower === "specroot") {
+      out.specRoot = val;
+      continue;
+    }
+    if (
+      lower === "level" ||
+      lower === "log_level" ||
+      lower === "verbosity"
+    ) {
+      out.level = val;
+      continue;
+    }
+    if (lower === "dry_run" || lower === "dryrun") {
+      const b = parseBool(val);
+      if (b !== undefined) out.dryRun = b;
+      continue;
+    }
+    if (lower === "execute_agent" || lower === "executeagent") {
+      const b = parseBool(val);
+      if (b !== undefined) out.executeAgent = b;
+      continue;
+    }
+    if (lower === "prompt_delivery" || lower === "promptdelivery") {
+      out.promptDelivery = val;
+      continue;
+    }
+    if (
+      lower === "use_native_pandoc" ||
+      lower === "usenativepandoc" ||
+      lower === "native_pandoc" ||
+      lower === "nativepandoc"
+    ) {
+      const b = parseBool(val);
+      if (b !== undefined) out.useNativePandoc = b;
+      continue;
+    }
+    if (lower.startsWith("sync_story_")) {
+      const suffix = lower.slice("sync_story_".length);
+      if (!out.syncStory) out.syncStory = emptySyncWorkItemBlock();
+      if (suffix === "direction") {
+        continue;
+      }
+      if (suffix === "provider") {
+        out.syncStory.provider = val;
+        continue;
+      }
+      if (suffix === "leading") {
+        const l = parseSyncLead(val);
+        if (l) out.syncStory.leading = l;
+        continue;
+      }
+      out.syncStory.options[suffix] = val;
+      continue;
+    }
+    if (lower.startsWith("sync_bug_")) {
+      const suffix = lower.slice("sync_bug_".length);
+      if (!out.syncBug) out.syncBug = emptySyncWorkItemBlock();
+      if (suffix === "direction") {
+        continue;
+      }
+      if (suffix === "provider") {
+        out.syncBug.provider = val;
+        continue;
+      }
+      if (suffix === "leading") {
+        const l = parseSyncLead(val);
+        if (l) out.syncBug.leading = l;
+        continue;
+      }
+      out.syncBug.options[suffix] = val;
+      continue;
+    }
+    if (/^[A-Z][A-Z0-9_]*$/.test(key)) {
+      out.envExports[key] = val;
+    }
+  }
+  return out;
+}
+
+function readDotWaterfallFile(absPath: string): DotWaterfallParsed {
+  if (!fs.existsSync(absPath)) return { envExports: {} };
+  try {
+    return parseDotWaterfallContent(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return { envExports: {} };
+  }
+}
+
+/** Overlay wins for defined fields; envExports are merged (overlay keys replace). */
+export function mergeDotWaterfallParsed(
+  base: DotWaterfallParsed,
+  overlay: DotWaterfallParsed,
+): DotWaterfallParsed {
+  return {
+    backend: overlay.backend ?? base.backend,
+    specRoot: overlay.specRoot ?? base.specRoot,
+    level: overlay.level ?? base.level,
+    dryRun: overlay.dryRun !== undefined ? overlay.dryRun : base.dryRun,
+    executeAgent:
+      overlay.executeAgent !== undefined ? overlay.executeAgent : base.executeAgent,
+    promptDelivery: overlay.promptDelivery ?? base.promptDelivery,
+    useNativePandoc:
+      overlay.useNativePandoc !== undefined
+        ? overlay.useNativePandoc
+        : base.useNativePandoc,
+    syncStory: mergeSyncWorkItemBlock(base.syncStory, overlay.syncStory),
+    syncBug: mergeSyncWorkItemBlock(base.syncBug, overlay.syncBug),
+    envExports: { ...base.envExports, ...overlay.envExports },
+  };
+}
+
+function mergeSyncWorkItemBlock(
+  base: SyncWorkItemBlock | undefined,
+  overlay: SyncWorkItemBlock | undefined,
+): SyncWorkItemBlock | undefined {
+  if (!overlay && !base) return undefined;
+  if (!overlay) return base;
+  if (!base) return overlay;
+  return {
+    leading: overlay.leading ?? base.leading,
+    provider: overlay.provider ?? base.provider,
+    options: { ...base.options, ...overlay.options },
+  };
+}
+
+export type LoadDotWaterfallOptions = {
+  /** Defaults to waterfallConfigHome() */
+  home?: string;
+  /** Defaults to process.cwd() */
+  cwd?: string;
+};
+
+/**
+ * Load `~/.waterfall` then merge `<cwd>/.waterfall` on top (working directory wins).
+ */
+export function loadDotWaterfallConfig(opts?: LoadDotWaterfallOptions): DotWaterfallParsed {
+  const home = opts?.home ?? waterfallConfigHome();
+  const cwd = opts?.cwd ?? process.cwd();
+  const fromHome = readDotWaterfallFile(dotWaterfallPath(home));
+  const fromCwd = readDotWaterfallFile(dotWaterfallPathCwd(cwd));
+  return mergeDotWaterfallParsed(fromHome, fromCwd);
+}
+
+/**
+ * Machine-readable `.waterfall` / `~/.waterfall` documentation for `waterfall help -o json`.
+ * Stays aligned with {@link parseDotWaterfallContent}.
+ */
+export const CLI_JSON_DOT_WATERFALL = {
+  description:
+    "Optional key=value config files merged before flags and env (cwd file wins over home per key).",
+  syntax: {
+    format: "One KEY=value per line; leading/trailing whitespace trimmed; # starts a comment line.",
+    quotedValues: "Values may be wrapped in double or single quotes.",
+  },
+  files: [
+    {
+      path: "~/.waterfall",
+      role: "User-wide defaults; created with a commented template on first CLI run when missing.",
+    },
+    {
+      path: ".waterfall",
+      role: "Working-directory overrides; wins over ~/.waterfall for each key.",
+    },
+  ],
+  merge: "Read ~/.waterfall then merge ./.waterfall (overlay replaces per field).",
+  knownKeys: [
+    {
+      keys: ["backend"],
+      valueType: "enum" as const,
+      enumValues: ["cline-ollama", "cursor", "claude-code"],
+      description: "Agent backend for prompt commands.",
+      cliFlag: "--backend",
+      env: "WATERFALL_BACKEND",
+    },
+    {
+      keys: ["spec_root", "specroot"],
+      valueType: "path" as const,
+      description: "Filesystem path to waterfall-spec root (optional).",
+      cliFlag: "--spec-root",
+      env: "WATERFALL_SPEC_ROOT",
+    },
+    {
+      keys: ["level", "log_level", "verbosity"],
+      valueType: "enum" as const,
+      enumValues: ["silent", "normal", "verbose"],
+      description: "CLI trace verbosity.",
+      cliFlag: "--log-level",
+      env: "WATERFALL_LOG_LEVEL",
+    },
+    {
+      keys: ["dry_run", "dryrun"],
+      valueType: "boolean" as const,
+      description: "true: plan agent runs only; false: allow execute when combined with execute_agent.",
+      cliFlag: "--dry-run",
+    },
+    {
+      keys: ["execute_agent", "executeagent"],
+      valueType: "boolean" as const,
+      description: "true: spawn real backend CLIs; false: dry-run only.",
+      cliFlag: "--execute-agent",
+    },
+    {
+      keys: ["prompt_delivery", "promptdelivery"],
+      valueType: "enum" as const,
+      enumValues: ["embed", "reference"],
+      description: "How workflow markdown is passed to the agent.",
+      cliFlag: "--prompt-delivery",
+    },
+    {
+      keys: [
+        "use_native_pandoc",
+        "usenativepandoc",
+        "native_pandoc",
+        "nativepandoc",
+      ],
+      valueType: "boolean" as const,
+      description:
+        "true: `waterfall export pdf` invokes system `pandoc` (see WATERFALL_PANDOC_ARGS); false: bundled pandoc-wasm + puppeteer.",
+      dotWaterfallKey: "use_native_pandoc",
+    },
+    {
+      keys: ["sync_story_provider", "sync_bug_provider"],
+      valueType: "string" as const,
+      description:
+        "Tracker adapter id: jira (stub), or direct (remote snapshot from CLI hint JSON, same shape as sync --dump-spec; sync always applies remote comments to spec then diffs; direct also appends source=waterfall-direct-out JSON after the report). Each kind has its own provider. Additional options use keys sync_story_<suffix> / sync_bug_<suffix> (e.g. sync_story_jira_site, sync_story_jira_project).",
+    },
+    {
+      keys: ["sync_story_leading", "sync_bug_leading"],
+      valueType: "enum" as const,
+      enumValues: ["waterfall", "remote"],
+      description:
+        "Authoritative side when spec and remote disagree for the same id (`waterfall` = spec tree wins, `remote` = tracker wins). Defaults: STORY → waterfall, BUG → remote.",
+    },
+  ],
+  booleanValues: ["true", "false", "1", "0", "yes", "no", "on", "off"],
+  keyMatching:
+    "Known keys are matched case-insensitively with - and _ normalized to _ for comparison.",
+  environmentPassthrough: {
+    rule: "Any KEY that looks like UPPER_SNAKE (^[A-Z][A-Z0-9_]*$) and is not consumed as a known key is stored and merged into process.env for agent subprocesses only where env is unset.",
+    examples: [
+      "ANTHROPIC_API_KEY",
+      "OPENAI_API_KEY",
+      "CURSOR_API_KEY",
+      "OLLAMA_HOST",
+    ],
+  },
+} as const;
+
+export const DOT_WATERFALL_TEMPLATE = `# Waterfall CLI user configuration
+# Path: ~/.waterfall (also supported: .waterfall in the current working directory)
+# If both exist, the file in the working directory wins for each setting.
+# Precedence: flags > environment variables > ./.waterfall > this file > built-in defaults
+#
+# Lines starting with # are comments. Use KEY=value (no spaces around =).
+
+# --- Agent backend (cline-ollama | cursor | claude-code) ---
+# backend=cline-ollama
+
+# --- waterfall-spec checkout (optional; overrides walk-up / waterfall.json) ---
+# spec_root=/absolute/path/to/waterfall-spec
+
+# --- CLI tracing: silent | normal | verbose (see also WATERFALL_LOG_LEVEL, --log-level, --quiet) ---
+# level=normal
+
+# --- Prompt steps: dry-run only vs run real agent CLIs ---
+# dry_run=true
+# execute_agent=false
+
+# When execute_agent=true, backends run (cline -y, agent|cursor -p --force, claude -p).
+# execute_agent=true
+# dry_run=false
+
+# --- Workflow prompt in agent message: embed (full .md inlined, default) | reference (paths only) ---
+# prompt_delivery=embed
+# Overridden per run by: --prompt-delivery embed|reference
+
+# --- export pdf: use system pandoc + PDF engine instead of bundled wasm + headless Chrome ---
+# use_native_pandoc=false
+
+# --- sync stories|bugs ↔ issue tracker (separate STORY vs BUG; all keys live in this file) ---
+# sync_story_provider=jira
+# sync_story_provider=direct   # remote side from CLI hint: waterfall sync stories @remote.json (JSON = --dump-spec shape)
+# sync_story_leading=waterfall
+# sync_story_jira_site=https://your.atlassian.net
+# sync_story_jira_project=BOOK
+# sync_bug_provider=jira
+# sync_bug_leading=remote
+# sync_bug_jira_site=https://your.atlassian.net
+# sync_bug_jira_project=BOOK
+# (Auth: e.g. JIRA_API_TOKEN + JIRA_USER_EMAIL as UPPER_SNAKE above for agent passthrough; wire in provider when implemented.)
+
+# --- Optional: pass through to agent processes (uncomment and set as needed) ---
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+# CURSOR_API_KEY=
+# OLLAMA_HOST=http://127.0.0.1:11434
+
+# Cline: run \`cline auth\` to pick provider (Ollama, Anthropic, etc.) — see https://docs.cline.bot/cline-cli/getting-started
+# Claude Code: \`claude\` uses its own auth / API key from env
+# Cursor: \`agent\` / \`cursor\` CLI — see https://cursor.com/docs/cli/overview
+`;
+
+/**
+ * Create ~/.waterfall with commented template if missing. Returns true if created.
+ */
+export function ensureDotWaterfallFile(home?: string): boolean {
+  // Avoid creating ~/.waterfall on the developer machine during unit tests.
+  if (process.env.VITEST === "true" && home === undefined) return false;
+  const p = dotWaterfallPath(home ?? waterfallConfigHome());
+  if (fs.existsSync(p)) return false;
+  try {
+    fs.writeFileSync(p, DOT_WATERFALL_TEMPLATE, { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Merge UPPER_SNAKE keys into process.env (only if not already set).
+ */
+export function applyDotWaterfallEnvExports(exports: Record<string, string>): void {
+  for (const [k, v] of Object.entries(exports)) {
+    if (v === "" || v === undefined) continue;
+    if (process.env[k] === undefined) process.env[k] = v;
+  }
+}

package/lib/cli/config/global-cli.ts

@@ -0,0 +1,21 @@
+import type { BackendId } from "../agent/backends";
+import type { PromptDelivery } from "../agent/agent-message";
+import type { LogLevel } from "../core/cli-log";
+import type { SyncWorkItemBlock } from "./sync-work-item-config";
+
+export type GlobalCli = {
+  cwd: string;
+  specRoot?: string;
+  backend: BackendId;
+  dryRun: boolean;
+  executeAgent: boolean;
+  logLevel: LogLevel;
+  /** Inlined prompt body vs filesystem paths only (smaller argv). */
+  promptDelivery: PromptDelivery;
+  /** From `.waterfall` / `~/.waterfall` `use_native_pandoc=` — `export pdf` calls system pandoc instead of bundled wasm + puppeteer. */
+  useNativePandoc: boolean;
+  /** From `.waterfall` `sync_story_*` — `waterfall sync stories`. */
+  syncStory?: SyncWorkItemBlock;
+  /** From `.waterfall` `sync_bug_*` — `waterfall sync bugs`. */
+  syncBug?: SyncWorkItemBlock;
+};

package/lib/cli/config/sync-work-item-config.ts

@@ -0,0 +1,34 @@
+import type { WorkItemSyncKind } from "../sync/provider-types";
+
+/** Authoritative side when spec and remote disagree for the same work item id. */
+export type SyncLeadSystem = "waterfall" | "remote";
+
+export function parseSyncLead(raw: string | undefined): SyncLeadSystem | undefined {
+  const v = raw?.trim().toLowerCase();
+  if (v === "waterfall") return "waterfall";
+  if (v === "remote") return "remote";
+  return undefined;
+}
+
+/** STORY → waterfall; BUG → remote (when `leading` is omitted in `.waterfall`). */
+export function defaultSyncLeadForKind(kind: WorkItemSyncKind): SyncLeadSystem {
+  return kind === "bug" ? "remote" : "waterfall";
+}
+
+export function effectiveSyncLead(
+  block: SyncWorkItemBlock | undefined,
+  kind: WorkItemSyncKind,
+): SyncLeadSystem {
+  return block?.leading ?? defaultSyncLeadForKind(kind);
+}
+
+export type SyncWorkItemBlock = {
+  /** Which side wins on field mismatch (`waterfall` = spec tree, `remote` = tracker). */
+  leading?: SyncLeadSystem;
+  provider?: string;
+  options: Record<string, string>;
+};
+
+export function emptySyncWorkItemBlock(): SyncWorkItemBlock {
+  return { options: {} };
+}