@rse/specbook 1.0.2 → 1.0.4

package/dst/specbook-cli.js

@@ -5,26 +5,29 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as fs from "node:fs";
-import { Command } from "commander";
+import * as path from "node:path";
+import { Command, CommanderError } from "commander";
 import chalk from "chalk";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, version } from "./specbook-api.js";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, previewAddr, previewPort, describeFormats, describeParts, parseDescribeFormat, parseDescribePart, parseCompressLevel, version } from "./specbook-api.js";
 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`);
     }
 };
-/*  write a buffer to stdout, awaiting the write callback which only
-    fires once the data has been flushed to the underlying pipe, so a
-    subsequent "process.exit" cannot truncate the output  */
-const writeStdout = (data) => {
+/*  write a buffer to a standard stream, awaiting the write callback
+    which only fires once the data has been flushed to the underlying
+    pipe, so a subsequent "process.exit" cannot truncate the output  */
+const writeStream = (stream, data) => {
     return new Promise((resolve, reject) => {
-        process.stdout.write(data, (err) => {
+        stream.write(data, (err) => {
             if (err)
                 reject(err);
             else
@@ -32,13 +35,15 @@ const writeStdout = (data) => {
         });
     });
 };
+const writeStdout = (data) => writeStream(process.stdout, data);
+const writeStderr = (data) => writeStream(process.stderr, data);
 /*  write a command result to the output file or stdout  */
 const writeOutput = async (output, data, cmd, verbose) => {
     if (output === "-")
         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
@@ -53,17 +58,36 @@ const envDefaultFlag = (name, fallback) => {
 /*  provide the verbose option of all sub-commands  */
 const withVerboseOption = (command) => command
     .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false));
+/*  provide the repeatable schema configuration option, whose files or
+    glob patterns are merged in order (with "std" naming the bundled
+    standard one), and determine its value, where the environment default
+    carries a path-delimiter-separated list of patterns  */
+const withConfigOption = (command, fallback) => command
+    .option("-c, --config <yaml-file>", "YAML schema configuration file or glob pattern " +
+    "(repeatable, merged in order, \"std\" for the bundled standard schema configuration; " +
+    `default: ${fallback})`, (value, previous) => previous.concat(value), new Array());
+const configOf = (opts) => opts.config.length > 0 ? opts.config : envDefault("config")?.split(path.delimiter);
 /*  provide the common options of the specification processing sub-commands,
     for which the YAML schema configuration falls back onto the standard one  */
-const withCommonOptions = (command) => withVerboseOption(command)
-    .option("-c, --config <yaml-file>", "YAML schema configuration file " +
-    "(default: the bundled standard schema configuration)", envDefault("config"))
+const withCommonOptions = (command) => withConfigOption(withVerboseOption(command), "the bundled standard schema configuration")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."));
+/*  the help, version, and usage-error output Commander produces, which
+    is collected instead of written directly, as Commander writes it
+    synchronously and then terminates the process, truncating a piped
+    stream; the settings are established before the sub-commands are
+    created, so they are inherited by all of them  */
+let commanderOut = "";
+let commanderErr = "";
 /*  parse the command line  */
 const program = new Command();
 program.name("specbook")
     .description("Markdown-based Specification Format")
     .version(version)
+    .configureOutput({
+    writeOut: (str) => { commanderOut += str; },
+    writeErr: (str) => { commanderErr += str; }
+})
+    .exitOverride()
     .action(() => {
     program.help();
 });
@@ -71,7 +95,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  */
@@ -79,58 +103,86 @@ withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const created = await specbook.init({ config: opts.config, basedir: opts.basedir });
+    const created = await specbook.init({ config: configOf(opts), basedir: opts.basedir });
     await writeStdout(created.length > 0 ?
         `initialized artifact file(s): ${created.join(", ")}\n` :
         "no artifact files were created\n");
 });
-/*  the lint command reports all diagnostics and fails on any of them  */
+/*  the lint command reports all diagnostics and fails on any error  */
 withCommonOptions(program.command("lint"))
     .description("lint the specification Markdown files below the base directory")
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const result = await specbook.lint({ config: opts.config, basedir: opts.basedir });
+    const result = await specbook.lint({ config: configOf(opts), basedir: opts.basedir });
     for (const diagnostic of result.diagnostics)
         await writeStdout(opts.verbose ?
             renderDiagnosticVerbose(diagnostic, process.stdout.isTTY === true) :
             `${renderDiagnostic(diagnostic)}\n`);
-    if (result.diagnostics.length > 0)
+    if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error"))
         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"))
     .description("export the specification Markdown files below the base directory " +
     "as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
+    .option("-w, --watch", "keep the outputs in sync by re-exporting on every source change", envDefaultFlag("watch", false))
     .option("-o, --output [<format>:]<output-file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
     "from the filename extension unless explicitly prefixed", (value, previous) => previous.concat(value), new Array())
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const outputs = (opts.output.length > 0 ? opts.output : [envDefault("output") ?? "-"])
         .map(parseOutputSpec);
+    /*  a re-export has to land somewhere it can be picked up again,
+        which a one-shot stdout stream cannot provide  */
+    if (opts.watch && outputs.some(({ output }) => output === "-"))
+        throw new Error("the watch mode requires regular output files " +
+            "(\"-\" for stdout is not supported)");
     /*  parse the input once and export each distinct format once  */
     const distinct = Array.from(new Set(outputs.map(({ format }) => format)));
-    const buffers = await specbook.export({ config: opts.config, basedir: opts.basedir,
-        formats: distinct });
-    for (const { format, output } of outputs)
-        await writeOutput(output, buffers[distinct.indexOf(format)], "export", verboseOf(opts));
+    const write = async (buffers) => {
+        for (const { format, output } of outputs)
+            await writeOutput(output, buffers[distinct.indexOf(format)], "export", verboseOf(opts));
+    };
+    if (opts.watch)
+        await specbook.watch({ config: configOf(opts), basedir: opts.basedir,
+            formats: distinct, onExport: write });
+    else
+        await write(await specbook.export({ config: configOf(opts), basedir: opts.basedir,
+            formats: distinct }));
+});
+/*  the preview command serves the HTML export live in the browser  */
+withCommonOptions(program.command("preview"))
+    .description("serve the HTML export of the specification Markdown files below the base " +
+    "directory as a live preview, re-exported and reloaded on every source change")
+    .option("-a, --addr <ip-addr>", "IP address to listen on", envDefault("addr", previewAddr))
+    .option("-p, --port <tcp-port>", "TCP port to listen on", envDefault("port", String(previewPort)))
+    .action(async (opts) => {
+    const port = Number(opts.port);
+    if (!Number.isInteger(port))
+        throw new Error(`invalid TCP port "${opts.port}"`);
+    const specbook = new SpecBook({ verbose: verboseOf(opts) });
+    await specbook.preview({ config: configOf(opts), basedir: opts.basedir, addr: opts.addr, port });
 });
 /*  the describe command also describes the generic SpecBook models and
     formats alone, so its YAML schema configuration stays optional  */
-withVerboseOption(program.command("describe"))
-    .description("describe the SpecBook models and formats as Markdown")
-    .option("-c, --config <yaml-file>", "YAML schema configuration file " +
-    "(default: the bundled standard schema configuration, embedded verbatim)", envDefault("config"))
+withConfigOption(withVerboseOption(program.command("describe"))
+    .description("describe the SpecBook models and formats as Markdown"), "the bundled standard schema configuration, embedded")
     .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir"))
     .option("-e, --embed", "embed the given YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
+    .option("-z, --compress [level]", "compression level of the emitted YAML schema configuration " +
+    "(0: verbatim, 1: re-emitted with 2-space indentation and without comments, " +
+    "2: also without \"refs\" fields, " +
+    "3: also without \"desc\" fields; default and bare flag: 1)", envDefault("compress", "1"))
     .option("-f, --format <format>", `output format (${describeFormats.join(", ")})`, envDefault("format", "md"))
     .option("-p, --part <part>", `document part (${describeParts.join(", ")})`, envDefault("part", "all"))
     .option("-o, --output <markdown-file>", "output file (\"-\" for stdout)", envDefault("output", "-"))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const text = await specbook.describe({ config: opts.config, basedir: opts.basedir,
-        embed: opts.embed, format: parseDescribeFormat(opts.format), part: parseDescribePart(opts.part) });
+    const text = await specbook.describe({ config: configOf(opts), basedir: opts.basedir,
+        embed: opts.embed, compress: parseCompressLevel(opts.compress),
+        format: parseDescribeFormat(opts.format), part: parseDescribePart(opts.part) });
     await writeOutput(opts.output, text, "describe", verboseOf(opts));
 });
 /*  run the command line program  */
@@ -138,10 +190,19 @@ try {
     await program.parseAsync();
 }
 catch (err) {
+    /*  Commander requested the termination (help, version, or a usage
+        error), so flush its own already rendered output and adopt its
+        exit code instead of reporting the control-flow error  */
+    if (err instanceof CommanderError) {
+        await writeStdout(commanderOut);
+        await writeStderr(commanderErr);
+        process.exit(err.exitCode);
+    }
     /*  include the cause chain, as e.g. fetch failures
         carry the underlying error only in the cause  */
     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));
+    await writeStderr(`specbook: ${chalk.red("ERROR:")} ${renderVerbose(msg, chalk.blue)}\n`);
+    process.exit(1);
 }

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

@@ -1,14 +1,20 @@
+import { type Schema } from "./specbook-format-schema.js";
 export declare const describeFormats: readonly ["md", "raw"];
 export declare const describeParts: readonly ["all", "meta", "schema", "spec"];
 export type DescribeFormat = typeof describeFormats[number];
 export type DescribePart = typeof describeParts[number];
 export declare const parseDescribeFormat: (value: string) => DescribeFormat;
 export declare const parseDescribePart: (value: string) => DescribePart;
+export declare const compressLevels: readonly [0, 1, 2, 3];
+export type CompressLevel = typeof compressLevels[number];
+export declare const parseCompressLevel: (value: string | number | boolean) => CompressLevel;
 export declare const describeFormat: (options: {
-    config?: string;
+    config?: string[];
+    schema?: Schema;
     basedir?: string;
     embed?: boolean;
     standard?: boolean;
+    compress?: CompressLevel;
     format?: DescribeFormat;
     part?: DescribePart;
 }) => string;

package/dst/specbook-cmd-describe.js

@@ -5,6 +5,7 @@
 */
 import * as fs from "node:fs";
 import textframe from "textframe";
+import { parseDocument, stringify, visit, isScalar } from "yaml";
 /*  the supported description output formats and document parts  */
 export const describeFormats = ["md", "raw"];
 export const describeParts = ["all", "meta", "schema", "spec"];
@@ -17,20 +18,58 @@ const parseChoice = (choices, kind, value) => {
 };
 export const parseDescribeFormat = (value) => parseChoice(describeFormats, "format", value);
 export const parseDescribePart = (value) => parseChoice(describeParts, "part", value);
+/*  the supported compression levels of the emitted YAML schema
+    configuration: verbatim (0), re-emitted with 2-space indentation and
+    without comments (1), additionally without its "refs" fields (2), and
+    additionally without its "desc" fields of objects and properties (3)  */
+export const compressLevels = [0, 1, 2, 3];
+/*  parse and validate a compression level specification,
+    where a bare flag selects the plain re-emitting  */
+export const parseCompressLevel = (value) => {
+    const level = typeof value === "boolean" ? (value ? 1 : 0) : Number(value);
+    if (!compressLevels.includes(level))
+        throw new Error(`unknown compress level "${value}" ` +
+            `(supported: ${compressLevels.join(", ")})`);
+    return level;
+};
 /*  provide the build-time bundled description of the generic
     SpecBook models and formats  */
 const description = () => fs.readFileSync(new URL("specbook-format.md", import.meta.url), "utf8");
+/*  compress the YAML schema configuration text by re-emitting the parsed
+    document (block scalar styles retained) with 2-space indentation and
+    unwrapped lines, dropping all comments and the fields the level demands  */
+const compressYaml = (yaml, level) => {
+    const doc = parseDocument(yaml);
+    const drop = ["refs", "desc"].slice(0, level - 1);
+    doc.commentBefore = null;
+    doc.comment = null;
+    visit(doc, {
+        Node: (_, node) => {
+            node.commentBefore = null;
+            node.comment = null;
+        },
+        Pair: (_, pair) => isScalar(pair.key) && drop.includes(String(pair.key.value)) ? visit.REMOVE : undefined
+    });
+    return doc.toString({ indent: 2, lineWidth: 0 });
+};
+/*  provide the YAML text of the schema configuration: the verbatim
+    content of its single file, or the merged configuration re-emitted
+    for several files (as no single file carries their merge)  */
+const schemaYaml = (config, schema) => config.length > 1 && schema !== undefined ?
+    stringify(schema, { indent: 2, lineWidth: 0 }) :
+    fs.readFileSync(config[0], "utf8");
 /*  render the reference to (or the embedding of) the YAML schema configuration,
     where the bundled standard one is embedded without its leading comment block  */
-const schemaSection = (config, embed, standard) => {
+const schemaSection = (config, schema, embed, standard, compress) => {
     if (!embed)
-        return textframe(`
-            The **SpecBook SCHEMA Model** is the YAML schema configuration in file:
-            @${config}
-        `);
-    let yaml = fs.readFileSync(config, "utf8");
+        return "The **SpecBook SCHEMA Model** is the YAML schema configuration " +
+            `${config.length > 1 ? "merged in order out of the files" : "in file"}:\n` +
+            config.map((file) => `@${file}\n`).join("");
+    let yaml = schemaYaml(config, schema);
     if (standard)
         yaml = yaml.replace(/^(?:[ \t]*##.*\n)+\s*/, "");
+    if (compress > 0)
+        yaml = compressYaml(yaml, compress);
     return textframe(`
         The **SpecBook SCHEMA Model** is the following YAML schema configuration:
     `) + "\n```yaml\n" + yaml.replace(/\n*$/, "\n") + "```\n\n";
@@ -45,10 +84,14 @@ const specSection = (basedir) => textframe(`
     artifacts of the particular project instantiation, and optionally
     reduced to a single part or to the raw original file content, where
     "standard" marks the configuration as the bundled standard one,
-    which still belongs to the generic description  */
+    which still belongs to the generic description, where "schema" is
+    the configuration loaded out of the "config" files (required for
+    embedding several files), and where "compress" emits the
+    configuration compressed by the given level instead of verbatim  */
 export const describeFormat = (options) => {
     const format = options.format ?? "md";
     const part = options.part ?? "all";
+    const compress = options.compress ?? 1;
     if (!describeFormats.includes(format))
         throw new Error(`unknown describe format "${format}"`);
     if (!describeParts.includes(part))
@@ -63,8 +106,10 @@ export const describeFormat = (options) => {
             return description();
         else if (options.config === undefined)
             throw new Error("format \"raw\" for part \"schema\" requires a YAML schema configuration");
-        else
-            return fs.readFileSync(options.config, "utf8");
+        else {
+            const yaml = schemaYaml(options.config, options.schema);
+            return compress > 0 ? compressYaml(yaml, compress) : yaml;
+        }
     }
     /*  the md format renders a single part standalone  */
     if (part === "meta")
@@ -72,7 +117,7 @@ export const describeFormat = (options) => {
     else if (part === "schema") {
         if (options.config === undefined)
             throw new Error("part \"schema\" requires a YAML schema configuration");
-        return schemaSection(options.config, options.embed === true, options.standard === true);
+        return schemaSection(options.config, options.schema, options.embed === true, options.standard === true, compress);
     }
     else if (part === "spec") {
         if (options.basedir === undefined)
@@ -85,7 +130,7 @@ export const describeFormat = (options) => {
         placed under their own section  */
     const sections = [description()];
     const schema = options.config !== undefined ?
-        schemaSection(options.config, options.embed === true, options.standard === true) : undefined;
+        schemaSection(options.config, options.schema, options.embed === true, options.standard === true, compress) : undefined;
     if (schema !== undefined || options.basedir !== undefined) {
         sections.push("SpecBook Project Instantiation\n" +
             "==============================\n");

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

@@ -1,9 +1,11 @@
 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 watchSpecification: (run: () => Promise<string[]>, verbose: Verbose) => Promise<void>;
+export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: Verbose, config?: Schema, realtime?: boolean) => Promise<Buffer>;

package/dst/specbook-cmd-export.js

@@ -3,6 +3,7 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import { watch } from "chokidar";
 import { minify } from "@swc/html";
 import { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet, charsetCodepoints } from "./specbook-export-common.js";
 import { themeColors, themeStylesheet, themeMapping } from "./specbook-theme.js";
@@ -46,8 +47,50 @@ export const parseOutputSpec = (spec) => {
     throw new Error(`unable to infer export format from output "${spec}" ` +
         "(use an explicit \"<format>:<filename>\" specification)");
 };
-/*  export a specification into the requested format  */
-export const exportSpecification = async (specification, format, verbose, config) => {
+/*  the quiet period the observed files have to stay silent for before a
+    burst of changes is coalesced into a single re-export  */
+const watchDelay = 1000;
+/*  keep a specification export in sync with its sources, where "run"
+    performs one export and returns the files to observe: the initial
+    export is performed up-front and every observed change triggers a
+    re-export once the sources fell silent again. The observed set is
+    re-synchronized after every run, as an edit can add or drop an
+    embedded asset. The returned promise settles once the initial export
+    is done, while the active watcher keeps the process alive afterwards  */
+export const watchSpecification = async (run, verbose) => {
+    /*  perform the regular export before entering the observe loop  */
+    let observed = await run();
+    const watcher = watch(observed, { ignoreInitial: true });
+    verbose(`observing ${literal(observed.length)} specification file(s) for changes`);
+    /*  perform a re-export and re-synchronize the observed files  */
+    const cycle = async () => {
+        const files = await run();
+        watcher.unwatch(observed.filter((file) => !files.includes(file)));
+        watcher.add(files.filter((file) => !observed.includes(file)));
+        observed = files;
+    };
+    /*  restart the quiet period on every change, so a burst collapses
+        into a single re-export, and chain the runs onto each other, so a
+        change arriving during a run cannot start a concurrent one (the
+        chained catch keeps an unexpected failure from breaking the chain
+        and hence silently ending the observe loop)  */
+    let chain = Promise.resolve();
+    let timer;
+    watcher.on("all", () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            chain = chain.then(cycle).catch((err) => {
+                verbose("re-export failed: " +
+                    (err instanceof Error ? err.message : String(err)), "notice");
+            });
+        }, watchDelay);
+    });
+};
+/*  export a specification into the requested format, where "realtime"
+    injects the client-side script of the live preview into the HTML  */
+export const exportSpecification = async (specification, format, verbose, config, realtime = false) => {
     if (!formats.includes(format))
         throw new Error(`unknown export format "${format}"`);
     verbose(`exporting specification as "${literal(format)}"`);
@@ -71,7 +114,7 @@ export const exportSpecification = async (specification, format, verbose, config
     const css = themeStylesheet(colors) + await subsetStylesheet(charset) + paperStylesheet(paper);
     if (format === "html") {
         /*  compress the rendered HTML (whitespace, comments, and inline CSS/JS)  */
-        const html = await renderHtml(specification, config, undefined, css);
+        const html = await renderHtml(specification, config, undefined, css, realtime);
         const minified = await minify(Buffer.from(html, "utf8"), {
             collapseWhitespaces: "smart",
             removeComments: true,

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,14 +1,16 @@
+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;
+    config: string[];
     basedir: string;
-    verbose: (msg: string) => void;
+    verbose: Verbose;
 }
 export interface LintResult {
     specification: Spec;
     diagnostics: Diagnostic[];
     config?: Schema;
+    files: string[];
 }
 export declare const lint: (options: LintOptions) => LintResult;

package/dst/specbook-cmd-lint.js

@@ -24,8 +24,9 @@ const schemaFiles = (config) => {
     against the configuration  */
 export const lint = (options) => {
     const diagnostics = new Array();
-    /*  load the mandatory YAML schema configuration  */
-    options.verbose(`loading schema configuration "${literal(options.config)}"`);
+    /*  load the mandatory YAML schema configuration, merged out of its files  */
+    options.verbose("loading schema configuration " +
+        options.config.map((file) => `"${literal(file)}"`).join(", "));
     const loaded = loadConfig(options.config);
     diagnostics.push(...loaded.diagnostics);
     const config = loaded.config;
@@ -34,15 +35,17 @@ export const lint = (options) => {
         its artifacts are optional  */
     const files = config !== undefined ? schemaFiles(config) : new Map();
     if (config !== undefined && files.size === 0)
-        diagnostics.push({ file: options.config, line: 1, column: 1,
+        diagnostics.push({ file: options.config[0], line: 1, column: 1, severity: "error",
             message: "no artifact files configured" });
     const sources = new Array();
     const present = new Set();
+    const watched = new Array();
     for (const [name, optional] of files) {
         const file = path.join(options.basedir, name);
+        watched.push(path.resolve(file));
         if (!fs.existsSync(file)) {
             if (!optional)
-                diagnostics.push({ file, line: 1, column: 1,
+                diagnostics.push({ file, line: 1, column: 1, severity: "error",
                     message: "missing artifact file" });
             continue;
         }
@@ -51,7 +54,7 @@ export const lint = (options) => {
             present.add(name);
         }
         catch (err) {
-            diagnostics.push({ file, line: 1, column: 1,
+            diagnostics.push({ file, line: 1, column: 1, severity: "error",
                 message: `unreadable file: ${err instanceof Error ? err.message : String(err)}` });
         }
     }
@@ -60,6 +63,7 @@ export const lint = (options) => {
         `below "${literal(options.basedir)}"`);
     const result = parseSpecification(sources, config);
     diagnostics.push(...result.diagnostics);
+    watched.push(...result.assets);
     /*  report the non-optional artifacts absent from the specification,
         against their loaded artifact file (an absent or unreadable file
         is already reported above) or else against the configuration  */
@@ -75,11 +79,11 @@ export const lint = (options) => {
             if (schema.optional === true || found.has(schema)
                 || (schema.file !== undefined && !present.has(schema.file)))
                 continue;
-            const file = schema.file !== undefined ? path.join(options.basedir, schema.file) : options.config;
+            const file = schema.file !== undefined ? path.join(options.basedir, schema.file) : options.config[0];
             const paren = schema.id !== undefined ? ` (${schema.id})` : "";
-            diagnostics.push({ file, line: 1, column: 1,
+            diagnostics.push({ file, line: 1, column: 1, severity: "error",
                 message: `missing artifact "${schema.kind}: ${schema.name ?? ""}${paren}"` });
         }
     }
-    return { specification: result.specification, diagnostics, config };
+    return { specification: result.specification, diagnostics, config, files: watched };
 };

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

@@ -0,0 +1,12 @@
+import { type Verbose } from "./specbook-verbose.js";
+export declare const previewAddr = "127.0.0.1";
+export declare const previewPort = 12345;
+export interface PreviewOptions {
+    addr: string;
+    port: number;
+    verbose: Verbose;
+}
+export interface PreviewServer {
+    update: (html: Buffer) => void;
+}
+export declare const servePreview: (options: PreviewOptions) => Promise<PreviewServer>;

package/dst/specbook-cmd-preview.js

@@ -0,0 +1,57 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import Fastify from "fastify";
+import fastifyWebsocket from "@fastify/websocket";
+import { literal } from "./specbook-verbose.js";
+/*  the default listening address and port of the preview server  */
+export const previewAddr = "127.0.0.1";
+export const previewPort = 12345;
+/*  serve the live HTML preview: a plain GET on "/" answers with the
+    most recent HTML export (or with 503 before the first successful
+    one), while a WebSocket upgrade on "/" subscribes the client to the
+    "RELOAD" command every fresh export broadcasts  */
+export const servePreview = async (options) => {
+    let html;
+    const clients = new Set();
+    const fastify = Fastify();
+    await fastify.register(fastifyWebsocket);
+    fastify.route({
+        method: "GET",
+        url: "/",
+        handler: (_request, reply) => {
+            if (html === undefined)
+                return reply.code(503).type("text/plain; charset=utf-8")
+                    .send("no specification export available yet\n");
+            return reply.type("text/html; charset=utf-8").send(html);
+        },
+        wsHandler: (socket, request) => {
+            /*  identify the client by its remote address and port  */
+            const addr = request.socket.remoteAddress ?? "unknown";
+            const client = `${addr.includes(":") ? `[${addr}]` : addr}:${request.socket.remotePort ?? 0}`;
+            options.verbose(`client ${literal(client)} connected`, "notice");
+            clients.add(socket);
+            socket.on("close", () => {
+                clients.delete(socket);
+                options.verbose(`client ${literal(client)} disconnected`, "notice");
+            });
+        }
+    });
+    await fastify.listen({ host: options.addr, port: options.port });
+    const url = `http://${options.addr}:${options.port}/`;
+    options.verbose(`listening on ${literal(url)}`, "notice");
+    return {
+        update: (buffer) => {
+            /*  the first export turns the 503 answers into the document  */
+            if (html === undefined)
+                options.verbose(`serving ${literal(url)}`, "notice");
+            html = buffer;
+            options.verbose(`notifying ${literal(clients.size)} preview client(s)`);
+            for (const client of clients)
+                if (client.readyState === client.OPEN)
+                    client.send("RELOAD");
+        }
+    };
+};

package/dst/specbook-config.d.ts

@@ -1,6 +1,6 @@
 import { Schema } from "./specbook-format-schema.js";
 import { type Diagnostic } from "./specbook-diagnostic.js";
-export declare const loadConfig: (file: string) => {
+export declare const loadConfig: (files: string[]) => {
     config?: Schema;
     diagnostics: Diagnostic[];
 };