@quillmark/quiver 0.1.0 → 0.2.0

package/dist/assert-node.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Throws a `transport_error` when called outside a Node.js environment.
+ * Call at the top of each Node-only static factory to fail fast in browsers.
+ */
+export declare function assertNode(method: string): void;

package/dist/assert-node.js

@@ -0,0 +1,12 @@
+import { QuiverError } from "./errors.js";
+/**
+ * Throws a `transport_error` when called outside a Node.js environment.
+ * Call at the top of each Node-only static factory to fail fast in browsers.
+ */
+export function assertNode(method) {
+    if (typeof globalThis.process === "undefined" ||
+        !globalThis.process
+            ?.versions?.node) {
+        throw new QuiverError("transport_error", `${method} is only available in Node.js`);
+    }
+}

package/dist/bundle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Zip utilities — browser-safe (uses fflate only).
+ */
+/**
+ * Pack a flat file map into a deterministic zip.
+ * Keys are sorted before zipping so insertion order doesn't affect output.
+ */
+export declare function packFiles(files: Record<string, Uint8Array>): Uint8Array;
+/**
+ * Unpack a zip into a flat file map.
+ * Returns { path: Uint8Array } for every file entry in the archive.
+ */
+export declare function unpackFiles(data: Uint8Array): Record<string, Uint8Array>;

package/dist/bundle.js

@@ -0,0 +1,33 @@
+/**
+ * Zip utilities — browser-safe (uses fflate only).
+ */
+import { zipSync, unzipSync } from "fflate";
+/**
+ * Fixed epoch mtime for deterministic zip output.
+ * All entries get this timestamp so byte-identical inputs → byte-identical zips.
+ */
+const ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
+/**
+ * Pack a flat file map into a deterministic zip.
+ * Keys are sorted before zipping so insertion order doesn't affect output.
+ */
+export function packFiles(files) {
+    const sorted = Object.keys(files).sort();
+    const input = {};
+    for (const key of sorted) {
+        input[key] = [files[key], { mtime: ZIP_EPOCH }];
+    }
+    return zipSync(input, { level: 6 });
+}
+/**
+ * Unpack a zip into a flat file map.
+ * Returns { path: Uint8Array } for every file entry in the archive.
+ */
+export function unpackFiles(data) {
+    const raw = unzipSync(data);
+    const result = {};
+    for (const [key, value] of Object.entries(raw)) {
+        result[key] = value;
+    }
+    return result;
+}

package/dist/engine-types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal structural types matching @quillmark/wasm >=0.57.0 (verified against 0.59.0-rc.2).
+ *
+ * Shape:
+ *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }
+ *   class Quill     { render(doc, opts?): RenderResult; open(doc): RenderSession }
+ *
+ * Note: as of 0.59.0-rc.2 the first arg to render/open is a `Document` instance
+ * (from `Document.fromMarkdown(...)`), not the old `ParsedDocument` interface.
+ * Quiver keeps the arg typed as `unknown` so consumers of either shape (and
+ * test doubles) satisfy the contract structurally.
+ *
+ * These types are INTERNAL — never re-exported from index.ts. They exist so
+ * registry.ts never imports from @quillmark/wasm directly and so test doubles
+ * can satisfy the contract without pulling the real WASM module.
+ *
+ * Call-site note: Quiver never invokes `render` or `open` itself; consumers do
+ * after `getQuill()`. The loose `unknown` parameter typing is intentional.
+ */
+export interface QuillmarkLike {
+    quill(tree: Map<string, Uint8Array>): QuillLike;
+}
+export interface QuillLike {
+    render(doc: unknown, opts?: unknown): unknown;
+    open?: (doc: unknown) => unknown;
+}

package/dist/engine-types.js

@@ -0,0 +1,20 @@
+/**
+ * Minimal structural types matching @quillmark/wasm >=0.57.0 (verified against 0.59.0-rc.2).
+ *
+ * Shape:
+ *   class Quillmark { quill(tree: Map<string, Uint8Array>): Quill }
+ *   class Quill     { render(doc, opts?): RenderResult; open(doc): RenderSession }
+ *
+ * Note: as of 0.59.0-rc.2 the first arg to render/open is a `Document` instance
+ * (from `Document.fromMarkdown(...)`), not the old `ParsedDocument` interface.
+ * Quiver keeps the arg typed as `unknown` so consumers of either shape (and
+ * test doubles) satisfy the contract structurally.
+ *
+ * These types are INTERNAL — never re-exported from index.ts. They exist so
+ * registry.ts never imports from @quillmark/wasm directly and so test doubles
+ * can satisfy the contract without pulling the real WASM module.
+ *
+ * Call-site note: Quiver never invokes `render` or `open` itself; consumers do
+ * after `getQuill()`. The loose `unknown` parameter typing is intentional.
+ */
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+export type QuiverErrorCode = "invalid_ref" | "quill_not_found" | "quiver_invalid" | "transport_error" | "quiver_collision";
+export declare class QuiverError extends Error {
+    readonly code: QuiverErrorCode;
+    /** Offending ref string, when available. */
+    readonly ref?: string;
+    /** Offending version, when available. */
+    readonly version?: string;
+    /** Quiver `name` from Quiver.yaml, when available. */
+    readonly quiverName?: string;
+    constructor(code: QuiverErrorCode, message: string, options?: {
+        ref?: string;
+        version?: string;
+        quiverName?: string;
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+export class QuiverError extends Error {
+    code;
+    /** Offending ref string, when available. */
+    ref;
+    /** Offending version, when available. */
+    version;
+    /** Quiver `name` from Quiver.yaml, when available. */
+    quiverName;
+    constructor(code, message, options) {
+        super(message, { cause: options?.cause });
+        this.name = "QuiverError";
+        this.code = code;
+        this.ref = options?.ref;
+        this.version = options?.version;
+        this.quiverName = options?.quiverName;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { QuiverError } from "./errors.js";
+export type { QuiverErrorCode } from "./errors.js";
+export { Quiver } from "./quiver.js";
+export { QuiverRegistry } from "./registry.js";
+export type { PackOptions } from "./pack.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// Main browser-safe entrypoint.
+export { QuiverError } from "./errors.js";
+export { Quiver } from "./quiver.js";
+export { QuiverRegistry } from "./registry.js";

package/dist/node.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/node.js

@@ -0,0 +1,5 @@
+// Node-only entrypoint.
+// Re-export everything from the main browser-safe entrypoint.
+// Node-only factories (fromSourceDir, fromPackedDir, pack) are methods on
+// Quiver itself — no additional exports are needed here.
+export * from "./index.js";

package/dist/pack.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pack logic — internal, Node-only.
+ *
+ * All Node.js built-in imports are done dynamically inside `packQuiver` so
+ * that a type-only import of `PackOptions` from `src/index.ts` does NOT
+ * pull `node:fs` or `node:crypto` into browser bundles.
+ */
+/** Reserved for future pack options (e.g. compression level, filters). */
+export type PackOptions = Record<string, never>;
+/**
+ * Reads a Source Quiver, validates it, and writes a Packed Quiver to outDir.
+ *
+ * Output layout:
+ *   outDir/
+ *     Quiver.json                   # stable pointer
+ *     manifest.<md5prefix6>.json    # hashed manifest
+ *     <name>@<version>.<md5>.zip    # one bundle per quill
+ *     store/
+ *       <md5>                       # dehydrated font bytes (full hash, no ext)
+ *
+ * Throws:
+ *   - `quiver_invalid` on source validation failures (propagated from scanner)
+ *   - `transport_error` on I/O failures
+ */
+export declare function packQuiver(sourceDir: string, outDir: string, _opts?: PackOptions): Promise<void>;

package/dist/pack.js

@@ -0,0 +1,120 @@
+/**
+ * Pack logic — internal, Node-only.
+ *
+ * All Node.js built-in imports are done dynamically inside `packQuiver` so
+ * that a type-only import of `PackOptions` from `src/index.ts` does NOT
+ * pull `node:fs` or `node:crypto` into browser bundles.
+ */
+import { QuiverError } from "./errors.js";
+import { packFiles } from "./bundle.js";
+/** Font file extensions recognised by the packer (case-insensitive). */
+const FONT_EXT = /\.(ttf|otf|woff|woff2)$/i;
+/**
+ * Reads a Source Quiver, validates it, and writes a Packed Quiver to outDir.
+ *
+ * Output layout:
+ *   outDir/
+ *     Quiver.json                   # stable pointer
+ *     manifest.<md5prefix6>.json    # hashed manifest
+ *     <name>@<version>.<md5>.zip    # one bundle per quill
+ *     store/
+ *       <md5>                       # dehydrated font bytes (full hash, no ext)
+ *
+ * Throws:
+ *   - `quiver_invalid` on source validation failures (propagated from scanner)
+ *   - `transport_error` on I/O failures
+ */
+export async function packQuiver(sourceDir, outDir, _opts) {
+    // Dynamic imports keep this module safe to type-import from browser contexts.
+    const { join } = await import("node:path");
+    const { mkdir, rm, writeFile, } = await import("node:fs/promises");
+    const { createHash } = await import("node:crypto");
+    const { scanSourceQuiver, readQuillTree } = await import("./source-loader.js");
+    // 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 });
+    }
+    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]);
+                }
+            }
+            // c. Dehydrate fonts into store/.
+            const fonts = {};
+            for (const [path, bytes] of fontEntries) {
+                const hash = createHash("md5").update(bytes).digest("hex");
+                const storePath = join(outDir, "store", hash);
+                try {
+                    await writeFile(storePath, bytes);
+                }
+                catch (err) {
+                    throw new QuiverError("transport_error", `Failed to write font store entry "${storePath}": ${err.message}`, { cause: err });
+                }
+                fonts[path] = 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("md5").update(zipBytes).digest("hex").slice(0, 6);
+            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("md5").update(manifestJson).digest("hex").slice(0, 6);
+    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 Quiver.json.
+    const pointer = { manifest: manifestFileName };
+    const pointerPath = join(outDir, "Quiver.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 });
+    }
+}

package/dist/packed-loader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Packed Quiver loader — browser-safe at module level.
+ * Internal; not exported from index.ts.
+ *
+ * Exposes:
+ *   - PackedTransport interface (also used by FsTransport / HttpTransport)
+ *   - loadPackedQuiver(transport) → Quiver
+ *
+ * NO static node: imports — this module is safe to load in browser contexts.
+ */
+import { Quiver } from "./quiver.js";
+/**
+ * Transport abstraction: fetch raw bytes by relative path within the packed
+ * artifact. Implementations are FsTransport (Node) and HttpTransport (browser).
+ */
+export interface PackedTransport {
+    fetchBytes(relativePath: string): Promise<Uint8Array>;
+}
+/**
+ * Load a Packed Quiver via the given transport.
+ *
+ * 1. Fetches Quiver.json (pointer) and parses it.
+ * 2. Fetches the manifest file it points to and validates it.
+ * 3. Builds a catalog from manifest entries (versions sorted descending).
+ * 4. Returns a Quiver instance backed by a PackedLoader.
+ */
+export declare function loadPackedQuiver(transport: PackedTransport): Promise<Quiver>;

package/dist/packed-loader.js

@@ -0,0 +1,232 @@
+/**
+ * Packed Quiver loader — browser-safe at module level.
+ * Internal; not exported from index.ts.
+ *
+ * Exposes:
+ *   - PackedTransport interface (also used by FsTransport / HttpTransport)
+ *   - loadPackedQuiver(transport) → Quiver
+ *
+ * NO static node: imports — this module is safe to load in browser contexts.
+ */
+import { QuiverError } from "./errors.js";
+import { unpackFiles } from "./bundle.js";
+import { isCanonicalSemver, compareSemver } from "./semver.js";
+import { Quiver } from "./quiver.js";
+// ─── Path validation ──────────────────────────────────────────────────────────
+const MANIFEST_FILENAME_RE = /^manifest\.[0-9a-f]+\.json$/;
+const BUNDLE_FILENAME_RE = /^[A-Za-z0-9_.-]+@[0-9]+\.[0-9]+\.[0-9]+\.[0-9a-f]+\.zip$/;
+const FONT_HASH_RE = /^[0-9a-f]{32}$/;
+function validateManifestFileName(name) {
+    if (!MANIFEST_FILENAME_RE.test(name)) {
+        throw new QuiverError("quiver_invalid", `Pointer manifest filename is invalid: "${name}"`);
+    }
+}
+function validateBundleFileName(bundle, context) {
+    if (!BUNDLE_FILENAME_RE.test(bundle)) {
+        throw new QuiverError("quiver_invalid", `${context}: bundle filename is invalid: "${bundle}"`);
+    }
+}
+function validateFontHash(hash, context) {
+    if (!FONT_HASH_RE.test(hash)) {
+        throw new QuiverError("quiver_invalid", `${context}: font hash is invalid: "${hash}"`);
+    }
+}
+// ─── PackedLoader implementation ─────────────────────────────────────────────
+class PackedLoader {
+    transport;
+    index;
+    /** Font byte cache: hash → in-flight or resolved Promise. */
+    fontCache = new Map();
+    constructor(transport, 
+    /** Index map from "name@version" to its manifest entry. */
+    index) {
+        this.transport = transport;
+        this.index = index;
+    }
+    async loadTree(name, version) {
+        const entry = this.index.get(`${name}@${version}`);
+        // If entry is missing, the outer Quiver.loadTree gate already validated
+        // that this name/version is in the catalog; trust that gate and fall
+        // through. The transport will surface a transport_error naturally.
+        // (Defensive: this should not be reachable in normal operation.)
+        if (!entry) {
+            throw new QuiverError("transport_error", `Quill "${name}@${version}" not found in packed quiver manifest`, { version, ref: `${name}@${version}` });
+        }
+        // 1. Fetch + unpack bundle zip.
+        const zipBytes = await this.transport.fetchBytes(entry.bundle);
+        const files = unpackFiles(zipBytes);
+        // 2. Rehydrate fonts from store (coalesced).
+        const fontEntries = Object.entries(entry.fonts);
+        await Promise.all(fontEntries.map(async ([path, hash]) => {
+            files[path] = await this.fetchFont(hash);
+        }));
+        // 3. Convert to Map.
+        return new Map(Object.entries(files));
+    }
+    /**
+     * Fetch a font by hash from store/<hash>, coalescing concurrent requests for
+     * the same hash into a single fetch. On error, removes the cache entry so
+     * callers can retry.
+     */
+    fetchFont(hash) {
+        let promise = this.fontCache.get(hash);
+        if (!promise) {
+            promise = this.transport
+                .fetchBytes(`store/${hash}`)
+                .catch((err) => {
+                this.fontCache.delete(hash);
+                throw err;
+            });
+            this.fontCache.set(hash, promise);
+        }
+        return promise;
+    }
+}
+// ─── Pointer + manifest validation helpers ────────────────────────────────────
+function assertNoUnknownKeys(obj, allowed, context) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            throw new QuiverError("quiver_invalid", `${context}: unknown field "${key}"`);
+        }
+    }
+}
+function parsePointer(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new QuiverError("quiver_invalid", "Quiver.json contains invalid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new QuiverError("quiver_invalid", "Quiver.json must be a JSON object");
+    }
+    const obj = parsed;
+    assertNoUnknownKeys(obj, ["manifest"], "Quiver.json");
+    if (typeof obj["manifest"] !== "string" || obj["manifest"].length === 0) {
+        throw new QuiverError("quiver_invalid", 'Quiver.json must have a non-empty string "manifest" field');
+    }
+    return obj["manifest"];
+}
+function parseManifest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new QuiverError("quiver_invalid", "Manifest file contains invalid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new QuiverError("quiver_invalid", "Manifest must be a JSON object");
+    }
+    const obj = parsed;
+    assertNoUnknownKeys(obj, ["version", "name", "quills"], "manifest");
+    if (obj["version"] !== 1) {
+        throw new QuiverError("quiver_invalid", `Manifest version must be 1, got ${String(obj["version"])}`);
+    }
+    if (typeof obj["name"] !== "string" || obj["name"].length === 0) {
+        throw new QuiverError("quiver_invalid", 'Manifest must have a non-empty string "name" field');
+    }
+    if (!Array.isArray(obj["quills"])) {
+        throw new QuiverError("quiver_invalid", 'Manifest must have a "quills" array');
+    }
+    const quills = [];
+    for (let i = 0; i < obj["quills"].length; i++) {
+        const entry = obj["quills"][i];
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new QuiverError("quiver_invalid", `manifest.quills[${i}] must be an object`);
+        }
+        const e = entry;
+        assertNoUnknownKeys(e, ["name", "version", "bundle", "fonts"], `manifest.quills[${i}]`);
+        if (typeof e["name"] !== "string" || e["name"].length === 0) {
+            throw new QuiverError("quiver_invalid", `manifest.quills[${i}].name must be a non-empty string`);
+        }
+        if (typeof e["version"] !== "string" ||
+            !isCanonicalSemver(e["version"])) {
+            throw new QuiverError("quiver_invalid", `manifest.quills[${i}].version must be canonical semver (x.y.z), got "${String(e["version"])}"`);
+        }
+        if (typeof e["bundle"] !== "string" ||
+            e["bundle"].length === 0) {
+            throw new QuiverError("quiver_invalid", `manifest.quills[${i}].bundle must be a non-empty string`);
+        }
+        validateBundleFileName(e["bundle"], `manifest.quills[${i}].bundle`);
+        if (typeof e["fonts"] !== "object" ||
+            e["fonts"] === null ||
+            Array.isArray(e["fonts"])) {
+            throw new QuiverError("quiver_invalid", `manifest.quills[${i}].fonts must be an object`);
+        }
+        const fonts = e["fonts"];
+        for (const [k, v] of Object.entries(fonts)) {
+            if (typeof v !== "string") {
+                throw new QuiverError("quiver_invalid", `manifest.quills[${i}].fonts["${k}"] must be a string`);
+            }
+            validateFontHash(v, `manifest.quills[${i}].fonts["${k}"]`);
+        }
+        quills.push({
+            name: e["name"],
+            version: e["version"],
+            bundle: e["bundle"],
+            fonts: fonts,
+        });
+    }
+    return {
+        version: 1,
+        name: obj["name"],
+        quills,
+    };
+}
+// ─── Main entry point ─────────────────────────────────────────────────────────
+/**
+ * Load a Packed Quiver via the given transport.
+ *
+ * 1. Fetches Quiver.json (pointer) and parses it.
+ * 2. Fetches the manifest file it points to and validates it.
+ * 3. Builds a catalog from manifest entries (versions sorted descending).
+ * 4. Returns a Quiver instance backed by a PackedLoader.
+ */
+export async function loadPackedQuiver(transport) {
+    // 1. Fetch and parse pointer.
+    let pointerBytes;
+    try {
+        pointerBytes = await transport.fetchBytes("Quiver.json");
+    }
+    catch (err) {
+        if (err instanceof QuiverError)
+            throw err;
+        throw new QuiverError("transport_error", `Failed to fetch Quiver.json: ${err.message}`, { cause: err });
+    }
+    const manifestFileName = parsePointer(new TextDecoder().decode(pointerBytes));
+    validateManifestFileName(manifestFileName);
+    // 2. Fetch and parse manifest.
+    let manifestBytes;
+    try {
+        manifestBytes = await transport.fetchBytes(manifestFileName);
+    }
+    catch (err) {
+        if (err instanceof QuiverError)
+            throw err;
+        throw new QuiverError("transport_error", `Failed to fetch manifest "${manifestFileName}": ${err.message}`, { cause: err });
+    }
+    const manifest = parseManifest(new TextDecoder().decode(manifestBytes));
+    // 3. Build catalog: name → versions sorted descending.
+    //    Also build index map: "name@version" → entry (with duplicate detection).
+    const catalogRaw = new Map();
+    const index = new Map();
+    for (const entry of manifest.quills) {
+        const key = `${entry.name}@${entry.version}`;
+        if (index.has(key)) {
+            throw new QuiverError("quiver_invalid", `Duplicate quill entry in manifest: "${key}"`);
+        }
+        index.set(key, entry);
+        const versions = catalogRaw.get(entry.name) ?? [];
+        versions.push(entry.version);
+        catalogRaw.set(entry.name, versions);
+    }
+    for (const [, versions] of catalogRaw) {
+        versions.sort((a, b) => compareSemver(b, a));
+    }
+    // 4. Build loader.
+    const loader = new PackedLoader(transport, index);
+    // 5. Return Quiver via internal factory.
+    return Quiver._fromLoader(manifest.name, catalogRaw, loader);
+}

package/dist/quiver-yaml.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Internal parser/validator for Quiver.yaml files.
+ *
+ * Uses the `yaml` npm package for robust YAML parsing. Quiver.yaml has a
+ * simple two-field schema (name, description), but using a proper YAML parser
+ * ensures correct handling of quoting, escaping, and multi-line strings.
+ */
+export interface QuiverMeta {
+    name: string;
+    description?: string;
+}
+/**
+ * Parses and validates Quiver.yaml contents.
+ *
+ * Throws `QuiverError('quiver_invalid')` on:
+ *   - YAML parse failure
+ *   - Missing or non-string `name`
+ *   - `name` fails charset validation [A-Za-z0-9_-]+
+ *   - Unknown fields (strict)
+ *   - `description` present but not a string
+ */
+export declare function parseQuiverYaml(raw: string | Uint8Array): QuiverMeta;

package/dist/quiver-yaml.js

@@ -0,0 +1,63 @@
+/**
+ * Internal parser/validator for Quiver.yaml files.
+ *
+ * Uses the `yaml` npm package for robust YAML parsing. Quiver.yaml has a
+ * simple two-field schema (name, description), but using a proper YAML parser
+ * ensures correct handling of quoting, escaping, and multi-line strings.
+ */
+import { parse as parseYaml } from "yaml";
+import { QuiverError } from "./errors.js";
+const NAME_RE = /^[A-Za-z0-9_-]+$/;
+const KNOWN_FIELDS = new Set(["name", "description"]);
+/**
+ * Parses and validates Quiver.yaml contents.
+ *
+ * Throws `QuiverError('quiver_invalid')` on:
+ *   - YAML parse failure
+ *   - Missing or non-string `name`
+ *   - `name` fails charset validation [A-Za-z0-9_-]+
+ *   - Unknown fields (strict)
+ *   - `description` present but not a string
+ */
+export function parseQuiverYaml(raw) {
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    let parsed;
+    try {
+        parsed = parseYaml(text);
+    }
+    catch (err) {
+        throw new QuiverError("quiver_invalid", `Quiver.yaml: YAML parse failure — ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new QuiverError("quiver_invalid", `Quiver.yaml: expected a mapping at the top level, got ${Array.isArray(parsed) ? "array" : String(parsed)}`);
+    }
+    const doc = parsed;
+    // Check for unknown fields (strict mode)
+    for (const key of Object.keys(doc)) {
+        if (!KNOWN_FIELDS.has(key)) {
+            throw new QuiverError("quiver_invalid", `Quiver.yaml: unknown field "${key}" — only "name" and "description" are valid in V1`);
+        }
+    }
+    // Validate `name`
+    if (!("name" in doc)) {
+        throw new QuiverError("quiver_invalid", `Quiver.yaml: required field "name" is missing`);
+    }
+    if (typeof doc["name"] !== "string") {
+        throw new QuiverError("quiver_invalid", `Quiver.yaml: "name" must be a string, got ${typeof doc["name"]}`);
+    }
+    const name = doc["name"];
+    if (!NAME_RE.test(name)) {
+        throw new QuiverError("quiver_invalid", `Quiver.yaml: "name" value "${name}" contains invalid characters — only [A-Za-z0-9_-] are allowed`);
+    }
+    // Validate optional `description`
+    if ("description" in doc && doc["description"] !== undefined) {
+        if (typeof doc["description"] !== "string") {
+            throw new QuiverError("quiver_invalid", `Quiver.yaml: "description" must be a string if present, got ${typeof doc["description"]}`);
+        }
+    }
+    const meta = { name };
+    if (typeof doc["description"] === "string") {
+        meta.description = doc["description"];
+    }
+    return meta;
+}