@carllee1983/dbcli 11.0.0 → 12.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "11.0.0",
+  "version": "12.0.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "author": {
     "name": "Carl Lee",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "11.0.0",
+  "version": "12.0.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/skills/dbcli/reference.md

@@ -1868,8 +1868,11 @@ at execution time, and no human has agreed to anything. `admin` in a config file
 is a permission level, not a DBA sign-off.
 
 `schema.read` is available under `DBCLI_AGENT_MODE=1`, and `dbcli schema` runs
-there: storing the schema cache is not a configuration change. Agent mode still
-refuses every change to connection identity, permission and credentials.
+there: storing the schema cache is not a configuration change. `blacklist.read`
+(`blacklist list`) is available there too, so read-only Task Packs that inspect
+the blacklist can plan; `blacklist.manage`, which adds and removes rules, is
+refused. Agent mode still refuses every change to connection identity,
+permission and credentials.
 
 **Permission:** query-only+ (no connection is made)
 

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "dbcli-agent",
   "displayName": "dbcli Agent",
   "description": "Database CLI skill and command reference for AI agents.",
-  "version": "11.0.0",
+  "version": "12.0.0",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/reference.md

@@ -1868,8 +1868,11 @@ at execution time, and no human has agreed to anything. `admin` in a config file
 is a permission level, not a DBA sign-off.
 
 `schema.read` is available under `DBCLI_AGENT_MODE=1`, and `dbcli schema` runs
-there: storing the schema cache is not a configuration change. Agent mode still
-refuses every change to connection identity, permission and credentials.
+there: storing the schema cache is not a configuration change. `blacklist.read`
+(`blacklist list`) is available there too, so read-only Task Packs that inspect
+the blacklist can plan; `blacklist.manage`, which adds and removes rules, is
+refused. Agent mode still refuses every change to connection identity,
+permission and credentials.
 
 **Permission:** query-only+ (no connection is made)
 

package/CHANGELOG.md

@@ -7,6 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [12.0.0] - 2026-10-18
+
+版本為 **12.0.0**。SQL 單一物件 `schema` 現在將含點號的輸入解析為完整名稱，
+會改變既有命令的查詢對象，因此採用 major 版本。升級前請檢查含點號的名稱、依賴完整
+schema metadata 的腳本、SHOW GRANTS 輸出用途，以及原生授權錯誤的處理分支。
+本版不需要連線設定、schema 快取或 recovery envelope 的資料遷移。
+
+### Fixed
+
+- **assert --expect 的 evidence receipt**：只投影檢查 pass bits，沿用既有 schema，
+  排除原始 SQL 與結果值；成功與失敗斷言都可產生 receipt。`--no-fail` 只影響斷言退出碼，
+  失敗 receipt 不會變成功，receipt 寫入失敗仍 exit 1。
+- **MongoDB Unix socket URI 與錯誤去敏**：`init --uri` 與互動貼上的 Unix socket
+  連線字串保留原始 `uri`、認證與 options，不再拆成 TCP host／port；既有明文儲存警告
+  仍會顯示。URI fallback 連線測試失敗時，同時遮蔽原始 URI、編碼及解碼後的密碼。
+- **內建 task pack 的操作指引**：`safe-backfill` 改用真實支援的
+  `update ... --dry-run`，raw SQL 的預覽使用 `plan`；移除不存在的 `query --dry-run`
+  與 `--execute` 指引，實際寫入仍需既有確認與權限。`migration-review` 說明執行 DDL
+  需要 `admin`，唯讀規劃不升權，也不執行 DDL。
+- **CLI 啟動 bundle**：建置使用 syntax minification 降低 runtime bundle 大小，
+  維持啟動效能預算；保留 whitespace，避免 Bun 對動態 import 的錯誤改寫。
+
+### Added
+
+- **單一物件 schema 支援完整名稱**：PostgreSQL 可用 `schema.table`，MySQL／MariaDB
+  可用 `database.table` 檢視表與系統視圖；支援原生識別字引用、內嵌點號與跳脫引號。
+  完整名稱不可搭配 `--refresh`／`--reset`，不改連線設定或 schema 快取，也不擴大掃描範圍。
+- **`blacklist.read` capability 與 agent-mode task planning**：唯讀的 `blacklist list`
+  有獨立 capability，內建需要檢視 blacklist 的 task pack 改用它；`connection-health`
+  不要求 blacklist capability。引擎與權限符合時，`DBCLI_AGENT_MODE=1` 可產生這些
+  plan-only 計畫；`blacklist.manage` 仍是設定異動，在 agent mode 下不可用。
+  規劃不執行任何步驟，也不授予執行權限。
+
+### Changed
+
+- **文件釐清 RDS CALL 證據交接**：query-only 仍拒絕 CALL，未新增 RDS 程序支援。
+  區分 CLI 政策拒絕與 DBA 的 indeterminate（證據不足）結論，提供既有授權內的人工
+  交接模板，並區分 binlog 保留小時與自動快照保留天數；不以升權或 AWS 自動化作為補救。
+- **SHOW GRANTS 認證內容去敏**：MySQL／MariaDB 的正常與 native-read-only 執行，
+  一律在 adapter 回傳前把可安全辨識的認證參數換成 `[REDACTED]`，保留帳號、角色、
+  授權範圍與權限；未知、不完整或歧義格式及異常型態則整格改為
+  `[OMITTED: grant text could not be safely redacted]`，保留列數、欄名與結果結構。
+  query、互動 shell 與 SQL 查詢 export 的適用輸出格式均受保護，不依賴 blacklist，
+  所有權限與 agent 模式均無 bypass。省略格不代表完整授權資訊，去敏結果不可作為可重播 SQL。
+  僅涵蓋 SHOW GRANTS；SHOW CREATE USER、直接系統表查詢與任意 SQL 不在掃描範圍，
+  saved query 仍拒絕 SHOW GRANTS。
+- **原生授權錯誤代碼**：MySQL／MariaDB 1044、1142、1143、1227 與 PostgreSQL
+  `42501` 現在分類為 `DB_PERMISSION_DENIED`，與登入驗證失敗 `AUTH_FAILED` 及本機政策
+  `PERMISSION_DENIED` 區分。Recovery 維持 schema v1 與 `error.code: "PERMISSION_DENIED"`，
+  以 `error.details.connectionCode: "DB_PERMISSION_DENIED"` 識別原生拒絕；只提供人工指引，
+  `recovery: []` 並省略 `verify`，`recover --apply` 不執行修復。既有 envelope 無需遷移，
+  呼叫端須依新 discriminator 區分拒絕來源。
+- **Schema 輸出與 metadata 保護**：完整名稱 JSON 保留局部 `name` 並另帶 `schema`，
+  文字輸出可區分兩個 component；`tableType` 正確呈現 table／view（materialized view 為 view）。
+  完整名稱不執行關係資料 `COUNT(*)`，未知筆數與大小分類為 null，不再以假零值或 small 表示。
+  舊、新 SQL 單一物件名稱都套用 blacklist；隱藏受保護欄位及涉及它的整項主鍵、索引與外鍵，
+  無法安全表達完整欄位相依性的 expression／partial index 也會整項省略；省略時 JSON 輸出
+  `metadataOmitted: true`，文字輸出顯示省略通知，回傳 metadata 不保證完整。
+  必要 metadata 讀取失敗會回報失敗，不以空集合冒充成功；省略不代表該 metadata 不存在。
+  MySQL／MariaDB 的 `indexes[].unique` 正規化為宣告的 boolean 型別，不再輸出 driver 的
+  數字 0／1；複合外鍵欄位順序與目標 namespace 依 catalog 正確呈現。
+- **破壞性變更：含點號名稱的解析**：原本 `dbcli schema audit.orders` 查詢預設
+  namespace 中字面名稱為 `audit.orders` 的物件，現在會查詢 namespace `audit` 中的
+  `orders`。PostgreSQL 原本的局部含點號名稱須改成
+  `dbcli schema 'public."audit.orders"' --format json`；MySQL／MariaDB 以 backtick
+  分別引用 database 與局部名稱，例如
+  ``dbcli schema '`reporting`.`audit.orders`' --format json``，仍須符合該引擎允許的名稱規則。
+  未限定且不含點號的名稱維持 PostgreSQL `public`／MySQL、MariaDB 預設 database 與既有
+  精確名稱語意。完整名稱不存在時不會退回預設 namespace 的同名物件；其他命令的名稱解析不變。
+
 ## [11.0.0] - 2026-10-14
 
 版本為 **11.0.0**。`dbcli init --uri` 寫出的設定形狀改變，且 `--uri` 與欄位 flag 並用會報錯，

package/assets/reference.md

@@ -1868,8 +1868,11 @@ at execution time, and no human has agreed to anything. `admin` in a config file
 is a permission level, not a DBA sign-off.
 
 `schema.read` is available under `DBCLI_AGENT_MODE=1`, and `dbcli schema` runs
-there: storing the schema cache is not a configuration change. Agent mode still
-refuses every change to connection identity, permission and credentials.
+there: storing the schema cache is not a configuration change. `blacklist.read`
+(`blacklist list`) is available there too, so read-only Task Packs that inspect
+the blacklist can plan; `blacklist.manage`, which adds and removes rules, is
+refused. Agent mode still refuses every change to connection identity,
+permission and credentials.
 
 **Permission:** query-only+ (no connection is made)
 

package/assets/tasks/README.md

@@ -33,4 +33,4 @@ The markdown body below the frontmatter is `Agent Notes` and is shown in
 
 Use `postgresql` for PostgreSQL. The legacy `postgres` engine spelling is read
 as `postgresql`; legacy requirement names `blacklist-list` and `schema-check`
-are rejected with their replacements, `blacklist.manage` and `schema.read`.
+are rejected with their replacements, `blacklist.read` and `schema.read`.

package/assets/tasks/analyze-table-perf.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/audit-permissions.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
 steps:
   - type: command
     command: status

package/assets/tasks/connection-health.md

@@ -12,8 +12,7 @@ params:
     enum: [health, capacity, perf]
 safety:
   mode: plan-only
-  requires:
-    - blacklist.manage
+  requires: []
 steps:
   - type: command
     command: status

package/assets/tasks/design-review.md

@@ -6,7 +6,7 @@ engines: [postgresql, mysql]
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

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

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/migration-review.md

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command
@@ -37,5 +37,7 @@ Use this task before applying a schema migration. It only PLANS — it never run
 Save the pre-change `schema {{table}} --format json` output as the baseline. After the
 migration is applied (out of band, via your migration tool), re-run
 `schema {{table}} --format json` and diff the two to confirm the change matches intent.
-Always prepare and record an explicit rollback statement before applying. Requires
-data-admin permission to actually run DDL — this task does not grant it.
+Always prepare and record an explicit rollback statement before applying.
+Read-only planning and review need no elevated permission beyond this task's existing
+requirements. Running DDL out of band requires `admin` permission — this task neither
+grants that permission nor runs DDL.

package/assets/tasks/mongo-safe-backfill.md

@@ -19,7 +19,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

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

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

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

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/pr-database-review.md

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/safe-backfill-verify.md

@@ -23,7 +23,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/safe-backfill.md

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command
@@ -34,9 +34,15 @@ steps:
 # 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.
+PLANS — it never writes. After reviewing the plan, run the real backfill manually:
+
+1. Confirm a narrow `WHERE` clause and capture its scope with a read-only
+   `SELECT count(*)` before writing.
+2. Preview the structured write with
+   `dbcli update <table> --where "<predicate>" --set '<json>' --dry-run`.
+   Keep raw SQL writes in `dbcli plan "<sql>"`; `query` does not dry-run arbitrary writes.
+3. Once the preview looks correct, re-run the write command without `--dry-run`
+   and with the required confirmation/force flag for your environment. The existing
+   write gate still applies; execution requires read-write (or higher) permission.
+4. Read the rows back afterwards to confirm the backfill achieved its goal. If the
+   result does not match, stop and investigate before attempting another write.

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

@@ -11,7 +11,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
     - schema.read
 steps:
   - type: command

package/assets/tasks/slow-endpoint-investigation.md

@@ -15,7 +15,7 @@ params:
 safety:
   mode: plan-only
   requires:
-    - blacklist.manage
+    - blacklist.read
 steps:
   - type: command
     command: blacklist list