@bushizhanghan/dsh-publish-gate 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.7.0
+
+- `tool-output-invalid` (error): a tool result its own `output.schema` rejects. The host validates every
+  result and throws `ToolOutputError`, so the tool is unusable from the first call. Only checked when the
+  caller names the tool in `call`, because calling a tool can launch applications or write files.
+- `npm-not-logged-in` (error) / `npm-scope-mismatch` (warn): ask npm who it is before spending a publish.
+  ENEEDAUTH and the 403 that names neither the token nor the scope both become a message instead of a loss.
+- `readme-wrong-package` (error): the README install line names a different package — a README copied from
+  another plugin. Whoever follows it installs something else, and nothing fails because that package exists.
 ## 0.6.0
 
 - New rule `tool-undeclared-param`: a tool whose `execute` reads `args.x` that

package/README.md

@@ -68,9 +68,11 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `version-taken` | 这个版本已经在 registry 上，再发是 403 |
 | `version-behind-latest` | 本地版本比 registry 上的 `latest` **旧**。npm 会照收，但 `latest` 继续指向新版本——包上传了，按名字装的人永远拿不到，且没有任何报错 |
 | `registry-unreachable` | registry 回了 500/429 —— 版本检查**没跑**，所以别把它当干净 |
+| `npm-not-logged-in` | 这台机器上 npm 没有可用登录（`npm whoami` 报 ENEEDAUTH）。`npm publish` 会在 tarball 打好之后才失败 |
+| `readme-wrong-package` | README 的安装命令写的是**另一个包名**（从别的插件抄过来没改）。照着装的人装到别的插件上，而且不会报错——那个包真的存在 |
 
 ### 值得在发布前知道的（warn / info）
-`unscoped-name`（granular token 的 403）、`repo-missing`、`patch-name-unresolvable`（junction 放错层级）、`inject-unused-service`（`inject` 里写了个拼错的服务名，cordis 一直等它，插件静默不激活）、`no-publish-config-access`（scoped 包没写 `publishConfig.access`，只是提醒，因为命令里本来就带 `--access public`）、`publish-config-registry`（`publishConfig.registry` 指到内网 registry，版本发到别人装不到的地方）、`no-readme` / `readme-no-install` / `readme-no-profile`、`license-mismatch`、`no-tests` / `no-test-files` / `no-test-script`、`no-engines`、`bad-repo-url`、`no-git` / `no-gitignore`、`readme-tool-undocumented`（README 没提这个工具）/ `readme-test-count`（README 写的测试数和真实数不一致），以及市场条目的 `market-*` 全系列。
+`npm-scope-mismatch`（登录的账号不是包 scope 的所有者，PUT 会 403，而错误里既不说 token 也不说 scope——我为一个 403 花了一小时）、`unscoped-name`（granular token 的 403）、`repo-missing`、`patch-name-unresolvable`（junction 放错层级）、`inject-unused-service`（`inject` 里写了个拼错的服务名，cordis 一直等它，插件静默不激活）、`no-publish-config-access`（scoped 包没写 `publishConfig.access`，只是提醒，因为命令里本来就带 `--access public`）、`publish-config-registry`（`publishConfig.registry` 指到内网 registry，版本发到别人装不到的地方）、`no-readme` / `readme-no-install` / `readme-no-profile`、`license-mismatch`、`no-tests` / `no-test-files` / `no-test-script`、`no-engines`、`bad-repo-url`、`no-git` / `no-gitignore`、`readme-tool-undocumented`（README 没提这个工具）/ `readme-test-count`（README 写的测试数和真实数不一致），以及市场条目的 `market-*` 全系列。
 
 ### 产物层：npm 到底会发出什么
 
@@ -103,6 +105,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `tool-bad-card-kind` | `card: 'generic'` 的 `kind` 不在宿主认识的那一组里（`other` / `execute` / `search` / `read` / `edit` / `delete` / `fetch`）。注册不报错，卡片渲染坏掉——我五个插件一起踩过 |
 | `tool-bad-parameter-type` | `parameters` 里某个 `type` 写错（`"strin"`）。宿主把 `parameters` 渲染进 prompt、但**从不校验**调用值，所以这个 typo 只是悄悄把类型提示弄丢 |
 | `tool-undeclared-param` | `execute` 读了 `args.x`，但 `parameters.properties` 里没有 `x`。模型只能传 schema 声明过的参数，所以这个值在真实调用里永远是 `undefined`——代码在，永远不跑，也不报错。`args.x`、`args['x']`、`const { x } = args` 三种写法都认 |
+| `tool-output-invalid` | 工具返回的东西**自己的 output schema 不收**。宿主每个结果都拿 schema 校验，不匹配就抛 `ToolOutputError`——工具从第一次调用起就不可用，而报错只给一个 JSON 路径，不给是哪行代码返回的。只有点名 `call` 真的调了才检查。这个插件自己踩过：schema 收紧成 `additionalProperties: false`，但有一条错误分支还在返回 `{ ok, error }` |
 
 ### 浏览器半边：侧栏面板到底会不会出现
 
@@ -211,7 +214,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 83 个引擎单测
+node --test                      # 88 个引擎单测
 node test/integration.test.mjs   # 26 条集成断言（9 个真实插件作 fixture）
 ```
 

package/lib/engine.js

@@ -517,6 +517,33 @@ export function checkDocs(dir) {
     if (text && !/dsh plugin .*add .*--profile/.test(text) && !/dsh plugin --profile \S+ add/.test(text)) {
       out.push(F('readme-no-profile', 'info', 'README install line omits --profile', 'Omitting it installs into the default profile, which is not what every user wants.', 'Show `dsh plugin --profile desktop add <pkg>`.'))
     }
+    // A README copied from another plugin keeps the old package name, and the
+    // install line then installs something else entirely — with no error, since
+    // that package really does exist.
+    const pkg = readPkgJson(dir)
+    if (text && pkg?.name) {
+      const specs = [...text.matchAll(/dsh plugin\b[^\n]*?\badd\s+(?:--profile\s+\S+\s+)?(\S+)/g)]
+        .map((m) => m[1].replace(/[`'"]/g, '').trim())
+        .filter((s) => s && !s.startsWith('-'))
+      const wrong = [...new Set(specs)].filter((s) => {
+        if (s === pkg.name || s.startsWith('github:') || s.includes('://')) return false
+        // A different install FORM is not a copy-paste slip: an unscoped name in
+        // a scoped package's README is usually just shorthand for a dependency.
+        if (s.startsWith('@') !== pkg.name.startsWith('@')) return false
+        return /^@[\w.-]+\/[\w.-]+$|^[\w.-]+$/.test(s)
+      })
+      for (const spec of wrong) {
+        out.push(
+          F(
+            'readme-wrong-package',
+            'error',
+            `README install line says "${spec}" but the package is "${pkg.name}"`,
+            'A README copied from another plugin keeps the old name. Whoever follows it installs a different package — and nothing fails, because that package exists too.',
+            `Change the install line to ${pkg.name}.`,
+          ),
+        )
+      }
+    }
   }
   if (!existsSync(join(dir, 'LICENSE'))) {
     out.push(F('no-license', 'error', 'LICENSE is missing', 'npm warns on publish and the market listing shows an unknown license.', 'Add a LICENSE file (MIT is the ecosystem norm).'))
@@ -533,6 +560,66 @@ export function checkDocs(dir) {
 // npm / GitHub / market state
 // =====================================================================
 
+/**
+ * Who npm thinks you are on this machine.
+ *
+ * A publish fails at the very last step with ENEEDAUTH or a 403 that names
+ * neither the token nor the scope. Asking first turns that into a message
+ * instead of a spent version number.
+ */
+export async function checkPublishIdentity(dir, { timeoutMs = 15000, whoami } = {}) {
+  const out = []
+  let who = whoami
+  if (who === undefined) {
+    try {
+      const isWin = process.platform === 'win32'
+      const cmd = isWin ? process.env.ComSpec || 'cmd.exe' : 'npm'
+      const args = isWin ? ['/d', '/s', '/c', 'npm whoami'] : ['whoami']
+      const { stdout } = await runFile(cmd, args, { timeout: timeoutMs, windowsHide: true })
+      who = stdout.trim() || null
+    } catch (error) {
+      const text = String(error?.stderr || error?.message || error)
+      if (/ENEEDAUTH|E401|not logged in|need auth/i.test(text)) {
+        out.push(
+          F(
+            'npm-not-logged-in',
+            'error',
+            'npm has no usable login on this machine',
+            '`npm publish` will fail with ENEEDAUTH after the tarball has been built. A granular token that lacks publish rights fails later still, with a 403 that names neither the token nor the scope.',
+            'Run `npm login`, or put a publish-capable token in ~/.npmrc.',
+          ),
+        )
+      } else {
+        out.push(
+          F(
+            'npm-whoami-unavailable',
+            'info',
+            'could not ask npm who is logged in',
+            'The publish-identity check did not run, so nothing is claimed about it.',
+            'Make sure npm is on PATH and re-run.',
+          ),
+        )
+      }
+      return out
+    }
+  }
+
+  const pkg = readPkgJson(dir)
+  const scope = /^@([^/]+)\//.exec(pkg?.name || '')?.[1]
+  if (who && scope && who !== scope) {
+    out.push(
+      F(
+        'npm-scope-mismatch',
+        'warn',
+        `logged in as "${who}" but the package is under @${scope}`,
+        `Publishing under a scope needs a token that owns that scope. A granular token scoped to another owner answers 403 on the PUT — the error names neither the token nor the scope, which is why this takes an hour to diagnose.`,
+        `Log in as ${scope}, or mint a token with publish rights for @${scope}.`,
+      ),
+    )
+  }
+  return out
+}
+
 export function checkNpmState(dir) {
   const out = []
   const json = readPkgJson(dir)
@@ -1110,6 +1197,7 @@ ctx.tools = {
       name: typeof def?.name === 'string' ? def.name : null,
       hasExecute: typeof def?.execute === 'function',
       hasOutputSchema: Boolean(def && def.output && def.output.schema),
+      schema: (def && def.output && def.output.schema) || null,
       cardKind: card,
       undeclaredParams: undeclaredArgs(def),
       run: typeof def?.execute === 'function' ? def.execute : null,
@@ -1117,6 +1205,50 @@ ctx.tools = {
     walkParams(def?.parameters, typeof def?.name === 'string' ? def.name : '(unnamed)')
   },
 }
+// The host validates every tool result against output.schema and throws
+// ToolOutputError when it does not match — the tool is then unusable, and the
+// failure names a JSON path rather than the code that produced it. This gate
+// shipped exactly that bug: a permissive schema was tightened to
+// additionalProperties:false while one error path still returned { ok, error }.
+const validateValue = (schema, value, path) => {
+  if (!schema || typeof schema !== 'object') return null
+  const at = path || '$'
+  if (typeof schema.type === 'string' && schema.type !== 'json') {
+    const t = schema.type
+    const ok = t === 'array' ? Array.isArray(value)
+      : t === 'null' ? value === null
+      : t === 'integer' ? Number.isInteger(value)
+      : t === 'object' ? (value !== null && typeof value === 'object' && !Array.isArray(value))
+      : typeof value === t
+    if (!ok) return at + ' must be ' + t + ', got ' + (value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value)
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
+    return at + ' is not one of ' + JSON.stringify(schema.enum)
+  }
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    for (const key of Array.isArray(schema.required) ? schema.required : []) {
+      if (!(key in value)) return at + '.' + key + ' is required but missing'
+    }
+    if (schema.additionalProperties === false && schema.properties && typeof schema.properties === 'object') {
+      const extra = Object.keys(value).filter((k) => !(k in schema.properties))
+      if (extra.length) return at + ' has key(s) the schema does not declare: ' + extra.join(', ')
+    }
+    if (schema.properties && typeof schema.properties === 'object') {
+      for (const [key, sub] of Object.entries(schema.properties)) {
+        if (!(key in value)) continue
+        const bad = validateValue(sub, value[key], at + '.' + key)
+        if (bad) return bad
+      }
+    }
+  }
+  if (Array.isArray(value) && schema.items) {
+    for (let i = 0; i < value.length; i++) {
+      const bad = validateValue(schema.items, value[i], at + '[' + i + ']')
+      if (bad) return bad
+    }
+  }
+  return null
+}
 const emit = (payload) => process.stdout.write('\\n@@PG@@' + JSON.stringify(payload) + '\\n')
 let stage = 'import'
 try {
@@ -1134,11 +1266,11 @@ try {
   for (const entry of registered) {
     if (!wanted.has(entry.name) || !entry.run) continue
     try {
-      await Promise.race([
+      const value = 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 })
+      calls.push({ name: entry.name, ok: true, invalid: validateValue(entry.schema, value) })
     } 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
@@ -1211,7 +1343,20 @@ 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.ok) {
+      if (c.invalid) {
+        out.push(
+          F(
+            'tool-output-invalid',
+            'error',
+            `tool "${c.name}" returns a value its own output schema rejects: ${c.invalid}`,
+            'The host validates every result against output.schema and throws ToolOutputError on a mismatch. The tool is unusable from the first call, and the error names a JSON path rather than the line that produced it.',
+            'Either widen the schema or change what execute returns so the two agree.',
+          ),
+        )
+      }
+      continue
+    }
     if (c.timedOut) {
       out.push(
         F(
@@ -1959,14 +2104,14 @@ 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-undeclared-param', 'tool-call-throws', 'tool-call-slow',
+  'tool-bad-card-kind', 'tool-missing-output-schema', 'tool-none-registered', 'tool-bad-parameter-type', 'tool-undeclared-param', 'tool-call-throws', 'tool-output-invalid', 'tool-call-slow',
   'lib-debugger', 'lib-console-log', 'lib-hardcoded-path', 'lib-url-pathname', 'node-too-old', 'stale-build', 'hand-edited-build',
   'undeclared-import', 'dep-in-dev-only', 'unused-dependency',
   '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', 'version-behind-latest', 'registry-unreachable', 'publish-not-served',
+  'no-license', 'license-mismatch', 'version-taken', 'version-behind-latest', 'npm-not-logged-in', 'npm-scope-mismatch', 'npm-whoami-unavailable', 'registry-unreachable', 'publish-not-served',
   'publish-served-mismatch', 'publish-served', 'market-empty', 'market-no-url', 'market-url-not-github',
-  'market-no-name', 'market-name-shape', 'market-no-category', 'market-bad-category', 'market-no-desc', 'market-no-en', 'market-no-zh', 'unscoped-name', 'no-git', 'no-readme', 'readme-no-install', 'readme-no-profile',
+  'market-no-name', 'market-name-shape', 'market-no-category', 'market-bad-category', 'market-no-desc', 'market-no-en', 'market-no-zh', 'unscoped-name', 'no-git', 'no-readme', 'readme-no-install', 'readme-no-profile', 'readme-wrong-package',
   'market-no-repo', 'market-unavailable', 'market-duplicate-entry', 'market-npm-name-collision', 'market-repo-too-new',
   'git-uncommitted', 'git-tag-missing', 'git-tag-elsewhere',
   'readme-tool-undocumented', 'readme-test-count',

package/lib/index.js

@@ -22,6 +22,7 @@ import {
   checkTests,
   checkToolRegistrations,
   checkClientRuntime,
+  checkPublishIdentity,
   checkVersionTaken,
   compareVersions,
   latestPublished,
@@ -64,6 +65,7 @@ export function apply(ctx, config = {}) {
     if (pkgJson?.name && pkgJson?.version) {
       findings.push(...(await checkVersionTaken(pkgJson.name, pkgJson.version, { registry: cfg.registry })))
     }
+    findings.push(...(await checkPublishIdentity(dir, { timeoutMs: cfg.networkTimeoutMs })))
     // is the GitHub repo there?
     if (pkgJson?.repository) {
       const url = repoUrl(pkgJson.repository)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bushizhanghan/dsh-publish-gate",
-  "version": "0.6.0",
-  "description": "Pre-publish gate for DSH plugins in five layers: manifest, dependencies, artifact, runtime, browser half — plus traceability (can you point at the bytes you shipped?). 发布前门禁：清单、依赖、产物、运行时、浏览器半边，外加可追溯性。",
+  "version": "0.7.0",
+  "description": "Pre-publish gate for DSH plugins: manifest, dependencies, artifact, runtime, browser half, traceability and market readiness. 发布前的七层门禁。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {