[SPIKE] Demystify deploy vs release for VPS-configured stacks

[gfargo]

Context

Hit real friction today rolling out a small env-var change to a harbor-deployed stack (hq-web-api): ran strut hq-web-api deploy --env prod expecting it to push+restart on the VPS. It didn't — deploy operates on wherever strut is currently running (local machine), not the VPS, even though the stack's services.conf has VPS_HOST set. The right command is release. This is the second time in one session this exact mixup happened, despite the tool actively warning about it.

What's actually going on (traced through the source)

• cmd_deploy and cmd_release are both defined in lib/cmd_deploy.sh (release at line 246) — closely related, same file, but exposed as two differently-named top-level commands with no naming cue that one is VPS-aware and the other isn't.
• cmd_deploy DOES detect the VPS case (lib/cmd_deploy.sh:338-341, if [ -n "${VPS_HOST:-}" ] && ! is_running_on_vps) and prints a warning + points at release — but then still offers an interactive "Continue with local deployment anyway? [y/N]" prompt. For a stack that's only ever meant to run on a VPS, that "continue anyway" path is a trap, not a safety net — it's very easy to reflexively confirm past a warning you've half-read.
• Separately (same session, same stack, discovered right after fixing the first issue): release requires GH_PAT in the env file. validate_env_file (lib/utils.sh:713-738) loops over required vars and fails on the first missing one — so after adding the vars for the actual thing you set out to configure, you only discover the next missing required var on the next run, one at a time, instead of getting the full list up front.

Spike questions

1. Should deploy even offer a "local" path for a stack with VPS_HOST set, or should that require an explicit opt-in flag (e.g. --force-local, which appears to already partially exist per force_local in the code) rather than being the default-invoked command name with a prompt escape hatch?
2. Is there a clearer naming split — e.g. deploy always means "wherever this stack's services.conf says", and something like deploy --local/local-deploy is the explicit local escape hatch instead of the reverse?
3. Should validate_env_file collect all missing required vars into one failure message instead of stopping at the first?

Filing as a spike, not a prescribed fix — genuinely not sure which naming direction is least surprising, and it may be a docs/warning-copy fix rather than a rename. Repro is trivial: any VPS_HOST-configured stack, run deploy instead of release.

🤖 Filed via Claude Code after hitting this live during a hq-web-api env rollout.