@quillmark/quiver 0.8.0 → 0.10.0

package/README.md

@@ -44,17 +44,16 @@ my-quiver/
 ```
 
 Recommended CI: use the bundled `@quillmark/quiver/testing` harness — it
-loads with `Quiver.fromDir` and exercises every quill so validation errors
-surface on publish, not on the consumer's build. The harness uses
-`node:test` (built into Node 18+); no extra test-runner dependency
-required. If you prefer vitest/jest/mocha, write a 12-line loop against
-the main API instead.
+loads with `Quiver.fromDir`, compiles every quill, and renders each quill's
+blueprint so validation errors surface on publish, not on the consumer's
+build. The harness uses `node:test` (built into Node 18+); no extra
+test-runner dependency required. If you prefer vitest/jest/mocha, write a
+12-line loop against the main API instead.
 
 ## Manual validation (rendering samples)
 
 The CI harness proves every quill _compiles_; it does not produce output a
-human can look at. To eyeball real renders, drop an `example.md` next to a
-quill's template (`quills/<name>/<x.y.z>/example.md`) and run the
+human can look at. To eyeball real renders, run the
 `@quillmark/quiver/preview` helper:
 
 ```ts
@@ -69,12 +68,12 @@ await renderQuiverSamples(import.meta.url, {
 // → writes ./preview/<name>@<version>.<fmt> + index.html
 ```
 
-It renders every quill's `example.md`, writes the artifacts to `outDir`
-(default `preview/`), and emits an `index.html` gallery. A `.gitignore` is
-written into `outDir` so the generated artifacts are never accidentally
-committed. Quills without an `example.md` are skipped; a quill that throws
-is recorded as failed — with every diagnostic, not just the first —
-without aborting the run, so one broken quill never hides the rest.
+It renders every quill's auto-generated blueprint (`quill.blueprint`), writes
+the artifacts to `outDir` (default `preview/`), and emits an `index.html`
+gallery. A `.gitignore` is written into `outDir` so the generated artifacts
+are never accidentally committed. A quill that throws is recorded as failed —
+with every diagnostic, not just the first — without aborting the run, so one
+broken quill never hides the rest.
 
 To iterate on a subset, pass `include` / `exclude` (each entry matches a
 quill name or canonical ref):

package/dist/bin/quiver.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Quiver CLI — build, test, and preview a quiver collection.
+ *
+ * Commands:
+ *   quiver build [--out <dir>]
+ *   quiver test
+ *   quiver preview [--out <dir>] [--format <fmt>] [--quiet]
+ *                  [--include <ref>...] [--exclude <ref>...]
+ *
+ * Engine discovery (for `test` and `preview`):
+ *   1. Named exports `engine` and `Document` from `quiver.config.js` at the
+ *      collection root, if the file exists.
+ *   2. Auto-imported `@quillmark/wasm` from the collection's node_modules.
+ */
+export {};

package/dist/bin/quiver.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * Quiver CLI — build, test, and preview a quiver collection.
+ *
+ * Commands:
+ *   quiver build [--out <dir>]
+ *   quiver test
+ *   quiver preview [--out <dir>] [--format <fmt>] [--quiet]
+ *                  [--include <ref>...] [--exclude <ref>...]
+ *
+ * Engine discovery (for `test` and `preview`):
+ *   1. Named exports `engine` and `Document` from `quiver.config.js` at the
+ *      collection root, if the file exists.
+ *   2. Auto-imported `@quillmark/wasm` from the collection's node_modules.
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Quiver } from "../node.js";
+import { renderQuiverSamples } from "../preview.js";
+// ---------------------------------------------------------------------------
+// Arg parsing helpers
+// ---------------------------------------------------------------------------
+const argv = process.argv.slice(2);
+const command = argv[0];
+function flag(name) {
+    const i = argv.indexOf(name);
+    return i !== -1 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
+function multiFlag(name) {
+    const out = [];
+    for (let i = 0; i < argv.length - 1; i++) {
+        if (argv[i] === name)
+            out.push(argv[i + 1]);
+    }
+    return out;
+}
+function hasFlag(name) {
+    return argv.includes(name);
+}
+// ---------------------------------------------------------------------------
+// Engine discovery
+// ---------------------------------------------------------------------------
+async function loadEngine(cwd) {
+    // 1. Named exports from quiver.config.js, if present.
+    try {
+        const cfg = await import(pathToFileURL(join(cwd, "quiver.config.js")).href);
+        if (cfg.engine != null && cfg.Document != null) {
+            return {
+                engine: cfg.engine,
+                Document: cfg.Document,
+            };
+        }
+    }
+    catch {
+        // File absent or incomplete — fall through to auto-discovery.
+    }
+    // 2. Auto-discover @quillmark/wasm from the collection's own node_modules.
+    const req = createRequire(pathToFileURL(join(cwd, "package.json")).href);
+    let wasmPath;
+    try {
+        wasmPath = req.resolve("@quillmark/wasm");
+    }
+    catch {
+        throw new Error("Cannot find @quillmark/wasm in this collection's node_modules.\n" +
+            "  Install it:  npm install @quillmark/wasm\n" +
+            "  Or export { engine, Document } from quiver.config.js for a custom engine.");
+    }
+    const wasm = (await import(pathToFileURL(wasmPath).href));
+    return { engine: new wasm.Quillmark(), Document: wasm.Document };
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+async function build() {
+    const cwd = process.cwd();
+    const outDir = flag("--out") ?? "dist";
+    console.log(`quiver build: ${cwd} → ${outDir}`);
+    await Quiver.build(cwd, outDir);
+    console.log("done.");
+}
+async function test() {
+    const cwd = process.cwd();
+    const { engine, Document } = await loadEngine(cwd);
+    const quiver = await Quiver.fromDir(cwd);
+    const names = quiver.quillNames();
+    if (names.length === 0) {
+        console.error("error: quiver has no quills");
+        process.exit(1);
+    }
+    let pass = 0;
+    let fail = 0;
+    for (const name of names) {
+        for (const version of quiver.versionsOf(name)) {
+            const ref = `${name}@${version}`;
+            try {
+                const quill = await quiver.getQuill(ref, { engine });
+                const doc = Document.fromMarkdown(quill.blueprint);
+                const result = quill.render(doc);
+                if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
+                    throw new Error("blueprint render produced no artifacts");
+                }
+                console.log(`pass  ${ref}`);
+                pass++;
+            }
+            catch (err) {
+                console.error(`FAIL  ${ref} — ${err.message}`);
+                fail++;
+            }
+        }
+    }
+    const total = pass + fail;
+    console.log(`\n${pass}/${total} passed`);
+    if (fail > 0)
+        process.exit(1);
+}
+async function preview() {
+    const cwd = process.cwd();
+    const { engine, Document } = await loadEngine(cwd);
+    const outDir = flag("--out");
+    const format = flag("--format");
+    const quiet = hasFlag("--quiet");
+    const include = multiFlag("--include");
+    const exclude = multiFlag("--exclude");
+    await renderQuiverSamples(cwd, {
+        engine,
+        Document,
+        ...(outDir !== undefined && { outDir }),
+        ...(format !== undefined && { format }),
+        quiet,
+        ...(include.length > 0 && { include }),
+        ...(exclude.length > 0 && { exclude }),
+    });
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+function usage() {
+    console.error([
+        "Usage:",
+        "  quiver build [--out <dir>]",
+        "  quiver test",
+        "  quiver preview [--out <dir>] [--format <fmt>] [--quiet]",
+        "                 [--include <ref>...] [--exclude <ref>...]",
+    ].join("\n"));
+}
+function die(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`error: ${msg}`);
+    process.exit(1);
+}
+switch (command) {
+    case "build":
+        build().catch(die);
+        break;
+    case "test":
+        test().catch(die);
+        break;
+    case "preview":
+        preview().catch(die);
+        break;
+    default:
+        usage();
+        process.exit(1);
+}

package/dist/engine-types.d.ts

@@ -23,4 +23,6 @@ export interface QuillmarkLike {
 export interface QuillLike {
     render(doc: unknown, opts?: unknown): unknown;
     open?: (doc: unknown) => unknown;
+    /** Auto-generated annotated Markdown blueprint — always present in @quillmark/wasm >=0.79.0. */
+    blueprint: string;
 }

package/dist/preview.d.ts

@@ -3,9 +3,9 @@
  *
  * `runQuiverTests` (`@quillmark/quiver/testing`) proves every quill *compiles*
  * — it never produces a rendered artifact a human can look at. This module
- * closes that gap: it renders each quill's bundled `example.md`, writes the
- * artifacts to a directory, and emits an `index.html` gallery so an author
- * can eyeball real output before publishing.
+ * closes that gap: it renders each quill's blueprint, writes the artifacts to
+ * a directory, and emits an `index.html` gallery so an author can eyeball real
+ * output before publishing.
  *
  * Node-only: writes files and loads a source quiver from disk.
  *
@@ -20,9 +20,9 @@
  *   });
  *   // → open ./preview/index.html
  *
- * The example document is the `example.md` file inside each quill version
- * directory (`quills/<name>/<version>/example.md`). Quills without one are
- * skipped, not failed.
+ * The sample document is the auto-generated blueprint (`quill.blueprint`) for
+ * each quill version. Every quill always has a blueprint, so no quills are
+ * skipped for lack of a sample document.
  *
  * A `.gitignore` is written into `outDir` so the generated artifacts are not
  * accidentally committed.
@@ -61,8 +61,8 @@ export interface RenderQuiverSamplesOptions {
 export interface RenderedSample {
     /** Canonical ref, e.g. `"memo@1.0.0"`. */
     ref: string;
-    /** `rendered` — artifacts written; `skipped` — no example; `failed` — error. */
-    status: "rendered" | "skipped" | "failed";
+    /** `rendered` — artifacts written; `failed` — error. */
+    status: "rendered" | "failed";
     /** Artifact filenames written under `outDir` (relative). */
     files: string[];
     /** Render warnings, formatted `"severity: message"`. */
@@ -74,7 +74,7 @@ export interface RenderedSample {
     reasons: string[];
 }
 /**
- * Renders every quill's `example.md` and writes the artifacts plus an
+ * Renders every quill's blueprint and writes the artifacts plus an
  * `index.html` gallery to `outDir`.
  *
  * Does NOT fail fast: a quill that throws is recorded as `failed` and the

package/dist/preview.js

@@ -3,9 +3,9 @@
  *
  * `runQuiverTests` (`@quillmark/quiver/testing`) proves every quill *compiles*
  * — it never produces a rendered artifact a human can look at. This module
- * closes that gap: it renders each quill's bundled `example.md`, writes the
- * artifacts to a directory, and emits an `index.html` gallery so an author
- * can eyeball real output before publishing.
+ * closes that gap: it renders each quill's blueprint, writes the artifacts to
+ * a directory, and emits an `index.html` gallery so an author can eyeball real
+ * output before publishing.
  *
  * Node-only: writes files and loads a source quiver from disk.
  *
@@ -20,9 +20,9 @@
  *   });
  *   // → open ./preview/index.html
  *
- * The example document is the `example.md` file inside each quill version
- * directory (`quills/<name>/<version>/example.md`). Quills without one are
- * skipped, not failed.
+ * The sample document is the auto-generated blueprint (`quill.blueprint`) for
+ * each quill version. Every quill always has a blueprint, so no quills are
+ * skipped for lack of a sample document.
  *
  * A `.gitignore` is written into `outDir` so the generated artifacts are not
  * accidentally committed.
@@ -30,12 +30,10 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { Quiver } from "./node.js";
-/** The `example.md` filename looked up inside each quill version directory. */
-const EXAMPLE_FILE = "example.md";
 /** Default directory rendered artifacts are written to. */
 const DEFAULT_OUT_DIR = "preview";
 /**
- * Renders every quill's `example.md` and writes the artifacts plus an
+ * Renders every quill's blueprint and writes the artifacts plus an
  * `index.html` gallery to `outDir`.
  *
  * Does NOT fail fast: a quill that throws is recorded as `failed` and the
@@ -86,21 +84,10 @@ function failureReasons(err) {
 }
 async function renderOne(quiver, name, version, outDir, opts) {
     const ref = `${name}@${version}`;
-    const tree = await quiver.loadTree(name, version);
-    const exampleBytes = tree.get(EXAMPLE_FILE);
-    if (exampleBytes === undefined) {
-        return {
-            ref,
-            status: "skipped",
-            files: [],
-            warnings: [],
-            reasons: [`no ${EXAMPLE_FILE} in quill directory`],
-        };
-    }
     let result;
     try {
         const quill = await quiver.getQuill(ref, { engine: opts.engine });
-        const markdown = new TextDecoder().decode(exampleBytes);
+        const markdown = quill.blueprint;
         const doc = opts.Document.fromMarkdown(markdown);
         result = quill.render(doc, opts.format ? { format: opts.format } : undefined);
     }
@@ -145,8 +132,7 @@ function printSummary(quiverName, outDir, results) {
         for (const w of r.warnings)
             console.log(`             ⚠ ${w}`);
     }
-    console.log(`\n${count("rendered")} rendered, ${count("skipped")} skipped, ` +
-        `${count("failed")} failed`);
+    console.log(`\n${count("rendered")} rendered, ${count("failed")} failed`);
     console.log(`Open ${join(outDir, "index.html")} to review.\n`);
 }
 function escapeHtml(text) {
@@ -198,7 +184,6 @@ function renderIndexHtml(quiverName, results) {
   .card { background: #fff; border: 1px solid #ddd; border-radius: 8px;
           padding: 1rem; margin: 1rem 0; }
   .card.failed { border-color: #e0b4b4; }
-  .card.skipped { opacity: 0.7; }
   h2 { font-size: 1rem; margin: 0 0 0.5rem; }
   .badge { font-size: 0.7rem; text-transform: uppercase; background: #eee;
            border-radius: 4px; padding: 2px 6px; vertical-align: middle; }

package/dist/testing.d.ts

@@ -7,14 +7,15 @@
  *
  * Usage (place this file next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Quillmark, Document } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
  *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine);
+ *   runQuiverTests(import.meta.url, engine, Document);
  *
  * Run with `node --test`.
  */
 import type { QuillmarkLike } from "./engine-types.js";
+import type { DocumentFactoryLike } from "./preview.js";
 /**
  * Registers a `node:test` describe block that validates every quill
  * version in the quiver at `metaUrlOrDir` against the provided engine.
@@ -23,6 +24,7 @@ import type { QuillmarkLike } from "./engine-types.js";
  * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
  * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
- * all template files, and engine compilation via engine.quill(tree).
+ * all template files, engine compilation via engine.quill(tree), and a
+ * full render of each quill's blueprint document.
  */
-export declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike): void;
+export declare function runQuiverTests(metaUrlOrDir: string, engine: QuillmarkLike, Document: DocumentFactoryLike): void;

package/dist/testing.js

@@ -7,10 +7,10 @@
  *
  * Usage (place this file next to your Quiver.yaml):
  *
- *   import { Quillmark } from "@quillmark/wasm";
+ *   import { Quillmark, Document } from "@quillmark/wasm";
  *   import { runQuiverTests } from "@quillmark/quiver/testing";
  *   const engine = new Quillmark();
- *   runQuiverTests(import.meta.url, engine);
+ *   runQuiverTests(import.meta.url, engine, Document);
  *
  * Run with `node --test`.
  */
@@ -27,9 +27,10 @@ import { Quiver } from "./node.js";
  * to Quiver.yaml). Pass an absolute directory path for any other layout.
  *
  * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml,
- * all template files, and engine compilation via engine.quill(tree).
+ * all template files, engine compilation via engine.quill(tree), and a
+ * full render of each quill's blueprint document.
  */
-export function runQuiverTests(metaUrlOrDir, engine) {
+export function runQuiverTests(metaUrlOrDir, engine, Document) {
     describe("Quiver", () => {
         let quiver;
         before(async () => {
@@ -40,12 +41,15 @@ export function runQuiverTests(metaUrlOrDir, engine) {
                 throw new Error("Quiver has no quills");
             }
         });
-        it("compiles every quill version without error", async () => {
+        it("compiles and renders every quill's blueprint without error", async () => {
             for (const name of quiver.quillNames()) {
                 for (const version of quiver.versionsOf(name)) {
-                    const quill = await quiver.getQuill(`${name}@${version}`, { engine });
-                    if (typeof quill.render !== "function") {
-                        throw new Error(`${name}@${version}: engine returned non-conforming Quill`);
+                    const ref = `${name}@${version}`;
+                    const quill = await quiver.getQuill(ref, { engine });
+                    const doc = Document.fromMarkdown(quill.blueprint);
+                    const result = quill.render(doc);
+                    if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
+                        throw new Error(`${ref}: blueprint render produced no artifacts`);
                     }
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Quiver registry and build tooling for Quillmark",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,9 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
+  "bin": {
+    "quiver": "./dist/bin/quiver.js"
+  },
   "scripts": {
     "build": "tsc",
     "test": "vitest run",