fix(cli): preserve saved stack settings on restart

Author: jgoux

apps/cli/docs/stack-commands.md

@@ -12,7 +12,7 @@ native runtimes.
 | `supabase stack start`   | Create or resume the project's stack.                                             |
 | `supabase stack status`  | Show identity, readiness, and drift, or export connection variables with `--env`. |
 | `supabase stack logs`    | Read retained or live stack logs.                                                 |
-| `supabase stack restart` | Prepare the current project configuration, then restart an existing stack.        |
+| `supabase stack restart` | Restart an existing stack using its saved effective configuration.                |
 | `supabase stack stop`    | Stop a stack while retaining its data.                                            |
 
 Use each command's `--help` for its available targeting and runtime options.
@@ -152,12 +152,15 @@ including `--workdir` and `SUPABASE_WORKDIR`, and prefers JSON when both files e
 
 ## Service selection and shutdown
 
-`supabase stack restart` applies the current project configuration to an existing stack. It
-prepares required artifacts before stopping, then stops and starts the same stack identity. Stack
-data and durable identity are preserved. Select a stack with `--stack <name>` or `--stack-id <id>`;
-the selected stack's persisted project root supplies the configuration for ID targets. Restart does
-not retain one-off `start` flags such as `--exclude`, `--eager`, or `--preparation`; those settings
-fall back to the project's configuration and runtime defaults.
+`supabase stack restart` reuses an existing stack's saved effective configuration. It stops and
+starts the same stack identity, preserving its data. Normal startup may still download missing
+artifacts according to the saved preparation policy. Select a stack with `--stack <name>` or
+`--stack-id <id>`. The restart handler does not reload project configuration. Set
+`SUPABASE_EXPERIMENTAL_STACK=1` when restarting by ID outside the project or with invalid project
+configuration, so feature routing does not depend on that configuration. Start flags such as `--exclude`, `--eager`, or
+`--preparation` remain in the saved stack configuration; a later normal `start` reloads the project
+configuration and current flags.
+An unconfigured stack must be initialized with `supabase stack start` before it can be restarted.
 
 `supabase stack start --exclude studio,analytics -x mail` disables those services in the effective
 start configuration without changing the project file. Valid names are `rest`, `auth`, `realtime`,

apps/cli/src/commands/experimental/stack/restart/SIDE_EFFECTS.md

@@ -6,18 +6,21 @@ configuration or `SUPABASE_EXPERIMENTAL_STACK=1`. It has no top-level alias.
 ## Files Read
 
 Reads the selected stack's descriptor and `<SUPABASE_HOME>/managed/stacks/<id>/state.json`,
-plus owner metadata in `control.json` when present. Configuration comes from the
-selected descriptor's project root: `supabase/config.toml` or `supabase/config.json`,
-project environment input through the config loader, configured signing material,
-and enabled function dotenv files under `supabase/functions/`.
+plus owner metadata in `control.json` when present. Restart does not load project
+configuration; it uses the selected stack's saved effective configuration and preparation policy.
+Feature routing and workdir discovery may still read `supabase/config.toml` or
+`supabase/config.json`. Use `SUPABASE_EXPERIMENTAL_STACK=1` with `--stack-id` when
+project configuration is invalid or unavailable. Runtime startup can read files
+referenced by the saved definition, such as signing material.
 
 ## Files Written
 
 The CLI does not rewrite project configuration. The stack package updates its
 state record, owner metadata, runtime files, logs, and service data beneath the
-selected stack directory. Preparation may populate the package's artifact cache
-or the container engine's image store. Restart preserves the stack ID and data;
-it never calls create or destroy.
+selected stack directory. Restart preserves the stack ID and data; it never calls
+create or destroy. There is no explicit `prepare()` call. Runtime startup reuses
+cached artifacts and may fetch missing ones; the saved `background` preparation
+policy can also prefetch enabled lazy services, while `on-demand` skips that prefetch.
 
 ## API Routes
 
@@ -29,18 +32,18 @@ Artifact URLs and registry requests depend on the selected runtime and releases.
 
 - `SUPABASE_HOME`: managed state location; defaults to the user's `.supabase` directory.
 - `HOME`: participates in default home resolution.
-- Environment references in project configuration and function dotenv files are
-  resolved by the shared config loader. Their secret values are not emitted.
+- Project configuration and function dotenv overrides are not reloaded by the
+  restart handler. Saved secret values are not emitted.
 - Standard CLI settings, output, and telemetry environment controls apply through
   the existing CLI layers; restart adds no command-specific environment variables.
 
 ## Exit Codes
 
-| Code  | Condition                                                                                            |
-| ----- | ---------------------------------------------------------------------------------------------------- |
-| `0`   | The selected stack restarted successfully.                                                           |
-| `1`   | Invalid flags, missing stack/configuration, or a configuration, preparation, stop, or start failure. |
-| `130` | The CLI waiter was interrupted.                                                                      |
+| Code  | Condition                                                 |
+| ----- | --------------------------------------------------------- |
+| `0`   | The selected stack restarted successfully.                |
+| `1`   | Invalid flags, missing stack, or a stop or start failure. |
+| `130` | The CLI waiter was interrupted.                           |
 
 ## Telemetry Events Fired
 
@@ -63,11 +66,11 @@ Legacy `-o/--output` is rejected with guidance to use `--output-format`.
 ## Notes
 
 Targets one existing stack through `--stack`, `--stack-id`, or the current
-project. Configuration validation and preparation precede stop. A preparation
-failure leaves the running stack untouched; stop failure prevents start; start
-failure leaves the same stack stopped and available for recovery. Interrupting
+project. The command stops and starts without an explicit configuration. Stop failure prevents
+start; start failure leaves the same stack stopped and available for recovery. Interrupting
 the CLI waiter follows the package's owner lifecycle contract and does not invoke
 destroy from the command handler.
+An unconfigured stack must be initialized with `supabase stack start` before it can be restarted.
 
-Restart does not retain one-off `start` flags such as `--exclude`, `--eager`, or
-`--preparation`; it uses the current project configuration and runtime defaults.
+Restart reuses saved one-off `start` flags such as `--exclude`, `--eager`, and
+`--preparation`; a normal `start` reloads project configuration and current flags.

apps/cli/src/commands/experimental/stack/restart/restart.command.ts

@@ -5,7 +5,10 @@ import { withCommandTelemetry } from "../../../../telemetry/command-telemetry.ts
 import { stackRestart } from "./restart.handler.ts";
 
 const config = {
-  stack: Flag.string("stack").pipe(Flag.withDescription("Restart a named stack."), Flag.optional),
+  stack: Flag.string("stack").pipe(
+    Flag.withDescription("Restart a named stack (defaults to the current project stack)."),
+    Flag.optional,
+  ),
   stackId: Flag.string("stack-id").pipe(
     Flag.withDescription("Restart an existing stack by id."),
     Flag.optional,
@@ -16,7 +19,7 @@ export type StackRestartFlags = CliCommand.Command.Config.Infer<typeof config>;
 
 export const stackRestartCommand = Command.make("restart", config).pipe(
   Command.withDescription(
-    "Restart an existing managed local Supabase stack using the current project configuration, prepared before stop.",
+    "Restart an existing managed local Supabase stack using its saved configuration, including the previous start's service selection and preparation policy.",
   ),
   Command.withShortDescription("Restart a managed local stack"),
   Command.withExamples([

apps/cli/src/commands/experimental/stack/restart/restart.handler.ts

@@ -1,5 +1,5 @@
 import { Effect, Match, Option } from "effect";
-import type { StackError, StackId } from "@supabase/stack/effect";
+import type { StackDescriptor, StackError, StackId } from "@supabase/stack/effect";
 import { Output } from "../../../../shared/output/output.service.ts";
 import { OutputFlag } from "../../../../command-internal/global-flags.ts";
 import { CommandSettings } from "../../../../config/command-settings.service.ts";
@@ -13,7 +13,6 @@ import {
   validateStackId,
   validateStackTarget,
 } from "../stack.shared.ts";
-import { loadStackConfig } from "../stack-config.ts";
 import type { StackRestartFlags } from "./restart.command.ts";
 import { StackCommandRestartError } from "./restart.errors.ts";
 
@@ -32,7 +31,7 @@ const mapStackError = (error: StackError) => {
     Match.tag("PortUnavailableError", "PortAllocationError", () => ({
       reason: "port" as const,
       suggestion:
-        "Free the conflicting port or update the local stack port configuration, then retry.",
+        "Free the conflicting port and retry, or stop the stack and use supabase stack start to apply updated project port configuration.",
     })),
     Match.tag(
       "InvalidStackConfigError",
@@ -72,6 +71,14 @@ const mapStackError = (error: StackError) => {
       reason: "artifact" as const,
       suggestion: "Retry the stack restart with --debug if the artifact cannot be prepared.",
     })),
+    Match.tag("StackRuntimeError", () => ({
+      reason: "unknown" as const,
+      suggestion: "Retry the stack restart with --debug and inspect the runtime diagnostics.",
+    })),
+    Match.tag("StackCleanupError", () => ({
+      reason: "unknown" as const,
+      suggestion: "Retry the stack restart with --debug and inspect cleanup diagnostics.",
+    })),
     Match.orElse(() => ({ reason: "unknown" as const })),
   );
   return new StackCommandRestartError({
@@ -96,13 +103,12 @@ export const stackRestart = Effect.fn("experimental.stack.restart")(function* (
       stackId: Option.getOrUndefined(flags.stackId),
     }).pipe(Effect.mapError(mapTargetError));
 
-    let target: { readonly projectRoot: string; readonly id: StackId };
+    let id: StackId;
+    let desiredLifecycle: StackDescriptor["desiredLifecycle"];
     if (Option.isSome(flags.stackId)) {
-      const validId = yield* validateStackId(flags.stackId.value).pipe(
-        Effect.mapError(mapTargetError),
-      );
-      const inspection = yield* api.inspectStack(validId).pipe(Effect.mapError(mapStackError));
-      target = { projectRoot: inspection.descriptor.projectRoot, id: inspection.descriptor.id };
+      id = yield* validateStackId(flags.stackId.value).pipe(Effect.mapError(mapTargetError));
+      const inspection = yield* api.inspectStack(id).pipe(Effect.mapError(mapStackError));
+      desiredLifecycle = inspection.descriptor.desiredLifecycle;
     } else {
       const found = yield* api
         .findStack({
@@ -120,30 +126,22 @@ export const stackRestart = Effect.fn("experimental.stack.restart")(function* (
             ? "Choose an existing --stack name or omit --stack for the current project."
             : "Run supabase stack start first.",
         });
-      target = { projectRoot: found.value.projectRoot, id: found.value.id };
+      id = found.value.id;
+      desiredLifecycle = found.value.desiredLifecycle;
     }
-    const config = yield* loadStackConfig(target.projectRoot).pipe(
-      Effect.mapError(
-        (error) =>
-          new StackCommandRestartError({
-            reason: "invalid-config",
-            message: error.message,
-            cause: error,
-          }),
-      ),
-    );
-    const stack = yield* api.openStack(target.id).pipe(Effect.mapError(mapStackError));
-    const task = yield* output.task("Preparing local Supabase stack...");
-    yield* stack.prepare({ config }).pipe(
-      Effect.mapError(mapStackError),
-      Effect.tapError((error) => task.fail(error.message)),
-    );
-    yield* task.message("Restarting local Supabase stack...");
+    if (desiredLifecycle === "unconfigured")
+      return yield* new StackCommandRestartError({
+        reason: "lifecycle",
+        message: "The selected stack has not been configured yet.",
+        suggestion: "Run supabase stack start to configure the stack first.",
+      });
+    const stack = yield* api.openStack(id).pipe(Effect.mapError(mapStackError));
+    const task = yield* output.task("Restarting local Supabase stack...");
     yield* stack.stop.pipe(
       Effect.mapError(mapStackError),
       Effect.tapError((error) => task.fail(error.message)),
     );
-    const status = yield* stack.start({ config }).pipe(
+    const status = yield* stack.start().pipe(
       Effect.mapError(mapStackError),
       Effect.tapError((error) => task.fail(error.message)),
       Effect.tap(() => task.clear()),