@vmz/vmz 0.0.4 → 0.1.1

package/dist/pack-client-packages.js

@@ -0,0 +1,399 @@
+/**
+ * Browser-safe client package lowering (Pack stage thin slice).
+ *
+ * Bare npm/workspace imports are legal on the author surface (01/04).
+ * Browser ESM cannot resolve them. Pack materializes reachable package
+ * modules under `dist/vendor/<pkg>/…` and rewrites importers to relative paths.
+ *
+ * Not full oxc chunk-split/minify (`oxc-pending` remains for release minify).
+ */
+// @ts-nocheck
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { resolvePackageRoot } from './packages.js';
+const VENDOR_DIR = 'vendor';
+const SKIP_PREFIXES = ['node:', 'nodejs:', 'cloudflare:', 'data:', 'http:', 'https:', 'vmz:', '#'];
+/**
+ * @param {string} outDir
+ * @param {{ projectRoot?: string | null }} [opts]
+ * @returns {{ rewrittenFiles: number, vendoredModules: string[], bareSpecs: string[] }}
+ */
+export function packClientBareImports(outDir, opts = {}) {
+    const projectRoot = opts.projectRoot ? path.resolve(opts.projectRoot) : path.dirname(path.resolve(outDir));
+    /** @type {Map<string, string>} bareSpec → absolute vendored .js path */
+    const bareToVendor = new Map();
+    /** @type {Set<string>} absolute source files already materialized */
+    const materializedSources = new Set();
+    /** @type {string[]} */
+    const bareQueue = [];
+    /** @type {string[]} */
+    const unresolved = [];
+    /** @type {string[]} */
+    const skippedVmz = [];
+    for (const file of listClientJs(outDir)) {
+        for (const spec of collectBareSpecs(readFileSync(file, 'utf8'))) {
+            if (!bareQueue.includes(spec))
+                bareQueue.push(spec);
+        }
+    }
+    while (bareQueue.length) {
+        const spec = bareQueue.shift();
+        if (bareToVendor.has(spec))
+            continue;
+        const resolved = resolveBareToSource(projectRoot, spec);
+        if (!resolved) {
+            if (!unresolved.includes(spec))
+                unresolved.push(spec);
+            continue;
+        }
+        if (/\.vmz$/i.test(resolved.sourceFile)) {
+            if (!skippedVmz.includes(spec))
+                skippedVmz.push(spec);
+            continue;
+        }
+        const destAbs = materializeSourceTree(outDir, resolved, materializedSources, bareQueue);
+        if (destAbs)
+            bareToVendor.set(spec, destAbs);
+        else if (!unresolved.includes(spec))
+            unresolved.push(spec);
+    }
+    /** @type {string[]} */
+    const rewritten = [];
+    for (const file of [...listClientJs(outDir), ...listVendorJs(outDir)]) {
+        const before = readFileSync(file, 'utf8');
+        let after = rewriteBareImports(before, file, bareToVendor);
+        after = rewriteRelativeTsSpecs(after);
+        if (after !== before) {
+            writeFileSync(file, after, 'utf8');
+            rewritten.push(path.relative(outDir, file).replace(/\\/g, '/'));
+        }
+    }
+    // Any bare that remains in client (non-vendor) JS after rewrite is still browser-broken.
+    /** @type {string[]} */
+    const remaining = [];
+    for (const file of listClientJs(outDir)) {
+        for (const spec of collectBareSpecs(readFileSync(file, 'utf8'))) {
+            if (!remaining.includes(spec))
+                remaining.push(spec);
+        }
+    }
+    return {
+        rewrittenFiles: rewritten.length,
+        vendoredModules: [...bareToVendor.values()].map((abs) => path.relative(outDir, abs).replace(/\\/g, '/')),
+        bareSpecs: [...bareToVendor.keys()],
+        unresolvedBareSpecs: unresolved,
+        skippedVmzExports: skippedVmz,
+        remainingBareSpecs: remaining,
+    };
+}
+/**
+ * Materialize `resolved.sourceFile` and its relative import closure under vendor/.
+ * @returns {string | null} vendor path for the entry source
+ */
+function materializeSourceTree(outDir, resolved, materializedSources, bareQueue) {
+    /** @type {string[]} */
+    const sourceQueue = [resolved.sourceFile];
+    // Subpath bare specs often land on a file already vendored via a relative
+    // import from the package root — still map the bare name to that vendor path.
+    /** @type {string | null} */
+    let entryDest = vendorPathForSource(outDir, resolved.pkgName, resolved.pkgRoot, resolved.sourceFile);
+    while (sourceQueue.length) {
+        const sourceFile = sourceQueue.shift();
+        if (materializedSources.has(sourceFile))
+            continue;
+        materializedSources.add(sourceFile);
+        const destAbs = vendorPathForSource(outDir, resolved.pkgName, resolved.pkgRoot, sourceFile);
+        mkdirSync(path.dirname(destAbs), { recursive: true });
+        const js = materializeModule(sourceFile);
+        writeFileSync(destAbs, js, 'utf8');
+        if (sourceFile === resolved.sourceFile)
+            entryDest = destAbs;
+        for (const bare of collectBareSpecs(js)) {
+            if (!bareQueue.includes(bare))
+                bareQueue.push(bare);
+        }
+        for (const rel of collectRelativeSpecs(js)) {
+            const target = resolveRelativeSource(path.dirname(sourceFile), rel);
+            if (target && !materializedSources.has(target))
+                sourceQueue.push(target);
+        }
+        // Also follow relative imports as written in the *source* (before transpile),
+        // so `./catalog.ts` is discovered even if transpile already rewrote to `.js`.
+        const raw = readFileSync(sourceFile, 'utf8');
+        for (const rel of collectRelativeSpecs(raw)) {
+            const target = resolveRelativeSource(path.dirname(sourceFile), rel);
+            if (target && !materializedSources.has(target))
+                sourceQueue.push(target);
+        }
+    }
+    return entryDest;
+}
+function listClientJs(outDir) {
+    /** @type {string[]} */
+    const out = [];
+    walk(outDir, (file) => {
+        const rel = path.relative(outDir, file).replace(/\\/g, '/');
+        if (rel.startsWith('_vmz/') || rel.startsWith(`${VENDOR_DIR}/`) || rel.startsWith('#server/') || rel.startsWith('_vmz_server/')) {
+            return;
+        }
+        if (rel.endsWith('.js') || rel.endsWith('.mjs'))
+            out.push(file);
+    });
+    return out;
+}
+function listVendorJs(outDir) {
+    const root = path.join(outDir, VENDOR_DIR);
+    if (!existsSync(root))
+        return [];
+    /** @type {string[]} */
+    const out = [];
+    walk(root, (file) => {
+        if (file.endsWith('.js') || file.endsWith('.mjs'))
+            out.push(file);
+    });
+    return out;
+}
+function walk(dir, visit) {
+    if (!existsSync(dir))
+        return;
+    for (const name of readdirSync(dir)) {
+        if (name === 'node_modules')
+            continue;
+        const full = path.join(dir, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            walk(full, visit);
+        else
+            visit(full);
+    }
+}
+/** @param {string} js */
+export function collectBareSpecs(js) {
+    /** @type {Set<string>} */
+    const specs = new Set();
+    const add = (spec) => {
+        if (!spec || isRelativeOrAbsolute(spec) || shouldSkipBare(spec))
+            return;
+        specs.add(spec);
+    };
+    // `from 'x'` covers import/export … from
+    let m;
+    const fromRe = /\bfrom\s+['"]([^'"]+)['"]/g;
+    while ((m = fromRe.exec(js)))
+        add(m[1]);
+    const dynRe = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    while ((m = dynRe.exec(js)))
+        add(m[1]);
+    // side-effect: import 'x' (not import( and not import … from)
+    const sideRe = /\bimport\s+['"]([^'"]+)['"]/g;
+    while ((m = sideRe.exec(js)))
+        add(m[1]);
+    return [...specs];
+}
+function collectRelativeSpecs(js) {
+    /** @type {Set<string>} */
+    const specs = new Set();
+    const re = /(?:from\s+|import\s*\(\s*)['"](\.[^'"]+)['"]/g;
+    let m;
+    while ((m = re.exec(js)))
+        specs.add(m[1]);
+    return [...specs];
+}
+function isRelativeOrAbsolute(spec) {
+    return spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('\\');
+}
+function shouldSkipBare(spec) {
+    return SKIP_PREFIXES.some((p) => spec.startsWith(p));
+}
+function resolveBareToSource(projectRoot, spec) {
+    const { pkgName, subpath } = splitPackageSpec(spec);
+    let pkgRoot = resolvePackageRoot(projectRoot, pkgName);
+    if (!pkgRoot) {
+        let cur = projectRoot;
+        for (let i = 0; i < 8; i++) {
+            pkgRoot = resolvePackageRoot(cur, pkgName);
+            if (pkgRoot)
+                break;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
+        }
+    }
+    if (!pkgRoot)
+        return null;
+    const sourceFile = resolveExportFile(pkgRoot, subpath);
+    if (!sourceFile)
+        return null;
+    return { pkgName, pkgRoot, subpath, sourceFile };
+}
+function splitPackageSpec(spec) {
+    if (spec.startsWith('@')) {
+        const parts = spec.split('/');
+        if (parts.length < 2)
+            return { pkgName: spec, subpath: '' };
+        return { pkgName: `${parts[0]}/${parts[1]}`, subpath: parts.slice(2).join('/') };
+    }
+    const i = spec.indexOf('/');
+    if (i < 0)
+        return { pkgName: spec, subpath: '' };
+    return { pkgName: spec.slice(0, i), subpath: spec.slice(i + 1) };
+}
+function resolveExportFile(pkgRoot, subpath) {
+    const pkgPath = path.join(pkgRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return null;
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const key = subpath ? `./${subpath}` : '.';
+    let target = null;
+    if (pkg.exports && typeof pkg.exports === 'object' && !Array.isArray(pkg.exports)) {
+        const entry = pkg.exports[key] ?? (!subpath ? pkg.exports['.'] : null);
+        target = flattenExportTarget(entry);
+    }
+    if (!target && !subpath)
+        target = pkg.module || pkg.main || './index.js';
+    if (!target && subpath) {
+        for (const cand of [
+            path.join(pkgRoot, 'src', `${subpath}.ts`),
+            path.join(pkgRoot, 'src', `${subpath}.js`),
+            path.join(pkgRoot, `${subpath}.ts`),
+            path.join(pkgRoot, `${subpath}.js`),
+            path.join(pkgRoot, 'src', subpath, 'index.ts'),
+            path.join(pkgRoot, 'src', subpath, 'index.js'),
+        ]) {
+            if (existsSync(cand) && statSync(cand).isFile())
+                return cand;
+        }
+        return null;
+    }
+    if (!target || typeof target !== 'string')
+        return null;
+    const abs = path.resolve(pkgRoot, target);
+    if (existsSync(abs) && statSync(abs).isFile())
+        return abs;
+    for (const ext of ['.ts', '.tsx', '.js', '.mjs']) {
+        const c = abs.endsWith(ext) ? abs : abs + ext;
+        if (existsSync(c) && statSync(c).isFile())
+            return c;
+    }
+    return null;
+}
+function flattenExportTarget(entry) {
+    if (typeof entry === 'string')
+        return entry;
+    if (!entry || typeof entry !== 'object')
+        return null;
+    const v = entry.import || entry.default || entry.require || entry.module || null;
+    if (typeof v === 'string')
+        return v;
+    if (v && typeof v === 'object')
+        return flattenExportTarget(v);
+    return null;
+}
+function vendorPathForSource(outDir, pkgName, pkgRoot, sourceFile) {
+    const rel = path.relative(pkgRoot, sourceFile).replace(/\\/g, '/');
+    return path.join(outDir, VENDOR_DIR, packageDirName(pkgName), rewriteTsExt(rel));
+}
+function packageDirName(pkgName) {
+    return pkgName.replace(/^@/, '');
+}
+function materializeModule(sourceFile) {
+    const ext = path.extname(sourceFile).toLowerCase();
+    const raw = readFileSync(sourceFile, 'utf8');
+    if (ext === '.ts' || ext === '.tsx')
+        return transpileTs(raw, sourceFile);
+    return rewriteRelativeTsSpecs(raw);
+}
+function transpileTs(source, filename) {
+    try {
+        const require = createRequire(import.meta.url);
+        const ts = require('typescript');
+        const out = ts.transpileModule(source, {
+            fileName: filename,
+            compilerOptions: {
+                module: ts.ModuleKind.ESNext,
+                target: ts.ScriptTarget.ES2022,
+                moduleResolution: ts.ModuleResolutionKind.Bundler,
+                esModuleInterop: true,
+                skipLibCheck: true,
+            },
+        });
+        return rewriteRelativeTsSpecs(out.outputText || '');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `/* vmz-pack: typescript transpile failed (${msg}) */\n${rewriteRelativeTsSpecs(source)}`;
+    }
+}
+function rewriteTsExt(p) {
+    return String(p)
+        .replace(/\.tsx$/i, '.js')
+        .replace(/\.ts$/i, '.js');
+}
+export function rewriteRelativeTsSpecs(js) {
+    return js
+        .replace(/(from\s+['"])(\.[^'"]+)\.tsx(['"])/g, '$1$2.js$3')
+        .replace(/(from\s+['"])(\.[^'"]+)\.ts(['"])/g, '$1$2.js$3')
+        .replace(/(import\s*\(\s*['"])(\.[^'"]+)\.tsx(['"]\s*\))/g, '$1$2.js$3')
+        .replace(/(import\s*\(\s*['"])(\.[^'"]+)\.ts(['"]\s*\))/g, '$1$2.js$3');
+}
+function resolveRelativeSource(fromDir, rel) {
+    const cleaned = rel.replace(/\?.*$/, '').replace(/#.*$/, '');
+    const base = path.resolve(fromDir, cleaned);
+    for (const cand of [
+        base,
+        `${base}.ts`,
+        `${base}.tsx`,
+        `${base}.js`,
+        `${base}.mjs`,
+        path.join(base, 'index.ts'),
+        path.join(base, 'index.js'),
+    ]) {
+        try {
+            if (existsSync(cand) && statSync(cand).isFile())
+                return cand;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return null;
+}
+function rewriteBareImports(js, fromFile, bareToVendor) {
+    const toRel = (spec) => {
+        const dest = bareToVendor.get(spec);
+        if (!dest)
+            return null;
+        let rel = path.relative(path.dirname(fromFile), dest).replace(/\\/g, '/');
+        if (!rel.startsWith('.'))
+            rel = `./${rel}`;
+        return rel;
+    };
+    let out = js;
+    out = out.replace(/\bimport\s*\(\s*(['"])([^'"]+)\1\s*\)/g, (full, quote, spec) => {
+        if (isRelativeOrAbsolute(spec) || shouldSkipBare(spec))
+            return full;
+        const rel = toRel(spec);
+        return rel ? `import(${quote}${rel}${quote})` : full;
+    });
+    out = out.replace(/\bfrom\s+(['"])([^'"]+)\1/g, (full, quote, spec) => {
+        if (isRelativeOrAbsolute(spec) || shouldSkipBare(spec))
+            return full;
+        const rel = toRel(spec);
+        return rel ? `from ${quote}${rel}${quote}` : full;
+    });
+    out = out.replace(/\bimport\s+(['"])([^'"]+)\1/g, (full, quote, spec) => {
+        if (isRelativeOrAbsolute(spec) || shouldSkipBare(spec))
+            return full;
+        const rel = toRel(spec);
+        return rel ? `import ${quote}${rel}${quote}` : full;
+    });
+    return out;
+}

package/dist/pack.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pack stage: consume Deployment IR (VPG-owned units), emit pack manifest,
+ * and lower browser-unreachable bare package imports to `dist/vendor/**`.
+ * Full oxc minify/chunk-split lands progressively (`oxc-pending` on release minify).
+ */
+export declare const PACK_MANIFEST_SCHEMA = "vmz.pack.manifest.v0";
+/**
+ * Ensure dom split companions sit next to vmz-dom.js (barrel imports ./dom-core.js).
+ * Always refresh from `@vmz/core` when present so SSR/runtime fixes are not sticky in outDir.
+ * @param {string} outDir
+ * @param {string | null | undefined} coreDist `@vmz/core` dist root
+ * @returns {string[]} copied relative names
+ */
+export declare function ensureRuntimeCompanions(outDir: any, coreDist: any): any[];
+/**
+ * @param {string} outDir
+ * @param {{
+ *   release?: boolean,
+ *   profileId?: string,
+ *   assembly?: string,
+ *   preferredClientFace?: string,
+ *   coreDist?: string | null,
+ *   projectRoot?: string | null,
+ * }} [opts]
+ */
+export declare function packFromDeploymentIr(outDir: any, opts?: {}): {
+    manifest: {
+        schema: string;
+        profileId: any;
+        assembly: any;
+        release: boolean;
+        preferredClientFace: any;
+        deploymentSchema: any;
+        unitCount: number;
+        units: any[];
+        minify: string;
+        treeShakeBasis: string;
+        bundler: string;
+        clientPackageLowering: {
+            status: string;
+            rewrittenFiles: number;
+            bareSpecs: any[];
+            vendoredModules: string[];
+            unresolvedBareSpecs: any[];
+            skippedVmzExports: any[];
+            remainingBareSpecs: any[];
+        };
+    };
+    path: string;
+    clientPackages: {
+        rewrittenFiles: number;
+        vendoredModules: string[];
+        bareSpecs: any[];
+        unresolvedBareSpecs: any[];
+        skippedVmzExports: any[];
+        remainingBareSpecs: any[];
+    };
+};

package/dist/pack.js

@@ -0,0 +1,123 @@
+/**
+ * Pack stage: consume Deployment IR (VPG-owned units), emit pack manifest,
+ * and lower browser-unreachable bare package imports to `dist/vendor/**`.
+ * Full oxc minify/chunk-split lands progressively (`oxc-pending` on release minify).
+ */
+// @ts-nocheck
+import crypto from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadDeploymentIr, planBundleInputs } from './bundler-adapter.js';
+import { packClientBareImports } from './pack-client-packages.js';
+import { writePrettyJsonFile } from './pretty-json.js';
+export const PACK_MANIFEST_SCHEMA = 'vmz.pack.manifest.v0';
+/**
+ * Ensure dom split companions sit next to vmz-dom.js (barrel imports ./dom-core.js).
+ * Always refresh from `@vmz/core` when present so SSR/runtime fixes are not sticky in outDir.
+ * @param {string} outDir
+ * @param {string | null | undefined} coreDist `@vmz/core` dist root
+ * @returns {string[]} copied relative names
+ */
+export function ensureRuntimeCompanions(outDir, coreDist) {
+    if (!coreDist)
+        return [];
+    const names = ['dom-core.js', 'dom-ssr.js', 'dom.client.js'];
+    const copied = [];
+    for (const name of names) {
+        const src = path.join(coreDist, name);
+        if (!existsSync(src))
+            continue;
+        const dest = path.join(outDir, name);
+        copyFileSync(src, dest);
+        copied.push(name);
+    }
+    return copied;
+}
+/**
+ * @param {string} outDir
+ * @param {{
+ *   release?: boolean,
+ *   profileId?: string,
+ *   assembly?: string,
+ *   preferredClientFace?: string,
+ *   coreDist?: string | null,
+ *   projectRoot?: string | null,
+ * }} [opts]
+ */
+export function packFromDeploymentIr(outDir, opts = {}) {
+    ensureRuntimeCompanions(outDir, opts.coreDist);
+    // Browser ESM cannot resolve bare npm specs — materialize reachable packages first
+    // so digests below reflect the rewritten graph.
+    const clientPackages = packClientBareImports(outDir, { projectRoot: opts.projectRoot || null });
+    const ir = loadDeploymentIr(outDir);
+    const inputs = planBundleInputs(outDir, ir);
+    const units = [];
+    for (const entry of inputs) {
+        const abs = entry.entry;
+        let digest = null;
+        let bytes = 0;
+        let present = false;
+        if (existsSync(abs)) {
+            present = true;
+            const buf = readFileSync(abs);
+            bytes = buf.length;
+            digest = crypto.createHash('sha256').update(buf).digest('hex');
+        }
+        units.push({
+            chunkId: entry.chunkId,
+            kind: entry.kind,
+            entry: path.relative(outDir, abs).replace(/\\/g, '/'),
+            programIr: path.relative(outDir, entry.programIr).replace(/\\/g, '/'),
+            source: entry.source,
+            present,
+            bytes,
+            digest,
+            rebuilt: Boolean(entry.rebuilt),
+        });
+    }
+    const body = {
+        schema: PACK_MANIFEST_SCHEMA,
+        profileId: opts.profileId || null,
+        assembly: opts.assembly || null,
+        release: Boolean(opts.release),
+        preferredClientFace: opts.preferredClientFace || '@vmz/core/dom/client',
+        deploymentSchema: ir.schema,
+        unitCount: units.length,
+        units,
+        minify: opts.release ? 'oxc-pending' : 'dev-identity',
+        treeShakeBasis: 'vpg-deployment-ir',
+        bundler: 'vmz-pack',
+        clientPackageLowering: {
+            status: 'thin',
+            rewrittenFiles: clientPackages.rewrittenFiles,
+            bareSpecs: clientPackages.bareSpecs,
+            vendoredModules: clientPackages.vendoredModules,
+            unresolvedBareSpecs: clientPackages.unresolvedBareSpecs || [],
+            skippedVmzExports: clientPackages.skippedVmzExports || [],
+            remainingBareSpecs: clientPackages.remainingBareSpecs || [],
+        },
+    };
+    body.packDigest = sha256Hex(stableStringify({ ...body }));
+    const vmzDir = path.join(outDir, '_vmz');
+    mkdirSync(vmzDir, { recursive: true });
+    const file = path.join(vmzDir, 'pack-manifest.json');
+    writePrettyJsonFile(file, body);
+    return { manifest: body, path: file, clientPackages };
+}
+function stableStringify(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value).sort())
+            out[k] = sortKeys(value[k]);
+        return out;
+    }
+    return value;
+}
+function sha256Hex(text) {
+    return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}

package/dist/plugin-host.d.ts

@@ -15,7 +15,7 @@ export declare function importMaybeTs(full: any): Promise<any>;
  * @returns {Promise<{
  *   plugins: import('@vmz/plugin').VmzPlugin[],
  *   engines: import('@vmz/plugin').VmzEngines,
- *   delivery: import('@vmz/plugin').SiteDeliveryAuthoring | null,
+ *   delivery: import('@vmz/plugin').DeliveryAuthoring | null,
  *   application: { id?: string } | null,
  *   path: string | null,
  *   pluginPath: string | null,

package/dist/plugin-host.js

@@ -35,7 +35,7 @@ export async function importMaybeTs(full) {
  * @returns {Promise<{
  *   plugins: import('@vmz/plugin').VmzPlugin[],
  *   engines: import('@vmz/plugin').VmzEngines,
- *   delivery: import('@vmz/plugin').SiteDeliveryAuthoring | null,
+ *   delivery: import('@vmz/plugin').DeliveryAuthoring | null,
  *   application: { id?: string } | null,
  *   path: string | null,
  *   pluginPath: string | null,
@@ -46,7 +46,7 @@ export async function loadVmzConfig(project) {
     const plugins = [];
     /** @type {import('@vmz/plugin').VmzEngines} */
     let engines = {};
-    /** @type {import('@vmz/plugin').SiteDeliveryAuthoring | null} */
+    /** @type {import('@vmz/plugin').DeliveryAuthoring | null} */
     let delivery = null;
     /** @type {{ id?: string } | null} */
     let application = null;

package/dist/pretty-json.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pretty-print a value through `vmz-generator` (N-API).
+ * @param {unknown} value
+ * @returns {string} Pretty JSON without trailing newline.
+ */
+export declare function generatePrettyJson(value: any): any;
+/**
+ * Write a pretty JSON artifact with a trailing newline.
+ * @param {string} filePath
+ * @param {unknown} value
+ */
+export declare function writePrettyJsonFile(filePath: any, value: any): void;
+/**
+ * CLI `--json` helper: write to a path when `target` is a string, else stdout.
+ * @param {string | boolean | undefined} target
+ * @param {unknown} value
+ * @param {{ logWrote?: (path: string) => void }} [opts]
+ */
+export declare function emitPrettyJson(target: any, value: any, opts?: {}): void;

package/dist/pretty-json.js

@@ -0,0 +1,43 @@
+// @ts-nocheck
+/**
+ * Production JSON artifact printer — always via N-API JsonCodeGenerator.
+ * Do not use `JSON.stringify(x, null, 2)` for on-disk artifacts.
+ */
+import fs from 'node:fs';
+import { requireNativeAddon } from './native-addon.js';
+/**
+ * Pretty-print a value through `vmz-generator` (N-API).
+ * @param {unknown} value
+ * @returns {string} Pretty JSON without trailing newline.
+ */
+export function generatePrettyJson(value) {
+    const native = requireNativeAddon();
+    if (typeof native.generatePrettyJson !== 'function') {
+        throw new Error('vmz native addon missing generatePrettyJson — rebuild with `pnpm napi:build`');
+    }
+    return native.generatePrettyJson(JSON.stringify(value));
+}
+/**
+ * Write a pretty JSON artifact with a trailing newline.
+ * @param {string} filePath
+ * @param {unknown} value
+ */
+export function writePrettyJsonFile(filePath, value) {
+    fs.writeFileSync(filePath, `${generatePrettyJson(value)}\n`, 'utf8');
+}
+/**
+ * CLI `--json` helper: write to a path when `target` is a string, else stdout.
+ * @param {string | boolean | undefined} target
+ * @param {unknown} value
+ * @param {{ logWrote?: (path: string) => void }} [opts]
+ */
+export function emitPrettyJson(target, value, opts = {}) {
+    const text = generatePrettyJson(value);
+    if (typeof target === 'string') {
+        fs.writeFileSync(target, `${text}\n`, 'utf8');
+        if (typeof opts.logWrote === 'function')
+            opts.logWrote(target);
+        return;
+    }
+    console.log(text);
+}

package/dist/production-observability.js

@@ -7,6 +7,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { canonicalJson, sha256Hex } from './release-pack.js';
+import { writePrettyJsonFile } from './pretty-json.js';
 export const PRODUCTION_OBSERVABILITY_SCHEMA = 'vmz.production.observability.v0';
 export const PRODUCTION_TRACE_SCHEMA = 'vmz.production.trace.v0';
 /** Facets that production traces must be able to carry (08 A5). */
@@ -457,8 +458,8 @@ export function emitProductionObservability(distDir, overrides = {}, meta = {})
     fs.mkdirSync(vmzDir, { recursive: true });
     const contractPath = path.join(vmzDir, 'production-observability.json');
     const tracePath = path.join(vmzDir, 'production-trace.sample.json');
-    fs.writeFileSync(contractPath, `${JSON.stringify(contract, null, 2)}\n`, 'utf8');
-    fs.writeFileSync(tracePath, `${JSON.stringify(trace, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(contractPath, contract);
+    writePrettyJsonFile(tracePath, trace);
     return { contract, trace, contractPath, tracePath };
 }
 export function observabilityDigest(contract) {