@carllee1983/dbcli 1.54.0 → 1.55.0

package/.cursor/skills/dbcli/reference.md

@@ -1660,6 +1660,21 @@ shape (`schemaVersion: 1`):
 Recovery codes (fixed in v1.15.0):
 - `CONFIG_MISSING` — no `.dbcli` config; run `dbcli init`.
 - `CONN_REFUSED` / `CONN_AUTH_FAILED` / `CONN_TIMEOUT` / `CONN_HOST_NOT_FOUND` / `CONN_UNKNOWN` — connection failure variants.
+  `CONN_TIMEOUT` also covers a statement the server canceled for exceeding the statement
+  timeout (PostgreSQL `57014`, MySQL `3024`, MariaDB `1969`); `details.connectionCode` is
+  `STATEMENT_TIMEOUT` there instead of `ETIMEDOUT`, the plan targets the query (`lint` →
+  `explain` → re-run with `--statement-timeout <ms>`) rather than `doctor`, and no
+  `branches` / `branchFork` / `verify` is emitted. PostgreSQL `57014` only counts as a
+  statement timeout when the server says so — a `pg_cancel_backend()` cancel keeps the
+  verbatim `Database error (57014): …` form instead of claiming a ceiling.
+  The same `details.connectionCode` field distinguishes the other causes that share a
+  connection code: `CONNECTION_LOST` (server closed the connection mid-session — PostgreSQL
+  class 08 and `57P01`/`57P02`, MySQL `1053`), `TOO_MANY_CONNECTIONS` (PostgreSQL `53300`,
+  MySQL `1040` — its plan counts current connections instead of running `doctor`, because
+  rewriting host/port cannot create a slot), `SERVER_NOT_READY` (`57P03`, still starting up),
+  `CONNECTION_REJECTED` (`08004` — the server answered and refused), `EHOSTUNREACH` (resolved
+  but unroutable) and `TLS_ERROR` (handshake failure; reported as `CONN_UNKNOWN` rather than
+  `CONN_AUTH_FAILED`, whose plan re-runs `init` for credentials that are not the problem).
 - `PERMISSION_DENIED` — active permission level forbids the operation.
 - `BLACKLIST_TABLE` / `BLACKLIST_COLUMN_WRITE` — blacklist violations.
 - `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` / `SNIPPET_PARAM_MISSING` — saved-query failures.

package/.github/skills/dbcli/reference.md

@@ -1660,6 +1660,21 @@ shape (`schemaVersion: 1`):
 Recovery codes (fixed in v1.15.0):
 - `CONFIG_MISSING` — no `.dbcli` config; run `dbcli init`.
 - `CONN_REFUSED` / `CONN_AUTH_FAILED` / `CONN_TIMEOUT` / `CONN_HOST_NOT_FOUND` / `CONN_UNKNOWN` — connection failure variants.
+  `CONN_TIMEOUT` also covers a statement the server canceled for exceeding the statement
+  timeout (PostgreSQL `57014`, MySQL `3024`, MariaDB `1969`); `details.connectionCode` is
+  `STATEMENT_TIMEOUT` there instead of `ETIMEDOUT`, the plan targets the query (`lint` →
+  `explain` → re-run with `--statement-timeout <ms>`) rather than `doctor`, and no
+  `branches` / `branchFork` / `verify` is emitted. PostgreSQL `57014` only counts as a
+  statement timeout when the server says so — a `pg_cancel_backend()` cancel keeps the
+  verbatim `Database error (57014): …` form instead of claiming a ceiling.
+  The same `details.connectionCode` field distinguishes the other causes that share a
+  connection code: `CONNECTION_LOST` (server closed the connection mid-session — PostgreSQL
+  class 08 and `57P01`/`57P02`, MySQL `1053`), `TOO_MANY_CONNECTIONS` (PostgreSQL `53300`,
+  MySQL `1040` — its plan counts current connections instead of running `doctor`, because
+  rewriting host/port cannot create a slot), `SERVER_NOT_READY` (`57P03`, still starting up),
+  `CONNECTION_REJECTED` (`08004` — the server answered and refused), `EHOSTUNREACH` (resolved
+  but unroutable) and `TLS_ERROR` (handshake failure; reported as `CONN_UNKNOWN` rather than
+  `CONN_AUTH_FAILED`, whose plan re-runs `init` for credentials that are not the problem).
 - `PERMISSION_DENIED` — active permission level forbids the operation.
 - `BLACKLIST_TABLE` / `BLACKLIST_COLUMN_WRITE` — blacklist violations.
 - `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` / `SNIPPET_PARAM_MISSING` — saved-query failures.

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.55.0] - 2026-08-13 - Packaging: the declared runtime matches the artifact
+
+### Removed
+
+- **`engines.node` — the runtime declaration now matches the artifact.** `package.json` claimed `node: ">=18.0.0"` since the first release, but measured on Node v22.17.1 against the `v1.54.1` `dist/`, only one published entry point actually loaded. `node dist/cli.mjs` threw `ERR_MODULE_NOT_FOUND` as soon as the launcher reached its dynamic import: `src/cli.ts` keeps the runtime path as a non-literal `'./cli-runtime'` so the `--version` launcher does not inline the heavy runtime, and Bun's resolver appends `.mjs` where Node's ESM resolver requires the extension. `import('dist/core.mjs')` — the `./core` subpath export — threw `Bun is not defined`, the bundle holding 30 Bun global references against `dist/cli-runtime.mjs`'s 143. The `bin` shebang is `#!/usr/bin/env bun` regardless, and the `--version` fast path branches on `import.meta.main`, which is `undefined` before Node 24. `engines` now declares `bun >= 1.3.3` alone. `dist/agent-core.mjs` was and remains Node-importable, and is documented as the one entry point that is. npm and npx stay supported as distribution channels, with the docs stating plainly that the installed executable still runs under Bun. `tests/integration/runtime-contract.test.ts` holds both ends: re-declaring `engines.node` fails unless `dist/cli.mjs` and `dist/core.mjs` really import in a bare Node process, and `dist/agent-core.mjs` must keep importing there whatever else changes. The alternative — `--target node` plus ~169 Bun API replacements in `src/` and a Node runtime CI suite — is rejected and its cost recorded in `docs/adr/0008-dbcli-is-a-bun-program-and-engines-says-so.md` (#65).
+
+### Added
+
+- **An install on a machine without Bun now says so.** npm validates no `engines` field it does not recognize, so dropping the false `engines.node` would otherwise have left `npm install -g` with no signal at all — success, then a `dbcli` on `PATH` that dies on its shebang. `scripts/postinstall-check-bun.mjs` prints the reason and the Bun install command at that moment, and never fails the install. It runs as `bun … || node … || exit 0` because the primary install path is Bun-only machines, which have no `node` to invoke a postinstall with. `plugins/dbcli-agent/scripts/install-dbcli.sh` stopped falling back to npm when Bun is absent: it used to leave a non-functional `dbcli` behind, and now refuses before changing anything (#65).
+
+## [1.54.1] - 2026-08-13 - Error classification: a failure now says which layer broke
+
+### Fixed
+
+- **A dropped connection, an exhausted connection pool, an unreachable host, and a TLS failure each say so.** `TRANSPORT_CODES` listed seven keys, so `ECONNRESET`, `EPIPE`, `EHOSTUNREACH`, `ENETUNREACH`, TLS certificate codes, PostgreSQL SQLSTATE class `08` and `53300`, and MySQL `1040` all carried a code, skipped the message-pattern fallback (which only runs when there is none), and landed on `Database error (ECONNRESET): …` with hints about `dbcli schema`. They now map to four new categories — `CONNECTION_LOST`, `TOO_MANY_CONNECTIONS`, `EHOSTUNREACH`, `TLS_ERROR` — each with the remedy that actually applies: retry a transient drop, inspect `pg_stat_activity` / `Threads_connected` against `max_connections`, check routing and VPN rather than DNS, or point `caPath` / `rejectUnauthorized` at the right certificate. PostgreSQL class `57` (`57P01` / `57P02` / `57P03`) and MySQL `1053` / `2006` / `2013` join them: restarting the server under a running query was reported as `Database error (57P01)` with hints about confirming the statement's objects. The codeless wordings drivers use for the same event — `Connection terminated unexpectedly`, `server closed the connection`, `server has gone away` — are recognized too. `57P03` (still starting up) and `08004` (the server answered and refused) get their own categories rather than borrowing a message that says the opposite, and TLS is matched by code prefix because enumerating OpenSSL's verify codes would keep missing some. The envelope states each cause in its own words instead of inheriting the shared recovery code's description — `CONN_HOST_NOT_FOUND` says the name could not be resolved, which is the one thing `EHOSTUNREACH` rules out — and TLS failures no longer route to the credentials plan, whose second step re-runs `init` for a certificate it never asks about. The adapter-code-to-envelope-code and the connection-versus-statement tables are both exhaustive `Record`s over the code union now, so a future code cannot silently inherit a generic category, and the REPL's reconnect decision reads the same table instead of its own list of codes and message substrings (#62).
+
+- **`insert` / `update` / `delete` / `q` no longer report every failure as "failed to connect".** All four branched on `instanceof ConnectionError` and applied one message key, but that class carries every adapter-level error and only four of its nine codes are transport failures — so a missing table, a syntax error, or a statement timeout all arrived as `Failed to connect to database: …` while the connection was fine. The wording is now chosen by code, and rendering goes through the same `formatCliError` the central presenter uses, so these commands print the stable `Code:` line and the error's hints — both previously dropped on this path — exactly as `query` does (#61).
+
+- **A statement the server canceled is no longer reported as a connection failure.** PostgreSQL `57014`, MySQL `3024`, and MariaDB `1969` fell through to `UNKNOWN` / `CONN_UNKNOWN`, so the CLI answered a query that ran out of statement time with connection-troubleshooting hints and a recovery plan that opened with `dbcli doctor` — the one thing that was not broken. They now map to a `STATEMENT_TIMEOUT` adapter code whose hints point at the query (`dbcli lint`, `dbcli explain`, re-run with an explicit `--statement-timeout <ms>`). The `--recovery` envelope keeps `schemaVersion` 1 and reports `CONN_TIMEOUT` with `details.connectionCode: "STATEMENT_TIMEOUT"`; that field selects the query-oriented plan, replaces the network-flavored message with one that states the ceiling that was in force, and suppresses both the `doctor-*` branches — whose `branchFork.after: 1` assumed step 1 was `doctor` — and the `verify` step, since nothing verifies this error except re-running the statement, which only the caller has. PostgreSQL `57014` is `query_canceled`, not only `statement_timeout`, so a `pg_cancel_backend()` or recovery-conflict cancel keeps the verbatim `Database error (57014): …` form rather than asserting a ceiling nobody set.
+
 ## [1.54.0] - 2026-08-13 - Query engine hardening: timeout semantics, load-on-demand, deterministic builds
 
 ### Added

package/README.dev.md

@@ -73,20 +73,22 @@ After publishing:
 
 1. **Global install:**
    ```bash
-   npm install -g @carllee1983/dbcli
+   bun install -g @carllee1983/dbcli
    which dbcli
    dbcli --version
    ```
+   `npm install -g` also works, but the installed executable still runs under Bun via its
+   `#!/usr/bin/env bun` shebang — verify on a machine that has Bun on `PATH`.
 
-2. **Zero-install (npx / bunx):**
+2. **Zero-install (bunx / npx):**
    ```bash
    cd /tmp && mkdir -p test-dbcli && cd test-dbcli
-   npx @carllee1983/dbcli --help
-   npx @carllee1983/dbcli --version
-   # or: bunx @carllee1983/dbcli --help
+   bunx @carllee1983/dbcli --help
+   bunx @carllee1983/dbcli --version
+   # or: npx @carllee1983/dbcli --help
    ```
 
-3. **Windows (if available):** `npm install -g @carllee1983/dbcli`, then `dbcli --help`. npm creates the `.cmd` stub for the `bin` entry; no hand-written `.cmd` in the repo.
+3. **Windows (if available):** `npm install -g @carllee1983/dbcli`, then `dbcli --help`. npm creates the `.cmd` stub for the `bin` entry; no hand-written `.cmd` in the repo. Bun must be on `PATH` there too.
 
 ### Rollback (if needed)
 
@@ -104,8 +106,9 @@ Then ship a patch version with the fix. Prefer **deprecate** over **unpublish**
 
 - **`files` (in `package.json`):** Publishes `dist/`, `assets/`, `README.md`, `CHANGELOG.md`, `LICENSE`. The `assets/` tree is required for `dbcli skill` to copy bundled `SKILL.md` / `reference.md` from the installed package.
 - **`prepublishOnly`:** `bun run build` so `dist/cli.mjs` matches current source.
-- **`engines`:** Declares `node >= 18.0.0` and `bun >= 1.3.3` so npm can warn on outdated runtimes.
+- **`engines`:** Declares `bun >= 1.3.3` only. `node` was removed because the published bundles cannot run on Node: `dist/cli.mjs` dynamic-imports the extensionless `./cli-runtime` (Bun's resolver appends `.mjs`, Node's does not) and `dist/core.mjs` calls Bun globals. `tests/integration/runtime-contract.test.ts` fails if `engines.node` comes back without the bundles being fixed to match, and if `dist/agent-core.mjs` — the one entry point that is Node-importable — regresses. See `docs/adr/0008-dbcli-is-a-bun-program-and-engines-says-so.md`.
 - **Shebang:** `scripts/build.ts` prepends `#!/usr/bin/env bun` to `dist/cli.mjs`; the `bin` field in `package.json` points at that file.
+- **`postinstall`:** `scripts/postinstall-check-bun.mjs` warns (never fails) when Bun is missing after install — npm ignores `engines.bun`, so this is the only signal an npm-only machine gets before `dbcli` refuses to start. The script command is `bun … || node … || exit 0` so it runs whichever runtime is present: Bun-only machines have no `node` to invoke it with, and a hard `node` dependency there would break the primary install path.
 - **Live DB tests:** `tests/integration/live-db.test.ts` uses project `.dbcli` by default or `LIVE_DB_CONFIG_PATH` when you point at another config directory. Set `SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
 
 For contributor workflow and release process, see **[CONTRIBUTING.md](./CONTRIBUTING.md)** and the main **[README.md](./README.md)** Development section.

package/README.md

@@ -38,16 +38,21 @@ All messages, help text, error messages, and command output respond to the langu
 #### Global Installation (Recommended)
 
 ```bash
-npm install -g @carllee1983/dbcli
-# or: bun install -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
+# or: npm install -g @carllee1983/dbcli
 ```
 
+**dbcli runs on Bun.** npm and npx are supported as distribution channels, but the
+installed `dbcli` executable requires Bun 1.3.3+ on your `PATH` — install it first with
+`curl -fsSL https://bun.sh/install | bash`. Only the `./agent-core` subpath export is
+importable from a plain Node process.
+
 #### Zero-Install (No Installation Needed)
 
 ```bash
-npx @carllee1983/dbcli init
-npx @carllee1983/dbcli query "SELECT * FROM users"
-# or with Bun: bunx @carllee1983/dbcli init
+bunx @carllee1983/dbcli init
+bunx @carllee1983/dbcli query "SELECT * FROM users"
+# or with npm: npx @carllee1983/dbcli init
 ```
 
 #### Update
@@ -1324,9 +1329,11 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 ### Platform-Specific Setup
 
+Every flow below assumes Bun 1.3.3+ on your `PATH`: the installed `dbcli` executable runs under Bun regardless of which package manager fetched it.
+
 #### Claude Code (Anthropic)
 
-1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
+1. Install dbcli globally: `bun install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init` (choose permission level)
 3. Install skill: `dbcli skill --install claude`
 4. Restart Claude Code extension
@@ -1338,7 +1345,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 #### Gemini CLI (Google)
 
-1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
+1. Install dbcli globally: `bun install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init`
 3. Install skill: `dbcli skill --install gemini`
 4. Start Gemini: `gemini start`
@@ -1350,7 +1357,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 #### GitHub Copilot CLI
 
-1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
+1. Install dbcli globally: `bun install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init`
 3. Install skill: `dbcli skill --install copilot`
 4. Install Copilot CLI: `npm install -g @github-next/github-copilot-cli`
@@ -1362,7 +1369,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 #### Cursor IDE
 
-1. Install dbcli globally: `npm install -g @carllee1983/dbcli`
+1. Install dbcli globally: `bun install -g @carllee1983/dbcli`
 2. Initialize: `dbcli init`
 3. Install skill: `dbcli skill --install cursor`
 4. Open Cursor editor
@@ -1378,7 +1385,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 1. Add the marketplace: `codex plugin marketplace add CarlLee1983/dbcli`.
 2. Open `/plugins`, select the dbcli Agent marketplace, and install `dbcli-agent`.
-3. For a persistent CLI, install dbcli globally: `bun install -g @carllee1983/dbcli` or `npm install -g @carllee1983/dbcli`.
+3. For a persistent CLI, install dbcli globally: `bun install -g @carllee1983/dbcli` (or `npm install -g`, which still needs Bun on `PATH`).
 4. Without a global install, the plugin skill uses `bunx @carllee1983/dbcli <command>` as its fallback.
 5. Initialize: `dbcli init` or `bunx @carllee1983/dbcli init`.
 
@@ -1394,7 +1401,7 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 ```bash
 # 1. Install and initialize
-npm install -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
 dbcli init  # Choose "query-only" for safety
 
 # 2. Install skill to Claude Code
@@ -1590,16 +1597,16 @@ dbcli query "SELECT * FROM users LIMIT 100 OFFSET 100"
 
 #### "CLI startup takes 30+ seconds (first run)"
 
-npx is downloading and caching package.
+bunx (or npx) is downloading and caching the package.
 
 **Solution:** This is normal on first run. Subsequent runs are instant:
 
 ```bash
-npx @carllee1983/dbcli init  # First run: 30s (downloads)
-npx @carllee1983/dbcli init  # Second run: <1s (cached)
+bunx @carllee1983/dbcli init  # First run: 30s (downloads)
+bunx @carllee1983/dbcli init  # Second run: <1s (cached)
 
 # Or install globally for faster startup
-npm install -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
 dbcli init  # All future runs: <1s
 ```
 
@@ -1609,15 +1616,19 @@ dbcli init  # All future runs: <1s
 
 #### Windows: "Command not found: dbcli"
 
-npm .cmd wrapper not created or PATH not updated.
+The shim was not created, PATH was not updated, or Bun is missing — `dbcli` runs under
+Bun on Windows too.
 
 **Solutions:**
 
 ```bash
+# Confirm Bun is installed and on PATH first
+bun --version
+
 # Restart terminal to refresh PATH
 # OR reinstall globally
-npm uninstall -g @carllee1983/dbcli
-npm install -g @carllee1983/dbcli
+bun uninstall -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
 
 # Verify installation
 where dbcli  # Windows command to find executable
@@ -1647,8 +1658,11 @@ chmod +x dist/cli.mjs
 
 ### Runtime
 
-- **Node.js:** 18.0.0+
-- **Bun:** 1.3.3+
+- **Bun:** 1.3.3+ — required. The published bundles use Bun APIs and Bun module
+  resolution; `dbcli` does not run on Node.
+- **Node.js:** only for the `./agent-core` subpath export, which is Node-importable
+  (18.0.0+). `npm install -g` / `npx` work as distribution channels but still shell out
+  to Bun at run time.
 
 ### Platforms
 

package/README.zh-TW.md

@@ -38,16 +38,20 @@ dbcli init
 #### 全域安裝（建議）
 
 ```bash
-npm install -g @carllee1983/dbcli
-# 或使用 Bun：bun install -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
+# 或使用 npm：npm install -g @carllee1983/dbcli
 ```
 
+**dbcli 執行於 Bun。** npm 與 npx 可作為發布通道，但安裝後的 `dbcli` 執行檔需要 `PATH`
+上有 Bun 1.3.3+，請先以 `curl -fsSL https://bun.sh/install | bash` 安裝。只有
+`./agent-core` 這個 subpath export 能被純 Node 程序 import。
+
 #### 免安裝（無需事先安裝）
 
 ```bash
-npx @carllee1983/dbcli init
-npx @carllee1983/dbcli query "SELECT * FROM users"
-# 或使用 Bun：bunx @carllee1983/dbcli init
+bunx @carllee1983/dbcli init
+bunx @carllee1983/dbcli query "SELECT * FROM users"
+# 或使用 npm：npx @carllee1983/dbcli init
 ```
 
 #### 更新
@@ -1214,9 +1218,11 @@ dbcli skill --install cursor
 
 ### 各平台設定
 
+以下所有流程都假設 `PATH` 上有 Bun 1.3.3+：無論用哪個套件管理器安裝，`dbcli` 執行檔都以 Bun 執行。
+
 #### Claude Code（Anthropic）
 
-1. 全域安裝 dbcli：`npm install -g @carllee1983/dbcli`
+1. 全域安裝 dbcli：`bun install -g @carllee1983/dbcli`
 2. 初始化：`dbcli init`（選擇權限等級）
 3. 安裝 skill：`dbcli skill --install claude`
 4. 重新啟動 Claude Code 擴充
@@ -1228,7 +1234,7 @@ dbcli skill --install cursor
 
 #### Gemini CLI（Google）
 
-1. 全域安裝：`npm install -g @carllee1983/dbcli`
+1. 全域安裝：`bun install -g @carllee1983/dbcli`
 2. 初始化：`dbcli init`
 3. 安裝 skill：`dbcli skill --install gemini`
 4. 啟動 Gemini：`gemini start`
@@ -1240,7 +1246,7 @@ dbcli skill --install cursor
 
 #### GitHub Copilot CLI
 
-1. 全域安裝：`npm install -g @carllee1983/dbcli`
+1. 全域安裝：`bun install -g @carllee1983/dbcli`
 2. 初始化：`dbcli init`
 3. 安裝 skill：`dbcli skill --install copilot`
 4. 安裝 Copilot CLI：`npm install -g @github-next/github-copilot-cli`
@@ -1252,7 +1258,7 @@ dbcli skill --install cursor
 
 #### Cursor IDE
 
-1. 全域安裝：`npm install -g @carllee1983/dbcli`
+1. 全域安裝：`bun install -g @carllee1983/dbcli`
 2. 初始化：`dbcli init`
 3. 安裝 skill：`dbcli skill --install cursor`
 4. 開啟 Cursor
@@ -1268,7 +1274,7 @@ dbcli skill --install cursor
 
 1. 加入 marketplace：`codex plugin marketplace add CarlLee1983/dbcli`。
 2. 開啟 `/plugins`，選擇 dbcli Agent marketplace，並安裝 `dbcli-agent`。
-3. 若要常駐 CLI，請全域安裝 dbcli：`bun install -g @carllee1983/dbcli` 或 `npm install -g @carllee1983/dbcli`。
+3. 若要常駐 CLI，請全域安裝 dbcli：`bun install -g @carllee1983/dbcli`（或 `npm install -g`，但仍需 `PATH` 上有 Bun）。
 4. 若未全域安裝，plugin 內的 skill 會以 `bunx @carllee1983/dbcli <command>` 作為 fallback。
 5. 初始化：`dbcli init` 或 `bunx @carllee1983/dbcli init`。
 
@@ -1284,7 +1290,7 @@ dbcli skill --install cursor
 
 ```bash
 # 1. 安裝並初始化
-npm install -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
 dbcli init  # 選擇「query-only」較安全
 
 # 2. 為 Claude Code 安裝 skill
@@ -1471,16 +1477,16 @@ dbcli query "SELECT * FROM users LIMIT 100 OFFSET 100"
 
 #### 「第一次執行 CLI 超過 30 秒」
 
-npx 正在下載並快取套件。
+bunx（或 npx）正在下載並快取套件。
 
 **處理方式：** 首次較慢屬正常，之後會很快：
 
 ```bash
-npx @carllee1983/dbcli init   # 首次約 30s
-npx @carllee1983/dbcli init   # 之後 <1s
+bunx @carllee1983/dbcli init   # 首次約 30s
+bunx @carllee1983/dbcli init   # 之後 <1s
 
 # 或全域安裝
-npm install -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
 dbcli init
 ```
 
@@ -1490,15 +1496,18 @@ dbcli init
 
 #### Windows：「Command not found: dbcli」
 
-npm 未建立 .cmd 或 PATH 未更新。
+shim 未建立、PATH 未更新，或機器上沒有 Bun —— `dbcli` 在 Windows 上同樣以 Bun 執行。
 
 **處理方式：**
 
 ```bash
+# 先確認 Bun 已安裝且在 PATH 上
+bun --version
+
 # 重開終端機以更新 PATH
 # 或重新全域安裝
-npm uninstall -g @carllee1983/dbcli
-npm install -g @carllee1983/dbcli
+bun uninstall -g @carllee1983/dbcli
+bun install -g @carllee1983/dbcli
 
 where dbcli
 ```
@@ -1527,8 +1536,10 @@ chmod +x dist/cli.mjs
 
 ### 執行環境
 
-- **Node.js：** 18.0.0+
-- **Bun：** 1.3.3+
+- **Bun：** 1.3.3+ —— 必要。發布的 bundle 使用 Bun API 與 Bun 的模組解析，`dbcli`
+  無法在 Node 上執行。
+- **Node.js：** 僅 `./agent-core` 這個 subpath export 可被 Node import（18.0.0+）。
+  `npm install -g` / `npx` 可作為發布通道，但執行時仍會轉交給 Bun。
 
 ### 平台
 

package/assets/reference.md

@@ -1660,6 +1660,21 @@ shape (`schemaVersion: 1`):
 Recovery codes (fixed in v1.15.0):
 - `CONFIG_MISSING` — no `.dbcli` config; run `dbcli init`.
 - `CONN_REFUSED` / `CONN_AUTH_FAILED` / `CONN_TIMEOUT` / `CONN_HOST_NOT_FOUND` / `CONN_UNKNOWN` — connection failure variants.
+  `CONN_TIMEOUT` also covers a statement the server canceled for exceeding the statement
+  timeout (PostgreSQL `57014`, MySQL `3024`, MariaDB `1969`); `details.connectionCode` is
+  `STATEMENT_TIMEOUT` there instead of `ETIMEDOUT`, the plan targets the query (`lint` →
+  `explain` → re-run with `--statement-timeout <ms>`) rather than `doctor`, and no
+  `branches` / `branchFork` / `verify` is emitted. PostgreSQL `57014` only counts as a
+  statement timeout when the server says so — a `pg_cancel_backend()` cancel keeps the
+  verbatim `Database error (57014): …` form instead of claiming a ceiling.
+  The same `details.connectionCode` field distinguishes the other causes that share a
+  connection code: `CONNECTION_LOST` (server closed the connection mid-session — PostgreSQL
+  class 08 and `57P01`/`57P02`, MySQL `1053`), `TOO_MANY_CONNECTIONS` (PostgreSQL `53300`,
+  MySQL `1040` — its plan counts current connections instead of running `doctor`, because
+  rewriting host/port cannot create a slot), `SERVER_NOT_READY` (`57P03`, still starting up),
+  `CONNECTION_REJECTED` (`08004` — the server answered and refused), `EHOSTUNREACH` (resolved
+  but unroutable) and `TLS_ERROR` (handshake failure; reported as `CONN_UNKNOWN` rather than
+  `CONN_AUTH_FAILED`, whose plan re-runs `init` for credentials that are not the problem).
 - `PERMISSION_DENIED` — active permission level forbids the operation.
 - `BLACKLIST_TABLE` / `BLACKLIST_COLUMN_WRITE` — blacklist violations.
 - `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` / `SNIPPET_PARAM_MISSING` — saved-query failures.