Give local JSON errors the same detail and hints as human output

[sdairs]

Why

local --json errors were consistently thinner than the human Error: ... line they replace, which is backwards: JSON is the surface coding agents read. Issue #608 reported three cases; this fixes them and the rest of the mapping they were symptoms of.

What

• Wrong hint. local server remove <running> suggested clickhousectl local server list; it now suggests clickhousectl local server stop <name> — the step that actually recovers — and carries the human message's stop it first with ... clause.
• Lost detail. Errors whose text clickhousectl composes itself are now rendered verbatim, so local server start --config does-not-exist reports config 'does-not-exist' not found in <dir> (available: analytics.xml) in JSON instead of {"code":"local_error","message":"Local command failed"}.
• Conflated code. local remove <not-installed-version> now reports a new version_not_installed code with a clickhousectl local list hint, instead of version_unavailable / clickhousectl local list --remote, which described an unresolvable download.

The mapping became an exhaustive match over Error. Every variant picks one of two documented rules: parity (render the error's own Display) or redaction (a curated summary). A new Error variant now has to be classified rather than silently collapsing into the fallback. Only text interpolating output we do not control stays summarized — subprocess stderr and log tails (startup_exit, startup_timeout), Docker daemon strings (docker_error), download bodies (download_failed), OS/serde sources (io_error, local_error).

New codes replace the fallback where it was hiding real classifications: version_not_installed, version_selection_required, version_already_installed, unsupported_client_version, unsupported_platform, config_not_found, invalid_config_name, invalid_server_name, unsupported_argument, docker_unavailable, docker_error, network_error. Docker unavailability is built by local::docker from a classified failure kind and platform guidance and never renders the daemon's own text, so it now reaches JSON in full.

Two small adjacent fixes the audit turned up:

• The --config passthrough guard used Error::Exec, whose payload is subprocess text and therefore redacted, so a pure usage mistake produced an opaque local_error. It now uses a dedicated Error::UnsupportedArgument.
• The bare server remove selection error gained "no server was removed" in human mode, which JSON already stated.

error.command is now Option<String> so a hint can name the concrete server or version.

Tests

cargo fmt --all, cargo clippy --workspace --all-targets -- -D warnings, cargo test -p clickhousectl (all green), plus cargo check --workspace --all-features.

• Inline exact-payload tests for the three reported cases.
• self_composed_errors_serialize_their_human_message_verbatim asserts message == error.to_string() across every parity-classified error, so the two surfaces cannot drift again.
• errors_carrying_foreign_output_stay_summarized asserts the complement, including that no injected secret or path is serialized.
• Subprocess coverage in local_structured_errors_test.rs for missing config, escaping config name, passthrough argument, the not-installed version, and the Docker diagnostic (still asserting the socket path and metadata contents never leak).
• Existing exact-JSON expectations updated in the postgres readiness/validation, server selection and server state-machine suites.

README documents the two message rules and the extended error-code table.

Stacking

Part of a stacked chain: based on fix/600-local-remove-global-guard, not main. Keeps JSON parity with the local remove guards added there (version_is_default, server_running for VersionInUse).

Fixes #608

🤖 Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ 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 9786ed4. Configure here.}