@dsh-workbench/module-tools 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",

package/src/check.mjs

@@ -4,6 +4,7 @@ const CHECKS = {
   bundles: { title: '模块产物边界', load: () => import('./checks/bundles.mjs') },
   source: { title: '模块源码边界', load: () => import('./checks/source.mjs') },
   primitives: { title: 'dsh 原语只从模块表拿', load: () => import('./checks/primitives.mjs') },
+  kit: { title: '外壳 kit 面', load: () => import('./checks/kit.mjs') },
   cards: { title: '卡片渲染', load: () => import('./checks/cards.mjs') },
   standalone: { title: '独立构建', load: () => import('./checks/standalone.mjs') },
   markers: { title: '公开包无内部标识', load: () => import('./checks/markers.mjs') },

package/src/checks/contracts.mjs

@@ -61,8 +61,15 @@ for (const pkg of packages) {
   if (dsh === undefined) continue;
   declared += 1;
 
-  if (dsh.bundle?.patch !== undefined && !existsSync(join(pkg.dir, dsh.bundle.patch))) {
-    problems.push(`${name}: dsh.bundle.patch 指的文件不存在 —— ${dsh.bundle.patch}`);
+  // `dsh.bundle.patch` 允许是**一个字符串，也允许是一个数组**（dsh 自己的 dsh-web-app 就是数组：
+  // 它的 cordis.patch.yml + 四个 preset 文件全挂在这一处）。这里原来只按字符串处理，
+  // 于是第一个用数组的包会把判据**打崩**（ERR_INVALID_ARG_TYPE，堆栈指在 path.join 上，
+  // 而真正的问题是"声明形状没接住"）—— 外壳加 DIY 的 preset 时踩到。
+  const patches = dsh.bundle?.patch;
+  for (const patch of patches === undefined ? [] : Array.isArray(patches) ? patches : [patches]) {
+    if (!existsSync(join(pkg.dir, patch))) {
+      problems.push(`${name}: dsh.bundle.patch 指的 ${patch} 不存在`);
+    }
   }
 
   if (dsh.client !== undefined) {

package/src/checks/kit.mjs

@@ -0,0 +1,183 @@
+// 模块产物从外壳 kit 里取的成员，必须真的在**它承诺给用户的那份外壳**里存在。
+//
+// 起因（2026-10-10 现场）：`module-cmdb@0.1.7` 的产物用了 0.1.8 才有的
+// `kit.components.StateBlock` / `Note` / `Activity*`，而 peer 写的是 `^0.1.4`。
+// 装到旧外壳上：顶层解构不抛（`undefined` 也照样解出来），卡片**首帧渲染**时才炸
+// `Element type is invalid`；外壳里没有错误边界 ⇒ 整块面板被 React 卸掉。
+// 维护者本机复现不了，因为本机 profile 把外壳 `link:` 到本仓（永远 HEAD）。
+//
+// 两条规则：
+//   ① **面差**：产物 bind 的 kit 成员 ⊆ 指定外壳 `client.js` 里那份 kit。
+//      默认用模块包自己装的那份外壳（devDependency）；`DSH_WB_CORE_CLIENT=<路径>`
+//      可以指定别的一份 —— 用它验"对 peer 下限那份外壳会不会红"（发布前该跑一遍）。
+//   ② **下限自洽**：`peerDependencies['@dsh-workbench/core']` 的下限不许低于
+//      `devDependencies` 的下限。你对用户承诺的版本比你自己构建/测试用的还旧时，
+//      产物的面到底够不够，没人验过 —— 这一条就是把"没人验过"变成红灯。
+//      用 `DSH_WB_CORE_CLIENT` 指着下限那份外壳跑（且面差通过）= 验过了，规则②不再报。
+//
+// 判据跟着 `dsh.workbench` 自述清单走；没有 client.js 的包这里没事可查（由 build/契约判据管）。
+
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+
+const SHELL = '@dsh-workbench/core';
+const KIT_SPECIFIER = '@dsh-workbench/core/client';
+
+function kitUsageOf(text) {
+  const bindings = new Set();
+  const BINDING = /(?:var|const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:__toESM\(\s*)?require\(\s*["']@dsh-workbench\/core\/client["']\s*\)/g;
+  for (const match of text.matchAll(BINDING)) bindings.add(match[1]);
+  if (bindings.size === 0) {
+    // 认不出绑定名时不静默放过：退化成"全文里任何 `<id>.kit.` 的 id"。
+    for (const match of text.matchAll(/([A-Za-z_$][\w$]*)\.kit\./g)) bindings.add(match[1]);
+  }
+
+  const used = new Map();
+  const add = (bucket, member) => {
+    if (bucket === undefined || member === undefined || member === '') return;
+    if (!used.has(bucket)) used.set(bucket, new Set());
+    used.get(bucket).add(member);
+  };
+  for (const id of bindings) {
+    const dotted = new RegExp(`\\b${id}\\.kit\\.([a-z]+)\\.([A-Za-z0-9_$]+)`, 'g');
+    for (const match of text.matchAll(dotted)) add(match[1], match[2]);
+    const destructured = new RegExp(`\\{([^{}]*)\\}\\s*=\\s*${id}\\.kit\\.([a-z]+)\\s*;`, 'g');
+    for (const match of text.matchAll(destructured)) {
+      for (const raw of match[1].split(',')) {
+        const name = raw.split(':')[0].trim();
+        if (name !== '') add(match[2], name);
+      }
+    }
+  }
+  return used;
+}
+
+function shellKitOf(clientPath) {
+  const stub = () => null;
+  const seed = new Proxy(
+    { default: stub },
+    { get: (target, key) => (key in target ? target[key] : stub) },
+  );
+  // react 得给一个**能 extends 的类**：外壳自己那段 `class CardBoundary extends Component`
+  // 在工厂体里就跑（错误边界只能这么写），换成箭头函数会当场 "not a constructor"。
+  const react = new Proxy(
+    { default: stub, Component: class {} },
+    { get: (target, key) => (key in target ? target[key] : stub) },
+  );
+  let exports;
+  const load = (registration) => {
+    exports = registration.factory((specifier) => {
+      if (specifier === 'react' || specifier === 'react/jsx-runtime' || specifier === 'react-dom') return react;
+      if (specifier.startsWith('@deepseek-ai/')) return seed;
+      if (specifier === SHELL) return exports;
+      throw new Error(`外壳产物里出现了一个不认识的 require("${specifier}")`);
+    });
+  };
+  const window = { __ModuleLoader__: { load } };
+  // eslint-disable-next-line no-new-func -- 要的就是"按浏览器加载器那样把这份产物跑一遍"，静态解析会骗人
+  new Function('window', readFileSync(clientPath, 'utf8'))(window);
+  return exports?.kit ?? {};
+}
+
+function shellClientPathOf(pkgDir) {
+  const override = process.env.DSH_WB_CORE_CLIENT;
+  if (override !== undefined && override.trim() !== '') return override.trim();
+  try {
+    const require = createRequire(join(pkgDir, 'package.json'));
+    return join(dirname(require.resolve(`${SHELL}/package.json`)), 'client.js');
+  } catch {
+    return undefined;
+  }
+}
+
+function floorOf(range) {
+  if (typeof range !== 'string') return undefined;
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(range);
+  if (match === null) return undefined;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function below(a, b) {
+  for (let at = 0; at < 3; at += 1) {
+    if (a[at] !== b[at]) return a[at] < b[at];
+  }
+  return false;
+}
+
+const problems = [];
+let inspected = 0;
+let noArtifact = 0;
+let noShell = 0;
+const override = process.env.DSH_WB_CORE_CLIENT;
+
+for (const pkg of discoverModulePackages({ root: process.cwd() })) {
+  const name = pkg.manifest.name;
+  const client = join(pkg.dir, 'client.js');
+  if (!existsSync(client)) {
+    noArtifact += 1;
+    continue;
+  }
+  inspected += 1;
+  const text = readFileSync(client, 'utf8');
+  const used = kitUsageOf(text);
+  const uses = used.size > 0 ? text.includes(KIT_SPECIFIER) : false;
+
+  if (uses) {
+    const shellClient = shellClientPathOf(pkg.dir);
+    if (shellClient === undefined || !existsSync(shellClient)) {
+      noShell += 1;
+    } else {
+      let kit;
+      try {
+        kit = shellKitOf(shellClient);
+      } catch (error) {
+        problems.push(
+          `${name}: 取不出这份外壳的 kit（${shellClient}）—— ${error instanceof Error ? error.message : String(error)}。` +
+            `执行产物是这份判据唯一可信的取数方式；看不懂就别放着不管`,
+        );
+        kit = undefined;
+      }
+      if (kit !== undefined) {
+        const missing = [];
+        for (const [bucket, members] of used) {
+          for (const member of [...members].sort()) {
+            if (kit[bucket]?.[member] === undefined) missing.push(`kit.${bucket}.${member}`);
+          }
+        }
+        if (missing.length > 0) {
+          problems.push(
+            `${name}: 产物用了这份外壳（${shellClient}）里没有的 ${missing.join('、')} —— ` +
+              `顶层解构不会抛（拿到 undefined），卡片首帧渲染才炸 "Element type is invalid"，` +
+              `而外壳没有错误边界 ⇒ 整块面板会跟着没。要么去掉/换掉这些成员，要么把 peer 下限提到真正需要的那版`,
+          );
+        }
+      }
+    }
+  }
+
+  const peerFloor = floorOf(pkg.manifest.peerDependencies?.[SHELL]);
+  const devFloor = floorOf(pkg.manifest.devDependencies?.[SHELL]);
+  if (peerFloor !== undefined && devFloor !== undefined && below(peerFloor, devFloor) && override === undefined) {
+    problems.push(
+      `${name}: peer 下限 ${pkg.manifest.peerDependencies[SHELL]} 比 devDependency ${pkg.manifest.devDependencies[SHELL]} 还旧 —— ` +
+        `你对用户承诺的那版外壳，产物从没对着验过。把 peer 下限提到与 devDependency 同档；` +
+        `确实要支持更旧的外壳，就用 DSH_WB_CORE_CLIENT=<那版外壳的 client.js> 跑一遍 check --only kit 证明面够用`,
+    );
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ 外壳 kit 面 ${problems.length} 条不过：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+
+const notes = [
+  `${inspected} 个模块的产物对过外壳 kit 面`,
+  override === undefined ? '（按各自装的那份外壳）' : `（DSH_WB_CORE_CLIENT=${override}）`,
+];
+if (noArtifact > 0) notes.push(`${noArtifact} 个还没建产物（跳过）`);
+if (noShell > 0) notes.push(`${noShell} 个没装外壳（跳过面差）`);
+console.log(`✔ 外壳 kit 面通过：${notes.join(' · ')}`);

package/src/checks/standalone.mjs

@@ -6,60 +6,64 @@ import { discoverModulePackages, discoverPackages } from '../discover.mjs';
 const SHELL = '@dsh-workbench/core';
 
 const shell = discoverPackages({ root: process.cwd() }).find((pkg) => pkg.manifest.name === SHELL);
-if (shell === undefined || !existsSync(join(shell.dir, 'src'))) {
-  console.log(`✔ 独立构建：本仓没有 ${SHELL} 的源码（模块侧靠"不许 @/ 指外壳"那条判据守）`);
-  process.exit(0);
+const visible = shell === undefined ? undefined : join(shell.dir, 'src');
+
+if (visible === undefined || !existsSync(visible)) {
+  console.log(`✔ 独立构建：跳过 —— 本仓没有 ${SHELL} 的源码（"不许 @/ 指外壳"那条判据照旧在守）`);
+} else {
+  runStandalone(visible);
 }
 
-const modules = discoverModulePackages({ root: process.cwd() });
-const visible = join(shell.dir, 'src');
-const hidden = join(shell.dir, 'src.hidden');
+function runStandalone(visible) {
+  const modules = discoverModulePackages({ root: process.cwd() });
+  const hidden = join(shell.dir, 'src.hidden');
 
-const restore = () => {
-  if (existsSync(hidden) && !existsSync(visible)) renameSync(hidden, visible);
-};
-process.on('SIGINT', () => {
-  restore();
-  process.exit(130);
-});
+  const restore = () => {
+    if (existsSync(hidden) && !existsSync(visible)) renameSync(hidden, visible);
+  };
+  process.on('SIGINT', () => {
+    restore();
+    process.exit(130);
+  });
 
-if (existsSync(hidden)) {
-  console.error(`上次没还原干净：${hidden} 还在，手动改名回去再跑。`);
-  process.exit(1);
-}
+  if (existsSync(hidden)) {
+    console.error(`上次没还原干净：${hidden} 还在，手动改名回去再跑。`);
+    process.exit(1);
+  }
 
-const rows = [];
-const problems = [];
-renameSync(visible, hidden);
-try {
-  for (const pkg of modules) {
-    const name = pkg.manifest.name;
-    for (const script of ['build', 'typecheck']) {
-      if (pkg.manifest.scripts?.[script] === undefined) continue;
-      try {
-        execFileSync('pnpm', ['run', script], { cwd: pkg.dir, stdio: 'pipe' });
-        rows.push(`${name} ${script}: ✅`);
-      } catch (error) {
-        const output = `${error.stdout ?? ''}${error.stderr ?? ''}`;
-        const first = output
-          .split('\n')
-          .filter((line) => /error|Cannot find|Could not resolve|ERR_/.test(line))
-          .slice(0, 2)
-          .map((line) => line.trim())
-          .join(' | ');
-        rows.push(`${name} ${script}: ❌`);
-        problems.push(`${name} ${script} 在外壳源码不在场时失败 —— ${first.slice(0, 220)}`);
+  const rows = [];
+  const problems = [];
+  renameSync(visible, hidden);
+  try {
+    for (const pkg of modules) {
+      const name = pkg.manifest.name;
+      for (const script of ['build', 'typecheck']) {
+        if (pkg.manifest.scripts?.[script] === undefined) continue;
+        try {
+          execFileSync('pnpm', ['run', script], { cwd: pkg.dir, stdio: 'pipe' });
+          rows.push(`${name} ${script}: ✅`);
+        } catch (error) {
+          const output = `${error.stdout ?? ''}${error.stderr ?? ''}`;
+          const first = output
+            .split('\n')
+            .filter((line) => /error|Cannot find|Could not resolve|ERR_/.test(line))
+            .slice(0, 2)
+            .map((line) => line.trim())
+            .join(' | ');
+          rows.push(`${name} ${script}: ❌`);
+          problems.push(`${name} ${script} 在外壳源码不在场时失败 —— ${first.slice(0, 220)}`);
+        }
       }
     }
+  } finally {
+    restore();
   }
-} finally {
-  restore();
-}
 
-if (problems.length > 0) {
-  console.error(`✖ 独立构建 ${problems.length} 条不过：`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  console.error('  （上面的清单就是"发布出去会散架"的地方：模块只许依赖已发布的接口）');
-  process.exit(1);
+  if (problems.length > 0) {
+    console.error(`✖ 独立构建 ${problems.length} 条不过：`);
+    for (const problem of problems) console.error(`  · ${problem}`);
+    console.error('  （上面的清单就是"发布出去会散架"的地方：模块只许依赖已发布的接口）');
+    process.exit(1);
+  }
+  console.log(`✔ 独立构建通过：${modules.length} 个模块包在外壳源码不在场时都能 build + typecheck`);
 }
-console.log(`✔ 独立构建通过：${modules.length} 个模块包在外壳源码不在场时都能 build + typecheck`);

package/src/init.mjs

@@ -2,14 +2,25 @@ import { cpSync, existsSync, readFileSync, readdirSync, rmSync, writeFileSync }
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const TEMPLATE = fileURLToPath(new URL('../template', import.meta.url));
+const TEMPLATES = {
+  minimal: '../template',
+  diy: '../template-diy',
+};
 const UNIT_ID = /^[a-z][a-z0-9-]*$/;
 
 export async function init({ root, args = [] }) {
   const unit = args[0];
   if (unit === undefined || !UNIT_ID.test(unit)) {
-    console.error('用法：dsh-wb-module init <unit> [--dir <目录>] [--description <文字>]');
+    console.error('用法：dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]');
     console.error('  unit 是小写短横线标识（它同时是单元 id、包名后缀、卡片 class 前缀）');
+    console.error('  --template diy：带一个真数据源 + 三态 + ?wbMock=1 夹具的样板（默认 minimal 是空壳）');
+    process.exit(2);
+  }
+  const picked = args[args.indexOf('--template') + 1];
+  const which = args.includes('--template') ? picked : 'minimal';
+  const template = TEMPLATES[which];
+  if (template === undefined) {
+    console.error(`不认识的模板：${String(which)}（可用：${Object.keys(TEMPLATES).join(' / ')}）`);
     process.exit(2);
   }
   const at = args.indexOf('--dir');
@@ -26,7 +37,12 @@ export async function init({ root, args = [] }) {
     __DESC__: description,
   };
   const fill = (text) => text.replace(/__[A-Z]+__/g, (token) => tokens[token] ?? token);
-  cpSync(TEMPLATE, target, { recursive: true });
+  const templateDir = fileURLToPath(new URL(template, import.meta.url));
+  if (!existsSync(templateDir)) {
+    console.error(`模板 ${which} 的目录不在：${templateDir}`);
+    process.exit(2);
+  }
+  cpSync(templateDir, target, { recursive: true });
   const walk = (dir) => {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       const full = join(dir, entry.name);
@@ -44,5 +60,5 @@ export async function init({ root, args = [] }) {
     }
   };
   walk(target);
-  console.log(`${target} 建好了：${unit} 模块骨架（build / check / selfcheck 已接工具）`);
+  console.log(`${target} 建好了：${unit} 模块骨架（模板 ${which}；build / check / selfcheck 已接工具）`);
 }

package/template/README.md.tpl

@@ -4,7 +4,17 @@
 
 ```bash
 dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
-dsh-wb-module check     # 契约 / 产物边界 / 源码边界 / 卡片渲染
+dsh-wb-module check     # 契约 / 产物边界 / 源码边界 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳
+dsh-wb-module check --only cards   # 十条可以单跑
+```
+
+包自带的四个脚本（`check` 的契约判据要求它们都在）：
+
+```bash
+pnpm build        # 构建产物
+pnpm typecheck    # tsc --noEmit
+pnpm test         # vitest（src/**/*.test.ts）
+pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍，看卡片真进没进外壳
 ```
 
 装进本地工作台：
@@ -15,4 +25,8 @@ dsh plugin --profile workbench add <本目录>
 
 面板只读、写入只走 agent 工具；共享代码从 `@dsh-workbench/shared` 拿，
 单例机制（hooks / 容器组件 / 读缝）只能从 `@dsh-workbench/core/client` 的 kit 拿。
-要发布：把 `package.json` 里的 `private` 去掉、按需改 `publishConfig`。
+dsh 已有的组件与样式**先从 kit 拿**，别从 DOM + CSS 重画。
+
+要发布：把 `package.json` 里的 `private` 去掉，并显式写上发布目标
+（`publishConfig.access: "public"` 或指向内网源的 `publishConfig.registry`）——
+`private: true` 的包不许发到任何源，这是刻意的默认。

package/template/package.json.tpl

@@ -13,7 +13,7 @@
     "build": "dsh-wb-module build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "selfcheck": "dsh-wb-module build && dsh-wb-module check",
+    "selfcheck": "dsh-wb-module build && node scripts/smoke.mjs",
     "prepack": "dsh-wb-module build"
   },
   "dsh": {
@@ -38,6 +38,5 @@
     "react": "^19.3.0",
     "typescript": "5.9",
     "vitest": "^5.0.2"
-  },
-  "publishConfig": { "access": "public" }
+  }
 }

package/template/scripts/smoke.mjs.tpl

@@ -0,0 +1,94 @@
+// 模块包的接线自检：把 client.js 当成浏览器里的加载器那样跑一遍。
+//
+// 为什么值得有：宿主侧挂没挂上，curl /panels 就能看见；浏览器侧挂没挂上，过去只能靠"刷个页面看看"。
+// 这个脚本复刻 dsh 加载器的**契约**（`window.__ModuleLoader__.load({ id, factory })` + `factory(require)`），
+// 于是"模块注册的卡片到底进没进外壳"变成一条机器判据，而不再是人的眼睛。
+//
+// 负例在最后一段：服务不在的时候必须**报出来**，不许静默通过 —— 静默的模块是最难查的那种坏。
+
+const PLUGIN_ID = '__NAME__';
+const UNIT_ID = '__UNIT__';
+const failures = [];
+
+function check(name, ok, detail) {
+  if (ok) {
+    console.log(`✅ ${name}`);
+    return;
+  }
+  failures.push(name);
+  console.log(`❌ ${name}${detail === undefined ? '' : ` —— ${detail}`}`);
+}
+
+function moduleRequire(name) {
+  if (name === 'react') return { createElement: () => null };
+  if (name === '@dsh-workbench/core/client') return { kit: { components: { Card: () => null } } };
+  throw new Error(`模块包不该 require ${JSON.stringify(name)}：模块表里只有外壳的 seed 词与外部声明`);
+}
+
+let boot = null;
+globalThis.window = {
+  __ModuleLoader__: {
+    load(entry) {
+      boot = entry;
+    },
+  },
+};
+
+await import(new URL('../client.js', import.meta.url).href);
+
+check('client.js 调用 __ModuleLoader__.load()', boot !== null);
+check('模块 id 等于包名', boot?.id === PLUGIN_ID, boot?.id);
+if (boot === null) {
+  console.error(`\n${failures.length} 条没过`);
+  process.exit(1);
+}
+
+const pluginExports = boot.factory(moduleRequire);
+check(
+  '注入 workbenchUnits（外壳交出来的那个服务名）',
+  Array.isArray(pluginExports.inject) && pluginExports.inject.includes('workbenchUnits'),
+  String(pluginExports.inject),
+);
+check('导出了 apply', typeof pluginExports.apply === 'function');
+
+const faces = [];
+const ctx = {
+  get: (name) =>
+    name === 'workbenchUnits'
+      ? {
+          registerUnit(face) {
+            faces.push(face);
+            return () => {};
+          },
+        }
+      : undefined,
+  effect: (fn) => {
+    fn();
+  },
+};
+
+pluginExports.apply(ctx);
+check('卡片真的注册进了外壳', faces.length === 1, `注册了 ${faces.length} 个`);
+check(`注册的是 ${UNIT_ID} 单元`, faces[0]?.manifest.id === UNIT_ID, faces[0]?.manifest.id);
+check('卡片是个能画的组件', typeof faces[0]?.card === 'function');
+check('卡片自己带标题与顺序（外壳的看板据此排）', faces[0]?.manifest.card?.order === 90);
+
+const warnings = [];
+const realWarn = console.warn;
+console.warn = (...args) => warnings.push(args.join(' '));
+pluginExports.apply({
+  get: () => undefined,
+  effect: (fn) => {
+    fn();
+  },
+});
+console.warn = realWarn;
+
+check(
+  '负例：外壳没交服务时必须报出来（不许静默通过）',
+  warnings.some((line) => line.includes('workbenchUnits')),
+  warnings.join(' | '),
+);
+
+console.log(`\n${failures.length === 0 ? '模块自检通过' : `${failures.length} 条没过`}`);
+if (failures.length > 0) process.exit(1);

package/template/src/client.tsx.tpl

@@ -1,27 +1,73 @@
 import { createElement as h } from 'react';
+import { kit } from '@dsh-workbench/core/client';
+import { messages } from './messages';
 
 const UNIT_ID = '__UNIT__';
 
+interface UnitManifest {
+  readonly id: string;
+  readonly kind: string;
+  readonly card: {
+    readonly titleKey: string;
+    readonly order: number;
+    readonly enabledByDefault: boolean;
+  } | null;
+  readonly tools: readonly unknown[];
+  readonly host: { readonly inject: readonly string[] };
+}
+
+type Rendered = ReturnType<typeof h>;
+type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+interface UnitClientFace {
+  readonly manifest: UnitManifest;
+  readonly messages: { readonly zh: Readonly<Record<string, string>>; readonly en: Readonly<Record<string, string>> };
+  readonly card: (props: { readonly t: Translate; readonly onRefresh: () => void }) => Rendered;
+}
+
+interface UnitClientApi {
+  registerUnit(face: UnitClientFace): () => void;
+}
+
+interface ClientContext {
+  get<T = unknown>(name: string): T | undefined;
+  effect(effect: () => void | (() => void), label?: string): () => void;
+}
+
+const manifest: UnitManifest = {
+  id: UNIT_ID,
+  kind: 'board',
+  card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
+  tools: [],
+  host: { inject: [] },
+};
+
+const face: UnitClientFace = {
+  manifest,
+  messages,
+  card: (props) => {
+    const { Card } = kit.components;
+    return h(
+      Card,
+      {
+        t: props.t,
+        title: props.t(`${UNIT_ID}.cardTitle`),
+        refreshing: false,
+        onRefresh: props.onRefresh,
+      },
+      h('p', null, props.t(`${UNIT_ID}.heading`)),
+      h('p', null, props.t(`${UNIT_ID}.body`)),
+    );
+  },
+};
+
 export const inject = ['workbenchUnits'];
 
-export function apply(ctx) {
-  const units = ctx.get('workbenchUnits');
+export function apply(ctx: ClientContext): void {
+  const units = ctx.get<UnitClientApi>('workbenchUnits');
   if (units === undefined) {
     console.warn(`[${UNIT_ID}] 外壳没有提供 workbenchUnits 服务：这张卡片装不进来`);
     return;
   }
-  ctx.effect(
-    () =>
-      units.registerUnit({
-        manifest: {
-          id: UNIT_ID,
-          kind: 'board',
-          card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
-          tools: [],
-          host: { inject: [] },
-        },
-        card: () => h('section', { className: `wb-${UNIT_ID}` }, h('h2', null, `${UNIT_ID}`)),
-      }),
-    `${UNIT_ID}: 注册`,
-  );
+  ctx.effect(() => units.registerUnit(face), `__NAME__: 注册 ${UNIT_ID}`);
 }

package/template/src/host.ts.tpl

@@ -4,24 +4,51 @@ export const name = '__NAME__';
 
 export const inject = ['workbenchUnits'];
 
-export function apply(ctx) {
-  const units = ctx.get('workbenchUnits');
+interface UnitManifest {
+  readonly id: string;
+  readonly kind: string;
+  readonly card: {
+    readonly titleKey: string;
+    readonly order: number;
+    readonly enabledByDefault: boolean;
+  } | null;
+  readonly tools: readonly unknown[];
+  readonly host: { readonly inject: readonly string[] };
+}
+
+interface UnitHostFace {
+  readonly manifest: UnitManifest;
+  mount(): { routes: Record<string, never>; registerTools(): Array<() => void> };
+}
+
+interface UnitRegistry {
+  register(face: UnitHostFace): () => void;
+}
+
+interface HostContext {
+  get<T = unknown>(name: string): T | undefined;
+  effect(effect: () => void | (() => void), label?: string): () => void;
+  logger?: { warn?(message: string): void } | undefined;
+}
+
+const manifest: UnitManifest = {
+  id: UNIT_ID,
+  kind: 'board',
+  card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
+  tools: [],
+  host: { inject: [] },
+};
+
+const face: UnitHostFace = {
+  manifest,
+  mount: () => ({ routes: {}, registerTools: () => [] }),
+};
+
+export function apply(ctx: HostContext): void {
+  const units = ctx.get<UnitRegistry>('workbenchUnits');
   if (units === undefined) {
     ctx.logger?.warn?.(`[${UNIT_ID}] 外壳没有提供 workbenchUnits 服务：这个模块装不进来`);
     return;
   }
-  ctx.effect(
-    () =>
-      units.register({
-        manifest: {
-          id: UNIT_ID,
-          kind: 'board',
-          card: { titleKey: `${UNIT_ID}.cardTitle`, order: 90, enabledByDefault: true },
-          tools: [],
-          host: { inject: [] },
-        },
-        mount: () => ({ routes: {}, registerTools: () => [] }),
-      }),
-    `${UNIT_ID}: 注册`,
-  );
+  ctx.effect(() => units.register(face), `__NAME__: 注册 ${UNIT_ID}`);
 }

package/template/src/messages.ts.tpl

@@ -0,0 +1,12 @@
+export const messages = {
+  zh: {
+    '__UNIT__.cardTitle': '新模块',
+    '__UNIT__.heading': '这张卡还是空的',
+    '__UNIT__.body': '改 src/client.tsx 画你要的内容，然后跑 dsh-wb-module build。',
+  },
+  en: {
+    '__UNIT__.cardTitle': 'New module',
+    '__UNIT__.heading': 'This card is still empty',
+    '__UNIT__.body': 'Edit src/client.tsx to render what you need, then run dsh-wb-module build.',
+  },
+};

package/template/src/plugin.test.ts.tpl

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+import { apply, inject, name } from './host';
+import { apply as applyClient, inject as injectClient } from './client';
+
+vi.mock('@dsh-workbench/core/client', () => ({
+  kit: { components: { Card: () => null } },
+}));
+
+function fakeCtx(service: unknown) {
+  const faces: unknown[] = [];
+  return {
+    faces,
+    ctx: {
+      get: () => service,
+      effect: (effect: () => void | (() => void)) => {
+        effect();
+        return () => {};
+      },
+    },
+  };
+}
+
+describe('__NAME__ 的面', () => {
+  it('插件名就是包名', () => {
+    expect(name).toBe('__NAME__');
+  });
+
+  it('两侧都只注入外壳交出来的那个服务', () => {
+    expect(inject).toEqual(['workbenchUnits']);
+    expect(injectClient).toEqual(['workbenchUnits']);
+  });
+
+  it('宿主半侧把自己的面注册进外壳', () => {
+    const { ctx, faces } = fakeCtx({
+      register: (face: unknown) => {
+        faces.push(face);
+        return () => {};
+      },
+    });
+    apply(ctx as never);
+    expect(faces).toHaveLength(1);
+    expect((faces[0] as { manifest: { id: string } }).manifest.id).toBe('__UNIT__');
+  });
+
+  it('浏览器半侧把自己的卡片注册进外壳', () => {
+    const { ctx, faces } = fakeCtx({
+      registerUnit: (face: unknown) => {
+        faces.push(face);
+        return () => {};
+      },
+    });
+    applyClient(ctx as never);
+    expect(faces).toHaveLength(1);
+  });
+});

package/template/tsconfig.json

@@ -14,7 +14,7 @@
     "skipLibCheck": true,
     "isolatedModules": true,
     "verbatimModuleSyntax": true,
-    "paths": { "@/modules/__UNIT__/*": ["src/*"] }
+    "paths": { "@/modules/__UNIT__/*": ["./src/*"] }
   },
   "include": ["src/**/*.ts", "src/**/*.tsx", "types/**/*.d.ts"]
 }

package/template/vitest.config.ts

@@ -0,0 +1,14 @@
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+const here = (relative: string): string => fileURLToPath(new URL(relative, import.meta.url));
+
+export default defineConfig({
+  resolve: {
+    alias: [
+      { find: /^@\/modules\/__UNIT__\//, replacement: `${here('./src')}/` },
+      { find: /^@\/platforms\/[^/]+\//, replacement: `${here('./src/platforms')}/` },
+    ],
+  },
+  test: { environment: 'node', include: ['src/**/*.test.ts', 'src/**/*.test.tsx'] },
+});