@rse/specbook 1.0.2 → 1.0.3

package/dst/specbook-api.d.ts

@@ -2,8 +2,8 @@ import { renderDiagnostic, renderDiagnosticVerbose, type Diagnostic } from "./sp
 import { type LintResult } from "./specbook-cmd-lint.js";
 import { parseOutputSpec, formats, type ExportFormat } from "./specbook-cmd-export.js";
 import { describeFormats, describeParts, parseDescribeFormat, parseDescribePart, type DescribeFormat, type DescribePart } from "./specbook-cmd-describe.js";
-import { literal, renderVerbose } from "./specbook-verbose.js";
-export { literal, renderVerbose };
+import { literal, renderVerbose, type Verbose, type VerboseLevel } from "./specbook-verbose.js";
+export { literal, renderVerbose, type Verbose, type VerboseLevel };
 export { formats, parseOutputSpec, type ExportFormat };
 export { describeFormats, describeParts, parseDescribeFormat, parseDescribePart };
 export { type DescribeFormat, type DescribePart };
@@ -13,7 +13,7 @@ export type { Spec, SpecArtifact, SpecObject, SpecDescription, SpecProperty } fr
 export type { Schema, SchemaObject, SchemaProperty } from "./specbook-format-schema.js";
 export declare const version: string;
 export declare const standardConfig: string;
-export type VerboseSink = (cmd: string, msg: string) => void;
+export type VerboseSink = (cmd: string, msg: string, level: VerboseLevel) => void;
 export interface SpecBookOptions {
     verbose?: VerboseSink;
 }

package/dst/specbook-api.js

@@ -11,6 +11,7 @@ import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
 import { exportSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
 import { describeFormat, describeFormats, describeParts, parseDescribeFormat, parseDescribePart } from "./specbook-cmd-describe.js";
+import { requireBrowser } from "./specbook-export-pdf.js";
 import { literal, renderVerbose } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
 export { literal, renderVerbose };
@@ -32,7 +33,7 @@ export class SpecBook {
     }
     /*  bind the verbose sink to a particular command  */
     verboseOf(cmd) {
-        return (msg) => this.verbose(cmd, msg);
+        return (msg, level = "debug") => this.verbose(cmd, msg, level);
     }
     /*  determine the file of the YAML schema configuration, falling
         back onto the bundled standard schema configuration  */
@@ -68,6 +69,11 @@ export class SpecBook {
         as a partial or invalid specification must never be emitted)  */
     async export(options) {
         const verbose = this.verboseOf("export");
+        const requested = options.formats ?? ["json"];
+        /*  a missing browser is an environment problem, so let the PDF
+            export fail before the specification is even parsed  */
+        if (requested.includes("pdf"))
+            await requireBrowser(verbose);
         const result = lint({ config: this.configFile(options.config),
             basedir: options.basedir ?? ".", verbose });
         if (result.diagnostics.length > 0)
@@ -76,7 +82,7 @@ export class SpecBook {
         if (result.specification.artifacts.length === 0)
             throw new Error("unexportable specification: no artifacts found");
         const buffers = new Array();
-        for (const format of options.formats ?? ["json"])
+        for (const format of requested)
             buffers.push(await exportSpecification(result.specification, format, verbose, result.config));
         return buffers;
     }

package/dst/specbook-cli.js

@@ -12,9 +12,11 @@ import { serveMcp } from "./specbook-mcp.js";
 /*  route verbose messages to stderr, keeping stdout reserved for the
     command outputs and the MCP protocol, and qualify every message with
     the tool name plus the scope path of the emitting command, where
-    Chalk styles the output only if the terminal supports colors  */
-const verboseOf = (opts, ...scope) => (cmd, msg) => {
-    if (opts.verbose) {
+    Chalk styles the output only if the terminal supports colors; the
+    "notice" messages pass regardless of the verbose option, as they
+    report environment problems the user has to see  */
+const verboseOf = (opts, ...scope) => (cmd, msg, level) => {
+    if (opts.verbose || level === "notice") {
         const scopePath = [...scope, cmd].map((segment) => chalk.bold(segment)).join(": ");
         process.stderr.write(`specbook: ${scopePath}: ${renderVerbose(msg, chalk.blue)}\n`);
     }
@@ -38,7 +40,7 @@ const writeOutput = async (output, data, cmd, verbose) => {
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`);
+        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`, "debug");
     }
 };
 /*  determine an option default value, overridable via a
@@ -71,7 +73,7 @@ program.name("specbook")
 withVerboseOption(program.command("mcp"))
     .description("run as MCP stdio server")
     .action(async (opts) => {
-    verboseOf(opts)("mcp", "starting MCP server on stdio");
+    verboseOf(opts)("mcp", "starting MCP server on stdio", "debug");
     await serveMcp(verboseOf(opts, "mcp"));
 });
 /*  the init command creates the configured artifact files  */
@@ -97,7 +99,7 @@ withCommonOptions(program.command("lint"))
     if (result.diagnostics.length > 0)
         process.exitCode = 1;
     else
-        verboseOf(opts)("lint", "specification valid");
+        verboseOf(opts)("lint", "specification valid", "debug");
 });
 /*  the export command parses the input once and writes every output  */
 withCommonOptions(program.command("export"))
@@ -143,5 +145,5 @@ catch (err) {
     let msg = err instanceof Error ? err.message : String(err);
     for (let cause = err instanceof Error ? err.cause : undefined; cause instanceof Error; cause = cause.cause)
         msg += `: ${cause.message}`;
-    process.stderr.write(`specbook: ERROR: ${msg}\n`, () => process.exit(1));
+    process.stderr.write(`specbook: ${chalk.red("ERROR:")} ${renderVerbose(msg, chalk.blue)}\n`, () => process.exit(1));
 }

package/dst/specbook-cmd-export.d.ts

@@ -1,9 +1,10 @@
 import type { Spec } from "./specbook-format-spec.js";
 import type { Schema } from "./specbook-format-schema.js";
+import type { Verbose } from "./specbook-verbose.js";
 export declare const formats: readonly ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
 export type ExportFormat = typeof formats[number];
 export declare const parseOutputSpec: (spec: string) => {
     format: ExportFormat;
     output: string;
 };
-export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: (msg: string) => void, config?: Schema) => Promise<Buffer>;
+export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: Verbose, config?: Schema) => Promise<Buffer>;

package/dst/specbook-cmd-init.d.ts

@@ -1,7 +1,8 @@
+import { type Verbose } from "./specbook-verbose.js";
 import { type Schema } from "./specbook-format-schema.js";
 export interface InitOptions {
     config: Schema;
     basedir: string;
-    verbose: (msg: string) => void;
+    verbose: Verbose;
 }
 export declare const initSpecification: (options: InitOptions) => string[];

package/dst/specbook-cmd-lint.d.ts

@@ -1,10 +1,11 @@
+import { type Verbose } from "./specbook-verbose.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
 import { type Spec } from "./specbook-format-spec.js";
 import { type Schema } from "./specbook-format-schema.js";
 export interface LintOptions {
     config: string;
     basedir: string;
-    verbose: (msg: string) => void;
+    verbose: Verbose;
 }
 export interface LintResult {
     specification: Spec;

package/dst/specbook-export-pdf.d.ts

@@ -1,9 +1,12 @@
+import type { LaunchOptions } from "playwright";
 import type { OutlineEntry } from "./specbook-export-html.js";
 import type { ThemeMapping } from "./specbook-theme.js";
+import { type Verbose } from "./specbook-verbose.js";
 type Heading = {
     title: string;
     subtitle?: string;
     logo: string;
 };
-export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], verbose: (msg: string) => void, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
+export declare const requireBrowser: (verbose: Verbose) => Promise<LaunchOptions>;
+export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], verbose: Verbose, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
 export {};

package/dst/specbook-export-pdf.js

@@ -3,7 +3,9 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import fs from "node:fs";
 import { escapeHtml, paperSetup, paperLength, paperSizeDefault } from "./specbook-export-common.js";
+import { literal } from "./specbook-verbose.js";
 /*  extract the per-anchor page numbers from a Chromium-generated PDF,
     which records the internal link targets as named PDF destinations  */
 const anchorPages = async (pdf) => {
@@ -121,6 +123,48 @@ const drawBrandBar = async (doc, accent) => {
         page.drawRectangle({ x: 0, y: 0, width: 5.4,
             height: page.getHeight(), color: rgb(r, g, b) });
 };
+/*  the launch options of the Chromium-class browser printing the PDF,
+    resolved just once per process, as probing a system-installed Google
+    Chrome has to actually launch it and as the export preflight and the
+    renderer both ask for the very same browser  */
+let browserOptions;
+/*  resolve the browser printing the PDF: the downloaded Playwright
+    Chromium is a plain file check, while a system-installed Google
+    Chrome is only detectable by launching it  */
+const resolveBrowser = async (verbose) => {
+    const { chromium } = await import("playwright");
+    let executable = "";
+    try {
+        executable = chromium.executablePath();
+    }
+    catch {
+        /*  Playwright knows no Chromium distribution at all  */
+    }
+    if (executable !== "" && fs.existsSync(executable))
+        return {};
+    try {
+        const chrome = await chromium.launch({ channel: "chrome" });
+        await chrome.close();
+        verbose("Playwright Chromium unavailable -- falling back to the " +
+            "system-installed Google Chrome", "notice");
+        return { channel: "chrome" };
+    }
+    catch {
+        return undefined;
+    }
+};
+/*  ensure a browser printing the PDF is available, so a missing browser
+    fails the export early and with an actionable remedy instead of deep
+    inside the rendering and with a Playwright-internal message  */
+export const requireBrowser = async (verbose) => {
+    browserOptions ??= resolveBrowser(verbose);
+    const options = await browserOptions;
+    if (options === undefined)
+        throw new Error("the PDF export requires a Chromium-class browser, but neither the " +
+            "Playwright Chromium nor a system-installed Google Chrome was found -- run " +
+            `"${literal("npx playwright install chromium")}" once to download the Playwright Chromium`);
+    return options;
+};
 /*  render a self-contained HTML document into a PDF via Playwright,
     re-rendering the HTML with the discovered ToC page numbers  */
 export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css, theme, paper = paperSizeDefault) => {
@@ -128,22 +172,8 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
     /*  the page geometry of the chosen paper size  */
     const setup = paperSetup(paper);
     const margin = setup.margin;
-    /*  launch the Playwright Chromium browser, falling back to a
-        system-installed Google Chrome if the Chromium download is missing  */
-    let browser;
-    try {
-        browser = await chromium.launch();
-    }
-    catch (err) {
-        verbose("Playwright Chromium unavailable -- falling back to installed Google Chrome");
-        try {
-            browser = await chromium.launch({ channel: "chrome" });
-        }
-        catch {
-            /*  report the original, more instructive error  */
-            throw err;
-        }
-    }
+    /*  launch the browser resolved for this process  */
+    const browser = await chromium.launch(await requireBrowser(verbose));
     try {
         const page = await browser.newPage();
         /*  render an HTML document into a paginated PDF  */

package/dst/specbook-mcp.js

@@ -7,7 +7,7 @@ import * as fs from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { SpecBook, renderDiagnostic, formats, parseOutputSpec, describeFormats, describeParts, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec, describeFormats, describeParts, version } from "./specbook-api.js";
 /*  render an error with its cause chain into a tool error result  */
 const errorResult = (err) => {
     let msg = err instanceof Error ? err.message : String(err);
@@ -15,7 +15,7 @@ const errorResult = (err) => {
         msg += `: ${cause.message}`;
     return {
         isError: true,
-        content: [{ type: "text", text: `ERROR: ${msg}` }]
+        content: [{ type: "text", text: `ERROR: ${renderVerbose(msg)}` }]
     };
 };
 /*  serve the SpecBook functionality as "specbook_<cmd>" MCP tools over stdio  */

package/dst/specbook-verbose.d.ts

@@ -1,2 +1,4 @@
+export type VerboseLevel = "debug" | "notice";
+export type Verbose = (msg: string, level?: VerboseLevel) => void;
 export declare const literal: (value: string | number) => string;
 export declare const renderVerbose: (msg: string, style?: (value: string) => string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                                "@rse/specbook",
-    "version":                             "1.0.2",
+    "version":                             "1.0.3",
     "publishConfig":                       { "access": "public" },
     "description":                         "Markdown-based Specification Format (API, CLI and MCP service)",
     "license":                             "Apache-2.0",