feat(setup): `setup agent` targets prod — staging becomes explicit via `--env staging`

Merged
TO
3mo ago
+196-19

Why

User report (Tony, 2026-08-20): running the public one-liner npx -y insta@latest setup agent on a machine that had been switched to staging weeks earlier silently produced a staging setup — staging skill text, insta-cloud-staging MCP — with only a small (staging) tag as warning. The public one-liner must mean production; staging should be an explicit ask that announces itself.

What

  • planSetupEnv (pure, unit-tested): bare setup agent targets prod. If the persisted env differs, it switches the machine through the env use path — persisted, the now-foreign session dropped, loudly announced — so the CLI, skills, and MCP can never disagree about the machine's deployment. --env <prod|staging> is the explicit override; $INSTA_ENV counts as explicit (installer/CI path). Deliberate custom hosts ($INSTA_API_URL, or a persisted custom apiUrl from login --api-url) are left alone unless --env is given.
  • install.sh staging path now passes --env $ENV_NAME to setup agent (a no-op switch after its own env use, but it stops the new setup from "correcting" the machine back to prod). Falls back to the bare form for pinned older CLIs, where bare setup follows the persisted env — the old, correct semantics. ⚠️ After merge: invalidate the agents.instacloud.com CloudFront cache so the stale installer window (old installer + new CLI would flip a staging install to prod) is minutes, not ~24h.
  • env use hint updated to insta setup agent --env <name> — following the old bare-form hint would now undo the switch the user just made.
  • Next-steps footer (second user ask: "should we have some visibility for next step?"): after the ✓ lines, one status-aware hint from local state only — logged out → insta login → insta project create; logged in → insta project create; both offer the Fetch https://instacloud.com/prompt.md agent prompt.

Gate

Typecheck clean; 403/403 tests (6 new: planSetupEnv matrix — prod/staging/custom-host/INSTA_ENV — plus switch-before-install ordering; all setupAgent tests now inject isolated config fakes so the suite can't read or write a developer's real ~/.insta).

Mirrors (follow this PR)

  • insta-skills cli-reference.md + setup.md: --env flag + prod-default contract
  • insta-landing prompt.md/agents.md/llms.txt: collapse step 1 to the single npx -y insta setup agent; staging = npx -y insta setup agent --env staging
  • Ships in 0.0.38

🤖 Generated with Claude Code

Summary by cubic

insta setup agent now targets production by default and switches the machine before installing; staging requires --env staging. A conflicting --env with $INSTA_API_URL or $INSTA_ENV now fails early to avoid mixed‑environment installs.

  • Review focus:

    • planSetupEnv (pure): picks target env and whether to switch; treats $INSTA_ENV as explicit; throws on --env conflicting with $INSTA_API_URL/$INSTA_ENV; leaves deliberate custom hosts ($INSTA_API_URL or persisted custom apiUrl from login --api-url) alone unless --env is given.
    • setupAgent: runs env use <target> before any installs; prints a short next‑steps footer.
    • install.sh: when staging, passes --env $ENV_NAME; falls back to the bare form only when the CLI rejects the flag with “unknown option” (stderr captured and replayed).
    • UX/docs: env use hint now says insta setup agent --env <name>; README/command help document the prod‑default and --env <prod|staging> option.
    • Tests: planner matrix incl. conflict cases; switch‑before‑install ordering; integration test for disagreeing $INSTA_ENV + --env; setup tests isolate ~/.insta.

  • Rollout/Migration:

    • Invalidate the agents.instacloud.com CloudFront cache after merge to minimize stale installer propagation.
    • Staging users and scripts must call: insta setup agent --env staging.