Make local server stop <name> idempotent (#255)

[sdairs]

Closes #255.

Problem

chctl local server stop <name> exits non-zero (ServerNotRunning) when the named server isn't running, forcing scripts to guard against the already-stopped case. stop-all is already idempotent (exits 0 with "No running servers"), so the two were inconsistent.

Approach

Rather than add the --none-ok flag from the issue, stop is now idempotent by default — the declarative paradigm used by docker stop / systemctl stop:

Command	Before	After
stop <running>	stopped, exit 0	stopped, exit 0 (unchanged)
stop <stopped-but-exists>	error, exit 1	already stopped, exit 0
stop <unknown-name>	error, exit 1	not found, exit 1 (unchanged)

The unknown-name case still errors (ServerNotFound) so typos surface — we distinguish it from already-stopped via the on-disk data dir (project-scoped, same check remove uses).

This is a deliberate behavior change, agreed appropriate pre-1.0 and consistent with stop-all.

Changes

• classify_stop(running, exists_on_disk) pure helper encodes the three outcomes; the handler stays thin. Unit-tested for all three cases.
• ServerStopOutput gains already_stopped: bool, surfaced in human output ("Server 'x' is already stopped") and --json.
• --global stop and Postgres stop are unchanged (out of scope; global is cross-project maintenance where the project-scoped data-dir check doesn't apply).
• README + stop agent-help text document the idempotent behavior.

Testing

• cargo build, cargo test -p clickhousectl (392 tests), cargo clippy --all-targets all clean.
• New unit tests: classify_stop_* (3 outcomes), server_stop_already_stopped (display + JSON).
• Manual smoke test: unknown name → exit 1; existing-but-stopped → exit 0 with already_stopped: true.

🤖 Generated with Claude Code

---

Note

Low Risk
Localized CLI behavior change for project-scoped ClickHouse stop only; running stops and unknown-name errors are unchanged aside from the already-stopped success path.

Overview
Project-scoped clickhousectl local server stop <name> now treats an existing but stopped server as success (exit 0) instead of failing with a not-running error, aligning with stop-all and typical docker stop / systemctl stop behavior.

The handler uses classify_stop(running, data_dir_exists) to choose kill, idempotent noop, or ServerNotFound for unknown names. ServerStopOutput adds already_stopped so CLI text says the server is already stopped and --json can tell a real stop from a noop. README and server stop agent help document this. --global stop and Postgres stop are unchanged.

^{Reviewed by Cursor Bugbot for commit 842ddb8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[iskakaushik]

LGTM