@fulgurjs/federation 4.0.0 → 4.2.0

package/dist/cli.js

@@ -9,52 +9,208 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/manifest.ts
+function validAssetRef(v) {
+  if (typeof v !== "string" || v.length === 0) return false;
+  if (/[\s\u0000-\u001f]/.test(v)) return false;
+  if (/^https?:\/\/[^/@\s]+:[^/@\s]+@/.test(v)) return false;
+  return true;
+}
+function validExposeName(v) {
+  return typeof v === "string" && /^\.[\w./-]+$/.test(v);
+}
+function parseManifest(input) {
+  const issues = [];
+  if (!isPlainObject(input)) {
+    return { issues: [{ field: "$", message: "manifest \u5FC5\u987B\u662F JSON \u5BF9\u8C61", got: typeof input }] };
+  }
+  const m = input;
+  let schemaVersion = MANIFEST_SCHEMA_VERSION;
+  if (m.schemaVersion !== void 0) {
+    if (typeof m.schemaVersion !== "number" || !Number.isInteger(m.schemaVersion)) {
+      issues.push({ field: "schemaVersion", message: "\u5FC5\u987B\u662F\u6574\u6570", got: m.schemaVersion });
+    } else if (m.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+      return {
+        issues: [
+          {
+            field: "schemaVersion",
+            message: `\u4E0D\u652F\u6301\u7684 manifest \u4E3B\u7248\u672C\uFF08\u5F53\u524D\u6D88\u8D39\u7AEF\u652F\u6301 ${MANIFEST_SCHEMA_VERSION}\uFF09`,
+            got: m.schemaVersion
+          }
+        ],
+        unsupportedVersion: m.schemaVersion
+      };
+    }
+  }
+  if (typeof m.name !== "string" || m.name.length === 0) {
+    issues.push({ field: "name", message: "\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32", got: m.name });
+  }
+  const exposes = m.exposes;
+  const shared = m.shared;
+  const sharedIssues = validateShared(shared);
+  issues.push(...sharedIssues);
+  if (Array.isArray(exposes)) {
+    if (m.devServer !== true) {
+      issues.push({ field: "devServer", message: "dev \u6570\u7EC4\u5F62\u6001 exposes \u5FC5\u987B\u4F34\u968F devServer: true", got: m.devServer });
+    }
+    if (typeof m.base !== "string" || !/^\/(?:.*\/)?$/.test(m.base)) {
+      issues.push({ field: "base", message: "\u5FC5\u987B\u662F\u4EE5 / \u5F00\u5934\u4E14 / \u7ED3\u5C3E\u7684\u8DEF\u5F84", got: m.base });
+    }
+    if (!validAssetRef(m.entry)) {
+      issues.push({ field: "entry", message: "\u5FC5\u987B\u662F\u5408\u6CD5\u8D44\u6E90\u5730\u5740", got: m.entry });
+    }
+    for (const [i, e] of exposes.entries()) {
+      if (!isPlainObject(e)) {
+        issues.push({ field: `exposes[${i}]`, message: "\u5FC5\u987B\u662F\u5BF9\u8C61", got: typeof e });
+        continue;
+      }
+      if (!validExposeName(e.name)) {
+        issues.push({ field: `exposes[${i}].name`, message: '\u5FC5\u987B\u662F "./xxx" \u5F62\u6001\u7684 expose \u540D', got: e.name });
+      }
+      if (typeof e.src !== "string" || e.src.length === 0) {
+        issues.push({ field: `exposes[${i}].src`, message: "dev \u5F62\u6001\u5FC5\u987B\u63D0\u4F9B\u6E90\u7801\u76F8\u5BF9\u8DEF\u5F84", got: e.src });
+      }
+      if (!validAssetRef(e.file)) {
+        issues.push({ field: `exposes[${i}].file`, message: "\u5FC5\u987B\u662F\u53EF\u8BF7\u6C42\u7684\u6A21\u5757\u5730\u5740", got: e.file });
+      }
+    }
+  } else if (isPlainObject(exposes)) {
+    if (!validAssetRef(m.entry)) {
+      issues.push({ field: "entry", message: "\u5FC5\u987B\u662F\u5408\u6CD5\u8D44\u6E90\u5730\u5740\uFF08\u76F8\u5BF9\u57FA\u51C6 = \u6240\u5728\u76EE\u5F55\uFF09", got: m.entry });
+    }
+    for (const [key, v] of Object.entries(exposes)) {
+      if (!validExposeName(key)) {
+        issues.push({ field: `exposes["${key}"]`, message: '\u952E\u5FC5\u987B\u662F "./xxx" \u5F62\u6001\u7684 expose \u540D' });
+      }
+      if (!isPlainObject(v)) {
+        issues.push({ field: `exposes["${key}"]`, message: "\u503C\u5FC5\u987B\u662F\u5BF9\u8C61", got: typeof v });
+        continue;
+      }
+      if (!validAssetRef(v.file)) {
+        issues.push({ field: `exposes["${key}"].file`, message: "\u5FC5\u987B\u662F\u8D44\u6E90\u8DEF\u5F84\uFF08\u76F8\u5BF9 entry \u76EE\u5F55\uFF09", got: v.file });
+      }
+      if (v.css !== void 0) {
+        if (!Array.isArray(v.css)) {
+          issues.push({ field: `exposes["${key}"].css`, message: "\u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4", got: typeof v.css });
+        } else {
+          v.css.forEach((css, i) => {
+            if (!validAssetRef(css)) {
+              issues.push({ field: `exposes["${key}"].css[${i}]`, message: "\u5FC5\u987B\u662F\u8D44\u6E90\u8DEF\u5F84", got: css });
+            }
+          });
+        }
+      }
+    }
+  } else {
+    issues.push({ field: "exposes", message: "\u5FC5\u987B\u662F\u6570\u7EC4\uFF08dev\uFF09\u6216\u5BF9\u8C61\uFF08prod\uFF09", got: typeof exposes });
+  }
+  if (issues.length > 0) return { issues };
+  return { manifest: input, issues };
+}
+function validateShared(shared) {
+  if (shared === void 0) return [];
+  const issues = [];
+  if (!Array.isArray(shared)) {
+    return [{ field: "shared", message: "\u5FC5\u987B\u662F\u6570\u7EC4", got: typeof shared }];
+  }
+  for (const [i, s] of shared.entries()) {
+    if (!isPlainObject(s)) {
+      issues.push({ field: `shared[${i}]`, message: "\u5FC5\u987B\u662F\u5BF9\u8C61", got: typeof s });
+      continue;
+    }
+    if (typeof s.name !== "string" || s.name.length === 0) {
+      issues.push({ field: `shared[${i}].name`, message: "\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32", got: s.name });
+    }
+    if (typeof s.version !== "string" || s.version.length === 0) {
+      issues.push({ field: `shared[${i}].version`, message: "\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32", got: s.version });
+    }
+  }
+  return issues;
+}
+function isDevManifest(m) {
+  return Array.isArray(m.exposes);
+}
+function normalizeExposes(manifest) {
+  const out = /* @__PURE__ */ new Map();
+  if (isDevManifest(manifest)) {
+    for (const e of manifest.exposes) {
+      if (!validExposeName(e.name)) continue;
+      out.set(e.name, { name: e.name, file: e.file, css: [], src: e.src });
+    }
+  } else {
+    for (const [key, v] of Object.entries(manifest.exposes)) {
+      if (!validExposeName(key)) continue;
+      out.set(key, { name: key, file: v.file, css: Array.isArray(v.css) ? v.css.filter((c) => typeof c === "string") : [] });
+    }
+  }
+  return out;
+}
+var MANIFEST_SCHEMA_VERSION, isPlainObject;
+var init_manifest = __esm({
+  "src/manifest.ts"() {
+    "use strict";
+    MANIFEST_SCHEMA_VERSION = 1;
+    isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+  }
+});
+
 // src/config.ts
 async function loadRepoConfig(configPath) {
-  const { pathToFileURL, fileURLToPath } = await import("node:url");
-  const { createRequire } = await import("node:module");
-  const fs2 = await import("node:fs");
+  const { pathToFileURL: pathToFileURL2, fileURLToPath } = await import("node:url");
+  const { createRequire: createRequire2 } = await import("node:module");
+  const fs3 = await import("node:fs");
   const os = await import("node:os");
-  const path2 = await import("node:path");
-  const selfDir = path2.dirname(fileURLToPath(import.meta.url));
-  const selfConfigJs = path2.join(selfDir, "config.js");
-  const SELF_SPEC = fs2.existsSync(selfConfigJs) ? pathToFileURL(selfConfigJs).href : "@fulgurjs-federation-config-unavailable";
+  const path3 = await import("node:path");
+  const selfDir = await (async () => {
+    try {
+      return path3.dirname(fileURLToPath(import.meta.url));
+    } catch {
+    }
+    try {
+      return __dirname;
+    } catch {
+    }
+    return "";
+  })();
+  const selfConfigJs = selfDir ? path3.join(selfDir, "config.js") : "";
+  const SELF_SPEC = selfConfigJs && fs3.existsSync(selfConfigJs) ? pathToFileURL2(selfConfigJs).href : "@fulgurjs-federation-config-unavailable";
   const rewriteSelfImports = (source) => source.replace(/(['"])@fulgurjs\/federation\/config\1/g, (_m, q) => `${q}${SELF_SPEC}${q}`);
+  let cacheBust = 0;
   const importConfigs = async (cacheKey) => {
-    return await import(`${cacheKey}?t=${Date.now()}`);
+    return await import(`${cacheKey}?t=${Date.now()}-${++cacheBust}`);
   };
   let mod;
   if (configPath.endsWith(".json")) {
-    mod = { default: JSON.parse(fs2.readFileSync(configPath, "utf8")) };
+    mod = { default: JSON.parse(fs3.readFileSync(configPath, "utf8")) };
   } else {
-    const source = rewriteSelfImports(fs2.readFileSync(configPath, "utf8"));
-    const tmpBase = path2.join(os.tmpdir(), `fulgurjs-config-${Date.now()}`);
+    const source = rewriteSelfImports(fs3.readFileSync(configPath, "utf8"));
+    const tmpBase = path3.join(os.tmpdir(), `fulgurjs-config-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
     if (/\.(ts|mts|cts)$/.test(configPath)) {
       try {
         const tmpTs = `${tmpBase}.ts`;
-        fs2.writeFileSync(tmpTs, source);
-        mod = await importConfigs(pathToFileURL(tmpTs).href);
+        fs3.writeFileSync(tmpTs, source);
+        mod = await importConfigs(pathToFileURL2(tmpTs).href);
       } catch (e) {
         if (!/Unexpected|SyntaxError|ERR_UNSUPPORTED_NODE_MODULES|ERR_UNKNOWN_FILE_EXTENSION|ERR_IMPORT_ATTRIBUTE/.test(String(e)) && process.version.startsWith("v2")) {
           throw e;
         }
-        const requireFromConfig = createRequire(configPath);
+        const requireFromConfig = createRequire2(configPath);
         let esbuild;
         try {
           esbuild = requireFromConfig("esbuild");
         } catch {
-          const requireFromSelf = createRequire(import.meta.url);
+          const requireFromSelf = createRequire2(import.meta.url);
           esbuild = requireFromSelf("esbuild");
         }
         const out = esbuild.buildSync({ entryPoints: [configPath], bundle: false, write: false, format: "esm", target: "node18" });
         const jsFile = `${tmpBase}.mjs`;
-        fs2.writeFileSync(jsFile, rewriteSelfImports(out.outputFiles[0].text));
-        mod = await importConfigs(pathToFileURL(jsFile).href);
+        fs3.writeFileSync(jsFile, rewriteSelfImports(out.outputFiles[0].text));
+        mod = await importConfigs(pathToFileURL2(jsFile).href);
       }
     } else {
       const jsFile = `${tmpBase}.mjs`;
-      fs2.writeFileSync(jsFile, source);
-      mod = await importConfigs(pathToFileURL(jsFile).href);
+      fs3.writeFileSync(jsFile, source);
+      mod = await importConfigs(pathToFileURL2(jsFile).href);
     }
   }
   const cfg = mod.default;
@@ -73,18 +229,278 @@ async function loadRepoConfig(configPath) {
       throw new Error(
         `[fulgurjs:init] \u5E94\u7528 "${app.path}" \u65E2\u65E0 host \u4E5F\u65E0 remote \u89D2\u8272
 \u6839\u56E0\uFF1A\u5E94\u7528\u5FC5\u987B\u81F3\u5C11\u58F0\u660E\u4E00\u4E2A\u89D2\u8272
-\u4FEE\u6CD5\uFF1A\u5BBF\u4E3B\u8865 host: { pages, remotePrefixes, remotes }\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
+\u4FEE\u6CD5\uFF1A\u5BBF\u4E3B\u8865 host: { remotePrefixes, remotes }\uFF08pages \u53EF\u9009\uFF09\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
       );
     }
   }
   return cfg;
 }
+function federationOptionsForApp(config, appPathOrName) {
+  const app = config.apps.find(
+    (a) => a.path === appPathOrName || a.name === appPathOrName
+  );
+  if (!app) {
+    throw new Error(
+      `[fulgurjs] \u5E94\u7528 "${appPathOrName}" \u4E0D\u5728\u4ED3\u5E93\u914D\u7F6E\u4E2D
+  \u53EF\u7528\u5E94\u7528: ${config.apps.map((a) => `${a.path}(${a.name})`).join("\u3001")}
+  \u4FEE\u6CD5: \u4FEE\u6B63\u5E94\u7528\u76EE\u5F55\u540D\u6216\u5BB9\u5668\u540D\uFF08fulgurjs.config.ts apps \u6570\u7EC4\u5185\u4E8C\u9009\u4E00\u5339\u914D\uFF09`
+    );
+  }
+  if (!app.host && !app.remote) {
+    throw new Error(
+      `[fulgurjs] \u5E94\u7528 "${app.path}" \u65E2\u65E0 host \u4E5F\u65E0 remote \u89D2\u8272
+  \u4FEE\u6CD5: \u5BBF\u4E3B\u8865 host: { remotePrefixes, remotes }\uFF0C\u8FDC\u7A0B\u8865 remote: { exposes }`
+    );
+  }
+  const remotes = {};
+  const remoteSource = /* @__PURE__ */ new Map();
+  const mergeRemotes = (from, role) => {
+    for (const [key, addr] of Object.entries(from ?? {})) {
+      const prev = remotes[key];
+      if (prev && (prev.dev !== addr.dev || prev.prod !== addr.prod)) {
+        throw new Error(
+          `[fulgurjs] \u5E94\u7528 "${app.path}" \u7684\u8FDC\u7A0B "${key}" \u5728 ${role} \u4E0E ${remoteSource.get(key)} \u4E24\u5904\u5730\u5740\u4E0D\u4E00\u81F4
+  ${remoteSource.get(key)}: dev=${prev.dev} prod=${prev.prod}
+  ${role}: dev=${addr.dev} prod=${addr.prod}
+  \u4FEE\u6CD5: \u4FEE\u6B63 fulgurjs.config.ts \u4F7F\u4E24\u5904\u4E00\u81F4\uFF08\u540C\u4E00\u8FDC\u7A0B\u5728\u4E00\u4E2A\u5E94\u7528\u5185\u53EA\u80FD\u6709\u4E00\u4E2A\u5730\u5740\uFF09`
+        );
+      }
+      remotes[key] = addr;
+      remoteSource.set(key, role);
+    }
+  };
+  mergeRemotes(app.host?.remotes, "host.remotes");
+  mergeRemotes(app.remote?.remotes, "remote.remotes");
+  const hasExposes = !!app.remote && Object.keys(app.remote.exposes).length > 0;
+  const hasRemotes = Object.keys(remotes).length > 0;
+  return {
+    name: app.name,
+    ...hasRemotes ? { remotes } : {},
+    ...hasExposes ? { exposes: app.remote.exposes } : {},
+    ...app.remote?.setup ? { setup: app.remote.setup } : {},
+    ...app.shared ? { shared: app.shared } : {},
+    devSharedSelf: app.devSharedSelf ?? (hasExposes || !!app.remote?.setup)
+  };
+}
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
   }
 });
 
+// src/app-config.ts
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+function appConfigError(what, cause, fix) {
+  throw new Error(`[fulgurjs:config] ${what}
+\u6839\u56E0\uFF1A${cause}
+\u4FEE\u6CD5\uFF1A${fix}`);
+}
+function isAggregateShape(value) {
+  return !!value && typeof value === "object" && Array.isArray(value.apps);
+}
+function fieldError(field, got, expect, example) {
+  appConfigError(
+    `fulgurjs.config.ts \u7684 ${field} \u5F62\u72B6\u4E0D\u5408\u6CD5\uFF08\u5B9E\u9645 ${JSON.stringify(got)}\uFF09`,
+    `CLI \u6309\u5355\u9879\u76EE\u5951\u7EA6\u8BFB\u53D6\uFF1A\u9ED8\u8BA4\u5BFC\u51FA\u76F4\u63A5\u662F federation() \u9009\u9879\u5BF9\u8C61`,
+    `\u671F\u671B ${expect}\u3002\u793A\u4F8B\uFF1A
+  ${example}`
+  );
+}
+function validateAppOptions(options) {
+  if (typeof options.name !== "string" || options.name.trim() === "") {
+    fieldError(
+      "\u9ED8\u8BA4\u5BFC\u51FA name",
+      options.name,
+      "\u975E\u7A7A\u5B57\u7B26\u4E32\uFF08\u8054\u90A6\u5BB9\u5668\u540D\uFF09",
+      `export default { name: 'my-app', exposes: { './pages/home': './src/views/Home.vue' } } satisfies FederationOptions`
+    );
+  }
+  for (const legacyField of ["root", "apps", "deploy", "host", "remote"]) {
+    if (options[legacyField] !== void 0) {
+      appConfigError(
+        `\u9ED8\u8BA4\u5BFC\u51FA\u5305\u542B\u65E7\u805A\u5408/\u89D2\u8272\u58F3\u5B57\u6BB5 "${legacyField}"`,
+        "\u5355\u9879\u76EE\u5951\u7EA6\u7684\u9ED8\u8BA4\u5BFC\u51FA\u76F4\u63A5\u662F federation() \u9009\u9879\uFF08name/exposes/setup/remotes/shared/\u2026\uFF09\uFF0C\u4E0D\u5305 host/remote \u89D2\u8272\u58F3\uFF0C\u4E5F\u6CA1\u6709 root/apps[]",
+        legacyField === "host" || legacyField === "remote" ? "\u628A host/remote \u5185\u7684\u5B57\u6BB5\u62CD\u5E73\u5230\u9876\u5C42\uFF1Ahost.remotes \u2192 remotes\uFF1Bremote.exposes \u2192 exposes\uFF1Bremote.setup \u2192 setup\uFF1Bhost.pages/remotePrefixes/deriveSpec \u2192 \u5177\u540D\u5BFC\u51FA hostPages" : `${legacyField} \u5C5E\u4E8E\u65E7\u805A\u5408\u914D\u7F6E\uFF08root + apps[]\uFF0C\u517C\u5BB9\u671F\u4FDD\u7559\uFF09\u3002\u5355\u9879\u76EE\u5F62\u6001\u8BF7\u5220\u9664\u8BE5\u5B57\u6BB5\uFF1B\u805A\u5408\u7528\u6CD5\u89C1 README\u300C\u5386\u53F2\u517C\u5BB9\u300D\u7AE0\u8282`
+      );
+    }
+  }
+}
+function validateHostPages(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    fieldError("\u5177\u540D\u5BFC\u51FA hostPages", value, "\u5BF9\u8C61 { pages, remotePrefixes, deriveSpec? }", `export const hostPages = { pages, remotePrefixes, deriveSpec }`);
+  }
+  const hp = value;
+  if (!Array.isArray(hp.pages)) {
+    fieldError("hostPages.pages", hp.pages, "PageEntry[]\uFF08\u8DEF\u7531\u8868\u6570\u7EC4\uFF09", `export const hostPages = { pages: [{ route: '/remote-a/home', name: 'Home', title: '\u9996\u9875' }], remotePrefixes: { '/remote-a/': 'remote-a' } }`);
+  }
+  if (!hp.remotePrefixes || typeof hp.remotePrefixes !== "object") {
+    fieldError("hostPages.remotePrefixes", hp.remotePrefixes, "Record<\u8DEF\u7531\u524D\u7F00, \u8FDC\u7A0B\u5BB9\u5668\u540D>", `remotePrefixes: { '/remote-a/': 'remote-a' }`);
+  }
+  if (hp.deriveSpec !== void 0 && typeof hp.deriveSpec !== "function") {
+    fieldError("hostPages.deriveSpec", hp.deriveSpec, "\u51FD\u6570 (route) => spec \u6216\u7701\u7565", `deriveSpec: (route) => 'pages/' + route.split('/').filter((s) => !s.startsWith(':')).join('/')`);
+  }
+  return hp;
+}
+function validatePathsInsideApp(options, appRoot, fs3, path3) {
+  const checkModule = (field, value) => {
+    if (typeof value !== "string" || value.trim() === "") return;
+    if (/^(https?:)?\/\//.test(value) || path3.isAbsolute(value)) {
+      appConfigError(
+        `${field} "${value}" \u4E0D\u662F\u672C\u9879\u76EE\u5185\u7684\u6A21\u5757\u8DEF\u5F84`,
+        "exposes/setup \u7684\u503C\u662F\u76F8\u5BF9\u672C\u5E94\u7528\u6839\u76EE\u5F55\u7684\u6E90\u6587\u4EF6\u8DEF\u5F84\uFF08URL/\u7EDD\u5BF9\u8DEF\u5F84\u65E0\u6CD5\u5728\u72EC\u7ACB\u4ED3\u5E93\u95F4\u79FB\u690D\uFF09",
+        `\u6539\u4E3A\u76F8\u5BF9\u8DEF\u5F84\uFF0C\u5982 './src/views/Home.vue'\uFF08\u914D\u7F6E\u6587\u4EF6\u76EE\u5F55 = \u5E94\u7528\u6839 ${appRoot}\uFF09`
+      );
+    }
+    const abs = path3.resolve(appRoot, value);
+    if (!fs3.existsSync(abs)) {
+      appConfigError(
+        `${field} \u6307\u5411\u7684\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${value}`,
+        `\u6309\u5E94\u7528\u6839 ${appRoot} \u89E3\u6790\u540E\u672A\u627E\u5230\u8BE5\u6587\u4EF6`,
+        `\u6838\u5BF9\u76F8\u5BF9\u8DEF\u5F84\uFF08\u4EE5\u914D\u7F6E\u6587\u4EF6\u6240\u5728\u76EE\u5F55\u4E3A\u57FA\u51C6\uFF09\uFF1B\u6587\u4EF6\u88AB\u79FB\u52A8/\u5220\u9664\u65F6\u540C\u6B65\u66F4\u65B0 ${field}`
+      );
+    }
+  };
+  const exposes = options.exposes;
+  if (exposes !== void 0 && (typeof exposes !== "object" || exposes === null || Array.isArray(exposes))) {
+    fieldError("exposes", exposes, 'Record<"./\u952E", "./\u6E90\u6587\u4EF6">', `exposes: { './pages/home': './src/views/Home.vue' }`);
+  }
+  for (const target of Object.values(exposes ?? {})) {
+    checkModule("exposes \u6761\u76EE", typeof target === "string" ? target : target?.import);
+  }
+  checkModule("setup", options.setup);
+}
+function resolveSelfEntry(configPath, spec) {
+  const tries = [() => createRequire(configPath).resolve(spec), () => createRequire(import.meta.url).resolve(spec)];
+  for (const t of tries) {
+    try {
+      return t();
+    } catch {
+    }
+  }
+  return void 0;
+}
+function resolveSpec(spec, from) {
+  try {
+    return createRequire(from).resolve(spec);
+  } catch {
+    return void 0;
+  }
+}
+function resolveEsbuild(configPath) {
+  const esbuildOf = (base) => {
+    const direct = resolveSpec("esbuild", base);
+    if (direct) return createRequire(direct)("esbuild");
+    const viteEntry = resolveSpec("vite", base);
+    if (viteEntry) {
+      const viaVite = resolveSpec("esbuild", viteEntry);
+      if (viaVite) return createRequire(viaVite)("esbuild");
+    }
+    return void 0;
+  };
+  for (const base of [configPath, import.meta.url]) {
+    const got = esbuildOf(base);
+    if (got) return got;
+  }
+  appConfigError(
+    "\u65E0\u6CD5\u52A0\u8F7D esbuild\uFF08\u5355\u9879\u76EE\u914D\u7F6E\u52A0\u8F7D\u9700\u8981\u5B83\u8F6C\u8BD1 TS \u4E0E\u76F8\u5BF9\u5BFC\u5165\uFF09",
+    "\u914D\u7F6E\u5DE5\u7A0B\uFF08\u542B\u5176 vite \u4F9D\u8D56\u6811\uFF09\u4E0E CLI \u4F9D\u8D56\u6811\u4E2D\u90FD\u89E3\u6790\u4E0D\u5230 esbuild",
+    "\u9879\u76EE\u5185\u6709 vite \u4F9D\u8D56\u5373\u53EF\uFF08\u7ECF\u5176\u4F9D\u8D56\u6811\u89E3\u6790\uFF09\uFF1B\u786E\u5B9E\u7F3A\u5931\u65F6 npm i -D esbuild \u540E\u91CD\u8BD5"
+  );
+}
+async function loadAppConfig(configPath) {
+  const fs3 = await import("node:fs");
+  const os = await import("node:os");
+  const path3 = await import("node:path");
+  const abs = path3.resolve(configPath);
+  if (!fs3.existsSync(abs)) {
+    appConfigError(
+      `\u914D\u7F6E\u6587\u4EF6\u4E0D\u5B58\u5728\uFF1A${abs}`,
+      "--config \u6307\u5411\u7684\u8DEF\u5F84\u5728\u672C\u673A\u4E0D\u5B58\u5728\uFF08\u76F8\u5BF9\u8DEF\u5F84\u4EE5 CLI \u8FDB\u7A0B cwd \u89E3\u6790\uFF09",
+      "\u6838\u5BF9\u8DEF\u5F84\uFF1B\u4ECE\u5E94\u7528\u6839\u76EE\u5F55\u8FD0\u884C\u65F6\u76F4\u63A5\u7528 fulgurjs.config.ts"
+    );
+  }
+  if (abs.endsWith(".json")) {
+    const parsed = JSON.parse(fs3.readFileSync(abs, "utf8"));
+    if (isAggregateShape(parsed)) {
+      const repo = await loadRepoConfig(abs);
+      return { kind: "repo", configPath: abs, appRoot: path3.dirname(abs), repo };
+    }
+    return finishAppShape(parsed, {}, abs, path3.dirname(abs), fs3, path3);
+  }
+  const esbuild = resolveEsbuild(abs);
+  const selfRedirect = {
+    name: "fulgurjs-self-redirect",
+    setup(build) {
+      build.onResolve({ filter: /^@fulgurjs\/federation(\/|$)/ }, (args) => {
+        const resolved = resolveSelfEntry(abs, args.path);
+        if (!resolved) {
+          return { errors: [{ text: `cannot resolve "${args.path}" from the config project or the CLI itself` }] };
+        }
+        return { path: resolved };
+      });
+    }
+  };
+  const out = await esbuild.build({
+    entryPoints: [abs],
+    bundle: true,
+    write: false,
+    format: "esm",
+    target: "node18",
+    platform: "node",
+    plugins: [selfRedirect],
+    logLevel: "silent"
+  });
+  const tmpDir = fs3.mkdtempSync(path3.join(os.tmpdir(), "fulgurjs-appcfg-"));
+  try {
+    const bundleFile = path3.join(tmpDir, "fulgurjs.config.bundle.mjs");
+    fs3.writeFileSync(bundleFile, out.outputFiles[0].text);
+    const mod = await import(`${pathToFileURL(bundleFile).href}?t=${Date.now()}`);
+    if (isAggregateShape(mod.default)) {
+      const repo = await loadRepoConfig(abs);
+      return { kind: "repo", configPath: abs, appRoot: path3.dirname(abs), repo };
+    }
+    return finishAppShape(mod.default, { hostPages: mod.hostPages }, abs, path3.dirname(abs), fs3, path3);
+  } finally {
+    fs3.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+function finishAppShape(def, named, configPath, appRoot, fs3, path3) {
+  if (def === void 0 || def === null) {
+    appConfigError(
+      "fulgurjs.config.ts \u6CA1\u6709\u53EF\u7528\u7684\u9ED8\u8BA4\u5BFC\u51FA",
+      "\u5355\u9879\u76EE\u5951\u7EA6\uFF1A\u9ED8\u8BA4\u5BFC\u51FA\u76F4\u63A5\u662F federation() \u9009\u9879\u5BF9\u8C61\uFF08satisfies FederationOptions\uFF09",
+      `export default { name: 'my-app', ... } satisfies FederationOptions`
+    );
+  }
+  if (typeof def !== "object" || Array.isArray(def)) {
+    fieldError("\u9ED8\u8BA4\u5BFC\u51FA", def, "\u5BF9\u8C61\uFF08federation() \u9009\u9879\uFF09", `export default { name: 'my-app', exposes: { /* \u2026 */ } } satisfies FederationOptions`);
+  }
+  const options = def;
+  validateAppOptions(options);
+  validatePathsInsideApp(options, appRoot, fs3, path3);
+  const hostPages = named.hostPages !== void 0 ? validateHostPages(named.hostPages) : void 0;
+  return {
+    kind: "app",
+    configPath,
+    appRoot,
+    options,
+    hostPages
+  };
+}
+function roleOfOptions(options) {
+  const hasRemotes = Object.keys(options.remotes ?? {}).length > 0;
+  const hasProvides = Object.keys(options.exposes ?? {}).length > 0 || !!options.setup;
+  if (hasRemotes && hasProvides) return "dual";
+  return hasRemotes ? "host" : "remote";
+}
+var init_app_config = __esm({
+  "src/app-config.ts"() {
+    "use strict";
+    init_config();
+  }
+});
+
 // src/init.ts
 var init_exports = {};
 __export(init_exports, {
@@ -118,6 +534,8 @@ ${hostRemotes || remoteRemotes}
   const exposesBlock = app.remote?.exposes ? `  exposes: {
 ${exposesLiteral(app.remote.exposes)}
   },
+` : "";
+  const setupBlock = app.remote?.setup ? `  setup: '${app.remote.setup}',
 ` : "";
   const sharedBlock = app.shared ? `  shared: {
 ${Object.entries(app.shared).map(([k, v]) => {
@@ -125,11 +543,22 @@ ${Object.entries(app.shared).map(([k, v]) => {
     return `    '${k}': { ${opts.join(", ")} },`;
   }).join("\n")}
   },
-` : `  ${DEFAULT_SHARED_BLOCK},
-`;
+` : "";
   return `federation({
   name: '${app.name}',
-${remotesBlock}${exposesBlock}${sharedBlock}})`;
+${remotesBlock}${exposesBlock}${setupBlock}${sharedBlock}})`;
+}
+function viteSnippetForAppMode(appRoot) {
+  return `// ${appRoot}/vite.config.ts\uFF08\u8054\u90A6\u76F8\u5173\u884C\uFF1B\u5176\u4F59 Vite \u914D\u7F6E\u539F\u6837\u4FDD\u7559\uFF09
+import federation from '@fulgurjs/federation'
+import fulgurjsConfig from './fulgurjs.config'
+
+export default defineConfig({
+  plugins: [
+    // ...\u539F\u6709\u63D2\u4EF6,
+    federation(fulgurjsConfig),
+  ],
+})`;
 }
 function nginxSnippetFor(cfg) {
   const listen = cfg.deploy?.listen ?? 8080;
@@ -156,7 +585,7 @@ function nginxSnippetFor(cfg) {
   }`;
     }
   ).join("\n\n");
-  return `# \u8054\u90A6\u7AD9\u70B9\u6A21\u677F\uFF08\u8981\u70B9\uFF1AremoteEntry/manifest/index.html \u5FC5\u987B no-cache\u2014\u2014
+  return `# \u8054\u90A6\u7AD9\u70B9\u6837\u677F\uFF08\u6253\u5370\u6837\u677F\uFF0C\u4E0D\u5199\u6587\u4EF6\u3002\u8981\u70B9\uFF1AremoteEntry/manifest/index.html \u5FC5\u987B no-cache\u2014\u2014
 # \u6587\u4EF6\u540D\u56FA\u5B9A\u800C\u5185\u5BB9\u6BCF\u6B21\u6784\u5EFA\u53D8\u5316\uFF0Cimmutable \u957F\u7F13\u5B58\u4F1A\u8BA9\u6D4F\u89C8\u5668\u6301\u65E7\u5165\u53E3\u3001\u91CD\u90E8\u7F72\u540E\u5168 404\uFF1B
 # \u5E26 hash \u7684 assets \u624D\u914D\u957F\u7F13\u5B58\uFF1B\u8DE8\u6E90\u90E8\u7F72\u65F6\u4FDD\u7559 Access-Control-Allow-Origin\uFF09
 server {
@@ -174,235 +603,695 @@ function appSummary(app) {
     for (const [k, v] of Object.entries(app.host.remotes)) {
       lines.push(`    \u6D88\u8D39\u8FDC\u7A0B ${k} \u2192 dev ${v.dev} / prod ${v.prod}`);
     }
-    lines.push(`    \u9875\u9762\u8DEF\u7531\u8868\uFF1A${app.host.pages.length} \u6761`);
+    lines.push(`    \u9875\u9762\u8DEF\u7531\u8868\uFF1A${app.host.pages?.length ?? 0} \u6761${app.host.pages ? "" : "\uFF08\u672A\u5728\u4ED3\u5E93\u914D\u7F6E\u4E2D\u63D0\u4F9B\u2014\u2014\u4EE5\u5E94\u7528\u4EE3\u7801\u9875\u9762\u8868\u4E3A\u51C6\uFF09"}`);
   }
   if (app.remote?.exposes) {
     lines.push(`    exposes\uFF1A${Object.keys(app.remote.exposes).join("\u3001")}`);
   }
+  if (app.remote?.setup) {
+    lines.push(`    setup\uFF08\u53EF\u9009\u8FDC\u7A0B\u521D\u59CB\u5316\uFF09\uFF1A${app.remote.setup}`);
+  }
   if (app.remote?.remotes) {
     for (const [k, v] of Object.entries(app.remote.remotes)) {
-      lines.push(`    \u53CD\u5411\u6D88\u8D39 ${k} \u2192 dev ${v.dev} / prod ${v.prod}\uFF08\u53CC\u5411\u8054\u90A6\uFF0Cdev \u4E0B\u9700 devSharedSelf: true\uFF09`);
+      lines.push(`    \u53CD\u5411\u6D88\u8D39 ${k} \u2192 dev ${v.dev} / prod ${v.prod}\uFF08\u53CC\u5411\u8054\u90A6\uFF09`);
     }
   }
   return lines.join("\n");
 }
+function appModeSummary(loaded) {
+  const options = loaded.options;
+  const roleText = { host: "\u5BBF\u4E3B", remote: "\u8FDC\u7A0B", dual: "\u5BBF\u4E3B+\u8FDC\u7A0B\uFF08\u53CC\u89D2\u8272\uFF09" }[Object.keys(options.remotes ?? {}).length > 0 && (Object.keys(options.exposes ?? {}).length > 0 || !!options.setup) ? "dual" : Object.keys(options.remotes ?? {}).length > 0 ? "host" : "remote"];
+  const lines = [];
+  lines.push(`  ${options.name}\uFF08${roleText}\uFF0C\u5355\u9879\u76EE\u914D\u7F6E\uFF0C\u76EE\u5F55 ${loaded.appRoot}\uFF1Bbase/dev \u7AEF\u53E3\u7531 vite.config.ts \u7BA1\u7406\uFF09`);
+  for (const [k, v] of Object.entries(options.remotes ?? {})) {
+    const cfg = typeof v === "string" ? { dev: v, prod: v } : v;
+    lines.push(`    \u6D88\u8D39\u8FDC\u7A0B ${k} \u2192 dev ${cfg.dev ?? ""} / prod ${cfg.prod ?? ""}`);
+  }
+  if (options.exposes) {
+    lines.push(`    exposes\uFF08${Object.keys(options.exposes).length}\uFF09\uFF1A${Object.keys(options.exposes).join("\u3001")}`);
+  }
+  if (options.setup) {
+    lines.push(`    setup\uFF08\u53EF\u9009\u8FDC\u7A0B\u521D\u59CB\u5316\uFF09\uFF1A${options.setup}`);
+  }
+  if (loaded.hostPages) {
+    lines.push(`    \u9875\u9762\u8DEF\u7531\u8868\uFF08hostPages \u5177\u540D\u5BFC\u51FA\uFF09\uFF1A${loaded.hostPages.pages.length} \u6761`);
+  } else {
+    lines.push("    \u9875\u9762\u8DEF\u7531\u8868\uFF1A\uFF08\u65E0 hostPages \u5BFC\u51FA\u2014\u2014\u7EAF\u8FDC\u7A0B\u5E94\u7528\u65E0\u9700\uFF1B\u5BBF\u4E3B\u5EFA\u8BAE\u63D0\u4F9B\uFF09");
+  }
+  return lines;
+}
 async function inspectConfig(configPath) {
-  const cfg = await loadRepoConfig(configPath);
+  const loaded = await loadAppConfig(configPath);
   const out = [];
-  out.push(`${MARK} \u914D\u7F6E\u6821\u9A8C\u901A\u8FC7\uFF1Aroot=${cfg.root}\uFF0Capps=${cfg.apps.length}`);
+  if (loaded.kind === "app") {
+    out.push(`${MARK} \u914D\u7F6E\u6821\u9A8C\u901A\u8FC7\uFF1A\u5355\u9879\u76EE\u5F62\u6001\uFF08\u9ED8\u8BA4\u5BFC\u51FA = federation() \u9009\u9879\uFF09`);
+    out.push("\u5E94\u7528\u6458\u8981\uFF1A");
+    out.push(...appModeSummary(loaded));
+    out.push("\n\u2500\u2500 vite.config.ts plugins \u63A5\u5165\u5757\uFF08\u8FD9\u5C31\u662F\u5168\u90E8\u8054\u90A6\u63A5\u5165\u4EE3\u7801\uFF09 \u2500\u2500");
+    out.push(viteSnippetForAppMode(loaded.appRoot));
+    out.push("\n\u2500\u2500 \u63A5\u5165\u6838\u5BF9\u6E05\u5355\uFF08\u8054\u90A6\u901A\u7528\u9879\uFF0C\u4E0E\u5177\u4F53\u9879\u76EE\u65E0\u5173\uFF09 \u2500\u2500");
+    out.push(...COMMON_CHECKLIST);
+    return out.join("\n");
+  }
+  const cfg = loaded.repo ?? await loadRepoConfig(loaded.configPath);
+  out.push(`${MARK} \u914D\u7F6E\u6821\u9A8C\u901A\u8FC7\uFF1Aroot=${cfg.root}\uFF0Capps=${cfg.apps.length}\u3010\u65E7\u805A\u5408\u914D\u7F6E\u5F62\u6001\uFF08root+apps[]\uFF09\uFF0C\u517C\u5BB9\u671F\u4FDD\u7559\uFF1B\u65B0\u9879\u76EE\u63A8\u8350\u6BCF\u9879\u76EE\u4E00\u4EFD\u5355\u9879\u76EE\u914D\u7F6E\uFF0C\u89C1 README\u3011`);
   out.push("\u5E94\u7528\u6458\u8981\uFF1A");
   for (const app of cfg.apps) out.push(appSummary(app));
-  out.push("\n\u2500\u2500 \u5404\u5E94\u7528 vite.config.ts plugins \u7C98\u8D34\u5757 \u2500\u2500");
+  out.push("\n\u2500\u2500 \u5404\u5E94\u7528 vite.config.ts plugins \u7C98\u8D34\u5757\uFF08\u65E7\u805A\u5408\u5F62\u6001\u9700\u7ECF loadRepoConfig/federationOptionsForApp \u8F6C\u6362\uFF09 \u2500\u2500");
   for (const app of cfg.apps) {
     out.push(`
 # ${app.path}\uFF08${app.name}\uFF09`);
     out.push(viteSnippetFor(app));
   }
-  out.push("\n\u2500\u2500 NGINX \u7AD9\u70B9\u6A21\u677F \u2500\u2500");
+  out.push("\n\u2500\u2500 NGINX \u7AD9\u70B9\u6837\u677F\uFF08\u6253\u5370\u6837\u677F\uFF0C\u4E0D\u5199\u6587\u4EF6\uFF09 \u2500\u2500");
   out.push(nginxSnippetFor(cfg));
   out.push("\n\u2500\u2500 \u63A5\u5165\u6838\u5BF9\u6E05\u5355\uFF08\u8054\u90A6\u901A\u7528\u9879\uFF0C\u4E0E\u5177\u4F53\u9879\u76EE\u65E0\u5173\uFF09 \u2500\u2500");
-  out.push("1. \u5BBF\u4E3B\u4E0E\u8FDC\u7A0B\u90FD\u5B89\u88C5\u4F9D\u8D56\uFF1Apnpm add @fulgurjs/federation");
-  out.push("2. expose \u4E00\u5F8B\u6307\u5411\u72EC\u7ACB\u9875\uFF08\u9875\u9762\u4ECE\u8DEF\u7531\u53D6\u53C2\uFF09\uFF1B\u7EC4\u4EF6\u9700\u8981\u5FC5\u586B props \u65F6\u7ED9\u9ED8\u8BA4\u503C\uFF08BLD-003\uFF09");
-  out.push("3. shared \u91CC vue / vue-router / pinia \u5EFA\u8BAE singleton: true\u2014\u2014\u8DE8\u5E94\u7528\u5FC5\u987B\u540C\u5B9E\u4F8B\uFF08\u5168\u5C40\u54CD\u5E94\u6027\u3001getActivePinia\u3001\u8DEF\u7531\u6CE8\u5165\uFF09");
-  out.push("4. \u8FDC\u7A0B\u7684\u5168\u5C40\u526F\u4F5C\u7528\uFF08\u5168\u5C40\u7EC4\u4EF6/\u6307\u4EE4/\u542F\u52A8\u671F\u521D\u59CB\u5316\uFF09\u5C01\u88C5\u4E3A\u542F\u52A8\u5668\u6A21\u5757\u5E76 expose\uFF0C\u5BBF\u4E3B\u5728 loadRemote \u9875\u9762\u524D\u8C03\u7528\uFF1B");
-  out.push("   \u8DE8\u5E94\u7528\u4F20\u503C\uFF08locale/store/\u4E8B\u4EF6\u7B49\uFF09\u7EDF\u4E00\u8D70 @fulgurjs/federation/runtime \u7684 context \u51FD\u6570\uFF1A\u5BBF\u4E3B provideAppContext \u4E00\u6B21\u5199\u5165\uFF0C\u8FDC\u7A0B boot \u7528 getAppContext / requireAppContext \u6D88\u8D39");
-  out.push("5. \u5E94\u7528\u4EE3\u7801\u552F\u4E00 API \u5165\u53E3\uFF1Aimport { loadRemote, provideAppContext, getAppContext, definePages, remoteSchema, remoteComponent } from '@fulgurjs/federation/runtime'\u2014\u20144.0.0 \u8D77 virtual:fulgurjs-api \u5DF2\u5220\u9664\uFF0C\u7C7B\u578B\u7531\u7269\u7406\u5B50\u8DEF\u5F84\u76F4\u63A5\u89E3\u6790");
-  out.push('6. dev \u51B7\u542F\u52A8\u9996\u8F6E 30~60s \u6709\u9884\u6784\u5EFA\u7A97\u53E3\uFF08\u77AC\u65F6 504/"ce"\uFF0CDEV-010\uFF09\uFF1A\u5148\u771F\u5B9E\u6253\u5F00\u9875\u9762\u9884\u70ED\u518D\u505A\u65AD\u8A00');
-  out.push("7. \u90E8\u7F72\u540E\u4F53\u68C0\uFF1Afulgurjs doctor --base <URL> --apps <\u5E94\u7528...>\uFF08\u7F13\u5B58\u5934/\u8D44\u6E90\u5F62\u6001/CORS/chunk \u53EF\u8FBE/\u7248\u672C skew\uFF09");
-  out.push("8. \u90E8\u7F72\u8BED\u4E49\uFF1AremoteEntry/manifest/index.html \u5FC5\u987B no-cache\uFF08\u4E25\u7981 immutable\uFF09\uFF1B\u5E26 hash \u7684 assets \u957F\u7F13\u5B58");
+  out.push(...COMMON_CHECKLIST);
   return out.join("\n");
 }
-var MARK, STARTER_CONFIG, DEFAULT_SHARED_BLOCK;
+var MARK, STARTER_CONFIG, COMMON_CHECKLIST;
 var init_init = __esm({
   "src/init.ts"() {
     "use strict";
+    init_app_config();
     init_config();
     MARK = "[fulgurjs:init]";
-    STARTER_CONFIG = `// fulgurjs.config.ts \u2014\u2014 @fulgurjs/federation \u63A5\u5165\u914D\u7F6E\uFF08\u5355\u6587\u4EF6\u9A71\u52A8\uFF0C\u53EF\u5165\u5E93\u3001\u53EF\u590D\u8DD1\uFF09
-// \u7528\u6CD5\uFF1Anpx fulgurjs init --config fulgurjs.config.ts   \u6821\u9A8C\u914D\u7F6E\u5E76\u8F93\u51FA\u53EF\u7C98\u8D34\u6837\u677F\u4E0E\u6838\u5BF9\u6E05\u5355
-//       npx fulgurjs doctor --base http://<\u7AD9\u70B9> --apps <\u5E94\u7528\u76EE\u5F55\u540D...>   \u90E8\u7F72\u4F53\u68C0
-import { defineRepoConfig } from '@fulgurjs/federation/config'
+    STARTER_CONFIG = `// fulgurjs.config.ts \u2014\u2014 @fulgurjs/federation \u5355\u9879\u76EE\u63A5\u5165\u914D\u7F6E\uFF08\u4E00\u9879\u76EE\u4E00\u4EFD\uFF0C\u53EF\u5165\u5E93\u3001\u53EF\u590D\u8DD1\uFF09
+//
+// Vite \u63A5\u5165\uFF08\u672C\u9879\u76EE vite.config.ts \u53EA\u9700\u4E24\u884C\u8054\u90A6\u76F8\u5173\u4EE3\u7801\uFF09\uFF1A
+//   import federation from '@fulgurjs/federation'
+//   import fulgurjsConfig from './fulgurjs.config'
+//   // plugins: [ ...\u539F\u6709\u63D2\u4EF6, federation(fulgurjsConfig) ]
+//
+// CLI\uFF08\u7EAF\u672C\u5730\uFF0C\u65E0\u7F51\u7EDC\uFF09\uFF1A
+//   npx fulgurjs explain                      # \u89E3\u91CA\u672C\u5E94\u7528\u6709\u6548\u5F62\u6001\u4E0E\u52A0\u8F7D\u94FE
+//   npx fulgurjs check-pages                  # \u5BBF\u4E3B\u9875\u9762\u8868 \u2194 \u8FDC\u7A0B manifest \u5951\u7EA6\u6838\u5BF9
+//   npx fulgurjs doctor --base http://<\u7AD9\u70B9> --apps <\u5BB9\u5668\u540D>   # \u90E8\u7F72\u4F53\u68C0
+import type { FederationOptions } from '@fulgurjs/federation'
 
-export default defineRepoConfig({
-  // \u5DE5\u7A0B\u6839\u76EE\u5F55\uFF08monorepo \u6839\u6216\u5355\u5E94\u7528\u4ED3\u5E93\u6839\uFF09
-  root: process.cwd(),
-  apps: [
-    // \u2500\u2500 \u5BBF\u4E3B\uFF1A\u6D88\u8D39\u8FDC\u7A0B\u9875\u9762/\u7EC4\u4EF6\uFF08\u4E5F\u53EF\u518D expose \u81EA\u5DF1\u7684\u7EC4\u4EF6\u7ED9\u66F4\u9AD8\u5C42\u6D88\u8D39\uFF09\u2500\u2500
-    {
-      path: 'apps/host',            // \u76F8\u5BF9 root \u7684\u5E94\u7528\u76EE\u5F55
-      name: 'host-app',             // \u8054\u90A6\u5BB9\u5668\u540D\uFF08\u8FDC\u7A0B\u5F15\u7528\u5B83\u65F6\u7528\u8FD9\u4E2A\u540D\uFF09
-      port: 5173,                   // dev \u7AEF\u53E3
-      base: '/',                    // \u90E8\u7F72/dev \u7684 URL \u524D\u7F00
-      host: {
-        // \u8DEF\u7531\u524D\u7F00 \u2192 \u8FDC\u7A0B\u540D\uFF1A\u5BBF\u4E3B\u628A /remote-a/** \u7684\u9875\u9762\u89E3\u6790\u5230\u8FDC\u7A0B remote-a
-        remotePrefixes: { '/remote-a/': 'remote-a' },
-        // \u8FDC\u7A0B\u5730\u5740\uFF1A\u88F8 URL\uFF08\u5BF9\u8C61\u5F62\u5F0F\u4E0D\u652F\u6301 name@ \u524D\u7F00\uFF0C\u89C1\u9519\u8BEF\u7801 CFG-007\uFF09
-        remotes: {
-          'remote-a': { dev: 'http://localhost:5174/remote-a', prod: '/remote-a' },
-        },
-        // \u9875\u9762\u8DEF\u7531\u8868\uFF1A\u5BBF\u4E3B\u8DEF\u5F84 \u2192 \u8FDC\u7A0B exposes \u952E\uFF08\u9ED8\u8BA4\u63A8\u5BFC pages/<\u53BB\u524D\u7F00\u53BB\u53C2\u6570\u6BB5>\uFF1B
-        // \u5E26\u53C2\u8DEF\u7531\u6216\u975E\u9ED8\u8BA4\u952E\u7528 spec \u663E\u5F0F\u8986\u76D6\uFF09
-        pages: [
-          { route: '/remote-a/home', name: 'RemoteAHome', title: '\u9996\u9875' },
-          { route: '/remote-a/detail/:id', name: 'RemoteADetail', spec: 'pages/remote-a/detail', title: '\u8BE6\u60C5' },
-        ],
-      },
-    },
-    // \u2500\u2500 \u8FDC\u7A0B\uFF1Aexpose \u72EC\u7ACB\u9875\uFF08\u9875\u9762\u81EA\u5DF1\u4ECE\u8DEF\u7531\u53D6\u53C2\uFF0C\u4E0D\u4F9D\u8D56\u7236\u7EC4\u4EF6\u4F20\u5FC5\u586B props\uFF0C\u89C1 BLD-003\uFF09\u2500\u2500
-    {
-      path: 'apps/remote-a',
-      name: 'remote-a',
-      port: 5174,
-      base: '/remote-a',
-      remote: {
-        exposes: {
-          './pages/remote-a/home': './src/views/Home.vue',
-          './pages/remote-a/detail': './src/views/Detail.vue',
-        },
-      },
-    },
-  ],
-  // \u90E8\u7F72\u4FE1\u606F\uFF08\u53EF\u9009\uFF09\uFF1A\u4EC5\u4F9B init \u8F93\u51FA NGINX \u6837\u677F\u65F6\u4F7F\u7528
-  deploy: { webRoot: '/var/www/your-site', listen: 8080 },
-})
+export default {
+  // \u8054\u90A6\u5BB9\u5668\u540D\uFF08\u8FDC\u7A0B\u5F15\u7528\u5B83\u65F6\u7528\u8FD9\u4E2A\u540D\uFF1B\u540C\u4E00\u9875\u9762\u5185\u552F\u4E00\uFF09
+  name: 'my-app',
+  // \u672C\u5E94\u7528\u5BF9\u5916\u66B4\u9732\u7684\u6A21\u5757\uFF1A'./\u952E' \u2192 \u76F8\u5BF9\u672C\u9879\u76EE\u6839\u7684\u6E90\u6587\u4EF6\u8DEF\u5F84
+  exposes: {
+    './pages/home': './src/views/Home.vue',
+  },
+  // \u672C\u5E94\u7528\u6D88\u8D39\u7684\u8FDC\u7A0B\uFF08\u952E = import \u524D\u7F00\uFF1Bdev/prod \u5730\u5740\u4E8C\u6BB5\u5F0F\uFF0C\u5355\u5730\u5740\u5B57\u7B26\u4E32\u4E5F\u884C\uFF09
+  remotes: {
+    'remote-a': { dev: 'http://localhost:5174/remote-a', prod: '/remote-a' },
+  },
+  // \u53EF\u9009\uFF1A\u8FDC\u7A0B\u9700\u8981\u542F\u52A8\u671F\u521D\u59CB\u5316\uFF08\u5168\u5C40\u6837\u5F0F/\u7EC4\u4EF6/locale\uFF09\u65F6\u58F0\u660E\u5165\u53E3\u6587\u4EF6\u2014\u2014
+  // \u9ED8\u8BA4\u5BFC\u51FA setup(context) \u5E94\u7528\u7EA7\u6267\u884C\u4E00\u6B21\uFF1B\u53EF\u9009\u5177\u540D\u5BFC\u51FA onSession(context)
+  // \u6309\u5BBF\u4E3B sessionKey \u53BB\u91CD\u6267\u884C\u3002\u7F3A\u7701 = \u65E0\u521D\u59CB\u5316\u884C\u4E3A\uFF08\u666E\u901A expose \u8BED\u4E49\u4E0D\u53D8\uFF09
+  // setup: './src/fulgurjs/setup.ts',
+  shared: {
+    vue: { singleton: true, requiredVersion: '^3.4.0' },
+    'vue-router': { singleton: true, requiredVersion: '^4.4.5' },
+    pinia: { singleton: true, requiredVersion: '^2.1.7' },
+  },
+} satisfies FederationOptions
+
+// \u2500\u2500 \u4EE5\u4E0B\u4EC5\u4F9B CLI explain/check-pages \u8BFB\u53D6\uFF08\u4E0D\u662F federation() \u7684\u53C2\u6570\uFF09\u2500\u2500
+// \u5BBF\u4E3B\u5E94\u7528\uFF1A\u628A\u9875\u9762\u8DEF\u7531\u8868\u4EE5\u5177\u540D\u5BFC\u51FA hostPages \u63D0\u4F9B\u7ED9 CLI\uFF0C\u4E0E\u8FD0\u884C\u65F6 createHostPages
+// \u6D88\u8D39\u540C\u4E00\u4EFD\u6570\u636E\u6A21\u5757\uFF08\u552F\u4E00\u624B\u5DE5\u7EF4\u62A4\u4F4D\u7F6E\uFF1B\u7EAF\u8FDC\u7A0B\u5E94\u7528\u5220\u9664\u672C\u6BB5\u5373\u53EF\uFF09\u3002
+// \u7EAF\u6570\u636E\u6A21\u5757\u793A\u4F8B src/fulgurjs/host/pages.data.ts\uFF1A
+//   export const remotePrefixes = { '/remote-a/': 'remote-a' }
+//   export const pages = [{ route: '/remote-a/home', name: 'Home', title: '\u9996\u9875' }]
+// import { pages, remotePrefixes } from './src/fulgurjs/host/pages.data'
+// export const hostPages = { pages, remotePrefixes }
 `;
-    DEFAULT_SHARED_BLOCK = `shared: {
-          vue: { singleton: true, requiredVersion: '^3.4.0' },
-          'vue-router': { singleton: true, requiredVersion: '^4.4.5' },
-          pinia: { singleton: true, requiredVersion: '^2.1.7' },
-        }`;
+    COMMON_CHECKLIST = [
+      "1. \u5B89\u88C5\u4F9D\u8D56\uFF1Anpm/pnpm add @fulgurjs/federation",
+      "2. expose \u4E00\u5F8B\u6307\u5411\u72EC\u7ACB\u9875\uFF08\u9875\u9762\u4ECE\u8DEF\u7531\u53D6\u53C2\uFF09\uFF1B\u7EC4\u4EF6\u9700\u8981\u5FC5\u586B props \u65F6\u7ED9\u9ED8\u8BA4\u503C\uFF08BLD-003\uFF09",
+      "3. shared \u91CC vue / vue-router / pinia \u5EFA\u8BAE singleton: true\u2014\u2014\u8DE8\u5E94\u7528\u5FC5\u987B\u540C\u5B9E\u4F8B\uFF08\u5168\u5C40\u54CD\u5E94\u6027\u3001getActivePinia\u3001\u8DEF\u7531\u6CE8\u5165\uFF09",
+      "4. \u8FDC\u7A0B\u9700\u8981\u542F\u52A8\u671F\u521D\u59CB\u5316\uFF08\u5168\u5C40\u7EC4\u4EF6/\u6837\u5F0F/locale \u7B49\uFF09\u65F6\uFF0C\u5728 fulgurjs.config.ts \u7684 setup \u58F0\u660E\u5165\u53E3\u6587\u4EF6\uFF1A",
+      "   \u9ED8\u8BA4\u5BFC\u51FA setup(context) \u5E94\u7528\u7EA7\u6267\u884C\u4E00\u6B21\uFF08\u5BB9\u5668\u9996\u6B21\u88AB\u52A0\u8F7D\u4E1A\u52A1\u6A21\u5757\u524D\uFF09\uFF1B\u53EF\u9009\u5177\u540D\u5BFC\u51FA onSession(context)",
+      "   \u6309\u5BBF\u4E3B sessionKey \u53BB\u91CD\u6267\u884C\uFF08\u6362\u8D26\u53F7/\u91CD\u767B\u81EA\u52A8\u91CD\u8DD1\uFF09\u3002\u5BBF\u4E3B\u65E0\u9700\u518D\u624B\u5199\u300CloadRemote \u542F\u52A8\u5668\u5E76\u8C03\u7528\u300D\uFF1B",
+      "   \u8DE8\u5E94\u7528\u4F20\u503C\u7EDF\u4E00\u8D70 @fulgurjs/federation/runtime \u7684 context \u51FD\u6570\uFF1A\u5BBF\u4E3B provideAppContext \u5199\u5165",
+      "   \uFF08\u9000\u51FA\u65F6 clearAppContext \u6E05\u7406\uFF09\uFF0C\u8FDC\u7A0B setup/onSession \u7528 getAppContext / requireAppContext \u6D88\u8D39",
+      "5. \u5E94\u7528\u4EE3\u7801\u552F\u4E00 API \u5165\u53E3\uFF1Aimport { loadRemote, provideAppContext, getAppContext, clearAppContext, definePages, createHostPages, remoteSchema, remoteComponent } from '@fulgurjs/federation/runtime'",
+      '6. dev \u51B7\u542F\u52A8\u9996\u8F6E 30~60s \u6709\u9884\u6784\u5EFA\u7A97\u53E3\uFF08\u77AC\u65F6 504/"ce"\uFF0CDEV-010\uFF09\uFF1A\u5148\u771F\u5B9E\u6253\u5F00\u9875\u9762\u9884\u70ED\u518D\u505A\u65AD\u8A00',
+      "7. \u914D\u7F6E\u89E3\u91CA\uFF1Afulgurjs explain\uFF08\u5355\u9879\u76EE\u5F62\u6001\u514D --app\uFF09\uFF1B\u9875\u9762\u5951\u7EA6\u6838\u5BF9\uFF1Afulgurjs check-pages\uFF08\u5BBF\u4E3B\u9879\u76EE\u8FD0\u884C\uFF0C--manifest/--site \u6307\u5B9A\u8FDC\u7A0B manifest \u6765\u6E90\uFF09\uFF1B",
+      "   \u90E8\u7F72\u4F53\u68C0\uFF1Afulgurjs doctor --base <URL> --apps <\u5BB9\u5668\u540D...>",
+      "8. \u90E8\u7F72\u8BED\u4E49\uFF1AremoteEntry/manifest/index.html \u5FC5\u987B no-cache\uFF08\u4E25\u7981 immutable\uFF09\uFF1B\u5E26 hash \u7684 assets \u957F\u7F13\u5B58"
+    ];
   }
 });
 
-// src/cli.ts
-import { resolve } from "node:path";
-
-// src/doctor.ts
-import http from "node:http";
-import https from "node:https";
+// src/pages.ts
+function defaultDeriveSpec(route) {
+  return segs(route).slice(1).filter((seg) => !seg.startsWith(":")).join("/");
+}
+function shadows(earlier, later) {
+  const a = segs(earlier);
+  const b = segs(later);
+  if (a.length !== b.length) return null;
+  if (earlier === later) return "full";
+  let hasParam2 = false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] === b[i]) continue;
+    if (a[i].startsWith(":")) {
+      hasParam2 = true;
+      continue;
+    }
+    return null;
+  }
+  return hasParam2 ? "param" : null;
+}
+function remoteOfRoute(route, remotes) {
+  if (!remotes) return null;
+  for (const [prefix, name] of Object.entries(remotes)) {
+    if (route === prefix.replace(/\/+$/, "") || route.startsWith(prefix)) return name;
+  }
+  return null;
+}
+function validatePages(pages, options = {}) {
+  const deriveSpec = options.deriveSpec ?? defaultDeriveSpec;
+  const violations = [];
+  const effective = pages.map((p) => normSpec(p.spec ?? deriveSpec(p.route)));
+  pages.forEach((p, i) => {
+    if (p.spec || !hasParam(p.route)) return;
+    pages.forEach((q, j) => {
+      if (i === j) return;
+      if (effective[j] !== effective[i]) return;
+      violations.push({
+        rule: "R1",
+        level: "error",
+        message: `[R1] \u8DEF\u7531 "${p.route}" \u5265\u53C2\u63A8\u5BFC spec "${effective[i]}" \u4E0E\u8DEF\u7531 "${q.route}"${q.spec ? "\uFF08\u663E\u5F0F spec\uFF09" : ""}\u6536\u655B\u76F8\u540C\u3002
+   \u6839\u56E0\uFF1A\u53C2\u6570\u6BB5\u5265\u79BB\u540E expose \u952E\u4E0E\u5176\u5B83\u6761\u76EE\u76F8\u540C\uFF0C\u8BE5\u8DEF\u7531\u4F1A\u9759\u9ED8\u52A0\u8F7D\u9519\u8BEF\u7EC4\u4EF6
+   \uFF08\u771F\u5B9E\u4E8B\u6545\uFF1A\u5E26\u53C2\u52A8\u4F5C\u9875\u8BEF\u8D70\u5217\u8868/\u66F4\u65B0\u8BED\u4E49\uFF0C\u6570\u636E\u98CE\u9669\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u4E3A\u8BE5\u6761\u76EE\u663E\u5F0F\u58F0\u660E spec: '...'\uFF08\u6307\u5411\u5E26\u53C2\u9875\u9762\u81EA\u5DF1\u7684 expose\uFF09\uFF0C\u6216\u8C03\u6574\u8DEF\u7531\u62C6\u5206\u3002`
+      });
+    });
+  });
+  const seenSpec = /* @__PURE__ */ new Map();
+  pages.forEach((p, i) => {
+    const key = effective[i];
+    if (seenSpec.has(key)) {
+      const first = pages[seenSpec.get(key)];
+      const bothExplicit = !!p.spec && !!first.spec;
+      violations.push({
+        rule: "R2",
+        level: "warn",
+        message: `[R2] \u8DEF\u7531 "${p.route}" \u4E0E "${first.route}" \u6709\u6548 spec \u76F8\u540C\uFF08"${key}"\uFF09\u3002${bothExplicit ? "\u4E24\u6761\u5747\u4E3A\u663E\u5F0F spec" : "\u5176\u4E2D\u542B\u63A8\u5BFC spec"}\u2014\u2014\u82E5\u4E3A\u523B\u610F\u7684\u83DC\u5355\u522B\u540D\u53EF\u5FFD\u7565\u672C\u8B66\u544A\uFF0C\u5426\u5219\u8BF7\u6838\u5BF9\u3002`
+      });
+    } else {
+      seenSpec.set(key, i);
+    }
+  });
+  if (options.schema && options.remotes) {
+    pages.forEach((p, i) => {
+      const remote = remoteOfRoute(p.route, options.remotes);
+      if (!remote) return;
+      const entry = options.schema[remote];
+      if (!entry || entry.exists === false) return;
+      const exposes = new Set((entry.exposes ?? []).map(normSpec));
+      if (!exposes.has(effective[i])) {
+        violations.push({
+          rule: "R3",
+          level: "error",
+          message: `[R3] \u8DEF\u7531 "${p.route}" \u7684 spec "${effective[i]}" \u4E0D\u5728\u8FDC\u7A0B "${remote}" \u7684 exposes \u6E05\u5355\u4E2D\u3002
+   \u6839\u56E0\uFF1Aspec \u62FC\u5199\u4E0E\u8FDC\u7A0B exposes \u952E\u4E0D\u4E00\u81F4\uFF08\u8FD0\u884C\u65F6\u5C06 MFU-006 \u52A0\u8F7D\u5931\u8D25\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u6838\u5BF9\u8FDC\u7A0B vite.config exposes \u952E\u540D\uFF0C\u6216\u4FEE\u6B63\u672C\u8868 spec\u3002
+   \u8FDC\u7A0B\u5B9E\u9645 exposes\uFF08\u524D 10\uFF09\uFF1A${[...exposes].slice(0, 10).join("\u3001") || "\uFF08\u7A7A\uFF09"}`
+        });
+      }
+    });
+  }
+  pages.forEach((p, i) => {
+    pages.forEach((q, j) => {
+      if (j <= i) return;
+      const kind = shadows(p.route, q.route);
+      if (!kind) return;
+      violations.push({
+        rule: "R4",
+        level: "error",
+        message: kind === "full" ? `[R4] \u8DEF\u7531\u5B8C\u5168\u91CD\u590D\uFF1A"${p.route}"\uFF08\u7B2C ${i + 1} \u6761\uFF09\u4E0E "${q.route}"\uFF08\u7B2C ${j + 1} \u6761\uFF09\u3002` : `[R4] \u8DEF\u7531 "${q.route}"\uFF08\u7B2C ${j + 1} \u6761\uFF09\u4F1A\u88AB\u66F4\u9760\u524D\u7684 "${p.route}" \u906E\u853D\uFF08\u5339\u914D\u5148\u5230\u5148\u5F97\uFF0C\u540E\u8005\u6210\u6B7B\u8DEF\u7531\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u8C03\u6574\u6570\u7EC4\u987A\u5E8F\uFF08\u66F4\u5177\u4F53\u7684\u9759\u6001\u8DEF\u7531\u653E\u524D\u9762\uFF09\u6216\u5408\u5E76\u6761\u76EE\u3002`
+      });
+    });
+  });
+  const seenName = /* @__PURE__ */ new Map();
+  pages.forEach((p, i) => {
+    const name = typeof p.name === "string" ? p.name : "";
+    if (!name) return;
+    if (seenName.has(name)) {
+      violations.push({
+        rule: "R5",
+        level: "warn",
+        message: `[R5] name "${name}" \u91CD\u590D\uFF08"${pages[seenName.get(name)].route}" \u4E0E "${p.route}"\uFF09\u2014\u2014vue-router \u547D\u540D\u8DF3\u8F6C push({name}) \u5C06\u547D\u4E2D\u524D\u8005\uFF0C\u8BF7\u6838\u5BF9\u3002`
+      });
+    } else {
+      seenName.set(name, i);
+    }
+  });
+  return violations;
+}
+var normSpec, hasParam, segs;
+var init_pages = __esm({
+  "src/pages.ts"() {
+    "use strict";
+    normSpec = (s) => s.replace(/^[./]+/, "").replace(/\/+$/, "");
+    hasParam = (route) => /(^|\/):[\w]+/.test(route);
+    segs = (route) => route.split("/").filter(Boolean);
+  }
+});
 
-// src/manifest.ts
-var MANIFEST_SCHEMA_VERSION = 1;
-var isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-function validAssetRef(v) {
-  if (typeof v !== "string" || v.length === 0) return false;
-  if (/[\s\u0000-\u001f]/.test(v)) return false;
-  if (/^https?:\/\/[^/@\s]+:[^/@\s]+@/.test(v)) return false;
-  return true;
+// src/commands.ts
+var commands_exports = {};
+__export(commands_exports, {
+  checkPages: () => checkPages,
+  explainApp: () => explainApp,
+  formatCheckPages: () => formatCheckPages,
+  formatExplain: () => formatExplain
+});
+import fs2 from "node:fs";
+import path2 from "node:path";
+function roleOf(app) {
+  if (app.host && app.remote) return "dual";
+  return app.host ? "host" : "remote";
 }
-function validExposeName(v) {
-  return typeof v === "string" && /^\.[\w./-]+$/.test(v);
+function pageMappings(app) {
+  const pages = app.host?.pages ?? [];
+  const prefixes = Object.entries(app.host?.remotePrefixes ?? {}).sort((a, b) => b[0].length - a[0].length);
+  const remoteOf = (route) => {
+    for (const [prefix, name] of prefixes) {
+      const p = prefix.endsWith("/") ? prefix : `${prefix}/`;
+      if (route.startsWith(p) || `${route}/` === p) return name;
+    }
+    return null;
+  };
+  const derive = app.host?.deriveSpec ?? ((route) => route.split("/").filter(Boolean).slice(1).filter((s) => !s.startsWith(":")).join("/"));
+  return mappingsOf({ pages, remotePrefixes: app.host?.remotePrefixes ?? {}, deriveSpec: app.host?.deriveSpec }, derive);
 }
-function parseManifest(input) {
-  const issues = [];
-  if (!isPlainObject(input)) {
-    return { issues: [{ field: "$", message: "manifest \u5FC5\u987B\u662F JSON \u5BF9\u8C61", got: typeof input }] };
+function mappingsOf(hp, deriveFallback) {
+  const pages = hp.pages ?? [];
+  const prefixes = Object.entries(hp.remotePrefixes ?? {}).sort((a, b) => b[0].length - a[0].length);
+  const remoteOf = (route) => {
+    for (const [prefix, name] of prefixes) {
+      const p = prefix.endsWith("/") ? prefix : `${prefix}/`;
+      if (route.startsWith(p) || `${route}/` === p) return name;
+    }
+    return null;
+  };
+  const derive = hp.deriveSpec ?? deriveFallback;
+  const out = [];
+  for (const page of pages) {
+    const remote = remoteOf(page.route);
+    if (!remote) continue;
+    const spec = `${remote}/${String(page.spec ?? derive(page.route)).replace(/^[./]+/, "")}`;
+    out.push({ route: page.route, remote, spec, title: typeof page.title === "string" ? page.title : void 0 });
   }
-  const m = input;
-  let schemaVersion = MANIFEST_SCHEMA_VERSION;
-  if (m.schemaVersion !== void 0) {
-    if (typeof m.schemaVersion !== "number" || !Number.isInteger(m.schemaVersion)) {
-      issues.push({ field: "schemaVersion", message: "\u5FC5\u987B\u662F\u6574\u6570", got: m.schemaVersion });
-    } else if (m.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
-      return {
-        issues: [
-          {
-            field: "schemaVersion",
-            message: `\u4E0D\u652F\u6301\u7684 manifest \u4E3B\u7248\u672C\uFF08\u5F53\u524D\u6D88\u8D39\u7AEF\u652F\u6301 ${MANIFEST_SCHEMA_VERSION}\uFF09`,
-            got: m.schemaVersion
-          }
-        ],
-        unsupportedVersion: m.schemaVersion
-      };
+  return out;
+}
+function remotesOfOptions(options) {
+  return Object.entries(options.remotes ?? {}).map(([key, v]) => {
+    const cfg = typeof v === "string" ? { external: v } : v;
+    return { key, dev: String(cfg.dev ?? cfg.external ?? ""), prod: String(cfg.prod ?? cfg.external ?? "") };
+  });
+}
+function sharedOfOptions(options) {
+  const shared = options.shared;
+  if (!shared) return [];
+  if (Array.isArray(shared)) {
+    return shared.map((name) => ({ name, singleton: false, requiredVersion: false }));
+  }
+  return Object.entries(shared).map(([name, v]) => {
+    const hint = typeof v === "string" ? { requiredVersion: v } : v ?? {};
+    return {
+      name,
+      singleton: !!hint.singleton,
+      requiredVersion: hint.requiredVersion ?? false
+    };
+  });
+}
+function chainLines(options, role) {
+  const chain = [];
+  chain.push(role === "remote" ? "\u88AB\u5BBF\u4E3B\u6D88\u8D39\uFF1AremoteEntry/\u5171\u4EAB\u4F9D\u8D56\u52A0\u8F7D \u2192 \u5BBF\u4E3B\u9996\u6B21 loadRemote \u672C\u5E94\u7528\u6A21\u5757\u65F6\u6267\u884C\u53EF\u9009 setup/onSession \u2192 \u9875\u9762\u6A21\u5757\u5728\u5BBF\u4E3B\u5E03\u5C40\u5185\u6E32\u67D3" : "\u5BBF\u4E3B\u63D0\u4F9B AppContext\uFF08provideAppContext\uFF0C\u542B sessionKey\uFF09\u2192 \u52A0\u8F7D remoteEntry/\u5171\u4EAB\u4F9D\u8D56 \u2192 \u9996\u6B21 loadRemote \u6267\u884C\u8BE5\u8FDC\u7A0B\u53EF\u9009 setup/onSession \u2192 \u53D6\u5F97\u9875\u9762\u6A21\u5757 \u2192 \u5BBF\u4E3B\u5E03\u5C40\u6E32\u67D3");
+  if (options.setup) {
+    chain.push(`setup \u5165\u53E3 ${options.setup}\uFF1A\u9ED8\u8BA4\u5BFC\u51FA\u5E94\u7528\u7EA7\u6267\u884C\u4E00\u6B21\uFF1BonSession \u6309\u5BBF\u4E3B sessionKey \u53BB\u91CD\uFF08\u7F3A sessionKey \u65F6\u62A5 MFU-013\uFF09`);
+  } else {
+    chain.push("\u672C\u5E94\u7528\u672A\u914D\u7F6E setup\uFF1A\u65E0\u521D\u59CB\u5316\u751F\u547D\u5468\u671F\uFF0CloadRemote \u76F4\u63A5\u8FD4\u56DE\u6A21\u5757\uFF08\u666E\u901A expose \u8BED\u4E49\uFF09");
+  }
+  return chain;
+}
+function explainAppMode(loaded, appName) {
+  const options = loaded.options;
+  if (appName && appName !== options.name) {
+    throw new Error(
+      `[fulgurjs:explain] \u5355\u9879\u76EE\u914D\u7F6E\u53EA\u63CF\u8FF0\u672C\u5E94\u7528\uFF08name: "${options.name}"\uFF09\uFF0C\u4E0E --app "${appName}" \u4E0D\u4E00\u81F4
+  \u4FEE\u6CD5: \u53BB\u6389 --app\uFF0C\u6216\u6539\u4E3A --app ${options.name}`
+    );
+  }
+  const role = roleOfOptions(options);
+  const devSharedSelfExplicit = options.devSharedSelf !== void 0;
+  const devSharedSelfValue = devSharedSelfExplicit ? options.devSharedSelf === true : role !== "host";
+  const hp = loaded.hostPages;
+  return {
+    app: options.name,
+    role,
+    mode: "app",
+    path: loaded.appRoot,
+    remotes: remotesOfOptions(options),
+    exposes: Object.keys(options.exposes ?? {}),
+    setup: options.setup,
+    shared: sharedOfOptions(options),
+    devSharedSelf: { value: devSharedSelfValue, source: devSharedSelfExplicit ? "explicit" : "inferred" },
+    pages: hp ? mappingsOf(hp, DEFAULT_DERIVE) : [],
+    pagesSource: hp ? `fulgurjs.config.ts \u7684 hostPages \u5177\u540D\u5BFC\u51FA\uFF08${hp.pages.length} \u6761\uFF1B\u8FD0\u884C\u65F6\u771F\u6E90\u4E3A\u5E94\u7528\u5185\u540C\u4E00\u6570\u636E\u6A21\u5757\uFF09` : "\u672A\u627E\u5230 hostPages \u5177\u540D\u5BFC\u51FA\uFF08\u7EAF\u8FDC\u7A0B\u5E94\u7528\u65E0\u9700\u9875\u9762\u8868\uFF1B\u5BBF\u4E3B\u82E5\u8981\u8DD1 check-pages \u8BF7\u5728 fulgurjs.config.ts \u8865\u5177\u540D\u5BFC\u51FA hostPages\uFF09",
+    chain: chainLines(options, role)
+  };
+}
+function explainRepoMode(cfg, appPathOrName) {
+  const app = cfg.apps.find((a) => a.path === appPathOrName || a.name === appPathOrName);
+  if (!app) {
+    throw new Error(
+      `[fulgurjs:explain] \u5E94\u7528 "${appPathOrName}" \u4E0D\u5728\u914D\u7F6E\u4E2D\uFF08\u53EF\u7528\uFF1A${cfg.apps.map((a) => a.path).join("\u3001")}\uFF09`
+    );
+  }
+  const opts = federationOptionsForApp(cfg, appPathOrName);
+  const remotes = Object.entries(opts.remotes ?? {}).map(
+    ([key, v]) => ({ key, dev: String(v.dev ?? v.external ?? ""), prod: String(v.prod ?? v.external ?? "") })
+  );
+  const shared = Object.entries(opts.shared ?? {}).map(
+    ([name, v]) => ({ name, singleton: !!v.singleton, requiredVersion: v.requiredVersion ?? false })
+  );
+  const chain = [];
+  chain.push(app.host ? "\u5BBF\u4E3B\u63D0\u4F9B AppContext\uFF08provideAppContext\uFF0C\u542B sessionKey\uFF09\u2192 \u52A0\u8F7D remoteEntry/\u5171\u4EAB\u4F9D\u8D56 \u2192 \u9996\u6B21 loadRemote \u6267\u884C\u8BE5\u8FDC\u7A0B\u53EF\u9009 setup/onSession \u2192 \u53D6\u5F97\u9875\u9762\u6A21\u5757 \u2192 \u5BBF\u4E3B\u5E03\u5C40\u6E32\u67D3" : "\u88AB\u5BBF\u4E3B\u6D88\u8D39\uFF1AremoteEntry/\u5171\u4EAB\u4F9D\u8D56\u52A0\u8F7D \u2192 \u5BBF\u4E3B\u9996\u6B21 loadRemote \u672C\u5E94\u7528\u6A21\u5757\u65F6\u6267\u884C\u53EF\u9009 setup/onSession \u2192 \u9875\u9762\u6A21\u5757\u5728\u5BBF\u4E3B\u5E03\u5C40\u5185\u6E32\u67D3");
+  if (app.remote?.setup) {
+    chain.push(`setup \u5165\u53E3 ${app.remote.setup}\uFF1A\u9ED8\u8BA4\u5BFC\u51FA\u5E94\u7528\u7EA7\u6267\u884C\u4E00\u6B21\uFF1B${"onSession"} \u6309\u5BBF\u4E3B sessionKey \u53BB\u91CD\uFF08\u7F3A sessionKey \u65F6\u62A5 MFU-013\uFF09`);
+  } else {
+    chain.push("\u672C\u5E94\u7528\u672A\u914D\u7F6E setup\uFF1A\u65E0\u521D\u59CB\u5316\u751F\u547D\u5468\u671F\uFF0CloadRemote \u76F4\u63A5\u8FD4\u56DE\u6A21\u5757\uFF08\u666E\u901A expose \u8BED\u4E49\uFF09");
+  }
+  return {
+    app: app.name,
+    role: roleOf(app),
+    mode: "repo",
+    path: app.path,
+    base: app.base,
+    port: app.port,
+    remotes,
+    exposes: Object.keys(app.remote?.exposes ?? {}),
+    setup: app.remote?.setup,
+    shared,
+    devSharedSelf: {
+      value: opts.devSharedSelf === true,
+      source: app.devSharedSelf === void 0 ? "inferred" : "explicit"
+    },
+    pages: pageMappings(app),
+    pagesSource: app.host?.pages ? "\u4ED3\u5E93\u914D\u7F6E host.pages \u526F\u672C\uFF08\u517C\u5BB9\u5F62\u6001\uFF1B\u5355\u9879\u76EE\u5F62\u6001\u8BF7\u6539\u7528 hostPages \u5177\u540D\u5BFC\u51FA\uFF09" : "\u4ED3\u5E93\u914D\u7F6E\u672A\u63D0\u4F9B\u9875\u9762\u8868\u2014\u2014\u5E94\u7528\u4EE3\u7801\u9875\u9762\u8868\u4E3A\u8FD0\u884C\u65F6\u771F\u6E90",
+    chain
+  };
+}
+async function explainApp(configPath, appName) {
+  const loaded = await loadAppConfig(configPath);
+  if (loaded.kind === "repo") {
+    if (!appName) {
+      throw new Error("[fulgurjs:explain] \u805A\u5408\u914D\u7F6E\u9700 --app <\u5E94\u7528\u76EE\u5F55\u540D\u6216\u5BB9\u5668\u540D>\uFF08\u5355\u9879\u76EE\u914D\u7F6E\u53EF\u7701\u7565\uFF09");
     }
+    return explainRepoMode(loaded.repo, appName);
   }
-  if (typeof m.name !== "string" || m.name.length === 0) {
-    issues.push({ field: "name", message: "\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32", got: m.name });
+  return explainAppMode(loaded, appName);
+}
+function formatExplain(r) {
+  const roleText = r.role === "dual" ? "\u5BBF\u4E3B+\u8FDC\u7A0B\uFF08\u53CC\u89D2\u8272\uFF09" : r.role === "host" ? "\u5BBF\u4E3B" : "\u8FDC\u7A0B";
+  const L = [];
+  if (r.mode === "app") {
+    L.push(`\u5E94\u7528 ${r.app}\uFF08${roleText}\uFF0C\u5355\u9879\u76EE\u914D\u7F6E\uFF0C\u76EE\u5F55 ${r.path}\uFF1Bbase/dev \u7AEF\u53E3\u7531 vite.config.ts \u7BA1\u7406\uFF09`);
+  } else {
+    L.push(`\u5E94\u7528 ${r.app}\uFF08${roleText}\uFF0C\u76EE\u5F55 ${r.path}\uFF0Cdev \u7AEF\u53E3 ${r.port}\uFF0Cbase ${r.base}\uFF09\u3010\u65E7\u805A\u5408\u914D\u7F6E\u5F62\u6001\uFF0C\u517C\u5BB9\u671F\u3011`);
   }
-  const exposes = m.exposes;
-  const shared = m.shared;
-  const sharedIssues = validateShared(shared);
-  issues.push(...sharedIssues);
-  if (Array.isArray(exposes)) {
-    if (m.devServer !== true) {
-      issues.push({ field: "devServer", message: "dev \u6570\u7EC4\u5F62\u6001 exposes \u5FC5\u987B\u4F34\u968F devServer: true", got: m.devServer });
+  if (r.remotes.length) {
+    L.push("\u6D88\u8D39\u8FDC\u7A0B\uFF1A");
+    for (const x of r.remotes) L.push(`  ${x.key} \u2192 dev ${x.dev} / prod ${x.prod}`);
+  } else {
+    L.push("\u6D88\u8D39\u8FDC\u7A0B\uFF1A\uFF08\u65E0\uFF09");
+  }
+  L.push(`\u516C\u5F00 exposes\uFF08${r.exposes.length}\uFF09\uFF1A${r.exposes.join("\u3001") || "\uFF08\u7A7A\uFF09"}`);
+  L.push(`\u5185\u90E8 setup\uFF1A${r.setup ?? "\uFF08\u672A\u914D\u7F6E\u2014\u2014\u65E0\u521D\u59CB\u5316\u751F\u547D\u5468\u671F\uFF09"}`);
+  if (r.shared.length) {
+    L.push("shared\uFF1A");
+    for (const s of r.shared) {
+      L.push(`  ${s.name}${s.singleton ? " [singleton]" : ""} requiredVersion=${String(s.requiredVersion)}`);
     }
-    if (typeof m.base !== "string" || !/^\/(?:.*\/)?$/.test(m.base)) {
-      issues.push({ field: "base", message: "\u5FC5\u987B\u662F\u4EE5 / \u5F00\u5934\u4E14 / \u7ED3\u5C3E\u7684\u8DEF\u5F84", got: m.base });
+  }
+  L.push(`devSharedSelf\uFF1A${r.devSharedSelf.value}\uFF08\u6765\u6E90\uFF1A${r.devSharedSelf.source === "explicit" ? "\u663E\u5F0F\u914D\u7F6E" : "\u6309\u89D2\u8272\u63A8\u65AD\u2014\u2014\u63D0\u4F9B exposes/setup \u7684\u5E94\u7528\u4E3A true\uFF0C\u7EAF\u5BBF\u4E3B\u4E3A false"}\uFF09`);
+  if (r.pages.length) {
+    L.push(`\u9875\u9762 spec \u6620\u5C04\uFF08${r.pages.length}\uFF09\u2014\u2014\u6765\u6E90\uFF1A${r.pagesSource}\uFF1A`);
+    for (const p of r.pages) L.push(`  ${p.route} \u2192 ${p.spec}${p.title ? `\uFF08${p.title}\uFF09` : ""}`);
+  } else {
+    L.push(`\u9875\u9762 spec \u6620\u5C04\uFF1A\uFF08\u65E0\uFF09\u2014\u2014\u6765\u6E90\uFF1A${r.pagesSource}`);
+  }
+  L.push("\u52A0\u8F7D\u94FE\uFF1A");
+  for (const c of r.chain) L.push(`  \xB7 ${c}`);
+  return L.join("\n");
+}
+function manifestFromFile(p) {
+  try {
+    const parsed = parseManifest(JSON.parse(fs2.readFileSync(p, "utf8")));
+    if (parsed.manifest && !parsed.unsupportedVersion) return parsed.manifest;
+  } catch {
+  }
+  return void 0;
+}
+async function manifestFromUrl(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
+    if (res.ok) {
+      const parsed = parseManifest(await res.json());
+      if (parsed.manifest && !parsed.unsupportedVersion) return parsed.manifest;
     }
-    if (!validAssetRef(m.entry)) {
-      issues.push({ field: "entry", message: "\u5FC5\u987B\u662F\u5408\u6CD5\u8D44\u6E90\u5730\u5740", got: m.entry });
+  } catch {
+  }
+  return void 0;
+}
+async function fetchRemoteManifestRepo(cfg, app, opts) {
+  const explicit = opts.manifests?.[app.name] ?? opts.manifests?.[app.path];
+  if (explicit) {
+    const fromUrl = /^https?:\/\//.test(explicit);
+    const got = fromUrl ? await manifestFromUrl(explicit) : manifestFromFile(explicit);
+    if (got) return { manifest: got, from: explicit };
+    return void 0;
+  }
+  const candidates = [app.deployDir || app.base.replace(/^\/|\/$/g, ""), "dist"];
+  for (const dir of candidates) {
+    const p = path2.join(cfg.root, app.path, dir, "fulgurjs-manifest.json");
+    const got = manifestFromFile(p);
+    if (got) return { manifest: got, from: p };
+  }
+  if (opts.site) {
+    const base = app.base === "/" ? "" : app.base.replace(/\/$/, "");
+    const url = `${opts.site.replace(/\/$/, "")}${base}/fulgurjs-manifest.json`;
+    const got = await manifestFromUrl(url);
+    if (got) return { manifest: got, from: url };
+  }
+  return void 0;
+}
+async function fetchRemoteManifestApp(loaded, options, remoteName, opts) {
+  const explicit = opts.manifests?.[remoteName];
+  if (explicit) {
+    const fromUrl = /^https?:\/\//.test(explicit);
+    const got = fromUrl ? await manifestFromUrl(explicit) : manifestFromFile(explicit);
+    if (got) return { manifest: got, from: explicit };
+    return void 0;
+  }
+  const remoteCfg = (options.remotes ?? {})[remoteName];
+  if (!remoteCfg) return void 0;
+  const cfg = typeof remoteCfg === "string" ? { external: remoteCfg } : remoteCfg;
+  const prodBase = cfg.prod ?? cfg.external ?? "";
+  if (!prodBase) return void 0;
+  if (/^https?:\/\//.test(prodBase)) {
+    const url = `${prodBase.replace(/\/$/, "")}/fulgurjs-manifest.json`;
+    const got = await manifestFromUrl(url);
+    if (got) return { manifest: got, from: url };
+    return void 0;
+  }
+  if (opts.site) {
+    const url = `${opts.site.replace(/\/$/, "")}${prodBase.startsWith("/") ? prodBase : `/${prodBase}`}/fulgurjs-manifest.json`;
+    const got = await manifestFromUrl(url);
+    if (got) return { manifest: got, from: url };
+  }
+  return void 0;
+}
+async function checkPagesApp(loaded, opts) {
+  const options = loaded.options;
+  const issues = [];
+  const hp = loaded.hostPages;
+  const pages = hp?.pages ?? [];
+  const prefixes = hp?.remotePrefixes ?? {};
+  if (pages.length === 0) {
+    issues.push({
+      level: "unverified",
+      message: "fulgurjs.config.ts \u672A\u63D0\u4F9B hostPages \u5177\u540D\u5BFC\u51FA\u2014\u2014\u65E0\u4ECE\u6838\u5BF9\u9875\u9762\u5951\u7EA6\uFF08\u7EAF\u8FDC\u7A0B\u5E94\u7528\u5C5E\u6B63\u5E38\uFF0C\u65E0\u9700\u9875\u9762\u8868\uFF09\u3002\n  \u4FEE\u6CD5: \u5BBF\u4E3B\u5E94\u7528\u5728 fulgurjs.config.ts \u52A0\u5177\u540D\u5BFC\u51FA hostPages = { pages, remotePrefixes, deriveSpec? }\uFF08\u4E0E\u8FD0\u884C\u65F6 createHostPages \u6D88\u8D39\u540C\u4E00\u4EFD\u6570\u636E\u6A21\u5757\uFF09"
+    });
+    return { app: options.name, checked: 0, issues, failed: false, unverifiedFailed: !!opts.requireVerified, manifestSources: [] };
+  }
+  const violations = validatePages(pages, { remotes: prefixes });
+  for (const v of violations) {
+    issues.push({ level: v.level === "error" ? "error" : "warn", message: v.message });
+  }
+  const remoteNames = [...new Set(Object.values(prefixes))];
+  const manifests = /* @__PURE__ */ new Map();
+  const sources = [];
+  for (const name of remoteNames) {
+    if (!options.remotes || !(name in options.remotes)) {
+      issues.push({ level: "error", message: `\u8DEF\u7531\u524D\u7F00\u6620\u5C04\u5230\u8FDC\u7A0B "${name}"\uFF0C\u4F46\u672C\u5E94\u7528 federation({ remotes }) \u672A\u6D88\u8D39\u5B83\u2014\u2014\u5BBF\u4E3B\u53EA\u6838\u5BF9\u5B83\u5B9E\u9645\u6D88\u8D39\u7684\u8FDC\u7A0B` });
+      continue;
     }
-    for (const [i, e] of exposes.entries()) {
-      if (!isPlainObject(e)) {
-        issues.push({ field: `exposes[${i}]`, message: "\u5FC5\u987B\u662F\u5BF9\u8C61", got: typeof e });
-        continue;
-      }
-      if (!validExposeName(e.name)) {
-        issues.push({ field: `exposes[${i}].name`, message: '\u5FC5\u987B\u662F "./xxx" \u5F62\u6001\u7684 expose \u540D', got: e.name });
-      }
-      if (typeof e.src !== "string" || e.src.length === 0) {
-        issues.push({ field: `exposes[${i}].src`, message: "dev \u5F62\u6001\u5FC5\u987B\u63D0\u4F9B\u6E90\u7801\u76F8\u5BF9\u8DEF\u5F84", got: e.src });
-      }
-      if (!validAssetRef(e.file)) {
-        issues.push({ field: `exposes[${i}].file`, message: "\u5FC5\u987B\u662F\u53EF\u8BF7\u6C42\u7684\u6A21\u5757\u5730\u5740", got: e.file });
-      }
+    const got = await fetchRemoteManifestApp(loaded, options, name, opts);
+    if (!got) {
+      const how = opts.manifests?.[name] ? `--manifest ${name}=${opts.manifests[name]} \u4E0D\u53EF\u8FBE\u6216\u975E\u6709\u6548 manifest` : opts.site ? `\u6309 remotes prod \u5730\u5740\u4E0E --site ${opts.site} \u63A8\u5BFC\u7684 manifest URL \u4E0D\u53EF\u8FBE` : "\u672A\u63D0\u4F9B manifest \u6765\u6E90";
+      issues.push({
+        level: "unverified",
+        message: `\u8FDC\u7A0B "${name}" \u7684 manifest \u4E0D\u53EF\u5F97\uFF08${how}\uFF09\u2014\u2014\u8BE5\u8FDC\u7A0B\u7684 spec \u5B58\u5728\u6027\u65E0\u6CD5\u6838\u5BF9\u3002
+  \u4FEE\u6CD5: --manifest ${name}=<\u5DF2\u6784\u5EFA\u4EA7\u7269\u8DEF\u5F84\u6216 https://\u2026/fulgurjs-manifest.json>\uFF0C\u6216 --site <\u90E8\u7F72\u7AD9\u70B9>\uFF08\u6309 prod \u5730\u5740\u63A8\u5BFC\uFF09`
+      });
+      continue;
     }
-  } else if (isPlainObject(exposes)) {
-    if (!validAssetRef(m.entry)) {
-      issues.push({ field: "entry", message: "\u5FC5\u987B\u662F\u5408\u6CD5\u8D44\u6E90\u5730\u5740\uFF08\u76F8\u5BF9\u57FA\u51C6 = \u6240\u5728\u76EE\u5F55\uFF09", got: m.entry });
+    manifests.set(name, { exposes: new Set([...normalizeExposes(got.manifest).keys()].map(normSpecKey)), from: got.from });
+    sources.push({ remote: name, from: got.from });
+  }
+  const derive = hp?.deriveSpec ?? DEFAULT_DERIVE;
+  let checked = 0;
+  for (const page of pages) {
+    const prefixHit = Object.entries(prefixes).sort((a, b) => b[0].length - a[0].length).find(
+      ([p]) => page.route.startsWith(p.endsWith("/") ? p : `${p}/`) || `${page.route}/` === (p.endsWith("/") ? p : `${p}/`)
+    );
+    if (!prefixHit) {
+      issues.push({ level: "error", message: `\u8DEF\u7531 "${page.route}" \u4E0D\u5728\u4EFB\u4F55 remotePrefixes \u524D\u7F00\u4E0B` });
+      continue;
     }
-    for (const [key, v] of Object.entries(exposes)) {
-      if (!validExposeName(key)) {
-        issues.push({ field: `exposes["${key}"]`, message: '\u952E\u5FC5\u987B\u662F "./xxx" \u5F62\u6001\u7684 expose \u540D' });
-      }
-      if (!isPlainObject(v)) {
-        issues.push({ field: `exposes["${key}"]`, message: "\u503C\u5FC5\u987B\u662F\u5BF9\u8C61", got: typeof v });
-        continue;
-      }
-      if (!validAssetRef(v.file)) {
-        issues.push({ field: `exposes["${key}"].file`, message: "\u5FC5\u987B\u662F\u8D44\u6E90\u8DEF\u5F84\uFF08\u76F8\u5BF9 entry \u76EE\u5F55\uFF09", got: v.file });
-      }
-      if (v.css !== void 0) {
-        if (!Array.isArray(v.css)) {
-          issues.push({ field: `exposes["${key}"].css`, message: "\u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u6570\u7EC4", got: typeof v.css });
-        } else {
-          v.css.forEach((css, i) => {
-            if (!validAssetRef(css)) {
-              issues.push({ field: `exposes["${key}"].css[${i}]`, message: "\u5FC5\u987B\u662F\u8D44\u6E90\u8DEF\u5F84", got: css });
-            }
-          });
-        }
-      }
+    checked++;
+    const m = manifests.get(prefixHit[1]);
+    if (!m) continue;
+    const spec = normSpecKey(String(page.spec ?? derive(page.route)));
+    if (!m.exposes.has(spec)) {
+      issues.push({
+        level: "error",
+        message: `\u8DEF\u7531 "${page.route}" \u7684 spec "${spec}" \u4E0D\u5728\u8FDC\u7A0B "${prefixHit[1]}" \u7684 exposes \u6E05\u5355\u4E2D\uFF08\u6765\u6E90 ${m.from}\uFF09\u3002
+  \u8FDC\u7A0B\u5B9E\u9645 exposes\uFF08\u524D 10\uFF09\uFF1A${[...m.exposes].slice(0, 10).join("\u3001") || "\uFF08\u7A7A\uFF09"}
+  \u4FEE\u6CD5: \u6838\u5BF9\u8FDC\u7A0B federation({ exposes }) \u952E\u540D\u6216\u4FEE\u6B63\u9875\u9762\u8868 spec`
+      });
     }
-  } else {
-    issues.push({ field: "exposes", message: "\u5FC5\u987B\u662F\u6570\u7EC4\uFF08dev\uFF09\u6216\u5BF9\u8C61\uFF08prod\uFF09", got: typeof exposes });
   }
-  if (issues.length > 0) return { issues };
-  return { manifest: input, issues };
+  const failed = issues.some((i) => i.level === "error");
+  return { app: options.name, checked, issues, failed, unverifiedFailed: !!opts.requireVerified, manifestSources: sources };
 }
-function validateShared(shared) {
-  if (shared === void 0) return [];
+async function checkPagesRepo(cfg, appPathOrName, opts) {
+  const app = cfg.apps.find((a) => a.path === appPathOrName || a.name === appPathOrName);
+  if (!app) {
+    throw new Error(`[fulgurjs:check-pages] \u5E94\u7528 "${appPathOrName}" \u4E0D\u5728\u914D\u7F6E\u4E2D\uFF08\u53EF\u7528\uFF1A${cfg.apps.map((a) => a.path).join("\u3001")}\uFF09`);
+  }
   const issues = [];
-  if (!Array.isArray(shared)) {
-    return [{ field: "shared", message: "\u5FC5\u987B\u662F\u6570\u7EC4", got: typeof shared }];
+  const pages = app.host?.pages ?? [];
+  const prefixes = app.host?.remotePrefixes ?? {};
+  if (pages.length === 0) {
+    issues.push({
+      level: "unverified",
+      message: "\u4ED3\u5E93\u914D\u7F6E\u672A\u63D0\u4F9B\u9875\u9762\u8868\uFF08pages \u53EF\u9009\uFF0C\u5E94\u7528\u4EE3\u7801\u9875\u9762\u8868\u4E3A\u8FD0\u884C\u65F6\u771F\u6E90\uFF09\u2014\u2014\u672C\u547D\u4EE4\u65E0\u4ECE\u6838\u5BF9\u3002\n  \u4FEE\u6CD5: \u5728 fulgurjs.config.ts \u5BBF\u4E3B host.pages \u63D0\u4F9B\u9875\u9762\u8868\u526F\u672C\uFF0C\u6216\u4F9D\u8D56 dev \u671F remoteSchema \u63A2\u9488\u6821\u9A8C"
+    });
+    return { app: app.name, checked: 0, issues, failed: false, unverifiedFailed: !!opts.requireVerified, manifestSources: [] };
   }
-  for (const [i, s] of shared.entries()) {
-    if (!isPlainObject(s)) {
-      issues.push({ field: `shared[${i}]`, message: "\u5FC5\u987B\u662F\u5BF9\u8C61", got: typeof s });
+  const violations = validatePages(pages, { remotes: prefixes });
+  for (const v of violations) {
+    issues.push({ level: v.level === "error" ? "error" : "warn", message: v.message });
+  }
+  const remoteNames = [...new Set(Object.values(prefixes))];
+  const manifests = /* @__PURE__ */ new Map();
+  const sources = [];
+  for (const name of remoteNames) {
+    const remoteApp = cfg.apps.find((a) => a.name === name);
+    if (!remoteApp) {
+      issues.push({ level: "error", message: `\u8DEF\u7531\u524D\u7F00\u6620\u5C04\u5230\u672A\u77E5\u8FDC\u7A0B "${name}"\u2014\u2014\u914D\u7F6E apps \u4E2D\u4E0D\u5B58\u5728\u8BE5\u5BB9\u5668\u540D` });
       continue;
     }
-    if (typeof s.name !== "string" || s.name.length === 0) {
-      issues.push({ field: `shared[${i}].name`, message: "\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32", got: s.name });
+    const got = await fetchRemoteManifestRepo(cfg, remoteApp, opts);
+    if (!got) {
+      issues.push({
+        level: "unverified",
+        message: `\u8FDC\u7A0B "${name}" \u7684 manifest \u4E0D\u53EF\u5F97\uFF08\u672C\u5730 dist \u4E0E${opts.site ? `\u7AD9\u70B9 ${opts.site}` : "\u9ED8\u8BA4 dist \u8DEF\u5F84"}\u5747\u672A\u547D\u4E2D\uFF09\u2014\u2014\u8BE5\u8FDC\u7A0B\u7684 spec \u5B58\u5728\u6027\u65E0\u6CD5\u6838\u5BF9\u3002
+  \u4FEE\u6CD5: \u5148\u6784\u5EFA\u8BE5\u8FDC\u7A0B\uFF08\u4EA7\u7269\u542B fulgurjs-manifest.json\uFF09\uFF0C\u6216\u7528 --site <URL> \u6307\u5411\u5DF2\u90E8\u7F72\u7AD9\u70B9`
+      });
+      continue;
     }
-    if (typeof s.version !== "string" || s.version.length === 0) {
-      issues.push({ field: `shared[${i}].version`, message: "\u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32", got: s.version });
+    manifests.set(name, { exposes: new Set([...normalizeExposes(got.manifest).keys()].map(normSpecKey)), from: got.from });
+    sources.push({ remote: name, from: got.from });
+  }
+  const derive = app.host?.deriveSpec ?? ((r) => r.split("/").filter(Boolean).slice(1).filter((s) => !s.startsWith(":")).join("/"));
+  let checked = 0;
+  for (const page of pages) {
+    const prefixHit = Object.entries(prefixes).sort((a, b) => b[0].length - a[0].length).find(
+      ([p]) => page.route.startsWith(p.endsWith("/") ? p : `${p}/`) || `${page.route}/` === (p.endsWith("/") ? p : `${p}/`)
+    );
+    if (!prefixHit) {
+      issues.push({ level: "error", message: `\u8DEF\u7531 "${page.route}" \u4E0D\u5728\u4EFB\u4F55 remotePrefixes \u524D\u7F00\u4E0B` });
+      continue;
+    }
+    checked++;
+    const m = manifests.get(prefixHit[1]);
+    if (!m) continue;
+    const spec = normSpecKey(String(page.spec ?? derive(page.route)));
+    if (!m.exposes.has(spec)) {
+      issues.push({
+        level: "error",
+        message: `\u8DEF\u7531 "${page.route}" \u7684 spec "${spec}" \u4E0D\u5728\u8FDC\u7A0B "${prefixHit[1]}" \u7684 exposes \u6E05\u5355\u4E2D\uFF08\u6765\u6E90 ${m.from}\uFF09\u3002
+  \u8FDC\u7A0B\u5B9E\u9645 exposes\uFF08\u524D 10\uFF09\uFF1A${[...m.exposes].slice(0, 10).join("\u3001") || "\uFF08\u7A7A\uFF09"}
+  \u4FEE\u6CD5: \u6838\u5BF9\u8FDC\u7A0B federation({ exposes }) \u952E\u540D\u6216\u4FEE\u6B63\u9875\u9762\u8868 spec`
+      });
     }
   }
-  return issues;
+  const failed = issues.some((i) => i.level === "error");
+  return { app: app.name, checked, issues, failed, unverifiedFailed: !!opts.requireVerified, manifestSources: sources };
+}
+async function checkPages(configPath, appPathOrName, opts = {}) {
+  const loaded = await loadAppConfig(configPath);
+  if (loaded.kind === "repo") {
+    if (!appPathOrName) {
+      throw new Error("[fulgurjs:check-pages] \u805A\u5408\u914D\u7F6E\u9700 --app <\u5E94\u7528\u76EE\u5F55\u540D\u6216\u5BB9\u5668\u540D>\uFF08\u5355\u9879\u76EE\u914D\u7F6E\u53EF\u7701\u7565\uFF09");
+    }
+    return checkPagesRepo(loaded.repo, appPathOrName, opts);
+  }
+  return checkPagesApp(loaded, opts);
 }
+function formatCheckPages(r) {
+  const L = [];
+  const errors = r.issues.filter((i) => i.level === "error");
+  const unverified = r.issues.filter((i) => i.level === "unverified");
+  const warns = r.issues.filter((i) => i.level === "warn");
+  L.push(`[fulgurjs:check-pages] \u5E94\u7528 ${r.app}\uFF1A\u6838\u5BF9 ${r.checked} \u6761\u9875\u9762\uFF0Cerror ${errors.length} / warn ${warns.length} / \u65E0\u6CD5\u9A8C\u8BC1 ${unverified.length}`);
+  if (r.manifestSources?.length) {
+    L.push("manifest \u6765\u6E90\uFF08\u4F18\u5148\u7EA7\uFF1A--manifest > --site/prod \u63A8\u5BFC > \u672C\u5730 dist\uFF1B\u4EE5\u5B9E\u9645\u547D\u4E2D\u7684\u6765\u6E90\u4E3A\u51C6\uFF09\uFF1A");
+    for (const s of r.manifestSources) L.push(`  ${s.remote} \u2190 ${s.from}`);
+  }
+  for (const i of [...errors, ...warns, ...unverified]) L.push(`
+[${i.level.toUpperCase()}] ${i.message}`);
+  if (r.issues.length === 0) L.push("\u5168\u90E8\u9875\u9762 spec \u4E0E\u8FDC\u7A0B exposes \u4E00\u81F4 \u2713");
+  if (r.unverifiedFailed && unverified.length > 0 && errors.length === 0) {
+    L.push(`
+--require-verified\uFF1A\u5B58\u5728 ${unverified.length} \u9879\u65E0\u6CD5\u9A8C\u8BC1\u2014\u2014\u6309 CI \u4E25\u683C\u6A21\u5F0F\u5224\u5B9A\u4E3A\u672A\u901A\u8FC7\uFF08\u9000\u51FA\u7801\u975E\u96F6\uFF09`);
+  }
+  return L.join("\n");
+}
+var DEFAULT_DERIVE, normSpecKey;
+var init_commands = __esm({
+  "src/commands.ts"() {
+    "use strict";
+    init_app_config();
+    init_config();
+    init_pages();
+    init_manifest();
+    DEFAULT_DERIVE = (route) => route.split("/").filter(Boolean).slice(1).filter((s) => !s.startsWith(":")).join("/");
+    normSpecKey = (s) => s.replace(/^[./]+/, "").replace(/\/+$/, "");
+  }
+});
+
+// src/cli.ts
+import { resolve } from "node:path";
 
 // src/doctor.ts
+init_manifest();
+import http from "node:http";
+import https from "node:https";
 function fetchHeadOrGet(url, method = "GET") {
   return new Promise((resolve2, reject) => {
     const mod = url.startsWith("https:") ? https : http;
@@ -709,18 +1598,31 @@ function formatDoctorReport(checks) {
 // src/cli.ts
 var HELP = `fulgurjs \u2014 Vite Module Federation CLI (@fulgurjs/federation)
 
-\u7528\u6CD5\uFF1A
-  fulgurjs init [--template <path>] [--force]      \u751F\u6210\u5E26\u6CE8\u91CA\u7684 fulgurjs.config.ts \u8D77\u6B65\u6A21\u677F
-  fulgurjs init --config <path>                    \u6821\u9A8C\u914D\u7F6E\uFF1B\u8F93\u51FA\u5404\u5E94\u7528 federation() \u7C98\u8D34\u5757\u3001
-                                                 NGINX no-cache \u7AD9\u70B9\u6A21\u677F\u4E0E\u63A5\u5165\u6838\u5BF9\u6E05\u5355
+\u7528\u6CD5\uFF08\u5355\u9879\u76EE fulgurjs.config.ts \u5728\u5E94\u7528\u6839\u76EE\u5F55\uFF1B\u547D\u4EE4\u9ED8\u8BA4\u8BFB ./fulgurjs.config.ts\uFF09\uFF1A
+  fulgurjs init [--template <path>] [--force]      \u751F\u6210\u5355\u9879\u76EE fulgurjs.config.ts \u8D77\u6B65\u6A21\u677F
+                                                   \uFF08\u9ED8\u8BA4\u5BFC\u51FA\u76F4\u63A5\u662F federation() \u9009\u9879\uFF09
+  fulgurjs init --config <path>                    \u6821\u9A8C\u914D\u7F6E\uFF1B\u8F93\u51FA federation(fulgurjsConfig) \u63A5\u5165\u5757
+                                                 \u4E0E\u63A5\u5165\u6838\u5BF9\u6E05\u5355\uFF08NGINX \u6837\u677F\u4EC5\u968F\u65E7\u805A\u5408\u914D\u7F6E\u6253\u5370\uFF09
+  fulgurjs explain [--config <path>] [--app <name>] [--json]
+                                                 \u89E3\u91CA\u672C\u5E94\u7528\u6709\u6548\u8054\u90A6\u5F62\u6001\u4E0E\u52A0\u8F7D\u94FE\uFF08\u7EAF\u672C\u5730\uFF0C\u65E0\u7F51\u7EDC\uFF1B
+                                                 \u5355\u9879\u76EE\u5F62\u6001\u514D --app\uFF0C\u65E7\u805A\u5408\u914D\u7F6E\u5FC5\u586B\uFF09
+  fulgurjs check-pages [--config <path>] [--app <name>] [--site <URL>]
+                        [--manifest <remote>=<\u8DEF\u5F84|URL>]... [--require-verified] [--json]
+                                                 \u6838\u5BF9\u5BBF\u4E3B\u9875\u9762\u8868\u4E0E\u8FDC\u7A0B exposes\uFF08\u5BBF\u4E3B\u9879\u76EE\u8FD0\u884C\uFF1B
+                                                 manifest \u6765\u6E90\u4F18\u5148\u7EA7 --manifest > --site/prod \u63A8\u5BFC\uFF1B
+                                                 \u786E\u5B9A\u6027\u9519\u8BEF\u975E\u96F6\u9000\u51FA\uFF1B--require-verified \u65F6\u65E0\u6CD5\u9A8C\u8BC1\u4E5F\u975E\u96F6\uFF09
   fulgurjs doctor --base <URL> --apps <a,b,c> [--dev] [--json] [--chunk-sample N]
   fulgurjs --help
 
-\u793A\u4F8B\uFF1A
+\u793A\u4F8B\uFF08\u5355\u9879\u76EE\u5F62\u6001\uFF0C\u5E94\u7528\u6839\u76EE\u5F55\u5185\u8FD0\u884C\uFF09\uFF1A
   fulgurjs init                                    # \u5F53\u524D\u76EE\u5F55\u5199 fulgurjs.config.ts\uFF08\u5DF2\u5B58\u5728\u5219\u62D2\u7EDD\uFF0C--force \u8986\u76D6\uFF09
-  fulgurjs init --config fulgurjs.config.ts          # \u6821\u9A8C + \u8F93\u51FA\u6837\u677F
-  fulgurjs doctor --base http://your-site --apps app-a,app-b
-  fulgurjs doctor --base http://localhost:5173 --apps app-a --dev
+  fulgurjs explain                                 # \u89E3\u91CA\u672C\u5E94\u7528\uFF08--config \u6307\u5411\u5176\u4ED6\u8DEF\u5F84\u65F6\u663E\u5F0F\u4F20\uFF09
+  fulgurjs check-pages --site http://your-site     # \u6309 remotes prod \u5730\u5740\u63A8\u5BFC\u8FDC\u7A0B manifest \u6838\u5BF9
+  fulgurjs check-pages --manifest remote-a=https://cdn.example.com/remote-a/fulgurjs-manifest.json
+  fulgurjs doctor --base http://your-site --apps my-app,remote-a
+
+\u65E7\u805A\u5408\u914D\u7F6E\uFF08root + apps[]\uFF0C\u517C\u5BB9\u671F\uFF09\uFF1A\u6240\u6709\u5B50\u547D\u4EE4\u52A0 --config \u6307\u5411\u805A\u5408\u6587\u4EF6\uFF0C
+explain/check-pages \u9700 --app <\u5E94\u7528\u76EE\u5F55\u540D\u6216\u5BB9\u5668\u540D>\u3002
 `;
 async function main() {
   const argv = process.argv.slice(2);
@@ -734,6 +1636,17 @@ async function main() {
     return i > -1 ? argv[i + 1] : void 0;
   };
   const has = (k) => argv.includes(k);
+  const kvAllOf = (k) => {
+    const out = {};
+    argv.forEach((a, i) => {
+      if (a !== k) return;
+      const v = argv[i + 1];
+      const eq = v?.indexOf("=");
+      if (!v || !eq || eq < 1) return;
+      out[v.slice(0, eq)] = v.slice(eq + 1);
+    });
+    return out;
+  };
   if (cmd === "init") {
     const { writeConfigTemplate: writeConfigTemplate2, inspectConfig: inspectConfig2 } = await Promise.resolve().then(() => (init_init(), init_exports));
     const configPath = argOf("--config");
@@ -752,14 +1665,42 @@ async function main() {
       console.error(`[fulgurjs:init] ${target} \u5DF2\u5B58\u5728\uFF0C\u62D2\u7EDD\u8986\u76D6\uFF08--force \u5F3A\u5236\u8986\u76D6\uFF09`);
       return 2;
     }
-    console.log(`[fulgurjs:init] \u5DF2\u751F\u6210\u8D77\u6B65\u6A21\u677F ${target}
+    console.log(`[fulgurjs:init] \u5DF2\u751F\u6210\u5355\u9879\u76EE\u8D77\u6B65\u6A21\u677F ${target}
 \u540E\u7EED\u6B65\u9AA4\uFF1A
-  1. \u7F16\u8F91 fulgurjs.config.ts\uFF1A\u586B\u5165\u4F60\u7684\u5E94\u7528\u76EE\u5F55/\u5BB9\u5668\u540D/\u7AEF\u53E3/base/\u9875\u9762\u8DEF\u7531\u8868/exposes
-  2. npx fulgurjs init --config fulgurjs.config.ts   # \u6821\u9A8C\u5E76\u8F93\u51FA\u53EF\u7C98\u8D34\u6837\u677F\u4E0E\u6838\u5BF9\u6E05\u5355
-  3. \u6309\u6E05\u5355\u628A federation() \u5757\u63A5\u5165\u5404\u5E94\u7528 vite.config.ts\uFF0C\u5B89\u88C5\u4F9D\u8D56
-  4. \u90E8\u7F72\u540E\uFF1Anpx fulgurjs doctor --base <URL> --apps <\u5E94\u7528...>`);
+  1. \u7F16\u8F91 fulgurjs.config.ts\uFF1A\u586B\u5165\u5BB9\u5668\u540D/exposes/remotes/shared\uFF08\u9ED8\u8BA4\u5BFC\u51FA\u76F4\u63A5\u662F federation() \u9009\u9879\uFF09
+  2. vite.config.ts \u63A5\u5165\uFF08\u4EC5\u4E24\u884C\u8054\u90A6\u76F8\u5173\u4EE3\u7801\uFF09\uFF1A
+       import federation from '@fulgurjs/federation'
+       import fulgurjsConfig from './fulgurjs.config'
+       // plugins: [ ...\u539F\u6709\u63D2\u4EF6, federation(fulgurjsConfig) ]
+  3. npx fulgurjs explain   # \u6838\u5BF9\u6709\u6548\u5F62\u6001\u4E0E\u52A0\u8F7D\u94FE
+  4. \u5BBF\u4E3B\u5E94\u7528\u53E6\u5728 fulgurjs.config.ts \u5177\u540D\u5BFC\u51FA hostPages\uFF08\u4E0E\u8FD0\u884C\u65F6\u9875\u9762\u6570\u636E\u6A21\u5757\u540C\u6E90\uFF09\uFF0C
+     \u8FD0\u884C npx fulgurjs check-pages --site <\u7AD9\u70B9> \u6838\u5BF9\u9875\u9762\u5951\u7EA6
+  5. \u90E8\u7F72\u540E\uFF1Anpx fulgurjs doctor --base <URL> --apps <\u5BB9\u5668\u540D>`);
     return 0;
   }
+  if (cmd === "explain" || cmd === "check-pages") {
+    const app = argOf("--app");
+    try {
+      if (cmd === "explain") {
+        const { explainApp: explainApp2, formatExplain: formatExplain2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+        const r2 = await explainApp2(resolve(argOf("--config") ?? "fulgurjs.config.ts"), app);
+        console.log(has("--json") ? JSON.stringify(r2, null, 2) : formatExplain2(r2));
+        return 0;
+      }
+      const { checkPages: checkPages2, formatCheckPages: formatCheckPages2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+      const opts = {
+        ...argOf("--site") ? { site: argOf("--site") } : {},
+        ...Object.keys(kvAllOf("--manifest")).length ? { manifests: kvAllOf("--manifest") } : {},
+        ...has("--require-verified") ? { requireVerified: true } : {}
+      };
+      const r = await checkPages2(resolve(argOf("--config") ?? "fulgurjs.config.ts"), app, opts);
+      console.log(has("--json") ? JSON.stringify(r, null, 2) : formatCheckPages2(r));
+      return r.failed || r.unverifiedFailed ? 1 : 0;
+    } catch (e) {
+      console.error(String(e.message ?? e));
+      return 2;
+    }
+  }
   if (cmd === "doctor") {
     const base = argOf("--base");
     const appsRaw = argOf("--apps") ?? "main";