[sdairs]

Closes #1077.

Summary

Read-only and lookup local commands no longer create .clickhouse/servers/.metadata.lock in the current directory. Only local server start, local postgres start and local init create project state now.

• New lock entry point. MetadataLock::acquire_existing_at and server::lock_existing_metadata() return None when .clickhouse/servers doesn't exist. The lock file is opened without create_dir_all, and ENOENT maps to None. There's no separate existence check, so there's no race: a concurrent start either created the directory first, in which case the reader waits on the lock, or it comes after the reader, which correctly sees no servers.
• Callers now on the read path:
  • local server list, stop, stop-all, remove and dotenv
  • managed local client
  • local udf list, reload, remove and deploy
  • local postgres stop, stop-all, remove, client and dotenv, through a shared lock_and_resolve_pg_target
  • the in-use guards in local remove <version> and in install
  • server start's pre-checks, so a start that fails before installing leaves nothing behind
• Output is unchanged. I compared 32 commands in an empty directory against origin/main: exit codes, stdout and stderr were identical. The only difference is that main creates the lock directory.

Visible changes

• stop or remove with no name after a list. These now report "no project state", because list no longer leaves .clickhouse/ behind. The state-machine tests are updated to match.
• .clickhouse/servers is a file. The error now says "open the server metadata lock file" instead of "create the server metadata lock directory".
• Orphan recovery still works without project state (second commit, from review). When .clickhouse/servers is missing, read commands first run a discovery-only pass that writes nothing. Only if it finds a running ClickHouse process or a labelled Postgres container for this project do they create the directory, lock, and recover as before. Example: after rm -rf .clickhouse with a Postgres container still running, stop-all still finds and stops it. Recovery runs again under the lock, so a concurrent start isn't duplicated. An empty non-project directory still gets nothing.

Notes

• local init: create the runtime gitignore after server list initializes metadata #802: the gitignore handling still holds. init_after_server_list_creates_runtime_gitignore now asserts that list leaves nothing, then seeds the leftovers an older release would have left.
• feat(local): deploy executable UDFs to local servers (local udf deploy|list|remove|reload) #1068's dotfile filter in looks_like_project_root is kept. The lock file still remains after the last server is removed, and interrupted temp files are dotfiles too. Only its comment changed.

Tests

• New subprocess tests: tests/local_readonly_no_project_state_test.rs, 9 tests. Each command runs in an empty directory, in an init-only directory, and as local remove <version>. The file is classified in both CI scripts and in the mirrored test set.
• New unit tests: 5 for the lock helper.
• Checks: fmt, both clippy configurations, --no-default-features check, cargo test -p clickhousectl and the Python classifier tests. I also checked by hand that the issue's repro leaves an empty directory.

🤖 Generated with Claude Code

---

Note

Medium Risk
Release workflow and self-update version resolution now depend on latest.txt; a failed or stale publish affects all updaters, while the org module split is large but should be behavior-preserving if tests pass.

Overview
This PR bundles release discovery, Cloud API/client updates, and a cloud CLI layout refactor (the attached PR title/description about local read-only commands is not reflected in this diff).

Release: Adds a Publish latest.txt job after uploads that writes clickhousectl/latest.txt to builds.clickhouse.com with forward-only semver (re-tagging an older release does not downgrade). The job verifies the CDN-served file and fails the release if it does not match. Docs and the release skill now say clickhousectl update and install.sh read that manifest (GitHub releases/latest only as fallback).

clickhouse-cloud-api: Refreshes the OpenAPI spec and models for ClickStack log sources (eventNameExpression, severityNumberExpression) and MongoDB ClickPipe table mappings (mongoConfig.persistDeletedDocuments). Conversion, README, and unit/smoke tests cover round-trips and optional fields.

clickhousectl: Deletes the monolithic organizations.rs in favor of the organizations/ directory pattern (with blame-ignore entries for similar splits of services/ and postgres/). Drops the service_query module re-export from cloud/mod.rs. ClickPipes --table-mapping-json accepts mongoConfig; ClickStack source file tests include the new log expressions. Agent docs (AGENTS.md, add-cli-command, cli-help-text) describe the directory layout and stricter convert_error_for_lookup guidance.

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

[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 533c6d2. Configure here.}

[cursor]

Stopped Postgres recreates project state

Medium Severity

The new “create state only if something is still running” gate uses discover_project_postgres_blocking, which lists every labelled container (all(true)), not just running ones. postgres stop leaves the container in place, so after .clickhouse/ is deleted any read path that calls lock_recovered_metadata (server list, udf list, local remove, client, and start pre-checks) recreates .clickhouse/servers/ for a stopped instance. That reintroduces #1077 for the common leftover-container case, and it contradicts the comments and docs that recovery should run only when something is still running.

Additional Locations (1)

• crates/clickhousectl/src/local/docker.rs#L712-L716

 

^{Reviewed by Cursor Bugbot for commit 533c6d2. Configure here.}