@carllee1983/dbcli 1.56.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.56.0",
+  "version": "1.58.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {
@@ -74,12 +74,14 @@
     "test:unit": "bun test tests/unit tests/core",
     "test:integration": "bun test tests/integration",
     "test:gherkin": "bun test tests/gherkin",
-    "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration/adapters; docker compose -f docker-compose.test.yml down",
+    "test:docker": "docker compose -f docker-compose.test.yml up -d --wait && bun test tests/integration; docker compose -f docker-compose.test.yml down",
+    "services:check": "bun run scripts/check-test-services.ts",
     "docs:check": "bun run scripts/check-user-docs.ts",
     "contract:check": "bun run scripts/check-cli-contract.ts",
     "skill:check": "bun run scripts/check-skill-parity.ts",
     "platform:check": "bun run scripts/check-platform-parity.ts",
     "agent-core:check": "bun run scripts/check-agent-core-purity.ts",
+    "core-stdout:check": "bun run scripts/check-core-no-stdout.ts",
     "typecheck": "tsc --noEmit --pretty false",
     "test:perf": "bun test ./tests/perf/*.bench.ts",
     "lint": "eslint src tests scripts --ext .ts --max-warnings=0",

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

@@ -310,6 +310,19 @@ dbcli init --rename staging:stg           # rename
 dbcli init --remove stg                   # remove
 ```
 
+Rotating one connection's password — nothing else in the config moves:
+
+```bash
+dbcli password prod                       # masked prompt
+rotate-secret | dbcli password prod --stdin   # for scheduled rotation scripts
+```
+
+The value goes to the env var the config actually references (a literal password
+is converted to `{ "$env": ... }` on first use, and a connection with no
+`envFile` gets one recorded so the reader loads it), is verified by connecting
+before it is saved (`--skip-test` to opt out), and the env file is written
+`0600` on POSIX.
+
 For a connection shared across projects, use the explicit root-level `--global` scope. It stores a v2 registry at `~/.config/dbcli/config.json`; it does not create or modify a project binding:
 
 ```bash
@@ -436,8 +449,13 @@ changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `updat
   (no `>=`, `!=`, `LIKE`, `OR`). MongoDB `--where` takes a full JSON filter
   (`'{"status":"pending"}'`), falling back to `col=val` when it is not valid JSON.
 - `--dry-run` prints the parameterized SQL (with `$1` / `?` placeholders, not real values)
-  and `rows_affected: 0`; proceed once `status:"success"` and the SQL shape matches the
-  intended `--where` / `--set`. MongoDB prints a shell-style preview.
+  and `status:"dry_run"` with `rows_affected: 0` — never `success`, which now means the
+  write really ran. Proceed once the SQL shape matches the intended `--where` / `--set`.
+  Declining at the confirmation prompt reports `status:"cancelled"`, also not `success`.
+  MongoDB prints a shell-style preview.
+- `--force` skips the confirmation prompt. Every `insert` / `update` / `delete` asks
+  first — SQL, MongoDB and Redis alike — and a non-interactive run cannot answer, so an
+  unattended write without `--force` ends as `status:"cancelled"` having changed nothing.
 - `--recovery` is recommended for automated agent pipelines (enables `dbcli recover --apply`
   after a failure); optional for one-off manual writes.
 

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

@@ -22,6 +22,7 @@ never the right move.
 **Commands** —
 [init](#init) ·
 [use](#use) ·
+[password](#password) ·
 [list](#list) ·
 [schema](#schema) ·
 [query](#query) ·
@@ -196,6 +197,46 @@ dbcli list --use prod
 
 **Options:** `--list`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
 
+### password
+
+Change one connection's password without touching any other setting — built for
+environments where credentials rotate on a schedule.
+
+```bash
+dbcli password                       # Masked prompt, rotates the default connection
+dbcli password prod                  # Masked prompt, rotates 'prod'
+rotate-secret | dbcli password prod --stdin   # Non-interactive, nothing lands in shell history
+dbcli password prod --password "$NEW" --skip-test --format json
+```
+
+Where the value lands is read from the config, never guessed: a connection whose
+`password` is `{ "$env": "NAME" }` gets `NAME` rewritten in its `envFile`. A
+connection that declares no `envFile` has one recorded (`.env.local`) as part of
+the rotation — without it the reader would never load the file. A connection
+still holding a literal password is converted to
+`{ "$env": "DBCLI_<CONN>_PASSWORD" }` once, so later rotations only touch the env
+file. Values are written quoted (`NAME="..."`), so leading and trailing
+whitespace survives the round trip.
+
+v1 configs rewrite `DBCLI_PASSWORD` in `.env.local`, matching the v1 reader. A v1
+config whose password comes from some other environment variable is refused with
+an explanation: v1 has no per-connection env file, so no file dbcli writes could
+make that variable resolve — set it in the environment, or migrate to v2.
+
+The new password is verified by connecting with it before anything is written,
+so a bad rotation fails without leaving broken credentials behind. Pass
+`--skip-test` when the database is unreachable from where the command runs. The
+env file is written with `0600` permissions on POSIX systems (Windows has no
+equivalent mode bit — the file inherits the directory's ACL), and the value is
+never echoed or
+logged.
+
+**Options:** `[connection]`, `--stdin`, `--password <value>` (visible in shell
+history and the process list — prefer `--stdin`), `--skip-test`,
+`--format <text|json>`.
+
+Blocked under `DBCLI_AGENT_MODE=1` like every other credential mutation.
+
 ### Agent configuration trust boundary
 
 When `DBCLI_AGENT_MODE=1`, configuration, permission, and credential mutations
@@ -296,6 +337,13 @@ dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdou
 **Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+> **Elasticsearch tiers by scope.** A read (`GET` / `HEAD`, plus `POST _search` and
+> `POST _count`) is query-only. Indexing or updating a document is read-write.
+> `DELETE /<index>/_doc/<id>` — one document — is data-admin. Everything that removes or
+> reshapes a container is **admin**: `DELETE /<index>`, a wildcard or `_all` delete,
+> templates and aliases, and `PUT` against `_mapping` or `_settings`. A request whose
+> scope cannot be established is treated as admin rather than guessed downward.
+
 > **Server-side scripts are rejected on every path.** MongoDB `$where`,
 > `$function`, and `$accumulator`, and Elasticsearch `script` / `script_fields`,
 > execute code on the database server. The adapters reject them anywhere in a
@@ -884,7 +932,7 @@ 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`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output; `json` also keeps the result envelope instead of prose in a terminal), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -897,7 +945,7 @@ 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`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output; `json` also keeps the result envelope instead of prose in a terminal), `--recovery`
 **Permission:** read-write+
 
 > **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
@@ -918,7 +966,7 @@ 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`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output; `json` also keeps the result envelope instead of prose in a terminal), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -2499,6 +2547,8 @@ dbcli migrate add-enum status active inactive suspended
 dbcli migrate alter-enum status --add-value archived
 dbcli migrate drop-enum status --execute --force
 ```
+A destructive `migrate` action (`drop`, `drop-column`, `drop-index`, `drop-enum`) asks for confirmation on stderr before it runs, and reports `status: "cancelled"` if you decline — not `success`, which it used to claim with the cancellation buried in `warnings`. `--force` skips the question; a non-interactive run that omits it cannot answer and therefore cancels.
+
 
 **Column spec format:** `name:type[:modifier[:modifier...]]`
 - Modifiers: `pk`, `not-null`, `unique`, `auto-increment`, `default=<value>`, `references=<table>.<column>`

package/skills/dbcli/SKILL.md

@@ -310,6 +310,19 @@ dbcli init --rename staging:stg           # rename
 dbcli init --remove stg                   # remove
 ```
 
+Rotating one connection's password — nothing else in the config moves:
+
+```bash
+dbcli password prod                       # masked prompt
+rotate-secret | dbcli password prod --stdin   # for scheduled rotation scripts
+```
+
+The value goes to the env var the config actually references (a literal password
+is converted to `{ "$env": ... }` on first use, and a connection with no
+`envFile` gets one recorded so the reader loads it), is verified by connecting
+before it is saved (`--skip-test` to opt out), and the env file is written
+`0600` on POSIX.
+
 For a connection shared across projects, use the explicit root-level `--global` scope. It stores a v2 registry at `~/.config/dbcli/config.json`; it does not create or modify a project binding:
 
 ```bash
@@ -436,8 +449,13 @@ changing the default. `--recovery` is honoured by `query`, `q`, `insert`, `updat
   (no `>=`, `!=`, `LIKE`, `OR`). MongoDB `--where` takes a full JSON filter
   (`'{"status":"pending"}'`), falling back to `col=val` when it is not valid JSON.
 - `--dry-run` prints the parameterized SQL (with `$1` / `?` placeholders, not real values)
-  and `rows_affected: 0`; proceed once `status:"success"` and the SQL shape matches the
-  intended `--where` / `--set`. MongoDB prints a shell-style preview.
+  and `status:"dry_run"` with `rows_affected: 0` — never `success`, which now means the
+  write really ran. Proceed once the SQL shape matches the intended `--where` / `--set`.
+  Declining at the confirmation prompt reports `status:"cancelled"`, also not `success`.
+  MongoDB prints a shell-style preview.
+- `--force` skips the confirmation prompt. Every `insert` / `update` / `delete` asks
+  first — SQL, MongoDB and Redis alike — and a non-interactive run cannot answer, so an
+  unattended write without `--force` ends as `status:"cancelled"` having changed nothing.
 - `--recovery` is recommended for automated agent pipelines (enables `dbcli recover --apply`
   after a failure); optional for one-off manual writes.
 

package/skills/dbcli/reference.md

@@ -22,6 +22,7 @@ never the right move.
 **Commands** —
 [init](#init) ·
 [use](#use) ·
+[password](#password) ·
 [list](#list) ·
 [schema](#schema) ·
 [query](#query) ·
@@ -196,6 +197,46 @@ dbcli list --use prod
 
 **Options:** `--list`, `--format <text|json>`, `--confirm-production <name>` (required when explicitly selecting a production connection as the default).
 
+### password
+
+Change one connection's password without touching any other setting — built for
+environments where credentials rotate on a schedule.
+
+```bash
+dbcli password                       # Masked prompt, rotates the default connection
+dbcli password prod                  # Masked prompt, rotates 'prod'
+rotate-secret | dbcli password prod --stdin   # Non-interactive, nothing lands in shell history
+dbcli password prod --password "$NEW" --skip-test --format json
+```
+
+Where the value lands is read from the config, never guessed: a connection whose
+`password` is `{ "$env": "NAME" }` gets `NAME` rewritten in its `envFile`. A
+connection that declares no `envFile` has one recorded (`.env.local`) as part of
+the rotation — without it the reader would never load the file. A connection
+still holding a literal password is converted to
+`{ "$env": "DBCLI_<CONN>_PASSWORD" }` once, so later rotations only touch the env
+file. Values are written quoted (`NAME="..."`), so leading and trailing
+whitespace survives the round trip.
+
+v1 configs rewrite `DBCLI_PASSWORD` in `.env.local`, matching the v1 reader. A v1
+config whose password comes from some other environment variable is refused with
+an explanation: v1 has no per-connection env file, so no file dbcli writes could
+make that variable resolve — set it in the environment, or migrate to v2.
+
+The new password is verified by connecting with it before anything is written,
+so a bad rotation fails without leaving broken credentials behind. Pass
+`--skip-test` when the database is unreachable from where the command runs. The
+env file is written with `0600` permissions on POSIX systems (Windows has no
+equivalent mode bit — the file inherits the directory's ACL), and the value is
+never echoed or
+logged.
+
+**Options:** `[connection]`, `--stdin`, `--password <value>` (visible in shell
+history and the process list — prefer `--stdin`), `--skip-test`,
+`--format <text|json>`.
+
+Blocked under `DBCLI_AGENT_MODE=1` like every other credential mutation.
+
 ### Agent configuration trust boundary
 
 When `DBCLI_AGENT_MODE=1`, configuration, permission, and credential mutations
@@ -296,6 +337,13 @@ dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdou
 **Options:** `--format <table|json|csv|html>`, `--ui` (open the dashboard in the system browser; implies `--format html`), `--limit <number>`, `--no-limit`, `--collection <name>` (MongoDB / Elasticsearch), `--index <name>` (Elasticsearch alias for `--collection`), `--fields <list>`, `--truncate <number>` / `--no-truncate`, `-f, --query-file <path>`, `--use <name[,name]>`, `--slow-ms <number>`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+> **Elasticsearch tiers by scope.** A read (`GET` / `HEAD`, plus `POST _search` and
+> `POST _count`) is query-only. Indexing or updating a document is read-write.
+> `DELETE /<index>/_doc/<id>` — one document — is data-admin. Everything that removes or
+> reshapes a container is **admin**: `DELETE /<index>`, a wildcard or `_all` delete,
+> templates and aliases, and `PUT` against `_mapping` or `_settings`. A request whose
+> scope cannot be established is treated as admin rather than guessed downward.
+
 > **Server-side scripts are rejected on every path.** MongoDB `$where`,
 > `$function`, and `$accumulator`, and Elasticsearch `script` / `script_fields`,
 > execute code on the database server. The adapters reject them anywhere in a
@@ -884,7 +932,7 @@ 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`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
+**Options:** `--data <json>`, `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output; `json` also keeps the result envelope instead of prose in a terminal), `--recovery`
 **Permission:** read-write+
 
 ### update
@@ -897,7 +945,7 @@ 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`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
+**Options:** `--where <condition>` (required), `--set <json>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output; `json` also keeps the result envelope instead of prose in a terminal), `--recovery`
 **Permission:** read-write+
 
 > **`--where` grammar (SQL `update` / `delete`)** — equality only: `col=val` or
@@ -918,7 +966,7 @@ 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`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output), `--recovery`
+**Options:** `--where <condition>` (required), `--dry-run`, `--force`, `--plan` (analyze risk without connecting or executing), `--format <text|json>` (`--plan` output; `json` also keeps the result envelope instead of prose in a terminal), `--recovery`
 **Permission:** data-admin+
 
 ### export
@@ -2499,6 +2547,8 @@ dbcli migrate add-enum status active inactive suspended
 dbcli migrate alter-enum status --add-value archived
 dbcli migrate drop-enum status --execute --force
 ```
+A destructive `migrate` action (`drop`, `drop-column`, `drop-index`, `drop-enum`) asks for confirmation on stderr before it runs, and reports `status: "cancelled"` if you decline — not `success`, which it used to claim with the cancellation buried in `warnings`. `--force` skips the question; a non-interactive run that omits it cannot answer and therefore cancels.
+
 
 **Column spec format:** `name:type[:modifier[:modifier...]]`
 - Modifiers: `pk`, `not-null`, `unique`, `auto-increment`, `default=<value>`, `references=<table>.<column>`