dsh-db-tool 0.1.9 → 1.2.0

package/README.md

@@ -36,7 +36,7 @@ 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)。
 
 ## 安全模型
 
@@ -63,6 +63,8 @@ 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>（占位，待上游仓库开放后替换）。
 
+**本插件的免补丁路径（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` 仍保留，用于修复**其他**含同类依赖的插件或宿主自身报错。
+
 ## 测试
 
 ```bash
@@ -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/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.2.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",
@@ -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,8 +47,8 @@
   },
   "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",
@@ -57,6 +59,8 @@
     "@stryker-mutator/vitest-runner": "^10.0.0",
     "@types/better-sqlite3": "latest",
     "@types/node": "latest",
+    "esbuild": "^0.28.0",
+    "mongodb": "^7.6.0",
     "stryker-cli": "^1.1.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11"
@@ -76,6 +80,7 @@
     "docs",
     "patches",
     "scripts",
+    "vendor/mongodb-driver.cjs",
     "README.md"
   ]
 }

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');