Rework cloud-connect-dev recipe onto the spice cloud enrollment flow

[claudespice]

Summary

spice connect is no longer how a runtime is connected to Spice Cloud. It retains only the deprecated <org>/<pod> Spicepod-add form and rejects every lifecycle spelling:

$ spice connect status
ERROR Invalid argument: `spice connect` only accepts the deprecated `<org>/<pod>` Spicepod form; use `spice cloud` for instance lifecycle.

The cloud-connect-dev recipe taught spice connect, spice connect status, and spice connect remove — so every cloud-facing command in it exits non-zero today. Repairing its doc links (the original scope of this PR) would have left a recipe that walks the reader down a path the CLI no longer has, so the recipe body is reworked onto the current surface. The link repairs are kept.

What changed

README.md now uses spice login → spice cloud project create → spice cloud link <org>/<project> → spice run, with spice cloud secrets, spice cloud status, spice cloud unlink, and spice cloud service for the rest. The portal is used only where it is genuinely the tool: editing the project Spicepod. Behaviours documented because the CLI actually does them:

• spice cloud link enrols the directory and attaches it in one step, requires a terminal, and does not start the runtime — its own output tells you to run spice run.
• A project holding no Spicepod is seeded from the local one, so the recipe's manual "paste spicepod.yaml into the portal" step is gone.
• spice cloud unlink releases the instance but never deletes the project. Clean-up names spice cloud project delete separately, and says to stop the runtime first, because unlink takes the runtime lock and refuses while it is held.
• spice cloud status reports project health and appends the local view under a Local enrolled-instance state: header, which the expected-output block gains. It reads from the control plane, so unlike the old command it does not work signed out — the README says so.

Breaking for anyone parsing --output json: the status JSON moves connection, service, and deployment under a link object; schema_version stays at the top level. That is a runtime change, not one this PR makes, but it is not discoverable from this diff and it silently breaks existing parsers.

The project is created with spice cloud project create cloud-connect-dev. --kind is the discriminator: naming one asks for a Spice-managed project and requires --region, while omitting it asks for a Cloud Connect project, which has no region to choose. --region and the hosted-runtime flags are refused rather than ignored when no kind is given, so the README says so.

validate.sh asserts that distinction, and can do it headlessly: execute_project_create resolves placement before it connects, so both refusals are argument validation that answer with no account and create nothing. The exit code is asserted alongside the message, so a future ordering change that created the project before validating it would fail the check rather than pass silently.

Secrets, and a hazard worth naming

The secrets step is spice cloud secrets set PG_PASSWORD "$SPICE_DEMO_PG_PASSWORD", confirmed with spice cloud secrets list. Linking resolves the project, so neither needs --project.

The value is a required positional argument, and there is no stdin, file, or environment form — SecretsSetArgs.value is a bare String with no clap attribute, and the only stdin read in the module is the project-delete confirmation prompt. So the recipe passes the shell variable: history records the line as typed, which keeps the password out of it, but the expanded value is still in the process argument list while the command runs. The README states that plainly and points at the portal for a shared machine, rather than implying the CLI form is unconditionally safer.

spice cloud secrets get prints the value to stdout, so the confirmation step uses list, which reports names and timestamps only. validate.sh fails if the README ever reaches for get, or if it spells the password literally instead of passing the variable.

validate.sh

Its stated contract is to run with no account, no login, and no control-plane access. The old spice connect status assertions met that because the command only read local state. spice cloud status calls the control plane — offline it exits 1 with No app specified — so those checks cannot be ported. Replacing them:

• --help assertions that the four lifecycle commands and all five service subcommands exist
• a README/CLI drift guard that fails if the recipe reintroduces a removed spice connect spelling
• the non-interactive refusal path, which still fails closed and still names spiced --token

Nothing in the suite sets, reads, or deletes a real secret, for the same reason a bare project create is not asserted: those commands reach the control plane, and a validator that mutates someone's cloud project when a developer happens to be logged in is a worse defect than the coverage it would buy.

Dropped: the assertion that an enrollment key is refused as a positional argument. spice cloud link fails its terminal check before argument handling, so that property is no longer reachable from this recipe's surface. The scan that fails the build if a key-shaped value appears in a recipe file is unchanged.

Verified against

• The shipped binary, not the release notes: spice cloud --help and the link / unlink / status / service / project create subcommand helps.
• Source, for the strings and ordering the README quotes: bin/spice/src/commands/cloud/mod.rs (execute_link output, execute_unlink runtime lock, execute_status local-state header and JSON shape) and bin/spice/src/commands/connect/status.rs ( secrets: {n} delivered: {names}).
• Links: every URL in the README re-checked with curl -sL -o /dev/null -w '%{http_code}' — 4/4 return 200. /docs/next/ is the correct prefix today because the released paths still 404: Cloud Connect is new in v2.2 and no version-2.2.x snapshot has been cut yet. When v2.2 is published these pages are snapshotted and also resolve at /docs/deployment/cloud/cloud-connect, which is then the better link for a recipe whose readers run the stable CLI — /docs/next/ tracks trunk and drifts from it. Worth revisiting at that point.
• The spice connect CLI reference link is removed rather than repointed — the spice cloud reference page is not published yet (/docs/cli/reference/cloud and /docs/next/cli/reference/cloud both 404). It can be added in a follow-up once that page exists.

Evidence

./cloud-connect-dev/validate.sh, run locally against a v2.2 CLI:

before:  18 passed, 12 failed   TEST FAILED
after:   43 passed,  0 failed   TEST PASSED

All 12 prior failures were the spice connect assertions.

Note on CI: validate-cloud-connect-dev installs the stable CLI, which still predates v2.2, so the workflow takes the version gate and reports the "not validated" notice — a green check there is not evidence for the CLI-dependent assertions, which were exercised locally against v2.2 and start running in CI when v2.2 ships.

The checks that only read README.md need no CLI, so they now sit above the gate and do run in CI: 23 checks, up from 16, including the guard that fails if the recipe ever spells the database password literally instead of passing $SPICE_DEMO_PG_PASSWORD. That is the check that most needs to run on every pull request, and it previously never did.

Sweep

The rest of the cookbook was checked for spice connect. Five other files match only in ordinary prose — "the replication user Spice connects with", "Spice connects to Unity Catalog", "the Spice connector accepts the dot form" — and no file anywhere uses the still-supported deprecated spice connect <org>/<pod> pod-add form. No other recipe needs a change.