@carllee1983/dbcli 1.39.1 → 1.39.2

package/dist/core.mjs

@@ -17423,6 +17423,7 @@ class SessionIdService {
 
 // src/core/config-binding.ts
 import { createHash } from "crypto";
+import { mkdir as mkdir4, unlink } from "fs/promises";
 import { homedir } from "os";
 import { basename, join as join3, resolve } from "path";
 var BINDING_FILE_NAME = "config.json";
@@ -17467,8 +17468,8 @@ async function writeProjectBinding(projectPath, storagePath = getProjectStorageP
       createdAt: new Date().toISOString()
     }
   };
-  await Bun.$`mkdir -p ${projectPath}`;
-  await Bun.$`mkdir -p ${storagePath}`;
+  await mkdir4(projectPath, { recursive: true });
+  await mkdir4(storagePath, { recursive: true });
   await Bun.file(join3(projectPath, BINDING_FILE_NAME)).write(JSON.stringify(binding, null, 2));
   return binding;
 }
@@ -21624,6 +21625,7 @@ async function loadEnvFile(filePath) {
 
 // src/core/config-v2.ts
 import { join as join4 } from "path";
+import { mkdir as mkdir5, rename as rename3 } from "fs/promises";
 function detectConfigVersion(raw) {
   if (typeof raw === "object" && raw !== null && "version" in raw && raw.version === 2 && "connections" in raw) {
     return 2;
@@ -21667,10 +21669,10 @@ async function writeV2Config(path, config) {
   const storagePath = await resolveConfigStoragePath(path);
   const configPath = join4(storagePath, "config.json");
   const tmpPath = `${configPath}.tmp`;
-  await Bun.$`mkdir -p ${storagePath}`;
+  await mkdir5(storagePath, { recursive: true });
   const json = JSON.stringify(config, null, 2);
   await Bun.write(tmpPath, json);
-  await Bun.$`mv -f ${tmpPath} ${configPath}`;
+  await rename3(tmpPath, configPath);
 }
 function listConnections(config) {
   return Object.entries(config.connections).map(([name, conn]) => {
@@ -21689,6 +21691,7 @@ function listConnections(config) {
 
 // src/core/config.ts
 import { join as join9 } from "path";
+import { mkdir as mkdir6 } from "fs/promises";
 var _globalConnectionName;
 function getGlobalConnectionName() {
   return _globalConnectionName;
@@ -21898,7 +21901,7 @@ var configModule = {
         isDirectory = false;
       }
       if (isDirectory || path.endsWith(".dbcli") || path === storagePath && isDirectory) {
-        await Bun.$`mkdir -p ${storagePath}`;
+        await mkdir6(storagePath, { recursive: true });
         const hasEnvReferences = isEnvReference(config.connection.password);
         if (hasEnvReferences) {
           const configPath = join9(storagePath, "config.json");

package/package.json

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

package/plugins/dbcli-agent/.codex-plugin/plugin.json

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

package/plugins/dbcli-agent/skills/dbcli/SKILL.md

@@ -18,7 +18,16 @@ the CLI package has not been installed globally.
 
 1. `dbcli blacklist list` — confirm sensitive-data boundaries.
 2. `dbcli schema <object> --format json` — confirm real column/field names. **Never guess.**
-3. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm.
+3. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm. Redis
+   `query` has **no `--dry-run`** (see **Redis**); Elasticsearch is **read-only**.
+
+**`update` / `delete` `--where` is equality-only (SQL).** It accepts **only** `col=val` or
+`col1=v1 AND col2=v2`. A comparison / pattern operator (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+is a **parse error**; worse, `OR` is **silently swallowed into the value** — `a=1 OR b=2`
+parses as `a = "1 OR b=2"` and matches the wrong rows (or none). For a range or compound
+condition, first `query` / `export` the target rows' primary keys, then run one
+`update` / `delete --where "id=<pk>"` per key — or escalate to a human. (MongoDB `--where`
+takes a full JSON filter and is exempt.)
 
 > `report` and `guide` already embed an `inspect` snapshot — you do **not** need to run
 > `dbcli inspect` first. Run `dbcli inspect --for-agent` manually only when you want the
@@ -364,12 +373,18 @@ without changing the default. `--recovery` is honoured by `query`, `q`, `insert`
   → `data-admin`. A command not in the whitelist is refused.
 - **No `--dry-run` for Redis `query`** — write safety comes from the permission gate and key
   blacklist (matching reads/writes are rejected). To preview a delete, use `delete <key> --dry-run`.
-- `database` is the logical DB index (default `0`). `dbcli blacklist add 'secrets:*'`
+- `database` is the logical DB index (default `0`). `dbcli blacklist table add 'secrets:*'`
   registers a key glob; an optional `redis.mask` block masks values on read. Size guards
   (SCAN/HGETALL truncation, `--no-limit` to bypass) and masking details: reference.md Redis section.
 
 ## Elasticsearch
 
+**dbcli is read-only against Elasticsearch — `insert` / `update` / `delete` are not supported.**
+
+```bash
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
+```
+
 - `query` takes a DSL (JSON body) or Lucene query string; `--collection <index>` is required.
 - **Supported:** `init`, `list` (indices with doc count), `schema [index]` (flattened mapping),
   `query`, `export` (v1.22), `shell` (v1.22), `status`, `use`, `doctor`. **Not supported:**

package/plugins/dbcli-agent/skills/dbcli/reference.md

@@ -249,6 +249,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
 - `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
+- `--verify` — run the snippet's verification assertions after execution (only if the snippet defines them)
 
 **Permission:** query-only+
 
@@ -474,9 +475,10 @@ Insert data into a table.
 dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
 dbcli insert users --data '{"name":"Alice"}' --dry-run
 dbcli insert users --data '{"name":"Alice"}' --force
+dbcli insert users --data '{"name":"Alice"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--data <json>`, `--dry-run`, `--force`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -486,11 +488,19 @@ Update existing data.
 ```bash
 dbcli update users --where "id=1" --set '{"name":"Bob"}'
 dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
+> **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
+> `col1=v1 AND col2=v2`. Comparison / pattern operators (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+> raise a parse error, and `OR` is **silently folded into the value** (`a=1 OR b=2` parses as
+> `a = "1 OR b=2"`, matching nothing intended). For ranges or compound predicates, select the
+> target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
+> (MongoDB `--where` accepts a full JSON filter and is exempt.)
+
 ### delete
 
 Delete data from a table.
@@ -499,9 +509,10 @@ Delete data from a table.
 dbcli delete users --where "id=1"
 dbcli delete users --where "id=1" --dry-run
 dbcli delete users --where "id=1" --force
+dbcli delete users --where "id=1" --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -521,7 +532,7 @@ dbcli export orders --format csv --output orders.csv      # index name as query
 dbcli export orders --no-limit --format jsonl             # scroll the whole index in batches
 ```
 
-**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--index <name>` (Elasticsearch), `--no-limit` (Elasticsearch full-index scroll)
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
@@ -892,6 +903,7 @@ Boundaries:
 | `--from <path>` | Read the envelope from this file instead of `.dbcli/last-recovery.json`. Accepts raw `RecoveryEnvelope` or `SavedRecoveryEnvelope`. | — |
 | `--allow-write <tier>` | Open the risk gate. Values: `readonly-cmd` (local-side writes) \| `write-cmd` (database writes). | `none` |
 | `--no-verify` | Skip the verify step appended after a successful `--apply`. | off (verify runs by default) |
+| `--write-verification-artifact` | After a successful `--apply`, persist a secret-free `VerificationArtifact` JSON under `.dbcli/verification/`. | off |
 | `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
 
 #### Plan source resolution
@@ -1650,6 +1662,7 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 **Options:**
 - `--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`.
+- `--lang <en|zh-TW>` — source language for the emitted SKILL content (default `en`). It selects `assets/SKILL.md` vs `assets/SKILL.zh-TW.md`; the install/output filename stays `SKILL.md` regardless.
 
 **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.
@@ -1662,6 +1675,21 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 
 **Permission:** n/a.
 
+### skill context
+
+Emit an AI-friendly snapshot of the connected database's schema and saved-query snippets (blacklist-filtered) so an agent can be primed with the current context.
+
+```bash
+dbcli skill context                      # XML (default)
+dbcli skill context --format json
+dbcli skill context --format markdown
+```
+
+**Options:**
+- `--format <xml|json|markdown>` — output format (default: `xml`)
+
+**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -2201,7 +2229,7 @@ Rewrites emit a `REDIS_SIZE_REWRITE` warning; truncations emit `REDIS_SIZE_TRUNC
 Blacklist rules are enforced as **Redis-native key globs** (`*`, `?`, `[abc]`, `[a-z]`):
 
 ```bash
-dbcli blacklist add 'secrets:*'          # register a key-glob rule
+dbcli blacklist table add 'secrets:*'    # register a key-glob rule
 dbcli query "GET secrets:api_key"        # → BlacklistRejection (exit non-zero)
 dbcli query "MGET safe:k secrets:api"    # → rejected (any matching key fails the whole command)
 dbcli query "KEYS secrets:*"             # → rejected (pattern overlaps a rule)

package/skills/dbcli/SKILL.md

@@ -18,7 +18,16 @@ the CLI package has not been installed globally.
 
 1. `dbcli blacklist list` — confirm sensitive-data boundaries.
 2. `dbcli schema <object> --format json` — confirm real column/field names. **Never guess.**
-3. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm.
+3. All writes: `--dry-run` (SQL/Mongo) → run → `query` read-back to confirm. Redis
+   `query` has **no `--dry-run`** (see **Redis**); Elasticsearch is **read-only**.
+
+**`update` / `delete` `--where` is equality-only (SQL).** It accepts **only** `col=val` or
+`col1=v1 AND col2=v2`. A comparison / pattern operator (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+is a **parse error**; worse, `OR` is **silently swallowed into the value** — `a=1 OR b=2`
+parses as `a = "1 OR b=2"` and matches the wrong rows (or none). For a range or compound
+condition, first `query` / `export` the target rows' primary keys, then run one
+`update` / `delete --where "id=<pk>"` per key — or escalate to a human. (MongoDB `--where`
+takes a full JSON filter and is exempt.)
 
 > `report` and `guide` already embed an `inspect` snapshot — you do **not** need to run
 > `dbcli inspect` first. Run `dbcli inspect --for-agent` manually only when you want the
@@ -364,12 +373,18 @@ without changing the default. `--recovery` is honoured by `query`, `q`, `insert`
   → `data-admin`. A command not in the whitelist is refused.
 - **No `--dry-run` for Redis `query`** — write safety comes from the permission gate and key
   blacklist (matching reads/writes are rejected). To preview a delete, use `delete <key> --dry-run`.
-- `database` is the logical DB index (default `0`). `dbcli blacklist add 'secrets:*'`
+- `database` is the logical DB index (default `0`). `dbcli blacklist table add 'secrets:*'`
   registers a key glob; an optional `redis.mask` block masks values on read. Size guards
   (SCAN/HGETALL truncation, `--no-limit` to bypass) and masking details: reference.md Redis section.
 
 ## Elasticsearch
 
+**dbcli is read-only against Elasticsearch — `insert` / `update` / `delete` are not supported.**
+
+```bash
+dbcli query '{"query":{"match":{"status":"active"}}}' --collection orders
+```
+
 - `query` takes a DSL (JSON body) or Lucene query string; `--collection <index>` is required.
 - **Supported:** `init`, `list` (indices with doc count), `schema [index]` (flattened mapping),
   `query`, `export` (v1.22), `shell` (v1.22), `status`, `use`, `doctor`. **Not supported:**

package/skills/dbcli/reference.md

@@ -249,6 +249,7 @@ dbcli q @analytics/revenue --param days=30 --format html > report.html
 - `--dry-run` — print the bound SQL + values without executing
 - `--use <name>` — pick a v2 named connection
 - `--recovery` — emit a `RecoveryEnvelope` on failure (see `recover`)
+- `--verify` — run the snippet's verification assertions after execution (only if the snippet defines them)
 
 **Permission:** query-only+
 
@@ -474,9 +475,10 @@ Insert data into a table.
 dbcli insert users --data '{"name":"Alice","email":"alice@example.com"}'
 dbcli insert users --data '{"name":"Alice"}' --dry-run
 dbcli insert users --data '{"name":"Alice"}' --force
+dbcli insert users --data '{"name":"Alice"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--data <json>`, `--dry-run`, `--force`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -486,11 +488,19 @@ Update existing data.
 ```bash
 dbcli update users --where "id=1" --set '{"name":"Bob"}'
 dbcli update users --where "id=1" --set '{"name":"Bob"}' --dry-run
+dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** read-write+
 
+> **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
+> `col1=v1 AND col2=v2`. Comparison / pattern operators (`>`, `>=`, `<`, `!=`, `LIKE`, `IN`)
+> raise a parse error, and `OR` is **silently folded into the value** (`a=1 OR b=2` parses as
+> `a = "1 OR b=2"`, matching nothing intended). For ranges or compound predicates, select the
+> target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
+> (MongoDB `--where` accepts a full JSON filter and is exempt.)
+
 ### delete
 
 Delete data from a table.
@@ -499,9 +509,10 @@ Delete data from a table.
 dbcli delete users --where "id=1"
 dbcli delete users --where "id=1" --dry-run
 dbcli delete users --where "id=1" --force
+dbcli delete users --where "id=1" --plan --format json   # risk analysis only; no DB connection
 ```
 
-**Options:** `--where <condition>` (required), `--dry-run`, `--force`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -521,7 +532,7 @@ dbcli export orders --format csv --output orders.csv      # index name as query
 dbcli export orders --no-limit --format jsonl             # scroll the whole index in batches
 ```
 
-**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--index <name>` (Elasticsearch), `--no-limit` (Elasticsearch full-index scroll)
+**Options:** `--format <json|jsonl|csv|html>` (required), `--output <path>`, `--force`, `--recovery`, `--collection <name>` (MongoDB collection) / `--index <name>` (Elasticsearch index; alias for `--collection`), `--limit <number>` (overrides auto-limit), `--no-limit` (Elasticsearch full-index scroll)
 **Permission:** query-only+ — SQL, MongoDB, and **(v1.22)** Elasticsearch.
 
 The `html` format emits the same self-contained dashboard as `query --ui` (see [Interactive HTML dashboard](#interactive-html-dashboard)). Because `export` runs raw SQL (no snippet metadata), the HTML report is always rendered as a sortable / filterable table — no KPIs or charts. Use `dbcli q @<name> --format html` (or `--ui`) for the charted view.
@@ -892,6 +903,7 @@ Boundaries:
 | `--from <path>` | Read the envelope from this file instead of `.dbcli/last-recovery.json`. Accepts raw `RecoveryEnvelope` or `SavedRecoveryEnvelope`. | — |
 | `--allow-write <tier>` | Open the risk gate. Values: `readonly-cmd` (local-side writes) \| `write-cmd` (database writes). | `none` |
 | `--no-verify` | Skip the verify step appended after a successful `--apply`. | off (verify runs by default) |
+| `--write-verification-artifact` | After a successful `--apply`, persist a secret-free `VerificationArtifact` JSON under `.dbcli/verification/`. | off |
 | `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
 
 #### Plan source resolution
@@ -1650,6 +1662,7 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 **Options:**
 - `--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`.
+- `--lang <en|zh-TW>` — source language for the emitted SKILL content (default `en`). It selects `assets/SKILL.md` vs `assets/SKILL.zh-TW.md`; the install/output filename stays `SKILL.md` regardless.
 
 **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.
@@ -1662,6 +1675,21 @@ dbcli skill --install codex                  # install to ~/.codex/skills/dbcli/
 
 **Permission:** n/a.
 
+### skill context
+
+Emit an AI-friendly snapshot of the connected database's schema and saved-query snippets (blacklist-filtered) so an agent can be primed with the current context.
+
+```bash
+dbcli skill context                      # XML (default)
+dbcli skill context --format json
+dbcli skill context --format markdown
+```
+
+**Options:**
+- `--format <xml|json|markdown>` — output format (default: `xml`)
+
+**Permission:** query-only+ — read-only; blacklisted objects are never emitted.
+
 ### skill tasks (Agent Task Packs)
 
 ```bash
@@ -2201,7 +2229,7 @@ Rewrites emit a `REDIS_SIZE_REWRITE` warning; truncations emit `REDIS_SIZE_TRUNC
 Blacklist rules are enforced as **Redis-native key globs** (`*`, `?`, `[abc]`, `[a-z]`):
 
 ```bash
-dbcli blacklist add 'secrets:*'          # register a key-glob rule
+dbcli blacklist table add 'secrets:*'    # register a key-glob rule
 dbcli query "GET secrets:api_key"        # → BlacklistRejection (exit non-zero)
 dbcli query "MGET safe:k secrets:api"    # → rejected (any matching key fails the whole command)
 dbcli query "KEYS secrets:*"             # → rejected (pattern overlaps a rule)