@carllee1983/dbcli 1.11.0 → 1.17.0

package/assets/reference.md

@@ -439,6 +439,302 @@ dbcli status --format text      # Human-readable text output
 **Output:** `permission`, `system`, `blacklist` summary, `version`
 **Permission:** query-only+
 
+### inspect
+
+Read-only snapshot for AI agents. Never emits credentials or blacklisted values.
+
+| Flag | Purpose |
+|------|---------|
+| `--format <json\|markdown>` | Output format (default `json`) |
+| `--brief` | Drop sample arrays and trim suggested commands to ≤3 |
+| `--for-agent` | Shortcut for `--format json --brief` |
+| `--no-connect` | Skip the cheap version/object probe (no DB traffic) |
+| `--probe-timeout <ms>` | Hard timeout for the version/object probe (default 1500) |
+
+Example:
+
+```bash
+dbcli inspect --for-agent
+```
+
+Output schema is locked at `schemaVersion: 1`. Sections: `connection`, `permission`, `blacklist`, `objects`, `schemaCache`, `snippets`, `suggestedCommands`, `warnings`.
+
+**Permission:** query-only+
+
+### report
+
+Diagnostic report built on top of `inspect`. Reuses inspect context (connection,
+permission, blacklist, snippet inventory) and additionally runs curated built-in
+`@diag/*` snippets grouped into sections.
+
+Flags:
+- `--format json|markdown` (default: json)
+- `--section health,capacity,perf` (default: all three)
+- `--brief` — drop evidence rows; keep counts and statuses
+- `--for-agent` — shortcut for `--format json --brief`
+- `--no-connect` — context-only snapshot (skip diagnostics + inspect probe)
+- `--per-snippet-timeout <ms>` (default 3000)
+- `--max-rows-per-evidence <n>` (default 50)
+- `--probe-timeout <ms>` (default 1500, inherited from inspect)
+
+Examples:
+
+    dbcli report --format json
+    dbcli report --format markdown --section health,capacity
+    dbcli report --for-agent
+    dbcli report --no-connect
+
+Boundaries:
+- Read-only. Skips snippets whose required params have no default value.
+- Never connects in `--no-connect` mode.
+- MongoDB and no-config workspaces emit a context-only snapshot with a warning.
+
+**Permission:** query-only+
+
+### guide
+
+Deterministic next-command planner for a fixed set of database goals. Reuses
+`inspect` context (cache-first) and the workspace's saved-query inventory to
+emit an ordered, read-only plan that an AI agent can follow step-by-step.
+
+Goals (fixed list):
+- `slow-query` — diagnose slow queries (long-running, locks, cache, indexes).
+- `capacity` — audit storage and memory.
+- `health` — connections, locks, cluster status.
+- `index-usage` — index effectiveness audit.
+- `permissions` — review permission level, blacklist, snippet inventory.
+- `schema-overview` — orient in an unfamiliar database.
+
+Flags:
+- `--format json|markdown` (default: json)
+- `--brief` — drop rationale + expects fields
+- `--for-agent` — shortcut for `--format json --brief`
+- `--list` — list available goals and exit
+- `--probe` — refresh inspect context via live probe (default: cache-first)
+- `--probe-timeout <ms>` (default 1500, inherited from inspect)
+
+Examples:
+
+    dbcli guide slow-query
+    dbcli guide capacity --format markdown
+    dbcli guide --list
+    dbcli guide health --for-agent
+    dbcli guide schema-overview --probe
+
+Boundaries:
+- Read-only. Guide plans commands; it does not execute them.
+- Goal vocabulary is fixed in v1.14.0; user-supplied goals are rejected.
+- Each step carries `risk: 'readonly'` in v1.14.0 (forward-compatible with v1.15.0 recovery).
+- Coexists with `dbcli skill tasks plan` (template-driven). Use guide for ad-hoc goals; use task packs for repeatable workflows.
+
+**Permission:** query-only+
+
+### recovery
+
+Machine-readable error envelope. Two surfaces share one `RecoveryEnvelope`
+shape (`schemaVersion: 1`):
+
+1. **Standalone lookup**: `dbcli recovery --code <CODE>` synthesizes an
+   envelope for any known recovery code without needing a real failure.
+2. **Failing-command opt-in**: pass `--recovery` to `dbcli query` or
+   `dbcli q`. On failure, the envelope is written to stdout as JSON, the
+   human stderr message is suppressed, and the process exits non-zero.
+
+Recovery codes (fixed in v1.15.0):
+- `CONFIG_MISSING` — no `.dbcli` config; run `dbcli init`.
+- `CONN_REFUSED` / `CONN_AUTH_FAILED` / `CONN_TIMEOUT` / `CONN_HOST_NOT_FOUND` / `CONN_UNKNOWN` — connection failure variants.
+- `PERMISSION_DENIED` — active permission level forbids the operation.
+- `BLACKLIST_TABLE` / `BLACKLIST_COLUMN_WRITE` — blacklist violations.
+- `SNIPPET_NOT_FOUND` / `SNIPPET_AMBIGUOUS` / `SNIPPET_PARAM_MISSING` — saved-query failures.
+- `SCHEMA_CACHE_MISSING` — local schema cache missing or stale.
+- `UNKNOWN` — fallback for unclassified errors.
+
+Flags (lookup mode):
+- `--code <CODE>` — required unless `--list` is set.
+- `--list` — list all codes and exit.
+- `--format json|markdown` (default: json).
+- `--brief` — drop `rationale` + `expects` from steps.
+- `--for-agent` — shortcut for `--format json --brief`.
+- `--hint <text>` — bind into placeholder steps.
+- `--snippet <name>` — bind snippet placeholder.
+- `--table <name>` — bind table placeholder.
+
+Examples:
+
+    dbcli recovery --code CONN_REFUSED
+    dbcli recovery --code BLACKLIST_TABLE --table users --format markdown
+    dbcli recovery --list --for-agent
+    dbcli query "SELECT * FROM users" --recovery
+    dbcli q @diag/missing --recovery
+
+Boundaries:
+- Recovery only **suggests** commands; agents (or humans) execute them. No automatic remediation in v1.15.0.
+- As of v1.16.0, `--recovery` is honored on `query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, and `inspect`. Other commands (`report`, `guide`, `doctor`, `migrate`, `init`, `use`, `status`, `list`, `check`, `diff`, `plan`, `shell`, `blacklist`, `completion`, `upgrade`, `skill`) keep their existing error behavior.
+- `dbcli inspect --require-schema-cache` throws `SCHEMA_CACHE_MISSING` when the active SQL connection has no usable schema cache. Combine with `--recovery` for the structured envelope.
+- `BLACKLIST_COLUMN_WRITE` and `PERMISSION_DENIED` envelopes prepend a `risk: 'dry-run'` step (e.g. `dbcli insert <table> --dry-run`) when the failing operation was an INSERT / UPDATE / DELETE.
+- Recovery steps reuse the v1.14.0 `GuideStep` shape, including the full `risk` enum (`readonly` / `dry-run` / `write` / `unknown`).
+
+**Permission:** n/a
+
+### recover
+
+(v1.17.0+) Inspect or apply the last recovery plan saved by `--recovery`.
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--apply` | Execute the saved plan under risk gating. | off (inspect only) |
+| `--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) |
+| `--format <format>` | `markdown` \| `json`. | `markdown` for inspect, `json` for `--apply` |
+
+#### Plan source resolution
+
+1. `--from <path>` if provided. The file must be either a raw `RecoveryEnvelope` or a `SavedRecoveryEnvelope` wrapper. When the file is a `SavedRecoveryEnvelope`, its `cwd` is reused for child-process execution. Strict zod validation; malformed → exit 2 with structured reason.
+2. Otherwise, `.dbcli/last-recovery.json` (auto-saved on every recovery emission). Validated with the same schema; missing fields, unknown `error.code`, or `cwd` that no longer exists → exit 2.
+3. Otherwise, exits 2 with `No recovery plan available. Run a command with --recovery to generate one, or pass --from <file>.`
+
+#### Code-owned tier (trust boundary)
+
+`--apply` derives the canonical execution tier from the per-`error.code` allowlist after parsing argv, **not** from the envelope's `risk` / `dbWrite` / `interactive` fields. Envelope hints can only widen safety (skip more steps); they cannot escalate execution.
+
+| Allowlist tier | Meaning | Example commands |
+|---|---|---|
+| `readonly` | local read-only | `dbcli inspect`, `dbcli doctor`, `dbcli blacklist list`, `dbcli schema <table>` |
+| `dry-run` | write subcommand invoked with `--dry-run` | `dbcli update orders --where id=1 --dry-run`, `dbcli q @x --dry-run` |
+| `local-write` | writes local config / cache / blacklist | `dbcli blacklist remove <table>`, `dbcli use <name>`, `dbcli schema --refresh` |
+| `db-write` | mutates the connected database | `dbcli update orders --where id=1 --set …` (no `--dry-run`), `dbcli q @x` (no `--dry-run`) |
+| `interactive` | requires TTY | `dbcli init`, `dbcli init --force` |
+
+`insert` / `update` / `delete` / `q` are tier `dry-run` only when argv contains `--dry-run`; otherwise they are tier `db-write` regardless of envelope `risk` claim.
+
+#### Risk gate matrix
+
+| Allowlist tier | Default | `--allow-write=readonly-cmd` | `--allow-write=write-cmd` |
+|---|---|---|---|
+| `readonly` | run | run | run |
+| `dry-run` | run | run | run |
+| `local-write` | `skipped:risk` | run | run |
+| `db-write` | `skipped:risk` | `skipped:risk` | run |
+| `interactive` | `skipped:interactive` | `skipped:interactive` | `skipped:interactive` |
+| unresolved placeholder in `command` | `skipped:placeholder` | `skipped:placeholder` | `skipped:placeholder` |
+| command fails parse / allowlist | `skipped:unsafe-command` | `skipped:unsafe-command` | `skipped:unsafe-command` |
+
+Precedence: envelope `interactive: true` > `placeholder` > `unsafe-command` > allowlist `interactive` > tier-based gating.
+
+#### Exit codes
+
+| Code | Condition |
+|---|---|
+| 0 | At least one step ran successfully and no step failed. |
+| 1 | A step exited non-zero (fail-fast); see `stoppedAt`. |
+| 2 | Envelope missing or malformed (failed schema validation, or saved `cwd` missing). |
+| 3 | Every step was skipped — open `--allow-write` or fill placeholders. |
+
+#### Auto-saved envelope
+
+Every command that emits a `RecoveryEnvelope` (`query`, `q`, `insert`, `update`, `delete`, `export`, `schema`, `inspect` — all with `--recovery`) atomically writes the envelope to `.dbcli/last-recovery.json`. The wrapper carries `schemaVersion`, `savedAt`, a sanitized `command` summary, the workspace `cwd`, and the envelope itself. SQL text and `--where` / `--set` / `--data` / `--param` values are redacted as `<sql>` or `<redacted>`. `.dbcli/` is gitignored.
+
+#### Verification (P4)
+
+Each `RecoveryEnvelope` now carries an optional `verify: GuideStep` (always
+`risk: 'readonly'`, never carries placeholders). `dbcli recover --apply` runs
+the verify step after the main plan, only when `finalStatus === 'ok'` and
+`--no-verify` is not set.
+
+| Recovery code | Verify command | Heuristic |
+|---|---|---|
+| CONFIG_MISSING | `dbcli inspect --no-connect --format json` | `connection.name` truthy → passed |
+| CONN_REFUSED / CONN_TIMEOUT / CONN_UNKNOWN / CONN_AUTH_FAILED / CONN_HOST_NOT_FOUND | `dbcli doctor --format json` | exit 0 → passed |
+| PERMISSION_DENIED | `dbcli inspect --for-agent` | exit 0 → passed |
+| BLACKLIST_TABLE | `dbcli inspect --for-agent` | exit 0 → passed |
+| BLACKLIST_COLUMN_WRITE | `dbcli inspect --for-agent` | exit 0 → passed |
+| SNIPPET_NOT_FOUND / SNIPPET_AMBIGUOUS / SNIPPET_PARAM_MISSING | `dbcli queries list --format json` | exit 0 → passed |
+| SCHEMA_CACHE_MISSING | `dbcli inspect --format json` | `schemaCache.available === true` → passed |
+| UNKNOWN | `dbcli doctor --format json` | exit 0 → passed |
+
+`verifyStatus` values:
+
+- `passed` — heuristic confirmed.
+- `failed` — verifier exited non-zero or timed out.
+- `indeterminate` — verifier exited 0 but expected shape not present, or the
+  step was gated (placeholder / unsafe-command); agents should re-check.
+
+Exit codes are unchanged — `verifyStatus` is signal, not gate.
+
+**Schema additions.** `RecoveryEnvelope.verify?: GuideStep` is additive (no
+`schemaVersion` bump). v1.16 consumers ignore the field.
+
+#### Multi-turn `--next` (P2)
+
+`dbcli recover --next` returns the single next step in a saved recovery plan,
+given which step the agent just executed and the result of that step. v1 walks
+the plan linearly; future codes may branch on `prevResult.stdoutSummary`
+deterministically.
+
+| Flag | Required | Description |
+|---|---|---|
+| `--next` | yes | Activate the multi-turn lookup. |
+| `--after-step <n>` | yes | 1-based order of the step the agent just executed. Range: `[1, envelope.recovery.length]`. |
+| `--result <value>` | yes | JSON `StepResultSummary` (inline) or `@<path>` to read from a file. |
+| `--from <path>` | no | Override the auto-saved envelope. |
+| `--format <fmt>` | no | `json` (default) or `markdown`. |
+
+`--next` and `--apply` cannot be combined. `--allow-write` and `--no-verify`
+are silently ignored under `--next` (no execution, no verification).
+
+**`StepResultSummary` shape**
+
+```ts
+interface StepResultSummary {
+  status: 'ok' | 'failed' | 'skipped'
+  exitCode?: number
+  stdoutSummary?: string  // last 4 KB; longer rejected
+  stderrSummary?: string  // last 4 KB; longer rejected
+}
+```
+
+`@<path>` resolves relative to the dbcli invocation cwd. File whole-size cap is
+64 KB; per-field 4 KB cap still applies.
+
+**`NextResult` shape (output)**
+
+```ts
+interface NextResult {
+  schemaVersion: 1
+  kind: 'step' | 'done'
+  source: { kind: 'auto' | 'from'; path: string }
+  errorCode: RecoveryCode
+  cursor: number       // step.order when kind='step'; totalSteps when 'done'
+  totalSteps: number
+  step?: GuideStep     // present iff kind='step'
+}
+```
+
+**Exit codes**
+
+| Exit | Condition |
+|---|---|
+| 0 | Returned a step or `done`. |
+| 2 | Envelope missing/malformed; `--after-step` missing/out-of-range; `--result` missing/malformed; `--next` combined with `--apply`. |
+
+**Examples**
+
+```bash
+# Walk a 3-step plan to completion
+dbcli recover --next --after-step 1 --result '{"status":"ok"}'   # → step 2
+dbcli recover --next --after-step 2 --result '{"status":"ok"}'   # → step 3
+dbcli recover --next --after-step 3 --result '{"status":"ok"}'   # → done
+
+# Result read from file (when stdout is large)
+dbcli recover --next --after-step 1 --result @/tmp/r1.json
+
+# Markdown for human inspection
+dbcli recover --next --after-step 1 --result '{"status":"ok"}' --format markdown
+```
+
+**Permission:** n/a (always-allowed lookup; child processes inherit the active permission level).
+
 ### doctor
 
 Run diagnostic checks on environment, configuration, connection, and data.