@carllee1983/dbcli 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.11.0] - 2026-05-08
+
+### Added
+
+- `dbcli queries search <keywords>` — fuzzy keyword search across saved queries.
+- `dbcli queries suggest <intent>` — intent-prefix suggestion.
+- Optional `intent` frontmatter field on snippets.
+- 9 new diagnostic snippets: ES x4 (hot-threads, index-stats, unassigned-shards, pending-tasks); Redis x4 (slowlog, client-list, memory-usage, cluster-info); SQL x1 (blocking-queries.postgres).
+- "When you don't know which query to run" section in SKILL.md.
+
+### Changed
+
+- All 18 existing built-in diagnostic snippets backfilled with `intent`.
+- `foldVariants` extracted from `src/commands/queries.ts` to `src/core/saved-queries/fold.ts`.
+- Redis read-only allowlist gained `CLIENT`, `INFO`, `CLUSTER`, `SLOWLOG` for diagnostic snippets.
+
+## [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

package/assets/SKILL.md

@@ -224,6 +224,14 @@ Run reusable parameterised SELECT snippets stored in your repo.
 | 2. Inspect | `dbcli queries show @<name>` |
 | 3. Run     | `dbcli q @<name> --param k=v` |
 
+### When you don't know which query to run
+
+1. `dbcli queries search <keywords>` — natural keywords, fuzzy ranked
+2. `dbcli queries suggest <intent>` — browse a category
+   Common intents: perf.slow-query, perf.cache-hit, capacity.size,
+                   safety.connections, monitor.cluster-health
+3. Once you find one: `dbcli q @<name>` (blacklist always enforced)
+
 Snippets resolve from three layers, **local > shared > builtin** (local wins):
 - `builtin` — bundled with dbcli (e.g. `@diag/*`); read-only at runtime
 - `.dbcli-shared/queries/` — committed, team-shared

package/assets/snippets/diag/blocking-queries.postgres.sql

@@ -0,0 +1,17 @@
+-- ---
+-- name: blocking-queries.postgres
+-- description: Top queries blocking others, with blocker/blocked PIDs
+-- engine: postgres
+-- intent: safety.locks
+-- tags: [diag, postgres, safety]
+-- ---
+SELECT blocked.pid       AS blocked_pid,
+       blocked.usename   AS blocked_user,
+       blocking.pid      AS blocking_pid,
+       blocking.usename  AS blocking_user,
+       blocked.query     AS blocked_query,
+       blocking.query    AS blocking_query
+FROM   pg_stat_activity blocked
+JOIN   pg_stat_activity blocking
+  ON   blocking.pid = ANY(pg_blocking_pids(blocked.pid))
+WHERE  blocked.wait_event_type IS NOT NULL;

package/assets/snippets/diag/cache-hit.mysql.sql

@@ -2,6 +2,7 @@
 -- name: InnoDB buffer pool hit ratio (mysql)
 -- description: Reads from disk vs. read requests from the buffer pool.
 -- engine: mysql
+-- intent: perf.cache-hit
 -- ---
 SELECT
   (SELECT VARIABLE_VALUE FROM performance_schema.global_status

package/assets/snippets/diag/cache-hit.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Cache hit ratio (postgres)
 -- description: Heap and index buffer cache hit ratios across user tables.
 -- engine: postgres
+-- intent: perf.cache-hit
 -- ---
 SELECT SUM(heap_blks_read)                                                       AS heap_read,
        SUM(heap_blks_hit)                                                        AS heap_hit,

package/assets/snippets/diag/client-list.redis.sql

@@ -0,0 +1,8 @@
+-- ---
+-- name: client-list.redis
+-- description: Active Redis client connections
+-- engine: redis
+-- intent: safety.connections
+-- tags: [diag, redis, safety]
+-- ---
+CLIENT LIST

package/assets/snippets/diag/cluster-info.redis.sql

@@ -0,0 +1,8 @@
+-- ---
+-- name: cluster-info.redis
+-- description: Redis cluster status (node count, slots, state)
+-- engine: redis
+-- intent: monitor.cluster-health
+-- tags: [diag, redis]
+-- ---
+CLUSTER INFO

package/assets/snippets/diag/connections.mysql.sql

@@ -2,6 +2,7 @@
 -- name: Active connections (mysql)
 -- description: Non-sleep processes ordered by elapsed time.
 -- engine: mysql
+-- intent: safety.connections
 -- ---
 SELECT id,
        user,

package/assets/snippets/diag/connections.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Active connections (postgres)
 -- description: Active sessions excluding idle, ordered by query start.
 -- engine: postgres
+-- intent: safety.connections
 -- ---
 SELECT pid,
        usename                              AS user,

package/assets/snippets/diag/db-size.mysql.sql

@@ -2,6 +2,7 @@
 -- name: Database size (mysql)
 -- description: Total data + index size per schema in MB.
 -- engine: mysql
+-- intent: capacity.size
 -- ---
 SELECT table_schema                                          AS `database`,
        ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS size_mb

package/assets/snippets/diag/db-size.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Database size (postgres)
 -- description: Each database with pretty-printed total size.
 -- engine: postgres
+-- intent: capacity.size
 -- ---
 SELECT datname                                AS database,
        pg_size_pretty(pg_database_size(datname)) AS size

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

@@ -2,6 +2,7 @@
 -- name: es-cluster-health
 -- description: Document counts per index across the cluster
 -- engine: elasticsearch
+-- intent: monitor.cluster-health
 -- index: '*'
 -- tags: [diag, elasticsearch]
 -- ---

package/assets/snippets/diag/hot-threads.elasticsearch.sql

@@ -0,0 +1,9 @@
+-- ---
+-- name: hot-threads.elasticsearch
+-- description: ES nodes hot threads — surface CPU bottlenecks
+-- engine: elasticsearch
+-- index: '_nodes/hot_threads'
+-- intent: monitor.cluster-health
+-- tags: [diag, elasticsearch, perf]
+-- ---
+{ "size": 0 }

package/assets/snippets/diag/index-stats.elasticsearch.sql

@@ -0,0 +1,16 @@
+-- ---
+-- name: index-stats.elasticsearch
+-- description: doc count + store size per index (top by store size)
+-- engine: elasticsearch
+-- index: '*'
+-- intent: capacity.size
+-- tags: [diag, elasticsearch, capacity]
+-- ---
+{
+  "size": 0,
+  "aggs": {
+    "by_index": {
+      "terms": { "field": "_index", "size": 50, "order": { "_count": "desc" } }
+    }
+  }
+}

package/assets/snippets/diag/index-usage.mysql.sql

@@ -2,6 +2,7 @@
 -- name: Index usage (mysql)
 -- description: Index I/O wait counts ordered by total uses.
 -- engine: mysql
+-- intent: perf.index-usage
 -- ---
 SELECT object_schema  AS `schema`,
        object_name    AS `table`,

package/assets/snippets/diag/index-usage.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Index usage (postgres)
 -- description: Indexes ordered by scan count (low scans = candidates to drop).
 -- engine: postgres
+-- intent: perf.index-usage
 -- ---
 SELECT schemaname                              AS schema,
        relname                                 AS table,

package/assets/snippets/diag/locks.mysql.sql

@@ -2,6 +2,7 @@
 -- name: Lock waits (mysql)
 -- description: InnoDB lock waits with waiting and blocking transactions.
 -- engine: mysql
+-- intent: safety.locks
 -- ---
 SELECT waiting.trx_mysql_thread_id  AS waiting_thread,
        waiting.trx_query            AS waiting_query,

package/assets/snippets/diag/locks.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Lock waits (postgres)
 -- description: Sessions blocked by other sessions with both queries shown.
 -- engine: postgres
+-- intent: safety.locks
 -- ---
 SELECT blocked.pid       AS blocked_pid,
        blocked.usename   AS blocked_user,

package/assets/snippets/diag/long-running.mysql.sql

@@ -2,6 +2,7 @@
 -- name: Long-running queries (mysql)
 -- description: Non-sleep processes whose elapsed time exceeds min_seconds.
 -- engine: mysql
+-- intent: perf.slow-query
 -- params:
 --   min_seconds:
 --     type: int

package/assets/snippets/diag/long-running.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Long-running queries (postgres)
 -- description: Queries running longer than min_seconds.
 -- engine: postgres
+-- intent: perf.slow-query
 -- params:
 --   min_seconds:
 --     type: int

package/assets/snippets/diag/memory-usage.redis.sql

@@ -0,0 +1,8 @@
+-- ---
+-- name: memory-usage.redis
+-- description: Redis memory usage breakdown
+-- engine: redis
+-- intent: capacity.memory
+-- tags: [diag, redis, capacity]
+-- ---
+INFO memory

package/assets/snippets/diag/missing-indexes.mysql.sql

@@ -2,6 +2,7 @@
 -- name: Missing indexes (mysql)
 -- description: Tables with significant full-scan I/O and no index used.
 -- engine: mysql
+-- intent: perf.index-usage
 -- ---
 SELECT object_schema  AS `schema`,
        object_name    AS `table`,

package/assets/snippets/diag/missing-indexes.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Missing indexes (postgres)
 -- description: User tables where seq scans dominate over index scans (>1k rows).
 -- engine: postgres
+-- intent: perf.index-usage
 -- ---
 SELECT schemaname     AS schema,
        relname        AS table,

package/assets/snippets/diag/pending-tasks.elasticsearch.sql

@@ -0,0 +1,9 @@
+-- ---
+-- name: pending-tasks.elasticsearch
+-- description: Cluster pending tasks queue depth and ages
+-- engine: elasticsearch
+-- index: '_cluster/pending_tasks'
+-- intent: monitor.cluster-health
+-- tags: [diag, elasticsearch]
+-- ---
+{ "size": 0 }

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

@@ -2,6 +2,7 @@
 -- name: redis-key-stats
 -- description: Sample keyspace via SCAN with explicit COUNT bound
 -- engine: redis
+-- intent: capacity.size
 -- params:
 --   match:
 --     type: string

package/assets/snippets/diag/slowlog.redis.sql

@@ -0,0 +1,12 @@
+-- ---
+-- name: slowlog.redis
+-- description: Recent Redis slow log entries
+-- engine: redis
+-- intent: perf.slow-query
+-- tags: [diag, redis, perf]
+-- params:
+--   count:
+--     type: int
+--     default: 50
+-- ---
+SLOWLOG GET :count

package/assets/snippets/diag/table-sizes.mysql.sql

@@ -2,6 +2,7 @@
 -- name: Table sizes (mysql)
 -- description: Data + index size in MB with estimated row count.
 -- engine: mysql
+-- intent: capacity.size
 -- ---
 SELECT table_schema                                              AS `schema`,
        table_name                                                AS `table`,

package/assets/snippets/diag/table-sizes.postgres.sql

@@ -2,6 +2,7 @@
 -- name: Table sizes (postgres)
 -- description: Total / table / index size with estimated row count.
 -- engine: postgres
+-- intent: capacity.size
 -- ---
 SELECT schemaname                                                           AS schema,
        tablename                                                            AS table,

package/assets/snippets/diag/unassigned-shards.elasticsearch.sql

@@ -0,0 +1,9 @@
+-- ---
+-- name: unassigned-shards.elasticsearch
+-- description: Shards stuck in UNASSIGNED state
+-- engine: elasticsearch
+-- index: '_cluster/allocation/explain'
+-- intent: monitor.cluster-health
+-- tags: [diag, elasticsearch, safety]
+-- ---
+{ "size": 0 }