@bushizhanghan/dsh-publish-gate 0.3.2 → 0.3.4

package/README.md

@@ -30,7 +30,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | 工具 | 作用 |
 |---|---|
 | `publish_gate` | 全量门禁：清单 + 产物 + 运行时 + 浏览器半边 + 网络，返回 `safeToPublish`（`skipPack` / `skipTools` / `skipClient` / `skipNetwork` 可逐层跳过） |
-| `publish_gate_tools` | 只跑运行时层：在子进程里 `apply(ctx)`，看注册了哪些工具、有没有缺 `execute`、重名、`presentCall` 抛错、`card` 用了宿主不认识的值 |
+| `publish_gate_tools` | 只跑运行时层：在子进程里 `apply(ctx)`，看注册了哪些工具、有没有缺 `execute`、重名、`presentCall` 抛错、`card` 用了宿主不认识的值 | 传 `call: ["工具名"]` 可以**真的调一次**（空参数）：注册永远不会执行 `execute`，所以「一调就抛 ReferenceError」这类 bug 只有这一条能看见。默认不调——有些工具会开程序或写文件，你点名才算同意。超时单独算 `tool-call-slow`（warn），不跟「真的抛了」混在一起：`of_env` 这种要起 WSL 的工具本来就慢。 |
 | `publish_gate_client` | 只跑浏览器半边：在子进程里假造 `window.__ModuleLoader__`，看 bundle 会不会加载、`apply` 会不会抛、到底往哪个服务注册了东西、`inject` 有没有漏 |
 | `publish_gate_verify` | 发后校验：`npm pack --dry-run` 的 shasum 和 registry 上的 `dist.shasum` 逐字节比，比版本号猜准 |
 | `publish_gate_patch` | 只查 `cordis.patch.yml`——「插件装了但工具没出现」的第一个怀疑对象 |
@@ -183,7 +183,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 65 个引擎单测
+node --test                      # 67 个引擎单测
 node test/integration.test.mjs   # 26 条集成断言（9 个真实插件作 fixture）
 ```
 

package/lib/engine.js

@@ -1062,6 +1062,7 @@ ctx.tools = {
       hasExecute: typeof def?.execute === 'function',
       hasOutputSchema: Boolean(def && def.output && def.output.schema),
       cardKind: card,
+      run: typeof def?.execute === 'function' ? def.execute : null,
     })
     walkParams(def?.parameters, typeof def?.name === 'string' ? def.name : '(unnamed)')
   },
@@ -1073,7 +1074,29 @@ try {
   stage = 'apply'
   if (typeof mod.apply !== 'function') throw new Error('lib/index.js does not export apply')
   await mod.apply(ctx, {})
-  emit({ ok: true, tools: registered, badParamTypes })
+  // Calling a tool is opt-in: some tools launch applications or write files, so
+  // the caller names the ones it considers safe. A tool that throws here is a
+  // bug the author cannot see any other way - registration never runs execute.
+  stage = 'call'
+  const wanted = new Set(JSON.parse(process.env.PG_CALLS || '[]'))
+  const budget = Number(process.env.PG_CALL_MS || 8000)
+  const calls = []
+  for (const entry of registered) {
+    if (!wanted.has(entry.name) || !entry.run) continue
+    try {
+      await Promise.race([
+        Promise.resolve(entry.run({}, { signal: undefined })),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), budget)),
+      ])
+      calls.push({ name: entry.name, ok: true })
+    } catch (error) {
+      const message = String((error && error.message) || error)
+      // A slow tool is not a broken tool: of_env shells out to WSL and takes
+      // seconds by design. Only a real throw is a defect.
+      calls.push({ name: entry.name, ok: false, timedOut: message === 'timed out', error: message })
+    }
+  }
+  emit({ ok: true, tools: registered.map(({ run, ...rest }) => rest), badParamTypes, calls })
 } catch (error) {
   emit({ ok: false, stage, error: String((error && error.message) || error) })
 }
@@ -1088,6 +1111,11 @@ export async function checkToolRegistrations(dir, opts = {}) {
       timeout: opts.timeoutMs ?? 20_000,
       maxBuffer: 4 * 1024 * 1024,
       windowsHide: true,
+      env: {
+        ...process.env,
+        PG_CALLS: JSON.stringify(Array.isArray(opts.calls) ? opts.calls : []),
+        PG_CALL_MS: String(opts.callTimeoutMs ?? 8000),
+      },
     })
     const line = String(stdout).split('\n').filter((l) => l.startsWith('@@PG@@')).pop()
     if (!line) throw new Error('the child printed no result')
@@ -1132,6 +1160,30 @@ export async function checkToolRegistrations(dir, opts = {}) {
   }
 
   const seen = new Set()
+  for (const c of Array.isArray(payload.calls) ? payload.calls : []) {
+    if (c.ok) continue
+    if (c.timedOut) {
+      out.push(
+        F(
+          'tool-call-slow',
+          'warn',
+          `tool "${c.name}" did not answer within the call budget`,
+          'A slow tool is not a broken one — this may shell out or wait on a service. Reported so a hang is not mistaken for a pass, and NOT counted as a defect.',
+          'Raise callTimeoutMs if the tool is legitimately slow, or check that it returns at all.',
+        ),
+      )
+      continue
+    }
+    out.push(
+      F(
+        'tool-call-throws',
+        'error',
+        `tool "${c.name}" throws when called with no arguments`,
+        `${c.error}. Registration never runs execute, so nothing else in this gate can see it — the consumer hits it on the first call.`,
+        'Guard the missing input, or accept that the tool is unusable without arguments and say so in its description.',
+      ),
+    )
+  }
   for (const t of tools) {
     const label = t.name || '(unnamed)'
     if (!t.name) out.push(F('tool-missing-name', 'error', 'a registered tool has no name', 'The host cannot address a tool without a name.', 'Give it a name.'))
@@ -1643,7 +1695,7 @@ const RULE_ORDER = [
   'inject-missing-tools', 'inject-missing-web', 'inject-missing-webServer', 'inject-missing-timer',
   'inject-unused-service',
   'tool-missing-name', 'tool-duplicate-name', 'tool-missing-execute', 'tool-present-call-throws',
-  'tool-bad-card-kind', 'tool-missing-output-schema', 'tool-none-registered', 'tool-bad-parameter-type',
+  'tool-bad-card-kind', 'tool-missing-output-schema', 'tool-none-registered', 'tool-bad-parameter-type', 'tool-call-throws', 'tool-call-slow',
   'lib-debugger', 'lib-console-log', 'lib-hardcoded-path', 'lib-url-pathname', 'node-too-old', 'stale-build', 'hand-edited-build',
   'pack-omits-lib', 'pack-omits-patch', 'pack-omits-client', 'pack-oversize', 'pack-omits-readme', 'pack-omits-license', 'pack-ships-secret',
   'pack-unexpected-dir', 'pack-script-build', 'pack-unavailable',

package/lib/index.js

@@ -136,12 +136,18 @@ export function apply(ctx, config = {}) {
         properties: {
           dir: { type: 'string', description: 'Plugin directory.' },
           timeoutMs: { type: 'number', description: 'Kill the child after this long (default 20000).' },
+          call: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              'Tool names to actually call with empty arguments, e.g. ["page_watch_list"]. Off by default: some tools open applications or write files, so you name the ones you consider safe. A tool that throws on {} is a bug no other check can see, because registration never runs execute.',
+          },
         },
       },
       async execute(args) {
         const dir = resolveDir(args.dir)
         if (!dir) return { ok: false, error: 'no plugin directory given' }
-        const { findings, tools } = await checkToolRegistrations(dir, { timeoutMs: args.timeoutMs })
+        const { findings, tools } = await checkToolRegistrations(dir, { timeoutMs: args.timeoutMs, calls: args.call })
         return { ok: true, tools, findings, report: renderReport(findings, { title: `runtime gate · ${dir}` }) }
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Helps DSH plugin AUTHORS publish their plugins: a gate that turns every silent failure in the publish path into a deterministic check. Manifest layer — package.json completeness, BOM, YAML/JSON parseability, entry paths that point at no file, a patch the manifest never declares, patch insert correctness, a build whose lib/ is older than src/, inject services that are missing or misspelled, npm scope permissions, GitHub repo and token state, market entry format, LICENSE/README, tests. Artifact layer — runs `npm pack --dry-run` and reads what npm will really ship: code missing from the tarball, an unpacked patch, oversize packages, dev directories. Runtime layer — imports the entry in an isolated child process, calls apply(ctx), and reports tools that never register, missing execute, duplicate names, throwing presentCall and card kinds the host does not render. Browser half — loads the client bundle against a fake window.__ModuleLoader__ and reports a bundle that never loads, returns no apply, throws, registers nothing, or uses a service its own inject array omits, because a panel that never appears looks like a UI bug, not a packaging one. Then GitHub + npm + market, and a post-publish shasum check that proves the registry holds these exact bytes. 帮助插件作者一键发布：写完插件后跑一遍门禁（清单 / 产物 / 运行时 / 浏览器半边），把发布链路上的每个静默坑变成确定性检查，然后 GitHub + npm + 市场一键三连。",
   "type": "module",
   "main": "lib/index.js",