@carllee1983/dbcli 1.23.1 → 1.25.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.25.0] - 2026-05-29 - Data-Layer Verification
+
+### Added
+
+- **`dbcli snapshot <query>` — 結果指紋。** 將任一查詢結果轉成確定性、黑名單安全的 `ResultSnapshot`(`rowCount` + 每欄聚合:null/distinct 計數、min/max/sum、順序無關的 checksum)。預設落檔至 `.dbcli/snapshots/snap-<timestamp>.json`,亦支援 `--out`、`--stdout`、`--rows`(連同遮罩後的列一併存檔)、`--format`、`--no-limit`。
+- **`dbcli assert <query>` — 行內不變量檢查。** 三種模式:`--expect`(`rows > 0`、`value == 5000`、`col:email not null`、`col:id unique`、`col:amount between 0 and 100`、`col:age >= 18`)、`--vs <query> --compare rows|value`(跨查詢對帳)、`--against <snapshot> --tolerance <pct>`(對既有快照基準比對)。預設失敗時 `exit 1`,可用 `--no-fail` 僅報告不改變 exit code。
+- 兩個指令均沿用既有 adapter / QueryExecutor / blacklist / audit 堆疊,黑名單欄位由 QueryExecutor 在源頭遮罩,指紋天生安全。目前支援 SQL 引擎(PostgreSQL / MySQL / MariaDB)。
+
+## [1.24.0] - 2026-05-29 - Antigravity CLI Skill Target
+
+### Added
+
+- **`dbcli skill --install antigravity` 新增 Antigravity CLI 安裝目標。** Antigravity CLI 是 Google Gemini CLI 的後繼者;skill 會寫入 CLI 範疇的全域路徑 `~/.gemini/antigravity-cli/skills/dbcli/SKILL.md`(同目錄附帶 `reference.md`)。`SUPPORTED_PLATFORMS` 一併納入 `antigravity`,故 `dbcli upgrade` 的 skill 過期檢查也會涵蓋此平台。
+
+### Changed
+
+- `gemini`(Gemini CLI)安裝目標暫予保留,但已標示為即將淘汰,建議改用 `antigravity`。README(en/zh-TW)、`assets/SKILL.md`、`assets/SKILL.zh-TW.md`、`assets/reference.md` 與 `docs/user` 的平台清單同步更新。
+
 ## [1.23.1] - 2026-05-29 - Skill Docs Sync
 
 ### Changed

package/README.md

@@ -630,7 +630,8 @@ Generate or install AI agent skill documentation.
 dbcli skill                           # Output skill to stdout
 dbcli skill --output SKILL.md         # Write to file
 dbcli skill --install claude          # Install to Claude Code config
-dbcli skill --install gemini          # Install to Gemini CLI
+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
 ```
@@ -654,6 +655,7 @@ dbcli skill
 # Install for all platforms
 dbcli skill --install claude && \
 dbcli skill --install gemini && \
+dbcli skill --install antigravity && \
 dbcli skill --install copilot && \
 dbcli skill --install cursor
 ```
@@ -766,6 +768,50 @@ dbcli diff --against ./schema-before.json --format table
 
 ---
 
+#### `dbcli snapshot`
+
+Capture a **result fingerprint** of a query (distinct from `diff`, which snapshots *schema*): row count plus per-column aggregates (null/distinct counts, min/max/sum) and an order-independent checksum. Blacklisted columns are masked at the source, so the snapshot is safe to store. Use it as a baseline for `dbcli assert --against`. SQL engines only.
+
+**Usage:**
+```bash
+dbcli snapshot "SELECT * FROM orders WHERE created_at >= '2026-05-01'"   # → .dbcli/snapshots/snap-<timestamp>.json
+dbcli snapshot @analytics/daily-revenue --out base.json
+dbcli snapshot "SELECT status, count(*) FROM orders GROUP BY status" --stdout
+```
+
+**Options:**
+- `--out <path>` — Output path (default: `.dbcli/snapshots/snap-<timestamp>.json`)
+- `--rows` — Also store the full (blacklist-masked) rows
+- `--stdout` — Print snapshot JSON to stdout instead of writing a file
+- `--format json|table` — Output format for `--stdout` (default: `json`)
+- `--no-limit` — Disable the automatic query-only LIMIT
+
+---
+
+#### `dbcli assert`
+
+Assert an **invariant** on a query result. Exits `1` on failure (composes in scripts/CI) unless `--no-fail`. SQL engines only.
+
+**Usage:**
+```bash
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 0"
+dbcli assert "SELECT * FROM orders WHERE total < 0" --expect "rows == 0"
+dbcli assert "SELECT email FROM users" --expect "col:email not null"
+dbcli assert "SELECT sum(amount) FROM ledger_a" --vs "SELECT sum(amount) FROM ledger_b" --compare value
+dbcli assert "SELECT * FROM orders" --against base.json --tolerance 0.01
+```
+
+**Options:**
+- `--expect <condition>` — `rows > 0`, `value == 5000`, `col:email not null`, `col:id unique`, `col:amount between 0 and 100`, `col:age >= 18`
+- `--vs <query>` — Reconcile against a second query
+- `--compare rows|value` — Comparison mode for `--vs` (default: `value`)
+- `--against <path>` — Compare the current result fingerprint to a saved snapshot
+- `--tolerance <pct>` — Allowed relative drift for `--against` (e.g. `0.01`; default: `0` = exact checksum match)
+- `--no-fail` — Always exit 0; report pass/fail in output only
+- `--format json|table` — Output format (default: `json`)
+
+---
+
 #### `dbcli status`
 
 Show non-sensitive configuration summary (permission level, DB system, blacklist counts, config metadata version). Does not print connection credentials — intended for AI agents.

package/README.zh-TW.md

@@ -528,7 +528,8 @@ dbcli export "SELECT * FROM users WHERE active=true" --format json | jq '.data |
 dbcli skill                           # 輸出至 stdout
 dbcli skill --output SKILL.md         # 寫入檔案
 dbcli skill --install claude          # 安裝至 Claude Code 設定
-dbcli skill --install gemini          # 安裝至 Gemini CLI
+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
 ```
@@ -552,6 +553,7 @@ dbcli skill
 # 為多平台安裝
 dbcli skill --install claude && \
 dbcli skill --install gemini && \
+dbcli skill --install antigravity && \
 dbcli skill --install copilot && \
 dbcli skill --install cursor
 ```
@@ -665,6 +667,50 @@ dbcli diff --against ./schema-before.json --format table
 
 ---
 
+#### `dbcli snapshot`
+
+擷取查詢的**結果指紋**(與 `diff` 不同,`diff` 快照的是 *schema*):rowCount 加上每欄聚合(null/distinct 計數、min/max/sum)與順序無關的 checksum。黑名單欄位在源頭遮罩,因此快照可安全保存。作為 `dbcli assert --against` 的基準。僅支援 SQL 引擎。
+
+**用法:**
+```bash
+dbcli snapshot "SELECT * FROM orders WHERE created_at >= '2026-05-01'"   # → .dbcli/snapshots/snap-<timestamp>.json
+dbcli snapshot @analytics/daily-revenue --out base.json
+dbcli snapshot "SELECT status, count(*) FROM orders GROUP BY status" --stdout
+```
+
+**選項:**
+- `--out <path>` — 輸出路徑(預設:`.dbcli/snapshots/snap-<timestamp>.json`)
+- `--rows` — 連同遮罩後的完整列一併存檔
+- `--stdout` — 將快照 JSON 印到 stdout 而非寫檔
+- `--format json|table` — `--stdout` 的輸出格式(預設:`json`)
+- `--no-limit` — 停用查詢限定模式的自動 LIMIT
+
+---
+
+#### `dbcli assert`
+
+對查詢結果驗證**不變量**。失敗時 `exit 1`(可組合進腳本 / CI),除非加上 `--no-fail`。僅支援 SQL 引擎。
+
+**用法:**
+```bash
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 0"
+dbcli assert "SELECT * FROM orders WHERE total < 0" --expect "rows == 0"
+dbcli assert "SELECT email FROM users" --expect "col:email not null"
+dbcli assert "SELECT sum(amount) FROM ledger_a" --vs "SELECT sum(amount) FROM ledger_b" --compare value
+dbcli assert "SELECT * FROM orders" --against base.json --tolerance 0.01
+```
+
+**選項:**
+- `--expect <condition>` — `rows > 0`、`value == 5000`、`col:email not null`、`col:id unique`、`col:amount between 0 and 100`、`col:age >= 18`
+- `--vs <query>` — 與第二個查詢對帳
+- `--compare rows|value` — `--vs` 的比較模式(預設:`value`)
+- `--against <path>` — 將目前結果指紋與已存快照比對
+- `--tolerance <pct>` — `--against` 容許的相對漂移(例如 `0.01`;預設 `0` = 完全相符 checksum)
+- `--no-fail` — 永遠 exit 0;僅在輸出中報告 pass/fail
+- `--format json|table` — 輸出格式(預設:`json`)
+
+---
+
 #### `dbcli status`
 
 顯示不含連線憑證的設定摘要（權限、資料庫系統、黑名單筆數、設定中繼版本），適合提供給 AI 代理。

package/assets/SKILL.md

@@ -250,6 +250,8 @@ Full flags and edge cases: see [reference.md](reference.md) `init` section.
 | `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. |
+| `snapshot` | query-only+ | **(v1.25)** SQL only. Capture a result fingerprint (`rowCount` + per-column null/distinct/min/max/sum + order-independent checksum). `--out` (default `.dbcli/snapshots/snap-<ts>.json`), `--rows`, `--stdout`, `--format`, `--no-limit`. Baseline for `assert --against`. |
+| `assert` | query-only+ | **(v1.25)** SQL only. Verify an invariant; exit 1 on failure unless `--no-fail`. `--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`, `--vs <query> --compare rows\|value` (reconcile), `--against <snapshot> --tolerance <pct>`. |
 | `status` | query-only+ | Safe JSON/text summary (no credentials). |
 | `inspect` | query-only+ | Read-only context snapshot (connection, permission, blacklist, objects, snippets, context-aware `suggestedCommands`, and **(v1.23)** human-readable `hints`). `--for-agent` / `--brief` / `--no-connect` / `--require-schema-cache`. Supports `--recovery`. |
 | `report` | query-only+ | Diagnostic report (health / capacity / perf) built from `@diag/*` snippets. `--section`, `--brief`, `--for-agent`, `--no-connect`. |
@@ -260,7 +262,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\|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>`); `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

@@ -209,6 +209,8 @@ dbcli init --use-env-refs \
 | `blacklist` | n/a | `list` / `table` / `column` 子指令,從查詢結果中遮蔽敏感資料。 |
 | `check` | query-only+ | 僅 SQL(在 MySQL / MariaDB 最佳)。 |
 | `diff` | query-only+ | 僅 SQL。儲存 / 比較 schema snapshot。 |
+| `snapshot` | query-only+ | **(v1.25)** 僅 SQL。擷取結果指紋(`rowCount` + 每欄 null/distinct/min/max/sum + 順序無關 checksum)。`--out`(預設 `.dbcli/snapshots/snap-<ts>.json`)、`--rows`、`--stdout`、`--format`、`--no-limit`。作為 `assert --against` 的基準。 |
+| `assert` | query-only+ | **(v1.25)** 僅 SQL。驗證不變量;失敗時 exit 1,除非 `--no-fail`。`--expect "rows>0\|value==X\|col:c not null\|unique\|between a and b\|>= n"`、`--vs <query> --compare rows\|value`(對帳)、`--against <snapshot> --tolerance <pct>`。 |
 | `status` | query-only+ | 安全 JSON / 文字摘要(不含憑證)。 |
 | `inspect` | query-only+ | 唯讀脈絡快照(連線、權限、blacklist、物件、snippets、建議指令)。`--for-agent` / `--no-connect` / `--require-schema-cache`。支援 `--recovery`。 |
 | `report` | query-only+ | 以 `@diag/*` snippet 組成的診斷報告(health / capacity / perf)。`--section`、`--brief`、`--for-agent`、`--no-connect`。 |
@@ -219,7 +221,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\|copilot\|cursor>`）；`skill tasks list/show/plan` 提供 Agent Task Packs；`skill context` 提供 LLM 提示詞脈絡載荷。 |
+| `skill` | n/a | 產出 / 安裝 AI skill 文件（`--install <claude\|gemini\|antigravity\|copilot\|cursor>`）；`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

@@ -572,6 +572,50 @@ dbcli diff --against before.json --format json
 **Options:** `--snapshot <path>`, `--against <path>`, `--format <json|table>`
 **Permission:** query-only+
 
+### snapshot
+
+Capture a **result fingerprint** of a query (not schema): `rowCount` plus per-column
+aggregates (null/distinct counts, min/max/sum, an order-independent checksum) and a
+top-level `resultChecksum`. Blacklisted columns are masked at the source by QueryExecutor,
+so the fingerprint is safe to store and share. Use it as a baseline for `assert --against`.
+
+```bash
+dbcli snapshot "SELECT * FROM orders WHERE created_at >= '2026-05-01'"   # → .dbcli/snapshots/snap-<timestamp>.json
+dbcli snapshot @analytics/daily-revenue --out base.json                  # saved query → explicit path
+dbcli snapshot "SELECT status, count(*) FROM orders GROUP BY status" --stdout
+dbcli snapshot "SELECT * FROM orders" --rows --out full.json             # also store masked rows
+```
+
+**Options:** `--out <path>` (default `.dbcli/snapshots/snap-<timestamp>.json`), `--rows`, `--stdout`, `--format <json|table>`, `--no-limit`
+**Engines:** SQL only (PostgreSQL / MySQL / MariaDB)
+**Permission:** query-only+
+
+### assert
+
+Assert an **invariant** on a query result. Exits `1` on failure (so it composes in
+scripts / CI) unless `--no-fail` is given. Three modes (combinable):
+
+- `--expect <condition>` — inline check against the result:
+  - `rows > 0` / `rows == 1` … (row count vs operators `> >= < <= == !=`)
+  - `value == 5000` / `value == "done"` (single-cell result; project to one column)
+  - `col:email not null` · `col:id unique` · `col:amount between 0 and 100` · `col:age >= 18`
+- `--vs <query> --compare rows|value` — reconcile against a second query (cross-check totals/counts).
+- `--against <snapshot> --tolerance <pct>` — compare the current result fingerprint to a saved snapshot. `tolerance 0` requires an exact (order-independent) checksum match; `tolerance 0.01` allows ±1% drift on rowCount and each numeric column sum.
+
+```bash
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 0"
+dbcli assert "SELECT * FROM orders WHERE total < 0" --expect "rows == 0"     # no negative totals
+dbcli assert "SELECT email FROM users" --expect "col:email not null"
+dbcli assert "SELECT sum(amount) FROM ledger_a" --vs "SELECT sum(amount) FROM ledger_b" --compare value
+dbcli assert "SELECT * FROM orders" --against base.json --tolerance 0.01
+dbcli assert "SELECT count(*) FROM orders" --expect "value > 100" --no-fail   # report only, exit 0
+```
+
+**Options:** `--expect <condition>`, `--vs <query>`, `--compare <rows|value>` (default `value`), `--against <path>`, `--tolerance <pct>` (default `0`), `--no-fail`, `--format <json|table>`
+**Output:** `AssertVerdict` = `{ pass, checks: [{ name, expected, actual, pass }] }`
+**Engines:** SQL only (PostgreSQL / MySQL / MariaDB)
+**Permission:** query-only+
+
 ### status
 
 Show current configuration status (safe for AI agents, no credentials exposed).
@@ -1138,26 +1182,28 @@ dbcli migrate drop-enum status --execute --force
 
 ### 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.
+Emit `SKILL.md` (and the companion `reference.md`) to stdout, a file, or an
+AI-agent platform directory. The skill is the source of truth that lets
+Claude Code / Gemini / Antigravity / 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 gemini                 # install to ~/.gemini/skills/dbcli/ (being phased out)
+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)
 ```
 
 **Options:**
-- `--install <platform>` — `claude` | `gemini` | `copilot` | `cursor`. Writes `SKILL.md` plus `reference.md` next to it so the agent gets progressive disclosure.
+- `--install <platform>` — `claude` | `gemini` | `antigravity` | `copilot` | `cursor` | `codex` | `windsurf`. 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/`.
+- `claude` / `gemini` / `antigravity` install paths are user-global; `copilot` / `cursor` are repo-local under `.github/` / `.cursor/`.
+- `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.
 
 **Permission:** n/a.

package/dist/cli.mjs

@@ -81217,7 +81217,7 @@ var {
 // package.json
 var package_default = {
   name: "@carllee1983/dbcli",
-  version: "1.23.1",
+  version: "1.25.0",
   description: "Database CLI for AI agents",
   type: "module",
   publishConfig: {
@@ -87648,6 +87648,7 @@ function resolveSkillSource(lang) {
 var SUPPORTED_PLATFORMS = [
   "claude",
   "gemini",
+  "antigravity",
   "copilot",
   "cursor",
   "codex",
@@ -87715,6 +87716,8 @@ function getInstallPath(platform) {
       return path4.join(home, ".claude", "skills", "dbcli", "SKILL.md");
     case "gemini":
       return path4.join(home, ".gemini", "skills", "dbcli", "SKILL.md");
+    case "antigravity":
+      return path4.join(home, ".gemini", "antigravity-cli", "skills", "dbcli", "SKILL.md");
     case "codex":
       return path4.join(home, ".codex", "skills", "dbcli", "SKILL.md");
     case "copilot":
@@ -87755,7 +87758,7 @@ async function ensureDir(dirPath) {
   }
 }
 function registerSkillCommand(program2) {
-  const skill = program2.command("skill").description(t("skill.description")).option("--install <platform>", "Install to platform directory (claude, gemini, copilot, cursor, codex, windsurf)").option("--output <path>", "Write skill to file instead of stdout").addOption(new Option("--lang <lang>", "Source language for SKILL content").choices(["en", "zh-TW"]).default("en")).action(async (options) => {
+  const skill = program2.command("skill").description(t("skill.description")).option("--install <platform>", "Install to platform directory (claude, gemini, antigravity, copilot, cursor, codex, windsurf)").option("--output <path>", "Write skill to file instead of stdout").addOption(new Option("--lang <lang>", "Source language for SKILL content").choices(["en", "zh-TW"]).default("en")).action(async (options) => {
     try {
       await skillCommand(program2, options);
     } catch (error) {
@@ -90355,11 +90358,454 @@ function makeSavedQueryLoader2() {
   };
 }
 
+// src/commands/snapshot.ts
+init_adapters();
+init_config();
+import { join as join26 } from "path";
+init_validation();
+init_blacklist_validator();
+init_engine_hints();
+
+// src/core/result-snapshot/fingerprint.ts
+import { createHash as createHash2 } from "crypto";
+function sha256(input) {
+  return createHash2("sha256").update(input).digest("hex");
+}
+function isNumeric(values) {
+  return values.length > 0 && values.every((v) => typeof v === "number");
+}
+function buildColumn(name2, type, values) {
+  const nonNull = values.filter((v) => v !== null && v !== undefined);
+  const nullCount = values.length - nonNull.length;
+  const asStrings = nonNull.map((v) => String(v));
+  const distinctCount = new Set(asStrings).size;
+  const checksum = sha256(JSON.stringify([...asStrings].sort()));
+  const col = { name: name2, type, nullCount, distinctCount, checksum };
+  if (isNumeric(nonNull)) {
+    col.min = Math.min(...nonNull);
+    col.max = Math.max(...nonNull);
+    col.sum = nonNull.reduce((a, b) => a + b, 0);
+  } else if (nonNull.length > 0) {
+    const sorted = [...asStrings].sort();
+    col.min = sorted[0];
+    col.max = sorted[sorted.length - 1];
+  }
+  return col;
+}
+function buildFingerprint(result, opts) {
+  const columns = result.columnNames.map((name2, i) => buildColumn(name2, result.columnTypes?.[i] ?? "unknown", result.rows.map((r) => r[name2])));
+  for (const name2 of opts.redactedColumns ?? []) {
+    if (!columns.some((c2) => c2.name === name2)) {
+      columns.push({
+        name: name2,
+        type: "redacted",
+        nullCount: 0,
+        distinctCount: 0,
+        checksum: "",
+        redacted: true
+      });
+    }
+  }
+  const rowStrings = result.rows.map((r) => JSON.stringify(result.columnNames.map((n) => r[n]))).sort();
+  const snap = {
+    schemaVersion: 1,
+    query: opts.query ?? "",
+    engine: opts.engine ?? "postgresql",
+    createdAt: opts.createdAt ?? new Date().toISOString(),
+    rowCount: result.rowCount,
+    resultChecksum: sha256(JSON.stringify(rowStrings)),
+    columns
+  };
+  if (opts.includeRows)
+    snap.rows = result.rows;
+  return snap;
+}
+function compareAgainst(current, baseline, tolerance) {
+  const checks = [];
+  if (tolerance === 0) {
+    checks.push({
+      name: "resultChecksum",
+      expected: baseline.resultChecksum,
+      actual: current.resultChecksum,
+      pass: current.resultChecksum === baseline.resultChecksum
+    });
+    return checks;
+  }
+  const within = (a, b) => b === 0 ? a === 0 : Math.abs(a - b) / Math.abs(b) <= tolerance;
+  checks.push({
+    name: "rowCount",
+    expected: `${baseline.rowCount} \xB1${tolerance * 100}%`,
+    actual: String(current.rowCount),
+    pass: within(current.rowCount, baseline.rowCount)
+  });
+  for (const base of baseline.columns) {
+    if (base.sum === undefined)
+      continue;
+    const cur = current.columns.find((c2) => c2.name === base.name);
+    const curSum = cur?.sum;
+    checks.push({
+      name: `sum(${base.name})`,
+      expected: `${base.sum} \xB1${tolerance * 100}%`,
+      actual: String(curSum),
+      pass: curSum !== undefined && within(curSum, base.sum)
+    });
+  }
+  return checks;
+}
+
+// src/core/result-snapshot/types.ts
+class SnapshotVersionError extends Error {
+  code = "SNAPSHOT_VERSION_MISMATCH";
+  constructor(message) {
+    super(message);
+    this.name = "SnapshotVersionError";
+  }
+}
+
+// src/core/result-snapshot/serializer.ts
+async function writeSnapshot(path6, snap) {
+  await Bun.write(path6, JSON.stringify(snap, null, 2));
+}
+async function readSnapshot(path6) {
+  const file = Bun.file(path6);
+  if (!await file.exists()) {
+    const err = new Error(`Snapshot file not found: ${path6}`);
+    err.code = "SNAPSHOT_NOT_FOUND";
+    throw err;
+  }
+  const parsed = JSON.parse(await file.text());
+  if (parsed.schemaVersion !== 1) {
+    throw new SnapshotVersionError(`Unsupported snapshot schemaVersion ${parsed.schemaVersion} (expected 1)`);
+  }
+  return parsed;
+}
+
+// src/commands/snapshot.ts
+init_saved_queries();
+init_integration_helper();
+var ALLOWED_FORMATS12 = ["json", "table"];
+var SQL_SYSTEMS5 = ["postgresql", "mysql", "mariadb"];
+function requireSqlConnection9(connection) {
+  if (!SQL_SYSTEMS5.includes(connection.system)) {
+    throw new Error(`snapshot currently supports SQL engines only, got: ${connection.system}`);
+  }
+  return connection;
+}
+function pad(n) {
+  return String(n).padStart(2, "0");
+}
+function defaultSnapshotPath() {
+  const d = new Date;
+  const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  return join26(".dbcli", "snapshots", `snap-${stamp}.json`);
+}
+var snapshotCommand = new Command().name("snapshot").description("Capture a result fingerprint (rowCount + per-column aggregates) for later comparison").argument("<query>", "SQL string or @saved-query reference").option("--out <path>", "Write snapshot to this path (default: .dbcli/snapshots/snap-<timestamp>.json)").option("--rows", "Also include full (blacklist-masked) rows in the snapshot", false).option("--stdout", "Print snapshot JSON to stdout instead of writing a file", false).option("--format <format>", "Output format for --stdout: json (default) or table", "json").option("--no-limit", "Disable the automatic query-only LIMIT").action(async (query, options, command) => {
+  try {
+    validateFormat(options.format, ALLOWED_FORMATS12, "snapshot");
+    const configPath = resolveConfigPath(command, options);
+    const config = await configModule.read(configPath);
+    if (!config.connection) {
+      console.error("Database not configured. Run: dbcli init");
+      process.exit(1);
+    }
+    let sql = query;
+    if (query.startsWith("@")) {
+      const engine = mapSystemToEngine(config.connection.system);
+      const dirs = resolveSnippetDirs(process.cwd());
+      const snippets = await loadSnippets(dirs);
+      sql = resolveByName(snippets, query.slice(1), engine).query.sqlBody;
+    }
+    const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection9(config.connection));
+    await adapter.connect();
+    try {
+      const blacklistManager = new BlacklistManager(config);
+      const blacklistValidator = new BlacklistValidator(blacklistManager);
+      const executor3 = new QueryExecutor(adapter, config.permission, blacklistValidator, config, options);
+      const result = await executor3.execute(sql, { autoLimit: options.limit !== false });
+      const table = extractTableName(sql);
+      const redactedColumns = table ? blacklistManager.getBlacklistedColumns(table) : [];
+      const snap = buildFingerprint(result, {
+        includeRows: options.rows === true,
+        redactedColumns,
+        query: sql,
+        engine: config.connection.system
+      });
+      if (options.stdout === true) {
+        console.log(JSON.stringify(snap, null, 2));
+      } else {
+        const outPath = options.out ?? defaultSnapshotPath();
+        await writeSnapshot(outPath, snap);
+        console.error(`Snapshot saved to ${outPath} (${snap.rowCount} rows, ${snap.columns.length} columns)`);
+      }
+      await writeAuditEntry(config, "snapshot", options, {
+        success: true,
+        sql
+      });
+    } finally {
+      await adapter.disconnect();
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+      if (error instanceof ConnectionError)
+        error.hints.forEach((h) => console.error(`   Hint: ${h}`));
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/assert.ts
+init_adapters();
+init_config();
+init_validation();
+init_blacklist_validator();
+init_saved_queries();
+
+// src/core/assert/grammar.ts
+class AssertExpressionError extends Error {
+  code = "ASSERT_BAD_EXPRESSION";
+  constructor(input) {
+    super(`Cannot parse --expect "${input}". Examples: "rows > 0", "value == 5000", ` + `"col:email not null", "col:id unique", "col:amount between 0 and 100", "col:age >= 18".`);
+    this.name = "AssertExpressionError";
+  }
+}
+var OP = /(>=|<=|==|!=|>|<)/;
+function parseScalar2(raw) {
+  const s = raw.trim();
+  if (/^".*"$/.test(s) || /^'.*'$/.test(s))
+    return s.slice(1, -1);
+  const n = Number(s);
+  return Number.isNaN(n) ? s : n;
+}
+function parseExpect(input) {
+  const s = input.trim();
+  const rows = s.match(new RegExp(`^rows\\s*${OP.source}\\s*(\\d+)$`));
+  if (rows)
+    return { kind: "rows", op: rows[1], value: parseInt(rows[2], 10) };
+  const value = s.match(new RegExp(`^value\\s*${OP.source}\\s*(.+)$`));
+  if (value)
+    return { kind: "value", op: value[1], value: parseScalar2(value[2]) };
+  const col = s.match(/^col:(\w+)\s+(.+)$/);
+  if (col) {
+    const column = col[1];
+    const rest = col[2].trim();
+    if (/^not\s+null$/i.test(rest))
+      return { kind: "col", column, pred: { type: "notNull" } };
+    if (/^unique$/i.test(rest))
+      return { kind: "col", column, pred: { type: "unique" } };
+    const between = rest.match(/^between\s+(-?\d+(?:\.\d+)?)\s+and\s+(-?\d+(?:\.\d+)?)$/i);
+    if (between) {
+      return {
+        kind: "col",
+        column,
+        pred: { type: "between", low: Number(between[1]), high: Number(between[2]) }
+      };
+    }
+    const cmp = rest.match(new RegExp(`^${OP.source}\\s*(.+)$`));
+    if (cmp)
+      return {
+        kind: "col",
+        column,
+        pred: { type: "cmp", op: cmp[1], value: parseScalar2(cmp[2]) }
+      };
+  }
+  throw new AssertExpressionError(input);
+}
+
+// src/core/assert/evaluator.ts
+class AssertShapeError extends Error {
+  code = "ASSERT_SHAPE_MISMATCH";
+  constructor(message) {
+    super(message);
+    this.name = "AssertShapeError";
+  }
+}
+function compare(a, op, b) {
+  switch (op) {
+    case ">":
+      return a > b;
+    case ">=":
+      return a >= b;
+    case "<":
+      return a < b;
+    case "<=":
+      return a <= b;
+    case "==":
+      return a === b;
+    case "!=":
+      return a !== b;
+  }
+}
+function firstScalar(result) {
+  if (result.columnNames.length !== 1) {
+    throw new AssertShapeError(`value assertion needs a single-column result, got ${result.columnNames.length} columns. Project to one column.`);
+  }
+  if (result.rows.length === 0)
+    return null;
+  const v = result.rows[0][result.columnNames[0]];
+  return v === null || v === undefined ? null : v;
+}
+function evaluateExpect(node, result) {
+  if (node.kind === "rows") {
+    const actual = result.rowCount;
+    return {
+      name: "rows",
+      expected: `rows ${node.op} ${node.value}`,
+      actual: String(actual),
+      pass: compare(actual, node.op, node.value)
+    };
+  }
+  if (node.kind === "value") {
+    const actual = firstScalar(result);
+    return {
+      name: "value",
+      expected: `value ${node.op} ${node.value}`,
+      actual: String(actual),
+      pass: actual !== null && compare(actual, node.op, node.value)
+    };
+  }
+  const { column, pred } = node;
+  const values = result.rows.map((r) => r[column]);
+  const nonNull = values.filter((v) => v !== null && v !== undefined);
+  if (pred.type === "notNull") {
+    const nullCount = values.length - nonNull.length;
+    return {
+      name: `col:${column} not null`,
+      expected: "0 nulls",
+      actual: `${nullCount} nulls`,
+      pass: nullCount === 0
+    };
+  }
+  if (pred.type === "unique") {
+    const distinct = new Set(nonNull.map((v) => String(v))).size;
+    return {
+      name: `col:${column} unique`,
+      expected: `${nonNull.length} distinct`,
+      actual: `${distinct} distinct`,
+      pass: distinct === nonNull.length
+    };
+  }
+  if (pred.type === "between") {
+    const bad2 = nonNull.filter((v) => typeof v !== "number" || v < pred.low || v > pred.high);
+    return {
+      name: `col:${column} between ${pred.low} and ${pred.high}`,
+      expected: "0 out of range",
+      actual: `${bad2.length} out of range`,
+      pass: bad2.length === 0
+    };
+  }
+  const bad = nonNull.filter((v) => !compare(v, pred.op, pred.value));
+  return {
+    name: `col:${column} ${pred.op} ${pred.value}`,
+    expected: "0 violations",
+    actual: `${bad.length} violations`,
+    pass: bad.length === 0
+  };
+}
+function compareVs(a, b, mode) {
+  if (mode === "rows") {
+    return {
+      name: "vs:rows",
+      expected: String(b.rowCount),
+      actual: String(a.rowCount),
+      pass: a.rowCount === b.rowCount
+    };
+  }
+  const av = firstScalar(a);
+  const bv = firstScalar(b);
+  return {
+    name: "vs:value",
+    expected: String(bv),
+    actual: String(av),
+    pass: av !== null && bv !== null && av === bv
+  };
+}
+
+// src/commands/assert.ts
+init_integration_helper();
+var ALLOWED_FORMATS13 = ["json", "table"];
+var SQL_SYSTEMS6 = ["postgresql", "mysql", "mariadb"];
+function requireSqlConnection10(connection) {
+  if (!SQL_SYSTEMS6.includes(connection.system)) {
+    throw new Error(`assert currently supports SQL engines only, got: ${connection.system}`);
+  }
+  return connection;
+}
+var assertCommand = new Command().name("assert").description("Assert an invariant on a query result (exit 1 on failure unless --no-fail)").argument("<query>", "SQL string or @saved-query reference").option("--expect <condition>", 'e.g. "rows > 0", "value == 5000", "col:email not null"').option("--vs <query>", "Second SQL/@saved query for reconciliation").option("--compare <mode>", "For --vs: rows | value (default value)", "value").option("--against <path>", "Compare current result fingerprint against a saved snapshot").option("--tolerance <pct>", "For --against: allowed relative drift, e.g. 0.01 (default 0)", (v) => parseFloat(v), 0).option("--no-fail", "Always exit 0; report pass/fail in output only").option("--format <format>", "Output format: json (default) or table", "json").action(async (query, options, command) => {
+  try {
+    validateFormat(options.format, ALLOWED_FORMATS13, "assert");
+    if (!options.expect && !options.vs && !options.against) {
+      console.error("Specify one of --expect, --vs, or --against");
+      process.exit(1);
+    }
+    const configPath = resolveConfigPath(command, options);
+    const config = await configModule.read(configPath);
+    if (!config.connection) {
+      console.error("Database not configured. Run: dbcli init");
+      process.exit(1);
+    }
+    const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection10(config.connection));
+    await adapter.connect();
+    let verdict;
+    try {
+      const blacklistManager = new BlacklistManager(config);
+      const blacklistValidator = new BlacklistValidator(blacklistManager);
+      const executor3 = new QueryExecutor(adapter, config.permission, blacklistValidator, config, options);
+      const engine = mapSystemToEngine(config.connection.system);
+      const dirs = resolveSnippetDirs(process.cwd());
+      const snippets = await loadSnippets(dirs);
+      const resolveSql = (q) => q.startsWith("@") ? resolveByName(snippets, q.slice(1), engine).query.sqlBody : q;
+      const result = await executor3.execute(resolveSql(query), { autoLimit: true });
+      const checks = [];
+      if (options.expect)
+        checks.push(evaluateExpect(parseExpect(options.expect), result));
+      if (options.vs) {
+        const other = await executor3.execute(resolveSql(options.vs), {
+          autoLimit: true
+        });
+        checks.push(compareVs(result, other, options.compare ?? "value"));
+      }
+      if (options.against) {
+        const baseline = await readSnapshot(options.against);
+        const current = buildFingerprint(result, {
+          query: resolveSql(query),
+          engine: config.connection.system
+        });
+        checks.push(...compareAgainst(current, baseline, options.tolerance));
+      }
+      verdict = { pass: checks.every((c2) => c2.pass), checks };
+      await writeAuditEntry(config, "assert", options, {
+        success: verdict.pass,
+        sql: query
+      });
+    } finally {
+      await adapter.disconnect();
+    }
+    if (options.format === "json") {
+      console.log(JSON.stringify(verdict, null, 2));
+    } else {
+      for (const c2 of verdict.checks) {
+        console.log(`${c2.pass ? "PASS" : "FAIL"}  ${c2.name}  expected=${c2.expected} actual=${c2.actual}`);
+      }
+      console.log(`
+Verdict: ${verdict.pass ? "PASS" : "FAIL"}`);
+    }
+    process.exit(verdict.pass || options.fail === false ? 0 : 1);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+      if (error instanceof ConnectionError)
+        error.hints.forEach((h) => console.error(`   Hint: ${h}`));
+    }
+    process.exit(1);
+  }
+});
+
 // src/commands/recovery.ts
 init_message_loader();
 init_validation();
 init_recovery();
-var ALLOWED_FORMATS12 = ["json", "markdown"];
+var ALLOWED_FORMATS14 = ["json", "markdown"];
 function parseCode(value) {
   const normalized = value.trim();
   if (!RECOVERY_CODES.includes(normalized)) {
@@ -90395,7 +90841,7 @@ var recoveryCommand = new Command().name("recovery").description(t("recovery.des
     const forAgent = options.forAgent === true;
     const format = forAgent ? "json" : options.format;
     const brief = forAgent || options.brief === true;
-    validateFormat(format, ALLOWED_FORMATS12, "recovery");
+    validateFormat(format, ALLOWED_FORMATS14, "recovery");
     if (options.list === true) {
       if (format === "markdown") {
         console.log(renderCodeList());
@@ -90572,7 +91018,7 @@ function looksLikeSavedEnvelope(x) {
 init_next_step();
 init_next_step_schema();
 init_validation();
-var ALLOWED_FORMATS13 = ["json", "markdown"];
+var ALLOWED_FORMATS15 = ["json", "markdown"];
 var ALLOWED_TIERS = ["readonly-cmd", "write-cmd"];
 
 class RecoverCliError extends Error {
@@ -90724,7 +91170,7 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
     }
     const explicitFormat = options.format;
     const format = explicitFormat ?? (options.apply === true || options.next === true ? "json" : "markdown");
-    validateFormat(format, ALLOWED_FORMATS13, "recover");
+    validateFormat(format, ALLOWED_FORMATS15, "recover");
     let allowWrite = "none";
     if (options.next !== true) {
       const allowWriteRaw = options.allowWrite;
@@ -90791,14 +91237,14 @@ var recoverCommand = new Command().name("recover").description("Inspect or apply
 
 // src/commands/audit.ts
 import { rm as rm3, stat as stat7 } from "fs/promises";
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 init_message_loader();
 init_validation();
 init_config();
 init_config_binding();
 init_reader();
 init_integration_helper();
-var ALLOWED_FORMATS14 = ["table", "json"];
+var ALLOWED_FORMATS16 = ["table", "json"];
 var DEFAULT_TAIL_N = 10;
 var MAX_TAIL_N = 1e4;
 var SHORT_ID_LEN = 8;
@@ -90807,8 +91253,8 @@ var PREFIX_MIN = 4;
 async function resolveAuditPaths(configPath, config) {
   const storagePath = await resolveConfigStoragePath(configPath);
   const connName = config.effectiveConnectionName || getGlobalConnectionName() || "default";
-  const auditDir = join26(storagePath, ".dbcli", "audit");
-  const auditFile = join26(auditDir, `${connName}.jsonl`);
+  const auditDir = join27(storagePath, ".dbcli", "audit");
+  const auditFile = join27(auditDir, `${connName}.jsonl`);
   return { auditDir, connectionName: connName, auditFile };
 }
 function isAuditDisabled(config) {
@@ -90992,13 +91438,13 @@ async function statAuditFile(file) {
   }
 }
 var auditCommand = new Command("audit").description(t("audit.description"));
-auditCommand.command("tail").description(t("audit.tail.description")).option("--n <number>", `Number of recent entries to show (1..${MAX_TAIL_N})`, String(DEFAULT_TAIL_N)).option("--all", "Merge entries across all connections", false).option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim each entry to ts/command/target/success", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
+auditCommand.command("tail").description(t("audit.tail.description")).option("--n <number>", `Number of recent entries to show (1..${MAX_TAIL_N})`, String(DEFAULT_TAIL_N)).option("--all", "Merge entries across all connections", false).option("--format <format>", `Output format: ${ALLOWED_FORMATS16.join(" | ")} (default: table)`, "table").option("--brief", "Trim each entry to ts/command/target/success", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
   const forAgent = options.forAgent === true;
   const format = forAgent ? "json" : options.format;
   const briefSource = command.getOptionValueSource("brief");
   const briefExplicit = briefSource !== undefined && briefSource !== "default";
   const brief = briefExplicit ? options.brief === true : forAgent;
-  validateFormat(format, ALLOWED_FORMATS14, "audit tail");
+  validateFormat(format, ALLOWED_FORMATS16, "audit tail");
   const n = parseTailN(options.n);
   const configPath = resolveConfigPath(command, options);
   const config = await configModule.read(configPath);
@@ -91041,7 +91487,7 @@ auditCommand.command("tail").description(t("audit.tail.description")).option("--
     console.log(renderTailTable(tail));
   }
 });
-auditCommand.command("show [id]").description(t("audit.show.description")).option("--all", "Search across all connections", false).option("--recovery-ref <ref>", "Look up by entry.recovery_ref (exact match)").option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim metadata + redacted_query", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (id, options, command) => {
+auditCommand.command("show [id]").description(t("audit.show.description")).option("--all", "Search across all connections", false).option("--recovery-ref <ref>", "Look up by entry.recovery_ref (exact match)").option("--format <format>", `Output format: ${ALLOWED_FORMATS16.join(" | ")} (default: table)`, "table").option("--brief", "Trim metadata + redacted_query", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (id, options, command) => {
   if (id && options.recoveryRef) {
     console.error(t("audit.show_mutex_violation"));
     process.exit(1);
@@ -91055,7 +91501,7 @@ auditCommand.command("show [id]").description(t("audit.show.description")).optio
   const briefSource = command.getOptionValueSource("brief");
   const briefExplicit = briefSource !== undefined && briefSource !== "default";
   const brief = briefExplicit ? options.brief === true : forAgent;
-  validateFormat(format, ALLOWED_FORMATS14, "audit show");
+  validateFormat(format, ALLOWED_FORMATS16, "audit show");
   const configPath = resolveConfigPath(command, options);
   const config = await configModule.read(configPath);
   if (isAuditDisabled(config))
@@ -91197,13 +91643,13 @@ auditCommand.command("clear").description(t("audit.clear.description")).option("
 `);
   process.exit(0);
 });
-auditCommand.command("health").description(t("audit.health.description")).option("--format <format>", `Output format: ${ALLOWED_FORMATS14.join(" | ")} (default: table)`, "table").option("--brief", "Trim to enabled / lastWrite / rotationUsage", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
+auditCommand.command("health").description(t("audit.health.description")).option("--format <format>", `Output format: ${ALLOWED_FORMATS16.join(" | ")} (default: table)`, "table").option("--brief", "Trim to enabled / lastWrite / rotationUsage", false).option("--no-brief", "Disable brief mode (override --for-agent default)").option("--for-agent", "Shortcut for --format json --brief", false).action(async (options, command) => {
   const forAgent = options.forAgent === true;
   const format = forAgent ? "json" : options.format;
   const briefSource = command.getOptionValueSource("brief");
   const briefExplicit = briefSource !== undefined && briefSource !== "default";
   const brief = briefExplicit ? options.brief === true : forAgent;
-  validateFormat(format, ALLOWED_FORMATS14, "audit health");
+  validateFormat(format, ALLOWED_FORMATS16, "audit health");
   const configPath = resolveConfigPath(command, options);
   const config = await configModule.read(configPath);
   const logger = await getAuditLogger(config, configPath);
@@ -91235,15 +91681,15 @@ init_config_binding();
 init_schema_path();
 init_config();
 init_integration_helper();
-import { join as join27 } from "path";
+import { join as join28 } from "path";
 import { resolveSrv as resolveSrv2 } from "dns/promises";
-function requireSqlConnection9(connection) {
+function requireSqlConnection11(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
   return connection;
 }
-var ALLOWED_FORMATS15 = ["text", "json"];
+var ALLOWED_FORMATS17 = ["text", "json"];
 var SENSITIVE_PATTERNS = [
   "password",
   "passwd",
@@ -91315,7 +91761,7 @@ var runDoctorChecks = {
     }
   },
   async checkConfigExists(configPath, existsFn) {
-    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join27(configPath, "config.json")).exists();
+    const exists = existsFn ? await existsFn(configPath) : await Bun.file(configPath).exists() || await Bun.file(join28(configPath, "config.json")).exists();
     return {
       group: "Configuration",
       label: "Config exists",
@@ -91472,7 +91918,7 @@ var runDoctorChecks = {
   async checkV2Config(configPath) {
     const results = [];
     const storagePath = await resolveConfigStoragePath(configPath);
-    const configFile = Bun.file(join27(storagePath, "config.json"));
+    const configFile = Bun.file(join28(storagePath, "config.json"));
     if (!await configFile.exists())
       return results;
     let raw;
@@ -91512,7 +91958,7 @@ var runDoctorChecks = {
     }
     for (const [name2, conn] of Object.entries(config.connections)) {
       if (conn.envFile) {
-        const envPath = join27(storagePath, conn.envFile);
+        const envPath = join28(storagePath, conn.envFile);
         const exists = await Bun.file(envPath).exists();
         results.push({
           group: "Configuration",
@@ -91657,7 +92103,7 @@ async function collectElasticsearchDoctorResults(config) {
   return results;
 }
 var doctorCommand = new Command("doctor").description("Run diagnostic checks on dbcli configuration, environment, and connection").option("--format <type>", "Output format: text, json", "text").action(async (options) => {
-  validateFormat(options.format, ALLOWED_FORMATS15, "doctor");
+  validateFormat(options.format, ALLOWED_FORMATS17, "doctor");
   const logger = getLogger();
   const results = [];
   const configPath = resolveConfigPath(doctorCommand);
@@ -91703,7 +92149,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
             blacklistedColumns
           }));
         } else {
-          const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection9(config.connection));
+          const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection11(config.connection));
           await adapter.connect();
           results.push({
             group: "Connection & Data",
@@ -91731,7 +92177,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
           }
           try {
             const schemaConnName = await getSchemaIsolationConnectionName(configPath);
-            const indexPath = join27(resolveSchemaPath(storagePath, schemaConnName), "index.json");
+            const indexPath = join28(resolveSchemaPath(storagePath, schemaConnName), "index.json");
             const indexFile = Bun.file(indexPath);
             let indexParsed = null;
             if (await indexFile.exists()) {
@@ -91785,7 +92231,7 @@ var doctorCommand = new Command("doctor").description("Run diagnostic checks on
 
 // src/commands/completion.ts
 init_colors();
-import { join as join28 } from "path";
+import { join as join29 } from "path";
 import { homedir as homedir3 } from "os";
 function extractCommands(program2) {
   return program2.commands.map((cmd) => ({
@@ -91887,11 +92333,11 @@ function getInstallPath2(shell) {
   const home = homedir3();
   switch (shell) {
     case "bash":
-      return join28(home, ".bashrc");
+      return join29(home, ".bashrc");
     case "zsh":
-      return join28(home, ".zshrc");
+      return join29(home, ".zshrc");
     case "fish":
-      return join28(home, ".config", "fish", "completions", "dbcli.fish");
+      return join29(home, ".config", "fish", "completions", "dbcli.fish");
     default:
       throw new Error(`Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
   }
@@ -91911,7 +92357,7 @@ var MARKER_END = "# <<< dbcli completion <<<";
 async function installCompletion(shell, script) {
   const targetPath = getInstallPath2(shell);
   if (shell === "fish") {
-    const dir = join28(homedir3(), ".config", "fish", "completions");
+    const dir = join29(homedir3(), ".config", "fish", "completions");
     await Bun.$`mkdir -p ${dir}`.quiet();
     await Bun.file(targetPath).write(script);
     console.log(colors.success(`\u2713 Fish completion installed to ${targetPath}`));
@@ -92144,7 +92590,7 @@ ${t("upgrade.failed")}`));
 init_config();
 init_adapters();
 import { createInterface as createInterface3 } from "readline";
-import { join as join29 } from "path";
+import { join as join30 } from "path";
 import { homedir as homedir4 } from "os";
 
 // src/core/repl/types.ts
@@ -93066,13 +93512,13 @@ async function runEsShell(configPath) {
 }
 
 // src/commands/shell.ts
-function requireSqlConnection10(connection) {
+function requireSqlConnection12(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
   return connection;
 }
-var HISTORY_PATH = join29(homedir4(), ".dbcli_history");
+var HISTORY_PATH = join30(homedir4(), ".dbcli_history");
 var MONGO_COMPLETION_EAGER_THRESHOLD = 20;
 async function populateMongoColumns(mongoAdapter, collectionNames, threshold = MONGO_COMPLETION_EAGER_THRESHOLD) {
   const columnsByTable = {};
@@ -93109,7 +93555,7 @@ async function runShell(options, configPath) {
   const connectionOpts = config.connection;
   const mongoInner = isMongoDB ? AdapterFactory.createMongoDBAdapter(connectionOpts) : null;
   const redisInner = isRedis ? AdapterFactory.createRedisAdapter(connectionOpts, config.blacklist?.tables ?? [], config.redis?.mask ?? []) : null;
-  const adapter = isMongoDB ? new MongoShellAdapter(mongoInner) : isRedis ? new RedisShellAdapter(redisInner) : AdapterFactory.createSqlAdapter(requireSqlConnection10(connectionOpts));
+  const adapter = isMongoDB ? new MongoShellAdapter(mongoInner) : isRedis ? new RedisShellAdapter(redisInner) : AdapterFactory.createSqlAdapter(requireSqlConnection12(connectionOpts));
   try {
     await adapter.connect();
   } catch (error) {
@@ -93836,7 +94282,7 @@ class DDLExecutor {
   }
 }
 // src/commands/migrate.ts
-function requireSqlConnection11(connection) {
+function requireSqlConnection13(connection) {
   if (!["postgresql", "mysql", "mariadb"].includes(connection.system)) {
     throw new Error(`This command requires a SQL connection, got: ${connection.system}`);
   }
@@ -93860,7 +94306,7 @@ async function runDDL(operation, opts) {
     console.error("\u6B64\u547D\u4EE4\u76EE\u524D\u4E0D\u652F\u63F4 Elasticsearch\uFF1B\u5982\u9700\u5EFA\u7ACB\u7D22\u5F15\u6216\u8ABF\u6574 mapping\uFF0C\u8ACB\u6539\u7528\u5916\u90E8\u5DE5\u5177");
     process.exit(1);
   }
-  const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection11(config.connection));
+  const adapter = AdapterFactory.createSqlAdapter(requireSqlConnection13(config.connection));
   const isDryRun = !opts.execute;
   if (!isDryRun) {
     await adapter.connect();
@@ -94071,7 +94517,7 @@ init_config();
 init_errors();
 init_message_loader();
 init_config_binding();
-import { join as join30 } from "path";
+import { join as join31 } from "path";
 async function switchDefault(configPath, name2, config) {
   if (!config.connections[name2]) {
     const available = Object.keys(config.connections).join(", ");
@@ -94094,7 +94540,7 @@ function listConnectionsForDisplay(config) {
 }
 async function ensureV2Config(configPath) {
   const storagePath = await resolveConfigStoragePath(configPath);
-  const configFile = Bun.file(join30(storagePath, "config.json"));
+  const configFile = Bun.file(join31(storagePath, "config.json"));
   const legacyFile = Bun.file(configPath);
   if (!await configFile.exists() && !await legacyFile.exists()) {
     throw new ConfigError(t("init.config_not_found"));
@@ -94158,7 +94604,7 @@ var useCommand = new Command("use").description("Switch or display the default d
 
 // src/cli.ts
 init_config();
-import { join as join31 } from "path";
+import { join as join32 } from "path";
 var _bgVersionCheckResult;
 function shouldSkipBackgroundChecks() {
   return process.env.DBCLI_NO_UPDATE_CHECK === "1" || process.env.DBCLI_NO_UPDATE_CHECK === "true" || false;
@@ -94187,7 +94633,7 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
       try {
         let cache = null;
         try {
-          const cacheFile = Bun.file(join31(configPath, "version-check.json"));
+          const cacheFile = Bun.file(join32(configPath, "version-check.json"));
           if (await cacheFile.exists()) {
             cache = await cacheFile.json();
           }
@@ -94307,6 +94753,8 @@ program2.addCommand(migrateCommand);
 program2.addCommand(useCommand);
 program2.addCommand(queriesCommand);
 program2.addCommand(explainCommand);
+program2.addCommand(snapshotCommand);
+program2.addCommand(assertCommand);
 if (!process.argv.slice(2).length) {
   program2.outputHelp();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.23.1",
+  "version": "1.25.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {