@vmz/vmz 0.0.2 → 0.0.4

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 /**
- * Node CLI command implementations (N2).
+ * Node CLI command implementations .
  */
 /**
  * @param {string[]} argv
@@ -7,9 +7,17 @@
 export declare function parseArgs(argv: any): {
     _: any[];
 };
+export declare function printGlobalHelp(): void;
+export declare function printProjectHelp(): void;
+/** @deprecated use printProjectHelp / printGlobalHelp */
 export declare function printHelp(): void;
 /**
  * @param {string[]} argv
+ * @param {{
+ * cwd?: string,
+ * thisPackageRoot?: string,
+ * reexec?: (bin: string, argv: string[]) => Promise<number>,
+ * }} [opts]
  * @returns {Promise<number>}
  */
-export declare function runCli(argv: any): Promise<any>;
+export declare function runCli(argv: any, opts?: {}): Promise<any>;

package/dist/cli.js

@@ -1,21 +1,29 @@
 // @ts-nocheck
 /**
- * Node CLI command implementations (N2).
+ * Node CLI command implementations .
  */
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { copyFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { HOST_PROTOCOL, createWorkspace, getProtocolVersions } from './index.js';
+import { HOST_PROTOCOL, createWorkspace, getProtocolVersions, resolveCoreRuntimeDist } from './index.js';
 import { createDevSession } from './dev-session.js';
+import { gateGlobalProjectCommand, getInvocationContext, isGlobalAllowedCommand } from './invocation.js';
 import { log } from './log.js';
+import { findAvailablePort } from './port.js';
 import { readPackageMeta, resolveWorkspaceDirs } from './resolve.js';
 import { cmdTest } from './test-cmd.js';
 import { cmdDocument } from './document-cmd.js';
 import { buildIntegratedDocuments, projectHasDocuments } from './document-integrate.js';
 import { cmdLocale } from './locale-cmd.js';
+import { emitLocaleRuntimeModules, localeHasErrors } from './locale-check.js';
 import { cmdApplication } from './application-cmd.js';
+import { cmdArtifact } from './release-cmd.js';
 import { cmdRefactor } from './refactor-cmd.js';
 import { cmdExplain } from './explain-cmd.js';
+import { resolveNativeVmzCli } from './resolve-native-cli.js';
+import { emitWebStatic } from './static-emit.js';
+import { emitSiteDelivery } from './site-delivery.js';
+import { loadVmzConfig } from './plugin-host.js';
 /**
  * @param {string[]} argv
  */
@@ -61,29 +69,62 @@ export function parseArgs(argv) {
     }
     return out;
 }
-export function printHelp() {
-    console.log(`vmz — Node toolchain host (N-API workspace)
+export function printGlobalHelp() {
+    console.log(`vmz — global mode (scaffold only)
+
+Install faces: @vmz/core (runtime) · @vmz/vmz (this CLI) · optional @vmz/ui / @vmz/plugin-*
+
+Three install modes:
+  developer  monorepo source (packages/runtimes/vmz) — full CLI
+  project    app node_modules/@vmz/vmz — full CLI
+  global     npm/pnpm -g — only new/init/help/version
+
+You are in global mode. Pin \`@vmz/vmz\` in the app so check/build/lsp
+use a traceable project install.
+
+Usage:
+  vmz new|init <dir>            Scaffold (native CLI; Node only gates + forwards)
+  vmz version                   Show host + native protocol versions
+  vmz help                      Show this help
+
+Project commands:
+  pnpm add @vmz/core && pnpm add -D @vmz/vmz
+  pnpm exec vmz check
+  # or: vmz new my-app && cd my-app && pnpm install
+
+If a project \`node_modules/@vmz/vmz\` exists, a global
+\`vmz <cmd>\` re-execs that bin.
+`);
+}
+export function printProjectHelp() {
+    console.log(`vmz — Node toolchain host (project / developer mode)
 
 Usage:
+  vmz new|init <dir>            Scaffold a minimal app (native CLI)
   vmz check [path]              Check project via Workspace
   vmz build [path] [options]    Build project via Workspace
   vmz serve [path] [options]    Serve dist (optional --build)
   vmz dev [path] [options]      Long-lived rebuild session (no CLI spawn)
   vmz format [path] [--check]   Format .vmz via N-API (oxc codegen)
   vmz lint [path] [--deny-warnings]  Lint (= check) via N-API
-  vmz test [path] [options]     Native test discover / report (T0+)
-  vmz document|docs <cmd>       Project /documents domain (D0: check)
-  vmz application <cmd>         Application Collection / Mount (M0–M5)
-  vmz refactor <cmd>            DX rename plans / apply (X1)
+  vmz test [path] [options]     Native test discover / report
+  vmz document|docs <cmd>       Project /documents domain 
+  vmz application <cmd>         Application Collection / Mount 
+  vmz artifact <cmd>            Release pack / publish / rollback / diff (A3)
+  vmz refactor <cmd>            DX rename plans / apply 
   vmz explain [style] <target>  DX causal explain (style Theme chain)
+  vmz lsp [root] [--out-dir]    Language server (stdio; native CLI)
+  vmz mcp [root] [--out-dir]    MCP server (stdio; native CLI)
   vmz version                   Show host + native protocol versions
   vmz help                      Show this help
 
 Options:
   --out-dir, -o <dir>   Output directory (default: dist)
   --release             Release build (build only)
+  --profile <name>      Delivery profile after build (web-static)
+  --origin <url>        Site origin for web-static canonical/sitemap
   --host <host>         Listen host (default: 127.0.0.1)
-  --port <port>         Listen port (default: 5173)
+  --port <port>         Listen port (dev: omit = auto from 5173; set = lock)
   --poll-ms <ms>        Dev watch poll interval (default: 300)
   --build               Build before serve
   --check               Format check-only (format)
@@ -99,21 +140,51 @@ Options:
   --strict              Strict document locale/PageKey coverage (document check)
 `);
 }
+/** @deprecated use printProjectHelp / printGlobalHelp */
+export function printHelp() {
+    printProjectHelp();
+}
 /**
  * @param {string[]} argv
+ * @param {{
+ * cwd?: string,
+ * thisPackageRoot?: string,
+ * reexec?: (bin: string, argv: string[]) => Promise<number>,
+ * }} [opts]
  * @returns {Promise<number>}
  */
-export async function runCli(argv) {
+export async function runCli(argv, opts = {}) {
     const [cmd, ...rest] = argv;
+    const inv = getInvocationContext({
+        cwd: opts.cwd,
+        thisPackageRoot: opts.thisPackageRoot,
+    });
     if (!cmd || cmd === 'help' || cmd === '-h' || cmd === '--help') {
-        printHelp();
+        if (inv.mode === 'global')
+            printGlobalHelp();
+        else
+            printProjectHelp();
         return 0;
     }
     if (cmd === 'version' || cmd === '-V' || cmd === '--version') {
         return cmdVersion();
     }
+    if (!isGlobalAllowedCommand(cmd)) {
+        const gated = await gateGlobalProjectCommand({
+            argv,
+            cwd: opts.cwd,
+            thisPackageRoot: opts.thisPackageRoot,
+            reexec: opts.reexec,
+            logError: (msg) => log.error(msg),
+        });
+        if (gated.action === 'exit')
+            return gated.code;
+    }
     const args = parseArgs(rest);
     switch (cmd) {
+        case 'new':
+        case 'init':
+            return cmdNativeForward(cmd, rest);
         case 'check':
             return cmdCheck(args);
         case 'build':
@@ -138,16 +209,57 @@ export async function runCli(argv) {
         case 'applications':
         case 'app':
             return cmdApplication(rest);
+        case 'artifact':
+        case 'artifacts':
+        case 'release':
+            return cmdArtifact(rest);
         case 'refactor':
             return cmdRefactor(rest);
         case 'explain':
             return cmdExplain(rest);
+        case 'lsp':
+            return cmdNativeForward('lsp', rest);
+        case 'mcp':
+            return cmdNativeForward('mcp', rest);
         default:
             log.error(`unknown command \`${cmd}\``);
-            printHelp();
+            if (inv.mode === 'global')
+                printGlobalHelp();
+            else
+                printProjectHelp();
             return 1;
     }
 }
+/**
+ * Forward to the single native `vmz` binary (vmz-tools).
+ * Scaffold / stdio servers live in Rust — Node only gates + re-execs.
+ *
+ * @param {'new' | 'init' | 'lsp' | 'mcp'} sub
+ * @param {string[]} argv
+ * @returns {Promise<number>}
+ */
+function cmdNativeForward(sub, argv) {
+    const bin = resolveNativeVmzCli();
+    if (!bin) {
+        log.error('native `vmz` CLI not found (vmz-tools).');
+        log.error('Build: cargo build -p vmz-tools');
+        log.error('Or set VMZ_NATIVE to the absolute path of that binary.');
+        return Promise.resolve(1);
+    }
+    return new Promise((resolve) => {
+        const child = spawn(bin, [sub, ...argv], { stdio: 'inherit' });
+        child.on('error', (err) => {
+            log.error(`failed to spawn ${bin}: ${err.message}`);
+            resolve(1);
+        });
+        child.on('exit', (code, signal) => {
+            if (signal)
+                resolve(1);
+            else
+                resolve(code ?? 1);
+        });
+    });
+}
 function cmdVersion() {
     const native = getProtocolVersions();
     console.log(`vmz host ${HOST_PROTOCOL}`);
@@ -217,11 +329,39 @@ async function cmdBuild(args) {
         });
         if (code !== 0)
             return code;
+        const localeEmit = emitLocaleRuntimeModules(project, outDir);
+        if (!localeEmit.ok || localeHasErrors({ diagnostics: localeEmit.diagnostics })) {
+            log.diagnostics(localeEmit.diagnostics ?? []);
+            log.error('locale runtime emit failed');
+            return 1;
+        }
+        if (localeEmit.written.length) {
+            log.info(`locale runtime emit (${localeEmit.written.length} module(s))`);
+        }
         if (projectHasDocuments(project)) {
             const docs = await buildIntegratedDocuments({ projectRoot: project, outDir });
             if (!docs.ok)
                 return 1;
         }
+        const cfg = await loadVmzConfig(project);
+        if (cfg.delivery) {
+            log.info(`site-delivery emit ${outDir}`);
+            const site = emitSiteDelivery(outDir, cfg.delivery, {
+                siteId: cfg.application?.id || undefined,
+            });
+            log.info(`site-delivery ok (digest=${String(site.contract.contractDigest).slice(0, 12)}…)`);
+        }
+        const profile = typeof args.profile === 'string' ? args.profile : '';
+        if (profile === 'web-static') {
+            const origin = typeof args.origin === 'string' ? args.origin : undefined;
+            log.info(`web-static emit ${outDir}`);
+            const result = await emitWebStatic(outDir, { origin });
+            log.info(`web-static ok (${result.htmlFiles.length} html, ${result.skipped.length} skipped, digest=${result.digest.slice(0, 12)}…)`);
+        }
+        else if (profile) {
+            log.error(`unknown build --profile ${profile} (supported: web-static)`);
+            return 1;
+        }
         return 0;
     }
     finally {
@@ -244,8 +384,16 @@ async function cmdServe(args) {
     });
     const hostJs = path.join(outDir, 'vmz-serve-host.mjs');
     if (!existsSync(hostJs)) {
-        log.error(`missing ${hostJs} — run \`vmz build\` first (or pass --build)`);
-        return 1;
+        const coreDist = resolveCoreRuntimeDist();
+        const src = coreDist ? path.join(coreDist, 'serve-host.mjs') : null;
+        if (src && existsSync(src)) {
+            copyFileSync(src, hostJs);
+            log.info(`materialized ${hostJs} from @vmz/core (release builds omit it)`);
+        }
+        else {
+            log.error(`missing ${hostJs} — run \`vmz build\` (without --release) or ensure @vmz/core is installed`);
+            return 1;
+        }
     }
     const host = typeof args.host === 'string' ? args.host : '127.0.0.1';
     const port = Number(args.port ?? 5173);
@@ -287,7 +435,22 @@ async function cmdDev(args) {
         outDir: typeof args['out-dir'] === 'string' ? args['out-dir'] : undefined,
     });
     const host = typeof args.host === 'string' ? args.host : '127.0.0.1';
-    const port = Number(args.port ?? 5173);
+    const portLocked = Object.prototype.hasOwnProperty.call(args, 'port');
+    let port;
+    if (portLocked) {
+        port = Number(args.port);
+        if (!Number.isFinite(port) || port <= 0) {
+            log.error(`invalid --port ${String(args.port)}`);
+            return 1;
+        }
+    }
+    else {
+        const preferred = 5173;
+        port = await findAvailablePort(host, preferred);
+        if (port !== preferred) {
+            log.info(`port ${preferred} busy → using ${port}`);
+        }
+    }
     const pollMs = Number(args['poll-ms'] ?? 300);
     const ac = new AbortController();
     const onSig = () => {

package/dist/content-addressed-assets.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A3: content-addressed assets/<hash> layout for immutable CDN objects.
+ * Logical paths stay available for serve/dev; web-static HTML rewrites to hashed URLs.
+ * Identical bytes → identical asset path (cross-release / cross-source reuse by digest).
+ */
+export declare const CONTENT_ADDRESSED_ASSETS_SCHEMA = "vmz.content_addressed_assets.v0";
+/**
+ * Emit `assets/<sha256>.<ext>` copies and rewrite HTML href/src to hashed URLs.
+ * @param {string} distDir
+ * @param {{ candidates?: string[], rewriteHtml?: boolean }} [opts]
+ */
+export declare function emitContentAddressedAssets(distDir: any, opts?: {}): {
+    manifest: {
+        schema: string;
+        layout: string;
+        immutable: boolean;
+        objectCount: number;
+        objects: any[];
+        rewrittenHtml: number;
+    };
+    assetsDir: string;
+    rewrites: {};
+    manifestPath: string;
+};
+/**
+ * Resolve an immutable object by digest under dist/assets (cross-source reuse).
+ * @param {string} distDir
+ * @param {string} digest
+ * @param {string} [ext]
+ */
+export declare function resolveAssetByDigest(distDir: any, digest: any, ext?: string): {
+    assetPath: string;
+    digest: string;
+    bytes: number;
+};
+/**
+ * Prove two buffers share one asset path (content-address stability).
+ * @param {string} distDir
+ * @param {Buffer|string} a
+ * @param {Buffer|string} b
+ * @param {string} [ext]
+ */
+export declare function assertSharedAssetPath(distDir: any, a: any, b: any, ext?: string): {
+    ok: boolean;
+    reason: string;
+    digestA: string;
+    digestB: string;
+    rel?: undefined;
+    assetPath?: undefined;
+    digest?: undefined;
+} | {
+    ok: boolean;
+    reason: string;
+    rel: string;
+    digestA?: undefined;
+    digestB?: undefined;
+    assetPath?: undefined;
+    digest?: undefined;
+} | {
+    ok: boolean;
+    assetPath: string;
+    digest: string;
+    reason?: undefined;
+    digestA?: undefined;
+    digestB?: undefined;
+    rel?: undefined;
+};
+export declare function contentAddressedAssetsDigest(manifest: any): any;
+export declare function sha256Buffer(buf: any): string;

package/dist/content-addressed-assets.js

@@ -0,0 +1,206 @@
+/**
+ * A3: content-addressed assets/<hash> layout for immutable CDN objects.
+ * Logical paths stay available for serve/dev; web-static HTML rewrites to hashed URLs.
+ * Identical bytes → identical asset path (cross-release / cross-source reuse by digest).
+ */
+// @ts-nocheck
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson, sha256Hex } from './release-pack.js';
+export const CONTENT_ADDRESSED_ASSETS_SCHEMA = 'vmz.content_addressed_assets.v0';
+/** Immutable delivery candidates (client-facing bytes). */
+const DEFAULT_CANDIDATES = [
+    'entry-client.js',
+    'entry-event.js',
+    'vmz.css',
+    'vmz-designs.css',
+    'vmz-dom.js',
+    'vmz-runtime.js',
+    'vmz-http.js',
+    'vmz-client-nav.js',
+];
+/**
+ * Emit `assets/<sha256>.<ext>` copies and rewrite HTML href/src to hashed URLs.
+ * @param {string} distDir
+ * @param {{ candidates?: string[], rewriteHtml?: boolean }} [opts]
+ */
+export function emitContentAddressedAssets(distDir, opts = {}) {
+    const abs = path.resolve(distDir);
+    if (!fs.existsSync(abs)) {
+        throw new Error(`emitContentAddressedAssets: missing dist ${abs}`);
+    }
+    const assetsDir = path.join(abs, 'assets');
+    fs.mkdirSync(assetsDir, { recursive: true });
+    const candidates = Array.isArray(opts.candidates) ? opts.candidates : collectCandidates(abs);
+    /** @type {Array<Record<string, any>>} */
+    const objects = [];
+    /** @type {Record<string, string>} */
+    const rewrites = {};
+    for (const rel of candidates) {
+        const logical = String(rel).replace(/\\/g, '/').replace(/^\//, '');
+        const src = path.join(abs, ...logical.split('/'));
+        if (!fs.existsSync(src) || !fs.statSync(src).isFile())
+            continue;
+        const buf = fs.readFileSync(src);
+        const digest = sha256Hex(buf);
+        const ext = path.extname(logical) || '';
+        const assetRel = `assets/${digest}${ext}`;
+        const dest = path.join(abs, ...assetRel.split('/'));
+        if (!fs.existsSync(dest)) {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.writeFileSync(dest, buf);
+        }
+        else {
+            // Cross-release reuse: identical digest must not be rewritten.
+            const existing = sha256Hex(fs.readFileSync(dest));
+            if (existing !== digest) {
+                throw new Error(`content-address collision at ${assetRel}`);
+            }
+        }
+        objects.push({
+            logicalPath: logical,
+            assetPath: assetRel,
+            digest,
+            bytes: buf.length,
+            immutable: true,
+        });
+        rewrites[`/${logical}`] = `/${assetRel}`;
+        rewrites[logical] = assetRel;
+    }
+    objects.sort((a, b) => (a.logicalPath < b.logicalPath ? -1 : a.logicalPath > b.logicalPath ? 1 : 0));
+    let rewrittenHtml = 0;
+    if (opts.rewriteHtml !== false) {
+        rewrittenHtml = rewriteHtmlReferences(abs, rewrites);
+    }
+    const manifest = {
+        schema: CONTENT_ADDRESSED_ASSETS_SCHEMA,
+        layout: 'assets/<sha256>.<ext>',
+        immutable: true,
+        objectCount: objects.length,
+        objects,
+        rewrittenHtml,
+    };
+    manifest.manifestDigest = sha256Hex(canonicalJson({ ...manifest, manifestDigest: undefined }));
+    const vmzDir = path.join(abs, '_vmz');
+    fs.mkdirSync(vmzDir, { recursive: true });
+    const outPath = path.join(vmzDir, 'content-addressed-assets.json');
+    fs.writeFileSync(outPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    return { manifest, assetsDir, rewrites, manifestPath: outPath };
+}
+/**
+ * Resolve an immutable object by digest under dist/assets (cross-source reuse).
+ * @param {string} distDir
+ * @param {string} digest
+ * @param {string} [ext]
+ */
+export function resolveAssetByDigest(distDir, digest, ext = '') {
+    const d = String(digest || '').trim();
+    if (!/^[a-f0-9]{64}$/i.test(d))
+        return null;
+    const suffix = ext && !ext.startsWith('.') ? `.${ext}` : ext;
+    const rel = `assets/${d}${suffix}`;
+    const abs = path.join(distDir, ...rel.split('/'));
+    if (!fs.existsSync(abs))
+        return null;
+    return { assetPath: rel, digest: d.toLowerCase(), bytes: fs.statSync(abs).size };
+}
+/**
+ * Prove two buffers share one asset path (content-address stability).
+ * @param {string} distDir
+ * @param {Buffer|string} a
+ * @param {Buffer|string} b
+ * @param {string} [ext]
+ */
+export function assertSharedAssetPath(distDir, a, b, ext = '.js') {
+    const da = sha256Hex(a);
+    const db = sha256Hex(b);
+    if (da !== db) {
+        return { ok: false, reason: 'digests differ', digestA: da, digestB: db };
+    }
+    const assetsDir = path.join(distDir, 'assets');
+    fs.mkdirSync(assetsDir, { recursive: true });
+    const rel = `assets/${da}${ext}`;
+    const dest = path.join(distDir, ...rel.split('/'));
+    fs.writeFileSync(dest, typeof a === 'string' ? Buffer.from(a) : a);
+    // Second write of identical bytes must be reuse, not fork.
+    fs.writeFileSync(dest, typeof b === 'string' ? Buffer.from(b) : b);
+    const again = resolveAssetByDigest(distDir, da, ext);
+    if (!again || again.assetPath !== rel) {
+        return { ok: false, reason: 'resolve missed shared path', rel };
+    }
+    return { ok: true, assetPath: rel, digest: da };
+}
+function collectCandidates(distDir) {
+    /** @type {string[]} */
+    const out = [];
+    for (const name of DEFAULT_CANDIDATES) {
+        if (fs.existsSync(path.join(distDir, name)))
+            out.push(name);
+    }
+    // Include top-level *.client.js and pages/**/*.client.js referenced by resume.
+    walk(distDir, distDir, (rel) => {
+        if (/\.client\.js$/i.test(rel))
+            out.push(rel);
+    });
+    return [...new Set(out)].sort();
+}
+function walk(root, dir, onFile) {
+    for (const name of fs.readdirSync(dir)) {
+        if (name === 'assets' || name === '_vmz' || name === 'node_modules')
+            continue;
+        const full = path.join(dir, name);
+        const st = fs.statSync(full);
+        if (st.isDirectory())
+            walk(root, full, onFile);
+        else
+            onFile(path.relative(root, full).replace(/\\/g, '/'));
+    }
+}
+/**
+ * @param {string} distDir
+ * @param {Record<string, string>} rewrites map `/logical` → `/assets/hash.ext`
+ */
+function rewriteHtmlReferences(distDir, rewrites) {
+    const pairs = Object.entries(rewrites)
+        .filter(([from]) => from.startsWith('/'))
+        .sort((a, b) => b[0].length - a[0].length);
+    if (!pairs.length)
+        return 0;
+    let count = 0;
+    walkHtml(distDir, (file) => {
+        let text = fs.readFileSync(file, 'utf8');
+        let next = text;
+        for (const [from, to] of pairs) {
+            // href="/x" src="/x" and unquoted variants in attributes
+            next = next.split(from).join(to);
+        }
+        if (next !== text) {
+            fs.writeFileSync(file, next, 'utf8');
+            count += 1;
+        }
+    });
+    return count;
+}
+function walkHtml(dir, onFile) {
+    const stack = [dir];
+    while (stack.length) {
+        const cur = stack.pop();
+        for (const name of fs.readdirSync(cur)) {
+            if (name === 'assets' || name === '_vmz' || name === 'node_modules')
+                continue;
+            const full = path.join(cur, name);
+            const st = fs.statSync(full);
+            if (st.isDirectory())
+                stack.push(full);
+            else if (name.endsWith('.html'))
+                onFile(full);
+        }
+    }
+}
+export function contentAddressedAssetsDigest(manifest) {
+    return manifest.manifestDigest || sha256Hex(canonicalJson({ ...manifest, manifestDigest: undefined }));
+}
+export function sha256Buffer(buf) {
+    return crypto.createHash('sha256').update(buf).digest('hex');
+}

package/dist/dev-session.d.ts

@@ -1,8 +1,8 @@
 /**
- * Long-lived Node dev session (N2/N4).
+ * Long-lived Node dev session (/session).
  *
  * Rebuilds go through the N-API `Workspace` — never spawn `cargo` / `vmz-tools`.
- * N4: only dirty leaves are marked; Workspace emits affected deployment units.
+ * session: only dirty leaves are marked; Workspace emits affected deployment units.
  */
 /**
  * @typedef {object} DevSessionOptions