@dsh-workbench/module-tools 0.3.10 → 1.0.0-beta.0

package/bin/dsh-wb-module.mjs

@@ -1,19 +1,17 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { Command } from 'commander';
 import { build } from '../src/build.mjs';
 import { CHECKS, check } from '../src/check.mjs';
+import { changelog } from '../src/changelog.mjs';
 import { design } from '../src/design.mjs';
 import { init } from '../src/init.mjs';
+import { marketInit } from '../src/market-init.mjs';
 import { publish } from '../src/publish.mjs';
+import { release } from '../src/release.mjs';
 import { sync } from '../src/sync.mjs';
 
-// `dsh-wb-module lint [--fix]`：跑模块**自己那份** `eslint.config.mjs`（方言住在 `src/lint.mjs`）。
-// ESLint 的构造只有一处 —— `src/checks/lint.mjs` 的 `lintPackage`，判据与这条命令共用它；
-// 这里只管打印与退出码（与 `check` 那条路同一分工）。
-//
-// 为什么 eslint 是**懒 import**：`build` / `init` 是工坊里的热路径，而 eslint 那一坨加载要几百毫秒 ——
-// 静态 import 会让每条命令都替这条 lint 付一次。写成命令里的动态 import，只有真跑 lint 才付。
 async function lint({ root, args }) {
   const [{ CONFIG_FILE, lintPackage }, { discoverModulePackages }] = await Promise.all([
     import('../src/checks/lint.mjs'),
@@ -47,39 +45,96 @@ async function lint({ root, args }) {
   if (failed > 0) process.exit(1);
 }
 
-const [command, ...rest] = process.argv.slice(2);
-const cwd = process.env.DSH_WB_MODULE_CWD ?? process.cwd();
+const commands = { build, check, init, 'market-init': marketInit, design, publish, release, sync, lint, changelog };
 
-const commands = { build, check, init, design, publish, sync, lint };
+const CHECK_HELP = `
+查询口：
+  check --only kit [--file <名字>]                      这份外壳的 kit 里有什么
+  check --only primitives [--all|--files|--json] [--file <名字>]
+                                                        这份外壳的 dsh 原语里有什么
+  check --list [--json|--markdown]                      只列判据元数据`;
 
-if (!command || !commands[command]) {
-  console.error(`用法：dsh-wb-module <build|check|init|design|publish|sync|lint> [--cwd <目录>]
-      dsh-wb-module check [--only ${Object.keys(CHECKS).join('|')}]
-      dsh-wb-module check --only kit                 # 单跑当查询口：这份外壳的 kit 里有什么（--file <名字> 给类型文件绝对路径）
-      dsh-wb-module check --only primitives [--all|--files|--json]
-                                                     # 单跑当查询口：dsh 原语里有什么 + --file <名字> 给类型文件绝对路径
-      dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]
-      dsh-wb-module design <init|check|render|accept>   # 三张表：填、查空格、生成 README、自验打勾
-      dsh-wb-module sync                                 # 按清单生成 src/declared-tools.ts（工具名只有清单一处写者）
-      dsh-wb-module lint [--fix]                         # 模块自己那份 eslint.config.mjs；--fix 写回文件
-      dsh-wb-module publish                              # 发货前的清单：门禁 + npm pack 清单 + files 漏项（只 dry run）`);
-  process.exit(2);
-}
+const RELEASE_HELP = `
+选项：
+  --target team|public|tarball|git|market|local         出口；省略按配置默认（可写索引优先 market）
+  --version patch|minor|major|x.y.z                     版本；省略时已存在就自动 patch
+  --registry <url> --access restricted|public --npmrc <文件>
+  --license <id> --out <目录> --git <remote>
+  --index auto|none|<目录|git 地址>                     发布后要更新的索引源
+  --index-ref <分支> --index-path <索引路径> --index-policy artifacts-in-repo|catalog-only
+  --resume                                              上次中断后接着发（用记录里的出口与版本）
+  --dry-run --verify --yes --json`;
+
+const MARKET_INIT_HELP = `
+用法：
+  market-init <git 地址|目录> [--ref <分支>] [--path <索引路径>] [--no-readme] [--json]
+
+空仓库：用仓库自己声明的默认分支，读不到时用 --ref 指定（github.com 兜底 main）。
+已有 commit 的仓库：只补 market.json / README.md，不改已有文件。`;
 
-const value = (flag) => {
-  const at = rest.indexOf(flag);
-  return at === -1 ? undefined : rest[at + 1];
+const CHANGELOG_HELP = `
+用法：
+  changelog init
+  changelog add [版本] [--type added|changed|fixed|removed|security|deprecated] [--note <文字>] [--date <日期>]
+  changelog check [版本] [--json]
+
+版本省略时用 package.json 里的 version。发布时这一版必须在 CHANGELOG.md 里有记录，否则 release 会拦下。`;
+
+const COMMANDS = {
+  build: '出 dist/host.js（单文件 ESM）与 client.js（套 loader 壳）',
+  check: '十三条判据；--only 单跑，也当查询口用；--list 只列判据元数据',
+  init: '建模块骨架（--dir / --template minimal|diy / --description）',
+  'market-init': '初始化市场索引仓库（写 market.json + README，推首个 commit）',
+  design: '设计底稿：init 填 / check 查空格 / render 生成 README / accept 打勾',
+  publish: '发货前清单：门禁 + files + npm pack（只 dry run）',
+  release: '真发布：全门禁 + 验收闸 + 预检接管 + 发到出口 + 发后核包 + 更新市场索引（中断可 --resume）',
+  sync: '按清单生成 src/declared-tools.ts，按 design.json 生成 src/datasource.ts',
+  lint: '用模块自己那份 eslint.config.mjs；--fix 写回文件',
+  changelog: '更新日志：init 建 / add 记一版 / check 查这一版有没有（发布前必须有）',
 };
-const args = [];
-for (let i = 0; i < rest.length; i += 1) {
-  if (rest[i] === '--cwd' || rest[i] === '--only') {
-    i += 1;
-    continue;
+
+function flagValue(raw, flag) {
+  const at = raw.indexOf(flag);
+  return at === -1 ? undefined : raw[at + 1];
+}
+
+async function dispatch(name, raw) {
+  const cwd = process.env.DSH_WB_MODULE_CWD ?? process.cwd();
+  const args = [];
+  for (let index = 0; index < raw.length; index += 1) {
+    if (raw[index] === '--cwd' || raw[index] === '--only') {
+      index += 1;
+      continue;
+    }
+    args.push(raw[index]);
   }
-  args.push(rest[i]);
+  const root = resolve(flagValue(raw, '--cwd') ?? cwd);
+  if (root !== process.cwd()) process.chdir(root);
+  await commands[name]({ root, only: flagValue(raw, '--only'), args });
 }
 
-const root = resolve(value('--cwd') ?? cwd);
-if (root !== process.cwd()) process.chdir(root);
+const program = new Command('dsh-wb-module')
+  .description(`模块包的工具链：${Object.keys(COMMANDS).join(' / ')}`)
+  .helpOption('-h, --help', '打印帮助')
+  .addHelpText(
+    'after',
+    '\n  --cwd <目录>  指定包目录（默认当前目录；也可用 DSH_WB_MODULE_CWD）\n  任何命令后跟 --help 都只打印帮助。\n',
+  );
+
+for (const [name, description] of Object.entries(COMMANDS)) {
+  const sub = program
+    .command(name)
+    .description(description)
+    .helpOption('-h, --help', '打印帮助')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true);
+  if (name === 'check') sub.addHelpText('after', `\n${CHECK_HELP}\n      --only 可选：${Object.keys(CHECKS).join('|')}\n`);
+  if (name === 'release') sub.addHelpText('after', `${RELEASE_HELP}\n`);
+  if (name === 'market-init') sub.addHelpText('after', `${MARKET_INIT_HELP}\n`);
+  if (name === 'changelog') sub.addHelpText('after', `${CHANGELOG_HELP}\n`);
+  sub.action(async (_options, command) => {
+    await dispatch(name, command.args);
+  });
+}
 
-await commands[command]({ root, only: value('--only'), args });
+await program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.3.10",
+  "version": "1.0.0-beta.0",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -22,16 +22,31 @@
     "access": "public"
   },
   "dependencies": {
-    "@arch-guard/core": "^0.11.0",
+    "@arch-guard/core": "^0.11.1",
     "@eslint/js": "^10.0.1",
+    "commander": "^15.0.0",
     "esbuild": "^0.28.2",
     "eslint": "^10.11.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
+    "execa": "^10.2.0",
+    "typescript": "5.9.3",
     "typescript-eslint": "^8.71.0",
-    "@dsh-workbench/shared": "0.3.10"
+    "@dsh-workbench/shared": "1.0.0-beta.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/novaeth/dsh-workbench.git",
+    "directory": "packages/module-tools"
+  },
+  "homepage": "https://github.com/novaeth/dsh-workbench#readme",
+  "bugs": {
+    "url": "https://github.com/novaeth/dsh-workbench/issues"
   },
   "scripts": {
+    "lint": "eslint src bin scripts",
+    "arch": "arch-guard",
+    "check": "pnpm run lint && pnpm run arch && pnpm run selfcheck",
     "selfcheck": "node scripts/selfcheck/index.mjs"
   }
 }

package/src/arch.mjs

@@ -1,42 +1,4 @@
-// 模块包的**架构方言**（arch-guard 的模块版）。
-//
-// 为什么要有这一份：模块包是"用户自己写"的代码，而模板给的是一个**单文件**起步的形状 ——
-// 卡片一复杂（多路取数、多态渲染、几个子件、几条文案）那个文件就会长到几百行，而门禁
-// （`check` 原本那十一条）只看产物边界与声明形状，**没有一条在看代码结构**。arch-guard 正好补这一层，
-// 但它认识的是"应用 / 库 / FSD"三种范式，模块包（一个插件包、两个面的小库）不在其中：
-// 直接把库范式套上去，`src/messages.ts` 这种根文件会报 S01「无处安放」，而两个运行时的
-// 互相 import 它也不管。所以这里把模块包的方言**写死一处**：层序表、两个运行时、阈值、
-// 允许的依赖、样式与文案的口径。
-//
-// 为什么不是让每个模板抄一份 arch.config.mjs：那样 ① 每个模块的方言会各自漂，
-// ② 方言跟着**工具链**走才对 —— 工坊那三个包本来就"与外壳同代"（seed-workshop.sh 的
-// 代际自愈），把方言放在 module-tools 里，它随代际一起更新，用户不用重抄一份配置。
-// 模板里那份 `arch.config.mjs` 只留一行 `moduleArch()`，要改（加目录、加依赖、放宽阈值）
-// 就在**这一处**改。
-//
-// 层序（数字越小越底层，S21：只许依赖层号 ≤ 自己的文件）：
-//
-//     src/model/**       1   纯逻辑：类型 / 换算 / 状态机。两个运行时都可达，不碰 react / kit / node:fs
-//     src/messages.ts    1   文案（zh / en）。同样是"谁都能用的数据"
-//     src/declared-tools.ts 1 `dsh-wb-module sync` 生成的工具名（工具链自己的产物，见下）
-//     src/components/**  2   浏览器侧的视图件；样式与它同目录（`*.module.css`）
-//     src/host.ts       10   宿主面（`dsh.workbenchFaces.host`）
-//     src/client.tsx    10   浏览器面（`dsh.workbenchFaces.client`）
-//     **/*.test.ts(x)   99   测试（库范式自带这条排他角色，S21 直接跳过；S16 的体积阈值也不管它）
-//     src/**/__tests__/** 99  测试的另一个家（方言自己声明的，见 TESTS_DIR_ROLE 那段）
-//
-// 两个运行时**互相隔离**：`structure.runtimes` + `faces` 让 S23 认得出"宿主侧文件 import 了
-// 浏览器面"（反过来也一样）。这一条以前没有任何判据管 —— `check:source` 只管 dsh 的包在不在
-// 客户端侧可达。
-//
-// 阈值刻意**严于** arch-guard 的默认（500 行 / 150 行函数）：模块包是"一个人写的一块面板"，
-// 一个文件 200 行、一个函数 80 行就该拆了 —— 这条不是审美，是"复杂模块不会退化成一个巨文件"
-// 的可判定下限。要更宽就在自己那份配置里传 `fileLines`。
-//
-// 三条内置豁免条目 / 两条规则（都要写 reason，arch-guard 的硬要求）：D04 的 `--dsw-*` 令牌
-// （我们**不拥有**主题，见 STYLE_EXCEPTION 那段）与 S16 的测试文件（脚手架不是产品代码，
-// 见 TEST_LINES_EXCEPTIONS 那段 —— 后缀式与 `__tests__/**` 各一条）。
-
+import { readFileSync } from 'node:fs';
 import {
   cssModulesKit,
   deps,
@@ -48,41 +10,21 @@ import {
   noneI18nKit,
   styles,
 } from '@arch-guard/core/presets';
+import { createRule } from '@arch-guard/core';
 import { DECLARED_TOOLS_FILE } from './declared-tools.mjs';
 import { SEED_SPECIFIERS } from './seed.mjs';
 
-// 两个面**就是** `dsh.workbenchFaces` 指的那两个文件（协议要求，见 ADR-0038）。改这两个名字
-// 等于改声明，判据（contracts / source）先红 —— 所以这里是常量，不是选项。
 const HOST_FACE = 'src/host.ts';
 const CLIENT_FACE = 'src/client.tsx';
 
-// 内部目录表（`library()` 的 modules）。目录名是约定：模型 / 视图，别的一个都不许有 ——
-// 多出来的目录会被 S01 报"不在目录契约内"，那正是要的：要加一层就明写在配置里。
 const LAYERS = { model: 1, components: 2 };
 
-// `src/messages.ts` 是文件不是目录，而 `modules` 只认目录前缀（文件级 key 实测仍报 S01），
-// 所以它走 `addRoles`。层号与 model 同层：文案不依赖任何东西，两端都能读。
 const MESSAGES_ROLE = { id: 'lib:messages', pattern: 'src/messages.ts', layer: 1 };
 
-// `src/declared-tools.ts` 是 `dsh-wb-module sync` 按清单生成的工具名（`tools[].key` 那一档，
-// 见 declared-tools.mjs）—— 与 messages.ts 一样是"谁都能读的常量"，所以同层、同样走 `addRoles`
-// （它也是文件不是目录）。这一条必须内置：那是**工具链自己的产物**，不认它等于"照我们推荐的路走
-// 就会撞 S01"（实测：作者得翻源码才知道 roles 的形状，再手写一行补上）。
-// 路径直接取 declared-tools 那份常量，不在这里抄一遍字符串（工具名只有一处写者，这条也一样）。
 const DECLARED_TOOLS_ROLE = { id: 'lib:declared-tools', pattern: DECLARED_TOOLS_FILE, layer: 1 };
 
 const DEFAULT_THRESHOLDS = { fileLines: 200, viewLines: 200, functionLines: 80 };
 
-// 测试文件不吃 S16 的体积阈值（类级豁免：arch-guard 的 exceptions 只认"某条规则对某类文件不适用"）。
-// 它与产品代码不是同一种东西 —— 夹具、逐条断言、一条用例十来行，200 行对它是错的口径；而"拆成两个
-// 测试文件"只会把脚手架摞进 src/（作者反馈：一个模块被这条逼出 `src/host/testing.ts`，测试脚手架住进
-// 了宿主层目录）。它本来就有一条排他角色（layer 99，S21 直接跳过），这条豁免与那条同一个理由。
-// 为什么不给"测试单列一个阈值"：S16 只读 thresholds 的 fileLines / viewLines / functionLines
-// （arch-guard structure.js），要按角色分档得改上游；先用类级豁免把口径说清楚。
-//
-// 两条覆盖面合起来 = 方言对"什么算测试"的**全部**声明，一份口径：后缀式的 `.test.` / `.spec.`
-// （库范式那条排他角色收的七种扩展，这里一种不落）与 `__tests__/**` 这个家（`metrics.testGlobs`
-// 里写着的那一条）。少于这个并集就会冒出第二份口径：同一个方言里"什么算测试"有两套答案。
 const TEST_LINES_REASON =
   '测试文件是脚手架，不是产品代码：夹具、逐条断言、一条用例十来行，200 行这个阈值对它是错的口径；' +
   '按它拆文件只会把测试脚手架摞进 src/ 的层里（作者反馈：一个模块被逼出过 src/host/testing.ts）。' +
@@ -91,16 +33,10 @@ const TEST_LINES_REASON =
 
 const TEST_LINES_EXCEPTIONS = [
   { rule: 'S16', glob: '**/*.{test,spec}.{ts,tsx,mts,cts,js,mjs,cjs}', reason: TEST_LINES_REASON },
-  // `__tests__/**` 也要豁免：那是方言自己声明过的测试家（`metrics.testGlobs`），
-  // 但库范式那条排他角色只认后缀式命名 —— 不豁免的话，把测试放进 `__tests__/` 反而吃 S16。
+
   { rule: 'S16', glob: 'src/**/__tests__/**', reason: TEST_LINES_REASON },
 ];
 
-// `__tests__/**` 里的文件（夹具 / 用例）也要有个角色：方言已经在 `metrics.testGlobs` 里把这里
-// 声明成测试的家，而库范式只给了后缀式命名一条角色 —— 于是 `src/__tests__/x.ts` 会撞 S01，
-// `src/model/__tests__/x.ts` 会被当成模型层（S16 与 S21 都按产品代码判它）。`exclusive` 是必须的：
-// 它排在库范式的目录角色后面，命中即清掉前面的命中，否则 `src/model/__tests__/**` 会"同时命中两个角色"
-// 再撞一次 S01。层号跟后缀式测试同一条（99 ⇒ S21 跳过）：脚手架能引产品代码，反过来不行。
 const TESTS_DIR_ROLE = {
   id: 'lib:tests-dir',
   pattern: 'src/**/__tests__/**',
@@ -108,9 +44,6 @@ const TESTS_DIR_ROLE = {
   exclusive: true,
 };
 
-// 我们**不拥有**主题：`--dsw-*` 那套令牌由 dsh 在运行时给（与外壳同一口径，
-// 见 ADR-0028 / .scratch/dsh-ui-alignment/spec.md）。所以这里声明的样式目录里，
-// "引用的令牌查不闭合"是正常的 —— 理由就写在下面这条里（与上面那条 S16 一起，是两条内置豁免）。
 const STYLE_EXCEPTION = {
   rule: 'D04',
   glob: 'src/components/**',
@@ -120,32 +53,25 @@ const STYLE_EXCEPTION = {
     'dsh 改名会由外壳升级暴露，而不是由模块本地的表兜住。',
 };
 
-// 模块包**运行时**允许的依赖：react（外壳经模块表提供）+ 外壳自己那两个包 + **平台种子词那一整族**。
-//
-// 种子词为什么要一起放进来（2026-10-19 补，用户口径「arch 没加依赖」）：那些包是 dsh 的模块表
-// 天生就提供的（`seed.mjs` 是唯一真相），模块引它们走 `dsh.client.external` 是**被允许的路**
-// （ADR-0028 §5 / ADR-0063）。但作者把它们写进 `dependencies` 时，P01 会报「未登记的运行时依赖」，
-// 而 arch-guard 给的那句修法是「加进 `deps({ allow })`」—— 对平台件这是**误导**：它逼每个模块
-// 为一条本来就合法的事开口子。所以这里按 `seed.mjs` 推导（dsh 加词，这张表自己跟着长），
-// 表外的包（真正的第三方 SDK）照旧要明着登记。
-//
-// 推荐写法仍是 **devDependency（类型）+ `dsh.client.external`**：放进 `dependencies` 不会报错，
-// 但 pnpm 会给模块装一份**运行时用不到的**副本（产物里是 `require`，实例由外壳给）。
-// 那是"浪费"不是"错误"，所以不由 arch 判；由 `check:source` / `check:primitives` 守真正的错误
-// （宿主侧碰它、漏声明 external、产物被内联）。
-// `@dsh-workbench/module-tools` 是构建/门禁工具，是 devDependency，不进这张表。
 const SEED_PACKAGES = [
   ...new Set(
     SEED_SPECIFIERS.map((name) => (name.startsWith('@') ? name.split('/').slice(0, 2).join('/') : name.split('/')[0])),
   ),
 ];
 const ALLOWED_DEPS = [
-  ...new Set([...SEED_PACKAGES, '@dsh-workbench/core', '@dsh-workbench/shared']),
+  ...new Set([
+    ...SEED_PACKAGES,
+    '@dsh-workbench/core',
+    '@dsh-workbench/shared',
+    'execa',
+    'which',
+    'proper-lockfile',
+    'write-file-atomic',
+    'dayjs',
+    'zod',
+  ]),
 ];
 
-// 我们**不拥有**主题：颜色 / 圆角 / 字号 / 时长一律引用 dsh 的 `--dsw-*` 令牌，
-// 所以这里没有 tokenDir / palette（声明一个自己的令牌表就是编造一处不存在的真相，
-// 与外壳那份 arch.config.mjs 同一个理由）。留白的三族白名单 = 一个手搓数值都不收（`0` 本来就被跳过）。
 const DESIGN = {
   styleDir: 'src/components',
   tokenDir: '',
@@ -159,32 +85,124 @@ const DESIGN = {
   ],
 };
 
-/**
- * 模块包的 arch-guard 配置。模板里那一行就是默认值：
- *
- * ```js
- * import { moduleArch } from '@dsh-workbench/module-tools/arch';
- * export default moduleArch();
- * ```
- *
- * 复杂模块要开口子时**从参数进**（每条口子都有名字，评审时看得见），别改判据：
- *
- * - `fileLines` / `viewLines` / `functionLines`：放宽体积阈值（默认 200 / 200 / 80）
- * - `deps`：追加允许的运行时依赖（比如宿主侧接了某个 SDK）。dsh 的**平台种子词**
- *   （`seed.mjs` 那一族：`react` / `zod` / `@deepseek-ai/dsh-client-*` …）与 `@dsh-workbench/*`
- *   已经按种子表推导进表里，不用为它们开口子
- * - `roles`：追加角色（自定义目录 / 文件；`{ id, pattern, layer }`）。
- *   内置已有三条**文件级**角色：`src/messages.ts`、`src/declared-tools.ts`，以及 `__tests__/`
- *   目录下的文件（`src/` 内任意一层）—— 后两条一条是 `sync` 生成的、一条是方言声明的测试家，
- *   工具链自己认，不用你补
- * - `layers`：**追加或覆盖**内部目录表（默认 `{ model: 1, components: 2 }`）。宿主侧想住
- *   `src/host/` 就在自己那份配置里加 `{ host: 10 }`；但**两个面的文件路径不是可调项**
- *   （`src/host.ts` / `src/client.tsx` 同时钉在 `library({ entry })`、`structure.faces` 与清单的
- *   `dsh.workbenchFaces` 上，要换面得整体替换 `structure` 并改清单 —— 先红的是 contracts）
- * - `structure`：整体替换 `structure` 声明（面在别处、或者只有一个运行时的模块）
- * - `exceptions`：结构性豁免，**每条必须写 reason**（arch-guard 的硬要求）；
- *   内置已有三条（`--dsw-*` 令牌 / 测试文件不吃 S16 的两条覆盖面），不必重复声明
- */
+const MODEL_FILE = /^src\/(model\/|messages\.ts$)/;
+const MODEL_BANNED = [
+  /^react(?:\/|$)/,
+  /^react-dom(?:\/|$)/,
+  /^@deepseek-ai\//,
+  /^@dsh-workbench\/core(?:\/client)?$/,
+  /^@dsh-workbench\/shared\/host$/,
+  /^node:/,
+  /^opencli(?:\/|$)/,
+  /^@\/components(?:\/|$)/,
+  /^(?:\.\.?\/)+(?:components|host|client)(?:\/|$)/,
+  /^(?:@\/|\.\.?\/)(?:host|client)$/,
+];
+
+const COMPONENT_FILE = /^src\/components\//;
+const COMPONENT_BANNED = [
+  /^@dsh-workbench\/shared\/host$/,
+  /^@dsh-workbench\/core$/,
+  /^node:/,
+  /^opencli(?:\/|$)/,
+  /^(?:\.\.?\/)+(?:host|client)$/,
+  /^(?:@\/)(?:host|client)$/,
+];
+
+const modelStaysPure = createRule({
+  id: 'S71',
+  domain: 'structure',
+  level: 'L2',
+  severity: 'error',
+  title: '模块核心（model / messages）不碰宿主、UI 与运行时',
+  hint:
+    'model / messages 是模块里最底的一层：只放纯逻辑、状态机、文案。' +
+    'React、kit、dsh、opencli、node:*、组件与两个面都不许 import；要用类型就从 core/contract 取 import type。',
+  run(ctx) {
+    const findings = [];
+    for (const record of ctx.records) {
+      if (!MODEL_FILE.test(record.rel)) continue;
+      for (const fact of ctx.facts.get(record.rel)?.imports ?? []) {
+        if (fact.typeOnly) continue;
+        if (!MODEL_BANNED.some((pattern) => pattern.test(fact.spec))) continue;
+        findings.push({
+          rule: 'S71',
+          file: record.rel,
+          line: fact.line,
+          ...(fact.column === undefined ? {} : { column: fact.column }),
+          text: `模块核心 import 了 ${fact.spec}`,
+          hint: '把宿主 / UI / 运行时的依赖推到 components 或两个面；核心只依赖纯类型与纯函数',
+        });
+      }
+    }
+    return findings;
+  },
+});
+
+const componentsStayBrowser = createRule({
+  id: 'S72',
+  domain: 'structure',
+  level: 'L2',
+  severity: 'error',
+  title: '模块视图不碰宿主面',
+  hint:
+    'components 只消费 props：可以拿 kit 与纯数据，不许 import 宿主入口、shared/host、dsh 原语或 node:*。' +
+    '取数、写、路由都在两个面与 model 里。',
+  run(ctx) {
+    const findings = [];
+    for (const record of ctx.records) {
+      if (!COMPONENT_FILE.test(record.rel)) continue;
+      for (const fact of ctx.facts.get(record.rel)?.imports ?? []) {
+        if (fact.typeOnly) continue;
+        if (!COMPONENT_BANNED.some((pattern) => pattern.test(fact.spec))) continue;
+        findings.push({
+          rule: 'S72',
+          file: record.rel,
+          line: fact.line,
+          ...(fact.column === undefined ? {} : { column: fact.column }),
+          text: `模块视图 import 了 ${fact.spec}`,
+          hint: '组件只接收数据与回调；宿主侧能力放 src/host.ts，浏览器侧取数放面的 hooks',
+        });
+      }
+    }
+    return findings;
+  },
+});
+
+const LOCAL_PROTOCOL =
+  /\b(?:interface|type)\s+(UnitModuleFace|UnitMountResult|UnitClientFace|UnitClientApi|UnitModuleRegistry|UnitClientRegistry|UnitRegistry|HostContext|ClientContext|BoardProps)\b/g;
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+const protocolsStayCanonical = createRule({
+  id: 'S73',
+  domain: 'structure',
+  level: 'L2',
+  severity: 'error',
+  title: '模块不本地重声明外壳协议',
+  hint:
+    '协议类型只有一份：`@dsh-workbench/core/contract`。删掉本地 interface / type，改成 `import type`；' +
+    '本地重声明会让外壳升级时模块静默对不上。',
+  run(ctx) {
+    const findings = [];
+    for (const record of ctx.records) {
+      const text = readFileSync(record.abs, 'utf8');
+      for (const match of text.matchAll(LOCAL_PROTOCOL)) {
+        findings.push({
+          rule: 'S73',
+          file: record.rel,
+          line: lineOf(text, match.index),
+          text: `本地声明 ${match[1]}`,
+          hint: '删掉，改 import type from @dsh-workbench/core/contract',
+        });
+      }
+    }
+    return findings;
+  },
+});
+
+const MODULE_RULES = [modelStaysPure, componentsStayBrowser, protocolsStayCanonical];
+
 export function moduleArch(options = {}) {
   const {
     fileLines,
@@ -207,20 +225,32 @@ export function moduleArch(options = {}) {
   return {
     sourceForm: 'react',
     presets: [
-      // 层序表 + 角色完备（S01 未命中任何角色的文件当场报）+ 体积（S16）。
+
       library({ src: 'src', entry: ['host.ts', 'client.tsx'], modules: { ...LAYERS, ...layers } }),
-      // 运行时依赖 fail-closed：没登记的依赖报 P01。
-      deps({ allow: [...ALLOWED_DEPS, ...extraDeps] }),
-      // 手搓数值 / !important / 选择器 / CSS Modules 的绑定闭合。令牌表留白（理由见 DESIGN）。
+
+      deps({
+        allow: [...ALLOWED_DEPS, ...extraDeps],
+        deny: ['shell-quote', 'shelljs', 'zx'],
+        capabilities: {
+          'unique-id': 'crypto.randomUUID',
+          'number-format': 'Intl.NumberFormat',
+          'deep-equal': 'node:util.isDeepStrictEqual',
+          datetime: 'dayjs',
+          'deep-clone': 'structuredClone',
+          'query-string': 'URLSearchParams',
+          validation: 'zod',
+        },
+        fingerprints: [{ capability: 'query-string', allowOwn: false }],
+      }),
+
       designSystem({ ...DESIGN }),
-      // 组件样式走 `*.module.css`（ADR-0029 的模块版：样式跟组件走）。
+
       styles(cssModulesKit()),
-      // 反退化：TODO / 调试残留 / 空 catch / 未完成标记。
+
       hygiene(),
-      // 文案走模块自己的 `messages`（zh / en），不用 i18next —— 与外壳同一口径。
+
       i18n(noneI18nKit()),
-      // 模型层必须有落地的测试（`src/model/**` 命中文件但一份测试都没有就红）。
-      // 门禁链不在这里查（`check` 不跑 vitest，那是 `pnpm test` 的事，与外壳同一条口径）。
+
       metrics({
         tests: {
           requireTestsFor: ['src/model/**'],
@@ -228,14 +258,15 @@ export function moduleArch(options = {}) {
           checkChain: { script: 'check', require: [] },
         },
       }),
+
+      { enable: ['S71', 'S72', 'S73'] },
     ],
     overrides: {
       include: ['src/**'],
       addRoles: [MESSAGES_ROLE, DECLARED_TOOLS_ROLE, TESTS_DIR_ROLE, ...roles],
       thresholds,
-      // 两个运行时 + 两个面：S23 据此判"跨运行时走了对面那个面"。
-      // 不写 `value`（面值形状）：模块的面导出的是 `apply` / `inject` / `name`，
-      // 那是 dsh 插件的契约，不是我们在这里能收敛成某个前缀的东西。
+      customRules: MODULE_RULES,
+
       structure: structure ?? {
         runtimes: [
           { name: 'host', entries: [HOST_FACE] },
@@ -244,9 +275,7 @@ export function moduleArch(options = {}) {
         faces: [
           { pattern: HOST_FACE, runtime: 'host' },
           { pattern: CLIENT_FACE, runtime: 'client' },
-          // 组件目录整片算"浏览器侧的面"：于是**宿主侧的文件 import 一个组件**会被 S23 当场报
-          // （层号拦不住它 —— components 在第 2 层、host 面在第 10 层，S21 认为"向下依赖"合法）。
-          // 那正是最典型的一种错：宿主产物里拖进一个只会渲染的东西，`dist/host.js` 在 Node 里起不来。
+
           { pattern: 'src/components/**', runtime: 'client' },
         ],
       },