Add upgrade apply for the CLI and API

[JAORMX]

Summary

With the Applier in place (PR #5410), expose it to users so they can apply an upgrade while preserving configuration, instead of manually re-running a workload with a new image. Part of RFC THV-0068, local scope.

• Add thv upgrade apply <name>: runs the check, shows the candidate image, new env vars, and any permission/transport/network posture drift, then prompts for confirmation. --dry-run reports the plan without applying; --env/--secret supply values for newly required variables; --yes (or a non-interactive shell) skips the prompt and fails loudly on missing required values; --image-verification mirrors thv run.
• Add POST /api/v1beta/workloads/{name}/upgrade, delegating to the same Applier so all clients share one apply path. The API path is always non-interactive (detached validator) and sources image verification from server config; the request body can only supply env/secret values — it cannot redirect the image or weaken verification. Apply failures return a sanitized 422 with the detailed cause logged server-side, so secret references in an error chain are never echoed to the caller.

Type of change

• New feature

Test plan

• Unit tests (task test) — API: happy path, no-op, 404/400, no-secret-leak (asserts a secret reference in the request never appears in success or 422 responses), route ordering. CLI: output-formatting helper.
• Linting (task lint-fix)

Changes

File	Change
cmd/thv/app/upgrade.go	apply subcommand + flags + confirmation
pkg/api/v1/workloads_upgrade.go	POST .../upgrade handler
pkg/api/v1/workloads.go, workload_types.go	Route + request type
docs/cli/*, docs/server/*	Regenerated reference

Does this introduce a user-facing change?

Yes — thv upgrade apply and POST /api/v1beta/workloads/{name}/upgrade. The command stops and replaces the existing workload (verifying and pulling the candidate image first); there is no automatic rollback, which the help text states.

Large PR Justification

This PR is ~1,007 lines, but only 330 are hand-written source; the remainder is generated reference and tests:

• 374 lines are auto-generated OpenAPI (docs/server/*) and CLI reference (docs/cli/*), produced by task docs. They must be regenerated and committed together (CI verifies them) and cannot be split.
• 303 lines are tests for the new handler and CLI helper.
• The 330 source lines are the CLI apply subcommand and the API POST handler — two thin callers of the same Applier that the user explicitly chose to ship together so all clients share one apply path. Splitting CLI from API here would duplicate the wiring and the "all clients benefit" goal of the RFC, and both are well under the threshold individually.

Special notes for reviewers

PR 5 of 6 in the RFC THV-0068 stack; based on #5410. The API path hardcodes the detached env-var validator and sources the verify mode from server config — a client cannot weaken verification or redirect the image via the request body.

🤖 Generated with Claude Code

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.

[codecov]

Codecov Report

❌ Patch coverage is 60.00000% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.82%. Comparing base (974aab5) to head (38897c9).

Files with missing lines	Patch %	Lines
pkg/api/v1/workloads.go	0.00%	9 Missing ⚠️
pkg/api/v1/workloads_upgrade.go	75.00%	6 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5411      +/-   ##
==========================================
- Coverage   68.84%   68.82%   -0.02%     
==========================================
  Files         635      635              
  Lines       64331    64376      +45     
==========================================
+ Hits        44286    44308      +22     
- Misses      16771    16790      +19     
- Partials     3274     3278       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Large PR justification has been provided. Thank you!

[github-actions]

✅ Large PR justification has been provided. The size review has been dismissed and this PR can now proceed with normal review.