@international-iot-association/plugin-vite-config 1.0.0-rc.1

package/index.d.mts

@@ -0,0 +1,42 @@
+import type { UserConfig, Plugin } from "vite";
+
+/**
+ * 兼容旧签名保留：本包自身所在的 workspace 根（向上找 pnpm-workspace.yaml，
+ * 找不到则退到本包自身根目录）。resolvePackageRoot 内部不再依赖它。
+ */
+export declare const pluginsMonorepoRoot: string;
+
+/** 解析 npm 包根目录（含 package.json）。 */
+export declare function resolvePackageRoot(name: string, pluginRoot: string): string;
+
+/**
+ * 插件 UI 的共享 Vite 配置（单文件 + React 单例）。
+ * @param configFileUrl 插件 vite.config.ts 的 `import.meta.url`
+ * @param overrides 极少需要；会浅合并进默认配置
+ */
+export declare function definePluginUiViteConfig(
+  configFileUrl: string,
+  overrides?: UserConfig,
+): UserConfig;
+
+/** 开发模式（vite serve）下写入 <meta> 的 CSP。 */
+export declare const DEV_UI_CSP: string;
+
+/** 把 html 里 CSP <meta> 的 content 替换为 DEV_UI_CSP。 */
+export declare function rewriteCspForDev(html: string): string;
+
+/** Vite 插件：仅 serve（`pnpm dev` / 外壳调试页）时替换 CSP meta；build 不生效。 */
+export declare function uiDevCsp(): Plugin;
+
+export type SingleReactAssertion =
+  | { ok: true; versions: string[] }
+  | { ok: false; error: string; versions?: string[] };
+
+/** 从 html 里提取出现过的 react 版本字面量。 */
+export declare function findReactVersionsInHtml(html: string): string[];
+
+/**
+ * 扫描单个插件目录的 ui-dist/index.html，拒绝打进多份 React 的产物。
+ * 纯产物断言，不含「禁 lockfile」检查（那是仓内 monorepo-only 规则）。
+ */
+export declare function assertPluginUiSingleReact(pluginDir: string): SingleReactAssertion;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@international-iot-association/plugin-vite-config",
+  "version": "1.0.0-rc.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/International-IoT-Association/MES.git",
+    "directory": "electron-station-plugins/packages/plugin-vite-config"
+  },
+  "type": "module",
+  "description": "插件 UI 共享 Vite 配置：单文件构建 + React 单例 + dev CSP 适配 + 产物单例断言。",
+  "main": "./src/index.mjs",
+  "types": "./index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.mts"
+  ],
+  "peerDependencies": {
+    "vite": "^7.2.6",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@tailwindcss/vite": "^4.3.1",
+    "tailwindcss": "^4.3.1",
+    "vite-plugin-singlefile": "^2.2.0"
+  },
+  "x-internal-version": "1.0.0",
+  "x-source-revision": "410a2f3b85ef03b678f04f22ea0a47718f5ddae1",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/assert-single-react-ui.mjs

@@ -0,0 +1,59 @@
+/**
+ * 插件 UI 产物单例断言：扫描 ui-dist/index.html，拒绝「打进多份 React」的产物。
+ *
+ * 启发式：统计产物中出现的 react@x.y.z 版本字面量；超过一个不同版本 → fail。
+ *
+ * 注意：仓内「禁止插件目录 pnpm-lock.yaml」是 monorepo-only 规则（根因是与根
+ * pnpm.overrides 分叉），本包只做纯产物断言，不含该检查——它保留在仓内
+ * electron-station-plugins/tools/verify.mjs 的 checkPluginStatic 里。仓外单目录
+ * 打包按定义就是安装根，必然有 lockfile，这条检查放在这里会让仓外打包 100% 失败。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** @returns {string[]} 如 ["19.2.7", "19.2.8"] */
+export function findReactVersionsInHtml(html) {
+  const found = new Set();
+  // 包内 version 字段、source map、error 文案里常见 "19.2.x"
+  const re = /\b(?:react(?:-dom)?@)?(1[89]\.\d+\.\d+)\b/g;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    found.add(m[1]);
+  }
+  // 更稳：package.json 嵌入的 "version":"19.2.8" 靠近 react 上下文
+  const reJson = /"name"\s*:\s*"react"\s*,\s*"version"\s*:\s*"(1[89]\.\d+\.\d+)"/g;
+  while ((m = reJson.exec(html)) !== null) {
+    found.add(m[1]);
+  }
+  return [...found].sort();
+}
+
+/**
+ * @param {string} pluginDir
+ * @returns {{ ok: true, versions: string[] } | { ok: false, error: string, versions?: string[] }}
+ */
+export function assertPluginUiSingleReact(pluginDir) {
+  const uiHtml = join(pluginDir, "ui-dist", "index.html");
+  if (!existsSync(uiHtml)) {
+    // 未构建 UI 的插件（无 vite / 未 build）跳过
+    return { ok: true, versions: [] };
+  }
+
+  const html = readFileSync(uiHtml, "utf8");
+  if (!html.includes("createRoot") && !html.includes("react")) {
+    return { ok: true, versions: [] };
+  }
+
+  const versions = findReactVersionsInHtml(html);
+  if (versions.length > 1) {
+    return {
+      ok: false,
+      versions,
+      error:
+        `${pluginDir}/ui-dist/index.html 打进了多份 React（${versions.join(" + ")}）。` +
+        `会导致 useRef null / 空白页。请用 definePluginUiViteConfig（@international-iot-association/plugin-vite-config），` +
+        `并确保安装根的 React 版本被钉死（overrides / resolutions）后重新 install && build。`,
+    };
+  }
+  return { ok: true, versions };
+}

package/src/define-plugin-ui-vite-config.mjs

@@ -0,0 +1,186 @@
+/**
+ * 插件 UI 的共享 Vite 配置（单文件 + React 单例）。
+ *
+ * 仓内 plugins 与 templates/plugin 下的 vite.config.ts：
+ *
+ *   import { definePluginUiViteConfig } from "../../tools/define-plugin-ui-vite-config.mjs";
+ *   export default definePluginUiViteConfig(import.meta.url);
+ *
+ * 仓外工程：
+ *
+ *   import { definePluginUiViteConfig } from "@international-iot-association/plugin-vite-config";
+ *   export default definePluginUiViteConfig(import.meta.url);
+ *
+ * ## 为什么强制 React 单例
+ * 插件 UI 经 vite-plugin-singlefile 打成单个 index.html。若解析到两份物理 React
+ * （典型：插件目录单独 pnpm install 出 19.2.8，workspace 包用 monorepo 根 19.2.7），
+ * 运行时 hooks dispatcher 为 null → Cannot read properties of null (reading useRef)
+ * → 整页空白。见 tsc-label 2026-08-24 现场。
+ *
+ * 本配置：
+ * 1. resolve.dedupe + alias 钉死 react / react-dom 到同一物理目录；
+ * 2. 优先安装根 hoisted 包，避免插件私有 node_modules 分叉。
+ *
+ * 注意：本文件注释里不要写星号斜杠连续字符（会提前结束块注释）。
+ */
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+import { uiDevCsp } from "./vite-ui-dev-csp.mjs";
+
+const toolsDir = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 兼容旧签名保留：尽量猜测「本包自身」所在的 workspace 根（向上找
+ * pnpm-workspace.yaml），找不到则退到本包自身根目录。
+ *
+ * 注意：resolvePackageRoot 不再用它做候选——本包被 hoist 到哪里，跟消费它的
+ * 插件在哪个 workspace 里，是两件不一定重合的事（本包一旦从 tools/ 迁到
+ * packages/plugin-vite-config/src/，这个常量的相对深度就和插件所在层级脱钩了，
+ * 曾导致 resolvePackageRoot 退化成「就近优先」而不是「monorepo 根优先」）。
+ */
+export const pluginsMonorepoRoot = (() => {
+  let dir = toolsDir;
+  for (;;) {
+    if (existsSync(path.join(dir, "pnpm-workspace.yaml"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(toolsDir, "..");
+    dir = parent;
+  }
+})();
+
+/**
+ * 判断 dir 是否是一个 workspace 根标记目录：pnpm-workspace.yaml，或
+ * package.json 里声明了 workspaces 字段（npm/yarn 风格，兼容两种写法）。
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isWorkspaceRootDir(dir) {
+  if (existsSync(path.join(dir, "pnpm-workspace.yaml"))) return true;
+  const pkgJsonPath = path.join(dir, "package.json");
+  if (!existsSync(pkgJsonPath)) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+    if (Array.isArray(pkg.workspaces)) return true;
+    if (pkg.workspaces && Array.isArray(pkg.workspaces.packages)) return true;
+  } catch {
+    // 解析失败不当作 workspace 根，退到「无标记」分支
+  }
+  return false;
+}
+
+/**
+ * 从 pluginRoot 向上走到 workspace 根（isWorkspaceRootDir 命中的目录，找不到
+ * 则走到文件系统根），返回沿途每一级目录（由近到远）与是否实际命中了标记。
+ * @param {string} startDir
+ * @returns {{ ancestors: string[], foundWorkspaceRoot: boolean }}
+ */
+function collectAncestorsUntilWorkspaceRoot(startDir) {
+  const ancestors = [];
+  let dir = path.resolve(startDir);
+  for (;;) {
+    ancestors.push(dir);
+    if (isWorkspaceRootDir(dir)) return { ancestors, foundWorkspaceRoot: true };
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { ancestors, foundWorkspaceRoot: false };
+}
+
+/**
+ * 解析 npm 包根目录（含 package.json）。
+ *
+ * 顺序：
+ * - 若 pluginRoot 向上能走到一个实际的 workspace 根（pnpm-workspace.yaml 或
+ *   package.json.workspaces），以 workspace 根为起点、由远到近逐层找
+ *   node_modules/<name>（workspace 根优先），不被插件私有分叉版本抢先——这是
+ *   单例门要防的场景。
+ * - 若没有任何 workspace 标记（仓外单目录插件，没有 monorepo 概念），只把
+ *   pluginRoot 自身当唯一候选，不再盲目往上翻——沿途任何无关祖先目录的
+ *   node_modules/<name>（比如用户主目录、上层其它工程）都不该被当作「根」。
+ * - 以上都没找到时退到 Node 的 createRequire 解析算法。
+ *
+ * @param {string} name
+ * @param {string} pluginRoot
+ * @returns {string}
+ */
+export function resolvePackageRoot(name, pluginRoot) {
+  const { ancestors, foundWorkspaceRoot } = collectAncestorsUntilWorkspaceRoot(pluginRoot);
+  const candidates = foundWorkspaceRoot ? ancestors : [ancestors[0]];
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const candidate = path.join(candidates[i], "node_modules", name);
+    if (existsSync(path.join(candidate, "package.json"))) {
+      return path.resolve(candidate);
+    }
+  }
+  const requireFrom = existsSync(path.join(pluginRoot, "package.json"))
+    ? path.join(pluginRoot, "package.json")
+    : import.meta.url;
+  const require = createRequire(requireFrom);
+  return path.dirname(require.resolve(`${name}/package.json`));
+}
+
+/**
+ * @param {string} configFileUrl 插件 vite.config.ts 的 `import.meta.url`
+ * @param {import("vite").UserConfig} [overrides] 极少需要；会浅合并进默认配置
+ */
+export function definePluginUiViteConfig(configFileUrl, overrides = {}) {
+  if (typeof configFileUrl !== "string" || !configFileUrl.includes(":")) {
+    throw new Error(
+      "definePluginUiViteConfig(import.meta.url)：必须传入插件 vite.config 的 import.meta.url",
+    );
+  }
+  const pluginRoot = path.dirname(fileURLToPath(configFileUrl));
+  const reactRoot = resolvePackageRoot("react", pluginRoot);
+  const reactDomRoot = resolvePackageRoot("react-dom", pluginRoot);
+
+  /** @type {import("vite").UserConfig} */
+  const base = {
+    root: "ui",
+    base: "./",
+    plugins: [react(), tailwindcss(), viteSingleFile(), uiDevCsp()],
+    resolve: {
+      dedupe: ["react", "react-dom"],
+      alias: {
+        react: reactRoot,
+        "react-dom": reactDomRoot,
+        "react/jsx-runtime": path.join(reactRoot, "jsx-runtime.js"),
+        "react/jsx-dev-runtime": path.join(reactRoot, "jsx-dev-runtime.js"),
+      },
+    },
+    build: {
+      outDir: "../ui-dist",
+      emptyOutDir: true,
+      chunkSizeWarningLimit: 4096,
+      // Siemens iX 样式内嵌字体/图形必须内联（CSP 无网络）。
+      assetsInlineLimit: 16 * 1024 * 1024,
+    },
+  };
+
+  return defineConfig({
+    ...base,
+    ...overrides,
+    resolve: {
+      ...base.resolve,
+      ...(overrides.resolve ?? {}),
+      dedupe: [
+        ...new Set([...(base.resolve?.dedupe ?? []), ...((overrides.resolve?.dedupe) ?? [])]),
+      ],
+      alias: {
+        ...(base.resolve?.alias ?? {}),
+        ...(overrides.resolve?.alias ?? {}),
+      },
+    },
+    plugins: overrides.plugins ?? base.plugins,
+    build: {
+      ...base.build,
+      ...(overrides.build ?? {}),
+    },
+  });
+}

package/src/index.mjs

@@ -0,0 +1,17 @@
+/**
+ * @international-iot-association/plugin-vite-config —— 统一入口，重新导出三块能力：
+ * - definePluginUiViteConfig / resolvePackageRoot / pluginsMonorepoRoot（共享 vite 配置）
+ * - uiDevCsp / rewriteCspForDev / DEV_UI_CSP（dev 模式 CSP 适配）
+ * - assertPluginUiSingleReact / findReactVersionsInHtml（产物单例断言，纯断言，不含
+ *   「禁 lockfile」检查——那是仓内 monorepo-only 规则，见 verify.mjs 的 checkPluginStatic）
+ */
+export {
+  definePluginUiViteConfig,
+  pluginsMonorepoRoot,
+  resolvePackageRoot,
+} from "./define-plugin-ui-vite-config.mjs";
+export { uiDevCsp, rewriteCspForDev, DEV_UI_CSP } from "./vite-ui-dev-csp.mjs";
+export {
+  assertPluginUiSingleReact,
+  findReactVersionsInHtml,
+} from "./assert-single-react-ui.mjs";

package/src/vite-ui-dev-csp.mjs

@@ -0,0 +1,58 @@
+// packages/plugin-vite-config/src/vite-ui-dev-csp.mjs —— 插件 UI 的 dev 模式 CSP 适配（仅 vite serve 生效）。
+//
+// 背景：ui/index.html 里的 CSP <meta> 是按「构建后单文件、无网络」的产物形态写的：
+// 脚本/样式全部内联（'unsafe-inline'）、connect-src 'none'。但外壳「调试」页走的是
+// vite dev server，页面不再是单文件——module script（/@vite/client、main.tsx …）
+// 要从 dev server 按 URL 加载，HMR 依赖本机 WebSocket。沿用产物形态的 CSP 会把
+// 调试页直接拦成空白（script-src 不含 'self'），或杀掉热更新（connect-src 'none'）。
+//
+// 本插件只在 serve 模式把 <meta> 里的 CSP 换成等价的「开发版」：
+// 脚本/样式放行 'self'（dev server 同源资源），connect 只放行本机 ws/wss（HMR 与
+// vite ping），其余仍然拒绝外部网络——与生产“UI 无网络”的行为保持一致，避免开发期
+// 误写出依赖网络的 UI。build 产物完全不受影响（apply: 'serve'）。
+//
+// 与外壳的关系：正式安装的插件 UI 经 station-plugin:// 提供，外壳会在响应头注入
+// PLUGIN_UI_CSP（见 electron-station-shell/src/main/security.ts），meta 只能更严
+// 不能更松；调试页 iframe 加载的是 http://127.0.0.1:<port>，此时 meta 是唯一的
+// 文档级 CSP，本插件负责让它与 dev server 的加载形态匹配。
+
+/** 开发模式（vite serve）下写入 <meta> 的 CSP。 */
+export const DEV_UI_CSP = [
+  "default-src 'self'",
+  "script-src 'self' 'unsafe-inline'",
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: blob:",
+  "font-src 'self' data:",
+  "media-src 'self' blob: data:",
+  "worker-src blob:",
+  // 仅本机 ws/wss（vite HMR）与同源 fetch（vite ping / 模块加载）；外部网络仍拒绝。
+  "connect-src 'self' ws://127.0.0.1:* ws://localhost:* wss://127.0.0.1:* wss://localhost:*",
+].join("; ");
+
+const CSP_META_RE =
+  /(<meta\s[\s\S]*?http-equiv="Content-Security-Policy"[\s\S]*?content=")([^"]*)(")/i;
+
+/**
+ * 把 html 里 CSP <meta> 的 content 替换为 DEV_UI_CSP。
+ * 没有 CSP <meta> 时原样返回（dev server 页面本就没有文档级 CSP 限制）。
+ * @param {string} html
+ * @returns {string}
+ */
+export function rewriteCspForDev(html) {
+  return html.replace(CSP_META_RE, (_m, pre, _val, post) => `${pre}${DEV_UI_CSP}${post}`);
+}
+
+/**
+ * Vite 插件：仅 serve（`pnpm dev` / 外壳调试页）时替换 CSP meta；build 不生效。
+ * @returns {import("vite").Plugin}
+ */
+export function uiDevCsp() {
+  return {
+    name: "rti-ui-dev-csp",
+    apply: "serve",
+    transformIndexHtml: {
+      order: "pre",
+      handler: (html) => rewriteCspForDev(html),
+    },
+  };
+}