Emit structured local runtime errors in JSON mode

[sdairs]

Summary

• emit one structured local runtime error object on stderr for explicit --json and detected-agent mode while leaving stdout empty
• define and document a closed 11-code taxonomy with fixed, non-interpolated recovery commands
• preserve human error text, existing exit codes, and native child stdout/stderr/status behavior
• redact opaque startup, download, filesystem, and fallback diagnostics and keep telemetry unchanged

Closes #475

Schema

{
  "error": {
    "code": "server_not_found",
    "message": "Server 'default' not found",
    "command": "clickhousectl local server list"
  }
}

The README pins the full code set: server_not_found, server_not_running, server_running, invalid_version, version_unavailable, port_in_use, startup_exit, startup_timeout, download_failed, io_error, and bounded fallback local_error. Progress is silent in structured mode so stderr remains one JSON object on failure. Clap usage errors and native protocol/child output remain outside the envelope.

Verification

• cargo fmt --all --check
• cargo build -p clickhousectl
• cargo check -p clickhousectl --no-default-features
• cargo test -p clickhousectl (776 passed)
• cargo clippy -p clickhousectl --all-targets -- -D warnings
• subprocess matrices assert exact schema, stderr/stdout placement, status, agent detection, human output, redaction, startup/download boundaries, and native child passthrough

Stack

• Position: child 6 of 6 in gh-stack #489
• Base: Preserve native query and query-file multiplicity in local client #506 (issue-470-local-client-query-multiplicity)
• Parent PR is unchanged and should merge first.

[macroscopeapp]

🟠 High local/postgres.rs:107

A stopped existing instance cannot be resumed when the caller supplies an occupied --port; preflight_start_options returns PostgresValidation before start reaches resume_existing. The resume path intentionally ignores supplied settings and uses the stored port, so defer explicit-port availability validation until the fresh-create path.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @crates/clickhousectl/src/local/postgres.rs around line 107:

A stopped existing instance cannot be resumed when the caller supplies an occupied `--port`; `preflight_start_options` returns `PostgresValidation` before `start` reaches `resume_existing`. The resume path intentionally ignores supplied settings and uses the stored port, so defer explicit-port availability validation until the fresh-create path.

[sdairs]

No change. The earlier PR #486 review deliberately retained validation of supplied ports before recovery/Docker work per issue #460. Resume defers auto-selection only when --port is omitted; an occupied explicit port is an invalid invocation even if the stored instance would otherwise resume with a different binding. Existing regressions pin both behaviors.

[iskakaushik]

LGTM

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9d275eb. Configure here.}

[cursor]

Postgres port exhaustion wrong code

Medium Severity

When Postgres auto-selection cannot find a free port, the failure is still raised as PostgresRuntime, so structured mode maps it to local_error with a generic Postgres message. The same exhaustion case for ClickHouse was converted to PortInUse and correctly emits port_in_use, so agents cannot classify this Postgres failure under the documented port code.

Additional Locations (2)

• crates/clickhousectl/src/local/server.rs#L632-L657
• crates/clickhousectl/src/local/output.rs#L88-L130

 

^{Reviewed by Cursor Bugbot for commit 9d275eb. Configure here.}

[sdairs]

Superseded by #556 in stack #563.