dsh-dbhub-live 3.1.2 → 3.1.3

package/AGENTS.md

@@ -34,6 +34,7 @@ cordis.patch.yml   bundle patch：`name: dsh-dbhub-live` 挂载本包
 - **工具声明数量恒定（上下文预算红线）**：**绝不为每个工作区 × 环境注册独有工具**（否则 2N 个工具声明每轮进模型上下文）。常驻查询只有 `dbhub_execute_sql(source, …)` / `dbhub_search_objects(source, …)` 两个声明，调用时 `resolveSource` 按 source 值（`标题_hash[_环境]`，来自 `dbhub_list_sources`）解析到真实连接并调用 `dbhub_<base>_<sourceId>`。曾实现过的 per-source 注册（syncToolsNow/兜底/升级）已移除，勿回恢复。核心工具全集固定：configure / list_sources / execute_sql / search_objects / query / query_objects。
 - **schema 弹性依赖**：优先用真实 `@deepseek-ai/schemastery` schema（`await import`）；解析失败时降级为 `lib/index.mjs` 内建的最小 callable schema（`schema(v)` 合默认值 + `toJSON()`），保证**链路安装（`dsh plugin add <本地目录>`，Node ESM 按源码真实路径解析裸导入）下插件照样启动、卡片照常工作**。tarball/npm 安装（真实目录在 profile node_modules 下）走真实 schemastery 路径。不要把这个 import 改回静态顶层 import——会重新引入链路安装时启动失败。
 - **懒加载**：`apply()` 只注册核心工具 + 后台异步初始化（`startLazyInit`）；任何工具调用先 `ensureRunning`（共享 `server.starting`，并发调用自动排队等待）；启动失败进入 `phase:'error'` 并记录 `lastError`，下次调用自动重试。**无工作区数据源时恒不拉起 dbhub 进程**（空 `[[sources]]` toml 对 dbhub 是致命的；空指纹若被当成“已同步”会在二次调用时绕过 toml 直接 spawn——`ensureRunning` 的 `sources.length === 0` 早退必须在指纹判断之外）。
+- **多源故障隔离（toml 每源 `lazy = true`）**：dbhub 对 eager 源是**启动串行全连、一源拒连整进程 Fatal exit**（3.1.2 事故：一个测试环境库连不上 → 所有环境工具全挂）。`generateToml` 因此给每个源写 `lazy = true`（dbhub ≥1.2 原生特性，老版本会静默忽略退回 eager）：启动只登记不连库，`execute_sql_<id>` 等工具名照常注册；某源连不上只在**该 source 的调用**返回 `SOURCE_UNREACHABLE` 类 isError 文本（`runOnServer` 已给 isError 也加环境标签），进程与其他源不受影响。副作用：卡片 🟢 只代表服务在线，不代表每个库可达（`dbhub_list_sources` 与工具描述已注明）。
 - **启用/禁用**：`state.setEnabled` 持久化到 `credentials.json`（权威值）；禁用时立即 `terminateServer()` 释放进程，所有工具 execute 首行返回「插件已禁用」；重新启用触发懒加载初始化。
 - **密码脱敏**：`maskDsn` 是唯一出口——工具描述、结果前缀、扫描候选一律走它。
 

package/README.en.md

@@ -14,7 +14,7 @@
 
 ## ✨ Features
 
-- **Persistent multi-source service** — a single background dbhub service connects to multiple sources; connections are reused and queries are faster.
+- **Persistent multi-source service** — a single background dbhub service connects to multiple sources; connections are reused and queries are faster. Each source connects lazily, so one unreachable environment never takes the others down (fault isolation).
 - **Per-workspace tools** — `dbhub_execute_sql_<workspace>` / `dbhub_search_objects_<workspace>`; the tool name is the workspace, multiple workspaces never mix up, and connections are clearly labeled (passwords masked).
 - **Ad-hoc dynamic connections** — `dbhub_query` / `dbhub_query_objects` connect to any database independently on each call and can query several databases in parallel, handy for cross-environment diagnosis.
 - **Lazy-load startup** — plugin startup does not block the GUI and tools are available immediately; environment initialization is deferred to the first call (queries during initialization automatically wait until ready).
@@ -40,6 +40,9 @@ dsh plugin --profile web add dsh-dbhub-live
 
 # Option 2: invoke dsh via npx (no global dsh installation required)
 npx @deepseek-ai/dsh plugin --profile web add dsh-dbhub-live
+
+# Update to a specific version (pin the currently published version so pnpm doesn't skip with "Already up to date")
+dsh plugin --profile web update dsh-dbhub-live@3.1.3
 ```
 
 After installing, **restart `dsh web`** for it to take effect (you can then see the status card at Settings → Plugins → dsh-dbhub-live).
@@ -86,6 +89,8 @@ If a workspace already has `mise env` or `.env` (`DSN` / `DB_*`), the plugin dis
 
 Settings → Plugins → dsh-dbhub-live: the plugin syncs its running state and configuration to the Web settings panel in real time (only visible on the `dsh web` side). The card uses the **single-row collapsible** style (consistent with the other plugin settings cards):
 
+> All card copy (name, status, config fields, buttons, connection rows) follows the dsh UI language (Chinese / English — Settings → General → Language); model-facing errors, feedback and the host logs follow it as well.
+
 **Collapsed (default)**: one row shows the status badge (🟢 running / 🟡 initializing / 🔴 error / ⚪ disabled), environment count, and the **enable/disable switch** — you can check the status and toggle without expanding.
 
 **Expanded** shows three blocks —
@@ -150,6 +155,7 @@ dsh plugin --profile web remove dsh-dbhub-live
 | Symptom | Fix |
 | --- | --- |
 | "Cannot locate dbhub" on first use | Make sure npm is present and online; offline, install `dbhub` manually and add it to PATH. |
+| A query to one environment fails with `SOURCE_UNREACHABLE` / connection refused | Persistent connections are established lazily **per source with fault isolation**: one unreachable environment (test DB down, VPN off) only makes that environment's queries fail — other environments and the plugin keep working. Fix host/port/network and retry. |
 | Status card shows 🔴 error | Check "Most recent error" in the status card and the `dsh web` logs; a crashed process is auto-restarted on the next call. |
 | Tools say "plugin disabled" | Open Settings → Plugins → dsh-dbhub-live and click "Enable". |
 | Status card not visible | Confirm the plugin is installed and restart `dsh web`; the card only shows in the Web settings panel (`dsh web`) — on terminal environments without the panel, tool usage is unaffected. |

package/README.md

@@ -14,7 +14,7 @@
 
 ## ✨ 特性
 
-- **常驻多源服务** — 后台一个 dbhub 服务同时接入多个数据源，连接复用、查询更快。
+- **常驻多源服务** — 后台一个 dbhub 服务同时接入多个数据源，连接复用、查询更快；连接按源懒建立，单个环境数据库不可达不影响其他环境（故障隔离）。
 - **按工作区工具** — `dbhub_execute_sql_<工作区>` / `dbhub_search_objects_<工作区>`，工具名即工作区，多工作区不混淆，连接标注（密码打码）清晰可见。
 - **临时动态连接** — `dbhub_query` / `dbhub_query_objects` 每次独立连任意库，可并行查多个不同库，便于跨环境排查。
 - **懒加载启动** — 插件启动不阻塞 GUI，工具立即可用；环境初始化推迟到首次调用（初始化期间查询自动等待就绪）。
@@ -40,6 +40,9 @@ dsh plugin --profile web add dsh-dbhub-live
 
 # 方式二：通过 npx 调用 dsh（无需本机全局安装 dsh）
 npx @deepseek-ai/dsh plugin --profile web add dsh-dbhub-live
+
+# 更新到指定版本（推荐写明当前发布的版本号，避免 pnpm 判「Already up to date」跳过）
+dsh plugin --profile web update dsh-dbhub-live@3.1.3
 ```
 
 安装后**重启 `dsh web`** 生效（重启后到 设置 → 插件 → dsh-dbhub-live 可看到状态卡片）。
@@ -86,6 +89,8 @@ dbhub_query  dsn=mysql://user:pass@127.0.0.1:3306/mydb  sql="SHOW TABLES;"
 
 设置 → 插件 → dsh-dbhub-live：插件会把运行状态与配置实时同步到 Web 设置面板（仅 `dsh web` 端可见）。卡片为**整行折叠**样式（与其它插件设置卡一致）：
 
+> 卡片全部文案（名称、状态、配置项、按钮、连接行）跟随 dsh 界面语言（中 / 英，设置 → 通用 → 语言）切换；模型的报错/反馈与宿主日志同样跟随。
+
 **折叠态（默认）**：一行显示 运行状态徽章（🟢 运行中 / 🟡 初始化中 / 🔴 异常 / ⚪ 已禁用）、环境数量、**启用/禁用开关**——不展开也能看状态、切开关。
 
 **展开后**分三块——
@@ -150,6 +155,7 @@ dsh plugin --profile web remove dsh-dbhub-live
 | 现象 | 处理 |
 | --- | --- |
 | 首次使用报「无法获取 dbhub」 | 确认本机有 npm 且能联网；离线可手动安装 `dbhub` 并加入 PATH。 |
+| 某个环境的查询报 `SOURCE_UNREACHABLE` / 连接被拒 | 常驻连接为**按需建立、环境间故障隔离**：某个环境的数据库不可达（如测试库停机、VPN 未连）只会让该环境的查询返回连接错误，其他环境与插件整体不受影响。核对该环境的主机/端口/网络后重试即可。 |
 | 状态卡片显示 🔴 异常 | 查看状态卡片中的「最近错误」与 `dsh web` 日志；进程异常退出时插件会在下次调用自动重启。 |
 | 工具显示「插件已禁用」 | 打开 设置 → 插件 → dsh-dbhub-live 卡片，点击「启用」。 |
 | 看不到状态卡片 | 确认插件已安装并重启 `dsh web`；状态卡片只在 Web 设置面板（`dsh web`）显示，在无设置面板的终端环境下不影响工具使用。 |

package/doc/REQUIREMENTS.md

@@ -26,10 +26,11 @@
 
 ### 3. 运行时保障
 - 常驻连接复用，提升多次查询效率；空闲一段时间自动回收。
+- **多环境故障隔离**：连接按环境懒建立——某个环境的数据库不可达（测试库停机、网络不通等）只影响该环境的查询（返回明确的连接错误），其余环境与服务整体照常可用。
 - 首次使用若缺少依赖则自动安装，之后定期自动更新；用户自行安装的版本不受影响。
 - 服务异常退出后，下次调用自动恢复，无需人工干预。
 
-## 二、本次新增功能
+## 二、v3.1 新增功能（当前已发布：3.1.3）
 
 ### 1. 懒加载启动优化
 - 插件启动不阻塞 GUI，工具立即可用。
@@ -38,12 +39,13 @@
 ### 2. 插件状态管理
 - **启用 / 禁用开关**：关闭后所有 dbhub 相关工具立即返回「插件已禁用」友好提示，无需重启；再次开启立即可用。
 - **运行状态**：运行中 / 初始化中 / 异常 三态，实时反映插件可用性。
-- **工具数量**：当前已注册工具总数实时展示。
+- **工具数量**：当前已注册工具总数实时展示（恒定 6 个声明，不随环境增减）。
 - **错误摘要**：最近一次初始化或运行错误简要信息，异常时展示。
 
 ### 3. 浏览器状态卡片（设置在插件的状态面板）
-- **整行折叠样式**（与其余插件设置卡一致）：折叠态一行展示运行状态徽章（🟢 / 🟡 / 🔴 / ⚪）、环境数量与 **启用 / 禁用开关**（不展开即可看状态、切开关）；展开后分「状态 / 配置 / 工作区连接」三块。
-- 状态块为辅助信息：常驻进程状态、工作模式（懒加载）、**工具声明数（固定 6，非重点）**、环境计数（N 个 · 已保存 M）、最近错误（红色展示）。
+- **整行折叠样式**（与其余插件设置卡一致）：折叠态一行展示插件显示名、运行状态徽章（🟢 / 🟡 / 🔴 / ⚪）、环境数量与 **启用 / 禁用开关**（不展开即可看状态、切开关）；展开后分「状态 / 配置 / 工作区连接」三块（新增连接表单并入工作区连接块）。
+- 状态块为辅助信息且**随宽度自适应多列**：常驻进程状态、工作模式（懒加载）、**工具声明数（固定 6，非重点）**、环境计数（N 个 · 已保存 M）、最近错误（红色展示）。
+- 配置块置于**分组框**内（保存按钮归属清晰）：自动更新间隔、空闲回收时长 + 保存。
 - 工作区连接块逐行展示：工作区名、环境名、**source 值**（等宽字体，供 `dbhub_execute_sql` 使用）、打码连接串、来源徽章（已保存 / 自动），支持修改 / 删除 / 新增。
 - 启用/禁用开关即时生效。
 
@@ -62,4 +64,10 @@
 - **变更即时生效**：卡片新增/修改/删除连接后，常驻 dbhub 服务立即重启，下一次查询即可使用新环境的 `source` 值，无需重启实例。
 - **连接源枚举工具**：`dbhub_list_sources` 列出全部已注册连接源（工作区 × 环境、打码连接串、来源与对应 source 值），避免把「测试环境」误当成默认（生产）库。
 - **脱敏连接串不可直连**：`dbhub_list_sources` 中展示的连接串密码为 `****`（仅识别用途）；`dbhub_query` / `dbhub_query_objects` 检测到脱敏密码时会直接拒绝并引导使用常驻工具（内置真实凭据），避免用 `****` 白跑一次失败连接。
-- 自动配置与已保存配置并存展示；自动发现与实际不符时可手动修改覆盖。
+- 自动配置与已保存配置并存展示；自动发现与实际不符时可手动修改覆盖。
+
+### 6. 多语言（跟随 dsh 界面语言）
+- 卡片的**全部界面文案**（插件显示名、状态徽章与网格、配置项与按钮、工作区连接行、空态与占位符）随 dsh 主体界面语言切换（中 / 英）。
+- 模型侧反馈（工具结果、报错与异常提示、脱敏/引导文案）与宿主日志同样跟随 dsh 语言设置；中文为默认与兜底。
+- 工具的**描述文案**保持中文（产品约定：模型可见文案统一中文，便于跨会话一致）。
+- 双语 README（中文 `README.md` 为唯一真源，英文 `README.en.md` 派生）。

package/lib/config.mjs

@@ -292,12 +292,21 @@ export function fingerprintOf(sources) {
   return sources.map((s) => s.id + '|' + s.dsn).join('\n')
 }
 
+// Every source is emitted `lazy = true`: dbhub connects it on first use
+// instead of eagerly at startup. dbhub's eager connect is all-or-nothing —
+// ONE unreachable environment (ECONNREFUSED etc.) kills the whole process
+// fatally, taking every other workspace/env tool down with it. Lazy sources
+// register at startup regardless of reachability (execute_sql_<id> etc. are
+// built from the config source list), and a connect failure only ever
+// surfaces as an isError result on that source's own call. Older dbhub
+// builds strip the unknown key and fall back to the previous eager behavior.
 export function generateToml(sources) {
   const lines = ['# Auto-generated by dsh-dbhub-live — do not edit. Regenerated on demand.']
   for (const s of sources) {
     lines.push('[[sources]]')
     lines.push('id = "' + tomlEscape(s.id) + '"')
     lines.push('dsn = "' + tomlEscape(s.dsn) + '"')
+    lines.push('lazy = true')
   }
   return lines.join('\n') + '\n'
 }

package/lib/i18n.mjs

@@ -29,7 +29,7 @@ const ZH = {
   'result.dsnMissing': '缺少 dsn 参数（如 mysql://user:pass@host:3306/db）',
   'result.masked': '检测到脱敏密码 `****`：dbhub_query / dbhub_query_objects 需要真实凭据，打码连接串不能直连。要查询已注册的环境，请改用对应的常驻工具（先用 dbhub_list_sources 查 source 值）；若确需临时直连，请提供真实密码的完整 DSN。',
   'result.noSource': '找不到数据源 "{src}"：请先调用 dbhub_list_sources 查看可用 source 值（如 <工作区> 或 <工作区>_<环境>）。',
-  'result.sourcesIntro': '⚠️ 下面每个连接串都是脱敏显示（密码 ****），仅供识别，不要把它们拷进 dbhub_query 直连；查询某环境请用 dbhub_execute_sql / dbhub_search_objects，source 参数取该行的「source 值」。\n已注册连接源 {n} 个：',
+  'result.sourcesIntro': '⚠️ 下面每个连接串都是脱敏显示（密码 ****），仅供识别，不要把它们拷进 dbhub_query 直连；查询某环境请用 dbhub_execute_sql / dbhub_search_objects，source 参数取该行的「source 值」。\n已注册连接源 {n} 个（连接为按需建立，列出不代表数据库当前可达）：',
   'result.srcRow': '- {title}（{badge}）｜环境 {env}｜连接 {dsn}（打码，仅显示）｜来源 {src}｜source 值 {srcId}',
   'result.sourcesEmpty': '暂无已注册的连接源（可用 dbhub_configure 或 设置 → 插件 → dsh-dbhub-live → 工作区连接 添加）。',
   'result.badgeSaved': '已保存',
@@ -70,7 +70,7 @@ const EN = {
   'result.dsnMissing': 'missing dsn argument (e.g. mysql://user:pass@host:3306/db)',
   'result.masked': 'masked password `****` detected: dbhub_query / dbhub_query_objects need real credentials. To query a registered environment use the persistent tools (run dbhub_list_sources for the source value); for a one-off connection pass a full DSN with the real password.',
   'result.noSource': 'source "{src}" not found: run dbhub_list_sources first to see the available source values (e.g. <workspace> or <workspace>_<env>).',
-  'result.sourcesIntro': '⚠️ Every DSN below is masked (password ****) and only for identification — do not copy one into dbhub_query. To query an environment use dbhub_execute_sql / dbhub_search_objects with the row\u2019s source value.\n{n} registered source(s):',
+  'result.sourcesIntro': '⚠️ Every DSN below is masked (password ****) and only for identification — do not copy one into dbhub_query. To query an environment use dbhub_execute_sql / dbhub_search_objects with the row\u2019s source value.\n{n} registered source(s) (connections are lazy — being listed does not mean the database is currently reachable):',
   'result.srcRow': '- {title} ({badge}) | env {env} | dsn {dsn} (masked) | source {src} | source value {srcId}',
   'result.sourcesEmpty': 'no registered sources yet (add one with dbhub_configure or Settings → Plugins → dsh-dbhub-live → Workspace connections).',
   'result.badgeSaved': 'saved',

package/lib/mcp.mjs

@@ -3,7 +3,10 @@
 // ONE persistent `dbhub --transport stdio --config <generated dbhub.toml>`
 // process, managed here: idle recycle, respawn on demand, lazy init. The toml
 // is auto-generated from every registered workspace's connection config and
-// hot-reloaded by dbhub itself — users never maintain it.
+// hot-reloaded by dbhub itself — users never maintain it. Every generated
+// source is `lazy = true` (see config.mjs/generateToml): the server starts
+// even when one environment's database is unreachable, and the failure only
+// surfaces as an error on that source's own calls.
 //
 // This module also owns the per-workspace tool registrations and their
 // disposers (the source of truth for the registered-tool count).
@@ -439,7 +442,9 @@ export async function runOnServer(ctx, subprocess, rawName, args, exec, label) {
     }
     resetIdle(ctx)
     const prefix = label ? label + '\n' : ''
-    if (res && res.isError) return { ok: false, text: textOf(res) }
+    // Label the failure too: a lazy source connects on first use, so a dead
+    // database surfaces HERE — the model must see which environment failed.
+    if (res && res.isError) return { ok: false, text: prefix + textOf(res) }
     if (res && res.structuredContent !== undefined) {
       return { ok: true, text: prefix + JSON.stringify(res.structuredContent, null, 2) }
     }

package/lib/tools.mjs

@@ -224,7 +224,8 @@ function buildListSourcesTool(ctx, subprocess) {
       '列出当前已注册的全部数据库连接源（每个 = 工作区 × 环境）及其对应的常驻查询工具名。' +
       '注意：列表中的连接串是脱敏显示（密码为 ****），仅供识别环境，绝不能拷进 dbhub_query / dbhub_query_objects 直连（会失败）；' +
       '查询某个环境请直接调用该行给出的 dbhub_execute_sql_<工作区>[_<环境>] 工具（已内置真实凭据）。' +
-      '当用户提到某个环境（如 test/测试）但你不确定它是否已注册时，先调用本工具确认环境名，再调用对应环境的工具，避免误用默认（生产）库。无参数。',
+      '当用户提到某个环境（如 test/测试）但你不确定它是否已注册时，先调用本工具确认环境名，再调用对应环境的工具，避免误用默认（生产）库。' +
+      '常驻连接为懒建立：本工具能列出的 source 不代表数据库当前可达，若某环境库不可达，只有对该 source 的调用会返回连接错误（不影响其他环境）。无参数。',
     parameters: {
       type: 'object',
       properties: {},
@@ -322,7 +323,8 @@ export function registerCoreTools(ctx, subprocess) {
       name: 'dbhub_execute_sql',
       description:
         '在指定数据源的常驻连接上执行 SQL。source 必填：数据源标识，先调用 dbhub_list_sources 查看全部可用值与对应环境（如 <工作区> 为默认环境，<工作区>_<环境> 为命名环境，例如通过 _test 指向测试库）。' +
-        'sql：要执行的 SQL（多语句用 ; 分隔）。结果自动标注所连环境。',
+        'sql：要执行的 SQL（多语句用 ; 分隔）。结果自动标注所连环境。' +
+        '连接为按需建立（该 source 首次调用时才真正连库）：某个环境的数据库不可达只会让该 source 的调用返回连接错误，不影响其他环境查询与常驻服务存活。',
       parameters: {
         type: 'object',
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-dbhub-live",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "DSH 数据库 MCP 桥接插件：常驻多源 dbhub 服务 + source 参数化常驻工具 + 临时动态连接 + 懒加载、浏览器状态卡片与可配置参数。",
   "type": "module",
   "main": "lib/index.mjs",

package/test/util.test.mjs

@@ -1,96 +1,112 @@
-// Unit tests for the pure utilities in lib/config.mjs and lib/collect.mjs.
-// Test isolation: these modules derive the storage directory from DSH_HOME at
-// import time, so point DSH_HOME at a temp dir BEFORE importing them.
-
-import test from 'node:test'
-import assert from 'node:assert/strict'
-import { mkdtempSync, rmSync, existsSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-const home = mkdtempSync(join(tmpdir(), 'dsh-dbhub-test-'))
-process.env.DSH_HOME = home
-
-const cfg = await import('../lib/config.mjs')
-
-test.after(() => {
-  rmSync(home, { recursive: true, force: true })
-})
-
-test('slugify normalizes titles', () => {
-  assert.equal(cfg.slugify('MyApp'), 'myapp')
-  assert.equal(cfg.slugify('hbtx-server-master_1hn7yaw'), 'hbtx-server-master_1hn7yaw')
-  assert.equal(cfg.slugify('A B!/c'), 'a-b-c')
-  assert.equal(cfg.slugify(''), 'ws')
-  assert.equal(cfg.slugify(undefined), 'ws')
-})
-
-test('tomlEscape escapes backslash, quotes and newlines', () => {
-  assert.equal(cfg.tomlEscape('a"b'), 'a\\"b')
-  assert.equal(cfg.tomlEscape('a\\b'), 'a\\\\b')
-  assert.equal(cfg.tomlEscape('a\nb'), 'a\\nb')
-})
-
-test('shortHash is stable and hex-ish', () => {
-  assert.equal(cfg.shortHash('abc'), cfg.shortHash('abc'))
-  assert.notEqual(cfg.shortHash('abc'), cfg.shortHash('another'))
-  assert.match(cfg.shortHash('abc'), /^[a-z0-9]+$/)
-  assert.ok(cfg.shortHash('abc').length > 0)
-})
-
-test('maskDsn hides passwords, keeps host/db', () => {
-  assert.equal(cfg.maskDsn('mysql://root:secret@10.0.0.1:3306/mydb'),
-    'mysql://root:****@10.0.0.1:3306/mydb')
-  assert.equal(cfg.maskDsn('postgres://u:p@h/db'), 'postgres://u:****@h/db')
-  // no password -> unchanged
-  assert.equal(cfg.maskDsn('sqlite:///C:/data/x.db'), 'sqlite:///C:/data/x.db')
-  // unparseable DSN falls back to regex masking
-  assert.equal(cfg.maskDsn('mysql://root:secret@h:3306/d'), 'mysql://root:****@h:3306/d')
-})
-
-test('dsnFromEnv joins DB_* variables and handles sqlite', () => {
-  const env = { DB_HOST: '10.0.0.1', DB_PORT: '3307', DB_USER: 'root', DB_PASSWORD: 'pw', DB_NAME: 'tx_zdsf_main_pro' }
-  assert.equal(cfg.dsnFromEnv(env), 'mysql://root:pw@10.0.0.1:3307/tx_zdsf_main_pro')
-  assert.equal(cfg.dsnFromEnv({ DB_HOST: 'a', DB_USER: 'b', DB_NAME: 'c', DB_TYPE: 'sqlite' }), 'sqlite:///a')
-  assert.equal(cfg.dsnFromEnv({ DB_HOST: 'a' }), undefined)
-})
-
-test('dsnFromMap prefers explicit DSN', () => {
-  assert.equal(cfg.dsnFromMap({ DSN: 'postgres://u@h/db' }), 'postgres://u@h/db')
-  assert.equal(cfg.dsnFromMap({ DB_HOST: 'h', DB_USER: 'u', DB_NAME: 'd' }), 'mysql://u:@h/d')
-})
-
-test('parseEnvFile skips comments/quotes', () => {
-  const map = cfg.parseEnvFile('# c\nDSN="mysql://u@h/d"\nEMPTY=\nFOO=bar')
-  assert.equal(map.DSN, 'mysql://u@h/d')
-  assert.equal(map.FOO, 'bar')
-  assert.equal(map.EMPTY, '')
-})
-
-test('generateToml and fingerprintOf', () => {
-  const sources = [{ id: 'ws_abc', dsn: 'mysql://u@h/d' }]
-  const toml = cfg.generateToml(sources)
-  assert.match(toml, /^# Auto-generated/)
-  assert.match(toml, /id = "ws_abc"/)
-  assert.match(toml, /dsn = "mysql:\/\/u@h\/d"/)
-  assert.notEqual(cfg.fingerprintOf(sources), cfg.fingerprintOf([{ id: 'ws_abc', dsn: 'other' }]))
-})
-
-test('collect: walkForCandidates skips noise dirs and finds config files', async () => {
-  const { walkForCandidates, extractDsnCandidates } = await import('../lib/collect.mjs')
-  const { writeFileSync, mkdirSync } = await import('node:fs')
-  const root = join(home, 'proj')
-  mkdirSync(join(root, 'node_modules'), { recursive: true })
-  mkdirSync(join(root, 'src'), { recursive: true })
-  writeFileSync(join(root, '.env'), 'DSN=mysql://root:pw@10.0.0.1:3306/appdb\n')
-  writeFileSync(join(root, 'node_modules', 'x.env'), 'DSN=mysql://nope@x/y\n')
-  writeFileSync(join(root, 'src', 'application.yml'), 'url: jdbc:mysql://1.2.3.4:3306/biz?user=u&password=p\n')
-
-  const found = walkForCandidates(root, { count: 0 })
-  assert.ok(found.includes(join(root, '.env')))
-  assert.ok(found.includes(join(root, 'src', 'application.yml')))
-  assert.ok(!found.some((f) => f.includes('node_modules')))
-
-  const candidates = extractDsnCandidates(join(root, '.env'), 'DSN=mysql://root:pw@10.0.0.1:3306/appdb\n')
-  assert.ok(candidates.some((c) => c.dsn === 'mysql://root:pw@10.0.0.1:3306/appdb'))
+// Unit tests for the pure utilities in lib/config.mjs and lib/collect.mjs.
+// Test isolation: these modules derive the storage directory from DSH_HOME at
+// import time, so point DSH_HOME at a temp dir BEFORE importing them.
+
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, rmSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const home = mkdtempSync(join(tmpdir(), 'dsh-dbhub-test-'))
+process.env.DSH_HOME = home
+
+const cfg = await import('../lib/config.mjs')
+
+test.after(() => {
+  rmSync(home, { recursive: true, force: true })
+})
+
+test('slugify normalizes titles', () => {
+  assert.equal(cfg.slugify('MyApp'), 'myapp')
+  assert.equal(cfg.slugify('hbtx-server-master_1hn7yaw'), 'hbtx-server-master_1hn7yaw')
+  assert.equal(cfg.slugify('A B!/c'), 'a-b-c')
+  assert.equal(cfg.slugify(''), 'ws')
+  assert.equal(cfg.slugify(undefined), 'ws')
+})
+
+test('tomlEscape escapes backslash, quotes and newlines', () => {
+  assert.equal(cfg.tomlEscape('a"b'), 'a\\"b')
+  assert.equal(cfg.tomlEscape('a\\b'), 'a\\\\b')
+  assert.equal(cfg.tomlEscape('a\nb'), 'a\\nb')
+})
+
+test('shortHash is stable and hex-ish', () => {
+  assert.equal(cfg.shortHash('abc'), cfg.shortHash('abc'))
+  assert.notEqual(cfg.shortHash('abc'), cfg.shortHash('another'))
+  assert.match(cfg.shortHash('abc'), /^[a-z0-9]+$/)
+  assert.ok(cfg.shortHash('abc').length > 0)
+})
+
+test('maskDsn hides passwords, keeps host/db', () => {
+  assert.equal(cfg.maskDsn('mysql://root:secret@10.0.0.1:3306/mydb'),
+    'mysql://root:****@10.0.0.1:3306/mydb')
+  assert.equal(cfg.maskDsn('postgres://u:p@h/db'), 'postgres://u:****@h/db')
+  // no password -> unchanged
+  assert.equal(cfg.maskDsn('sqlite:///C:/data/x.db'), 'sqlite:///C:/data/x.db')
+  // unparseable DSN falls back to regex masking
+  assert.equal(cfg.maskDsn('mysql://root:secret@h:3306/d'), 'mysql://root:****@h:3306/d')
+})
+
+test('dsnFromEnv joins DB_* variables and handles sqlite', () => {
+  const env = { DB_HOST: '10.0.0.1', DB_PORT: '3307', DB_USER: 'root', DB_PASSWORD: 'pw', DB_NAME: 'tx_zdsf_main_pro' }
+  assert.equal(cfg.dsnFromEnv(env), 'mysql://root:pw@10.0.0.1:3307/tx_zdsf_main_pro')
+  assert.equal(cfg.dsnFromEnv({ DB_HOST: 'a', DB_USER: 'b', DB_NAME: 'c', DB_TYPE: 'sqlite' }), 'sqlite:///a')
+  assert.equal(cfg.dsnFromEnv({ DB_HOST: 'a' }), undefined)
+})
+
+test('dsnFromMap prefers explicit DSN', () => {
+  assert.equal(cfg.dsnFromMap({ DSN: 'postgres://u@h/db' }), 'postgres://u@h/db')
+  assert.equal(cfg.dsnFromMap({ DB_HOST: 'h', DB_USER: 'u', DB_NAME: 'd' }), 'mysql://u:@h/d')
+})
+
+test('parseEnvFile skips comments/quotes', () => {
+  const map = cfg.parseEnvFile('# c\nDSN="mysql://u@h/d"\nEMPTY=\nFOO=bar')
+  assert.equal(map.DSN, 'mysql://u@h/d')
+  assert.equal(map.FOO, 'bar')
+  assert.equal(map.EMPTY, '')
+})
+
+test('generateToml and fingerprintOf', () => {
+  const sources = [{ id: 'ws_abc', dsn: 'mysql://u@h/d' }]
+  const toml = cfg.generateToml(sources)
+  assert.match(toml, /^# Auto-generated/)
+  assert.match(toml, /id = "ws_abc"/)
+  assert.match(toml, /dsn = "mysql:\/\/u@h\/d"/)
+  assert.match(toml, /lazy = true/)
+  assert.notEqual(cfg.fingerprintOf(sources), cfg.fingerprintOf([{ id: 'ws_abc', dsn: 'other' }]))
+})
+
+test('generateToml emits lazy = true for EVERY source (one dead env must not kill the server)', () => {
+  const sources = [
+    { id: 'hbtx_1hn7yaw', dsn: 'mysql://root:pw@10.253.0.3:3307/tx_zdsf_main_pro' },
+    { id: 'hbtx_1hn7yaw_test', dsn: 'mysql://root:pw@10.253.0.6:1688/db_zdsf' },
+    { id: 'other_2', dsn: 'sqlite:///C:/data/x.db' },
+  ]
+  const blocks = cfg.generateToml(sources).split('[[sources]]').slice(1)
+  assert.equal(blocks.length, 3)
+  for (const b of blocks) {
+    assert.match(b, /id = ".+"/)
+    assert.match(b, /dsn = ".+"/)
+    assert.match(b, /lazy = true/)
+  }
+})
+
+test('collect: walkForCandidates skips noise dirs and finds config files', async () => {
+  const { walkForCandidates, extractDsnCandidates } = await import('../lib/collect.mjs')
+  const { writeFileSync, mkdirSync } = await import('node:fs')
+  const root = join(home, 'proj')
+  mkdirSync(join(root, 'node_modules'), { recursive: true })
+  mkdirSync(join(root, 'src'), { recursive: true })
+  writeFileSync(join(root, '.env'), 'DSN=mysql://root:pw@10.0.0.1:3306/appdb\n')
+  writeFileSync(join(root, 'node_modules', 'x.env'), 'DSN=mysql://nope@x/y\n')
+  writeFileSync(join(root, 'src', 'application.yml'), 'url: jdbc:mysql://1.2.3.4:3306/biz?user=u&password=p\n')
+
+  const found = walkForCandidates(root, { count: 0 })
+  assert.ok(found.includes(join(root, '.env')))
+  assert.ok(found.includes(join(root, 'src', 'application.yml')))
+  assert.ok(!found.some((f) => f.includes('node_modules')))
+
+  const candidates = extractDsnCandidates(join(root, '.env'), 'DSN=mysql://root:pw@10.0.0.1:3306/appdb\n')
+  assert.ok(candidates.some((c) => c.dsn === 'mysql://root:pw@10.0.0.1:3306/appdb'))
 })