From 940a6a9eda671a3f0798e6182f98f2de2e737f5d Mon Sep 17 00:00:00 2001
From: Colum Ferry <cferry09@gmail.com>
Date: Thu, 4 Jun 2026 11:59:01 +0100
Subject: [PATCH 1/2] feat(cli): port bootstrap command to native TypeScript

Replaces the Phase-0 Go proxy for `supabase bootstrap` with a native
TypeScript implementation in the legacy shell. The command orchestrates:
workdir resolve/prompt -> template list/download -> blank init ->
ensure-login -> projects create -> api-keys (backoff) -> link services ->
health poll (backoff) -> write .env -> db push -> start suggestion.

Every step is native except the migration push, which is delegated to the
bundled Go binary via LegacyGoProxy as a documented interim until `db push`
is natively ported (LegacyGoProxy.exec exits on non-zero rather than
failing, so its push backoff is not reproducible from the proxy).

Per the "hoist before you duplicate" policy, shared orchestration cores are
extracted from the already-ported login/create/api-keys/link handlers and
those handlers refactored to delegate:
- legacy-ensure-login (browser login + post-login telemetry)
- legacy-project-create-core
- legacy-get-api-keys
- legacy-link-services-core
- legacy-tenant-keys (legacyExtractServiceKeys)
- login api/crypto layers moved to legacy/shared so bootstrap composes them
  without a cross-command import

Go-parity notes:
- bootstrap fires no cli_project_linked event: Go calls link.LinkServices
  (services only), not link.Run, so it skips the project-linked telemetry,
  status check, and linked-project.json temp write.
- api-keys are fetched without `reveal` (Go's RunGetApiKeys uses empty params).
- workdir / db-password env vars are read prefixed (SUPABASE_WORKDIR,
  SUPABASE_DB_PASSWORD) to match Go's viper SetEnvPrefix("SUPABASE").
- "Using workdir" prints only when the resolved workdir differs from the cwd.

Template download validates entries stay within the target directory, and
GitHub/health error bodies are sanitized before surfacing.
---
 apps/cli/docs/go-cli-porting-status.md        |   8 +-
 .../legacy/commands/bootstrap/SIDE_EFFECTS.md | 132 +++--
 .../commands/bootstrap/bootstrap.command.ts   |  10 +-
 .../commands/bootstrap/bootstrap.dotenv.ts    | 174 +++++++
 .../bootstrap/bootstrap.dotenv.unit.test.ts   | 121 +++++
 .../commands/bootstrap/bootstrap.errors.ts    |  54 +++
 .../commands/bootstrap/bootstrap.handler.ts   | 294 +++++++++++-
 .../bootstrap/bootstrap.integration.test.ts   | 449 ++++++++++++++++++
 .../commands/bootstrap/bootstrap.layers.ts    |  55 +++
 .../commands/bootstrap/bootstrap.pgconfig.ts  |  74 +++
 .../bootstrap/bootstrap.pgconfig.unit.test.ts |  68 +++
 .../commands/bootstrap/bootstrap.suggest.ts   |  34 ++
 .../bootstrap/bootstrap.suggest.unit.test.ts  |  36 ++
 .../commands/bootstrap/bootstrap.templates.ts | 229 +++++++++
 .../src/legacy/commands/link/link.handler.ts  | 121 +----
 .../legacy/commands/login/login.handler.ts    | 137 +-----
 .../src/legacy/commands/login/login.layers.ts |   4 +-
 .../projects/api-keys/api-keys.handler.ts     |  18 +-
 .../projects/create/create.handler.ts         | 148 +-----
 apps/cli/src/legacy/shared/legacy-colors.ts   |  22 +
 .../src/legacy/shared/legacy-ensure-login.ts  | 181 +++++++
 .../src/legacy/shared/legacy-get-api-keys.ts  |  33 ++
 .../shared/legacy-link-services-core.ts       | 126 +++++
 .../legacy-login-api.layer.ts}                |   9 +-
 .../legacy-login-crypto.layer.ts}             |   7 +-
 .../shared/legacy-project-create-core.ts      | 167 +++++++
 .../src/legacy/shared/legacy-tenant-keys.ts   |  43 ++
 27 files changed, 2301 insertions(+), 453 deletions(-)
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.unit.test.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.errors.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.unit.test.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.unit.test.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts
 create mode 100644 apps/cli/src/legacy/shared/legacy-colors.ts
 create mode 100644 apps/cli/src/legacy/shared/legacy-ensure-login.ts
 create mode 100644 apps/cli/src/legacy/shared/legacy-get-api-keys.ts
 create mode 100644 apps/cli/src/legacy/shared/legacy-link-services-core.ts
 rename apps/cli/src/legacy/{commands/login/login-api.layer.ts => shared/legacy-login-api.layer.ts} (92%)
 rename apps/cli/src/legacy/{commands/login/login-crypto.layer.ts => shared/legacy-login-crypto.layer.ts} (93%)
 create mode 100644 apps/cli/src/legacy/shared/legacy-project-create-core.ts
 create mode 100644 apps/cli/src/legacy/shared/legacy-tenant-keys.ts

diff --git a/apps/cli/docs/go-cli-porting-status.md b/apps/cli/docs/go-cli-porting-status.md
index ff70e62590..1abb8ab283 100644
--- a/apps/cli/docs/go-cli-porting-status.md
+++ b/apps/cli/docs/go-cli-porting-status.md
@@ -57,9 +57,9 @@ These commands exist in the TS CLI today but have no direct top-level equivalent
 
 ## Quick Start
 
-| Old command | TS status | TS command path or `missing` | Missing flags/params | Extra TS flags/params | Notes                                       |
-| ----------- | --------- | ---------------------------- | -------------------- | --------------------- | ------------------------------------------- |
-| `bootstrap` | `missing` | `missing`                    | `n/a`                | `n/a`                 | No TS command yet. Wrapped in legacy shell. |
+| Old command | TS status | TS command path or `missing` | Missing flags/params | Extra TS flags/params | Notes                                                                                                                                                                                  |
+| ----------- | --------- | ---------------------------- | -------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bootstrap` | `missing` | `missing`                    | `n/a`                | `n/a`                 | No `next/` command yet. Ported to native TS in the legacy shell; the migration-push sub-step is delegated to the Go binary as a documented interim until `db push` is natively ported. |
 
 ## Project / Stack Lifecycle
 
@@ -265,7 +265,7 @@ Legend:
 | `logout`                               | `ported`      | [`../src/legacy/commands/logout/logout.command.ts`](../src/legacy/commands/logout/logout.command.ts)                                                                                      |
 | `link`                                 | `ported`      | [`../src/legacy/commands/link/link.command.ts`](../src/legacy/commands/link/link.command.ts)                                                                                              |
 | `unlink`                               | `ported`      | [`../src/legacy/commands/unlink/unlink.command.ts`](../src/legacy/commands/unlink/unlink.command.ts)                                                                                      |
-| `bootstrap`                            | `wrapped`     | [`../src/legacy/commands/bootstrap/bootstrap.command.ts`](../src/legacy/commands/bootstrap/bootstrap.command.ts)                                                                          |
+| `bootstrap`                            | `ported`      | [`../src/legacy/commands/bootstrap/bootstrap.command.ts`](../src/legacy/commands/bootstrap/bootstrap.command.ts) (native; `db push` step delegated to the Go binary — interim)            |
 | `init`                                 | `ported`      | [`../src/legacy/commands/init/init.command.ts`](../src/legacy/commands/init/init.command.ts)                                                                                              |
 | `services`                             | `wrapped`     | [`../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)                                                                                          |
diff --git a/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md
index 720d4096b6..c43ac9d168 100644
--- a/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md
+++ b/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md
@@ -1,71 +1,115 @@
 # `supabase bootstrap [template]`
 
+`bootstrap` is a meta-orchestrator: it chains a workdir prompt → template fetch/download →
+blank `init` → ensure-login → `projects create` → `projects api-keys` → `link` services →
+health poll → write `.env` → `db push` → start suggestion. Every step is native TypeScript
+**except** the migration push, which is delegated to the bundled Go binary (interim — see Notes).
+
 ## Files Read
 
-| Path                       | Format                    | When                                                       |
-| -------------------------- | ------------------------- | ---------------------------------------------------------- |
-| `~/.supabase/access-token` | plain text (token string) | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable |
+| Path                                   | Format     | When                                                        |
+| -------------------------------------- | ---------- | ----------------------------------------------------------- |
+| `~/.supabase/access-token`             | plain text | ensure-login token miss (env unset and keyring unavailable) |
+| `<workdir>/.env.example`               | dotenv     | optional; merged into the generated `.env`                  |
+| `<workdir>/supabase/.temp/project-ref` | plain text | read by the delegated `db push` subprocess (post-`chdir`)   |
 
 ## Files Written
 
-| Path                             | Format | When                                                          |
-| -------------------------------- | ------ | ------------------------------------------------------------- |
-| `<workdir>/supabase/config.toml` | TOML   | always on success; created from selected template             |
-| `<workdir>/.env`                 | env    | always on success; populated with API keys and project config |
-| `<workdir>/<template files>`     | varies | template-specific files cloned or copied from GitHub          |
+| Path                                                                                                  | Format     | When                                                       |
+| ----------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------- |
+| `<workdir>/supabase/config.toml`                                                                      | TOML       | blank/`scratch` path only (via `initProject`)              |
+| `<workdir>/<template files>`                                                                          | varies     | template path only (GitHub download)                       |
+| `<workdir>/supabase/.temp/project-ref`                                                                | plain text | always (mandatory; fails the command on write error)       |
+| `<workdir>/supabase/.temp/{pooler-url,rest-version,gotrue-version,storage-version,storage-migration}` | plain text | best-effort, from `link.LinkServices`                      |
+| `<workdir>/.env`                                                                                      | dotenv     | best-effort (write failure prints a warning and continues) |
+| `~/.supabase/<workdir-hash>/linked-project.json`                                                      | JSON       | PersistentPostRun linked-project cache (`Effect.ensuring`) |
+| `~/.supabase/telemetry.json`                                                                          | JSON       | PersistentPostRun telemetry flush (`Effect.ensuring`)      |
+
+**Process side effect:** `process.chdir(<workdir>)` mirrors Go's `ChangeWorkDir` and prints
+`Using workdir <workdir>\n` to stderr (`workdir` bolded on a TTY). The original cwd is restored
+in a finalizer so the delegated `db push` subprocess inherits the bootstrap workdir without
+leaking the change to the surrounding process.
 
 ## API Routes
 
-| Method | Path                                                      | Auth         | Request body                    | Response (used fields)                   |
-| ------ | --------------------------------------------------------- | ------------ | ------------------------------- | ---------------------------------------- |
-| `GET`  | `https://api.github.com/repos/supabase/samples/contents/` | none         | none                            | `[{name, type, ...}]` (template listing) |
-| `POST` | `/v1/projects`                                            | Bearer token | `{name, region, db_pass, plan}` | `{id, ref, ...}`                         |
-| `GET`  | `/v1/projects/{ref}/api-keys`                             | Bearer token | none                            | `[{name, api_key}]`                      |
+| Method          | Path                                                                                      | Auth                           | Notes                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------- |
+| `GET`           | `api.github.com/repos/supabase-community/supabase-samples/contents/samples.json?ref=main` | optional `Bearer GITHUB_TOKEN` | base64 `content` → `{samples:[…]}`                                                           |
+| `GET`           | `api.github.com/repos/<owner>/<repo>/contents/<path>?ref=<ref>` + raw `download_url`      | optional `Bearer GITHUB_TOKEN` | template download (BFS, concurrency 5)                                                       |
+| `GET`           | `/v1/organizations`                                                                       | Bearer                         | interactive org picker (create core)                                                         |
+| `POST`          | `/v1/projects`                                                                            | Bearer                         | `{name, organization_slug, db_pass, region?, desired_instance_size?, template_url?}` → `201` |
+| `GET`           | `/v1/projects/{ref}/api-keys`                                                             | Bearer                         | retried with exponential backoff (no `reveal`)                                               |
+| `GET`           | `/v1/projects/{ref}` + storage/pooler config + tenant version probes                      | Bearer / service key           | `link.LinkServices` (best-effort)                                                            |
+| `GET`           | `/v1/projects/{ref}/health?services=db`                                                   | Bearer                         | retried with exponential backoff                                                             |
+| login endpoints | —                                                                                         | —                              | ensure-login browser flow (token miss)                                                       |
+| db push routes  | —                                                                                         | —                              | fired by the **Go subprocess** (interim)                                                     |
 
 ## Environment Variables
 
-| Variable                | Purpose                                              | Required?                                               |
-| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
-| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) |
-| `SUPABASE_API_URL`      | override Management API base URL                     | no (defaults to `https://api.supabase.com`)             |
-| `WORKDIR`               | target directory for bootstrapping                   | no (prompts interactively if not set)                   |
-| `DB_PASSWORD`           | database password (bound from `--password` flag)     | no (generated if not provided)                          |
+| Variable                               | Purpose                                            | Required? |
+| -------------------------------------- | -------------------------------------------------- | --------- |
+| `SUPABASE_WORKDIR`                     | target dir (`--workdir` flag → env → prompt → cwd) | no        |
+| `SUPABASE_DB_PASSWORD`                 | DB password (`-p` flag → env → prompt/generate)    | no        |
+| `GITHUB_TOKEN`                         | raise the GitHub API rate limit for template fetch | no        |
+| `SUPABASE_ACCESS_TOKEN`                | auth bypass for ensure-login                       | no        |
+| `SUPABASE_API_URL`, `SUPABASE_PROFILE` | API host / profile                                 | no        |
 
 ## Exit Codes
 
-| Code | Condition                                                         |
-| ---- | ----------------------------------------------------------------- |
-| `0`  | success — project created, files written, start command suggested |
-| `1`  | invalid template name provided as argument                        |
-| `1`  | GitHub API unavailable for template listing                       |
-| `1`  | authentication error — no valid token found for project creation  |
-| `1`  | project creation failure (API error)                              |
-| `1`  | network / connection failure                                      |
+| Code | Condition                                                                                                                                                                                                                                                                                                                                      |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success                                                                                                                                                                                                                                                                                                                                        |
+| `1`  | invalid template arg; overwrite declined (`context canceled`); template list/download failure; login failure; create failure; api-keys exhausted; health unhealthy / error status; db-push subprocess non-zero exit; any network failure. The `.env` derive/write is **non-fatal** (prints `Failed to create .env file: <err>` and continues). |
 
-## Output
+## Telemetry
 
-### `--output-format text` (Go CLI compatible)
+- `cli_command_executed` — once (via `withLegacyCommandInstrumentation`).
+- `cli_login_completed` — once, **only** on the browser-login path (token miss).
+- **No `cli_project_linked`** — Go's `bootstrap` calls `link.LinkServices` (services only), **not**
+  `link.Run`, so it deliberately skips the project-linked telemetry, status check, and the
+  `linked-project.json` temp write that the standalone `link` command performs.
+- `create` fires no custom event.
+- db-push events are emitted by the **Go subprocess**, not the TS shell.
 
-Interactive prompts for working directory and template selection (if not provided). On success, prints project details and suggested start command:
+## Output
 
-```
-To start your app:
-  <start command>
-```
+### `--output-format text` (Go-compatible)
 
-### `--output-format json`
+stderr progress only: `Using workdir …`, `Created a new project at …`, `Linking project…`,
+`Checking project health…`, and the final `To start your app:` suggestion (Aqua command lines).
+`Downloading: <url>` goes to stdout (text mode only). The `create` sub-step also echoes the new
+project per `-o` (`pretty|json|yaml|toml|env`); bootstrap adds no `-o` output of its own.
 
-Not applicable — bootstrap is an interactive command.
+### `--output-format json` / `stream-json`
 
-### `--output-format stream-json`
+Human banners are suppressed; a single structured result is emitted:
 
-Not applicable — bootstrap is an interactive command.
+```json
+{
+  "workdir": "…",
+  "project_ref": "…",
+  "template": "scratch",
+  "start_command": "supabase start",
+  "env_file": "…/.env"
+}
+```
 
 ## Notes
 
-- Accepts an optional positional `[template]` argument to skip template selection prompt.
-- Without `WORKDIR`, prompts the user to enter a directory (defaulting to `CurrentDirAbs`).
-- Templates are fetched from `https://api.github.com/repos/supabase/samples/contents/`.
-- A "scratch" (empty) template is always available as fallback without GitHub access.
-- The `--password` flag sets the database password, bound to `DB_PASSWORD` viper key.
-- On success, the Go CLI prints a suggestion like `To start your app: supabase start`.
+- **Interim Go-proxy delegation for migration push.** The push step shells out to the bundled
+  Go binary (`db push --include-roles --include-seed [--password …]`) until `db push` gets its
+  own native port (separate Linear issue). The sub-step is **not** instrumentation-wrapped (the
+  subprocess fires its own push telemetry). Known divergence: `LegacyGoProxy.exec` propagates the
+  exit code, so Go's push backoff is **not** reproduced (single attempt) — to be restored when
+  `db push` is natively ported. (`LegacyGoProxy.exec` exits the process on a non-zero exit rather
+  than returning a failure, so the step cannot be wrapped in `Effect.retry`.)
+- **Interim credential exposure.** Because the push step runs in a subprocess, the DB password is
+  passed as `--password <value>` and is therefore briefly visible in the OS process table for the
+  lifetime of that subprocess (Go runs `push.Run` in-process and never exposes it). The same
+  password is already written in plaintext to `<workdir>/.env` in the same directory, so the
+  incremental exposure is small; it is eliminated when `db push` is natively ported (no subprocess).
+- The api-keys and health retries use exponential backoff (3s initial, 8 retries), matching Go's
+  `utils.NewBackoffPolicy`. The per-attempt `Linking project…` / `Checking project health…` lines
+  are reproduced; Go's debug-only `Retry (n/8):` notifier is not.
+- `Downloading:` / progress banners are gated to text mode to keep machine stdout payload-only
+  (CLI-1546).
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.command.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.command.ts
index 3ecda8bcc8..ed0aa608e0 100644
--- a/apps/cli/src/legacy/commands/bootstrap/bootstrap.command.ts
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.command.ts
@@ -1,5 +1,9 @@
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";
+
+import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts";
+import { withLegacyCommandInstrumentation } from "../../telemetry/legacy-command-instrumentation.ts";
+import { legacyBootstrapRuntimeLayer } from "./bootstrap.layers.ts";
 import { legacyBootstrap } from "./bootstrap.handler.ts";
 
 const config = {
@@ -19,5 +23,9 @@ export type LegacyBootstrapFlags = CliCommand.Command.Config.Infer<typeof config
 export const legacyBootstrapCommand = Command.make("bootstrap", config).pipe(
   Command.withDescription("Bootstrap a Supabase project from a starter template."),
   Command.withShortDescription("Bootstrap a Supabase project from a starter template"),
-  Command.withHandler((flags) => legacyBootstrap(flags)),
+  Command.withHandler((flags) =>
+    // Go marks no bootstrap flag `markFlagTelemetrySafe`, so no `safeFlags`.
+    legacyBootstrap(flags).pipe(withLegacyCommandInstrumentation({ flags }), withJsonErrorHandling),
+  ),
+  Command.provide(legacyBootstrapRuntimeLayer),
 );
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.ts
new file mode 100644
index 0000000000..eff232709e
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.ts
@@ -0,0 +1,174 @@
+import type { ApiKeyResponse } from "@supabase/api/effect";
+
+import { apiKeysToEnv } from "../../shared/legacy-api-keys.format.ts";
+import { type LegacyDbConfig, toPostgresUrl } from "./bootstrap.pgconfig.ts";
+
+type ApiKey = typeof ApiKeyResponse.Type;
+
+// Env-var keys bootstrap writes / derives. Mirrors the constants in
+// `apps/cli-go/internal/bootstrap/bootstrap.go:131-150`.
+const SUPABASE_SERVICE_ROLE_KEY = "SUPABASE_SERVICE_ROLE_KEY";
+const SUPABASE_ANON_KEY = "SUPABASE_ANON_KEY";
+const SUPABASE_URL = "SUPABASE_URL";
+const POSTGRES_URL = "POSTGRES_URL";
+// Derived keys (only populated when present in .env.example).
+const POSTGRES_PRISMA_URL = "POSTGRES_PRISMA_URL";
+const POSTGRES_URL_NON_POOLING = "POSTGRES_URL_NON_POOLING";
+const POSTGRES_USER = "POSTGRES_USER";
+const POSTGRES_HOST = "POSTGRES_HOST";
+const POSTGRES_PASSWORD = "POSTGRES_PASSWORD";
+const POSTGRES_DATABASE = "POSTGRES_DATABASE";
+const NEXT_PUBLIC_SUPABASE_ANON_KEY = "NEXT_PUBLIC_SUPABASE_ANON_KEY";
+const NEXT_PUBLIC_SUPABASE_URL = "NEXT_PUBLIC_SUPABASE_URL";
+const EXPO_PUBLIC_SUPABASE_ANON_KEY = "EXPO_PUBLIC_SUPABASE_ANON_KEY";
+const EXPO_PUBLIC_SUPABASE_URL = "EXPO_PUBLIC_SUPABASE_URL";
+
+/**
+ * Reproduces Go's `writeDotEnv` env-map construction (`bootstrap.go:166-243`).
+ *
+ * Seeds the api-key env vars (`SUPABASE_<NAME>_KEY`), the project `SUPABASE_URL`,
+ * and the pooled `POSTGRES_URL` (transaction mode, port 6543). When a `.env.example`
+ * map is supplied, each of its keys is merged via Go's switch: the four seeded keys
+ * are preserved, the derived `POSTGRES_*` / `NEXT_PUBLIC_*` / `EXPO_PUBLIC_*` keys are
+ * computed from the db config + seeded values, and any other key copies its example
+ * value verbatim.
+ */
+export function buildDotEnv(
+  keys: ReadonlyArray<ApiKey>,
+  config: LegacyDbConfig,
+  supabaseUrl: string,
+  example: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  const initial = apiKeysToEnv(keys);
+  initial[SUPABASE_URL] = supabaseUrl;
+  initial[POSTGRES_URL] = toPostgresUrl({ ...config, port: 6543 });
+
+  if (example === undefined) {
+    return initial;
+  }
+
+  for (const [key, value] of Object.entries(example)) {
+    switch (key) {
+      // Seeded keys win over any example value.
+      case SUPABASE_SERVICE_ROLE_KEY:
+      case SUPABASE_ANON_KEY:
+      case SUPABASE_URL:
+      case POSTGRES_URL:
+        break;
+      case POSTGRES_PRISMA_URL:
+        initial[key] = initial[POSTGRES_URL] ?? "";
+        break;
+      case POSTGRES_URL_NON_POOLING:
+        initial[key] = toPostgresUrl(config);
+        break;
+      case POSTGRES_USER:
+        initial[key] = config.user;
+        break;
+      case POSTGRES_HOST:
+        initial[key] = config.host;
+        break;
+      case POSTGRES_PASSWORD:
+        initial[key] = config.password;
+        break;
+      case POSTGRES_DATABASE:
+        initial[key] = config.database;
+        break;
+      case NEXT_PUBLIC_SUPABASE_ANON_KEY:
+      case EXPO_PUBLIC_SUPABASE_ANON_KEY:
+        initial[key] = initial[SUPABASE_ANON_KEY] ?? "";
+        break;
+      case NEXT_PUBLIC_SUPABASE_URL:
+      case EXPO_PUBLIC_SUPABASE_URL:
+        initial[key] = initial[SUPABASE_URL] ?? "";
+        break;
+      default:
+        initial[key] = value;
+    }
+  }
+  return initial;
+}
+
+// godotenv's `doubleQuoteSpecialChars` (`joho/godotenv/godotenv.go`): backslash,
+// newline, carriage return, double-quote, `!`, `$`, backtick.
+const DOUBLE_QUOTE_SPECIAL = ["\\", "\n", "\r", '"', "!", "$", "`"] as const;
+
+function doubleQuoteEscape(line: string): string {
+  let out = line;
+  for (const char of DOUBLE_QUOTE_SPECIAL) {
+    const replacement = char === "\n" ? "\\n" : char === "\r" ? "\\r" : `\\${char}`;
+    out = out.replaceAll(char, replacement);
+  }
+  return out;
+}
+
+// strconv.Atoi surface: optional sign + base-10 digits, parsed within int range.
+const INTEGER_PATTERN = /^[+-]?\d+$/;
+
+/**
+ * Reproduces `godotenv.Marshal`: each entry renders as `KEY=<int>` when the value
+ * parses as an integer (Go's `strconv.Atoi` + `%d`), otherwise `KEY="<escaped>"`.
+ * Lines are sorted lexicographically (Go sorts the rendered lines, which orders
+ * by key) and joined with `\n` (no trailing newline).
+ */
+export function marshalDotEnv(env: Readonly<Record<string, string>>): string {
+  const lines: Array<string> = [];
+  for (const [key, value] of Object.entries(env)) {
+    if (INTEGER_PATTERN.test(value)) {
+      const parsed = Number(value);
+      if (Number.isSafeInteger(parsed)) {
+        lines.push(`${key}=${parsed}`);
+        continue;
+      }
+    }
+    lines.push(`${key}="${doubleQuoteEscape(value)}"`);
+  }
+  lines.sort();
+  return lines.join("\n");
+}
+
+// godotenv.Parse-compatible enough for `.env.example`: `KEY=VALUE` / `KEY="VALUE"`
+// lines, `#` comments, blank lines. A line with an empty / invalid variable name
+// throws (Go's `godotenv.Parse` surfaces `unexpected character ... in variable name`).
+const EXPORT_PREFIX = /^\s*export\s+/;
+
+/**
+ * Minimal godotenv parser for `.env.example`. Returns the parsed key/value map.
+ * Throws an `Error` whose message mirrors Go's parser for a malformed variable
+ * name so the caller can surface the same failure (`"!="` → unexpected character).
+ */
+export function parseDotEnv(contents: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const rawLine of contents.split("\n")) {
+    const line = rawLine.replace(EXPORT_PREFIX, "").trim();
+    if (line.length === 0 || line.startsWith("#")) {
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq <= 0) {
+      const offending = line.slice(0, eq < 0 ? line.length : eq + 1);
+      throw new Error(
+        `unexpected character "${line[0] ?? ""}" in variable name near "${offending}"`,
+      );
+    }
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(key)) {
+      throw new Error(`unexpected character "${key[0] ?? ""}" in variable name near "${line}"`);
+    }
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+      // godotenv expands escapes inside double-quoted values: `\n` / `\r` become
+      // real newlines, and a backslash before any other char (except `$`) is
+      // dropped (`\"` -> `"`, `\\` -> `\`).
+      value = value
+        .slice(1, -1)
+        .replaceAll("\\n", "\n")
+        .replaceAll("\\r", "\r")
+        .replace(/\\([^$])/g, "$1");
+    } else if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+      // Single-quoted values are taken literally (no escape expansion).
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+  return result;
+}
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.unit.test.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.unit.test.ts
new file mode 100644
index 0000000000..a4c8b16a4a
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.dotenv.unit.test.ts
@@ -0,0 +1,121 @@
+import type { ApiKeyResponse } from "@supabase/api/effect";
+import { describe, expect, it } from "vitest";
+
+import { buildDotEnv, marshalDotEnv, parseDotEnv } from "./bootstrap.dotenv.ts";
+import type { LegacyDbConfig } from "./bootstrap.pgconfig.ts";
+
+type ApiKey = typeof ApiKeyResponse.Type;
+
+// Mirrors Go's `bootstrap_test.go::TestWriteEnv` fixtures.
+const API_KEYS: ReadonlyArray<ApiKey> = [
+  { name: "anon", api_key: "anonkey" },
+  { name: "service_role", api_key: "servicekey" },
+];
+
+const DB_CONFIG: LegacyDbConfig = {
+  host: "db.supabase.co",
+  port: 5432,
+  user: "admin",
+  password: "password",
+  database: "postgres",
+};
+
+const SUPABASE_URL = "https://testing.supabase.co";
+
+describe("buildDotEnv + marshalDotEnv", () => {
+  it("writes the api keys, project URL and pooled POSTGRES_URL", () => {
+    const env = buildDotEnv(API_KEYS, DB_CONFIG, SUPABASE_URL, undefined);
+    expect(marshalDotEnv(env)).toBe(
+      `POSTGRES_URL="postgresql://admin:password@db.supabase.co:6543/postgres?connect_timeout=10"
+SUPABASE_ANON_KEY="anonkey"
+SUPABASE_SERVICE_ROLE_KEY="servicekey"
+SUPABASE_URL="https://testing.supabase.co"`,
+    );
+  });
+
+  it("merges the derived keys from a .env.example (every switch branch)", () => {
+    const example: Record<string, string> = {
+      POSTGRES_PRISMA_URL: "example",
+      POSTGRES_URL_NON_POOLING: "example",
+      POSTGRES_USER: "example",
+      POSTGRES_HOST: "example",
+      POSTGRES_PASSWORD: "example",
+      POSTGRES_DATABASE: "example",
+      NEXT_PUBLIC_SUPABASE_ANON_KEY: "example",
+      NEXT_PUBLIC_SUPABASE_URL: "example",
+      no_match: "example",
+      SUPABASE_SERVICE_ROLE_KEY: "example",
+      SUPABASE_ANON_KEY: "example",
+      SUPABASE_URL: "example",
+      POSTGRES_URL: "example",
+    };
+    const env = buildDotEnv(API_KEYS, DB_CONFIG, SUPABASE_URL, example);
+    expect(marshalDotEnv(env)).toBe(
+      `NEXT_PUBLIC_SUPABASE_ANON_KEY="anonkey"
+NEXT_PUBLIC_SUPABASE_URL="https://testing.supabase.co"
+POSTGRES_DATABASE="postgres"
+POSTGRES_HOST="db.supabase.co"
+POSTGRES_PASSWORD="password"
+POSTGRES_PRISMA_URL="postgresql://admin:password@db.supabase.co:6543/postgres?connect_timeout=10"
+POSTGRES_URL="postgresql://admin:password@db.supabase.co:6543/postgres?connect_timeout=10"
+POSTGRES_URL_NON_POOLING="postgresql://admin:password@db.supabase.co:5432/postgres?connect_timeout=10"
+POSTGRES_USER="admin"
+SUPABASE_ANON_KEY="anonkey"
+SUPABASE_SERVICE_ROLE_KEY="servicekey"
+SUPABASE_URL="https://testing.supabase.co"
+no_match="example"`,
+    );
+  });
+
+  it("mirrors the EXPO_PUBLIC_* keys to the anon key and project URL", () => {
+    const env = buildDotEnv(API_KEYS, DB_CONFIG, SUPABASE_URL, {
+      EXPO_PUBLIC_SUPABASE_ANON_KEY: "example",
+      EXPO_PUBLIC_SUPABASE_URL: "example",
+    });
+    expect(env["EXPO_PUBLIC_SUPABASE_ANON_KEY"]).toBe("anonkey");
+    expect(env["EXPO_PUBLIC_SUPABASE_URL"]).toBe(SUPABASE_URL);
+  });
+
+  it("masks a nullable-null api key as ******", () => {
+    const env = buildDotEnv(
+      [{ name: "service_role", api_key: null }],
+      DB_CONFIG,
+      SUPABASE_URL,
+      undefined,
+    );
+    expect(env["SUPABASE_SERVICE_ROLE_KEY"]).toBe("******");
+  });
+});
+
+describe("marshalDotEnv", () => {
+  it("emits integer-valued entries unquoted and escapes special characters", () => {
+    expect(marshalDotEnv({ COUNT: "42", PATH: 'a"b\\c', NOTE: "hi!" })).toBe(
+      `COUNT=42\nNOTE="hi\\!"\nPATH="a\\"b\\\\c"`,
+    );
+  });
+});
+
+describe("parseDotEnv", () => {
+  it("parses KEY=VALUE lines, skipping comments and blanks, and strips quotes", () => {
+    expect(parseDotEnv('# comment\nFOO=bar\n\nBAZ="quoted"\nexport QUX=1')).toEqual({
+      FOO: "bar",
+      BAZ: "quoted",
+      QUX: "1",
+    });
+  });
+
+  it("expands escape sequences in double-quoted values (godotenv parity)", () => {
+    expect(parseDotEnv('A="line1\\nline2"\nB="a\\"b\\\\c"')).toEqual({
+      A: "line1\nline2",
+      B: 'a"b\\c',
+    });
+  });
+
+  it("takes single-quoted values literally (no escape expansion)", () => {
+    expect(parseDotEnv("A='line1\\nline2'")).toEqual({ A: "line1\\nline2" });
+  });
+
+  it("throws Go's 'unexpected character' error on a malformed variable name", () => {
+    expect(() => parseDotEnv("!=")).toThrow(/unexpected character "!" in variable name/);
+  });
+});
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.errors.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.errors.ts
new file mode 100644
index 0000000000..95896f9b6f
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.errors.ts
@@ -0,0 +1,54 @@
+import { Data } from "effect";
+
+// ---------------------------------------------------------------------------
+// Bootstrap-specific tagged errors. Each maps to a Go `errors.New` / failure
+// site in `apps/cli-go/cmd/bootstrap.go` + `internal/bootstrap/bootstrap.go`.
+// Login / create / api-keys / link failures are surfaced by the extracted
+// shared cores (`legacy/shared/legacy-*`), so they are NOT redefined here.
+// ---------------------------------------------------------------------------
+
+/** Positional template arg with no case-insensitive match — Go's `"Invalid template: " + name` (`cmd/bootstrap.go:48`). */
+export class LegacyBootstrapInvalidTemplateError extends Data.TaggedError(
+  "LegacyBootstrapInvalidTemplateError",
+)<{
+  readonly message: string;
+}> {}
+
+/** GitHub samples listing failure — Go's `failed to list samples` (`bootstrap.go:ListSamples`). */
+export class LegacyBootstrapTemplateListError extends Data.TaggedError(
+  "LegacyBootstrapTemplateListError",
+)<{
+  readonly message: string;
+}> {}
+
+/** Reading the target workdir failed — Go's `failed to read workdir: %w` (`bootstrap.go:44`). */
+export class LegacyBootstrapWorkdirReadError extends Data.TaggedError(
+  "LegacyBootstrapWorkdirReadError",
+)<{
+  readonly message: string;
+}> {}
+
+/**
+ * User declined the overwrite prompt — Go returns `errors.New(context.Canceled)`
+ * (`bootstrap.go:51`). Carries no suggestion frame (cancellation, not a fault).
+ */
+export class LegacyBootstrapOverwriteDeclinedError extends Data.TaggedError(
+  "LegacyBootstrapOverwriteDeclinedError",
+)<{
+  readonly message: string;
+}> {}
+
+/** Template download failure — Go's `failed to download template: %w` (`bootstrap.go:downloadSample`). */
+export class LegacyBootstrapTemplateDownloadError extends Data.TaggedError(
+  "LegacyBootstrapTemplateDownloadError",
+)<{
+  readonly message: string;
+}> {}
+
+/**
+ * Project health probe failed — Go's `Error status %d: %s` (non-200) or
+ * `Service not healthy: %s (%s)` (`bootstrap.go:checkProjectHealth`).
+ */
+export class LegacyBootstrapHealthError extends Data.TaggedError("LegacyBootstrapHealthError")<{
+  readonly message: string;
+}> {}
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts
index fb30b24e01..2bae1c1c9f 100644
--- a/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts
@@ -1,13 +1,297 @@
-import { Effect, Option } from "effect";
+import { Effect, FileSystem, Option, Path, Schedule } from "effect";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
+
+import { LegacyPlatformApi } from "../../auth/legacy-platform-api.service.ts";
+import { LegacyCliConfig } from "../../config/legacy-cli-config.service.ts";
+import { LegacyLinkedProjectCache } from "../../telemetry/legacy-linked-project-cache.service.ts";
+import { LegacyTelemetryState } from "../../telemetry/legacy-telemetry-state.service.ts";
+import { LegacyWorkdirFlag, LegacyYesFlag } from "../../../shared/legacy/global-flags.ts";
+import { Output } from "../../../shared/output/output.service.ts";
 import { LegacyGoProxy } from "../../../shared/legacy/go-proxy.service.ts";
+import { RuntimeInfo } from "../../../shared/runtime/runtime-info.service.ts";
+import { Tty } from "../../../shared/runtime/tty.service.ts";
+import { legacyAqua, legacyBold } from "../../shared/legacy-colors.ts";
+import { legacyEnsureLogin } from "../../shared/legacy-ensure-login.ts";
+import { legacyGetProjectApiKeys } from "../../shared/legacy-get-api-keys.ts";
+import { sanitizeLegacyErrorBody } from "../../shared/legacy-http-errors.ts";
+import { legacyLinkServicesCore } from "../../shared/legacy-link-services-core.ts";
+import { legacyProjectCreateCore } from "../../shared/legacy-project-create-core.ts";
+import { legacyTempPaths } from "../../shared/legacy-temp-paths.ts";
+import { legacyExtractServiceKeys } from "../../shared/legacy-tenant-keys.ts";
+import { initProject } from "../../../shared/init/project-init.ts";
+import { buildDotEnv, marshalDotEnv, parseDotEnv } from "./bootstrap.dotenv.ts";
+import {
+  LegacyBootstrapHealthError,
+  LegacyBootstrapInvalidTemplateError,
+  LegacyBootstrapOverwriteDeclinedError,
+  LegacyBootstrapWorkdirReadError,
+} from "./bootstrap.errors.ts";
+import { deriveDbConfig } from "./bootstrap.pgconfig.ts";
+import { suggestAppStart } from "./bootstrap.suggest.ts";
+import { type LegacyStarterTemplate, LegacyTemplateService } from "./bootstrap.templates.ts";
 import type { LegacyBootstrapFlags } from "./bootstrap.command.ts";
 
+// Go's built-in starter (`cmd/bootstrap.go:17-21`).
+const SCRATCH_TEMPLATE: LegacyStarterTemplate = {
+  name: "scratch",
+  description: "An empty project from scratch.",
+  url: "",
+  start: "supabase start",
+};
+
+// Go's `utils.NewBackoffPolicy`: exponential backoff, 3s initial interval,
+// `maxRetries = 8` (`internal/utils/retry.go`). Injectable so tests run fast.
+const LEGACY_BOOTSTRAP_MAX_RETRIES = 8;
+const legacyBootstrapBackoff = Schedule.exponential("3 seconds");
+
 export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
   flags: LegacyBootstrapFlags,
+  retrySchedule: typeof legacyBootstrapBackoff = legacyBootstrapBackoff,
 ) {
+  const output = yield* Output;
+  const tty = yield* Tty;
+  const runtimeInfo = yield* RuntimeInfo;
+  const cliConfig = yield* LegacyCliConfig;
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const templateService = yield* LegacyTemplateService;
   const proxy = yield* LegacyGoProxy;
-  const args: string[] = ["bootstrap"];
-  if (Option.isSome(flags.template)) args.push(flags.template.value);
-  if (Option.isSome(flags.password)) args.push("--password", flags.password.value);
-  yield* proxy.exec(args);
+  const api = yield* LegacyPlatformApi;
+  const linkedProjectCache = yield* LegacyLinkedProjectCache;
+  const telemetryState = yield* LegacyTelemetryState;
+  const workdirFlag = yield* LegacyWorkdirFlag;
+  const yesFlag = yield* LegacyYesFlag;
+
+  const isText = output.format === "text";
+  const retry = { schedule: retrySchedule, times: LEGACY_BOOTSTRAP_MAX_RETRIES } as const;
+
+  // `process.chdir` mirrors Go's `ChangeWorkDir`; restore the original cwd in a
+  // finalizer so the (mocked) proxy step still inherits the bootstrap workdir
+  // while leaving the surrounding process untouched.
+  const originalCwd = process.cwd();
+  let createdRef: string | undefined;
+
+  yield* Effect.gen(function* () {
+    // A. Resolve workdir (flag -> env -> prompt -> cwd). `bootstrap.go:30-40`.
+    // Go's viper uses `SetEnvPrefix("SUPABASE")`, so `viper.IsSet("WORKDIR")` reads
+    // the prefixed `SUPABASE_WORKDIR` only (never plain `WORKDIR`).
+    const workdirRaw = Option.isSome(workdirFlag)
+      ? workdirFlag.value
+      : process.env["SUPABASE_WORKDIR"];
+    const workdirInput =
+      workdirRaw ??
+      (yield* output.promptText(
+        `Enter a directory to bootstrap your project (or leave blank to use ${legacyBold(
+          runtimeInfo.cwd,
+        )}): `,
+      ));
+    const workdir = path.isAbsolute(workdirInput)
+      ? workdirInput
+      : path.join(runtimeInfo.cwd, workdirInput);
+
+    // B. List templates + resolve the starter. `bootstrap.go:38-58` / `cmd:25-58`.
+    const samples = yield* templateService.listSamples;
+    const allTemplates = [...samples, SCRATCH_TEMPLATE];
+    let starter: LegacyStarterTemplate;
+    if (Option.isSome(flags.template)) {
+      const name = flags.template.value;
+      const match = allTemplates.find((t) => t.name.toLowerCase() === name.toLowerCase());
+      if (match === undefined) {
+        return yield* new LegacyBootstrapInvalidTemplateError({
+          message: `Invalid template: ${name}`,
+        });
+      }
+      starter = match;
+    } else {
+      const choice = yield* output.promptSelect(
+        "Which starter template do you want to use?",
+        allTemplates.map((t) => ({ value: t.name, label: t.name, hint: t.description })),
+      );
+      starter = allTemplates.find((t) => t.name === choice) ?? SCRATCH_TEMPLATE;
+    }
+
+    // C. mkdir + overwrite prompt. `bootstrap.go:41-53`.
+    yield* fs.makeDirectory(workdir, { recursive: true });
+    const entries = yield* fs
+      .readDirectory(workdir)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new LegacyBootstrapWorkdirReadError({ message: `failed to read workdir: ${cause}` }),
+        ),
+      );
+    if (entries.length > 0) {
+      const overwrite = yesFlag
+        ? true
+        : yield* output.promptConfirm(
+            `Do you want to overwrite existing files in ${legacyBold(workdir)} directory?`,
+            { defaultValue: true },
+          );
+      if (!overwrite) {
+        return yield* new LegacyBootstrapOverwriteDeclinedError({ message: "context canceled" });
+      }
+    }
+
+    // D. chdir + "Using workdir" to stderr. `bootstrap.go:54` + `misc.go:240-247`.
+    // Go only prints the line when the resolved workdir differs from the original
+    // cwd (`cwd != CurrentDirAbs`); match that guard.
+    yield* Effect.sync(() => process.chdir(workdir));
+    if (workdir !== runtimeInfo.cwd) {
+      yield* output.raw(`Using workdir ${legacyBold(workdir)}\n`, "stderr");
+    }
+
+    // E. Download template OR scaffold a blank project. `bootstrap.go:57-65`.
+    if (starter.url.length > 0) {
+      if (isText) yield* output.raw(`Downloading: ${starter.url}\n`, "stdout");
+      yield* templateService.download(starter.url, workdir);
+    } else {
+      yield* initProject({
+        cwd: workdir,
+        force: true,
+        interactive: false,
+        useOrioledb: false,
+        withVscodeSettings: false,
+        withIntellijSettings: false,
+      });
+    }
+
+    // F. Ensure login (browser flow when no token). `bootstrap.go:66-77`.
+    yield* legacyEnsureLogin({ openBrowser: tty.stdinIsTty });
+
+    // G. Create project (echoes via the shared create core). `bootstrap.go:78-87`.
+    // Go binds `-p` to viper `DB_PASSWORD`; with the `SUPABASE` env prefix the env
+    // fallback is `SUPABASE_DB_PASSWORD` (consumed by `flags.PromptPassword`).
+    const seededPassword = Option.isSome(flags.password)
+      ? flags.password.value
+      : (process.env["SUPABASE_DB_PASSWORD"] ?? "");
+    const created = yield* legacyProjectCreateCore({
+      name: path.basename(workdir),
+      orgId: "",
+      dbPassword: seededPassword,
+      region: undefined,
+      size: undefined,
+      templateUrl: starter.url.length > 0 ? starter.url : undefined,
+      emitStructuredResult: false,
+    });
+    const projectRef = created.ref;
+    createdRef = projectRef.length > 0 ? projectRef : undefined;
+
+    // H. Fetch api keys with backoff; each attempt prints "Linking project...".
+    // `bootstrap.go:88-97`.
+    const keys = yield* Effect.gen(function* () {
+      if (isText) yield* output.raw("Linking project...\n", "stderr");
+      return yield* legacyGetProjectApiKeys(projectRef);
+    }).pipe(Effect.retry(retry));
+    const { anon } = legacyExtractServiceKeys(keys);
+
+    // I. Link services (best-effort, anon key) + mandatory project-ref write.
+    // `bootstrap.go:98-105`. Go calls `link.LinkServices` (no telemetry / status).
+    yield* legacyLinkServicesCore({
+      ref: projectRef,
+      serviceKey: anon,
+      skipPooler: false,
+      workdir,
+    });
+    const paths = legacyTempPaths(path, workdir);
+    yield* fs.makeDirectory(path.dirname(paths.projectRef), { recursive: true });
+    yield* fs.writeFileString(paths.projectRef, projectRef);
+
+    // J. Poll health until db is healthy. `bootstrap.go:106-113`.
+    yield* Effect.gen(function* () {
+      if (isText) yield* output.raw("Checking project health...\n", "stderr");
+      const services = yield* api.v1
+        .getServicesHealth({ ref: projectRef, services: ["db"] })
+        .pipe(Effect.catch(mapHealthError));
+      for (const service of services) {
+        if (!service.healthy) {
+          return yield* new LegacyBootstrapHealthError({
+            message: `Service not healthy: ${service.name} (${service.status})`,
+          });
+        }
+      }
+    }).pipe(Effect.retry(retry));
+
+    // K. Derive db config + write .env (non-fatal). `bootstrap.go:114-121`.
+    const dbConfig = deriveDbConfig(projectRef, created.dbPassword, cliConfig.projectHost);
+    const supabaseUrl = `https://${projectRef}.${cliConfig.projectHost}`;
+    const envFilePath = path.join(workdir, ".env");
+    let envFileWritten = true;
+    yield* Effect.gen(function* () {
+      const examplePath = path.join(workdir, ".env.example");
+      const hasExample = yield* fs.exists(examplePath);
+      let example: Record<string, string> | undefined;
+      if (hasExample) {
+        const content = yield* fs.readFileString(examplePath);
+        example = yield* Effect.try({
+          try: () => parseDotEnv(content),
+          catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+        });
+      }
+      const env = buildDotEnv(keys, dbConfig, supabaseUrl, example);
+      yield* fs.writeFileString(envFilePath, marshalDotEnv(env));
+    }).pipe(
+      Effect.catch((cause) =>
+        Effect.gen(function* () {
+          envFileWritten = false;
+          yield* output.raw(
+            `Failed to create .env file: ${cause instanceof Error ? cause.message : String(cause)}\n`,
+            "stderr",
+          );
+        }),
+      ),
+    );
+
+    // L. Push migrations — DELEGATED to the Go binary (interim; see SIDE_EFFECTS.md).
+    // No instrumentation wrap: the subprocess fires its own push telemetry.
+    // `bootstrap.go:122-127` -> push.Run(..., includeRoles, includeSeed) =>
+    // `--include-roles --include-seed` (no `--include-all`).
+    const pushArgs = ["db", "push", "--include-roles", "--include-seed"];
+    if (created.dbPassword.length > 0) pushArgs.push("--password", created.dbPassword);
+    yield* proxy.exec(pushArgs);
+
+    // M. Start suggestion. `bootstrap.go:128-130`.
+    if (isText) {
+      const suggestion = suggestAppStart(runtimeInfo.cwd, workdir, starter.start, legacyAqua);
+      yield* output.raw(`${suggestion}\n`, "stderr");
+    } else {
+      yield* output.success("", {
+        workdir,
+        project_ref: projectRef,
+        template: starter.name,
+        start_command: starter.start,
+        env_file: envFileWritten ? envFilePath : null,
+      });
+    }
+  }).pipe(
+    Effect.ensuring(
+      Effect.sync(() => {
+        try {
+          process.chdir(originalCwd);
+        } catch {
+          /* original cwd vanished — nothing to restore to */
+        }
+      }),
+    ),
+    Effect.ensuring(
+      Effect.suspend(() =>
+        createdRef === undefined ? Effect.void : linkedProjectCache.cache(createdRef),
+      ),
+    ),
+    Effect.ensuring(telemetryState.flush),
+  );
 });
+
+// Mirrors Go's `checkProjectHealth` non-200 branch: `Error status %d: %s`.
+const mapHealthError = (cause: unknown): Effect.Effect<never, LegacyBootstrapHealthError> => {
+  if (HttpClientError.isHttpClientError(cause) && cause.response !== undefined) {
+    const status = cause.response.status;
+    return cause.response.text.pipe(
+      Effect.orElseSucceed(() => ""),
+      Effect.map(sanitizeLegacyErrorBody),
+      Effect.flatMap((body) =>
+        Effect.fail(new LegacyBootstrapHealthError({ message: `Error status ${status}: ${body}` })),
+      ),
+    );
+  }
+  return Effect.fail(new LegacyBootstrapHealthError({ message: `Error status 0: ${cause}` }));
+};
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts
new file mode 100644
index 0000000000..46cf3e2b54
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts
@@ -0,0 +1,449 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { BunServices } from "@effect/platform-bun";
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Exit, Layer, Option, Schedule } from "effect";
+
+import {
+  mockAnalytics,
+  mockBrowser,
+  mockOutput,
+  mockRuntimeInfo,
+  mockStdin,
+  mockTty,
+} from "../../../../tests/helpers/mocks.ts";
+import {
+  type LegacyApiHandler,
+  LEGACY_VALID_REF,
+  legacyJsonResponse,
+  mockLegacyCliConfig,
+  mockLegacyCredentialsTracked,
+  mockLegacyLinkedProjectCacheTracked,
+  mockLegacyLoginApi,
+  mockLegacyLoginCrypto,
+  mockLegacyPlatformApi,
+  mockLegacyTelemetryStateTracked,
+  useLegacyTempWorkdir,
+} from "../../../../tests/helpers/legacy-mocks.ts";
+import {
+  LegacyWorkdirFlag,
+  LegacyYesFlag,
+  LegacyOutputFlag,
+} from "../../../shared/legacy/global-flags.ts";
+import { LegacyGoProxy } from "../../../shared/legacy/go-proxy.service.ts";
+import { LegacyTemplateService, type LegacyStarterTemplate } from "./bootstrap.templates.ts";
+import { legacyBootstrap } from "./bootstrap.handler.ts";
+import type { LegacyBootstrapFlags } from "./bootstrap.command.ts";
+
+const FAST_BACKOFF = Schedule.exponential("1 milli");
+
+const CREATED = {
+  id: LEGACY_VALID_REF,
+  ref: LEGACY_VALID_REF,
+  organization_id: "org-1",
+  organization_slug: "acme",
+  name: "alpha",
+  region: "us-east-1",
+  created_at: "2026-01-01T00:00:00Z",
+  status: "COMING_UP",
+};
+
+const ORGS = [{ id: "org-1", slug: "acme", name: "Acme Inc" }];
+
+const API_KEYS = [
+  { name: "anon", api_key: "anon-key" },
+  { name: "service_role", api_key: "svc-key" },
+];
+
+const HEALTHY = [{ name: "db", healthy: true, status: "ACTIVE_HEALTHY" }];
+
+const tempRoot = useLegacyTempWorkdir("supabase-bootstrap-int-");
+
+const NEXTJS_TEMPLATE: LegacyStarterTemplate = {
+  name: "nextjs",
+  description: "Next.js starter.",
+  url: "https://github.com/supabase/supabase/tree/master/examples/nextjs",
+  start: "npm ci && npm run dev",
+};
+
+interface SetupOpts {
+  readonly format?: "text" | "json" | "stream-json";
+  readonly workdir?: Option.Option<string>;
+  readonly yes?: boolean;
+  readonly stdinIsTty?: boolean;
+  readonly loggedIn?: boolean;
+  readonly samples?: ReadonlyArray<LegacyStarterTemplate>;
+  readonly apiKeysFailTimes?: number;
+  readonly health?: { readonly status: number; readonly body: unknown };
+  readonly promptTextResponses?: ReadonlyArray<string>;
+  readonly promptConfirmResponses?: ReadonlyArray<boolean>;
+}
+
+function setup(opts: SetupOpts = {}) {
+  const out = mockOutput({
+    format: opts.format ?? "text",
+    promptTextResponses: opts.promptTextResponses,
+    promptConfirmResponses: opts.promptConfirmResponses,
+  });
+  const telemetry = mockLegacyTelemetryStateTracked();
+  const linkedCache = mockLegacyLinkedProjectCacheTracked();
+  const analytics = mockAnalytics();
+  const credentials = mockLegacyCredentialsTracked();
+
+  let apiKeysCalls = 0;
+  const handler: LegacyApiHandler = (request, recorded) => {
+    const url = recorded.urlWithParams;
+    if (recorded.method === "POST" && /\/v1\/projects(\?|$)/.test(url)) {
+      return Effect.succeed(legacyJsonResponse(request, 201, CREATED));
+    }
+    if (url.includes("/api-keys")) {
+      apiKeysCalls += 1;
+      // 403 (not 5xx) so the api client's internal 5xx retry does not absorb it,
+      // forcing the bootstrap-level backoff to drive the retry.
+      if (apiKeysCalls <= (opts.apiKeysFailTimes ?? 0)) {
+        return Effect.succeed(legacyJsonResponse(request, 403, { message: "not ready" }));
+      }
+      return Effect.succeed(legacyJsonResponse(request, 200, API_KEYS));
+    }
+    if (url.includes("/health")) {
+      const health = opts.health ?? { status: 200, body: HEALTHY };
+      return Effect.succeed(legacyJsonResponse(request, health.status, health.body));
+    }
+    if (url.includes("/v1/organizations")) {
+      return Effect.succeed(legacyJsonResponse(request, 200, ORGS));
+    }
+    // storage/pooler config + tenant version probes — best-effort, ignored.
+    return Effect.succeed(legacyJsonResponse(request, 404, {}));
+  };
+  const api = mockLegacyPlatformApi({ handler });
+
+  const cliConfig = mockLegacyCliConfig({
+    workdir: tempRoot.current,
+    projectHost: "supabase.co",
+    accessToken: opts.loggedIn === false ? Option.none() : undefined,
+  });
+
+  const samples = opts.samples ?? [];
+  const downloads: Array<{ url: string; targetDir: string }> = [];
+  const templateLayer = Layer.succeed(LegacyTemplateService, {
+    listSamples: Effect.succeed(samples),
+    download: (url: string, targetDir: string) =>
+      Effect.sync(() => {
+        downloads.push({ url, targetDir });
+      }),
+  });
+
+  const proxyCalls: Array<ReadonlyArray<string>> = [];
+  const proxyLayer = Layer.succeed(LegacyGoProxy, {
+    exec: (args: ReadonlyArray<string>) =>
+      Effect.sync(() => {
+        proxyCalls.push(args);
+      }),
+  });
+
+  const loginApi = mockLegacyLoginApi({ gotrueId: "gotrue-user" });
+  const loginCrypto = mockLegacyLoginCrypto();
+
+  const layer = Layer.mergeAll(
+    BunServices.layer,
+    out.layer,
+    api.layer,
+    api.httpClientLayer,
+    cliConfig,
+    mockTty({ stdinIsTty: opts.stdinIsTty ?? true, stdoutIsTty: false }),
+    // cwd differs from the (absolute) workdir so the "Using workdir" line prints,
+    // matching Go's `cwd != CurrentDirAbs` guard.
+    mockRuntimeInfo({ cwd: dirname(tempRoot.current) }),
+    telemetry.layer,
+    linkedCache.layer,
+    analytics.layer,
+    credentials.layer,
+    templateLayer,
+    proxyLayer,
+    loginApi.layer,
+    loginCrypto.layer,
+    mockBrowser(),
+    mockStdin(opts.stdinIsTty ?? true),
+    Layer.succeed(LegacyOutputFlag, Option.none()),
+    Layer.succeed(LegacyWorkdirFlag, opts.workdir ?? Option.some(tempRoot.current)),
+    Layer.succeed(LegacyYesFlag, opts.yes ?? false),
+  );
+
+  return {
+    layer,
+    out,
+    telemetry,
+    linkedCache,
+    analytics,
+    credentials,
+    api,
+    workdir: tempRoot.current,
+    downloads,
+    proxyCalls,
+    loginApi,
+    get apiKeysCalls() {
+      return apiKeysCalls;
+    },
+  };
+}
+
+function flags(overrides: Partial<LegacyBootstrapFlags> = {}): LegacyBootstrapFlags {
+  return {
+    template: Option.none(),
+    password: Option.some("s3cret"),
+    ...overrides,
+  };
+}
+
+describe("legacy bootstrap integration", () => {
+  it.live("bootstraps the scratch template into the workdir (blank init, logged in)", () => {
+    const s = setup();
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      // Blank init scaffolded config.toml.
+      expect(existsSync(join(s.workdir, "supabase", "config.toml"))).toBe(true);
+      // Project ref written for the delegated db push.
+      expect(readFileSync(join(s.workdir, "supabase", ".temp", "project-ref"), "utf8")).toBe(
+        LEGACY_VALID_REF,
+      );
+      // .env populated with derived keys.
+      const env = readFileSync(join(s.workdir, ".env"), "utf8");
+      expect(env).toContain('SUPABASE_ANON_KEY="anon-key"');
+      expect(env).toContain("SUPABASE_URL=");
+      expect(env).toContain("POSTGRES_URL=");
+      // Progress + create echo on stderr.
+      expect(s.out.stderrText).toContain("Using workdir");
+      expect(s.out.stderrText).toContain("Created a new project at");
+      expect(s.out.stderrText).toContain("To start your app:");
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("downloads a named template matched by argument", () => {
+    const s = setup({ samples: [NEXTJS_TEMPLATE] });
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("NextJS") }), FAST_BACKOFF);
+      expect(s.downloads).toHaveLength(1);
+      expect(s.downloads[0]).toEqual({ url: NEXTJS_TEMPLATE.url, targetDir: s.workdir });
+      // No blank config.toml when a template is downloaded.
+      expect(existsSync(join(s.workdir, "supabase", "config.toml"))).toBe(false);
+      expect(s.out.stdoutText).toContain(`Downloading: ${NEXTJS_TEMPLATE.url}`);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("rejects an unknown template argument", () => {
+    const s = setup({ samples: [NEXTJS_TEMPLATE] });
+    return Effect.gen(function* () {
+      const exit = yield* Effect.exit(
+        legacyBootstrap(flags({ template: Option.some("nope") }), FAST_BACKOFF),
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        const json = JSON.stringify(exit.cause);
+        expect(json).toContain("LegacyBootstrapInvalidTemplateError");
+        expect(json).toContain("Invalid template: nope");
+      }
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("prompts for a template when none is given", () => {
+    const s = setup({ samples: [NEXTJS_TEMPLATE] });
+    return Effect.gen(function* () {
+      // Default mock promptSelect picks the first option (the nextjs template).
+      yield* legacyBootstrap(flags(), FAST_BACKOFF);
+      expect(s.out.promptSelectCalls[0]?.message).toBe(
+        "Which starter template do you want to use?",
+      );
+      expect(s.downloads).toHaveLength(1);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("prompts for a workdir when none is configured", () => {
+    const s = setup({
+      workdir: Option.none(),
+      promptTextResponses: [tempRoot.current],
+    });
+    const prevWorkdir = process.env["SUPABASE_WORKDIR"];
+    delete process.env["SUPABASE_WORKDIR"];
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      expect(existsSync(join(s.workdir, "supabase", "config.toml"))).toBe(true);
+    }).pipe(
+      Effect.provide(s.layer),
+      Effect.ensuring(
+        Effect.sync(() => {
+          if (prevWorkdir !== undefined) process.env["SUPABASE_WORKDIR"] = prevWorkdir;
+        }),
+      ),
+    );
+  });
+
+  it.live("aborts when the user declines to overwrite a non-empty workdir", () => {
+    const s = setup({ promptConfirmResponses: [false] });
+    writeFileSync(join(tempRoot.current, "existing.txt"), "keep me");
+    return Effect.gen(function* () {
+      const exit = yield* Effect.exit(
+        legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF),
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        expect(JSON.stringify(exit.cause)).toContain("LegacyBootstrapOverwriteDeclinedError");
+      }
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("proceeds past a non-empty workdir with --yes", () => {
+    const s = setup({ yes: true });
+    writeFileSync(join(tempRoot.current, "existing.txt"), "keep me");
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      expect(existsSync(join(s.workdir, "supabase", "config.toml"))).toBe(true);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("runs the browser login flow when no token is present (one cli_login_completed)", () => {
+    const s = setup({ loggedIn: false });
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      expect(s.credentials.savedToken).toBeDefined();
+      expect(
+        s.analytics.captured.map((c) => c.event).filter((e) => e === "cli_login_completed"),
+      ).toHaveLength(1);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live(
+    "skips login when already authenticated (no login event, no project-linked event)",
+    () => {
+      const s = setup({ loggedIn: true });
+      return Effect.gen(function* () {
+        yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+        const events = s.analytics.captured.map((c) => c.event);
+        expect(events).not.toContain("cli_login_completed");
+        // Go's bootstrap calls link.LinkServices (not link.Run) — no cli_project_linked.
+        expect(events).not.toContain("cli_project_linked");
+      }).pipe(Effect.provide(s.layer));
+    },
+  );
+
+  it.live("retries fetching api keys until they are available", () => {
+    const s = setup({ apiKeysFailTimes: 2 });
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      expect(s.apiKeysCalls).toBe(3);
+      const linkingLines = s.out.stderrText.match(/Linking project\.\.\./g) ?? [];
+      expect(linkingLines.length).toBeGreaterThanOrEqual(3);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("fails when a service stays unhealthy", () => {
+    const s = setup({
+      health: { status: 200, body: [{ name: "db", healthy: false, status: "UNHEALTHY" }] },
+    });
+    return Effect.gen(function* () {
+      const exit = yield* Effect.exit(
+        legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF),
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        expect(JSON.stringify(exit.cause)).toContain("Service not healthy: db (UNHEALTHY)");
+      }
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("fails with an Error status when the health endpoint returns non-200", () => {
+    const s = setup({ health: { status: 503, body: { message: "down" } } });
+    return Effect.gen(function* () {
+      const exit = yield* Effect.exit(
+        legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF),
+      );
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        expect(JSON.stringify(exit.cause)).toContain("Error status 503");
+      }
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("merges .env.example derived keys", () => {
+    const s = setup();
+    mkdirSync(tempRoot.current, { recursive: true });
+    writeFileSync(
+      join(tempRoot.current, ".env.example"),
+      "POSTGRES_USER=example\nNEXT_PUBLIC_SUPABASE_ANON_KEY=example\n",
+    );
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      const env = readFileSync(join(s.workdir, ".env"), "utf8");
+      expect(env).toContain('POSTGRES_USER="postgres"');
+      expect(env).toContain('NEXT_PUBLIC_SUPABASE_ANON_KEY="anon-key"');
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("continues (non-fatal) when the .env.example is malformed", () => {
+    const s = setup();
+    mkdirSync(tempRoot.current, { recursive: true });
+    writeFileSync(join(tempRoot.current, ".env.example"), "!=");
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      expect(s.out.stderrText).toContain("Failed to create .env file:");
+      // Bootstrap still completes through the db push step.
+      expect(s.proxyCalls).toHaveLength(1);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("delegates the db push step to the Go proxy with the resolved password", () => {
+    const s = setup();
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(
+        flags({ template: Option.some("scratch"), password: Option.some("pw123") }),
+        FAST_BACKOFF,
+      );
+      expect(s.proxyCalls).toHaveLength(1);
+      expect(s.proxyCalls[0]).toEqual([
+        "db",
+        "push",
+        "--include-roles",
+        "--include-seed",
+        "--password",
+        "pw123",
+      ]);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("flushes telemetry and caches the linked project via ensuring", () => {
+    const s = setup();
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      expect(s.telemetry.flushed).toBe(true);
+      expect(s.linkedCache.cached).toBe(true);
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("emits a single structured result in json mode", () => {
+    const s = setup({ format: "json" });
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      const successes = s.out.messages.filter((m) => m.type === "success");
+      expect(successes).toHaveLength(1);
+      expect(successes[0]?.data).toMatchObject({
+        project_ref: LEGACY_VALID_REF,
+        template: "scratch",
+        start_command: "supabase start",
+        workdir: s.workdir,
+      });
+      // No human progress banners on stdout in json mode.
+      expect(s.out.stdoutText).not.toContain("To start your app:");
+    }).pipe(Effect.provide(s.layer));
+  });
+
+  it.live("reports env_file: null in the json result when the .env write fails", () => {
+    const s = setup({ format: "json" });
+    mkdirSync(tempRoot.current, { recursive: true });
+    writeFileSync(join(tempRoot.current, ".env.example"), "!=");
+    return Effect.gen(function* () {
+      yield* legacyBootstrap(flags({ template: Option.some("scratch") }), FAST_BACKOFF);
+      const success = s.out.messages.find((m) => m.type === "success");
+      expect(success?.data).toMatchObject({ env_file: null });
+    }).pipe(Effect.provide(s.layer));
+  });
+});
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts
new file mode 100644
index 0000000000..a9f305c2f7
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts
@@ -0,0 +1,55 @@
+import { Layer } from "effect";
+
+import { legacyCredentialsLayer } from "../../auth/legacy-credentials.layer.ts";
+import { legacyHttpClientLayer } from "../../auth/legacy-http-debug.layer.ts";
+import { legacyPlatformApiLayer } from "../../auth/legacy-platform-api.layer.ts";
+import { legacyCliConfigLayer } from "../../config/legacy-cli-config.layer.ts";
+import { legacyProjectRefLayer } from "../../config/legacy-project-ref.layer.ts";
+import { legacyLinkedProjectCacheLayer } from "../../telemetry/legacy-linked-project-cache.layer.ts";
+import { legacyTelemetryStateLayer } from "../../telemetry/legacy-telemetry-state.layer.ts";
+import { commandRuntimeLayer } from "../../../shared/runtime/command-runtime.layer.ts";
+import { browserLayer } from "../../../shared/runtime/browser.layer.ts";
+import { stdinLayer } from "../../../shared/runtime/stdin.layer.ts";
+import { legacyLoginApiLayer } from "../../shared/legacy-login-api.layer.ts";
+import { legacyLoginCryptoLayer } from "../../shared/legacy-login-crypto.layer.ts";
+import { legacyTemplateServiceLayer } from "./bootstrap.templates.ts";
+
+// `bootstrap` is a meta-orchestrator: it needs the full Management-API stack
+// (create / api-keys / link cores), the browser-login stack (ensure-login), and
+// the GitHub template service. `Layer.provide` does not share to siblings inside
+// a `Layer.mergeAll` (legacy CLAUDE.md item 5), so every sub-layer that requires
+// `LegacyCliConfig` / `HttpClient` / `LegacyCredentials` is fed those explicitly.
+// Shared sub-layers are memoised by reference so the merge reuses one keyring
+// reader / one debug-logging HTTP wrapper / one config loader.
+//
+// `Output`, `Analytics`, `Stdio`, `Tty`, `RuntimeInfo`, `ProcessControl`,
+// `LegacyGoProxy`, and `BunServices` (`FileSystem` / `Path` / `ChildProcessSpawner`)
+// come from the root layer (`legacy/cli/root.ts` + `runCli`).
+const cliConfig = legacyCliConfigLayer;
+const httpClient = legacyHttpClientLayer;
+const credentials = legacyCredentialsLayer.pipe(Layer.provide(cliConfig));
+const platformApi = legacyPlatformApiLayer.pipe(
+  Layer.provide(credentials),
+  Layer.provide(cliConfig),
+  Layer.provide(httpClient),
+);
+
+export const legacyBootstrapRuntimeLayer = Layer.mergeAll(
+  platformApi,
+  httpClient,
+  credentials,
+  cliConfig,
+  legacyProjectRefLayer.pipe(Layer.provide(platformApi), Layer.provide(cliConfig)),
+  legacyLinkedProjectCacheLayer.pipe(
+    Layer.provide(credentials),
+    Layer.provide(cliConfig),
+    Layer.provide(httpClient),
+  ),
+  legacyTelemetryStateLayer,
+  legacyLoginApiLayer.pipe(Layer.provide(httpClient), Layer.provide(cliConfig)),
+  legacyLoginCryptoLayer,
+  legacyTemplateServiceLayer.pipe(Layer.provide(httpClient)),
+  browserLayer,
+  stdinLayer,
+  commandRuntimeLayer(["bootstrap"]),
+);
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.ts
new file mode 100644
index 0000000000..b3d6abf6eb
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.ts
@@ -0,0 +1,74 @@
+/**
+ * Pure Postgres connection-string helpers. Ports of Go's `utils.ToPostgresURL`
+ * (`apps/cli-go/internal/utils/connect.go`) and the db-config derivation in
+ * `flags.NewDbConfigWithPassword`, reduced to just the connection-string
+ * components bootstrap needs (no live DB connection).
+ */
+
+export interface LegacyDbConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly user: string;
+  readonly password: string;
+  readonly database: string;
+}
+
+// Go's `url.UserPassword` escapes userinfo with the `encodeUserPassword` mode:
+// unreserved chars + the sub-delims `$ & + , ; =` pass through; the reserved
+// `@ / ? :` and everything else are percent-encoded (`net/url.shouldEscape`).
+const USERINFO_UNESCAPED = new Set(
+  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.~$&+,;=".split(""),
+);
+
+// Go's `url.PathEscape` uses `encodePathSegment`: escape `/ ; , ?` and anything
+// outside unreserved + the remaining reserved sub-delims `$ & + : = @`.
+const PATH_SEGMENT_UNESCAPED = new Set(
+  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.~$&+:=@".split(""),
+);
+
+function percentEscape(value: string, allowed: ReadonlySet<string>): string {
+  const bytes = new TextEncoder().encode(value);
+  let out = "";
+  for (const byte of bytes) {
+    const char = String.fromCharCode(byte);
+    if (byte < 0x80 && allowed.has(char)) {
+      out += char;
+    } else {
+      out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  return out;
+}
+
+/**
+ * Reproduces Go's `ToPostgresURL`:
+ * `postgresql://<user>:<pass>@<host>:<port>/<db>?connect_timeout=10`, with
+ * percent-encoded userinfo, a path-escaped database, and IPv6 hosts wrapped in
+ * square brackets. Bootstrap passes no `RuntimeParams`, so the only query
+ * parameter is the default `connect_timeout=10`.
+ */
+export function toPostgresUrl(config: LegacyDbConfig): string {
+  const userinfo = `${percentEscape(config.user, USERINFO_UNESCAPED)}:${percentEscape(
+    config.password,
+    USERINFO_UNESCAPED,
+  )}`;
+  const host = config.host.includes(":") ? `[${config.host}]` : config.host;
+  const database = percentEscape(config.database, PATH_SEGMENT_UNESCAPED);
+  return `postgresql://${userinfo}@${host}:${config.port}/${database}?connect_timeout=10`;
+}
+
+/**
+ * Derives the remote project's direct (session-mode) connection config. Mirrors
+ * Go's `flags.NewDbConfigWithPassword`: `host = db.<ref>.<projectHost>`,
+ * `user = postgres`, `database = postgres`, direct port `5432`. The pooled
+ * (transaction-mode) variant uses the same config with port `6543`.
+ */
+export function deriveDbConfig(ref: string, password: string, projectHost: string): LegacyDbConfig {
+  return {
+    host: `db.${ref}.${projectHost}`,
+    port: 5432,
+    user: "postgres",
+    password,
+    database: "postgres",
+  };
+}
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.unit.test.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.unit.test.ts
new file mode 100644
index 0000000000..0037864b1b
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.pgconfig.unit.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+
+import { deriveDbConfig, toPostgresUrl } from "./bootstrap.pgconfig.ts";
+
+describe("deriveDbConfig", () => {
+  it("derives the direct (session-mode) connection config from ref + host", () => {
+    expect(deriveDbConfig("testing", "s3cret", "supabase.co")).toEqual({
+      host: "db.testing.supabase.co",
+      port: 5432,
+      user: "postgres",
+      password: "s3cret",
+      database: "postgres",
+    });
+  });
+});
+
+describe("toPostgresUrl", () => {
+  it("renders the transaction-mode (6543) pooled URL", () => {
+    expect(
+      toPostgresUrl({
+        host: "db.supabase.co",
+        port: 6543,
+        user: "admin",
+        password: "password",
+        database: "postgres",
+      }),
+    ).toBe("postgresql://admin:password@db.supabase.co:6543/postgres?connect_timeout=10");
+  });
+
+  it("renders the direct (5432) URL", () => {
+    expect(
+      toPostgresUrl({
+        host: "db.supabase.co",
+        port: 5432,
+        user: "admin",
+        password: "password",
+        database: "postgres",
+      }),
+    ).toBe("postgresql://admin:password@db.supabase.co:5432/postgres?connect_timeout=10");
+  });
+
+  it("percent-encodes reserved characters in the userinfo (Go's url.UserPassword)", () => {
+    // `@ / ? :` and space are escaped; the sub-delim `$` passes through.
+    expect(
+      toPostgresUrl({
+        host: "db.supabase.co",
+        port: 5432,
+        user: "ad:min",
+        password: "p@ss/w?rd $1",
+        database: "postgres",
+      }),
+    ).toBe(
+      "postgresql://ad%3Amin:p%40ss%2Fw%3Frd%20$1@db.supabase.co:5432/postgres?connect_timeout=10",
+    );
+  });
+
+  it("wraps an IPv6 host in square brackets", () => {
+    expect(
+      toPostgresUrl({
+        host: "2001:db8::1",
+        port: 5432,
+        user: "postgres",
+        password: "pw",
+        database: "postgres",
+      }),
+    ).toBe("postgresql://postgres:pw@[2001:db8::1]:5432/postgres?connect_timeout=10");
+  });
+});
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.ts
new file mode 100644
index 0000000000..1d19be79a4
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.ts
@@ -0,0 +1,34 @@
+import { relative } from "node:path";
+
+/**
+ * Reproduces Go's `suggestAppStart` (`apps/cli-go/internal/bootstrap/bootstrap.go`).
+ *
+ * Builds the "To start your app:" hint printed at the end of bootstrap. Go computes
+ * the relative path from the original working directory (`utils.CurrentDirAbs`) to
+ * the (post-chdir) project directory; a non-trivial relative path adds a `cd <rel>`
+ * line, and a non-empty start command adds a second line.
+ *
+ * Colour is applied via the injected `colorize` callback (Go wraps each command
+ * line in `utils.Aqua`). It defaults to identity so unit tests assert the raw text,
+ * matching Go's `TestSuggestAppStart` which runs under a non-TTY (uncoloured) profile.
+ */
+export function suggestAppStart(
+  currentDirAbs: string,
+  workdir: string,
+  command: string,
+  colorize: (line: string) => string = (line) => line,
+): string {
+  const rel = relative(currentDirAbs, workdir);
+  const lines: Array<string> = [];
+  if (rel.length > 0 && rel !== ".") {
+    lines.push(`cd ${rel}`);
+  }
+  if (command.length > 0) {
+    lines.push(command);
+  }
+  let suggestion = "To start your app:";
+  for (const line of lines) {
+    suggestion += `\n  ${colorize(line)}`;
+  }
+  return suggestion;
+}
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.unit.test.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.unit.test.ts
new file mode 100644
index 0000000000..6a990ffac4
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.suggest.unit.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+
+import { suggestAppStart } from "./bootstrap.suggest.ts";
+
+// Ports Go's `bootstrap_test.go::TestSuggestAppStart`. Colour is identity here so
+// the assertions match Go's non-TTY (uncoloured) output byte-for-byte.
+describe("suggestAppStart", () => {
+  it("suggests the start command when the workdir is the current directory", () => {
+    expect(suggestAppStart("/home/me/app", "/home/me/app", "npm ci && npm run dev")).toBe(
+      "To start your app:\n  npm ci && npm run dev",
+    );
+  });
+
+  it("prefixes a cd line when the workdir is nested", () => {
+    expect(suggestAppStart("/home/me", "/home/me/app", "npm ci && npm run dev")).toBe(
+      "To start your app:\n  cd app\n  npm ci && npm run dev",
+    );
+  });
+
+  it("omits the cd line for a '.' relative path", () => {
+    expect(suggestAppStart("/home/me/app", "/home/me/app", "supabase start")).toBe(
+      "To start your app:\n  supabase start",
+    );
+  });
+
+  it("omits the command line when the start command is empty", () => {
+    expect(suggestAppStart("/home/me", "/home/me/app", "")).toBe("To start your app:\n  cd app");
+  });
+
+  it("applies the colorize callback to each command line", () => {
+    const aqua = (line: string) => `<${line}>`;
+    expect(suggestAppStart("/home/me", "/home/me/app", "npm run dev", aqua)).toBe(
+      "To start your app:\n  <cd app>\n  <npm run dev>",
+    );
+  });
+});
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts
new file mode 100644
index 0000000000..376728a496
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts
@@ -0,0 +1,229 @@
+import { Context, Effect, FileSystem, Layer, Path } from "effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+
+import { Output } from "../../../shared/output/output.service.ts";
+import { sanitizeLegacyErrorBody } from "../../shared/legacy-http-errors.ts";
+import {
+  LegacyBootstrapTemplateDownloadError,
+  LegacyBootstrapTemplateListError,
+} from "./bootstrap.errors.ts";
+
+export interface LegacyStarterTemplate {
+  readonly name: string;
+  readonly description: string;
+  readonly url: string;
+  readonly start: string;
+}
+
+interface LegacyTemplateServiceShape {
+  /**
+   * Fetches and decodes `samples.json` from the `supabase-community/supabase-samples`
+   * repo (Go's `ListSamples`). Returns the declared starter templates.
+   */
+  readonly listSamples: Effect.Effect<
+    ReadonlyArray<LegacyStarterTemplate>,
+    LegacyBootstrapTemplateListError
+  >;
+  /**
+   * Downloads every file under a `https://github.com/<owner>/<repo>/tree/<ref>/<root>`
+   * template URL into `targetDir`, preserving the directory layout below `<root>`
+   * (Go's `downloadSample`). Concurrency matches Go's job queue (5).
+   */
+  readonly download: (
+    templateUrl: string,
+    targetDir: string,
+  ) => Effect.Effect<void, LegacyBootstrapTemplateDownloadError>;
+}
+
+export class LegacyTemplateService extends Context.Service<
+  LegacyTemplateService,
+  LegacyTemplateServiceShape
+>()("supabase/legacy/TemplateService") {}
+
+const GITHUB_API = "https://api.github.com";
+const SAMPLES_OWNER = "supabase-community";
+const SAMPLES_REPO = "supabase-samples";
+const DOWNLOAD_CONCURRENCY = 5;
+
+interface GithubContentEntry {
+  readonly type?: string;
+  readonly name?: string;
+  readonly path?: string;
+  readonly content?: string;
+  readonly encoding?: string;
+  readonly download_url?: string | null;
+}
+
+function isStarterTemplate(value: unknown): value is LegacyStarterTemplate {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as LegacyStarterTemplate).name === "string"
+  );
+}
+
+// Preserve an explicit non-200 / parse failure (already a tagged error); wrap any
+// transport / filesystem cause in the same tagged error so the channel stays narrow.
+const mapDownloadError = (
+  cause: unknown,
+): Effect.Effect<never, LegacyBootstrapTemplateDownloadError> =>
+  Effect.fail(
+    cause instanceof LegacyBootstrapTemplateDownloadError
+      ? cause
+      : new LegacyBootstrapTemplateDownloadError({
+          message: `failed to download template: ${cause}`,
+        }),
+  );
+
+export const legacyTemplateServiceLayer = Layer.effect(
+  LegacyTemplateService,
+  Effect.gen(function* () {
+    const httpClient = yield* HttpClient.HttpClient;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const output = yield* Output;
+
+    // Go reads `GITHUB_TOKEN` directly (`utils.GetGitHubClient`) to raise the
+    // anonymous GitHub API rate limit. When unset, requests are anonymous.
+    const githubToken = process.env["GITHUB_TOKEN"];
+
+    const contentsRequest = (owner: string, repo: string, contentPath: string, ref: string) => {
+      const encodedPath = contentPath
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+      let request = HttpClientRequest.get(
+        `${GITHUB_API}/repos/${owner}/${repo}/contents/${encodedPath}?ref=${ref}`,
+      ).pipe(HttpClientRequest.setHeader("Accept", "application/vnd.github.v3+json"));
+      if (githubToken !== undefined && githubToken.length > 0) {
+        request = request.pipe(
+          HttpClientRequest.setHeader("Authorization", `Bearer ${githubToken}`),
+        );
+      }
+      return request;
+    };
+
+    const listSamples: Effect.Effect<
+      ReadonlyArray<LegacyStarterTemplate>,
+      LegacyBootstrapTemplateListError
+    > = Effect.gen(function* () {
+      const response = yield* httpClient
+        .execute(contentsRequest(SAMPLES_OWNER, SAMPLES_REPO, "samples.json", "main"))
+        .pipe(
+          Effect.mapError(
+            (cause) =>
+              new LegacyBootstrapTemplateListError({
+                message: `failed to list samples: ${cause}`,
+              }),
+          ),
+        );
+      if (response.status !== 200) {
+        const body = sanitizeLegacyErrorBody(
+          yield* response.text.pipe(Effect.orElseSucceed(() => "")),
+        );
+        return yield* new LegacyBootstrapTemplateListError({
+          message: `failed to list samples: status ${response.status}: ${body}`,
+        });
+      }
+      const payload = yield* response.json.pipe(
+        Effect.mapError(
+          (cause) =>
+            new LegacyBootstrapTemplateListError({ message: `failed to decode samples: ${cause}` }),
+        ),
+      );
+      const decoded = Buffer.from(
+        ((payload as GithubContentEntry).content ?? "").replaceAll("\n", ""),
+        "base64",
+      ).toString("utf8");
+      const parsed = yield* Effect.try({
+        try: () => JSON.parse(decoded) as { samples?: ReadonlyArray<unknown> },
+        catch: (cause) =>
+          new LegacyBootstrapTemplateListError({
+            message: `failed to unmarshal samples: ${cause}`,
+          }),
+      });
+      return (parsed.samples ?? []).filter(isStarterTemplate);
+    });
+
+    const downloadFile = (localPath: string, remoteUrl: string) =>
+      Effect.gen(function* () {
+        const response = yield* httpClient.execute(HttpClientRequest.get(remoteUrl));
+        if (response.status !== 200) {
+          return yield* new LegacyBootstrapTemplateDownloadError({
+            message: `failed to download template: status ${response.status}`,
+          });
+        }
+        const bytes = new Uint8Array(yield* response.arrayBuffer);
+        yield* fs.makeDirectory(path.dirname(localPath), { recursive: true });
+        yield* fs.writeFile(localPath, bytes);
+      }).pipe(Effect.catch(mapDownloadError));
+
+    const download = (templateUrl: string, targetDir: string) =>
+      Effect.gen(function* () {
+        // e.g. https://github.com/supabase/supabase/tree/master/examples/user-management
+        const parsed = new URL(templateUrl);
+        const parts = parsed.pathname.split("/");
+        const owner = parts[1] ?? "";
+        const repo = parts[2] ?? "";
+        const ref = parts[4] ?? "";
+        const root = parts.slice(5).join("/");
+
+        const downloads: Array<{ readonly localPath: string; readonly remoteUrl: string }> = [];
+        const queue: Array<string> = [root];
+        while (queue.length > 0) {
+          const contentPath = queue.shift() ?? "";
+          const response = yield* httpClient.execute(
+            contentsRequest(owner, repo, contentPath, ref),
+          );
+          if (response.status !== 200) {
+            const body = sanitizeLegacyErrorBody(
+              yield* response.text.pipe(Effect.orElseSucceed(() => "")),
+            );
+            return yield* new LegacyBootstrapTemplateDownloadError({
+              message: `failed to download template: status ${response.status}: ${body}`,
+            });
+          }
+          const payload = yield* response.json;
+          if (!Array.isArray(payload)) {
+            return yield* new LegacyBootstrapTemplateDownloadError({
+              message: `failed to download template: expected a directory listing for ${contentPath}`,
+            });
+          }
+          const listing = payload as ReadonlyArray<GithubContentEntry>;
+          for (const entry of listing) {
+            const entryPath = entry.path ?? "";
+            if (entry.type === "file") {
+              const relative = entryPath.startsWith(root)
+                ? entryPath.slice(root.length)
+                : entryPath;
+              const localPath = path.join(targetDir, ...relative.split("/").filter(Boolean));
+              // Defence-in-depth: reject a malicious `path` (e.g. `../../etc/x`)
+              // that would escape the target directory.
+              const resolvedTarget = path.resolve(targetDir);
+              const resolvedLocal = path.resolve(localPath);
+              if (
+                resolvedLocal !== resolvedTarget &&
+                !resolvedLocal.startsWith(resolvedTarget + path.sep)
+              ) {
+                return yield* new LegacyBootstrapTemplateDownloadError({
+                  message: `failed to download template: entry escapes target directory: ${entryPath}`,
+                });
+              }
+              downloads.push({ localPath, remoteUrl: entry.download_url ?? "" });
+            } else if (entry.type === "dir") {
+              queue.push(entryPath);
+            } else {
+              yield* output.raw(`Ignoring ${entry.type}: ${entryPath}\n`, "stderr");
+            }
+          }
+        }
+
+        yield* Effect.forEach(downloads, (job) => downloadFile(job.localPath, job.remoteUrl), {
+          concurrency: DOWNLOAD_CONCURRENCY,
+        });
+      }).pipe(Effect.catch(mapDownloadError));
+
+    return { listSamples, download };
+  }),
+);
diff --git a/apps/cli/src/legacy/commands/link/link.handler.ts b/apps/cli/src/legacy/commands/link/link.handler.ts
index 1a81005f7e..88e2503771 100644
--- a/apps/cli/src/legacy/commands/link/link.handler.ts
+++ b/apps/cli/src/legacy/commands/link/link.handler.ts
@@ -18,12 +18,9 @@ import {
 } from "../../../shared/telemetry/event-catalog.ts";
 import { legacyDashboardUrl } from "../../shared/legacy-profile.ts";
 import { mapLegacyHttpError, sanitizeLegacyErrorBody } from "../../shared/legacy-http-errors.ts";
+import { legacyLinkServicesCore } from "../../shared/legacy-link-services-core.ts";
+import { legacyExtractServiceKeys } from "../../shared/legacy-tenant-keys.ts";
 import { legacyTempPaths } from "../../shared/legacy-temp-paths.ts";
-import {
-  legacyFetchGotrueVersion,
-  legacyFetchPostgrestVersion,
-  legacyFetchStorageVersion,
-} from "../../shared/legacy-tenant-versions.ts";
 import {
   LegacyLinkApiKeysNetworkError,
   LegacyLinkAuthTokenError,
@@ -74,47 +71,8 @@ const classifyProjectError = (
   );
 };
 
-interface ApiKeyEntry {
-  readonly api_key?: string | null;
-  readonly type?: string | null;
-  readonly name: string;
-  readonly secret_jwt_template?: Record<string, unknown> | null;
-}
-
 type WriteTempFile = (filePath: string, content: string) => Effect.Effect<void, PlatformError>;
 
-// Mirrors `tenant.NewApiKey` (`apps/cli-go/internal/utils/tenant/client.go:28-57`):
-// publishable -> anon, secret w/ role=service_role -> service_role, else legacy
-// name-based fallback (`anon` / `service_role`).
-function extractServiceKeys(keys: ReadonlyArray<ApiKeyEntry>): {
-  anon: string;
-  serviceRole: string;
-} {
-  let anon = "";
-  let serviceRole = "";
-  for (const key of keys) {
-    const value = key.api_key;
-    if (value === undefined || value === null) continue;
-    if (key.type === "publishable") {
-      anon = value;
-      continue;
-    }
-    if (key.type === "secret") {
-      const role = key.secret_jwt_template?.["role"];
-      if (typeof role === "string" && role.toLowerCase() === "service_role") {
-        serviceRole = value;
-      }
-      continue;
-    }
-    if (key.name === "anon" && anon.length === 0) {
-      anon = value;
-    } else if (key.name === "service_role" && serviceRole.length === 0) {
-      serviceRole = value;
-    }
-  }
-  return { anon, serviceRole };
-}
-
 const mapApiKeysError = mapLegacyHttpError({
   networkError: LegacyLinkApiKeysNetworkError,
   statusError: LegacyLinkAuthTokenError,
@@ -181,46 +139,18 @@ export const legacyLink = Effect.fn("legacy.link")(function* (flags: LegacyLinkF
     const keys = yield* api.v1
       .getProjectApiKeys({ ref, reveal: true })
       .pipe(Effect.catch(mapApiKeysError));
-    const { anon, serviceRole } = extractServiceKeys(keys);
+    const { anon, serviceRole } = legacyExtractServiceKeys(keys);
     if (anon.length === 0 && serviceRole.length === 0) {
       return yield* Effect.fail(new LegacyLinkMissingKeyError({ message: "Anon key not found." }));
     }
 
-    // 3. Link services — best-effort. Every error is swallowed so a single
-    // unreachable service never fails the link (link.go:91-100).
-    yield* linkStorageMigration(api, ref, paths.storageMigration, writeTempFile);
-    yield* linkPooler({
-      api,
+    // 3. Link services — best-effort, using the service-role key for tenant probes.
+    yield* legacyLinkServicesCore({
       ref,
+      serviceKey: serviceRole,
       skipPooler: flags.skipPooler,
-      fs,
-      poolerUrlPath: paths.poolerUrl,
-      writeTempFile,
+      workdir: cliConfig.workdir,
     });
-    const tenantOpts = {
-      ref,
-      projectHost: cliConfig.projectHost,
-      serviceKey: serviceRole,
-      userAgent: cliConfig.userAgent,
-    };
-    yield* legacyFetchPostgrestVersion(tenantOpts).pipe(
-      Effect.flatMap((v) =>
-        Option.isSome(v) ? writeTempFile(paths.restVersion, v.value) : Effect.void,
-      ),
-      Effect.ignore,
-    );
-    yield* legacyFetchGotrueVersion(tenantOpts).pipe(
-      Effect.flatMap((v) =>
-        Option.isSome(v) ? writeTempFile(paths.gotrueVersion, v.value) : Effect.void,
-      ),
-      Effect.ignore,
-    );
-    yield* legacyFetchStorageVersion(tenantOpts).pipe(
-      Effect.flatMap((v) =>
-        Option.isSome(v) ? writeTempFile(paths.storageVersion, v.value) : Effect.void,
-      ),
-      Effect.ignore,
-    );
 
     // 4. Save project ref (mandatory — a write failure fails the command).
     yield* writeTempFile(paths.projectRef, ref);
@@ -264,40 +194,3 @@ export const legacyLink = Effect.fn("legacy.link")(function* (flags: LegacyLinkF
     }
   }).pipe(Effect.ensuring(linkedProjectCache.cache(ref)), Effect.ensuring(telemetryState.flush));
 });
-
-const linkStorageMigration = (
-  api: ApiClient,
-  ref: string,
-  storageMigrationPath: string,
-  writeTempFile: WriteTempFile,
-) =>
-  api.v1.getStorageConfig({ ref }).pipe(
-    Effect.flatMap((config) => writeTempFile(storageMigrationPath, config.migrationVersion)),
-    Effect.ignore,
-  );
-
-const linkPooler = (opts: {
-  api: ApiClient;
-  ref: string;
-  skipPooler: boolean;
-  fs: FileSystem.FileSystem;
-  poolerUrlPath: string;
-  writeTempFile: WriteTempFile;
-}) =>
-  Effect.gen(function* () {
-    if (opts.skipPooler) {
-      // Use direct connection: drop any cached pooler URL (link.go:81-84).
-      yield* opts.fs.remove(opts.poolerUrlPath, { recursive: true }).pipe(Effect.ignore);
-      return;
-    }
-    const configs = yield* opts.api.v1.getPoolerConfig({ ref: opts.ref });
-    const primary = configs.find((c) => c.database_type === "PRIMARY");
-    if (primary === undefined) return;
-    // Strip the [YOUR-PASSWORD] placeholder; force session mode 5432 unless the
-    // pooler already reports session mode (link.go:221-229).
-    let connectionString = primary.connection_string.replaceAll(":[YOUR-PASSWORD]", "");
-    if (primary.pool_mode !== "session") {
-      connectionString = connectionString.replaceAll(":6543/", ":5432/");
-    }
-    yield* opts.writeTempFile(opts.poolerUrlPath, connectionString);
-  }).pipe(Effect.ignore);
diff --git a/apps/cli/src/legacy/commands/login/login.handler.ts b/apps/cli/src/legacy/commands/login/login.handler.ts
index ea32aef833..52e0a08aae 100644
--- a/apps/cli/src/legacy/commands/login/login.handler.ts
+++ b/apps/cli/src/legacy/commands/login/login.handler.ts
@@ -4,49 +4,34 @@ import { LegacyCredentials } from "../../auth/legacy-credentials.service.ts";
 import { LegacyCliConfig } from "../../config/legacy-cli-config.service.ts";
 import { saveLegacyProfileName } from "../../config/legacy-profile-file.ts";
 import { LegacyTelemetryState } from "../../telemetry/legacy-telemetry-state.service.ts";
-import { legacyDashboardUrl } from "../../shared/legacy-profile.ts";
+import {
+  LEGACY_LOGGED_IN_MSG,
+  legacyBrowserLogin,
+  legacyPostLoginTelemetry,
+} from "../../shared/legacy-ensure-login.ts";
 import { LegacyProfileFlag } from "../../../shared/legacy/global-flags.ts";
 import { Output } from "../../../shared/output/output.service.ts";
-import type { NonInteractiveError } from "../../../shared/output/errors.ts";
-import { Browser } from "../../../shared/runtime/browser.service.ts";
 import { RuntimeInfo } from "../../../shared/runtime/runtime-info.service.ts";
 import { Stdin } from "../../../shared/runtime/stdin.service.ts";
 import { Tty } from "../../../shared/runtime/tty.service.ts";
-import { Analytics } from "../../../shared/telemetry/analytics.service.ts";
-import { withAnalyticsContext } from "../../../shared/telemetry/analytics-context.ts";
-import { EventLoginCompleted } from "../../../shared/telemetry/event-catalog.ts";
-import { LegacyLoginApi, type LegacyLoginSessionResponse } from "./login-api.service.ts";
-import { LegacyLoginCrypto } from "./login-crypto.service.ts";
 import { legacySuggestClaudePlugin } from "./login-claude-hint.ts";
 import {
   LEGACY_LOGIN_MISSING_TOKEN_MESSAGE,
-  LegacyLoginFailedError,
   LegacyLoginMissingTokenError,
   LegacyLoginSaveTokenError,
 } from "./login.errors.ts";
 import type { LegacyLoginFlags } from "./login.command.ts";
 
-// Go's `maxRetries` (`login.go:130`): the initial probe plus 2 retries (3 total).
-const MAX_LOGIN_RETRIES = 2;
-
-const LOGGED_IN_MSG = "You are now logged in. Happy coding!\n";
-
 export const legacyLogin = Effect.fn("legacy.login")(function* (flags: LegacyLoginFlags) {
   const output = yield* Output;
-  const cliConfig = yield* LegacyCliConfig;
   const credentials = yield* LegacyCredentials;
-  const crypto = yield* LegacyLoginCrypto;
-  const loginApi = yield* LegacyLoginApi;
   const telemetryState = yield* LegacyTelemetryState;
-  const analytics = yield* Analytics;
-  const browser = yield* Browser;
   const tty = yield* Tty;
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const runtimeInfo = yield* RuntimeInfo;
   const profileFlag = yield* LegacyProfileFlag;
 
-  const apiHost = cliConfig.apiUrl;
   const claudeHint = legacySuggestClaudePlugin({ stdoutIsTty: tty.stdoutIsTty });
 
   // Mirrors Go's login `PostRunE` (`cmd/login.go:42-48`): when a profile was
@@ -67,28 +52,6 @@ export const legacyLogin = Effect.fn("legacy.login")(function* (flags: LegacyLog
       ? Effect.void
       : saveLegacyProfileName(fs, path, runtimeInfo.homeDir, profileToken);
 
-  // Mirrors Go's `handleTelemetryAfterLogin` (`login.go:273-299`): fetch the
-  // gotrue id (best-effort), stitch or clear the telemetry identity, then always
-  // capture `cli_login_completed`. The capture rides the just-stitched identity
-  // so PostHog attributes it to the user (Go's `s.distinctID()` after StitchLogin).
-  //
-  // NOTE: Go's `StitchLogin` only *aliases* (`service.go:137`) — it does NOT
-  // call `identify`. Do not add `analytics.identify` here; that is a `next/`
-  // shell behavior and would emit an event Go never sends.
-  const postLoginTelemetry = (token: string) =>
-    Effect.gen(function* () {
-      const gotrueId = yield* loginApi.fetchGotrueId(apiHost, token);
-      if (Option.isSome(gotrueId)) {
-        yield* telemetryState.stitchLogin(gotrueId.value);
-        yield* analytics
-          .capture(EventLoginCompleted)
-          .pipe(withAnalyticsContext({ distinct_id: gotrueId.value }));
-      } else {
-        yield* telemetryState.clearDistinctId;
-        yield* analytics.capture(EventLoginCompleted);
-      }
-    });
-
   const tokenPath = (token: string) =>
     Effect.gen(function* () {
       yield* credentials.saveAccessToken(token).pipe(
@@ -100,100 +63,16 @@ export const legacyLogin = Effect.fn("legacy.login")(function* (flags: LegacyLog
           ),
         ),
       );
-      yield* postLoginTelemetry(token);
+      yield* legacyPostLoginTelemetry(token);
 
       if (output.format !== "text") {
         yield* output.success("You are now logged in.");
         return;
       }
-      yield* output.raw(LOGGED_IN_MSG, "stdout");
+      yield* output.raw(LEGACY_LOGGED_IN_MSG, "stdout");
       if (claudeHint.length > 0) yield* output.raw(`${claudeHint}\n`, "stderr");
     });
 
-  const browserPath = Effect.gen(function* () {
-    const { ecdh, publicKeyHex } = yield* crypto.generateKeyPair;
-    const sessionId = yield* crypto.generateSessionId;
-    const tokenName = Option.isSome(flags.name) ? flags.name.value : yield* crypto.defaultTokenName;
-
-    // Go concatenates the query string without URL-encoding (`login.go:197-198`).
-    const loginUrl =
-      `${legacyDashboardUrl(cliConfig.profile)}/cli/login` +
-      `?session_id=${sessionId}&token_name=${tokenName}&public_key=${publicKeyHex}`;
-
-    // The banners are human-facing text — suppressed in json / stream-json so
-    // stdout stays payload-only. The prompts still run (and fail cleanly with
-    // `NonInteractiveError` in a non-interactive machine mode).
-    const isText = output.format === "text";
-    if (!flags.noBrowser) {
-      if (isText) {
-        yield* output.raw(
-          "Hello from Supabase! Press Enter to open browser and login automatically.\n",
-          "stdout",
-        );
-      }
-      yield* output.promptText("");
-      if (isText) {
-        yield* output.raw(
-          `Here is your login link in case browser did not open ${loginUrl}\n\n`,
-          "stdout",
-        );
-      }
-      yield* Effect.ignore(browser.open(loginUrl));
-    } else if (isText) {
-      yield* output.raw(
-        `Here is your login link, open it in the browser ${loginUrl}\n\n`,
-        "stdout",
-      );
-    }
-
-    // Verify + retry, mirroring Go's `pollForAccessToken` backoff
-    // (`login.go:132-166`): the notifier prints `<err>\nRetry (n/2): ` after the
-    // first 2 failures; the 3rd failure gives up without a notice.
-    const verifyWithRetries = (
-      failuresSoFar: number,
-    ): Effect.Effect<LegacyLoginSessionResponse, LegacyLoginFailedError | NonInteractiveError> =>
-      Effect.gen(function* () {
-        const code = yield* output.promptText("Enter your verification code: ", {
-          validate: (v) => (v.trim().length > 0 ? undefined : "Verification code is required"),
-        });
-        return yield* loginApi.fetchLoginSession(apiHost, sessionId, code.trim());
-      }).pipe(
-        Effect.catchTag("LegacyLoginVerificationError", (err) =>
-          Effect.gen(function* () {
-            const failures = failuresSoFar + 1;
-            if (failures > MAX_LOGIN_RETRIES) {
-              return yield* Effect.fail(new LegacyLoginFailedError({ message: err.message }));
-            }
-            yield* output.raw(
-              `${err.message}\nRetry (${failures}/${MAX_LOGIN_RETRIES}): `,
-              "stderr",
-            );
-            return yield* verifyWithRetries(failures);
-          }),
-        ),
-      );
-
-    const session = yield* verifyWithRetries(0);
-
-    const token = yield* crypto.decryptToken(ecdh, {
-      ciphertext: session.access_token,
-      publicKey: session.public_key,
-      nonce: session.nonce,
-    });
-    // Go returns the raw save error here (`login.go:222-224`) — not the
-    // "cannot save provided token" wrapper used on the token path.
-    yield* credentials.saveAccessToken(token);
-    yield* postLoginTelemetry(token);
-
-    if (output.format !== "text") {
-      yield* output.success("You are now logged in.", { token_name: tokenName });
-      return;
-    }
-    yield* output.raw(`Token ${tokenName} created successfully.\n\n`, "stdout");
-    yield* output.raw(LOGGED_IN_MSG, "stdout");
-    if (claudeHint.length > 0) yield* output.raw(`${claudeHint}\n`, "stderr");
-  });
-
   const body = Effect.gen(function* () {
     // Token resolution priority: --token → SUPABASE_ACCESS_TOKEN → piped stdin
     // (non-TTY only). Matches `cmd/login.go:31-39` + `login.go:236-247`.
@@ -201,7 +80,7 @@ export const legacyLogin = Effect.fn("legacy.login")(function* (flags: LegacyLog
     if (Option.isSome(resolved)) {
       return yield* tokenPath(resolved.value);
     }
-    return yield* browserPath;
+    return yield* legacyBrowserLogin({ openBrowser: !flags.noBrowser, tokenName: flags.name });
   });
 
   // `Effect.tap` runs the profile save only on success (Go's `PostRunE`);
diff --git a/apps/cli/src/legacy/commands/login/login.layers.ts b/apps/cli/src/legacy/commands/login/login.layers.ts
index 4ed14b4295..076ee5245f 100644
--- a/apps/cli/src/legacy/commands/login/login.layers.ts
+++ b/apps/cli/src/legacy/commands/login/login.layers.ts
@@ -7,8 +7,8 @@ import { legacyTelemetryStateLayer } from "../../telemetry/legacy-telemetry-stat
 import { commandRuntimeLayer } from "../../../shared/runtime/command-runtime.layer.ts";
 import { browserLayer } from "../../../shared/runtime/browser.layer.ts";
 import { stdinLayer } from "../../../shared/runtime/stdin.layer.ts";
-import { legacyLoginApiLayer } from "./login-api.layer.ts";
-import { legacyLoginCryptoLayer } from "./login-crypto.layer.ts";
+import { legacyLoginApiLayer } from "../../shared/legacy-login-api.layer.ts";
+import { legacyLoginCryptoLayer } from "../../shared/legacy-login-crypto.layer.ts";
 
 // `login` is the only command that writes the access token, so it builds its own
 // lean runtime instead of `legacyManagementApiRuntimeLayer` — it must NOT eagerly
diff --git a/apps/cli/src/legacy/commands/projects/api-keys/api-keys.handler.ts b/apps/cli/src/legacy/commands/projects/api-keys/api-keys.handler.ts
index 4eb3908984..2453c67583 100644
--- a/apps/cli/src/legacy/commands/projects/api-keys/api-keys.handler.ts
+++ b/apps/cli/src/legacy/commands/projects/api-keys/api-keys.handler.ts
@@ -1,42 +1,29 @@
 import type { V1GetProjectApiKeysOutput } from "@supabase/api/effect";
 import { Effect, Option } from "effect";
 
-import { LegacyPlatformApi } from "../../../auth/legacy-platform-api.service.ts";
 import { LegacyProjectRefResolver } from "../../../config/legacy-project-ref.service.ts";
 import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
 import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
 import { LegacyOutputFlag } from "../../../../shared/legacy/global-flags.ts";
 import { Output } from "../../../../shared/output/output.service.ts";
 import { apiKeysToEnv } from "../../../shared/legacy-api-keys.format.ts";
+import { legacyGetProjectApiKeys } from "../../../shared/legacy-get-api-keys.ts";
 import {
   encodeEnv,
   encodeGoJson,
   encodeToml,
   encodeYaml,
 } from "../../../shared/legacy-go-output.encoders.ts";
-import { mapLegacyHttpError } from "../../../shared/legacy-http-errors.ts";
-import {
-  LegacyProjectsApiKeysNetworkError,
-  LegacyProjectsApiKeysUnexpectedStatusError,
-} from "../projects.errors.ts";
 import { renderProjectApiKeysTable } from "../projects.format.ts";
 import type { LegacyProjectsApiKeysFlags } from "./api-keys.command.ts";
 
 type ApiKeys = typeof V1GetProjectApiKeysOutput.Type;
 
-const mapApiKeysError = mapLegacyHttpError({
-  networkError: LegacyProjectsApiKeysNetworkError,
-  statusError: LegacyProjectsApiKeysUnexpectedStatusError,
-  networkMessage: (cause) => `failed to get api keys: ${cause}`,
-  statusMessage: (status, body) => `unexpected get api keys status ${status}: ${body}`,
-});
-
 export const legacyProjectsApiKeys = Effect.fn("legacy.projects.api-keys")(function* (
   flags: LegacyProjectsApiKeysFlags,
 ) {
   const output = yield* Output;
   const goOutputFlag = yield* LegacyOutputFlag;
-  const api = yield* LegacyPlatformApi;
   const resolver = yield* LegacyProjectRefResolver;
   const linkedProjectCache = yield* LegacyLinkedProjectCache;
   const telemetryState = yield* LegacyTelemetryState;
@@ -48,9 +35,8 @@ export const legacyProjectsApiKeys = Effect.fn("legacy.projects.api-keys")(funct
   yield* Effect.gen(function* () {
     const fetching =
       output.format === "text" ? yield* output.task("Fetching API keys...") : undefined;
-    const keys: ApiKeys = yield* api.v1.getProjectApiKeys({ ref }).pipe(
+    const keys: ApiKeys = yield* legacyGetProjectApiKeys(ref).pipe(
       Effect.tapError(() => fetching?.fail() ?? Effect.void),
-      Effect.catch(mapApiKeysError),
     );
     yield* fetching?.clear() ?? Effect.void;
 
diff --git a/apps/cli/src/legacy/commands/projects/create/create.handler.ts b/apps/cli/src/legacy/commands/projects/create/create.handler.ts
index 2e0af17b74..7ad4f783c1 100644
--- a/apps/cli/src/legacy/commands/projects/create/create.handler.ts
+++ b/apps/cli/src/legacy/commands/projects/create/create.handler.ts
@@ -1,52 +1,17 @@
-import { type V1CreateAProjectInput, operationDefinitions } from "@supabase/api/effect";
 import { Effect, Option } from "effect";
 
-import { LegacyPlatformApi } from "../../../auth/legacy-platform-api.service.ts";
-import { LegacyCliConfig } from "../../../config/legacy-cli-config.service.ts";
 import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
 import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
-import { LegacyOutputFlag } from "../../../../shared/legacy/global-flags.ts";
 import { Output } from "../../../../shared/output/output.service.ts";
 import { Tty } from "../../../../shared/runtime/tty.service.ts";
-import {
-  encodeEnv,
-  encodeGoJson,
-  encodeToml,
-  encodeYaml,
-} from "../../../shared/legacy-go-output.encoders.ts";
-import { sanitizeLegacyErrorBody } from "../../../shared/legacy-http-errors.ts";
-import {
-  LegacyProjectsCreateMissingArgError,
-  LegacyProjectsCreateNetworkError,
-  LegacyProjectsCreateUnexpectedStatusError,
-} from "../projects.errors.ts";
-import {
-  dashboardUrlForProfile,
-  readProjectField,
-  renderProjectCreateTable,
-} from "../projects.format.ts";
-import {
-  legacyPromptDbPassword,
-  legacyPromptOrgId,
-  legacyPromptProjectName,
-  legacyPromptProjectRegion,
-} from "../projects.prompt.ts";
+import { legacyProjectCreateCore } from "../../../shared/legacy-project-create-core.ts";
+import { LegacyProjectsCreateMissingArgError } from "../projects.errors.ts";
 import type { LegacyProjectsCreateFlags } from "./create.command.ts";
 
-type CreateInput = typeof V1CreateAProjectInput.Type;
-
-/** Go's `printKeyValue` (`create.go:52-56`): `key` + `:` + pad to width 20 + value. */
-function printKeyValue(key: string, value: string): string {
-  return `${key}:${" ".repeat(Math.max(0, 20 - key.length))}${value}`;
-}
-
 export const legacyProjectsCreate = Effect.fn("legacy.projects.create")(function* (
   flags: LegacyProjectsCreateFlags,
 ) {
   const output = yield* Output;
-  const goOutputFlag = yield* LegacyOutputFlag;
-  const api = yield* LegacyPlatformApi;
-  const cliConfig = yield* LegacyCliConfig;
   const linkedProjectCache = yield* LegacyLinkedProjectCache;
   const telemetryState = yield* LegacyTelemetryState;
   const tty = yield* Tty;
@@ -60,10 +25,10 @@ export const legacyProjectsCreate = Effect.fn("legacy.projects.create")(function
     const interactive = Option.getOrElse(flags.interactive, () => true);
     const effectiveInteractive = interactive && tty.stdinIsTty && output.interactive;
 
-    let name = Option.getOrElse(flags.name, () => "");
-    let orgId = Option.getOrElse(flags.orgId, () => "");
-    let region: CreateInput["region"] = Option.getOrUndefined(flags.region);
-    let dbPassword = Option.getOrElse(flags.dbPassword, () => "");
+    const name = Option.getOrElse(flags.name, () => "");
+    const orgId = Option.getOrElse(flags.orgId, () => "");
+    const region = Option.getOrUndefined(flags.region);
+    const dbPassword = Option.getOrElse(flags.dbPassword, () => "");
     const size = Option.getOrUndefined(flags.size);
 
     // Non-interactive: Go's PreRunE marks `--org-id`, `--db-password`,
@@ -81,99 +46,16 @@ export const legacyProjectsCreate = Effect.fn("legacy.projects.create")(function
       }
     }
 
-    // promptMissingParams (`create.go:58-85`): prompt for each empty value and
-    // echo the resolved value to stderr in text mode.
-    if (name.length === 0) {
-      name = yield* legacyPromptProjectName();
-    } else if (output.format === "text") {
-      yield* output.raw(printKeyValue("Creating project", name) + "\n", "stderr");
-    }
-    if (orgId.length === 0) {
-      orgId = yield* legacyPromptOrgId();
-      if (output.format === "text") {
-        yield* output.raw(printKeyValue("Selected org-id", orgId) + "\n", "stderr");
-      }
-    }
-    if (region === undefined) {
-      const chosenRegion = yield* legacyPromptProjectRegion();
-      region = chosenRegion;
-      if (output.format === "text") {
-        yield* output.raw(printKeyValue("Selected region", chosenRegion) + "\n", "stderr");
-      }
-    }
-    if (dbPassword.length === 0) {
-      dbPassword = yield* legacyPromptDbPassword();
-    }
-
-    const input: CreateInput = {
+    const { ref } = yield* legacyProjectCreateCore({
       name,
-      organization_slug: orgId,
-      db_pass: dbPassword,
-      ...(region !== undefined ? { region } : {}),
-      ...(size !== undefined ? { desired_instance_size: size } : {}),
-    };
-
-    const creating =
-      output.format === "text" ? yield* output.task("Creating project...") : undefined;
-
-    // `executeRaw` sends the body with Go-sorted keys (matching `json.Marshal`)
-    // and skips output decoding: the 201 response's `ref` can be the cli-e2e
-    // `__PROJECT_REF__` placeholder, which the generated schema rejects.
-    const response = yield* api.executeRaw(operationDefinitions.v1CreateAProject, input).pipe(
-      Effect.tapError(() => creating?.fail() ?? Effect.void),
-      Effect.mapError(
-        (cause) =>
-          new LegacyProjectsCreateNetworkError({ message: `failed to create project: ${cause}` }),
-      ),
-    );
-
-    if (response.status !== 201) {
-      const body = sanitizeLegacyErrorBody(
-        yield* response.text.pipe(Effect.orElseSucceed(() => "")),
-      );
-      yield* creating?.fail() ?? Effect.void;
-      return yield* new LegacyProjectsCreateUnexpectedStatusError({
-        status: response.status,
-        body,
-        message: `Unexpected error creating project: ${body}`,
-      });
-    }
-
-    const created = yield* response.json.pipe(Effect.orElseSucceed((): unknown => ({})));
-    yield* creating?.clear() ?? Effect.void;
-
-    const id = readProjectField(created, "id");
-    createdRef = id.length > 0 ? id : undefined;
-
-    // Go prints this to stderr for every output format (`create.go:33-34`).
-    const projectUrl = `${dashboardUrlForProfile(cliConfig.profile)}/project/${id}`;
-    yield* output.raw(`Created a new project at ${projectUrl}\n`, "stderr");
-
-    const goFmt = Option.getOrUndefined(goOutputFlag);
-    if (goFmt === "json") {
-      yield* output.raw(encodeGoJson(created));
-      return;
-    }
-    if (goFmt === "yaml") {
-      yield* output.raw(encodeYaml(created));
-      return;
-    }
-    if (goFmt === "toml") {
-      yield* output.raw(encodeToml(created) + "\n");
-      return;
-    }
-    if (goFmt === "env") {
-      yield* output.raw(encodeEnv(created) + "\n");
-      return;
-    }
-
-    if (output.format === "json" || output.format === "stream-json") {
-      const data = typeof created === "object" && created !== null ? created : {};
-      yield* output.success("Created project", { ...data });
-      return;
-    }
-
-    yield* output.raw(renderProjectCreateTable(created));
+      orgId,
+      dbPassword,
+      region,
+      size,
+      templateUrl: undefined,
+      emitStructuredResult: true,
+    });
+    createdRef = ref.length > 0 ? ref : undefined;
   }).pipe(
     Effect.ensuring(
       Effect.suspend(() =>
diff --git a/apps/cli/src/legacy/shared/legacy-colors.ts b/apps/cli/src/legacy/shared/legacy-colors.ts
new file mode 100644
index 0000000000..5ce368ae44
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-colors.ts
@@ -0,0 +1,22 @@
+import { styleText } from "node:util";
+
+/**
+ * Ports of Go's `utils.Aqua` / `utils.Bold` (`apps/cli-go/internal/utils/colors.go`).
+ *
+ * Go uses lipgloss, which auto-detects the output profile and renders **plain**
+ * text when the stream is not a TTY (piped output, CI, tests). `styleText`
+ * mirrors that: with `validateStream` (the default) it checks the target stream
+ * and `NO_COLOR`, returning the unstyled string when colour is unsupported. We
+ * point it at `process.stderr` because the bootstrap progress / suggestion lines
+ * these style are written to stderr.
+ *
+ * lipgloss colour "14" is bright cyan; `"cyan"` is the closest faithful match,
+ * matching `branches.prompt.ts`'s existing port of `utils.Aqua`.
+ */
+export function legacyAqua(text: string): string {
+  return styleText("cyan", text, { stream: process.stderr });
+}
+
+export function legacyBold(text: string): string {
+  return styleText("bold", text, { stream: process.stderr });
+}
diff --git a/apps/cli/src/legacy/shared/legacy-ensure-login.ts b/apps/cli/src/legacy/shared/legacy-ensure-login.ts
new file mode 100644
index 0000000000..e94aa87a20
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-ensure-login.ts
@@ -0,0 +1,181 @@
+import { Effect, Option } from "effect";
+
+import { LegacyCredentials } from "../auth/legacy-credentials.service.ts";
+import { LegacyCliConfig } from "../config/legacy-cli-config.service.ts";
+import { LegacyTelemetryState } from "../telemetry/legacy-telemetry-state.service.ts";
+import type { NonInteractiveError } from "../../shared/output/errors.ts";
+import { Output } from "../../shared/output/output.service.ts";
+import { Browser } from "../../shared/runtime/browser.service.ts";
+import { Tty } from "../../shared/runtime/tty.service.ts";
+import { Analytics } from "../../shared/telemetry/analytics.service.ts";
+import { withAnalyticsContext } from "../../shared/telemetry/analytics-context.ts";
+import { EventLoginCompleted } from "../../shared/telemetry/event-catalog.ts";
+import {
+  LegacyLoginApi,
+  type LegacyLoginSessionResponse,
+} from "../commands/login/login-api.service.ts";
+import { LegacyLoginCrypto } from "../commands/login/login-crypto.service.ts";
+import { legacySuggestClaudePlugin } from "../commands/login/login-claude-hint.ts";
+import {
+  LegacyLoginFailedError,
+  type LegacyLoginVerificationError,
+} from "../commands/login/login.errors.ts";
+import { legacyDashboardUrl } from "./legacy-profile.ts";
+import { resolveLegacyAccessToken } from "./legacy-resolve-token.ts";
+
+// Go's `maxRetries` (`login.go:130`): the initial probe plus 2 retries (3 total).
+const MAX_LOGIN_RETRIES = 2;
+
+export const LEGACY_LOGGED_IN_MSG = "You are now logged in. Happy coding!\n";
+
+/**
+ * Mirrors Go's `handleTelemetryAfterLogin` (`login.go:273-299`): fetch the gotrue
+ * id (best-effort), stitch or clear the telemetry identity, then always capture
+ * `cli_login_completed`. The capture rides the just-stitched identity so PostHog
+ * attributes it to the user.
+ *
+ * NOTE: Go's `StitchLogin` only *aliases* — it does NOT call `identify`. Do not add
+ * `analytics.identify` here; that is a `next/` behavior and would emit an event Go
+ * never sends. Shared by the token path (`login`) and the browser flow.
+ */
+export const legacyPostLoginTelemetry = Effect.fnUntraced(function* (token: string) {
+  const loginApi = yield* LegacyLoginApi;
+  const telemetryState = yield* LegacyTelemetryState;
+  const analytics = yield* Analytics;
+  const cliConfig = yield* LegacyCliConfig;
+
+  const gotrueId = yield* loginApi.fetchGotrueId(cliConfig.apiUrl, token);
+  if (Option.isSome(gotrueId)) {
+    yield* telemetryState.stitchLogin(gotrueId.value);
+    yield* analytics
+      .capture(EventLoginCompleted)
+      .pipe(withAnalyticsContext({ distinct_id: gotrueId.value }));
+  } else {
+    yield* telemetryState.clearDistinctId;
+    yield* analytics.capture(EventLoginCompleted);
+  }
+});
+
+export interface LegacyBrowserLoginOptions {
+  /** When true, prompt + open the browser; when false, just print the login link. */
+  readonly openBrowser: boolean;
+  /** Token name (Go's `--name`); `None` falls back to the generated default. */
+  readonly tokenName: Option.Option<string>;
+}
+
+/**
+ * The interactive browser login flow, extracted from `login`'s handler so
+ * `bootstrap` can reuse it: generate an ECDH keypair, surface the dashboard
+ * login link (optionally opening the browser), poll for the verification code
+ * with Go's retry/notify cadence, decrypt + persist the token, then run the
+ * post-login telemetry and print the success banners. Owns the single
+ * `cli_login_completed` capture for this path.
+ */
+export const legacyBrowserLogin = Effect.fnUntraced(function* (opts: LegacyBrowserLoginOptions) {
+  const output = yield* Output;
+  const crypto = yield* LegacyLoginCrypto;
+  const loginApi = yield* LegacyLoginApi;
+  const credentials = yield* LegacyCredentials;
+  const cliConfig = yield* LegacyCliConfig;
+  const browser = yield* Browser;
+  const tty = yield* Tty;
+
+  const claudeHint = legacySuggestClaudePlugin({ stdoutIsTty: tty.stdoutIsTty });
+  const apiHost = cliConfig.apiUrl;
+
+  const { ecdh, publicKeyHex } = yield* crypto.generateKeyPair;
+  const sessionId = yield* crypto.generateSessionId;
+  const tokenName = Option.isSome(opts.tokenName)
+    ? opts.tokenName.value
+    : yield* crypto.defaultTokenName;
+
+  // Go concatenates the query string without URL-encoding (`login.go:197-198`).
+  const loginUrl =
+    `${legacyDashboardUrl(cliConfig.profile)}/cli/login` +
+    `?session_id=${sessionId}&token_name=${tokenName}&public_key=${publicKeyHex}`;
+
+  // The banners are human-facing text — suppressed in json / stream-json so
+  // stdout stays payload-only. The prompts still run (and fail cleanly with
+  // `NonInteractiveError` in a non-interactive machine mode).
+  const isText = output.format === "text";
+  if (opts.openBrowser) {
+    if (isText) {
+      yield* output.raw(
+        "Hello from Supabase! Press Enter to open browser and login automatically.\n",
+        "stdout",
+      );
+    }
+    yield* output.promptText("");
+    if (isText) {
+      yield* output.raw(
+        `Here is your login link in case browser did not open ${loginUrl}\n\n`,
+        "stdout",
+      );
+    }
+    yield* Effect.ignore(browser.open(loginUrl));
+  } else if (isText) {
+    yield* output.raw(`Here is your login link, open it in the browser ${loginUrl}\n\n`, "stdout");
+  }
+
+  // Verify + retry, mirroring Go's `pollForAccessToken` backoff
+  // (`login.go:132-166`): the notifier prints `<err>\nRetry (n/2): ` after the
+  // first 2 failures; the 3rd failure gives up without a notice.
+  const verifyWithRetries = (
+    failuresSoFar: number,
+  ): Effect.Effect<
+    LegacyLoginSessionResponse,
+    LegacyLoginFailedError | NonInteractiveError,
+    Output | LegacyLoginApi
+  > =>
+    Effect.gen(function* () {
+      const code = yield* output.promptText("Enter your verification code: ", {
+        validate: (v) => (v.trim().length > 0 ? undefined : "Verification code is required"),
+      });
+      return yield* loginApi.fetchLoginSession(apiHost, sessionId, code.trim());
+    }).pipe(
+      Effect.catchTag("LegacyLoginVerificationError", (err: LegacyLoginVerificationError) =>
+        Effect.gen(function* () {
+          const failures = failuresSoFar + 1;
+          if (failures > MAX_LOGIN_RETRIES) {
+            return yield* Effect.fail(new LegacyLoginFailedError({ message: err.message }));
+          }
+          yield* output.raw(`${err.message}\nRetry (${failures}/${MAX_LOGIN_RETRIES}): `, "stderr");
+          return yield* verifyWithRetries(failures);
+        }),
+      ),
+    );
+
+  const session = yield* verifyWithRetries(0);
+
+  const token = yield* crypto.decryptToken(ecdh, {
+    ciphertext: session.access_token,
+    publicKey: session.public_key,
+    nonce: session.nonce,
+  });
+  // Go returns the raw save error here (`login.go:222-224`) — not the
+  // "cannot save provided token" wrapper used on the token path.
+  yield* credentials.saveAccessToken(token);
+  yield* legacyPostLoginTelemetry(token);
+
+  if (output.format !== "text") {
+    yield* output.success("You are now logged in.", { token_name: tokenName });
+    return;
+  }
+  yield* output.raw(`Token ${tokenName} created successfully.\n\n`, "stdout");
+  yield* output.raw(LEGACY_LOGGED_IN_MSG, "stdout");
+  if (claudeHint.length > 0) yield* output.raw(`${claudeHint}\n`, "stderr");
+});
+
+/**
+ * Ensures a Management API access token exists. Mirrors Go's `bootstrap` login
+ * step (`bootstrap.go:67-77`): if a token is already resolvable (env / keyring /
+ * file) it is a no-op; otherwise the browser login flow runs and fires
+ * `cli_login_completed` once.
+ */
+export const legacyEnsureLogin = Effect.fnUntraced(function* (opts: { openBrowser: boolean }) {
+  const existing = yield* resolveLegacyAccessToken;
+  if (Option.isSome(existing)) {
+    return;
+  }
+  yield* legacyBrowserLogin({ openBrowser: opts.openBrowser, tokenName: Option.none() });
+});
diff --git a/apps/cli/src/legacy/shared/legacy-get-api-keys.ts b/apps/cli/src/legacy/shared/legacy-get-api-keys.ts
new file mode 100644
index 0000000000..cd60147229
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-get-api-keys.ts
@@ -0,0 +1,33 @@
+import type { V1GetProjectApiKeysOutput } from "@supabase/api/effect";
+import { Effect } from "effect";
+
+import { LegacyPlatformApi } from "../auth/legacy-platform-api.service.ts";
+import {
+  LegacyProjectsApiKeysNetworkError,
+  LegacyProjectsApiKeysUnexpectedStatusError,
+} from "../commands/projects/projects.errors.ts";
+import { mapLegacyHttpError } from "./legacy-http-errors.ts";
+
+type ApiKeys = typeof V1GetProjectApiKeysOutput.Type;
+
+const mapApiKeysError = mapLegacyHttpError({
+  networkError: LegacyProjectsApiKeysNetworkError,
+  statusError: LegacyProjectsApiKeysUnexpectedStatusError,
+  networkMessage: (cause) => `failed to get api keys: ${cause}`,
+  statusMessage: (status, body) => `unexpected get api keys status ${status}: ${body}`,
+});
+
+/**
+ * Ports Go's `apiKeys.RunGetApiKeys` (`apps/cli-go/internal/projects/apiKeys/api_keys.go:41-49`):
+ * `GET /v1/projects/{ref}/api-keys` with no `reveal` param, mapping transport /
+ * non-200 failures to the same `failed to get api keys` / `unexpected get api keys
+ * status` errors Go raises. Shared by `projects api-keys` (display) and `bootstrap`
+ * (which derives the `.env` keys).
+ */
+export const legacyGetProjectApiKeys = Effect.fnUntraced(function* (ref: string) {
+  const api = yield* LegacyPlatformApi;
+  const keys: ApiKeys = yield* api.v1
+    .getProjectApiKeys({ ref })
+    .pipe(Effect.catch(mapApiKeysError));
+  return keys;
+});
diff --git a/apps/cli/src/legacy/shared/legacy-link-services-core.ts b/apps/cli/src/legacy/shared/legacy-link-services-core.ts
new file mode 100644
index 0000000000..4885c21e3d
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-link-services-core.ts
@@ -0,0 +1,126 @@
+import type { ApiClient } from "@supabase/api/effect";
+import { Effect, FileSystem, Option, Path } from "effect";
+import type { PlatformError } from "effect/PlatformError";
+
+import { LegacyCliConfig } from "../config/legacy-cli-config.service.ts";
+import { LegacyPlatformApi } from "../auth/legacy-platform-api.service.ts";
+import { legacyTempPaths } from "./legacy-temp-paths.ts";
+import {
+  legacyFetchGotrueVersion,
+  legacyFetchPostgrestVersion,
+  legacyFetchStorageVersion,
+} from "./legacy-tenant-versions.ts";
+
+export interface LegacyLinkServicesInput {
+  readonly ref: string;
+  /**
+   * Tenant API key used for the service version probes. `link` passes the
+   * service-role key; `bootstrap` passes the anon key (mirroring Go's
+   * `link.LinkServices(ctx, ref, tenant.NewApiKey(keys).Anon, …)`).
+   */
+  readonly serviceKey: string;
+  readonly skipPooler: boolean;
+  /**
+   * Absolute project directory whose `supabase/.temp/*` files receive the linked
+   * service metadata. Passed explicitly (never read from `LegacyCliConfig.workdir`)
+   * because `bootstrap` links a freshly created project directory that differs
+   * from the cwd-walked config workdir.
+   */
+  readonly workdir: string;
+}
+
+type WriteTempFile = (filePath: string, content: string) => Effect.Effect<void, PlatformError>;
+
+/**
+ * Ports Go's `link.LinkServices` (`apps/cli-go/internal/link/link.go:71-103`): the
+ * best-effort portion of linking that writes `supabase/.temp/{storage-migration,
+ * pooler-url,rest-version,gotrue-version,storage-version}`. Every probe is
+ * best-effort — a single unreachable service never fails the caller. This core
+ * does NOT write `project-ref`, the linked-project cache, or fire
+ * `cli_project_linked`; `link.Run` (the standalone command) owns those, and Go's
+ * `bootstrap` deliberately skips them by calling `LinkServices` directly.
+ */
+export const legacyLinkServicesCore = Effect.fnUntraced(function* (input: LegacyLinkServicesInput) {
+  const api = yield* LegacyPlatformApi;
+  const cliConfig = yield* LegacyCliConfig;
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const paths = legacyTempPaths(path, input.workdir);
+
+  const writeTempFile: WriteTempFile = (filePath, content) =>
+    fs
+      .makeDirectory(path.dirname(filePath), { recursive: true })
+      .pipe(Effect.andThen(() => fs.writeFileString(filePath, content)));
+
+  yield* linkStorageMigration(api, input.ref, paths.storageMigration, writeTempFile);
+  yield* linkPooler({
+    api,
+    ref: input.ref,
+    skipPooler: input.skipPooler,
+    fs,
+    poolerUrlPath: paths.poolerUrl,
+    writeTempFile,
+  });
+
+  const tenantOpts = {
+    ref: input.ref,
+    projectHost: cliConfig.projectHost,
+    serviceKey: input.serviceKey,
+    userAgent: cliConfig.userAgent,
+  };
+  yield* legacyFetchPostgrestVersion(tenantOpts).pipe(
+    Effect.flatMap((v) =>
+      Option.isSome(v) ? writeTempFile(paths.restVersion, v.value) : Effect.void,
+    ),
+    Effect.ignore,
+  );
+  yield* legacyFetchGotrueVersion(tenantOpts).pipe(
+    Effect.flatMap((v) =>
+      Option.isSome(v) ? writeTempFile(paths.gotrueVersion, v.value) : Effect.void,
+    ),
+    Effect.ignore,
+  );
+  yield* legacyFetchStorageVersion(tenantOpts).pipe(
+    Effect.flatMap((v) =>
+      Option.isSome(v) ? writeTempFile(paths.storageVersion, v.value) : Effect.void,
+    ),
+    Effect.ignore,
+  );
+});
+
+const linkStorageMigration = (
+  api: ApiClient,
+  ref: string,
+  storageMigrationPath: string,
+  writeTempFile: WriteTempFile,
+) =>
+  api.v1.getStorageConfig({ ref }).pipe(
+    Effect.flatMap((config) => writeTempFile(storageMigrationPath, config.migrationVersion)),
+    Effect.ignore,
+  );
+
+const linkPooler = (opts: {
+  api: ApiClient;
+  ref: string;
+  skipPooler: boolean;
+  fs: FileSystem.FileSystem;
+  poolerUrlPath: string;
+  writeTempFile: WriteTempFile;
+}) =>
+  Effect.gen(function* () {
+    if (opts.skipPooler) {
+      // Use direct connection: drop any cached pooler URL (link.go:81-84).
+      yield* opts.fs.remove(opts.poolerUrlPath, { recursive: true }).pipe(Effect.ignore);
+      return;
+    }
+    const configs = yield* opts.api.v1.getPoolerConfig({ ref: opts.ref });
+    const primary = configs.find((c) => c.database_type === "PRIMARY");
+    if (primary === undefined) return;
+    // Strip the [YOUR-PASSWORD] placeholder; force session mode 5432 unless the
+    // pooler already reports session mode (link.go:221-229).
+    let connectionString = primary.connection_string.replaceAll(":[YOUR-PASSWORD]", "");
+    if (primary.pool_mode !== "session") {
+      connectionString = connectionString.replaceAll(":6543/", ":5432/");
+    }
+    yield* opts.writeTempFile(opts.poolerUrlPath, connectionString);
+  }).pipe(Effect.ignore);
diff --git a/apps/cli/src/legacy/commands/login/login-api.layer.ts b/apps/cli/src/legacy/shared/legacy-login-api.layer.ts
similarity index 92%
rename from apps/cli/src/legacy/commands/login/login-api.layer.ts
rename to apps/cli/src/legacy/shared/legacy-login-api.layer.ts
index 78d2eaa9fd..d40f47524b 100644
--- a/apps/cli/src/legacy/commands/login/login-api.layer.ts
+++ b/apps/cli/src/legacy/shared/legacy-login-api.layer.ts
@@ -2,9 +2,12 @@ import { Effect, Layer, Option } from "effect";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 
-import { LegacyCliConfig } from "../../config/legacy-cli-config.service.ts";
-import { LegacyLoginApi, type LegacyLoginSessionResponse } from "./login-api.service.ts";
-import { LegacyLoginVerificationError } from "./login.errors.ts";
+import { LegacyCliConfig } from "../config/legacy-cli-config.service.ts";
+import {
+  LegacyLoginApi,
+  type LegacyLoginSessionResponse,
+} from "../commands/login/login-api.service.ts";
+import { LegacyLoginVerificationError } from "../commands/login/login.errors.ts";
 
 const POLL_TIMEOUT = "10 seconds";
 
diff --git a/apps/cli/src/legacy/commands/login/login-crypto.layer.ts b/apps/cli/src/legacy/shared/legacy-login-crypto.layer.ts
similarity index 93%
rename from apps/cli/src/legacy/commands/login/login-crypto.layer.ts
rename to apps/cli/src/legacy/shared/legacy-login-crypto.layer.ts
index c63eeac9b6..854626808d 100644
--- a/apps/cli/src/legacy/commands/login/login-crypto.layer.ts
+++ b/apps/cli/src/legacy/shared/legacy-login-crypto.layer.ts
@@ -3,8 +3,11 @@ import { createDecipheriv, createECDH, randomUUID, type ECDH } from "node:crypto
 import { hostname, userInfo } from "node:os";
 import { Effect, Layer } from "effect";
 
-import { LegacyLoginCrypto, type LegacyEncryptedPayload } from "./login-crypto.service.ts";
-import { LegacyLoginCryptoError, LegacyLoginDecryptError } from "./login.errors.ts";
+import {
+  LegacyLoginCrypto,
+  type LegacyEncryptedPayload,
+} from "../commands/login/login-crypto.service.ts";
+import { LegacyLoginCryptoError, LegacyLoginDecryptError } from "../commands/login/login.errors.ts";
 
 const DECRYPTION_ERROR_MSG = "cannot decrypt access token";
 
diff --git a/apps/cli/src/legacy/shared/legacy-project-create-core.ts b/apps/cli/src/legacy/shared/legacy-project-create-core.ts
new file mode 100644
index 0000000000..fd1c3c6b4f
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-project-create-core.ts
@@ -0,0 +1,167 @@
+import { type V1CreateAProjectInput, operationDefinitions } from "@supabase/api/effect";
+import { Effect, Option } from "effect";
+
+import { LegacyPlatformApi } from "../auth/legacy-platform-api.service.ts";
+import { LegacyCliConfig } from "../config/legacy-cli-config.service.ts";
+import { LegacyOutputFlag } from "../../shared/legacy/global-flags.ts";
+import { Output } from "../../shared/output/output.service.ts";
+import { encodeEnv, encodeGoJson, encodeToml, encodeYaml } from "./legacy-go-output.encoders.ts";
+import { sanitizeLegacyErrorBody } from "./legacy-http-errors.ts";
+import {
+  LegacyProjectsCreateNetworkError,
+  LegacyProjectsCreateUnexpectedStatusError,
+} from "../commands/projects/projects.errors.ts";
+import {
+  dashboardUrlForProfile,
+  readProjectField,
+  renderProjectCreateTable,
+} from "../commands/projects/projects.format.ts";
+import {
+  legacyPromptDbPassword,
+  legacyPromptOrgId,
+  legacyPromptProjectName,
+  legacyPromptProjectRegion,
+} from "../commands/projects/projects.prompt.ts";
+
+type CreateInput = typeof V1CreateAProjectInput.Type;
+
+export interface LegacyProjectCreateInput {
+  readonly name: string;
+  readonly orgId: string;
+  readonly dbPassword: string;
+  readonly region: CreateInput["region"];
+  readonly size: CreateInput["desired_instance_size"];
+  readonly templateUrl: string | undefined;
+  /**
+   * Standalone `projects create` emits a `--output-format` json/stream-json
+   * success result; `bootstrap` suppresses it (it emits its own top-level
+   * result), matching Go's `create.Run` which only ever echoes via `-o`.
+   */
+  readonly emitStructuredResult: boolean;
+}
+
+/** Go's `printKeyValue` (`create.go`): `key` + `:` + pad to width 20 + value. */
+function printKeyValue(key: string, value: string): string {
+  return `${key}:${" ".repeat(Math.max(0, 20 - key.length))}${value}`;
+}
+
+/**
+ * Ports Go's `create.Run` (`apps/cli-go/internal/projects/create/create.go:16-50`):
+ * `promptMissingParams` (prompt for / echo each empty field), `POST /v1/projects`,
+ * and the project echo (`Created a new project at …` plus the `-o`/pretty render).
+ *
+ * Returns the created ref + the resolved db password (Go stores both globally via
+ * `flags.ProjectRef` / `viper.Set("DB_PASSWORD", …)`). Does NOT validate required
+ * flags (that is the standalone command's cobra PreRunE) and does NOT write the
+ * linked-project cache (the caller owns that via `Effect.ensuring`).
+ */
+export const legacyProjectCreateCore = Effect.fnUntraced(function* (
+  input: LegacyProjectCreateInput,
+) {
+  const output = yield* Output;
+  const goOutputFlag = yield* LegacyOutputFlag;
+  const api = yield* LegacyPlatformApi;
+  const cliConfig = yield* LegacyCliConfig;
+
+  let name = input.name;
+  let orgId = input.orgId;
+  let region: CreateInput["region"] = input.region;
+  let dbPassword = input.dbPassword;
+  const size = input.size;
+
+  // promptMissingParams (`create.go:58-85`): prompt for each empty value and
+  // echo the resolved value to stderr in text mode.
+  if (name.length === 0) {
+    name = yield* legacyPromptProjectName();
+  } else if (output.format === "text") {
+    yield* output.raw(printKeyValue("Creating project", name) + "\n", "stderr");
+  }
+  if (orgId.length === 0) {
+    orgId = yield* legacyPromptOrgId();
+    if (output.format === "text") {
+      yield* output.raw(printKeyValue("Selected org-id", orgId) + "\n", "stderr");
+    }
+  }
+  if (region === undefined) {
+    const chosenRegion = yield* legacyPromptProjectRegion();
+    region = chosenRegion;
+    if (output.format === "text") {
+      yield* output.raw(printKeyValue("Selected region", chosenRegion) + "\n", "stderr");
+    }
+  }
+  if (dbPassword.length === 0) {
+    dbPassword = yield* legacyPromptDbPassword();
+  }
+
+  const body: CreateInput = {
+    name,
+    organization_slug: orgId,
+    db_pass: dbPassword,
+    ...(region !== undefined ? { region } : {}),
+    ...(size !== undefined ? { desired_instance_size: size } : {}),
+    ...(input.templateUrl !== undefined ? { template_url: input.templateUrl } : {}),
+  };
+
+  const creating = output.format === "text" ? yield* output.task("Creating project...") : undefined;
+
+  // `executeRaw` sends the body with Go-sorted keys (matching `json.Marshal`)
+  // and skips output decoding: the 201 response's `ref` can be the cli-e2e
+  // `__PROJECT_REF__` placeholder, which the generated schema rejects.
+  const response = yield* api.executeRaw(operationDefinitions.v1CreateAProject, body).pipe(
+    Effect.tapError(() => creating?.fail() ?? Effect.void),
+    Effect.mapError(
+      (cause) =>
+        new LegacyProjectsCreateNetworkError({ message: `failed to create project: ${cause}` }),
+    ),
+  );
+
+  if (response.status !== 201) {
+    const errorBody = sanitizeLegacyErrorBody(
+      yield* response.text.pipe(Effect.orElseSucceed(() => "")),
+    );
+    yield* creating?.fail() ?? Effect.void;
+    return yield* new LegacyProjectsCreateUnexpectedStatusError({
+      status: response.status,
+      body: errorBody,
+      message: `Unexpected error creating project: ${errorBody}`,
+    });
+  }
+
+  const created = yield* response.json.pipe(Effect.orElseSucceed((): unknown => ({})));
+  yield* creating?.clear() ?? Effect.void;
+
+  const id = readProjectField(created, "id");
+
+  // Go prints this to stderr for every output format (`create.go:33-34`).
+  const projectUrl = `${dashboardUrlForProfile(cliConfig.profile)}/project/${id}`;
+  yield* output.raw(`Created a new project at ${projectUrl}\n`, "stderr");
+
+  const goFmt = Option.getOrUndefined(goOutputFlag);
+  if (goFmt === "json") {
+    yield* output.raw(encodeGoJson(created));
+    return { ref: id, dbPassword };
+  }
+  if (goFmt === "yaml") {
+    yield* output.raw(encodeYaml(created));
+    return { ref: id, dbPassword };
+  }
+  if (goFmt === "toml") {
+    yield* output.raw(encodeToml(created) + "\n");
+    return { ref: id, dbPassword };
+  }
+  if (goFmt === "env") {
+    yield* output.raw(encodeEnv(created) + "\n");
+    return { ref: id, dbPassword };
+  }
+
+  if (output.format === "json" || output.format === "stream-json") {
+    if (input.emitStructuredResult) {
+      const data = typeof created === "object" && created !== null ? created : {};
+      yield* output.success("Created project", { ...data });
+    }
+    return { ref: id, dbPassword };
+  }
+
+  yield* output.raw(renderProjectCreateTable(created));
+  return { ref: id, dbPassword };
+});
diff --git a/apps/cli/src/legacy/shared/legacy-tenant-keys.ts b/apps/cli/src/legacy/shared/legacy-tenant-keys.ts
new file mode 100644
index 0000000000..1ec93343b6
--- /dev/null
+++ b/apps/cli/src/legacy/shared/legacy-tenant-keys.ts
@@ -0,0 +1,43 @@
+export interface LegacyApiKeyEntry {
+  readonly api_key?: string | null;
+  readonly type?: string | null;
+  readonly name: string;
+  readonly secret_jwt_template?: Record<string, unknown> | null;
+}
+
+/**
+ * Mirrors `tenant.NewApiKey` (`apps/cli-go/internal/utils/tenant/client.go:28-57`):
+ * `publishable` -> anon, `secret` with `role=service_role` -> service_role, else the
+ * legacy name-based fallback (`anon` / `service_role`).
+ *
+ * Shared by `link` (which writes the service-role key into `.temp` version probes)
+ * and `bootstrap` (which derives the anon key for the generated `.env`).
+ */
+export function legacyExtractServiceKeys(keys: ReadonlyArray<LegacyApiKeyEntry>): {
+  readonly anon: string;
+  readonly serviceRole: string;
+} {
+  let anon = "";
+  let serviceRole = "";
+  for (const key of keys) {
+    const value = key.api_key;
+    if (value === undefined || value === null) continue;
+    if (key.type === "publishable") {
+      anon = value;
+      continue;
+    }
+    if (key.type === "secret") {
+      const role = key.secret_jwt_template?.["role"];
+      if (typeof role === "string" && role.toLowerCase() === "service_role") {
+        serviceRole = value;
+      }
+      continue;
+    }
+    if (key.name === "anon" && anon.length === 0) {
+      anon = value;
+    } else if (key.name === "service_role" && serviceRole.length === 0) {
+      serviceRole = value;
+    }
+  }
+  return { anon, serviceRole };
+}

From dbb69fb436d7a0cff3d479b288964192f122b557 Mon Sep 17 00:00:00 2001
From: Colum Ferry <cferry09@gmail.com>
Date: Fri, 5 Jun 2026 10:06:35 +0100
Subject: [PATCH 2/2] fix(cli): address bootstrap port review feedback

Resolve the review comments on the native bootstrap port:

- Retry backoff now reproduces Go's full cenkalti policy (3s initial,
  factor 1.5, 60s max interval, +/-50% jitter, 15m max elapsed, 8 retries)
  and the NewErrorCallback "Retry (n/8)" notice (debug logger for failures
  1-2, stderr from 3 on, none on the final attempt). Extracted to
  bootstrap.retry.ts.
- linked-project.json now resolves against the bootstrap-resolved workdir
  via an optional LegacyLinkedProjectCache.cache(ref, workdir?) override,
  so it lands beside project-ref on the prompt path instead of
  cliConfig.workdir.
- Template download: segment-aware root prefix stripping and an explicit
  guard for null/empty GitHub download_url (files >1MB / submodules).
- Provide legacyDebugLoggerLayer to the bootstrap runtime base layers,
  fixing a "Service not found: DebugLogger" panic at the first HTTP call
  that the mocked integration tests could not catch.
---
 .../legacy/commands/bootstrap/SIDE_EFFECTS.md |  28 +--
 .../commands/bootstrap/bootstrap.handler.ts   |  30 ++-
 .../bootstrap/bootstrap.integration.test.ts   |   3 +
 .../commands/bootstrap/bootstrap.layers.ts    |  17 +-
 .../commands/bootstrap/bootstrap.retry.ts     |  77 ++++++++
 .../bootstrap/bootstrap.retry.unit.test.ts    | 125 ++++++++++++
 .../commands/bootstrap/bootstrap.templates.ts |  25 ++-
 ...ootstrap.workdir-cache.integration.test.ts | 184 ++++++++++++++++++
 .../legacy-linked-project-cache.layer.ts      |   4 +-
 .../legacy-linked-project-cache.service.ts    |   8 +-
 10 files changed, 468 insertions(+), 33 deletions(-)
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.unit.test.ts
 create mode 100644 apps/cli/src/legacy/commands/bootstrap/bootstrap.workdir-cache.integration.test.ts

diff --git a/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md b/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md
index c43ac9d168..7a4ff00269 100644
--- a/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md
+++ b/apps/cli/src/legacy/commands/bootstrap/SIDE_EFFECTS.md
@@ -15,15 +15,15 @@ health poll → write `.env` → `db push` → start suggestion. Every step is n
 
 ## Files Written
 
-| Path                                                                                                  | Format     | When                                                       |
-| ----------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------- |
-| `<workdir>/supabase/config.toml`                                                                      | TOML       | blank/`scratch` path only (via `initProject`)              |
-| `<workdir>/<template files>`                                                                          | varies     | template path only (GitHub download)                       |
-| `<workdir>/supabase/.temp/project-ref`                                                                | plain text | always (mandatory; fails the command on write error)       |
-| `<workdir>/supabase/.temp/{pooler-url,rest-version,gotrue-version,storage-version,storage-migration}` | plain text | best-effort, from `link.LinkServices`                      |
-| `<workdir>/.env`                                                                                      | dotenv     | best-effort (write failure prints a warning and continues) |
-| `~/.supabase/<workdir-hash>/linked-project.json`                                                      | JSON       | PersistentPostRun linked-project cache (`Effect.ensuring`) |
-| `~/.supabase/telemetry.json`                                                                          | JSON       | PersistentPostRun telemetry flush (`Effect.ensuring`)      |
+| Path                                                                                                  | Format     | When                                                                                                                                                              |
+| ----------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<workdir>/supabase/config.toml`                                                                      | TOML       | blank/`scratch` path only (via `initProject`)                                                                                                                     |
+| `<workdir>/<template files>`                                                                          | varies     | template path only (GitHub download)                                                                                                                              |
+| `<workdir>/supabase/.temp/project-ref`                                                                | plain text | always (mandatory; fails the command on write error)                                                                                                              |
+| `<workdir>/supabase/.temp/{pooler-url,rest-version,gotrue-version,storage-version,storage-migration}` | plain text | best-effort, from `link.LinkServices`                                                                                                                             |
+| `<workdir>/.env`                                                                                      | dotenv     | best-effort (write failure prints a warning and continues)                                                                                                        |
+| `<workdir>/supabase/.temp/linked-project.json`                                                        | JSON       | PersistentPostRun linked-project cache (`Effect.ensuring`); resolves against the bootstrap workdir (the prompted/`--workdir`/env target), not `cliConfig.workdir` |
+| `~/.supabase/telemetry.json`                                                                          | JSON       | PersistentPostRun telemetry flush (`Effect.ensuring`)                                                                                                             |
 
 **Process side effect:** `process.chdir(<workdir>)` mirrors Go's `ChangeWorkDir` and prints
 `Using workdir <workdir>\n` to stderr (`workdir` bolded on a TTY). The original cwd is restored
@@ -108,8 +108,12 @@ Human banners are suppressed; a single structured result is emitted:
   lifetime of that subprocess (Go runs `push.Run` in-process and never exposes it). The same
   password is already written in plaintext to `<workdir>/.env` in the same directory, so the
   incremental exposure is small; it is eliminated when `db push` is natively ported (no subprocess).
-- The api-keys and health retries use exponential backoff (3s initial, 8 retries), matching Go's
-  `utils.NewBackoffPolicy`. The per-attempt `Linking project…` / `Checking project health…` lines
-  are reproduced; Go's debug-only `Retry (n/8):` notifier is not.
+- The api-keys and health retries use the full Go `utils.NewBackoffPolicy` policy: exponential
+  backoff, 3s initial interval, multiplier 1.5, 60s max interval (capped before jitter), ±50% jitter
+  (randomization factor 0.5), 15m max-elapsed cap, and 8 retries (9 total attempts). The per-attempt
+  `Linking project…` / `Checking project health…` lines are reproduced, **and** Go's
+  `NewErrorCallback` notice — `<err>\nRetry (n/8): ` after each failed attempt — is reproduced:
+  failures 1-2 go to the debug logger (shown only under `--debug`), failures 3+ to stderr; the final
+  exhausted attempt prints no notice (matches `backoff.RetryNotify`).
 - `Downloading:` / progress banners are gated to text mode to keep machine stdout payload-only
   (CLI-1546).
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts
index 2bae1c1c9f..42111b30ee 100644
--- a/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.handler.ts
@@ -28,6 +28,11 @@ import {
 } from "./bootstrap.errors.ts";
 import { deriveDbConfig } from "./bootstrap.pgconfig.ts";
 import { suggestAppStart } from "./bootstrap.suggest.ts";
+import {
+  LEGACY_BOOTSTRAP_MAX_RETRIES,
+  legacyBootstrapBackoff,
+  legacyBootstrapRetryNotify,
+} from "./bootstrap.retry.ts";
 import { type LegacyStarterTemplate, LegacyTemplateService } from "./bootstrap.templates.ts";
 import type { LegacyBootstrapFlags } from "./bootstrap.command.ts";
 
@@ -39,14 +44,9 @@ const SCRATCH_TEMPLATE: LegacyStarterTemplate = {
   start: "supabase start",
 };
 
-// Go's `utils.NewBackoffPolicy`: exponential backoff, 3s initial interval,
-// `maxRetries = 8` (`internal/utils/retry.go`). Injectable so tests run fast.
-const LEGACY_BOOTSTRAP_MAX_RETRIES = 8;
-const legacyBootstrapBackoff = Schedule.exponential("3 seconds");
-
 export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
   flags: LegacyBootstrapFlags,
-  retrySchedule: typeof legacyBootstrapBackoff = legacyBootstrapBackoff,
+  retrySchedule: Schedule.Schedule<unknown> = legacyBootstrapBackoff,
 ) {
   const output = yield* Output;
   const tty = yield* Tty;
@@ -70,6 +70,10 @@ export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
   // while leaving the surrounding process untouched.
   const originalCwd = process.cwd();
   let createdRef: string | undefined;
+  // Resolved bootstrap workdir, hoisted so the linked-project-cache finalizer writes
+  // beside the other `supabase/.temp/` files instead of `cliConfig.workdir`. Go achieves
+  // this by re-running `flags.LoadConfig` after `ChangeWorkDir` (`bootstrap.go:98-100`).
+  let resolvedWorkdir: string | undefined;
 
   yield* Effect.gen(function* () {
     // A. Resolve workdir (flag -> env -> prompt -> cwd). `bootstrap.go:30-40`.
@@ -88,6 +92,7 @@ export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
     const workdir = path.isAbsolute(workdirInput)
       ? workdirInput
       : path.join(runtimeInfo.cwd, workdirInput);
+    resolvedWorkdir = workdir;
 
     // B. List templates + resolve the starter. `bootstrap.go:38-58` / `cmd:25-58`.
     const samples = yield* templateService.listSamples;
@@ -177,11 +182,13 @@ export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
     createdRef = projectRef.length > 0 ? projectRef : undefined;
 
     // H. Fetch api keys with backoff; each attempt prints "Linking project...".
-    // `bootstrap.go:88-97`.
+    // `bootstrap.go:88-97`. The notify wrapper reproduces Go's `NewErrorCallback`
+    // (`<err>\nRetry (n/8):` after each failed attempt); a fresh counter per block.
+    const apiKeysNotify = legacyBootstrapRetryNotify();
     const keys = yield* Effect.gen(function* () {
       if (isText) yield* output.raw("Linking project...\n", "stderr");
       return yield* legacyGetProjectApiKeys(projectRef);
-    }).pipe(Effect.retry(retry));
+    }).pipe(apiKeysNotify, Effect.retry(retry));
     const { anon } = legacyExtractServiceKeys(keys);
 
     // I. Link services (best-effort, anon key) + mandatory project-ref write.
@@ -197,6 +204,7 @@ export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
     yield* fs.writeFileString(paths.projectRef, projectRef);
 
     // J. Poll health until db is healthy. `bootstrap.go:106-113`.
+    const healthNotify = legacyBootstrapRetryNotify();
     yield* Effect.gen(function* () {
       if (isText) yield* output.raw("Checking project health...\n", "stderr");
       const services = yield* api.v1
@@ -209,7 +217,7 @@ export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
           });
         }
       }
-    }).pipe(Effect.retry(retry));
+    }).pipe(healthNotify, Effect.retry(retry));
 
     // K. Derive db config + write .env (non-fatal). `bootstrap.go:114-121`.
     const dbConfig = deriveDbConfig(projectRef, created.dbPassword, cliConfig.projectHost);
@@ -274,7 +282,9 @@ export const legacyBootstrap = Effect.fn("legacy.bootstrap")(function* (
     ),
     Effect.ensuring(
       Effect.suspend(() =>
-        createdRef === undefined ? Effect.void : linkedProjectCache.cache(createdRef),
+        createdRef === undefined
+          ? Effect.void
+          : linkedProjectCache.cache(createdRef, resolvedWorkdir),
       ),
     ),
     Effect.ensuring(telemetryState.flush),
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts
index 46cf3e2b54..9988e9d0c1 100644
--- a/apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.integration.test.ts
@@ -27,6 +27,7 @@ import {
   useLegacyTempWorkdir,
 } from "../../../../tests/helpers/legacy-mocks.ts";
 import {
+  LegacyDebugFlag,
   LegacyWorkdirFlag,
   LegacyYesFlag,
   LegacyOutputFlag,
@@ -73,6 +74,7 @@ interface SetupOpts {
   readonly yes?: boolean;
   readonly stdinIsTty?: boolean;
   readonly loggedIn?: boolean;
+  readonly debug?: boolean;
   readonly samples?: ReadonlyArray<LegacyStarterTemplate>;
   readonly apiKeysFailTimes?: number;
   readonly health?: { readonly status: number; readonly body: unknown };
@@ -168,6 +170,7 @@ function setup(opts: SetupOpts = {}) {
     Layer.succeed(LegacyOutputFlag, Option.none()),
     Layer.succeed(LegacyWorkdirFlag, opts.workdir ?? Option.some(tempRoot.current)),
     Layer.succeed(LegacyYesFlag, opts.yes ?? false),
+    Layer.succeed(LegacyDebugFlag, opts.debug ?? false),
   );
 
   return {
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts
index a9f305c2f7..985b88ee2b 100644
--- a/apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.layers.ts
@@ -5,6 +5,7 @@ import { legacyHttpClientLayer } from "../../auth/legacy-http-debug.layer.ts";
 import { legacyPlatformApiLayer } from "../../auth/legacy-platform-api.layer.ts";
 import { legacyCliConfigLayer } from "../../config/legacy-cli-config.layer.ts";
 import { legacyProjectRefLayer } from "../../config/legacy-project-ref.layer.ts";
+import { legacyDebugLoggerLayer } from "../../shared/legacy-debug-logger.layer.ts";
 import { legacyLinkedProjectCacheLayer } from "../../telemetry/legacy-linked-project-cache.layer.ts";
 import { legacyTelemetryStateLayer } from "../../telemetry/legacy-telemetry-state.layer.ts";
 import { commandRuntimeLayer } from "../../../shared/runtime/command-runtime.layer.ts";
@@ -24,14 +25,22 @@ import { legacyTemplateServiceLayer } from "./bootstrap.templates.ts";
 //
 // `Output`, `Analytics`, `Stdio`, `Tty`, `RuntimeInfo`, `ProcessControl`,
 // `LegacyGoProxy`, and `BunServices` (`FileSystem` / `Path` / `ChildProcessSpawner`)
-// come from the root layer (`legacy/cli/root.ts` + `runCli`).
-const cliConfig = legacyCliConfigLayer;
-const httpClient = legacyHttpClientLayer;
-const credentials = legacyCredentialsLayer.pipe(Layer.provide(cliConfig));
+// come from the root layer (`legacy/cli/root.ts` + `runCli`). `LegacyDebugLogger` is
+// NOT provided by the root, so every base layer that reads it for `--debug` traces
+// (`legacyCliConfigLayer`, `legacyHttpClientLayer`, `legacyCredentialsLayer`,
+// `legacyPlatformApiLayer`) is fed `legacyDebugLoggerLayer` here — matching `login.layers.ts`.
+const debugLogger = legacyDebugLoggerLayer;
+const cliConfig = legacyCliConfigLayer.pipe(Layer.provide(debugLogger));
+const httpClient = legacyHttpClientLayer.pipe(Layer.provide(debugLogger));
+const credentials = legacyCredentialsLayer.pipe(
+  Layer.provide(cliConfig),
+  Layer.provide(debugLogger),
+);
 const platformApi = legacyPlatformApiLayer.pipe(
   Layer.provide(credentials),
   Layer.provide(cliConfig),
   Layer.provide(httpClient),
+  Layer.provide(debugLogger),
 );
 
 export const legacyBootstrapRuntimeLayer = Layer.mergeAll(
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.ts
new file mode 100644
index 0000000000..6ea685fafe
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.ts
@@ -0,0 +1,77 @@
+import { Duration, Effect, Random, Schedule } from "effect";
+
+import { LegacyDebugFlag } from "../../../shared/legacy/global-flags.ts";
+import { Output } from "../../../shared/output/output.service.ts";
+
+/**
+ * `maxRetries` from Go's `utils.NewBackoffPolicy` (`internal/utils/retry.go:12`).
+ * `backoff.WithMaxRetries(b, 8)` performs 8 retries -> 9 total attempts, matching
+ * `Effect.retry({ schedule, times: 8 })`.
+ */
+export const LEGACY_BOOTSTRAP_MAX_RETRIES = 8;
+
+const MAX_INTERVAL = Duration.seconds(60);
+
+/**
+ * Go-parity backoff for the api-keys and health retry loops
+ * (`utils.NewBackoffPolicy` -> `cenkalti/backoff` `NewExponentialBackOff`):
+ *
+ *  - 3s initial interval, multiplier `1.5`
+ *  - `MaxInterval` capped at 60s (applied to the base interval **before** jitter,
+ *    matching cenkalti's order — so an individual delay can reach ~90s)
+ *  - `RandomizationFactor` `0.5` -> each delay is jittered into `[0.5x, 1.5x]`
+ *  - `MaxElapsedTime` 15m (intersected via `during`; in practice the 8-retry cap
+ *    always trips first, but reproduced for completeness)
+ */
+export const legacyBootstrapBackoff: Schedule.Schedule<[Duration.Duration, Duration.Duration]> =
+  Schedule.exponential("3 seconds", 1.5).pipe(
+    Schedule.modifyDelay((_, delay) => Effect.succeed(Duration.min(delay, MAX_INTERVAL))),
+    Schedule.modifyDelay((_, delay) =>
+      Random.next.pipe(
+        Effect.map((random) => Duration.millis(Duration.toMillis(delay) * (0.5 + random))),
+      ),
+    ),
+    Schedule.both(Schedule.during("15 minutes")),
+  );
+
+/**
+ * Reproduces Go's `utils.NewErrorCallback` (`internal/utils/retry.go:19-35`): after
+ * each failed attempt it prints `<err>\nRetry (n/8): ` to a logger that starts as the
+ * debug logger (discarded unless `--debug`) and switches to stderr once
+ * `failureCount*3 > maxRetries` (i.e. from the 3rd failure on). Notify fires only for
+ * attempts that will be retried, never the final exhausted one.
+ *
+ * Returns a fresh wrapper with its own failure counter per call, mirroring Go's
+ * per-`RetryNotify` `NewErrorCallback()` + `policy.Reset()`.
+ */
+export const legacyBootstrapRetryNotify = () => {
+  let failureCount = 0;
+  return <A, E, R>(operation: Effect.Effect<A, E, R>) =>
+    operation.pipe(
+      Effect.tapError((error) =>
+        Effect.gen(function* () {
+          failureCount += 1;
+          // No notify on the final attempt (cenkalti returns `Stop` before notifying).
+          if (failureCount > LEGACY_BOOTSTRAP_MAX_RETRIES) return;
+          const toStderr = failureCount * 3 > LEGACY_BOOTSTRAP_MAX_RETRIES;
+          const debug = yield* LegacyDebugFlag;
+          // Failures 1-2 go to the debug logger (discarded unless `--debug`); 3+ to stderr.
+          if (!toStderr && !debug) return;
+          const output = yield* Output;
+          const message = stringifyError(error);
+          yield* output.raw(
+            `${message}\nRetry (${failureCount}/${LEGACY_BOOTSTRAP_MAX_RETRIES}): `,
+            "stderr",
+          );
+        }),
+      ),
+    );
+};
+
+function stringifyError(error: unknown): string {
+  if (typeof error === "object" && error !== null && "message" in error) {
+    const message = (error as { message: unknown }).message;
+    if (typeof message === "string") return message;
+  }
+  return String(error);
+}
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.unit.test.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.unit.test.ts
new file mode 100644
index 0000000000..19419390a7
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.retry.unit.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Duration, Effect, Layer, Pull, Schedule } from "effect";
+
+import { mockOutput } from "../../../../tests/helpers/mocks.ts";
+import { LegacyDebugFlag } from "../../../shared/legacy/global-flags.ts";
+import { legacyBootstrapBackoff, legacyBootstrapRetryNotify } from "./bootstrap.retry.ts";
+
+// Drive the schedule's step function directly (no real sleeping): each call returns the
+// next delay, and we feed an artificial `now` advanced by that delay so the `during`
+// (max-elapsed) gate sees virtual time pass.
+const collectDelays = (maxAttempts: number) =>
+  Effect.gen(function* () {
+    const step = yield* Schedule.toStep(legacyBootstrapBackoff);
+    const delays: Array<number> = [];
+    let now = 0;
+    let stopped = false;
+    for (let i = 0; i < maxAttempts; i++) {
+      const result = yield* step(now, undefined).pipe(
+        Effect.map((output) => ({ kind: "delay" as const, delay: output[1] })),
+        Pull.catchDone(() => Effect.succeed({ kind: "done" as const })),
+      );
+      if (result.kind === "done") {
+        stopped = true;
+        break;
+      }
+      const ms = Duration.toMillis(result.delay);
+      delays.push(ms);
+      now += ms;
+    }
+    return { delays, stopped };
+  });
+
+describe("legacyBootstrapBackoff", () => {
+  it.effect("caps each delay at the 60s max interval (plus 50% jitter)", () =>
+    Effect.gen(function* () {
+      const { delays } = yield* collectDelays(40);
+      // 60s `MaxInterval` capped before jitter, then jittered up to 1.5x => 90s ceiling.
+      // Without the cap, the exponential base alone would exceed 90s within ~9 attempts.
+      for (const ms of delays) {
+        expect(ms).toBeGreaterThan(0);
+        expect(ms).toBeLessThanOrEqual(90_000);
+      }
+    }),
+  );
+
+  it.effect("jitters the 3s initial interval into [1.5s, 4.5s]", () =>
+    Effect.gen(function* () {
+      const { delays } = yield* collectDelays(1);
+      expect(delays[0]).toBeGreaterThanOrEqual(1_500);
+      expect(delays[0]).toBeLessThanOrEqual(4_500);
+    }),
+  );
+
+  it.effect("stops at the 15m max-elapsed cap, independent of the 8-retry limit", () =>
+    Effect.gen(function* () {
+      const { delays, stopped } = yield* collectDelays(60);
+      // The schedule itself is bounded by elapsed time (15m), not the `times: 8` the
+      // handler layers on, so it yields more than 8 delays before halting.
+      expect(stopped).toBe(true);
+      expect(delays.length).toBeGreaterThan(8);
+    }),
+  );
+});
+
+const BOOM = new Error("boom");
+
+// Always-failing effect retried 8 times (9 attempts) to exercise the notify routing.
+const runNotify = (opts: { debug: boolean; error?: unknown }) => {
+  const out = mockOutput({ format: "text" });
+  const notify = legacyBootstrapRetryNotify();
+  const program = Effect.fail(opts.error ?? BOOM).pipe(
+    notify,
+    Effect.retry({ times: 8 }),
+    Effect.exit,
+  );
+  return Effect.gen(function* () {
+    yield* program;
+    return out;
+  }).pipe(Effect.provide(Layer.mergeAll(out.layer, Layer.succeed(LegacyDebugFlag, opts.debug))));
+};
+
+describe("legacyBootstrapRetryNotify", () => {
+  it.effect("routes failures 1-2 to the debug logger (suppressed without --debug)", () =>
+    Effect.gen(function* () {
+      const out = yield* runNotify({ debug: false });
+      // Failures 1-2 are debug-only; with --debug unset they must not reach stderr.
+      expect(out.stderrText).not.toContain("Retry (1/8): ");
+      expect(out.stderrText).not.toContain("Retry (2/8): ");
+      // Failures 3+ always print to stderr, preceded by the error message.
+      expect(out.stderrText).toContain("boom\nRetry (3/8): ");
+      expect(out.stderrText).toContain("Retry (8/8): ");
+    }),
+  );
+
+  it.effect("prints every notice to stderr under --debug", () =>
+    Effect.gen(function* () {
+      const out = yield* runNotify({ debug: true });
+      expect(out.stderrText).toContain("boom\nRetry (1/8): ");
+      expect(out.stderrText).toContain("Retry (2/8): ");
+      expect(out.stderrText).toContain("Retry (8/8): ");
+    }),
+  );
+
+  it.effect("emits no notice on the final exhausted attempt", () =>
+    Effect.gen(function* () {
+      const out = yield* runNotify({ debug: true });
+      // 8 retries => 9 attempts, but cenkalti returns Stop before notifying the last one.
+      expect(out.stderrText).not.toContain("Retry (9/8): ");
+    }),
+  );
+
+  it.effect("stringifies a non-Error failure value", () =>
+    Effect.gen(function* () {
+      const out = yield* runNotify({ debug: true, error: "plain string failure" });
+      expect(out.stderrText).toContain("plain string failure\nRetry (1/8): ");
+    }),
+  );
+
+  it.effect("falls back to String() when the failure has a non-string message", () =>
+    Effect.gen(function* () {
+      const out = yield* runNotify({ debug: true, error: { message: 123 } });
+      expect(out.stderrText).toContain("[object Object]\nRetry (1/8): ");
+    }),
+  );
+});
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts
index 376728a496..db298a68a5 100644
--- a/apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.templates.ts
@@ -194,9 +194,18 @@ export const legacyTemplateServiceLayer = Layer.effect(
           for (const entry of listing) {
             const entryPath = entry.path ?? "";
             if (entry.type === "file") {
-              const relative = entryPath.startsWith(root)
-                ? entryPath.slice(root.length)
-                : entryPath;
+              // Strip `<root>` on a path-segment boundary so a sibling directory that
+              // merely shares the prefix (e.g. `examples/app-2` under `root="examples/app"`)
+              // is never mis-sliced. The contents API only returns children of the queried
+              // directory, but matching on `root + "/"` is the obviously-correct form.
+              const relative =
+                root === ""
+                  ? entryPath
+                  : entryPath === root
+                    ? ""
+                    : entryPath.startsWith(`${root}/`)
+                      ? entryPath.slice(root.length + 1)
+                      : entryPath;
               const localPath = path.join(targetDir, ...relative.split("/").filter(Boolean));
               // Defence-in-depth: reject a malicious `path` (e.g. `../../etc/x`)
               // that would escape the target directory.
@@ -210,7 +219,15 @@ export const legacyTemplateServiceLayer = Layer.effect(
                   message: `failed to download template: entry escapes target directory: ${entryPath}`,
                 });
               }
-              downloads.push({ localPath, remoteUrl: entry.download_url ?? "" });
+              // GitHub returns a null `download_url` for files over 1 MB and for
+              // submodules; without an explicit guard the `?? ""` fallback would issue
+              // `GET ""` and surface a confusing transport error instead of a clear one.
+              if (entry.download_url == null || entry.download_url.length === 0) {
+                return yield* new LegacyBootstrapTemplateDownloadError({
+                  message: `failed to download template: unsupported entry (no download URL): ${entryPath}`,
+                });
+              }
+              downloads.push({ localPath, remoteUrl: entry.download_url });
             } else if (entry.type === "dir") {
               queue.push(entryPath);
             } else {
diff --git a/apps/cli/src/legacy/commands/bootstrap/bootstrap.workdir-cache.integration.test.ts b/apps/cli/src/legacy/commands/bootstrap/bootstrap.workdir-cache.integration.test.ts
new file mode 100644
index 0000000000..17f96a9aa2
--- /dev/null
+++ b/apps/cli/src/legacy/commands/bootstrap/bootstrap.workdir-cache.integration.test.ts
@@ -0,0 +1,184 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { BunServices } from "@effect/platform-bun";
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer, Option, Schedule } from "effect";
+
+import {
+  mockAnalytics,
+  mockBrowser,
+  mockOutput,
+  mockRuntimeInfo,
+  mockStdin,
+  mockTty,
+} from "../../../../tests/helpers/mocks.ts";
+import {
+  type LegacyApiHandler,
+  LEGACY_VALID_REF,
+  legacyJsonResponse,
+  mockLegacyCredentialsTracked,
+  mockLegacyLoginApi,
+  mockLegacyLoginCrypto,
+  mockLegacyPlatformApi,
+  mockLegacyTelemetryStateTracked,
+} from "../../../../tests/helpers/legacy-mocks.ts";
+import {
+  LegacyDebugFlag,
+  LegacyOutputFlag,
+  LegacyProfileFlag,
+  LegacyWorkdirFlag,
+  LegacyYesFlag,
+} from "../../../shared/legacy/global-flags.ts";
+import { LegacyGoProxy } from "../../../shared/legacy/go-proxy.service.ts";
+import { legacyDebugLoggerLayer } from "../../shared/legacy-debug-logger.layer.ts";
+import { legacyCliConfigLayer } from "../../config/legacy-cli-config.layer.ts";
+import { legacyLinkedProjectCacheLayer } from "../../telemetry/legacy-linked-project-cache.layer.ts";
+import { LegacyTemplateService } from "./bootstrap.templates.ts";
+import { legacyBootstrap } from "./bootstrap.handler.ts";
+import type { LegacyBootstrapFlags } from "./bootstrap.command.ts";
+
+const FAST_BACKOFF = Schedule.exponential("1 milli");
+
+const PROJECT = {
+  id: LEGACY_VALID_REF,
+  ref: LEGACY_VALID_REF,
+  organization_id: "org-1",
+  organization_slug: "acme",
+  name: "alpha",
+  region: "us-east-1",
+  status: "COMING_UP",
+};
+const ORGS = [{ id: "org-1", slug: "acme", name: "Acme Inc" }];
+const API_KEYS = [{ name: "anon", api_key: "anon-key" }];
+const HEALTHY = [{ name: "db", healthy: true, status: "ACTIVE_HEALTHY" }];
+
+// Drives the handler through the *prompt* workdir path (no `--workdir` flag and no
+// `SUPABASE_WORKDIR` env) with the real config + linked-project-cache layers. This is
+// the case the rest of the suite never covers: when the workdir comes from the prompt,
+// `cliConfig.workdir` (the cwd-walk result) diverges from the bootstrap workdir, and the
+// cache must follow the bootstrap workdir so `linked-project.json` lands beside
+// `project-ref` (matching Go's `flags.LoadConfig` after `ChangeWorkDir`).
+describe("legacy bootstrap linked-project cache location", () => {
+  it.live(
+    "writes linked-project.json into the prompted bootstrap workdir, not cliConfig.workdir",
+    () => {
+      const parent = mkdtempSync(join(tmpdir(), "bootstrap-cache-"));
+      const subdir = "myproj";
+      const bootstrapWorkdir = join(parent, subdir);
+
+      // Token via env => ensure-login is a no-op and the cache has a bearer token.
+      const prevToken = process.env["SUPABASE_ACCESS_TOKEN"];
+      const prevWorkdir = process.env["SUPABASE_WORKDIR"];
+      process.env["SUPABASE_ACCESS_TOKEN"] = "sbp_" + "a".repeat(40);
+      delete process.env["SUPABASE_WORKDIR"];
+
+      const out = mockOutput({ format: "text", promptTextResponses: [subdir] });
+
+      const handler: LegacyApiHandler = (request, recorded) => {
+        const url = recorded.urlWithParams;
+        if (recorded.method === "POST" && /\/v1\/projects(\?|$)/.test(url)) {
+          return Effect.succeed(legacyJsonResponse(request, 201, PROJECT));
+        }
+        if (url.includes("/api-keys")) {
+          return Effect.succeed(legacyJsonResponse(request, 200, API_KEYS));
+        }
+        if (url.includes("/health")) {
+          return Effect.succeed(legacyJsonResponse(request, 200, HEALTHY));
+        }
+        if (url.includes("/v1/organizations")) {
+          return Effect.succeed(legacyJsonResponse(request, 200, ORGS));
+        }
+        // GET /v1/projects/{ref} — read by the linked-project cache.
+        if (recorded.method === "GET" && url.includes(`/v1/projects/${LEGACY_VALID_REF}`)) {
+          return Effect.succeed(legacyJsonResponse(request, 200, PROJECT));
+        }
+        return Effect.succeed(legacyJsonResponse(request, 404, {}));
+      };
+      const api = mockLegacyPlatformApi({ handler });
+
+      const proxyLayer = Layer.succeed(LegacyGoProxy, { exec: () => Effect.void });
+      const templateLayer = Layer.succeed(LegacyTemplateService, {
+        listSamples: Effect.succeed([]),
+        download: () => Effect.void,
+      });
+
+      // GlobalFlag services don't cross sibling boundaries in Layer.mergeAll
+      // (apps/cli/CLAUDE.md item 5), so provide them explicitly into the real config layer.
+      const flagsLayer = Layer.mergeAll(
+        Layer.succeed(LegacyProfileFlag, "supabase"),
+        Layer.succeed(LegacyWorkdirFlag, Option.none()),
+        Layer.succeed(LegacyYesFlag, false),
+        Layer.succeed(LegacyOutputFlag, Option.none()),
+        Layer.succeed(LegacyDebugFlag, false),
+      );
+      const runtime = mockRuntimeInfo({ cwd: parent });
+      const credentials = mockLegacyCredentialsTracked();
+      const debugLoggerLayer = legacyDebugLoggerLayer.pipe(Layer.provide(flagsLayer));
+
+      const configLayer = legacyCliConfigLayer.pipe(
+        Layer.provide(flagsLayer),
+        Layer.provide(debugLoggerLayer),
+        Layer.provide(runtime),
+        Layer.provide(BunServices.layer),
+      );
+      const cacheLayer = legacyLinkedProjectCacheLayer.pipe(
+        Layer.provide(configLayer),
+        Layer.provide(credentials.layer),
+        Layer.provide(api.httpClientLayer),
+        Layer.provide(BunServices.layer),
+      );
+
+      const layer = Layer.mergeAll(
+        BunServices.layer,
+        out.layer,
+        api.layer,
+        api.httpClientLayer,
+        configLayer,
+        cacheLayer,
+        credentials.layer,
+        mockTty({ stdinIsTty: true, stdoutIsTty: false }),
+        runtime,
+        mockLegacyTelemetryStateTracked().layer,
+        mockAnalytics().layer,
+        templateLayer,
+        proxyLayer,
+        mockLegacyLoginApi({ gotrueId: "gotrue-user" }).layer,
+        mockLegacyLoginCrypto().layer,
+        mockBrowser(),
+        mockStdin(true),
+        flagsLayer,
+      );
+
+      const flags: LegacyBootstrapFlags = {
+        template: Option.some("scratch"),
+        password: Option.some("s3cret"),
+      };
+
+      return Effect.gen(function* () {
+        yield* legacyBootstrap(flags, FAST_BACKOFF);
+
+        const projectRef = join(bootstrapWorkdir, "supabase", ".temp", "project-ref");
+        const cacheInWorkdir = join(bootstrapWorkdir, "supabase", ".temp", "linked-project.json");
+        const cacheInParent = join(parent, "supabase", ".temp", "linked-project.json");
+
+        // project-ref already goes to the right place...
+        expect(existsSync(projectRef)).toBe(true);
+        // ...so linked-project.json must land beside it (Go writes both into workdir).
+        expect(existsSync(cacheInWorkdir)).toBe(true);
+        expect(existsSync(cacheInParent)).toBe(false);
+      }).pipe(
+        Effect.provide(layer),
+        Effect.ensuring(
+          Effect.sync(() => {
+            if (prevToken !== undefined) process.env["SUPABASE_ACCESS_TOKEN"] = prevToken;
+            else delete process.env["SUPABASE_ACCESS_TOKEN"];
+            if (prevWorkdir !== undefined) process.env["SUPABASE_WORKDIR"] = prevWorkdir;
+            rmSync(parent, { recursive: true, force: true });
+          }),
+        ),
+      );
+    },
+  );
+});
diff --git a/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.layer.ts b/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.layer.ts
index 06c3e474e3..926b32e2c6 100644
--- a/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.layer.ts
+++ b/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.layer.ts
@@ -41,9 +41,9 @@ export const legacyLinkedProjectCacheLayer = Layer.effect(
     const path = yield* Path.Path;
 
     return LegacyLinkedProjectCache.of({
-      cache: (ref: string) =>
+      cache: (ref: string, workdir?: string) =>
         Effect.gen(function* () {
-          const cachePath = legacyTempPaths(path, cliConfig.workdir).linkedProjectCache;
+          const cachePath = legacyTempPaths(path, workdir ?? cliConfig.workdir).linkedProjectCache;
           const exists = yield* fs.exists(cachePath).pipe(Effect.orElseSucceed(() => false));
           if (exists) return;
 
diff --git a/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.service.ts b/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.service.ts
index eacfaca6c9..92e3dceafc 100644
--- a/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.service.ts
+++ b/apps/cli/src/legacy/telemetry/legacy-linked-project-cache.service.ts
@@ -6,11 +6,17 @@ interface LegacyLinkedProjectCacheShape {
    * Fire-and-forget: fetches the project metadata from the Management API and
    * writes `<workdir>/supabase/.temp/linked-project.json` if no cache exists yet.
    *
+   * `workdir` overrides the directory the cache resolves against. Callers that have
+   * already changed the working directory (e.g. `bootstrap`, whose target workdir can
+   * come from an interactive prompt rather than `cliConfig.workdir`) pass their resolved
+   * workdir so the cache lands beside the other `supabase/.temp/` files. When omitted it
+   * falls back to `cliConfig.workdir` (the cwd-walk result), matching every other caller.
+   *
    * Best-effort. Never fails the calling effect — auth errors, network errors,
    * and write errors are all swallowed (matches Go's `ensureProjectGroupsCached`
    * which logs to debug and returns).
    */
-  readonly cache: (ref: string) => Effect.Effect<void>;
+  readonly cache: (ref: string, workdir?: string) => Effect.Effect<void>;
 }
 
 export class LegacyLinkedProjectCache extends Context.Service<