@rse/specbook 1.0.3 → 1.1.0

package/dst/specbook-cli.js

@@ -5,9 +5,10 @@
 **  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
@@ -21,12 +22,12 @@ const verboseOf = (opts, ...scope) => (cmd, msg, level) => {
         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
@@ -34,6 +35,8 @@ 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 === "-")
@@ -55,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();
 });
@@ -81,22 +103,22 @@ 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", "debug");
@@ -105,34 +127,62 @@ withCommonOptions(program.command("lint"))
 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  */
@@ -140,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: ${chalk.red("ERROR:")} ${renderVerbose(msg, chalk.blue)}\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

@@ -7,4 +7,5 @@ export declare const parseOutputSpec: (spec: string) => {
     format: ExportFormat;
     output: string;
 };
-export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: Verbose, 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-lint.d.ts

@@ -3,7 +3,7 @@ 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: Verbose;
 }
@@ -11,5 +11,6 @@ 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[];
 };