@dsh-workbench/module-tools 0.1.14 → 0.1.16

package/README.md

@@ -0,0 +1,71 @@
+# @dsh-workbench/module-tools
+
+工作台**模块的工具箱**：建骨架、构建、过门禁、管三张表、发货前核清单。
+模块作者（以及替用户造模块的 agent）只跟这几条命令打交道。
+
+## 命令
+
+```bash
+dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description "一句话"]
+dsh-wb-module build                 # 出 dist/host.js 与套了 loader 壳的 client.js
+dsh-wb-module check [--only <判据>]  # 十条判据；--only 可以单跑
+dsh-wb-module design <init|check|render|accept>
+dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 + npm pack 清单（只 dry run）
+```
+
+`--cwd <目录>` 指定包目录（默认当前目录）。模块目录里更省事的是骨架自带的脚本：
+`pnpm build` / `pnpm typecheck` / `pnpm test` / `pnpm selfcheck` / `pnpm design`。
+
+## 十条判据（`check`）
+
+| 判据 | 盯什么 |
+|---|---|
+| `contracts` | 模块契约：单元 id 唯一、两个面、四个脚本、`files`、peer 下限 |
+| `bundles` | 产物边界：宿主面里不许出现浏览器侧的东西 |
+| `source` | 源码边界：不直接引 dsh 的包、不引不是种子词的 `@deepseek-ai/*` |
+| `primitives` | dsh 原语只从模块表（`kit`）拿 |
+| `kit` | 这份外壳的 kit 成员到底有哪些（缺什么会当场点名） |
+| `cards` | 卡片渲染：五态都要画得出来，空数据不许抛 |
+| `standalone` | 独立构建：产物不依赖工坊里跑 |
+| `markers` | 公开包无内部标识（内网域名、企业内部名） |
+| `style` | 样式归属：模块不许定义外壳前缀（`wb-*`）的规则 |
+| `alias` | 模块不指外壳：源码里没有指向外壳 `@/` 的引用 |
+
+三态输出：`✔ 通过` / `○ 不适用` / `✖ 不过`；有任何不过就退出 1。
+
+## 三张表：`design.json`
+
+三张表（面板 / 能力 / 联动）+ 状态矩阵 + 数据源记录 + 验收清单住在模块根目录的 `design.json`，
+README 里那一段由它生成（夹在 `<!-- dsh-wb:design:start/end -->` 之间）。
+
+```bash
+dsh-wb-module design check    # 空着的格一格格点名叫出来 + README 有没有落后
+dsh-wb-module design render   # 用 design.json 重新生成 README 那一段
+dsh-wb-module design accept   # 用户逐条点头之后，把验收清单打勾
+```
+
+## 两个模板
+
+| 模板 | 是什么 |
+|---|---|
+| `minimal`（默认） | 空壳：卡壳、文案、测试接好了，没有数据源 |
+| `diy` | 一份真能跑的样板：宿主侧一条只读路由真读盘、卡片五态、`?wbMock=1` 三档夹具，**三张表也是填好的** |
+
+`init` 会连模板里的 `*.tpl` 一起拷过去、把 `__UNIT__` / `__NAME__` / `__DESC__` 填上、剥掉 `.tpl` 后缀，
+再用 `design.json` 生成 README 那一段。
+
+## 自己的自检
+
+```bash
+node scripts/selfcheck.mjs
+```
+
+工具箱的回归网：两个模板各 `init` 一遍、各跑全套（门禁 + 五个脚本）；判据的**正例与负例**都要对；
+打包清单不含 `.tpl` 残留；`design` 的空格、README 同步、`accept`；`publish` 的清单。
+
+## 去哪看"为什么"
+
+模块怎么写、DIY 那套流程怎么走，见外壳包里的指引：`@dsh-workbench/core` 的
+`skills/workbench-module-diy/**`（`SKILL.md` / `BUILD.md` / `WIRING.md` / `DESIGN.md` / `PANEL.md` /
+`TOOLS.md` / `LINKAGE.md` / `DATASOURCE.md` / `REVIEW.md` / `TOOLING.md` / `STEPS.md`）。
+架构上的取舍写在工作台仓库的 `docs/adr/**`。

package/bin/dsh-wb-module.mjs

@@ -2,15 +2,17 @@
 import { resolve } from 'node:path';
 import { build } from '../src/build.mjs';
 import { check } from '../src/check.mjs';
+import { design } from '../src/design.mjs';
 import { init } from '../src/init.mjs';
+import { publish } from '../src/publish.mjs';
 
 const [command, ...rest] = process.argv.slice(2);
 const cwd = process.env.DSH_WB_MODULE_CWD ?? process.cwd();
 
-const commands = { build, check, init };
+const commands = { build, check, init, design, publish };
 
 if (!command || !commands[command]) {
-  console.error('用法：dsh-wb-module <build|check|init> [--cwd <目录>] [--only contracts|bundles|source|cards]\n      dsh-wb-module init <unit> [--dir <目录>] [--description <文字>]');
+  console.error('用法：dsh-wb-module <build|check|init|design|publish> [--cwd <目录>]\n      dsh-wb-module check [--only contracts|bundles|source|primitives|kit|cards|standalone|markers|style|alias]\n      dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]\n      dsh-wb-module design <init|check|render|accept>   # 三张表：填、查空格、生成 README、验收打勾\n      dsh-wb-module publish                              # 发货前的清单：门禁 + npm pack 清单 + files 漏项（只 dry run）');
   process.exit(2);
 }
 

package/package.json

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

package/src/build.mjs

@@ -5,6 +5,7 @@ import { builtinModules } from 'node:module';
 import { isAbsolute, join, relative } from 'node:path';
 import { build as esbuild } from 'esbuild';
 import { SEED_SPECIFIERS } from './seed.mjs';
+import { cssInjectionCode } from './css-injection.mjs';
 
 const SHELL_CLIENT = '@dsh-workbench/core/client';
 const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.json'];
@@ -102,17 +103,7 @@ function cssInjector({ root }) {
         }
         return {
           loader: 'js',
-          contents: [
-            `const css = ${JSON.stringify(css)};`,
-            `const key = ${JSON.stringify(key)};`,
-            "if (typeof document !== 'undefined' && document.querySelector('style[data-dsh-wb-css=\"' + key + '\"]') === null) {",
-            "  const style = document.createElement('style');",
-            "  style.setAttribute('data-dsh-wb-css', key);",
-            "  style.textContent = css;",
-            "  document.head.appendChild(style);",
-            "}",
-            `export default ${map};`,
-          ].join('\n'),
+          contents: [`${cssInjectionCode(key, css)}`, `export default ${map};`].join('\n'),
         };
       });
     },

package/src/check.mjs

@@ -1,5 +1,28 @@
+// 十条判据的**聚合层**：跑、收集三态、打印、决定退出码。
+//
+// ── 为什么判据改成"导出函数"，打印与退出码都搬到这里 ──────────────────────────
+//
+// 在这之前，每条 `checks/*.mjs` 都是"import 即执行 + 自己 console.log + 自己 process.exit"
+// 的脚本。那样"不适用"就没有一等形状 —— 只能靠"这条判据不许 exit(0)"这条**纪律**维持：
+// 谁哪天写个 `process.exit(0)`，排在它后面的判据就静默不跑，而屏幕看着还是全绿
+// （standalone 在仓外工作区就是这么吞掉 markers / style / alias 三条的，见
+// `.scratch/workbench-diy/spec.md` §20）。
+//
+// 另一件后果是聚合层拿不到"跑了哪些、跳了哪些、为什么跳"，只能看判据自己打的字。
+//
+// 新形状：每条判据导出 `run()`，返回
+//     { status: 'pass' | 'fail' | 'skip', notes: string[], problems: string[] }
+// ——"不适用"于是是一等结果，而**截断在形状上就不可能**：
+// 判据手里没有 exit，退出码只有这一层按汇总给。
+//
+// 打印形状（三态，稳定）：
+//     通过   ✔ <title>：<notes 拼起来>
+//     不适用 ○ <title>：（不适用）<notes>
+//     失败   ✖ <title> <N> 条不过：  然后逐条 `  · <problem>`
+// 最后一行是汇总；有任何 fail 就 exit 1。
 
-const CHECKS = {
+// 十个名字与 title 一字不变 —— selfcheck 会把它与各判据模块导出的 `title` 逐个对一遍。
+export const CHECKS = {
   contracts: { title: '模块契约', load: () => import('./checks/contracts.mjs') },
   bundles: { title: '模块产物边界', load: () => import('./checks/bundles.mjs') },
   source: { title: '模块源码边界', load: () => import('./checks/source.mjs') },
@@ -12,14 +35,72 @@ const CHECKS = {
   alias: { title: '模块不指外壳', load: () => import('./checks/alias.mjs') },
 };
 
+/** 判据只许回这三态；聚合层的打印与汇总都按它分支。 */
+const STATES = ['pass', 'fail', 'skip'];
+
+/** 一屏一条：三态各一种前缀，notes 的第一条跟在标题后面，其余各占一行。 */
+function report(title, result) {
+  const notes = Array.isArray(result.notes) ? result.notes : [];
+  if (result.status === 'fail') {
+    const problems = Array.isArray(result.problems) ? result.problems : [];
+    console.log(`✖ ${title} ${problems.length} 条不过：`);
+    for (const problem of problems) console.log(`  · ${problem}`);
+    for (const note of notes) console.log(`  ${note}`);
+    return;
+  }
+  if (result.status === 'skip') {
+    console.log(`○ ${title}：（不适用）${notes[0] ?? ''}`);
+  } else {
+    console.log(`✔ ${title}：${notes[0] ?? ''}`);
+  }
+  for (const note of notes.slice(1)) console.log(`  ${note}`);
+}
+
 export async function check({ only } = {}) {
   const names = only === undefined ? Object.keys(CHECKS) : [only];
-  for (const name of names) {
-    const entry = CHECKS[name];
-    if (entry === undefined) {
-      console.error(`不认识的判据：${name}（有：${Object.keys(CHECKS).join(' / ')}）`);
-      process.exit(2);
+  const tally = { pass: 0, skip: 0, fail: 0 };
+  const skipped = [];
+  let ran = 0;
+  try {
+    for (const name of names) {
+      const entry = CHECKS[name];
+      if (entry === undefined) {
+        console.error(`不认识的判据：${name}（有：${Object.keys(CHECKS).join(' / ')}）`);
+        process.exit(2);
+      }
+      // 告诉这一条"这次是不是只跑它"：有的判据在单跑时顺带当查询口（`--only kit` 会把
+      // 这份外壳的 kit 成员列出来），聚合跑时那些清单属于噪音，不该倒。
+      process.env.DSH_WB_ONLY = only === undefined ? '' : name;
+      const module = await entry.load();
+      const result = await module.run();
+      // title 的发声处是判据模块自己；表里那份是兜底（两边必须一字不差，selfcheck 钉着）。
+      const title = typeof module.title === 'string' && module.title !== '' ? module.title : entry.title;
+      ran += 1;
+      if (!STATES.includes(result.status)) {
+        report(title, {
+          status: 'fail',
+          notes: [],
+          problems: [`返回了不认识的 status：${String(result.status)} —— 只许 ${STATES.join(' / ')}`],
+        });
+        tally.fail += 1;
+        continue;
+      }
+      tally[result.status] += 1;
+      if (result.status === 'skip') skipped.push(`${title}（${result.notes[0] ?? ''}）`);
+      report(title, result);
     }
-    await entry.load();
+  } finally {
+    process.env.DSH_WB_ONLY = '';
+  }
+
+  console.log(`${ran} 条判据：${tally.pass} 通过 · ${tally.skip} 不适用 · ${tally.fail} 不过`);
+  // 「不适用」不是「通过」。汇总行里那两个数字长得很像，读的人（尤其 agent）很容易把
+  // "8 通过 · 2 不适用" 念成"全过了" —— 而工坊里那两条是**结构性**跑不了，不是这次没问题。
+  if (skipped.length > 0) {
+    console.log(`  这 ${skipped.length} 条这次一条都没查（不是"没问题"）：`);
+    for (const one of skipped) console.log(`  ○ ${one}`);
+    console.log('  换个 cwd 它们才跑得起来（工坊里「独立构建」扫不到外壳源码、「公开包无内部标识」只扫');
+    console.log('  要发出去的包）—— 想验这两条，回工作台仓库根跑 `dsh-wb-module check`。');
   }
+  if (tally.fail > 0) process.exit(1);
 }

package/src/checks/alias.mjs

@@ -1,3 +1,12 @@
+// 模块的源码只许引**自己的** `@/modules/<unit>/*`，不许出现任何指向外壳的 `@/`。
+//
+// 为什么：模块出包后用户手上没有外壳源码，`@/app/...` 这类别名只在**本仓的构建配置**里
+// 解析得到 —— 装到别人那里就是构建期找不到文件（`check:standalone` 会把它变成红灯，
+// 这条判据则直接指到源码那一行）。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
+
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { discoverModulePackages } from '../discover.mjs';
@@ -14,36 +23,49 @@ function walk(dir, acc = []) {
   return acc;
 }
 
-const modules = discoverModulePackages({ root: process.cwd() });
-const problems = [];
-for (const pkg of modules) {
-  const unit = pkg.manifest.dsh?.workbench?.unit;
-  const src = join(pkg.dir, 'src');
-  const viaPlatform = /(^|\/)platform-/.test(
-    Object.keys({ ...(pkg.manifest.dependencies ?? {}), ...(pkg.manifest.devDependencies ?? {}) }).join(' '),
-  );
-  if (unit === undefined) continue;
-  for (const file of walk(src)) {
-    const text = readFileSync(file, 'utf8');
-    text.split('\n').forEach((line, index) => {
-      for (const match of line.matchAll(SPECIFIER)) {
-        const specifier = match[1];
-        const own = specifier.startsWith(`@/modules/${unit}/`);
-        const selfPlatform = specifier.startsWith('@/platforms/') && !viaPlatform;
-        if (!own && !selfPlatform) {
-          problems.push(
-            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 用了 ${specifier} —— ` +
-              `模块只许引自己的 @/modules/${unit}/*；共享代码走包名，平台知识走包名或本包的 @/platforms/*（用了平台包就不许再用）`,
-          );
+export const title = '模块不指外壳';
+
+export async function run() {
+  const modules = discoverModulePackages({ root: process.cwd() });
+  const problems = [];
+  for (const pkg of modules) {
+    const unit = pkg.manifest.dsh?.workbench?.unit;
+    const src = join(pkg.dir, 'src');
+    const viaPlatform = /(^|\/)platform-/.test(
+      Object.keys({ ...(pkg.manifest.dependencies ?? {}), ...(pkg.manifest.devDependencies ?? {}) }).join(' '),
+    );
+    if (unit === undefined) continue;
+    for (const file of walk(src)) {
+      const text = readFileSync(file, 'utf8');
+      text.split('\n').forEach((line, index) => {
+        for (const match of line.matchAll(SPECIFIER)) {
+          const specifier = match[1];
+          const own = specifier.startsWith(`@/modules/${unit}/`);
+          const selfPlatform = specifier.startsWith('@/platforms/') && !viaPlatform;
+          if (!own && !selfPlatform) {
+            problems.push(
+              `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 用了 ${specifier} —— ` +
+                `模块只许引自己的 @/modules/${unit}/*；共享代码走包名，平台知识走包名或本包的 @/platforms/*（用了平台包就不许再用）`,
+            );
+          }
         }
-      }
-    });
+      });
+    }
   }
-}
 
-if (problems.length > 0) {
-  console.error(`✖ 模块源码不许出现指向外壳的 @/：${problems.length} 处`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  process.exit(1);
+  if (problems.length > 0) {
+    return { status: 'fail', notes: [], problems };
+  }
+  if (modules.length === 0) {
+    return {
+      status: 'skip',
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有源码要查 @/'],
+      problems: [],
+    };
+  }
+  return {
+    status: 'pass',
+    notes: [`${modules.length} 个模块的 src 里没有指向外壳的 @/`],
+    problems: [],
+  };
 }
-console.log(`✔ 模块不指外壳：${modules.length} 个模块的 src 里没有指向外壳的 @/`);

package/src/checks/bundles.mjs

@@ -13,12 +13,14 @@
 //
 // 覆盖范围跟着**自述清单**走：凡 `package.json` 里声明了 `dsh.workbench` 的包都被检查，
 // 新加一个模块不用改这个脚本。
+//
+// 形状（十条判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
+// 打印与退出码归 `../check.mjs` 那一层。
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { discoverModulePackages } from '../discover.mjs';
 
-
 const CLIENT_FORBIDDEN = [
   ['node 内置', /\bnode:[a-z]/],
   ['process.env（宿主环境）', /\bprocess\.env\b/],
@@ -31,41 +33,52 @@ const HOST_FORBIDDEN = [
   ['react', /require\("react"\)/],
 ];
 
-const modulePackages = () => discoverModulePackages({ root: process.cwd() });
+export const title = '模块产物边界';
 
-const problems = [];
-let checked = 0;
+export async function run() {
+  const modulePackages = discoverModulePackages({ root: process.cwd() });
+  const problems = [];
+  let checked = 0;
 
-for (const pkg of modulePackages()) {
-  const name = pkg.manifest.name;
-  const artifacts = [
-    { what: '浏览器产物', file: 'client.js', rules: CLIENT_FORBIDDEN },
-    { what: '宿主产物', file: 'dist/host.js', rules: HOST_FORBIDDEN },
-  ];
+  for (const pkg of modulePackages) {
+    const name = pkg.manifest.name;
+    const artifacts = [
+      { what: '浏览器产物', file: 'client.js', rules: CLIENT_FORBIDDEN },
+      { what: '宿主产物', file: 'dist/host.js', rules: HOST_FORBIDDEN },
+    ];
 
-  for (const artifact of artifacts) {
-    const full = join(pkg.dir, artifact.file);
-    if (!existsSync(full)) {
-      problems.push(`${name}: 找不到${artifact.what} ${artifact.file} —— 先 build 再 check`);
-      continue;
-    }
-    checked += 1;
-    const source = readFileSync(full, 'utf8');
-    for (const [label, pattern] of artifact.rules) {
-      if (pattern.test(source)) {
-        problems.push(
-          `${name}: ${artifact.what} ${artifact.file} 里出现了${label} —— ` +
-            `两个运行时混了（判据是能力：浏览器侧不许碰宿主传输层，宿主侧不许碰 DOM/react）`,
-        );
+    for (const artifact of artifacts) {
+      const full = join(pkg.dir, artifact.file);
+      if (!existsSync(full)) {
+        problems.push(`${name}: 找不到${artifact.what} ${artifact.file} —— 先 build 再 check`);
+        continue;
+      }
+      checked += 1;
+      const source = readFileSync(full, 'utf8');
+      for (const [label, pattern] of artifact.rules) {
+        if (pattern.test(source)) {
+          problems.push(
+            `${name}: ${artifact.what} ${artifact.file} 里出现了${label} —— ` +
+              `两个运行时混了（判据是能力：浏览器侧不许碰宿主传输层，宿主侧不许碰 DOM/react）`,
+          );
+        }
       }
     }
   }
-}
 
-if (problems.length > 0) {
-  console.error(`✖ 模块产物边界 ${problems.length} 条不过：`);
-  for (const problem of problems) console.error(`  · ${problem}`);
-  process.exit(1);
+  if (problems.length > 0) {
+    return { status: 'fail', notes: [], problems };
+  }
+  if (modulePackages.length === 0) {
+    return {
+      status: 'skip',
+      notes: ['没有模块包（没有声明 dsh.workbench 的包）—— 没有产物可查'],
+      problems: [],
+    };
+  }
+  return {
+    status: 'pass',
+    notes: [`${checked} 份产物 · 浏览器侧无 node 内置 · 宿主侧无 DOM/react`],
+    problems: [],
+  };
 }
-
-console.log(`✔ 模块产物边界通过：${checked} 份产物 · 浏览器侧无 node 内置 · 宿主侧无 DOM/react`);