fix(service): validate --upload before spending anything

[scttfrdmn]

Found while validating #409 against real EC2 — I made this mistake myself, and the dry run rendered a plan that couldn't work.

The bug

--upload takes a value, so this:

spawn service ./svc --instance-type t4g.micro --ttl 20m --upload --region us-east-1

binds --region as the filename and leaves us-east-1 to be parsed as a positional argument. The service gets a stray argv element, the region silently goes unset, and the dry run happily prints:

Instance:    t4g.micro in -
Command:     './svc' 'us-east-1' --addr 127.0.0.1:0
Upload:      --region → /tmp/spawn-service-bin

No cost line, because there's no region to price — but nothing says so.

Three changes, ordered by what they cost

Validation moves before the launch. uploadToInstance already stat'd the file, but only after an instance was running — so a typo cost a launch. It's now checked during argument parsing, before the AWS client is even built. This is the substance of the fix; the message improvements below are the cosmetics.

A flag-shaped value is named as such:

--upload got "--region", which looks like a flag, not a file: --upload takes the
local file to copy, so it swallowed the next argument. Write --upload <file>
(or --upload=<file>) and put other flags after it

rather than --upload --region: stat --region: no such file or directory, which is technically true and buries the lede. Directories are rejected too.

The dry run explains a missing cost bound instead of dropping the line. Silence reads as "this is free", and an unset region is the symptom of this exact mistake, so naming it points at the cause:

Rate:        unknown — no region resolved yet (pass --region to see the cost bound)

Validation runs before the --dry-run branch, not just before the launch: a preview that renders an unusable plan is worse than no preview, since catching this for free is the whole point of --dry-run.

Also: a missed reference fragment

This commits docs-gen/service.md, which #409 generated but never committed. The drift gate is git diff --exit-code docs-gen/, which sees tracked files only — so a brand-new untracked fragment passes CI and would first fail at tag time, where make check-docs runs as a release guard. Worth knowing the gate has that blind spot.

Verification

All three guards mutation-tested:

Mutation	Result
if strings.HasPrefix(path, "-") → if false	TestValidateServiceUpload fails
validation removed from RunE	TestServiceRejectsABadUploadBeforeSpendingAnything fails
missing-region note deleted	TestRenderServiceDryRunSaysWhyTheCostBoundIsMissing fails

The second mutation exposed a flaw in my own test worth calling out: it initially reached a real AWS account (30s, a live DescribeInstances) because this shell has AWS_PROFILE set. It never launched anything — the instance ID was nonexistent, and I leak-checked three regions to confirm zero instances — but a unit test whose claim is "this never reaches AWS" must not depend on the ambient environment being empty. It now neutralises the credential env vars and points the config/credential files at an empty temp dir, so the same mutation fails in 0.00s having contacted nothing.

Also added spawnRegion to resetServiceFlags, since it's the root persistent flag shared with every other command and these tests now set it.

make check-docs passes. Full cmd suite green except TestCatalogValid, which fails only on my machine — ~/.spawn/catalog.yaml is a personal overlay pointing chimerax/paraview at private ECR, exactly as #392 prescribes, and the validator checks the merged view. CI has no overlay.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!