@markbrutx/promptbook-cli 0.1.0 → 0.2.0

package/dist/src/workspace.js

@@ -0,0 +1,103 @@
+import { basename, join, relative } from "node:path";
+import { loadPrompts } from "@markbrutx/promptbook-core";
+/** 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, dir) {
+    let entries;
+    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, rootDir) {
+    let entries;
+    try {
+        entries = await io.fs.readDir(rootDir);
+    }
+    catch {
+        return [];
+    }
+    const books = [];
+    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, rootDir) {
+    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) {
+    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, book) {
+    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, workspace, operand) {
+    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], comp: operand };
+    }
+    const matches = [];
+    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>.`);
+}
+//# sourceMappingURL=workspace.js.map

package/dist/src/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/workspace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,28 @@
 {
   "name": "@markbrutx/promptbook-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Thin terminal surface over @markbrutx/promptbook-core: resolve and ls for agents and CI.",
   "type": "module",
   "license": "MIT",
+  "keywords": [
+    "prompt",
+    "prompt-engineering",
+    "prompt-management",
+    "llm",
+    "ai",
+    "cli",
+    "composition",
+    "storybook"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markbrutx/promptbook.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/markbrutx/promptbook#readme",
+  "bugs": "https://github.com/markbrutx/promptbook/issues",
   "bin": {
-    "promptbook": "./dist/bin/promptbook.js"
+    "promptbook": "dist/bin/promptbook.js"
   },
   "exports": {
     ".": {
@@ -31,11 +48,11 @@
     "check": "biome check ."
   },
   "dependencies": {
-    "@markbrutx/promptbook-core": "^0.1.0",
-    "@markbrutx/promptbook-openrouter": "^0.1.0"
+    "@markbrutx/promptbook-core": "^0.2.0",
+    "@markbrutx/promptbook-openrouter": "^0.2.0"
   },
   "optionalDependencies": {
-    "@markbrutx/promptbook-viewer": "^0.1.0"
+    "@markbrutx/promptbook-viewer": "^0.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "latest",

package/src/args.ts

@@ -20,6 +20,8 @@ export interface ParsedArgs {
   contextFile?: string;
   fragments: boolean;
   compositions: boolean;
+  /** ls/resolve: operate across every book in the workspace. */
+  all: boolean;
   /** lint: estimated token ceiling for the token-budget rule. */
   maxTokens?: number;
   /** lint: treat warnings as failures for the exit code. */
@@ -88,6 +90,7 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
       "context-file": { type: "string" },
       fragments: { type: "boolean" },
       compositions: { type: "boolean" },
+      all: { type: "boolean" },
       "max-tokens": { type: "string" },
       strict: { type: "boolean" },
       model: { type: "string" },
@@ -133,6 +136,7 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     contextFile: values["context-file"],
     fragments: values.fragments ?? false,
     compositions: values.compositions ?? false,
+    all: values.all ?? false,
     maxTokens,
     strict: values.strict ?? false,
     model: values.model,

package/src/commands/ls.ts

@@ -1,15 +1,112 @@
-import { relative } from "node:path";
-import { loadPrompts } from "@markbrutx/promptbook-core";
+import { basename, relative } from "node:path";
+import type { PromptBook, RequiredContext } from "@markbrutx/promptbook-core";
+import { loadPrompts, requiredContext } from "@markbrutx/promptbook-core";
 import type { ParsedArgs } from "../args.js";
 import { requirePromptsDir } from "../config.js";
 import { emitWarnings, type IO } from "../io.js";
+import { bookDir, loadWorkspace } from "../workspace.js";
+
+interface CompositionEntry {
+  name: string;
+  base: number;
+  rules: number;
+  requiredContext: RequiredContext;
+}
+
+interface CodePromptEntry {
+  name: string;
+  description: string | null;
+  samples: number;
+}
+
+/** Composition rows for the menu: counts plus the statically-declared context. */
+function compositionEntries(book: PromptBook): CompositionEntry[] {
+  return [...book.compositions.values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((c) => ({
+      name: c.name,
+      base: c.base.length,
+      rules: c.rules.length,
+      requiredContext: requiredContext(book, c.name),
+    }));
+}
+
+/** Code-prompt rows: builder metadata only (opaque; no requiredContext). */
+function codePromptEntries(book: PromptBook): CodePromptEntry[] {
+  return [...book.codePrompts.values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((c) => ({ name: c.name, description: c.description ?? null, samples: c.samples.length }));
+}
+
+/** Compact one-line context summary for the plain `--all` tree. */
+function ctxSummary(rc: RequiredContext): string {
+  const vars = rc.vars.length > 0 ? rc.vars.join(",") : "-";
+  const axes =
+    Object.entries(rc.axes)
+      .map(([key, values]) => `${key}=${values.join("|")}`)
+      .join(" ") || "-";
+  return `vars=${vars} axes=${axes}`;
+}
+
+/**
+ * `ls --all`: a cross-book inventory of the whole workspace. Discovers every
+ * book under the root, loads each, and emits the menu (compositions with their
+ * required context + code-prompts) — `--json` as `{ workspace, books[] }`,
+ * plain as an indented book→composition tree. Order is deterministic (books and
+ * compositions sorted by name).
+ */
+async function cmdLsAll(io: IO, root: string, json: boolean): Promise<number> {
+  const workspace = await loadWorkspace(io, root);
+  const books = await Promise.all(
+    workspace.books.map(async (b) => {
+      const book = await loadPrompts(b.dir, io.fs);
+      return {
+        name: b.name,
+        dir: bookDir(workspace, b),
+        compositions: compositionEntries(book),
+        codePrompts: codePromptEntries(book),
+        warnings: book.warnings,
+      };
+    }),
+  );
+
+  if (json) {
+    io.stdout(`${JSON.stringify({ workspace: basename(workspace.root), books }, null, 2)}\n`);
+    return 0;
+  }
+
+  const lines: string[] = [`workspace: ${basename(workspace.root)}`];
+  if (books.length === 0) {
+    lines.push("  (no books found)");
+  }
+  for (const book of books) {
+    lines.push("", `${book.name}  (${book.dir})`);
+    lines.push("  compositions:");
+    if (book.compositions.length === 0) {
+      lines.push("    (none)");
+    }
+    for (const c of book.compositions) {
+      lines.push(`    ${c.name}  base=${c.base} rules=${c.rules}  ctx: ${ctxSummary(c.requiredContext)}`);
+    }
+    if (book.codePrompts.length > 0) {
+      lines.push("  code-prompts:");
+      for (const c of book.codePrompts) {
+        lines.push(`    ${c.name}  kind=code samples=${c.samples}`);
+      }
+    }
+    emitWarnings(io, book.warnings);
+  }
+  io.stdout(`${lines.join("\n")}\n`);
+  return 0;
+}
 
 /**
- * `ls`: list compositions (name, base length, rule count), code-prompts
- * (name, description, sample count) and fragments (id, kind, tags, source) —
- * the unified menu of every prompt in the book. `--fragments`/`--compositions`
- * narrow the output (code-prompts ride with compositions, both being prompts);
- * `--json` emits a structured list instead of the human-readable tree.
+ * `ls`: list compositions (name, base length, rule count, required context),
+ * code-prompts (name, description, sample count) and fragments (id, kind, tags,
+ * source) — the unified menu of every prompt in the book. `--fragments`/
+ * `--compositions` narrow the output (code-prompts ride with compositions, both
+ * being prompts); `--json` emits a structured list; `--all` spans every book in
+ * the workspace instead of one folder.
  */
 export async function cmdLs(args: ParsedArgs, io: IO): Promise<number> {
   const promptsDir = await requirePromptsDir(io, args.dir);
@@ -17,6 +114,10 @@ export async function cmdLs(args: ParsedArgs, io: IO): Promise<number> {
     return 1;
   }
 
+  if (args.all) {
+    return cmdLsAll(io, promptsDir, args.json);
+  }
+
   const book = await loadPrompts(promptsDir, io.fs);
   emitWarnings(io, book.warnings);
 
@@ -24,23 +125,15 @@ export async function cmdLs(args: ParsedArgs, io: IO): Promise<number> {
   const showCompositions = args.compositions || !onlyOneSection;
   const showFragments = args.fragments || !onlyOneSection;
 
-  const compositions = [...book.compositions.values()].sort((a, b) => a.name.localeCompare(b.name));
-  const codePrompts = [...book.codePrompts.values()].sort((a, b) => a.name.localeCompare(b.name));
+  const compositions = compositionEntries(book);
+  const codePrompts = codePromptEntries(book);
   const fragments = [...book.fragments.values()].sort((a, b) => a.id.localeCompare(b.id));
 
   if (args.json) {
     const out: Record<string, unknown> = {};
     if (showCompositions) {
-      out.compositions = compositions.map((c) => ({
-        name: c.name,
-        base: c.base.length,
-        rules: c.rules.length,
-      }));
-      out.codePrompts = codePrompts.map((c) => ({
-        name: c.name,
-        description: c.description ?? null,
-        samples: c.samples.length,
-      }));
+      out.compositions = compositions;
+      out.codePrompts = codePrompts;
     }
     if (showFragments) {
       out.fragments = fragments.map((f) => ({
@@ -61,13 +154,13 @@ export async function cmdLs(args: ParsedArgs, io: IO): Promise<number> {
       lines.push("  (none)");
     }
     for (const c of compositions) {
-      lines.push(`  ${c.name}  base=${c.base.length}  rules=${c.rules.length}`);
+      lines.push(`  ${c.name}  base=${c.base}  rules=${c.rules}`);
     }
     if (codePrompts.length > 0) {
       lines.push("");
       lines.push("code-prompts:");
       for (const c of codePrompts) {
-        lines.push(`  ${c.name}  kind=code  samples=${c.samples.length}`);
+        lines.push(`  ${c.name}  kind=code  samples=${c.samples}`);
       }
     }
   }

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/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>.`,
+  );
+}