@carllee1983/dbcli 12.0.0 → 12.1.0

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "dbcli-agent",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "Database CLI skill and command reference for AI agents.",
   "contextFileName": "AGENTS.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carllee1983/dbcli",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "Database CLI for AI agents",
   "type": "module",
   "publishConfig": {
@@ -69,6 +69,7 @@
     "prepublishOnly": "bun run build",
     "audit": "bun run scripts/audit.ts",
     "release:check": "bash scripts/release-check.sh",
+    "release:extras": "bash scripts/release-extras.sh",
     "plugin:sync": "bun run scripts/sync-plugin-assets.ts --write",
     "plugin:check": "bun run scripts/sync-plugin-assets.ts",
     "manifest:sync": "bun run scripts/check-plugin-manifests.ts --write",

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

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

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

@@ -152,6 +152,14 @@ dbcli capabilities check --require schema.read,query.read         # gate your wo
 dbcli capabilities check --require data.delete --format json      # machine-readable
 ```
 
+`connection.tls` derives support from the engine matrix and maps to existing
+connection command surfaces, supporting PostgreSQL, MySQL and MariaDB. It adds
+no TLS subcommand. Check with
+`dbcli capabilities check --require connection.tls --format json`.
+`available` establishes tool support only, not TLS configuration, readable CA,
+a successful handshake or authorization. Catalog/check stay offline, read no CA
+and change no configuration. Older binaries without this ID return `unknown`.
+
 For a copyable Bun/TypeScript consumer with strict parsing, schema pins, exit handling,
 Operation Envelope handling, Task Pack `safety.requires`, and correlation/evidence guidance,
 start with `assets/integration-kit/README.md`.
@@ -326,6 +334,44 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
 > If a `.dbcli` already contains `{"$env": "..."}` references, **do not** rerun
 > `init` to "fill them in" — the env-ref form is intentional for CI/multi-env.
 
+### PostgreSQL, MySQL and MariaDB verified TLS
+
+When verified TLS is required, use the named `init` entry with both
+`--sql-tls verify-full --sql-tls-ca <path>`. PostgreSQL, MySQL and MariaDB support this SQL
+contract; explicit requests on other engines fail. The saved
+`sqlTls: { mode: 'verify-full', caPath: '/absolute/path/root-ca.pem' }` uses an
+absolute literal PEM path; `init` resolves relative paths from cwd. CA environment
+references are unsupported. Existing host/user environment references and profiles
+without `sqlTls` keep their behavior. V1 directory/v2 reads, normal `init` import
+from a V1 directory and `migrateV1ToV2` preserve TLS. Legacy V1 single-file TLS
+profiles remain readable/usable in human mode; automatic `init` import refuses
+before connecting or writing, preserving the original. Migrate that case by
+creating a verified named profile in a separate config directory, verifying it,
+then selecting it; preserve `sqlTls` throughout.
+
+Ambient TLS settings cannot weaken verification or supply another profile’s trust.
+Each connection reloads its own CA and verifies encryption, trust, validity and the
+configured DNS/IP identity; explicit SQL TLS refuses Unix sockets. Failures stop
+before the user query. Repair the CA, hostname or certificate; keep verification
+and TLS required. On binary rollback, stop TLS-required workflows or retain a
+supporting version: older binaries may strip `sqlTls`. Local fixture evidence does
+not establish real RDS acceptance. Configured permitted reads work in agent mode;
+`init` and other configuration changes remain refused.
+
+For TLS error recovery, repair certificates while retaining TLS, then explicitly
+select `--config <path>` or `--global`; v2 also requires `--use <name>` or
+`DBCLI_CONNECTION`. The selected profile must retain `sqlTls.mode: verify-full`.
+Missing, ambiguous or plaintext selections block live steps. Saved envelopes
+redact original selectors, so current targeting does not establish original
+provenance. Apply and verification use the current CLI binary. Example:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+For the complete configuration, example and failure contract, read
+[SQL verified TLS](reference.md#verified-tls-for-postgresql-mysql-and-mariadb).
+
 ### Decision tree (ask before writing)
 
 1. **What is the connection name?** Every new connection uses named v2, even

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

@@ -157,7 +157,7 @@ Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `
 
 New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
 
-**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+**Key options:** `--sql-tls verify-full`, `--sql-tls-ca <path>`, `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
@@ -193,6 +193,57 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
 
+#### Verified TLS for PostgreSQL, MySQL and MariaDB
+
+Use both SQL TLS flags when creating a named PostgreSQL, MySQL or MariaDB profile. This example prompts for the password and tests the connection before saving:
+
+```bash
+dbcli init --conn-name verified-pg --system postgresql \
+  --host db.example.com --port 5432 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/root-ca.pem
+dbcli --use verified-pg blacklist list
+dbcli --use verified-pg schema public.events --format json
+dbcli --use verified-pg query "SELECT id FROM public.events LIMIT 10" --format json
+```
+
+MySQL and MariaDB use the same flags, with separate named profiles and CA paths. Select the corresponding profile, then check blacklist and schema before an authorized query:
+
+```bash
+dbcli init --conn-name verified-mysql --system mysql \
+  --host mysql.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mysql-ca.pem
+dbcli init --conn-name verified-mariadb --system mariadb \
+  --host mariadb.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mariadb-ca.pem
+```
+
+Replace the host, database and table with your authorized target; confirm real columns through schema before querying. The saved connection includes this dedicated SQL object (shown as a connection fragment):
+
+```json
+{
+  "sqlTls": {
+    "mode": "verify-full",
+    "caPath": "/absolute/path/to/certs/root-ca.pem"
+  }
+}
+```
+
+`--sql-tls verify-full` and `--sql-tls-ca <path>` are required together. Empty values, other modes and unsupported engines fail explicitly. PostgreSQL, MySQL and MariaDB support this SQL TLS contract; all other engines reject an explicit request. MongoDB's `tls` and Elasticsearch's TLS settings remain separate. Existing profiles without `sqlTls` keep their previous behavior; no global TLS policy is added. V1 directory and v2 profile reads, normal `init` import from a V1 directory to v2, and the public `migrateV1ToV2` helper preserve the TLS object. A legacy V1 single-file TLS profile remains readable and usable in human mode, but automatic `init` import explicitly refuses it before connecting or writing and leaves the original untouched. For that case, create a verified named profile in a separate configuration directory, verify it, then select it; preserve `sqlTls` throughout migration.
+
+`init` resolves a relative CA path against its current working directory before saving. Saved `caPath` must be a nonempty absolute literal path to a PEM CA bundle; it accepts no environment-variable reference. Existing environment references in host/user and other supported fields remain usable. Explicit TLS uses only the selected profile’s CA and identity settings; ambient TLS settings cannot weaken verification or supply another profile’s trust. Each new connection reads the CA bundle again; an unreadable, empty or invalid bundle stops before connecting. `--skip-test` skips only the initialization test, not verification on subsequent use.
+
+`verify-full` requires encryption, a trusted certificate chain, valid certificate dates and certificate identity matching the configured DNS name or IP address. Unix sockets are refused for explicit SQL TLS. Untrusted, expired or mismatched certificates and servers without TLS fail before the user query; there is no plaintext retry or verification downgrade. Correct the CA, target hostname or certificate validity before retrying. A cipher alone does not prove identity verification.
+
+For TLS error recovery, keep TLS configured and repair the CA, hostname or certificate first. Then deliberately select the configuration with `--config <path>` (or `--global`) and, for v2, the named profile with `--use <name>` (`DBCLI_CONNECTION` is also accepted). The selected profile must still have `sqlTls.mode: verify-full`; missing, ambiguous or plaintext selections block live recovery steps instead of falling back to a default plaintext connection. Saved recovery envelopes redact the original selectors: your current selection is deliberate targeting, not proof of the original target. Recovery apply and verification use the current CLI binary, avoiding an older `dbcli` on PATH. For the MySQL example above:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+Permitted reads through an already configured profile remain usable in agent mode; `init` and other configuration mutations remain refused under `DBCLI_AGENT_MODE=1`. TLS does not bypass explicit production selection, native database authorization, permission, blacklist, write-gate or audit controls.
+
+For binary rollback, stop workflows that require verified TLS or keep a supporting version. Older binaries may strip `sqlTls`; retaining the profile after downgrading does not preserve the guarantee. Removing TLS settings or retrying in plaintext cannot restore compliance. Local isolated PostgreSQL, MySQL and MariaDB fixture results are not evidence of real RDS acceptance; RDS remains unverified.
+
 ### use
 
 Set, clear, or display the default database connection (v2 multi-connection config).
@@ -1731,6 +1782,8 @@ Every actionable block carries machine-readable next steps so an agent can move
 
 ### capabilities
 
+`connection.tls` reports PostgreSQL, MySQL and MariaDB support from the engine capability matrix and maps to the existing connection command surfaces; it adds no TLS subcommand. Check with `dbcli --use verified-pg capabilities check --require connection.tls --format json`. `available` means tool support only: it does not prove that this profile configures TLS, the CA is readable, the handshake succeeds, or the operation is authorized. Catalog/check remain offline, read no CA bundle, perform no handshake and change no configuration. Other engines do not report this capability as available; older binaries without the ID return `unknown`. Configuration mutation still requires its own authorization.
+
 Discovery. Lists the static dbcli capability catalog — what this tool can do,
 described in a versioned shape an external Skill can parse before it starts
 working. It never opens a database connection and never writes anything.

package/skills/dbcli/SKILL.md

@@ -152,6 +152,14 @@ dbcli capabilities check --require schema.read,query.read         # gate your wo
 dbcli capabilities check --require data.delete --format json      # machine-readable
 ```
 
+`connection.tls` derives support from the engine matrix and maps to existing
+connection command surfaces, supporting PostgreSQL, MySQL and MariaDB. It adds
+no TLS subcommand. Check with
+`dbcli capabilities check --require connection.tls --format json`.
+`available` establishes tool support only, not TLS configuration, readable CA,
+a successful handshake or authorization. Catalog/check stay offline, read no CA
+and change no configuration. Older binaries without this ID return `unknown`.
+
 For a copyable Bun/TypeScript consumer with strict parsing, schema pins, exit handling,
 Operation Envelope handling, Task Pack `safety.requires`, and correlation/evidence guidance,
 start with `assets/integration-kit/README.md`.
@@ -326,6 +334,44 @@ or `doctor` / `status` reports a missing or invalid config, follow this flow.
 > If a `.dbcli` already contains `{"$env": "..."}` references, **do not** rerun
 > `init` to "fill them in" — the env-ref form is intentional for CI/multi-env.
 
+### PostgreSQL, MySQL and MariaDB verified TLS
+
+When verified TLS is required, use the named `init` entry with both
+`--sql-tls verify-full --sql-tls-ca <path>`. PostgreSQL, MySQL and MariaDB support this SQL
+contract; explicit requests on other engines fail. The saved
+`sqlTls: { mode: 'verify-full', caPath: '/absolute/path/root-ca.pem' }` uses an
+absolute literal PEM path; `init` resolves relative paths from cwd. CA environment
+references are unsupported. Existing host/user environment references and profiles
+without `sqlTls` keep their behavior. V1 directory/v2 reads, normal `init` import
+from a V1 directory and `migrateV1ToV2` preserve TLS. Legacy V1 single-file TLS
+profiles remain readable/usable in human mode; automatic `init` import refuses
+before connecting or writing, preserving the original. Migrate that case by
+creating a verified named profile in a separate config directory, verifying it,
+then selecting it; preserve `sqlTls` throughout.
+
+Ambient TLS settings cannot weaken verification or supply another profile’s trust.
+Each connection reloads its own CA and verifies encryption, trust, validity and the
+configured DNS/IP identity; explicit SQL TLS refuses Unix sockets. Failures stop
+before the user query. Repair the CA, hostname or certificate; keep verification
+and TLS required. On binary rollback, stop TLS-required workflows or retain a
+supporting version: older binaries may strip `sqlTls`. Local fixture evidence does
+not establish real RDS acceptance. Configured permitted reads work in agent mode;
+`init` and other configuration changes remain refused.
+
+For TLS error recovery, repair certificates while retaining TLS, then explicitly
+select `--config <path>` or `--global`; v2 also requires `--use <name>` or
+`DBCLI_CONNECTION`. The selected profile must retain `sqlTls.mode: verify-full`.
+Missing, ambiguous or plaintext selections block live steps. Saved envelopes
+redact original selectors, so current targeting does not establish original
+provenance. Apply and verification use the current CLI binary. Example:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+For the complete configuration, example and failure contract, read
+[SQL verified TLS](reference.md#verified-tls-for-postgresql-mysql-and-mariadb).
+
 ### Decision tree (ask before writing)
 
 1. **What is the connection name?** Every new connection uses named v2, even

package/skills/dbcli/reference.md

@@ -157,7 +157,7 @@ Without a TTY, with `--no-interactive`, or when `--use-env-refs` plus all five `
 
 New initialization always creates named v2 configuration, including plain `init` and explicit `--config` paths; it no longer creates an unnamed v1 configuration. Existing v1 configurations remain readable and their established named v2 import is retained. The first explicitly named connection is still the default in a new registry; adding a connection preserves an existing registry's default or no-default state. An explicitly chosen duplicate name still requires interactive overwrite confirmation or `--force`; a noninteractive duplicate without `--force`, or a declined confirmation, leaves files untouched. `--remove` and `--rename` do not ask for a new connection name.
 
-**Key options:** `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
+**Key options:** `--sql-tls verify-full`, `--sql-tls-ca <path>`, `--system`, `--permission`, `--use-env-refs`, `--skip-test`, `--no-interactive`, `--force`, `--conn-name <name>`, `--env-file <path>`, `--remove <name>`, `--rename <old:new>`
 
 **Environment-reference options:** `--env-host <var>`, `--env-port <var>`, `--env-user <var>`, `--env-password <var>`, `--env-database <var>`
 
@@ -193,6 +193,57 @@ Use root-level `--global` with `init`, `use`, `status`, `query`, or any other co
 
 > **AI agent note on `--use-env-refs`:** If an existing `.dbcli` config contains `{"$env": "DB_HOST"}` style references, the connection values are read from environment variables at runtime. Do NOT re-run `init` to replace these references with actual values — the env-ref format is intentional for CI/CD and multi-environment setups.
 
+#### Verified TLS for PostgreSQL, MySQL and MariaDB
+
+Use both SQL TLS flags when creating a named PostgreSQL, MySQL or MariaDB profile. This example prompts for the password and tests the connection before saving:
+
+```bash
+dbcli init --conn-name verified-pg --system postgresql \
+  --host db.example.com --port 5432 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/root-ca.pem
+dbcli --use verified-pg blacklist list
+dbcli --use verified-pg schema public.events --format json
+dbcli --use verified-pg query "SELECT id FROM public.events LIMIT 10" --format json
+```
+
+MySQL and MariaDB use the same flags, with separate named profiles and CA paths. Select the corresponding profile, then check blacklist and schema before an authorized query:
+
+```bash
+dbcli init --conn-name verified-mysql --system mysql \
+  --host mysql.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mysql-ca.pem
+dbcli init --conn-name verified-mariadb --system mariadb \
+  --host mariadb.example.com --port 3306 --user reader --name appdb \
+  --permission query-only --sql-tls verify-full --sql-tls-ca ./certs/mariadb-ca.pem
+```
+
+Replace the host, database and table with your authorized target; confirm real columns through schema before querying. The saved connection includes this dedicated SQL object (shown as a connection fragment):
+
+```json
+{
+  "sqlTls": {
+    "mode": "verify-full",
+    "caPath": "/absolute/path/to/certs/root-ca.pem"
+  }
+}
+```
+
+`--sql-tls verify-full` and `--sql-tls-ca <path>` are required together. Empty values, other modes and unsupported engines fail explicitly. PostgreSQL, MySQL and MariaDB support this SQL TLS contract; all other engines reject an explicit request. MongoDB's `tls` and Elasticsearch's TLS settings remain separate. Existing profiles without `sqlTls` keep their previous behavior; no global TLS policy is added. V1 directory and v2 profile reads, normal `init` import from a V1 directory to v2, and the public `migrateV1ToV2` helper preserve the TLS object. A legacy V1 single-file TLS profile remains readable and usable in human mode, but automatic `init` import explicitly refuses it before connecting or writing and leaves the original untouched. For that case, create a verified named profile in a separate configuration directory, verify it, then select it; preserve `sqlTls` throughout migration.
+
+`init` resolves a relative CA path against its current working directory before saving. Saved `caPath` must be a nonempty absolute literal path to a PEM CA bundle; it accepts no environment-variable reference. Existing environment references in host/user and other supported fields remain usable. Explicit TLS uses only the selected profile’s CA and identity settings; ambient TLS settings cannot weaken verification or supply another profile’s trust. Each new connection reads the CA bundle again; an unreadable, empty or invalid bundle stops before connecting. `--skip-test` skips only the initialization test, not verification on subsequent use.
+
+`verify-full` requires encryption, a trusted certificate chain, valid certificate dates and certificate identity matching the configured DNS name or IP address. Unix sockets are refused for explicit SQL TLS. Untrusted, expired or mismatched certificates and servers without TLS fail before the user query; there is no plaintext retry or verification downgrade. Correct the CA, target hostname or certificate validity before retrying. A cipher alone does not prove identity verification.
+
+For TLS error recovery, keep TLS configured and repair the CA, hostname or certificate first. Then deliberately select the configuration with `--config <path>` (or `--global`) and, for v2, the named profile with `--use <name>` (`DBCLI_CONNECTION` is also accepted). The selected profile must still have `sqlTls.mode: verify-full`; missing, ambiguous or plaintext selections block live recovery steps instead of falling back to a default plaintext connection. Saved recovery envelopes redact the original selectors: your current selection is deliberate targeting, not proof of the original target. Recovery apply and verification use the current CLI binary, avoiding an older `dbcli` on PATH. For the MySQL example above:
+
+```bash
+bun run src/cli.ts --config .dbcli --use verified-mysql recover --apply --format json
+```
+
+Permitted reads through an already configured profile remain usable in agent mode; `init` and other configuration mutations remain refused under `DBCLI_AGENT_MODE=1`. TLS does not bypass explicit production selection, native database authorization, permission, blacklist, write-gate or audit controls.
+
+For binary rollback, stop workflows that require verified TLS or keep a supporting version. Older binaries may strip `sqlTls`; retaining the profile after downgrading does not preserve the guarantee. Removing TLS settings or retrying in plaintext cannot restore compliance. Local isolated PostgreSQL, MySQL and MariaDB fixture results are not evidence of real RDS acceptance; RDS remains unverified.
+
 ### use
 
 Set, clear, or display the default database connection (v2 multi-connection config).
@@ -1731,6 +1782,8 @@ Every actionable block carries machine-readable next steps so an agent can move
 
 ### capabilities
 
+`connection.tls` reports PostgreSQL, MySQL and MariaDB support from the engine capability matrix and maps to the existing connection command surfaces; it adds no TLS subcommand. Check with `dbcli --use verified-pg capabilities check --require connection.tls --format json`. `available` means tool support only: it does not prove that this profile configures TLS, the CA is readable, the handshake succeeds, or the operation is authorized. Catalog/check remain offline, read no CA bundle, perform no handshake and change no configuration. Other engines do not report this capability as available; older binaries without the ID return `unknown`. Configuration mutation still requires its own authorization.
+
 Discovery. Lists the static dbcli capability catalog — what this tool can do,
 described in a versioned shape an external Skill can parse before it starts
 working. It never opens a database connection and never writes anything.