feat(cli): add experimental stack list

AGENTS.md

@@ -28,7 +28,7 @@ These workspaces should generally follow this structure:
 - Standard scripts: `test`, `types:check`
 - Standard devDependencies: `@tsconfig/bun`, `@types/bun`, `typescript`
 
-Generic linting (`oxlint`), formatting (`oxfmt`), and unused-code analysis (`knip`) are repo-wide, not per-package: the tools are root devDependencies configured by `.oxlintrc.json`, `.oxfmtrc.json`, and `knip.json` at the repo root (knip's config maps each workspace under its `workspaces` key). Effect-specific linting is scoped to `packages/stack` through `.oxlintrc.effect.json`; run it with the root `lint:effect:check` or `lint:effect:fix` scripts. The root `check:all`/`fix:all` scripts are the sole repo-wide quality entrypoints and use Turbo to orchestrate the root-owned generic `lint:*`/`fmt:*`/`knip:*` scripts and package `types:check` targets; `fix:all` runs the Effect lint fix after those generic fixes complete. Package-local work can run `pnpm types:check` and the package's test scripts; `pnpm exec oxlint`, `pnpm exec oxfmt`, and `pnpm exec knip-bun` from the repo root also work directly.
+Generic linting (`oxlint`), formatting (`oxfmt`), and unused-code analysis (`knip`) are repo-wide, not per-package: the tools are root devDependencies configured by `.oxlintrc.json`, `.oxfmtrc.json`, and `knip.json` at the repo root (knip's config maps each workspace under its `workspaces` key). Effect-specific linting covers `packages/stack` and all files under `apps/cli/src/commands/experimental/stack` through `.oxlintrc.effect.json`; run it with the root `lint:effect:check` or `lint:effect:fix` scripts. The root `check:all`/`fix:all` scripts are the sole repo-wide quality entrypoints and use Turbo to orchestrate the root-owned generic `lint:*`/`fmt:*`/`knip:*` scripts and package `types:check` targets; `fix:all` runs the Effect lint fix after those generic fixes complete. Package-local work can run `pnpm types:check` and the package's test scripts; `pnpm exec oxlint`, `pnpm exec oxfmt`, and `pnpm exec knip-bun` from the repo root also work directly.
 
 Expected exceptions:
 

apps/cli/package.json

@@ -58,6 +58,7 @@
     "@supabase/config": "workspace:*",
     "@supabase/pg-delta": "1.0.0-alpha.49",
     "@supabase/pg-topo": "1.0.0-alpha.6",
+    "@supabase/stack": "workspace:*",
     "@tsconfig/bun": "catalog:",
     "@types/bun": "catalog:",
     "@types/pg": "^8.23.1",

apps/cli/src/command-internal/legacy-db-target-flags.ts

@@ -181,6 +181,10 @@ export const VALUE_CONSUMING_LONG_FLAGS = new Set([
   "link",
   "issue-type",
   "improvement",
+  // experimental stack start flags
+  "stack",
+  "stack-id",
+  "preparation",
 ]);
 
 /**

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

@@ -1,5 +1,6 @@
 import { Command } from "effect/unstable/cli";
 import { legacyWorkersCommand } from "./workers/workers.command.ts";
+import { legacyExperimentalStackCommand } from "./stack/stack.command.ts";
 
 /**
  * `supabase experimental` — the parent for command families that are not yet
@@ -17,6 +18,6 @@ export const legacyExperimentalCommand = Command.make("experimental").pipe(
     "Experimental commands. These are unstable: their flags, output, and invocation path can change or be removed in any release, and they are excluded from the CLI's compatibility promise.",
   ),
   Command.withShortDescription("Experimental, unstable commands"),
-  Command.withSubcommands([legacyWorkersCommand]),
+  Command.withSubcommands([legacyWorkersCommand, legacyExperimentalStackCommand]),
   Command.unlisted,
 );

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

@@ -0,0 +1,16 @@
+# `supabase experimental stack list`
+
+Lists persisted managed local stacks discovered in the global stack registry.
+The command includes stopped stacks and performs no config loading, owner RPC,
+activation, or lifecycle mutation. Registry discovery is currently fail-fast: a
+corrupt or unsupported entry can prevent other entries from being listed.
+
+Entries are sorted by project root, stack name, and id. Text output includes the
+identity, project root, branch context, runtime, and desired lifecycle. Structured
+output returns the same fields under `stacks`. The legacy `-o/--output` flag is
+rejected; use `--output-format json`.
+
+The command reads `${SUPABASE_HOME ?? $HOME/.supabase}/managed/stacks/<stack-id>/`,
+including each persisted state document and state remnant metadata. It consumes
+`SUPABASE_HOME`, falling back to `HOME/.supabase`. Exit code 0 indicates success;
+exit code 1 indicates a registry read error or rejected legacy output flag.

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

@@ -0,0 +1,12 @@
+import { Command } from "effect/unstable/cli";
+import { withJsonErrorHandling } from "../../../../shared/output/json-error-handling.ts";
+import { withLegacyCommandInstrumentation } from "../../../../telemetry/legacy-command-instrumentation.ts";
+import { legacyExperimentalStackList } from "./list.handler.ts";
+
+export const legacyExperimentalStackListCommand = Command.make("list").pipe(
+  Command.withDescription("List persisted managed local Supabase stacks."),
+  Command.withShortDescription("List managed local stacks"),
+  Command.withHandler(() =>
+    legacyExperimentalStackList().pipe(withLegacyCommandInstrumentation(), withJsonErrorHandling),
+  ),
+);

apps/cli/src/commands/experimental/stack/list/list.errors.ts

@@ -0,0 +1,20 @@
+import { Data } from "effect";
+import {
+  actionability,
+  type CliErrorActionabilityDeclaration,
+  ErrorActionabilityId,
+} from "../../../../shared/telemetry/error-actionability.ts";
+
+export class LegacyExperimentalStackListError extends Data.TaggedError(
+  "LegacyExperimentalStackListError",
+)<{
+  readonly message: string;
+  readonly reason: "flags" | "invalid-config";
+  readonly suggestion?: string;
+  readonly cause?: unknown;
+}> {
+  get [ErrorActionabilityId](): CliErrorActionabilityDeclaration {
+    if (this.reason === "flags") return actionability.provideFlags;
+    return actionability.invalidConfig;
+  }
+}

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

@@ -0,0 +1,81 @@
+import { Effect, Match, Option } from "effect";
+import {
+  type StackDescriptor,
+  type StackDiscoveryError,
+  type StackRuntime,
+} from "@supabase/stack/effect";
+import { Output } from "../../../../shared/output/output.service.ts";
+import { LegacyOutputFlag } from "../../../../shared/legacy/global-flags.ts";
+import { LegacyExperimentalStackApi } from "../stack.shared.ts";
+import { LegacyExperimentalStackListError } from "./list.errors.ts";
+
+const entry = (descriptor: StackDescriptor) => ({
+  id: descriptor.id,
+  project_root: descriptor.projectRoot,
+  name: descriptor.name,
+  branch_context: descriptor.branchContext,
+  runtime: descriptor.runtime,
+  desired_lifecycle: descriptor.desiredLifecycle,
+});
+
+const compareCodeunit = (left: string, right: string): number =>
+  left === right ? 0 : left < right ? -1 : 1;
+
+const compareEntries = (
+  left: ReturnType<typeof entry>,
+  right: ReturnType<typeof entry>,
+): number => {
+  const project = compareCodeunit(left.project_root, right.project_root);
+  if (project !== 0) return project;
+  const name = compareCodeunit(left.name, right.name);
+  return name !== 0 ? name : compareCodeunit(left.id, right.id);
+};
+
+const mapStackError = (error: StackDiscoveryError) =>
+  new LegacyExperimentalStackListError({
+    reason: "invalid-config",
+    message: error.message,
+    suggestion:
+      "Inspect the managed stack registry under $SUPABASE_HOME/managed/stacks or ~/.supabase/managed/stacks.",
+    cause: error,
+  });
+
+const renderRuntime = (runtime: StackRuntime): string =>
+  Match.value(runtime).pipe(
+    Match.when({ kind: "native" }, () => "native"),
+    Match.when({ kind: "container" }, ({ engine }) => `container (${engine})`),
+    Match.exhaustive,
+  );
+
+const render = (stacks: ReadonlyArray<ReturnType<typeof entry>>): string => {
+  if (stacks.length === 0) return "No managed stacks found.\n";
+  const lines = stacks.flatMap((stack, index) => [
+    ...(index === 0 ? [] : [""]),
+    `${stack.name} (${stack.id})`,
+    `  Project: ${stack.project_root}`,
+    `  Branch: ${stack.branch_context}`,
+    `  Runtime: ${renderRuntime(stack.runtime)}`,
+    `  Desired lifecycle: ${stack.desired_lifecycle}`,
+  ]);
+  return `${lines.join("\n")}\n`;
+};
+
+export const legacyExperimentalStackList = Effect.fn("legacy.experimental.stack.list")(
+  function* () {
+    const output = yield* Output;
+    const legacyOutput = yield* Effect.serviceOption(LegacyOutputFlag);
+    if (Option.isSome(legacyOutput) && Option.isSome(legacyOutput.value))
+      return yield* new LegacyExperimentalStackListError({
+        reason: "flags",
+        message: "The legacy -o/--output flag is not supported here; use --output-format json.",
+        suggestion: "Use --output-format json or --output-format text.",
+      });
+    const api = yield* LegacyExperimentalStackApi;
+    const stacks = (yield* api.listStacks().pipe(Effect.mapError(mapStackError)))
+      .map(entry)
+      .sort(compareEntries);
+    if (output.format === "text") yield* output.raw(render(stacks));
+    else yield* output.success("", { stacks });
+    return stacks;
+  },
+);