@carllee1983/dbcli 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.9.0] - 2026-05-06
+
+### Added
+
+- **Agent Task Packs（plan-only 第一版）**：`dbcli skill tasks list/show/plan` 讓 AI agent 可探索團隊定義的資料庫任務範本並產生安全可審查的執行計畫。
+  - 三層儲存：`assets/tasks/`（內建）< `.dbcli-shared/tasks/`（團隊共享）< `.dbcli/tasks/`（個人覆蓋）。
+  - Task 檔為 `.md`：YAML frontmatter（name/description/tags/engines/params/safety/steps）＋ markdown agent notes。
+  - 嚴格 schema：`safety.mode` 僅接受 `plan-only`、`step.type` 僅接受 `command`，未知欄位直接 fail 解析而非靜默忽略。
+  - `plan` 輸出包含原始 `command`、`resolvedCommand`、`argv`（shell-aware 切分），方便 agent 直接消費。
+  - 內建第一版 `diagnose-slow-query` 任務作為範例。
+- 文件：`assets/SKILL.md` 與 `assets/reference.md` 同步加入 Agent Task Packs 章節；`docs/feature-matrix.md` 補充 `skill tasks` 子命令說明。
+
+### Changed
+
+- `src/core/saved-queries/yaml-mini.ts`：擴充支援 YAML block list 語法（`- scalar`、`- key: value` 起始的 sub-map），以承載 Agent Task Packs 的 frontmatter；既有 saved-queries 解析行為不變、66 個既有測試全綠。
+
+## [1.8.0] - 2026-05-06
+
+### Added
+
+- **Redis 與 Elasticsearch 支援**：`init`、`list`、`schema`、`query`、`status`、`use`、`doctor`、`upgrade`、`completion` 在兩個系統皆真實可用。
+  - Redis：`list` 透過 SCAN 取 keys；`schema <key>` 顯示 type/TTL/size/sample；`query` 執行白名單 Redis 指令並走原本權限與黑名單檢查。
+  - Elasticsearch：`list` 顯示 indices 與文件數；`schema [index]` 攤平 mapping、揭露 `.fields` multi-fields；`query` 接受 DSL JSON 或 Lucene 字串。
+- 文件：`assets/SKILL.md` 與 `assets/reference.md` 同步加入 Redis / Elasticsearch 章節。
+
+### Fixed
+
+- **`insert` / `update` / `delete` / `export` / `diff` 對 Redis / Elasticsearch 的早期錯誤訊息**：先前會落入 SQL DataExecutor 出現「Column ... not found in table」之類誤導訊息，現在直接回傳明確的「不支援」JSON，並指引正確替代路徑（Redis 改用 `query`、Elasticsearch 改用外部工具或 `query --index`）。
+- **TypeScript 嚴格度**：`bun run typecheck` 從 43 個錯誤降為 0。
+  - `ConnectionConfig` union 加入 `ElasticsearchConnectionConfig`。
+  - `ResolvedConnection.connection.system`、`ReplContext.system` 涵蓋 `'elasticsearch'`。
+  - `ExecutionResult` 補上 optional `rowCount` / `columnNames`。
+  - `getDefaultsForSystem` 涵蓋 redis (6379) / elasticsearch (9200) 預設值。
+
 ## [1.7.0] - 2026-05-04
 
 ### Added

package/README.md

@@ -114,7 +114,45 @@ dbcli query '{"status":"active"}' --collection users --use atlas
 
 For MongoDB, `list` and `query` operate on the database configured for the connection, and `query` requires `--collection <name>`.
 
-For a command-by-command support matrix across PostgreSQL, MySQL, MariaDB, and MongoDB, see [docs/feature-matrix.md](./docs/feature-matrix.md).
+For a command-by-command support matrix across PostgreSQL, MySQL, MariaDB, MongoDB, Redis, and Elasticsearch, see [docs/feature-matrix.md](./docs/feature-matrix.md).
+
+### Redis & Elasticsearch Support
+
+dbcli extends its unified interface to Redis and Elasticsearch, providing consistent discovery and querying.
+
+#### Redis
+
+```bash
+# Connect to Redis
+dbcli init --system redis --host localhost --port 6379
+
+# List keys (uses SCAN)
+dbcli list
+
+# Inspect a key (type, TTL, size, sample)
+dbcli schema my-key
+
+# Run Redis commands (whitelisted)
+dbcli query "GET my-key"
+dbcli query "HGETALL user:1"
+```
+
+#### Elasticsearch
+
+```bash
+# Connect to Elasticsearch
+dbcli init --system elasticsearch --host localhost --port 9200
+
+# List indices and document counts
+dbcli list
+
+# Show mapping/structure of an index
+dbcli schema my-index
+
+# Query using Lucene or DSL JSON
+dbcli query "status:active" --index my-index
+dbcli query '{"query": {"match_all": {}}}' --index my-index
+```
 
 ---
 

package/README.zh-TW.md

@@ -189,7 +189,7 @@ dbcli init [OPTIONS]
 ```
 
 **選項 (基本)：**
-- `--system <type>` — 資料庫系統：`postgresql`、`mysql`、`mariadb`、`mongodb`
+- `--system <type>` — 資料庫系統：`postgresql`、`mysql`、`mariadb`、`mongodb`、`redis`、`elasticsearch`
 - `--host <host>` — 主機
 - `--port <port>` — 埠號
 - `--user <user>` — 使用者

package/assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dbcli
-description: Database CLI for AI agents with permission-based access control. Use to query, inspect schemas, insert/update/delete, export results, and blacklist sensitive columns/tables. Supports MySQL, PostgreSQL, MariaDB, and MongoDB with multiple named connections per project and custom env files. Trigger when working with databases, running SQL or MongoDB JSON queries, exploring table/collection structures, switching database environments, or protecting sensitive data from AI access. For exhaustive flags and examples, read the sibling `reference.md`.
+description: Database CLI for AI agents with permission-based access control. Use to 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 working with databases, running SQL / MongoDB JSON / Redis commands / Elasticsearch DSL, exploring table/collection/key/index structures, switching database environments, or protecting sensitive data from AI access. For exhaustive flags and examples, read the sibling `reference.md`.
 ---
 
 # dbcli
@@ -11,13 +11,32 @@ Database CLI for AI agents with permission-based access control.
 
 1. `dbcli status` — permission level and system summary (no credentials).
 2. `dbcli blacklist list` — sensitive data boundaries.
-3. `dbcli schema <table> --format json` — real column names. **Never guess.**
+3. `dbcli schema <table> --format json` — real column names (SQL/Mongo/ES) or `schema <key>` (Redis). **Never guess.**
 4. Run `query` / `insert` / `update` / `delete` / `export` within permission.
-5. All writes: `--dry-run` → run → `query` read-back to confirm.
+5. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm.
 
 Prefer `--format json` for agent-friendly output.
 
-Full flags, per-command copy-paste blocks, `migrate` DDL, interactive `shell`, and MongoDB walkthroughs are in [reference.md](reference.md) (installed next to this file).
+## Agent Task Packs
+
+When the user asks for a database workflow (e.g. "diagnose this slow query", "audit
+permissions", "review long-running operations"), prefer published task templates
+over inventing steps from memory.
+
+```bash
+dbcli skill tasks list --format json                              # discover
+dbcli skill tasks show <task>                                     # inspect
+dbcli skill tasks plan <task> --param key=value --format json     # generate plan
+```
+
+The plan output is an ordered list of dbcli commands with rationale and risk
+labels. Execute them one at a time — task plans do **not** override blacklist,
+schema, dry-run, or confirmation requirements.
+
+Tasks live under `assets/tasks/` (builtin), `.dbcli-shared/tasks/` (shared), and
+`.dbcli/tasks/` (local override).
+
+Full flags, per-command copy-paste blocks, `migrate` DDL, interactive `shell`, and MongoDB/Redis/ES walkthroughs are in [reference.md](reference.md) (installed next to this file).
 
 ## Quick start
 
@@ -33,21 +52,21 @@ dbcli query "SELECT * FROM users"   # Execute SQL (auto LIMIT 1000)
 |---------|-----------------|---------|
 | `init` | n/a | Create `.dbcli` (v1 single or v2 multi via `--conn-name` / `--env-file`). **Usually run by the human** — do NOT re-run to strip `{"$env"}` references; that format is intentional. |
 | `use` | n/a | Show/switch default named connection (v2 only). |
-| `list` | query-only+ | Tables (SQL) or collections (MongoDB). |
-| `schema` | query-only+ | Per-table or full scan into `.dbcli/schemas/`; use `--use` for the correct connection cache. |
-| `query` | query-only+ | SQL, or Mongo JSON filter / pipeline with `--collection`. |
-| `insert` / `update` | read-write+ | JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. |
-| `delete` | data-admin+ | `--where` required; `--dry-run` first. |
-| `export` | query-only+ | Query → CSV/JSON file or stdout. |
+| `list` | query-only+ | Tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |
+| `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). |
+| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). |
+| `insert` / `update` | read-write+ | SQL or MongoDB only. JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. Redis writes go through `query`. |
+| `delete` | data-admin+ | SQL or MongoDB only. `--where` required; `--dry-run` first. |
+| `export` | query-only+ | SQL or MongoDB only. Query → CSV/JSON(L) file or stdout. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
-| `check` | query-only+ | Table health: nulls, duplicates, orphans, rowCount, size. |
-| `diff` | query-only+ | Save/compare schema snapshots. |
+| `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
+| `diff` | query-only+ | SQL only. Save/compare schema snapshots. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `doctor` | n/a | Environment, config, connection, SRV diagnostics (Mongo), schema cache age. |
 | `completion` | n/a | bash / zsh / fish scripts. |
 | `upgrade` | n/a | Self-update from npm; 24h-cached version hints on every command. |
-| `shell` | (same as query+) | Interactive REPL. |
-| `migrate` | admin | **DDL; dry-run by default** — needs `--execute`; DROP also needs `--force`. |
+| `shell` | (same as query+) | Interactive REPL. SQL engines + MongoDB shell only. |
+| `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 `--use <name>` on any subcommand targets a v2 connection without changing the default.
 
@@ -69,11 +88,31 @@ dbcli query "SELECT * FROM users"   # Execute SQL (auto LIMIT 1000)
 ## MongoDB
 
 - JSON filter object (`find`) or JSON array (`aggregate`); SQL is rejected. `--collection <name>` is required on `query`.
-- **Supported:** `init`, `list`, `query`, `status`, `use`, `shell`, `doctor`, `upgrade`, `completion`.
-- **Not supported:** `schema`, `insert`, `update`, `delete`, `export`, `diff`, `migrate`, `check`.
-- No auto-limit on MongoDB queries — use `$limit` in the pipeline if needed.
+- **Supported:** `init`, `list`, `schema` (sampled), `query`, `insert`, `update`, `delete`, `export`, `status`, `use`, `shell`, `doctor`, `upgrade`, `completion`.
+- **Not supported:** `q` (saved queries), `diff`, `migrate`, `check`.
+- Schema is **sampled** (default 50 docs); types are JS `typeof` strings.
 - See reference.md MongoDB section for full syntax and examples.
 
+## Redis
+
+- Command-style execution; `query` runs a whitelisted Redis command (e.g. `GET`, `HSET`, `DEL`).
+- **Supported:** `init`, `list` (keys via SCAN), `schema <key>` (type / TTL / size / sample), `query`, `status`, `use`, `doctor`, `upgrade`, `completion`.
+- **Not supported:** `schema` full scan, `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q`.
+  Use `query "DEL <key>"` etc. for writes — they go through the same permission gate.
+- Permission tiers map to commands: read commands → `query-only`; mutators (`SET`, `HSET`, ...) → `read-write`; `DEL` / `UNLINK` → `data-admin`.
+- `database` field is the logical DB index (default `0`); `list` returns ≤ 100 000 keys via SCAN.
+- See reference.md Redis section.
+
+## Elasticsearch
+
+- DSL (JSON body) or Lucene query string; `--collection <index>` is required on `query`.
+- **Supported:** `init`, `list` (indices with doc count), `schema [index]` (flattened mapping), `query`, `status`, `use`, `doctor`, `upgrade`, `completion`.
+- **Not supported:** `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q`.
+  Writes are not exposed via dedicated subcommands yet — use `query` if the cluster allows or external tools.
+- Query-only mode caps at 1000 hits; `--no-limit` is bounded at 10 000.
+- Schema flattens nested fields (`a.b.c`) and surfaces `.fields` multi-fields.
+- See reference.md Elasticsearch section.
+
 ## Saved queries
 
 Run reusable parameterised SELECT snippets stored in your repo.

package/assets/reference.md

@@ -21,6 +21,14 @@ dbcli init --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSourc
 dbcli init --system mongodb --host localhost --port 27017 --user admin --password secret --name mydb
 dbcli init --system mongodb --host localhost --port 27017 --name mydb  # No auth
 
+# Redis (database = logical DB index)
+dbcli init --system redis --host localhost --port 6379
+dbcli init --system redis --host localhost --port 6379 --password secret --name 0
+
+# Elasticsearch
+dbcli init --system elasticsearch --host localhost --port 9200 --user elastic --password changeme
+dbcli init --system elasticsearch --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
+
 # Multi-connection (v2 format)
 dbcli init --conn-name staging --env-file .env.staging   # Named connection with custom env file
 dbcli init --conn-name prod --env-file .env.production --use-env-refs --skip-test
@@ -32,6 +40,10 @@ dbcli init --rename staging:production                   # Rename a connection
 
 **MongoDB-specific options:** `--uri <uri>` (full connection URI), `--auth-source <db>` (auth database, default: `admin` when user/password set)
 
+**Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
+
+**Redis note:** the `database` (or `--name`) field is the logical DB index (`"0"` … `"15"`), not a database name.
+
 **Multi-connection:** Using `--conn-name` or `--env-file` creates a v2 config with named connections. Each connection can have its own env file and permission level. Existing v1 configs are automatically imported as the `default` connection when upgrading.
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
@@ -57,16 +69,19 @@ dbcli list --use prod
 
 ### list
 
-List all tables (SQL) or collections (MongoDB).
+List all tables (SQL), collections (MongoDB), keys (Redis), or indices (Elasticsearch).
 
 ```bash
 dbcli list
 dbcli list --format json
+dbcli list --include-system        # Elasticsearch: include `.system` indices
 ```
 
 **Permission:** query-only+
 
-> **MongoDB:** Lists collections with estimated document count instead of tables.
+> **MongoDB:** Lists collections with estimated document count.
+> **Redis:** Returns up to 100 000 keys via `SCAN MATCH * COUNT 1000`. The header reads `Keys in db <n> (redis):` where `<n>` is the logical DB index.
+> **Elasticsearch:** Returns indices with `documentCount` from `/_stats/docs`; aliases are tagged separately. System indices (names starting with `.`) are hidden unless `--include-system` is passed.
 
 ### schema
 
@@ -90,6 +105,9 @@ dbcli schema --use prod             # Scan prod DB; saves to .dbcli/schemas/prod
 
 **Schema storage (v1.4+):** Schema is persisted as layered files under `.dbcli/schemas/`. With v2 multi-connection config each connection gets its own subdirectory (`.dbcli/schemas/<connection>/`). Run `dbcli schema --use <connection>` once per connection before querying it — otherwise `schema <table>` may return data from the wrong connection's cache.
 
+> **Redis:** `schema <key>` is required (no full scan). The output exposes `type`, `ttl`, `size`, and a small `sample` (e.g. first 5 hash keys). `--reset` / `--refresh` are rejected — Redis caches no schema.
+> **Elasticsearch:** `schema [index]` flattens the `_mapping` properties (nested `a.b.c`) and emits each `.fields` multi-field as a separate column (e.g. `text` + `text.keyword`). Full scan iterates all non-system indices and stores per-connection caches alongside SQL engines.
+
 ### query
 
 Execute SQL query (MySQL/PostgreSQL/MariaDB) or JSON filter/pipeline (MongoDB).
@@ -106,16 +124,38 @@ dbcli query '{"age": {"$gt": 18}}' --collection users --format json
 
 # MongoDB: aggregation pipeline
 dbcli query '[{"$match": {"status": "active"}}, {"$group": {"_id": "$role", "count": {"$sum": 1}}}]' --collection users
+
+# Redis: any whitelisted command (permission-gated by command)
+dbcli query "GET session:abc"
+dbcli query "HGETALL user:42" --format json
+dbcli query "SCAN 0 MATCH user:* COUNT 100"
+dbcli query "SET feature:flag enabled"          # requires read-write+
+dbcli query "DEL stale:key"                      # requires data-admin+
+
+# Elasticsearch: DSL body or Lucene q-string
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
+dbcli query 'status:active AND amount:>100' --index orders --limit 50
 ```
 
-**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB only)
-**Permission:** query-only+
+**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`)
+**Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
 > **MongoDB notes:**
 > - SQL syntax is rejected — use JSON object (filter) or JSON array (pipeline)
 > - `--collection <name>` is required
 > - Auto-limit does not apply; use `$limit` in your pipeline if needed
 
+> **Redis notes:**
+> - The first token must be an allow-listed command (`GET`/`SET`/`HGET`/`HSET`/`DEL`/...). Unknown commands are refused.
+> - Permission tier is derived from the command (read → `query-only`, write → `read-write`, delete → `data-admin`, `KEYS`/`FLUSHDB`/`CONFIG`/... → `admin`).
+> - Output is always shaped into rows: scalar replies become `{value: ...}`; arrays become indexed rows; `HGETALL` is folded into a single object.
+
+> **Elasticsearch notes:**
+> - `--collection` (or `--index`) is required.
+> - A body that begins with `{` is sent as DSL via `POST /<index>/_search`; otherwise the value is URL-encoded into `?q=...` (Lucene query string) via `GET`.
+> - Hits are flattened: each result row contains `_id` plus dotted-path fields from `_source`. Pass `--format json` to keep nested structures readable.
+> - Query-only mode caps at 1000 hits; `--no-limit` is internally capped at 10 000 (use saved searches / `search_after` for deeper pagination).
+
 ### q
 
 Run a saved query snippet by `@name`. Snippets are parameterised SELECT/WITH statements resolved from three layers, with **local > shared > builtin** precedence (a local file always shadows shared and builtin variants of the same key):
@@ -458,6 +498,33 @@ dbcli migrate drop-enum status --execute --force
 
 **AI agent note:** Always use dry-run first (no `--execute`) to preview generated SQL. Only add `--execute` after confirming the SQL is correct. For DROP operations, both `--execute` and `--force` are required.
 
+### skill tasks (Agent Task Packs)
+
+```bash
+dbcli skill tasks list                                            # human table
+dbcli skill tasks list --format json --tag diagnostics
+dbcli skill tasks list --engine postgres --source builtin
+dbcli skill tasks show diagnose-slow-query
+dbcli skill tasks show diagnose-slow-query --format json
+dbcli skill tasks plan diagnose-slow-query --param query="SELECT 1"
+dbcli skill tasks plan diagnose-slow-query --param query="..." --format json
+```
+
+- **list filters:** `--tag <tag>`, `--engine <postgres|mysql|mongodb|redis|elasticsearch>`, `--source <builtin|shared|local>`, `--format <table|json>`.
+- **show:** prints the full task definition (frontmatter + Agent Notes). Use `--format json` for an agent-friendly contract.
+- **plan:** resolves `{{param}}` placeholders, validates required parameters, and emits a stable plan. Plans are **plan-only** in this version — dbcli will never execute the resulting commands automatically.
+
+Task storage layers:
+
+| Source | Path | Notes |
+| --- | --- | --- |
+| builtin | `assets/tasks/` | shipped with dbcli |
+| shared | `.dbcli-shared/tasks/` | team-managed, version-controlled |
+| local | `.dbcli/tasks/` | personal, gitignored |
+
+Higher tiers override lower tiers by task name. Task name is derived from the
+file path under the tier root (e.g. `diag/inspect.md` → `diag/inspect`).
+
 ## MongoDB Support
 
 MongoDB connections use a JSON-based query model instead of SQL. Treat MongoDB support as a narrower document-database path, not as a full SQL feature equivalent.
@@ -508,3 +575,144 @@ dbcli delete orders --where '{"status":"cancelled"}' --force
 | Field filter | `'{"field": "value"}'` |
 | Comparison | `'{"age": {"$gt": 18}}'` |
 | Aggregation | `'[{"$match": {...}}, {"$group": {...}}]'` |
+
+## Redis Support
+
+Redis connections speak Redis commands rather than SQL. The adapter uses the `ioredis` driver and exposes a narrow, permission-gated surface.
+
+**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.
+
+### Connection and configuration
+
+- Required fields: `system: redis`, `host`, `port`. `password` and `database` are optional.
+- `database` is the **logical DB index** (`"0"` … `"15"`), kept as a string to play nicely with env-ref bindings. `list` and the connection metadata both label it as the active DB.
+- `connection.timeout` (ms, default 5000) maps to ioredis's `connectTimeout`.
+
+### Permission classification
+
+Permission is derived from the command's first token (case-insensitive). Unknown commands are denied even at `admin` tier — they must be added to the allow-list.
+
+| Tier | Commands |
+|------|----------|
+| `query-only` | `GET`, `MGET`, `STRLEN`, `EXISTS`, `TTL`, `PTTL`, `TYPE`, `SCAN`, `HGET`, `HGETALL`, `HKEYS`, `HVALS`, `HLEN`, `HEXISTS`, `HMGET`, `LRANGE`, `LLEN`, `LINDEX`, `SMEMBERS`, `SCARD`, `SISMEMBER`, `ZRANGE`, `ZREVRANGE`, `ZRANGEBYSCORE`, `ZCARD`, `ZSCORE`, `PING`, `ECHO` |
+| `read-write` | `SET`, `SETEX`, `SETNX`, `PSETEX`, `MSET`, `MSETNX`, `APPEND`, `INCR`/`INCRBY`, `DECR`/`DECRBY`, `HSET`/`HSETNX`/`HMSET`/`HINCRBY`, `LPUSH`/`RPUSH`/`LPOP`/`RPOP`/`LSET`, `SADD`/`SREM`, `ZADD`/`ZREM`, `EXPIRE`/`EXPIREAT`/`PEXPIRE`/`PERSIST`, `RENAME` |
+| `data-admin` | `DEL`, `UNLINK`, `HDEL` |
+| `admin` | `FLUSHDB`, `FLUSHALL`, `CONFIG`, `INFO`, `CLIENT`, `DEBUG`, `SHUTDOWN`, `KEYS`, `MONITOR`, `SAVE`, `BGSAVE`, `BGREWRITEAOF`, `REPLICAOF`, `SLAVEOF`, `ACL` |
+
+### Schema inspection
+
+`schema <key>` returns one synthetic row per key with these columns:
+
+| column | meaning |
+|--------|---------|
+| `type` | Redis type (`string` / `hash` / `list` / `set` / `zset` / `stream` / `none`) |
+| `ttl` | `<n>s`, `no expiry`, or `missing` |
+| `size` | `STRLEN` / `HLEN` / `LLEN` / `SCARD` / `ZCARD` / `XLEN` depending on type |
+| `sample` | First 5 hash field names (hash only) |
+
+`schema` (no key) and `--refresh` / `--reset` are rejected — there is no full-database schema cache for Redis.
+
+### Recommended `query` patterns
+
+```bash
+# Read
+dbcli query "GET feature:flag"
+dbcli query "HGETALL user:42" --format json
+dbcli query "LRANGE queue:jobs 0 9"
+
+# Iterate keys (paginated; never use KEYS — admin-only)
+dbcli query "SCAN 0 MATCH session:* COUNT 200"
+
+# Write (requires read-write+)
+dbcli query "SET counter 1"
+dbcli query "EXPIRE session:abc 3600"
+dbcli query "HSET user:42 name Alice"
+
+# Delete (requires data-admin+)
+dbcli query "DEL temp:lock"
+dbcli query "HDEL user:42 lastLogin"
+```
+
+### Limitations
+
+- No `--dry-run` for writes — Redis commands execute immediately. Pair writes with a confirming read (`GET`, `HGETALL`, `EXISTS`).
+- No transaction wrapping (`MULTI`/`EXEC`). Submit one command at a time.
+- `KEYS` requires `admin`. Prefer `SCAN` for routine work.
+- Blacklist rules are not enforced for Redis (there is no concept of "column" / "table" the validator can map). Be careful with sensitive key prefixes.
+
+## Elasticsearch Support
+
+Elasticsearch connections speak the REST API. The adapter is fetch-based (no SDK) and supports HTTPS, custom CA, API key, basic auth, and Cloud ID.
+
+**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.
+
+### Connection and configuration
+
+- Either `host` + `port` (default `https://localhost:9200`) or `nodes: [...]` (first node is used) or `cloudId`.
+- Auth precedence: `apiKey` → `user`/`password` (HTTP Basic). Leave both unset for an open cluster.
+- `protocol` defaults to `https`. For TLS quirks: `caPath` (path to a PEM bundle) and `rejectUnauthorized: false` (last resort).
+- `connection.timeout` (ms, default 5000) is wired to `AbortController` on every request.
+
+### Permission classification
+
+Each REST request is mapped to a SQL-shaped tier based on method + path:
+
+| ES surface | Mapped to | Permission |
+|------------|-----------|------------|
+| `GET _search` / `_count` / `_mapping` / `_settings` / `_alias` / `GET _doc` / `_source` | `SELECT` | `query-only` |
+| `POST _update` / `POST _doc` | `UPDATE` | `read-write` |
+| `PUT _doc` / `_create` | `INSERT` | `read-write` |
+| `DELETE` (any) | `DELETE` | `data-admin` |
+| `_bulk` | highest tier among the NDJSON actions (`delete` ⇒ `data-admin`) | derived |
+| Anything else | `DROP` | `admin` (deny by default) |
+
+### Schema inspection
+
+`schema [index]` calls `GET /<index>/_mapping` and flattens nested properties into dotted-path columns. Multi-fields under `.fields` (e.g. `text` → `text.keyword`) are emitted as separate columns. All fields are reported as nullable. There is no PK / FK / index info.
+
+`schema` (no argument) iterates all non-system indices through the standard full-scan code path and writes per-connection caches under `.dbcli/schemas/<connection>/`.
+
+### Query semantics
+
+- `--collection <index>` (or `--index <index>`) is required.
+- Body that starts with `{` → sent as JSON DSL via `POST /<index>/_search`. Body otherwise → URL-encoded into `?q=...` (Lucene query string) on `GET`.
+- Hits are flattened: each row carries `_id` plus dotted-path fields lifted from `_source`. Use `--format json` to inspect raw nested structure.
+- Query-only mode caps `size` at 1000. `--no-limit` is internally capped at 10 000; for deeper pagination use the API directly with `search_after` or PIT.
+
+### Recommended `query` patterns
+
+```bash
+# DSL match
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders --format json
+
+# DSL with sort + size
+dbcli query '{"query":{"range":{"created_at":{"gte":"2026-01-01"}}},"sort":[{"created_at":"desc"}],"size":50}' \
+  --collection orders
+
+# Aggregation
+dbcli query '{"size":0,"aggs":{"by_status":{"terms":{"field":"status.keyword"}}}}' \
+  --collection orders --format json
+
+# Lucene query string
+dbcli query 'status:active AND amount:>100' --index orders --limit 100
+```
+
+### Doctor and diagnostics
+
+`dbcli doctor` runs a dedicated Elasticsearch path:
+
+- Verifies REST connectivity to `GET /`.
+- Reads `version.number` and runs the standard version freshness check.
+- Walks every index via `listTables()` + `getTableSchema()` to feed the blacklist completeness check and the large-table heuristic (using `documentCount`).
+- Standard schema-cache freshness using `schemaLastUpdated`.
+
+### Limitations
+
+- Writes (`insert`/`update`/`delete`/`export`) are not exposed yet — the adapter implements them, but the CLI currently only routes them for SQL and MongoDB.
+- No `_search/scroll` or PIT pagination at the CLI layer; large pulls need a saved external script.
+- `check`, `diff`, `migrate`, and `q` are SQL-only and exit with errors (or fall through to a generic "unsupported" path).
+- Blacklist column rules are applied to flattened hit rows on `query`; table-level blacklist rejects an index up front.

package/assets/tasks/README.md

@@ -0,0 +1,30 @@
+# dbcli Agent Tasks (built-in)
+
+Built-in task templates shipped with dbcli for AI agents.
+
+## Resolution order
+
+```
+assets/tasks/             # builtin (lowest)
+.dbcli-shared/tasks/      # shared, version-controlled
+.dbcli/tasks/             # local, gitignored (highest)
+```
+
+A task with the same name in a higher tier overrides the lower one. Use this to
+customize built-in workflows without modifying dbcli source.
+
+## File format
+
+Each task is a `.md` file with a YAML frontmatter block:
+
+- `name` (required, must match the file path without `.md`)
+- `description`, `tags`, `engines`
+- `params` (map of name → `{ type, required?, default?, description?, enum? }`)
+- `safety.mode` — only `plan-only` is supported in this version
+- `steps[]` — each step is `{ type: command, command, reason?, risk? }`
+
+Use block-style YAML (no inline `{ ... }` maps) — the built-in YAML parser does
+not support inline maps.
+
+The markdown body below the frontmatter is `Agent Notes` and is shown in
+`dbcli skill tasks show <name>`.

package/assets/tasks/diagnose-slow-query.md

@@ -0,0 +1,33 @@
+---
+name: diagnose-slow-query
+description: Diagnose slow query causes using safe read-only dbcli steps.
+tags: [diagnostics, performance, readonly]
+engines: [postgres, mysql]
+params:
+  query:
+    type: string
+    required: true
+    description: The slow SQL query or query fingerprint to inspect.
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm sensitive tables and columns are protected before inspection.
+    risk: readonly
+  - type: command
+    command: plan "{{query}}"
+    reason: Analyze SQL risk without executing the query.
+    risk: readonly
+  - type: command
+    command: q @diag/long-running --format json
+    reason: Inspect active long-running queries through a saved diagnostic snippet.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when the user reports a slow SQL query and wants safe diagnostic next steps.
+Do not run write operations.