@carllee1983/dbcli 1.55.1 → 1.57.0

package/.cursor/rules/dbcli.mdc

@@ -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

package/.cursor/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

package/.github/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

package/.github/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

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to dbcli are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.57.0] - 2026-08-14 - One connection's password, rotated on its own
+
+### Added
+
+- **`dbcli password [connection]` — rotating one connection's password no longer means editing the rest of its config.** A connection whose password is rotated on a schedule previously had two options: re-run `init` and re-enter every other field, or hand-edit the env file and hope the key name matched what the reader looks for. The new command changes the password and nothing else. Where the value lands is read from the config rather than derived from a naming rule: `password: { "$env": "NAME" }` rewrites `NAME` in that connection's `envFile`, and a connection still holding a literal password is converted to `{ "$env": "DBCLI_<CONN>_PASSWORD" }` once, so every later rotation touches only the env file. v1 configs rewrite `DBCLI_PASSWORD` in `.env.local`, matching the v1 reader at `src/core/config.ts:200`; a v1 config whose password comes from any other environment variable is refused with the reason, because v1 has no per-connection env file and no file dbcli could write would make that variable resolve. The new password is verified by connecting with it **before** anything is written — a rejected credential exits 1 with the stored value untouched, rather than leaving a config that no longer opens the database — with `--skip-test` for when the database is unreachable from where the rotation runs. Three input paths, one of which must be chosen: a masked prompt (never a plain-text fallback, since that would print the secret into the scrollback), `--stdin` for rotation scripts, and `--password` for callers that accept shell-history exposure. The env file is written `0600` on POSIX (Windows has no equivalent mode bit, so the file inherits the directory's ACL), the value never reaches stdout, stderr, or the audit log, and `DBCLI_AGENT_MODE=1` refuses at the first line of the action rather than after prompting and connecting.
+
+### Fixed
+
+- **A password written to a connection that declared no `envFile` could not be read back.** `loadConnectionEnv` (`src/core/config-v2.ts:164`) loads only the file a connection names, and the `.env.local` fallback in `src/core/config.ts:274` recognizes exactly one key, v1's `DBCLI_PASSWORD`. So writing `DBCLI_<CONN>_PASSWORD` into `.env.local` for a v2 connection with no `envFile` produced a config whose `$env` reference resolved to nothing: `Environment variable not defined`, on every subsequent command. Rotation now records `envFile` on the connection as part of the write. `tests/unit/core/connection-credential.test.ts` asserts the round trip through `configModule.read()` for all four paths (v2 with and without `envFile`, v2 converted from a literal, v1) rather than asserting the file merely contains the expected line — the file being right while the reader cannot see it is precisely the failure that shipped otherwise.
+
+- **A password containing `$&`, `$1`, or `` $` `` was silently stored as something else.** The in-place rewrite passed the new line as `String.replace`'s second argument, where `$`-patterns are substitution syntax: rotating to `a$&b` over an existing `K=old` wrote `K=aK=oldb`. Verification passed because it used the in-memory value, so the command reported success and the next connection attempt failed with a password nobody could reproduce. The replacement is a function now, which does no `$` expansion. Values are also written quoted (`NAME="…"`), because both env parsers trim the whole line before splitting — an unquoted value silently lost leading and trailing whitespace. `parseEnvPassword` strips one layer of matching quotes to match `parseEnvContent`, so values written by either path read back identically.
+
+### Removed
+
+- **`writeConnectionSecret` — the exported helper wrote to a file the reader never opens.** Exported from `@carllee1983/dbcli/core`, it derived the env var name from the connection name and defaulted the file to `.env.<connection>` when a connection declared no `envFile`, while the reader falls back to `.env.local` and, for connections created with `init --use-env-refs --env-password <VAR>`, looks up `<VAR>` rather than the derived name. Both mismatches ended the same way: a write that succeeded and a password that could not be read. `setConnectionPassword` and `resolvePasswordTarget` replace it on the same barrel — they resolve the target from the config, convert a literal password once, and record `envFile` when it is missing. Callers of the old function should switch to `setConnectionPassword(projectPath, connectionName, value)`; the `field` parameter is gone, since `'password'` was its only accepted value.
+
+## [1.56.0] - 2026-08-13 - The package no longer runs the CLI when you import it
+
+### Removed
+
+- **`exports["."]` — importing the package ran the CLI instead of returning a module.** The root export pointed at `dist/cli.mjs`, and `src/cli-runtime.ts:280-290` calls `outputHelp()` and `parseAsync(process.argv)` at module top level with no guard. So any import that reached the runtime executed the CLI against the host process's argv: under Bun, `await import('@carllee1983/dbcli')` printed 186 lines of help and exited 1 — the statement after the import never ran — and under Node it threw `ERR_MODULE_NOT_FOUND` for the same extensionless `./cli-runtime` specifier described in v1.55.0. `.` is gone; `./core` and `./agent-core`, both with `types`, are the library surface, and neither bundle contains `cli-runtime`. `bin` does not resolve through `exports`, so `dbcli` itself is untouched. Anyone importing the root now gets `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a process that exits — a declaration withdrawn, not a capability. `tests/integration/runtime-contract.test.ts` asserts no `exports` target is the `bin` target, and keeps a positive control on the top-level side effect, so if `cli-runtime` ever stops executing on import the test says so rather than leaving the export permanently unreconsidered (#67).
+
 ## [1.55.1] - 2026-08-13 - The Bun-missing warning actually reaches the user
 
 ### Fixed

package/README.dev.md

@@ -108,6 +108,7 @@ Then ship a patch version with the fix. Prefer **deprecate** over **unpublish**
 - **`prepublishOnly`:** `bun run build` so `dist/cli.mjs` matches current source.
 - **`engines`:** Declares `bun >= 1.3.3` only. `node` was removed because the published bundles cannot run on Node: `dist/cli.mjs` dynamic-imports the extensionless `./cli-runtime` (Bun's resolver appends `.mjs`, Node's does not) and `dist/core.mjs` calls Bun globals. `tests/integration/runtime-contract.test.ts` fails if `engines.node` comes back without the bundles being fixed to match, and if `dist/agent-core.mjs` — the one entry point that is Node-importable — regresses. See `docs/adr/0008-dbcli-is-a-bun-program-and-engines-says-so.md`.
 - **Shebang:** `scripts/build.ts` prepends `#!/usr/bin/env bun` to `dist/cli.mjs`; the `bin` field in `package.json` points at that file.
+- **`exports`:** `./core` and `./agent-core` only — there is deliberately no `.` entry. It used to point at `dist/cli.mjs`, and `src/cli-runtime.ts` calls `outputHelp()` and `parseAsync(process.argv)` at module top level, so importing the package ran the CLI against the host's argv and never returned. `bin` does not resolve through `exports`, so the executable is unaffected. `tests/integration/runtime-contract.test.ts` pins both the absence of `.` and the side effect that justifies it.
 - **`postinstall`:** `scripts/postinstall-check-bun.mjs` reports a missing Bun — npm ignores `engines.bun`, so this is the only signal an npm-only machine gets before `dbcli` refuses to start. The command is `bun … || node …` so it runs under whichever runtime is present: Bun-only machines have no `node` to invoke it with, and a hard `node` dependency there would break the primary install path. It must **not** end in `|| exit 0`; v1.55.0 shipped with that mask and npm, which hides lifecycle output unless a script fails, therefore showed nothing at all. On a global install (`npm_config_global === 'true'`) a missing Bun exits 1, so the reason is printed and npm rolls the `bin` back; a dependency install only warns, because that is the `./agent-core` consumer. Both outcomes are pinned in `tests/integration/runtime-contract.test.ts`.
 - **Live DB tests:** `tests/integration/live-db.test.ts` uses project `.dbcli` by default or `LIVE_DB_CONFIG_PATH` when you point at another config directory. Set `SKIP_INTEGRATION_TESTS=true` to skip all integration tests.
 

package/assets/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

package/assets/SKILL.zh-TW.md

@@ -246,6 +246,17 @@ dbcli init --rename staging:stg           # rename
 dbcli init --remove stg                   # remove
 ```
 
+只輪替單一連線的密碼，其餘設定不動：
+
+```bash
+dbcli password prod                       # 遮蔽輸入
+rotate-secret | dbcli password prod --stdin   # 供排程輪替腳本使用
+```
+
+新密碼會寫進 config 實際參照的 env 變數（明文密碼會在第一次使用時轉成
+`{ "$env": ... }`；連線沒宣告 `envFile` 時會一併補記錄，讀取端才載得到），
+存檔前先用它連一次驗證（`--skip-test` 可跳過），env 檔在 POSIX 上以 0600 權限寫入。
+
 若要讓多個專案共用連線，請使用明確的 root-level `--global` scope。它會把 v2 registry 儲存在 `~/.config/dbcli/config.json`，不會建立或修改專案 binding：
 
 ```bash

package/assets/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