@quillmark/quiver 0.18.1 → 0.19.0

package/README.md

@@ -62,7 +62,7 @@ import { build } from '@quillmark/quiver/node';
 await build('./node_modules/@org/my-quiver', './public/quivers/my-quiver');
 ```
 
-`build` clears its output directory before writing, so it owns that path outright. An `outDir` that is, or contains, the source quiver or the working directory is refused with a `transport_error` rather than deleted.
+`build` owns its output path outright: it assembles a generation in `<outDir>.stage`, moves it in whole, and deletes the one it replaced. A reader fetching mid-build sees the previous generation rather than a torn tree, and a build that throws leaves it serving. An `outDir` that is, or contains, the source quiver or the working directory is refused with a `transport_error` rather than deleted.
 
 ```ts
 // browser runtime
@@ -134,32 +134,17 @@ A consumer reaches an installed quiver by resolving `<specifier>/Quiver.yaml`, w
 }
 ```
 
-Gate the quiver in CI so a validation failure surfaces on publish rather than on a consumer's build. `quillmark-quiver test` loads with `fromDir`, compiles every quill, and renders each quill's example document. One door, so what you run locally is what CI runs.
+## Authoring is [quillkit](../quillkit#readme)'s
 
-The CLI needs no file. Installing the package links `quillmark-quiver` into `node_modules/.bin`, which npm puts on PATH for every script:
+This package is a library: it loads a quiver and packs one, and it has no CLI. The verbs a quill author runs (gate, pack, look at, deploy) are `quillkit`'s, and it resolves this package out of the collection's own `node_modules`. Depend on it here and the version you pin is the format your quiver is packed in:
 
 ```sh
-npm install --save-dev @quillmark/quiver @quillmark/wasm
+npm install --save-dev @quillmark/quiver @quillmark/wasm quillkit
 ```
 
 ```jsonc
 // package.json
 {
-	"scripts": { "test": "quillmark-quiver test" }
+	"scripts": { "test": "quillkit test" }
 }
 ```
-
-It finds the engine itself: a named `engine` export from `quiver.config.js` at the collection root, else `@quillmark/wasm` from your own `node_modules`. `quillmark-quiver build [--out <dir>]` packs the same source into a servable artifact.
-
-On vitest, jest or `node:test`, spawn the bin from a test rather than rebuilding the loop against the main API. The gate stays one implementation, and the case gates what CI gates:
-
-```ts
-// quiver.test.ts
-import { execFileSync } from 'node:child_process';
-
-it('gates the quiver', () => {
-	execFileSync('quillmark-quiver', ['test'], { stdio: 'inherit' });
-});
-```
-
-It answers _does it work_, and that is the whole of what this package offers a quill author: _what is it like to use_ is answered by working a real document through the quill live, which is an app rather than a subpath.

package/dist/build.d.ts

@@ -17,6 +17,10 @@
  *     store/
  *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
+ * A generation is assembled beside outDir and moved in whole, so a reader
+ * fetching mid-build reads the previous one rather than a torn tree, and a
+ * build that throws leaves the previous one serving.
+ *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
  *   - `transport_error` on I/O failures, and on an outDir the build would have

package/dist/build.js

@@ -11,12 +11,20 @@ import { NAME_DIGEST_LENGTH } from './digest.js';
 import { POINTER_FORMAT } from './format.js';
 /** Font file extensions recognised by the builder (case-insensitive). */
 const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
+/** The two trees a build owns beside its output: where a generation is assembled, and
+ *  where the one it replaces waits to be deleted. Siblings of outDir, so the swap is a
+ *  rename rather than a copy across filesystems. */
+const stagesOf = (out) => ({
+    stage: `${out}.stage`,
+    prev: `${out}.prev`
+});
 /**
- * The build's first act is `rm(outDir, { recursive: true })`, so an outDir that
- * is, or contains, the source quiver or the working directory deletes the
- * thing the caller was building from. `quillmark-quiver build --out .` and a
- * mistyped `--out ..` are both one keystroke away, and the failure is
- * unrecoverable, so an outDir that owns the caller is refused up front.
+ * The build deletes each of the three trees it owns, so an outDir that is, or contains,
+ * the source quiver or the working directory deletes the thing the caller was building
+ * from. `quillkit build --out .` and a mistyped `--out ..` are both one keystroke away,
+ * and the failure is unrecoverable, so an outDir that owns the caller is refused up
+ * front. The staging siblings are checked too: they are named off outDir and cleared
+ * with it, so a caller who avoids one spelling has not avoided the others.
  *
  * An outDir *inside* sourceDir stays allowed: the scan reads the source before
  * any write, and `dist/` under the quiver root is the ordinary layout.
@@ -25,18 +33,19 @@ const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
  */
 function assertSafeOutDir(path, sourceDir, outDir) {
     const out = path.resolve(outDir);
-    /** True when `dir` is `target` or an ancestor of it. */
-    const owns = (target) => {
-        const rel = path.relative(out, path.resolve(target));
+    const { stage, prev } = stagesOf(out);
+    /** True when one of the owned trees is `target` or an ancestor of it. */
+    const owns = (target) => [out, stage, prev].some((dir) => {
+        const rel = path.relative(dir, path.resolve(target));
         return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-    };
+    });
     const what = owns(sourceDir)
         ? 'the source quiver'
         : owns(process.cwd())
             ? 'the working directory'
             : undefined;
     if (what !== undefined) {
-        throw new QuiverError('transport_error', `Refusing to build into "${outDir}": the build clears its output directory, and this one holds ${what} ("${out}"). Point --out at a directory the build owns.`);
+        throw new QuiverError('transport_error', `Refusing to build into "${outDir}": the build clears that directory and two staging siblings beside it, and this one holds ${what} ("${out}"). Point --out somewhere the build can own outright.`);
     }
 }
 /**
@@ -51,6 +60,10 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  *     store/
  *       <sha256>                      # dehydrated font bytes (full hash, no ext)
  *
+ * A generation is assembled beside outDir and moved in whole, so a reader
+ * fetching mid-build reads the previous one rather than a torn tree, and a
+ * build that throws leaves the previous one serving.
+ *
  * Throws:
  *   - `quiver_invalid` on source validation failures (propagated from scanner)
  *   - `transport_error` on I/O failures, and on an outDir the build would have
@@ -59,107 +72,139 @@ function assertSafeOutDir(path, sourceDir, outDir) {
 export async function buildQuiver(sourceDir, outDir) {
     // Dynamic imports keep this module safe to type-import from browser contexts.
     const path = await import('node:path');
-    const { join } = path;
-    const { mkdir, rm, writeFile } = await import('node:fs/promises');
+    const { dirname, join, resolve } = path;
+    const { mkdir, rename, rm, writeFile } = await import('node:fs/promises');
+    const { existsSync } = await import('node:fs');
     const { createHash } = await import('node:crypto');
     const { scanSourceQuiver, readQuillTree } = await import('./source-loader.js');
-    // 0. The first write is a recursive delete of outDir; refuse the paths where
-    //    that deletes the caller instead of a previous build.
+    // 0. Three trees get cleared here; refuse the paths where that deletes the
+    //    caller instead of a previous build.
     assertSafeOutDir(path, sourceDir, outDir);
+    const out = resolve(outDir);
+    const { stage, prev } = stagesOf(out);
     // 1. Scan + validate source quiver (throws quiver_invalid on bad input).
     const { meta, catalog } = await scanSourceQuiver(sourceDir);
-    // 2. Clear and recreate outDir + outDir/store/.
     try {
-        await rm(outDir, { recursive: true, force: true });
-        await mkdir(join(outDir, 'store'), { recursive: true });
+        await packGeneration();
     }
-    catch (err) {
-        throw new QuiverError('transport_error', `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
+    finally {
+        // A throw anywhere above leaves a partial generation staged, and outDir
+        // untouched. Neither tree outlives the call either way. Swept rather than
+        // checked: a sweep that threw would answer for the build, and what a caller
+        // needs to hear is why the build failed.
+        for (const at of [stage, prev])
+            await rm(at, { recursive: true, force: true }).catch(() => { });
     }
-    // 3. Process each quill version.
-    const manifestQuills = [];
-    for (const [quillName, versions] of catalog) {
-        for (const version of versions) {
-            const quillDir = join(sourceDir, 'quills', quillName, version);
-            // a. Read quill file tree.
-            const tree = await readQuillTree(quillDir);
-            // b. Partition fonts vs content.
-            const fontEntries = [];
-            const contentEntries = [];
-            for (const [path, bytes] of tree) {
-                if (FONT_EXT.test(path)) {
-                    fontEntries.push([path, bytes]);
+    /**
+     * Write a whole generation into `stage`, then move it to outDir.
+     *
+     * The move is two renames: a directory rename refuses a non-empty target, so the
+     * outgoing generation steps aside first. That is the window, and it is two syscalls
+     * wide against the seconds a build takes.
+     */
+    async function packGeneration() {
+        // 2. Clear and recreate the staged tree + its store/.
+        try {
+            await rm(stage, { recursive: true, force: true });
+            await mkdir(join(stage, 'store'), { recursive: true });
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Failed to prepare output directory "${outDir}": ${err.message}`, { cause: err });
+        }
+        // 3. Process each quill version.
+        const manifestQuills = [];
+        for (const [quillName, versions] of catalog) {
+            for (const version of versions) {
+                const quillDir = join(sourceDir, 'quills', quillName, version);
+                // a. Read quill file tree.
+                const tree = await readQuillTree(quillDir);
+                // b. Partition fonts vs content.
+                const fontEntries = [];
+                const contentEntries = [];
+                for (const [path, bytes] of tree) {
+                    if (FONT_EXT.test(path)) {
+                        fontEntries.push([path, bytes]);
+                    }
+                    else {
+                        contentEntries.push([path, bytes]);
+                    }
                 }
-                else {
-                    contentEntries.push([path, bytes]);
+                // c. Dehydrate fonts into store/.
+                const fonts = {};
+                for (const [path, bytes] of fontEntries) {
+                    // Full width: the store is keyed by hash, so two distinct fonts
+                    // sharing a prefix would merge into one entry.
+                    const hash = createHash('sha256').update(bytes).digest('hex');
+                    try {
+                        await writeFile(join(stage, 'store', hash), bytes);
+                    }
+                    catch (err) {
+                        throw new QuiverError('transport_error', `Failed to write font store entry "${join(outDir, 'store', hash)}": ${err.message}`, { cause: err });
+                    }
+                    fonts[path] = hash;
                 }
-            }
-            // c. Dehydrate fonts into store/.
-            const fonts = {};
-            for (const [path, bytes] of fontEntries) {
-                // Full width: the store is keyed by hash, so two distinct fonts
-                // sharing a prefix would merge into one entry.
-                const hash = createHash('sha256').update(bytes).digest('hex');
-                const storePath = join(outDir, 'store', hash);
+                // d. Zip content files (deterministic: sorted paths, fixed mtime).
+                const contentRecord = {};
+                for (const [path, bytes] of contentEntries) {
+                    contentRecord[path] = bytes;
+                }
+                const zipBytes = packFiles(contentRecord);
+                // e–f. Compute bundle hash and name.
+                const bundleHash = createHash('sha256')
+                    .update(zipBytes)
+                    .digest('hex')
+                    .slice(0, NAME_DIGEST_LENGTH);
+                const bundleName = `${quillName}@${version}.${bundleHash}.zip`;
+                // g. Write bundle zip.
                 try {
-                    await writeFile(storePath, bytes);
+                    await writeFile(join(stage, bundleName), zipBytes);
                 }
                 catch (err) {
-                    throw new QuiverError('transport_error', `Failed to write font store entry "${storePath}": ${err.message}`, { cause: err });
+                    throw new QuiverError('transport_error', `Failed to write bundle "${join(outDir, bundleName)}": ${err.message}`, { cause: err });
                 }
-                fonts[path] = hash;
+                // h. Record manifest entry.
+                manifestQuills.push({ name: quillName, version, bundle: bundleName, fonts });
             }
-            // d. Zip content files (deterministic: sorted paths, fixed mtime).
-            const contentRecord = {};
-            for (const [path, bytes] of contentEntries) {
-                contentRecord[path] = bytes;
-            }
-            const zipBytes = packFiles(contentRecord);
-            // e–f. Compute bundle hash and name.
-            const bundleHash = createHash('sha256')
-                .update(zipBytes)
-                .digest('hex')
-                .slice(0, NAME_DIGEST_LENGTH);
-            const bundleName = `${quillName}@${version}.${bundleHash}.zip`;
-            // g. Write bundle zip.
-            const bundlePath = join(outDir, bundleName);
-            try {
-                await writeFile(bundlePath, zipBytes);
-            }
-            catch (err) {
-                throw new QuiverError('transport_error', `Failed to write bundle "${bundlePath}": ${err.message}`, { cause: err });
-            }
-            // h. Record manifest entry.
-            manifestQuills.push({ name: quillName, version, bundle: bundleName, fonts });
         }
-    }
-    // 4–8. Build and write hashed manifest.
-    const manifest = {
-        version: 1,
-        name: meta.name,
-        quills: manifestQuills
-    };
-    const manifestJson = JSON.stringify(manifest, null, 2);
-    const manifestHash = createHash('sha256')
-        .update(manifestJson)
-        .digest('hex')
-        .slice(0, NAME_DIGEST_LENGTH);
-    const manifestFileName = `manifest.${manifestHash}.json`;
-    const manifestPath = join(outDir, manifestFileName);
-    try {
-        await writeFile(manifestPath, manifestJson, 'utf-8');
-    }
-    catch (err) {
-        throw new QuiverError('transport_error', `Failed to write manifest "${manifestPath}": ${err.message}`, { cause: err });
-    }
-    // 9–10. Write stable pointer latest.json. The format is stamped here and read first,
-    //       so a client older than the tree says so rather than misreading it.
-    const pointer = { format: POINTER_FORMAT, manifest: manifestFileName };
-    const pointerPath = join(outDir, 'latest.json');
-    try {
-        await writeFile(pointerPath, JSON.stringify(pointer), 'utf-8');
-    }
-    catch (err) {
-        throw new QuiverError('transport_error', `Failed to write pointer "${pointerPath}": ${err.message}`, { cause: err });
+        // 4–8. Build and write hashed manifest.
+        const manifest = {
+            version: 1,
+            name: meta.name,
+            quills: manifestQuills
+        };
+        const manifestJson = JSON.stringify(manifest, null, 2);
+        const manifestHash = createHash('sha256')
+            .update(manifestJson)
+            .digest('hex')
+            .slice(0, NAME_DIGEST_LENGTH);
+        const manifestFileName = `manifest.${manifestHash}.json`;
+        try {
+            await writeFile(join(stage, manifestFileName), manifestJson, 'utf-8');
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Failed to write manifest "${join(outDir, manifestFileName)}": ${err.message}`, { cause: err });
+        }
+        // 9–10. Write stable pointer latest.json. The format is stamped here and read first,
+        //       so a client older than the tree says so rather than misreading it.
+        const pointer = { format: POINTER_FORMAT, manifest: manifestFileName };
+        try {
+            await writeFile(join(stage, 'latest.json'), JSON.stringify(pointer), 'utf-8');
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Failed to write pointer "${join(outDir, 'latest.json')}": ${err.message}`, { cause: err });
+        }
+        // 11. Move the generation in. `prev` is cleared first: a rename onto a
+        //     non-empty directory fails, and the tree left by an interrupted run is
+        //     one.
+        try {
+            await mkdir(dirname(out), { recursive: true });
+            await rm(prev, { recursive: true, force: true });
+            if (existsSync(out))
+                await rename(out, prev);
+            await rename(stage, out);
+        }
+        catch (err) {
+            throw new QuiverError('transport_error', `Failed to move the build into "${outDir}": ${err.message}`, { cause: err });
+        }
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.18.1",
-	"description": "Quiver registry and build tooling for Quillmark",
+	"version": "0.19.0",
+	"description": "A quiver of Quillmark quills: load one, pack one, hand out quills.",
 	"type": "module",
 	"license": "Apache-2.0",
 	"repository": {
@@ -53,9 +53,6 @@
 		"typescript": "^5.9.3",
 		"vitest": "^4.0.18"
 	},
-	"bin": {
-		"quillmark-quiver": "./dist/bin/quiver.js"
-	},
 	"scripts": {
 		"build": "tsc",
 		"prepare": "npm run build",

package/dist/bin/quiver.d.ts

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-/**
- * Quiver CLI — build and test a quiver collection. Two verbs, and they are the
- * whole of what a quiver author gets from here: `build` packs, `test` gates.
- * Looking at rendered output is studio's, an app rather than a verb.
- *
- * Commands:
- *   quillmark-quiver build [--out <dir>]
- *   quillmark-quiver test
- *
- * Engine discovery (for `test`):
- *   1. Named export `engine` 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

@@ -1,141 +0,0 @@
-#!/usr/bin/env node
-/**
- * Quiver CLI — build and test a quiver collection. Two verbs, and they are the
- * whole of what a quiver author gets from here: `build` packs, `test` gates.
- * Looking at rendered output is studio's, an app rather than a verb.
- *
- * Commands:
- *   quillmark-quiver build [--out <dir>]
- *   quillmark-quiver test
- *
- * Engine discovery (for `test`):
- *   1. Named export `engine` 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 { build as buildQuiver, fromDir } from '../node.js';
-// ---------------------------------------------------------------------------
-// Arg parsing helpers
-// ---------------------------------------------------------------------------
-const argv = process.argv.slice(2);
-const command = argv[0];
-/** One flag with a value. `build --out` is the only one either verb takes. */
-function flag(name) {
-    const i = argv.indexOf(name);
-    return i !== -1 && i + 1 < argv.length ? argv[i + 1] : undefined;
-}
-// ---------------------------------------------------------------------------
-// Engine discovery
-// ---------------------------------------------------------------------------
-async function loadEngine(cwd) {
-    // Resolve @quillmark/wasm from the collection's node_modules (best-effort).
-    // Its `Engine` renders every quill (cloning the core Quill/Document into the
-    // backend itself). A quiver.config.js may export a custom `engine`.
-    let wasm;
-    try {
-        const req = createRequire(pathToFileURL(join(cwd, 'package.json')).href);
-        const wasmPath = req.resolve('@quillmark/wasm');
-        wasm = (await import(pathToFileURL(wasmPath).href));
-        // Instantiate the core. Every `@quillmark/wasm` export throws
-        // `runtime::not_initialized` until `init()` resolves, and `new Engine()` is
-        // lazy, so without this the throw arrives at the first render and reads as a
-        // failing quill rather than an uninitialized runtime.
-        await wasm.init();
-    }
-    catch {
-        // Not installed — a quiver.config.js may still provide an engine.
-    }
-    // 1. Named `engine` export from quiver.config.js, if present.
-    try {
-        const cfg = await import(pathToFileURL(join(cwd, 'quiver.config.js')).href);
-        if (cfg.engine != null) {
-            return cfg.engine;
-        }
-    }
-    catch {
-        // File absent or incomplete — fall through to auto-discovery.
-    }
-    // 2. Auto-discover from @quillmark/wasm.
-    if (wasm == null) {
-        throw new Error("Cannot find @quillmark/wasm in this collection's node_modules.\n" +
-            '  Install it:  npm install @quillmark/wasm\n' +
-            '  Or export { engine } from quiver.config.js for a custom engine.');
-    }
-    return new wasm.Engine();
-}
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-async function build() {
-    const cwd = process.cwd();
-    const outDir = flag('--out') ?? 'dist';
-    console.log(`quillmark-quiver build: ${cwd} → ${outDir}`);
-    await buildQuiver(cwd, outDir);
-    console.log('done.');
-}
-async function test() {
-    const cwd = process.cwd();
-    const engine = await loadEngine(cwd);
-    const quiver = await 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);
-                const doc = quill.seedDocument();
-                let result;
-                try {
-                    result = await engine.render(quill, doc);
-                }
-                finally {
-                    doc.free();
-                }
-                if (!Array.isArray(result.artifacts) || result.artifacts.length === 0) {
-                    throw new Error('example 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);
-}
-// ---------------------------------------------------------------------------
-// Dispatch
-// ---------------------------------------------------------------------------
-function usage() {
-    console.error(['Usage:', '  quillmark-quiver build [--out <dir>]', '  quillmark-quiver test'].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;
-    default:
-        usage();
-        process.exit(1);
-}