@carllee1983/dbcli 1.38.1 → 1.39.1

package/.cursor/rules/dbcli.mdc

@@ -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
@@ -30,6 +30,7 @@ the CLI package has not been installed globally.
 | --- | --- |
 | A named workflow fits ("diagnose slow query", "audit permissions") | `skill tasks list` → `skill tasks plan <pack>` — **prefer this; do not invent steps** |
 | A fixed diagnostic goal | `guide <goal>` (`slow-query` / `capacity` / `health` / `index-usage` / `permissions` / `schema-overview`; `guide --list`) |
+| A DB report / dashboard / HTML UI | `blacklist list` → `queries search <keywords>` or `queries suggest <intent>` → `queries show @<name>` → browser: `q @<name> --param k=v --ui`; file: `q @<name> --format html > report.html` or `export "<SQL>" --format html --output report.html` |
 | Setting up a connection | see **Connection setup** |
 | Anything else | run commands manually; consult the **Developer workflows** cheat-sheet |
 
@@ -89,6 +90,7 @@ in **How to use dbcli** still applies.
 | Situation | Minimum safe path |
 | --- | --- |
 | DB-backed feature | `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` or `--format html` |
 | Application data bug | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → narrow query |
 | ORM or migration work | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column` (preview SQL) → `diff --against <snapshot>` |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
@@ -103,6 +105,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
@@ -425,14 +432,18 @@ Run with `dbcli q @diag/<topic>` (engine variant auto-picked by the active conne
 
 ```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` implies `--format html` and opens the file; `--format html` alone prints to stdout.
-Blacklist redaction is applied **before** rendering. To get KPIs and charts instead of a plain
-table, add a `visual:` block (`title`, `kpis[]`, `charts[]`) to the snippet frontmatter — see
-reference.md for the full `visual:` schema. Raw `query` invocations render a sortable table only.
+When a saved snippet exists, prefer `q @<name> --ui` / `q @<name> --format html` because snippet
+metadata can drive titles, KPI cards, and charts. Blacklist redaction is applied **before**
+rendering. To get KPIs and charts instead of a plain table, add a `visual:` block (`title`,
+`kpis[]`, `charts[]`) to the snippet frontmatter — see reference.md for the full `visual:`
+schema. Raw `query` / `export` invocations render a sortable table only.
 
 ## Common workflows
 

package/.github/skills/dbcli/SKILL.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
@@ -30,6 +30,7 @@ the CLI package has not been installed globally.
 | --- | --- |
 | A named workflow fits ("diagnose slow query", "audit permissions") | `skill tasks list` → `skill tasks plan <pack>` — **prefer this; do not invent steps** |
 | A fixed diagnostic goal | `guide <goal>` (`slow-query` / `capacity` / `health` / `index-usage` / `permissions` / `schema-overview`; `guide --list`) |
+| A DB report / dashboard / HTML UI | `blacklist list` → `queries search <keywords>` or `queries suggest <intent>` → `queries show @<name>` → browser: `q @<name> --param k=v --ui`; file: `q @<name> --format html > report.html` or `export "<SQL>" --format html --output report.html` |
 | Setting up a connection | see **Connection setup** |
 | Anything else | run commands manually; consult the **Developer workflows** cheat-sheet |
 
@@ -89,6 +90,7 @@ in **How to use dbcli** still applies.
 | Situation | Minimum safe path |
 | --- | --- |
 | DB-backed feature | `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` or `--format html` |
 | Application data bug | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → narrow query |
 | ORM or migration work | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column` (preview SQL) → `diff --against <snapshot>` |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
@@ -103,6 +105,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
@@ -425,14 +432,18 @@ Run with `dbcli q @diag/<topic>` (engine variant auto-picked by the active conne
 
 ```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` implies `--format html` and opens the file; `--format html` alone prints to stdout.
-Blacklist redaction is applied **before** rendering. To get KPIs and charts instead of a plain
-table, add a `visual:` block (`title`, `kpis[]`, `charts[]`) to the snippet frontmatter — see
-reference.md for the full `visual:` schema. Raw `query` invocations render a sortable table only.
+When a saved snippet exists, prefer `q @<name> --ui` / `q @<name> --format html` because snippet
+metadata can drive titles, KPI cards, and charts. Blacklist redaction is applied **before**
+rendering. To get KPIs and charts instead of a plain table, add a `visual:` block (`title`,
+`kpis[]`, `charts[]`) to the snippet frontmatter — see reference.md for the full `visual:`
+schema. Raw `query` / `export` invocations render a sortable table only.
 
 ## Common workflows
 

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.39.1] - 2026-06-30 - Skill report dashboard routing
+
+### Changed
+
+- **Skill 路由補上 DB report / dashboard / HTML UI 意圖。** `assets/SKILL.md` / `assets/SKILL.zh-TW.md` 的 metadata、任務路由表、開發者速查與 HTML dashboard 範例現在明確導向 `queries search|suggest` → `queries show` → `q @<name> --ui` / `--format html`，並保留 raw SQL `export --format html` 的檔案輸出路徑。已透過 `plugin:sync` 同步到所有受管理平台副本。純文件 / skill 變更，無 CLI 行為更動。
+
+## [1.39.0] - 2026-06-24 - Dashboard chart type 解析時邊界驗證
+
+### Changed
+
+- **`--ui` dashboard chart type 改為解析時驗證。** Saved query 的 `visual.charts[].type` 現以單一合法集合 `line` / `bar` / `area` / `pie` 驗證；指定未支援的類型（含打錯字）會在解析時拋出 `SavedQueryError`（`PARSE_ERROR`），訊息列出合法清單。先前的行為是把任何未知類型**靜默畫成圓餅圖**。型別宣告中從未被渲染的 `scatter` 一併移除。
+
+### Fixed
+
+- **未知 chart type 不再靜默偽裝成圓餅圖。** dashboard 渲染端對非可渲染類型顯示明確的「Unsupported chart type」佔位，而非 fallthrough 成 `PieChart`。
+
 ## [1.38.1] - 2026-06-23 - Redis delete 能力對齊 & SKILL.md 任務路由重構
 
 ### Fixed

package/assets/SKILL.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
@@ -30,6 +30,7 @@ the CLI package has not been installed globally.
 | --- | --- |
 | A named workflow fits ("diagnose slow query", "audit permissions") | `skill tasks list` → `skill tasks plan <pack>` — **prefer this; do not invent steps** |
 | A fixed diagnostic goal | `guide <goal>` (`slow-query` / `capacity` / `health` / `index-usage` / `permissions` / `schema-overview`; `guide --list`) |
+| A DB report / dashboard / HTML UI | `blacklist list` → `queries search <keywords>` or `queries suggest <intent>` → `queries show @<name>` → browser: `q @<name> --param k=v --ui`; file: `q @<name> --format html > report.html` or `export "<SQL>" --format html --output report.html` |
 | Setting up a connection | see **Connection setup** |
 | Anything else | run commands manually; consult the **Developer workflows** cheat-sheet |
 
@@ -89,6 +90,7 @@ in **How to use dbcli** still applies.
 | Situation | Minimum safe path |
 | --- | --- |
 | DB-backed feature | `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` or `--format html` |
 | Application data bug | `audit tail --for-agent --n 10` → `blacklist list` → `schema <object>` → narrow query |
 | ORM or migration work | `schema --format json` → `diff --snapshot <name>` → `migrate add-index`/`add-column` (preview SQL) → `diff --against <snapshot>` |
 | PR database review | Review changed persistence paths, then propose concrete `schema` / `plan` / `dry-run` / `report` / `guide` commands per material claim. |
@@ -103,6 +105,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
@@ -425,14 +432,18 @@ Run with `dbcli q @diag/<topic>` (engine variant auto-picked by the active conne
 
 ```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` implies `--format html` and opens the file; `--format html` alone prints to stdout.
-Blacklist redaction is applied **before** rendering. To get KPIs and charts instead of a plain
-table, add a `visual:` block (`title`, `kpis[]`, `charts[]`) to the snippet frontmatter — see
-reference.md for the full `visual:` schema. Raw `query` invocations render a sortable table only.
+When a saved snippet exists, prefer `q @<name> --ui` / `q @<name> --format html` because snippet
+metadata can drive titles, KPI cards, and charts. Blacklist redaction is applied **before**
+rendering. To get KPIs and charts instead of a plain table, add a `visual:` block (`title`,
+`kpis[]`, `charts[]`) to the snippet frontmatter — see reference.md for the full `visual:`
+schema. Raw `query` / `export` invocations render a sortable table only.
 
 ## Common workflows
 

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
@@ -25,6 +25,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 +66,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 +79,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
@@ -329,11 +336,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。
 
 ## 常見工作流程