@rse/specbook 0.9.2

package/dst/specbook-export-pdf.js

@@ -0,0 +1,198 @@
+/*
+**  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 { escapeHtml, paperSetup, paperLength, paperSizeDefault } from "./specbook-export-common.js";
+/*  extract the per-anchor page numbers from a Chromium-generated PDF,
+    which records the internal link targets as named PDF destinations  */
+const anchorPages = async (pdf) => {
+    const { PDFDocument, PDFName, PDFDict, PDFArray, PDFRef } = await import("pdf-lib");
+    const doc = await PDFDocument.load(pdf);
+    const indexes = new Map();
+    doc.getPages().forEach((page, index) => indexes.set(page.ref.toString(), index + 1));
+    const pages = new Map();
+    const dests = doc.catalog.lookupMaybe(PDFName.of("Dests"), PDFDict);
+    if (dests !== undefined) {
+        for (const [name] of dests.entries()) {
+            const dest = dests.lookup(name);
+            const target = dest instanceof PDFArray ? dest.get(0) : undefined;
+            const page = target instanceof PDFRef ? indexes.get(target.toString()) : undefined;
+            if (page !== undefined)
+                pages.set(name.decodeText(), page);
+        }
+    }
+    return pages;
+};
+/*  attach a hierarchical PDF outline (the "bookmarks" of the viewer
+    side-bar) to a document, resolving the entry anchors against the
+    named destinations and hoisting the childs of an unresolvable entry  */
+const addOutline = async (doc, entries) => {
+    const { PDFName, PDFDict, PDFArray, PDFRef, PDFHexString } = await import("pdf-lib");
+    const context = doc.context;
+    /*  collect the still intact named destinations  */
+    const live = new Set(doc.getPages().map((page) => page.ref.toString()));
+    const targets = new Map();
+    const dests = doc.catalog.lookupMaybe(PDFName.of("Dests"), PDFDict);
+    if (dests !== undefined) {
+        for (const [name] of dests.entries()) {
+            const dest = dests.lookup(name);
+            const page = dest instanceof PDFArray ? dest.get(0) : undefined;
+            if (dest instanceof PDFArray && page instanceof PDFRef && live.has(page.toString()))
+                targets.set(name.decodeText(), dest);
+        }
+    }
+    const resolve = (entries) => entries.flatMap((entry) => {
+        const dest = targets.get(entry.anchor);
+        const childs = resolve(entry.childs);
+        return dest !== undefined ? [{ title: entry.title, dest, childs }] : childs;
+    });
+    const items = resolve(entries);
+    if (items.length === 0)
+        return;
+    /*  recursively materialize the outline items, wiring up the
+        Parent/Prev/Next/First/Last cross-references of the tree  */
+    const materialize = (items, parent) => {
+        const refs = items.map(() => context.nextRef());
+        items.forEach((item, i) => {
+            const childs = item.childs.length > 0 ? materialize(item.childs, refs[i]) : undefined;
+            context.assign(refs[i], context.obj({
+                Title: PDFHexString.fromText(item.title),
+                Parent: parent,
+                Prev: i > 0 ? refs[i - 1] : undefined,
+                Next: i < refs.length - 1 ? refs[i + 1] : undefined,
+                First: childs?.first,
+                Last: childs?.last,
+                /*  a negative count keeps the sub-tree initially collapsed  */
+                Count: childs !== undefined ? -item.childs.length : undefined,
+                Dest: item.dest
+            }));
+        });
+        return { first: refs[0], last: refs[refs.length - 1] };
+    };
+    const root = context.nextRef();
+    const top = materialize(items, root);
+    context.assign(root, context.obj({
+        Type: "Outlines", First: top.first, Last: top.last, Count: items.length
+    }));
+    doc.catalog.set(PDFName.of("Outlines"), root);
+    doc.catalog.set(PDFName.of("PageMode"), PDFName.of("UseOutlines"));
+};
+/*  render a self-contained HTML document into a PDF via Playwright,
+    re-rendering the HTML with the discovered ToC page numbers  */
+export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css, theme, paper = paperSizeDefault) => {
+    const { chromium } = await import("playwright");
+    /*  the page geometry of the chosen paper size  */
+    const setup = paperSetup(paper);
+    const margin = setup.margin;
+    /*  the regular font face and the title/subtitle
+        text for the header/footer templates  */
+    const fontFace = css.match(/@font-face\s*\{[^}]*\}/)?.[0] ?? "";
+    const headText = escapeHtml(heading.title) +
+        (heading.subtitle !== undefined ? ` &mdash; ${escapeHtml(heading.subtitle)}` : "");
+    /*  launch the Playwright Chromium browser, falling back to a
+        system-installed Google Chrome if the Chromium download is missing  */
+    let browser;
+    try {
+        browser = await chromium.launch();
+    }
+    catch (err) {
+        verbose("Playwright Chromium unavailable -- falling back to installed Google Chrome");
+        try {
+            browser = await chromium.launch({ channel: "chrome" });
+        }
+        catch {
+            /*  report the original, more instructive error  */
+            throw err;
+        }
+    }
+    try {
+        const page = await browser.newPage();
+        /*  render an HTML document into a paginated PDF  */
+        const renderPdf = async (html, options = {}) => {
+            await page.setContent(html, { waitUntil: "networkidle" });
+            await page.evaluate(() => document.fonts.ready);
+            return page.pdf({
+                format: paper,
+                margin: {
+                    top: paperLength(setup, margin.top),
+                    right: paperLength(setup, margin.right),
+                    bottom: paperLength(setup, margin.bottom),
+                    left: paperLength(setup, margin.left)
+                },
+                printBackground: true,
+                preferCSSPageSize: true,
+                ...options
+            });
+        };
+        /*  determine the ToC page numbers via a fixpoint iteration:
+            paginate undecorated, extract the per-anchor pages, and
+            re-render until the HTML is stable, as the ToC page number
+            column itself can shift the pagination  */
+        verbose("determining ToC page numbers");
+        let html = await renderHtmlPass();
+        let plain = await renderPdf(html);
+        for (let i = 0; i < 3; i++) {
+            const next = await renderHtmlPass(await anchorPages(plain));
+            if (next === html)
+                break;
+            html = next;
+            plain = await renderPdf(html);
+        }
+        const decorated = await renderPdf(html, {
+            /*  the header/footer templates render in an isolated context,
+                so they need their own inline styling, the regular font face
+                embedded as a data: URI, and the special "title"/"pageNumber"
+                classes for the injected values  */
+            displayHeaderFooter: true,
+            headerTemplate: `<style>${fontFace}</style>` +
+                "<div style=\"width: 100%; margin-top: 0.8cm;\">" +
+                `<div style="margin: 0 ${paperLength(setup, margin.left)}; ` +
+                "font-family: 'Source Sans 3', sans-serif; " +
+                `font-size: 8pt; color: ${theme.symbol}; border-bottom: 1px solid ${theme.border}; ` +
+                "padding-bottom: 1mm; display: flex; justify-content: space-between; " +
+                "align-items: flex-end;\">" +
+                `<span>${headText}</span>` +
+                `<img src="${heading.logo}" alt="" style="height: 3.5mm;"/>` +
+                "</div></div>",
+            footerTemplate: `<style>${fontFace}</style>` +
+                "<div style=\"width: 100%; margin-bottom: 0.8cm;\">" +
+                `<div style="margin: 0 ${paperLength(setup, margin.left)}; ` +
+                "font-family: 'Source Sans 3', sans-serif; " +
+                `font-size: 8pt; color: ${theme.text}; display: flex; ` +
+                `justify-content: space-between; border-top: 1px solid ${theme.border}; ` +
+                "padding-top: 1mm;\">" +
+                `<span style="color: ${theme.symbol}">${headText}</span>` +
+                `<span style="color: ${theme.muted}; font-weight: bold;" class="pageNumber"></span></div></div>`
+        });
+        /*  a title page carries no header/footer: as Chromium decorates
+            all pages unconditionally, swap the first page of the
+            identically paginated undecorated document (left over from
+            the ToC page number iteration) into the decorated document
+            *in place*, which keeps the decorated document's link
+            destinations (and hence the internal hyperlinks) intact  */
+        const { PDFDocument, rgb } = await import("pdf-lib");
+        const merged = await PDFDocument.load(decorated);
+        if (html.includes("class=\"titlepage\"")) {
+            const source = await PDFDocument.load(plain);
+            const [titlePage] = await merged.copyPages(source, [0]);
+            merged.removePage(0);
+            merged.insertPage(0, titlePage);
+        }
+        /*  attach the document outline for the viewer side-bar  */
+        verbose("attaching PDF outline (bookmarks)");
+        await addOutline(merged, outline);
+        /*  draw the vertical brand bar onto the left edge of the
+            physical paper of every page, as Chromium clips print
+            content to the page box (0.6rem at the 9pt print root)  */
+        const [r, g, b] = (theme.accent.match(/[0-9a-f]{2}/gi) ?? [])
+            .map((hex) => parseInt(hex, 16) / 255);
+        for (const pdfPage of merged.getPages())
+            pdfPage.drawRectangle({ x: 0, y: 0, width: 5.4,
+                height: pdfPage.getHeight(), color: rgb(r, g, b) });
+        return Buffer.from(await merged.save());
+    }
+    finally {
+        await browser.close();
+    }
+};

package/dst/specbook-link.d.ts

@@ -0,0 +1,17 @@
+import type { Specification, Object as SpecObject } from "./specbook-struct-spec.js";
+export declare const referenceRegex: RegExp;
+interface LinkNode {
+    object: SpecObject;
+    parent?: LinkNode;
+}
+export type LinkIndex = LinkNode[];
+export interface LinkTarget {
+    target?: SpecObject;
+    ambiguous: boolean;
+}
+export declare const buildLinkIndex: (specification: Specification) => LinkIndex;
+export declare const resolveSet: (index: LinkIndex, reference: string) => SpecObject[];
+export declare const resolveUnique: (index: LinkIndex, reference: string) => LinkTarget;
+export declare const anchorPaths: (index: LinkIndex) => Map<SpecObject, string>;
+export declare const expandReferences: (text: string, replace: (reference: string) => string) => string;
+export {};

package/dst/specbook-link.js

@@ -0,0 +1,113 @@
+/*
+**  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>
+*/
+/*  the Wiki-style reference syntax ("[[xxx]]")  */
+export const referenceRegex = /\[\[([^[\]]+)\]\]/g;
+/*  build the resolution index over all objects of a specification  */
+export const buildLinkIndex = (specification) => {
+    const index = [];
+    const walk = (object, parent) => {
+        const node = { object, parent };
+        index.push(node);
+        for (const child of object.childs)
+            walk(child, node);
+    };
+    for (const artifact of specification.artifacts)
+        for (const object of artifact.objects)
+            walk(object);
+    return index;
+};
+/*  split a text at a separator character, honoring double-quoted
+    sections (the quotes are retained for a later unquote())  */
+const splitQuoted = (text, separator) => {
+    const parts = [""];
+    let quoted = false;
+    for (const char of text) {
+        if (char === "\"")
+            quoted = !quoted;
+        if (!quoted && char === separator)
+            parts.push("");
+        else
+            parts[parts.length - 1] += char;
+    }
+    return parts;
+};
+/*  strip the optional surrounding double quotes of a part  */
+const unquote = (part) => part.replace(/^"(.*)"$/s, "$1");
+/*  match a name-or-id part against an object (with "*" wildcard)  */
+const matchesPart = (object, part) => part === "*"
+    || object.id === part
+    || object.anchor === part
+    || object.name.replace(/`/g, "") === part;
+/*  match a single reference segment ("id", "name", "KIND:name-or-id",
+    "KIND:*", or "*", each part optionally double-quoted to allow
+    spaces, dots, and colons) against a single object  */
+const matchesSegment = (object, segment) => {
+    const parts = splitQuoted(segment, ":");
+    if (parts.length >= 2)
+        return object.kind === unquote(parts[0].trim())
+            && matchesPart(object, unquote(parts.slice(1).join(":").trim()));
+    return matchesPart(object, unquote(segment.trim()));
+};
+/*  split a reference into its hierarchical path segments,
+    honoring double-quoted parts  */
+const segmentsOf = (reference) => splitQuoted(reference, ".").map((segment) => segment.trim()).filter((segment) => segment !== "");
+/*  resolve a reference into the set of all matching objects: a path
+    matches object chains connected by direct parent-to-child steps,
+    with the leading segments up to the root freely omittable  */
+export const resolveSet = (index, reference) => {
+    const segments = segmentsOf(reference);
+    if (segments.length === 0)
+        return [];
+    return index.filter((node) => {
+        let current = node;
+        for (let i = segments.length - 1; i >= 0; i--) {
+            if (current === undefined || !matchesSegment(current.object, segments[i]))
+                return false;
+            current = current.parent;
+        }
+        return true;
+    }).map((node) => node.object);
+};
+/*  resolve a reference into a unique target: a single segment tries the
+    ordered variants (1) id/anchor, (2) name, (3) "KIND:name-or-id", where
+    the first variant yielding matches decides (several matches are an
+    ambiguity), while a hierarchical path resolves via its full match set  */
+export const resolveUnique = (index, reference) => {
+    const segments = segmentsOf(reference);
+    let matches = [];
+    if (segments.length === 1) {
+        const segment = segments[0];
+        const plain = unquote(segment);
+        const variants = [
+            (object) => object.id === plain || object.anchor === plain,
+            (object) => object.name.replace(/`/g, "") === plain,
+            (object) => matchesSegment(object, segment)
+        ];
+        for (const variant of variants) {
+            matches = index.filter((node) => variant(node.object)).map((node) => node.object);
+            if (matches.length > 0)
+                break;
+        }
+    }
+    else
+        matches = resolveSet(index, reference);
+    return { target: matches.length === 1 ? matches[0] : undefined, ambiguous: matches.length > 1 };
+};
+/*  derive the fully-qualified anchor path of every object: the
+    "<kind>-<id>" segments (whitespace in kinds dashed) of the ancestor
+    chain joined with "." (the index lists parents before childs)  */
+export const anchorPaths = (index) => {
+    const paths = new Map();
+    for (const node of index) {
+        const kind = node.object.kind.replace(/\s+/g, "-");
+        const segment = kind !== "" ? `${kind}-${node.object.id}` : node.object.id;
+        const parent = node.parent !== undefined ? paths.get(node.parent.object) : undefined;
+        paths.set(node.object, parent !== undefined ? `${parent}.${segment}` : segment);
+    }
+    return paths;
+};
+/*  expand all references of a text via a per-reference replacer  */
+export const expandReferences = (text, replace) => text.replace(referenceRegex, (_, reference) => replace(reference.trim()));

package/dst/specbook-llm.d.ts

@@ -0,0 +1,13 @@
+import { type LanguageModel } from "ai";
+export interface AiOptions {
+    provider?: string;
+    model?: string;
+}
+export declare const resolveModel: (options: AiOptions) => Promise<LanguageModel>;
+export declare const complete: (options: AiOptions, system: string, prompt: string) => Promise<string>;
+export declare const timestamp: () => string;
+export declare const renderFileBlock: (name: string, content: string) => string;
+export declare const parseFileBlocks: (text: string) => {
+    name: string;
+    content: string;
+}[];

package/dst/specbook-llm.js

@@ -0,0 +1,61 @@
+/*
+**  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 { generateText } from "ai";
+/*  the default model per supported provider  */
+const defaults = {
+    anthropic: "claude-sonnet-5",
+    openai: "gpt-5.6-luna",
+    openrouter: "anthropic/claude-sonnet-5",
+    ollama: "qwen3"
+};
+/*  resolve the AI provider and model into a language model handle  */
+export const resolveModel = async (options) => {
+    const provider = options.provider ?? process.env.SPECBOOK_AI_PROVIDER ?? "anthropic";
+    const model = options.model ?? process.env.SPECBOOK_AI_MODEL ?? defaults[provider];
+    if (provider === "anthropic") {
+        const { createAnthropic } = await import("@ai-sdk/anthropic");
+        return createAnthropic()(model);
+    }
+    else if (provider === "openai") {
+        const { createOpenAI } = await import("@ai-sdk/openai");
+        return createOpenAI()(model);
+    }
+    else if (provider === "openrouter") {
+        const { createOpenRouter } = await import("@openrouter/ai-sdk-provider");
+        return createOpenRouter()(model);
+    }
+    else if (provider === "ollama") {
+        const { createOllama } = await import("ollama-ai-provider-v2");
+        return createOllama()(model);
+    }
+    else
+        throw new Error(`unknown AI provider "${provider}" ` +
+            "(expected \"anthropic\", \"openai\", \"openrouter\" or \"ollama\")");
+};
+/*  perform a single LLM completion  */
+export const complete = async (options, system, prompt) => {
+    const model = await resolveModel(options);
+    const result = await generateText({ model, system, prompt });
+    return result.text;
+};
+/*  the current time in the frontmatter timestamp format  */
+export 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())}`;
+};
+/*  render a named file as a block of the LLM file exchange protocol  */
+export const renderFileBlock = (name, content) => `<<<FILE: ${name}>>>\n${content.replace(/\n$/, "")}\n<<<END-FILE>>>`;
+/*  parse all file blocks of the LLM file exchange protocol  */
+export const parseFileBlocks = (text) => {
+    const blocks = new Array();
+    const re = /<<<FILE:\s*([^>]+?)\s*>>>\r?\n([\s\S]*?)<<<END-FILE>>>/g;
+    let m;
+    while ((m = re.exec(text)) !== null)
+        blocks.push({ name: m[1], content: m[2].replace(/\n*$/, "\n") });
+    return blocks;
+};

package/dst/specbook-mcp.d.ts

@@ -0,0 +1 @@
+export declare const serveMcp: (verbose: (msg: string) => void) => Promise<void>;

package/dst/specbook-mcp.js

@@ -0,0 +1,163 @@
+/*
+**  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 * as fs from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { SpecBook, renderDiagnostic, formats } from "./specbook-api.js";
+/*  render an error with its cause chain into a tool error result  */
+const errorResult = (err) => {
+    let msg = err instanceof Error ? err.message : String(err);
+    for (let cause = err instanceof Error ? err.cause : undefined; cause instanceof Error; cause = cause.cause)
+        msg += `: ${cause.message}`;
+    return {
+        isError: true,
+        content: [{ type: "text", text: `ERROR: ${msg}` }]
+    };
+};
+/*  serve the SpecBook functionality as "specbook_<cmd>" MCP tools over stdio  */
+export const serveMcp = async (verbose) => {
+    const server = new McpServer({ name: "specbook", version: "0.9.0" });
+    const specbook = new SpecBook({ verbose });
+    server.registerTool("specbook_init", {
+        title: "Initialize Specification",
+        description: "Initialize the configured specification artifact files below the base directory " +
+            "with their frontmatter and artifact heading, skipping already existing files.",
+        inputSchema: {
+            config: z.string().describe("YAML schema configuration file"),
+            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
+        }
+    }, async (args) => {
+        try {
+            const created = await specbook.init(args);
+            return { content: [{ type: "text", text: created.length > 0 ?
+                            `initialized artifact file(s): ${created.join(", ")}` :
+                            "no artifact files were created" }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("specbook_lint", {
+        title: "Lint Specification",
+        description: "Lint the specification Markdown files below the base directory against the " +
+            "optional YAML schema configuration and return all diagnostics.",
+        inputSchema: {
+            config: z.string().optional().describe("YAML schema configuration file"),
+            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")")
+        }
+    }, async (args) => {
+        try {
+            const result = await specbook.lint(args);
+            const text = result.diagnostics.length > 0 ?
+                result.diagnostics.map(renderDiagnostic).join("\n") :
+                "specification valid";
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("specbook_export", {
+        title: "Export Specification",
+        description: "Export the specification Markdown files below the base directory as JSON, JSON5, " +
+            "YAML, TOON, HTML, PDF, or normalized Markdown. The result is written to the output file " +
+            "if an output path is given, else it is returned directly (PDF as a base64-encoded resource).",
+        inputSchema: {
+            config: z.string().optional().describe("YAML schema configuration file"),
+            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
+            format: z.enum(formats).optional().describe("output format (default: json)"),
+            output: z.string().optional().describe("output file path"),
+            maxTableColumns: z.number().optional().describe("maximum name/property/description " +
+                "columns for the compact table rendering (default: 4)")
+        }
+    }, async (args) => {
+        try {
+            const [data] = await specbook.export({ config: args.config, basedir: args.basedir,
+                formats: [args.format ?? "json"], maxTableColumns: args.maxTableColumns });
+            if (args.output !== undefined) {
+                await fs.promises.writeFile(args.output, data);
+                return { content: [{ type: "text", text: `exported specification into "${args.output}" (${data.length} bytes)` }] };
+            }
+            else if ((args.format ?? "json") === "pdf")
+                return { content: [{
+                            type: "resource",
+                            resource: { uri: "specbook:export.pdf", mimeType: "application/pdf", blob: data.toString("base64") }
+                        }] };
+            else
+                return { content: [{ type: "text", text: data.toString("utf8") }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("specbook_describe", {
+        title: "Describe Specification Format",
+        description: "Describe the specification format configured by the YAML schema configuration " +
+            "as a Markdown document.",
+        inputSchema: {
+            config: z.string().describe("YAML schema configuration file"),
+            output: z.string().optional().describe("output file path (default: return description)")
+        }
+    }, async (args) => {
+        try {
+            const text = await specbook.describe(args);
+            if (args.output !== undefined) {
+                await fs.promises.writeFile(args.output, text, "utf8");
+                return { content: [{ type: "text", text: `described specification format into "${args.output}"` }] };
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("specbook_import", {
+        title: "Import Foreign Sources",
+        description: "Import the information of foreign source files into the configured specification " +
+            "artifact files below the base directory, using an LLM.",
+        inputSchema: {
+            config: z.string().describe("YAML schema configuration file"),
+            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
+            inputs: z.array(z.string()).describe("foreign source files to import"),
+            provider: z.string().optional().describe("AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")"),
+            model: z.string().optional().describe("AI model")
+        }
+    }, async (args) => {
+        try {
+            const written = await specbook.import(args);
+            return { content: [{ type: "text", text: written.length > 0 ?
+                            `imported into artifact file(s): ${written.join(", ")}` :
+                            "no artifact files were changed" }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.registerTool("specbook_edit", {
+        title: "Edit Specification",
+        description: "Apply a free-text edit request to the configured specification artifact files " +
+            "below the base directory, using an LLM.",
+        inputSchema: {
+            config: z.string().describe("YAML schema configuration file"),
+            basedir: z.string().optional().describe("base directory of the specification Markdown files (default: \".\")"),
+            query: z.string().describe("free-text edit request"),
+            provider: z.string().optional().describe("AI provider (\"anthropic\", \"openai\", \"openrouter\" or \"ollama\")"),
+            model: z.string().optional().describe("AI model")
+        }
+    }, async (args) => {
+        try {
+            const written = await specbook.edit(args);
+            return { content: [{ type: "text", text: written.length > 0 ?
+                            `edited artifact file(s): ${written.join(", ")}` :
+                            "no artifact files were changed" }] };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    await server.connect(new StdioServerTransport());
+};

package/dst/specbook-parse-common.d.ts

@@ -0,0 +1,26 @@
+import { type Specification, type Object as SpecObject, type Property } from "./specbook-struct-spec.js";
+import { type Diagnostic } from "./specbook-diagnostic.js";
+import { type LinkIndex } from "./specbook-link.js";
+export interface SourceFile {
+    file: string;
+    text: string;
+}
+export interface ParseResult {
+    specification: Specification;
+    diagnostics: Diagnostic[];
+}
+export interface ObjectMeta {
+    file: string;
+    line: number;
+}
+export declare class ParseContext {
+    diagnostics: Diagnostic[];
+    objectMeta: WeakMap<SpecObject, ObjectMeta>;
+    propMeta: WeakMap<Property, {
+        line: number;
+    }>;
+    linkIndex: LinkIndex;
+    diagnose(file: string, line: number, message: string): void;
+}
+export declare const embeddingRegex: RegExp;
+export declare const embeddingMimeType: (reference: string) => string | undefined;

package/dst/specbook-parse-common.js

@@ -0,0 +1,33 @@
+/*
+**  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>
+*/
+/*  the state shared between the syntactic and semantic parsing phases  */
+export class ParseContext {
+    diagnostics = new Array();
+    objectMeta = new WeakMap();
+    propMeta = new WeakMap();
+    linkIndex = [];
+    /*  record a single diagnostic  */
+    diagnose(file, line, message) {
+        this.diagnostics.push({ file, line, column: 1, message });
+    }
+}
+/*  the Markdown image embedding syntax ("![alt](file)")  */
+export const embeddingRegex = /!\[([^\]]*)\]\(([^()]+)\)/g;
+/*  the embeddable file types and their MIME types  */
+const embeddingTypes = {
+    svg: "image/svg+xml",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg"
+};
+/*  map a local image embedding reference onto its MIME type
+    (URLs and other file types are not embeddable)  */
+export const embeddingMimeType = (reference) => {
+    if (/^[a-z][a-z0-9+.-]+:/i.test(reference))
+        return undefined;
+    const extension = reference.match(/\.([a-z0-9]+)$/i)?.[1].toLowerCase();
+    return extension !== undefined ? embeddingTypes[extension] : undefined;
+};

package/dst/specbook-parse-semantic.d.ts

@@ -0,0 +1,5 @@
+import { type Specification } from "./specbook-struct-spec.js";
+import { type SchemaSpecification } from "./specbook-struct-schema.js";
+import { ParseContext } from "./specbook-parse-common.js";
+export declare const validate: (ctx: ParseContext, specification: Specification, config: SchemaSpecification) => void;
+export declare const validateReferences: (ctx: ParseContext, specification: Specification) => void;