create-ax-trusted-plugin 1.0.4 → 1.0.5

package/README.md

@@ -1,7 +1,8 @@
 # create-ax-trusted-plugin
 
 可信(internal)插件**脚手架**:一条命令生成一个基于 `@ax-npm/host-trusted-sdk-v4` 的可信插件骨架
-(Module Federation remote + 共享 Vue + `activate(ctx)` + 自定义元素面板 + 调 `map.flyTo` + 遥测订阅)。
+(默认「形态一」:ESM 直出 `activate` + 自带 Vue + 自定义元素面板 + 调 `map.flyTo` + 遥测订阅;
+dev 走裸 `vite`,原生 sourcemap、无构建步)。
 
 > 脚手架本身已发**公网 npm**,生成这步**零配置**;生成出的工程才走私有源(`192.168.1.209` GitLab)拉
 > `@ax-npm/*` 依赖,届时只需一个 `GITLAB_TOKEN`(无需手建任何 `.npmrc`,工程自带)。
@@ -36,9 +37,9 @@ npm run dev
 锚点可选:`top-left/top-right/top-center/bottom-left/bottom-right/left-center/right-center/center`。
 
 ## 生成内容
-`template/` 经占位替换(`__ID__`/`__TITLE__`/`__ANCHOR__`/`__FED_NAME__`)后落地:`src/{index.ts,Panel.vue,state.ts}`、
-`manifest.json`(trust:internal)、`vite.config.ts`(federation remote)、`serve.mjs`(dev 静态源)、`package.json`、
-`tsconfig.json`、`.npmrc`、`.gitignore`、`README.md`。
+`template/` 经占位替换(`__ID__`/`__TITLE__`/`__ANCHOR__`)后落地:`src/{index.ts,Panel.vue,state.ts}`、
+`manifest.json`(trust:internal、entry:main.js)、`vite.config.ts`(形态一 lib 构建 + dev 市场源桥)、
+`package.json`、`tsconfig.json`、`.npmrc`、`.gitignore`、`README.md`。
 
 ## 发布(维护者)
 脚手架包发**公网 npm**(`publishConfig` 已指向 `registry.npmjs.org`、`access: public`):

package/bin/index.mjs

@@ -87,7 +87,6 @@ async function main() {
       __ID__: id,
       __TITLE__: title,
       __ANCHOR__: anchor,
-      __FED_NAME__: id.replace(/[^a-zA-Z0-9]/g, '_'),
     };
     await scaffold(TEMPLATE, destDir, vars);
 
@@ -100,7 +99,7 @@ async function main() {
     console.log('  $env:GITLAB_TOKEN="<读权限 PAT>"     # PowerShell');
     console.log('  set GITLAB_TOKEN=<读权限 PAT>        # cmd');
     console.log('  npm install');
-    console.log('  npm run dev   # build:watch + 静态托管 + host-dev,浏览器调试\n');
+    console.log('  npm run dev   # 裸 vite(市场源,原生 sourcemap) + host-dev 真宿主,浏览器调试\n');
   } finally {
     rl.close();
   }

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "create-ax-trusted-plugin",
-  "version": "1.0.4",
-  "description": "可信(internal)插件脚手架:一条命令生成一个基于 @ax-npm/host-trusted-sdk-v4 的可信插件骨架(Module Federation remote + 共享 Vue + activate(ctx))。用法:npm create ax-trusted-plugin <id>。生成器本身无机密,公网可装;生成出的工程仍走私有源拉 @ax-npm/* 依赖。",
+  "version": "1.0.5",
+  "description": "可信(internal)插件脚手架:一条命令生成一个基于 @ax-npm/host-trusted-sdk-v4 的可信插件骨架(默认形态一:ESM 直出 activate + 自带 Vue,dev 裸 vite 原生 sourcemap)。用法:npm create ax-trusted-plugin <id>。生成器本身无机密,公网可装;生成出的工程仍走私有源拉 @ax-npm/* 依赖。",
   "type": "module",
   "license": "MIT",
   "keywords": [
     "create-ax-trusted-plugin",
     "scaffold",
-    "module-federation",
     "vue",
     "plugin"
   ],

package/template/README.md

@@ -1,7 +1,7 @@
 # __ID__
 
-可信(internal)插件:经 Module Federation 融入宿主进程、共享宿主 Vue、拿完整 `ctx`。
-由 `create-ax-trusted-plugin` 脚手架生成。
+可信(internal)插件「形态一」:模块直接 `export activate`,壳 `import` 即用;进程内拿完整 `ctx`。
+Vue 打进本插件 bundle(与宿主/其它插件隔离)。由 `create-ax-trusted-plugin` 脚手架生成。
 
 ## 开发
 ```bash
@@ -9,22 +9,25 @@ export GITLAB_TOKEN=<读权限 PAT>           # bash / git-bash
 # $env:GITLAB_TOKEN="<读权限 PAT>"        # PowerShell(别用 set / %VAR%)
 # set GITLAB_TOKEN=<读权限 PAT>           # cmd
 npm install
-npm run dev   # build:watch + serve(:5174) + host-dev(:5173)
+npm run dev   # concurrently: vite(:5174,市场源) + host-dev 真宿主(:5173)
 ```
-浏览器打开 `http://localhost:5173`,锚点出现「__TITLE__」面板。改代码 → 自动重建 → 刷新浏览器。
+浏览器打开 `http://localhost:5173`,锚点出现「__TITLE__」面板。**改代码 → 刷新浏览器即生效**(原生 sourcemap)。
 
-> ⚠️ 可信插件不能用 `vite dev`(federation dev 不产可加载 remoteEntry),故用 `build --watch` + 静态托管。
+> dev 走裸 `vite`:`vite.config.ts` 的 `hostSourceBridge` 把单插件服务伪装成市场源,
+> `/<id>/main.js` 实时转译 `src/index.ts`。多插件并行各自 `vite --port 5175/5176/…`。
 
 ## 构建 / 上架
 ```bash
-npm run build   # → dist/assets/remoteEntry.js
+npm run build   # → dist/main.js(+ main.js.map)
 ```
-把 `dist/` + `manifest.json` 部署到静态源,在宿主市场 `plugins.json` 登记本插件 id 即可加载。
+把 `dist/main.js`(+ `.map`)+ `manifest.json` 部署到静态源,在宿主市场 `plugins.json` 登记本插件 id(及 `baseUrl`)即可加载。
 
 ## 关键约定
-- federation:`exposes:{'./plugin':'./src/index.ts'}` + `shared:['vue','pinia']`(**别设 requiredVersion**)。
-- `manifest.entry` = `assets/remoteEntry.js`,`mfExpose` 与 exposes key 一致(`./plugin`)。
+- 入口 `src/index.ts` 必须 `export function activate(ctx)`(可选 `elementTag`/`deactivate`);`manifest.entry`=`main.js`。
+- `vue({customElement:true})` 把样式注入 shadow root;Vue 自带打包,不与宿主共享。
 - 提供能力须命名空间化(`__ID__/...`)且在 `contributes.capabilities` 声明;消费走 `uses.capabilities`。
 - 插件间不互相 import,只走 `ctx.commands` / `ctx.events`。
 
-完整说明见 `@ax-npm/host-trusted-sdk-v4` 的 README。
+> 需要多个可信插件**共享单例** Vue / 跨边界共享响应式 store,或要省 Vue 体积时,才回退「形态二」
+> (Module Federation):`vite.config` 改用 `@originjs/vite-plugin-federation`、`manifest` 加 `mfExpose`、
+> dev 走 `vite build --watch` + 静态托管。详见 `@ax-npm/host-trusted-sdk-v4` 的 README 与《三角色开发方法.md》。

package/template/manifest.json

@@ -3,8 +3,7 @@
   "version": "0.1.0",
   "trust": "internal",
   "host": "^1.0.0",
-  "entry": "assets/remoteEntry.js",
-  "mfExpose": "./plugin",
+  "entry": "main.js",
   "activationEvents": ["onStartup"],
   "contributes": { "capabilities": ["__ID__/ping"] },
   "uses": { "capabilities": ["map.flyTo"] },

package/template/package.json

@@ -3,13 +3,12 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "可信(internal)插件:经 Module Federation 融入宿主进程、共享 Vue、拿完整 ctx。只依赖 @ax-npm/host-trusted-sdk-v4。",
+  "description": "可信(internal)插件「形态一」:ESM 直出 activate,壳 import 即用、Vue 自带打包(隔离)、拿完整 ctx。dev 走裸 vite(原生 sourcemap、无构建步)。只依赖 @ax-npm/host-trusted-sdk-v4。",
   "scripts": {
     "build": "vue-tsc --noEmit && vite build",
-    "build:watch": "vite build --watch",
-    "serve": "node serve.mjs",
-    "dev": "vite build && concurrently -k -n build,serve,host -c blue,magenta,green \"vite build --watch\" \"node serve.mjs\" \"host-dev --plugin http://localhost:5174\"",
-    "dev:electron": "vite build && concurrently -k -n build,serve,host -c blue,magenta,green \"vite build --watch\" \"node serve.mjs\" \"host-dev --electron --plugin http://localhost:5174\"",
+    "serve": "vite",
+    "dev": "concurrently -k -n plugin,host -c blue,green \"vite\" \"host-dev --plugin http://localhost:5174\"",
+    "dev:electron": "concurrently -k -n plugin,host -c blue,green \"vite\" \"host-dev --electron --plugin http://localhost:5174\"",
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {
@@ -18,11 +17,9 @@
   },
   "devDependencies": {
     "@ax-npm/host-dev-v4": "^1.0.7",
-    "@originjs/vite-plugin-federation": "^1.3.5",
     "@vitejs/plugin-vue": "^5.0.0",
     "concurrently": "^9.0.0",
     "electron": "^39.0.0",
-    "pinia": "^2.1.7",
     "typescript": "^5.4.0",
     "vite": "^5.2.0",
     "vue-tsc": "^2.0.0"

package/template/src/index.ts

@@ -1,5 +1,6 @@
-// 可信插件入口(打成 MF remote 的 expose './plugin')。
-// 宿主经容器协议加载本模块后调 activate(ctx),据 elementTag + manifest.component 挂自定义元素。
+// 可信插件入口「形态一」:本模块直接导出 activate/elementTag(manifest.entry → main.js)。
+// 宿主 loader `import(url)` 命中「直出 activate」分支,调 activate(ctx),据 elementTag +
+// manifest.component 挂自定义元素。(业务代码与形态二一致,只差打包/加载方式。)
 import { definePluginElement, type PluginCtx } from '@ax-npm/host-trusted-sdk-v4';
 import Panel from './Panel.vue';
 import { state, type FcsBasic } from './state';

package/template/vite.config.ts

@@ -1,33 +1,83 @@
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
-import federation from '@originjs/vite-plugin-federation';
+import { fileURLToPath, URL } from 'node:url';
+import { readFileSync } from 'node:fs';
 
-// 可信插件构建:打成 Module Federation remote。
-// - vue({ customElement: true }):SFC 以自定义元素模式编译,样式自动进 shadow root。
-// - federation exposes './plugin' → src/index.ts(导出 activate/elementTag);
-//   shared ['vue','pinia'] 让本插件对 vue/pinia 的引用运行时复用宿主单例。
-//   **不要给 shared 设 requiredVersion**(宿主按首个注册版本提供,无需精确匹配)。
-// 产物 dist/assets/remoteEntry.js 即 manifest.entry 指向的容器。
+// 可信插件「形态一」(ESM 直出 activate)构建。与「形态二」(Module Federation 容器)对比:
+// - 形态一:本模块 import(url) 后**直接导出 activate/elementTag**,壳 loader 命中直出分支。
+//   Vue 打进 bundle(自带依赖,与宿主/其它插件隔离 —— 宿主升级 Vue 波及不到本插件)。
+// - 形态二:打成 federation remoteEntry,运行时与宿主**共享单例** Vue/Pinia。
+// 只经 ctx 交互的内部插件用形态一**功能零损失**,且换来:dev 走裸 `vite`(实时转译、原生
+// sourcemap、无构建步),build 产单文件 `main.js`。仅当需要跨边界共享响应式 store / 省体积
+// 到单份 Vue 时才回退形态二(见 README 与《三角色开发方法.md》)。
 //
-// 可信插件**不能**用 vite dev 调试(federation dev 不产可加载 remoteEntry),
-// 故走 `vite build --watch` + 静态托管 dist(见 serve.mjs / package.json dev)。
+// vue({ customElement: true }):SFC 以自定义元素模式编译,样式自动注入 shadow root,
+// 故无独立 CSS 产物,单个 main.js 即完整插件。
+
+const MANIFEST = JSON.parse(
+  readFileSync(fileURLToPath(new URL('./manifest.json', import.meta.url)), 'utf-8'),
+) as { id: string };
+const PLUGIN_ID = MANIFEST.id;
+
+// —— dev 桥:让「单插件 vite 服务」对外长得像宿主的插件市场源 ——
+// 宿主(LocalRegistry)会请求 /plugins.json、/<id>/manifest.json、/<id>/<entry>。
+// 这里:① /plugins.json = [{ id }];② 把 /<id>/* 重写回 /*(插件本体在根目录);
+//        ③ manifest.entry 是 `main.js`(生产构建产物),dev 无此产物 → 把对它的请求
+//           顶替为 `src/index.ts`,由 vite 实时转译(原生 sourcemap、无构建步)。
+// 这样单跑 `vite` 即可被 harness/host-dev 当市场源加载,改代码刷新即生效。
+function hostSourceBridge() {
+  return {
+    name: 'host-source-bridge',
+    configureServer(server: {
+      middlewares: { use: (fn: (req: any, res: any, next: () => void) => void) => void };
+    }) {
+      server.middlewares.use((req, res, next) => {
+        const url = (req.url || '').split('?')[0];
+        if (url === '/plugins.json') {
+          res.setHeader('content-type', 'application/json');
+          res.setHeader('access-control-allow-origin', '*');
+          res.end(JSON.stringify([{ id: PLUGIN_ID }]));
+          return;
+        }
+        // /<id>/xxx → /xxx(去掉宿主加的 id 前缀)
+        if (req.url === `/${PLUGIN_ID}` || req.url === `/${PLUGIN_ID}/`) {
+          req.url = '/';
+        } else if (req.url && req.url.startsWith(`/${PLUGIN_ID}/`)) {
+          req.url = req.url.slice(PLUGIN_ID.length + 1);
+        }
+        // 形态一 dev:把 main.js 入口请求顶替为可实时转译的源文件。
+        if ((req.url || '').split('?')[0] === '/main.js') req.url = '/src/index.ts';
+        next();
+      });
+    },
+  };
+}
+
 export default defineConfig({
-  plugins: [
-    vue({ customElement: true }),
-    federation({
-      name: '__FED_NAME__',
-      filename: 'remoteEntry.js',
-      exposes: { './plugin': './src/index.ts' },
-      shared: ['vue', 'pinia'],
-    }),
-  ],
+  plugins: [vue({ customElement: true }), hostSourceBridge()],
+  server: {
+    // 活跃集多插件并行时用 `vite --port 5175/5176/…` 覆盖,一份多源 plugins.json 列各端口。
+    port: 5174,
+    strictPort: true,
+    // 宿主(:5180 / app://)跨源拉清单/manifest/入口模块,需放开 CORS。
+    cors: { origin: '*' },
+  },
   build: {
     target: 'esnext',
     outDir: 'dist',
-    // 不清空 outDir:`vite build --watch` 每次重建都会先清空再写,留下一个 remoteEntry.js
-    // 缺失的窗口;若浏览器在该窗口请求 remoteEntry 就会 404、插件激活失败。保留旧产物、
-    // 原地覆盖可消除该窗口(产物文件名带 hash,残留旧 chunk 无害)。
-    emptyOutDir: false,
+    emptyOutDir: true,
+    // 源码级调试可信插件产物:留 sourcemap、不混淆。
+    sourcemap: true,
     minify: false,
+    // library 模式:入口导出(activate/elementTag/deactivate)即模块导出,壳 import(url) 直出。
+    lib: {
+      entry: fileURLToPath(new URL('./src/index.ts', import.meta.url)),
+      formats: ['es'],
+      fileName: () => 'main.js',
+    },
+    rollupOptions: {
+      // 保住入口导出签名,别被当可执行 chunk 摇掉 activate。
+      preserveEntrySignatures: 'strict',
+    },
   },
 });

package/template/index.html

@@ -1,6 +0,0 @@
-<!doctype html>
-<html>
-  <head><meta charset="utf-8" /><title>__ID__ (build entry)</title></head>
-  <!-- 仅作 federation 构建入口;宿主实际加载的是 assets/remoteEntry.js 容器,不是本页。 -->
-  <body></body>
-</html>

package/template/serve.mjs

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-// 零依赖静态服务:把构建产物 dist/ 对外伪装成「宿主插件源」。
-// 宿主会请求 /plugins.json、/<id>/manifest.json、/<id>/assets/remoteEntry.js…
-// 配合 host-dev --plugin http://localhost:5174 调试。改代码 → vite build --watch 自动重建 → 刷新浏览器。
-import { createServer } from 'node:http';
-import { readFile, stat } from 'node:fs/promises';
-import { readFileSync, existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join, normalize, extname, resolve } from 'node:path';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const DIST = resolve(here, 'dist');
-const MANIFEST = JSON.parse(readFileSync(resolve(here, 'manifest.json'), 'utf8'));
-const ID = MANIFEST.id;
-const PORT = Number(process.env.PORT || 5174);
-// 真正决定「插件就绪」的产物 = manifest.entry 指向的 remoteEntry。
-// /plugins.json 的就绪信号必须以它为准,否则 host-dev 会在 dist 尚未产出(或 watch 重建
-// 清空 dist 的窗口内)就判定就绪并开浏览器,导致 remoteEntry 404、插件激活失败。
-const REMOTE_ENTRY = resolve(DIST, MANIFEST.entry || 'assets/remoteEntry.js');
-
-const MIME = {
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.html': 'text/html; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.map': 'application/json; charset=utf-8',
-};
-
-createServer(async (req, res) => {
-  res.setHeader('access-control-allow-origin', '*');
-  const url = (req.url || '/').split('?')[0];
-
-  if (url === '/plugins.json') {
-    // 产物未就绪(首次构建未完成 / watch 重建窗口)时回 503,让 host-dev 的就绪轮询继续等。
-    if (!existsSync(REMOTE_ENTRY)) {
-      res.writeHead(503, { 'content-type': MIME['.json'], 'retry-after': '1' });
-      return res.end(JSON.stringify({ error: 'building', detail: 'remoteEntry 未就绪,等 vite build 完成' }));
-    }
-    res.writeHead(200, { 'content-type': MIME['.json'] });
-    return res.end(JSON.stringify([{ id: ID }]));
-  }
-
-  let rel = url;
-  if (rel === `/${ID}` || rel === `/${ID}/`) rel = '/';
-  else if (rel.startsWith(`/${ID}/`)) rel = rel.slice(ID.length + 1);
-
-  if (rel === '/manifest.json') {
-    res.writeHead(200, { 'content-type': MIME['.json'] });
-    return res.end(JSON.stringify(MANIFEST));
-  }
-
-  let file = normalize(join(DIST, rel));
-  if (file !== DIST && !file.startsWith(DIST + (process.platform === 'win32' ? '\\' : '/'))) {
-    res.writeHead(403);
-    return res.end('forbidden');
-  }
-  try {
-    const s = await stat(file);
-    if (s.isDirectory()) file = join(file, 'index.html');
-  } catch {
-    res.writeHead(404);
-    return res.end('not found (dist 未就绪? 等 vite build --watch 首次完成)');
-  }
-  try {
-    const body = await readFile(file);
-    res.writeHead(200, { 'content-type': MIME[extname(file).toLowerCase()] || 'application/octet-stream' });
-    res.end(body);
-  } catch {
-    res.writeHead(404);
-    res.end('not found');
-  }
-}).listen(PORT, () => {
-  console.log(`[__ID__] 插件源 → http://localhost:${PORT} (id=${ID})`);
-  console.log('[__ID__] 配合 host-dev --plugin http://localhost:' + PORT + ' 调试');
-});