@carllee1983/dbcli 1.57.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "1.57.0",
+  "version": "2.0.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

@@ -43,6 +43,18 @@ 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.)
 
+**Write gate (2.0.0) — the rule that will refuse you.** Every write is classified into two
+tiers. Ordinary writes (`INSERT`, `UPDATE` / `DELETE` with a `WHERE`, `CREATE`, `ALTER`)
+run unattended exactly as before; `--yes` skips the terminal prompt a human would see.
+**Statements that are not limited to specific rows are refused outright when nobody can
+answer a prompt** — `UPDATE` / `DELETE` with no `WHERE`, `DROP`, `TRUNCATE`, a statement
+the SQL parser cannot read, several statements in one string, and `update` / `delete --where` matching on no primary key and
+no unique index. The process exits `1` with `reason=no_where`, `reason=ddl_destruction`,
+`reason=unparseable` or `reason=non_unique_where`, and **nothing reaches the database**.
+**No flag bypasses this** — not `--yes`, not `--force`. To write every row on purpose, put
+the intent in the SQL itself: add `WHERE 1=1` or a `LIMIT`. `DROP` / `TRUNCATE` have no
+unattended route at all; escalate to a human.
+
 > `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
 > audit-recent context or to diagnose a connection problem.
@@ -449,8 +461,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

@@ -334,9 +334,50 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**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`
+**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>`, `--yes`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Write confirmation gate (2.0.0)
+
+A SQL write passes through a two-tier gate before the connection is opened. The gate is
+separate from the permission axis: permission says what the connection may do, the gate
+says whether this particular statement may run right now.
+
+| Tier | Statements | Interactive terminal | Non-interactive (or `--format json`) |
+| :--- | :--- | :--- | :--- |
+| One | `INSERT`, `UPDATE` / `DELETE` **with** a `WHERE` or `LIMIT`, `CREATE`, `ALTER` | Summary + `y/N`; `--yes` skips it | Runs, exactly as before |
+| Two | `UPDATE` / `DELETE` with **no** `WHERE`, `DROP`, `TRUNCATE`, unparseable statements, several statements in one string | Type the target table name; **no flag skips it** | **Refused**: exit `1`, nothing sent to the database |
+
+A refusal message names a machine-readable reason — `reason=no_where`,
+`reason=ddl_destruction`, `reason=unparseable`, `reason=multiple_statements` — so a caller can tell it apart from a
+connection failure or a permission denial.
+
+**Escape routes.** For a statement that accepts a `WHERE`, put the intent in the SQL:
+
+```bash
+dbcli query "UPDATE users SET banned = 1"                    # refused, reason=no_where
+dbcli query "UPDATE users SET banned = 1 WHERE 1=1"          # runs — intent is explicit
+dbcli query "DELETE FROM sessions LIMIT 1000"                # runs — damage is bounded
+dbcli query "UPDATE users SET banned = 1 WHERE id = 3" --yes # tier one, question skipped
+```
+
+This is deliberately not a flag. `WHERE 1=1` appended to a statement that already has a
+`WHERE` is a syntax error, so a blanket "always add it" habit breaks on the first ordinary
+statement; a flag would be harmless everywhere and therefore added everywhere. For `DROP`
+and `TRUNCATE` there is no clause to add — the connection's `permission` level decides
+whether they are possible at all, and the typed confirmation must come from a person.
+
+Every tier-two evaluation is written to the audit log with
+`metadata.write_gate_outcome` (`allowed` / `declined` / `refused`) and
+`metadata.write_gate_reason`.
+
+> **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
@@ -925,7 +966,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
@@ -938,7 +979,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
@@ -948,6 +989,14 @@ dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json
 > target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
 > (MongoDB `--where` accepts a full JSON filter and is exempt.)
 
+> **Tier two for structured writes (2.0.0)** — a `--where` that matches on no primary key
+> and no unique index selects an unknown number of rows, so it is treated the same as a
+> raw statement with no `WHERE`: the target table name must be typed at an interactive
+> terminal, and a non-interactive run is refused with exit `1` and
+> `reason=non_unique_where`. `--force` and `--dry-run` do not affect this; `--force` skips
+> the ordinary confirmation only. Select the primary keys first and write one row at a
+> time, or run it where a person can confirm it.
+
 ### delete
 
 Delete data from a table.
@@ -959,7 +1008,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
@@ -2540,6 +2589,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

@@ -43,6 +43,18 @@ 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.)
 
+**Write gate (2.0.0) — the rule that will refuse you.** Every write is classified into two
+tiers. Ordinary writes (`INSERT`, `UPDATE` / `DELETE` with a `WHERE`, `CREATE`, `ALTER`)
+run unattended exactly as before; `--yes` skips the terminal prompt a human would see.
+**Statements that are not limited to specific rows are refused outright when nobody can
+answer a prompt** — `UPDATE` / `DELETE` with no `WHERE`, `DROP`, `TRUNCATE`, a statement
+the SQL parser cannot read, several statements in one string, and `update` / `delete --where` matching on no primary key and
+no unique index. The process exits `1` with `reason=no_where`, `reason=ddl_destruction`,
+`reason=unparseable` or `reason=non_unique_where`, and **nothing reaches the database**.
+**No flag bypasses this** — not `--yes`, not `--force`. To write every row on purpose, put
+the intent in the SQL itself: add `WHERE 1=1` or a `LIMIT`. `DROP` / `TRUNCATE` have no
+unattended route at all; escalate to a human.
+
 > `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
 > audit-recent context or to diagnose a connection problem.
@@ -449,8 +461,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

@@ -334,9 +334,50 @@ dbcli query "SELECT day, dau FROM dau_daily" --ui                # open in brows
 dbcli query "SELECT * FROM orders" --format html > orders.html   # pipe to stdout
 ```
 
-**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`
+**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>`, `--yes`, `--recovery`
 **Permission:** query-only+ (Redis: per-command; Elasticsearch: per HTTP method/path)
 
+#### Write confirmation gate (2.0.0)
+
+A SQL write passes through a two-tier gate before the connection is opened. The gate is
+separate from the permission axis: permission says what the connection may do, the gate
+says whether this particular statement may run right now.
+
+| Tier | Statements | Interactive terminal | Non-interactive (or `--format json`) |
+| :--- | :--- | :--- | :--- |
+| One | `INSERT`, `UPDATE` / `DELETE` **with** a `WHERE` or `LIMIT`, `CREATE`, `ALTER` | Summary + `y/N`; `--yes` skips it | Runs, exactly as before |
+| Two | `UPDATE` / `DELETE` with **no** `WHERE`, `DROP`, `TRUNCATE`, unparseable statements, several statements in one string | Type the target table name; **no flag skips it** | **Refused**: exit `1`, nothing sent to the database |
+
+A refusal message names a machine-readable reason — `reason=no_where`,
+`reason=ddl_destruction`, `reason=unparseable`, `reason=multiple_statements` — so a caller can tell it apart from a
+connection failure or a permission denial.
+
+**Escape routes.** For a statement that accepts a `WHERE`, put the intent in the SQL:
+
+```bash
+dbcli query "UPDATE users SET banned = 1"                    # refused, reason=no_where
+dbcli query "UPDATE users SET banned = 1 WHERE 1=1"          # runs — intent is explicit
+dbcli query "DELETE FROM sessions LIMIT 1000"                # runs — damage is bounded
+dbcli query "UPDATE users SET banned = 1 WHERE id = 3" --yes # tier one, question skipped
+```
+
+This is deliberately not a flag. `WHERE 1=1` appended to a statement that already has a
+`WHERE` is a syntax error, so a blanket "always add it" habit breaks on the first ordinary
+statement; a flag would be harmless everywhere and therefore added everywhere. For `DROP`
+and `TRUNCATE` there is no clause to add — the connection's `permission` level decides
+whether they are possible at all, and the typed confirmation must come from a person.
+
+Every tier-two evaluation is written to the audit log with
+`metadata.write_gate_outcome` (`allowed` / `declined` / `refused`) and
+`metadata.write_gate_reason`.
+
+> **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
@@ -925,7 +966,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
@@ -938,7 +979,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
@@ -948,6 +989,14 @@ dbcli update users --where "id=1" --set '{"name":"Bob"}' --plan --format json
 > target primary keys first, then issue one `update` / `delete --where "id=<pk>"` per key.
 > (MongoDB `--where` accepts a full JSON filter and is exempt.)
 
+> **Tier two for structured writes (2.0.0)** — a `--where` that matches on no primary key
+> and no unique index selects an unknown number of rows, so it is treated the same as a
+> raw statement with no `WHERE`: the target table name must be typed at an interactive
+> terminal, and a non-interactive run is refused with exit `1` and
+> `reason=non_unique_where`. `--force` and `--dry-run` do not affect this; `--force` skips
+> the ordinary confirmation only. Select the primary keys first and write one row at a
+> time, or run it where a person can confirm it.
+
 ### delete
 
 Delete data from a table.
@@ -959,7 +1008,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
@@ -2540,6 +2589,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>`