@rse/specbook 0.9.5 → 0.9.7

package/dst/specbook-cmd-edit.js

@@ -1,74 +0,0 @@
-/*
-**  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 * as path from "node:path";
-import textframe from "textframe";
-import { describeConfiguration } from "./specbook-cmd-describe.js";
-import { complete, timestamp, renderFileBlock, parseFileBlocks } from "./specbook-llm.js";
-/*  the LLM instruction for the edit command  */
-const instruction = (description, now) => textframe `
-    You are the edit engine of SpecBook, a Markdown-based specification
-    format. Apply the given edit request to the Markdown specification
-    artifact files of the project. Strictly honor the following rules:
-
-    -   Surgical changes: change only what the edit request actually
-        demands; do not rewrite unrelated parts of an artifact.
-    -   No fabrication: never invent content the edit request does not
-        support; leave gaps open instead of guessing.
-    -   Format conformance: strictly follow the specification format
-        described below.
-    -   Markdown generation: MIRROR the format each existing object already
-        uses (keep Complex Format objects complex and Concise Format
-        objects concise); for entirely new objects emit the Complex Format
-        on levels 1-3 ("#"/"##"/"###") and the Concise Format on level 4
-        and deeper.
-    -   Timestamps: refresh the "Modified:" frontmatter of every changed
-        file to "${now}"; keep "Created:" untouched.
-    -   Files: update ONLY the configured artifact files listed in the
-        format description below -- never any other file.
-    -   Output: return ONLY the actually changed files, each as a block of
-        the exact form below, and no other text at all:
-
-        <<<FILE: <name>>>>
-        <content>
-        <<<END-FILE>>>
-
-    ${description}
-`;
-/*  apply an edit request to the specification artifact files  */
-export const editSpecification = async (options) => {
-    const basedir = options.basedir ?? ".";
-    const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
-    /*  ensure a non-empty edit request was given  */
-    if (options.query.trim() === "")
-        throw new Error("no edit request given");
-    /*  gather the existing artifact files  */
-    const existing = files
-        .filter((file) => fs.existsSync(path.join(basedir, file)))
-        .map((file) => renderFileBlock(file, fs.readFileSync(path.join(basedir, file), "utf8")));
-    if (existing.length === 0)
-        throw new Error(`no configured artifact files found in "${basedir}"`);
-    /*  let the LLM apply the edit request  */
-    options.verbose(`editing artifact files in "${basedir}"`);
-    const system = instruction(describeConfiguration(options.config), timestamp());
-    const prompt = "EXISTING ARTIFACT FILES:\n\n" + existing.join("\n\n") +
-        "\n\nEDIT REQUEST:\n\n" + options.query;
-    const response = await complete(options, system, prompt);
-    /*  write back all returned artifact files  */
-    const written = new Array();
-    for (const block of parseFileBlocks(response)) {
-        if (!files.includes(block.name)) {
-            options.verbose(`ignoring unconfigured file "${block.name}"`);
-            continue;
-        }
-        const file = path.join(basedir, block.name);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, block.content, "utf8");
-        options.verbose(`wrote artifact file "${block.name}"`);
-        written.push(block.name);
-    }
-    return written;
-};

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

@@ -1,9 +0,0 @@
-import { type SchemaSpecification } from "./specbook-struct-schema.js";
-import { type AiOptions } from "./specbook-llm.js";
-export interface ImportOptions extends AiOptions {
-    config: SchemaSpecification;
-    basedir?: string;
-    inputs: string[];
-    verbose: (msg: string) => void;
-}
-export declare const importSpecification: (options: ImportOptions) => Promise<string[]>;

package/dst/specbook-cmd-import.js

@@ -1,78 +0,0 @@
-/*
-**  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 * as path from "node:path";
-import textframe from "textframe";
-import { describeConfiguration } from "./specbook-cmd-describe.js";
-import { complete, timestamp, renderFileBlock, parseFileBlocks } from "./specbook-llm.js";
-/*  the LLM instruction for the import command  */
-const instruction = (description, now) => textframe `
-    You are the import engine of SpecBook, a Markdown-based specification
-    format. Import the information of the given foreign sources into the
-    Markdown specification artifact files of the project, generating or
-    updating the artifact files so they faithfully reflect the imported
-    information. Strictly honor the following rules:
-
-    -   Faithful reflection: the artifacts must reflect the imported
-        sources exactly -- no more, no less.
-    -   No fabrication: never invent content the sources do not support;
-        leave gaps open instead of guessing.
-    -   Surgical updates: when updating an existing artifact, change only
-        what the imported information actually requires.
-    -   Level-appropriate translation: re-express the imported facts at the
-        artifact's level of abstraction; do not copy verbatim.
-    -   Format conformance: strictly follow the specification format
-        described below.
-    -   Markdown generation: emit the Complex Format on levels 1-3
-        ("#"/"##"/"###") and the Concise Format on level 4 and deeper.
-    -   Timestamps: use "${now}" for the "Created:" and "Modified:"
-        frontmatter of generated files, and refresh "Modified:" to
-        "${now}" on updated files.
-    -   Files: generate or update ONLY the configured artifact files listed
-        in the format description below -- never any other file.
-    -   Output: return ONLY the generated or updated files, each as a block
-        of the exact form below, and no other text at all:
-
-        <<<FILE: <name>>>>
-        <content>
-        <<<END-FILE>>>
-
-    ${description}
-`;
-/*  import foreign sources into the specification artifact files  */
-export const importSpecification = async (options) => {
-    const basedir = options.basedir ?? ".";
-    const files = options.config.map((artifact) => artifact.file).filter((file) => file !== undefined);
-    /*  ensure at least one foreign source was given  */
-    if (options.inputs.length === 0)
-        throw new Error("no foreign sources given to import");
-    /*  gather the existing artifact files and the foreign sources  */
-    const existing = files
-        .filter((file) => fs.existsSync(path.join(basedir, file)))
-        .map((file) => renderFileBlock(file, fs.readFileSync(path.join(basedir, file), "utf8")));
-    const sources = options.inputs
-        .map((input) => renderFileBlock(input, fs.readFileSync(input, "utf8")));
-    /*  let the LLM generate or update the artifact files  */
-    options.verbose(`importing ${options.inputs.length} foreign source(s) into "${basedir}"`);
-    const system = instruction(describeConfiguration(options.config), timestamp());
-    const prompt = "EXISTING ARTIFACT FILES:\n\n" + (existing.length > 0 ? existing.join("\n\n") : "(none)") +
-        "\n\nFOREIGN SOURCES TO IMPORT:\n\n" + sources.join("\n\n");
-    const response = await complete(options, system, prompt);
-    /*  write back all returned artifact files  */
-    const written = new Array();
-    for (const block of parseFileBlocks(response)) {
-        if (!files.includes(block.name)) {
-            options.verbose(`ignoring unconfigured file "${block.name}"`);
-            continue;
-        }
-        const file = path.join(basedir, block.name);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, block.content, "utf8");
-        options.verbose(`wrote artifact file "${block.name}"`);
-        written.push(block.name);
-    }
-    return written;
-};

package/dst/specbook-export-logo.svg

@@ -1,35 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 260.81 110.54">
-  <!-- Generator: Adobe Illustrator 30.7.0, SVG Export Plug-In . SVG Version: 2.1.4 Build 114)  -->
-  <defs>
-    <style>
-      .st0 {
-        fill: none;
-      }
-
-      .st1 {
-        fill: #231f20;
-      }
-
-      .st2 {
-        fill: #666766;
-      }
-    </style>
-  </defs>
-  <g>
-    <rect class="st0" x="128.02" y="5.89" width="297.69" height="245.38"/>
-    <path class="st1" d="M132.56,41.28c2.62,1.34,6.66,2.69,10.82,2.69,4.48,0,6.85-1.86,6.85-4.67s-2.05-4.22-7.23-6.08c-7.17-2.5-11.84-6.46-11.84-12.73,0-7.36,6.14-12.99,16.32-12.99,4.86,0,8.45,1.02,11.01,2.18l-2.18,7.87c-1.73-.83-4.8-2.05-9.02-2.05s-6.27,1.92-6.27,4.16c0,2.75,2.43,3.97,8,6.08,7.62,2.82,11.2,6.78,11.2,12.86,0,7.23-5.57,13.38-17.41,13.38-4.93,0-9.79-1.28-12.22-2.62l1.98-8.06Z"/>
-    <path class="st1" d="M163.28,30.53c0-4.1-.13-7.62-.26-10.5h8.45l.45,4.35h.13c2.3-3.33,5.89-5.06,10.43-5.06,6.85,0,12.99,5.95,12.99,15.93,0,11.39-7.23,16.77-14.21,16.77-3.78,0-6.72-1.54-8.13-3.58h-.13v15.55h-9.73V30.53ZM173.01,37.89c0,.77.06,1.47.19,2.05.64,2.62,2.88,4.61,5.7,4.61,4.22,0,6.72-3.52,6.72-8.83,0-4.99-2.24-8.77-6.59-8.77-2.75,0-5.18,2.05-5.82,4.93-.13.51-.19,1.15-.19,1.73v4.29Z"/>
-    <path class="st1" d="M206.03,38.78c.32,4.03,4.29,5.95,8.83,5.95,3.33,0,6.02-.45,8.64-1.28l1.28,6.59c-3.2,1.28-7.1,1.92-11.33,1.92-10.62,0-16.7-6.14-16.7-15.94,0-7.94,4.93-16.7,15.81-16.7,10.11,0,13.95,7.87,13.95,15.61,0,1.66-.19,3.14-.32,3.84h-20.16ZM217.48,32.13c0-2.37-1.02-6.34-5.5-6.34-4.1,0-5.76,3.71-6.02,6.34h11.52Z"/>
-    <path class="st1" d="M252.62,50.56c-1.73.77-4.99,1.41-8.7,1.41-10.11,0-16.57-6.14-16.57-16,0-9.15,6.27-16.64,17.92-16.64,2.56,0,5.38.45,7.42,1.22l-1.54,7.23c-1.15-.51-2.88-.96-5.44-.96-5.12,0-8.45,3.65-8.38,8.77,0,5.76,3.84,8.77,8.58,8.77,2.3,0,4.1-.38,5.57-.96l1.15,7.17Z"/>
-  </g>
-  <path d="M25.37,18.54h0c-1.03,0-2,.4-2.73,1.13-.74.74-1.15,1.72-1.15,2.77v58.42c0,2.14,1.75,3.89,3.9,3.9,9.07.02,24.26,1.91,34.75,12.88v-61.14c0-.73-.19-1.41-.54-1.97-8.6-13.85-25.14-15.96-34.23-15.98Z"/>
-  <path d="M104.82,80.86V22.43c0-1.05-.41-2.03-1.15-2.77-.73-.73-1.7-1.13-2.73-1.13h0c-9.09.02-25.62,2.13-34.23,15.98-.35.56-.54,1.25-.54,1.97v61.14c10.48-10.97,25.68-12.86,34.75-12.88,2.15,0,3.9-1.75,3.9-3.89Z"/>
-  <path class="st2" d="M113.7,32.01h-2.83v48.85c0,5.47-4.46,9.93-9.94,9.94-7.69.02-20.38,1.52-29.36,10.02,15.54-3.8,31.91-1.33,41.25.8,1.17.27,2.37,0,3.3-.75.93-.74,1.46-1.85,1.46-3.04v-61.92c0-2.15-1.75-3.9-3.9-3.9Z"/>
-  <path class="st2" d="M15.43,80.86v-48.85h-2.83c-2.15,0-3.9,1.75-3.9,3.9v61.92c0,1.19.53,2.3,1.46,3.04.93.74,2.14,1.02,3.3.75,9.33-2.13,25.71-4.6,41.25-.8-8.98-8.5-21.67-10.01-29.36-10.02-5.48-.01-9.94-4.47-9.94-9.94Z"/>
-  <g>
-    <path class="st2" d="M131.67,55.5c2.63-.55,6.77-.97,10.99-.97,6.01,0,9.88,1.04,12.78,3.39,2.42,1.8,3.87,4.56,3.87,8.22,0,4.49-2.97,8.43-7.88,10.23v.14c4.42,1.11,9.6,4.77,9.6,11.68,0,4.01-1.59,7.05-3.94,9.33-3.25,2.97-8.5,4.35-16.1,4.35-4.15,0-7.32-.28-9.33-.55v-45.81ZM137.68,74.57h5.46c6.36,0,10.09-3.32,10.09-7.81,0-5.46-4.15-7.6-10.23-7.6-2.76,0-4.35.21-5.32.41v14.99ZM137.68,96.89c1.17.21,2.9.28,5.04.28,6.22,0,11.95-2.28,11.95-9.05,0-6.36-5.46-8.98-12.02-8.98h-4.97v17.76Z"/>
-    <path class="st2" d="M206.14,66.9c-9.26,0-16.58,6.56-16.58,17.75,0,.12.01.24.01.36h-.04c-.27,7.16-4.51,12.28-10.13,12.28-5.94,0-10.16-5.53-10.16-12.85,0-6.36,3.11-12.99,10.29-12.99,4.29,0,7.02,2.57,8.53,5.85.79-2.15,1.94-3.99,3.37-5.51-2.83-3.1-6.89-4.9-11.76-4.9-9.26,0-16.58,6.56-16.58,17.75,0,10.57,6.98,17.2,16.03,17.2,7.88,0,16.19-5.14,16.61-16.84h0c0-.19-.02-.38-.02-.57,0-6.36,3.11-12.99,10.29-12.99s10.02,7.19,10.02,12.85c0,7.53-4.35,12.99-10.15,12.99-4.05,0-7.29-2.57-8.94-6.51-.75,2.31-1.89,4.24-3.29,5.8,2.9,3.37,7.13,5.27,11.96,5.27,8.08,0,16.65-5.39,16.65-17.75,0-10.22-6.49-17.2-16.1-17.2Z"/>
-    <path class="st2" d="M230.65,83.76h.14c.83-1.17,2-2.63,2.97-3.8l9.81-11.54h7.32l-12.92,13.75,14.72,19.69h-7.39l-11.54-16.03-3.11,3.45v12.57h-6.01v-49.06h6.01v30.95Z"/>
-  </g>
-</svg>

package/dst/specbook-llm.d.ts

@@ -1,13 +0,0 @@
-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

@@ -1,51 +0,0 @@
-/*
-**  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 supported AI providers  */
-const providers = {
-    anthropic: { model: "claude-sonnet-5",
-        create: async (id) => (await import("@ai-sdk/anthropic")).createAnthropic()(id) },
-    openai: { model: "gpt-5.6-luna",
-        create: async (id) => (await import("@ai-sdk/openai")).createOpenAI()(id) },
-    openrouter: { model: "anthropic/claude-sonnet-5",
-        create: async (id) => (await import("@openrouter/ai-sdk-provider")).createOpenRouter()(id) },
-    ollama: { model: "qwen3",
-        create: async (id) => (await import("ollama-ai-provider-v2")).createOllama()(id) }
-};
-/*  resolve the AI provider and model into a language model handle  */
-export const resolveModel = async (options) => {
-    const name = options.provider ?? process.env.SPECBOOK_AI_PROVIDER ?? "anthropic";
-    const provider = providers[name];
-    if (provider === undefined)
-        throw new Error(`unknown AI provider "${name}" (expected ` +
-            Object.keys(providers).map((n) => `"${n}"`).join(", ") + ")");
-    const model = options.model ?? process.env.SPECBOOK_AI_MODEL ?? provider.model;
-    return provider.create(model);
-};
-/*  perform a single LLM completion  */
-export const complete = async (options, system, prompt) => {
-    const { generateText } = await import("ai");
-    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-struct-spec.d.ts

@@ -1,31 +0,0 @@
-import * as v from "valibot";
-export type Specification = {
-    artifacts: Artifact[];
-};
-export type Artifact = {
-    created: Date;
-    modified: Date;
-    objects: Object[];
-};
-export type Object = {
-    kind: string;
-    id: string;
-    anchor?: string;
-    paren?: string;
-    name: string;
-    primary?: boolean;
-    description?: Description;
-    properties: Property[];
-    childs: Object[];
-};
-export type Description = {
-    description: string;
-    rationale?: string;
-    embedding?: string[];
-};
-export type Property = {
-    key: string;
-    value: string;
-    embedding?: string[];
-};
-export declare const Specification: v.GenericSchema<Specification>;