@carllee1983/dbcli 1.38.1 → 1.39.2

package/assets/SKILL.zh-TW.md

@@ -1,6 +1,6 @@
 ---
 name: dbcli
-description: Database CLI for AI agents with permission-based access control. Use to set up new connections, query, inspect schemas, insert/update/delete, export results, and blacklist sensitive columns/tables. Supports MySQL, PostgreSQL, MariaDB, MongoDB, Redis, and Elasticsearch with multiple named connections per project and custom env files. Trigger when configuring a database connection (`.dbcli` / `.env`), choosing between v1 single and v2 multi-connection layouts, picking auth modes (URI, env refs, Cloud ID, API key), running SQL / MongoDB JSON / Redis commands / Elasticsearch DSL, exploring table/collection/key/index structures, switching database environments, protecting sensitive data from AI access, or performing automated recovery and guided remediation after command failures. For exhaustive flags and examples, read the sibling `reference.md`.
+description: Database CLI for AI agents with permission-based access control. Use to set up new connections, query, inspect schemas, insert/update/delete, export results, generate DB reports or interactive HTML dashboards, and blacklist sensitive columns/tables. Supports MySQL, PostgreSQL, MariaDB, MongoDB, Redis, and Elasticsearch with multiple named connections per project and custom env files. Trigger when configuring a database connection (`.dbcli` / `.env`), choosing between v1 single and v2 multi-connection layouts, picking auth modes (URI, env refs, Cloud ID, API key), running SQL / MongoDB JSON / Redis commands / Elasticsearch DSL, generating a report/dashboard/HTML UI from raw SQL or saved snippets, exploring table/collection/key/index structures, switching database environments, protecting sensitive data from AI access, or performing automated recovery and guided remediation after command failures. For exhaustive flags and examples, read the sibling `reference.md`.
 ---
 
 # dbcli
@@ -15,7 +15,16 @@ description: Database CLI for AI agents with permission-based access control. Us
 
 1. `dbcli blacklist list` — 確認敏感資料邊界。
 2. `dbcli schema <object> --format json` — 確認真實欄位名稱。**禁止猜測。**
-3. 所有寫入：`--dry-run`（SQL / Mongo）→ 實際執行 → `query` 回讀確認。
+3. 所有寫入：`--dry-run`（SQL / Mongo）→ 實際執行 → `query` 回讀確認。Redis 的 `query`
+   **沒有 `--dry-run`**（見 **Redis** 節）；Elasticsearch 為**唯讀**。
+
+**`update` / `delete` 的 `--where` 僅支援等式（SQL）。** 只接受 `col=val` 或
+`col1=v1 AND col2=v2`。比較 / 模式運算子（`>`、`>=`、`<`、`!=`、`LIKE`、`IN`）會直接
+**報錯**；更危險的是，`OR` 會被**靜默當成值的一部分** — `a=1 OR b=2` 會被解析成
+`a = "1 OR b=2"`，比對到錯誤的列（或完全比對不到）。需要範圍或複合條件時，先用
+`query` / `export` 撈出目標列的主鍵，再對每個主鍵執行一次
+`update` / `delete --where "id=<pk>"`（逐一等式）— 或升級交給人類處理。（MongoDB 的
+`--where` 接受完整 JSON filter，不受此限。）
 
 > `report` 與 `guide` 已內嵌 `inspect` 快照 — **不需要**先跑 `dbcli inspect`。只有在需要 audit-recent 脈絡或診斷連線問題時，才手動跑 `dbcli inspect --for-agent`。
 
@@ -25,6 +34,7 @@ description: Database CLI for AI agents with permission-based access control. Us
 | --- | --- |
 | 有名稱的工作流程符合（「診斷慢查詢」、「審計權限」） | `skill tasks list` → `skill tasks plan <pack>` — **優先選用；不要自己組合步驟** |
 | 固定診斷目標 | `guide <goal>`（`slow-query` / `capacity` / `health` / `index-usage` / `permissions` / `schema-overview`；`guide --list`） |
+| DB report / dashboard / HTML UI | `blacklist list` → `queries search <keywords>` 或 `queries suggest <intent>` → `queries show @<name>` → 瀏覽器：`q @<name> --param k=v --ui`；檔案：`q @<name> --format html > report.html` 或 `export "<SQL>" --format html --output report.html` |
 | 設定連線 | 見 **連線設定** |
 | 其他情況 | 手動執行指令；參考 **開發者工作流** 速查表 |
 
@@ -65,6 +75,7 @@ dbcli skill tasks plan <task> --param key=value --format json     # generate pla
 | 情境 | 最小安全路徑 |
 | --- | --- |
 | DB-backed 功能 | `blacklist list` → `schema <object>` → `queries suggest <intent>` |
+| DB report / dashboard request | `blacklist list` → `queries search <keywords>` / `queries suggest <intent>` → `queries show @<name>` → `q @<name> --ui` 或 `--format html` |
 | 應用程式資料錯誤 | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → 最小查詢 |
 | ORM 或 migration | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column`（預覽 SQL）→ `diff --against <snapshot>` |
 | PR 資料庫風險審查 | 審查變更的 persistence path，並針對每個重要主張提出具體 `schema`、`plan`、`dry-run`、`report` 或 `guide` 指令。 |
@@ -77,6 +88,11 @@ dbcli inspect --for-agent --format json
 dbcli blacklist list --format json
 dbcli schema <object> --format json
 dbcli queries suggest <intent> --format json
+dbcli queries search <report keywords> --format json
+dbcli queries show @<name> --format json
+dbcli q @<name> --param k=v --ui
+dbcli q @<name> --param k=v --format html > report.html
+dbcli export "<SQL>" --format html --output report.html
 dbcli audit tail --for-agent --n 10
 dbcli diff --snapshot <name>
 dbcli report --section perf --format json
@@ -273,10 +289,16 @@ dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-tes
 - **支援：** `init`、`list`（透過 SCAN 列 keys）、`schema <key>`（type / TTL / size / sample）、`query`、`q`（saved snippet — **僅唯讀命令**）、`delete`（基本實作：`DEL` / `HDEL` / `LREM` / `SREM` / `ZREM`，需 `data-admin`；`query "DEL <key>"` 亦可）、`shell`、`status`、`use`、`doctor`。**不支援：** `schema` 全掃描、`insert`、`update`、`check`、`diff`、`migrate`。
 - **權限分層：** 讀取類（`GET`/`HGET`/`SCAN`/…）→ `query-only`；mutator（`SET`/`HSET`/`INCR`/`EXPIRE`/`SETEX`/`RENAME`/…）→ `read-write`；`DEL`/`UNLINK`/`HDEL`/`XDEL` → `data-admin`。白名單外的指令一律拒絕。
 - **Redis `query` 無 `--dry-run`** — 寫入安全來自權限門檻與 key 黑名單（命中的讀寫會被拒絕）。如需預覽刪除，請用 `delete <key> --dry-run`。
-- `database` 是 logical DB index（預設 `0`）。`dbcli blacklist add 'secrets:*'` 註冊 key glob；可選的 `redis.mask` 區塊在讀取時遮罩值。大小防護（SCAN/HGETALL 截斷，`--no-limit` 可略過）與遮罩細節：reference.md Redis 段落。
+- `database` 是 logical DB index（預設 `0`）。`dbcli blacklist table add 'secrets:*'` 註冊 key glob；可選的 `redis.mask` 區塊在讀取時遮罩值。大小防護（SCAN/HGETALL 截斷，`--no-limit` 可略過）與遮罩細節：reference.md Redis 段落。
 
 ## Elasticsearch
 
+**dbcli 對 Elasticsearch 為唯讀 — 不支援 `insert` / `update` / `delete`。**
+
+```bash
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
+```
+
 - `query` 接受 DSL（JSON body）或 Lucene query string；`--collection <index>` 為必填。
 - **支援：** `init`、`list`（含文件數的索引清單）、`schema [index]`（flattened mapping）、`query`、`export`（v1.22）、`shell`（v1.22）、`status`、`use`、`doctor`。**不支援：** `insert`、`update`、`delete`、`check`、`diff`、`migrate`。
 - `export` 接受含 `--index <index>` 的 search DSL，或以 index 名稱作為查詢來透過 `match_all` scroll 整個 index。Query-only 上限 1000 hits；`--no-limit` 放寬至 10,000。
@@ -329,11 +351,13 @@ Snippet 從三層解析，**local > shared > builtin**（本地優先）：`buil
 
 ```bash
 dbcli query "SELECT day, dau FROM dau_daily" --ui          # open in browser
+dbcli q @analytics/revenue --param days=30 --ui            # snippet metadata + charts/KPIs
+dbcli q @analytics/revenue --param days=30 --format html > report.html
 dbcli query "SELECT * FROM orders" --format html > out.html # pipe HTML to stdout
 dbcli export "SELECT * FROM orders" --format html --output orders.html
 ```
 
-`--ui` 隱含 `--format html` 並開啟檔案；`--format html` 單獨使用則寫到 stdout。Blacklist 遮蔽在渲染**之前**套用。若要取得 KPI 與圖表而非純 table，請在 snippet frontmatter 加上 `visual:` 區塊（`title`、`kpis[]`、`charts[]`）— 完整 `visual:` schema 見 reference.md。原始 `query` 呼叫只能渲染 sortable table。
+`--ui` 隱含 `--format html` 並開啟檔案；`--format html` 單獨使用則寫到 stdout。若已存在 saved snippet，優先用 `q @<name> --ui` / `q @<name> --format html`，因為 snippet metadata 可驅動標題、KPI cards 與圖表。Blacklist 遮蔽在渲染**之前**套用。若要取得 KPI 與圖表而非純 table，請在 snippet frontmatter 加上 `visual:` 區塊（`title`、`kpis[]`、`charts[]`）— 完整 `visual:` schema 見 reference.md。原始 `query` / `export` 呼叫只能渲染 sortable table。
 
 ## 常見工作流程
 

package/assets/reference.md

@@ -249,6 +249,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
 - `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
+- `--verify` — run the snippet's verification assertions after execution (only if the snippet defines them)
 
 **Permission:** query-only+
 
@@ -474,9 +475,10 @@ Insert data into a table.
 dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
 dbcli insert users --data '{"name":"Alice"}' --dry-run
 dbcli insert users --data '{"name":"Alice"}' --force
+dbcli insert users --data '{"name":"Alice"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--data <json>`, `--dry-run`, `--force`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -486,11 +488,19 @@ Update existing data.
 ```bash
 dbcli update users --where "id=1" --set '{"name":"Bob"}'
 dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
+> **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
+> `col1=v1 AND col2=v2`. Comparison / pattern operators (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+> raise a parse error, and `OR` is **silently folded into the value** (`a=1 OR b=2` parses as
+> `a = "1 OR b=2"`, matching nothing intended). For ranges or compound predicates, select the
+> target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
+> (MongoDB `--where` accepts a full JSON filter and is exempt.)
+
 ### delete
 
 Delete data from a table.
@@ -499,9 +509,10 @@ Delete data from a table.
 dbcli delete users --where "id=1"
 dbcli delete users --where "id=1" --dry-run
 dbcli delete users --where "id=1" --force
+dbcli delete users --where "id=1" --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -521,7 +532,7 @@ dbcli export orders --format csv --output orders.csv      # index name as query
 dbcli export orders --no-limit --format jsonl             # scroll the whole index in batches
 ```
 
-**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--index <name>` (Elasticsearch), `--no-limit` (Elasticsearch full-index scroll)
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
@@ -892,6 +903,7 @@ Boundaries:
 | `--from <path>` | Read the envelope from this file instead of `.dbcli/last-recovery.json`. Accepts raw `RecoveryEnvelope` or `SavedRecoveryEnvelope`. | — |
 | `--allow-write <tier>` | Open the risk gate. Values: `readonly-cmd` (local-side writes) \| `write-cmd` (database writes). | `none` |
 | `--no-verify` | Skip the verify step appended after a successful `--apply`. | off (verify runs by default) |
+| `--write-verification-artifact` | After a successful `--apply`, persist a secret-free `VerificationArtifact` JSON under `.dbcli/verification/`. | off |
 | `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
 
 #### Plan source resolution
@@ -1650,6 +1662,7 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 **Options:**
 - `--install <platform>` — `claude` | `gemini` | `antigravity` | `copilot` | `cursor` | `codex` | `windsurf`. Writes `SKILL.md` plus `reference.md` next to it so the agent gets progressive disclosure.
 - `--output <path>` — write `SKILL.md` to a file instead of stdout. Does not install `reference.md`.
+- `--lang <en|zh-TW>` — source language for the emitted SKILL content (default `en`). It selects `assets/SKILL.md` vs `assets/SKILL.zh-TW.md`; the install/output filename stays `SKILL.md` regardless.
 
 **Notes:**
 - Both files come straight from `assets/SKILL.md` + `assets/reference.md` inside the dbcli package — no runtime rendering. Keep these in sync when shipping a release.
@@ -1662,6 +1675,21 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 
 **Permission:** n/a.
 
+### skill context
+
+Emit an AI-friendly snapshot of the connected database's schema and saved-query snippets (blacklist-filtered) so an agent can be primed with the current context.
+
+```bash
+dbcli skill context                      # XML (default)
+dbcli skill context --format json
+dbcli skill context --format markdown
+```
+
+**Options:**
+- `--format <xml|json|markdown>` — output format (default: `xml`)
+
+**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -2201,7 +2229,7 @@ Rewrites emit a `REDIS_SIZE_REWRITE` warning; truncations emit `REDIS_SIZE_TRUNC
 Blacklist rules are enforced as **Redis-native key globs** (`*`, `?`, `[abc]`, `[a-z]`):
 
 ```bash
-dbcli blacklist add 'secrets:*'          # register a key-glob rule
+dbcli blacklist table add 'secrets:*'    # register a key-glob rule
 dbcli query "GET secrets:api_key"        # → BlacklistRejection (exit non-zero)
 dbcli query "MGET safe:k secrets:api"    # → rejected (any matching key fails the whole command)
 dbcli query "KEYS secrets:*"             # → rejected (pattern overlaps a rule)