@vmz/vmz 0.3.6 → 0.3.8

package/README.md

@@ -1,55 +1,58 @@
-# `@vmz/vmz` (bin: `vmz`)
-
-CLI / N-API toolchain host. Runtime mental entry is **`@vmz/core`**; optional official UI is **`@vmz/ui`**; plugins are
-**`@vmz/plugin-*`**. Shelved umbrella name: `@vmz/vmz`.
-
-When a project reaches the point where it has a browser surface, SSR, server work, documents, tests, and several
-deployment concerns, the usual workflow becomes a chain of tools that each see a different version of the application. A
-build may pass while a route boundary is wrong; a browser test may pass while SSR work is replayed; a plugin may
-transform code without anyone being able to explain the delivery result.
-
-`vmz` is the command-line home for a different workflow. Development, checking, building, serving, testing, document
-generation, and deployment output all begin from VMZ's understanding of the same application. The useful unit is not
-only a module graph. It is a program with state reads and writes, control regions, routes, server capabilities,
-ownership, and delivery boundaries.
-
-That means the CLI can grow into something more useful than a collection of commands: it can say why a change affects a
-region, why code was placed on the client, why a conservative boundary was used, or why a route and its server work
-belong together. ⚡
-
-With VMZ, a normal workflow is expected to answer all of these from the same source program:
-
-- **Develop:** which application regions are affected by a change?
-- **Check:** which state, route, server, or lifecycle boundary is unsafe?
-- **Build:** what belongs in browser, SSR, resume, and server output?
-- **Test:** what did a user interaction actually cause?
-- **Explain:** why did the compiler make that decision?
-
-Use it when you are adopting VMZ as the application model. The CLI targets VMZ-native source and semantics; Vue, React,
-and legacy VDOM ecosystems keep their own toolchains.
-
-## One tool, several views of the same program
-
-| Workflow    | The question it should answer                                      |
-|-------------|--------------------------------------------------------------------|
-| Development | What changed, and which application regions are affected?          |
-| Checking    | Which state, route, server, or lifetime boundary cannot be proven? |
-| Building    | What belongs in browser, SSR, resume, and server output?           |
-| Testing     | Did the application behave correctly and avoid unrelated work?     |
-| Documents   | Are project documents connected, localized, and deployable?        |
-
-### Designed for the npm world
-
-VMZ does not ask users to abandon JavaScript packaging. Node remains the npm, plugin, development-server, and
-orchestration host. A long-lived N-API bridge connects that ecosystem to Rust and oxc without reducing semantic analysis
-to a sequence of tiny file transforms.
-
-### More than pass or fail
-
-The interesting future of the CLI is explanation. A useful compiler should expose the source span, graph edge, owner,
-deployment boundary, and fallback reason behind a decision. That is a better developer experience than adding more
-colored output to an opaque build. 🧭
-
-## License
-
-MIT
+# `@vmz/vmz` (bin: `vmz`)
+
+Requires Node `>=24.12.0`. Project `vmz.config.ts|mts` loads through native ESM (erasable TypeScript only, no runtime
+transpiler).
+
+CLI / N-API toolchain host. Runtime mental entry is **`@vmz/core`**; optional official UI is **`@vmz/ui`**; plugins are
+**`@vmz/plugin-*`**. Shelved umbrella name: `@vmz/vmz`.
+
+When a project reaches the point where it has a browser surface, SSR, server work, documents, tests, and several
+deployment concerns, the usual workflow becomes a chain of tools that each see a different version of the application. A
+build may pass while a route boundary is wrong; a browser test may pass while SSR work is replayed; a plugin may
+transform code without anyone being able to explain the delivery result.
+
+`vmz` is the command-line home for a different workflow. Development, checking, building, serving, testing, document
+generation, and deployment output all begin from VMZ's understanding of the same application. The useful unit is not
+only a module graph. It is a program with state reads and writes, control regions, routes, server capabilities,
+ownership, and delivery boundaries.
+
+That means the CLI can grow into something more useful than a collection of commands: it can say why a change affects a
+region, why code was placed on the client, why a conservative boundary was used, or why a route and its server work
+belong together. ⚡
+
+With VMZ, a normal workflow is expected to answer all of these from the same source program:
+
+- **Develop:** which application regions are affected by a change?
+- **Check:** which state, route, server, or lifecycle boundary is unsafe?
+- **Build:** what belongs in browser, SSR, resume, and server output?
+- **Test:** what did a user interaction actually cause?
+- **Explain:** why did the compiler make that decision?
+
+Use it when you are adopting VMZ as the application model. The CLI targets VMZ-native source and semantics; Vue, React,
+and legacy VDOM ecosystems keep their own toolchains.
+
+## One tool, several views of the same program
+
+| Workflow    | The question it should answer                                      |
+|-------------|--------------------------------------------------------------------|
+| Development | What changed, and which application regions are affected?          |
+| Checking    | Which state, route, server, or lifetime boundary cannot be proven? |
+| Building    | What belongs in browser, SSR, resume, and server output?           |
+| Testing     | Did the application behave correctly and avoid unrelated work?     |
+| Documents   | Are project documents connected, localized, and deployable?        |
+
+### Designed for the npm world
+
+VMZ does not ask users to abandon JavaScript packaging. Node remains the npm, plugin, development-server, and
+orchestration host. A long-lived N-API bridge connects that ecosystem to Rust and oxc without reducing semantic analysis
+to a sequence of tiny file transforms.
+
+### More than pass or fail
+
+The interesting future of the CLI is explanation. A useful compiler should expose the source span, graph edge, owner,
+deployment boundary, and fallback reason behind a decision. That is a better developer experience than adding more
+colored output to an opaque build. 🧭
+
+## License
+
+MIT

package/bin/vmz.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
-import { runCli } from '../dist/cli/cli.js';
+const [major = 0, minor = 0] = process.versions.node.split('.').map((part) => Number.parseInt(part, 10));
+if (major < 24 || (major === 24 && minor < 12)) {
+    process.stderr.write(
+        `vmz: Node >=24.12.0 is required (found ${process.versions.node}).\n` +
+            '  Why: project `vmz.config.*` and plugin entries load through native ESM type stripping.\n',
+    );
+    process.exit(1);
+}
+const { runCli } = await import('../dist/cli/cli.js');
 const code = await runCli(process.argv.slice(2));
 process.exit(code ?? 0);

package/delivery-runtime-files.json

@@ -1,38 +1,38 @@
-{
-    "schema": "vmz.delivery-runtime-files.v0",
-    "note": "Browser/SSR runtime companions copied into app delivery dist. Consumed by vmz-compiler emit_runtime_js and pack ensureRuntimeCompanions.",
-    "flatBarrels": [
-        { "src": "faces/server.js", "out": "vmz-runtime.js" },
-        { "src": "faces/dom.js", "out": "vmz-dom.js" },
-        { "src": "browser/dom-core.js", "out": "dom-core.js" },
-        { "src": "ssr/dom-ssr.js", "out": "dom-ssr.js" },
-        { "src": "faces/dom.client.js", "out": "dom.client.js" },
-        { "src": "faces/dom.browser.js", "out": "dom.browser.js" },
-        { "src": "browser/direct-host-box.js", "out": "direct-host-box.js" },
-        { "src": "browser/unknown-component.js", "out": "unknown-component.js" },
-        { "src": "shared/dom-attr-normalize.js", "out": "dom-attr-normalize.js" },
-        { "src": "faces/http.js", "out": "vmz-http.js" },
-        { "src": "browser/client-nav.js", "out": "vmz-client-nav.js" }
-    ],
-    "nested": [
-        { "src": "browser/diagnostics/precision-trace.js", "out": "browser/diagnostics/precision-trace.js" },
-        { "src": "browser/dom/attributes.js", "out": "browser/dom/attributes.js" },
-        { "src": "browser/dom/component.js", "out": "browser/dom/component.js" },
-        { "src": "browser/dom/direct-api.js", "out": "browser/dom/direct-api.js" },
-        { "src": "browser/dom/lifecycle.js", "out": "browser/dom/lifecycle.js" },
-        { "src": "browser/dom/registry.js", "out": "browser/dom/registry.js" },
-        { "src": "browser/reactivity/patch-scheduler.js", "out": "browser/reactivity/patch-scheduler.js" },
-        { "src": "browser/reactivity/write-barrier.js", "out": "browser/reactivity/write-barrier.js" },
-        { "src": "browser/navigation/client-navigation.js", "out": "browser/navigation/client-navigation.js" },
-        { "src": "browser/navigation/extract-html.js", "out": "browser/navigation/extract-html.js" },
-        { "src": "browser/navigation/layout-retain.js", "out": "browser/navigation/layout-retain.js" },
-        { "src": "browser/navigation/locale-transition.js", "out": "browser/navigation/locale-transition.js" },
-        { "src": "browser/navigation/scroll-focus.js", "out": "browser/navigation/scroll-focus.js" },
-        { "src": "browser/resume/adopt.js", "out": "browser/resume/adopt.js" },
-        { "src": "browser/resume/hydrate.js", "out": "browser/resume/hydrate.js" },
-        { "src": "browser/resume/resume.js", "out": "browser/resume/resume.js" },
-        { "src": "ssr/render.js", "out": "ssr/render.js" },
-        { "src": "ssr/serialize.js", "out": "ssr/serialize.js" },
-        { "src": "ssr/document.js", "out": "ssr/document.js" }
-    ]
-}
+{
+    "schema": "vmz.delivery-runtime-files.v0",
+    "note": "Browser/SSR runtime companions copied into app delivery dist. Consumed by vmz-compiler emit_runtime_js and pack ensureRuntimeCompanions.",
+    "flatBarrels": [
+        { "src": "faces/server.js", "out": "vmz-runtime.js" },
+        { "src": "faces/dom.js", "out": "vmz-dom.js" },
+        { "src": "browser/dom-core.js", "out": "dom-core.js" },
+        { "src": "ssr/dom-ssr.js", "out": "dom-ssr.js" },
+        { "src": "faces/dom.client.js", "out": "dom.client.js" },
+        { "src": "faces/dom.browser.js", "out": "dom.browser.js" },
+        { "src": "browser/direct-host-box.js", "out": "direct-host-box.js" },
+        { "src": "browser/unknown-component.js", "out": "unknown-component.js" },
+        { "src": "shared/dom-attr-normalize.js", "out": "dom-attr-normalize.js" },
+        { "src": "faces/http.js", "out": "vmz-http.js" },
+        { "src": "browser/client-nav.js", "out": "vmz-client-nav.js" }
+    ],
+    "nested": [
+        { "src": "browser/diagnostics/precision-trace.js", "out": "browser/diagnostics/precision-trace.js" },
+        { "src": "browser/dom/attributes.js", "out": "browser/dom/attributes.js" },
+        { "src": "browser/dom/component.js", "out": "browser/dom/component.js" },
+        { "src": "browser/dom/direct-api.js", "out": "browser/dom/direct-api.js" },
+        { "src": "browser/dom/lifecycle.js", "out": "browser/dom/lifecycle.js" },
+        { "src": "browser/dom/registry.js", "out": "browser/dom/registry.js" },
+        { "src": "browser/reactivity/patch-scheduler.js", "out": "browser/reactivity/patch-scheduler.js" },
+        { "src": "browser/reactivity/write-barrier.js", "out": "browser/reactivity/write-barrier.js" },
+        { "src": "browser/navigation/client-navigation.js", "out": "browser/navigation/client-navigation.js" },
+        { "src": "browser/navigation/extract-html.js", "out": "browser/navigation/extract-html.js" },
+        { "src": "browser/navigation/layout-retain.js", "out": "browser/navigation/layout-retain.js" },
+        { "src": "browser/navigation/locale-transition.js", "out": "browser/navigation/locale-transition.js" },
+        { "src": "browser/navigation/scroll-focus.js", "out": "browser/navigation/scroll-focus.js" },
+        { "src": "browser/resume/adopt.js", "out": "browser/resume/adopt.js" },
+        { "src": "browser/resume/hydrate.js", "out": "browser/resume/hydrate.js" },
+        { "src": "browser/resume/resume.js", "out": "browser/resume/resume.js" },
+        { "src": "ssr/render.js", "out": "ssr/render.js" },
+        { "src": "ssr/serialize.js", "out": "ssr/serialize.js" },
+        { "src": "ssr/document.js", "out": "ssr/document.js" }
+    ]
+}

package/dist/cli/cli.js

@@ -13,7 +13,7 @@ import { registerDocumentCommands } from '../document/document-cmd.js';
 import { buildIntegratedDocuments, projectHasDocuments } from '../document/document-integrate.js';
 import { registerExplainCommand } from './explain-cmd.js';
 import { registerGithubActionsCommand } from './github-actions-cmd.js';
-import { createWorkspace, getProtocolVersions, HOST_PROTOCOL, materializeServeHostRuntime, resolveCoreRuntimeDist, resolveNativePath, } from '../workspace/public-api.js';
+import { createWorkspace, getProtocolVersions, HOST_PROTOCOL, materializeServeHostRuntime, materializeWechatPackaging, resolveCoreRuntimeDist, resolveNativePath, } from '../workspace/public-api.js';
 import { gateGlobalProjectCommand, getInvocationContext, isGlobalAllowedCommand } from '../workspace/invocation.js';
 import { emitLocaleRuntimeModules, localeHasErrors } from '../locale/locale-check.js';
 import { registerLocaleCommands } from '../locale/locale-cmd.js';
@@ -56,32 +56,29 @@ function buildProductCli(opts = {}) {
         cli.command('version', 'cli.cmd.version').action(() => cmdVersion());
         return cli;
     }
-    const withWorkspaceOpts = (cmd) => cmd
+    const withCoreOpts = (cmd) => cmd
         .option('--out-dir, -o <dir>', 'cli.opt.out-dir')
         .option('--release', 'cli.opt.release')
         .option('--profile <name>', 'cli.opt.profile')
         .option('--target <id>', 'cli.opt.target')
         .option('--origin <url>', 'cli.opt.origin')
-        .option('--host <host>', 'cli.opt.host')
-        .option('--port <port>', 'cli.opt.port')
-        .option('--poll-ms <ms>', 'cli.opt.poll-ms')
-        .option('--build', 'cli.opt.build')
         .option('--check', 'cli.opt.check')
         .option('--deny-warnings', 'cli.opt.deny-warnings');
-    withWorkspaceOpts(cli.command('check', 'cli.cmd.check'))
+    const withServeExtras = (cmd) => cmd.option('--host <host>', 'cli.opt.host').option('--port <port>', 'cli.opt.port').option('--poll-ms <ms>', 'cli.opt.poll-ms').option('--build', 'cli.opt.build');
+    withCoreOpts(cli.command('check', 'cli.cmd.check'))
         .option('--level <level>', 'cli.opt.level')
         .option('--info', 'cli.opt.info-level')
         .option('--style <style>', 'cli.opt.diag-style')
         .action((options) => cmdCheck(options));
-    withWorkspaceOpts(cli.command('build', 'cli.cmd.build')).action((options) => cmdBuild(options));
-    withWorkspaceOpts(cli.command('serve', 'cli.cmd.serve')).action((options) => cmdServe(options));
-    withWorkspaceOpts(cli.command('dev', 'cli.cmd.dev')).action((options) => cmdDev(options));
-    withWorkspaceOpts(cli.command('format', 'cli.cmd.format'))
+    withCoreOpts(cli.command('build', 'cli.cmd.build')).action((options) => cmdBuild(options));
+    withServeExtras(withCoreOpts(cli.command('serve', 'cli.cmd.serve'))).action((options) => cmdServe(options));
+    withServeExtras(withCoreOpts(cli.command('dev', 'cli.cmd.dev'))).action((options) => cmdDev(options));
+    withCoreOpts(cli.command('format', 'cli.cmd.format'))
         .option('--no-javascript', 'cli.opt.format-no-javascript')
         .option('--no-rust', 'cli.opt.format-no-rust')
         .option('--no-vmz', 'cli.opt.format-no-vmz')
         .action((options) => cmdFormat(options));
-    withWorkspaceOpts(cli.command('lint', 'cli.cmd.lint'))
+    withCoreOpts(cli.command('lint', 'cli.cmd.lint'))
         .option('--level <level>', 'cli.opt.level')
         .option('--info', 'cli.opt.info-level')
         .option('--style <style>', 'cli.opt.diag-style')
@@ -155,9 +152,10 @@ async function cmdCheck(args) {
     });
     const meta = readPackageMeta(project);
     log.info(`check ${project}${meta?.name ? ` (${meta.name})` : ''}`);
+    const cfg = await loadVmzConfig(project);
     const ws = createWorkspace({ root: project, outDir });
     try {
-        return runWithPlugins(ws, project, outDir, async () => {
+        return runWithPlugins(ws, cfg, project, outDir, async () => {
             const report = ws.check();
             const { checkLocales, localeHasErrors } = await import('../locale/locale-check.js');
             const localeReport = checkLocales({ projectRoot: project, checkUnused: false });
@@ -185,9 +183,9 @@ function dedupeDiagnostics(list) {
     }
     return out;
 }
-async function runWithPlugins(ws, project, outDir, fn) {
-    const { loadVmzConfig, applyPlugins } = await import('../workspace/plugin-host.js');
-    const { plugins, engines } = await loadVmzConfig(project);
+async function runWithPlugins(ws, cfg, project, outDir, fn) {
+    const { applyPlugins } = await import('../workspace/plugin-host.js');
+    const { plugins, engines } = cfg;
     if (plugins.length) {
         await applyPlugins(ws, plugins, { project, outDir, engines });
     }
@@ -221,10 +219,12 @@ async function cmdBuild(args) {
     }
     const outDir = resolveProfileArtifactDir(outDirRoot, selected.profile);
     log.info(`build ${project} → ${outDir}${wechatPack ? ' (target=mini-program-wechat)' : ''} (out-dir=${outDirRoot}, name=${selected.profile.name})`);
+    if (wechatPack)
+        materializeWechatPackaging(project, cfg.delivery);
     const ws = createWorkspace({ root: project, outDir });
     try {
         log.info(`delivery profile ${selected.selection.profileId} (assembly=${selected.selection.assembly}, name=${selected.profile.name})`);
-        const code = await runWithPlugins(ws, project, outDir, () => {
+        const code = await runWithPlugins(ws, cfg, project, outDir, () => {
             const report = ws.build(Boolean(args.release));
             const errors = log.diagnostics(report.diagnostics ?? []);
             if (errors)
@@ -488,6 +488,7 @@ async function cmdDev(args) {
         port,
         pollMs,
         target: targetRaw,
+        delivery: cfg.delivery,
         signal: ac.signal,
     });
     try {
@@ -497,6 +498,9 @@ async function cmdDev(args) {
     catch (err) {
         if (ac.signal.aborted)
             return 0;
+        // Config/plugin failures carry a product diagnostic: let the CLI boundary print once.
+        if (err && typeof err === 'object' && 'diagnostic' in err)
+            throw err;
         log.error(String(err));
         return 1;
     }

package/dist/dev/config-cycle-worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Child process for one dev config build cycle.
+ *
+ * Evaluates `vmz.config.*`, applies plugin contributions into the workspace,
+ * then writes a data-only report (no functions across the process boundary).
+ */
+export {};

package/dist/dev/config-cycle-worker.js

@@ -0,0 +1,83 @@
+/**
+ * Child process for one dev config build cycle.
+ *
+ * Evaluates `vmz.config.*`, applies plugin contributions into the workspace,
+ * then writes a data-only report (no functions across the process boundary).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { applyPlugins, loadVmzConfig } from '../workspace/plugin-host.js';
+import { createWorkspace } from '../workspace/public-api.js';
+function errorDetail(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const cause = err instanceof Error && err.cause ? `: ${errorDetail(err.cause)}` : '';
+    return `${message}${cause}`;
+}
+function writeReport(reportPath, report) {
+    let text;
+    try {
+        text = JSON.stringify(report, (_key, value) => (typeof value === 'function' ? undefined : value));
+    }
+    catch (err) {
+        text = JSON.stringify({
+            ok: false,
+            configPath: null,
+            pluginPath: null,
+            plugins: [],
+            engines: {},
+            delivery: null,
+            error: {
+                code: 'vmz::config::load_failed',
+                severity: 'error',
+                args: { detail: `config report is not serializable: ${errorDetail(err)}` },
+            },
+        });
+    }
+    writeFileSync(reportPath, text);
+}
+const [inputPath, reportPath] = process.argv.slice(2);
+if (!inputPath || !reportPath) {
+    process.stderr.write('config-cycle-worker: <input.json> <report.json> required\n');
+    process.exit(2);
+}
+const input = JSON.parse(readFileSync(inputPath, 'utf8'));
+let ws = null;
+try {
+    const cfg = await loadVmzConfig(input.project);
+    ws = createWorkspace({ root: input.project, outDir: input.outDir });
+    if (cfg.plugins.length) {
+        await applyPlugins(ws, cfg.plugins, { project: input.project, outDir: input.outDir, engines: cfg.engines });
+    }
+    writeReport(reportPath, {
+        ok: true,
+        configPath: cfg.path,
+        pluginPath: cfg.pluginPath,
+        plugins: cfg.plugins.map((p) => ({
+            name: p.manifest.name,
+            version: p.manifest.version,
+            stages: p.manifest.stages ?? [],
+        })),
+        engines: cfg.engines,
+        delivery: cfg.delivery ?? null,
+    });
+}
+catch (err) {
+    const diagnostic = err?.diagnostic ?? {
+        code: 'vmz::config::load_failed',
+        severity: 'error',
+        path: path.join(input.project, 'vmz.config.ts'),
+        args: { detail: errorDetail(err) },
+    };
+    writeReport(reportPath, {
+        ok: false,
+        configPath: null,
+        pluginPath: null,
+        plugins: [],
+        engines: {},
+        delivery: null,
+        error: diagnostic,
+    });
+}
+finally {
+    ws?.dispose();
+}

package/dist/dev/config-cycle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Dev config build cycle.
+ *
+ * Each cycle runs config evaluation + plugin contribution in its own Node process.
+ * Functions and plugin objects stay in that process; the parent receives data only.
+ * Config/IPS changes restart the cycle: the old process is cancelled and awaited
+ * before a new one may write plugin artifacts.
+ */
+export interface ConfigCycleDiagnostic {
+    code: string;
+    severity?: 'error';
+    path?: string;
+    args?: Record<string, string>;
+}
+export interface ConfigCycleReport {
+    ok: boolean;
+    configPath: string | null;
+    pluginPath: string | null;
+    plugins: Array<{
+        name: string;
+        version: string;
+        stages: string[];
+    }>;
+    engines: Record<string, string>;
+    delivery: unknown;
+    error?: ConfigCycleDiagnostic;
+}
+export interface ConfigCycleOptions {
+    project: string;
+    outDir: string;
+    /** Built worker (`dist/dev/config-cycle-worker.js`); defaults next to this module. */
+    workerPath?: string;
+    nodePath?: string;
+    timeoutMs?: number;
+}
+export interface ConfigCycle {
+    start(): Promise<ConfigCycleReport>;
+    restart(): Promise<ConfigCycleReport>;
+    cancel(): Promise<void>;
+    running(): boolean;
+}
+export declare class ConfigCycleCancelledError extends Error {
+    constructor();
+}
+export declare function createConfigCycle(options: ConfigCycleOptions): ConfigCycle;

package/dist/dev/config-cycle.js

@@ -0,0 +1,152 @@
+/**
+ * Dev config build cycle.
+ *
+ * Each cycle runs config evaluation + plugin contribution in its own Node process.
+ * Functions and plugin objects stay in that process; the parent receives data only.
+ * Config/IPS changes restart the cycle: the old process is cancelled and awaited
+ * before a new one may write plugin artifacts.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export class ConfigCycleCancelledError extends Error {
+    constructor() {
+        super('vmz dev: config build process cancelled');
+        this.name = 'ConfigCycleCancelledError';
+    }
+}
+function defaultWorkerPath() {
+    return fileURLToPath(new URL('./config-cycle-worker.js', import.meta.url));
+}
+function emptyReport(project, error) {
+    return {
+        ok: !error,
+        configPath: null,
+        pluginPath: null,
+        plugins: [],
+        engines: {},
+        delivery: null,
+        ...(error ? { error } : {}),
+    };
+}
+function syntheticFailure(project, detail, configPath) {
+    return emptyReport(project, {
+        code: 'vmz::config::load_failed',
+        severity: 'error',
+        path: configPath ?? path.join(project, 'vmz.config.ts'),
+        args: { detail },
+    });
+}
+export function createConfigCycle(options) {
+    const project = path.resolve(options.project);
+    const outDir = path.resolve(options.outDir);
+    const workerPath = options.workerPath ?? defaultWorkerPath();
+    const nodePath = options.nodePath ?? process.env.VMZ_NODE ?? process.execPath;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    let child = null;
+    let exited = null;
+    let cancelled = false;
+    async function cancel() {
+        if (!child)
+            return;
+        cancelled = true;
+        const proc = child;
+        const done = exited;
+        try {
+            proc.kill();
+        }
+        catch {
+            /* already gone */
+        }
+        if (done)
+            await Promise.race([done, new Promise((r) => setTimeout(r, 5000))]);
+        if (proc.exitCode == null && proc.signalCode == null) {
+            try {
+                proc.kill('SIGKILL');
+            }
+            catch {
+                /* already gone */
+            }
+            if (done)
+                await Promise.race([done, new Promise((r) => setTimeout(r, 2000))]);
+        }
+    }
+    async function start() {
+        if (child)
+            throw new Error('vmz dev: config build process already running');
+        if (!existsSync(workerPath)) {
+            throw new Error(`vmz dev: missing config cycle worker ${workerPath} — run build:js`);
+        }
+        cancelled = false;
+        const tmp = mkdtempSync(path.join(os.tmpdir(), 'vmz-config-cycle-'));
+        const inputPath = path.join(tmp, 'input.json');
+        const reportPath = path.join(tmp, 'report.json');
+        writeFileSync(inputPath, JSON.stringify({ project, outDir }));
+        let stderr = '';
+        let timedOut = false;
+        const proc = spawn(nodePath, [workerPath, inputPath, reportPath], {
+            cwd: project,
+            env: { ...process.env, VMZ_PROJECT_ROOT: project, VMZ_DIST: outDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        child = proc;
+        proc.stderr?.on('data', (chunk) => {
+            if (stderr.length < 16_384)
+                stderr += chunk.toString();
+        });
+        exited = new Promise((resolve) => {
+            proc.once('exit', (code, signal) => resolve({ code, signal }));
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                proc.kill();
+            }
+            catch {
+                /* already gone */
+            }
+        }, timeoutMs);
+        const result = await exited;
+        clearTimeout(timer);
+        child = null;
+        exited = null;
+        let report = null;
+        if (!cancelled) {
+            try {
+                report = JSON.parse(readFileSync(reportPath, 'utf8'));
+            }
+            catch {
+                report = null;
+            }
+        }
+        rmSync(tmp, { recursive: true, force: true });
+        if (cancelled)
+            throw new ConfigCycleCancelledError();
+        if (!report) {
+            const detail = timedOut
+                ? `config build process timed out after ${timeoutMs}ms`
+                : `config build process exited with code ${String(result.code)}${result.signal ? ` (${result.signal})` : ''}${stderr.trim() ? `: ${stderr.trim().split('\n').slice(0, 4).join(' | ')}` : ''}`;
+            return syntheticFailure(project, detail);
+        }
+        if (!report.ok && report.error) {
+            if (!report.error.args?.detail && stderr.trim()) {
+                report.error.args = { ...(report.error.args ?? {}), detail: stderr.trim().split('\n').slice(0, 4).join(' | ') };
+            }
+            return report;
+        }
+        return report;
+    }
+    async function restart() {
+        await cancel();
+        return start();
+    }
+    return {
+        start,
+        restart,
+        cancel,
+        running: () => child != null,
+    };
+}

package/dist/dev/dev-session.d.ts

@@ -10,6 +10,7 @@
  * 3. Soft reload failure → **auto-respawn** serve-host (fresh ESM graph), not "keep broken host".
  */
 import { createWorkspace } from '../workspace/public-api.js';
+import { type ConfigCycle } from './config-cycle.js';
 interface DevSessionOptions {
     project: string;
     outDir: string;
@@ -17,6 +18,8 @@ interface DevSessionOptions {
     port?: number;
     pollMs?: number;
     target?: 'browser' | 'mini-program-wechat';
+    /** Delivery snapshot evaluated by the config host; the package contract is prepared from it. */
+    delivery?: unknown;
     signal?: AbortSignal;
     createWorkspaceFn?: typeof createWorkspace;
     spawnHostFn?: (opts: {
@@ -26,6 +29,14 @@ interface DevSessionOptions {
         port: number;
     }) => import('node:child_process').ChildProcess;
     softReloadFn?: (host: string, port: number, payload?: object) => Promise<void>;
+    /** Override the detached config build process (tests). */
+    configCycleFn?: (opts: {
+        project: string;
+        outDir: string;
+        workerPath?: string;
+    }) => ConfigCycle;
+    /** Built config cycle worker path (defaults to `dist/dev/config-cycle-worker.js`). */
+    configCycleWorkerPath?: string;
 }
 export declare function createDevSession(options: DevSessionOptions): {
     ws: any;