@markbrutx/promptbook-cli 0.1.0

package/src/config.ts

@@ -0,0 +1,209 @@
+import { resolve as resolvePath } from "node:path";
+import type { Context, ContextValue } from "@markbrutx/promptbook-core";
+import type { IO } from "./io.js";
+
+const NUMERIC = /^-?\d+(?:\.\d+)?$/;
+
+/** True for a plain JSON object: an object that is neither null nor an array. */
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Coerce a raw `--ctx` value to a {@link ContextValue}: `true`/`false` become
+ * booleans, integer/decimal literals become numbers, everything else stays a
+ * string. For values that must stay strings (e.g. "123"), use `--context-file`.
+ */
+export function coerceScalar(raw: string): ContextValue {
+  if (raw === "true") {
+    return true;
+  }
+  if (raw === "false") {
+    return false;
+  }
+  if (NUMERIC.test(raw)) {
+    return Number(raw);
+  }
+  return raw;
+}
+
+/** Parse repeated `key=value` pairs into a context bag, coercing each value. */
+export function parseCtxPairs(pairs: string[]): Context {
+  const context: Context = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) {
+      throw new Error(`invalid --ctx "${pair}"; expected key=value`);
+    }
+    const key = pair.slice(0, eq);
+    if (key === "") {
+      throw new Error(`invalid --ctx "${pair}"; key is empty`);
+    }
+    context[key] = coerceScalar(pair.slice(eq + 1));
+  }
+  return context;
+}
+
+function parseContextFile(raw: string, path: string): Context {
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`context file "${path}" is not valid JSON: ${(error as Error).message}`);
+  }
+  if (!isJsonObject(data)) {
+    throw new Error(`context file "${path}" must be a JSON object`);
+  }
+  const context: Context = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      context[key] = value;
+    } else {
+      throw new Error(`context file "${path}" key "${key}" must be a string, number or boolean`);
+    }
+  }
+  return context;
+}
+
+/**
+ * Build the resolve context: `--context-file` first, then `--ctx` pairs layered
+ * on top so explicit flags win over the file.
+ */
+export async function buildContext(io: IO, pairs: string[], contextFile?: string): Promise<Context> {
+  let fileContext: Context = {};
+  if (contextFile !== undefined) {
+    const path = resolvePath(io.cwd(), contextFile);
+    let raw: string;
+    try {
+      raw = await io.fs.readFile(path);
+    } catch {
+      throw new Error(`context file not found: ${path}`);
+    }
+    fileContext = parseContextFile(raw, path);
+  }
+  return { ...fileContext, ...parseCtxPairs(pairs) };
+}
+
+interface PromptbookConfig {
+  promptsDir?: unknown;
+  lint?: unknown;
+  eval?: unknown;
+}
+
+/** lint options sourced from the `lint` section of `promptbook.json`. */
+export interface LintConfig {
+  maxTokens?: number;
+  bannedTokens?: string[];
+}
+
+/**
+ * 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.
+ */
+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 {};
+  }
+}
+
+/** Extract the `lint` section from an already-loaded config. */
+export function lintConfigFrom(config: PromptbookConfig): LintConfig {
+  const section = config.lint;
+  if (!isJsonObject(section)) {
+    return {};
+  }
+  const lint: LintConfig = {};
+  if (typeof section.maxTokens === "number") {
+    lint.maxTokens = section.maxTokens;
+  }
+  if (Array.isArray(section.bannedTokens)) {
+    lint.bannedTokens = section.bannedTokens.filter((token): token is string => typeof token === "string");
+  }
+  return lint;
+}
+
+/** Convenience wrapper: load config and extract its `lint` section. */
+export async function loadLintConfig(io: IO): Promise<LintConfig> {
+  return lintConfigFrom(await loadConfig(io));
+}
+
+/** eval options sourced from the `eval` section of `promptbook.json`. */
+export interface EvalConfig {
+  model?: string;
+  baseUrl?: string;
+}
+
+/** Extract the `eval` section from an already-loaded config. */
+export function evalConfigFrom(config: PromptbookConfig): EvalConfig {
+  const section = config.eval;
+  if (!isJsonObject(section)) {
+    return {};
+  }
+  const evalConfig: EvalConfig = {};
+  if (typeof section.model === "string") {
+    evalConfig.model = section.model;
+  }
+  if (typeof section.baseUrl === "string") {
+    evalConfig.baseUrl = section.baseUrl;
+  }
+  return 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.
+ */
+export async function resolvePromptsDir(
+  io: IO,
+  dirFlag?: string,
+  config?: PromptbookConfig,
+): 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);
+  }
+  return resolvePath(io.cwd(), "prompts");
+}
+
+/** Whether a directory can be listed; used to give a clear missing-folder error. */
+async function dirExists(io: IO, dir: string): Promise<boolean> {
+  try {
+    await io.fs.readDir(dir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the prompts folder and confirm it exists. On a missing folder, write
+ * a clear error to stderr and return null so the caller can exit non-zero.
+ */
+export async function requirePromptsDir(
+  io: IO,
+  dirFlag?: string,
+  config?: PromptbookConfig,
+): Promise<string | null> {
+  const promptsDir = await resolvePromptsDir(io, dirFlag, config);
+  if (!(await dirExists(io, promptsDir))) {
+    io.stderr(`error: prompts folder not found: ${promptsDir}\n`);
+    return null;
+  }
+  return promptsDir;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { ParsedArgs } from "./args.js";
+export type { IO } from "./io.js";
+export { run } from "./run.js";

package/src/io.ts

@@ -0,0 +1,77 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { FsAdapter, ModelAdapter } from "@markbrutx/promptbook-core";
+import { nodeFs } from "@markbrutx/promptbook-core";
+
+/** Options the `eval` command needs to build a model adapter. */
+export interface AdapterOptions {
+  model?: string;
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+/**
+ * Injectable side-effect surface for the CLI.
+ *
+ * Keeping stdout/stderr/cwd/fs behind this interface lets {@link run} be driven
+ * from tests without spawning a process. The stream contract is fixed:
+ * **stdout = payload** (prompt text or JSON), **stderr = explanations/errors**.
+ */
+export interface IO {
+  /** Write payload bytes verbatim (the command appends its own newlines). */
+  stdout(text: string): void;
+  /** Write explanations, warnings and errors verbatim. */
+  stderr(text: string): void;
+  /** Write a file to disk, creating parent directories as needed (e.g. `bundle -o`). */
+  writeFile(path: string, contents: string): Promise<void>;
+  /** Current working directory, used to resolve relative paths and config. */
+  cwd(): string;
+  /** Environment bag, consulted for `NO_COLOR`. */
+  env: Record<string, string | undefined>;
+  /** Filesystem adapter passed straight through to the core. */
+  fs: FsAdapter;
+  /** Whether color is allowed when `NO_COLOR` is unset (true on a TTY). */
+  colorDefault: boolean;
+  /**
+   * Build the model adapter for `eval`. Tests inject a fake so no network or
+   * key is needed; when unset, the command falls back to the OpenRouter
+   * adapter built from flags/config/env.
+   */
+  makeAdapter?(options: AdapterOptions): ModelAdapter;
+}
+
+/** Real-process IO: stdout/stderr streams, Node fs, live env and cwd. */
+export function defaultIO(): IO {
+  return {
+    stdout(text) {
+      process.stdout.write(text);
+    },
+    stderr(text) {
+      process.stderr.write(text);
+    },
+    async writeFile(path, contents) {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, contents);
+    },
+    cwd: () => process.cwd(),
+    env: process.env,
+    fs: nodeFs(),
+    colorDefault: Boolean(process.stderr.isTTY),
+  };
+}
+
+/** Emit each warning to stderr with the standard `warning:` prefix. */
+export function emitWarnings(io: IO, warnings: string[]): void {
+  for (const warning of warnings) {
+    io.stderr(`warning: ${warning}\n`);
+  }
+}
+
+/** Resolve whether colored output is allowed: off if `NO_COLOR` is set. */
+export function colorEnabled(io: IO): boolean {
+  const flag = io.env.NO_COLOR;
+  if (flag !== undefined && flag !== "") {
+    return false;
+  }
+  return io.colorDefault;
+}

package/src/render-eval.ts

@@ -0,0 +1,55 @@
+import type { AssertionResult, EvalReport, FixtureResult } from "@markbrutx/promptbook-core";
+import { makeStyle, plural, type Style } from "./style.js";
+
+function rate(value: number): string {
+  return value.toFixed(2);
+}
+
+/** One line per fixture plus indented failure details for the failed ones. */
+function renderFixture(s: Style, fixture: FixtureResult, threshold: number): string[] {
+  const ok = fixture.passRate >= threshold;
+  const mark = ok ? s.green("✓") : s.red("✗");
+  const head = `  ${mark} ${fixture.name}  passRate ${rate(fixture.passRate)} (${fixture.passes}/${fixture.samples})`;
+  const lines = [head];
+  if (!ok) {
+    for (const failure of dedupeFailures(fixture.failures)) {
+      lines.push(`      ${s.red(failure.type)}: ${failure.message}`);
+      if (failure.excerpt !== undefined && failure.excerpt !== "") {
+        lines.push(`        ${s.dim(`output: ${failure.excerpt}`)}`);
+      }
+    }
+  }
+  return lines;
+}
+
+/** Collapse identical failures (same type + message) repeated across samples. */
+function dedupeFailures(failures: AssertionResult[]): AssertionResult[] {
+  const seen = new Set<string>();
+  const unique: AssertionResult[] = [];
+  for (const failure of failures) {
+    const key = `${failure.type}\u0000${failure.message}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push(failure);
+    }
+  }
+  return unique;
+}
+
+/**
+ * Render an {@link EvalReport} as a human-readable block: a per-fixture line
+ * (pass/fail mark, passRate, samples) with indented failing assertions and
+ * output excerpts, then a summary line gated by `threshold`.
+ */
+export function renderEvalReport(report: EvalReport, threshold: number, color: boolean): string {
+  const s = makeStyle(color);
+  const lines: string[] = [s.bold("eval")];
+  for (const fixture of report.results) {
+    lines.push(...renderFixture(s, fixture, threshold));
+  }
+  const total = report.results.length;
+  const summary = `${report.passed}/${total} fixtures passed (threshold ${rate(threshold)})`;
+  const colored = report.failed > 0 ? s.red(summary) : s.green(summary);
+  lines.push(`summary: ${colored}, ${plural(report.failed, "failure")}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/render-explain.ts

@@ -0,0 +1,64 @@
+import type { ContextValue, Trace } from "@markbrutx/promptbook-core";
+import { formatContext, makeStyle } from "./style.js";
+
+function whenLabel(when: Record<string, ContextValue>): string {
+  const label = formatContext(when);
+  return label === "" ? "always" : label;
+}
+
+/**
+ * Render an explain {@link Trace} as a human-readable block for stderr: which
+ * rules fired (and why not), the final order, the replace/add/forbid effects,
+ * and a highlighted "no rule matched" section for unmatched context axes.
+ */
+export function renderExplain(trace: Trace, color: boolean): string {
+  const s = makeStyle(color);
+  const lines: string[] = [];
+
+  const contextLabel = whenLabel(trace.context);
+  lines.push(`${s.bold(`resolve "${trace.prompt}"`)}${s.dim(` · context: ${contextLabel}`)}`);
+
+  lines.push(s.bold("rules:"));
+  if (trace.rules.length === 0) {
+    lines.push(`  ${s.dim("(none)")}`);
+  }
+  for (const rule of trace.rules) {
+    const head = `#${rule.index} ${rule.action} ${s.dim(`[${whenLabel(rule.when)}]`)}`;
+    if (rule.fired) {
+      lines.push(`  ${s.green("✓")} ${head} → ${rule.effect ?? ""}`);
+    } else {
+      lines.push(`  ${s.red("✗")} ${head} ${s.dim(`— ${rule.reason ?? "did not match"}`)}`);
+    }
+  }
+
+  lines.push(`${s.bold("final order:")} ${trace.finalOrder.join(" → ") || "(empty)"}`);
+
+  if (trace.replaced.length > 0) {
+    lines.push(s.bold("replaced:"));
+    for (const entry of trace.replaced) {
+      lines.push(`  ${entry.from} → ${entry.to} ${s.dim(`(#${entry.ruleIndex})`)}`);
+    }
+  }
+  if (trace.added.length > 0) {
+    lines.push(s.bold("added:"));
+    for (const entry of trace.added) {
+      const anchor = entry.after !== undefined ? ` after ${entry.after}` : "";
+      lines.push(`  ${entry.id}${anchor} ${s.dim(`(#${entry.ruleIndex})`)}`);
+    }
+  }
+  if (trace.forbidden.length > 0) {
+    lines.push(s.bold("forbidden:"));
+    for (const entry of trace.forbidden) {
+      lines.push(`  ${entry.id} ${s.dim(`(#${entry.ruleIndex})`)}`);
+    }
+  }
+
+  if (trace.unmatchedAxes.length > 0) {
+    lines.push(s.warn(s.bold("unmatched axes:")));
+    for (const axis of trace.unmatchedAxes) {
+      lines.push(`  ${s.warn(`⚠ no rules matched for ${axis.key}=${axis.value}`)}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/render-lint.ts

@@ -0,0 +1,63 @@
+import type { LintFinding, LintReport, Severity } from "@markbrutx/promptbook-core";
+import { makeStyle, plural, type Style } from "./style.js";
+
+const SEVERITY_ORDER: Severity[] = ["error", "warning", "info"];
+
+function location(finding: LintFinding): string {
+  const parts: string[] = [];
+  if (finding.fragmentId !== undefined) {
+    parts.push(`fragment: ${finding.fragmentId}`);
+  }
+  if (finding.ruleIndex !== undefined) {
+    parts.push(`rule #${finding.ruleIndex}`);
+  }
+  return parts.length > 0 ? `  (${parts.join(", ")})` : "";
+}
+
+function colorize(s: Style, severity: Severity, text: string): string {
+  if (severity === "error") {
+    return s.red(text);
+  }
+  if (severity === "warning") {
+    return s.warn(text);
+  }
+  return s.dim(text);
+}
+
+/**
+ * Render a {@link LintReport} as a human-readable block grouped by severity.
+ * A clean report is a single green line; otherwise a summary line is followed
+ * by `errors:`/`warnings:`/`info:` sections listing `ruleId: message`.
+ */
+export function renderLintReport(report: LintReport, label: string, color: boolean): string {
+  const s = makeStyle(color);
+  const head = s.bold(`lint "${label}"`);
+  if (report.findings.length === 0) {
+    return `${head} ${s.green("— no findings")}\n`;
+  }
+
+  const infoCount = report.findings.length - report.errorCount - report.warningCount;
+  const summary: string[] = [];
+  if (report.errorCount > 0) {
+    summary.push(s.red(plural(report.errorCount, "error")));
+  }
+  if (report.warningCount > 0) {
+    summary.push(s.warn(plural(report.warningCount, "warning")));
+  }
+  if (infoCount > 0) {
+    summary.push(s.dim(plural(infoCount, "info")));
+  }
+
+  const lines: string[] = [`${head} — ${summary.join(", ")}`];
+  for (const severity of SEVERITY_ORDER) {
+    const group = report.findings.filter((finding) => finding.severity === severity);
+    if (group.length === 0) {
+      continue;
+    }
+    lines.push(colorize(s, severity, s.bold(`${severity}s:`)));
+    for (const finding of group) {
+      lines.push(`  ${finding.ruleId}: ${finding.message}${location(finding)}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/run.ts

@@ -0,0 +1,107 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseCliArgs } from "./args.js";
+import { cmdAnnotations } from "./commands/annotations.js";
+import { cmdBundle } from "./commands/bundle.js";
+import { cmdEval } from "./commands/eval.js";
+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 { defaultIO, type IO } from "./io.js";
+
+const HELP = `promptbook — compose prompts from reusable fragments
+
+Usage:
+  promptbook <command> [options]
+
+Commands:
+  resolve <prompt>        Assemble a prompt and print it to stdout
+  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
+  annotations <action>    Drain the viewer's feedback queue: list | resolve <id> | clear
+  ls                      List compositions and fragments
+
+Options:
+  --dir <path>            Prompts folder (default: promptbook.json promptsDir, else ./prompts)
+  --ctx key=value         Context value, repeatable (coerced to boolean/number/string)
+  --context-file <json>   Merge context from a JSON file (--ctx overrides it)
+  --explain               resolve: print the resolution trace to stderr
+  --json                  Emit machine-readable JSON on stdout
+  --max-tokens N          lint: token-budget ceiling (overrides promptbook.json)
+  --strict                lint: exit non-zero on warnings too
+  --model <id>            eval: model id for the adapter (overrides promptbook.json)
+  --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)
+  --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
+  -h, --help              Show this help
+  -v, --version           Show the version
+
+Streams: stdout = payload (prompt text or JSON); stderr = explanations and errors.
+`;
+
+function readVersion(): string {
+  try {
+    const path = fileURLToPath(new URL("../../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync(path, "utf8")) as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/**
+ * CLI entry point. Parses argv, handles `--help`/`--version`, then dispatches
+ * to a subcommand. Returns the process exit code; never calls `process.exit`
+ * so it stays testable. `io` injects all side effects (streams, fs, env, cwd).
+ */
+export async function run(argv: string[], io: IO = defaultIO()): Promise<number> {
+  let args: ReturnType<typeof parseCliArgs>;
+  try {
+    args = parseCliArgs(argv);
+  } catch (error) {
+    io.stderr(`error: ${(error as Error).message}\n`);
+    return 1;
+  }
+
+  if (args.help) {
+    io.stdout(HELP);
+    return 0;
+  }
+  if (args.version) {
+    io.stdout(`${readVersion()}\n`);
+    return 0;
+  }
+  if (args.command === undefined) {
+    io.stdout(HELP);
+    return 0;
+  }
+
+  switch (args.command) {
+    case "resolve":
+      return cmdResolve(args, io);
+    case "lint":
+      return cmdLint(args, io);
+    case "eval":
+      return cmdEval(args, io);
+    case "bundle":
+      return cmdBundle(args, io);
+    case "view":
+      return cmdView(args, io);
+    case "annotations":
+      return cmdAnnotations(args, io);
+    case "ls":
+      return cmdLs(args, io);
+    default:
+      io.stderr(`error: unknown command "${args.command}". Run "promptbook --help".\n`);
+      return 1;
+  }
+}

package/src/style.ts

@@ -0,0 +1,37 @@
+import type { ContextValue } from "@markbrutx/promptbook-core";
+
+/** Render a context/when bag as `k=v, k=v` (empty string when empty). */
+export function formatContext(context: Record<string, ContextValue>): string {
+  return Object.entries(context)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(", ");
+}
+
+/** Minimal ANSI styling, used by the explain and lint renderers. */
+export interface Style {
+  bold(text: string): string;
+  dim(text: string): string;
+  green(text: string): string;
+  red(text: string): string;
+  warn(text: string): string;
+}
+
+/** Pluralize `word` by `count`, e.g. `plural(2, "error")` -> "2 errors". */
+export function plural(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+
+/** Build a {@link Style}; when `color` is false every helper is a no-op. */
+export function makeStyle(color: boolean): Style {
+  const wrap =
+    (code: string) =>
+    (text: string): string =>
+      color ? `\x1b[${code}m${text}\x1b[0m` : text;
+  return {
+    bold: wrap("1"),
+    dim: wrap("2"),
+    green: wrap("32"),
+    red: wrap("31"),
+    warn: wrap("33"),
+  };
+}