@pknx/waterfall-cli 0.1.0

package/lib/cli/commands/sync-work-items.ts

@@ -0,0 +1,59 @@
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { runSyncWorkItems } from "../sync/run-sync-work-items";
+import type { WaterfallCommand } from "./types";
+import type { WorkItemSyncKind } from "../sync/provider-types";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+
+function parseSyncArgv(
+  rest: string[],
+  cwd: string,
+): { dumpSpec: boolean; hint?: string } {
+  const dumpSpec = rest.includes("--dump-spec");
+  if (dumpSpec) {
+    return { dumpSpec: true };
+  }
+  const parts = rest.slice(2).filter((t) => t !== "--dump-spec");
+  const { text } = resolveOperatorHint(parts, { cwd });
+  return { dumpSpec: false, hint: text || undefined };
+}
+
+function makeSyncCommand(kind: WorkItemSyncKind): WaterfallCommand {
+  const label = kind === "story" ? "stories" : "bugs";
+  return {
+    matches: (r) => r[0] === "sync" && r[1] === label,
+    run(ctx, rest) {
+      try {
+        const block = kind === "story" ? ctx.g.syncStory : ctx.g.syncBug;
+        runSyncWorkItems(
+          ctx.specRoot,
+          ctx.g.cwd,
+          kind,
+          block,
+          ctx.g.logLevel,
+          parseSyncArgv(rest, ctx.g.cwd),
+          kind === "bug"
+            ? {
+                afterBugsMaterialized: ({ mdRels }) => {
+                  if (mdRels.length === 0) return;
+                  const list = mdRels.map((r) => `- ${r}`).join("\n");
+                  ctx.runAgentPrompt(
+                    "prompts/commands/sync-bugs-refine-imports.md",
+                    `BUG markdown was just imported from remote sync (this run). Refine each file below per the prompt (Summary + remove Draft steering). Comments were written to matching *.comments.json already.\n\n${list}\n`,
+                    AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+                    `waterfall sync bugs — refine ${mdRels.length} imported BUG(s)`,
+                  );
+                },
+              }
+            : undefined,
+        );
+        return 0;
+      } catch (e) {
+        process.stderr.write(`${(e as Error).message}\n`);
+        return 1;
+      }
+    },
+  };
+}
+
+export const syncStoriesCommand = makeSyncCommand("story");
+export const syncBugsCommand = makeSyncCommand("bug");

package/lib/cli/commands/sys-start.ts

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { gitExecSync } from "../git/git-cli";
+import { assertSpecRoot } from "../spec/spec-root";
+import { scaffoldHeadingFromDescription, slugifyDescription } from "../core/slug";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+type NumberJson = { next: { SYS: number } };
+
+function git(specRoot: string, args: string[]): void {
+  gitExecSync(specRoot, args, { stdio: "inherit" });
+}
+
+function formatSysId(n: number): string {
+  return String(n).padStart(3, "0");
+}
+
+/**
+ * Creates a new SYS folder and scaffold document.
+ * Mutates spec repo: new technical/SYS-* folder, number.json bump, commit.
+ */
+export function runSysStart(specRoot: string, description: string): void {
+  assertSpecRoot(specRoot);
+  const slug = slugifyDescription(description);
+  const numPath = path.join(specRoot, "number.json");
+  const raw = JSON.parse(fs.readFileSync(numPath, "utf8")) as NumberJson;
+  const n = raw.next.SYS;
+  const id = formatSysId(n);
+  const base = `SYS-${id}-${slug}`;
+
+  const sysDir = path.join(specRoot, "technical", base);
+  if (fs.existsSync(sysDir)) {
+    throw new Error(`SYS folder already exists: technical/${base}`);
+  }
+  fs.mkdirSync(sysDir, { recursive: true });
+
+  const mdPath = path.join(sysDir, `SYS-${id}.md`);
+  const headingTitle = scaffoldHeadingFromDescription(description, slug);
+  const steeringLines = description
+    .trim()
+    .split(/\r?\n/)
+    .map((line) => (line.length > 0 ? `> ${line}` : ">"));
+  const steeringBlock =
+    steeringLines.length > 0 ? steeringLines.join("\n") : "> _(empty)_";
+
+  const md = `# SYS-${id} — ${headingTitle}
+
+**Id:** SYS-${id}  
+**Status:** draft
+
+## Links and dependencies
+
+### Downstream references
+
+- (none)
+
+## Purpose
+
+*(Replace with subsystem purpose and boundaries per \`prompts/items/sys-document-structure.md\`. **Synthesize** from **Draft steering (CLI)** below — do not paste that block verbatim as the only Purpose text. Remove **Draft steering** when done.)*
+
+## Draft steering (CLI)
+
+The operator supplied this when running \`waterfall sys start\`. **Scratch input only**:
+
+${steeringBlock}
+`;
+  fs.writeFileSync(mdPath, md, "utf8");
+
+  raw.next.SYS = n + 1;
+  fs.writeFileSync(numPath, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+
+  git(specRoot, ["add", `technical/${base}/SYS-${id}.md`, "number.json"]);
+  git(specRoot, ["commit", "-m", `feat(SYS-${id}): scaffold subsystem`]);
+}
+
+export const sysStartCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "sys" && r[1] === "start",
+  run(ctx, rest) {
+    const [, , a2, ...tail] = rest;
+    const { text } = resolveOperatorHint([a2, ...tail].filter(Boolean), {
+      required: true,
+    });
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall sys start");
+    runSysStart(ctx.specRoot, text);
+    ctx.runAgentPrompt(
+      "prompts/commands/sys-start.md",
+      text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+      "waterfall sys start — refine SYS prose",
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/test-all.ts

@@ -0,0 +1,18 @@
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { ORCHESTRATE_TEST_ALL_ORDER } from "../core/prompt-map";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const testAllCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "test" && r[1] === "all",
+  run(ctx, rest) {
+    const tail = rest.slice(2);
+    ctx.runOrchestrate(
+      ORCHESTRATE_TEST_ALL_ORDER,
+      "waterfall test all",
+      resolveOperatorHint(tail, { required: false }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/test-to-story.ts

@@ -0,0 +1,18 @@
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const testToStoryCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "test" && r[1] === "to" && r[2] === "story",
+  run(ctx, rest) {
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall test to story");
+    const tail = rest.slice(3);
+    ctx.runAgentPrompt(
+      "prompts/commands/test-to-story.md",
+      resolveOperatorHint(tail, { required: true }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/types.ts

@@ -0,0 +1,33 @@
+import type { GlobalCli } from "../config/global-cli";
+import type { WaterfallGlobalPrompt } from "../agent/global-prompts";
+import type { LifecycleStep } from "../core/prompt-map";
+
+/** Optional flags for `runAgentPrompt` (4th/5th parameters). */
+export type RunAgentPromptOptions = {
+  /** @default true — set false when the hint already includes develop...HEAD path scope. */
+  attachCrBranchPaths?: boolean;
+};
+
+/** Per-command execution: branch guards, git, filesystem, or agent prompt. */
+export type CommandRunContext = {
+  g: GlobalCli;
+  specRoot: string;
+  runAgentPrompt: (
+    relPrompt: string,
+    hint: string,
+    globalPrompts: WaterfallGlobalPrompt[],
+    orchestrationContext?: string,
+    runOpts?: RunAgentPromptOptions,
+  ) => void;
+  runOrchestrate: (
+    order: LifecycleStep[],
+    batchLabel: string,
+    hint: string,
+    globalPrompts: WaterfallGlobalPrompt[],
+  ) => void;
+};
+
+export type WaterfallCommand = {
+  matches(rest: string[]): boolean;
+  run(ctx: CommandRunContext, rest: string[]): number;
+};

package/lib/cli/commands/uc-all.ts

@@ -0,0 +1,18 @@
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { ORCHESTRATE_UC_ALL_ORDER } from "../core/prompt-map";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const ucAllCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "uc" && r[1] === "all",
+  run(ctx, rest) {
+    const tail = rest.slice(2);
+    ctx.runOrchestrate(
+      ORCHESTRATE_UC_ALL_ORDER,
+      "waterfall uc all",
+      resolveOperatorHint(tail, { required: false }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/uc-to-story.ts

@@ -0,0 +1,18 @@
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const ucToStoryCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "uc" && r[1] === "to" && r[2] === "story",
+  run(ctx, rest) {
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall uc to story");
+    const tail = rest.slice(3);
+    ctx.runAgentPrompt(
+      "prompts/commands/uc-to-story.md",
+      resolveOperatorHint(tail, { required: true }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/commands/uc-to-test.ts

@@ -0,0 +1,18 @@
+import { assertBranchForCrScopedCommand } from "../git/git-branch-guards";
+import { AGENT_GLOBAL_PROMPTS_LIFECYCLE } from "../agent/global-prompts";
+import { resolveOperatorHint } from "./resolve-operator-hint";
+import type { WaterfallCommand } from "./types";
+
+export const ucToTestCommand: WaterfallCommand = {
+  matches: (r) => r[0] === "uc" && r[1] === "to" && r[2] === "test",
+  run(ctx, rest) {
+    assertBranchForCrScopedCommand(ctx.specRoot, "waterfall uc to test");
+    const tail = rest.slice(3);
+    ctx.runAgentPrompt(
+      "prompts/commands/uc-to-test.md",
+      resolveOperatorHint(tail, { required: true }).text,
+      AGENT_GLOBAL_PROMPTS_LIFECYCLE,
+    );
+    return 0;
+  },
+};

package/lib/cli/comments/item-comments.ts

@@ -0,0 +1,285 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** Spec item families that have a canonical `{PREFIX}-{NNN}.md` (same set as export pdf codes, minus CURSOR). */
+export const ITEM_COMMENT_PREFIXES = [
+  "CR",
+  "RQ",
+  "UC",
+  "SYS",
+  "STORY",
+  "BUG",
+  "HOR",
+  "TST",
+] as const;
+
+export type ItemCommentPrefix = (typeof ITEM_COMMENT_PREFIXES)[number];
+
+const PREFIX_PARSE_RE = new RegExp(
+  `^(${ITEM_COMMENT_PREFIXES.join("|")})-(\\d+)$`,
+  "i",
+);
+
+const SKIP_WALK_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+]);
+
+export type ItemCommentState = "OPEN" | "RESOLVED" | "REJECTED";
+
+export type ItemCommentEntry = {
+  id: string;
+  /** Display name. */
+  from: string;
+  /** Author identity (sync key; matches WorkItemComment.email). */
+  email: string;
+  /** Free-form remark; can later be incorporated into the spec markdown. */
+  hint: string;
+  state: ItemCommentState;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type ItemCommentsFile = {
+  itemId: string;
+  comments: ItemCommentEntry[];
+};
+
+const VALID_STATES = new Set<ItemCommentState>(["OPEN", "RESOLVED", "REJECTED"]);
+
+export function parseWorkItemCanonicalId(raw: string): {
+  prefix: ItemCommentPrefix;
+  canonicalId: string;
+} {
+  const t = raw.trim();
+  const m = t.match(PREFIX_PARSE_RE);
+  if (!m) {
+    throw new Error(
+      `Invalid item id "${raw}". Use ${ITEM_COMMENT_PREFIXES.join(", ")}-NNN (e.g. STORY-001, CR-002, HOR-003).`,
+    );
+  }
+  const prefix = m[1]!.toUpperCase() as ItemCommentPrefix;
+  const padded = String(parseInt(m[2]!, 10)).padStart(3, "0");
+  const canonicalId = `${prefix}-${padded}`;
+  return { prefix, canonicalId };
+}
+
+function mdStemMatchesCanonical(stem: string, canonicalId: string): boolean {
+  const s = stem.toLowerCase();
+  const id = canonicalId.toLowerCase();
+  return s === id || s.startsWith(`${id}-`);
+}
+
+/**
+ * Find the markdown file for an item under the spec tree: exact `{id}.md` or `{id}-*.md`
+ * (e.g. `CR-001.md`, `HOR-001-scope.md`). If several candidates exist, prefers exact `{id}.md`.
+ */
+export function findCanonicalItemMarkdown(
+  specRoot: string,
+  canonicalId: string,
+): string {
+  const { canonicalId: id } = parseWorkItemCanonicalId(canonicalId);
+  const root = path.resolve(specRoot);
+  const matches: string[] = [];
+  const stack = [root];
+  while (stack.length) {
+    const d = stack.pop()!;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (e.name.startsWith(".")) continue;
+        if (SKIP_WALK_DIRS.has(e.name)) continue;
+        stack.push(p);
+      } else if (e.isFile() && /\.md$/i.test(e.name)) {
+        const stem = e.name.replace(/\.md$/i, "");
+        if (mdStemMatchesCanonical(stem, id)) {
+          matches.push(p);
+        }
+      }
+    }
+  }
+  matches.sort();
+  if (matches.length === 0) {
+    throw new Error(
+      `No markdown for ${id} under ${specRoot} (expected ${id}.md or ${id}-*.md).`,
+    );
+  }
+  if (matches.length === 1) {
+    return matches[0]!;
+  }
+  const exactName = `${id}.md`.toLowerCase();
+  const exactHits = matches.filter(
+    (p) => path.basename(p).toLowerCase() === exactName,
+  );
+  if (exactHits.length === 1) {
+    return exactHits[0]!;
+  }
+  throw new Error(
+    `Multiple markdown files for ${id}: ${matches.map((x) => path.relative(root, x)).join(", ")}.`,
+  );
+}
+
+/** Directory containing the canonical `{id}.md`. */
+export function findWorkItemDir(specRoot: string, canonicalId: string): string {
+  return path.dirname(findCanonicalItemMarkdown(specRoot, canonicalId));
+}
+
+/** `{ITEM-ID}.comments.json` next to the item markdown (same directory as `{ITEM}.md`). */
+export function itemCommentsJsonPath(
+  itemDir: string,
+  canonicalId: string,
+): string {
+  const { canonicalId: id } = parseWorkItemCanonicalId(canonicalId);
+  return path.join(itemDir, `${id}.comments.json`);
+}
+
+export function resolveItemCommentStorage(
+  specRoot: string,
+  canonicalId: string,
+): { itemDir: string; mdPath: string; commentsPath: string } {
+  const mdPath = findCanonicalItemMarkdown(specRoot, canonicalId);
+  const itemDir = path.dirname(mdPath);
+  const commentsPath = itemCommentsJsonPath(itemDir, canonicalId);
+  return { itemDir, mdPath, commentsPath };
+}
+
+function parseCommentEntry(
+  x: unknown,
+  index: number,
+  filePath: string,
+): ItemCommentEntry {
+  if (!x || typeof x !== "object") {
+    throw new Error(`${filePath}: comments[${index}] must be an object`);
+  }
+  const o = x as Record<string, unknown>;
+  const id = o.id;
+  const from = o.from;
+  const emailRaw = o.email;
+  const hint = o.hint;
+  const state = o.state;
+  const createdAt = o.createdAt;
+  const updatedAt = o.updatedAt;
+  if (typeof id !== "string" || !id.trim()) {
+    throw new Error(`${filePath}: comments[${index}].id must be a non-empty string`);
+  }
+  if (typeof from !== "string") {
+    throw new Error(`${filePath}: comments[${index}].from must be a string`);
+  }
+  let email = "";
+  if (emailRaw !== undefined) {
+    if (typeof emailRaw !== "string") {
+      throw new Error(`${filePath}: comments[${index}].email must be a string`);
+    }
+    email = emailRaw.trim();
+  }
+  if (typeof hint !== "string") {
+    throw new Error(`${filePath}: comments[${index}].hint must be a string`);
+  }
+  if (typeof state !== "string" || !VALID_STATES.has(state as ItemCommentState)) {
+    throw new Error(
+      `${filePath}: comments[${index}].state must be OPEN | RESOLVED | REJECTED`,
+    );
+  }
+  if (typeof createdAt !== "string" || typeof updatedAt !== "string") {
+    throw new Error(
+      `${filePath}: comments[${index}].createdAt and updatedAt must be strings`,
+    );
+  }
+  return {
+    id,
+    from,
+    email,
+    hint,
+    state: state as ItemCommentState,
+    createdAt,
+    updatedAt,
+  };
+}
+
+/** Read and validate a comments file; returns `null` if the file is missing. */
+export function readItemCommentsFile(filePath: string): ItemCommentsFile | null {
+  if (!fs.existsSync(filePath)) return null;
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch {
+    throw new Error(`Cannot read ${filePath}`);
+  }
+  let j: unknown;
+  try {
+    j = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Invalid JSON in ${filePath}: ${(e as Error).message}`);
+  }
+  if (!j || typeof j !== "object") {
+    throw new Error(`${filePath}: root must be an object`);
+  }
+  const o = j as Record<string, unknown>;
+  if (typeof o.itemId !== "string") {
+    throw new Error(`${filePath}: missing string itemId`);
+  }
+  if (!Array.isArray(o.comments)) {
+    throw new Error(`${filePath}: comments must be an array`);
+  }
+  const comments = o.comments.map((c, i) => parseCommentEntry(c, i, filePath));
+  comments.sort((a, b) =>
+    `${a.email}\t${a.createdAt}\t${a.from}`.localeCompare(
+      `${b.email}\t${b.createdAt}\t${b.from}`,
+      "en",
+    ),
+  );
+  return {
+    itemId: o.itemId,
+    comments,
+  };
+}
+
+export function addItemComment(args: {
+  itemId: string;
+  email: string;
+  from: string;
+  hint: string;
+  commentsPath: string;
+}): ItemCommentsFile {
+  const p = args.commentsPath;
+  const now = new Date().toISOString();
+  const existing = readItemCommentsFile(p);
+  const entry: ItemCommentEntry = {
+    id: randomUUID(),
+    from: args.from.trim(),
+    email: args.email.trim(),
+    hint: args.hint.trim(),
+    state: "OPEN",
+    createdAt: now,
+    updatedAt: now,
+  };
+  let next: ItemCommentsFile;
+  if (!existing) {
+    next = {
+      itemId: args.itemId,
+      comments: [entry],
+    };
+  } else {
+    if (existing.itemId !== args.itemId) {
+      throw new Error(
+        `${p}: file itemId "${existing.itemId}" does not match ${args.itemId}`,
+      );
+    }
+    next = {
+      ...existing,
+      comments: [...existing.comments, entry],
+    };
+  }
+  fs.writeFileSync(p, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  return next;
+}