dsh-db-tool 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# dsh-db-tool
+
+DSH 社区插件：在聊天中安全操作数据库，配套侧边栏管理台与 `db-admin` skill。架构与交互模式对齐 [dsh-ssh-tunnel](https://github.com/thirsty5034/dsh-ssh-tunnel)。
+
+## 功能
+
+- **8 种数据库**：MySQL、PostgreSQL、GaussDB（openGauss 官方驱动）、SQLite、Redis、MongoDB、Oracle、达梦（DM）
+- **DatabaseManager 单工具多 action**：`list_connections / query / execute / schema / preview / run_script`
+- **分级权限**：连接级只读（ro）/读写（rw）+ 项目级授权（`grants.json`：projectPathKey → 连接 → 模式）；未授权项目一律拒绝
+- **危险操作确认**：DDL / FLUSHALL / dropDatabase 等先返回 `NEEDS_CONFIRMATION`，对话内（模型经 ask）或 SQL 控制台（弹窗）确认后携一次性 `challengeId`（绑定语句 SHA256、5 分钟过期）重试
+- **审计**：全部执行落 `audit.jsonl`（语句、危险级、是否确认、结果）
+- **侧边栏 4 面板**（dsh-better-sidebar，zh/en）：连接管理、项目授权、数据浏览、SQL 控制台
+- **db-admin skill**：随插件分发，覆盖 8 库方言速查、安全规范、确认流程
+
+## 数据布局
+
+`$DSH_HOME/db-tool/`（0700）：
+
+| 文件 | 内容 |
+|---|---|
+| `connections.json` | 连接定义（`urlSafe` 中密码脱敏为 `***`） |
+| `secrets.json` | 0600，密码/URL 凭据，永不返回给模型 |
+| `grants.json` | 项目授权（归一化路径 → connId → ro/rw） |
+| `audit.jsonl` | 追加式审计日志 |
+
+## 安装
+
+```bash
+# 发布模式
+dsh plugin --profile web add "dsh-db-tool@github:<user>/dsh-db-tool"
+
+# 本地开发
+pnpm dsh web --patch ./cordis.patch.yml
+```
+
+GaussDB 官方驱动未发布 npm，需先构建 vendor：`npm run build:gaussdb`（PowerShell）或 `bash scripts/build-gaussdb.sh`；oracledb 安装脚本需 `npm approve-scripts oracledb`。详见 [docs/install.md](docs/install.md)。
+
+## 安全模型
+
+- HTTP API 仅同源（`ctx.webServer` prefix `/dsh-db-tool/api`）+ 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}` 句柄
+- 已知边界：对话内确认为提示级强制 + 审计兜底；DSH 无硬中断通道前，恶意对话仍可能诱导用户确认，请配合最小权限数据库账号使用
+
+## 测试
+
+```bash
+npm test        # 离线 mock 全量（含 e2e-mock 全链路与对抗用例）
+npx tsc --noEmit
+npx stryker run # 变异测试（范围 lib/guard + lib/manager + lib/store，报告 reports/mutation/）
+```
+
+真机冒烟（设了才跑）：`DBT_TEST_MYSQL_URL / DBT_TEST_PG_URL / DBT_TEST_REDIS_URL / DBT_TEST_DM_CONNECT / DBT_TEST_MONGO_URL / DBT_TEST_ORACLE_CONNECT`。GaussDB 与 Oracle/Mongo 官方要求均按官方文档实现，未真机验证处以代码内标注为准。
+
+## 目录
+
+```
+lib/        host 插件（store / adapters×8 / guard / manager / http / index）
+client/     侧边栏单文件产物（client.js，即源码）
+skills/     db-admin skill
+scripts/    GaussDB vendor 构建（sh / ps1）
+docs/       安装、HTTP 契约（api-contract.md）、skill 说明
+tests/      vitest（离线 mock + DBT_TEST_* 门控真机）
+vendor/     gaussdb-pg 构建产物（gitignore，不入库）
+```

package/client/README.md

@@ -0,0 +1,53 @@
+# dsh-db-tool client（侧边栏前端）
+
+## 形态：无构建、单文件产物
+
+本目录**不需要任何构建步骤**。`client.js` 即最终发布产物，与 dsh-ssh-tunnel 的发布形态一致：一个 `window.__ModuleLoader__.load({ id, factory })` 包裹的单文件 IIFE 模块，`factory(require)` 内 `require("react")` 取 React，运行于 DSH 侧边栏底座 dsh-better-sidebar（>=0.12）。
+
+这样做的好处：无打包器、无依赖漂移、产物可直接被插件安装流程原样打包。
+
+## 文件
+
+- `client.js` — 全部前端逻辑（约 1000 行），内含：
+  - 4 个面板：管理（连接 CRUD + 测试 + 审计查看）、授权（项目路径 → 连接 ro/rw/撤销）、浏览（库 → 表 → 结构 → 预览分页）、SQL 控制台（连接/库选择、query/execute/script、危险确认对话框 → challengeId 重发）
+  - zh/en 双语词典（zh 默认），经 `ctx.locale.register(NS, ...)` 注册，`useSyncExternalStore` 订阅语言切换
+  - 危险确认：`runGuarded()` 先发请求，收到 `code:"NEEDS_CONFIRMATION"` 且有 `challengeId` 时弹 `DangerDialog`，用户确认后携 challengeId 重发（challenge 一次性、绑语句、5 分钟有效）
+  - REST API 调用走同源前缀 **`/dsh-db-tool/api`**（须与 host 端 `webServer.register` 的 prefix 一致）
+
+## 验证（本地跑通的方式）
+
+无构建器，验证即两项检查：
+
+```powershell
+node --check client/client.js        # 语法检查
+```
+
+再加一个最小冒烟：stub `window.__ModuleLoader__` / `require("react")`，eval 加载文件，调 `factory` 得到 `exports`，断言 `exports.inject` 含 `"betterSidebar"`、`exports.apply(ctx)` 能注册 `id:"dsh-db-tool"` 的 tab、根组件可创建（见本文件历史提交中的 smoke 脚本写法；依赖仅 node 内置 fs）。
+
+## 打包接入（发布形态，需根 package.json 配合）
+
+npm 包需暴露 client 供 DSH 注入（此字段属根 package.json，超出 client scope，需 lib/lead 侧补上）：
+
+```jsonc
+{
+  "exports": { "./client": "./client/client.js" },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": { "inject": ["@deepseek-ai/dsh-client-locale"], "platform": "web" }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "dsh-better-sidebar": ">=0.12.0"
+  }
+}
+```
+
+## 本地开发
+
+仓库根目录执行（Windows）：
+
+```powershell
+pnpm dsh web --patch ./cordis.patch.yml
+```
+
+侧边栏出现「数据库」tab（order 45）即加载成功。projectPath 取自 `scope.cwd || scope.workspacePath`，也可在面板顶部手动输入后点「加载」。