@rse/specbook 0.9.5 → 0.9.7

package/dst/specbook-api.js

@@ -4,38 +4,42 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 import { loadConfig } from "./specbook-config.js";
 import { renderDiagnostic, renderDiagnosticVerbose } from "./specbook-diagnostic.js";
 import { initSpecification } from "./specbook-cmd-init.js";
 import { lint } from "./specbook-cmd-lint.js";
 import { exportSpecification, parseOutputSpec, formats } from "./specbook-cmd-export.js";
-import { describeConfiguration } from "./specbook-cmd-describe.js";
-import { importSpecification } from "./specbook-cmd-import.js";
-import { editSpecification } from "./specbook-cmd-edit.js";
+import { describeFormat } from "./specbook-cmd-describe.js";
+import { literal, renderVerbose } from "./specbook-verbose.js";
 /*  re-export the central types for API consumers  */
+export { literal, renderVerbose };
 export { formats, parseOutputSpec };
 export { renderDiagnostic, renderDiagnosticVerbose };
-/*  the own version, taken from the package manifest, which resides one
+/*  our own version, taken from the package manifest, which resides one
     level above both the source and the compiled module directory  */
-export const version = (() => {
-    const manifest = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
-    return JSON.parse(fs.readFileSync(manifest, "utf8")).version;
-})();
+export const version = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 /*  the SpecBook API  */
 export class SpecBook {
     verbose;
     constructor(options = {}) {
         this.verbose = options.verbose ?? (() => { });
     }
-    /*  load a mandatory YAML schema configuration, failing on any problem  */
-    requireConfig(file) {
+    /*  bind the verbose sink to a particular command  */
+    verboseOf(cmd) {
+        return (msg) => this.verbose(cmd, msg);
+    }
+    /*  require the file of the mandatory YAML schema configuration  */
+    requireConfigFile(file) {
         if (file === undefined)
             throw new Error("YAML schema configuration required");
-        this.verbose(`loading configuration "${file}"`);
+        return file;
+    }
+    /*  load a mandatory YAML schema configuration, failing on any problem  */
+    requireConfig(file, verbose) {
+        file = this.requireConfigFile(file);
+        verbose(`loading configuration "${literal(file)}"`);
         const { config, diagnostics } = loadConfig(file);
-        if (config === null)
+        if (config === undefined)
             throw new Error("invalid configuration:\n" +
                 diagnostics.map(renderDiagnostic).join("\n"));
         return config;
@@ -43,44 +47,44 @@ export class SpecBook {
     /*  initialize the configured specification artifact files
         below the base directory  */
     async init(options) {
-        return initSpecification({ ...options,
-            config: this.requireConfig(options.config), verbose: this.verbose });
+        const verbose = this.verboseOf("init");
+        return initSpecification({ config: this.requireConfig(options.config, verbose),
+            basedir: options.basedir ?? ".", verbose });
     }
     /*  lint the specification Markdown files below the base directory  */
     async lint(options) {
-        return lint({ config: options.config, basedir: options.basedir ?? ".", verbose: this.verbose });
+        return lint({ config: this.requireConfigFile(options.config),
+            basedir: options.basedir ?? ".", verbose: this.verboseOf("lint") });
     }
     /*  export the specification Markdown files below the base directory
         as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown,
         parsing the input just once and returning one buffer per
-        requested format (best-effort: diagnostics do not prevent the
-        export, as validation is the concern of lint)  */
+        requested format (strict: any diagnostic prevents the export,
+        as a partial or invalid specification must never be emitted)  */
     async export(options) {
-        const result = lint({ config: options.config, basedir: options.basedir ?? ".", verbose: this.verbose });
-        for (const diagnostic of result.diagnostics)
-            this.verbose(`diagnostic: ${renderDiagnostic(diagnostic)}`);
-        if (result.specification.artifacts.length === 0)
-            throw new Error("unexportable specification:\n" +
+        const verbose = this.verboseOf("export");
+        const result = lint({ config: this.requireConfigFile(options.config),
+            basedir: options.basedir ?? ".", verbose });
+        if (result.diagnostics.length > 0)
+            throw new Error("invalid specification:\n" +
                 result.diagnostics.map(renderDiagnostic).join("\n"));
+        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"])
-            buffers.push(await exportSpecification(result.specification, format, this.verbose, result.config));
+            buffers.push(await exportSpecification(result.specification, format, verbose, result.config));
         return buffers;
     }
-    /*  describe the configured specification format as Markdown  */
+    /*  describe the generic SpecBook models and formats as Markdown,
+        optionally pointing to the artifacts of the particular project,
+        whose YAML schema configuration is validated if given  */
     async describe(options) {
-        return describeConfiguration(this.requireConfig(options.config));
-    }
-    /*  import foreign sources into the specification artifact files
-        below the base directory  */
-    async import(options) {
-        return importSpecification({ ...options,
-            config: this.requireConfig(options.config), verbose: this.verbose });
-    }
-    /*  apply an edit request to the specification artifact files
-        below the base directory  */
-    async edit(options) {
-        return editSpecification({ ...options,
-            config: this.requireConfig(options.config), verbose: this.verbose });
+        const verbose = this.verboseOf("describe");
+        if (options.config !== undefined)
+            this.requireConfig(options.config, verbose);
+        else if (options.embed === true)
+            throw new Error("YAML schema configuration required for embedding");
+        verbose("describing the SpecBook models and formats");
+        return describeFormat(options);
     }
 }

package/dst/specbook-cli.js

@@ -6,13 +6,18 @@
 */
 import * as fs from "node:fs";
 import { Command } from "commander";
-import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, parseOutputSpec, version } from "./specbook-api.js";
+import chalk from "chalk";
+import { SpecBook, renderDiagnostic, renderDiagnosticVerbose, renderVerbose, literal, parseOutputSpec, 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  */
-const verboseOf = (opts) => (msg) => {
-    if (opts.verbose)
-        process.stderr.write(`specbook: ${msg}\n`);
+/*  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) {
+        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
@@ -28,12 +33,12 @@ const writeStdout = (data) => {
     });
 };
 /*  write a command result to the output file or stdout  */
-const writeOutput = async (output, data, verbose) => {
+const writeOutput = async (output, data, cmd, verbose) => {
     if (output === "-")
         await writeStdout(data);
     else {
         await fs.promises.writeFile(output, data);
-        verbose(`wrote "${output}" (${Buffer.byteLength(data)} bytes)`);
+        verbose(cmd, `wrote "${literal(output)}" (${literal(Buffer.byteLength(data))} bytes)`);
     }
 };
 /*  determine an option default value, overridable via a
@@ -45,10 +50,14 @@ const envDefaultFlag = (name, fallback) => {
     const value = process.env[`SPECBOOK_${name.toUpperCase().replace(/-/g, "_")}`];
     return value !== undefined ? !(/^(?:|0|false|no|off)$/i).test(value) : fallback;
 };
-/*  provide the common options of all sub-commands  */
-const withCommonOptions = (command) => command
-    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
-    .option("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"));
+/*  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 common options of the specification processing sub-commands,
+    for which the YAML schema configuration is mandatory  */
+const withCommonOptions = (command) => withVerboseOption(command)
+    .requiredOption("-c, --config <yaml-file>", "YAML schema configuration file", envDefault("config"))
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."));
 /*  parse the command line  */
 const program = new Command();
 program.name("specbook")
@@ -57,16 +66,16 @@ program.name("specbook")
     .action(() => {
     program.help();
 });
-program.command("mcp")
+/*  the mcp command runs all other commands as MCP tools over stdio  */
+withVerboseOption(program.command("mcp"))
     .description("run as MCP stdio server")
-    .option("-v, --verbose", "print verbose processing information to stderr", envDefaultFlag("verbose", false))
     .action(async (opts) => {
-    verboseOf(opts)("starting MCP server on stdio");
-    await serveMcp(verboseOf(opts));
+    verboseOf(opts)("mcp", "starting MCP server on stdio");
+    await serveMcp(verboseOf(opts, "mcp"));
 });
+/*  the init command creates the configured artifact files  */
 withCommonOptions(program.command("init"))
     .description("initialize the configured specification artifact files below the base directory")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const created = await specbook.init({ config: opts.config, basedir: opts.basedir });
@@ -74,9 +83,9 @@ withCommonOptions(program.command("init"))
         `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  */
 withCommonOptions(program.command("lint"))
     .description("lint the specification Markdown files below the base directory")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .action(async (opts) => {
     const specbook = new SpecBook({ verbose: verboseOf(opts) });
     const result = await specbook.lint({ config: opts.config, basedir: opts.basedir });
@@ -87,61 +96,39 @@ withCommonOptions(program.command("lint"))
     if (result.diagnostics.length > 0)
         process.exitCode = 1;
     else
-        verboseOf(opts)("specification valid");
+        verboseOf(opts)("lint", "specification valid");
 });
+/*  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("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
     .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), [])
+    "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((spec) => parseOutputSpec(spec));
+        .map(parseOutputSpec);
     /*  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)], verboseOf(opts));
+        await writeOutput(output, buffers[distinct.indexOf(format)], "export", verboseOf(opts));
 });
-withCommonOptions(program.command("describe"))
-    .description("describe the configured specification format as Markdown")
+/*  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", envDefault("config"))
+    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir"))
+    .option("-e, --embed", "embed the YAML schema configuration instead of just referencing it", envDefaultFlag("embed", false))
     .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 });
-    await writeOutput(opts.output, text, verboseOf(opts));
-});
-withCommonOptions(program.command("import"))
-    .description("import foreign sources into the specification artifact files below the base directory")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
-    .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
-    .option("--model <model>", "AI model", envDefault("model"))
-    .argument("<input-files...>", "foreign source files to import")
-    .action(async (inputs, opts) => {
-    const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const written = await specbook.import({ config: opts.config, basedir: opts.basedir,
-        inputs, provider: opts.provider, model: opts.model });
-    await writeStdout(written.length > 0 ?
-        `imported into artifact file(s): ${written.join(", ")}\n` :
-        "no artifact files were changed\n");
-});
-withCommonOptions(program.command("edit"))
-    .description("apply a free-text edit request to the specification artifact files below the base directory")
-    .option("-b, --basedir <directory>", "base directory of the specification Markdown files", envDefault("basedir", "."))
-    .option("--provider <provider>", "AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")", envDefault("provider"))
-    .option("--model <model>", "AI model", envDefault("model"))
-    .argument("<query>", "free-text edit request")
-    .action(async (query, opts) => {
-    const specbook = new SpecBook({ verbose: verboseOf(opts) });
-    const written = await specbook.edit({ config: opts.config, basedir: opts.basedir,
-        query, provider: opts.provider, model: opts.model });
-    await writeStdout(written.length > 0 ?
-        `edited artifact file(s): ${written.join(", ")}\n` :
-        "no artifact files were changed\n");
+    const text = await specbook.describe({ config: opts.config, basedir: opts.basedir, embed: opts.embed });
+    await writeOutput(opts.output, text, "describe", verboseOf(opts));
 });
+/*  run the command line program  */
 try {
     await program.parseAsync();
 }

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

@@ -1,2 +1,5 @@
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
-export declare const describeConfiguration: (config: SchemaSpecification) => string;
+export declare const describeFormat: (options: {
+    config?: string;
+    basedir?: string;
+    embed?: boolean;
+}) => string;

package/dst/specbook-cmd-describe.js

@@ -3,97 +3,36 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import * as fs from "node:fs";
 import textframe from "textframe";
-/*  collapse folded YAML prose into a single line  */
-const collapse = (text) => (text ?? "").replace(/\s+/g, " ").trim();
-/*  the static description of the generic Markdown syntax  */
-const syntax = textframe `
-    #   SpecBook Specification Format
-
-    A specification consists of Markdown *artifact* files, each carrying a
-    frontmatter with \`Created:\` and \`Modified:\` timestamps (format
-    \`yyyy-LL-dd HH:mm\`) and a tree of *objects*. Every object has a *kind*,
-    a *name*, a unique anchor *id*, optional *properties* (key/value pairs),
-    an optional *description* statement with an optional rationale, and
-    optional *child* objects. Two concrete syntaxes exist:
-
-    ##  Complex Format (used on levels 1-3)
-
-    \`\`\`
-    #   <kind>: <name> (<id>)
-
-    -   <key>: <value>
-    -   [...]
-
-    <statement>, BECAUSE <rationale>.
-    \`\`\`
-
-    Level 1 (\`#\`) carries the artifact id in parentheses. Levels 2 (\`##\`)
-    and 3 (\`###\`) instead carry an HTML anchor \`<a id="<id>"></a>\` after
-    the name, where the id uses the artifact id as its prefix.
-
-    ##  Concise Format (used on level 4 and deeper)
-
-    \`\`\`
-    -   <kind>: <name>; <key>: <value>; [...]; <statement>, BECAUSE <rationale>.
-    \`\`\`
-
-    Child objects nest as indented list items below their parent item.
-
-    ##  Primary Marker
-
-    In both formats a literal \`(*)\` directly after the \`<name>\` marks the
-    object as *primary* (e.g. the primary attribute of an entity). It is
-    distinct from an id given as \`(<id>)\` and both may be combined.
-
-    ##  Configured Artifacts
-
-    The following artifacts, object kinds, and properties are configured.
-    Object kinds and property names are *case-sensitive* and must be
-    written exactly as configured. Properties marked \`required\` must be
-    present, and property values must match their given constraint (if
-    any, else any value is allowed): \`/xxx/\` requires a match of the
-    regular expression, \`[[xxx]]\` requires exactly one Wiki-style link
-    reference resolving into the (usually wildcard) reference pattern,
-    \`enum(xxx,yyy)\` requires one of the listed members, \`tags(xxx,yyy)\`
-    requires a comma-separated set of the listed members (each at most
-    once), and \`list(xxx[, ...])\` requires a comma-separated list of
-    items, each matching one of the alternative constraints.
-`;
-/*  describe a single configured property  */
-const describeProperty = (prop, indent) => {
-    let line = `${indent}-   property \`${prop.name}\` (${prop.optional === true ? "optional" : "required"}`;
-    if (prop.value !== undefined)
-        line += `, constraint \`${prop.value}\``;
-    line += `): ${collapse(prop.desc)}`;
-    return line;
-};
-/*  describe a single configured object kind (and recursively its childs)  */
-const describeObject = (object, level, indent) => {
-    const lines = new Array();
-    lines.push(`${indent}-   object kind \`${object.kind}\` on level ${level}` +
-        `${object.optional === true ? " (optional)" : ""}: ${collapse(object.desc)}`);
-    for (const prop of object.props ?? [])
-        lines.push(describeProperty(prop, `${indent}    `));
-    for (const child of object.childs ?? [])
-        lines.push(describeObject(child, level + 1, `${indent}    `));
-    return lines.join("\n");
-};
-/*  describe the configured specification format as Markdown  */
-export const describeConfiguration = (config) => {
-    const sections = new Array();
-    for (const artifact of config) {
-        const lines = new Array();
-        lines.push(`### ${artifact.kind}: ${artifact.name ?? ""} (${artifact.kind}-${artifact.id ?? ""})`);
-        lines.push("");
-        if (artifact.file !== undefined)
-            lines.push(`-   file: \`${artifact.file}\``);
-        lines.push(`-   description: ${collapse(artifact.desc)}`);
-        for (const prop of artifact.props ?? [])
-            lines.push(describeProperty(prop, ""));
-        for (const child of artifact.childs ?? [])
-            lines.push(describeObject(child, 2, ""));
-        sections.push(lines.join("\n"));
+/*  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");
+/*  describe the generic SpecBook models and formats as Markdown,
+    optionally extended by the references to (or the embeddings of) the
+    artifacts of the particular project instantiation  */
+export const describeFormat = (options) => {
+    const sections = [description()];
+    if (options.config !== undefined || options.basedir !== undefined) {
+        sections.push("SpecBook Project Instantiation\n" +
+            "==============================\n");
+        if (options.config !== undefined && options.embed === true)
+            sections.push(textframe(`
+                The **SpecBook SCHEMA Model** of this particular project is the following
+                YAML schema configuration of the file \`${options.config}\`:
+            `) + "\n```yaml\n" +
+                fs.readFileSync(options.config, "utf8").replace(/\n*$/, "\n") +
+                "```\n");
+        else if (options.config !== undefined)
+            sections.push(textframe(`
+                The **SpecBook SCHEMA Model** of this particular project is the YAML
+                schema configuration in the file \`${options.config}\`.
+            `));
+        if (options.basedir !== undefined)
+            sections.push(textframe(`
+                The **SpecBook SPEC Model** of this particular project is the set of
+                specification Markdown files in the directory \`${options.basedir}\`.
+            `));
     }
-    return `${syntax}\n${sections.join("\n\n")}\n`;
+    return sections.join("\n");
 };

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

@@ -1,9 +1,9 @@
-import type { Specification } from "./specbook-struct-spec.js";
-import type { SchemaSpecification } from "./specbook-struct-schema.js";
+import type { Spec } from "./specbook-format-spec.js";
+import type { Schema } from "./specbook-format-schema.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: Specification, format: ExportFormat, verbose: (msg: string) => void, config?: SchemaSpecification) => Promise<Buffer>;
+export declare const exportSpecification: (specification: Spec, format: ExportFormat, verbose: (msg: string) => void, config?: Schema) => Promise<Buffer>;

package/dst/specbook-cmd-export.js

@@ -4,35 +4,39 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { minify } from "@swc/html";
-import { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet } from "./specbook-export-common.js";
+import { documentTitle, documentLogo, documentCharset, documentThemeTone, subsetStylesheet, documentPaperSize, paperStylesheet, charsetCodepoints } from "./specbook-export-common.js";
 import { themeColors, themeStylesheet, themeMapping } from "./specbook-theme.js";
 import { renderAst } from "./specbook-export-ast.js";
 import { renderMarkdown } from "./specbook-export-md.js";
 import { renderHtml, htmlOutline } from "./specbook-export-html.js";
 import { htmlToPdf } from "./specbook-export-pdf.js";
+import { literal } from "./specbook-verbose.js";
 /*  the supported export formats  */
 export const formats = ["json", "json5", "yaml", "toon", "html", "pdf", "md"];
-/*  the filename extensions mapping onto the export formats  */
-const extensions = {
-    json: "json",
-    json5: "json5",
-    yaml: "yaml", yml: "yaml",
-    toon: "toon",
-    html: "html", htm: "html",
-    pdf: "pdf",
-    md: "md", markdown: "md"
-};
+/*  the format names and filename extensions mapping onto the export formats  */
+const extensions = new Map([
+    ["json", "json"],
+    ["json5", "json5"],
+    ["yaml", "yaml"], ["yml", "yaml"],
+    ["toon", "toon"],
+    ["html", "html"], ["htm", "html"],
+    ["pdf", "pdf"],
+    ["md", "md"], ["markdown", "md"]
+]);
 /*  parse an output specification "[<format>:]<filename>", inferring the
     format from the filename extension when not explicitly given
     (plain "-" for stdout defaults to JSON)  */
 export const parseOutputSpec = (spec) => {
     const prefixed = spec.match(/^([a-zA-Z0-9]+):(.+)$/);
-    if (prefixed !== null && formats.includes(prefixed[1]))
-        return { format: prefixed[1], output: prefixed[2] };
+    if (prefixed !== null) {
+        const explicit = extensions.get(prefixed[1].toLowerCase());
+        if (explicit !== undefined)
+            return { format: explicit, output: prefixed[2] };
+    }
     if (spec === "-")
         return { format: "json", output: spec };
     const ext = spec.match(/\.([a-zA-Z0-9]+)$/);
-    const format = ext !== null ? extensions[ext[1].toLowerCase()] : undefined;
+    const format = ext !== null ? extensions.get(ext[1].toLowerCase()) : undefined;
     if (format !== undefined)
         return { format, output: spec };
     throw new Error(`unable to infer export format from output "${spec}" ` +
@@ -42,20 +46,20 @@ export const parseOutputSpec = (spec) => {
 export const exportSpecification = async (specification, format, verbose, config) => {
     if (!formats.includes(format))
         throw new Error(`unknown export format "${format}"`);
-    verbose(`exporting specification as "${format}"`);
+    verbose(`exporting specification as "${literal(format)}"`);
     if (format === "json" || format === "json5" || format === "yaml" || format === "toon")
         return renderAst(specification, format, config);
     else if (format === "md")
-        return Buffer.from(await renderMarkdown(specification, config), "utf8");
+        return Buffer.from(renderMarkdown(specification, config), "utf8");
     /*  the HTML-based formats share the stylesheet, with the embedded
         fonts subsetted to the CHARSET of the specification (if any)  */
     const charset = documentCharset(specification);
-    if (charset !== undefined)
-        verbose(`subsetting embedded fonts to charset "${charset}"`);
+    if (charset !== undefined && charsetCodepoints(charset) !== undefined)
+        verbose(`subsetting embedded fonts to charset "${literal(charset)}"`);
     /*  the theme tone (THEME-TONE) drives the layer-1 color spread
         variables and the PDF decoration colors  */
     const tone = documentThemeTone(specification) ?? "#336699";
-    verbose(`generating theme color spreads (tone "${tone}")`);
+    verbose(`generating theme color spreads (tone "${literal(tone)}")`);
     const colors = themeColors(tone);
     /*  the paper size (PAPER-SIZE) drives the PDF page setup and the
         print-time height constraint of the diagrams  */

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

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

package/dst/specbook-cmd-init.js

@@ -5,35 +5,58 @@
 */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { timestamp } from "./specbook-llm.js";
+import { literal } from "./specbook-verbose.js";
+/*  the current time in the frontmatter timestamp format  */
+const timestamp = () => {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+        `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+};
 /*  initialize the configured specification artifact files below the
-    base directory with their frontmatter and artifact heading  */
+    base directory with their frontmatter and artifact headings, where
+    all artifacts configured onto the same file reside in it side by
+    side, following each other on level 1  */
 export const initSpecification = (options) => {
-    const basedir = options.basedir ?? ".";
-    fs.mkdirSync(basedir, { recursive: true });
+    fs.mkdirSync(options.basedir, { recursive: true });
     const now = timestamp();
     const created = new Array();
+    /*  group the configured artifacts by their file, preserving the
+        schema order both of the files and of the artifacts within  */
+    const groups = new Map();
     for (const artifact of options.config) {
         if (artifact.file === undefined)
             continue;
-        const file = path.join(basedir, artifact.file);
-        if (fs.existsSync(file)) {
-            options.verbose(`skipping existing artifact file "${artifact.file}"`);
+        const group = groups.get(artifact.file);
+        if (group === undefined)
+            groups.set(artifact.file, [artifact]);
+        else
+            group.push(artifact);
+    }
+    /*  create each absent artifact file with its frontmatter and
+        the level 1 headings of its artifacts  */
+    for (const [file, artifacts] of groups) {
+        const target = path.join(options.basedir, file);
+        if (fs.existsSync(target)) {
+            options.verbose(`skipping existing artifact file "${literal(file)}"`);
             continue;
         }
-        const name = artifact.name ?? "";
-        const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
+        const headings = artifacts.map((artifact) => {
+            const name = artifact.name ?? "";
+            const paren = artifact.id !== undefined ? ` (${artifact.id})` : "";
+            return `#   ${artifact.kind}: ${name}${paren}\n\n`;
+        }).join("");
         const text = "---\n" +
             `Created:  ${now}\n` +
             `Modified: ${now}\n` +
             "---\n" +
             "\n" +
-            `#   ${artifact.kind}: ${name}${paren}\n` +
-            "\n";
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, text, "utf8");
-        options.verbose(`created artifact file "${artifact.file}"`);
-        created.push(artifact.file);
+            headings;
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, text, "utf8");
+        options.verbose(`created artifact file "${literal(file)}" ` +
+            `with ${literal(artifacts.length)} artifact(s)`);
+        created.push(file);
     }
     return created;
 };