feat(stack): prepare slim resources on demand

apps/cli/src/next/commands/branches/switch/switch.handler.ts

@@ -145,18 +145,18 @@ export const switchBranch = Effect.fn("branches.switch")(function* (opts: {
     // TODO: run `supabase pull` against the new branch before restarting the stack
     // so the local config reflects the branch's migrations and seed state.
     // `pull` does not exist yet.
+    const launch = stackCheck.value.launch;
     const launchConfig =
-      stackCheck.value.launch === undefined
-        ? toStartStackConfig([], "auto")
+      launch === undefined
+        ? toStartStackConfig([], undefined)
         : withServiceVersions(
             toStartStackConfig(
-              stackCheck.value.launch.excludedServices?.filter(
-                (service): service is ExcludedStackService =>
-                  excludedStackServices.some((candidate) => candidate === service),
+              launch.excludedServices?.filter((service): service is ExcludedStackService =>
+                excludedStackServices.some((candidate) => candidate === service),
               ) ?? [],
-              stackCheck.value.launch.mode,
+              "mode" in launch ? launch.mode : undefined,
             ),
-            stackCheck.value.launch.versions,
+            launch.versions,
           );
     const loadedProjectConfig = yield* loadProjectConfig(projectHome.projectRoot);
 
@@ -166,7 +166,7 @@ export const switchBranch = Effect.fn("branches.switch")(function* (opts: {
       projectDir: projectHome.projectRoot,
       name: stackName,
       portIntents: managedPortIntents(launchConfig, loadedProjectConfig ?? undefined),
-      ...(stackCheck.value.launch !== undefined && { launch: stackCheck.value.launch }),
+      ...(launch !== undefined && { launch }),
       ...launchConfig,
     });
 

apps/cli/src/next/commands/functions/dev/functions-dev-runtime.ts

@@ -55,7 +55,7 @@ const startFullStack = Effect.fnUntraced(function* (opts: FunctionsDevStackOptio
   const serviceVersionContext = yield* resolveServiceVersionContext([], undefined);
   const loadedProjectConfig = yield* loadProjectConfig(projectHome.projectRoot);
   const stackConfig = withServiceVersions(
-    toStartStackConfig([], "auto"),
+    toStartStackConfig([], undefined),
     serviceVersionContext.runtimeVersions,
   );
   const stackLayer = yield* daemonLayer({
@@ -65,7 +65,6 @@ const startFullStack = Effect.fnUntraced(function* (opts: FunctionsDevStackOptio
     name: opts.stack,
     edgeRuntime: opts.edgeRuntime,
     launch: {
-      mode: "auto",
       versions: serviceVersionContext.pinnedBaseline,
       excludedServices: [],
     },

apps/cli/src/next/commands/start/service-version-overrides.unit.test.ts

@@ -11,14 +11,14 @@ import {
 } from "../../config/service-version-resolution.ts";
 
 describe("service version overrides", () => {
-  test("parses and normalizes repeated flag overrides", async () => {
+  test("parses repeated flag overrides as exact image tags", async () => {
     await expect(
       Effect.runPromise(
         parseServiceVersionOverrides(["postgrest=v14.5", "mailpit=1.30.2", "auth=2.180.0"]),
       ),
     ).resolves.toEqual({
-      postgrest: "14.5",
-      mailpit: "v1.30.2",
+      postgrest: "v14.5",
+      mailpit: "1.30.2",
       auth: "2.180.0",
     });
   });
@@ -27,8 +27,8 @@ describe("service version overrides", () => {
     const candidateBaseline = {
       ...DEFAULT_VERSIONS,
       postgres: "17.6.1.090",
-      postgrest: "14.5",
-      auth: "2.187.0",
+      postgrest: "v14.5",
+      auth: "v2.187.0",
     };
 
     const layer = Layer.mergeAll(
@@ -68,12 +68,12 @@ describe("service version overrides", () => {
       runtimeVersions: {
         ...candidateBaseline,
         postgres: "17.4.1.045",
-        auth: "2.170.0",
+        auth: "v2.170.0",
         storage: "1.40.0",
       },
       activeOverrides: [
         { service: "postgres", version: "17.4.1.045", source: "flag" },
-        { service: "auth", version: "2.170.0", source: "flag" },
+        { service: "auth", version: "v2.170.0", source: "flag" },
         { service: "storage", version: "1.40.0", source: "local" },
       ],
       availableUpdates: [],

apps/cli/src/next/commands/start/start.command.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer, Context } from "effect";
+import { Effect, Layer, Context, Option } from "effect";
 import { loadProjectConfig } from "@supabase/config";
 import {
   DEFAULT_MANAGED_STACK_NAME,
@@ -79,14 +79,15 @@ export const serviceVersionFlag = Flag.string("service-version").pipe(
 
 const modeFlag = Flag.choice("mode", startModes).pipe(
   Flag.withDescription(
-    'Stack startup mode. "auto" prefers native binaries and falls back to Docker, "native" requires native-compatible services, and "docker" forces Docker for all services.',
+    'Stack startup mode. "native" requires native-compatible services and "docker" requires a usable Docker or Podman runtime.',
   ),
-  Flag.withDefault("auto" as StartMode),
+  Flag.optional,
+  Flag.map(Option.getOrUndefined),
 );
 
 interface StartVersionStateShape {
   readonly launch: {
-    readonly mode: StartMode;
+    readonly mode?: StartMode;
     readonly versions: Readonly<Record<string, string>>;
     readonly excludedServices: ReadonlyArray<ExcludedStackService>;
   };
@@ -124,7 +125,7 @@ export type StartFlags = CliCommand.Command.Config.Infer<typeof flags>;
 export const startCommand = Command.make("start", flags).pipe(
   Command.withDescription(
     "Start the local Supabase development stack.\n\n" +
-      "Starts the full local Supabase stack. Use --mode auto (default) to prefer native binaries and fall back to Docker, --mode native to require native-compatible services, or --mode docker to force Docker-backed startup.\n\n" +
+      "Starts the full local Supabase stack. By default, a usable Docker or Podman runtime selects Docker mode; otherwise the stack uses native mode. Use --mode to require one explicitly.\n\n" +
       "Named CLI stacks persist managed runtime state under the Supabase home directory. Use --exclude to skip optional services. Use --detach to run in the background.",
   ),
   Command.withShortDescription("Start local Supabase stack"),
@@ -219,7 +220,7 @@ export const startCommand = Command.make("start", flags).pipe(
               portDocument: portIntents,
             });
       const launch = {
-        mode: flags.mode,
+        ...(flags.mode === undefined ? {} : { mode: flags.mode }),
         versions: serviceVersionContext.pinnedBaseline,
         excludedServices: flags.exclude,
         ...(existingSummary?.lastNotifiedUpdateFingerprint === undefined
@@ -242,12 +243,15 @@ export const startCommand = Command.make("start", flags).pipe(
         cwd: runtimeInfo.cwd,
         name: flags.stack,
       });
+      if (summary.launch === undefined) {
+        return yield* Effect.die("Managed stack started without persisted launch settings");
+      }
 
       return {
         stackLayer,
         startVersionState: StartVersionState.of({
           launch: {
-            mode: flags.mode,
+            mode: "mode" in summary.launch ? summary.launch.mode : undefined,
             versions: serviceVersionContext.pinnedBaseline,
             excludedServices: flags.exclude,
           },

apps/cli/src/next/commands/start/start.handler.ts

@@ -50,7 +50,6 @@ export const start = Effect.fnUntraced(function* (flags: StartFlags) {
         yield* updateManagedLaunch({
           ...lifecycleInput,
           launch: {
-            mode: launch.mode,
             versions: launch.versions,
             excludedServices: launch.excludedServices,
             lastNotifiedUpdateFingerprint: serviceVersionContext.updateFingerprint,
@@ -68,7 +67,7 @@ export const start = Effect.fnUntraced(function* (flags: StartFlags) {
       }
 
       yield* analytics.capture("cli_stack_started", {
-        mode: flags.mode,
+        mode: launch.mode,
         detach: flags.detach,
         stack: flags.stack,
       });

apps/cli/src/next/commands/start/start.integration.test.ts

@@ -80,7 +80,7 @@ describe("start handler", () => {
               );
               return start({
                 stack: fixture.stackName,
-                mode: "auto",
+                mode: "docker",
                 exclude: [],
                 serviceVersion: [],
                 detach: false,