dsh-deps 0.0.1 → 0.1.0

package/plugin.mjs

@@ -0,0 +1,156 @@
+/**
+ * dsh-deps 的 host 半：往 DSH 里注册模型可调用工具 `dsh_deps`。
+ *
+ * 契约（照本机 DSH 0.2.2-rc.1 实测）：
+ * - 只 import `node:` 内置与包内相对路径，**不 import `@deepseek-ai/*`**；
+ * - 工具用裸 JSON Schema ToolDefinition 注册，无编译；
+ * - 只读、不联网：latest 只来自调用方传的本地快照；快照缺了就 unknown；
+ * - 不自动改文件：pin 只返回 diff 文本。
+ */
+
+import { runAction, VERSION } from './lib/engine.mjs'
+import { renderReport } from './lib/format.mjs'
+import { describeError } from './lib/errors.mjs'
+
+/** cordis 插件名（= 包名）。 */
+export const name = 'dsh-deps'
+
+/** 需要宿主提供的服务：工具注册表。 */
+export const inject = ['tools']
+
+/** 默认值；可被 cordis.patch.yml 的 config 覆盖。 */
+const DEFAULTS = {
+  snapshot: null,
+  installed: null,
+  nodeVersion: '',
+}
+
+/** 工具参数（宿主强制 JSON Schema 子集；任意 JSON 字段用 {} 声明）。 */
+const PARAMETERS = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: 'string',
+      enum: ['plan', 'why', 'pin', 'audit'],
+      description: 'plan = 升级清单 + 五档分级 + 风险 + 建议顺序；why = 某个依赖为什么这么判；pin = 把范围收紧到已锁版本的 diff；audit = 一次体检。',
+    },
+    package_json: { description: 'package.json 解析后的对象（只读，不会被修改）。' },
+    package_json_text: { type: 'string', description: 'package.json 原文（用于 pin 生成带行号的 diff；与 package_json 二选一）。' },
+    snapshot: { description: '本地 registry 快照 {name:{latest,deprecated?,engines?,yanked?}}；latest 只能来自这里，缺了就 unknown。' },
+    installed: { description: 'installed 快照 {name:"x.y.z"}（例如从 lockfile 解析）；不传则当前版本取声明范围下界。' },
+    manifests: { type: 'array', items: { type: 'object' }, description: '工作区里所有 manifest（用于统计被依赖次数；第一份是根）。' },
+    dependents: { description: '显式的被依赖次数 {name: count}，覆盖自动统计。' },
+    node_version: { type: 'string', description: '当前 Node 版本（默认取运行时版本），用于判断 engines 兼容性。' },
+    name: { type: 'string', description: 'why 动作要解释的依赖名。' },
+  },
+  required: ['action'],
+}
+
+/** 工具返回值 schema：声明关键字段，允许可空 / 任意 JSON。 */
+const OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    tool: { type: 'string' },
+    version: { type: 'string' },
+    action: { type: 'string' },
+    readOnly: { type: 'boolean' },
+    wroteFiles: { type: 'array', items: { type: 'string' } },
+    manifestName: { type: 'string' },
+    nodeVersion: { type: 'string' },
+    snapshotProvided: { type: 'boolean' },
+    installedProvided: { type: 'boolean' },
+    versionSourceNote: { type: 'string' },
+    entries: { type: 'array', items: { type: 'object' } },
+    plan: {},
+    audit: {},
+    rationale: { type: 'string' },
+    phaseOrder: { type: 'array', items: { type: 'string' } },
+    found: { type: 'boolean' },
+    checks: { type: 'array', items: { type: 'object' } },
+    conclusion: { type: 'string' },
+    changes: { type: 'array', items: { type: 'object' } },
+    diff: { type: 'string' },
+    applied: { type: 'boolean' },
+    summary: { type: 'string' },
+    notes: { type: 'array', items: { type: 'string' } },
+    limitations: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['action', 'readOnly'],
+}
+
+/**
+ * 组装工具定义。
+ * @param {object} [config] 插件配置（来自 cordis.patch.yml）
+ * @returns {object} 可注册的 ToolDefinition
+ */
+export function createToolDefinition(config = {}) {
+  const settings = { ...DEFAULTS, ...config }
+
+  return {
+    name: 'dsh_deps',
+    description:
+      '依赖升级规划：给定 package.json 与（可选的）本地 registry 快照，算哪些依赖能升、升了有什么风险、按什么顺序升。'
+      + '五档分级写死：patch / minor / major / pinned / unknown；latest 只来自调用方给的本地快照，快照里没有就 unknown，绝不联网猜。'
+      + '风险信号具体到 major 升级 / engines 不兼容 / deprecated / yanked / peer 范围破坏，每条给建议动作；'
+      + '建议顺序先 patch 后 minor 再 major，同组按被依赖次数降序并说明理由。只读：不写 package.json / lockfile，pin 只返回 diff 文本。',
+    parameters: PARAMETERS,
+    output: {
+      schema: OUTPUT_SCHEMA,
+      render(_args, value) {
+        return [{ type: 'text', text: renderReport(value, { detail: 'brief' }) }]
+      },
+      presentationMeta(_args, value) {
+        return {
+          action: value.action,
+          verdict: value.audit?.verdict ?? null,
+          bump: value.plan?.counts?.byBump ?? null,
+          actionable: value.plan?.counts?.actionable ?? null,
+          changes: Array.isArray(value.changes) ? value.changes.length : null,
+        }
+      },
+    },
+    presentCall(args) {
+      return { card: 'search', title: `依赖升级规划 ${args.action}${args.name ? ` · ${args.name}` : ''}`, kind: 'search', rawInput: args }
+    },
+    presentResult(_args, result) {
+      if (result.isError || !result.meta) return undefined
+      const meta = result.meta
+      const state = meta.action === 'pin'
+        ? `pin ${meta.changes ?? 0} 项`
+        : meta.action === 'why'
+          ? '单依赖解释'
+          : `${meta.actionable ?? 0} 个可升 · ${meta.verdict ?? ''}`
+      return { card: 'search', title: `dsh_deps · ${state}`, content: result.content }
+    },
+    async execute(args, exec) {
+      try {
+        return await runAction(args.action, {
+          packageJson: args.package_json ?? settings.packageJson,
+          packageJsonText: args.package_json_text,
+          snapshot: args.snapshot ?? settings.snapshot,
+          installed: args.installed ?? settings.installed,
+          manifests: args.manifests,
+          dependents: args.dependents,
+          nodeVersion: args.node_version || settings.nodeVersion,
+          name: args.name,
+          signal: exec?.signal,
+        })
+      } catch (error) {
+        const info = describeError(error)
+        throw new Error(`[${info.code}] ${info.message}${info.hint ? `\n→ ${info.hint}` : ''}`)
+      }
+    },
+  }
+}
+
+/**
+ * 插件激活：注册工具。
+ * @param {object} ctx cordis 上下文（需已注入 tools）
+ * @param {object} [config] 插件配置
+ * @returns {void}
+ */
+export function apply(ctx, config = {}) {
+  ctx.tools.register(createToolDefinition(config))
+  ctx.logger?.info?.(`dsh-deps ${VERSION}: 已注册工具 dsh_deps（升级规划，只读不猜 latest）`)
+}