@quillmark/quiver 0.17.0 → 0.18.1

package/README.md

@@ -134,9 +134,9 @@ 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. `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.
+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.
 
-The CLI needs no file. Installing the package links `quiver` into `node_modules/.bin`, which npm puts on PATH for every script:
+The CLI needs no file. Installing the package links `quillmark-quiver` into `node_modules/.bin`, which npm puts on PATH for every script:
 
 ```sh
 npm install --save-dev @quillmark/quiver @quillmark/wasm
@@ -145,11 +145,11 @@ npm install --save-dev @quillmark/quiver @quillmark/wasm
 ```jsonc
 // package.json
 {
-	"scripts": { "test": "quiver test" }
+	"scripts": { "test": "quillmark-quiver 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`. `quiver build [--out <dir>]` packs the same source into a servable artifact.
+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:
 
@@ -158,7 +158,7 @@ On vitest, jest or `node:test`, spawn the bin from a test rather than rebuilding
 import { execFileSync } from 'node:child_process';
 
 it('gates the quiver', () => {
-	execFileSync('quiver', ['test'], { stdio: 'inherit' });
+	execFileSync('quillmark-quiver', ['test'], { stdio: 'inherit' });
 });
 ```
 

package/dist/bin/quiver.d.ts

@@ -5,8 +5,8 @@
  * Looking at rendered output is studio's, an app rather than a verb.
  *
  * Commands:
- *   quiver build [--out <dir>]
- *   quiver test
+ *   quillmark-quiver build [--out <dir>]
+ *   quillmark-quiver test
  *
  * Engine discovery (for `test`):
  *   1. Named export `engine` from `quiver.config.js` at the collection root,

package/dist/bin/quiver.js

@@ -5,8 +5,8 @@
  * Looking at rendered output is studio's, an app rather than a verb.
  *
  * Commands:
- *   quiver build [--out <dir>]
- *   quiver test
+ *   quillmark-quiver build [--out <dir>]
+ *   quillmark-quiver test
  *
  * Engine discovery (for `test`):
  *   1. Named export `engine` from `quiver.config.js` at the collection root,
@@ -72,7 +72,7 @@ async function loadEngine(cwd) {
 async function build() {
     const cwd = process.cwd();
     const outDir = flag('--out') ?? 'dist';
-    console.log(`quiver build: ${cwd} → ${outDir}`);
+    console.log(`quillmark-quiver build: ${cwd} → ${outDir}`);
     await buildQuiver(cwd, outDir);
     console.log('done.');
 }
@@ -121,7 +121,7 @@ async function test() {
 // Dispatch
 // ---------------------------------------------------------------------------
 function usage() {
-    console.error(['Usage:', '  quiver build [--out <dir>]', '  quiver test'].join('\n'));
+    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);

package/dist/build.d.ts

@@ -11,7 +11,7 @@
  * Output layout. Every name but the pointer carries the SHA-256 of what it
  * names, which is what the loader checks on fetch:
  *   outDir/
- *     latest.json                     # stable pointer to the current manifest
+ *     latest.json                     # the format, and a stable pointer to the manifest
  *     manifest.<sha256:12>.json       # hashed manifest
  *     <name>@<version>.<sha256:12>.zip  # one bundle per quill
  *     store/

package/dist/build.js

@@ -8,14 +8,15 @@
 import { QuiverError } from './errors.js';
 import { packFiles } from './bundle.js';
 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 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. `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.
+ * 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.
  *
  * An outDir *inside* sourceDir stays allowed: the scan reads the source before
  * any write, and `dist/` under the quiver root is the ordinary layout.
@@ -44,7 +45,7 @@ function assertSafeOutDir(path, sourceDir, outDir) {
  * Output layout. Every name but the pointer carries the SHA-256 of what it
  * names, which is what the loader checks on fetch:
  *   outDir/
- *     latest.json                     # stable pointer to the current manifest
+ *     latest.json                     # the format, and a stable pointer to the manifest
  *     manifest.<sha256:12>.json       # hashed manifest
  *     <name>@<version>.<sha256:12>.zip  # one bundle per quill
  *     store/
@@ -151,8 +152,9 @@ export async function buildQuiver(sourceDir, outDir) {
     catch (err) {
         throw new QuiverError('transport_error', `Failed to write manifest "${manifestPath}": ${err.message}`, { cause: err });
     }
-    // 9–10. Write stable pointer latest.json.
-    const pointer = { manifest: manifestFileName };
+    // 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');

package/dist/built-loader.js

@@ -9,6 +9,7 @@ import { QuiverError } from './errors.js';
 import { unpackFiles } from './bundle.js';
 import { isCanonicalSemver, compareSemver } from './semver.js';
 import { NAME_DIGEST_LENGTH, sha256Hex } from './digest.js';
+import { POINTER_FORMAT } from './format.js';
 import { createQuiver } from './quiver.js';
 /**
  * Fetch, then check the bytes against the digest their name carries. That
@@ -115,7 +116,18 @@ function parsePointer(raw) {
         throw new QuiverError('quiver_invalid', 'latest.json must be a JSON object');
     }
     const obj = parsed;
-    assertNoUnknownKeys(obj, ['manifest'], 'latest.json');
+    // The format, read before anything is believed about the rest. An unknown key is NOT
+    // a failure here: this is the document a newer format announces itself on, and a
+    // reader rejecting what it does not recognise refuses the announcement too. Absent
+    // means a build from before the marker (`format.ts`).
+    const format = obj['format'] ?? POINTER_FORMAT;
+    if (typeof format !== 'number' || !Number.isInteger(format) || format < 1) {
+        throw new QuiverError('quiver_invalid', `latest.json: "format" must be a positive integer, got ${JSON.stringify(obj['format'])}`);
+    }
+    if (format > POINTER_FORMAT) {
+        throw new QuiverError('quiver_invalid', `This quiver is built in format ${format} and this loader reads ${POINTER_FORMAT}. ` +
+            `Upgrade @quillmark/quiver, or for a served client the client itself, which carries the copy that reads this.`);
+    }
     if (typeof obj['manifest'] !== 'string' || obj['manifest'].length === 0) {
         throw new QuiverError('quiver_invalid', 'latest.json must have a non-empty string "manifest" field');
     }

package/dist/format.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The built artifact's format, stamped into `latest.json` and refused to be read past
+ * (QUIVER §"The pointer" for why the pointer carries it and reads past keys it does not
+ * know).
+ *
+ * It moves when a reader assuming it would MISREAD a tree rather than fail on it: a
+ * renamed pointer field, a second pointer, a store keyed by something other than the
+ * full hash. A change confined to the manifest's own shape moves the manifest's
+ * `version` instead.
+ */
+export declare const POINTER_FORMAT = 1;

package/dist/format.js

@@ -0,0 +1,11 @@
+/**
+ * The built artifact's format, stamped into `latest.json` and refused to be read past
+ * (QUIVER §"The pointer" for why the pointer carries it and reads past keys it does not
+ * know).
+ *
+ * It moves when a reader assuming it would MISREAD a tree rather than fail on it: a
+ * renamed pointer field, a second pointer, a store keyed by something other than the
+ * full hash. A change confined to the manifest's own shape moves the manifest's
+ * `version` instead.
+ */
+export const POINTER_FORMAT = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quillmark/quiver",
-	"version": "0.17.0",
+	"version": "0.18.1",
 	"description": "Quiver registry and build tooling for Quillmark",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -26,11 +26,13 @@
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
 		},
 		"./node": {
 			"types": "./dist/node.d.ts",
-			"import": "./dist/node.js"
+			"import": "./dist/node.js",
+			"default": "./dist/node.js"
 		}
 	},
 	"sideEffects": false,
@@ -52,7 +54,7 @@
 		"vitest": "^4.0.18"
 	},
 	"bin": {
-		"quiver": "./dist/bin/quiver.js"
+		"quillmark-quiver": "./dist/bin/quiver.js"
 	},
 	"scripts": {
 		"build": "tsc",