@vmz/vmz 0.3.6 → 0.3.8

package/dist/workspace/plugin-host.js

@@ -4,30 +4,57 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { createJiti } from 'jiti';
 import { PLUGIN_PROTOCOL as PLUGIN_PROTOCOL_PKG, contentHash, defineConfig, definePlugin } from '@vmz/plugin';
 import { log } from './log.js';
 import { resolveWorkspacePackages } from './packages.js';
 export { contentHash, defineConfig, definePlugin };
 export const PLUGIN_PROTOCOL = PLUGIN_PROTOCOL_PKG;
-const CONFIG_NAMES = ['vmz.config.ts', 'vmz.config.mts', 'vmz.config.mjs', 'vmz.config.js'];
+export const CONFIG_NAMES = ['vmz.config.ts', 'vmz.config.mts', 'vmz.config.mjs', 'vmz.config.js'];
 const ROOT_PLUGIN_NAMES = ['vmz.plugin.ts', 'vmz.plugin.mts', 'vmz.plugin.mjs', 'vmz.plugin.js'];
+export const CONFIG_LOAD_FAILED = 'vmz::config::load_failed';
+export const PLUGIN_ENTRY_INVALID = 'vmz::plugin::invalid_entry';
 /**
+ * Load an ES module through the Node host (native `import()`).
+ * Project config and plugin entries must be erasable TS or JS: the host never
+ * runs a runtime TypeScript transpiler.
  * @param {string} full
  * @returns {Promise<any>}
  */
-export async function importMaybeTs(full) {
-    const ext = path.extname(full).toLowerCase();
-    if (ext === '.ts' || ext === '.mts') {
-        const jiti = createJiti(import.meta.url, {
-            interopDefault: true,
-            moduleCache: false,
-        });
-        return jiti(full);
-    }
+async function importHostModule(full) {
     const mod = await import(pathToFileURL(full).href);
     return mod.default ?? mod;
 }
+function errorDetail(err) {
+    const parts = [];
+    let cur = err;
+    for (let i = 0; cur && i < 4; i += 1) {
+        const message = cur instanceof Error ? cur.message : String(cur);
+        if (message && !parts.includes(message))
+            parts.push(message);
+        cur = cur && typeof cur === 'object' && 'cause' in cur ? cur.cause : null;
+    }
+    return parts.join(' ← ') || 'unknown error';
+}
+/**
+ * Build a host error carrying a product diagnostic (one print at the CLI boundary).
+ * @param {string} code
+ * @param {string} sourcePath
+ * @param {unknown} err
+ */
+function configDiagnosticError(code, sourcePath, err) {
+    const detail = errorDetail(err);
+    const error = new Error(detail);
+    if (err instanceof Error)
+        error.cause = err;
+    return Object.assign(error, {
+        diagnostic: {
+            code,
+            severity: 'error',
+            path: sourcePath,
+            args: { detail },
+        },
+    });
+}
 /**
  * Load `vmz.config.*` from project root (+ optional root `vmz.plugin.*`).
  * @param {string} project
@@ -61,7 +88,13 @@ export async function loadVmzConfig(project) {
         if (!existsSync(full))
             continue;
         configPath = full;
-        const cfg = await importMaybeTs(full);
+        let cfg;
+        try {
+            cfg = await importHostModule(full);
+        }
+        catch (err) {
+            throw configDiagnosticError(CONFIG_LOAD_FAILED, full, err);
+        }
         const raw = cfg?.plugins ?? [];
         engines = cfg?.engines && typeof cfg.engines === 'object' ? { ...cfg.engines } : {};
         if (cfg?.delivery && typeof cfg.delivery === 'object') {
@@ -96,9 +129,11 @@ async function resolvePluginEntry(project, entry) {
     let value = entry;
     if (typeof value === 'string') {
         const resolved = path.isAbsolute(value) ? value : path.join(project, value);
-        value = await importMaybeTs(resolved);
-        if (value && typeof value === 'object' && 'default' in value && value.default) {
-            value = value.default;
+        try {
+            value = await importHostModule(resolved);
+        }
+        catch (err) {
+            throw configDiagnosticError(PLUGIN_ENTRY_INVALID, resolved, err);
         }
     }
     value = await value;
@@ -106,7 +141,8 @@ async function resolvePluginEntry(project, entry) {
         return value;
     if (value?.name && value?.stages)
         return definePlugin(value);
-    throw new Error(`invalid vmz plugin entry: ${String(entry)}`);
+    const sourcePath = typeof entry === 'string' ? (path.isAbsolute(entry) ? entry : path.join(project, entry)) : '';
+    throw configDiagnosticError(PLUGIN_ENTRY_INVALID, sourcePath, new Error(`invalid vmz plugin entry: ${String(entry)}`));
 }
 /**
  * Collect + apply contribution batches for the given stages onto a Workspace.
@@ -289,17 +325,17 @@ function buildMathFacade(defaultEngine, engines) {
         return `  <${tag} ${kw}="(engine || ${defaultLit}) === ${engLit}" :tex="tex" :display="display" />`;
     })
         .join('\n');
-    return `<template>
-${branches}
-</template>
-
-<script client>
-export default class Math {
-  public tex: string = '';
-  public display: boolean = false;
-  public engine: string | null = null;
-}
-</script>
+    return `<template>
+${branches}
+</template>
+
+<script client>
+export default class Math {
+  public tex: string = '';
+  public display: boolean = false;
+  public engine: string | null = null;
+}
+</script>
 `;
 }
 /**
@@ -316,18 +352,18 @@ function buildCodeFacade(defaultEngine, engines) {
         return `  <${tag} ${kw}="(engine || ${defaultLit}) === ${engLit}" :code="code" :lang="lang" :theme="theme" />`;
     })
         .join('\n');
-    return `<template>
-${branches}
-</template>
-
-<script client>
-export default class Code {
-  public code: string = '';
-  public lang: string = 'text';
-  public theme: string | null = null;
-  public engine: string | null = null;
-}
-</script>
+    return `<template>
+${branches}
+</template>
+
+<script client>
+export default class Code {
+  public code: string = '';
+  public lang: string = 'text';
+  public theme: string | null = null;
+  public engine: string | null = null;
+}
+</script>
 `;
 }
 /**
@@ -344,16 +380,16 @@ function buildMarkdownFacade(defaultEngine, engines) {
         return `  <${tag} ${kw}="(engine || ${defaultLit}) === ${engLit}" :source="source" />`;
     })
         .join('\n');
-    return `<template>
-${branches}
-</template>
-
-<script client>
-export default class Markdown {
-  public source: string = '';
-  public engine: string | null = null;
-}
-</script>
+    return `<template>
+${branches}
+</template>
+
+<script client>
+export default class Markdown {
+  public source: string = '';
+  public engine: string | null = null;
+}
+</script>
 `;
 }
 /** Embed a JS string literal inside a double-quoted Vue attribute. */

package/dist/workspace/public-api.d.ts

@@ -46,6 +46,10 @@ export declare function lowerMiniprogramBindingEventJson(rootPath: string): stri
 export declare function lowerMiniprogramStructureJson(rootPath: string): string;
 export declare function lowerMiniprogramRouteServerStyleJson(rootPath: string): string;
 export declare function lowerMiniprogramToolingDeployJson(rootPath: string): string;
+/**
+ * Consume the prepared `dist/_vmz/wechat-packaging.json` snapshot.
+ * Callers that start from a config must `await prepareWechatPackaging(rootPath)` first.
+ */
 export declare function lowerMiniprogramWechatPackagingJson(rootPath: string): string;
 export declare function lowerMiniprogramMultiAdapterJson(rootPath: string): string;
 import { createMiniHost } from './mini-host.js';
@@ -99,7 +103,7 @@ export { CDN_POLICY_MANIFEST_SCHEMA, CDN_ADAPTER_PROJECTION_SCHEMA, CACHE_HTML,
 export { SITE_DELIVERY_CONTRACT_SCHEMA, SITE_DELIVERY_RESOLUTION_SCHEMA, defineSite, normalizeSiteDelivery, normalizeSourceProbe, resolveSiteRelease, probeReleaseDirectory, emitSiteDelivery, } from './site-delivery.js';
 export { EMBEDDED_RESOURCE_INDEX_SCHEMA, emitEmbeddedPackaging } from './embedded-packaging.js';
 export { SERVER_LANG_IDS, SERVER_LANG_ALIASES, SERVER_LANGUAGE_BACKENDS, resolveServerLanguage, assertLangRuntimePair, } from './server-language-backend.js';
-export { WECHAT_PACKAGING_SCHEMA, WECHAT_PACKAGING_REL, wechatPackagingFromDelivery, materializeWechatPackaging } from './wechat-packaging.js';
+export { WECHAT_PACKAGING_SCHEMA, WECHAT_PACKAGING_REL, wechatPackagingFromDelivery, materializeWechatPackaging, prepareWechatPackaging, } from './wechat-packaging.js';
 export { DELIVERY_PROFILE_AUTHORING_SCHEMA, BUILD_PROFILE_SELECTION_SCHEMA, ASSEMBLIES, SERVER_RUNTIMES, BUILTIN_PROFILES, pickSiteAuthoring, pickDeliveryPackaging, normalizeProfileArtifactName, resolveProfileArtifactDir, normalizeDeliveryAuthoring, selectBuildProfile, semanticIdsForAssembly, } from '../delivery/delivery-profile.js';
 export { PACK_MANIFEST_SCHEMA, packFromDeploymentIr, ensureRuntimeCompanions } from './pack.js';
 export { SERVER_ARTIFACT_SCHEMA, HTTP_CONTRACT_SCHEMA, SERVER_RUNTIME_ADAPTER_SCHEMA, emitServerArtifact, projectServerRuntimeAdapter, } from './server-artifact.js';

package/dist/workspace/public-api.js

@@ -8,7 +8,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { materializeServeHostRuntime, SERVE_HOST_RUNTIME_FILES } from '../host-materialize/serve-host-runtime.js';
 import { resolveCoreRuntimeDist } from './runtime-dist.js';
-import { materializeWechatPackaging } from './wechat-packaging.js';
 export { resolveCoreRuntimeDist } from './runtime-dist.js';
 export { loadHostRuntimeFilesManifest, serveHostRuntimeFilePairs } from '../host-materialize/host-runtime-files.js';
 export { materializeServeHostRuntime, SERVE_HOST_RUNTIME_FILES } from '../host-materialize/serve-host-runtime.js';
@@ -125,25 +124,7 @@ export function createWorkspace(options) {
             pluginProtocol: protocol.pluginProtocol,
         },
     });
-    const pack = ws.lowerMiniprogramWechatPackaging.bind(ws);
-    const wrappedPack = () => {
-        materializeWechatPackaging(options.root);
-        return pack();
-    };
-    try {
-        ws.lowerMiniprogramWechatPackaging = wrappedPack;
-        return ws;
-    }
-    catch {
-        return new Proxy(ws, {
-            get(target, prop, receiver) {
-                if (prop === 'lowerMiniprogramWechatPackaging')
-                    return wrappedPack;
-                const value = Reflect.get(target, prop, receiver);
-                return typeof value === 'function' ? value.bind(target) : value;
-            },
-        });
-    }
+    return ws;
 }
 /** frozen application composition protocol catalog. */
 export function queryApplicationProtocolCatalog() {
@@ -183,9 +164,12 @@ export function lowerMiniprogramToolingDeployJson(rootPath) {
     const native = loadNative();
     return native.lowerMiniprogramToolingDeployJson(rootPath);
 }
+/**
+ * Consume the prepared `dist/_vmz/wechat-packaging.json` snapshot.
+ * Callers that start from a config must `await prepareWechatPackaging(rootPath)` first.
+ */
 export function lowerMiniprogramWechatPackagingJson(rootPath) {
     const native = loadNative();
-    materializeWechatPackaging(rootPath);
     return native.lowerMiniprogramWechatPackagingJson(rootPath);
 }
 export function lowerMiniprogramMultiAdapterJson(rootPath) {
@@ -307,7 +291,7 @@ export { CDN_POLICY_MANIFEST_SCHEMA, CDN_ADAPTER_PROJECTION_SCHEMA, CACHE_HTML,
 export { SITE_DELIVERY_CONTRACT_SCHEMA, SITE_DELIVERY_RESOLUTION_SCHEMA, defineSite, normalizeSiteDelivery, normalizeSourceProbe, resolveSiteRelease, probeReleaseDirectory, emitSiteDelivery, } from './site-delivery.js';
 export { EMBEDDED_RESOURCE_INDEX_SCHEMA, emitEmbeddedPackaging } from './embedded-packaging.js';
 export { SERVER_LANG_IDS, SERVER_LANG_ALIASES, SERVER_LANGUAGE_BACKENDS, resolveServerLanguage, assertLangRuntimePair, } from './server-language-backend.js';
-export { WECHAT_PACKAGING_SCHEMA, WECHAT_PACKAGING_REL, wechatPackagingFromDelivery, materializeWechatPackaging } from './wechat-packaging.js';
+export { WECHAT_PACKAGING_SCHEMA, WECHAT_PACKAGING_REL, wechatPackagingFromDelivery, materializeWechatPackaging, prepareWechatPackaging, } from './wechat-packaging.js';
 export { DELIVERY_PROFILE_AUTHORING_SCHEMA, BUILD_PROFILE_SELECTION_SCHEMA, ASSEMBLIES, SERVER_RUNTIMES, BUILTIN_PROFILES, pickSiteAuthoring, pickDeliveryPackaging, normalizeProfileArtifactName, resolveProfileArtifactDir, normalizeDeliveryAuthoring, selectBuildProfile, semanticIdsForAssembly, } from '../delivery/delivery-profile.js';
 export { PACK_MANIFEST_SCHEMA, packFromDeploymentIr, ensureRuntimeCompanions } from './pack.js';
 export { SERVER_ARTIFACT_SCHEMA, HTTP_CONTRACT_SCHEMA, SERVER_RUNTIME_ADAPTER_SCHEMA, emitServerArtifact, projectServerRuntimeAdapter, } from './server-artifact.js';

package/dist/workspace/wechat-packaging.d.ts

@@ -16,8 +16,15 @@ interface WechatPackagingSpec {
 }
 export declare function wechatPackagingFromDelivery(delivery: unknown): WechatPackagingSpec;
 /**
- * Load `vmz.config.*` and write the WeChat packaging contract for the Rust packer.
+ * Write the WeChat packaging contract from an already-evaluated delivery snapshot.
+ * Sync by contract: the native packer must consume prepared data, never read a config.
+ * @param {string} project
+ * @param {unknown} delivery
+ */
+export declare function materializeWechatPackaging(project: string, delivery: unknown): WechatPackagingSpec;
+/**
+ * Async host entry: evaluate `vmz.config.*` once, then prepare the packaging snapshot.
  * @param {string} project
  */
-export declare function materializeWechatPackaging(project: any): WechatPackagingSpec;
+export declare function prepareWechatPackaging(project: string): Promise<WechatPackagingSpec>;
 export {};

package/dist/workspace/wechat-packaging.js

@@ -2,27 +2,13 @@
  * Materialize `defineConfig({ delivery: { packaging: { wechat } } })` for wechat_pack.
  * Pure data only. Writes `dist/_vmz/wechat-packaging.json` (not a second config entry).
  */
-import { existsSync, mkdirSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
 import path from 'node:path';
-import { createJiti } from 'jiti';
 import { pickDeliveryPackaging } from '../delivery/delivery-profile.js';
 import { writePrettyJsonFile } from './pretty-json.js';
+import { loadVmzConfig } from './plugin-host.js';
 export const WECHAT_PACKAGING_SCHEMA = 'vmz.target.wechat_packaging.v0';
 export const WECHAT_PACKAGING_REL = 'dist/_vmz/wechat-packaging.json';
-const CONFIG_NAMES = ['vmz.config.ts', 'vmz.config.mts', 'vmz.config.mjs', 'vmz.config.js'];
-function loadConfigSync(project) {
-    for (const name of CONFIG_NAMES) {
-        const full = path.join(project, name);
-        if (!existsSync(full))
-            continue;
-        const jiti = createJiti(import.meta.url, {
-            interopDefault: true,
-            moduleCache: false,
-        });
-        return jiti(full);
-    }
-    return null;
-}
 export function wechatPackagingFromDelivery(delivery) {
     const diagnostics = [];
     const packaging = pickDeliveryPackaging(delivery && typeof delivery === 'object' ? delivery : {}, diagnostics);
@@ -40,14 +26,23 @@ export function wechatPackagingFromDelivery(delivery) {
     return out;
 }
 /**
- * Load `vmz.config.*` and write the WeChat packaging contract for the Rust packer.
+ * Write the WeChat packaging contract from an already-evaluated delivery snapshot.
+ * Sync by contract: the native packer must consume prepared data, never read a config.
  * @param {string} project
+ * @param {unknown} delivery
  */
-export function materializeWechatPackaging(project) {
-    const cfg = loadConfigSync(project);
-    const spec = wechatPackagingFromDelivery(cfg?.delivery);
+export function materializeWechatPackaging(project, delivery) {
+    const spec = wechatPackagingFromDelivery(delivery);
     const abs = path.join(project, WECHAT_PACKAGING_REL);
     mkdirSync(path.dirname(abs), { recursive: true });
     writePrettyJsonFile(abs, spec);
     return spec;
 }
+/**
+ * Async host entry: evaluate `vmz.config.*` once, then prepare the packaging snapshot.
+ * @param {string} project
+ */
+export async function prepareWechatPackaging(project) {
+    const cfg = await loadVmzConfig(project);
+    return materializeWechatPackaging(project, cfg.delivery);
+}

package/locales/en-US/cli.json

@@ -1,126 +1,126 @@
-{
-    "cli.intro.project": "vmz — Node toolchain host (`@vmz/vmz`, N-API)",
-    "cli.intro.global": "vmz — global install (help/version only). Pin `@vmz/vmz` in the app (`pnpm add -D @vmz/vmz`) and run `pnpm exec vmz <command>`. A global `vmz` re-execs the nearest project bin when present.",
-    "cli.cmd.check": "Check project via Workspace",
-    "cli.cmd.build": "Build project via Workspace",
-    "cli.cmd.serve": "Serve dist (optional --build)",
-    "cli.cmd.dev": "Rebuild session",
-    "cli.cmd.format": "Format workspace surfaces and .vmz via vmz.config format",
-    "cli.opt.format-no-javascript": "Skip JS/TS workspace format",
-    "cli.opt.format-no-rust": "Skip cargo fmt",
-    "cli.opt.format-no-vmz": "Skip .vmz author format",
-    "cli.cmd.lint": "Lint (= check) via N-API",
-    "cli.cmd.test": "Native test discover / report",
-    "cli.cmd.document": "Project /documents domain",
-    "cli.cmd.document.check": "Check locale tree + links/anchors + evidence",
-    "cli.cmd.document.build": "Static HTML + view + evidence + designs CSS",
-    "cli.cmd.locale": "Locale domain",
-    "cli.cmd.locale.check": "Check locales.json5 + catalogs + param contracts",
-    "cli.cmd.locale.list": "List LocaleIds",
-    "cli.cmd.locale.emit-types": "Emit #locales/* .d.ts stubs",
-    "cli.cmd.locale.rename": "MessageId rename plan",
-    "cli.cmd.locale.runtime-check": "LocaleContext / FormatterContext / SSR parity",
-    "cli.cmd.locale.router-check": "Route realization / canonical / hreflang",
-    "cli.cmd.locale.delivery-check": "Multi-host LocaleDeliveryResolution",
-    "cli.cmd.locale.explain": "Explain MessageId",
-    "cli.cmd.locale.diff": "Diff two locales",
-    "cli.cmd.locale.extract": "Hardcoded text sink check",
-    "cli.cmd.locale.pseudo": "Pseudo-localize catalog",
-    "cli.cmd.locale.conformance": "Cross-host MessageId/hash conformance",
-    "cli.cmd.application": "Application Collection / Mount",
-    "cli.cmd.application.check": "Validate descriptors + applications.config.json5",
-    "cli.cmd.application.list": "List ApplicationIds / collections / mounts",
-    "cli.cmd.application.schemas": "Print frozen protocol catalog JSON",
-    "cli.cmd.application.relocatable": "ApplicationBase / non_relocatable_url proof",
-    "cli.cmd.application.relocate": "Apply ApplicationBase to relocation manifest",
-    "cli.cmd.application.artifacts": "ApplicationArtifact + MountTable boundary",
-    "cli.cmd.application.isolation": "Isolation namespaces + failure containment",
-    "cli.cmd.application.composition": "Catalog consumption + cross-app Link hrefs",
-    "cli.cmd.application.dev": "Sessions / affected / proxy / mounted tests",
-    "cli.cmd.artifact": "Release pack / publish / rollback / diff",
-    "cli.cmd.artifact.pack": "Write dist/_vmz manifests + envelope",
-    "cli.cmd.artifact.publish": "Pack + publish under dist/releases",
-    "cli.cmd.artifact.rollback": "Restore PREVIOUS pointer",
-    "cli.cmd.artifact.current": "Print CURRENT digest",
-    "cli.cmd.artifact.diff": "Structured file digest diff",
-    "cli.cmd.refactor": "DX rename plans / apply",
-    "cli.cmd.refactor.rename": "Plan or apply a workspace rename",
-    "cli.cmd.explain": "DX causal explain",
-    "cli.cmd.github-actions": "Monitor GitHub Actions via Rust GitHub REST monitor (status|wait)",
-    "cli.cmd.plan": "Dump frozen Rust plans via N-API",
-    "cli.cmd.plan.locale": "LocalePlan from locales/",
-    "cli.cmd.plan.document-route": "DocumentRoutePlan from documents/",
-    "cli.cmd.version": "Show host + native protocol versions",
-    "cli.opt.out-dir": "Workspace output root (default: dist)",
-    "cli.opt.release": "Release build (omit serve-host; pack minify; proof)",
-    "cli.opt.profile": "Delivery profile id",
-    "cli.opt.target": "browser | mini-program-wechat (or test affected alias)",
-    "cli.opt.origin": "Site origin for web-static",
-    "cli.opt.host": "Listen host",
-    "cli.opt.port": "Listen port",
-    "cli.opt.poll-ms": "Dev watch poll interval",
-    "cli.opt.build": "Build before serve",
-    "cli.opt.check": "Format check-only / extract fail on CJK",
-    "cli.opt.deny-warnings": "Treat warnings as errors",
-    "cli.opt.level": "Diagnostic verbosity: error | warn | info (default warn)",
-    "cli.opt.info-level": "Show advice diagnostics and progress (same as --level info)",
-    "cli.opt.diag-style": "Diagnostic layout: pretty | compact (default pretty)",
-    "cli.opt.json": "Write JSON to stdout or file",
-    "cli.opt.root": "Project root",
-    "cli.opt.out": "Output directory",
-    "cli.opt.strict": "Strict coverage / require defaultLocale",
-    "cli.opt.list": "List discovered tests",
-    "cli.opt.mode": "compile|logic|browser|ssr|resume|deployment|all",
-    "cli.opt.filter": "Filter by test id or file",
-    "cli.opt.application": "Run only tests for ApplicationId",
-    "cli.opt.mounted": "Relocation + host-boundary tests for ApplicationId",
-    "cli.opt.affected": "Select tests from dirty VPG units",
-    "cli.opt.locale": "Requested locale id",
-    "cli.opt.delivery": "Delivery id",
-    "cli.opt.timezone": "Formatter time zone",
-    "cli.opt.production": "Fail pseudo in production",
-    "cli.opt.base": "ApplicationBase path",
-    "cli.opt.dirty": "Dirty file path for affected planning (repeatable)",
-    "cli.opt.releases": "Releases root directory",
-    "cli.opt.app-id": "applicationId for envelope",
-    "cli.opt.refactor.kind": "route_id|field|method|component|capability",
-    "cli.opt.refactor.from": "Rename from id",
-    "cli.opt.refactor.to": "Rename to id",
-    "cli.opt.refactor.scope": "Optional chunk scope",
-    "cli.opt.apply": "Apply workspace edit plan",
-    "cli.opt.explain": "Include rename explain chain",
-    "cli.opt.explain.target": "Generic Workspace.explain target",
-    "cli.opt.gha.mode": "status (one-shot) or wait (poll until completed)",
-    "cli.opt.gha.workflow": "Workflow file name (e.g. ci.yml) or numeric id",
-    "cli.opt.gha.run-id": "Watch a specific workflow run id",
-    "cli.opt.gha.ref": "Commit SHA filter (head_sha)",
-    "cli.opt.gha.branch": "Branch name filter",
-    "cli.opt.gha.owner": "Repository owner (default GITHUB_REPOSITORY)",
-    "cli.opt.gha.repo": "Repository name (default GITHUB_REPOSITORY)",
-    "cli.opt.gha.token": "GitHub token (default GITHUB_TOKEN / GH_TOKEN)",
-    "cli.opt.gha.timeout-minutes": "Max wait minutes for mode=wait",
-    "cli.opt.gha.interval-seconds": "Poll interval seconds for mode=wait",
-    "cli.opt.gha.required-conclusion": "Required conclusion when mode=wait (default success)",
-    "cli.err.unknown_plan_kind": "unknown plan kind `{kind}` (locale | document-route)",
-    "cli.err.gha.mode": "unknown --mode {mode} (status | wait)",
-    "cli.err.gha.repo": "set --owner/--repo or GITHUB_REPOSITORY (owner/repo)",
-    "cli.err.invalid_level": "unknown --level `{level}` (error | warn | info)",
-    "cli.err.invalid_style": "unknown --style `{style}` (pretty | compact)",
-    "cli.err.unknown_target": "unknown --target {target} (browser | mini-program-wechat)",
-    "cli.err.document_build_aborted": "document build aborted due to diagnostics",
-    "cli.err.locale_rename_usage": "usage: vmz locale rename <from-message-id> <to-message-id>",
-    "cli.err.locale_explain_usage": "usage: vmz locale explain <message-id> [project]",
-    "cli.err.locale_diff_usage": "usage: vmz locale diff <base-locale> <target-locale> [project]",
-    "cli.err.locale_pseudo_usage": "usage: vmz locale pseudo <source-locale> [project]",
-    "cli.err.application_relocate_manifest": "relocate requires a relocation manifest JSON path",
-    "cli.err.application_relocate_base": "relocate requires --base <ApplicationBase>",
-    "cli.err.artifact_diff_usage": "artifact diff requires <aDigest> <bDigest>",
-    "cli.err.refactor_rename_usage": "rename requires --kind, --from, and --to",
-    "cli.err.explain_style_usage": "usage: vmz explain style <node> [path]",
-    "cli.err.explain_usage": "usage: vmz explain style <node> [path] | vmz explain <target> [path]",
-    "cli.err.project_bin_missing": "found project `vmz` / `@vmz/vmz` but bin/vmz.js is missing.",
-    "cli.err.global_needs_project": "this `vmz` is a global install (mode=global); project commands need a project install.",
-    "cli.err.global_install_hint": "Install in the app:  pnpm add -D @vmz/vmz",
-    "cli.err.global_run_hint": "Then run:            pnpm exec vmz <command>",
-    "cli.err.global_developer_hint": "(developer mode: run from vmz-framework packages/runtimes/vmz source — full CLI)"
-}
+{
+    "cli.intro.project": "vmz — Node toolchain host (`@vmz/vmz`, N-API)",
+    "cli.intro.global": "vmz — global install (help/version only). Pin `@vmz/vmz` in the app (`pnpm add -D @vmz/vmz`) and run `pnpm exec vmz <command>`. A global `vmz` re-execs the nearest project bin when present.",
+    "cli.cmd.check": "Check project via Workspace",
+    "cli.cmd.build": "Build project via Workspace",
+    "cli.cmd.serve": "Serve dist (optional --build)",
+    "cli.cmd.dev": "Rebuild session",
+    "cli.cmd.format": "Format workspace surfaces and .vmz via vmz.config format",
+    "cli.opt.format-no-javascript": "Skip JS/TS workspace format",
+    "cli.opt.format-no-rust": "Skip cargo fmt",
+    "cli.opt.format-no-vmz": "Skip .vmz author format",
+    "cli.cmd.lint": "Lint (= check) via N-API",
+    "cli.cmd.test": "Native test discover / report",
+    "cli.cmd.document": "Project /documents domain",
+    "cli.cmd.document.check": "Check locale tree + links/anchors + evidence",
+    "cli.cmd.document.build": "Static HTML + view + evidence + designs CSS",
+    "cli.cmd.locale": "Locale domain",
+    "cli.cmd.locale.check": "Check locales.json5 + catalogs + param contracts",
+    "cli.cmd.locale.list": "List LocaleIds",
+    "cli.cmd.locale.emit-types": "Emit #locales/* .d.ts stubs",
+    "cli.cmd.locale.rename": "MessageId rename plan",
+    "cli.cmd.locale.runtime-check": "LocaleContext / FormatterContext / SSR parity",
+    "cli.cmd.locale.router-check": "Route realization / canonical / hreflang",
+    "cli.cmd.locale.delivery-check": "Multi-host LocaleDeliveryResolution",
+    "cli.cmd.locale.explain": "Explain MessageId",
+    "cli.cmd.locale.diff": "Diff two locales",
+    "cli.cmd.locale.extract": "Hardcoded text sink check",
+    "cli.cmd.locale.pseudo": "Pseudo-localize catalog",
+    "cli.cmd.locale.conformance": "Cross-host MessageId/hash conformance",
+    "cli.cmd.application": "Application Collection / Mount",
+    "cli.cmd.application.check": "Validate descriptors + applications.config.json5",
+    "cli.cmd.application.list": "List ApplicationIds / collections / mounts",
+    "cli.cmd.application.schemas": "Print frozen protocol catalog JSON",
+    "cli.cmd.application.relocatable": "ApplicationBase / non_relocatable_url proof",
+    "cli.cmd.application.relocate": "Apply ApplicationBase to relocation manifest",
+    "cli.cmd.application.artifacts": "ApplicationArtifact + MountTable boundary",
+    "cli.cmd.application.isolation": "Isolation namespaces + failure containment",
+    "cli.cmd.application.composition": "Catalog consumption + cross-app Link hrefs",
+    "cli.cmd.application.dev": "Sessions / affected / proxy / mounted tests",
+    "cli.cmd.artifact": "Release pack / publish / rollback / diff",
+    "cli.cmd.artifact.pack": "Write dist/_vmz manifests + envelope",
+    "cli.cmd.artifact.publish": "Pack + publish under dist/releases",
+    "cli.cmd.artifact.rollback": "Restore PREVIOUS pointer",
+    "cli.cmd.artifact.current": "Print CURRENT digest",
+    "cli.cmd.artifact.diff": "Structured file digest diff",
+    "cli.cmd.refactor": "DX rename plans / apply",
+    "cli.cmd.refactor.rename": "Plan or apply a workspace rename",
+    "cli.cmd.explain": "DX causal explain",
+    "cli.cmd.github-actions": "Monitor GitHub Actions via Rust GitHub REST monitor (status|wait)",
+    "cli.cmd.plan": "Dump frozen Rust plans via N-API",
+    "cli.cmd.plan.locale": "LocalePlan from locales/",
+    "cli.cmd.plan.document-route": "DocumentRoutePlan from documents/",
+    "cli.cmd.version": "Show host + native protocol versions",
+    "cli.opt.out-dir": "Workspace output root (default: dist)",
+    "cli.opt.release": "Release build (omit serve-host; pack minify; proof)",
+    "cli.opt.profile": "Delivery profile id",
+    "cli.opt.target": "browser | mini-program-wechat (or test affected alias)",
+    "cli.opt.origin": "Site origin for web-static",
+    "cli.opt.host": "Listen host",
+    "cli.opt.port": "Listen port",
+    "cli.opt.poll-ms": "Dev watch poll interval",
+    "cli.opt.build": "Build before serve",
+    "cli.opt.check": "Format check-only / extract fail on CJK",
+    "cli.opt.deny-warnings": "Treat warnings as errors",
+    "cli.opt.level": "Diagnostic verbosity: error | warn | info (default warn)",
+    "cli.opt.info-level": "Show advice diagnostics and progress (same as --level info)",
+    "cli.opt.diag-style": "Diagnostic layout: pretty | compact (default pretty)",
+    "cli.opt.json": "Write JSON to stdout or file",
+    "cli.opt.root": "Project root",
+    "cli.opt.out": "Output directory",
+    "cli.opt.strict": "Strict coverage / require defaultLocale",
+    "cli.opt.list": "List discovered tests",
+    "cli.opt.mode": "compile|logic|browser|ssr|resume|deployment|all",
+    "cli.opt.filter": "Filter by test id or file",
+    "cli.opt.application": "Run only tests for ApplicationId",
+    "cli.opt.mounted": "Relocation + host-boundary tests for ApplicationId",
+    "cli.opt.affected": "Select tests from dirty VPG units",
+    "cli.opt.locale": "Requested locale id",
+    "cli.opt.delivery": "Delivery id",
+    "cli.opt.timezone": "Formatter time zone",
+    "cli.opt.production": "Fail pseudo in production",
+    "cli.opt.base": "ApplicationBase path",
+    "cli.opt.dirty": "Dirty file path for affected planning (repeatable)",
+    "cli.opt.releases": "Releases root directory",
+    "cli.opt.app-id": "applicationId for envelope",
+    "cli.opt.refactor.kind": "route_id|field|method|component|capability",
+    "cli.opt.refactor.from": "Rename from id",
+    "cli.opt.refactor.to": "Rename to id",
+    "cli.opt.refactor.scope": "Optional chunk scope",
+    "cli.opt.apply": "Apply workspace edit plan",
+    "cli.opt.explain": "Include rename explain chain",
+    "cli.opt.explain.target": "Generic Workspace.explain target",
+    "cli.opt.gha.mode": "status (one-shot) or wait (poll until completed)",
+    "cli.opt.gha.workflow": "Workflow file name (e.g. ci.yml) or numeric id",
+    "cli.opt.gha.run-id": "Watch a specific workflow run id",
+    "cli.opt.gha.ref": "Commit SHA filter (head_sha)",
+    "cli.opt.gha.branch": "Branch name filter",
+    "cli.opt.gha.owner": "Repository owner (default GITHUB_REPOSITORY)",
+    "cli.opt.gha.repo": "Repository name (default GITHUB_REPOSITORY)",
+    "cli.opt.gha.token": "GitHub token (default GITHUB_TOKEN / GH_TOKEN)",
+    "cli.opt.gha.timeout-minutes": "Max wait minutes for mode=wait",
+    "cli.opt.gha.interval-seconds": "Poll interval seconds for mode=wait",
+    "cli.opt.gha.required-conclusion": "Required conclusion when mode=wait (default success)",
+    "cli.err.unknown_plan_kind": "unknown plan kind `{kind}` (locale | document-route)",
+    "cli.err.gha.mode": "unknown --mode {mode} (status | wait)",
+    "cli.err.gha.repo": "set --owner/--repo or GITHUB_REPOSITORY (owner/repo)",
+    "cli.err.invalid_level": "unknown --level `{level}` (error | warn | info)",
+    "cli.err.invalid_style": "unknown --style `{style}` (pretty | compact)",
+    "cli.err.unknown_target": "unknown --target {target} (browser | mini-program-wechat)",
+    "cli.err.document_build_aborted": "document build aborted due to diagnostics",
+    "cli.err.locale_rename_usage": "usage: vmz locale rename <from-message-id> <to-message-id>",
+    "cli.err.locale_explain_usage": "usage: vmz locale explain <message-id> [project]",
+    "cli.err.locale_diff_usage": "usage: vmz locale diff <base-locale> <target-locale> [project]",
+    "cli.err.locale_pseudo_usage": "usage: vmz locale pseudo <source-locale> [project]",
+    "cli.err.application_relocate_manifest": "relocate requires a relocation manifest JSON path",
+    "cli.err.application_relocate_base": "relocate requires --base <ApplicationBase>",
+    "cli.err.artifact_diff_usage": "artifact diff requires <aDigest> <bDigest>",
+    "cli.err.refactor_rename_usage": "rename requires --kind, --from, and --to",
+    "cli.err.explain_style_usage": "usage: vmz explain style <node> [path]",
+    "cli.err.explain_usage": "usage: vmz explain style <node> [path] | vmz explain <target> [path]",
+    "cli.err.project_bin_missing": "found project `vmz` / `@vmz/vmz` but bin/vmz.js is missing.",
+    "cli.err.global_needs_project": "this `vmz` is a global install (mode=global); project commands need a project install.",
+    "cli.err.global_install_hint": "Install in the app:  pnpm add -D @vmz/vmz",
+    "cli.err.global_run_hint": "Then run:            pnpm exec vmz <command>",
+    "cli.err.global_developer_hint": "(developer mode: run from vmz-framework packages/runtimes/vmz source — full CLI)"
+}

package/locales/en-US/diag.json

@@ -2,6 +2,10 @@
     "diag.message": "{message}",
     "diag.detail": "{detail}",
     "commander::action_failed": "Command failed: {message}",
+    "commander::unknown_command": "Unknown command `{cmd}`.",
+    "commander::unknown_option": "Unknown option `{option}`.",
+    "commander::missing_option_value": "Missing value for option `{option}`.",
+    "commander::parse_failed": "Parse failed: {detail}",
 
     "vmz::template::illegal_directive": "Illegal or unsupported directive in `<template>`: {detail}",
     "vmz::template::parse_failed": "Failed to parse `<template>`: {detail}",
@@ -150,5 +154,7 @@
     "vmz::target::mini_platform_private_schema": "{detail}",
     "vmz::target::mini_shared_fork": "{detail}",
     "vmz::target::mini_static_slice_catalog_only": "{detail}",
-    "vmz::target::mini_route_server_style_catalog_only": "{detail}"
+    "vmz::target::mini_route_server_style_catalog_only": "{detail}",
+    "vmz::config::load_failed": "failed to load project config: {detail}",
+    "vmz::plugin::invalid_entry": "invalid plugin entry: {detail}"
 }