@carllee1983/dbcli 1.9.1 → 1.10.1

package/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.10.1] - 2026-05-08
+
+### Fixed
+
+- **Packaged `dist/cli.mjs` 找不到 assets**：1.10.0 bundle 在 `task-paths.ts` / `snippet-paths.ts` 用 `import.meta.dir + ../../../` 解析 builtin 目錄，bundle 後三層往上會跳出 package root，npm 全域安裝的使用者執行 `dbcli queries list` / `dbcli skill tasks list` 讀不到資源。抽出 `src/utils/package-root.ts` 以 `package.json` 走訪定位 root，dev 與 bundle 都正確；`skill.ts` 內既有的 `findPackageRoot` 也收斂到同一處。
+- **`dbcli q` 略過 blacklist 檢查（安全）**：`q.ts` 把空字串當作 `tableName` 傳給 `BlacklistValidator.filterColumns`，column-level redaction 永遠不命中；同時也沒呼叫 `checkTableBlacklist`，使用者可以透過 saved snippet 直接 SELECT 黑名單表/欄位繞開保護。改為從 `prepared.rewrittenSql` 抽出主表（SQL）或 `prepared.execHints.index`（ES），執行前先 `checkTableBlacklist('SELECT', target)`，並把真正的 `tableName` 餵給 `filterColumns`；Redis 維持原樣。
+
+### Added
+
+- **dist/ 整合 smoke 測試**：`tests/integration/dist-smoke.test.ts` 從 OS tmpdir 執行 `dist/cli.mjs`，覆蓋 `--version`、`skill --output`、`queries list`、`skill tasks list`，守住 packaged assets path 不再回退。
+- **`q` blacklist 迴歸測試**：`tests/unit/commands/q-blacklist.test.ts` 覆蓋黑名單表阻擋、欄位 redact、未受影響 snippet 三種情境。
+
+### Changed
+
+- **Lint release-blocking**：`bun run lint` / `lint:fix` 加上 `--max-warnings=0`；同時清掉 45 個 `@typescript-eslint/no-explicit-any` warnings（以正型替代為主，`elasticsearch-adapter.ts` 因刻意不引入 `@elastic/elasticsearch` SDK 而以檔案層 `eslint-disable` 標註理由）。任何新 warning 從此會擋住 release。
+
+## [1.10.0] - 2026-05-08
+
+### Added
+
+- **Saved Queries 擴展至 Elasticsearch 與 Redis**：`dbcli q @<name>` 與 `queries` 子命令現在能依 frontmatter `engine` 自動切換到對應引擎，並走各引擎專屬的安全管線。
+  - **Engine strategy 重構**：runner 透過 `EngineStrategy` 介面分派到 SQL / Elasticsearch / Redis 三個獨立 strategy；既有 SQL 行為以 strategy 形式保留，無行為變更。
+  - **Elasticsearch strategy**：
+    - Frontmatter 接受 `engine: elasticsearch` 與 `index` 欄位；body 必須是合法 JSON，含 `script` 欄位的 query 直接拒絕。
+    - JSON-aware 參數注入：`:name` 僅在 JSON 字串脈絡裡替換，避免破壞語法。
+    - Size guard：自動補 `size` 上限；`aggs` 模式下放行但加註警告，分頁 (`from + size`) 過大時提示。
+  - **Redis strategy**：
+    - 命令白名單（read-only 為主）+ body validation；直接拒絕 unsupported 或寫入命令。
+    - Raw 參數注入：`:name` 直接代入字面量並打印 foot-gun 警告，提醒使用者 saved query 內不可放使用者輸入。
+    - Size guard：對 range / SCAN 命令的 `COUNT` / `LIMIT` 加上保險上限。
+  - **`q` 命令分派**：根據 prepared execution 的 engine family 呼叫對應 adapter，`--dry-run` 依 engine 用對應格式輸出（SQL 維持 SQL、ES 印 JSON body、Redis 印 argv）。
+  - **內建診斷 snippet**：
+    - `assets/snippets/diag/es-cluster-health.elasticsearch.sql` — ES 叢集健康度摘要。
+    - `assets/snippets/diag/redis-key-stats.redis.sql` — Redis key 數量 / type 分佈快照。
+- **整合測試**：新增 ES / Redis end-to-end saved query 測試（依本機是否有 Docker 而 skip，與既有 PG / MySQL 測試一致）。
+
+### Changed
+
+- **Redis 驅動**：改用 Bun 內建 `RedisClient`，移除外部 `ioredis` 依賴。
+- **Elasticsearch adapter**：refactor 並收斂錯誤訊息與 ExecutionResult 形狀，與 SQL / Mongo / Redis 對齊。
+- **文件**：`assets/SKILL.md` 與 `assets/reference.md` 補上 ES / Redis snippet 工作流；`docs/feature-matrix.md` 更新 saved-queries 欄位。
+
+### Fixed
+
+- **`dbcli export`（Redis 分支）**：`result.rowCount` 在 Redis 上可能 undefined 時導致 `tsc --noEmit` 報 TS2322；改為 `result.rowCount ?? result.rows.length ?? 0`，release gate 中的 typecheck 回到 0 錯誤。
+
 ## [1.9.1] - 2026-05-07
 
 ### Changed

package/assets/SKILL.md

@@ -237,6 +237,18 @@ Each `.sql` file may declare YAML frontmatter inside `-- ---` blocks
 (name, description, engine, params, tags). See `dbcli queries show @<name> --format json`
 for the machine-readable contract.
 
+### Engine-specific bodies
+
+Each snippet's body format is determined by the `engine` frontmatter field:
+
+| Engine            | Body format            | Notes |
+|-------------------|------------------------|-------|
+| postgres / mysql  | Single SELECT or WITH  | `:name` → driver bind (`$1` / `?`) |
+| elasticsearch     | JSON DSL               | `:name` → JSON-aware substitution; `index:` field required |
+| redis             | Single Redis command   | `:name` → raw text; only read commands allowed |
+
+Mixed-family `engine` arrays (e.g. `[postgres, elasticsearch]`) are rejected at parse time.
+
 ### Built-in diagnostic snippets
 
 dbcli ships ready-made diagnostic queries. Run with `dbcli q @diag/<topic>`:
@@ -251,6 +263,8 @@ dbcli ships ready-made diagnostic queries. Run with `dbcli q @diag/<topic>`:
 | `@diag/locks`           | lock-wait chains                         |
 | `@diag/db-size`         | database size summary                    |
 | `@diag/cache-hit`       | buffer cache hit ratios                  |
+| `@diag/es-cluster-health` | document counts per index (ES connections) |
+| `@diag/redis-key-stats`   | sample SCAN over keyspace (Redis connections) |
 
 Engine variants are picked automatically based on the active connection.
 Override any of them by placing a same-named file under `.dbcli-shared/queries/`

package/assets/reference.md

@@ -230,6 +230,62 @@ Param placeholders use `:name`. They are rewritten to `$1, $2, …` (Postgres) o
 - Files exceeding 64 KiB are rejected.
 - `--no-limit` is honoured only at the outermost level; nested subqueries are still wrapped by the size guard.
 
+##### Elasticsearch snippets
+
+Body is a JSON DSL `_search` request body. Frontmatter requires an `index:` field (may contain `:param`).
+
+Example:
+
+    -- ---
+    -- name: events-by-day
+    -- engine: elasticsearch
+    -- index: 'events-:date'
+    -- params:
+    --   date:    { type: date,   required: true }
+    --   user_id: { type: int,    required: true }
+    -- ---
+    {
+      "query": {
+        "bool": {
+          "filter": [
+            { "term": { "user_id": :user_id } }
+          ]
+        }
+      },
+      "size": 100
+    }
+
+Substitution rules (type-aware JSON injection):
+
+- `int` / `float` / `bool` outside string literals → bare value (`42`, `1.5`, `true`)
+- `string` / `date` / `datetime` outside string literals → JSON-quoted (`"Alice"`, `"2026-05-08"`)
+- Any param inside a JSON string literal → escaped inner form (`"prefix-:name"` works)
+
+`script` and `script_fields` are rejected anywhere in the body.
+
+Size guard: if `size` is missing, `1000` is injected (or `0` when `aggs` is present); explicit `size > 1000` is overridden with a warning unless `--no-limit`.
+
+##### Redis snippets
+
+Body is a single Redis command on one line. Only read-only commands are allowed:
+`GET MGET HGET HGETALL HMGET HKEYS HVALS HLEN HEXISTS LRANGE LLEN LINDEX SMEMBERS SISMEMBER SCARD ZRANGE ZRANGEBYSCORE ZRANGEBYLEX ZSCORE ZCARD ZCOUNT ZRANK TYPE EXISTS TTL PTTL STRLEN OBJECT SCAN HSCAN SSCAN ZSCAN`.
+
+`KEYS`, `EVAL`, `FLUSHDB`, `FLUSHALL`, `CONFIG`, `DEBUG`, `SHUTDOWN`, `SCRIPT` and any write command are rejected.
+
+Example:
+
+    -- ---
+    -- name: cache-user
+    -- engine: redis
+    -- params:
+    --   id: { type: int, required: true }
+    -- ---
+    HGETALL user::id
+
+Substitution rules: pure raw text — `:name` becomes the value's `String()` form. **Quoting is the snippet author's responsibility**: wrap `:name` in double quotes if the value may contain whitespace. The parser warns when a `string`-typed `:name` is adjacent to non-whitespace and unquoted.
+
+Size guard: `LRANGE` / `ZRANGE` stop overridden when `< 0` or `> 1000`; `SCAN` / `HSCAN` / `SSCAN` / `ZSCAN` get `COUNT 1000` injected if absent. `--no-limit` disables.
+
 ### queries
 
 Manage saved snippets — discover, inspect, scaffold, and edit local copies. Mutating
@@ -582,7 +638,9 @@ Redis connections speak Redis commands rather than SQL. The adapter uses the `io
 
 **Supported commands:** `init`, `use`, `list`, `schema`, `query`, `status`, `doctor`, `upgrade`, `completion`
 
-**Not supported (exit with error or unsupported error):** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q` (saved queries), `shell`. For writes, run the equivalent Redis command via `query` — the same permission gate applies.
+**Saved queries:** `q` is supported for read-only Redis commands (see "Redis snippets" below).
+
+**Not supported (exit with error or unsupported error):** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `shell`. For writes, run the equivalent Redis command via `query` — the same permission gate applies.
 
 ### Connection and configuration
 
@@ -648,7 +706,9 @@ Elasticsearch connections speak the REST API. The adapter is fetch-based (no SDK
 
 **Supported commands:** `init`, `use`, `list`, `schema`, `query`, `status`, `doctor`, `upgrade`, `completion`
 
-**Not supported (use external tooling):** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q`, `shell`. The permission classifier already understands `_doc` / `_update` / `_bulk` so future write surfaces can be wired in without changing tiers.
+**Saved queries:** `q` is supported for ES JSON DSL bodies (see "Elasticsearch snippets" below).
+
+**Not supported (use external tooling):** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `shell`. The permission classifier already understands `_doc` / `_update` / `_bulk` so future write surfaces can be wired in without changing tiers.
 
 ### Connection and configuration
 

package/assets/snippets/diag/es-cluster-health.elasticsearch.sql

@@ -0,0 +1,15 @@
+-- ---
+-- name: es-cluster-health
+-- description: Document counts per index across the cluster
+-- engine: elasticsearch
+-- index: '*'
+-- tags: [diag, elasticsearch]
+-- ---
+{
+  "size": 0,
+  "aggs": {
+    "by_index": {
+      "terms": { "field": "_index", "size": 50 }
+    }
+  }
+}

package/assets/snippets/diag/redis-key-stats.redis.sql

@@ -0,0 +1,11 @@
+-- ---
+-- name: redis-key-stats
+-- description: Sample keyspace via SCAN with explicit COUNT bound
+-- engine: redis
+-- params:
+--   match:
+--     type: string
+--     default: '*'
+-- tags: [diag, redis]
+-- ---
+SCAN 0 MATCH :match COUNT 100