@carllee1983/dbcli 1.54.1 → 1.55.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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

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/dist/cli-runtime.mjs

@@ -51,7 +51,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@carllee1983/dbcli",
-    version: "1.54.1",
+    version: "1.55.0",
     description: "Database CLI for AI agents",
     type: "module",
     publishConfig: {
@@ -93,11 +93,11 @@ var init_package = __esm(() => {
       "blacklist"
     ],
     engines: {
-      node: ">=18.0.0",
       bun: ">=1.3.3"
     },
     files: [
       "dist/",
+      "scripts/postinstall-check-bun.mjs",
       "!dist/.build-stamp",
       "assets/",
       "plugins/",
@@ -114,6 +114,7 @@ var init_package = __esm(() => {
       "LICENSE"
     ],
     scripts: {
+      postinstall: "bun scripts/postinstall-check-bun.mjs || node scripts/postinstall-check-bun.mjs || exit 0",
       dev: "bun run src/cli.ts",
       build: "bun run scripts/build.ts",
       "build:determinism": "bun run scripts/check-build-determinism.ts",

package/dist/cli.mjs

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.54.1",
+  version: "1.55.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -45,11 +45,11 @@ var package_default = {
     "blacklist"
   ],
   engines: {
-    node: ">=18.0.0",
     bun: ">=1.3.3"
   },
   files: [
     "dist/",
+    "scripts/postinstall-check-bun.mjs",
     "!dist/.build-stamp",
     "assets/",
     "plugins/",
@@ -66,6 +66,7 @@ var package_default = {
     "LICENSE"
   ],
   scripts: {
+    postinstall: "bun scripts/postinstall-check-bun.mjs || node scripts/postinstall-check-bun.mjs || exit 0",
     dev: "bun run src/cli.ts",
     build: "bun run scripts/build.ts",
     "build:determinism": "bun run scripts/check-build-determinism.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.54.1",
+  "version": "1.55.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {
@@ -42,11 +42,11 @@
     "blacklist"
   ],
   "engines": {
-    "node": ">=18.0.0",
     "bun": ">=1.3.3"
   },
   "files": [
     "dist/",
+    "scripts/postinstall-check-bun.mjs",
     "!dist/.build-stamp",
     "assets/",
     "plugins/",
@@ -63,6 +63,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "postinstall": "bun scripts/postinstall-check-bun.mjs || node scripts/postinstall-check-bun.mjs || exit 0",
     "dev": "bun run src/cli.ts",
     "build": "bun run scripts/build.ts",
     "build:determinism": "bun run scripts/check-build-determinism.ts",

package/plugins/dbcli-agent/INSTALL.md

@@ -197,17 +197,16 @@ For a persistent `dbcli` executable in `PATH`, run:
 plugins/dbcli-agent/scripts/install-dbcli.sh
 ```
 
-The installer prefers Bun:
+The installer requires Bun:
 
 ```bash
 bun install -g @carllee1983/dbcli
 ```
 
-If Bun is unavailable but npm exists, it falls back to:
-
-```bash
-npm install -g @carllee1983/dbcli
-```
+If Bun is not on `PATH` the script refuses and exits non-zero rather than installing
+through npm: the executable starts with `#!/usr/bin/env bun`, so an npm-only machine would
+end up with a `dbcli` that cannot start. Install Bun first with
+`curl -fsSL https://bun.sh/install | bash`.
 
 ## Verify Installation
 

package/plugins/dbcli-agent/scripts/install-dbcli.sh

@@ -6,10 +6,10 @@ if command -v bun >/dev/null 2>&1; then
   exit 0
 fi
 
-if command -v npm >/dev/null 2>&1; then
-  npm install -g @carllee1983/dbcli
-  exit 0
-fi
-
-echo "Install Bun or npm first, then run: bun install -g @carllee1983/dbcli" >&2
+# npm can fetch the package, but the installed executable runs under Bun
+# (`#!/usr/bin/env bun`), so installing it here would leave a `dbcli` on PATH that
+# cannot start. Refuse instead of half-installing.
+echo "Bun is required: dbcli's executable runs under Bun, whichever package manager installs it." >&2
+echo "Install Bun, then re-run this script:" >&2
+echo "  curl -fsSL https://bun.sh/install | bash" >&2
 exit 1

package/scripts/postinstall-check-bun.mjs

@@ -0,0 +1,49 @@
+/**
+ * Post-install runtime check.
+ *
+ * `engines` declares bun only, but npm ignores engine fields it does not know, so an
+ * `npm install -g @carllee1983/dbcli` on a machine without Bun succeeds and leaves a
+ * `dbcli` on PATH whose `#!/usr/bin/env bun` shebang cannot start. This warns at the
+ * moment that happens, which is closer to the user than any README paragraph.
+ *
+ * Plain Node ESM on purpose: npm runs this with node, not bun. Never fails the install —
+ * a warning is the whole point, and a non-zero exit here would break the package.
+ */
+
+import { spawnSync } from 'node:child_process'
+
+const BUN_INSTALL_HINT =
+  process.platform === 'win32'
+    ? 'powershell -c "irm bun.sh/install.ps1 | iex"'
+    : 'curl -fsSL https://bun.sh/install | bash'
+
+function bunIsAvailable() {
+  if (process.versions.bun) return true
+  try {
+    const result = spawnSync('bun', ['--version'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      shell: process.platform === 'win32',
+    })
+    return result.status === 0
+  } catch {
+    return false
+  }
+}
+
+if (!bunIsAvailable()) {
+  console.warn(
+    [
+      '',
+      'dbcli: Bun was not found on PATH.',
+      '',
+      "  The package installed, but dbcli's executable runs under Bun (its shebang is",
+      '  `#!/usr/bin/env bun`), so `dbcli` will not start until Bun 1.3.3+ is installed:',
+      '',
+      `    ${BUN_INSTALL_HINT}`,
+      '',
+      '  The ./agent-core subpath export is importable from Node without Bun.',
+      '',
+    ].join('\n')
+  )
+}