dsh-db-tool 0.1.9 → 1.3.0

package/README.md

@@ -36,11 +36,11 @@ dsh plugin --profile web add "dsh-db-tool@github:mengqi1436/dsh-db-tool"
 dsh plugin --profile web add "link:E:\path\to\dsh-db-tool"
 ```
 
-GaussDB 官方驱动未发布 npm，需先构建 vendor：`npm run build:gaussdb`（PowerShell）或 `bash scripts/build-gaussdb.sh`；运行要求 Node ≥ 22.12（产物依赖 p-limit@7 纯 ESM）。oracledb 安装脚本需 `npm approve-scripts oracledb`。详见 [docs/install.md](docs/install.md)。
+GaussDB 官方驱动未发布 npm，需先构建 vendor：`npm run build:gaussdb`（PowerShell）或 `bash scripts/build-gaussdb.sh`；运行要求 Node ≥ 22.12（产物依赖 p-limit@7 纯 ESM）。oracledb 安装脚本需 `npm approve-scripts oracledb`。mongodb 驱动已 bundle 进发布包（`vendor/mongodb-driver.cjs`，esbuild 构建，`npm run build:mongodb` 可重建），依赖树中不含 mongodb/punycode，详见 [docs/install.md](docs/install.md)。
 
 ## 安全模型
 
-- HTTP API 仅同源（`ctx.webServer` prefix `/dsh-db-tool/api`）+ loopback/Origin trust 校验（等价 ssh-tunnel `http-trust`），body 限 2MB
+- HTTP API 仅同源（`ctx.webServer` prefix `/dsh-db-tool/api`）+ 宿主 Connection 栅栏（`ctx.connection.requestRejection`：Host/Origin + 浏览器 token 鉴权。0.2.0-rc.1 起插件前缀路由不经宿主栅栏，故在 handler 顶层显式应用；宿主无 connection 服务时回退 loopback/Origin trust 校验，等价 ssh-tunnel `http-trust`），body 限 2MB
 - ro 双保险：服务层拦截 + 驱动会话级 `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY`（pg/gaussdb）、readonly 打开（SQLite）
 - SQL 参数绑定 + 标识符白名单（`[A-Za-z0-9_$]+` + 引用包裹）；MySQL `multipleStatements:false`；Redis 元数据走 `SCAN`（禁 `KEYS`）；Mongo 递归拒 `$where`
 - `run_script`：node:vm 独立 context、60s 超时、无 require/process/网络/文件系统，仅注入受限 `db.{query,execute}` 句柄
@@ -52,7 +52,7 @@ GaussDB 官方驱动未发布 npm，需先构建 vendor：`npm run build:gaussdb
 
 症状：DSH 启动后插件加载报 `failed to import`，伴随 `TypeError: Cannot read properties of null (reading 'Symbol(Symbol.iterator)')`，栈指向 `dsh-app-boot` 的 `routeScoped`。
 
-根因：上游 `@deepseek-ai/dsh-app-boot` 对 `createRequire(parent).resolve.paths(name)` 直接做 `for..of`，而 Node 对 core-module 同名包（`punycode` 等）返回 `null`，hoisted profile 下凡依赖树含此类 npm 包的插件都会炸。`0.1.7-rc.2` 中共两处同型缺陷：`routeScoped()` 与 `nativePackageDir()`，本补丁一并修复（两处分别独立判定，已打过旧版单处补丁的机器只会补上缺的那处）。
+根因：上游 `@deepseek-ai/dsh-app-boot` 对 `createRequire(parent).resolve.paths(name)` 直接做 `for..of`，而 Node 对 core-module 同名包（`punycode` 等）返回 `null`，hoisted profile 下凡依赖树含此类 npm 包的插件都会炸。`0.1.7-rc.2` 与 `0.2.0-rc.1` 中同型缺陷两处（锚点行逐字节一致，仅整体行号偏移 1 行）：`routeScoped()` 与 `nativePackageDir()`，本补丁一并修复（两处分别独立判定，已打过旧版单处补丁的机器只会补上缺的那处）。
 
 一键修复（幂等，应用前自动备份为 `index.js.bak-hotfix`；`--revert` 可还原）：
 
@@ -61,7 +61,9 @@ npm run patch:dsh        # Windows（PowerShell）
 npm run patch:dsh:sh     # macOS / Linux
 ```
 
-脚本自动探测 DSH 安装根（`--dsh-root` 可显式指定）；补丁文件见 `patches/dsh-app-boot-route-scoped-hotfix.patch`，仅对 `0.1.7-rc.2` 声明兼容，其他版本会警告（`--force` 覆盖）。上游 issue：<https://github.com/mengqi1436/dsh-db-tool/issues>（占位，待上游仓库开放后替换）。
+脚本自动探测 DSH 安装根（`--dsh-root` 可显式指定）；补丁文件按安装版本自动选择：`patches/dsh-app-boot-route-scoped-hotfix.patch`（`0.1.7-rc.2`）、`patches/dsh-app-boot-route-scoped-hotfix-0.2.0-rc.1.patch`（`0.2.0-rc.1`，与内建替换路径逐字节等价已验证）；不支持的版本会警告（`--force` 覆盖）。上游 issue：<https://github.com/mengqi1436/dsh-db-tool/issues>（占位，待上游仓库开放后替换）。
+
+**本插件的免补丁路径（0.1.9+）**：该 bug 的触发条件是依赖树中出现 core-module 同名包，mongodb 链（`mongodb-connection-string-url → whatwg-url → tr46 → punycode`）正是元凶。0.1.9 起 mongodb 驱动经 esbuild bundle 为 `vendor/mongodb-driver.cjs` 随包发布，生产依赖树不再含 mongodb 与 punycode——在**未修复宿主**（含桌面版 app.asar，无法打补丁）上也能正常安装加载。守卫测试 `tests/guard/deps-core-collision.spec.ts` 断言依赖树永不回退（dependencies 白名单 + lockfile 生产树 core 同名包零交集）。`patch:dsh` 仍保留，用于修复**其他**含同类依赖的插件或宿主自身报错。
 
 ## 测试
 
@@ -79,8 +81,8 @@ npx stryker run # 变异测试（范围 lib/guard + lib/manager + lib/store，
 lib/        host 插件（store / adapters×8 / guard / manager / http / index）
 client/     侧边栏单文件产物（client.js，即源码）
 skills/     db-admin skill
-scripts/    GaussDB vendor 构建、DSH dsh-app-boot 热修复（patch:dsh）
+scripts/    GaussDB vendor 构建、mongodb 驱动 bundle（build:mongodb）、DSH dsh-app-boot 热修复（patch:dsh）
 docs/       安装、HTTP 契约（api-contract.md）、skill 说明
 tests/      vitest（离线 mock + DBT_TEST_* 门控真机）
-vendor/     gaussdb-pg 构建产物（gitignore，不入库）
+vendor/     gaussdb 构建源/产物与 mongodb-driver.cjs bundle（gitignore，发布经 files 白名单收录 bundle）
 ```

package/dist/adapters/index.js

@@ -15,7 +15,7 @@ const INSTALL_HINTS = {
     gaussdb: 'npm run build:gaussdb（构建 vendor/gaussdb-pg）',
     sqlite: 'npm install better-sqlite3',
     redis: 'npm install redis',
-    mongodb: 'npm install mongodb',
+    mongodb: 'npm run build:mongodb（构建 vendor/mongodb-driver.cjs；发布包已内置产物，仅在缺失时需要）',
     oracle: 'npm install oracledb',
     dmdb: 'npm install dmdb',
 };

package/dist/adapters/mongodb/index.js

@@ -10,8 +10,36 @@
  *  - execute() 写白名单；updateMany/deleteMany 空 filter 直接拒绝（适配器级防线）。
  *  - 错误判定用 instanceof MongoServerError（官方建议不解析 message）。
  *  - 只读账号由用户配置官方内置角色 read / readWrite（见文档）。
+ *  - 驱动不进依赖树：mongodb 经 esbuild bundle 成 vendor/mongodb-driver.cjs（见
+ *    scripts/build-mongodb.mjs），运行时经 createRequire 相对加载（不经宿主
+ *    dsh-app-boot 的模块解析器，规避其 resolve.paths 未防护的 for..of bug，
+ *    该 bug 会因依赖树中的 punycode 等核心模块同名包直接炸掉插件加载）。
+ *    bson 保持 dependencies（bundle 的 external），保证 BSON 类实例与外部一致。
  */
-import { Binary, Decimal128, MongoClient, MongoServerError, Long, ObjectId, Timestamp, } from 'mongodb';
+import { createRequire } from 'node:module';
+let vendorCache;
+/** 容错加载 vendor bundle：缺失时返回 undefined（调用方降级处理），成功后缓存。
+ * 失败不缓存 → vendor 构建完成后无需重启即可恢复。 */
+function vendorOrNull() {
+    if (vendorCache === undefined) {
+        try {
+            // 相对路径从本模块出发：dist/adapters/mongodb/ 或 lib/adapters/mongodb/ 均指向包根 vendor/
+            vendorCache = createRequire(import.meta.url)('../../../vendor/mongodb-driver.cjs');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return vendorCache;
+}
+/** 严格加载 vendor bundle：缺失时抛带修复指引的错误 */
+function vendor() {
+    const m = vendorOrNull();
+    if (m === undefined) {
+        throw new Error('mongodb 驱动不可用：缺少 vendor/mongodb-driver.cjs。请在插件目录运行 npm run build:mongodb 构建后重试');
+    }
+    return m;
+}
 /** 危险操作：服务层拦截器用于确认流程。deleteMany/updateMany 仅空 filter 时危险（适配器已拦截）；createIndex 在大集合上可能阻塞。createIndexes/dropIndexes 为单数形式别名，renameCollection 影响集合可见性。 */
 export const DANGEROUS_OPS = new Set([
     'dropDatabase', 'dropCollection', 'renameCollection', 'deleteMany', 'updateMany',
@@ -33,7 +61,9 @@ const CELL_TRUNC = 1000;
 function trunc(s, max = CELL_TRUNC) {
     return s.length > max ? `${s.slice(0, max)}…[截断,共${s.length}字符]` : s;
 }
-/** NormalizedCell 规范化：ObjectId/Decimal128/Long/Timestamp → toString()；Binary → hex 截断；Date → ISO；嵌套对象/数组 → JSON 截断 1000 */
+/** NormalizedCell 规范化：ObjectId/Decimal128/Long/Timestamp → toString()；Binary → hex 截断；Date → ISO；嵌套对象/数组 → JSON 截断 1000。
+ * BSON 类型判别依赖 vendor bundle 的类（external bson，与外部 require('bson') 同实例）；
+ * vendor 缺失时降级为普通对象处理，不阻断非 BSON 值的规范化。 */
 export function normalizeMongoCell(v) {
     if (v === null || v === undefined)
         return null;
@@ -45,10 +75,11 @@ export function normalizeMongoCell(v) {
         return v ? 'true' : 'false';
     if (v instanceof Date)
         return v.toISOString();
-    if (v instanceof ObjectId || v instanceof Decimal128 || v instanceof Long || v instanceof Timestamp) {
+    const M = vendorOrNull();
+    if (M && (v instanceof M.ObjectId || v instanceof M.Decimal128 || v instanceof M.Long || v instanceof M.Timestamp)) {
         return trunc(v.toString());
     }
-    if (v instanceof Binary)
+    if (M && v instanceof M.Binary)
         return trunc(Buffer.from(v.buffer ?? []).toString('hex') || String(v));
     if (typeof v === 'object') {
         try {
@@ -120,7 +151,7 @@ export async function createMongoAdapter(conn, opts) {
     }
     else {
         const uri = conn.url ?? buildUri(conn.fields, conn.ssl);
-        client = new MongoClient(uri, {
+        client = new (vendor().MongoClient)(uri, {
             maxPoolSize: 10,
             readPreference: 'primary',
             w: 'majority',
@@ -138,7 +169,8 @@ export async function createMongoAdapter(conn, opts) {
         : defaultDbName(conn.fields);
     const db = client.db(dbName);
     function wrap(e) {
-        if (e instanceof MongoServerError) {
+        const M = vendorOrNull();
+        if (M && e instanceof M.MongoServerError) {
             return new Error(`MongoDB 服务端错误：${e.message}${e.codeName ? `（${e.codeName}）` : ''}`);
         }
         return new Error(`MongoDB 错误：${e instanceof Error ? e.message : String(e)}`);
@@ -471,16 +503,19 @@ function objectToResult(obj) {
 function inferBsonType(v) {
     if (v === null)
         return 'null';
-    if (v instanceof ObjectId)
-        return 'ObjectId';
-    if (v instanceof Decimal128)
-        return 'Decimal128';
-    if (v instanceof Long)
-        return 'Long';
-    if (v instanceof Timestamp)
-        return 'Timestamp';
-    if (v instanceof Binary)
-        return 'Binary';
+    const M = vendorOrNull();
+    if (M) {
+        if (v instanceof M.ObjectId)
+            return 'ObjectId';
+        if (v instanceof M.Decimal128)
+            return 'Decimal128';
+        if (v instanceof M.Long)
+            return 'Long';
+        if (v instanceof M.Timestamp)
+            return 'Timestamp';
+        if (v instanceof M.Binary)
+            return 'Binary';
+    }
     if (v instanceof Date)
         return 'date';
     if (Array.isArray(v))

package/dist/index.js

@@ -4,15 +4,17 @@
  *  - 注册 DatabaseManager 模型工具（单工具多 action），projectPath 取自
  *    session header.cwd（不信任模型自报），业务操作经 GrantStore 授权。
  *  - HTTP API 挂载在 DSH webServer（prefix /dsh-db-tool/api）：前端同源
- *    相对路径 fetch('/dsh-db-tool/api/...') 即可达；trust 校验移植
- *    http-trust 逻辑（Host loopback / trustedHosts + Origin 同源校验）。
+ *    相对路径 fetch('/dsh-db-tool/api/...') 即可达；0.2.0-rc.1 起插件前缀路由
+ *    不经宿主 Connection 栅栏，故在 handler 顶层先应用 ctx.connection.requestRejection
+ *    （Host/Origin + 浏览器 token 鉴权，401/403）；宿主无 connection 服务时退回
+ *    http-trust 本地校验（Host loopback / trustedHosts + Origin 同源校验）。
  *  - ctx.effect 收尾：注销 HTTP 路由、关适配器、停 challenge 清理。
  */
 import { DbToolStore, normalizeProjectKey } from './store/index.js';
 import { DbToolService, handleToolAction } from './manager.js';
 import { handleDbToolRequest } from './http/index.js';
-/** cordis 注入清单（服务名以 dsh-ssh-tunnel 为准） */
-export const inject = ['webServer', 'sessions', 'tools', 'webRuntime'];
+/** cordis 注入清单（服务名以 dsh-ssh-tunnel 为准；connection 用于宿主鉴权栅栏） */
+export const inject = ['webServer', 'sessions', 'tools', 'webRuntime', 'connection'];
 const TOOL_DESCRIPTION = `数据库管理工具（dsh-db-tool）：在已配置的数据库连接上执行查询/写操作/脚本。
 
 权限模型（务必遵守）：
@@ -50,6 +52,21 @@ export function apply(ctx) {
         kind: 'prefix',
         path: '/dsh-db-tool/api',
         handler: async (req, res) => {
+            // 宿主 Connection 栅栏优先：0.2.0-rc.1 起插件前缀路由不经宿主鉴权，
+            // 必须显式应用 requestRejection（Host/Origin + 浏览器 token）；
+            // 401/403 时由本处兜底写出 JSON 响应（宿主只返回状态码）。
+            const rejection = ctx.connection?.requestRejection?.(req);
+            if (rejection !== undefined) {
+                const httpRes = res;
+                httpRes.statusCode = rejection;
+                httpRes.setHeader('Content-Type', 'application/json; charset=utf-8');
+                httpRes.end(JSON.stringify({
+                    ok: false,
+                    error: rejection === 401 ? 'unauthorized: browser authentication required' : 'forbidden: untrusted request',
+                    code: rejection === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN',
+                }));
+                return;
+            }
             await handleDbToolRequest(req, res, service, {
                 trustedHosts: trustedHosts(),
                 // 项目上下文权威解析：会话 header.cwd 优先，回退前端 cwd（对齐 ssh-tunnel getProjectContext）

package/docs/dsh-db-tool /351/224/231/350/257/257/350/256/260/345/275/225.txt"

@@ -0,0 +1,66 @@
+DSH 插件 dsh-db-tool 加载错误记录
+=====================================
+记录时间：2026-09-28
+当前状态：已从 desktop profile 卸载；卸载后该错误归零，其余 12 个第三方插件全部正常。
+
+一、错误原文
+-------------------------------------
+dsh: error: [/197] createRequire.resolve.paths is not a function or its return value is not iterable
+
+对应条目：/197   id=db-tool   name=dsh-db-tool   status=error
+
+出现场景：DSH 0.1.7-rc.2 桌面版，desktop profile 的插件组合检查
+（等价 `dsh --profile desktop --dump-config-schema` 的官方加载路径）。
+同一检查中，其余 12 个第三方插件均无错误。
+
+二、根因（DSH 0.1.7-rc.2 自带代码的 bug）
+-------------------------------------
+1) DSH 自带 @deepseek-ai/dsh-app-boot 的 lib/index.js 里有 6 处
+   `createRequire(parent).resolve.paths(name)` 调用，其中 5 处未做空值防护。
+2) Node 对「内置模块同名包」调用该 API 会返回 null
+   （本机实测：resolve.paths('punycode') 返回 null；普通包返回数组）。
+   对 null 做 for..of 即抛 TypeError —— 这就是上面的错误消息。
+3) dsh-db-tool 的依赖链包含 npm 包 punycode：
+   dsh-db-tool → mongodb → mongodb-connection-string-url → whatwg-url → tr46 → punycode
+   因此该插件的加载路径必然触发这个 bug。
+
+三、本机复现证据
+-------------------------------------
+运行环境：Electron Node（DeepSeek Harness.exe 加 --expose-internals），可直接访问 asar 内模块。
+
+复现结果（最小用例）：
+  createRequire('.../node_modules/dsh-db-tool/dist/index.js').resolve.paths('punycode')  =>  null
+  createRequire('.../node_modules/tr46/index.js').resolve.paths('punycode')             =>  null
+  createRequire('.../node_modules/dsh-db-tool/dist/index.js').resolve.paths('ssh2')      =>  array[11]
+
+DSH 官方检查的诊断输出：
+  卸载前：F:\DSH\_recon\dump-schema-err.txt      （含 /197 db-tool 错误）
+  卸载后：F:\DSH\_recon\dump-schema-err-2.txt    （该错误消失，只剩 DSH 内置 agent-preset 的 4 条既有诊断）
+
+四、插件作者已知该问题（包内自带 hotfix）
+-------------------------------------
+dsh-db-tool 包内提供：
+  scripts/hotfix-core.mjs
+  patches/dsh-app-boot-route-scoped-hotfix.patch
+目标：@deepseek-ai/dsh-app-boot 0.1.7-rc.2 中未防护的那行 for..of。
+修法：resolve.paths 返回 null 时回退到标准 node_modules 搜索链。
+
+限制（本机为何没能直接用）：
+  该脚本按「文件系统安装的 DSH」定位目标（找 DSH_HOME、PATH 上的 dsh、全局 npm 目录），
+  而桌面版把 dsh-app-boot 打包在 F:\DSH\resources\app.asar 内，脚本找不到文件，无法应用。
+
+五、可选修复路径（供向 DSH/插件作者反馈）
+-------------------------------------
+1) 等 DSH 上游修复（推荐）：该 bug 属于 0.1.7-rc.2 自带代码，任意「依赖树含 core-module 同名包」的插件都会触发。
+2) 重打包 app.asar 应用该 hotfix：需先关闭 DSH 应用，修改应用安装文件，版本更新时会被覆盖，有风险。
+3) 插件侧规避：依赖树中避免引入 core-module 同名包（例如替换 punycode 的实现）。
+
+六、本次卸载记录
+-------------------------------------
+卸载方式：DSH plugin-manager operations（pnpm remove + 从 dsh.profile.bundles 移除，等价插件页卸载）。
+结果核对：依赖 13 → 12；bundles 17 → 16；传递依赖 mongodb / punycode 等已一并清理。
+其余 12 个插件的运行时依赖健康检查全部通过（ssh2 纯 JS 可用、better-sqlite3/oracledb 可用、rtk 0.50.0 可用）。
+
+相关产物：
+  报告目录：F:\DSH\_recon\（install-results.json、各 recon 报告、dump 诊断、验证脚本）
+  安装前备份：F:\DSH\_backup\profile-20260928-162128\

package/docs/install.md

@@ -73,6 +73,6 @@ rm -rf ../gaussdb-pg && cp -r packages/pg ../gaussdb-pg
 ## 常见问题
 
 - **侧边栏没有「数据库」tab**：确认 dsh-better-sidebar >= 0.12 已随 DSH 加载；本地开发模式确认 `--patch ./cordis.patch.yml` 生效。
-- **插件导入失败（punycode / resolve.paths）**：宿主 `dsh-app-boot@0.1.7-rc.2` 已知缺陷，在插件目录运行 `npm run patch:dsh`（macOS/Linux 用 `patch:dsh:sh`）一键修复，详见 README「Troubleshooting」。
+- **插件导入失败（punycode / resolve.paths）**：宿主 `dsh-app-boot@0.1.7-rc.2` 已知缺陷，触发条件是插件依赖树含 core-module 同名包（mongodb 链的 `tr46 → punycode` 即元凶）。**0.1.9 起 mongodb 驱动已 bundle 进发布包（`vendor/mongodb-driver.cjs`），本插件依赖树不含 punycode，正常安装不再触发此 bug**——包括无法打补丁的桌面版 app.asar 形态。若错误仍指向其他插件，或需修复宿主自身，在插件目录运行 `npm run patch:dsh`（macOS/Linux 用 `patch:dsh:sh`）一键修复，详见 README「Troubleshooting」。从源码安装（`npm install` 后直接用）时构建链会自动产出 bundle；缺失时可单独跑 `npm run build:mongodb`。
 - **API 全部报错**：host 端 webServer 须注册前缀 `/dsh-db-tool/api`（loopback only）；前端与 host 前缀不一致是最常见的接错方式。
 - **连接测试通过但查询报 UNAUTHORIZED_PROJECT**：当前项目路径未被授权，在「授权」面板为该项目路径授 ro 或 rw。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-db-tool",
-  "version": "0.1.9",
+  "version": "1.3.0",
   "description": "DSH community plugin: chat-operated multi-database admin tool with sidebar management, project-scoped grants, ro/rw modes and dangerous-operation confirmation",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,7 @@
   "homepage": "https://github.com/mengqi1436/dsh-db-tool#readme",
   "engines": {
     "node": ">=20",
-    "dsh": ">=0.1.0-rc.6"
+    "dsh": ">=0.1.0-rc.6 <0.2.0-0 || 0.1.7-rc.2 || >=0.2.0-rc.1 <0.3.0-0"
   },
   "main": "dist/index.js",
   "exports": {
@@ -26,7 +26,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs'); fs.mkdirSync('dist/script',{recursive:true}); fs.copyFileSync('lib/script/worker.cjs','dist/script/worker.cjs'); console.log('build OK')\"",
+    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('fs'); fs.mkdirSync('dist/script',{recursive:true}); fs.copyFileSync('lib/script/worker.cjs','dist/script/worker.cjs'); console.log('build OK')\" && node scripts/build-mongodb.mjs",
+    "build:mongodb": "node scripts/build-mongodb.mjs",
+    "prepack": "npm run build",
     "build:gaussdb": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-gaussdb.ps1",
     "build:gaussdb:sh": "bash scripts/build-gaussdb.sh",
     "patch:dsh": "powershell -NoProfile -ExecutionPolicy Bypass -File scripts/apply-dsh-hotfix.ps1",
@@ -45,18 +47,22 @@
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3",
+    "bson": "^7.2.0",
     "dmdb": "^1.0.52452",
-    "mongodb": "^7.6.0",
     "mysql2": "^3.24.4",
     "oracledb": "^7.0.1",
     "pg": "^8.23.0",
     "redis": "^6.2.1"
   },
   "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
     "@stryker-mutator/core": "^10.0.0",
     "@stryker-mutator/vitest-runner": "^10.0.0",
     "@types/better-sqlite3": "latest",
     "@types/node": "latest",
+    "dsh-better-sidebar": "^0.24.1",
+    "esbuild": "^0.28.0",
+    "mongodb": "^7.6.0",
     "stryker-cli": "^1.1.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11"
@@ -76,6 +82,7 @@
     "docs",
     "patches",
     "scripts",
+    "vendor/mongodb-driver.cjs",
     "README.md"
   ]
 }

package/patches/dsh-app-boot-route-scoped-hotfix-0.2.0-rc.1.patch

@@ -0,0 +1,40 @@
+# DSH dsh-app-boot resolve.paths hotfix (upstream bug: createRequire(parent).resolve.paths(name)
+# returns null for core-module names like "punycode", breaking hoisted profile installs).
+# Covers BOTH unguarded for..of sites in 0.2.0-rc.1: routeScoped() (@@ -1423,14) and
+# nativePackageDir() (@@ -1245,10). Anchor lines are byte-identical to 0.1.7-rc.2 (overall +1 shift).
+# Target-Version: 0.2.0-rc.1
+# Apply manually:  git apply -p1 -d <dsh-app-boot package root> <this file>
+# Or one command:  npm run patch:dsh    (scripts/apply-dsh-hotfix.ps1)
+# Generated from @deepseek-ai/dsh-app-boot@0.2.0-rc.1 npm tarball vs patched local copy.
+diff --git a/lib/index.js b/lib/index.js
+index e60aac4..fcd1a38 100644
+--- a/lib/index.js
++++ b/lib/index.js
+@@ -1245,7 +1245,10 @@ function profileChild(path, treePrefix) {
+ 	return treePrefix + (end < 0 ? rest : rest.slice(0, end));
+ }
+ function nativePackageDir(parent, name) {
+-	for (const searchPath of createRequire(parent).resolve.paths(name)) {
++	/* local hotfix: nativePackageDir: resolve.paths returns null for core-module names
++	   (fs, node:fs, ...); an empty list means no local candidate, matching the
++	   guard in profile.ts:596. */
++	for (const searchPath of createRequire(parent).resolve.paths(name) ?? []) {
+ 		const candidate = join(searchPath, name);
+ 		if (existsSync(join(candidate, "package.json"))) return candidate;
+ 	}
+@@ -1420,7 +1423,14 @@ var ResolutionRouter = class {
+ 		const target = resolution.entries.get(name);
+ 		const candidates = [];
+ 		const localSearchPaths = [];
+-		for (const searchPath of createRequire(parent).resolve.paths(name)) {
++		/* local hotfix: resolve.paths returns null for core-module names (e.g. "punycode"),
++		   which made the for..of throw TypeError and broke every hoisted profile install
++		   whose dependency tree requires such an npm package. Fall back to the standard
++		   node_modules search chain so the local candidate can still be found. */
++		const _hotReq = createRequire(parent);
++		const _hotPaths = _hotReq.resolve.paths(name)
++			?? _hotReq("node:module")._nodeModulePaths(_hotReq("node:path").dirname(parent));
++		for (const searchPath of _hotPaths) {
+ 			if (!searchPath.startsWith(layer.localPrefix)) break;
+ 			localSearchPaths.push(searchPath);
+ 			const candidate = localPackageCandidate(searchPath, name, flavor);

package/scripts/build-mongodb.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * 构建 vendor/mongodb-driver.cjs：把 mongodb 驱动 bundle 成单文件（esbuild JS API）。
+ *
+ * 背景：DSH 宿主 @deepseek-ai/dsh-app-boot（<= 0.1.7-rc.2）在插件安装/加载时对依赖树
+ * 逐包调 `require.resolve.paths(name)` 且未防护 null 返回值（for..of null → TypeError）。
+ * mongodb → mongodb-connection-string-url → whatwg-url → tr46 → punycode 链会让生产依赖树
+ * 出现核心模块同名包 punycode，在未修复宿主上直接炸掉整个插件。bundle 后 punycode/
+ * whatwg-url/tr46/@mongodb-js/saslprep 全部内联进产物，不再出现在依赖树。
+ *
+ * --external:bson 是刻意设计：bson 保留在 dependencies，bundle 内 mongodb re-export 的
+ * ObjectId/Binary 等来自运行时 require('bson')，与测试/插件其他代码 require 的 bson 是
+ * 同一模块实例（instanceof 兼容，避免双份 BSON 类）。其余 externals 为 mongodb 全部
+ * optional peer 依赖（驱动对其本就 try/catch 降级，缺失不影响功能）。
+ *
+ * 每次执行全量重建（esbuild 亚秒级），不做幂等跳过，避免"源升级产物旧"。
+ */
+import { build } from 'esbuild';
+import { mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const outfile = path.join(root, 'vendor', 'mongodb-driver.cjs');
+
+/** bson 必须 external（实例一致性，见文件头注释）；其余为 mongodb optional peers */
+const externals = [
+  'bson',
+  'bson-ext',
+  'kerberos',
+  'snappy',
+  'socks',
+  'gcp-metadata',
+  '@aws-sdk/credential-providers',
+  '@mongodb-js/zstd',
+  'mongodb-client-encryption',
+];
+
+const entry = path.join(root, 'node_modules', 'mongodb', 'lib', 'index.js');
+if (!statSync(entry, { throwIfNoEntry: false })) {
+  console.error('[build-mongodb] 未找到 node_modules/mongodb/lib/index.js —— 请先 npm install（mongodb 在 devDependencies，提供 bundle 源）');
+  process.exit(1);
+}
+
+mkdirSync(path.dirname(outfile), { recursive: true });
+await build({
+  entryPoints: [entry],
+  outfile,
+  bundle: true,
+  platform: 'node',
+  format: 'cjs',
+  target: 'node20',
+  external: externals,
+  legalComments: 'none',
+  sourcemap: false,
+  minify: false,
+  logLevel: 'warning',
+});
+
+const size = statSync(outfile).size;
+console.log(`[build-mongodb] wrote vendor/mongodb-driver.cjs (${(size / 1024 / 1024).toFixed(2)} MB)`);
+console.log('[build-mongodb] done');

package/scripts/hotfix-core.d.mts

@@ -2,6 +2,8 @@
  * 类型声明：scripts/hotfix-core.mjs（无 allowJs，为 tests/scripts/hotfix.spec.ts 提供 import 类型）。
  */
 export declare const TARGET_VERSION: string;
+export declare const TARGET_VERSIONS: string[];
+export declare const PATCH_BY_VERSION: Record<string, string>;
 export declare const HOTFIX_MARKER: string;
 export declare const BOOT_INDEX_REL: string;
 export declare const BACKUP_SUFFIX: string;

package/scripts/hotfix-core.mjs

@@ -2,12 +2,15 @@
 /**
  * DSH dsh-app-boot resolve.paths hotfix —— 核心逻辑（纯 Node、零依赖、可被测试 import）。
  *
- * 修复的 bug：@deepseek-ai/dsh-app-boot@0.1.7-rc.2 对
+ * 修复的 bug：@deepseek-ai/dsh-app-boot 对
  * `createRequire(parent).resolve.paths(name)` 的 for..of 无保护，而 Node 对
  * core-module 同名包（punycode 等）返回 null，for..of null 直接抛 TypeError，
- * 导致 hoisted profile 下 npm 安装插件导入失败。rc.2 中共两处同型缺陷：
- * 1. routeScoped()（L1419 区域）—— 症状直接暴露；
- * 2. nativePackageDir()（L1246 区域）—— 第二处，症状相同，一并修复。
+ * 导致 hoisted profile 下 npm 安装插件导入失败。rc.2 起共两处同型缺陷：
+ * 1. routeScoped()（rc.2 L1419 区域 / 0.2.0-rc.1 L1423 区域）—— 症状直接暴露；
+ * 2. nativePackageDir()（rc.2 L1244 区域 / 0.2.0-rc.1 L1248 区域）—— 症状相同，一并修复。
+ *
+ * 版本支持：锚点行在 TARGET_VERSIONS 列出的版本中逐字节一致（仅整体行号偏移），
+ * 内建替换路径与版本无关；git-apply 路径按安装版本选择 patches/ 下行号匹配的补丁。
  *
  * 用法：node scripts/hotfix-core.mjs [--dsh-root <dir>] [--patch-file <file>]
  *           [--force] [--revert] [--dry-run]
@@ -20,6 +23,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 /** 补丁文件里的目标版本声明行（patches/*.patch 注释头）。 */
 export const TARGET_VERSION = '0.1.7-rc.2';
+/** 锚点行逐字节一致的受支持版本列表（仅整体行号偏移；0.2.0-rc.1 = rc.2 行号 +1）。 */
+export const TARGET_VERSIONS = ['0.1.7-rc.2', '0.2.0-rc.1'];
+/** 各受支持版本对应的默认补丁文件名（patches/ 下；git-apply 路径按版本选择）。 */
+export const PATCH_BY_VERSION = {
+	'0.1.7-rc.2': 'dsh-app-boot-route-scoped-hotfix.patch',
+	'0.2.0-rc.1': 'dsh-app-boot-route-scoped-hotfix-0.2.0-rc.1.patch',
+};
 /** 判断目标文件是否已打补丁的标识串（hotfix 注释首行片段）。 */
 export const HOTFIX_MARKER = 'local hotfix: resolve.paths returns null';
 /** dsh-app-boot 内 lib/index.js 相对包根的路径。 */
@@ -287,15 +297,18 @@ function isGitApplyable(indexFile, patchFile) {
 /** 命令行主入口。@returns {number} 退出码 */
 export function run(argv = process.argv.slice(2)) {
 	let dshRoot;
-	let patchFile = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'patches', 'dsh-app-boot-route-scoped-hotfix.patch');
+	let patchFile = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'patches', PATCH_BY_VERSION[TARGET_VERSION]);
+	let patchFileExplicit = false;
 	let force = false;
 	let revert = false;
 	let dryRun = false;
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
 		if (arg === '--dsh-root') dshRoot = argv[++i];
-		else if (arg === '--patch-file') patchFile = argv[++i];
-		else if (arg === '--force') force = true;
+		else if (arg === '--patch-file') {
+			patchFile = argv[++i];
+			patchFileExplicit = true;
+		} else if (arg === '--force') force = true;
 		else if (arg === '--revert') revert = true;
 		else if (arg === '--dry-run') dryRun = true;
 		else if (arg === '--help' || arg === '-h') {
@@ -324,11 +337,25 @@ export function run(argv = process.argv.slice(2)) {
 	} catch {
 		/* 读不到版本号时跳过比对 */
 	}
+	// 按安装版本选择行号匹配的补丁（未显式指定 --patch-file 时）；
+	// 锚点内容各版本一致，选错补丁只会让 git-apply 路径失配回退内建替换，但优先选对。
+	if (!patchFileExplicit && actualVersion && PATCH_BY_VERSION[actualVersion]) {
+		patchFile = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'patches', PATCH_BY_VERSION[actualVersion]);
+	}
 	const patchText = fs.existsSync(patchFile) ? fs.readFileSync(patchFile, 'utf8') : '';
-	const declared = parsePatchTargetVersion(patchText) ?? TARGET_VERSION;
-	if (actualVersion && actualVersion !== declared && !force) {
-		console.warn(`[dsh-hotfix] version mismatch: installed ${actualVersion} != patch target ${declared}. Use --force to apply anyway.`);
-		return 2;
+	const declared = parsePatchTargetVersion(patchText);
+	if (actualVersion && !force) {
+		if (declared) {
+			if (declared !== actualVersion) {
+				console.warn(`[dsh-hotfix] version mismatch: installed ${actualVersion} != patch target ${declared}. Use --force to apply anyway.`);
+				return 2;
+			}
+		} else if (!TARGET_VERSIONS.includes(actualVersion)) {
+			console.warn(
+				`[dsh-hotfix] version mismatch: installed ${actualVersion} is not supported (supported: ${TARGET_VERSIONS.join(', ')}) and patch declares no Target-Version. Use --force to apply anyway.`,
+			);
+			return 2;
+		}
 	}
 
 	let content;