@carllee1983/dbcli 1.30.0 → 1.32.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.32.0] - 2026-06-18 - Agent Task Packs Expansion & Skill Parity Guards
+
+### Added
+
+- **4 個新的內建 Agent Task Pack（皆 `plan-only` 唯讀）。** `audit-permissions`（權限等級與 blacklist 覆蓋稽核）、`safe-backfill`（在寫入前做 blacklist + schema + 風險檢查的回填計畫）、`schema-drift-review`（快取/committed schema 與線上 schema 的漂移比對）、`connection-health`（連線可達性 / 設定 / 容量分級三步診斷）。皆走確定存在的唯讀指令;用 `dbcli skill tasks list` 瀏覽完整清單。
+- **平台清單 parity 檢查（`scripts/check-platform-parity.ts`，`bun run platform:check`）。** 以 `SUPPORTED_PLATFORMS` 為單一真實來源，驗證 README、SKILL.md、SKILL.zh-TW.md、reference.md 與 CLI `--install` 選項描述的平台列舉完全一致（缺項或多項皆報錯），並掛進 `release-check.sh`。
+- **語意 parity 守門。** `scripts/check-skill-parity.ts` 在結構比對外，新增 14 個語言不變的安全/命令 token（`query`/`insert`/`update`/`delete`/`export`/`schema`、`blacklist`、`--dry-run`/`--no-limit`/`--recovery`、`LIMIT 1000`、三個權限等級）在 EN 與 zh-TW 皆須對稱出現的檢查。
+- **安裝與 context CLI 測試覆蓋。** 新增 `skill --install` 對 7 個平台寫入 temp HOME/cwd 的 smoke 測試（含 cursor/windsurf 的 root-rule + reference 雙檔結構），以及 `skill context` 的 xml/json/markdown、預設格式、無效格式與 blacklist 不外洩的 CLI 入口測試。
+
+### Fixed
+
+- **`codex` / `windsurf` 安裝目標文件漂移。** 兩者已存在於 `SUPPORTED_PLATFORMS`（`--install` 實際可用），卻在 `SKILL.md` / `SKILL.zh-TW.md` 缺漏、`windsurf` 在 README 缺漏。已補齊並重新同步所有 plugin/skill 副本;新的 `platform:check` 會防止再次漂移。
+
+## [1.31.0] - 2026-06-10 - Data Editing Surface & Agent Plugin Packaging
+
+### Added
+
+- **`@carllee1983/dbcli/core` 公開匯出 `DataExecutor` 與資料執行型別。** 在 `./core` barrel 開出資料編輯介面（insert/update/delete 執行面），讓外部消費者（如 `dbcli-gui` sidecar）能重用與 CLI 同源的資料寫入能力，不必重寫 adapter 邏輯。CLI 行為不變。
+- **Agent plugin 打包與 marketplace 安裝。** 將 dbcli 打包為 agent plugin（Ponytail 風格 marketplace install），新增 GitHub Copilot CLI plugin 支援與 Cursor plugin 安裝（add-plugin metadata、marketplace 提交路徑），並依各 agent 拆分安裝指令與文件。
+- **開發者工作流 skill 指引（en/zh-TW）。** 在 dbcli skill 新增「Developer workflows」段落，把資料庫影響隱含於開發任務時的最小安全路徑（DB-backed 功能、資料錯誤排查、ORM/migration、PR 審查、慢查詢、回填、環境驗證）寫入 SKILL en/zh-TW 與各平台副本，並以可執行的指令錨點取代不可執行的 migrate 範例。
+
+## [1.30.0] - 2026-06-09 - Connection Writer API
+
+### Added
+
+- **`@carllee1983/dbcli/core` 新增連線寫入 API。** 在 `./core` barrel 公開純函式 mutation：`upsertConnection`、`removeConnection`（含預設連線重指派與 last-connection 防護）、`setDefaultConnection`、`migrateV1ToV2`（保留 legacy `.env.local` 密碼）、`writeConnectionSecret` + `envVarNameFor`（per-connection env 命名空間）。讓外部消費者（如 `dbcli-gui` sidecar）能程式化管理 `.dbcli` v2 連線，與 CLI 同源。CLI 行為不變。
+
+### Fixed
+
+- **`writeV2Config` 改為 atomic temp+rename 寫入**，避免寫入中斷時破壞設定庫。
+- **`migrateV1ToV2` 對非 SQL 的 v1 連線 fail-loud 拒絕**，防止把不相容連線寫進 v2 設定庫。
+
 ## [1.29.0] - 2026-06-08 - Core Config-Read Entrypoint
 
 ### Added

package/README.md

@@ -634,6 +634,8 @@ dbcli skill --install gemini          # Install to Gemini CLI (being phased out)
 dbcli skill --install antigravity     # Install to Antigravity CLI (Gemini CLI's successor)
 dbcli skill --install copilot         # Install to GitHub Copilot
 dbcli skill --install cursor          # Install to Cursor IDE
+dbcli skill --install codex           # Install to Codex skills
+dbcli skill --install windsurf        # Install to Windsurf (.windsurfrules)
 ```
 
 **Behavior:**
@@ -657,7 +659,8 @@ dbcli skill --install claude && \
 dbcli skill --install gemini && \
 dbcli skill --install antigravity && \
 dbcli skill --install copilot && \
-dbcli skill --install cursor
+dbcli skill --install cursor && \
+dbcli skill --install codex
 ```
 
 ---
@@ -1231,8 +1234,20 @@ dbcli skill --install gemini
 # GitHub Copilot CLI
 dbcli skill --install copilot
 
+# GitHub Copilot CLI plugin marketplace
+#   copilot plugin marketplace add CarlLee1983/dbcli
+#   copilot plugin install dbcli-agent@dbcli-agent
+
 # Cursor IDE (AI-native editor)
 dbcli skill --install cursor
+
+# Cursor plugin marketplace
+#   /add-plugin dbcli-agent
+
+# Codex plugin marketplace
+#   codex plugin marketplace add CarlLee1983/dbcli
+# Then open /plugins and install dbcli-agent.
+# Full install guide: plugins/dbcli-agent/INSTALL.md
 ```
 
 After installation, the AI agent will have access to dbcli commands and can use them to query, insert, update, or export data based on your permission level.
@@ -1285,6 +1300,22 @@ After installation, the AI agent will have access to dbcli commands and can use
 
 **Skill location:** `.cursor/rules/dbcli.mdc` (summary + workflows) and `.cursor/skills/dbcli/reference.md` (full command flags and examples) under the **current working directory** when you run `dbcli skill --install cursor`.
 
+**Cursor plugin install:** in Cursor Agent chat, run `/add-plugin dbcli-agent`, or see `plugins/dbcli-agent/INSTALL.md#cursor` for marketplace and fallback options.
+
+---
+
+#### Codex
+
+1. Add the marketplace: `codex plugin marketplace add CarlLee1983/dbcli`.
+2. Open `/plugins`, select the dbcli Agent marketplace, and install `dbcli-agent`.
+3. For a persistent CLI, install dbcli globally: `bun install -g @carllee1983/dbcli` or `npm install -g @carllee1983/dbcli`.
+4. Without a global install, the plugin skill uses `bunx @carllee1983/dbcli <command>` as its fallback.
+5. Initialize: `dbcli init` or `bunx @carllee1983/dbcli init`.
+
+**Plugin skill location:** `skills/dbcli/` (SKILL.md + reference.md).
+
+**Install guide:** `plugins/dbcli-agent/INSTALL.md`.
+
 ---
 
 ### Example: AI Agent Workflow

package/README.zh-TW.md

@@ -532,6 +532,7 @@ dbcli skill --install gemini          # 安裝至 Gemini CLI（即將淘汰）
 dbcli skill --install antigravity     # 安裝至 Antigravity CLI（Gemini CLI 後繼者）
 dbcli skill --install copilot         # 安裝至 GitHub Copilot
 dbcli skill --install cursor          # 安裝至 Cursor IDE
+dbcli skill --install codex           # 安裝至 Codex skills
 ```
 
 **行為：**
@@ -555,7 +556,8 @@ dbcli skill --install claude && \
 dbcli skill --install gemini && \
 dbcli skill --install antigravity && \
 dbcli skill --install copilot && \
-dbcli skill --install cursor
+dbcli skill --install cursor && \
+dbcli skill --install codex
 ```
 
 ---
@@ -1127,8 +1129,20 @@ dbcli skill --install gemini
 # GitHub Copilot CLI
 dbcli skill --install copilot
 
+# GitHub Copilot CLI plugin marketplace
+#   copilot plugin marketplace add CarlLee1983/dbcli
+#   copilot plugin install dbcli-agent@dbcli-agent
+
 # Cursor IDE
 dbcli skill --install cursor
+
+# Cursor plugin marketplace
+#   /add-plugin dbcli-agent
+
+# Codex plugin marketplace
+#   codex plugin marketplace add CarlLee1983/dbcli
+# 接著開啟 /plugins 並安裝 dbcli-agent。
+# 完整安裝說明：plugins/dbcli-agent/INSTALL.md
 ```
 
 安裝後，AI 可依你的權限等級使用 dbcli 查詢、插入、更新或匯出資料。
@@ -1181,6 +1195,22 @@ dbcli skill --install cursor
 
 **Skill 路徑：** 在**目前工作目錄**執行 `dbcli skill --install cursor` 時，寫入 **`.cursor/rules/dbcli.mdc`**（摘要與工作流程）及 **`.cursor/skills/dbcli/reference.md`**（完整旗標與範例）。
 
+**Cursor plugin 安裝：** 在 Cursor Agent chat 執行 `/add-plugin dbcli-agent`，或參考 `plugins/dbcli-agent/INSTALL.md#cursor` 的 marketplace 與 fallback 說明。
+
+---
+
+#### Codex
+
+1. 加入 marketplace：`codex plugin marketplace add CarlLee1983/dbcli`。
+2. 開啟 `/plugins`，選擇 dbcli Agent marketplace，並安裝 `dbcli-agent`。
+3. 若要常駐 CLI，請全域安裝 dbcli：`bun install -g @carllee1983/dbcli` 或 `npm install -g @carllee1983/dbcli`。
+4. 若未全域安裝，plugin 內的 skill 會以 `bunx @carllee1983/dbcli <command>` 作為 fallback。
+5. 初始化：`dbcli init` 或 `bunx @carllee1983/dbcli init`。
+
+**Plugin skill 路徑：** `skills/dbcli/`（`SKILL.md` + `reference.md`）。
+
+**安裝說明：** `plugins/dbcli-agent/INSTALL.md`。
+
 ---
 
 ### 範例：AI 代理工作流程

package/assets/SKILL.md

@@ -7,6 +7,11 @@ description: Database CLI for AI agents with permission-based access control. Us
 
 Database CLI for AI agents with permission-based access control.
 
+If the `dbcli` executable is not available in `PATH`, use
+`bunx @carllee1983/dbcli <command>` as the command prefix. This is the expected
+fallback for Codex plugin installs where the skill is installed by the plugin but
+the CLI package has not been installed globally.
+
 ## AI agent workflow (follow in order)
 
 0. `dbcli skill context --format xml` — LLM prompt context payload: serializes connection metadata, schema caches, and saved queries into a compressed XML/JSON structure for prompt injection.
@@ -74,11 +79,64 @@ Builtin packs: `diagnose-slow-query` and **(v1.23)** `analyze-table-perf` — a
 read-only `plan-only` pack taking a required `table` parameter that walks
 `blacklist list` → `schema <table> --format json` → `guide index-usage`. `dbcli
 inspect` suggests `analyze-table-perf` automatically for the hottest table in
-recent audit activity.
+recent audit activity. Additional read-only packs: `audit-permissions`,
+`safe-backfill`, `schema-drift-review`, `connection-health` — run
+`dbcli skill tasks list` for the full set.
 
 Tasks live under `assets/tasks/` (builtin), `.dbcli-shared/tasks/` (shared), and
 `.dbcli/tasks/` (local override).
 
+## Developer workflows
+
+Use these workflows when database impact is implicit in a development task. Keep
+the normal dbcli safety rules: prefer `--format json`, run `blacklist list`
+before touching sensitive data, confirm names with `schema`, dry-run writes, and
+use `--recovery` / `recover` after failures.
+
+| Situation | Use dbcli for | Minimum safe path |
+| --- | --- | --- |
+| DB-backed feature | Map product/code terms to real objects before editing code. | `inspect --for-agent` -> `blacklist list` -> `schema <object>` -> `queries suggest <intent>` |
+| Application data bug | Separate stored facts from application-code inference. | `inspect --for-agent` -> `audit tail --for-agent --n 10` -> `blacklist list` -> `schema <object>` -> narrow query/snippet |
+| ORM or migration work | Ground model and migration edits in live schema evidence. | `schema --format json` -> `diff --snapshot <name>` -> generate DDL via `migrate add-index`/`add-column` (preview SQL) -> `diff --against <snapshot>` |
+| PR database review | Check query, write, migration, export, fixture, and blacklist risk. | Review changed persistence paths, then propose concrete `schema`, `plan`, `dry-run`, `report`, or `guide` commands for each material claim. |
+| Slow endpoint or query | Prefer read-only diagnostics before index proposals. | `report --section perf` -> task pack `analyze-table-perf` -> `guide missing-index-for "<query>"`; use `proxy analyze` when logs exist. |
+| Safe data backfill | Scope affected rows and preview mutations before execution. | `blacklist list` -> `schema <object>` -> count/scope query -> `update ... --dry-run` -> read-back or snippet `--verify`. |
+| Environment validation | Check config shape and connectivity without leaking secrets. | `status --format json` -> `doctor --format json` -> `inspect --for-agent --no-connect --format json`. |
+
+Copy-paste command anchors:
+
+```bash
+dbcli inspect --for-agent --format json
+dbcli blacklist list --format json
+dbcli schema <object> --format json
+dbcli queries suggest <intent> --format json
+dbcli audit tail --for-agent --n 10
+dbcli schema --format json
+dbcli diff --snapshot <name>
+dbcli migrate add-index <table>
+dbcli diff --against <snapshot>
+dbcli report --section perf --format json
+dbcli skill tasks plan analyze-table-perf --param table=<table> --format json
+dbcli guide missing-index-for "<query>" --format json
+dbcli proxy analyze --format json
+dbcli query "<count/scope query>" --format json
+dbcli update <object> --where "<bounded predicate>" --set '<json>' --dry-run --format json
+dbcli status --format json
+dbcli doctor --format json
+dbcli inspect --for-agent --no-connect --format json
+```
+
+Developer workflow guardrails:
+
+- Never invent table, collection, key, index, or field names. Confirm them with
+  `schema` before writing code that depends on them.
+- Separate database facts from application-code inference. Report which dbcli
+  output shaped the code or review conclusion.
+- For writes and backfills, include scope count, dry-run preview, execution
+  command, and read-back or snippet verification.
+- Do not create indexes directly from a performance suggestion; turn them into reviewed migrations.
+- Do not print credentials, copied connection strings, or blacklisted values.
+
 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).
 
 ## Audit Log usage
@@ -263,7 +321,7 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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, and Redis (single-line; `.no-limit on/off`). **(v1.22)** Elasticsearch opens a Kibana Dev Tools-style REPL (`<METHOD> /<path>` + optional JSON body, blank line submits). |
-| `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for LLM prompt context payload. |
+| `skill` | n/a | Generate / install AI skill docs (`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`); `skill tasks list/show/plan` for Agent Task Packs; `skill context` for LLM prompt context payload. |
 | `migrate` | admin | SQL only. **DDL; dry-run by default** — needs `--execute`. |
 
 `--use <name>` on any subcommand targets a v2 connection without changing the default.

package/assets/SKILL.zh-TW.md

@@ -68,8 +68,57 @@ dbcli skill tasks plan <task> --param key=value --format json     # 產生計畫
 
 計畫輸出是一組附帶說明與風險標籤的 dbcli 指令序列。請逐一執行 — 任務計畫**不會**繞過 blacklist、schema、dry-run 或確認等要求。
 
+內建套件:`diagnose-slow-query` 與 **(v1.23)** `analyze-table-perf` — 後者是 read-only 的 `plan-only` 套件,需帶入必填的 `table` 參數,依序執行 `blacklist list` → `schema <table> --format json` → `guide index-usage`。`dbcli inspect` 會針對近期 audit 活動中最熱門的資料表自動建議 `analyze-table-perf`。其他唯讀套件:`audit-permissions`、`safe-backfill`、`schema-drift-review`、`connection-health` — 用 `dbcli skill tasks list` 瀏覽完整清單。
+
 任務檔放在 `assets/tasks/`(內建)、`.dbcli-shared/tasks/`(共享)與 `.dbcli/tasks/`(本地覆寫)。
 
+## 開發者工作流
+
+當資料庫影響隱含在開發任務中時使用這些流程。保留一般 dbcli 安全規則：優先使用 `--format json`，碰觸敏感資料前先跑 `blacklist list`，用 `schema` 確認名稱，寫入先 dry-run，失敗後使用 `--recovery` / `recover`。
+
+| 情境 | 使用 dbcli 的目的 | 最小安全路徑 |
+| --- | --- | --- |
+| DB-backed 功能 | 編輯程式碼前先把產品/程式語彙對應到真實資料物件。 | `inspect --for-agent` -> `blacklist list` -> `schema <object>` -> `queries suggest <intent>` |
+| 應用程式資料錯誤 | 分離資料庫事實與應用程式推論。 | `inspect --for-agent` -> `audit tail --for-agent --n 10` -> `blacklist list` -> `schema <object>` -> 最小查詢/snippet |
+| ORM 或 migration | 用 live schema 證據支撐 model 與 migration 修改。 | `schema --format json` -> `diff --snapshot <name>` -> 用 `migrate add-index`/`add-column` 產生 DDL(預覽 SQL)-> `diff --against <snapshot>` |
+| PR 資料庫風險審查 | 檢查 query、write、migration、export、fixture 與 blacklist 風險。 | 審查變更的 persistence path，並針對每個重要主張提出具體 `schema`、`plan`、`dry-run`、`report` 或 `guide` 指令。 |
+| 慢 endpoint 或查詢 | 在提出 index 前優先使用 read-only diagnostics。 | `report --section perf` -> task pack `analyze-table-perf` -> `guide missing-index-for "<query>"`；有 proxy log 時使用 `proxy analyze`。 |
+| 安全資料回填 | 先界定受影響資料範圍並預覽 mutation。 | `blacklist list` -> `schema <object>` -> count/scope query -> `update ... --dry-run` -> read-back 或 snippet `--verify`。 |
+| 環境設定驗證 | 不洩漏 secrets 地檢查 config shape 與 connectivity。 | `status --format json` -> `doctor --format json` -> `inspect --for-agent --no-connect --format json`。 |
+
+可直接複製的指令錨點：
+
+```bash
+dbcli inspect --for-agent --format json
+dbcli blacklist list --format json
+dbcli schema <object> --format json
+dbcli queries suggest <intent> --format json
+dbcli audit tail --for-agent --n 10
+dbcli schema --format json
+dbcli diff --snapshot <name>
+dbcli migrate add-index <table>
+dbcli diff --against <snapshot>
+dbcli report --section perf --format json
+dbcli skill tasks plan analyze-table-perf --param table=<table> --format json
+dbcli guide missing-index-for "<query>" --format json
+dbcli proxy analyze --format json
+dbcli query "<count/scope query>" --format json
+dbcli update <object> --where "<bounded predicate>" --set '<json>' --dry-run --format json
+dbcli status --format json
+dbcli doctor --format json
+dbcli inspect --for-agent --no-connect --format json
+```
+
+開發者工作流守門規則：
+
+- 不要猜測 table、collection、key、index 或 field 名稱。先用 `schema` 確認，再編寫依賴這些名稱的程式碼。
+- 分離資料庫事實與應用程式推論。回報是哪個 dbcli 輸出影響了程式修改或 review 結論。
+- 寫入與 backfill 必須包含 scope count、dry-run preview、execution command，以及 read-back 或 snippet verification。
+- 不要直接從 performance suggestion 建 index；應轉成經過 review 的 migration。
+- 不要列印 credentials、複製的連線字串或 blacklisted 值。
+
+完整旗標、每個指令的可貼上範例、`migrate` DDL、互動式 `shell` 與 MongoDB / Redis / ES 教學在 [reference.md](reference.md)(安裝時與本檔放在一起)。
+
 ## Audit Log 使用
 
 當需要跨 session 或事後 forensics 重建工具歷史時,請優先使用 audit log,而非從零開始查詢 DB 狀態。
@@ -97,8 +146,6 @@ dbcli audit show --recovery-ref <envelope-id> # 反向找出觸發 envelope 的
 
 詳細指令參考:[`reference.md`](./reference.md) §audit(英文)。完整 agent 復原 walkthrough(各錯誤碼 end-to-end 情境、`--next` 多輪逐步、envelope ⇄ audit pivot、risk gate cheat sheet)見 [`reference.md`](./reference.md) §Recovery Cookbook(英文)。
 
-完整旗標、每個指令的可貼上範例、`migrate` DDL、互動式 `shell` 與 MongoDB / Redis / ES 教學在 [reference.md](reference.md)(安裝時與本檔放在一起)。
-
 ## 快速開始
 
 ```bash
@@ -200,6 +247,7 @@ dbcli init --use-env-refs \
 | `list` | query-only+ | 資料表(SQL)、collections(MongoDB)、keys(Redis)或 indices(Elasticsearch)。 |
 | `schema` | query-only+ | SQL:單表或全掃描存入 `.dbcli/schemas/`。MongoDB:sampled。ES:flattened mapping。Redis:僅單一 key(type / TTL / size)。支援 `--recovery`。 |
 | `query` | query-only+ | SQL、Mongo JSON(`--collection`)、Redis 指令、ES DSL / Lucene(`--collection`)。`--format table\|json\|csv\|html`、`--ui` 開啟瀏覽器互動式 dashboard。支援 `--recovery`。 |
+| `explain` | query-only+ | **(v1.23)** 唯讀查詢計畫並附註解。僅 SQL。單一查詢、`@saved-query`、`@file.sql` 或 `--bulk @glob/*`。`--analyze`(EXPLAIN ANALYZE / MariaDB ANALYZE SELECT)、`--format markdown\|json\|table`。 |
 | `plan` | n/a | 靜態 SQL 風險分析器(`--format text\|json`);不連線即可分類語句。 |
 | `q` | query-only+ | 以 `@name` 執行已儲存 snippet，搭配 `--param k=v`。支援 `--verify` 以執行斷言。 |
 | `queries` | n/a | 管理已儲存 snippet:`list` / `show` / `search` / `suggest` / `new` / `edit` / `check` / `delete` / `rename` / `copy` / `import` / `export`。 |
@@ -222,7 +270,7 @@ dbcli init --use-env-refs \
 | `completion` | n/a | bash / zsh / fish 腳本。 |
 | `upgrade` | n/a | 從 npm 自我更新;每個指令都帶 24h 快取的版本提示。 |
 | `shell` | (與 query 同) | 互動式 REPL。支援 SQL 引擎、MongoDB 與 Redis(單行;`.no-limit on/off`)。 |
-| `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|antigravity\|copilot\|cursor>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷。 |
+| `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|antigravity\|copilot\|cursor\|codex\|windsurf>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷。 |
 | `migrate` | admin | 僅 SQL。**DDL;預設 dry-run** — 需 `--execute` 才會真的執行。 |
 
 任何子指令上的 `--use <name>` 都會把目標切到對應的 v2 連線,但不改變預設值。

package/assets/reference.md

@@ -1238,6 +1238,7 @@ dbcli skill --install gemini                 # install to ~/.gemini/skills/dbcli
 dbcli skill --install antigravity            # install to ~/.gemini/antigravity-cli/skills/dbcli/
 dbcli skill --install copilot                # install to .github/skills/dbcli/ (repo-local)
 dbcli skill --install cursor                 # install to .cursor/skills/dbcli/ (repo-local)
+dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 ```
 
 **Options:**
@@ -1247,6 +1248,9 @@ dbcli skill --install cursor                 # install to .cursor/skills/dbcli/
 **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` / `antigravity` install paths are user-global; `copilot` / `cursor` are repo-local under `.github/` / `.cursor/`.
+- Cursor can install through `/add-plugin dbcli-agent` when available in Cursor's plugin marketplace; this repo includes `.cursor-plugin/plugin.json`. Instruction-file fallback options remain documented in `plugins/dbcli-agent/INSTALL.md#cursor`.
+- Codex can consume the repo through the Ponytail-style marketplace layout at `.agents/plugins/marketplace.json` and `.codex-plugin/plugin.json`; plugin installs provide the skill from `skills/dbcli/`, and the skill falls back to `bunx @carllee1983/dbcli` when `dbcli` is not on `PATH`.
+- Agent plugin installation details live in `plugins/dbcli-agent/INSTALL.md`, including Codex, Claude Code, GitHub Copilot CLI, Antigravity (`agy`), and Cursor targets.
 - `gemini` (Gemini CLI) is retained for now but is being phased out in favour of `antigravity` (Antigravity CLI), Google's successor terminal agent.
 - Re-running `--install` overwrites the existing skill atomically; no prompt.
 
@@ -1272,7 +1276,11 @@ dbcli skill tasks plan diagnose-slow-query --param query="..." --format json
 a read-only (`plan-only`) pack taking a required `table` parameter that walks
 `blacklist list` → `schema <table> --format json` → `guide index-usage --format json`.
 `dbcli inspect` suggests `analyze-table-perf` automatically for the hottest table
-in recent audit activity.
+in recent audit activity. Additional read-only packs ship for common agent
+workflows: `audit-permissions` (permission/blacklist audit), `safe-backfill`
+(plan a write with blacklist+schema+risk checks), `schema-drift-review` (cached
+vs live schema diff), and `connection-health` (reachability/config/capacity
+triage). Run `dbcli skill tasks list` for the full set.
 
 ```bash
 dbcli skill tasks plan analyze-table-perf --param table=betting_logs --format json

package/assets/tasks/audit-permissions.md

@@ -0,0 +1,35 @@
+---
+name: audit-permissions
+description: Audit the active permission tier and blacklist coverage before granting an agent write access.
+tags: [security, permissions, readonly]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: false
+    description: Optional table to spot-check column-level blacklist coverage (exact name; confirm via `dbcli list`).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+steps:
+  - type: command
+    command: status
+    reason: Read the current permission tier and connection summary (no credentials).
+    risk: readonly
+  - type: command
+    command: blacklist list
+    reason: Enumerate every protected table and column so sensitive data is accounted for.
+    risk: readonly
+  - type: command
+    command: guide permissions --format json
+    reason: Get the deterministic next-step plan for reviewing what the current tier allows.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task before widening an agent's access (e.g. query-only → read-write) or
+when a user asks "what can this connection touch?". Confirm the permission tier is
+the minimum required and that every sensitive table/column already appears in the
+blacklist. Do not run write operations. If a `table` is supplied, follow up with
+`dbcli schema {{table}} --format json` to verify no sensitive column is exposed.

package/assets/tasks/connection-health.md

@@ -0,0 +1,37 @@
+---
+name: connection-health
+description: Quick read-only health check of the active connection (reachability, config, capacity signals).
+tags: [diagnostics, health, readonly]
+engines: [postgres, mysql]
+params:
+  section:
+    type: string
+    required: false
+    default: health
+    description: Which report section to pull.
+    enum: [health, capacity, perf]
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+steps:
+  - type: command
+    command: status
+    reason: Confirm the connection and permission tier resolve without exposing credentials.
+    risk: readonly
+  - type: command
+    command: doctor
+    reason: Run environment, config, connection and schema-cache diagnostics.
+    risk: readonly
+  - type: command
+    command: report --section {{section}} --for-agent
+    reason: Pull the diagnostic report section for a structured health snapshot.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task as a first-touch triage when a connection "feels" wrong or before a
+larger operation — it answers "can I reach the DB, is the config sane, and are there
+obvious health/capacity red flags?" entirely read-only. If `doctor` reports a stale
+schema cache, refresh it before trusting cached schema. Escalate to
+`dbcli guide capacity` or `dbcli report --section perf` for deeper analysis.

package/assets/tasks/safe-backfill.md

@@ -0,0 +1,42 @@
+---
+name: safe-backfill
+description: Plan a safe data backfill/UPDATE with blacklist, schema and risk checks before any write.
+tags: [data, write, safety]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: true
+    description: The table the backfill writes to (exact name; confirm via `dbcli list`).
+  query:
+    type: string
+    required: true
+    description: The backfill UPDATE statement to analyze (not executed by this task).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm the target table and its columns are not protected before planning a write.
+    risk: readonly
+  - type: command
+    command: schema {{table}} --format json
+    reason: Verify the exact column names and types the backfill will touch.
+    risk: readonly
+  - type: command
+    command: plan "{{query}}"
+    reason: Analyze the UPDATE's risk and scope without executing it.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when a user wants to backfill or correct existing rows. This task only
+PLANS — it never writes. After reviewing the plan, run the real backfill manually in
+two steps: first `dbcli update ... --dry-run` (or `dbcli query "<sql>" --dry-run`) to
+preview the generated SQL, then re-run with `--execute` only once the dry-run looks
+correct. Prefer a narrow `WHERE` clause and verify the affected row count with a
+read-only `SELECT count(*)` before writing. Requires read-write (or higher) permission
+to actually execute.

package/assets/tasks/schema-drift-review.md

@@ -0,0 +1,37 @@
+---
+name: schema-drift-review
+description: Detect drift between the cached/committed schema and the live database for one table.
+tags: [diagnostics, schema, readonly]
+engines: [postgres, mysql]
+params:
+  table:
+    type: string
+    required: true
+    description: The table to compare against its cached schema (exact name; confirm via `dbcli list`).
+safety:
+  mode: plan-only
+  requires:
+    - blacklist-list
+    - schema-check
+steps:
+  - type: command
+    command: blacklist list
+    reason: Confirm the table is inspectable and not protected before reading its schema.
+    risk: readonly
+  - type: command
+    command: doctor
+    reason: Report the schema-cache age so a stale cache can be ruled out as the cause of drift.
+    risk: readonly
+  - type: command
+    command: schema {{table}} --format json
+    reason: Pull the current live schema to diff against the cached/committed definition.
+    risk: readonly
+---
+# Agent Notes
+
+Use this task when a migration may have landed out of band, or a query fails on a
+column that "should" exist. Compare the live `schema {{table}}` output against the
+`schema` block committed in the `.dbcli` config (or the cached snapshot). If they
+disagree, the cache is stale or the live DB drifted — surface the specific column
+differences. Do not run write operations or DDL. Refresh the cache before acting on a
+stale snapshot.

package/dist/cli.mjs

@@ -81224,7 +81224,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.30.0",
+  version: "1.32.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -81268,6 +81268,15 @@ var package_default = {
   files: [
     "dist/",
     "assets/",
+    "plugins/",
+    "skills/",
+    ".codex-plugin/",
+    ".claude-plugin/",
+    ".cursor-plugin/",
+    ".agents/",
+    ".cursor/",
+    ".github/skills/",
+    "gemini-extension.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -81277,15 +81286,19 @@ var package_default = {
     build: "bun run scripts/build.ts",
     prepublishOnly: "bun run build",
     "release:check": "bash scripts/release-check.sh",
+    "plugin:sync": "bun run scripts/sync-plugin-assets.ts --write",
+    "plugin:check": "bun run scripts/sync-plugin-assets.ts",
     test: "bun test",
     "test:unit": "bun test tests/unit tests/core",
     "test:integration": "bun test tests/integration",
     "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration/adapters; docker compose -f docker-compose.test.yml down",
     "docs:check": "bun run scripts/check-user-docs.ts",
+    "skill:check": "bun run scripts/check-skill-parity.ts",
+    "platform:check": "bun run scripts/check-platform-parity.ts",
     typecheck: "tsc --noEmit --pretty false",
     "test:perf": "bun test ./tests/perf/*.bench.ts",
-    lint: "eslint src tests --ext .ts --max-warnings=0",
-    "lint:fix": "eslint src tests --ext .ts --fix --max-warnings=0",
+    lint: "eslint src tests scripts --ext .ts --max-warnings=0",
+    "lint:fix": "eslint src tests scripts --ext .ts --fix --max-warnings=0",
     format: 'prettier --write "src/**/*.ts" "tests/**/*.ts"'
   },
   dependencies: {
@@ -81306,7 +81319,7 @@ var package_default = {
   },
   devDependencies: {
     "@eslint/js": "^9.39.4",
-    "@happy-dom/global-registrator": "^20.9.0",
+    "@happy-dom/global-registrator": "^20.10.6",
     "@inquirer/prompts": "^8.4.3",
     "@testing-library/react": "^16.3.2",
     "@types/bun": "latest",
@@ -81316,7 +81329,7 @@ var package_default = {
     autoprefixer: "^10.5.0",
     "dts-bundle-generator": "^9.5.1",
     eslint: "^10.4.0",
-    "happy-dom": "^20.9.0",
+    "happy-dom": "^20.10.6",
     postcss: "^8.5.14",
     prettier: "^3.8.3",
     tailwindcss: "3.4.1",
@@ -89408,7 +89421,7 @@ function parseGoal(value) {
   }
   return normalized;
 }
-var guideCommand = new Command().name("guide").description(t("guide.description")).argument("[goal]", `Guide goal ID; one of [${ALLOWED_GOALS.join(", ")}]`).option("--format <format>", "Output format: json (default) or markdown", "json").option("--brief", "Trim rationale/expects for compact output", false).option("--for-agent", "Shortcut for --format json --brief", false).option("--list", "List available guide goals and exit", false).option("--probe", "Refresh inspect context via live probe (default: cache-first)", false).option("--probe-timeout <ms>", "Inspect probe timeout for cheap version/object check (default 1500)", (v) => parseInt(v, 10), 1500).action(async (goal, options, command) => {
+var guideCommand = new Command().name("guide").enablePositionalOptions().description(t("guide.description")).argument("[goal]", `Guide goal ID; one of [${ALLOWED_GOALS.join(", ")}]`).option("--format <format>", "Output format: json (default) or markdown", "json").option("--brief", "Trim rationale/expects for compact output", false).option("--for-agent", "Shortcut for --format json --brief", false).option("--list", "List available guide goals and exit", false).option("--probe", "Refresh inspect context via live probe (default: cache-first)", false).option("--probe-timeout <ms>", "Inspect probe timeout for cheap version/object check (default 1500)", (v) => parseInt(v, 10), 1500).action(async (goal, options, command) => {
   let config;
   try {
     const forAgent = options.forAgent === true;