@tokensapi/dsh-plugin-check 0.3.2 → 0.3.4

package/lib/cowork-plugin.mjs

@@ -1,83 +1,118 @@
-/* ============================================================
- * Cowork 插件入口:会话内插件体检工具
- * ============================================================
- * 装进 TokensCowork 后注册 plugin_check 工具:对任意 npm 插件包
- * 跑清单规则 + 包内补丁行检查(与 CLI 的清单阶段同源),模型或
- * 用户在会话里即可判断"这个插件装进来会不会有问题"。补丁行会
- * 从 tarball 里真读出来 —— 只看 registry 清单会漏掉"补丁行 name
- * 写成插件名"这类装上即崩的缺陷。含隔离启动冒烟的完整体检仍走
- * CLI:npx @tokensapi/dsh-plugin-check --package <name@ver>。
- * ============================================================ */
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import { checkPublishedPackage } from './registry-check.mjs'
-
-/** 缺省比对的运行时版本;宿主升级后可通过插件配置覆盖。 */
-const DEFAULT_RUNTIME = '0.1.3-alpha.1'
-const REGISTRY = 'https://registry.npmjs.org'
-const FETCH_TIMEOUT_MS = 15_000
-
-export const name = 'tokens-plugin-check'
-export const inject = ['tools']
-
-async function fetchManifest(packageName, version) {
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
-  try {
-    const response = await fetch(
-      `${REGISTRY}/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}`,
-      { signal: controller.signal, headers: { accept: 'application/json' } },
-    )
-    if (!response.ok) {
-      throw new Error(response.status === 404 ? `npm 上未找到 ${packageName}@${version}` : `npm 查询失败(HTTP ${response.status})`)
-    }
-    return await response.json()
-  } finally {
-    clearTimeout(timer)
-  }
-}
-
-/**
- * @param {import('@deepseek-ai/cordis').Context} ctx
- * @param {{ runtime?: string }} [config]
- */
-export function apply(ctx, config = {}) {
-  const runtime = typeof config.runtime === 'string' && config.runtime !== '' ? config.runtime : DEFAULT_RUNTIME
-  ctx.tools.register(defineTool({
-    name: 'plugin_check',
-    description: 'Check whether a published DSH/TokensCowork plugin npm package is safe to install: '
-      + 'forbidden lifecycle scripts, dual-kernel core dependencies, missing dsh bundle patch, '
-      + 'and runtime/peer compatibility against the current DSH runtime. '
-      + 'Returns ok=false with per-rule findings when the plugin would break the host.',
-    parameters: {
-      package: {
-        type: 'string',
-        required: true,
-        description: 'npm package name, e.g. "@tokensapi/dsh-progressive-tools".',
-      },
-      version: {
-        type: 'string',
-        description: 'Exact version to check. Defaults to the latest dist-tag.',
-      },
-    },
-    output: {
-      schema: { type: 'json' },
-      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
-    },
-    isConcurrencySafe: () => true,
-    async execute(args) {
-      const manifest = await fetchManifest(args.package, args.version ?? 'latest')
-      const { findings, inspectedPatch } = await checkPublishedPackage(manifest, runtime)
-      return {
-        package: manifest.name,
-        version: manifest.version,
-        runtime,
-        ok: !findings.some(finding => finding.level === 'error'),
-        inspectedPatch,
-        findings,
-        note: inspectedPatch
-          ? '以上为清单规则 + 包内补丁行检查;含隔离启动冒烟的完整体检请运行 npx @tokensapi/dsh-plugin-check --package <name@version>'
-          : '未读到包内补丁文件,补丁行未检查;请运行 npx @tokensapi/dsh-plugin-check --package <name@version> 做完整体检',
-      }
-    },
-  }))
-}
+/* ============================================================
+ * Cowork 插件入口:会话内插件体检工具
+ * ============================================================
+ * 装进 TokensCowork 后注册 plugin_check 工具:对本地插件目录或
+ * 任意 npm 插件包
+ * 跑清单规则 + 包内补丁行检查(与 CLI 的清单阶段同源),模型或
+ * 用户在会话里即可判断"这个插件装进来会不会有问题"。补丁行会
+ * 从 tarball 里真读出来 —— 只看 registry 清单会漏掉"补丁行 name
+ * 写成插件名"这类装上即崩的缺陷。含隔离启动冒烟的完整体检仍走
+ * CLI:npx @tokensapi/dsh-plugin-check --package <name@ver>。
+ * ============================================================ */
+import { resolve } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { checkManifest } from './manifest-check.mjs'
+import { checkPublishedPackage } from './registry-check.mjs'
+import { CONTRACT, checkContractBaseline } from './contract.mjs'
+
+/** 缺省比对的运行时版本;宿主升级后可通过插件配置覆盖。 */
+const DEFAULT_RUNTIME = '0.1.3-alpha.1'
+const REGISTRY = 'https://registry.npmjs.org'
+const FETCH_TIMEOUT_MS = 15_000
+
+export const name = 'tokens-plugin-check'
+export const inject = ['tools']
+
+async function fetchManifest(packageName, version) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const response = await fetch(
+      `${REGISTRY}/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}`,
+      { signal: controller.signal, headers: { accept: 'application/json' } },
+    )
+    if (!response.ok) {
+      throw new Error(response.status === 404 ? `npm 上未找到 ${packageName}@${version}` : `npm 查询失败(HTTP ${response.status})`)
+    }
+    return await response.json()
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ runtime?: string }} [config]
+ */
+export function apply(ctx, config = {}) {
+  const runtime = typeof config.runtime === 'string' && config.runtime !== '' ? config.runtime : DEFAULT_RUNTIME
+  ctx.tools.register(defineTool({
+    name: 'plugin_check',
+    description: 'Check whether a DSH/TokensCowork plugin is safe to install: forbidden lifecycle '
+      + 'scripts, dual-kernel core dependencies, missing or out-of-scope cordis patch rows, and '
+      + 'runtime/peer compatibility against the current DSH runtime. Returns ok=false with per-rule '
+      + 'findings when the plugin would break the host. '
+      + 'Pass "path" for a plugin the user is developing locally (checks the working tree, no publish '
+      + 'needed) — prefer this whenever the user asks about their own plugin before releasing it. '
+      + 'Pass "package" for an already published npm package. Exactly one of the two is required.',
+    parameters: {
+      path: {
+        type: 'string',
+        description: 'Local plugin directory containing package.json. Use for unpublished/in-development plugins.',
+      },
+      package: {
+        type: 'string',
+        description: 'Published npm package name, e.g. "@tokensapi/dsh-progressive-tools".',
+      },
+      version: {
+        type: 'string',
+        description: 'Exact version to check with "package". Defaults to the latest dist-tag.',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      const hasPath = typeof args.path === 'string' && args.path !== ''
+      const hasPackage = typeof args.package === 'string' && args.package !== ''
+      if (hasPath === hasPackage) {
+        throw new Error('plugin_check 需要且只需要一个目标:本地目录传 path,已发布包传 package')
+      }
+      if (hasPath) {
+        // 本地工作区体检:发版前就能判,不需要先 publish。隔离冒烟要装
+        // 依赖起子进程,宿主进程里不做,如实告知走 CLI。
+        const local = checkManifest(resolve(args.path), { runtime })
+        const localFindings = [...checkContractBaseline(runtime), ...local.findings]
+        return {
+          path: resolve(args.path),
+          package: local.manifest?.name,
+          version: local.manifest?.version,
+          runtime,
+          contract: CONTRACT,
+          ok: !localFindings.some(finding => finding.level === 'error'),
+          inspectedPatch: true,
+          findings: localFindings,
+          note: '以上为清单规则 + 补丁行检查(读的是本地工作区);隔离启动冒烟请在插件目录运行 '
+            + 'npx @tokensapi/dsh-plugin-check --runtime ' + runtime,
+        }
+      }
+      const manifest = await fetchManifest(args.package, args.version ?? 'latest')
+      const { findings, inspectedPatch } = await checkPublishedPackage(manifest, runtime)
+      const published = [...checkContractBaseline(runtime), ...findings]
+      return {
+        package: manifest.name,
+        version: manifest.version,
+        runtime,
+        contract: CONTRACT,
+        ok: !published.some(finding => finding.level === 'error'),
+        inspectedPatch,
+        findings: published,
+        note: inspectedPatch
+          ? '以上为清单规则 + 包内补丁行检查;含隔离启动冒烟的完整体检请运行 npx @tokensapi/dsh-plugin-check --package <name@version>'
+          : '未读到包内补丁文件,补丁行未检查;请运行 npx @tokensapi/dsh-plugin-check --package <name@version> 做完整体检',
+      }
+    },
+  }))
+}

package/lib/manifest-check.mjs

@@ -1,139 +1,138 @@
-/* ============================================================
- * 阶段①:清单体检(纯静态,秒级,离线)
- * ============================================================
- * 每一条规则都对应一种已经真实发生过的"把宿主搞崩/搞坏"路径,
- * 规则说明写在 README;error 挡上架,warning 提示即将收紧或
- * 潜在错配。判定为纯函数,便于单测与市场门禁复用。
- * ============================================================ */
-import { existsSync, readFileSync, statSync } from 'node:fs'
-import { join, resolve } from 'node:path'
-import semver from 'semver'
-import { checkPatchContent } from './patch-rows.mjs'
-
-/** 安装即执行任意代码的脚本;市场受控安装的既有红线。 */
-const FORBIDDEN_LIFECYCLE = ['preinstall', 'install', 'postinstall', 'prepare']
-
-/**
- * 携带身份语义的核心包:cordis 上下文与 dsh 服务在宿主/插件各持一份时
- * Symbol 不等,注册对不上。schemastery、cosmokit 等纯工具库不在此列,
- * 插件可以正常依赖。
- */
-const CORE_SCOPE = '@deepseek-ai/'
-const isIdentityCore = (name) => name === '@deepseek-ai/cordis'
-  || name.startsWith('@deepseek-ai/cordis-')
-  || name.startsWith('@deepseek-ai/dsh')
-
-const SUSPICIOUS_FILE = /(\.env(\.|$)|id_rsa|\.pem$|\.p12$|\.key$)/u
-
-/**
- * 对一个插件目录执行全部清单规则。
- * @param {string} pluginDir - 插件根目录(含 package.json)。
- * @param {{ runtime?: string }} [options] - runtime 为目标 DSH 运行时
- *   版本(如 0.1.3-alpha.1);给出时才执行 engine/peer 与其的交集判定。
- * @returns {{ findings: Array<{level: 'error'|'warning', rule: string, message: string}>, manifest?: object, rows?: object[] }}
- */
-export function checkManifest(pluginDir, options = {}) {
-  const findings = []
-  const error = (rule, message) => findings.push({ level: 'error', rule, message })
-  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
-
-  const manifestPath = resolve(pluginDir, 'package.json')
-  if (!existsSync(manifestPath)) {
-    error('M1-manifest', 'package.json 不存在')
-    return { findings }
-  }
-  let manifest
-  try {
-    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-  } catch (cause) {
-    error('M1-manifest', `package.json 不是合法 JSON: ${cause instanceof Error ? cause.message : String(cause)}`)
-    return { findings }
-  }
-
-  if (typeof manifest.name !== 'string' || manifest.name === '') {
-    error('M1-manifest', 'name 缺失')
-  }
-  if (typeof manifest.version !== 'string' || semver.valid(manifest.version) === null) {
-    error('M1-manifest', 'version 不是合法 SemVer')
-  } else if (semver.prerelease(manifest.version) !== null) {
-    warning('M1-manifest', `version ${manifest.version} 是预发布版;市场上架要求精确稳定版`)
-  }
-
-  const scripts = manifest.scripts ?? {}
-  for (const script of FORBIDDEN_LIFECYCLE) {
-    if (typeof scripts[script] === 'string') {
-      error('M2-lifecycle', `禁止 ${script} 生命周期脚本(安装即执行任意代码,市场受控安装会拒绝);构建请改用 prepack`)
-    }
-  }
-
-  const dependencies = manifest.dependencies ?? {}
-  for (const name of Object.keys(dependencies)) {
-    if (isIdentityCore(name)) {
-      error('M3-core-peer', `${name} 出现在 dependencies;核心运行时必须声明为 peerDependencies,否则宿主与插件各持一份实例,服务注册无法对上,典型症状是整个 Cowork 启动失败`)
-    }
-  }
-
-  const dsh = manifest.dsh ?? {}
-  const bundle = dsh.bundle ?? {}
-  let rows
-  if (typeof bundle.patch !== 'string' || bundle.patch === '') {
-    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
-  } else {
-    const patchPath = resolve(pluginDir, bundle.patch)
-    if (!existsSync(patchPath)) {
-      error('M4-bundle', `dsh.bundle.patch 指向的文件不存在: ${bundle.patch}`)
-    } else {
-      // M4/M5 与会话内体检共用同一份实现,避免两条路径判定漂移。
-      const checked = checkPatchContent(
-        typeof manifest.name === 'string' ? manifest.name : '',
-        readFileSync(patchPath, 'utf8'),
-      )
-      findings.push(...checked.findings)
-      rows = checked.rows
-    }
-  }
-
-  const engine = typeof dsh.engine === 'string' ? dsh.engine : undefined
-  if (engine === undefined) {
-    warning('M6-engine', 'dsh.engine 未声明(目标 DSH 运行时 SemVer 范围,如 ">=0.1.3-alpha.1 <0.2");该字段将成为上架必填')
-  } else if (semver.validRange(engine, { includePrerelease: true }) === null) {
-    error('M6-engine', `dsh.engine 不是合法 SemVer 范围: ${engine}`)
-  } else if (options.runtime !== undefined
-    && !semver.satisfies(options.runtime, engine, { includePrerelease: true })) {
-    error('M6-engine', `dsh.engine "${engine}" 不覆盖目标运行时 ${options.runtime}`)
-  }
-
-  const peers = manifest.peerDependencies ?? {}
-  if (options.runtime !== undefined) {
-    for (const [name, range] of Object.entries(peers)) {
-      if (!name.startsWith(`${CORE_SCOPE}dsh`)) continue
-      if (semver.validRange(range, { includePrerelease: true }) === null) {
-        error('M7-peer-range', `peer ${name} 的范围不合法: ${range}`)
-      } else if (!semver.satisfies(options.runtime, range, { includePrerelease: true })) {
-        warning('M7-peer-range', `peer ${name}@"${range}" 不含目标运行时 ${options.runtime};宿主升级后此插件可能在运行时断裂(接口错配类故障)`)
-      }
-    }
-  }
-
-  if (manifest.engines?.node === undefined) {
-    warning('M8-node-engines', 'engines.node 未声明;宿主运行在 Node 22+')
-  }
-  if (manifest.license === undefined) {
-    warning('M9-license', 'license 未声明')
-  }
-
-  const filesList = Array.isArray(manifest.files) ? manifest.files : []
-  for (const entry of filesList) {
-    if (typeof entry === 'string' && SUSPICIOUS_FILE.test(entry)) {
-      error('M10-secrets', `files 白名单包含疑似凭据文件: ${entry}`)
-    }
-  }
-  for (const candidate of ['.env', 'id_rsa']) {
-    const candidatePath = join(pluginDir, candidate)
-    if (existsSync(candidatePath) && statSync(candidatePath).isFile() && filesList.length === 0) {
-      warning('M10-secrets', `目录含 ${candidate} 且未用 files 白名单限定发布内容,npm pack 可能把它带上`)
-    }
-  }
-
-  return { findings, manifest, rows }
-}
+/* ============================================================
+ * 阶段①:清单体检(纯静态,秒级,离线)
+ * ============================================================
+ * 每一条规则都对应一种已经真实发生过的"把宿主搞崩/搞坏"路径,
+ * 规则说明写在 README;error 挡上架,warning 提示即将收紧或
+ * 潜在错配。判定为纯函数,便于单测与市场门禁复用。
+ * ============================================================ */
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import semver from 'semver'
+import { checkPatchContent } from './patch-rows.mjs'
+import { LIFECYCLE_SCRIPTS, lifecycleMessage } from './contract.mjs'
+
+/**
+ * 携带身份语义的核心包:cordis 上下文与 dsh 服务在宿主/插件各持一份时
+ * Symbol 不等,注册对不上。schemastery、cosmokit 等纯工具库不在此列,
+ * 插件可以正常依赖。
+ */
+const CORE_SCOPE = '@deepseek-ai/'
+const isIdentityCore = (name) => name === '@deepseek-ai/cordis'
+  || name.startsWith('@deepseek-ai/cordis-')
+  || name.startsWith('@deepseek-ai/dsh')
+
+const SUSPICIOUS_FILE = /(\.env(\.|$)|id_rsa|\.pem$|\.p12$|\.key$)/u
+
+/**
+ * 对一个插件目录执行全部清单规则。
+ * @param {string} pluginDir - 插件根目录(含 package.json)。
+ * @param {{ runtime?: string }} [options] - runtime 为目标 DSH 运行时
+ *   版本(如 0.1.3-alpha.1);给出时才执行 engine/peer 与其的交集判定。
+ * @returns {{ findings: Array<{level: 'error'|'warning', rule: string, message: string}>, manifest?: object, rows?: object[] }}
+ */
+export function checkManifest(pluginDir, options = {}) {
+  const findings = []
+  const error = (rule, message) => findings.push({ level: 'error', rule, message })
+  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
+
+  const manifestPath = resolve(pluginDir, 'package.json')
+  if (!existsSync(manifestPath)) {
+    error('M1-manifest', 'package.json 不存在')
+    return { findings }
+  }
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (cause) {
+    error('M1-manifest', `package.json 不是合法 JSON: ${cause instanceof Error ? cause.message : String(cause)}`)
+    return { findings }
+  }
+
+  if (typeof manifest.name !== 'string' || manifest.name === '') {
+    error('M1-manifest', 'name 缺失')
+  }
+  if (typeof manifest.version !== 'string' || semver.valid(manifest.version) === null) {
+    error('M1-manifest', 'version 不是合法 SemVer')
+  } else if (semver.prerelease(manifest.version) !== null) {
+    warning('M1-manifest', `version ${manifest.version} 是预发布版;`
+      + `市场受控安装只认稳定的精确版(上游 stableExactVersion),npm latest 若停在预发布版,`
+      + `用户端拿不到一键安装按钮,只会看到手动命令。预发布请发在 next 之类的 dist-tag 上`)
+  }
+
+  const scripts = manifest.scripts ?? {}
+  for (const script of LIFECYCLE_SCRIPTS) {
+    if (typeof scripts[script] === 'string') warning('M2-lifecycle', lifecycleMessage(script))
+  }
+
+  const dependencies = manifest.dependencies ?? {}
+  for (const name of Object.keys(dependencies)) {
+    if (isIdentityCore(name)) {
+      error('M3-core-peer', `${name} 出现在 dependencies;核心运行时必须声明为 peerDependencies,否则宿主与插件各持一份实例,服务注册无法对上,典型症状是整个 Cowork 启动失败`)
+    }
+  }
+
+  const dsh = manifest.dsh ?? {}
+  const bundle = dsh.bundle ?? {}
+  let rows
+  if (typeof bundle.patch !== 'string' || bundle.patch === '') {
+    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
+  } else {
+    const patchPath = resolve(pluginDir, bundle.patch)
+    if (!existsSync(patchPath)) {
+      error('M4-bundle', `dsh.bundle.patch 指向的文件不存在: ${bundle.patch}`)
+    } else {
+      // M4/M5 与会话内体检共用同一份实现,避免两条路径判定漂移。
+      const checked = checkPatchContent(
+        typeof manifest.name === 'string' ? manifest.name : '',
+        readFileSync(patchPath, 'utf8'),
+      )
+      findings.push(...checked.findings)
+      rows = checked.rows
+    }
+  }
+
+  const engine = typeof dsh.engine === 'string' ? dsh.engine : undefined
+  if (engine === undefined) {
+    warning('M6-engine', 'dsh.engine 未声明(目标 DSH 运行时 SemVer 范围,如 ">=0.1.3-alpha.1 <0.2");'
+      + '上游目前不强制读取该字段,但声明之后体检才能判断你与目标运行时是否相容')
+  } else if (semver.validRange(engine, { includePrerelease: true }) === null) {
+    error('M6-engine', `dsh.engine 不是合法 SemVer 范围: ${engine}`)
+  } else if (options.runtime !== undefined
+    && !semver.satisfies(options.runtime, engine, { includePrerelease: true })) {
+    error('M6-engine', `dsh.engine "${engine}" 不覆盖目标运行时 ${options.runtime}`)
+  }
+
+  const peers = manifest.peerDependencies ?? {}
+  if (options.runtime !== undefined) {
+    for (const [name, range] of Object.entries(peers)) {
+      if (!name.startsWith(`${CORE_SCOPE}dsh`)) continue
+      if (semver.validRange(range, { includePrerelease: true }) === null) {
+        error('M7-peer-range', `peer ${name} 的范围不合法: ${range}`)
+      } else if (!semver.satisfies(options.runtime, range, { includePrerelease: true })) {
+        warning('M7-peer-range', `peer ${name}@"${range}" 不含目标运行时 ${options.runtime};宿主升级后此插件可能在运行时断裂(接口错配类故障)`)
+      }
+    }
+  }
+
+  if (manifest.engines?.node === undefined) {
+    warning('M8-node-engines', 'engines.node 未声明;宿主运行在 Node 22+')
+  }
+  if (manifest.license === undefined) {
+    warning('M9-license', 'license 未声明')
+  }
+
+  const filesList = Array.isArray(manifest.files) ? manifest.files : []
+  for (const entry of filesList) {
+    if (typeof entry === 'string' && SUSPICIOUS_FILE.test(entry)) {
+      error('M10-secrets', `files 白名单包含疑似凭据文件: ${entry}`)
+    }
+  }
+  for (const candidate of ['.env', 'id_rsa']) {
+    const candidatePath = join(pluginDir, candidate)
+    if (existsSync(candidatePath) && statSync(candidatePath).isFile() && filesList.length === 0) {
+      warning('M10-secrets', `目录含 ${candidate} 且未用 files 白名单限定发布内容,npm pack 可能把它带上`)
+    }
+  }
+
+  return { findings, manifest, rows }
+}