@fulgurjs/federation 5.8.0 → 5.9.0

package/examples/templates/vue-host-react-remote/pnpm-workspace.yaml

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

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

@@ -1,15 +1,20 @@
 # bridge-react-remote — React 桥接子应用示例
 
-`@fulgurjs/federation` 跨框架桥接的 **React 18/19 子应用**侧示例：以 `defineBridgeApp`（`@fulgurjs/federation/react`）导出 `mount/unmount` 契约，可被 **Vue 宿主**（配合 `examples/bridge/vue-host`）整站挂载。
+`@fulgurjs/federation` 跨框架桥接的 **React 18/19 子应用**侧示例：以 `defineBridgeApp`（`@fulgurjs/federation/react`）导出 `mount/unmount` 契约，可被 **Vue 宿主**（配合 `examples/templates/vue-host-react-remote/vue-host-react-remote/vue-host`）整站挂载。
 
 ## 运行
 
+复制整个 `vue-host-react-remote/` 模板，在模板根执行：
+
 ```bash
-npm install
-npm run dev        # http://localhost:5303（独立运行态）
-npm run build      # 产出 /bridge-react-remote/ 子路径产物
+pnpm install --frozen-lockfile
+pnpm dev                         # 同时启动宿主和子应用
+pnpm build                       # 构建完整组合
+# 单独启动本应用：pnpm --dir react-remote dev
 ```
 
+端口、复制范围与部署路径见[组合说明](../README.md)。
+
 ## 关键点
 
 - `src/bridge.tsx`：`defineBridgeApp((props) => <MemoryRouter>…</MemoryRouter>)`，作为 `./bridge` expose 的默认导出。

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

@@ -9,7 +9,7 @@
     "preview": "vite preview --port 5303 --strictPort"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.7.1",
+    "@fulgurjs/federation": "5.8.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router-dom": "^7.1.0"

package/examples/templates/vue-host-react-remote/scripts/dev.config.json

@@ -0,0 +1,6 @@
+{
+  "apps": [
+    { "name": "react-remote", "dir": "react-remote", "port": 5303 },
+    { "name": "vue-host", "dir": "vue-host", "port": 5314 }
+  ]
+}

package/examples/templates/vue-host-react-remote/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/examples/{bridge → templates/vue-host-react-remote}/vue-host/README.md

@@ -4,16 +4,17 @@
 
 ## 运行
 
-```bash
-# 1) 先启动 React 子应用（5303）
-cd ../react-remote && npm install && npm run dev
+复制整个 `vue-host-react-remote/` 模板，在模板根执行：
 
-# 2) 再启动本宿主（5314）
-npm install
-npm run dev        # http://localhost:5314
-npm run build      # 产出 /bridge-vue-host/ 子路径产物
+```bash
+pnpm install --frozen-lockfile
+pnpm dev                         # 同时启动宿主和子应用
+pnpm build                       # 构建完整组合
+# 单独启动本应用：pnpm --dir vue-host dev
 ```
 
+端口、复制范围与部署路径见[组合说明](../README.md)。
+
 ## 关键点（对应 README §8.2）
 
 - **双框架安装合同**：本宿主同时安装 `vue` + `react` + `react-dom`，shared 三键全部 `singleton: true`。

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

@@ -9,7 +9,7 @@
     "preview": "vite preview --port 5314 --strictPort"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.7.1",
+    "@fulgurjs/federation": "5.8.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "vue": "^3.5.13"

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

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 /**
  * Vue 宿主 × React 桥接子应用（examples 版，含全部关键语义注释）。
- * 先启动 examples/bridge/react-remote（5303）再启动本宿主。
+ * 先启动 examples/templates/react-remote（5303）再启动本宿主。
  */
 import { ref } from 'vue'
 import { clearAppContext } from '@fulgurjs/federation/runtime'

package/examples/templates/vue-host-react-remote/vue-host/src/fulgurjs/types/bridge-react-remote.d/_paths.d.ts

@@ -0,0 +1,4 @@
+// 精确轨启用方法（把下面片段合入宿主 tsconfig 的 compilerOptions；baseUrl 指向本 tsconfig 所在目录）：
+//   "paths": { "bridge-react-remote/*": ["src/fulgurjs/types/bridge-react-remote.d/*"] }
+// 说明：零配置轨（bridge-react-remote.d.ts 的 ambient 声明）可解析但导出为宽松类型；
+// 配置 paths 后同形态导入解析到本目录的转发模块，获得远程源码级类型精度。

package/examples/templates/vue-host-react-remote/vue-host/src/fulgurjs/types/bridge-react-remote.d/bridge.ts

@@ -0,0 +1,3 @@
+// 自动生成（精确轨）：经 tsconfig paths 解析到本文件后获得源码级类型
+export * from "../../../../../react-remote/src/bridge"
+export { default } from "../../../../../react-remote/src/bridge"

package/examples/templates/vue-host-react-remote/vue-host/src/fulgurjs/types/bridge-react-remote.d.ts

@@ -0,0 +1,9 @@
+// 自动生成：fulgurjs-federation dev 类型直连（remote: bridge-react-remote，mode: source）
+// 重新生成：重启 host dev server
+
+declare module "bridge-react-remote/bridge" {
+  const __fg_default: any
+  export default __fg_default
+  export const App: any
+  export type App = any
+}

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

@@ -7,23 +7,19 @@
 | [`remote/`](./remote/) | **Vue 远程**（被消费方） | 5213 | 暴露可点击按钮组件、普通 TS 工具模块、联邦首页与参数详情页 |
 | [`host/`](./host/) | **Vue 宿主**（消费方） | 5214 | 消费 vue-remote 的组件/模块/页面，提供导航与懒加载 |
 
-- 包管理器统一为 **npm**；插件依赖为 **registry 精确正式包**（`@fulgurjs/federation`，见各 `package.json`），不依赖本仓库源码、monorepo workspace 或父目录 node_modules。
-- 把 `host/` 与 `remote/` 复制到**两个互不共享父目录的目录**后，各自 `npm install` 仍可运行。
+- 包管理器为 **pnpm**；复制整个模板目录，包含 workspace 和锁文件。插件使用 registry 正式精确版本。
 
 ## 最快开始（从干净拷贝）
 
 ```bash
-# 终端 1 —— 先启动远程
-cd vue/remote
-npm install
-npm run dev            # http://localhost:5213
-
-# 终端 2 —— 再启动宿主
-cd vue/host
-npm install
-npm run dev            # http://localhost:5214
+cd examples/templates/vue-vue  # 若已复制出去，进入复制后的模板根
+pnpm install --frozen-lockfile
+pnpm dev                       # 同时启动远程和宿主
+# http://localhost:5214
 ```
 
+环境要求与 pnpm 版本说明见[模板指南](../README.md)。单独启动用 `pnpm dev:remote`、`pnpm dev:host`，构建整个组合用 `pnpm build`。
+
 打开 <http://localhost:5214/>：
 
 - 「首页」里有来自 vue-remote 的**可点击计数按钮**（进入页面才按需加载）。
@@ -44,8 +40,8 @@ npm run dev            # http://localhost:5214
 ## 生产构建与最小 Nginx 部署
 
 ```bash
-cd vue/remote && npm run build -- --base=/vue-remote/   # 产物 remote/dist/（子路径 base 与部署位置对应）
-cd vue/host   && npm run build   # 产物 host/dist/
+pnpm --dir remote build -- --base=/vue-remote/   # 产物 remote/dist/（子路径 base 与部署位置对应）
+pnpm --dir host build   # 产物 host/dist/
 ```
 
 部署形态：宿主部署在站点根 `/`，远程部署在子路径 `/vue-remote/`（与 `host/fulgurjs.config.ts` 的 `prod: '/vue-remote'` 对应）。远程工程的 `vite.config.ts` 已配置 `base` 随 `build` 命令自动切换为 `/vue-remote/`（dev 不变）——Vite 的 preload helper 会把依赖链接转成根绝对路径，远程子路径部署必须带此 base。最小 Nginx 配置（SPA fallback + 联邦入口正确 Content-Type）：

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

@@ -1,19 +1,17 @@
 # vue-host —— Vue 宿主（fulgurjs 联邦演示）
 
-> **角色：Vue 宿主（消费方）。** 消费 [`../remote/`](../remote/)（vue-remote，端口 5213）暴露的组件、TS 模块与联邦页面；本应用自身不暴露任何模块。
+> **角色：Vue 宿主（消费方）。** 消费 [`../remote/`](../remote)（vue-remote，端口 5213）暴露的组件、TS 模块与联邦页面；本应用自身不暴露任何模块。
 
 ## 从干净拷贝运行
 
-前置：Node ≥ 20.19 与 npm（与本仓库示例验证版本一致即可）。
+复制整个 `vue-vue/` 模板，在模板根安装依赖后启动本应用：
 
 ```bash
-# 先启动远程（另一终端）：见 ../remote/README.md
-cd vue-host          # 把本目录复制到任意位置后进入
-npm install
-npm run dev          # http://localhost:5214
+pnpm install --frozen-lockfile
+pnpm --dir host dev
 ```
 
-成功画面：导航条含「首页 / 远程首页 / 远程详情 / TS 模块调用」；「远程首页」出现 vue-remote 的标题与可点击计数按钮。
+宿主需要先启动对应远程；也可以在模板根执行 `pnpm dev` 启动完整组合。环境和完整运行步骤见[组合说明](../README.md)。
 
 ## 目录与关键配置
 
@@ -34,7 +32,7 @@ npm run dev          # http://localhost:5214
 ## 生产构建与部署
 
 ```bash
-npm run build        # dist/
+pnpm run build        # dist/
 ```
 
 部署在站点根 `/`（Nginx SPA fallback 见 [组合说明](../README.md#生产构建与最小-nginx-部署)）。深链 `/remote/detail/7?tab=basic` 刷新后由 fallback 回退 index.html、插件路由解析恢复同一页面。

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

@@ -9,7 +9,7 @@
     "preview": "vite preview --port 5214 --strictPort"
   },
   "dependencies": {
-    "@fulgurjs/federation": "5.7.1",
+    "@fulgurjs/federation": "5.8.0",
     "vue": "^3.5.13",
     "vue-router": "^4.5.0"
   },

package/examples/templates/vue-vue/host/src/fulgurjs/types/vue-remote.d/ClickButton.ts

@@ -0,0 +1,4 @@
+// 自动生成（精确轨）：.vue expose 为宽松形态（精确类型需宿主 vue-tsc/shim）
+import type { DefineComponent } from 'vue'
+declare const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+export default component

package/examples/templates/vue-vue/host/src/fulgurjs/types/vue-remote.d/_paths.d.ts

@@ -0,0 +1,4 @@
+// 精确轨启用方法（把下面片段合入宿主 tsconfig 的 compilerOptions；baseUrl 指向本 tsconfig 所在目录）：
+//   "paths": { "vue-remote/*": ["src/fulgurjs/types/vue-remote.d/*"] }
+// 说明：零配置轨（vue-remote.d.ts 的 ambient 声明）可解析但导出为宽松类型；
+// 配置 paths 后同形态导入解析到本目录的转发模块，获得远程源码级类型精度。

package/examples/templates/vue-vue/host/src/fulgurjs/types/vue-remote.d/pages/DetailPage.ts

@@ -0,0 +1,4 @@
+// 自动生成（精确轨）：.vue expose 为宽松形态（精确类型需宿主 vue-tsc/shim）
+import type { DefineComponent } from 'vue'
+declare const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+export default component

package/examples/templates/vue-vue/host/src/fulgurjs/types/vue-remote.d/pages/HomePage.ts

@@ -0,0 +1,4 @@
+// 自动生成（精确轨）：.vue expose 为宽松形态（精确类型需宿主 vue-tsc/shim）
+import type { DefineComponent } from 'vue'
+declare const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+export default component

package/examples/templates/vue-vue/host/src/fulgurjs/types/vue-remote.d/utils.ts

@@ -0,0 +1,2 @@
+// 自动生成（精确轨）：经 tsconfig paths 解析到本文件后获得源码级类型
+export * from "../../../../../remote/src/exposes/utils"

package/examples/templates/vue-vue/host/src/fulgurjs/types/vue-remote.d.ts

@@ -0,0 +1,29 @@
+// 自动生成：fulgurjs-federation dev 类型直连（remote: vue-remote，mode: source）
+// 重新生成：重启 host dev server
+
+declare module "vue-remote/ClickButton" {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}
+
+declare module "vue-remote/utils" {
+  export const sumNumbers: any
+  export type sumNumbers = any
+  export const formatPrice: any
+  export type formatPrice = any
+  export const DEMO_ANSWER: any
+  export type DEMO_ANSWER = any
+}
+
+declare module "vue-remote/pages/HomePage" {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}
+
+declare module "vue-remote/pages/DetailPage" {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}

package/examples/templates/vue-vue/host/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { federation } from '@fulgurjs/federation'
+import fulgurjsConfig from './fulgurjs.config.ts'
+
+export default defineConfig({
+  plugins: [vue(), federation(fulgurjsConfig)],
+})

package/examples/templates/vue-vue/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "fulgurjs-template-vue-vue",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "dev:remote": "pnpm --dir remote dev",
+    "dev:host": "pnpm --dir host dev",
+    "dev": "node scripts/dev.mjs",
+    "build": "pnpm --dir remote build && pnpm --dir host build"
+  }
+}