supabase · Coly010 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
@@ -237,6 +237,10 @@ Concrete examples worth watching for as more commands land:
 
 This rule is consistent with the repo-wide **Refactoring Policy** ("delete obsolete helpers, shims, and parallel code paths as part of the refactor") — it just makes the policy concrete for the legacy-port workflow.
 
+### `Config.Validate` parity has one home
+
+Go's `Config.Validate` (`apps/cli-go/pkg/config/config.go:989-1190`) is ported exactly once: `src/legacy/shared/legacy-config-validate.ts` (`legacyValidateResolvedConfig`). Both the db/migration loader (`legacy-db-config.toml-read.ts`) and the status/stop resolver (`legacy-local-config-values.ts`) build a `LegacyConfigValidationInput` from their own pipelines and call it — do not add per-command reimplementations of these checks. When a Go validation branch or message changes, change it there. `legacy-config-validate.parity.unit.test.ts` feeds the same broken configs through both real pipelines and asserts identical error strings; extend it when adding a branch both callers share.
+
 ---
 
 ## Legacy Port: Go CLI Output Parity
@@ -403,6 +407,7 @@ Read https://www.effect.solutions/testing for Effect testing patterns. Note that
 - `*.unit.test.ts` belongs to the `unit` Vitest project and is the default for unit-style and other fast in-process tests.
 - `*.integration.test.ts` belongs to the `integration` project and is for in-process integration tests that exercise real handler or service behavior with layered dependency replacement.
 - `*.e2e.test.ts` belongs to the `e2e` Vitest project and is for black-box CLI subprocess tests.
+- `*.live.test.ts` belongs to the `live` Vitest project and is for black-box CLI subprocess tests that run against a **real, running Supabase platform or local Docker stack** — see "Live tests" below.
 
 ### Testing policy
 
@@ -417,6 +422,21 @@ Read https://www.effect.solutions/testing for Effect testing patterns. Note that
 - Keep `*.e2e.test.ts` focused on golden paths, CLI surface behavior, and subprocess correctness, not branch-by-branch coverage.
 - **Forbidden pattern (do not add):** spawning the CLI to assert that `--help` renders a flag. Help text is dynamic over flag wiring and is exercised by the integration test's flag parser. The two backups e2e files removed alongside this guidance update are the canonical example of what not to write.
 
+### Live tests (`*.live.test.ts`)
+
+Live tests are black-box CLI subprocess tests — like `*.e2e.test.ts`, but run against a **real backend** instead of local fakes/mocks: either the real Management API (a full [supabox](https://github.com/supabase/supabox) platform stack) or a real local Docker dev stack (`supabase start`'s actual containers). They are the highest-fidelity, most expensive tier — reserved for the small set of behaviors that only a genuinely running backend can prove (auth round-trips, real Docker label filtering, real container lifecycle), not for anything an integration test can already cover with mocks.
+
+- **Where they run:** authored in this repo, but executed by the [`supabase/cli-e2e-ci`](https://github.com/supabase/cli-e2e-ci) harness, which builds this CLI, brings up a full supabox stack (and has a real Docker daemon, since that's how supabox itself runs), and invokes the `live` Vitest project (`nx run-many -t test:live`). They never run as part of the default unit/integration/e2e loop, and locally they no-op unless the live environment is configured (see below) — there is no need to stand up supabox yourself to develop other code.
+- **Add one whenever you add or change a command whose correctness genuinely depends on a real backend** — a new Management API command, or a change to `start`/`stop`/`status`'s real Docker interaction. Colocate it with the command, same as `*.e2e.test.ts`: `src/legacy/commands/<command>/[<subcommand>/]<subcommand>.live.test.ts`.
+- **Gating:** every live suite must be wrapped in one of `tests/helpers/live.ts`'s `describe.skipIf` gates so the file is inert (skipped, not failed) outside the cli-e2e-ci runner:
+  - `describeLive` — runs whenever `SUPABASE_ACCESS_TOKEN` is set (the live env is configured at all). Reuse this even for commands that don't call the Management API themselves (e.g. `stop`/`status`) — it doubles as the "we're in the full cli-e2e-ci runner, which also has a real Docker daemon" signal, and there is no dedicated Docker-availability gate today.
+  - `describeLiveProject` — additionally requires a provisioned project (`SUPABASE_LIVE_PROJECT_REF`); use for project-scoped Management API commands (branches, functions, project-scoped db).
+  - `describeLiveDataPlane` — additionally requires the project's own Postgres instance to be `ACTIVE_HEALTHY`; use for commands that talk to the project's data plane (migration, db, storage).
+- **Invocation:** use `runSupabaseLive(args, options?)` (wraps `runSupabase` with the `legacy` entrypoint and the live profile/timeout defaults) rather than calling `runSupabase` directly, so every live test picks up the same environment plumbing.
+- **Local-dev-stack live tests** (`start`/`stop`/`status`, and anything else that manages real Docker containers rather than calling the Management API) follow the same file/gating convention but don't need `SUPABASE_PROFILE`/project-ref machinery. Pattern: `mkdtemp` a project dir, `runSupabaseLive(["init"], { cwd })` to generate a real Go-schema `config.toml`, `runSupabaseLive(["start", ...])` to bring up (a lightweight subset of) the real stack, exercise the command under test, then clean up in `afterEach` (best-effort `stop --no-backup` + `rm` the temp dir) so a failed assertion never leaks containers onto the CI runner. See `commands/stop/stop.live.test.ts` and `commands/status/status.live.test.ts` for the canonical example.
+- **Keep the suite small and golden-path only** — same philosophy as `*.e2e.test.ts`, but even more so given the cost of a real backend. One or two scenarios per command is normal; branch-by-branch coverage belongs in `*.integration.test.ts`.
+- Timeouts are generous by default (`testTimeout`/`hookTimeout: 300_000` for the whole `live` project) because real platform/Docker operations are slow — pass an explicit per-`test()` timeout when a scenario needs less (or, for a real local-stack `start`, close to the full budget).
+
 ---
 
 ## Go CLI Parity Tracking

@@ -269,8 +269,8 @@ Legend:
 | `init`                                 | `ported`      | [`../src/legacy/commands/init/init.command.ts`](../src/legacy/commands/init/init.command.ts)                                                                                                                                                                                                                                                                                                                         |
 | `services`                             | `ported`      | [`../src/legacy/commands/services/services.command.ts`](../src/legacy/commands/services/services.command.ts)                                                                                                                                                                                                                                                                                                         |
 | `start`                                | `wrapped`     | [`../src/legacy/commands/start/start.command.ts`](../src/legacy/commands/start/start.command.ts)                                                                                                                                                                                                                                                                                                                     |
-| `stop`                                 | `wrapped`     | [`../src/legacy/commands/stop/stop.command.ts`](../src/legacy/commands/stop/stop.command.ts)                                                                                                                                                                                                                                                                                                                         |
-| `status`                               | `wrapped`     | [`../src/legacy/commands/status/status.command.ts`](../src/legacy/commands/status/status.command.ts)                                                                                                                                                                                                                                                                                                                 |
+| `stop`                                 | `ported`      | [`../src/legacy/commands/stop/stop.command.ts`](../src/legacy/commands/stop/stop.command.ts) — native; talks directly to Docker/Podman via subprocess, replicating Go's label-filter and container-naming scheme                                                                                                                                                                                                     |
+| `status`                               | `ported`      | [`../src/legacy/commands/status/status.command.ts`](../src/legacy/commands/status/status.command.ts) — native; talks directly to Docker/Podman via subprocess, replicating Go's label-filter and container-naming scheme                                                                                                                                                                                             |
 | `telemetry enable`                     | `ported`      | [`../src/legacy/commands/telemetry/enable/enable.command.ts`](../src/legacy/commands/telemetry/enable/enable.command.ts)                                                                                                                                                                                                                                                                                             |
 | `telemetry disable`                    | `ported`      | [`../src/legacy/commands/telemetry/disable/disable.command.ts`](../src/legacy/commands/telemetry/disable/disable.command.ts)                                                                                                                                                                                                                                                                                         |
 | `telemetry status`                     | `ported`      | [`../src/legacy/commands/telemetry/status/status.command.ts`](../src/legacy/commands/telemetry/status/status.command.ts)                                                                                                                                                                                                                                                                                             |

@@ -116,7 +116,10 @@ export const legacyConfigPush = Effect.fn("legacy.config.push")(function* (
     // Pass `ref` so a matching `[remotes.*]` block is merged over the base config
     // before decode (Go's `loadFromFile` with `Config.ProjectId` set). A duplicate
     // `project_id` across remotes surfaces Go's verbatim message.
-    const loaded = yield* loadProjectConfig(runtimeInfo.cwd, { projectRef: ref }).pipe(
+    const loaded = yield* loadProjectConfig(runtimeInfo.cwd, {
+      projectRef: ref,
+      goViperCompat: true,
+    }).pipe(
       Effect.catchTag(
         "ProjectConfigParseError",
         (cause) =>

@@ -347,12 +347,14 @@ describe("legacy db reset", () => {
   });
 
   it.live("finishes a local reset when bucket seeding hits a strict-loader-rejected config", () => {
-    // The bucket-seeding core re-loads config via the strict `@supabase/config` loader,
-    // which rejects some Go-valid configs (e.g. `[db.seed] enabled = "env(SEED_ENABLED)"`).
-    // The seam's Go recreate already validated + rebuilt the DB, so aborting here would
-    // leave the reset half-done — warn and skip buckets so reset finishes like Go.
+    // The bucket-seeding core re-loads config via the strict `@supabase/config` loader.
+    // `SEED_ENABLED=maybe` is invalid for both Go's `strconv.ParseBool` and the TS
+    // loader's coercion, so the reload fails during decode (unlike e.g. `1`/`true`,
+    // which both now accept). The seam's Go recreate already validated + rebuilt the
+    // DB, so aborting here would leave the reset half-done — warn and skip buckets so
+    // reset finishes like Go.
     const previous = process.env["SEED_ENABLED"];
-    process.env["SEED_ENABLED"] = "1";
+    process.env["SEED_ENABLED"] = "maybe";
     const { layer, out, seam } = setup(tmp.current, {
       toml: 'project_id = "test"\n\n[db.seed]\nenabled = "env(SEED_ENABLED)"\n',
       args: ["db", "reset"],

@@ -41,6 +41,7 @@ export const legacyFunctionsDeploy = Effect.fn("legacy.functions.deploy")(functi
     projectRoot: cliConfig.workdir,
     supabaseDir: join(cliConfig.workdir, "supabase"),
     dashboardUrl: legacyDashboardUrl(cliConfig.profile),
+    goViperCompat: true,
     yes,
     rawArgs,
     edgeRuntimeVersion,

@@ -89,7 +89,9 @@ const listExistingFunctionSlugs = Effect.fnUntraced(function* (workdir: string)
 });
 
 const resolveTemplateInputs = Effect.fnUntraced(function* (workdir: string, slug: string) {
-  const loaded = yield* loadProjectConfig(workdir).pipe(Effect.orElseSucceed(() => null));
+  const loaded = yield* loadProjectConfig(workdir, { goViperCompat: true }).pipe(
+    Effect.orElseSucceed(() => null),
+  );
   const port = loaded?.config.api.port ?? DEFAULT_LOCAL_API_PORT;
   const publishableKey = loaded?.config.auth.publishable_key ?? defaultPublishableKey;
   return {

@@ -33,5 +33,6 @@ export const legacyFunctionsServe = Effect.fn("legacy.functions.serve")(function
     debug,
     networkId,
     projectIdOverride: cliConfig.projectId,
+    goViperCompat: true,
   }).pipe(Effect.ensuring(telemetryState.flush));
 });
@@ -1695,7 +1695,7 @@ describe("legacy functions serve integration", () => {
               "verify_jwt = true",
               "",
               "[remotes.override]",
-              'project_id = "override-project"',
+              'project_id = "overrideprojectaaaaa"',
               "",
               "[remotes.override.functions.hello]",
               "verify_jwt = false",
@@ -1710,7 +1710,7 @@ describe("legacy functions serve integration", () => {
 
         const { layer } = setupServe({
           childSpawner,
-          projectId: Option.some("override-project"),
+          projectId: Option.some("overrideprojectaaaaa"),
         });
         const error = yield* legacyFunctionsServe(baseFlags()).pipe(
           Effect.provide(layer),
@@ -1724,20 +1724,20 @@ describe("legacy functions serve integration", () => {
 
         expect(deployMockState.volumeCalls).toEqual([
           {
-            volumeName: "supabase_edge_runtime_override-project",
-            projectId: "override-project",
+            volumeName: "supabase_edge_runtime_overrideprojectaaaaa",
+            projectId: "overrideprojectaaaaa",
           },
         ]);
         expect(deployMockState.networkCalls).toEqual([
           {
-            networkMode: "supabase_network_override-project",
-            projectId: "override-project",
+            networkMode: "supabase_network_overrideprojectaaaaa",
+            projectId: "overrideprojectaaaaa",
           },
         ]);
         expect(deployMockState.runCalls).toContainEqual(
           expect.objectContaining({
             command: "docker",
-            args: ["container", "inspect", "supabase_db_override-project"],
+            args: ["container", "inspect", "supabase_db_overrideprojectaaaaa"],
           }),
         );
 

@@ -162,7 +162,7 @@ const generatePrivateKey = Effect.fnUntraced(function* (algorithm: SigningAlgori
 
 const loadSigningKeysConfig = Effect.fnUntraced(function* (cwd: string) {
   const path = yield* Path.Path;
-  const loaded = yield* loadProjectConfig(cwd).pipe(
+  const loaded = yield* loadProjectConfig(cwd, { goViperCompat: true }).pipe(
     Effect.catchTag("ProjectConfigParseError", (cause) =>
       Effect.fail(
         new LegacyGenSigningKeyConfigParseError({

@@ -248,9 +248,9 @@ export const legacyGenTypes = Effect.fn("legacy.gen.types")(function* (flags: Le
     );
   }
 
-  const loadConfig = () => loadProjectConfig(cliConfig.workdir);
+  const loadConfig = () => loadProjectConfig(cliConfig.workdir, { goViperCompat: true });
   const loadConfigForRef = (projectRef: string) =>
-    loadProjectConfig(cliConfig.workdir, { projectRef });
+    loadProjectConfig(cliConfig.workdir, { projectRef, goViperCompat: true });
 
   const schemasFromConfig = (apiSchemas: ReadonlyArray<string> | undefined) =>
     defaultSchemas(apiSchemas);

@@ -183,7 +183,13 @@ export const legacySecretsSet = Effect.fn("legacy.secrets.set")(function* (
     // Without this, a schema-decode error on `--project-ref <remote-ref>`
     // would recover the *base* `[edge_runtime.secrets]` instead of the
     // explicitly selected remote's override.
-    const loadedConfig = yield* loadProjectConfig(runtimeInfo.cwd, { projectRef: ref }).pipe(
+    // `goViperCompat: true` opts into `applyRemoteOverride`'s duplicate-
+    // `project_id`/format checks (`packages/config/src/io.ts`) — required for
+    // the `DuplicateRemoteProjectIdError` catch below to ever fire.
+    const loadedConfig = yield* loadProjectConfig(runtimeInfo.cwd, {
+      projectRef: ref,
+      goViperCompat: true,
+    }).pipe(
       Effect.flatMap((loaded) => {
         if (loaded === null) {
           return Effect.succeed(null);
@@ -265,6 +271,17 @@ export const legacySecretsSet = Effect.fn("legacy.secrets.set")(function* (
       Effect.catchTag("DuplicateRemoteProjectIdError", (cause) =>
         debugLogger.debug(cause.message).pipe(Effect.as(null)),
       ),
+      // A `[remotes.*]` block's `project_id` fails Go's ref-pattern check —
+      // raised from `Config.Validate` (`pkg/config/config.go:996-1001`), which
+      // runs inside the same `Config.Load()` call as the duplicate check above
+      // (`config.go:882`). Go's `flags.LoadConfig` swallows this the same
+      // non-fatal way (`internal/secrets/set/set.go:22-24`), so a malformed
+      // remote block must not abort an otherwise-valid `secrets set`.
+      // `cause.message` already matches Go's string verbatim (see
+      // `InvalidRemoteProjectIdError`'s field doc).
+      Effect.catchTag("InvalidRemoteProjectIdError", (cause) =>
+        debugLogger.debug(cause.message).pipe(Effect.as(null)),
+      ),
     );
     if (loadedConfig !== null) {
       const projectEnv = yield* loadProjectEnvironment({
@@ -276,6 +293,7 @@ export const legacySecretsSet = Effect.fn("legacy.secrets.set")(function* (
           loadedConfig.edge_runtime,
           projectEnv,
           "edge_runtime",
+          { goViperCompat: true },
         );
         for (const [name, value] of Object.entries(resolved.secrets ?? {})) {
           // Go's `DecryptSecretHookFunc` (`pkg/config/secret.go:98`) never