@markbrutx/promptbook-cli 0.1.0

package/dist/src/io.js

@@ -0,0 +1,37 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { nodeFs } from "@markbrutx/promptbook-core";
+/** Real-process IO: stdout/stderr streams, Node fs, live env and cwd. */
+export function defaultIO() {
+    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, warnings) {
+    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) {
+    const flag = io.env.NO_COLOR;
+    if (flag !== undefined && flag !== "") {
+        return false;
+    }
+    return io.colorDefault;
+}
+//# sourceMappingURL=io.js.map

package/dist/src/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAuCpD,yEAAyE;AACzE,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,MAAM,CAAC,IAAI;YACT,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,MAAM,CAAC,IAAI;YACT,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ;YAC5B,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,MAAM,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClC,CAAC;QACD,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;QACxB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,EAAE,EAAE,MAAM,EAAE;QACZ,YAAY,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,EAAM,EAAE,QAAkB;IACrD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,EAAE,CAAC,MAAM,CAAC,YAAY,OAAO,IAAI,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,YAAY,CAAC,EAAM;IACjC,MAAM,IAAI,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC7B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,EAAE,CAAC,YAAY,CAAC;AACzB,CAAC"}

package/dist/src/render-eval.d.ts

@@ -0,0 +1,8 @@
+import type { EvalReport } from "@markbrutx/promptbook-core";
+/**
+ * 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 declare function renderEvalReport(report: EvalReport, threshold: number, color: boolean): string;
+//# sourceMappingURL=render-eval.d.ts.map

package/dist/src/render-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-eval.d.ts","sourceRoot":"","sources":["../../src/render-eval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,UAAU,EAAiB,MAAM,4BAA4B,CAAC;AAsC7F;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAW9F"}

package/dist/src/render-eval.js

@@ -0,0 +1,51 @@
+import { makeStyle, plural } from "./style.js";
+function rate(value) {
+    return value.toFixed(2);
+}
+/** One line per fixture plus indented failure details for the failed ones. */
+function renderFixture(s, fixture, threshold) {
+    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) {
+    const seen = new Set();
+    const unique = [];
+    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, threshold, color) {
+    const s = makeStyle(color);
+    const lines = [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`;
+}
+//# sourceMappingURL=render-eval.js.map

package/dist/src/render-eval.js.map

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

package/dist/src/render-explain.d.ts

@@ -0,0 +1,8 @@
+import type { Trace } from "@markbrutx/promptbook-core";
+/**
+ * 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 declare function renderExplain(trace: Trace, color: boolean): string;
+//# sourceMappingURL=render-explain.d.ts.map

package/dist/src/render-explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-explain.d.ts","sourceRoot":"","sources":["../../src/render-explain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAQtE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAkDlE"}

package/dist/src/render-explain.js

@@ -0,0 +1,57 @@
+import { formatContext, makeStyle } from "./style.js";
+function whenLabel(when) {
+    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, color) {
+    const s = makeStyle(color);
+    const lines = [];
+    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`;
+}
+//# sourceMappingURL=render-explain.js.map

package/dist/src/render-explain.js.map

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

package/dist/src/render-lint.d.ts

@@ -0,0 +1,8 @@
+import type { LintReport } from "@markbrutx/promptbook-core";
+/**
+ * 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 declare function renderLintReport(report: LintReport, label: string, color: boolean): string;
+//# sourceMappingURL=render-lint.d.ts.map

package/dist/src/render-lint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-lint.d.ts","sourceRoot":"","sources":["../../src/render-lint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,UAAU,EAAY,MAAM,4BAA4B,CAAC;AA0BpF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CA+B1F"}

package/dist/src/render-lint.js

@@ -0,0 +1,57 @@
+import { makeStyle, plural } from "./style.js";
+const SEVERITY_ORDER = ["error", "warning", "info"];
+function location(finding) {
+    const parts = [];
+    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, severity, text) {
+    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, label, color) {
+    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 = [];
+    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 = [`${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`;
+}
+//# sourceMappingURL=render-lint.js.map

package/dist/src/render-lint.js.map

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

package/dist/src/run.d.ts

@@ -0,0 +1,8 @@
+import { type IO } from "./io.js";
+/**
+ * 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 declare function run(argv: string[], io?: IO): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/src/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAUA,OAAO,EAAa,KAAK,EAAE,EAAE,MAAM,SAAS,CAAC;AAkD7C;;;;GAIG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,EAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyC/E"}

package/dist/src/run.js

@@ -0,0 +1,105 @@
+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 } 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() {
+    try {
+        const path = fileURLToPath(new URL("../../package.json", import.meta.url));
+        const pkg = JSON.parse(readFileSync(path, "utf8"));
+        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, io = defaultIO()) {
+    let args;
+    try {
+        args = parseCliArgs(argv);
+    }
+    catch (error) {
+        io.stderr(`error: ${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;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/src/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAW,MAAM,SAAS,CAAC;AAE7C,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCZ,CAAC;AAEF,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,oBAAoB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3E,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAyB,CAAC;QAC3E,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAc,EAAE,EAAE,GAAO,SAAS,EAAE;IAC5D,IAAI,IAAqC,CAAC;IAC1C,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,EAAE,CAAC,MAAM,CAAC,UAAW,KAAe,CAAC,OAAO,IAAI,CAAC,CAAC;QAClD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,EAAE,CAAC,MAAM,CAAC,GAAG,WAAW,EAAE,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,KAAK,SAAS;YACZ,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC9B,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7B,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,KAAK,aAAa;YAChB,OAAO,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAClC,KAAK,IAAI;YACP,OAAO,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACzB;YACE,EAAE,CAAC,MAAM,CAAC,2BAA2B,IAAI,CAAC,OAAO,+BAA+B,CAAC,CAAC;YAClF,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/src/style.d.ts

@@ -0,0 +1,16 @@
+import type { ContextValue } from "@markbrutx/promptbook-core";
+/** Render a context/when bag as `k=v, k=v` (empty string when empty). */
+export declare function formatContext(context: Record<string, ContextValue>): string;
+/** 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 declare function plural(count: number, word: string): string;
+/** Build a {@link Style}; when `color` is false every helper is a no-op. */
+export declare function makeStyle(color: boolean): Style;
+//# sourceMappingURL=style.d.ts.map

package/dist/src/style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../../src/style.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAI3E;AAED,oEAAoE;AACpE,MAAM,WAAW,KAAK;IACpB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC5B;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAY/C"}

package/dist/src/style.js

@@ -0,0 +1,22 @@
+/** Render a context/when bag as `k=v, k=v` (empty string when empty). */
+export function formatContext(context) {
+    return Object.entries(context)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(", ");
+}
+/** Pluralize `word` by `count`, e.g. `plural(2, "error")` -> "2 errors". */
+export function plural(count, word) {
+    return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+/** Build a {@link Style}; when `color` is false every helper is a no-op. */
+export function makeStyle(color) {
+    const wrap = (code) => (text) => color ? `\x1b[${code}m${text}\x1b[0m` : text;
+    return {
+        bold: wrap("1"),
+        dim: wrap("2"),
+        green: wrap("32"),
+        red: wrap("31"),
+        warn: wrap("33"),
+    };
+}
+//# sourceMappingURL=style.js.map

package/dist/src/style.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.js","sourceRoot":"","sources":["../../src/style.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,OAAqC;IACjE,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;SACxC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAWD,4EAA4E;AAC5E,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,IAAY;IAChD,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AACrD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,MAAM,IAAI,GACR,CAAC,IAAY,EAAE,EAAE,CACjB,CAAC,IAAY,EAAU,EAAE,CACvB,KAAK,CAAC,CAAC,CAAC,QAAQ,IAAI,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;QACf,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;QACd,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;QACjB,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC;QACf,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;KACjB,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@markbrutx/promptbook-cli",
+  "version": "0.1.0",
+  "description": "Thin terminal surface over @markbrutx/promptbook-core: resolve and ls for agents and CI.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "promptbook": "./dist/bin/promptbook.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "bin"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "test": "vitest --run",
+    "check": "biome check ."
+  },
+  "dependencies": {
+    "@markbrutx/promptbook-core": "^0.1.0",
+    "@markbrutx/promptbook-openrouter": "^0.1.0"
+  },
+  "optionalDependencies": {
+    "@markbrutx/promptbook-viewer": "^0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "latest",
+    "@types/node": "^20.14.0",
+    "@typescript/native-preview": "latest",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20.6"
+  }
+}

package/src/args.ts

@@ -0,0 +1,145 @@
+import { parseArgs } from "node:util";
+
+/** Normalized view of the command line, independent of `parseArgs` shape. */
+export interface ParsedArgs {
+  /** First positional: the subcommand, or undefined when none was given. */
+  command: string | undefined;
+  /** Positionals after the subcommand (e.g. the prompt name). */
+  operands: string[];
+  help: boolean;
+  version: boolean;
+  dir?: string;
+  json: boolean;
+  explain: boolean;
+  /** bundle: write the generated module to this file instead of stdout. */
+  out?: string;
+  /** bundle: emit a plain module without the type-only import/annotation. */
+  plain: boolean;
+  /** Repeated `--ctx key=value` pairs, parsed later by config. */
+  ctx: string[];
+  contextFile?: string;
+  fragments: boolean;
+  compositions: boolean;
+  /** lint: estimated token ceiling for the token-budget rule. */
+  maxTokens?: number;
+  /** lint: treat warnings as failures for the exit code. */
+  strict: boolean;
+  /** eval: model id passed to the adapter (overrides promptbook.json). */
+  model?: string;
+  /** eval: default samples per fixture when the fixture sets none. */
+  samples?: number;
+  /** eval: a fixture passes when passRate >= this threshold. */
+  threshold?: number;
+  /** eval: run lint on each resolved variant before sampling. */
+  lint: boolean;
+  /** view: port for the viewer server (0/undefined picks a free port). */
+  port?: number;
+  /** view: do not open the browser after the server starts. */
+  noOpen: boolean;
+}
+
+/** Constraints for a numeric flag, used by {@link parseNumberFlag}. */
+interface NumberFlagSpec {
+  integer?: boolean;
+  min?: number;
+  max?: number;
+  /** Human-readable expectation, e.g. "a positive integer". */
+  expected: string;
+}
+
+/**
+ * Parse an optional numeric flag, validating against `spec`. Returns undefined
+ * when the flag was not given; throws a uniform `invalid --name` error when the
+ * value is not a number or falls outside the allowed range.
+ */
+function parseNumberFlag(raw: string | undefined, name: string, spec: NumberFlagSpec): number | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  const parsed = Number(raw);
+  const valid =
+    Number.isFinite(parsed) &&
+    (!spec.integer || Number.isInteger(parsed)) &&
+    (spec.min === undefined || parsed >= spec.min) &&
+    (spec.max === undefined || parsed <= spec.max);
+  if (!valid) {
+    throw new Error(`invalid --${name} "${raw}"; expected ${spec.expected}`);
+  }
+  return parsed;
+}
+
+/**
+ * Parse argv into {@link ParsedArgs}. Strict mode throws on unknown flags; the
+ * caller turns that into a friendly stderr message and a non-zero exit.
+ */
+export function parseCliArgs(argv: string[]): ParsedArgs {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      dir: { type: "string" },
+      json: { type: "boolean" },
+      explain: { type: "boolean" },
+      out: { type: "string", short: "o" },
+      plain: { type: "boolean" },
+      ctx: { type: "string", multiple: true },
+      "context-file": { type: "string" },
+      fragments: { type: "boolean" },
+      compositions: { type: "boolean" },
+      "max-tokens": { type: "string" },
+      strict: { type: "boolean" },
+      model: { type: "string" },
+      samples: { type: "string" },
+      threshold: { type: "string" },
+      lint: { type: "boolean" },
+      port: { type: "string" },
+      "no-open": { type: "boolean" },
+    },
+  });
+  const maxTokens = parseNumberFlag(values["max-tokens"], "max-tokens", {
+    integer: true,
+    min: 1,
+    expected: "a positive integer",
+  });
+  const samples = parseNumberFlag(values.samples, "samples", {
+    integer: true,
+    min: 1,
+    expected: "a positive integer",
+  });
+  const threshold = parseNumberFlag(values.threshold, "threshold", {
+    min: 0,
+    max: 1,
+    expected: "a number between 0 and 1",
+  });
+  const port = parseNumberFlag(values.port, "port", {
+    integer: true,
+    min: 0,
+    max: 65535,
+    expected: "a port between 0 and 65535",
+  });
+  return {
+    command: positionals[0],
+    operands: positionals.slice(1),
+    help: values.help ?? false,
+    version: values.version ?? false,
+    dir: values.dir,
+    json: values.json ?? false,
+    explain: values.explain ?? false,
+    out: values.out,
+    plain: values.plain ?? false,
+    ctx: values.ctx ?? [],
+    contextFile: values["context-file"],
+    fragments: values.fragments ?? false,
+    compositions: values.compositions ?? false,
+    maxTokens,
+    strict: values.strict ?? false,
+    model: values.model,
+    samples,
+    threshold,
+    lint: values.lint ?? false,
+    port,
+    noOpen: values["no-open"] ?? false,
+  };
+}