@markbrutx/promptbook-cli 0.1.0 → 0.3.0

package/src/commands/resolve.ts

@@ -1,31 +1,123 @@
-import type { ResolveResult } from "@markbrutx/promptbook-core";
-import { resolve } from "@markbrutx/promptbook-core";
+import type { Context, ResolveResult } from "@markbrutx/promptbook-core";
+import { loadPrompts, resolve, resolveBook } from "@markbrutx/promptbook-core";
 import type { ParsedArgs } from "../args.js";
 import { buildContext, requirePromptsDir } from "../config.js";
 import { colorEnabled, emitWarnings, type IO } from "../io.js";
 import { renderExplain } from "../render-explain.js";
+import { loadWorkspace, resolveAddress } from "../workspace.js";
+
+/** One node of a book's menu in deterministic (name) order, typed by kind. */
+interface BookNode {
+  name: string;
+  kind: "composition" | "code-prompt";
+}
 
 /**
- * `resolve <prompt>`: assemble the prompt and print its text to stdout. With
- * `--json`, print `{ text, trace }` instead; with `--explain`, additionally
- * print the trace to stderr. Warnings always go to stderr so nothing is lost.
+ * `resolve --all`: assemble every composition of every book in the workspace.
+ * Missing variables become stderr warnings, never throws, so the run always
+ * completes. `--json` emits a `{ "book/comp": value }` map (compositions carry
+ * `text`+`trace`; code-prompts ride along as inventory `{kind, samples}` so
+ * builders are not silently dropped); plain prints each composition under a
+ * `=== book/comp ===` header and notes the skipped code-prompts. Order is by
+ * book then by node name.
  */
-export async function cmdResolve(args: ParsedArgs, io: IO): Promise<number> {
-  const prompt = args.operands[0];
-  if (prompt === undefined) {
-    io.stderr('error: resolve requires a <prompt> name. Run "promptbook --help".\n');
-    return 1;
+async function cmdResolveAll(io: IO, root: string, context: Context, json: boolean): Promise<number> {
+  const workspace = await loadWorkspace(io, root);
+  const blocks: string[] = [];
+  const skipped: string[] = [];
+  const map: Record<string, unknown> = {};
+
+  // Load every book up front (concurrently); iterate the sorted result for
+  // deterministic output, matching `ls --all`.
+  const loadedBooks = await Promise.all(
+    workspace.books.map(async (book) => ({ book, loaded: await loadPrompts(book.dir, io.fs) })),
+  );
+
+  for (const { book, loaded } of loadedBooks) {
+    emitWarnings(
+      io,
+      loaded.warnings.map((w) => `${book.name}: ${w}`),
+    );
+    const nodes: BookNode[] = [
+      ...[...loaded.compositions.keys()].map((name): BookNode => ({ name, kind: "composition" })),
+      ...[...loaded.codePrompts.keys()].map((name): BookNode => ({ name, kind: "code-prompt" })),
+    ].sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const node of nodes) {
+      const key = `${book.name}/${node.name}`;
+      if (node.kind === "code-prompt") {
+        const codePrompt = loaded.codePrompts.get(node.name);
+        skipped.push(key);
+        if (json) {
+          map[key] = { kind: "code-prompt", samples: codePrompt?.samples ?? [] };
+        }
+        continue;
+      }
+      const { text, trace } = resolveBook(loaded, node.name, context);
+      emitWarnings(
+        io,
+        trace.warnings.map((w) => `${key}: ${w}`),
+      );
+      if (json) {
+        map[key] = { kind: "composition", text, trace };
+      } else {
+        blocks.push(`=== ${key} ===\n${text}`);
+      }
+    }
   }
 
+  if (json) {
+    io.stdout(`${JSON.stringify(map, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout(`${blocks.join("\n\n")}\n`);
+  if (skipped.length > 0) {
+    io.stderr(`note: skipped ${skipped.length} code-prompt(s) (not resolvable): ${skipped.join(", ")}\n`);
+  }
+  return 0;
+}
+
+/**
+ * `resolve [<book>/]<prompt>`: assemble the prompt and print its text to stdout.
+ * A `<book>/` prefix addresses a specific book; a bare name resolves by
+ * uniqueness across the workspace (and works as before in a single-book root).
+ * `--json` prints `{ text, trace }`; `--explain` adds the trace to stderr;
+ * `--all` assembles every composition of every book. Warnings always go to
+ * stderr so nothing is lost.
+ */
+export async function cmdResolve(args: ParsedArgs, io: IO): Promise<number> {
   const promptsDir = await requirePromptsDir(io, args.dir);
   if (promptsDir === null) {
     return 1;
   }
 
+  let context: Context;
+  try {
+    context = await buildContext(io, args.ctx, args.contextFile);
+  } catch (error) {
+    io.stderr(`error: ${(error as Error).message}\n`);
+    return 1;
+  }
+
+  if (args.all) {
+    return cmdResolveAll(io, promptsDir, context, args.json);
+  }
+
+  const operand = args.operands[0];
+  if (operand === undefined) {
+    io.stderr('error: resolve requires a <prompt> name (or --all). Run "promptbook --help".\n');
+    return 1;
+  }
+
   let result: ResolveResult;
   try {
-    const context = await buildContext(io, args.ctx, args.contextFile);
-    result = await resolve({ promptsDir, prompt, context, fs: io.fs });
+    const workspace = await loadWorkspace(io, promptsDir);
+    const { book, comp, loaded } = await resolveAddress(io, workspace, operand);
+    // Bare-name resolution already loaded the matched book — reuse it; otherwise load now.
+    result =
+      loaded !== undefined
+        ? resolveBook(loaded, comp, context)
+        : await resolve({ promptsDir: book.dir, prompt: comp, context, fs: io.fs });
   } catch (error) {
     io.stderr(`error: ${(error as Error).message}\n`);
     return 1;

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

@@ -16,13 +16,16 @@ Usage:
   promptbook <command> [options]
 
 Commands:
-  resolve <prompt>        Assemble a prompt and print it to stdout
+  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
-  view                    Start the local web viewer over the prompts folder
+  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
+  ls                      List compositions and fragments (--all: cross-book inventory)
+
+A <book>/<comp> operand addresses one book in a multi-book workspace; a bare
+name resolves by uniqueness. With a single-book --dir, names work unqualified.
 
 Options:
   --dir <path>            Prompts folder (default: promptbook.json promptsDir, else ./prompts)
@@ -42,6 +45,7 @@ Options:
   --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
   -h, --help              Show this help
   -v, --version           Show the version
 

package/src/workspace.ts

@@ -0,0 +1,144 @@
+import { basename, join, relative } from "node:path";
+import type { PromptBook } from "@markbrutx/promptbook-core";
+import { loadPrompts } from "@markbrutx/promptbook-core";
+import type { IO } from "./io.js";
+
+/** A discovered prompts book: its folder name and absolute directory. */
+export interface Book {
+  name: string;
+  dir: string;
+}
+
+/** A workspace root and the books found directly under it (sorted by name). */
+export interface Workspace {
+  root: string;
+  books: Book[];
+}
+
+/** A `<book>/<comp>` operand split into its parts (`book` absent for bare names). */
+export interface Address {
+  book?: string;
+  comp: string;
+}
+
+/** A bare/qualified operand resolved to a concrete book + composition name. */
+export interface ResolvedAddress {
+  book: Book;
+  comp: string;
+  /** The matched book, already loaded during bare-name resolution (reuse to skip a reload). */
+  loaded?: PromptBook;
+}
+
+/** Folder names that are book internals or noise, never workspace sub-books. */
+const NON_BOOK_DIRS = new Set(["node_modules", "fragments", "rules", "code-prompts"]);
+
+/** Markers that make a folder a loadable book (a config or a loadable form). */
+const BOOK_MARKERS = ["promptbook.json", "rules", "code-prompts"];
+
+/** True when `dir` looks like a prompts book (has a config or a loadable form). */
+export async function isBook(io: IO, dir: string): Promise<boolean> {
+  let entries: string[];
+  try {
+    entries = await io.fs.readDir(dir);
+  } catch {
+    return false;
+  }
+  return BOOK_MARKERS.some((marker) => entries.includes(marker));
+}
+
+/**
+ * Find the books directly under `rootDir`: each non-internal subfolder that is
+ * itself a book. One level deep, not recursive; sorted by name for a stable
+ * menu. Dot/underscore folders and book internals are skipped.
+ */
+export async function discoverBooks(io: IO, rootDir: string): Promise<Book[]> {
+  let entries: string[];
+  try {
+    entries = await io.fs.readDir(rootDir);
+  } catch {
+    return [];
+  }
+  const books: Book[] = [];
+  for (const name of [...entries].sort()) {
+    if (name.startsWith(".") || name.startsWith("_") || NON_BOOK_DIRS.has(name)) {
+      continue;
+    }
+    const dir = join(rootDir, name);
+    if (await isBook(io, dir)) {
+      books.push({ name, dir });
+    }
+  }
+  return books;
+}
+
+/**
+ * Read a workspace from `rootDir`. When the root is itself a book it is the only
+ * book (back-compat single-book path, named after the folder); otherwise the
+ * root is a workspace of its sub-books.
+ */
+export async function loadWorkspace(io: IO, rootDir: string): Promise<Workspace> {
+  if (await isBook(io, rootDir)) {
+    return { root: rootDir, books: [{ name: basename(rootDir), dir: rootDir }] };
+  }
+  return { root: rootDir, books: await discoverBooks(io, rootDir) };
+}
+
+/** Split an operand on the first `/`: `book/comp` (comp may itself contain `/`). */
+export function parseAddress(operand: string): Address {
+  const slash = operand.indexOf("/");
+  if (slash === -1) {
+    return { comp: operand };
+  }
+  return { book: operand.slice(0, slash), comp: operand.slice(slash + 1) };
+}
+
+/** A book's directory relative to the workspace root (`.` when it is the root). */
+export function bookDir(workspace: Workspace, book: Book): string {
+  return relative(workspace.root, book.dir) || ".";
+}
+
+/**
+ * Resolve an operand to a concrete book + composition. A `<book>/<comp>` prefix
+ * that names a known book addresses it directly; otherwise the whole operand is
+ * a bare composition name, resolved by uniqueness across the workspace's books
+ * (a single-book workspace always uses its one book). Throws a clear error when
+ * a bare name is missing or ambiguous.
+ */
+export async function resolveAddress(
+  io: IO,
+  workspace: Workspace,
+  operand: string,
+): Promise<ResolvedAddress> {
+  const address = parseAddress(operand);
+  if (address.book !== undefined) {
+    const book = workspace.books.find((b) => b.name === address.book);
+    if (book !== undefined) {
+      return { book, comp: address.comp };
+    }
+    // Prefix names no book: fall through and treat the whole operand as a
+    // (possibly path-like) bare composition name.
+  }
+
+  if (workspace.books.length === 1) {
+    return { book: workspace.books[0] as Book, comp: operand };
+  }
+
+  const matches: { book: Book; loaded: PromptBook }[] = [];
+  for (const book of workspace.books) {
+    const loaded = await loadPrompts(book.dir, io.fs);
+    if (loaded.compositions.has(operand)) {
+      matches.push({ book, loaded });
+    }
+  }
+  const [first] = matches;
+  if (matches.length === 1 && first !== undefined) {
+    return { book: first.book, comp: operand, loaded: first.loaded };
+  }
+  if (matches.length === 0) {
+    throw new Error(`Unknown prompt "${operand}" in any book. Qualify it as <book>/<comp>.`);
+  }
+  const names = matches.map((m) => m.book.name).join(", ");
+  throw new Error(
+    `Ambiguous prompt "${operand}"; found in ${matches.length} books (${names}). Qualify it as <book>/<comp>.`,
+  );
+}