refactor(api): require apply IDs for control operations

[aparajon]

Why

Control operations should target a specific stored apply, not whatever active work happens to match a database and environment. Requiring an apply ID keeps storage as the source of truth for the database, route, and Tern apply identifier.

What

• Require apply_id and environment for cutover, stop, start, volume, revert, and skip-revert
• Derive database, deployment, and Tern apply ID from the stored apply record
• Remove database from control CLI/API payloads and update operator-facing command hints
• Cover rejected client-supplied database/deployment fields and derived Tern requests in tests

Generated with Codex

[Copilot]

Pull request overview

This PR updates SchemaBot’s control-operation contract so operator actions (cutover/stop/start/volume/revert/skip-revert) are explicitly scoped to a stored apply_id + environment, with the backend deriving database/routing metadata from the stored apply record (and rejecting client-supplied database/deployment fields).

Changes:

• Require apply_id and environment for control operations; derive database + Tern apply ID from storage.
• Update CLI/TUI/operator-facing hints to use positional apply IDs and -e <env> for control commands.
• Expand/adjust API, integration, and e2e tests to cover the new request contract and rejection of extra fields.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
TEMPLATES.md	Updates operator-facing examples to include -e <env> + positional apply IDs for control operations.
pkg/cmd/templates/progress.go	Updates printed CLI hints (progress/status/start resume guidance).
pkg/cmd/templates/preview_progress.go	Updates preview output strings to match new CLI contract.
pkg/cmd/templates/preview_defer.go	Updates defer/cutover/stop hints to require -e <env> + apply ID.
pkg/cmd/commands/watch_tui_view.go	Updates TUI footer instructions for control operations to include -e <env> + apply ID.
pkg/cmd/commands/watch_tui_test.go	Adjusts error-message expectations for new required apply_id.
pkg/cmd/commands/watch_tui_commands.go	Updates control API calls to omit database and include apply ID where required.
pkg/cmd/commands/volume.go	Removes database from volume control calls; relies on apply scoping + display population.
pkg/cmd/commands/stop.go	Updates stop control call signature; (contains a not-found handling regression noted in comments).
pkg/cmd/commands/start.go	Updates start control call signature; removes DB scoping from request.
pkg/cmd/commands/skip_revert.go	Updates skip-revert call signature to include apply ID; adds display field population.
pkg/cmd/commands/revert.go	Updates revert call signature to include apply ID; adds display field population.
pkg/cmd/commands/progress.go	Tightens apply-id requirement messaging and keeps progress-by-apply-id flow.
pkg/cmd/commands/cutover.go	Updates cutover control call signature; removes DB scoping from request.
pkg/cmd/commands/common.go	Makes control-flag resolution require apply_id + environment; removes DB flag and related resolution logic.
pkg/cmd/commands/apply.go	Updates printed guidance for cutover/status based on new control-operation contract.
pkg/cmd/client/client.go	Changes control-client APIs to remove database and require apply ID + environment in request bodies.
pkg/apitypes/apitypes.go	Removes database from control/volume request types; makes apply_id required in JSON.
pkg/api/README.md	Documents the new control-operation scoping and server-side derivation/rejection behavior.
pkg/api/handlers_test.go	Updates/extends handler tests to validate derived Tern requests + rejection of client DB/deployment fields.
pkg/api/control_handlers.go	Enforces apply_id + environment scoping, loads apply from storage, derives database/deployment/Tern apply ID.
integration/cli_test.go	Updates CLI integration tests to pass -e staging for control ops.
e2e/local/vitess_test.go	Updates e2e calls to new client control signatures (environment + apply ID).
e2e/local/local_test.go	Updates local e2e CLI invocations to include -e staging for control ops.
e2e/local/helpers_test.go	Updates helper control calls (start/cutover) to new signatures.
e2e/grpc/cli_test.go	Updates gRPC e2e CLI invocations to include -e staging for control ops.
docs/spirit_progress.md	Updates documentation strings for control-operation hints.
docs/architecture.md	Updates architecture doc examples to show apply-id-scoped control operations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.