@dsh-workbench/module-tools 0.1.10 → 0.1.11

package/package.json

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

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/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'] },
+});