Allow direct local client connections to select a binary version

[sdairs]

Summary

• add direct-mode local client --version selection for installed ClickHouse binaries without modifying the global default
• define actionable zero, one, multiple, stale-default, missing-explicit, and named-mode behavior
• document connection selection versus local binary selection and reject named-mode version overrides during clap parsing
• cover parser behavior and the complete isolated fake-binary subprocess matrix

Tests

• cargo test -p clickhousectl
• cargo clippy -p clickhousectl --all-targets -- -D warnings
• cargo fmt --all --check

Closes #469

[sdairs]

Carry-over review from PR #500 (old PR for #469). Functionally this PR is stronger than #500 (parse-time typed validation with genuinely good postgres/latest rejection messages, deliberate+documented zero/one/multiple fallback policy, broader subprocess matrix, default-file non-mutation asserted). Two required items:

1. Trim the --version help noise — sdairs' only review comment on Allow direct local client connections to select a binary version #500 applies here, more strongly. On Allow direct local client connections to select a binary version #500, sdairs wrote: "good but adds too much noise to agent context help. it is unlikely that thorough explanation of a --version flag is needed beyond the actual flag description", and then addressed it: "removed the redundant --version explanation from agent-context help, restored the existing concise connection/default wording, and retained the flag and its description." This PR re-adds exactly that explanation in crates/clickhousectl/src/local/cli.rs:~246-254 (after_help): the connection-vs-binary sentence and a full resolution-semantics paragraph ("Direct mode without --version uses a valid default… sole installed version… stale default must be repaired…"), and it locks the noise in with a test (clickhouse_client_help_distinguishes_connection_and_binary_selection, cli.rs:~971-984) asserting six substrings — so trimming later breaks the suite. Issue Allow direct local client connections to select a binary version #469's criterion 5 does require help to distinguish connection selection from binary selection, so some text is warranted — but Allow direct local client connections to select a binary version #500's accepted end state satisfied that with the flag description alone ("Installed local client version for direct host/port mode (e.g. 25, 25.12, or 25.12.9.61). Does not change the default.") plus the README. Cut the resolution-semantics lines from after_help, keep the detail in README and the flag description, and adjust the pinned test accordingly.

2. Fix the IO-error masking (open low-severity Cursor finding here). try_resolve_local (crates/clickhousectl/src/version_manager/resolve.rs:~35) swallows list_installed_versions() IO errors via .ok()?, so an explicit --version against an unreadable ~/.clickhouse/versions reports ClientVersionNotInstalled, while the no-default branch propagates the IO error. Inconsistent and misleading. Propagate the error in the explicit-version path too (Allow direct local client connections to select a binary version #500's explicit path used list_installed_versions()? and did not have this).

Cosmetic: partial-version "newest installed match" is a mild expansion beyond the issue's "explicit exact version" framing — it is documented and user-directed, so acceptable, but confirm intentional.

[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 88a5e8f. Configure here.}

[cursor]

Client version parser skips trimming

Low Severity

ClientVersionArg checks the postgres@ / postgres: prefix on the raw input instead of trimming first, so a whitespace-padded selector misses the dedicated rejection path and falls through to the generic numeric parse error. UseVersionArg and ServerVersionArg trim before that check.

 

^{Reviewed by Cursor Bugbot for commit 88a5e8f. Configure here.}