@dsh-workbench/module-tools 0.1.14 → 0.1.16

package/src/design.mjs

@@ -0,0 +1,424 @@
+// 三张表的**唯一真相**：`design.json`。
+//
+// ── 为什么要有这个文件 ────────────────────────────────────────────────────────
+//
+// 在这之前，三张表只活在 README 的散文里：SKILL.md 说"空着的格就是还没定的事，别带着空格往下做"，
+// 可**没有一条判据看得见那些格**。于是它靠 agent 自觉：忘了填、填了一半、只留在对话里 —— 都没人拦。
+// README 是给人读的落点，不是给机器判的形状。
+//
+// 现在的分工：
+//   · `design.json` —— 机器可读的需求底稿（三张表 + 状态矩阵 + 数据源记录 + 验收清单）；
+//   · `README.md`   —— 由它**生成**的那一段（夹在 `<!-- dsh-wb:design:start/end -->` 之间）；
+//   · `dsh-wb-module design check` —— 把**空着的格**列出来（红），并核对 README 没落后于 design.json。
+//
+// 这样"空格"第一次有了形状：填空 → 再往下做；写完 → `design accept` 逐条打勾。
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DESIGN_FILE = 'design.json';
+export const START_MARK = '<!-- dsh-wb:design:start -->';
+export const END_MARK = '<!-- dsh-wb:design:end -->';
+
+/** 卡片五态 —— 与指引 PANEL.md 的状态矩阵、`check:cards` 的渲染判据同一套。 */
+export const STATE_KEYS = ['idle', 'loading', 'ready', 'empty', 'unreadable'];
+const STATE_LABELS = {
+  idle: '待机（还没选东西）',
+  loading: '加载',
+  ready: '就绪',
+  empty: '就绪但空',
+  unreadable: '读不到',
+};
+const LETTERS = ['A', 'B', 'C', 'D', 'E'];
+const PENDING = '（待填）';
+
+/** 必填的行字段；`optional` 的那些留空不算空。 */
+const ROWS = {
+  panel: { fields: ['cell', 'conclusion'], optional: ['link'] },
+  config: {
+    fields: ['persistence', 'key', 'watches', 'default', 'valuesFrom', 'wrongChoice'],
+    choices: { persistence: ['prefs', 'view'] },
+    mayBeEmpty: true,
+  },
+  capabilities: {
+    fields: ['name', 'oneLine', 'shape', 'approval', 'scope'],
+    choices: { scope: ['always', 'workspace'] },
+    optional: ['approvalText'],
+    mayBeEmpty: true,
+  },
+  linkage: { fields: ['who', 'when', 'whatChanges', 'userSees'] },
+  acceptance: { fields: ['step'] },
+};
+const DATASOURCE_FIELDS = ['read', 'params', 'credentials', 'notLoggedIn', 'timeout'];
+
+/** 一条卡背后可以有多条读（甚至跨站点）：规范形状 `reads: [ … ]`，一条一行；
+ *  `datasource: { … }` 是只有一条读时的写法（老模块都长这样，继续认）。 */
+function readsOf(design) {
+  const list = design?.reads;
+  if (Array.isArray(list) && list.length > 0) return list;
+  const one = design?.datasource;
+  return one === undefined || one === null || typeof one !== 'object' ? [] : [one];
+}
+
+/** 「他能自己配什么」有两种，分不清就会写成一个不落盘的选择还自称配置： */
+function persistenceLabel(value) {
+  const raw = text(value);
+  if (raw === 'prefs') return '存起来（按工作区记，刷新还在）';
+  if (raw === 'view') return '只在这次看的时候选（刷新回默认）';
+  return cell(raw);
+}
+
+/** 一条能力在哪些项目里出现：`always` = 每个项目都该看见；`workspace` = 只在某些项目里有意义，
+ *  代码里必须真的用 `gate.deniedTools(workspace)` 把它收窄，否则表上写着窄、实际到处都在。 */
+function scopeLabel(value) {
+  const raw = text(value);
+  if (raw === 'always') return '哪个项目都能用';
+  if (raw === 'workspace') return '只在某些项目里出现（按项目收窄）';
+  return cell(raw);
+}
+
+function datasourceRowsOf(read) {
+  return [
+    '| 项 | 值（照抄，别转述） |',
+    '|---|---|',
+    `| 哪条读（命令 / URL） | ${cell(read?.read)} |`,
+    `| 参数（缺省 / 范围 / 上限） | ${cell(read?.params)} |`,
+    `| 凭据从哪来 | ${cell(read?.credentials)} |`,
+    `| 没登录 / 凭据过期时是什么样 | ${cell(read?.notLoggedIn)} |`,
+    `| 超时 / 连不上时是什么样 | ${cell(read?.timeout)} |`,
+    `| 当初探明用的那次调用（原文） | ${soft(read?.probeCommand)} |`,
+  ];
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function pending(value) {
+  return text(value) === '' || text(value) === PENDING;
+}
+
+function asRows(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+export function readDesign(root) {
+  const file = join(root, DESIGN_FILE);
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    console.error(`✖ ${DESIGN_FILE} 不是合法 JSON：${error.message}`);
+    process.exit(1);
+  }
+}
+
+function skeleton(manifest = {}) {
+  return {
+    unit: text(manifest?.dsh?.workbench?.unit) || text(manifest.name).replace(/^.*\/module-/, ''),
+    name: text(manifest.name),
+    oneLine: text(manifest.description),
+    panel: [{ cell: '', conclusion: '', link: '' }],
+    states: STATE_KEYS.map((key) => ({ key, sees: '', canDo: '', agentCan: '' })),
+    config: [],
+    capabilities: [],
+    linkage: [{ who: '', when: '', whatChanges: '', userSees: '' }],
+    datasource: {
+      read: '',
+      params: '',
+      credentials: '',
+      notLoggedIn: '',
+      timeout: '',
+      probeCommand: '',
+    },
+    acceptance: [{ step: '' }],
+  };
+}
+
+export function writeDesign(root, value) {
+  writeFileSync(join(root, DESIGN_FILE), `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function need(cells, value, path) {
+  if (pending(value)) cells.push(path);
+}
+
+/** 空着的格 —— 这就是"别带着空格往下做"那条纪律的机器形状。 */
+export function emptyCells(design) {
+  const cells = [];
+  for (const field of ['unit', 'name', 'oneLine']) need(cells, design?.[field], field);
+
+  for (const [key, rule] of Object.entries(ROWS)) {
+    const rows = asRows(design?.[key]);
+    if (rows.length === 0) {
+      if (rule.mayBeEmpty !== true) cells.push(`${key}（一行都没有）`);
+      continue;
+    }
+    rows.forEach((row, index) => {
+      for (const field of rule.fields) need(cells, row?.[field], `${key}[${index}].${field}`);
+      for (const [field, allowed] of Object.entries(rule.choices ?? {})) {
+        const raw = text(row?.[field]);
+        if (raw !== '' && !allowed.includes(raw)) {
+          cells.push(`${key}[${index}].${field}（只认 ${allowed.join(' / ')}，收到「${raw}」）`);
+        }
+      }
+    });
+  }
+
+  const states = asRows(design?.states);
+  const noCapabilities = asRows(design?.capabilities).length === 0;
+  for (const [index, key] of STATE_KEYS.entries()) {
+    const row = states.find((one) => text(one?.key) === key);
+    if (row === undefined) {
+      cells.push(`states[${index}]（缺 ${key} 这一态）`);
+      continue;
+    }
+    // 这一态对这份模块确实不适用时，写一句**为什么**就行（例：账号级的卡没有"还没选项目"这一态）。
+    // 行仍然要占着 —— 五态是矩阵的行，不是"能省则省"的清单；省掉的只是那三个格子。
+    if (text(row.na) !== '') continue;
+    for (const field of ['sees', 'canDo']) need(cells, row[field], `states.${key}.${field}`);
+    // 这份模块故意没有 agent 能力时，`agentCan` 没有内容可写 —— 那几格不必硬填一句同义反复。
+    if (!noCapabilities) need(cells, row.agentCan, `states.${key}.agentCan`);
+  }
+
+  const reads = readsOf(design);
+  if (reads.length === 0) cells.push('数据源（一条读都没写：datasource 或 reads 至少要有一条）');
+  reads.forEach((read, index) => {
+    const label = reads.length === 1 ? 'datasource' : `reads[${index}]`;
+    for (const field of DATASOURCE_FIELDS) need(cells, read?.[field], `${label}.${field}`);
+  });
+
+  return cells;
+}
+
+function cell(value) {
+  const raw = text(value);
+  return raw === '' ? PENDING : raw.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
+}
+
+/** 可空的格：空着是**合法**的（例：这张卡没有外链），渲染成 `—` 而不是"待填"。 */
+function soft(value) {
+  const raw = text(value);
+  return raw === '' || raw === PENDING ? '—' : cell(raw);
+}
+
+function tableOf(header, rows) {
+  const columns = header.split(' | ');
+  const divider = `|${columns.map(() => '---').join('|')}|`;
+  return [`| ${header} |`, divider, ...rows.map((row) => `| ${row.join(' | ')} |`)].join('\n');
+}
+
+export function renderDesign(design) {
+  const panel = asRows(design?.panel);
+  const config = asRows(design?.config);
+  const capabilities = asRows(design?.capabilities);
+  const linkage = asRows(design?.linkage);
+  const acceptance = asRows(design?.acceptance);
+  const states = asRows(design?.states);
+  const reads = readsOf(design);
+
+  const stateRows = STATE_KEYS.map((key, index) => {
+    const row = states.find((one) => text(one?.key) === key) ?? {};
+    const na = text(row.na);
+    if (na !== '') {
+      return [LETTERS[index], STATE_LABELS[key], `（这份模块不适用）${na}`, '—', '—'];
+    }
+    return [
+      LETTERS[index],
+      STATE_LABELS[key],
+      cell(row.sees),
+      cell(row.canDo),
+      capabilities.length === 0 ? soft(row.agentCan) : cell(row.agentCan),
+    ];
+  });
+
+  const acceptanceRows =
+    acceptance.length === 0
+      ? ['- [ ] （待填）']
+      : acceptance.map((one) => `- [${one?.checked === true ? 'x' : ' '}] ${cell(one?.step)}`);
+
+  return [
+    '### 表 1 面板：他看什么、他能自己配什么',
+    '',
+    tableOf('这一格 | 一眼能得出什么结论 | 点一下可以去哪', panel.length === 0
+      ? [['（待填）', PENDING, PENDING]]
+      : panel.map((one) => [cell(one?.cell), cell(one?.conclusion), soft(one?.link)])),
+    '',
+    tableOf(
+      '存不存（刷新还在吗） | 能自己配的 | 管什么 | 默认是什么 | 可选值从哪来 | 选错了会怎样',
+      config.length === 0 ? [['（没有可配项）', '—', '—', '—', '—', '—']] : config.map((one) => [
+        persistenceLabel(one?.persistence),
+        cell(one?.key),
+        cell(one?.watches),
+        cell(one?.default),
+        cell(one?.valuesFrom),
+        cell(one?.wrongChoice),
+      ]),
+    ),
+    '',
+    '状态矩阵（每种状态：他看到什么 / 他能做什么 / agent 能接着做什么）——',
+    '图号对着「卡片画哪五态」那一节：',
+    '',
+    tableOf('# | 状态 | 他看到什么 | 他能做什么 | agent 能接着做什么', stateRows),
+    '',
+    '### 表 2 agent：他能替用户做什么、哪几件要点头',
+    '',
+    tableOf(
+      '能力 | 一句话 | 传什么 / 拿回什么（贴真实调用与返回） | 要点头吗 | 点头时他看到的"会发生什么" | 在哪些项目里出现',
+      capabilities.length === 0
+        ? [['（这份模块故意没有能力）', '—', '—', '—', '—', '—']]
+        : capabilities.map((one) => [
+            cell(one?.name),
+            cell(one?.oneLine),
+            cell(one?.shape),
+            cell(one?.approval),
+            soft(one?.approvalText),
+            scopeLabel(one?.scope),
+          ]),
+    ),
+    '',
+    '### 表 3 联动：agent 动完，这个模块哪一格变',
+    '',
+    tableOf('谁在动 | 面板什么时候变 | 哪一格变（投影 + 最窄那个参数） | 用户看到什么', linkage.length === 0
+      ? [['（待填）', PENDING, PENDING, PENDING]]
+      : linkage.map((one) => [cell(one?.who), cell(one?.when), cell(one?.whatChanges), cell(one?.userSees)])),
+    '',
+    '### 数据源探明记录',
+    '',
+    ...(reads.length <= 1
+      ? [...datasourceRowsOf(reads[0]), '']
+      : reads.flatMap((one, index) => [`#### 读 ${String(index + 1)}`, '', ...datasourceRowsOf(one), ''])),
+    '### 验收（做完逐条打勾：`dsh-wb-module design accept`）',
+    '',
+    ...acceptanceRows,
+    '',
+    `> 这一段由 \`${DESIGN_FILE}\` 生成（\`dsh-wb-module design render\`），别手改。`,
+  ].join('\n');
+}
+
+function regionOf(readme) {
+  const start = readme.indexOf(START_MARK);
+  const end = readme.indexOf(END_MARK);
+  if (start === -1 || end === -1 || end < start) return undefined;
+  return { start, end };
+}
+
+export function applyToReadme(root, markdown) {
+  const file = join(root, 'README.md');
+  const block = `${START_MARK}\n${markdown}\n${END_MARK}`;
+  if (!existsSync(file)) {
+    writeFileSync(file, `# ${text(manifestOf(root).name) || '模块'}\n\n${block}\n`);
+    return 'created';
+  }
+  const text0 = readFileSync(file, 'utf8');
+  const at = regionOf(text0);
+  if (at !== undefined) {
+    const next = `${text0.slice(0, at.start)}${block}${text0.slice(at.end + END_MARK.length)}`;
+    if (next === text0) return 'same';
+    writeFileSync(file, next);
+    return 'updated';
+  }
+  const heading = text0.indexOf('## 需求底稿');
+  const insertAt = (() => {
+    if (heading === -1) return text0.length;
+    const after = text0.indexOf('\n## ', heading + 1);
+    return after === -1 ? text0.length : after + 1;
+  })();
+  const before = text0.slice(0, insertAt).replace(/\s*$/, '');
+  const after = text0.slice(insertAt);
+  writeFileSync(file, `${before}\n\n${block}\n${after === '' ? '' : `\n${after}`}`);
+  return 'inserted';
+}
+
+function manifestOf(root) {
+  try {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function checkDesign(root) {
+  const design = readDesign(root);
+  if (design === undefined) {
+    console.error(`✖ 没有 ${DESIGN_FILE} —— 先跑 dsh-wb-module design init`);
+    process.exit(1);
+  }
+  const cells = emptyCells(design);
+  const rows = (key) => asRows(design[key]).length;
+  const acceptance = asRows(design.acceptance);
+  const accepted = acceptance.filter((one) => one?.checked === true).length;
+
+  const readme = existsSync(join(root, 'README.md')) ? readFileSync(join(root, 'README.md'), 'utf8') : '';
+  const at = regionOf(readme);
+  const fresh = at === undefined ? false : readme.slice(at.start, at.end) === `${START_MARK}\n${renderDesign(design)}\n`;
+
+  console.log(`design.json：面板 ${rows('panel')} 行 · 状态 ${STATE_KEYS.length} 态 · 配置 ${rows('config')} 项 · 能力 ${rows('capabilities')} 条 · 联动 ${rows('linkage')} 行 · 验收 ${accepted}/${acceptance.length}`);
+  if (cells.length > 0) {
+    console.error(`✖ 还空着 ${cells.length} 格（"空着的格就是还没定的事"，别带着空格往下做）：`);
+    for (const one of cells) console.error(`  · ${one}`);
+  }
+  if (!fresh) {
+    console.error('✖ README 里那一段落后于 design.json（或者没有标记）—— 跑 dsh-wb-module design render');
+  }
+  if (cells.length === 0 && fresh) {
+    console.log(`✔ 三张表填全了，README 也是最新的${accepted === acceptance.length ? '，验收也打完了' : `；验收还差 ${acceptance.length - accepted} 条（用户点头后跑 design accept）`}`);
+  }
+  process.exit(cells.length === 0 && fresh ? 0 : 1);
+}
+
+export async function design({ root, args = [] }) {
+  const action = args[0] ?? 'check';
+
+  if (action === 'init') {
+    if (existsSync(join(root, DESIGN_FILE))) {
+      console.error(`✖ ${DESIGN_FILE} 已经在了；要重来先删掉它`);
+      process.exit(1);
+    }
+    const design0 = skeleton(manifestOf(root));
+    writeDesign(root, design0);
+    const how = applyToReadme(root, renderDesign(design0));
+    console.log(`✔ 写好 ${DESIGN_FILE}（三张表 + 状态矩阵 + 数据源记录 + 验收清单的空骨架）`);
+    console.log(`  README 的那一段：${how === 'created' ? '新建' : how === 'inserted' ? '插进「需求底稿」那一节' : '已更新'}`);
+    console.log('  接着把每一格填成"用户看得见的东西"，然后 dsh-wb-module design check');
+    return;
+  }
+
+  if (action === 'render') {
+    const design0 = readDesign(root);
+    if (design0 === undefined) {
+      console.error(`✖ 没有 ${DESIGN_FILE} —— 先跑 dsh-wb-module design init`);
+      process.exit(1);
+    }
+    const how = applyToReadme(root, renderDesign(design0));
+    console.log(`✔ README 的那一段：${how === 'same' ? '本来就是最新的' : how === 'updated' ? '更新了' : how === 'inserted' ? '插进「需求底稿」那一节' : '建了 README'}`);
+    return;
+  }
+
+  if (action === 'accept') {
+    const design0 = readDesign(root);
+    if (design0 === undefined) {
+      console.error(`✖ 没有 ${DESIGN_FILE} —— 先跑 dsh-wb-module design init`);
+      process.exit(1);
+    }
+    const acceptance = asRows(design0.acceptance);
+    if (acceptance.length === 0) {
+      console.error('✖ 验收清单是空的 —— 先写清"打开哪 → 看什么 → 点什么 → 应该看到什么"');
+      process.exit(1);
+    }
+    design0.acceptance = acceptance.map((one) => ({ ...one, checked: true }));
+    design0.acceptedAt = new Date().toISOString();
+    writeDesign(root, design0);
+    applyToReadme(root, renderDesign(design0));
+    console.log(`✔ ${acceptance.length} 条验收全部打勾（只在他真的逐条看过之后再跑这条）`);
+    return;
+  }
+
+  if (action === 'check') {
+    checkDesign(root);
+    return;
+  }
+
+  console.error(`不认识的 design 动作：${action}（可用：init / check / render / accept）`);
+  process.exit(2);
+}

package/src/discover.mjs

@@ -12,7 +12,7 @@ function manifestOf(dir) {
   }
 }
 
-function workspaceRootOf(start) {
+export function workspaceRootOf(start) {
   if (process.env.DSH_WB_ROOT) return process.env.DSH_WB_ROOT;
   let dir = start;
   for (;;) {

package/src/init.mjs

@@ -1,4 +1,5 @@
 import { cpSync, existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { DESIGN_FILE, applyToReadme, readDesign, renderDesign } from './design.mjs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -60,5 +61,9 @@ export async function init({ root, args = [] }) {
     }
   };
   walk(target);
-  console.log(`${target} 建好了：${unit} 模块骨架（模板 ${which}；build / check / selfcheck 已接工具）`);
+  const declared = readDesign(target);
+  if (declared !== undefined) applyToReadme(target, renderDesign(declared));
+  const tables = existsSync(join(target, DESIGN_FILE)) ? `${DESIGN_FILE} 里那份三张表` : '还没有三张表（dsh-wb-module design init 生成）';
+  console.log(`${target} 建好了：${unit} 模块骨架（模板 ${which}；build / check / design / selfcheck 已接工具）`);
+  console.log(`  需求底稿在 ${tables}；空格用 dsh-wb-module design check 查，README 由它生成`);
 }

package/src/publish.mjs

@@ -0,0 +1,134 @@
+// 发货前那一张清单：门禁 + 三张表 + `npm pack --dry-run` 的清单。
+//
+// ── 为什么要有这个命令 ────────────────────────────────────────────────────────
+//
+// 打包这件事有两条**静默**的坑，都真发生过：
+//   · `files` 里漏一个目录（`template-diy/` 那次）：在仓里跑永远看不出问题，装出来的那份
+//     `init --template diy` 直接报"模板不存在"；
+//   · 产物/声明对不上（`exports` 指向的文件没被 `files` 带上）：装上去加载器找不到入口。
+// 两条都不会在开发时冒头，只会在"别人装到那一刻"炸。所以把它们变成发货前的一条命令。
+//
+// 这条命令**只做 dry run**：真发布要凭据、要人点头，不在这里做。它跑完会打印你该跑的那一条。
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { DESIGN_FILE } from './design.mjs';
+
+/** 门禁那几条命令自己会 `process.exit`（它们本来就是 CLI），所以这里**走子进程** ——
+ *  直接 import 进来调，成功那次也会把整条 publish 结束掉（实测：清单还没打印就退出了）。 */
+const CLI = fileURLToPath(new URL('../bin/dsh-wb-module.mjs', import.meta.url));
+
+function runCli(root, argv) {
+  try {
+    execFileSync(process.execPath, [CLI, ...argv, '--cwd', root], { stdio: 'inherit' });
+  } catch {
+    console.error(`✖ ${argv.join(' ')} 没过 —— 清单先不打印了，把上面那些红字处理掉`);
+    process.exit(1);
+  }
+}
+
+function readManifest(root) {
+  return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+}
+
+function packList(root) {
+  const cache = join(tmpdir(), 'dsh-wb-pack-cache');
+  // `--ignore-scripts`：`prepack`（= build）会往 stdout 打自己的日志，和 `--json` 的输出混在一起
+  // 就没法 parse 了（实测）。反正上面已经自己 build 过一遍，这里不需要 npm 再跑一次。
+  const raw = execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts', '--cache', cache], {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const start = raw.search(/[[{]/);
+  if (start === -1) throw new Error(`npm pack 没有输出 JSON：${raw.slice(0, 200)}`);
+  const parsed = JSON.parse(raw.slice(start));
+  return Array.isArray(parsed) ? parsed[0] : parsed;
+}
+
+const normalize = (one) => String(one).replace(/^\.\//, '');
+
+export async function publish({ root }) {
+  if (!existsSync(join(root, 'package.json'))) {
+    console.error(`✖ ${root} 里没有 package.json —— 这不是一个包目录`);
+    process.exit(2);
+  }
+  const manifest = readManifest(root);
+  const unit = manifest?.dsh?.workbench?.unit;
+  const isModule = typeof unit === 'string' && unit !== '';
+
+  if (isModule) {
+    // 先构建：清单评的是**要发出去的那份**，而 `npm pack` 自己也会跑 prepack（= build）——
+    // 不先构建就会拿"还没构建"的半成品去跑门禁，红得莫名其妙。
+    runCli(root, ['build']);
+    runCli(root, ['check']);
+    if (existsSync(join(root, DESIGN_FILE))) runCli(root, ['design', 'check']);
+    else console.log('○ 没有 design.json（三张表还没落成机器形状）—— 建议先 dsh-wb-module design init');
+  } else {
+    console.log('○ 这不是一个 wb 模块包（没有 dsh.workbench.unit）—— 跳过十条判据，只查打包清单');
+  }
+
+  const packed = packList(root);
+  const paths = (packed.files ?? []).map((one) => normalize(one.path));
+  const declared = Array.isArray(manifest.files) ? manifest.files.map(normalize) : [];
+  const problems = [];
+
+  const artifacts = Object.values(manifest.exports ?? {})
+    .filter((one) => typeof one === 'string')
+    .map(normalize)
+    .filter((one) => one !== '' && !one.endsWith('.css'));
+  for (const one of artifacts) {
+    if (!paths.includes(one)) problems.push(`exports 里的 ${one} 不在包里（files 少带了它）`);
+  }
+
+  if (isModule && !paths.includes('cordis.patch.yml')) {
+    problems.push('cordis.patch.yml 不在包里 —— 模块是靠它插进 dsh 组合的');
+  }
+
+  const templateDirs = readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith('template'))
+    .map((entry) => entry.name);
+  for (const one of templateDirs) {
+    if (!declared.includes(one)) problems.push(`模板目录 ${one}/ 不在 files 里（init --template 会当场找不到它）`);
+  }
+
+  const readmeOnDisk = existsSync(join(root, 'README.md'));
+  if (readmeOnDisk && !paths.includes('README.md')) problems.push('README.md 在盘上却没进包');
+  if (!readmeOnDisk) console.log('○ 包根下没有 README.md —— 发出去的包在源上会是一页空白，建议补一份');
+
+  // `.tpl` 在 `template*/` 里是**本体**（init 拷过去才剥壳），只有在别处冒出来才算混进脏东西。
+  const inTemplate = (one) => templateDirs.some((dir) => one.startsWith(`${dir}/`));
+  const leftovers = paths.filter((one) => !inTemplate(one) && (one.endsWith('.tpl') || one.includes('.init-')));
+  if (leftovers.length > 0) problems.push(`包里混进了不该发的东西：${leftovers.slice(0, 3).join('、')}`);
+
+  for (const one of declared) {
+    const hit = paths.some((path0) => path0 === one || path0.startsWith(`${one}/`));
+    if (!hit) problems.push(`files 里声明了 ${one}，但包里没有它（声明与产物不一致）`);
+  }
+
+  const listed = packed.entryCount ?? paths.length;
+  console.log(
+    `打包清单：${listed} 个文件 · ${(packed.size / 1024).toFixed(1)} KB（解包 ${(packed.unpackedSize / 1024).toFixed(1)} KB）`,
+  );
+  for (const one of paths.slice(0, 12)) console.log(`  · ${one}`);
+  if (listed > 12) console.log(`  … 还有 ${listed - 12} 个`);
+
+  if (problems.length > 0) {
+    console.error(`✖ 发货前清单 ${problems.length} 条不过：`);
+    for (const one of problems) console.error(`  · ${one}`);
+    process.exit(1);
+  }
+
+  if (manifest.private === true) {
+    console.log('✔ 清单干净。包是 `private: true` —— **不会**发到任何源（DIY 的模块都该这样）。');
+    console.log(`  要给别人用：摘掉 private + 写上发布目标，再自己跑 \`npm publish\`（这条命令不会替你发）。`);
+    return;
+  }
+  console.log('✔ 清单干净。真要发就自己跑（凭据在你手上）：');
+  console.log(`  npm publish${manifest.publishConfig?.registry === undefined ? '' : ` --registry ${manifest.publishConfig.registry}`}`);
+  console.log(`  包目录：${relative(process.cwd(), root) === '' ? '.' : relative(process.cwd(), root)}`);
+}