Fix rollback hint to reference a capture route that exists

[aram356]

Problem

Addresses #350. The run_rollback missing-target error told operators to use deploy's previous-version output, but no such output exists: the CLI's production deploy emits only version=<N>. previous-version is produced one layer up, by the deploy-fastly GitHub action's capture-previous.sh, which runs active-version before deploying. An operator following the hint mid-incident found nothing to use.

Change

Reword the hint in run_rollback and the matching --rollback-to doc comment in RollbackArgs to name the capture routes that actually exist: run active-version before deploying, or wire the deploy-fastly action's previous-version output. Two strings, no behavior change. The docs site already attributes previous-version to the action correctly, so it needs no edit.

Why not option 1 (emit previous-version from the CLI deploy)

The production deploy resolves its version from the deploy command's own output first, with the Fastly API only as a fallback, deliberately so manifest deploy command overrides (including test fixtures with dummy credentials) work without API access. Capturing the previous version can only happen via a pre-deploy API call, so option 1 either makes that call mandatory (breaking the override path and adding a new failure mode to every production deploy) or tolerates capture failure (emitting a line scripts cannot rely on, which is worse than no line). The action layer already captures the target fail-closed at the right place; the CLI hint just needs to tell the truth.

Verification

• cargo fmt -p edgezero-cli -- --check passes
• cargo clippy -p edgezero-cli --all-targets --all-features -- -D warnings passes
• cargo test -p edgezero-cli passes
• git grep previous-version crates/ shows only the corrected references; no test pins the old hint text

Closes #350

[prk-Jr]

PR Review

Summary

Correct diagnosis and a minimal two-string fix: the hint now names capture routes that actually exist (active-version, and the deploy-fastly action's previous-version output), matching what capture-previous.sh really does. No behavior change, CI green. All findings below are non-blocking wording/consistency polish.

😃 Praise

• Rejecting option 1 was the right call, and the reasoning is recorded. The production deploy resolves its version from the deploy command's own output first, with the Fastly API only as a fallback, precisely so manifest deploy overrides work without API access — making a pre-deploy capture mandatory would have broken that path and added a failure mode to every production deploy. Writing that trade-off into the PR body (and commit message) is what stops it being re-litigated in six months.
• Verification was done properly: git grep previous-version crates/ confirms no CLI surface emits it, and no test pinned the old string, so the change is genuinely two strings.

Findings

Blocking

None.

Non-blocking

• 🤔 Hint gives the operator no forward path — crates/edgezero-cli/src/lib.rs:519-521 (inline). The reader is past the point where "capture it before deploying" can help.

• ⛏ Output key not named — crates/edgezero-cli/src/lib.rs:519 (inline). active-version emits version=<N>, not previous-version=<N>.

• ⛏ Parenthetical mixes a command with an output — crates/edgezero-cli/src/args.rs:384-385 (inline). Renders in --help.

• 🏕 CLI reference still names only the Actions route — docs/guide/cli-reference.md:257. The bullet reads "capture it before the superseding deploy (deploy-fastly's previous-version)". Not wrong, but this is the CLI reference and it omits the CLI-native route — edgezero active-version, documented 60 lines above it at docs/guide/cli-reference.md:194. A CLI-only operator with no GitHub Actions gets pointed at an action. This is the same asymmetry the PR fixes in --help, and a one-line edit keeps the error text, --help, and the docs all saying the same thing:

  - `--rollback-to <n>` — **production only:** ... capture it before the superseding
    deploy (run [`active-version`](#edgezero-active-version), or use `deploy-fastly`'s
    `previous-version` output) and pass it here. ...

  (Verified: heading ### edgezero active-version exists and is unique, so the anchor resolves and the VitePress build stays clean.)

• 📝 Fastly-specific text in an adapter-agnostic function — crates/edgezero-cli/src/lib.rs:517-521. run_rollback dispatches to any adapter, but the hint names Fastly and a Fastly-specific GitHub action. Pre-existing (the "Fastly exposes no metadata" clause already did this) and Fastly is currently the only adapter implementing rollback. Informational, no action.

📌 Out of Scope

• 🌱 Nothing guards against the same drift recurring. The bug class here is an operator-facing string that quietly stopped matching reality; a stale hint costs the most at exactly the moment it is read. Nothing in the tree catches the next one. Not this PR's job — worth a tracking issue if hint accuracy is considered load-bearing.

CI Status

Run locally on 296f247 (PR head):

• fmt: PASS
• clippy (--workspace --all-targets --all-features -D warnings): PASS
• tests (--workspace --all-targets): PASS — 1392 tests, 0 failures
• GitHub checks: 21/21 SUCCESS

[ChristianPavilonis]

Review summary

Reviewed 296f2476b77accb2424a2c09e4b050fdc8679073 against 10263543d352b1293c325245ab94dd1a5e275314.

This is a low-risk, two-string correction. The revised error and --help text now point to capture routes that exist: the CLI's active-version command and the deploy-fastly action's previous-version output. No deployment or rollback logic changed.

Safety proof

1. The action captures and later consumes the same rollback target

   • Highest evidence: Runtime
   • Evidence: The composite-smoke job captured version=40 as previous-version=40 before deployment, then passed it through rollback, which emitted rolled-back-to=40.
   • Status: proven

2. active-version handles active, absent, and malformed provider state

   • Highest evidence: Executed
   • Evidence: Focused Fastly adapter tests passed for active-version policy and malformed provider responses. A compiled-CLI check also mapped version=40 through capture-previous.sh to previous-version=40.
   • Status: proven

Findings

No P0, P1, P2, or P3 issues found.

Validation and review context

• cargo test -p edgezero-cli: passed.
• Focused Fastly active-version tests: passed.
• Repository-pinned Rust 1.95 clippy for edgezero-cli: passed.
• Action contract tests: 242 passed, 0 failed.
• CI: 21 of 21 checks passed.
• Existing feedback: Three unresolved non-blocking wording threads and one documentation consistency note already cover the remaining polish suggestions. No duplicate findings added.
• Residual risk: No live Fastly API call was made. The unchanged provider path is covered by focused tests, action-contract tests, and end-to-end CI smoke tests.

[aram356]

Addressed the review polish in 389362b: output key named in the hint, forward-path clause added, the --rollback-to doc-comment parenthetical reworked, and the CLI reference bullet now names the CLI-native active-version route alongside the Actions one. The 🌱 drift-guard suggestion is left for a tracking issue since this PR stays a wording fix.