Scope CLI↔client contract test coverage

[sdairs]

Summary

The live integration tests exercise the typed Rust client library. The CLI (crates/clickhousectl/) is a thin wrapper over that library, so most regressions caught by cargo build cover both. But the CLI also assembles request bodies from clap-parsed args and prints responses — that assembly logic isn't tested today.

This issue is scoping work: figure out what contract coverage looks like and what it would catch.

Questions to answer

• What classes of bug would slip through cargo build + library integration tests but be caught by CLI-level tests? Candidates:
  • CLI builds a request body that drops a required field.
  • CLI's --flag to API field mapping silently desyncs from the library's expected request shape.
  • CLI's JSON output mode doesn't round-trip through the library types (regression in Display vs serde).
• Should this be assertion-on-snapshot (the CLI invocation produces an expected wire request), wiremock-driven (CLI hits a local mock, assert the request), or both?
• Where does this live — crates/clickhousectl/tests/ (new), or extend client_test.rs to assert request shape only?

Out of scope

• Implementing the coverage. This issue produces a proposal + a sub-issue or two with concrete scope.

Notes

• This was raised in the context of why we don't path-filter live tests. The argument was: if CLI-only PRs run no live tests, we need some coverage that catches a broken contract. Until contract tests exist, we run live everywhere.

Parent: #151

[sdairs]

Proposal: CLI↔client contract test coverage

Goal

Two things to assert at this layer, neither of which cargo build or the live integration tests catch:

1. CLI → library wiring: the CLI's clap-parsed args build the library request types with the right fields populated. Catches things like a --idle-timeout-minutes flag silently dropping its value because the Options struct field was renamed, or a new optional field being added to the lib request type without a corresponding CLI flag.
2. Library → wire serialization: the library request types serialize to the camelCase JSON shape the API actually expects, at the HTTP method + path + body the spec describes. The library's client_test.rs already does this at the library boundary; the gap is asserting the CLI's invocation produces the same wire request.

In short: when a CLI-only PR runs no live tests, this layer should still fail if either of the above contracts breaks.

Current state

• cli_request_shape_test.rs is referenced in CLAUDE.md but does not exist — crates/clickhousectl/tests/ doesn't exist at all, and wiremock is not a dev-dep of the CLI crate.
• The closest existing coverage is the #[cfg(test)] mod tests block at the bottom of crates/clickhousectl/src/cloud/commands.rs (line ~2030 onwards), which has ad-hoc shape assertions for 6 of the 8 build_*_request helpers. Coverage is partial: each helper has one happy-path test that cherry-picks a few field assertions rather than asserting the full serialized JSON, and a couple of *_rejects_* validation tests. Optional-vs-required serialization (camelCase keys absent when None) is not consistently asserted.
• clickhouse-cloud-api/tests/client_test.rs is wiremock-driven and covers all 100 library client methods, but at the library boundary — it never goes through the CLI's clap parsing or the CloudClient wrapper.
• The CLI has ~40 cloud command handlers; ~8 of them build a request body (POST/PATCH), the other ~32 are GET/DELETE/list and pass args straight to path segments / query params.

So the gap is: clap-parsed CLI invocation → library request type construction → wire JSON. Nothing exercises that whole path end-to-end today.

Recommendation: hybrid (snapshot first, then wiremock)

Snapshot for breadth on the inputs side, wiremock for one targeted layer that catches transport-level regressions. Snapshot tests against the full serialized JSON of each build_*_request helper are cheap, reviewable in PR diffs, and slot into the existing in-module pattern with zero new dependencies — that's the right tool for asserting "every CLI flag round-trips into the right field of the request body." But snapshots alone miss method/path/header regressions and don't exercise clap. A small wiremock-driven binary at crates/clickhousectl/tests/cli_request_shape_test.rs (the file CLAUDE.md already references) closes that gap for the 8 body-building commands without ballooning maintenance cost. Doing snapshot-only is too narrow; doing wiremock-only is unnecessarily heavy for the 32 commands that don't build a body — hybrid pays the cost only where it returns a fault class snapshots can't catch.

Sub-issues filed

Both targeted at milestone v0.2.0 (matches parent #151; no v0.2.1 milestone exists yet).

• Implement CLI→library request builder snapshot coverage for CLI↔client contract test coverage #170 — Implement CLI→library request builder snapshot coverage. Systematizes the existing #[cfg(test)] mod tests block: minimal + maximal full-shape snapshot per build_*_request helper, single assert_eq! against serde_json::json!(...) for the complete serialized body. No new dependencies. Single PR.
• Implement clap-to-wire CLI request shape test binary for CLI↔client contract test coverage #171 — Implement clap-to-wire CLI request shape test binary. Adds crates/clickhousectl/tests/cli_request_shape_test.rs with wiremock = \"0.6\" as a CLI dev-dep. One test per body-building command (8 total) asserting method + path + body. Depends on Implement CLI→library request builder snapshot coverage for CLI↔client contract test coverage #170. Single PR.

GET/DELETE/list commands are deferred — their CLI↔client contract is essentially path-segment mapping that clap and cargo build already cover, and live integration in clickhouse-cloud-api/tests/integration_*_test.rs exercises the response path. If runtime regressions show up there, we can extend #171's pattern to read paths in a follow-up.