refactor(stack): narrow package entrypoints

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

@@ -1,5 +1,4 @@
 import { StateManager, daemonLayer, resolveManagedStack, stopDaemon } from "@supabase/stack/effect";
-import { daemonEntryPoint } from "@supabase/stack";
 import { Effect, Option } from "effect";
 import { PlatformApi } from "../../../auth/platform-api.service.ts";
 import { CliConfig } from "../../../config/cli-config.service.ts";
@@ -154,17 +153,14 @@ export const switchBranch = Effect.fn("branches.switch")(function* (opts: {
       },
     });
 
-    const stackLayer = yield* daemonLayer(
-      {
-        cacheRoot: cliConfig.supabaseHome,
-        cwd: runtimeInfo.cwd,
-        projectDir: projectHome.projectRoot,
-        projectStateRoot: projectHome.projectHomeDir,
-        name: stackState.name,
-        ...launchConfig,
-      },
-      daemonEntryPoint,
-    );
+    const stackLayer = yield* daemonLayer({
+      cacheRoot: cliConfig.supabaseHome,
+      cwd: runtimeInfo.cwd,
+      projectDir: projectHome.projectRoot,
+      projectStateRoot: projectHome.projectHomeDir,
+      name: stackState.name,
+      ...launchConfig,
+    });
 
     yield* Effect.scoped(
       Effect.gen(function* () {

apps/cli/src/next/commands/functions/dev/dev.command.ts

@@ -1,5 +1,4 @@
-import { unixHttpClientLayer } from "@supabase/stack";
-import { DEFAULT_MANAGED_STACK_NAME } from "@supabase/stack/effect";
+import { DEFAULT_MANAGED_STACK_NAME, unixHttpClientLayer } from "@supabase/stack/effect";
 import { Layer } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";

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

@@ -1,4 +1,3 @@
-import { daemonEntryPoint } from "@supabase/stack";
 import {
   connectLayer,
   daemonLayer,
@@ -68,18 +67,15 @@ const startFullStack = Effect.fnUntraced(function* (opts: FunctionsDevStackOptio
   yield* ensureProjectStateIgnored(projectHome.projectRoot);
 
   const serviceVersionContext = yield* resolveServiceVersionContext([], undefined);
-  const stackLayer = yield* daemonLayer(
-    {
-      cacheRoot: cliConfig.supabaseHome,
-      cwd: runtimeInfo.cwd,
-      projectDir: projectHome.projectRoot,
-      projectStateRoot: projectHome.projectHomeDir,
-      name: opts.stack,
-      edgeRuntime: opts.edgeRuntime,
-      ...versionsFromContext(serviceVersionContext),
-    },
-    daemonEntryPoint,
-  );
+  const stackLayer = yield* daemonLayer({
+    cacheRoot: cliConfig.supabaseHome,
+    cwd: runtimeInfo.cwd,
+    projectDir: projectHome.projectRoot,
+    projectStateRoot: projectHome.projectHomeDir,
+    name: opts.stack,
+    edgeRuntime: opts.edgeRuntime,
+    ...versionsFromContext(serviceVersionContext),
+  });
   const state = yield* stateManager.read(opts.stack);
 
   yield* stateManager.writeMetadata(

apps/cli/src/next/commands/functions/list/list.integration.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "@effect/vitest";
 import { FunctionResponse } from "@supabase/api/effect";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { mkdtempSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";

apps/cli/src/next/commands/functions/new/new.integration.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { existsSync, mkdtempSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { Effect, Exit, Fiber, Layer } from "effect";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";

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

@@ -7,7 +7,6 @@ import {
   stackMetadata,
   type StackMetadata,
 } from "@supabase/stack/effect";
-import { daemonEntryPoint } from "@supabase/stack";
 import { Command, Flag } from "effect/unstable/cli";
 import type * as CliCommand from "effect/unstable/cli/Command";
 import { projectLocalServiceVersionsLayer } from "../../config/project-local-service-versions.layer.ts";
@@ -197,17 +196,14 @@ export const startCommand = Command.make("start", flags).pipe(
       yield* output.intro("Start local Supabase stack");
       yield* ensureProjectStateIgnored(projectHome.projectRoot);
 
-      const stackLayer = yield* daemonLayer(
-        {
-          cacheRoot: cliConfig.supabaseHome,
-          cwd: runtimeInfo.cwd,
-          projectDir: projectHome.projectRoot,
-          projectStateRoot: projectHome.projectHomeDir,
-          name: flags.stack,
-          ...stackConfig,
-        },
-        daemonEntryPoint,
-      );
+      const stackLayer = yield* daemonLayer({
+        cacheRoot: cliConfig.supabaseHome,
+        cwd: runtimeInfo.cwd,
+        projectDir: projectHome.projectRoot,
+        projectStateRoot: projectHome.projectHomeDir,
+        name: flags.stack,
+        ...stackConfig,
+      });
       const daemonState = yield* stateManager.read(flags.stack);
 
       const metadata = stackMetadata({

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "@effect/vitest";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { StackServiceState } from "@supabase/stack/effect";
 import { Effect, Layer } from "effect";
 import { status } from "./status.handler.ts";

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

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Effect, Exit, Layer } from "effect";
 import { BunServices } from "@effect/platform-bun";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { stop } from "./stop.handler.ts";
 import { mockOutput, withEnv } from "../../../../tests/helpers/mocks.ts";
 import {

apps/cli/src/shared/cli/run.ts

@@ -1,6 +1,6 @@
 import { BunServices } from "@effect/platform-bun";
 import { ProjectConfigStore } from "@supabase/config";
-import { unixHttpClientLayer } from "@supabase/stack";
+import { unixHttpClientLayer } from "@supabase/stack/effect";
 import { Cause, Console, Effect, Exit, Fiber, Layer, Runtime, Stdio } from "effect";
 import { CliError, CliOutput, Command } from "effect/unstable/cli";
 import { CLI_VERSION } from "./version.ts";

apps/cli/tests/helpers/mocks.ts

@@ -14,7 +14,7 @@ import {
   type StackMetadata,
   type StackState,
 } from "@supabase/stack/effect";
-import { UnixHttpClient } from "@supabase/stack";
+import { UnixHttpClient } from "@supabase/stack/testing";
 import { Api } from "../../src/next/auth/api.service.ts";
 import type { LoginSessionResponse, ProfileResponse } from "../../src/next/auth/api.service.ts";
 import { Credentials } from "../../src/next/auth/credentials.service.ts";

apps/cli/tests/helpers/running-stack.ts

@@ -1,8 +1,6 @@
 import { BunServices } from "@effect/platform-bun";
 import * as BunHttpServer from "@effect/platform-bun/BunHttpServer";
-import { unixHttpClientLayer } from "@supabase/stack";
 import {
-  DaemonServer,
   DEFAULT_VERSIONS,
   fullVersionManifest,
   type PartialVersionManifest,
@@ -14,7 +12,9 @@ import {
   type StackInfo,
   type StackMetadata,
   type StackState,
+  unixHttpClientLayer,
 } from "@supabase/stack/effect";
+import { DaemonServer } from "@supabase/stack/testing";
 import { Effect, Layer, ManagedRuntime, Option, Stream } from "effect";
 import { spawn, type ChildProcess } from "node:child_process";
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";

packages/stack/docs/architecture.md

@@ -11,12 +11,14 @@ The package exposes two levels of Interface:
 
 - `@supabase/stack` selects `bun.ts` or `node.ts` through export conditions and exposes the
   Promise-oriented `createStack()` / `StackHandle` Interface plus prefetch helpers.
-- `@supabase/stack/effect` exposes Effect Interfaces and layer factories used by the CLI and
-  advanced callers.
+- `@supabase/stack/effect` selects a runtime Adapter through the same export conditions and exposes
+  Effect Interfaces plus platform-bound layer factories used by the CLI and advanced callers.
+- `@supabase/stack/testing` exposes only the service tags needed to replace daemon transport in
+  consumer tests. Runtime implementation tags do not leak through the root or Effect barrels.
 
-The root runtime Adapters provide Effect filesystem, path, child-process, HTTP-server, and Unix
-socket HTTP implementations. `createStack.ts` remains platform-agnostic and receives a
-`PlatformFactory`.
+Internal runtime Adapters provide Effect filesystem, path, child-process, HTTP-server, and Unix
+socket HTTP implementations. `createStack.ts` and the layer factories remain platform-agnostic;
+the conditional root and Effect entries bind them to their selected runtime.
 
 ```mermaid
 flowchart LR
@@ -293,12 +295,15 @@ Callers may explicitly supply `projectStateRoot`, in which case durable stacks l
 ## Runtime entrypoints and exports
 
 - `bun.ts` and `node.ts` are root export-condition targets.
+- `effect-bun.ts` and `effect-node.ts` are Effect export-condition targets. They bind foreground,
+  daemon, and Unix-socket layers without exposing raw platform factories or bootstrap paths.
 - `daemon-bun.ts` is exported as `@supabase/stack/daemon-bun` so the compiled CLI can dispatch to
   it in-process.
-- `daemon-node.ts` is intentionally not a package export. `node.ts` resolves it by file URL and
-  passes that filesystem path to `daemonLayer`; the package `knip.entry` list preserves this live
-  file-URL-only entrypoint.
-- `effect.ts` is the low-level Effect export used by the CLI. There is no `internals.ts` entrypoint.
+- `daemon-node.ts` is intentionally not a package export. The internal Node platform Adapter
+  resolves it by file URL and passes that filesystem path to `daemonLayer`; the package
+  `knip.entry` list preserves this live file-URL-only entrypoint.
+- `effect.ts` is the platform-agnostic consumer contract re-exported by the conditional Effect
+  entries. There is no general-purpose `internals.ts` entrypoint.
 
 ## Testing
 

packages/stack/docs/detach-mode.md

@@ -163,20 +163,21 @@ crash-recovery metadata is deliberately separate from user-facing `/status` conn
 
 ## Package entrypoints
 
-| File                  | Reachability and role                                                                                         |
-| --------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `src/daemon.ts`       | Shared daemon protocol and lifecycle; receives runtime-specific HTTP-server factories.                        |
-| `src/daemon-bun.ts`   | Bun daemon Adapter. Exported as `@supabase/stack/daemon-bun` for compiled CLI dispatch.                       |
-| `src/daemon-node.ts`  | Node daemon Adapter. Intentionally file-URL-only: `node.ts` resolves its path and passes it to `daemonLayer`. |
-| `src/DaemonServer.ts` | Unix-socket HTTP/SSE Adapter over `Stack`.                                                                    |
-| `src/RemoteStack.ts`  | Remote Effect `Stack` Adapter over that transport.                                                            |
-| `src/layers.ts`       | Foreground, foreground-daemon, forked-daemon, and connect layer composition.                                  |
-| `src/StateManager.ts` | Durable metadata, live-state claims, scanning, stale-state removal, and deletion.                             |
-| `src/effect.ts`       | Effect-facing exports consumed by the CLI and advanced callers.                                               |
-
-There is no `internals.ts`. `daemon-node.ts` is not a package export because Node root consumers
-reach it by the file URL returned from `node.ts`; it is listed under `knip.entry` in `package.json`
-so static unused-code analysis preserves that live entrypoint.
+| File                  | Reachability and role                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `src/daemon.ts`       | Shared daemon protocol and lifecycle; receives runtime-specific HTTP-server factories.                  |
+| `src/daemon-bun.ts`   | Bun daemon Adapter. Exported as `@supabase/stack/daemon-bun` for compiled CLI dispatch.                 |
+| `src/daemon-node.ts`  | Node daemon Adapter. Intentionally file-URL-only: the internal Node platform Adapter resolves its path. |
+| `src/DaemonServer.ts` | Unix-socket HTTP/SSE Adapter over `Stack`.                                                              |
+| `src/RemoteStack.ts`  | Remote Effect `Stack` Adapter over that transport.                                                      |
+| `src/layers.ts`       | Foreground, foreground-daemon, forked-daemon, and connect layer composition.                            |
+| `src/StateManager.ts` | Durable metadata, live-state claims, scanning, stale-state removal, and deletion.                       |
+| `src/effect-*.ts`     | Conditional Effect entries that bind consumer layers to Bun or Node.                                    |
+| `src/effect.ts`       | Platform-agnostic Effect contracts re-exported by the conditional entries.                              |
+
+There is no `internals.ts`. `daemon-node.ts` is not a package export because the Node Effect
+Adapter reaches it through the file URL returned by the internal platform module; it is listed
+under `knip.entry` in `package.json` so static unused-code analysis preserves that live entrypoint.
 
 ## Compiled executable re-entry
 

packages/stack/package.json

@@ -8,7 +8,11 @@
       "bun": "./src/bun.ts",
       "default": "./src/node.ts"
     },
-    "./effect": "./src/effect.ts",
+    "./effect": {
+      "bun": "./src/effect-bun.ts",
+      "default": "./src/effect-node.ts"
+    },
+    "./testing": "./src/testing.ts",
     "./daemon-bun": "./src/daemon-bun.ts"
   },
   "scripts": {

packages/stack/src/JwtGenerator.ts

@@ -1,5 +1,4 @@
 import { createHmac } from "node:crypto";
-import { Effect, Layer, Context } from "effect";
 
 // Hardcoded opaque key defaults matching Go CLI (pkg/config/apikeys.go:19-20).
 // These are client-facing keys for local dev — SDKs use these, not JWTs directly.
@@ -10,8 +9,7 @@ export const defaultSecretKey = "sb_secret_N7UND0UgjKTVK-Uodkm0Hg_xSvEMPvz";
 export const defaultJwtSecret = "super-secret-jwt-token-with-at-least-32-characters-long";
 
 /**
- * Pure synchronous JWT generation. Used both by the JwtGenerator service
- * and directly in createStack() where JWTs are needed before layers run.
+ * Pure synchronous JWT generation used while resolving stack configuration.
  */
 export function generateJwt(secret: string, role: string): string {
   const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
@@ -38,16 +36,3 @@ export function generateJwks(secret: string): string {
     ],
   });
 }
-
-export class JwtGenerator extends Context.Service<
-  JwtGenerator,
-  {
-    readonly generate: (secret: string, role: string) => Effect.Effect<string>;
-    readonly generateJwks: (secret: string) => Effect.Effect<string>;
-  }
->()("local/JwtGenerator") {
-  static layer: Layer.Layer<JwtGenerator> = Layer.succeed(this, {
-    generate: (secret: string, role: string) => Effect.sync(() => generateJwt(secret, role)),
-    generateJwks: (secret: string) => Effect.sync(() => generateJwks(secret)),
-  });
-}

packages/stack/src/UnixSocketSse.integration.test.ts

@@ -10,7 +10,7 @@ import { DaemonServer } from "./DaemonServer.ts";
 import { RemoteStack } from "./RemoteStack.ts";
 import { Stack, type StackInfo } from "./Stack.ts";
 import { StackServiceState } from "./StackServiceState.ts";
-import { unixHttpClientLayer } from "./bun.ts";
+import { unixHttpClientLayer } from "./platform-bun.ts";
 
 const REFERENCE_IDLE_TIMEOUT_SECONDS = 1;
 // Keep the idle gap just past a short reference timeout so the suite stays fast.

packages/stack/src/bun.ts

@@ -1,59 +1,17 @@
 import { BunServices } from "@effect/platform-bun";
-import * as BunHttpServer from "@effect/platform-bun/BunHttpServer";
-import { fileURLToPath } from "node:url";
 import { Effect, Layer } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { BinaryResolver } from "./BinaryResolver.ts";
-import {
-  createStack as createStackCore,
-  type PlatformFactory,
-  type StackHandle,
-} from "./createStack.ts";
+import { createStack as createStackCore, type StackHandle } from "./createStack.ts";
 import {
   prefetch as prefetchEffect,
   type PrefetchOptions,
   type PrefetchResult,
 } from "./prefetch.ts";
 import { defaultCacheRoot } from "./paths.ts";
+import { platformFactory } from "./platform-bun.ts";
 import { StackPreparation } from "./StackPreparation.ts";
 import type { StackConfig } from "./StackConfig.ts";
-import { UnixHttpClient, UnixHttpClientError } from "./UnixHttpClient.ts";
-
-interface BunUnixRequestInit extends RequestInit {
-  readonly unix: string;
-}
-
-export const unixHttpClientLayer = Layer.succeed(UnixHttpClient, {
-  request: (socketPath, path, init) =>
-    Effect.tryPromise({
-      try: () => {
-        const requestInit: BunUnixRequestInit = {
-          ...init,
-          unix: socketPath,
-        };
-        return fetch(`http://localhost${path}`, requestInit);
-      },
-      catch: (cause) => new UnixHttpClientError({ socketPath, path, cause }),
-    }),
-});
-
-// ---------------------------------------------------------------------------
-// Platform values — for use with Effect layer factories
-// ---------------------------------------------------------------------------
-
-/** Bun platform factory for use with foregroundLayer / daemonLayer. */
-export const platformFactory: PlatformFactory = ({ apiPort, releaseApiPort }) =>
-  Layer.mergeAll(
-    BunServices.layer,
-    Layer.unwrap(releaseApiPort.pipe(Effect.as(BunHttpServer.layer({ port: apiPort })))),
-  );
-
-/** Path to the Bun daemon entry point for use with daemonLayer. */
-export const daemonEntryPoint: string = fileURLToPath(new URL("./daemon-bun.ts", import.meta.url));
-
-// ---------------------------------------------------------------------------
-// Promise API — convenience wrappers for non-Effect consumers
-// ---------------------------------------------------------------------------
 
 export async function createStack(config?: StackConfig): Promise<StackHandle> {
   return createStackCore(config, platformFactory);