Add mass environment preview for per-PR preview environments

[coryodaniel]

Summary

Adds mass environment preview <ID> -f preview.yaml — a single command that converges a preview environment for a PR / branch / feature ramp. Re-running the command resets the env back to whatever the YAML declares.

Under the hood it composes four idempotent V2 mutations:

1. forkEnvironment from the base env in the config (copyEnvironmentDefaults / copySecrets / copyRemoteReferences macros pass through).
2. setEnvironmentDefault per environmentDefaults entry.
3. Per-instance overrides — copyInstance for params, updateInstance for version/release strategy, setInstanceSecret per secret, setRemoteReference per ref.
4. deployEnvironment to fan a provision wave across all instances.

The companion V2 API changes (copySecrets/copyRemoteReferences on fork, deployEnvironment mutation) are on the platform side in massdriver-cloud/massdriver#3246.

Config schema

Follows V2 terminology — no "slug", no "artifact", no massdriver/ scoping prefix.

project: demo
baseEnvironment: production
copyEnvironmentDefaults: true

environmentDefaults:
  - resourceType: aws-iam-role
    resourceId: 161aeb95-...

instances:
  chatdb:
    version: "~2.0"
    releaseStrategy: stable
    params:
      ingress: { enabled: true }
    secrets:
      - { name: STRIPE_KEY, value: FOO }
    remoteReferences:
      - { resourceId: a1b2c3..., field: kubernetes_cluster }
  sessions:    # listed without overrides — inherits from the fork

Full schema doc + example: docs/helpdocs/environment/preview.md and preview.example.yaml.

Test plan

• go build ./...
• go test ./... — preview unit tests cover load, validation, happy-path call sequence, and fork-failure propagation
• Smoke-test against a real org once the platform-side PR (massdriver-cloud/massdriver#3246) is merged

🤖 Generated with Claude Code

[chrisghill]

There is a HUUUUUGE PR about to merge that puts all of this on the SDK. Can this wait?
#237

[coryodaniel]

We should include an option to watch for deployments and tail prefixing each line with the instance.id for grepability since some may run in parallel

[coryodaniel]

Done in 0c78eb8 — added --follow to both environment preview (here) and environment deploy (in #238, since that's where the deploy command lives). Output looks like:

[ecomm-pr42-db]  applying db schema
[ecomm-pr42-app] starting container
[ecomm-pr42-db]  migrations done

Each tail goroutine line-buffers and serializes through a mutex'd sink, so parallel deployments don't tear lines.

One implementation note worth flagging: I went with polling rather than subscribing to environmentEvents / instanceEvents as you suggested. The SDK's Absinthe/Phoenix-channels machinery is in internal/absinthe, so doing real subscriptions from the CLI would mean re-porting that layer just for this flag. Polling per-instance Deployments.List every ~2s has a few seconds of discovery latency per new deployment, which seemed acceptable next to per-instance deploy times measured in minutes. Happy to switch to the subscription path the moment the SDK exposes event subscriptions publicly — at that point it's a one-file swap inside internal/commands/environment/follow.go.

[coryodaniel]

Filed the SDK ask: massdriver-cloud/massdriver-sdk-go#21 — request to expose environmentEvents / instanceEvents as typed Subscribe methods on the existing services. Once that ships, the swap inside follow.go is one file.

[coryodaniel]

@claude review

[claude]

Claude finished @coryodaniel's task in 2m 38s —— View job

---

Code Review

Note on chrisghill's comment: PR #237 ("swap to using SDK for GQL interactions") has already merged (commit 2148f7b) and this branch is rebased on top of it — the SDK concern is already resolved.

---

Summary

Solid, well-structured implementation. The interface-based PreviewAPI, env-var expansion via os.ExpandEnv, and the --attributes CLI override pattern are all good design choices. The test coverage for happy-path and error propagation is thorough. A few concrete issues below.

---

Issues

1. releaseStrategy promised but not implemented

The PR description and the example YAML show releaseStrategy: stable, and the PR summary says step 3 handles "version/release strategy" via updateInstance. But InstanceOverride only has Version — there is no ReleaseStrategy field, and instances.UpdateInput is called with only {Version: override.Version}.

Either the field needs to be added or the PR description/docs need to be corrected. Given instances.UpdateInput almost certainly supports it (the existing mass instance update command uses the same input), this is likely an unintentional omission. Fix this →

2. ID format not validated

The docs and help text both state the ID must match ^[a-z0-9]{1,20}$, but the code only checks for empty string:

// preview.go:157
if opts.ID == "" {
    return nil, errors.New("preview environment ID is required")
}

A user passing pr-123 (with dashes) or UPPERCASE will get a confusing platform-level error instead of a clear CLI message. Fix this →

3. Fork idempotency claim needs verification

RunPreview calls api.Fork(...) unconditionally on every run. The PR claims "re-running the command is safe — every step is idempotent", but this depends entirely on the platform returning a successful response (or the existing env) when a fork with the same ID already exists. If Fork returns an error for a duplicate ID, the second run fails immediately before applying any overrides.

This should either be documented clearly ("the platform forkEnvironment mutation is upsert-style") or handled in the CLI with a fallback. The smoke-test requirement makes this the most critical unknown before merging.

4. Secret values in plain text YAML

preview.example.yaml has value: FOO and the secrets section doesn't highlight the env-var pattern for actual secrets. Users will naturally check in a preview.yaml with hardcoded secrets. The example and docs should strongly recommend value: "${STRIPE_KEY}" for any real secret value — the env-var expansion already supports it, just not emphasized. Fix this →

---

Minor issues

Non-deterministic instance processing order (preview.go:195): for localID, override := range config.Instances iterates over a map, so call order varies between runs. This is fine semantically (operations are independent), but it makes debugging harder and will cause occasional test flakiness if anyone ever asserts call order. Consider a sorted iteration or note this as intentional.

applyInstanceOverride over-receives (preview.go:214): The function takes the full *PreviewConfig but only touches config.Project and config.BaseEnvironment. Accepting just those two strings would reduce coupling and make the function easier to test in isolation.

SilenceUsage placement (cmd/environment.go:406): It's set after config load but before client creation. Other run functions in this file set it immediately. Move it to be the first statement in the function body for consistency.

---

Testing observations

• No test for invalid ID format (would catch issue Adding examples #2 above)
• No test for validatePreviewConfig rejecting a missing secret name
• TestRunPreview_HappyPath doesn't assert which instance triggered the copyInstance call — with map iteration being non-deterministic, the test reliably passes today but could hide ordering bugs. Asserting api.copyInputs[0].source == "demo-production-chatdb" would be more precise.

---

On coryodaniel's suggestion at line 433

The --watch / deployment tail idea is a good UX addition. Suggest tracking it as a follow-up issue rather than blocking this PR — the deploy step today is "fire and forget", and adding watch would require polling or streaming support from the platform side anyway.

---

Checklist:

• Gather context and understand the request
• Read changed files
• Review internal/commands/environment/preview.go
• Review internal/commands/environment/preview_test.go
• Review cmd/environment.go changes
• Review docs and example YAML
• Post comprehensive review feedback