@carllee1983/dbcli 10.0.0 → 12.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "10.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": "10.0.0",
+  "version": "12.0.0",
   "description": "Database CLI skill and command reference for AI agents",
   "author": {
     "name": "Carl Lee",

package/.cursor/rules/dbcli.mdc

@@ -372,7 +372,7 @@ dbcli init                                                # parses .env in cwd
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 \
   --user admin --password '<secret>' --auth-source admin --name mydb
-# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
+# MongoDB — full URI (decomposed into fields on write; multi-host / secret-option strings stay as `uri` with a warning)
 dbcli init --conn-name local --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
 
@@ -494,9 +494,10 @@ refs have no value to connect with yet.
   natively or via the DoH fallback; useful when the runtime restricts DNS.
 - **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
   these interactively (`authSource` only when a user is set; `replicaSet` /
-  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
-  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
-  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  `tls` behind an "advanced options?" prompt); non-interactive flags are
+  `--auth-source <db>`, `--replica-set <name>`, `--srv` (no `port` written) and
+  `--tls` / `--no-tls` (neither given writes no `tls`); a flag you pass skips
+  its prompt. If a config has both `uri` and
   per-field values, `uri` wins silently — `dbcli doctor` flags this and also
   warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,

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

@@ -127,7 +127,7 @@ dbcli init --conn-name local --no-interactive --force    # Non-interactive; cred
 # MongoDB — field-by-field (primary path, same shape as SQL)
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb  # No auth
-# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
+# MongoDB — full URI (decomposed into fields on write; multi-host / secret-option strings stay as `uri` with a warning)
 dbcli init --conn-name local --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
@@ -161,7 +161,7 @@ New initialization always creates named v2 configuration, including plain `init`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
+**MongoDB-specific options:** `--uri <uri>` (full connection URI, decomposed into field config on write: `authSource`/`replicaSet`/`tls`(`ssl`) become dedicated fields, `mongodb+srv` becomes `srv: true`, the path database becomes `database`, other parameters go to `options`; multi-host strings, strings carrying `authMechanismProperties`/`tlsCertificateKeyFilePassword`/`proxyPassword`, strings repeating a query key, and strings whose `authMechanism` is not SCRAM-SHA-1/SCRAM-SHA-256 are stored as-is in `uri` with a plaintext-credentials warning; cannot be combined with `--host`/`--port`/`--user`/`--password`/`--auth-source`/`--replica-set`/`--srv`/`--tls`/`--no-tls` or `--use-env-refs`; `--name` may be combined), `--auth-source <db>` (auth database, default: `admin` when user/password set). `--replica-set <name>` (writes `replicaSet`), `--srv` (writes `srv: true` and no `port`; builds `mongodb+srv://` and resolves hosts via DNS SRV), `--tls` / `--no-tls` (writes `tls: true` / `tls: false`; neither flag writes no `tls` key, so the driver default applies). Interactive `init` skips the prompt for any of these given as a flag; otherwise it asks `srv` right after `host` (before `port`) and `replicaSet` / `tls` under an "advanced options?" prompt. The flags also apply with `--use-env-refs`.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
@@ -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)
 
@@ -3644,7 +3647,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 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.
 
-`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the non-interactive path via `--uri` (with the required `--conn-name`). Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow (stored as-is) and the non-interactive path via `--uri` (with the required `--conn-name`), where the string is decomposed into the field config on write. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
 

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": "10.0.0",
+  "version": "12.0.0",
   "author": {
     "name": "Carl Lee",
     "url": "https://github.com/CarlLee1983"

package/.github/skills/dbcli/SKILL.md

@@ -372,7 +372,7 @@ dbcli init                                                # parses .env in cwd
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 \
   --user admin --password '<secret>' --auth-source admin --name mydb
-# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
+# MongoDB — full URI (decomposed into fields on write; multi-host / secret-option strings stay as `uri` with a warning)
 dbcli init --conn-name local --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
 
@@ -494,9 +494,10 @@ refs have no value to connect with yet.
   natively or via the DoH fallback; useful when the runtime restricts DNS.
 - **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
   these interactively (`authSource` only when a user is set; `replicaSet` /
-  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
-  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
-  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  `tls` behind an "advanced options?" prompt); non-interactive flags are
+  `--auth-source <db>`, `--replica-set <name>`, `--srv` (no `port` written) and
+  `--tls` / `--no-tls` (neither given writes no `tls`); a flag you pass skips
+  its prompt. If a config has both `uri` and
   per-field values, `uri` wins silently — `dbcli doctor` flags this and also
   warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,

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

@@ -127,7 +127,7 @@ dbcli init --conn-name local --no-interactive --force    # Non-interactive; cred
 # MongoDB — field-by-field (primary path, same shape as SQL)
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb  # No auth
-# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
+# MongoDB — full URI (decomposed into fields on write; multi-host / secret-option strings stay as `uri` with a warning)
 dbcli init --conn-name local --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
@@ -161,7 +161,7 @@ New initialization always creates named v2 configuration, including plain `init`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
+**MongoDB-specific options:** `--uri <uri>` (full connection URI, decomposed into field config on write: `authSource`/`replicaSet`/`tls`(`ssl`) become dedicated fields, `mongodb+srv` becomes `srv: true`, the path database becomes `database`, other parameters go to `options`; multi-host strings, strings carrying `authMechanismProperties`/`tlsCertificateKeyFilePassword`/`proxyPassword`, strings repeating a query key, and strings whose `authMechanism` is not SCRAM-SHA-1/SCRAM-SHA-256 are stored as-is in `uri` with a plaintext-credentials warning; cannot be combined with `--host`/`--port`/`--user`/`--password`/`--auth-source`/`--replica-set`/`--srv`/`--tls`/`--no-tls` or `--use-env-refs`; `--name` may be combined), `--auth-source <db>` (auth database, default: `admin` when user/password set). `--replica-set <name>` (writes `replicaSet`), `--srv` (writes `srv: true` and no `port`; builds `mongodb+srv://` and resolves hosts via DNS SRV), `--tls` / `--no-tls` (writes `tls: true` / `tls: false`; neither flag writes no `tls` key, so the driver default applies). Interactive `init` skips the prompt for any of these given as a flag; otherwise it asks `srv` right after `host` (before `port`) and `replicaSet` / `tls` under an "advanced options?" prompt. The flags also apply with `--use-env-refs`.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
@@ -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)
 
@@ -3644,7 +3647,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 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.
 
-`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the non-interactive path via `--uri` (with the required `--conn-name`). Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow (stored as-is) and the non-interactive path via `--uri` (with the required `--conn-name`), where the string is decomposed into the field config on write. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
 

package/CHANGELOG.md

@@ -7,6 +7,113 @@ 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 並用會報錯，
+會影響既有腳本，所以採用 major 版本。已存在、含 `uri` 的設定不會被遷移，連線行為不變。
+
+### Changed
+
+- **破壞性變更：`dbcli init --uri` 寫出的設定形狀改變。** 以 `--uri` 傳入的 MongoDB
+  連線字串現在寫入前先拆解成欄位設定（`host`、`user`、`password`、`database`、
+  `authSource`、`replicaSet`、`tls`、`srv`，其餘參數進 `options`），不再原樣存成 `uri`（互動 init 貼上的連線字串也一樣：拆解後列出結果並直接進連線測試，選單第二項改稱「貼上連線字串（Atlas / Compass 複製的）」）；互動終端下 `--uri` 字串沒帶資料庫名稱時，`Database name` 改為必填、不再預設 `testdb`；
+  讀取 `uri` 欄位的腳本須改讀欄位。**既有設定檔裡已存成 `uri` 的連線不會被遷移，照常連線**；
+  只有之後重新以 `--uri` 執行 init 才會套用新的拆解行為。多組 host、帶 `authMechanismProperties`、
+  `tlsCertificateKeyFilePassword`、`proxyPassword`、同一 query 鍵重複出現，或 `authMechanism`
+  不是 `SCRAM-SHA-1`／`SCRAM-SHA-256` 的字串無法拆解，仍存成只含 `system`、
+  `uri`、`database` 的連線並警告帳密明文存放（除此之外一律拆解成欄位）。字串裡的 `ssl` 寫成 `tls`；
+  非 SRV、有帳號、路徑帶資料庫且未寫 `authSource` 的字串，拆解後寫入 `authSource: <路徑資料庫>`，
+  與 driver 對原字串的認證對象一致。`--uri` 與 `--host`／`--port`／`--user`／
+  `--password`／`--auth-source`／`--replica-set`／`--srv`／`--tls`／`--no-tls` 並用，
+  以及與 `--use-env-refs` 並用，現在都會報錯（後者原本只警告）。
+- **`srv: true` 欄位設定的 `authSource` 改為 SRV TXT 優先。** 既有、有 `user` 但未設定
+  `authSource` 的 `srv: true` 連線，若 SRV TXT record 提供 `authSource`，現在會採用該值，
+  不再固定使用 `admin`；TXT 沒有提供時仍補 `admin`。明確設定的 `authSource` 欄位仍優先，
+  非 SRV 的欄位設定維持預設 `admin`。
+
+### Added
+
+- **MongoDB 欄位設定新增 `options`**：字串對字串的物件，內容附加到連線 URI 的 query
+  （例如 `{"retryWrites": "false", "appName": "dbcli"}`）。只接受純字串，不支援 env-ref；
+  鍵若與 `authSource`／`replicaSet`／`tls`／`ssl` 同名（不分大小寫）會驗證失敗並指出該鍵，
+  請改設專屬欄位。設定了 `uri` 時 `options` 被忽略。
+- **`dbcli init` 新增 MongoDB flag**：`--replica-set <name>`、`--srv`、`--tls` / `--no-tls`。
+  `--srv` 寫入 `srv: true` 且不寫 `port`，並在同時給 `--port`／`--env-port` 時警告該 port 被忽略；
+  `--tls` 與 `--no-tls` 皆未給時不寫 `tls`，沿用 driver 預設。互動精靈不會再問已用 flag
+  給的值；搭配 `--use-env-refs` 時這些 flag 同樣生效。
+- **`dbcli doctor` 在 `uri` 與 `options` 並存時警告**：`uri` 優先，`options` 會被忽略
+  （原本只檢查 `host`／`user`，現在 `options` 也納入）。
+
 ## [10.0.0] - 2026-10-13
 
 這次發布整合 npm 9.1.2 之後合併的變更：明確命名連線、可不設預設連線、Bun 1.4.0

package/assets/SKILL.md

@@ -372,7 +372,7 @@ dbcli init                                                # parses .env in cwd
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 \
   --user admin --password '<secret>' --auth-source admin --name mydb
-# MongoDB — full URI (advanced escape hatch: multi-host, non-standard driver options)
+# MongoDB — full URI (decomposed into fields on write; multi-host / secret-option strings stay as `uri` with a warning)
 dbcli init --conn-name local --system mongodb \
   --uri "mongodb+srv://user:pw@cluster.example.mongodb.net/mydb?authSource=admin"
 
@@ -494,9 +494,10 @@ refs have no value to connect with yet.
   natively or via the DoH fallback; useful when the runtime restricts DNS.
 - **MongoDB `authSource` / `replicaSet` / `tls` / `srv`** — `init` asks for
   these interactively (`authSource` only when a user is set; `replicaSet` /
-  `tls` behind an "advanced options?" prompt); `--auth-source <db>` is the
-  only one with a dedicated non-interactive flag, so set `replicaSet` / `tls`
-  interactively or edit `.dbcli` afterward. If a config has both `uri` and
+  `tls` behind an "advanced options?" prompt); non-interactive flags are
+  `--auth-source <db>`, `--replica-set <name>`, `--srv` (no `port` written) and
+  `--tls` / `--no-tls` (neither given writes no `tls`); a flag you pass skips
+  its prompt. If a config has both `uri` and
   per-field values, `uri` wins silently — `dbcli doctor` flags this and also
   warns when `srv: true` is combined with a non-default `port`.
 - **MySQL/Postgres password with `@` `:` `/`** — when using `DATABASE_URL`,

package/assets/reference.md

@@ -127,7 +127,7 @@ dbcli init --conn-name local --no-interactive --force    # Non-interactive; cred
 # MongoDB — field-by-field (primary path, same shape as SQL)
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --user admin --password secret --auth-source admin --name mydb
 dbcli init --conn-name local --system mongodb --host localhost --port 27017 --name mydb  # No auth
-# MongoDB — full URI (advanced fallback: multi-host, non-standard driver options)
+# MongoDB — full URI (decomposed into fields on write; multi-host / secret-option strings stay as `uri` with a warning)
 dbcli init --conn-name local --system mongodb --uri "mongodb://user:pass@host:27017/mydb?authSource=admin"
 
 # Redis (database = logical DB index)
@@ -161,7 +161,7 @@ New initialization always creates named v2 configuration, including plain `init`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
-**MongoDB-specific options:** `--uri <uri>` (full connection URI — advanced fallback), `--auth-source <db>` (auth database, default: `admin` when user/password set). Interactive `init` also asks for `replicaSet` and `tls` under an "advanced options?" prompt; there is no dedicated non-interactive flag for either yet — set them interactively or edit `.dbcli` afterward. `srv` (boolean, builds `mongodb+srv://` and resolves hosts via DNS SRV, ignoring `port`) is asked right after `host`, before `port`, since it decides whether `port` is even relevant.
+**MongoDB-specific options:** `--uri <uri>` (full connection URI, decomposed into field config on write: `authSource`/`replicaSet`/`tls`(`ssl`) become dedicated fields, `mongodb+srv` becomes `srv: true`, the path database becomes `database`, other parameters go to `options`; multi-host strings, strings carrying `authMechanismProperties`/`tlsCertificateKeyFilePassword`/`proxyPassword`, strings repeating a query key, and strings whose `authMechanism` is not SCRAM-SHA-1/SCRAM-SHA-256 are stored as-is in `uri` with a plaintext-credentials warning; cannot be combined with `--host`/`--port`/`--user`/`--password`/`--auth-source`/`--replica-set`/`--srv`/`--tls`/`--no-tls` or `--use-env-refs`; `--name` may be combined), `--auth-source <db>` (auth database, default: `admin` when user/password set). `--replica-set <name>` (writes `replicaSet`), `--srv` (writes `srv: true` and no `port`; builds `mongodb+srv://` and resolves hosts via DNS SRV), `--tls` / `--no-tls` (writes `tls: true` / `tls: false`; neither flag writes no `tls` key, so the driver default applies). Interactive `init` skips the prompt for any of these given as a flag; otherwise it asks `srv` right after `host` (before `port`) and `replicaSet` / `tls` under an "advanced options?" prompt. The flags also apply with `--use-env-refs`.
 
 **Elasticsearch-specific options:** `--cloud-id <id>` (Elastic Cloud), `--api-key <key>` (ApiKey auth). Other ES fields (`nodes[]`, `protocol`, `caPath`, `rejectUnauthorized`) can be edited directly in `.dbcli`.
 
@@ -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)
 
@@ -3644,7 +3647,7 @@ Parser behaviour (`src/core/saved-queries/parser.ts::normaliseVisual`):
 
 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.
 
-`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow and the non-interactive path via `--uri` (with the required `--conn-name`). Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
+`init --system mongodb` defaults to a field-by-field wizard (`host`, `srv`, `port`, `user`, `password` + `authSource`, then optional `replicaSet` / `tls`); a full `uri` is an explicit advanced choice in the interactive flow (stored as-is) and the non-interactive path via `--uri` (with the required `--conn-name`), where the string is decomposed into the field config on write. Optional fields `authSource`, `replicaSet`, `tls`, and `srv` express what previously required embedding options in the `uri` query string. Atlas-style `mongodb+srv://` URIs are supported both as a full `uri` and via the per-field `srv: true` option. `list` and `query` run against the database configured for the connection, and `query` always requires `--collection <name>`.
 
 The 5000ms default server-selection timeout is often too tight for a connection over a VPN or to Atlas. Set a `timeout` field (ms) in the connection config, or override it per invocation with root-level `--timeout`, e.g. `dbcli --timeout 20000 --use <conn> list`.
 

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