@dsh-workbench/module-tools 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "typescript-eslint": "^8.71.0",
-    "@dsh-workbench/shared": "0.3.5"
+    "@dsh-workbench/shared": "0.3.7"
   },
   "scripts": {
     "selfcheck": "node scripts/selfcheck/index.mjs"

package/src/checks/contracts.mjs

@@ -251,11 +251,15 @@ function fakeLongTasks(created) {
   return {
     create(options) {
       created.push(options);
+      // 形状跟着真外壳那份注册表走（`createLongTaskRegistry`）：假的那份少一个方法，
+      // 把注册表原样返回的模块就会被这条判据冤枉成"缺方法"——所以 `stop` / `live` 也在这里。
       return {
         start: () => ({}),
         snapshot: () => null,
         active: () => null,
         current: () => [],
+        live: () => [],
+        stop: () => false,
         onChange: () => () => {},
       };
     },
@@ -347,7 +351,7 @@ function mountOf(face, created, manifest, tools) {
   }
 }
 
-const LONG_TASK_METHODS = ['start', 'snapshot', 'active', 'current', 'onChange'];
+const LONG_TASK_METHODS = ['start', 'snapshot', 'active', 'current', 'live', 'stop', 'onChange'];
 
 const LONG_TASK_RENDERERS = ['useLongTask', 'LongTaskRow', 'longTaskDot'];
 
@@ -788,12 +792,19 @@ export async function run() {
       }
     }
 
-    // 长任务：跑一会儿的事，注册了就得让用户看得见那四盏灯。
+    // 长任务：跑一会儿的事，注册了就得让用户看得见那一行。
     //
     // 外壳按 mount 结果里的 longTasks 投影出 `${unit}/runs`（kit 的 useLongTask 读的就是它）。
-    // 契约里的状态只有四种：running / needs-login / ok / failed（`longTaskDot` 把它们映成
-    // 进行中 / 要登录 / 完成 / 出错）——**没有"停止"**，所以这里不查停止，只查"能不能画出来"：
-    //   · 注册表形状要全（少了方法，外壳那条 runs 路由读不动）；
+    // 契约里的状态是**五种**：running / needs-login / stopped / ok / failed（`longTaskDot` 把它们映成
+    // 进行中 / 要登录 / 灰点 / 完成 / 出错 —— `stopped` 落进默认分支，是"用户按停的"，不是成功也不是出错）。
+    // 契约里也**有"停止"**：注册表多一个 `stop(id)`，`run` 多收一个 `signal`。
+    // `start` 还可以带一个**可选**的 `session`（起这一趟的那个会话 id，模块从 `sessionIdOf(exec)` 拿）：
+    // 不记 = 用户在界面上按的 —— 外壳那两把 `workbench_long_tasks_*` 按它判"谁的"（自己起的免审批）。
+    // 判据**不查**这一条（它只查形状；"起的时候记没记来源"是形状之外的事）。
+    // 但"停止"在注册表这一侧的射程只有两件：外壳把 `signal` abort 掉、把这一趟标成 `stopped`；
+    // **真停不停得了看生产方认不认这个 signal** —— 那是模块的知识，判据查不了这一条
+    // （内部是 opencli 子进程那类编排，今天最多做到"我们不再等它"）。判据能查的是形状与"画得出来"：
+    //   · 注册表形状要全（少了方法，外壳那条 runs 路由 / 那颗停止钮就按不动）；
     //   · create 的 key 非空、run 与 view 都是函数（没有 view，卡片上那行就没有可渲染的快照）；
     //   · 真的注册了长任务，客户端产物里就得出现 kit 那套（useLongTask / LongTaskRow / longTaskDot），
     //     否则用户点完只看到"没反应"。
@@ -803,8 +814,9 @@ export async function run() {
         const missing = LONG_TASK_METHODS.filter((method) => typeof registry[method] !== 'function');
         if (missing.length > 0) {
           problems.push(
-            `${name}: 长任务注册表缺方法 ${missing.join(' / ')} —— 外壳按它给这个单元投影出 /runs 路由，` +
-              `kit 的 useLongTask 读的就是那条（注册表用 @dsh-workbench/shared/host 的 createLongTaskRegistry 建）`,
+            `${name}: 长任务注册表缺方法 ${missing.join(' / ')} —— 外壳按它给这个单元投影出 /runs 路由（停止那颗钮也按它发），` +
+              `kit 的 useLongTask 与左栏会话行那颗 loading 点读的也是它（后者走 \`live()\`；注册表用 ` +
+              `@dsh-workbench/shared/host 的 createLongTaskRegistry 建）`,
           );
         }
       }
@@ -827,7 +839,7 @@ export async function run() {
       if (!LONG_TASK_RENDERERS.some((one) => clientText.includes(one))) {
         problems.push(
           `${name}: 注册了长任务，但客户端产物里没有 ${LONG_TASK_RENDERERS.join(' / ')}（kit 里那套）—— ` +
-            `用户点完只看得到"没反应"，看不到进行中 / 要登录 / 完成 / 出错`,
+            `用户点完只看得到"没反应"，看不到进行中 / 要登录 / 停下的 / 完成 / 出错`,
         );
       }
     }

package/src/design.mjs

@@ -51,6 +51,26 @@ const ROWS = {
 const DATASOURCE_FIELDS = ['read', 'params', 'credentials', 'notLoggedIn', 'timeout'];
 const WRITE_FIELDS = ['command', 'params', 'credentials', 'preview', 'readback', 'undo', 'failure'];
 
+/** `params` 里写了"必填"，就得说清凭什么是必填 —— 来源只能是这五个词之一
+ *  （`已证` 那句话的来源是**录下来的图**上那个红 `*`，或者**契约**里 `--help -f json` 的 `required`）。**气味判据不是解析器**：
+ *  只看来源有没有写出来，不看句式、不数个数、不认字段名，也不校验来源是不是真的 ——
+ *  真话假话只有人和复核能判（照 `undo` 那条的原话：逼作者想过，不逼他造假）。 */
+const SOURCE_TAGS = ['已证', '声明', '人证', '契约', '未定'];
+
+/** `params` 里有没有一处「必填」**没被否掉** —— `非必填` / `不必填`（只看紧邻的那个字符）才算被否掉。
+ *  这是**字符级守卫**，只挡这一种写法：不认"必填项""必填字段"以外的语法、不做否定句理解。
+ *  为什么非要有它：`design check` 是模块作者天天跑的门禁，`非必填` 这种**明确说不要**的写法
+ *  被误咬一次，他下次就把这条判据当噪音 —— 误红的代价比漏一两次大得多。 */
+function hasBareRequired(value) {
+  let at = value.indexOf('必填');
+  while (at !== -1) {
+    const before = value[at - 1];
+    if (before !== '非' && before !== '不') return true;
+    at = value.indexOf('必填', at + 2);
+  }
+  return false;
+}
+
 /** 一条卡背后可以有多条读（甚至跨站点）：规范形状 `reads: [ … ]`，一条一行；
  *  `datasource: { … }` 是只有一条读时的写法（老模块都长这样，继续认）。 */
 function readsOf(design) {
@@ -208,6 +228,13 @@ export function emptyCells(design) {
   writes.forEach((write, index) => {
     const label = writes.length === 1 ? 'write' : `writes[${index}]`;
     for (const field of WRITE_FIELDS) need(cells, write?.[field], `${label}.${field}`);
+    // 写了"必填"却不带来源词 ⇒ 点名（`非必填` / `不必填` 那种**明确说不要**的不算，见 hasBareRequired）。
+    // 空着 / `（待填）` 是上一轮那条 `pending` 的事，两条不叠。
+    // 判的是**值**不是表头：渲染出来的行名「参数（必填 / 取值枚举 / 上限）」不在这条路上。
+    const params = text(write?.params);
+    if (!pending(params) && hasBareRequired(params) && !SOURCE_TAGS.some((tag) => params.includes(tag))) {
+      cells.push(`${label}.params.source`);
+    }
   });
 
   return cells;

package/template-diy/README.md.tpl

@@ -194,7 +194,12 @@ approvalDetail: async (call) => ({ zh: '会覆盖 3 个模块的产物，不碰
 mount({ longTasks, ... }) {
   const runs = longTasks?.create({
     key: 'rebuild',
-    run: async ({ payload, onStep }) => { onStep({ kind: 'start', text: '开始…' }); /* … */ return {}; },
+    run: async ({ payload, onStep, signal }) => {
+      onStep({ kind: 'start', text: '开始…' });
+      // signal 被 abort = 有人按了停止（用户 / agent）：每一轮都看一眼 `signal.aborted`，能收手就收手
+      /* … */
+      return {};
+    },
     outcome: (result) => ({ why: '…' }),
     view: (snapshot) => ({ steps: String(snapshot.steps.length) }),
   });
@@ -202,9 +207,27 @@ mount({ longTasks, ... }) {
 }
 ```
 
-浏览器侧用 kit 那套画（`kit.hooks.useLongTask` + `<LongTaskRow …/>`）：状态只有
-`running` 进行中 / `needs-login` 要登录 / `ok` 完成 / `failed` 出错 —— **契约里没有"停止"**，
-别在界面上摆一个不存在的按钮。
+起这一趟的那把工具里（`execute(args, exec)` 拿得到现场）记下来源：
+
+```ts
+runs.start({ workspace, target, payload, session: sessionIdOf(exec) ?? undefined });
+```
+
+`sessionIdOf`（`@dsh-workbench/shared/host`）说这次调用是哪个会话发的。**不记来源 = 用户按的**
+（或这一版之前起的）—— 停它要走审批；外壳自带的那两把 `workbench_long_tasks_list` /
+`workbench_long_tasks_stop` 就是这么判"谁的"（自己起的免审批，别人的 / 用户按的要审批，
+不在当前工作区的直接拒绝）。
+
+浏览器侧用 kit 那套画（`kit.hooks.useLongTask` + `<LongTaskRow …/>`）：状态有五种 ——
+`running` 进行中 / `needs-login` 要登录 / `stopped` 停下的（用户按停）/ `ok` 完成 / `failed` 出错。
+
+要给用户那颗停止钮，就在卡片上给那一行的 `LongTaskRow` 传 `stop`
+（词与取值照 dsh 任务列表那行：aria `停止任务 {label}` → 上膛 → 可见字 `确认停止`、
+aria `再次点击确认停止`，3 秒落膛；**失败那半是我们自己的** —— 不往钮里写「停止失败」，
+而是把这次请求失败的原话画在那一行下面，`failed` 给什么画什么）；**要停就认 `signal`，不认就别画** ——
+画了就是骗人：外壳只会把这一趟标成 `stopped`，你的活儿还在跑（内部是 opencli 子进程那类编排，
+今天最多做到"我们不再等它"）。要用这个新 prop 就得装带这次改动的那份外壳 ——
+把自己 `peerDependencies['@dsh-workbench/core']` 的下限抬到那一版。
 
 ### 存起来：他能自己配什么（`prefs`）