@bushizhanghan/dsh-publish-gate 0.3.1 → 0.3.3

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 只有这一条能看见。默认不调——有些工具会开程序或写文件，你点名才算同意。 |
 | `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`——「插件装了但工具没出现」的第一个怀疑对象 |
@@ -135,7 +135,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 
 ### 代码卫生
 
-`lib-debugger`（error）、`lib-console-log`、`lib-hardcoded-path`（`C:\Users\...` 硬编码）、`lib-url-pathname`（`new URL(...).pathname` 在中文路径上会百分号编码，得用 `fileURLToPath`）。
+`lib-debugger`（error）、`lib-console-log`、`lib-hardcoded-path`（`C:\Users\...` 硬编码）、`lib-url-pathname`（`new URL(...).pathname` 在中文路径上会百分号编码，得用 `fileURLToPath`）、`node-too-old`（`engines.node` 写着 `>=18`，`lib/` 里却用了 `Object.groupBy`（21）或 `Promise.withResolvers`（22）。npm 对 `engines` 只是警告，照样装上，然后在 import 那一刻抛——用户看到的是「插件坏了」，不是版本不匹配）。字符串和注释里的同名文字不算。
 
 ### 构建产物：`src/` 和 `lib/` 谁更新
 
@@ -183,7 +183,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 64 个引擎单测
+node --test                      # 66 个引擎单测
 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,25 @@ 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 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 after 8s')), 8000)),
+      ])
+      calls.push({ name: entry.name, ok: true })
+    } catch (error) {
+      calls.push({ name: entry.name, ok: false, error: String((error && error.message) || error) })
+    }
+  }
+  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 +1107,7 @@ 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 : []) },
     })
     const line = String(stdout).split('\n').filter((l) => l.startsWith('@@PG@@')).pop()
     if (!line) throw new Error('the child printed no result')
@@ -1132,6 +1152,18 @@ export async function checkToolRegistrations(dir, opts = {}) {
   }
 
   const seen = new Set()
+  for (const c of Array.isArray(payload.calls) ? payload.calls : []) {
+    if (c.ok) 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.'))
@@ -1202,6 +1234,63 @@ export function checkLibHygiene(dir) {
   return out
 }
 
+/**
+ * Features that need a newer Node than the manifest promises.
+ *
+ * `engines.node` is only advisory — npm warns and installs anyway — so a plugin
+ * that says `>=20` and uses `Object.groupBy` (21) breaks on exactly the Node it
+ * advertised. Each entry is [name, regex, minimum major], newest evidence only.
+ */
+const NODE_FEATURES = [
+  ['Object.groupBy / Map.groupBy', /\b(?:Object|Map)\.groupBy\b/, 21],
+  ['Array.fromAsync', /\bArray\.fromAsync\b/, 22],
+  ['Promise.withResolvers', /\bPromise\.withResolvers\b/, 22],
+  ['import.meta.dirname', /\bimport\.meta\.dirname\b/, 21],
+  ['Array.prototype.toSorted / toReversed / toSpliced / with', /\.(?:toSorted|toReversed|toSpliced)\(|\.with\(/, 20],
+  ['structuredClone', /\bstructuredClone\s*\(/, 17],
+]
+
+/** `>=22.1.0`, `^20`, `>=18 <21` -> the first major it allows. */
+const minNodeMajor = (range) => {
+  if (typeof range !== 'string') return null
+  const m = /(\d+)/.exec(range)
+  return m ? Number(m[1]) : null
+}
+
+export function checkNodeVersion(dir) {
+  const declared = minNodeMajor(readPkgJson(dir)?.engines?.node)
+  if (declared === null) return []
+  const out = []
+  const seen = new Set()
+  for (const file of walkFiles(join(dir, 'lib'), /\.(?:js|mjs|cjs)$/)) {
+    const text = safeText(file)
+    if (text === null) continue
+    // Strings are stripped first: a tool description that names a feature is
+    // prose, not a call (the same false positive require-in-esm had).
+    const code = text
+      .split('\n')
+      .map(stripComment)
+      .join('\n')
+      .replace(/'(?:[^'\\\n]|\\.)*'/g, "''")
+      .replace(/"(?:[^"\\\n]|\\.)*"/g, '""')
+      .replace(/`(?:[^`\\]|\\.)*`/g, '``')
+    for (const [name, re, needs] of NODE_FEATURES) {
+      if (needs <= declared || seen.has(name) || !re.test(code)) continue
+      seen.add(name)
+      out.push(
+        F(
+          'node-too-old',
+          'warn',
+          `engines.node says ${JSON.stringify(readPkgJson(dir).engines.node)} but lib/ uses ${name} (needs >=${needs})`,
+          'npm only warns about engines, so it installs on the older Node and throws at import time — the consumer sees a broken plugin, not a version mismatch.',
+          `Raise engines.node to >=${needs}, or stop using ${name}.`,
+        ),
+      )
+    }
+  }
+  return out
+}
+
 const INJECT_HINTS = [
   ['tools', /ctx\.tools\b/],
   ['web', /ctx\.web\b/],
@@ -1564,6 +1653,7 @@ export function runStaticChecks(dir) {
     ...checkInjectCoverage(dir),
     ...checkClientHalf(dir),
     ...checkLibHygiene(dir),
+    ...checkNodeVersion(dir),
     ...checkBuildFreshness(dir),
     ...checkDocs(dir),
     ...checkTests(dir),
@@ -1586,7 +1676,7 @@ const RULE_ORDER = [
   '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',
-  'lib-debugger', 'lib-console-log', 'lib-hardcoded-path', 'lib-url-pathname', 'stale-build', 'hand-edited-build',
+  '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',
   'no-license', 'license-mismatch', 'version-taken', 'registry-unreachable', 'publish-not-served',

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.1",
+  "version": "0.3.3",
   "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",