@carllee1983/dbcli 1.8.0 → 1.9.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.1] - 2026-05-07
+
+### Changed
+
+- **Skill 連線設定指引**：`assets/SKILL.md` 加入「Connection setup」章節，補齊 AI agent 協助使用者建立資料庫連線時所需的決策樹與各 engine essentials。
+  - 決策樹：v1 vs v2、credentials 來源（`.env` / env-refs / 明文）、權限 tier、`status` + `doctor` 驗證。
+  - Per-engine essentials：PostgreSQL / MySQL / MariaDB / MongoDB（含 `mongodb+srv://`）/ Redis（`--name` 為 logical DB index）/ Elasticsearch（basic / Cloud ID / API key）。
+  - v2 multi-connection 範例（`--conn-name`、`--env-file`、`use --list`、`--rename`、`--remove`）與 per-connection schema cache 注意事項。
+  - env-refs（`{ "$env": "..." }`）說明，以及「不要用 `--force` 把 env-refs 蓋成明文」的 guard。
+  - 常見陷阱：SRV DNS、URL 中特殊字元編碼、Redis `--name` 限制、Elasticsearch TLS 設定需手動編輯 `.dbcli`。
+  - 同步擴充 frontmatter `description`，加入 `init` / `.dbcli` / auth modes 觸發詞，提升 skill 觸發精準度。
+
+## [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

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, 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`.
+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, 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
 
@@ -27,6 +46,107 @@ dbcli schema                        # Scan all tables → .dbcli/schemas/
 dbcli query "SELECT * FROM users"   # Execute SQL (auto LIMIT 1000)
 ```
 
+If `.dbcli` does not yet exist, route through **Connection setup** below before
+touching `schema` / `query`.
+
+## Connection setup (helping the user wire up a database)
+
+When the user asks "how do I connect to X?", "set up dbcli for our staging DB",
+or `doctor` / `status` reports a missing or invalid config, follow this flow.
+
+> **Default to guiding, not running.** `init` writes credentials to disk. Only
+> execute it for the user with explicit permission and confirmed values.
+> If a `.dbcli` already contains `{"$env": "..."}` references, **do not** rerun
+> `init` to "fill them in" — the env-ref form is intentional for CI/multi-env.
+
+### Decision tree (ask before writing)
+
+1. **One DB or many environments?** One → v1 (single connection). Multiple
+   environments / tenants / replicas → v2 (`--conn-name <name>`, optionally
+   `--env-file <path>` per connection).
+2. **Where do credentials live?**
+   - Already in a `.env` (`DATABASE_URL` or `DB_HOST` / `DB_PORT` / `DB_USER` /
+     `DB_PASSWORD` / `DB_NAME` | `DB_DATABASE`) → `init` parses it automatically.
+   - Need to keep secrets out of `.dbcli` (CI/CD, multi-env) → `--use-env-refs`
+     plus `--env-host` / `--env-port` / `--env-user` / `--env-password` / `--env-database`.
+   - Plain values are acceptable → pass `--host` / `--port` / `--user` /
+     `--password` / `--name` (and `--system`).
+3. **What permission tier?** Default to the **lowest** that satisfies the task:
+   `query-only` → `read-write` → `data-admin` → `admin`. Set with `--permission`.
+4. **Verify, never assume.** After init: `dbcli status` (system + permission +
+   blacklist summary, no creds) and `dbcli doctor --format json` (env, config
+   shape, connectivity, schema-cache age, Mongo SRV path).
+
+### Per-engine essentials
+
+```bash
+# PostgreSQL / MySQL / MariaDB (v1, plain values)
+dbcli init --system postgresql --host localhost --port 5432 \
+  --user app --password '<secret>' --name appdb --permission query-only
+
+# Reuse an existing .env (DATABASE_URL=postgresql://user:pw@host:5432/db)
+dbcli init                                                # parses .env in cwd
+
+# MongoDB — full URI (Atlas / replica sets / authSource)
+dbcli init --system mongodb \
+  --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
+# MongoDB — discrete params (no auth = omit --user/--password)
+dbcli init --system mongodb --host localhost --port 27017 --name mydb
+
+# Redis — `--name` is the LOGICAL DB INDEX ("0".."15"), not a database name
+dbcli init --system redis --host localhost --port 6379 --password '<secret>' --name 0
+
+# Elasticsearch — basic auth, Cloud ID, or API key
+dbcli init --system elasticsearch --host localhost --port 9200 \
+  --user elastic --password '<secret>'
+dbcli init --system elasticsearch \
+  --cloud-id "myCluster:dXMtZWFzdC0xLmF3..." --api-key "<base64>"
+# Multi-node / custom CA / self-signed: edit `.dbcli` directly to add
+# `nodes: [...]`, `protocol: https`, `caPath`, `rejectUnauthorized: false`.
+```
+
+### Multi-connection (v2)
+
+```bash
+dbcli init --conn-name staging --env-file .env.staging --permission query-only
+dbcli init --conn-name prod    --env-file .env.production --use-env-refs --skip-test
+dbcli use --list                          # show all, * marks default
+dbcli use prod                            # switch default
+dbcli query --use staging "SELECT 1"      # one-shot override
+dbcli init --rename staging:stg           # rename
+dbcli init --remove stg                   # remove
+```
+
+Per-connection schema cache lives at `.dbcli/schemas/<connection>/`. Run
+`dbcli schema --use <name>` once per connection before `schema <table>` —
+otherwise the cache may serve another connection's columns.
+
+### env-refs (keep secrets out of `.dbcli`)
+
+```bash
+dbcli init --use-env-refs \
+  --env-host DB_HOST --env-port DB_PORT \
+  --env-user DB_USER --env-password DB_PASSWORD --env-database DB_NAME
+```
+
+Stored as `{ "$env": "DB_HOST" }` etc. and resolved at runtime. Pair with
+`--env-file <path>` (v2) when each connection has its own env file.
+
+### Common gotchas
+
+- **MongoDB `mongodb+srv://`** — `dbcli doctor` reports whether SRV resolves
+  natively or via the DoH fallback; useful when the runtime restricts DNS.
+- **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,
+  percent-encode (`@` → `%40`); discrete `--password` flags do not need encoding.
+- **Redis `--name`** — accepts only the logical DB index string; non-numeric
+  values are rejected.
+- **Elasticsearch TLS** — `caPath` and `rejectUnauthorized` are not exposed as
+  flags; edit `.dbcli` after `init` to add them.
+- **Re-running `init`** — refuses to overwrite without `--force`; never use
+  `--force` to "fix" a config full of `{ "$env": "..." }` refs.
+
+Full flags and edge cases: see [reference.md](reference.md) `init` section.
+
 ## Command overview
 
 | Command | Min permission | Summary |
@@ -34,8 +154,8 @@ 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), collections (MongoDB), keys (Redis), or indices (Elasticsearch). |
-| `schema` | query-only+ | SQL: per-table or full scan into `.dbcli/schemas/` (use `--use` for the right cache). 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`/`--index`). |
+| `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. |
@@ -43,11 +163,11 @@ dbcli query "SELECT * FROM users"   # Execute SQL (auto LIMIT 1000)
 | `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; ES has a dedicated path. |
+| `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. SQL engines + MongoDB shell only; Redis/ES not currently exposed in REPL. |
-| `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`; DROP also needs `--force`. Mongo/Redis exit with error. |
+| `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.
 
@@ -71,29 +191,27 @@ dbcli query "SELECT * FROM users"   # Execute SQL (auto LIMIT 1000)
 - JSON filter object (`find`) or JSON array (`aggregate`); SQL is rejected. `--collection <name>` is required on `query`.
 - **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, `--sample-size`); types are JS `typeof` strings — no PK/FK/index info.
-- `--limit` applies on `find`/aggregate; query-only mode caps at 1000 unless `--no-limit`.
+- 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 / `--refresh` / `--reset`, `insert`, `update`, `delete`, `export`, `check`, `diff`, `migrate`, `q`.
+- **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`, `EXPIRE`, …) → `read-write`; `DEL` / `HDEL` / `UNLINK` → `data-admin`; `KEYS`, `FLUSHDB`, `CONFIG`, `INFO`, … → `admin`. Unlisted commands are denied.
+- 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>` (or `--index <index>`) is required on `query`.
+- 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 external tooling for indexing.
-- Auth: API key (`apiKey`), Basic (`user`/`password`), or Cloud ID (`cloudId`); supports HTTPS, custom CA (`caPath`), and multi-node arrays (`nodes`).
-- Query-only mode caps at 1000 hits; `--no-limit` is bounded at 10 000 (use saved searches with `search_after` beyond that).
-- Schema flattens nested fields (`a.b.c`) and surfaces `.fields` multi-fields (e.g. `text.keyword`).
+  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

package/assets/reference.md

@@ -498,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.

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.