@fulgurjs/federation 5.8.0 → 5.9.1

package/examples/templates/vue-vue/pnpm-workspace.yaml

@@ -0,0 +1,10 @@
+packages:
+  - host
+  - remote
+minimumReleaseAgeExclude:
+  - '@fulgurjs/federation@5.7.1 || 5.8.0 || 5.9.0'
+# pnpm >=12 构建脚本批准（12 起弃用 onlyBuiltDependencies；pnpm 9-11 忽略本键：
+# esbuild >=0.16 二进制经 optionalDependencies 平台包分发，postinstall 仅校验，不阻塞安装）
+allowBuilds:
+  esbuild: true
+  vue-demi: true

package/examples/{vue → templates/vue-vue}/remote/README.md

@@ -1,16 +1,17 @@
 # vue-remote —— Vue 远程（fulgurjs 联邦演示）
 
-> **角色：Vue 远程（被消费方）。** 向 [`../host/`](../host/)（vue-host，端口 5214）暴露可点击按钮组件、普通 TS 工具模块、联邦首页与参数详情页；也可独立运行调试。
+> **角色：Vue 远程（被消费方）。** 向 [`../host/`](../host)（vue-host，端口 5214）暴露可点击按钮组件、普通 TS 工具模块、联邦首页与参数详情页；也可独立运行调试。
 
 ## 从干净拷贝运行
 
+复制整个 `vue-vue/` 模板，在模板根安装依赖后启动本应用：
+
 ```bash
-cd vue-remote        # 把本目录复制到任意位置后进入
-npm install
-npm run dev          # http://localhost:5213
+pnpm install --frozen-lockfile
+pnpm --dir remote dev
 ```
 
-独立运行画面：`vue-remote 独立运行` 页面 + 一枚可点击计数按钮（这是远程自己的壳，`src/main.ts` + `src/App.vue`；联邦消费走 `fulgurjs-remoteEntry.js` 容器入口，与壳无关）。
+宿主需要先启动对应远程；也可以在模板根执行 `pnpm dev` 启动完整组合。环境和完整运行步骤见[组合说明](../README.md)。
 
 ## 暴露的模块（exposes）
 
@@ -37,7 +38,7 @@ utils.sumNumbers(2, 3, 7) // 12
 ## 生产构建与部署
 
 ```bash
-npm run build        # dist/（含 fulgurjs-remoteEntry.js 与 fulgurjs-manifest.json）
+pnpm run build        # dist/（含 fulgurjs-remoteEntry.js 与 fulgurjs-manifest.json）
 ```
 
 部署到 Nginx 子路径 `/vue-remote/`（与宿主 `fulgurjs.config.ts` 的 `prod: '/vue-remote'` 对应；`vite.config.ts` 已配置 `base` 随 `build` 自动切换为 `/vue-remote/`（dev 不受影响）；不要去掉它，否则 modulepreload 链接会指向站点根导致 404）。完整 Nginx 示例见[组合说明](../README.md#生产构建与最小-nginx-部署)。

package/examples/{vue → templates/vue-vue}/remote/package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview --port 5213 --strictPort"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.7.1",
+    "@fulgurjs/federation": "5.9.0",
     "vue": "^3.5.13"
   },
   "devDependencies": {

package/examples/{vue → templates/vue-vue}/remote/src/App.vue

@@ -1,7 +1,7 @@
 <template>
   <div style="font-family: sans-serif; padding: 16px">
     <h1>vue-remote 独立运行</h1>
-    <p>这是远程应用自己的壳，用于单独开发。联邦消费方（examples/vue/host）按 exposes 加载以下模块：</p>
+    <p>这是远程应用自己的壳，用于单独开发。联邦消费方（examples/templates/vue-vue/host）按 exposes 加载以下模块：</p>
     <ul>
       <li>./ClickButton —— 可点击计数按钮组件</li>
       <li>./utils —— 普通 TS 工具模块</li>

package/examples/templates/vue-vue/scripts/dev.config.json

@@ -0,0 +1,6 @@
+{
+  "apps": [
+    { "name": "remote", "dir": "remote", "port": 5213 },
+    { "name": "host", "dir": "host", "port": 5214 }
+  ]
+}

package/examples/templates/vue-vue/scripts/dev.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * 模板统一 dev 启动器（规范源）。
+ *
+ * 本文件经 examples/scripts/sync-template-scripts.mjs 同步到五个模板的 scripts/dev.mjs；
+ * 模板内副本必须与规范源逐字节一致（check-catalog.mjs 校验哈希），模板复制出仓库后独立可用——
+ * 只依赖同目录 dev.config.json 与 Node 内置模块，不依赖仓库其他文件。
+ *
+ * 行为契约（与模板 README 一致）：
+ * - 启动前预检全部端口：任何端口被占用则拒绝启动并指认处理方法（绝不按端口杀别人的进程）；
+ * - 按 dev.config.json 顺序（远程在前宿主在后）启动各应用，逐个探活；
+ * - 任一应用启动失败/超时/中途退出：整组停止（只杀本次启动的子进程），非零退出并打印该应用日志尾部；
+ * - Ctrl+C / SIGTERM：清理本次启动的全部子进程后退出；不依赖 PID 文件；
+ * - 全部就绪后打印访问入口；探活 = 端口可连接（dev server 已监听），页面可用以浏览器验收为准。
+ *
+ * 平台：macOS/Linux 实测；Windows 走 taskkill 兜底路径，未经验证（见模板 README）。
+ */
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import net from 'node:net'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const templateRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const { apps, readyTimeoutMs = 120000 } = JSON.parse(
+  fs.readFileSync(path.join(templateRoot, 'scripts', 'dev.config.json'), 'utf8'),
+)
+const isTTY = process.stdout.isTTY
+const color = (code, text) => (isTTY ? `\x1b[${code}m${text}\x1b[0m` : text)
+const EXIT = { ok: 0, startupFailed: 1, portConflict: 2, signal: 130 }
+
+/** 双栈端口探测（vite 可能只绑 IPv4 或 IPv6 回环） */
+function isPortUp(port) {
+  const probe = (host) =>
+    new Promise((resolve, reject) => {
+      const s = net.connect({ port, host, timeout: 800 })
+      s.on('connect', () => { s.destroy(); resolve(true) })
+      s.on('error', reject)
+      s.on('timeout', () => { s.destroy(); reject(new Error('timeout')) })
+    })
+  return Promise.any([probe('127.0.0.1'), probe('::1')]).catch(() => false)
+}
+
+const tailOf = new Map()
+const children = new Map()
+let shuttingDown = false
+
+function recordOutput(name, chunk) {
+  const lines = (tailOf.get(name) ?? [])
+  for (const line of String(chunk).split('\n')) {
+    if (line === '') continue
+    lines.push(line)
+  }
+  while (lines.length > 60) lines.shift()
+  tailOf.set(name, lines)
+}
+
+function printAppLine(name, text) {
+  process.stdout.write(`${color('2', `[${name}]`)} ${text}\n`)
+}
+
+async function preflight() {
+  const conflicts = []
+  for (const app of apps) {
+    if (await isPortUp(app.port)) conflicts.push(app)
+  }
+  if (conflicts.length === 0) return
+  console.error(color('31', '[dev] 启动前检查失败：以下端口已被占用（不区分占用者，一律不启动）：'))
+  for (const app of conflicts) {
+    const posix = `lsof -nP -iTCP:${app.port} -sTCP:LISTEN`
+    const win = `netstat -ano | findstr :${app.port}`
+    console.error(
+      `  ${app.name} → 端口 ${app.port} 已监听。查看占用：${process.platform === 'win32' ? win : posix}；` +
+        `结束占用进程，或同步修改 ${app.dir}/package.json 的 dev/preview 端口与宿主 fulgurjs.config.ts 的 remotes dev 地址后重试`,
+    )
+  }
+  console.error('[dev] 本启动器只清理自己启动的进程，不会替你结束端口上的既有服务。')
+  process.exit(EXIT.portConflict)
+}
+
+function spawnApp(app) {
+  const child = spawn('pnpm', ['--dir', app.dir, 'run', 'dev'], {
+    cwd: templateRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // POSIX：独立进程组，便于整组终止；Windows：shell 解析 pnpm.cmd，树杀交给 taskkill
+    detached: true,
+    shell: process.platform === 'win32',
+  })
+  children.set(app.name, child)
+  child.stdout.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
+  child.stderr.on('data', (c) => { recordOutput(app.name, c); String(c).split('\n').filter(Boolean).forEach((l) => printAppLine(app.name, l)) })
+  return child
+}
+
+const exitedOnce = (child) =>
+  new Promise((resolve) => {
+    child.once('exit', (code, signal) => resolve({ code, signal }))
+    child.once('error', (e) => resolve({ code: -1, signal: null, error: e }))
+  })
+
+async function waitReady(app, child) {
+  const exited = exitedOnce(child)
+  const deadline = Date.now() + readyTimeoutMs
+  while (Date.now() < deadline) {
+    if (await isPortUp(app.port)) return { ok: true }
+    const done = await Promise.race([exited.then(() => 'exit'), new Promise((r) => setTimeout(() => r('tick'), 400))])
+    if (done === 'exit') return { ok: false, reason: `进程提前退出（启动命令失败——看下方日志尾部）` }
+  }
+  return { ok: false, reason: `${Math.round(readyTimeoutMs / 1000)}s 内端口 ${app.port} 未就绪（dev server 未监听）` }
+}
+
+function killTree(appName) {
+  const child = children.get(appName)
+  if (!child || child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+  return new Promise((resolve) => {
+    const force = setTimeout(() => {
+      try { process.kill(process.platform === 'win32' ? child.pid : -child.pid, 'SIGKILL') } catch { /* 已退出 */ }
+    }, 3000).unref()
+    child.once('exit', () => { clearTimeout(force); resolve() })
+    try {
+      if (process.platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+      else process.kill(-child.pid, 'SIGTERM')
+    } catch { clearTimeout(force); resolve() }
+  })
+}
+
+async function shutdown(exitCode, reason) {
+  if (shuttingDown) return
+  shuttingDown = true
+  if (reason) console.log(`[dev] ${reason}`)
+  console.log(`[dev] 正在停止本次启动的 ${children.size} 个应用…`)
+  await Promise.all([...children.keys()].map(killTree))
+  console.log('[dev] 已全部停止。')
+  process.exit(exitCode)
+}
+
+process.on('SIGINT', () => void shutdown(EXIT.signal, '[dev] 收到 Ctrl+C'))
+process.on('SIGTERM', () => void shutdown(143, '[dev] 收到 SIGTERM'))
+
+await preflight()
+
+console.log(`[dev] 模板 ${path.basename(templateRoot)}：按顺序启动 ${apps.map((a) => a.name).join(' → ')}`)
+for (const app of apps) {
+  printAppLine(app.name, `启动（pnpm --dir ${app.dir} run dev），等待端口 ${app.port} 就绪…`)
+  const child = spawnApp(app)
+  const ready = await waitReady(app, child)
+  if (!ready.ok) {
+    console.error(color('31', `\n[dev] 启动失败：${app.name} —— ${ready.reason}`))
+    const tail = tailOf.get(app.name) ?? []
+    if (tail.length) {
+      console.error(color('31', `[dev] ${app.name} 日志尾部（最后 ${tail.length} 行）：`))
+      for (const line of tail) console.error(`  [${app.name}] ${line}`)
+    }
+    await Promise.all([...children.keys()].map(killTree))
+    console.error(`[dev] 已停止本次启动的全部进程（${children.size} 个）。修复上面的问题后重新运行 pnpm dev。`)
+    process.exit(EXIT.startupFailed)
+  }
+  printAppLine(app.name, `就绪 → http://localhost:${app.port}/`)
+}
+
+console.log(color('32', '\n[dev] 全部应用已就绪：'))
+for (const app of [...apps].reverse()) {
+  console.log(`  http://localhost:${app.port}/    ${app.name}`)
+}
+console.log('[dev] Ctrl+C 停止全部应用（只清理本次启动的进程）。dev server 已监听 ≠ 页面必然可用，验收请以浏览器实际加载为准。\n')
+
+// 运行期任何子应用退出（崩溃/被外部杀掉）→ 整组停止，不让半残组合冒充正常运行
+for (const [name, child] of children) {
+  child.once('exit', (code) => {
+    if (!shuttingDown) void shutdown(EXIT.startupFailed, `[dev] ${name} 意外退出（退出码 ${code}）——停止其余应用`)
+  })
+}
+await new Promise(() => {})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fulgurjs/federation",
-  "version": "5.8.0",
+  "version": "5.9.1",
   "type": "module",
   "description": "Vite Module Federation for Vue and React: remote modules, shared dependencies and app bridges.",
   "license": "MIT",
@@ -124,9 +124,9 @@
     "docs/API.en.md"
   ],
   "scripts": {
-    "build": "cp ../../README.md README.md && cp ../../README.en.md README.en.md && mkdir -p docs && cp ../../docs/API.md ../../docs/API.en.md ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md docs/ && cp ../../CHANGELOG.md CHANGELOG.md && cp ../../DESIGN.md DESIGN.md && rm -rf examples && cp -R ../../examples examples && find examples \\( -name node_modules -o -name dist -o -path '*/src/fulgurjs/types' \\) -exec rm -rf {} + && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime.mjs && tsup src/index.ts src/pages.ts src/vue-adapter.ts src/react-adapter.ts src/context.ts src/bridge-core.ts src/bridge-errors.ts src/bridge-app-vue.ts src/bridge-app-react.ts src/bridge-host-vue.ts src/bridge-host-react.ts --format esm,cjs --dts --external vite --target node18 --clean && tsup src/runtime-entry.ts --format esm --dts --external vite,vue --target node18 && tsup src/react.ts --format esm --dts --external vite,react --target node18 && tsup src/bridge.ts src/bridge-vue.ts src/bridge-react.ts --format esm --dts --external vite,vue,react,react-dom --target node18 && tsup src/bridge-router-vue.ts --format esm --dts --external vite,vue,vue-router --target node18 && tsup src/bridge-router-react.tsx --format esm --dts --external vite,react,react-dom,react-router-dom --target node18 && esbuild src/cli.ts --bundle --format=esm --target=node18 --platform=node --outfile=dist/cli.js && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime-entry.mjs && node scripts/check-gzip.mjs && node scripts/check-manual-codes.mjs",
+    "build": "cp ../../README.md README.md && cp ../../README.en.md README.en.md && mkdir -p docs && cp ../../docs/API.md ../../docs/API.en.md ../../docs/迁移指南.md ../../docs/webpack-mf-对照与缺口.md ../../docs/沙箱边界审计.md ../../docs/P5-vite7-8兼容矩阵.md docs/ && cp ../../CHANGELOG.md CHANGELOG.md && cp ../../DESIGN.md DESIGN.md && node scripts/sync-package-examples.mjs && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime.mjs && tsup src/index.ts src/pages.ts src/vue-adapter.ts src/react-adapter.ts src/context.ts src/bridge-core.ts src/bridge-errors.ts src/bridge-app-vue.ts src/bridge-app-react.ts src/bridge-host-vue.ts src/bridge-host-react.ts --format esm,cjs --dts --external vite --target node18 --clean && tsup src/runtime-entry.ts --format esm --dts --external vite,vue --target node18 && tsup src/react.ts --format esm --dts --external vite,react --target node18 && tsup src/bridge.ts src/bridge-vue.ts src/bridge-react.ts --format esm --dts --external vite,vue,react,react-dom --target node18 && tsup src/bridge-router-vue.ts --format esm --dts --external vite,vue,vue-router --target node18 && tsup src/bridge-router-react.tsx --format esm --dts --external vite,react,react-dom,react-router-dom --target node18 && esbuild src/cli.ts --bundle --format=esm --target=node18 --platform=node --outfile=dist/cli.js && esbuild src/runtime/index.ts --bundle --format=esm --target=es2022 --minify --outfile=dist/runtime.js && node scripts/gen-runtime-entry.mjs && node scripts/check-gzip.mjs && node scripts/check-manual-codes.mjs",
     "dev": "tsup --watch",
-    "test": "vitest run",
+    "test": "vitest run --dir tests",
     "typecheck": "tsc --noEmit",
     "typecheck:latest": "node scripts/typecheck-latest.mjs"
   },
@@ -205,4 +205,4 @@
       "optional": true
     }
   }
-}
+}

package/examples/README.en.md

@@ -1,67 +0,0 @@
-# fulgurjs-federation Examples
-
-Pick your framework, copy the host and remote directories, run `npm install`, and you get a full module federation demo. All four projects are standalone: no dependency on this repo's source, the monorepo workspace, or any parent `node_modules` — the plugin dependency is an exact published version from the npm registry.
-
-## Vue (host 5214 / remote 5213)
-
-Full walkthrough: **[vue/README.md](./vue/README.md)** (Chinese).
-
-```bash
-cd examples/vue/remote && npm install && npm run dev   # terminal 1: vue-remote, http://localhost:5213
-cd examples/vue/host   && npm install && npm run dev   # terminal 2: vue-host,   http://localhost:5214
-```
-
-## React (host 5204 / remote 5203)
-
-Full walkthrough: **[react/README.md](./react/README.md)** (Chinese).
-
-```bash
-cd examples/react/remote && npm install && npm run dev   # terminal 1: react-remote, http://localhost:5203
-cd examples/react/host   && npm install && npm run dev   # terminal 2: react-host,   http://localhost:5204
-```
-
-## Cross-framework bridge (Vue host 5314 × React remote 5303; React host 5304 × Vue remote 5313)
-
-Full walkthrough: **[bridge/README.md](./bridge/README.md)** (Chinese).
-
-```bash
-# Vue host × React sub-app
-cd examples/bridge/react-remote && npm install && npm run dev   # 5303
-cd examples/bridge/vue-host     && npm install && npm run dev   # 5314
-
-# React host × Vue sub-app
-cd examples/bridge/vue-remote   && npm install && npm run dev   # 5313
-cd examples/bridge/react-host   && npm install && npm run dev   # 5304
-```
-
-## What each pair demonstrates
-
-- A clickable remote counter component (local state lives inside the remote component; operated on the host page)
-- Cross-application plain TS module calls (the host renders real return values)
-- A remote home page plus a parameterized detail page (deep links survive refresh)
-- Host navigation with route-level lazy loading (the home page never bulk-prefetches unvisited remote pages)
-- The plugin's built-in loading/error placeholders and recovery actions (**Retry load** recovers in-page; **Refresh page to retry** recovers via a user-initiated full reload)
-- Production build with a minimal Nginx deployment (including SPA fallback)
-
-## Layout
-
-```text
-examples/
-├── README.md / README.en.md   # this entry (CN/EN)
-├── bridge/                    # Cross-framework bridge (sub-app-level mount/unmount, §8.2)
-│   ├── README.md
-│   ├── vue-host/              # Vue host × React sub-app (5314)
-│   ├── react-remote/          # React sub-app (5303)
-│   ├── react-host/            # React host × Vue sub-app (5304)
-│   └── vue-remote/            # Vue sub-app (5313)
-├── vue/
-│   ├── README.md              # guide for the Vue pair
-│   ├── host/                  # Vue host (vue-host, 5214)
-│   └── remote/                # Vue remote (vue-remote, 5213)
-└── react/
-    ├── README.md              # guide for the React pair
-    ├── host/                  # React host (react-host, 5204)
-    └── remote/                # React remote (react-remote, 5203)
-```
-
-> `examples/` is for users to copy and run. The repository-root `fixtures/` are internal regression harnesses (source-linked to the plugin workspace) — do not treat them as usage templates.

package/examples/bridge/README.md

@@ -1,36 +0,0 @@
-# 跨框架桥接示例（/bridge）
-
-双向「子应用级跨框架嵌入」的最小可运行组合（README §8.2）：
-
-| 组合 | 宿主 | 子应用 | 端口 |
-|---|---|---|---|
-| Vue 宿主 × React 子应用 | [vue-host](./vue-host)（5314） | [react-remote](./react-remote)（5303） | 先起 5303 |
-| React 宿主 × Vue 子应用 | [react-host](./react-host)（5304） | [vue-remote](./vue-remote)（5313） | 先起 5313 |
-
-四个工程互相独立：`npm install` 即用 registry 正式包；宿主同时安装两套框架并全部 singleton（桥接使用合同），子应用只装自己的框架。
-
-## 快速开始（Vue 宿主 × React 子应用）
-
-```bash
-cd react-remote && npm install && npm run dev    # 终端 1：http://localhost:5303
-cd ../vue-host  && npm install && npm run dev    # 终端 2：http://localhost:5314
-```
-
-打开 5314：点击「切换到 Bob / 登出」体验受控会话（卸载→清 context→新代次重挂）；子应用内部按钮操作其 memory 路由与本地状态。
-
-## 快速开始（React 宿主 × Vue 子应用）
-
-```bash
-cd vue-remote  && npm install && npm run dev     # 终端 1：http://localhost:5313
-cd ../react-host && npm install && npm run dev   # 终端 2：http://localhost:5304
-```
-
-## 生产构建与部署
-
-每个示例 `npm run build` 产出各自子路径（`/bridge-vue-host/` 等）。部署时保持「子应用子路径 + 宿主子路径」并列，宿主 fulgurjs 配置的 `prod` 指向子应用子路径（已是根相对写法）。NGINX 需对各 `fulgurjs-remoteEntry.js`/`fulgurjs-manifest.json`/`index.html` 设置 no-cache，其余静态资源可长缓存。
-
-## 范围声明（v1）
-
-- 只做子应用级挂载/卸载；组件级混渲染（Vue 里直接渲染 React 组件）不支持。
-- 子应用用 memory 路由，不与宿主 URL 同步。
-- 无 JS 沙箱与 CSS 隔离：远程全局样式/body 级副作用会影响宿主，需自行命名空间治理。