@carllee1983/dbcli 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.18.0] - 2026-05-11
+
+### Added
+
+- **Interactive HTML Dashboards**: `query`, `q`, and `export` can now render results as fully interactive, standalone HTML reports.
+- New `--ui` flag to open dashboards directly in the system browser.
+- New `html` format for `stdout` and file-based report generation.
+- Snippet `visual:` block in frontmatter for KPI and chart configuration (Line, Bar, Area, Pie, Scatter).
+- Secure payload injection with automatic HTML escaping and blacklist redaction.
+- Bundled React + Recharts + Tailwind UI template for zero-dependency portability.
+
 ## [1.17.0] - 2026-05-10
 
 ### Added

package/README.md

@@ -133,6 +133,25 @@ The planner is cache-first (no network); add `--probe` to refresh the
 underlying inspect context. Use `--list` to see all goals,
 `--format markdown` for human reading, or `--for-agent` for compact JSON.
 
+### Interactive HTML Dashboards
+
+```bash
+# Open results in browser
+dbcli query "SELECT * FROM orders" --ui
+
+# Run a saved snippet with visualization metadata
+dbcli q @analytics/revenue --ui
+
+# Export query results as a standalone HTML file
+dbcli export "SELECT * FROM users" --format html --output report.html
+```
+
+`dbcli` can render query results as fully interactive, standalone HTML dashboards. These reports are powered by React + Recharts and are zero-dependency — the entire application and data are inlined into a single HTML file.
+
+- **`--ui` flag**: Automatically generates a temporary report and opens it in your default browser.
+- **`visual:` block**: Snippet frontmatter can define KPIs and charts (Line, Bar, Area, Pie, Scatter) to drive the dashboard.
+- **Security**: Result sets are redacted by the blacklist before injection, and data is safely escaped for HTML.
+
 ### Recovery & Guided Remediation
 
 ```bash

package/README.zh-TW.md

@@ -118,6 +118,25 @@ dbcli query '{"status":"active"}' --collection users --use atlas
 
 對 MongoDB 而言，`list` 與 `query` 會使用該連線設定中的資料庫；`query` 也必須指定 `--collection <名稱>`。
 
+### 互動式 HTML 儀表板 (Interactive HTML Dashboards)
+
+```bash
+# 在瀏覽器中開啟查詢結果
+dbcli query "SELECT * FROM orders" --ui
+
+# 執行具備視覺化中繼資料的片段
+dbcli q @analytics/revenue --ui
+
+# 將結果匯出為獨立的 HTML 檔案
+dbcli export "SELECT * FROM users" --format html --output report.html
+```
+
+`dbcli` 可將查詢結果算繪為完全互動、獨立的 HTML 儀表板。這些報表由 React + Recharts 驅動且具備「零依賴」特性 — 整個應用程式與資料皆被內嵌於單一 HTML 檔案中。
+
+- **`--ui` 旗標**：自動產生暫時性報表並在預設瀏覽器中開啟。
+- **`visual:` 區塊**：可在查詢片段的 frontmatter 中定義 KPI 與圖表 (Line, Bar, Area, Pie, Scatter)。
+- **安全性**：資料在注入前會先經過黑名單過濾，且針對 HTML 進行了安全跳脫處理。
+
 ---
 
 ## 多重連線支援 (v2)

package/assets/SKILL.md

@@ -188,13 +188,13 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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/`. MongoDB: sampled. ES: flattened mapping. Redis: per-key only (type/TTL/size). Supports `--recovery`. |
-| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). Supports `--recovery`. |
+| `query` | query-only+ | SQL, Mongo JSON (`--collection`), Redis command, or ES DSL/Lucene (`--collection`). `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard in a browser. Supports `--recovery`. |
 | `plan` | n/a | Static SQL risk analyzer (`--format text\|json`); classifies a statement without connecting to the database. |
-| `q` | query-only+ | Run a saved snippet by `@name` with `--param k=v`. SQL / Elasticsearch DSL / read-only Redis bodies; blacklist enforced. Supports `--recovery`. |
+| `q` | query-only+ | Run a saved snippet by `@name` with `--param k=v`. SQL / Elasticsearch DSL / read-only Redis bodies; blacklist enforced. `--format table\|json\|csv\|html`, `--ui` to open the interactive dashboard. Supports `--recovery`. |
 | `queries` | n/a | Manage saved snippets: `list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`. |
 | `insert` / `update` | read-write+ | SQL or MongoDB only. JSON `--data` / `--set`; `--where` required on `update`; `--dry-run` first. Redis writes go through `query`. Supports `--recovery`. |
 | `delete` | data-admin+ | SQL or MongoDB only. `--where` required; `--dry-run` first. Supports `--recovery`. |
-| `export` | query-only+ | SQL or MongoDB only. Query → CSV/JSON(L) file or stdout. Supports `--recovery`. |
+| `export` | query-only+ | SQL or MongoDB only. Query → `--format json\|jsonl\|csv\|html` file or stdout. `html` emits a standalone interactive dashboard. Supports `--recovery`. |
 | `blacklist` | n/a | `list` / `table` / `column` subcommands redact sensitive data from query results. |
 | `check` | query-only+ | SQL only (best on MySQL/MariaDB). |
 | `diff` | query-only+ | SQL only. Save/compare schema snapshots. |
@@ -285,8 +285,9 @@ Manage local snippets with `queries new | edit | delete | rename | copy | import
 local layer for editing.
 
 Each `.sql` file may declare YAML frontmatter inside `-- ---` blocks
-(name, description, engine, params, tags). See `dbcli queries show @<name> --format json`
-for the machine-readable contract.
+(name, description, engine, params, tags, optional `intent`, optional `visual`).
+The `visual:` block drives the interactive dashboard (see "Interactive HTML dashboard"
+below). See `dbcli queries show @<name> --format json` for the machine-readable contract.
 
 ### Engine-specific bodies
 
@@ -321,6 +322,58 @@ Engine variants are picked automatically based on the active connection.
 Override any of them by placing a same-named file under `.dbcli-shared/queries/`
 or `.dbcli/queries/`.
 
+## Interactive HTML dashboard
+
+`query`, `q`, and `export` can render results as a standalone, self-contained HTML
+report powered by a bundled React + Recharts template (`assets/ui-template.html`,
+injected via a hardened `window.__DBCLI_PAYLOAD__ = {...}` block — `<` is escaped
+to neutralise `</script>` payloads).
+
+```bash
+# Open in browser (writes to a temp file, then `open`/`xdg-open`/`start`)
+dbcli query "SELECT day, dau FROM dau_daily" --ui
+dbcli q @analytics/revenue --param days=30 --ui
+
+# Pipe HTML to stdout (CI artifacts, email, static hosting)
+dbcli query "SELECT * FROM orders" --format html > orders.html
+
+# Export to a file (interchangeable with json/jsonl/csv)
+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 — the dashboard never
+sees masked columns.
+
+### Snippet `visual:` block
+
+To get KPIs and charts (rather than just a sortable table), add a `visual:` block
+to the snippet's frontmatter. Column names must exist in the result row.
+
+```sql
+-- ---
+-- name: Revenue Trend
+-- engine: postgres
+-- params:
+--   days: { type: int, default: 30 }
+-- visual:
+--   title: Revenue (last :days days)
+--   kpis:
+--     - { label: Total Revenue,  value_column: total_revenue, format: currency }
+--     - { label: Orders,         value_column: order_count,   format: number   }
+--     - { label: Conversion,     value_column: conv_rate,     format: percent  }
+--   charts:
+--     - { type: line, title: Daily Revenue, x: day, y: [revenue] }
+--     - { type: bar,  title: By Channel,    x: channel, y: [revenue, refunds] }
+-- ---
+SELECT ...
+```
+
+- `kpis[].format`: `currency` / `number` / `percent` (omit for raw value).
+- `charts[].type`: `line` / `bar` / `area` / `pie` / `scatter`.
+- Raw `query` invocations (no snippet) render a sortable/filterable table only —
+  there is no `visual:` to attach.
+
 ## Common workflows
 
 - **Debug odd state:** `schema` → `check` → `query` with tight `WHERE` → follow FKs from schema JSON. Evidence over theory.

package/assets/reference.md

@@ -135,9 +135,13 @@ 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
+
+# Interactive HTML dashboard (see "Interactive HTML dashboard" below)
+dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in browser
+dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**Options:** `--format <table|json|csv>`, `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`)
+**Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
 > **MongoDB notes:**
@@ -156,6 +160,31 @@ dbcli query 'status:active AND amount:>100' --index orders --limit 50
 > - 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).
 
+### plan
+
+Static SQL risk analyzer. Classifies a statement into the same permission tiers
+used by `query` (`query-only` / `read-write` / `data-admin` / `admin`) and lists
+the underlying signals (DML / DDL / multi-statement / unsafe constructs) without
+ever connecting to the database.
+
+```bash
+dbcli plan "SELECT * FROM users"
+dbcli plan "UPDATE users SET name='x'"           # human-readable text classification
+dbcli plan "DROP TABLE users" --format json      # machine-readable risk report
+```
+
+**Options:** `--format <text|json>` (default `text`).
+**Permission:** n/a (offline analyzer; no connection opened).
+
+Use cases:
+- Agents that want to decide whether to call `query` vs `insert` / `update` /
+  `delete` before sending SQL.
+- Pre-flight safety check before binding parameters into a saved snippet.
+- Lint hook for code review pipelines that store SQL in source.
+
+`plan` does not enforce blacklist or auto-`LIMIT`; those still apply when the
+SQL is actually executed via `query` / `q`.
+
 ### 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):
@@ -172,15 +201,19 @@ dbcli q @dau --param days=30 --format json    # override a param
 dbcli q @analytics/revenue --param-file params.json
 dbcli q @dau --dry-run                        # show final SQL + bind values
 dbcli q @dau --no-limit                       # disable size guard wrap
+dbcli q @analytics/revenue --param days=30 --ui                       # open dashboard
+dbcli q @analytics/revenue --param days=30 --format html > report.html
 ```
 
 **Options:**
-- `--format <table|json|csv>` — output format (default: `table`)
+- `--format <table|json|csv|html>` — output format (default: `table`)
+- `--ui` — open the rendered HTML dashboard in the system browser (implies `--format html`; writes to a temp file then invokes `open` / `xdg-open` / `start`)
 - `--param <key=value>` — pass a parameter (repeatable)
 - `--param-file <path>` — JSON object whose keys are param names
 - `--no-limit` — skip the `SELECT * FROM (…) AS _dbcli_guard LIMIT 1000` wrap
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
+- `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
 
 **Permission:** query-only+
 
@@ -201,6 +234,13 @@ Each `.sql` file is plain SQL with optional YAML frontmatter inside a leading `-
 --     description: lookback window in days
 --     enum: [7, 30, 90]
 -- tags: [analytics]
+-- intent: perf.slow-query   # optional; consumed by `queries suggest`
+-- visual:                   # optional; consumed by `--ui` / `--format html`
+--   title: Daily Active Users
+--   kpis:
+--     - { label: DAU, value_column: dau, format: number }
+--   charts:
+--     - { type: line, title: DAU trend, x: day, y: [dau] }
 -- ---
 SELECT COUNT(DISTINCT user_id) AS dau
 FROM events
@@ -209,6 +249,8 @@ WHERE created_at > NOW() - (:days || ' days')::interval;
 
 Param placeholders use `:name`. They are rewritten to `$1, $2, …` (Postgres) or `?, ?, …` (MySQL) at execution time and passed as bind values — string interpolation is never used.
 
+The `visual:` block is documented in detail under [Interactive HTML dashboard](#interactive-html-dashboard) below. Unknown / malformed fields are silently dropped at parse time; the snippet still runs and the dashboard falls back to a sortable table.
+
 #### Param type coercion
 
 | Declared `type` | Accepts |
@@ -299,6 +341,10 @@ dbcli queries list --tag analytics --engine postgres --format json
 dbcli queries list --source local       # only personal overrides
 dbcli queries show @dau                 # frontmatter + SQL
 dbcli queries show @dau --format json   # MCP-shaped contract
+dbcli queries search slow query         # fuzzy-ranked keyword search across snippets
+dbcli queries search cache --engine postgres --source builtin --limit 5
+dbcli queries suggest perf              # browse snippets by intent prefix (v1.11+)
+dbcli queries suggest perf.cache-hit --format json
 
 # Authoring
 dbcli queries new @new/sample           # scaffold under .dbcli-shared/queries/
@@ -319,8 +365,10 @@ dbcli queries export @dau --output dau.sql          # write snippet body to a fi
 dbcli queries export @diag/connections --engine postgres  # pick a variant when multiple engines exist
 ```
 
-**`list` options:** `--format <table|json|csv>`, `--tag <tag>`, `--engine <postgres|mysql>`, `--source <local|shared>`
+**`list` options:** `--format <table|json|csv>`, `--tag <tag>`, `--engine <postgres|mysql|redis|elasticsearch|all>`, `--source <local|shared|builtin|all>`
 **`show` options:** `--format <table|json|csv>`
+**`search` options:** `--format <table|json>`, `--engine <postgres|mysql|redis|elasticsearch|all>`, `--source <local|shared|builtin|all>`, `--limit <n>` (default 10), `--include-internal` (show fuzzy ranking score). Keyword(s) are fuzzy-matched against name, description, tags, intent.
+**`suggest` options:** `--format <table|json>`, `--engine <postgres|mysql|redis|elasticsearch|all>`, `--source <local|shared|builtin|all>`. Intent prefix-matched against the snippet's `intent` frontmatter field. Common intents: `perf.slow-query`, `perf.cache-hit`, `capacity.size`, `safety.connections`, `monitor.cluster-health`.
 **`new` options:** `--local`, `--edit`
 **`edit` options:** `--shared`
 **`check` options:** `--strict`, `--format <table|json|csv>`
@@ -378,11 +426,15 @@ Export query results to file or stdout.
 dbcli export "SELECT * FROM users" --format csv --output users.csv
 dbcli export "SELECT * FROM users" --format csv --output users.csv --force  # Skip overwrite confirmation
 dbcli export "SELECT * FROM users" --format json | jq '.[]'
+dbcli export "SELECT * FROM users" --format jsonl --output users.ndjson
+dbcli export "SELECT * FROM orders" --format html --output orders.html      # standalone dashboard
 ```
 
-**Options:** `--format <json|csv>` (required), `--output <path>`, `--force`
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`
 **Permission:** query-only+
 
+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.
+
 ### blacklist
 
 Manage sensitive data blacklist to prevent AI access to restricted tables/columns.
@@ -850,6 +902,32 @@ 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
+
+Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or one of
+four AI-agent platform directories. The skill is the source of truth that lets
+Claude Code / Gemini / Copilot / Cursor know how to drive dbcli safely.
+
+```bash
+dbcli skill                                  # print SKILL.md to stdout
+dbcli skill --output ./SKILL.md              # write to a file (no platform install)
+dbcli skill --install claude                 # install to ~/.claude/skills/dbcli/
+dbcli skill --install gemini                 # install to ~/.gemini/skills/dbcli/
+dbcli skill --install copilot                # install to .github/skills/dbcli/ (repo-local)
+dbcli skill --install cursor                 # install to .cursor/skills/dbcli/ (repo-local)
+```
+
+**Options:**
+- `--install <platform>` — `claude` | `gemini` | `copilot` | `cursor`. 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`.
+
+**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.
+- `claude` / `gemini` install paths are user-global; `copilot` / `cursor` are repo-local under `.github/` / `.cursor/`.
+- Re-running `--install` overwrites the existing skill atomically; no prompt.
+
+**Permission:** n/a.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -877,6 +955,108 @@ Task storage layers:
 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`).
 
+## Interactive HTML dashboard
+
+`query`, `q`, and `export` can render results as a single, fully self-contained
+HTML file backed by a bundled React + Recharts template. The template lives at
+`assets/ui-template.html` and is installed alongside the binary; no external
+network, CDN, or runtime is required to view the report.
+
+### Entry points
+
+| Command form | Behaviour |
+|--------------|-----------|
+| `dbcli query "<sql>" --ui` | Render to a temp file under `$TMPDIR/dbcli-query-<ts>.html` and open with `open` / `xdg-open` / `start`. |
+| `dbcli q @<name> --ui` | Same, with snippet metadata (`name`, `description`, `visual:` block). |
+| `dbcli query "<sql>" --format html` | Print HTML to stdout (pipe, redirect, attach). |
+| `dbcli q @<name> --format html` | Same, snippet-aware. |
+| `dbcli export "<sql>" --format html --output report.html` | Write HTML to an explicit path; respects `--force` / overwrite confirmation. |
+
+`--ui` is a convenience flag — it implies `--format html` and then opens the
+file. `--ui` and `--format` are mutually compatible; passing both is allowed and
+behaves as `--ui`.
+
+### Data injection contract
+
+The template ships with a single placeholder, `/*DBCLI_PAYLOAD*/`, which dbcli
+replaces with:
+
+```js
+window.__DBCLI_PAYLOAD__ = { "meta": {...}, "rows": [...] };
+```
+
+Hardening rules applied before injection:
+
+- Payload is `JSON.stringify(...)`-encoded.
+- Every `<` is replaced with `<` so a malicious row containing `</script>`
+  cannot terminate the inline script tag.
+- Blacklist redaction (`dbcli blacklist`) runs **before** the formatter — masked
+  columns never reach the dashboard.
+- The replacement uses a function callback (`html.replace(..., () => injection)`)
+  so `$&`-style backreferences in the payload are not interpreted.
+
+### `meta` shape
+
+`meta` is the `SavedQueryMeta` object (see `dbcli queries show @<name> --format json`):
+
+```jsonc
+{
+  "name": "Revenue Trend",        // display title
+  "key":  "@analytics/revenue",   // snippet key, or "raw-sql" / "export"
+  "description": "...",           // free text (SQL preview for raw query)
+  "params": [...],                // ParamSpec[]
+  "tags":   ["analytics"],
+  "intent": "perf.slow-query",
+  "visual": { ... }               // optional, see below
+}
+```
+
+For raw `query` / `export` invocations, `meta.params` is `[]` and
+`meta.visual` is absent — the dashboard renders a sortable / filterable table.
+
+### `visual:` block (snippet frontmatter)
+
+```yaml
+visual:
+  title: Revenue (last :days days)   # optional override of meta.name
+  kpis:
+    - label: Total Revenue
+      value_column: total_revenue    # must exist in result rows
+      format: currency               # currency | number | percent (optional)
+    - label: Orders
+      value_column: order_count
+      format: number
+  charts:
+    - type: line                     # line | bar | area | pie | scatter
+      title: Daily Revenue
+      x: day                         # column for X axis
+      y: [revenue]                   # 1..N columns for series
+    - type: bar
+      title: By Channel
+      x: channel
+      y: [revenue, refunds]
+```
+
+Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
+
+- The block is **optional**. Missing → table-only render.
+- Items missing required fields (`kpi.label` + `kpi.value_column`, or
+  `chart.type` + `chart.x` + `chart.y[]`) are silently dropped.
+- Unknown `format` / `type` values are forwarded as strings; the dashboard
+  decides how to render them (unknown chart types fall back gracefully).
+- The snippet still executes as a normal SQL/DSL query — `visual:` only affects
+  the HTML renderer.
+
+### Limitations
+
+- The dashboard is read-only; there is no in-page editor or re-run button.
+- Raw `query` / `export` HTML output never shows KPIs or charts (no snippet
+  metadata is available). Use `dbcli q @<name>` for the charted view.
+- Engine support follows the underlying command: SQL, MongoDB (`--collection`),
+  Redis, and Elasticsearch (`--collection`) all render through the same template.
+- Very wide / very long result sets render as a single client-side table; for
+  >10k rows prefer `--format csv` / `--format jsonl` and a downstream tool.
+
 ## 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.