feat(cli): add experimental stack start

[jgoux]

supabase experimental stack start creates or resumes a managed stack for the current project and branch, with named-stack and explicit-ID targeting, Docker/native selection, and eager activation or background artifact preparation.

Translate project configuration at the CLI boundary and embed the supervisor and native-process dispatch in the compiled binary. The stack package owns lifecycle and persistent state, and resolves PostgreSQL major versions through its release catalog.

[github-actions]

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@162cc57f457e10b0c33a2377b1cb2d78e9639b0e

Preview package for commit 162cc57.

[github-actions]

🤖 AI Review

Only Claude's independent review was available; the Codex review did not complete. All 11 reported findings were verified against the checked-out code and confirmed. No critical or major issues were found. The confirmed concerns cover error classification and guidance, unexported error classes, function environment/path translation, database release selection, dead code, and potentially flaky fixed test ports.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/experimental/stack/start/start.handler.ts:220	error-handling	claude	StackStateInvalidError and StackStateFormatUnsupportedError are declared start errors but are not explicitly classified, so telemetry records them as unknown failures.
🟡 MINOR	apps/cli/src/commands/experimental/stack/start/start.handler.ts:207	error-handling	claude	StackRuntimeError and StackCleanupError receive misleading stop-the-stack guidance and are classified as invalid configuration through the lifecycle reason.
🟡 MINOR	apps/cli/src/commands/experimental/stack/stack-config.ts:14	conventions	claude	LegacyStackConfigError and LegacyExperimentalStackTargetError are file-private despite the trusted CLI convention requiring new error classes under apps/cli/src to be exported.
🟡 MINOR	apps/cli/src/commands/experimental/stack/stack-config.ts:76	error-handling	claude	Function dotenv keys are copied without validation into a schema that only accepts uppercase environment names, causing otherwise parseable dotenv files to abort stack configuration with a generic schema error.
🟡 MINOR	apps/cli/src/commands/experimental/stack/stack-config.ts:158	correctness	claude	Translating a legal function path located under supabase/ but outside supabase/functions/ produces .. segments that the stack resolver rejects, silently making the function unavailable.
🟡 MINOR	packages/stack/src/model/Compiler.ts:461	correctness	claude	The database major-version fallback selects the first matching catalog key by insertion order rather than applying a deterministic newest-release policy.
🟡 MINOR	apps/cli/src/commands/experimental/stack/stack-config.ts:151	correctness	claude	Paths beginning with supabase/ are incorrectly treated as project-root-relative even though legacy config paths are resolved relative to the existing supabase/ directory.
⚪ NIT	apps/cli/src/commands/experimental/stack/stack-config.ts:513	dead-code	claude	legacyConfigInput accepts a projectRoot parameter that its implementation never uses.
⚪ NIT	apps/cli/src/commands/experimental/stack/stack-config.ts:531	dead-code	claude	The translated config hardcodes preparation: "background", but the production consumer always overwrites it with the command flag.
⚪ NIT	packages/stack/src/supervisor/ingress.integration.test.ts:56	test-flakiness	claude	The hash-derived fixed test ports occupy the normal Linux ephemeral-port range and are not reserved before use, allowing sporadic collisions.
⚪ NIT	apps/cli/src/commands/experimental/stack/stack.shared.ts:76	style	claude	The target resolver layer wraps a constant service value in Effect.succeed and Layer.effect even though Layer.succeed directly expresses the same construction.

Stats

Claude findings: 11 · Codex findings: 0 · Confirmed: 11 · Refuted: 0 · Uncertain: 0

---

Models: claude-opus-5 + gpt-5.6-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[jgoux]

/ai-review

[avallete]

Approving. Dispatch, targeting, and error classification look good for an experimental first command.

Inline comments are follow-ups on config translation (Studio default URL, functions .env parsing, encrypted: secrets, SUPABASE_* overlays, Windows signing-key paths, telemetry flush). None of those should block landing this.

On the Depthfirst thread: db.network_restrictions / ssl_enforcement / vault are accepted by the stack schema but nothing in the stack runtime reads them today, same as local supabase start. Optional to forward for definition fidelity; not a current local access-control hole.

[Coly010]

I merged develop into this branch to resolve the conflicts caused by #6525 (the legacy-prefix rename, which touched ~1400 files). No functional changes to this PR's own work — the merge was mechanical: renamed identifiers/imports to match the post-rename names (e.g. legacyExperimentalStackCommand → experimentalStackCommand, LegacyCliSettings → CommandSettings, legacy-cli-settings.layer.ts → command-settings.layer.ts, etc.), and dropped the removed entrypoint: "legacy" e2e test option.

While resolving this, a new commit (d81788e, "address experimental stack start review feedback") landed on this branch mid-resolution, so I merged that in too rather than force-pushing over it — its content is unchanged, just the same rename applied consistently (e.g. findEncryptedSecret, the Path-aware stackProjectPath fix, and the TelemetryState/Effect.ensuring(telemetryState.flush) wiring in stack.command.ts/start.handler.ts are all preserved).

Verified: pnpm check:all passes (the only failure is the pre-existing @supabase/cli-go#lint:check gosec warnings, unrelated to this branch — no Go files touched), and the full apps/cli unit + integration suite passes (9204 tests). Please double-check the diff when you get a chance.