v10.0.0

這次發布整合 npm 9.1.2 之後合併的變更：明確命名連線、可不設預設連線、Bun 1.4.0
最低版本、PostgreSQL schema 修正、帶期限的 audit 豁免，以及實錄的 agent 操作影片。
9.2.0 曾完成發布準備，但未發布到 npm；原本的 9.2.0 與 Unreleased 更新紀錄合併於此。

版本為 10.0.0。新連線不再自動取名，刪除預設連線也不再自動改選另一條；這兩項
行為會影響既有腳本，所以採用 major 版本。

Breaking changes and upgrade notes

• 非互動式初始化必須指定 --conn-name <連線名稱>。 適用於非 TTY、
  --no-interactive 與完整 env-reference 自動非互動模式；互動模式會詢問名稱。
  --name 仍表示資料庫名稱，不能拿它代替 --conn-name。原先依賴自動命名的腳本
  須補上連線名稱；明確指定 --conn-name default 仍合法。
• 升級 Bun 至 1.4.0 以上。 仍使用 1.3.x 的環境須先升級，原因與相依套件細節見下方。
• 既有 v1 設定讀取與具名匯入仍保留。 單純 init 與明確 --config 新建連線
  改用具名 v2；全新 registry 的第一條具名連線仍會成為預設，追加連線則保留既有的
  default/no-default 狀態，不會偷偷建立或替換預設。
• 預設連線可以清除，刪除後不再自動補選。 使用 dbcli use --unset 清除預設；
  刪除預設連線也會留下無預設狀態，而不是選取下一條。之後須透過 --use 或
  DBCLI_CONNECTION 選取，或以 dbcli use <連線名稱> 明確設定新預設；仍禁止刪除
  最後一條連線。
• 帶自訂 envFile 的直接專案 v2 設定須先遷移。 若新增連線需要匯入舊版直接
  專案 v2 設定，而它的 envFile 不是 .env.local，init 會在寫入前拒絕並保留
  原檔。須先由管理員完成 home storage 遷移，再新增連線。

Added

• 介紹頁與 README 加上一段實錄的 agent 操作影片。 一段真實的 Claude Code session
  對著一個用完即丟的 PostgreSQL 操作：agent 透過 dbcli 讀資料，被列入黑名單的
  password_hash 欄位帶著 dbcli 的安全提示被略去，它在 query-only 連線上的寫入被拒絕。
  影片放在兩個語系介紹頁的 #safety 區，兩份 README 各以縮圖連到自己語系的頁面。
  scripts/demo/ 保留 seed、設定、錄製與剪輯腳本，CLI 輸出改變時可以重錄。

Changed

• 新建或新增連線必須明確命名。 init 未提供 --conn-name 時會在互動式
  終端機主動詢問名稱，不再代填 default；空白回答會說明並再次詢問，取消或
  結束提示不會寫入；明確傳入空白名稱則在任何模式都報錯。非 TTY、
  --no-interactive 或完整 env-reference 自動非互動
  模式缺少名稱時，會在連線測試、設定及憑證寫入前報錯。--name 仍是資料庫名，
  明確指定 --conn-name default 仍合法。單純 init 與明確 --config 都改用
  具名 v2 新建，既有 v1 讀取與具名匯入保留。全新 registry 仍以第一條具名連線
  為預設，追加連線保留既有 default/no-default；同名覆寫確認及 --force 保護
  維持不變（#212）。

• v2 可以不設定預設連線。 省略 default 即可要求每次透過 --use 或
  DBCLI_CONNECTION 明確選取；未選取時會在連線前失敗，列出可用名稱而不洩漏
  端點或憑證。新增 dbcli use --unset，透過既有核准與 integrity record 保護
  流程清除預設值，重複執行也安全。刪除預設連線會清除預設值，不再依 JSON
  順序改選另一條；仍禁止刪除最後一條連線。清單與 doctor 支援無預設狀態，
  初始化與 v1 遷移建立預設值的方式、selector 優先序與正式環境防護不變（#212）。
  若新增連線會匯入帶有自訂 envFile（非 .env.local）的舊版直接專案 v2
  設定，init 會在寫入前拒絕並保留原檔，須先由管理員完成 home storage 遷移。

• Bun 最低版本從 1.3.3 提高到 1.4.0。 mongodb@7.2.0 依賴 bson: "^7.2.0"，
  不帶 lockfile 的使用者安裝會解析到 bson 7.3+。bson 7.3.0 起，ObjectId 載入時會呼叫
  v8.startupSnapshot.isBuildingSnapshot()，Bun 1.3.x 對此丟出
  NotImplementedError: node:v8 isBuildingSnapshot is not yet implemented in Bun.，
  任何碰到 MongoDB 的指令都會失敗。實測 Bun 1.3.3 與 1.3.10–1.3.14 都會失敗，
  1.4.0–1.4.3 都正常。本 repo 的 bun.lock 把 bson 鎖在 7.2.0，所以 CI 的 1.3.3 那一列
  從來沒碰到這個問題。engines.bun、CI 最低版本、postinstall 提示、doctor 的預設值與
  使用者文件都改為 1.4.0。

• audit gate 可以帶有期限、附理由的豁免。 scripts/audit-exemptions.json 逐筆列出
  GHSA id、套件、理由與 UTC 到期日。未到期的項目轉成 bun audit --ignore 參數，每次執行
  都印出來；過期或格式錯誤的項目讓 gate 失敗，所以豁免不會悄悄變成永久。第一筆豁免
  GHSA-vfj7-8cjw-p6xm（braces <= 3.0.3，沒有修正版，只經由建置期的 tailwindcss 引入）
  到 2026-11-30。決定記在 ADR-0042。

• 發布流程改由版本 tag 驅動。 合併發布準備 PR 後才在 main 建立 vX.Y.Z；
  工作流程核對版本與來源、啟動測試資料庫並執行 make verify，通過後等待
  npm-publish 環境審批，再透過 npm trusted publishing 發布附 provenance 的套件，
  最後從本檔對應版本章節建立 GitHub Release。須先完成 trusted publisher 與審批環境
  設定（#214）。

Fixed

• Elasticsearch 整合驗證不再把未執行的 roundtrip 算成通過。 測試的 DOM preload
  同時保留 Bun 的 fetch、AbortController 與 AbortSignal，避免混用不同實作而在
  HTTP 送出前失敗。有服務時的連線／初始化錯誤會讓測試失敗；只有明確停用整合測試，
  或本機未要求必備服務且 TCP 端點不存在時，才記為真正的 skip。CI 必須實跑建立索引、
  寫入、refresh、查詢、schema 斷言與清理，完成後才輸出 roundtrip 驗證紀錄。
  這是測試基礎設施修正，沒有改變發布套件的 adapter 行為。

• PostgreSQL 的 schema 重新回報主鍵、索引與外鍵欄位。 對 pg_attribute.attname 做
  array_agg 得到的是 name[]，node-postgres 把它當字串回傳，schema 因此丟掉了這些欄位，
  寫入閘門也就拒絕了每一筆結構化寫入。改為先轉成 text。

• PostgreSQL 的 enum 欄位重新回報 enumValues。 pg_enum.enumlabel 的 array_agg
  同樣是 name[]，以相同方式修正。

• SQL 引擎的 update 先檢查權限等級再連線。 與 Redis、MongoDB 分支以及 delete
  一致：query-only 連線現在因為權限不足被拒，而不是被寫入閘門擋下；權限檢查也排在
  executor 的黑名單檢查之前。

Security

• 兩筆開發依賴的安全公告。 source-map-js 1.2.1 → 1.2.2（high，GHSA-68fv-2mgg-jv7q），
  修正版在 postcss 的 ^1.2.1 範圍內，只更新 lockfile。postcss-selector-parser
  （moderate，GHSA-rj75-hqrm-r3gf）只在 7.1.6 修正，但 tailwindcss@3.4.19 與
  postcss-nested@6.2.0 都要求 6.x，因此依 ADR-0042 在 scripts/audit-exemptions.json
  豁免到 2026-11-30：它只在建置時解析本 repo 自己的樣式表，執行期與使用者輸入都碰不到。