@esmx/core 3.0.0-rc.117 → 3.0.0-rc.118

package/README.md

@@ -29,10 +29,10 @@
 
 ## 🚀 Features
 
-- **Native Microfrontend** - Based on ESM + ImportMap for native module loading with zero runtime overhead
+- **Native Microfrontend** - Based on ESM + Import Map for native module loading with zero runtime overhead
 - **Dependency Management** - Centralized dependency management with content-hash-based strong caching strategy
 - **Application Isolation** - ESM native module isolation ensuring runtime stability
-- **SSR Support** - Flexible server-side rendering strategy supporting any frontend framework
+- **SSR Support** - Flexible SSR strategy supporting any frontend framework
 - **Developer Experience** - Complete TypeScript support with native Module Linking capabilities
 
 ## 📦 Installation
@@ -50,7 +50,21 @@ yarn add @esmx/core
 
 ## 🚀 Quick Start
 
-See Quick Start guide: https://esmx.dev/guide/start/getting-started.html
+Define your app in `entry.node.ts`, choosing a build-tool integration in `devApp`:
+
+```typescript
+import type { EsmxOptions } from '@esmx/core';
+
+export default {
+  async devApp(esmx) {
+    return import('@esmx/rspack').then((m) => m.createRspackHtmlApp(esmx));
+  }
+} satisfies EsmxOptions;
+```
+
+Then drive it with the `esmx` CLI: `esmx dev`, `esmx build`, `esmx start`.
+
+📖 [Documentation](https://esmx.dev/guide/start/getting-started.html)
 
 ## 📚 Documentation
 

package/README.zh-CN.md

@@ -20,7 +20,7 @@
     </a>
   </div>
   
-  <p>支持 Vue、React、Preact、Solid、Svelte 的高性能微前端框架，具备 SSR 和模块链接能力</p>
+  <p>支持 Vue、React、Preact、Solid、Svelte 的高性能微前端框架，支持 SSR 与模块链接</p>
   
   <p>
     <a href="https://github.com/esmnext/esmx/blob/master/packages/core/README.md">English</a> | 中文
@@ -29,10 +29,10 @@
 
 ## 🚀 特性
 
-- **原生微前端** - 基于 ESM + ImportMap 的原生模块加载，零运行时开销
-- **依赖管理** - 中心化的依赖管理，基于内容哈希的强缓存策略
-- **应用隔离** - ESM 原生模块隔离，保障应用运行时的稳定性
-- **SSR 支持** - 灵活的服务端渲染策略，支持任意前端框架
+- **原生微前端** - 基于 ESM + Import Map 的原生模块加载，零运行时开销
+- **依赖管理** - 中心化依赖管理，基于内容哈希的强缓存策略
+- **应用隔离** - ESM 原生模块隔离，保障应用运行时稳定性
+- **SSR 支持** - 灵活的 SSR 策略，支持任意前端框架
 - **开发体验** - 完整的 TypeScript 支持，原生模块链接能力
 
 ## 📦 安装
@@ -50,7 +50,21 @@ yarn add @esmx/core
 
 ## 🚀 快速开始
 
-查看快速开始指南：https://esmx.dev/zh-CN/guide/start/getting-started.html
+在 `entry.node.ts` 中定义应用，并在 `devApp` 选择构建工具集成：
+
+```typescript
+import type { EsmxOptions } from '@esmx/core';
+
+export default {
+  async devApp(esmx) {
+    return import('@esmx/rspack').then((m) => m.createRspackHtmlApp(esmx));
+  }
+} satisfies EsmxOptions;
+```
+
+然后用 `esmx` CLI 驱动：`esmx dev`、`esmx build`、`esmx start`。
+
+📖 [完整文档](https://esmx.dev/zh/guide/start/getting-started.html)
 
 ## 📚 文档
 

package/dist/app.mjs

@@ -1,5 +1,6 @@
 import { pathToFileURL } from "node:url";
 import { createLoaderImport } from "@esmx/import";
+import { DEFAULT_MODULE_ENTRY } from "./module-config.mjs";
 import {
   RenderContext
 } from "./render-context.mjs";
@@ -15,9 +16,10 @@ async function createStartRender(esmx) {
   const baseURL = pathToFileURL(esmx.resolvePath("dist/server"));
   const importMap = await esmx.getImportMap("server");
   const loaderImport = createLoaderImport(baseURL, importMap);
+  const serverEntry = esmx.moduleConfig.entry.server ?? DEFAULT_MODULE_ENTRY.server;
   return async (options) => {
     const rc = new RenderContext(esmx, options);
-    const result = await loaderImport(`${esmx.name}/src/entry.server`);
+    const result = await loaderImport(`${esmx.name}/${serverEntry.name}`);
     const serverRender = result[rc.entryName];
     if (typeof serverRender === "function") {
       await serverRender(rc);
@@ -28,7 +30,7 @@ async function createStartRender(esmx) {
 function createErrorRender(esmx) {
   return (options) => {
     throw new Error(
-      `App instance is only available in production and can only execute built artifacts.`
+      `[@esmx/core] esmx.render() is only available in production. The current process is in dev mode and has no built artifacts. Run \`esmx build\` first, then start the server with NODE_ENV=production node dist/index.mjs.`
     );
   };
 }

package/dist/cli/cli.d.ts

@@ -1,2 +1,3 @@
 export declare function cli(command: string): Promise<void>;
 export declare function resolve(specifier: string, context: Record<string, any>, nextResolve: Function): any;
+export declare function load(url: string, context: Record<string, any>, nextLoad: Function): Promise<any>;

package/dist/cli/cli.mjs

@@ -3,6 +3,7 @@ import { styleText } from "node:util";
 import pkg from "../../package.json" with { type: "json" };
 import { COMMAND, Esmx } from "../core.mjs";
 import { resolveImportPath } from "../utils/resolve-path.mjs";
+import { runValidate, VALIDATE_HELP } from "./validate.mjs";
 async function getSrcOptions() {
   return import(resolveImportPath(process.cwd(), "./src/entry.node.ts")).then(
     (m) => m.default
@@ -24,6 +25,21 @@ async function getDistOptions() {
   }
 }
 export async function cli(command) {
+  if (command === "validate") {
+    const flags = process.argv.slice(3);
+    if (flags.includes("--help")) {
+      console.log(VALIDATE_HELP);
+      return;
+    }
+    const result = await runValidate(process.cwd(), {
+      json: flags.includes("--json")
+    });
+    console.log(result.output);
+    if (result.exitCode !== 0) {
+      process.exit(result.exitCode);
+    }
+    return;
+  }
   console.log(`\u{1F525} ${styleText("yellow", "Esmx")} v${pkg.version}
     `);
   if (command !== COMMAND.dev && typeof process.env.NODE_ENV === "undefined") {
@@ -87,8 +103,19 @@ module.register(import.meta.url, {
   parentURL: import.meta.url
 });
 export function resolve(specifier, context, nextResolve) {
-  if (context?.parentURL.endsWith(".ts") && specifier.startsWith(".") && !specifier.endsWith(".ts")) {
+  if (context?.parentURL?.endsWith(".ts") && specifier.startsWith(".") && !specifier.endsWith(".ts")) {
     return nextResolve(specifier + ".ts", context);
   }
   return nextResolve(specifier, context);
 }
+const STYLE_ASSET_RE = /\.(?:css|scss|sass|less|stylus|styl|pcss|postcss)(?:\?.*)?$/i;
+export async function load(url, context, nextLoad) {
+  if (STYLE_ASSET_RE.test(url)) {
+    return {
+      format: "module",
+      shortCircuit: true,
+      source: `export default ${JSON.stringify(url)}; export const href = ${JSON.stringify(url)};`
+    };
+  }
+  return nextLoad(url, context);
+}

package/dist/cli/validate.d.ts

@@ -0,0 +1,15 @@
+export declare const VALIDATE_HELP = "Usage: esmx validate [--json]\n\nBuild-free dry run of the RFC 0001 module protocol: reads the package.json\n\"esmx\" declaration in the current directory and runs the resolution layer\n(phases 1-2: consumption graph + supply merge) without building anything.\n\nExit code is non-zero only when an error-severity diagnostic is found;\nwarnings alone exit 0. A package without an \"esmx\" field uses the legacy\nentry.node.ts config and is not an error.\n\nOptions:\n  --json    Emit a machine-readable envelope on stdout and nothing else:\n            {\n              \"diagnostics\": [ { \"code\", \"check\"?, \"module\", \"package\"?,\n                                 \"found\"?, \"required\"?, \"message\", \"fix\" } ],\n              \"supply\":      { \"<package>\": { \"groups\": [ { \"major\",\n                                              \"provider\", \"version\" } ] } },\n              \"mounts\":      { \"<module>\":  { \"name\", \"root\",\n                                              \"artifactDir\", \"built\" } }\n            }\n            Two providers of one (package, major) is an E_DUP_PROVIDER error\n            (a shared dependency must have a single owner).\n            Legacy packages emit { \"protocol\": \"legacy\", \"diagnostics\": [] }.\n  --help    Show this message.";
+export interface RunValidateOptions {
+    json?: boolean;
+}
+export interface RunValidateResult {
+    exitCode: number;
+    /** Full stdout payload (JSON envelope or human report). */
+    output: string;
+}
+/**
+ * `esmx validate` core (RFC 0001 §10 Phase 5, the agent verification loop).
+ * Pure with respect to process state: never writes to stdout/stderr and
+ * never exits — the CLI case owns printing and the exit code.
+ */
+export declare function runValidate(rootDir: string, options?: RunValidateOptions): Promise<RunValidateResult>;

package/dist/cli/validate.mjs

@@ -0,0 +1,139 @@
+import { styleText } from "node:util";
+import { resolveDeclaration } from "../declaration/index.mjs";
+export const VALIDATE_HELP = `Usage: esmx validate [--json]
+
+Build-free dry run of the RFC 0001 module protocol: reads the package.json
+"esmx" declaration in the current directory and runs the resolution layer
+(phases 1-2: consumption graph + supply merge) without building anything.
+
+Exit code is non-zero only when an error-severity diagnostic is found;
+warnings alone exit 0. A package without an "esmx" field uses the legacy
+entry.node.ts config and is not an error.
+
+Options:
+  --json    Emit a machine-readable envelope on stdout and nothing else:
+            {
+              "diagnostics": [ { "code", "check"?, "module", "package"?,
+                                 "found"?, "required"?, "message", "fix" } ],
+              "supply":      { "<package>": { "groups": [ { "major",
+                                              "provider", "version" } ] } },
+              "mounts":      { "<module>":  { "name", "root",
+                                              "artifactDir", "built" } }
+            }
+            Two providers of one (package, major) is an E_DUP_PROVIDER error
+            (a shared dependency must have a single owner).
+            Legacy packages emit { "protocol": "legacy", "diagnostics": [] }.
+  --help    Show this message.`;
+function toEnvelopeEntry(diagnostic) {
+  const entry = {
+    code: diagnostic.code,
+    module: diagnostic.module,
+    message: diagnostic.message,
+    fix: diagnostic.fix
+  };
+  if (diagnostic.check !== void 0) {
+    entry.check = diagnostic.check;
+  }
+  if (diagnostic.package !== void 0) {
+    entry.package = diagnostic.package;
+  }
+  if (diagnostic.found !== void 0) {
+    entry.found = diagnostic.found;
+  }
+  if (diagnostic.required !== void 0) {
+    entry.required = diagnostic.required;
+  }
+  return entry;
+}
+function formatHumanDiagnostic(diagnostic) {
+  const color = diagnostic.severity === "error" ? "red" : "yellow";
+  const location = diagnostic.package ? `${diagnostic.module} \u2192 ${diagnostic.package}` : diagnostic.module;
+  const lines = [styleText(color, `[${diagnostic.code}]`) + ` ${location}`];
+  if (diagnostic.check) {
+    lines.push(`    check: ${diagnostic.check}`);
+  }
+  if (diagnostic.found !== void 0 || diagnostic.required !== void 0) {
+    lines.push(
+      `    found: ${diagnostic.found ?? "\u2014"} / required: ${diagnostic.required ?? "\u2014"}`
+    );
+  }
+  lines.push(`    ${diagnostic.message}`);
+  lines.push(`    fix: ${diagnostic.fix}`);
+  return lines.join("\n");
+}
+function formatHumanReport(diagnostics, supply, mounts) {
+  const sections = [];
+  const errorCount = diagnostics.filter((d) => d.severity === "error").length;
+  const warningCount = diagnostics.length - errorCount;
+  if (diagnostics.length === 0) {
+    sections.push(styleText("green", "\u2713 Declaration is valid."));
+  } else {
+    sections.push(diagnostics.map(formatHumanDiagnostic).join("\n"));
+    sections.push(`${errorCount} error(s), ${warningCount} warning(s).`);
+  }
+  const supplyEntries = Object.entries(supply);
+  sections.push(
+    supplyEntries.length === 0 ? "Supply: (empty)" : [
+      "Supply:",
+      ...supplyEntries.flatMap(
+        ([pkg, entry]) => entry.groups.map(
+          (group) => `  ${pkg} \u2192 ${group.provider}@${group.version ?? "unresolved"}${entry.groups.length > 1 ? ` (major ${group.major})` : ""}`
+        )
+      )
+    ].join("\n")
+  );
+  const mountEntries = Object.entries(mounts);
+  sections.push(
+    mountEntries.length === 0 ? "Mounts: (empty)" : [
+      "Mounts:",
+      ...mountEntries.map(
+        ([name, mount]) => `  ${name} \u2192 ${mount.artifactDir} (${mount.built ? "built" : "not built"})`
+      )
+    ].join("\n")
+  );
+  return sections.join("\n\n");
+}
+export async function runValidate(rootDir, options = {}) {
+  const resolved = resolveDeclaration(rootDir);
+  if (!resolved) {
+    if (options.json) {
+      return {
+        exitCode: 0,
+        output: JSON.stringify(
+          { protocol: "legacy", diagnostics: [] },
+          null,
+          4
+        )
+      };
+    }
+    return {
+      exitCode: 0,
+      output: [
+        'No "esmx" field in package.json \u2014 this module uses the legacy entry.node.ts config.',
+        'That is fine: the new module protocol is opt-in. To adopt it, add an "esmx" field to package.json (see the module protocol docs).'
+      ].join("\n")
+    };
+  }
+  const { diagnostics, supply } = resolved;
+  const mounts = resolved.mounts;
+  const hasError = diagnostics.some((d) => d.severity === "error");
+  const exitCode = hasError ? 1 : 0;
+  if (options.json) {
+    return {
+      exitCode,
+      output: JSON.stringify(
+        {
+          diagnostics: diagnostics.map(toEnvelopeEntry),
+          supply,
+          mounts
+        },
+        null,
+        4
+      )
+    };
+  }
+  return {
+    exitCode,
+    output: formatHumanReport(diagnostics, supply, mounts)
+  };
+}

package/dist/cli/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/validate.test.mjs

@@ -0,0 +1,216 @@
+import fs from "node:fs";
+import path from "node:path";
+import url from "node:url";
+import util from "node:util";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createFixtureRoot,
+  removeFixtureRoot,
+  writeFixturePackage
+} from "../declaration/test-fixtures.mjs";
+import { runValidate } from "./validate.mjs";
+const fixtureRoots = [];
+async function fixtureRoot() {
+  const root = await createFixtureRoot();
+  fixtureRoots.push(root);
+  return root;
+}
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(fixtureRoots.splice(0).map(removeFixtureRoot));
+});
+async function legacyFixture() {
+  const root = await fixtureRoot();
+  return writeFixturePackage(root, {
+    dir: "legacy",
+    packageJson: { name: "legacy", version: "1.0.0" }
+  });
+}
+async function warningOnlyFixture() {
+  const root = await fixtureRoot();
+  writeFixturePackage(root, {
+    dir: "app/node_modules/base",
+    packageJson: {
+      name: "base",
+      version: "1.0.0",
+      dependencies: { vue: "^3.4.0" },
+      esmx: { provides: ["vue"] }
+    },
+    built: true
+  });
+  writeFixturePackage(root, {
+    dir: "app/node_modules/base/node_modules/vue",
+    packageJson: { name: "vue", version: "3.4.21" }
+  });
+  return writeFixturePackage(root, {
+    dir: "app",
+    packageJson: {
+      name: "app",
+      version: "1.0.0",
+      esmx: {
+        entry: { client: "./src/entry.client.ts" },
+        uses: ["base"]
+      }
+    }
+  });
+}
+async function dupProviderFixture() {
+  const root = await fixtureRoot();
+  writeFixturePackage(root, {
+    dir: "node_modules/base",
+    packageJson: {
+      name: "base",
+      version: "1.0.0",
+      dependencies: { vue: "^3.4.0" },
+      esmx: { provides: ["vue"] }
+    },
+    built: true
+  });
+  writeFixturePackage(root, {
+    dir: "node_modules/base/node_modules/vue",
+    packageJson: { name: "vue", version: "3.4.21" }
+  });
+  writeFixturePackage(root, {
+    dir: "node_modules/vue-base",
+    packageJson: {
+      name: "vue-base",
+      version: "1.0.0",
+      dependencies: { vue: "^3.4.0" },
+      esmx: { uses: ["base"], provides: ["vue"] }
+    },
+    built: true
+  });
+  writeFixturePackage(root, {
+    dir: "node_modules/vue-base/node_modules/vue",
+    packageJson: { name: "vue", version: "3.5.13" }
+  });
+  return writeFixturePackage(root, {
+    dir: "app",
+    packageJson: {
+      name: "app",
+      version: "1.0.0",
+      dependencies: { vue: "^3.4.0" },
+      esmx: { uses: ["vue-base"] }
+    }
+  });
+}
+async function notLinkedFixture() {
+  const root = await fixtureRoot();
+  return writeFixturePackage(root, {
+    dir: "app",
+    packageJson: {
+      name: "app",
+      version: "1.0.0",
+      esmx: {
+        entry: { client: "./src/entry.client.ts" },
+        uses: ["ghost"]
+      }
+    }
+  });
+}
+describe("runValidate", () => {
+  it("should exit 0 with protocol legacy for a package without esmx field", async () => {
+    const appDir = await legacyFixture();
+    const jsonResult = await runValidate(appDir, { json: true });
+    const humanResult = await runValidate(appDir);
+    expect(jsonResult.exitCode).toBe(0);
+    expect(JSON.parse(jsonResult.output)).toEqual({
+      protocol: "legacy",
+      diagnostics: []
+    });
+    expect(humanResult.exitCode).toBe(0);
+    expect(humanResult.output).toContain("entry.node.ts");
+    expect(humanResult.output).toContain("opt-in");
+  });
+  it("should exit 0 when the declaration only has warnings", async () => {
+    const appDir = await warningOnlyFixture();
+    const result = await runValidate(appDir, { json: true });
+    const envelope = JSON.parse(result.output);
+    expect(result.exitCode).toBe(0);
+    expect(envelope.diagnostics).toHaveLength(1);
+    expect(envelope.diagnostics[0].code).toBe("W_NO_RANGE");
+    expect(envelope.supply.vue).toEqual({
+      groups: [{ major: 3, provider: "base", version: "3.4.21" }]
+    });
+    expect(Object.keys(envelope.mounts)).toEqual(["base"]);
+    expect(envelope.mounts.base.built).toBe(true);
+  });
+  it("should exit non-zero for E_NOT_LINKED with the exact envelope entry shape", async () => {
+    const appDir = await notLinkedFixture();
+    const result = await runValidate(appDir, { json: true });
+    const envelope = JSON.parse(result.output);
+    expect(result.exitCode).toBe(1);
+    const entry = envelope.diagnostics.find(
+      (d) => d.code === "E_NOT_LINKED"
+    );
+    expect(entry).toBeDefined();
+    expect(entry.module).toBe("app");
+    expect(typeof entry.message).toBe("string");
+    expect(typeof entry.fix).toBe("string");
+    expect(entry).not.toHaveProperty("severity");
+  });
+  it("should exit non-zero and surface E_DUP_PROVIDER in the JSON envelope", async () => {
+    const appDir = await dupProviderFixture();
+    const result = await runValidate(appDir, { json: true });
+    const envelope = JSON.parse(result.output);
+    expect(result.exitCode).toBe(1);
+    const entry = envelope.diagnostics.find(
+      (d) => d.code === "E_DUP_PROVIDER"
+    );
+    expect(entry).toBeDefined();
+    expect(entry.module).toBe("vue-base");
+    expect(entry.package).toBe("vue");
+    expect(entry.found).toBe("base, vue-base");
+    expect(envelope).not.toHaveProperty("elections");
+  });
+  it("should print E_DUP_PROVIDER in the human report", async () => {
+    const appDir = await dupProviderFixture();
+    const result = await runValidate(appDir);
+    const plain = util.stripVTControlCharacters(result.output);
+    expect(plain).toContain("[E_DUP_PROVIDER]");
+    expect(plain).toContain("vue-base \u2192 vue");
+    expect(plain).toContain("base, vue-base");
+  });
+  it("should report diagnostics, supply and mounts in human mode", async () => {
+    const appDir = await warningOnlyFixture();
+    const result = await runValidate(appDir);
+    const plain = util.stripVTControlCharacters(result.output);
+    expect(result.exitCode).toBe(0);
+    expect(plain).toContain("[W_NO_RANGE]");
+    expect(plain).toContain("fix:");
+    expect(plain).toContain("vue \u2192 base@3.4.21");
+    expect(plain).toMatch(/base → .*dist \(built\)/);
+  });
+  it("should produce pure JSON output without writing to the console", async () => {
+    const appDir = await notLinkedFixture();
+    const log = vi.spyOn(console, "log").mockImplementation(() => {
+    });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {
+    });
+    const error = vi.spyOn(console, "error").mockImplementation(() => {
+    });
+    const result = await runValidate(appDir, { json: true });
+    expect(() => JSON.parse(result.output)).not.toThrow();
+    expect(log).not.toHaveBeenCalled();
+    expect(warn).not.toHaveBeenCalled();
+    expect(error).not.toHaveBeenCalled();
+  });
+});
+const distCli = path.resolve(
+  path.dirname(url.fileURLToPath(import.meta.url)),
+  "../../dist/cli/index.mjs"
+);
+describe.skipIf(!fs.existsSync(distCli))("esmx validate (spawned CLI)", () => {
+  it("should emit only the JSON envelope on stdout and exit non-zero on errors", async () => {
+    const childProcess = await import("node:child_process");
+    const appDir = await notLinkedFixture();
+    const spawned = childProcess.spawnSync(
+      process.execPath,
+      [distCli, "validate", "--json"],
+      { cwd: appDir, encoding: "utf-8" }
+    );
+    expect(spawned.status).toBe(1);
+    const envelope = JSON.parse(spawned.stdout);
+    expect(envelope.diagnostics[0].code).toBe("E_NOT_LINKED");
+  });
+});

package/dist/core.d.ts

@@ -298,6 +298,35 @@ export declare class Esmx {
      * ```
      */
     destroy(): Promise<boolean>;
+    /**
+     * Atomic generational relink (RFC 0001 §9).
+     *
+     * In-process remotes are not hot-swappable: the server import map and the
+     * module loader are captured once when the app is created. When a mounted
+     * remote republishes (new resolved versions, new wiring), the composer
+     * adopts it by relinking — building a NEW generation (fresh cache,
+     * re-resolved module config, rebuilt app capturing a new import map +
+     * loader) and switching to it atomically.
+     *
+     * The previous generation keeps serving throughout the rebuild; the new
+     * app is installed only once it is fully built, then the previous app's
+     * resources are released. If the rebuild fails, the previous generation
+     * is fully restored (rollback) and the error propagates — a failed relink
+     * never takes the running server down.
+     *
+     * Scope: the production render path (`start`/`preview`). Dev rebuilds its
+     * own app. Cross-compiler dev-watch invalidation remains future work.
+     *
+     * @returns true once the new generation is live.
+     * @throws {NotReadyError} when called before {@link init}.
+     *
+     * @example
+     * ```ts
+     * // After a mounted remote republishes:
+     * await esmx.reinit(); // new generation live, old requests drained
+     * ```
+     */
+    reinit(): Promise<boolean>;
     /**
      * Execute the application's build process.
      *
@@ -672,10 +701,12 @@ export declare class Esmx {
         src: string;
         filepath: string;
         code: string;
+        integrity: Record<string, string> | null;
     } : {
         src: null;
         filepath: null;
         code: string;
+        integrity: Record<string, string> | null;
     }>;
     /**
      * Get the list of static import paths for a module.