@bushizhanghan/dsh-publish-gate 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# 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
+  `parameters.properties` never declares. The host renders `parameters` into the
+  prompt and passes the model nothing else, so that value is undefined on every
+  real call — the code path exists and never runs, and nothing throws.
+  Covers `args.x`, `args['x']` and `const { x } = args`.
+
+## 0.5.0
+
+- New layer: traceability. `git-uncommitted` (files that ship in the tarball are
+  not committed), `git-tag-missing` (no `v<version>` tag on HEAD),
+  `git-tag-elsewhere` (the tag exists but points at another commit).
+- The incident behind it: a 1.2.7 went to npm while the GitHub release still
+  said 1.2.6 and the market entry still pointed at the old tarball.
+
+## 0.4.0
+
+- New layer: dependency truth. `undeclared-import` (lib/ imports a package
+  package.json never declares), `dep-in-dev-only` (only devDependencies satisfy
+  it — npm never installs those for the consumer), `unused-dependency` (info).
+- New rule `version-behind-latest`: publishing under the live `latest` is
+  accepted by npm and reaches nobody.
+
+## 0.3.4
+
+- `tool-call-slow` split from `tool-call-throws`: a timeout is not a defect.
+
+## 0.3.3
+
+- `publish_gate_tools` accepts `call: ["name"]` to really invoke a tool, opt-in
+  because some tools open applications or write files.
+
+## 0.3.2
+
+- New rule `node-too-old`: `engines.node` says one thing, `lib/` uses an API from
+  a newer Node. npm only warns on `engines`, so the plugin installs and then
+  throws at import.
+
+## 0.3.1
+
+- `publish_gate_commands` emits commands that actually run on this machine
+  (`cmd /c "npm publish --access public"` on Windows) and pairs the publish step
+  with a `publish_gate_verify` shasum check.
+
+## 0.3.0
+
+- New layer: the browser half. `checkClientHalf` / `checkClientRuntime` load the
+  bundle against a fake `window.__ModuleLoader__` and report a bundle that never
+  loads, never returns `apply`, throws, registers nothing, or uses a service its
+  `inject` array does not declare.
+- New layer: market readiness — the repo is already listed, another entry
+  publishes the same npm name, or the repo is under 24 hours old (the gate fails
+  and reruns itself).
+- New rules: `client-without-platform`, `pack-omits-client`, `pack-ships-secret`,
+  `private-field-set`, `publish-config-registry`, `tool-bad-parameter-type`,
+  `entry-path-missing`, `bundle-patch-not-declared`, `inject-unused-service`.
+- New tool `publish_gate_client` (9 tools).
+
+## 0.2.0
+
+- New layers: artifact (`npm pack --dry-run` — what npm will really ship) and
+  runtime (import the entry in an isolated child process, call `apply`, report a
+  throwing import, a throwing apply, missing execute, duplicate tool names, a
+  throwing `presentCall`, and card kinds the host does not render).
+- New tools `publish_gate_tools` and `publish_gate_verify`.
+- Fixed: `bad-repo-url` never fired for the object form of `repository`.
+
+## 0.1.0
+
+- First release: manifest rules, `cordis.patch.yml` insert checks, README and
+  test presence, npm name and registry state.

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 到底会发出什么
 
@@ -102,6 +104,8 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 | `tool-present-call-throws` | `presentCall` 抛——调用记录渲染时炸 |
 | `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 }` |
 
 ### 浏览器半边：侧栏面板到底会不会出现
 
@@ -210,7 +214,7 @@ dsh plugin --profile desktop add @bushizhanghan/dsh-publish-gate
 ## 开发
 
 ```sh
-node --test                      # 80 个引擎单测
+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)
@@ -1057,6 +1144,31 @@ const walkParams = (schema, path) => {
   }
   if (schema.items) walkParams(schema.items, path + '[]')
 }
+// The model only ever sends the arguments \`parameters\` declares — the host
+// renders that schema into the prompt and passes nothing else. So an execute
+// that reads args.dir while the schema never mentions dir is unreachable code:
+// every call sees undefined, and the tool looks broken with no error anywhere.
+const ARG_DOT = /\\bargs\\s*\\??\\.\\s*([A-Za-z_$][\\w$]*)/g
+const ARG_INDEX = /\\bargs\\s*\\[\\s*['"]([^'"]+)['"]\\s*\\]/g
+const ARG_DESTRUCTURE = /\\{\\s*([^{}]+?)\\s*\\}\\s*=\\s*args\\b/g
+const undeclaredArgs = (def) => {
+  const props = def?.parameters?.properties
+  if (!props || typeof props !== 'object') return []
+  const declared = Object.keys(props)
+  if (typeof def.execute !== 'function') return []
+  let src = ''
+  try { src = def.execute.toString() } catch { return [] }
+  const reads = []
+  for (const m of src.matchAll(ARG_DOT)) reads.push(m[1])
+  for (const m of src.matchAll(ARG_INDEX)) reads.push(m[1])
+  for (const m of src.matchAll(ARG_DESTRUCTURE)) {
+    for (const part of m[1].split(',')) {
+      const key = part.split(':')[0].split('=')[0].replace(/\\.\\.\\./, '').trim()
+      if (/^[A-Za-z_$][\\w$]*$/.test(key)) reads.push(key)
+    }
+  }
+  return [...new Set(reads)].filter((r) => !declared.includes(r))
+}
 const noopService = () => new Proxy(function () {}, {
   get: (target, prop) => {
     // Own properties win, or ctx.tools would resolve to another no-op proxy
@@ -1085,12 +1197,58 @@ 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,
     })
     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 {
@@ -1108,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
@@ -1185,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(
@@ -1229,6 +1400,21 @@ export async function checkToolRegistrations(dir, opts = {}) {
         ),
       )
     }
+
+    // The model only sends what `parameters` declares, so a read of anything
+    // else is unreachable: args.dir is undefined on every real call, and the
+    // tool looks broken while nothing throws.
+    for (const name of Array.isArray(t.undeclaredParams) ? t.undeclaredParams : []) {
+      out.push(
+        F(
+          'tool-undeclared-param',
+          'warn',
+          `tool "${label}" reads args.${name}, which parameters never declares`,
+          'The host renders parameters into the prompt and passes the model nothing else, so this value is always undefined on a real call. The code path exists and never runs.',
+          `Add "${name}" to parameters.properties, or stop reading it.`,
+        ),
+      )
+    }
   }
   const badParams = Array.isArray(payload.badParamTypes) ? payload.badParamTypes : []
   for (const where of badParams) {
@@ -1918,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-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.5.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": {
@@ -13,7 +13,8 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "dsh",