@markbrutx/promptbook-cli 0.2.0 → 0.4.0

package/src/commands/watch.ts

@@ -0,0 +1,221 @@
+import { relative, sep } from "node:path";
+import { watch as chokidarWatch } from "chokidar";
+import type { ParsedArgs } from "../args.js";
+import { requirePromptsDir } from "../config.js";
+import { colorEnabled, type IO } from "../io.js";
+import { makeStyle, type Style } from "../style.js";
+import { type Book, loadWorkspace } from "../workspace.js";
+import { bundleOne } from "./bundle.js";
+
+/** Folders inside a book whose edits warrant a rebuild (mirrors core's loader layout). */
+const BOOK_DIRS = ["fragments", "rules", "code-prompts"];
+
+/** Single-book root files we re-bundle on touch (config edits change the assembly). */
+const BOOK_FILES = ["promptbook.json"];
+
+/** Debounce window per book: a burst of edits collapses into one rebuild. */
+const DEBOUNCE_MS = 250;
+
+interface RebuildStats {
+  bytes: number;
+  ms: number;
+}
+
+/** Local-time clock prefix (`hours:minutes:seconds`); slices off Date#toTimeString's TZ tail. */
+function clock(): string {
+  return new Date().toTimeString().slice(0, 8);
+}
+
+/** True when `event` happened inside one of the book's watched folders (or is a root file). */
+function eventInBook(book: Book, eventPath: string): boolean {
+  const rel = relative(book.dir, eventPath);
+  if (rel === "" || rel.startsWith("..")) {
+    return false;
+  }
+  const parts = rel.split(sep);
+  if (parts.length === 1) {
+    return BOOK_FILES.includes(parts[0] as string);
+  }
+  return BOOK_DIRS.includes(parts[0] as string);
+}
+
+/** Ignore artifacts, tests, fixtures, and everything VCS / dep manager touches. */
+function shouldIgnore(eventPath: string): boolean {
+  const lower = eventPath.toLowerCase();
+  if (lower.endsWith("book.generated.ts")) {
+    return true;
+  }
+  if (lower.endsWith(".test.ts") || lower.endsWith(".test.js")) {
+    return true;
+  }
+  const segments = eventPath.split(sep);
+  for (const segment of segments) {
+    if (segment === "node_modules" || segment === ".git" || segment === "fixtures") {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Wrap `io` so `bundleOne`'s `wrote <path>` chatter is dropped and the artifact size is captured. */
+function captureBytes(io: IO): { sink: IO; bytes: () => number } {
+  let bytes = 0;
+  const sink: IO = {
+    ...io,
+    stderr(text) {
+      if (text.startsWith("wrote ")) {
+        return;
+      }
+      io.stderr(text);
+    },
+    async writeFile(path, contents) {
+      bytes = contents.length;
+      await io.writeFile(path, contents);
+    },
+  };
+  return { sink, bytes: () => bytes };
+}
+
+function emitEvent(
+  io: IO,
+  args: ParsedArgs,
+  style: Style,
+  event: "started" | "bundled" | "error" | "stopped",
+  payload: Record<string, unknown> = {},
+): void {
+  if (args.json) {
+    io.stderr(`${JSON.stringify({ event, ts: clock(), ...payload })}\n`);
+    return;
+  }
+  const ts = style.dim(`[${clock()}]`);
+  if (event === "started") {
+    const books = payload.books as string[];
+    io.stderr(`${ts} watching ${books.length} book(s): ${books.join(", ")}\n`);
+    return;
+  }
+  if (event === "bundled") {
+    io.stderr(`${ts} ${payload.book} bundled (${payload.bytes} B, ${payload.ms}ms)\n`);
+    return;
+  }
+  if (event === "stopped") {
+    io.stderr("stopped\n");
+    return;
+  }
+  io.stderr(`${ts} ${payload.book} ${style.red("ERROR")}: ${payload.message}\n`);
+}
+
+async function rebuild(io: IO, args: ParsedArgs, book: Book): Promise<RebuildStats | Error> {
+  const start = Date.now();
+  const capture = captureBytes(io);
+  try {
+    const code = await bundleOne(capture.sink, args, book.dir, book.name, true);
+    if (code !== 0) {
+      return new Error(`bundle exited with code ${code}`);
+    }
+    return { bytes: capture.bytes(), ms: Date.now() - start };
+  } catch (error) {
+    return error as Error;
+  }
+}
+
+/** Run one rebuild and emit its bundled/error event. */
+async function rebuildAndReport(io: IO, args: ParsedArgs, style: Style, book: Book): Promise<void> {
+  const result = await rebuild(io, args, book);
+  if (result instanceof Error) {
+    emitEvent(io, args, style, "error", { book: book.name, message: result.message });
+  } else {
+    emitEvent(io, args, style, "bundled", { book: book.name, bytes: result.bytes, ms: result.ms });
+  }
+}
+
+/**
+ * `watch [<dir>]`: rebuild `book.generated.ts` whenever fragments, rules,
+ * compositions, code-prompts or `promptbook.json` change. Streams one short
+ * line per rebuild to stderr (`[clock] <book> bundled (<bytes> B, <ms>ms)`);
+ * stdout stays empty (the contract: stdout = payload, watch has no payload).
+ *
+ * Discovers every book under the prompts folder and rebuilds each once on
+ * startup, then debounces per-book events with a 250 ms window so a burst of
+ * edits collapses into one rebuild. SIGINT / SIGTERM closes the watcher and
+ * exits 0. Honors `--plain`, `--exclude-code-prompts`, `--json`, and the
+ * config / `--dir` resolution chain.
+ *
+ * `--out <file>` only works in a single-book workspace; the multi-book mode
+ * always writes each book's artifact next to its sources.
+ */
+export async function cmdWatch(args: ParsedArgs, io: IO): Promise<number> {
+  if (args.check) {
+    io.stderr("error: --check is not supported by watch (run `bundle --check --all` from CI)\n");
+    return 1;
+  }
+
+  const promptsDir = await requirePromptsDir(io, args.operands[0] ?? args.dir);
+  if (promptsDir === null) {
+    return 1;
+  }
+
+  const workspace = await loadWorkspace(io, promptsDir);
+  if (workspace.books.length === 0) {
+    io.stderr(`error: no books found under ${promptsDir}\n`);
+    return 1;
+  }
+  if (args.out !== undefined && workspace.books.length > 1) {
+    io.stderr("error: --out requires a single book; drop --out to write each book's book.generated.ts\n");
+    return 1;
+  }
+
+  const style = makeStyle(colorEnabled(io));
+  emitEvent(io, args, style, "started", { books: workspace.books.map((b) => b.name) });
+
+  // Initial pass runs in parallel: each book writes its own artifact, no contention.
+  await Promise.all(workspace.books.map((book) => rebuildAndReport(io, args, style, book)));
+
+  const watcher = chokidarWatch(promptsDir, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 },
+    ignored: (eventPath) => shouldIgnore(eventPath),
+  });
+
+  const timers = new Map<string, NodeJS.Timeout>();
+  const scheduleRebuild = (book: Book): void => {
+    const existing = timers.get(book.name);
+    if (existing !== undefined) {
+      clearTimeout(existing);
+    }
+    const timer = setTimeout(() => {
+      timers.delete(book.name);
+      void rebuildAndReport(io, args, style, book);
+    }, DEBOUNCE_MS);
+    timers.set(book.name, timer);
+  };
+
+  watcher.on("all", (_event, eventPath) => {
+    const book = workspace.books.find((b) => eventInBook(b, eventPath));
+    if (book === undefined) {
+      return;
+    }
+    scheduleRebuild(book);
+  });
+
+  // Hold the promise open until SIGINT / SIGTERM closes the watcher.
+  return new Promise<number>((resolveDone) => {
+    let stopped = false;
+    const stop = async (): Promise<void> => {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      for (const timer of timers.values()) {
+        clearTimeout(timer);
+      }
+      timers.clear();
+      await watcher.close();
+      emitEvent(io, args, style, "stopped");
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      resolveDone(0);
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}

package/src/config.ts

@@ -1,4 +1,4 @@
-import { resolve as resolvePath } from "node:path";
+import { dirname, resolve as resolvePath } from "node:path";
 import type { Context, ContextValue } from "@markbrutx/promptbook-core";
 import type { IO } from "./io.js";
 
@@ -90,6 +90,14 @@ interface PromptbookConfig {
   eval?: unknown;
 }
 
+/** A loaded `promptbook.json`: parsed data plus the directory that held it. */
+export interface LoadedConfig {
+  /** Parsed JSON object (or `{}` when no file was found or parsing failed). */
+  data: PromptbookConfig;
+  /** Absolute directory where the config was found; `undefined` if nothing matched up the tree. */
+  dir?: string;
+}
+
 /** lint options sourced from the `lint` section of `promptbook.json`. */
 export interface LintConfig {
   maxTokens?: number;
@@ -97,30 +105,45 @@ export interface LintConfig {
 }
 
 /**
- * Read and parse `promptbook.json` from cwd once. Missing, unreadable or
- * malformed config yields an empty object, so callers treat it as best-effort
- * and layer flags on top. Pass the result to {@link resolvePromptsDir} and
- * {@link lintConfigFrom} to avoid re-reading the file per command.
+ * Walk up from `io.cwd()` to find the first `promptbook.json`, parse it, and
+ * return its data + the directory it lived in. Walking up (rather than only
+ * checking cwd) is what makes `promptbook` work like `git`/`biome`/`eslint`:
+ * one config at the repo root reaches every subfolder. Path-valued keys
+ * (currently just `promptsDir`) are resolved relative to {@link LoadedConfig.dir}
+ * by {@link resolvePromptsDir}, not relative to wherever the shell happens to
+ * be — so `pnpm exec` snapping cwd to a workspace package cannot break the
+ * lookup. Missing, unreadable or malformed files yield an empty config
+ * (best-effort), so callers can layer flags on top.
  */
-export async function loadConfig(io: IO): Promise<PromptbookConfig> {
-  const configPath = resolvePath(io.cwd(), "promptbook.json");
-  let raw: string;
-  try {
-    raw = await io.fs.readFile(configPath);
-  } catch {
-    return {};
-  }
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    return isJsonObject(parsed) ? parsed : {};
-  } catch {
-    return {};
+export async function loadConfig(io: IO): Promise<LoadedConfig> {
+  let dir = resolvePath(io.cwd());
+  for (;;) {
+    const configPath = resolvePath(dir, "promptbook.json");
+    let raw: string | undefined;
+    try {
+      raw = await io.fs.readFile(configPath);
+    } catch {
+      // not found at this level; try the parent
+    }
+    if (raw !== undefined) {
+      try {
+        const parsed = JSON.parse(raw) as unknown;
+        return { data: isJsonObject(parsed) ? parsed : {}, dir };
+      } catch {
+        return { data: {}, dir };
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return { data: {} };
+    }
+    dir = parent;
   }
 }
 
 /** Extract the `lint` section from an already-loaded config. */
-export function lintConfigFrom(config: PromptbookConfig): LintConfig {
-  const section = config.lint;
+export function lintConfigFrom(loaded: LoadedConfig): LintConfig {
+  const section = loaded.data.lint;
   if (!isJsonObject(section)) {
     return {};
   }
@@ -146,8 +169,8 @@ export interface EvalConfig {
 }
 
 /** Extract the `eval` section from an already-loaded config. */
-export function evalConfigFrom(config: PromptbookConfig): EvalConfig {
-  const section = config.eval;
+export function evalConfigFrom(loaded: LoadedConfig): EvalConfig {
+  const section = loaded.data.eval;
   if (!isJsonObject(section)) {
     return {};
   }
@@ -162,21 +185,22 @@ export function evalConfigFrom(config: PromptbookConfig): EvalConfig {
 }
 
 /**
- * Resolve the prompts folder by priority: `--dir` flag > `promptbook.json`
- * (`promptsDir` key) in cwd > `./prompts`. All results are absolute. Pass a
- * preloaded `config` to reuse a single read; otherwise it is loaded here.
+ * Resolve the prompts folder by priority:
+ *   1. `--dir <path>` — relative to **cwd** (explicit per-invocation override).
+ *   2. `promptbook.json` `promptsDir` — relative to **the config file's directory**
+ *      (so the value can stay stable while the user shells around in subfolders).
+ *   3. `./prompts` — relative to cwd (back-compat default when no config exists).
+ *
+ * All results are absolute. Pass a preloaded {@link LoadedConfig} to reuse a
+ * single read; otherwise it is loaded here.
  */
-export async function resolvePromptsDir(
-  io: IO,
-  dirFlag?: string,
-  config?: PromptbookConfig,
-): Promise<string> {
+export async function resolvePromptsDir(io: IO, dirFlag?: string, loaded?: LoadedConfig): Promise<string> {
   if (dirFlag !== undefined) {
     return resolvePath(io.cwd(), dirFlag);
   }
-  const resolved = config ?? (await loadConfig(io));
-  if (typeof resolved.promptsDir === "string") {
-    return resolvePath(io.cwd(), resolved.promptsDir);
+  const resolved = loaded ?? (await loadConfig(io));
+  if (typeof resolved.data.promptsDir === "string" && resolved.dir !== undefined) {
+    return resolvePath(resolved.dir, resolved.data.promptsDir);
   }
   return resolvePath(io.cwd(), "prompts");
 }
@@ -198,9 +222,9 @@ async function dirExists(io: IO, dir: string): Promise<boolean> {
 export async function requirePromptsDir(
   io: IO,
   dirFlag?: string,
-  config?: PromptbookConfig,
+  loaded?: LoadedConfig,
 ): Promise<string | null> {
-  const promptsDir = await resolvePromptsDir(io, dirFlag, config);
+  const promptsDir = await resolvePromptsDir(io, dirFlag, loaded);
   if (!(await dirExists(io, promptsDir))) {
     io.stderr(`error: prompts folder not found: ${promptsDir}\n`);
     return null;

package/src/run.ts

@@ -8,6 +8,7 @@ import { cmdLint } from "./commands/lint.js";
 import { cmdLs } from "./commands/ls.js";
 import { cmdResolve } from "./commands/resolve.js";
 import { cmdView } from "./commands/view.js";
+import { cmdWatch } from "./commands/watch.js";
 import { defaultIO, type IO } from "./io.js";
 
 const HELP = `promptbook — compose prompts from reusable fragments
@@ -19,7 +20,8 @@ Commands:
   resolve [<book>/]<prompt>  Assemble a prompt and print it to stdout (--all: every book)
   lint [<prompt>]         Run static checks; with no prompt, book rules only
   eval [<name|glob>]      Run fixtures through a model adapter, report pass-rate
-  bundle [<dir>]          Compile a prompts folder into an importable book module
+  bundle [<dir>]          Compile a prompts folder into an importable book module (--all/--check)
+  watch [<dir>]           Rebuild book.generated.ts as fragments/rules/compositions change
   view                    Start the local web viewer over the workspace (book switcher)
   annotations <action>    Drain the viewer's feedback queue: list | resolve <id> | clear
   ls                      List compositions and fragments (--all: cross-book inventory)
@@ -39,13 +41,15 @@ Options:
   --samples N             eval: default samples per fixture (default 1; a fixture's own samples wins)
   --threshold R           eval: a fixture passes when passRate >= R (default 1)
   --lint                  eval: run a static lint gate over every variant first
-  -o, --out <file>        bundle: write the generated module to a file (default: stdout)
-  --plain                 bundle: emit a plain module (no type-only import; e.g. for Deno)
+  -o, --out <file>        bundle/watch: write to a file (default: stdout for bundle, <bookDir>/book.generated.ts for watch/--all)
+  --plain                 bundle/watch: emit a plain module (no type-only import; e.g. for Deno)
+  --check                 bundle: compare with the existing output; exit 1 on drift or missing artifact
+  --exclude-code-prompts  bundle/watch: serialize code-prompts as an empty map (runtime-lean bundle)
   --port N                view: port for the viewer server (default: a free port)
   --no-open               view: do not open the browser after starting
   --fragments             ls: list fragments only
   --compositions          ls: list compositions only
-  --all                   ls/resolve: span every book in the workspace
+  --all                   ls/resolve/bundle: span every book in the workspace
   -h, --help              Show this help
   -v, --version           Show the version
 
@@ -98,6 +102,8 @@ export async function run(argv: string[], io: IO = defaultIO()): Promise<number>
       return cmdEval(args, io);
     case "bundle":
       return cmdBundle(args, io);
+    case "watch":
+      return cmdWatch(args, io);
     case "view":
       return cmdView(args, io);
     case "annotations":