@vmz/vmz 0.0.3 → 0.1.0

package/dist/locale-route-emit.js

@@ -0,0 +1,134 @@
+// @ts-nocheck
+/**
+ * Emit RouteId × LocaleId realization (+ PageMeta / hreflang seed) into dist/_vmz.
+ * Consumed by serve-host + static-emit; LocaleId stays out of stable RouteId.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkLocales, localeHasErrors } from './locale-check.js';
+import { buildLocalePageMeta, buildLocaleRouteRealizationTable } from './locale-router.js';
+export const LOCALE_ROUTE_REALIZATION_ARTIFACT_SCHEMA = 'vmz.locale.route_realization.v0';
+/**
+ * @param {string} chunkId
+ */
+function pathPatternFromChunk(chunkId) {
+    const rel = String(chunkId || '').replace(/^pages\//, '');
+    const parts = rel.split('/').filter(Boolean);
+    const segs = [];
+    for (let i = 0; i < parts.length; i++) {
+        const p = parts[i];
+        if (p === 'index' && i === parts.length - 1)
+            continue;
+        segs.push(p);
+    }
+    return segs.length ? `/${segs.join('/')}` : '/';
+}
+/**
+ * Layouts are not public RouteNodes for locale realization / SEO.
+ * @param {string} chunkId
+ */
+function isPublicPageChunk(chunkId) {
+    const id = String(chunkId || '');
+    if (!id.startsWith('pages/'))
+        return false;
+    if (/(^|\/)Layout$/.test(id))
+        return false;
+    return true;
+}
+/**
+ * @param {string} projectRoot
+ * @param {string} distDir
+ * @param {{ origin?: string }} [opts]
+ */
+export function emitLocaleRouteRealization(projectRoot, distDir, opts = {}) {
+    const report = checkLocales({ projectRoot, checkUnused: false });
+    if (localeHasErrors(report)) {
+        return { ok: false, written: [], diagnostics: report.diagnostics || [], artifact: null };
+    }
+    // Missing /locales is warning (not error) — still never silent; no realization artifact yet.
+    if (!report.manifest) {
+        return { ok: true, written: [], artifact: null, diagnostics: report.diagnostics || [] };
+    }
+    const deploymentPath = path.join(distDir, 'vmz-deployment.json');
+    if (!fs.existsSync(deploymentPath)) {
+        return {
+            ok: false,
+            written: [],
+            diagnostics: [{ severity: 'error', code: 'locale.route.missing_deployment', message: 'missing vmz-deployment.json' }],
+            artifact: null,
+        };
+    }
+    const deployment = JSON.parse(fs.readFileSync(deploymentPath, 'utf8'));
+    const pages = (deployment.units || []).filter((u) => u.kind === 'page' && isPublicPageChunk(String(u.chunkId)));
+    const routes = pages.map((u) => ({
+        routeId: String(u.chunkId),
+        path: pathPatternFromChunk(String(u.chunkId)),
+    }));
+    const localeEntries = report.manifest?.locales || [];
+    const locales = localeEntries.map((l) => l.id);
+    const directions = Object.fromEntries(localeEntries.map((l) => [l.id, l.direction || 'ltr']));
+    const defaultLocale = report.manifest?.defaultLocale;
+    const routing = report.manifest?.routing || { strategy: 'prefix', defaultPrefix: 'include' };
+    const table = buildLocaleRouteRealizationTable({
+        routes,
+        locales,
+        defaultLocale,
+        routing,
+    });
+    if (table.status === 'failed') {
+        return { ok: false, written: [], diagnostics: table.diagnostics || [], artifact: null };
+    }
+    const origin = String(opts.origin || process.env.VMZ_SITE_ORIGIN || 'https://example.test').replace(/\/$/, '');
+    /** @type {any[]} */
+    const pageMetas = [];
+    for (const route of routes) {
+        for (const loc of locales) {
+            const meta = buildLocalePageMeta({
+                routeId: route.routeId,
+                localeId: loc,
+                direction: directions[loc],
+                title: route.routeId,
+                origin,
+                realizations: table.realizations,
+                locales,
+                defaultLocale,
+            });
+            pageMetas.push(meta);
+        }
+    }
+    const artifact = {
+        schema: LOCALE_ROUTE_REALIZATION_ARTIFACT_SCHEMA,
+        defaultLocale,
+        locales: localeEntries.map((l) => ({
+            id: l.id,
+            label: l.label || l.id,
+            direction: l.direction || 'ltr',
+        })),
+        routing: {
+            strategy: routing.strategy || 'prefix',
+            defaultPrefix: routing.defaultPrefix || 'include',
+            defaultLocale,
+        },
+        origin,
+        routes,
+        realizations: table.realizations,
+        pageMetas,
+    };
+    const vmzDir = path.join(distDir, '_vmz');
+    fs.mkdirSync(vmzDir, { recursive: true });
+    const outPath = path.join(vmzDir, 'locale-route-realization.json');
+    fs.writeFileSync(outPath, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+    const manifestOut = path.join(vmzDir, 'locale-manifest.json');
+    fs.writeFileSync(manifestOut, `${JSON.stringify({
+        schema: 'vmz.locale.manifest.v0',
+        defaultLocale,
+        locales: artifact.locales,
+        routing: artifact.routing,
+    }, null, 2)}\n`, 'utf8');
+    return {
+        ok: true,
+        written: ['_vmz/locale-route-realization.json', '_vmz/locale-manifest.json'],
+        artifact,
+        diagnostics: [],
+    };
+}

package/dist/locale-router.d.ts

@@ -116,6 +116,26 @@ export declare function parseLocaleFromPath(pathname: any, supportedLocales: any
     localeId: string;
     restPath: string;
 };
+/**
+ * Rewrite a same-app href to the given LocaleId via route realization.
+ * Stable path (no locale) is recovered first, then re-realized — Link never hardcodes locale.
+ * @param {string} href
+ * @param {string} localeId
+ * @param {{
+ *   locales?: Array<{ id: string }|string>,
+ *   defaultLocale?: string,
+ *   routing?: { strategy?: string, defaultPrefix?: string, defaultLocale?: string },
+ * }} artifact
+ */
+export declare function localizeSameAppHref(href: any, localeId: any, artifact: any): any;
+/**
+ * Rewrite `<a data-vmz-route href>` in HTML body to retain `localeId`.
+ * @param {string} html
+ * @param {string} localeId
+ * @param {Parameters<typeof localizeSameAppHref>[2]} artifact
+ * @param {(s: string) => string} [escapeAttr]
+ */
+export declare function localizeBodyLinks(html: any, localeId: any, artifact: any, escapeAttr?: (s: any) => string): any;
 /**
  * Plan redirect / negotiation for an incoming URL (omit-prefix aware).
  * @param {{

package/dist/locale-router.js

@@ -260,6 +260,74 @@ export function parseLocaleFromPath(pathname, supportedLocales) {
     }
     return { localeId: null, restPath: normalizePath(pathname) };
 }
+/**
+ * Rewrite a same-app href to the given LocaleId via route realization.
+ * Stable path (no locale) is recovered first, then re-realized — Link never hardcodes locale.
+ * @param {string} href
+ * @param {string} localeId
+ * @param {{
+ *   locales?: Array<{ id: string }|string>,
+ *   defaultLocale?: string,
+ *   routing?: { strategy?: string, defaultPrefix?: string, defaultLocale?: string },
+ * }} artifact
+ */
+export function localizeSameAppHref(href, localeId, artifact) {
+    if (!href || !localeId || !artifact)
+        return href;
+    if (href.startsWith('#') || /^(mailto|tel|javascript):/i.test(href))
+        return href;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('/'))
+        return href;
+    let pathname = String(href);
+    let search = '';
+    let hash = '';
+    const hashIdx = pathname.indexOf('#');
+    if (hashIdx >= 0) {
+        hash = pathname.slice(hashIdx);
+        pathname = pathname.slice(0, hashIdx);
+    }
+    const qIdx = pathname.indexOf('?');
+    if (qIdx >= 0) {
+        search = pathname.slice(qIdx);
+        pathname = pathname.slice(0, qIdx);
+    }
+    if (!pathname)
+        pathname = '/';
+    const supported = (artifact.locales || []).map((l) => (typeof l === 'string' ? l : l.id)).filter(Boolean);
+    const defaultLocale = artifact.defaultLocale || artifact.routing?.defaultLocale;
+    const routing = {
+        strategy: artifact.routing?.strategy || 'prefix',
+        defaultPrefix: artifact.routing?.defaultPrefix || 'include',
+        defaultLocale,
+    };
+    const parsed = parseLocaleFromPath(pathname, supported);
+    const rest = parsed.restPath || '/';
+    const realized = realizeRoutePath(localeId, rest, routing);
+    return `${realized.path}${search}${hash}`;
+}
+/**
+ * Rewrite `<a data-vmz-route href>` in HTML body to retain `localeId`.
+ * @param {string} html
+ * @param {string} localeId
+ * @param {Parameters<typeof localizeSameAppHref>[2]} artifact
+ * @param {(s: string) => string} [escapeAttr]
+ */
+export function localizeBodyLinks(html, localeId, artifact, escapeAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;')) {
+    if (!html || !localeId || !artifact)
+        return html;
+    return String(html).replace(/<a\b([^>]*)>/gi, (full, attrs) => {
+        if (!/\bdata-vmz-route\s*=/.test(attrs))
+            return full;
+        const hm = attrs.match(/\bhref\s*=\s*"([^"]*)"/i);
+        if (!hm)
+            return full;
+        const next = localizeSameAppHref(hm[1], localeId, artifact);
+        if (next === hm[1])
+            return full;
+        const newAttrs = attrs.replace(/\bhref\s*=\s*"[^"]*"/i, `href="${escapeAttr(next)}"`);
+        return `<a${newAttrs}>`;
+    });
+}
 /**
  * Plan redirect / negotiation for an incoming URL (omit-prefix aware).
  * @param {{

package/dist/log.d.ts

@@ -8,10 +8,10 @@ export declare const log: {
     warn(...args: any[]): void;
     /** @param {...unknown} args */
     error(...args: any[]): void;
-    /** @param {{ severity: string, path: string, message: string }} d */
+    /** @param {{ severity: string, path?: string, message: string, code?: string }} d */
     diagnostic(d: any): void;
     /**
-     * @param {Array<{ severity: string, path: string, message: string }>} diagnostics
+     * @param {Array<{ severity: string, path?: string, message: string, code?: string }>} diagnostics
      * @param {{ denyWarnings?: boolean }} [opts]
      * @returns {number} failing count (errors, and warnings if denyWarnings)
      */

package/dist/log.js

@@ -19,12 +19,20 @@ export const log = {
     error(...args) {
         console.error(stamp('error'), ...args);
     },
-    /** @param {{ severity: string, path: string, message: string }} d */
+    /** @param {{ severity: string, path?: string, message: string, code?: string }} d */
     diagnostic(d) {
-        console.error(`${d.severity}: ${d.path}: ${d.message}`);
+        const sev = d.severity || 'error';
+        const code = d.code ? `${d.code}: ` : '';
+        const loc = d.path ? ` (${d.path})` : '';
+        // Prefer `vmz warn|error CODE: message (path)` so locale warnings are visible, not silent.
+        if (sev === 'warning') {
+            console.error(`${stamp('warn')} ${code}${d.message}${loc}`);
+            return;
+        }
+        console.error(`${stamp(sev === 'error' ? 'error' : sev)} ${code}${d.path ? `${d.path}: ` : ''}${d.message}`);
     },
     /**
-     * @param {Array<{ severity: string, path: string, message: string }>} diagnostics
+     * @param {Array<{ severity: string, path?: string, message: string, code?: string }>} diagnostics
      * @param {{ denyWarnings?: boolean }} [opts]
      * @returns {number} failing count (errors, and warnings if denyWarnings)
      */

package/dist/pack.d.ts

@@ -0,0 +1,40 @@
+/**
+ * B4 — Pack stage: consume Deployment IR (VPG-owned units), emit pack manifest.
+ * Full oxc minify/chunk-split lands progressively; this stage always runs and
+ * records integrity digests so Assemble/Prove never skip the pack contract.
+ */
+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,
+ * }} [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;
+    };
+    path: string;
+};

package/dist/pack.js

@@ -0,0 +1,108 @@
+/**
+ * B4 — Pack stage: consume Deployment IR (VPG-owned units), emit pack manifest.
+ * Full oxc minify/chunk-split lands progressively; this stage always runs and
+ * records integrity digests so Assemble/Prove never skip the pack contract.
+ */
+// @ts-nocheck
+import crypto from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadDeploymentIr, planBundleInputs } from './bundler-adapter.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,
+ * }} [opts]
+ */
+export function packFromDeploymentIr(outDir, opts = {}) {
+    ensureRuntimeCompanions(outDir, opts.coreDist);
+    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',
+    };
+    body.packDigest = sha256Hex(stableStringify({ ...body }));
+    const vmzDir = path.join(outDir, '_vmz');
+    mkdirSync(vmzDir, { recursive: true });
+    const file = path.join(vmzDir, 'pack-manifest.json');
+    writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+    return { manifest: body, path: file };
+}
+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

@@ -12,11 +12,20 @@ export declare function importMaybeTs(full: any): Promise<any>;
 /**
  * Load `vmz.config.*` from project root (+ optional root `vmz.plugin.*`).
  * @param {string} project
- * @returns {Promise<{ plugins: import('@vmz/plugin').VmzPlugin[], engines: import('@vmz/plugin').VmzEngines, path: string | null, pluginPath: string | null }>}
+ * @returns {Promise<{
+ *   plugins: import('@vmz/plugin').VmzPlugin[],
+ *   engines: import('@vmz/plugin').VmzEngines,
+ *   delivery: import('@vmz/plugin').DeliveryAuthoring | null,
+ *   application: { id?: string } | null,
+ *   path: string | null,
+ *   pluginPath: string | null,
+ * }>}
  */
 export declare function loadVmzConfig(project: any): Promise<{
     plugins: any[];
     engines: {};
+    delivery: any;
+    application: any;
     path: any;
     pluginPath: any;
 }>;

package/dist/plugin-host.js

@@ -32,13 +32,24 @@ export async function importMaybeTs(full) {
 /**
  * Load `vmz.config.*` from project root (+ optional root `vmz.plugin.*`).
  * @param {string} project
- * @returns {Promise<{ plugins: import('@vmz/plugin').VmzPlugin[], engines: import('@vmz/plugin').VmzEngines, path: string | null, pluginPath: string | null }>}
+ * @returns {Promise<{
+ *   plugins: import('@vmz/plugin').VmzPlugin[],
+ *   engines: import('@vmz/plugin').VmzEngines,
+ *   delivery: import('@vmz/plugin').DeliveryAuthoring | null,
+ *   application: { id?: string } | null,
+ *   path: string | null,
+ *   pluginPath: string | null,
+ * }>}
  */
 export async function loadVmzConfig(project) {
     /** @type {import('@vmz/plugin').VmzPlugin[]} */
     const plugins = [];
     /** @type {import('@vmz/plugin').VmzEngines} */
     let engines = {};
+    /** @type {import('@vmz/plugin').DeliveryAuthoring | null} */
+    let delivery = null;
+    /** @type {{ id?: string } | null} */
+    let application = null;
     /** @type {string | null} */
     let configPath = null;
     /** @type {string | null} */
@@ -51,6 +62,12 @@ export async function loadVmzConfig(project) {
         const cfg = await importMaybeTs(full);
         const raw = cfg?.plugins ?? [];
         engines = cfg?.engines && typeof cfg.engines === 'object' ? { ...cfg.engines } : {};
+        if (cfg?.delivery && typeof cfg.delivery === 'object') {
+            delivery = cfg.delivery;
+        }
+        if (cfg?.application && typeof cfg.application === 'object') {
+            application = cfg.application;
+        }
         for (const entry of raw) {
             plugins.push(await resolvePluginEntry(project, entry));
         }
@@ -64,7 +81,7 @@ export async function loadVmzConfig(project) {
         plugins.push(await resolvePluginEntry(project, full));
         break;
     }
-    return { plugins, engines, path: configPath, pluginPath };
+    return { plugins, engines, delivery, application, path: configPath, pluginPath };
 }
 /**
  * @param {string} project

package/dist/port.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Probe for a free TCP port starting at `start` (inclusive).
+ * Used by `vmz dev` when `--port` is omitted.
+ *
+ * @param {string} host
+ * @param {number} [start=5173]
+ * @param {number} [maxTries=50]
+ * @returns {Promise<number>}
+ */
+export declare function findAvailablePort(host: any, start?: number, maxTries?: number): Promise<unknown>;

package/dist/port.js

@@ -0,0 +1,46 @@
+// @ts-nocheck
+import net from 'node:net';
+/**
+ * Probe for a free TCP port starting at `start` (inclusive).
+ * Used by `vmz dev` when `--port` is omitted.
+ *
+ * @param {string} host
+ * @param {number} [start=5173]
+ * @param {number} [maxTries=50]
+ * @returns {Promise<number>}
+ */
+export function findAvailablePort(host, start = 5173, maxTries = 50) {
+    const first = Number(start);
+    if (!Number.isFinite(first) || first <= 0) {
+        return Promise.reject(new Error(`invalid start port: ${start}`));
+    }
+    return new Promise((resolve, reject) => {
+        let port = first;
+        const attempt = () => {
+            if (port > first + maxTries) {
+                reject(new Error(`no free port in ${first}..${first + maxTries} on ${host}`));
+                return;
+            }
+            const server = net.createServer();
+            server.unref();
+            server.once('error', (err) => {
+                if (err && err.code === 'EADDRINUSE') {
+                    port += 1;
+                    attempt();
+                    return;
+                }
+                reject(err);
+            });
+            server.once('listening', () => {
+                server.close((closeErr) => {
+                    if (closeErr)
+                        reject(closeErr);
+                    else
+                        resolve(port);
+                });
+            });
+            server.listen(port, host);
+        };
+        attempt();
+    });
+}