feat(cli): port link and unlink commands to native TypeScript (#5426)

## What changed

Promotes `supabase link` and `supabase unlink` from Phase-0 Go-binary
proxy wrappers to native Effect TypeScript in the legacy
(stable-channel) shell. Behaviour follows the Go source
(`apps/cli-go/internal/{link,unlink}`) verbatim — same flags,
stdout/stderr text, `supabase/.temp/*` file writes, API routes, and exit
codes.

### `supabase link`
- Resolves the project ref `--project-ref` → `SUPABASE_PROJECT_ID` → TTY
prompt, **skipping** the on-disk ref file (matching Go's
empty-MemMapFs), and emits the cobra `required flag(s) "project-ref" not
set` error on a non-TTY.
- Checks remote project status: 404 tolerated (branch projects),
`INACTIVE` → paused error + dashboard unpause suggestion,
non-`ACTIVE_HEALTHY` → stderr warning; writes `postgres-version`.
- Fetches api-keys (`reveal=true`), then best-effort links:
`storage-migration`, `pooler-url` (placeholder-stripped, session-mode
rewrite; removed on `--skip-pooler`), and `rest`/`gotrue`/`storage`
tenant versions.
- Writes `project-ref` + `linked-project.json` and fires
`cli_project_linked` (org/project `groupIdentify`, groups keyed by org
**id**).

### `supabase unlink`
- Reads the project ref, removes `supabase/.temp/`, deletes the keyring
database-password entry, and surfaces all failures together (Go
`errors.Join` parity).
- Uses a minimal runtime layer — `unlink` makes no API calls and
requires no access token (the management-API layer eagerly requires
one).

### Shared / supporting
- New `legacy-temp-paths` and `legacy-tenant-versions` helpers in
`legacy/shared/` (existing `legacy-project-ref` /
`legacy-linked-project-cache` call sites refactored onto the former).
- `resolveForLink` on `LegacyProjectRefResolver`;
`deleteProjectCredential` on `LegacyCredentials`.
- The legacy credentials layer now honours `SUPABASE_NO_KEYRING=1`
(matching `next/` and the cli-e2e harness), preventing non-interactive
Keychain hangs for keyring-touching commands.

### Reviewer notes — intentional divergences from Go
- The cosmetic `WARNING: Local database version differs…` message is
omitted (it needs `config.toml [db].major_version` with CLI defaults,
not surfaced by the legacy shell); the `postgres-version` file is still
written.
- The four discarded Go config probes (`/config/database/postgres`,
`/postgrest`, `/config/auth`, `/network-restrictions`) are omitted —
they only populated in-process config that standalone `link` discards.
- The `Finished …` lines render plain (Go's `utils.Aqua` cyan), matching
the established legacy-port convention.

Both `SIDE_EFFECTS.md` files and `docs/go-cli-porting-status.md` (rows
flipped to `ported`) are updated.

Author: Coly010

apps/cli-e2e/src/server/placeholder.ts

@@ -61,6 +61,33 @@ export function applyPlaceholders(input: string): { output: string } {
   return { output };
 }
 
+// The project-ref placeholder (`__PROJECT_REF__`) is 15 characters, but the
+// Management API schema constrains project refs to `^[a-z]{20}$` (minLength 20).
+// The Go CLI doesn't validate response bodies, so it tolerates the short
+// placeholder; the TS port decodes responses against the generated schema and
+// rejects it (e.g. `link` calling `getProject`). When serving a recorded
+// response we therefore substitute any field whose value is *exactly* the
+// placeholder back to a valid 20-char ref. Substring occurrences such as
+// `db.__PROJECT_REF__.supabase.red` are left untouched so tests that assert on
+// the literal placeholder host keep matching.
+const PROJECT_REF_VALUE = /"__PROJECT_REF__"/g;
+const PLACEHOLDER_PROJECT_REF = "abcdefghijklmnopqrst";
+
+/** Extract the 20-char project ref from a `/v1/projects/<ref>` request path,
+ *  falling back to a stable placeholder ref for refless endpoints (e.g. the
+ *  project list). */
+export function projectRefFromPath(urlPath: string): string {
+  const match = urlPath.match(/\/projects\/([a-z]{20})(?:\/|$)/);
+  return match?.[1] ?? PLACEHOLDER_PROJECT_REF;
+}
+
+/** Replace exact-match `__PROJECT_REF__` string values in a serialized JSON
+ *  body with a schema-valid 20-char ref. Operates on the JSON string so only
+ *  full quoted values are rewritten, never substrings. */
+export function restoreProjectRef(json: string, ref: string): string {
+  return json.replace(PROJECT_REF_VALUE, `"${ref}"`);
+}
+
 /** Normalize dynamic segments in a URL path to stable unnumbered placeholders.
  *  Apply this to both the stored fixture path and the incoming request path so
  *  both sides of a scenario comparison transform identically. */

apps/cli-e2e/src/server/replay-server.ts

@@ -9,7 +9,13 @@ import type {
   FixtureStore,
 } from "./fixture-loader.ts";
 import { loadFixtures, loadScenario } from "./fixture-loader.ts";
-import { applyPlaceholders, fixtureKey, normalizeUrlPath } from "./placeholder.ts";
+import {
+  applyPlaceholders,
+  fixtureKey,
+  normalizeUrlPath,
+  projectRefFromPath,
+  restoreProjectRef,
+} from "./placeholder.ts";
 import { matchFixture, resetCounters, sortBody, type SequenceCounters } from "./request-matcher.ts";
 import type { PgFixture, PgMockHandle } from "./pg-mock.ts";
 
@@ -470,10 +476,15 @@ async function proxyAndRecord(
     scenario,
   });
 
-  return buildApiResponse(responseBody, upstreamStatus, {
-    ...responseHeaders,
-    "content-type": responseContentType,
-  });
+  return buildApiResponse(
+    responseBody,
+    upstreamStatus,
+    {
+      ...responseHeaders,
+      "content-type": responseContentType,
+    },
+    projectRefFromPath(pathname),
+  );
 }
 
 /** Record a Docker interaction once its streamed body has fully drained.  Errors
@@ -750,11 +761,14 @@ function nextFixtureIndex(keyDir: string): number {
   return max + 1;
 }
 
-/** Build an API response, respecting HTTP no-body status codes (204, 304, 205). */
+/** Build an API response, respecting HTTP no-body status codes (204, 304, 205).
+ *  `projectRef` is the ref from the request path, used to restore short
+ *  `__PROJECT_REF__` placeholders to schema-valid 20-char refs in JSON bodies. */
 function buildApiResponse(
   body: unknown,
   status: number,
   headers: Record<string, string>,
+  projectRef: string,
 ): Response {
   if (status === 204 || status === 304 || status === 205) {
     return new Response(null, { status, headers });
@@ -770,7 +784,10 @@ function buildApiResponse(
   if (body === null) {
     return new Response(null, { status, headers });
   }
-  return Response.json(body, { status, headers });
+  return new Response(restoreProjectRef(JSON.stringify(body), projectRef), {
+    status,
+    headers: { "content-type": "application/json", ...headers },
+  });
 }
 
 function serveFromFixtures(
@@ -791,6 +808,7 @@ function serveFromFixtures(
     result.entry.response.body,
     result.entry.response.status,
     result.entry.response.headers,
+    projectRefFromPath(pathname),
   );
 }
 
@@ -882,6 +900,7 @@ function serveFromScenario(
     expected.response.body,
     expected.response.status,
     expected.response.headers,
+    projectRefFromPath(pathname),
   );
 }
 

apps/cli-e2e/src/tests/project-lifecycle.e2e.test.ts

@@ -158,10 +158,10 @@ describe("unlink", () => {
   });
 
   // The success path (pre-populate project-ref → unlink succeeds) is omitted: the
-  // ts-legacy unlink handler is a Phase 0 proxy to the Go binary, which attempts
-  // a system keyring delete on exit. On Linux CI (no D-Bus session bus) the
-  // keyring call returns an unhandled error and the binary exits 1. The error path
-  // above already gives meaningful coverage for a proxy command.
+  // unlink handler deletes the database-password keyring entry on success. On
+  // Linux CI (no D-Bus session bus) the keyring call returns an unhandled error
+  // and the command exits 1. The not-linked error path above gives meaningful
+  // coverage; deeper success-path behaviour is covered by unlink.integration.test.ts.
 
   testParity(["unlink"]);
 });

apps/cli/docs/go-cli-porting-status.md

@@ -263,8 +263,8 @@ Legend:
 | `postgres-config delete`               | `ported`      | [`../src/legacy/commands/postgres-config/delete/delete.command.ts`](../src/legacy/commands/postgres-config/delete/delete.command.ts)                                                      |
 | `login`                                | `wrapped`     | [`../src/legacy/commands/login/login.command.ts`](../src/legacy/commands/login/login.command.ts)                                                                                          |
 | `logout`                               | `wrapped`     | [`../src/legacy/commands/logout/logout.command.ts`](../src/legacy/commands/logout/logout.command.ts)                                                                                      |
-| `link`                                 | `wrapped`     | [`../src/legacy/commands/link/link.command.ts`](../src/legacy/commands/link/link.command.ts)                                                                                              |
-| `unlink`                               | `wrapped`     | [`../src/legacy/commands/unlink/unlink.command.ts`](../src/legacy/commands/unlink/unlink.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)                                                                          |
 | `init`                                 | `wrapped`     | [`../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)                                                                              |

apps/cli/src/legacy/auth/legacy-credentials.layer.ts

@@ -4,7 +4,7 @@ import { RuntimeInfo } from "../../shared/runtime/runtime-info.service.ts";
 import { normalizeKeyringToken } from "../../shared/auth/keyring-token.ts";
 import { LegacyCliConfig } from "../config/legacy-cli-config.service.ts";
 import { LegacyCredentials } from "./legacy-credentials.service.ts";
-import { LegacyInvalidAccessTokenError } from "./legacy-errors.ts";
+import { LegacyCredentialDeleteError, LegacyInvalidAccessTokenError } from "./legacy-errors.ts";
 
 const KEYRING_SERVICE = "Supabase CLI";
 const LEGACY_KEYRING_ACCOUNT = "access-token";
@@ -160,6 +160,64 @@ function deleteGoWindowsTarget(module: KeyringModule, account: string): boolean
     return false;
   }
 }
+// Delete the project database-password entry (keyed by project ref), surfacing a
+// real failure while ignoring the "nothing to delete" cases — mirroring Go's
+// unlink, which ignores both `keyring.ErrNotFound` AND `credentials.ErrNotSupported`
+// (backend unavailable) and only surfaces other errors (`unlink.go:36-40`).
+//
+// The plain `Entry(service, projectRef)` is the macOS/Linux form and the Windows
+// default. On Windows, Go also writes a separate target-shaped credential; it is
+// detected via `findCredentials` (a plain `getPassword` does not read the Go
+// target reliably) and deleted through the `withTarget` entry. The `withTarget`
+// entry is only constructed on Windows — on macOS its first argument is an
+// invalid keychain domain and throws.
+//
+// Each entry is probed before `deleteCredential()`: on macOS deleting an absent
+// entry blocks on a Keychain authorization prompt, and an absent read means
+// there is nothing to delete (ignorable, per Go). Only a real delete failure is
+// surfaced as `LegacyCredentialDeleteError`.
+const deleteKeyringEntryStrict = (
+  module: KeyringModule,
+  account: string,
+  platform: RuntimePlatform,
+): Effect.Effect<boolean, LegacyCredentialDeleteError> =>
+  Effect.gen(function* () {
+    let deleted = false;
+
+    const plain = new module.Entry(KEYRING_SERVICE, account);
+    if (readEntryPassword(plain)) {
+      yield* Effect.try({
+        try: () => {
+          plain.deleteCredential();
+        },
+        catch: (cause) =>
+          new LegacyCredentialDeleteError({
+            message: `failed to delete project credential: ${String(cause)}`,
+          }),
+      });
+      deleted = true;
+    }
+
+    if (platform === "win32" && readGoWindowsTarget(module, account)) {
+      const target = module.Entry.withTarget(
+        goWindowsCredentialTarget(account),
+        KEYRING_SERVICE,
+        account,
+      );
+      yield* Effect.try({
+        try: () => {
+          target.deleteCredential();
+        },
+        catch: (cause) =>
+          new LegacyCredentialDeleteError({
+            message: `failed to delete project credential: ${String(cause)}`,
+          }),
+      });
+      deleted = true;
+    }
+
+    return deleted;
+  });
 
 const makeLegacyCredentials = Effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem;
@@ -172,10 +230,16 @@ const makeLegacyCredentials = Effect.gen(function* () {
   const fallbackDir = path.join(runtimeInfo.homeDir, ".supabase");
   const fallbackPath = path.join(fallbackDir, "access-token");
 
+  // `SUPABASE_NO_KEYRING=1` disables the OS keyring entirely (matches `next/`'s
+  // credentials layer and the cli-e2e harness, which sets it). Without this, any
+  // unconditional keyring access — e.g. `unlink`'s credential delete — blocks on a
+  // Keychain authorization prompt in non-interactive / CI contexts.
+  const noKeyring = process.env["SUPABASE_NO_KEYRING"] === "1";
   const wsl = yield* detectWsl(fs);
-  const keyringModule = wsl
-    ? Option.none<KeyringModule>()
-    : yield* Effect.tryPromise(() => import("@napi-rs/keyring")).pipe(Effect.option);
+  const keyringModule =
+    wsl || noKeyring
+      ? Option.none<KeyringModule>()
+      : yield* Effect.tryPromise(() => import("@napi-rs/keyring")).pipe(Effect.option);
 
   const validate = (token: string): Effect.Effect<string, LegacyInvalidAccessTokenError> =>
     ACCESS_TOKEN_PATTERN.test(token)
@@ -261,6 +325,17 @@ const makeLegacyCredentials = Effect.gen(function* () {
       }
       return anyDeleted;
     }),
+
+    deleteProjectCredential: (projectRef: string) =>
+      Effect.gen(function* () {
+        // WSL / no keyring module: treated as `ErrNotSupported` — a no-op success.
+        if (Option.isNone(keyringModule)) return false;
+        return yield* deleteKeyringEntryStrict(
+          keyringModule.value,
+          projectRef,
+          runtimeInfo.platform,
+        );
+      }),
   });
 });
 

apps/cli/src/legacy/auth/legacy-credentials.service.ts

@@ -1,7 +1,10 @@
 import type { Effect, Option, Redacted } from "effect";
 import { Context } from "effect";
 
-import type { LegacyInvalidAccessTokenError } from "./legacy-errors.ts";
+import type {
+  LegacyCredentialDeleteError,
+  LegacyInvalidAccessTokenError,
+} from "./legacy-errors.ts";
 
 interface LegacyCredentialsShape {
   readonly getAccessToken: Effect.Effect<
@@ -10,6 +13,19 @@ interface LegacyCredentialsShape {
   >;
   readonly saveAccessToken: (token: string) => Effect.Effect<void, LegacyInvalidAccessTokenError>;
   readonly deleteAccessToken: Effect.Effect<boolean>;
+  /**
+   * Deletes the stored database-password credential for a project from the OS
+   * keyring (keyring service `"Supabase CLI"`, account = the **project ref** —
+   * distinct from the access-token entry). Used by `supabase unlink`.
+   *
+   * Returns `true` when an entry was removed, `false` when none existed or the
+   * keyring is unavailable (WSL). Fails with `LegacyCredentialDeleteError` only
+   * for real keyring errors (e.g. permission denied), mirroring Go's unlink
+   * which ignores `ErrNotFound` / `ErrNotSupported` but surfaces everything else.
+   */
+  readonly deleteProjectCredential: (
+    projectRef: string,
+  ) => Effect.Effect<boolean, LegacyCredentialDeleteError>;
 }
 
 export class LegacyCredentials extends Context.Service<LegacyCredentials, LegacyCredentialsShape>()(

apps/cli/src/legacy/auth/legacy-errors.ts

@@ -11,3 +11,14 @@ export class LegacyPlatformAuthRequiredError extends Data.TaggedError(
 )<{
   readonly message: string;
 }> {}
+
+/**
+ * Raised by `deleteProjectCredential` when removing a stored database-password
+ * credential from the OS keyring fails for a reason other than "entry not
+ * found" (which is ignored). Mirrors `supabase unlink`'s behaviour of collecting
+ * non-`ErrNotFound` / non-`ErrNotSupported` keyring errors
+ * (`apps/cli-go/internal/unlink/unlink.go:36-40`).
+ */
+export class LegacyCredentialDeleteError extends Data.TaggedError("LegacyCredentialDeleteError")<{
+  readonly message: string;
+}> {}

apps/cli/src/legacy/auth/legacy-platform-api.layer.unit.test.ts

@@ -36,6 +36,7 @@ function mockCredentials(token: Option.Option<string>) {
     getAccessToken: Effect.succeed(Option.map(token, Redacted.make)),
     saveAccessToken: () => Effect.void,
     deleteAccessToken: Effect.succeed(false),
+    deleteProjectCredential: () => Effect.succeed(false),
   });
 }