alchemy 2.0.0-beta.76 → 2.0.0-beta.78

package/src/Local/LocalProvider.ts

@@ -6,7 +6,7 @@ import * as Fiber from "effect/Fiber";
 import * as Redacted from "effect/Redacted";
 import * as Scope from "effect/Scope";
 import * as Semaphore from "effect/Semaphore";
-import type { ScopedPlanStatusSession } from "../Cli/Cli.ts";
+import type { ScopedPlanStatusSession } from "../Report.ts";
 import { isResolved, stripEffects, type Diff } from "../Diff.ts";
 import type { Platform } from "../Platform.ts";
 import type { ProviderService } from "../Provider.ts";
@@ -267,7 +267,8 @@ export const canonicalHash = (value: unknown): Effect.Effect<string> => {
  * a per-id semaphore so restarts never interleave.
  *
  * @param cls - the resource class (or Platform) this provider serves.
- * @param serverEntryUrl - sidecar entry module (see {@link RpcProvider.effect}).
+ * @param providersUrl - the provider group module this provider is registered
+ *   in (see {@link RpcProvider.effect}).
  * @param spec - Effect constructing the {@link LocalProviderSpec}; resolve
  *   the services your callbacks need here and close over them.
  */
@@ -278,12 +279,12 @@ export const make = <
   Req = never,
 >(
   cls: ResourceClassLike<R> | Platform<R, any, any, any, any>,
-  serverEntryUrl: string,
+  providersUrl: string,
   spec: Effect.Effect<LocalProviderSpec<R, Config, StartR>, never, Req>,
 ) =>
   RpcProvider.effect(
     cls,
-    serverEntryUrl,
+    providersUrl,
     Effect.gen(function* () {
       const {
         resolveConfig = defaultResolveConfig<R, Config>,
@@ -456,7 +457,7 @@ export const make = <
               if (existing) {
                 if (existing.configHash === configHash) {
                   yield* Effect.log(
-                    `[${id}] No changes, using existing instance`,
+                    `[${fqn}] No changes, using existing instance`,
                   );
                   // Adopt the newest instanceId so a later replacement's
                   // old-generation delete cannot tear this instance down.
@@ -464,7 +465,7 @@ export const make = <
                   return yield* Fiber.join(existing.fiber);
                 }
                 yield* Effect.log(
-                  `[${id}] Changes detected, restarting instance`,
+                  `[${fqn}] Changes detected, restarting instance`,
                 );
                 yield* teardown(existing);
                 instances.delete(fqn);

package/src/Local/ProviderLayer.ts

@@ -14,15 +14,18 @@ import type { ResourceClassLike, ResourceLike } from "../Resource.ts";
  * implementation, making provider mode a first-class, per-run *and*
  * per-resource concern:
  *
- * - The `Provider(type)` service placed in context is the variant for the
- *   run's default mode (`AlchemyContext.dev ? "local" : "live"`), so
- *   existing lookups keep working unchanged.
- * - Both variants are additionally exposed via
- *   {@link ProviderService.modes} as lazy, memoized builders. The
- *   non-default variant (and its mode-specific dependency layers, composed
- *   inside the thunk) is only constructed when something actually demands
- *   it — e.g. deleting a `providerMode: "local"` state row during a live
- *   deploy.
+ * - The `Provider(type)` service placed in context delegates to the
+ *   variant for the run's default mode (`AlchemyContext.dev ? "local" :
+ *   "live"`). `findProvider` resolves the concrete variant, including its
+ *   optional lifecycle methods and metadata.
+ * - Both variants are exposed via {@link ProviderService.modes} as lazy,
+ *   memoized builders. NEITHER is constructed at registration: a variant
+ *   (and the mode-specific dependency layers composed inside its thunk) is
+ *   built the first time something demands it — planning a resource of
+ *   this type, deleting a state row stamped with its mode, a nuke scan. A
+ *   dual provider whose resources never appear in a run costs nothing, and
+ *   in dev the sidecar process a local variant spawns only starts once a
+ *   resource of its type is actually planned.
  *
  * Laziness mechanics: the layer is a {@link Layer.fromBuildMemo}, so the
  * build itself is memoized by layer identity (one provider instance — and
@@ -129,14 +132,27 @@ export const dual = <
         local: Effect.orDie(cached.local),
       };
 
-      // The default-mode variant builds eagerly — matching today's cost
-      // profile (`select` built exactly this variant) and guaranteeing the
-      // registered service has real method presence (`provider.read`,
-      // `provider.precreate`, ...) for Plan's capability checks.
-      const defaultService = yield* cached[defaultMode];
+      // Every engine path resolves a concrete variant through
+      // `providerForMode` and reads optional-method presence (`read`,
+      // `precreate`, `tail`, `logs`), `version`, `stables` and `nuke`
+      // there. The registered service therefore only needs the required
+      // lifecycle methods for structural provider checks and direct
+      // registration access — each forwarding to the default
+      // variant, built on first call.
+      const variant = modes[defaultMode];
 
       return Context.make(Provider(cls.Type) as any, {
-        ...defaultService,
+        aliases: "Aliases" in cls ? cls.Aliases : undefined,
+        diff: (input) =>
+          Effect.flatMap(variant, (service) =>
+            service.diff === undefined ? Effect.void : service.diff(input),
+          ),
+        reconcile: (input) =>
+          Effect.flatMap(variant, (service) => service.reconcile(input)),
+        delete: (input) =>
+          Effect.flatMap(variant, (service) => service.delete(input)),
+        list: (...args) =>
+          Effect.flatMap(variant, (service) => service.list(...args)),
         mode: defaultMode,
         modes,
         localDataPlane: input.dataPlane,

package/src/Local/RpcProvider.ts

@@ -42,7 +42,7 @@ import { RpcProviderProxy } from "./RpcProviderProxy.ts";
  * ```
  *
  * @param cls - The tag of the resource class to construct a provider for.
- * @param serverEntryUrl - The main file for the server entry point, if the provider is to be run in a separate process. This is typically obtained using `import.meta.url` or `import.meta.resolve`.
+ * @param providersUrl - URL of the module whose default export is the provider group's layer (the layer this provider is registered in). When the provider runs in the dev sidecar, the sidecar imports that module on first use — see `Local/Sidecar.ts`. Typically `import.meta.resolve("./Local.ts")`.
  * @param eff - The Effect to use to construct the provider.
  * @returns A layer containing the RpcProvider.
  */
@@ -166,7 +166,7 @@ export const effect = <
   ListReq = never,
 >(
   cls: ResourceClassLike<R> | Platform<R, any, any, any, any, any>,
-  serverEntryUrl: string,
+  providersUrl: string,
   eff: Effect.Effect<
     RpcProviderService<
       R,
@@ -223,7 +223,7 @@ export const effect = <
           },
         });
       }
-      return withDefaultList(yield* client.value.get(serverEntryUrl, cls.Type));
+      return withDefaultList(yield* client.value.get(providersUrl, cls.Type));
     }),
   );
 

package/src/Local/RpcProviderProxy.ts

@@ -21,8 +21,13 @@ import type { RpcSpawnPayload } from "./RpcSpawner.ts";
 export class RpcProviderProxy extends Context.Service<
   RpcProviderProxy,
   {
+    /**
+     * The provider for `providerName`, served by the dev sidecar. `providersUrl`
+     * is the URL of the module whose default export is the provider group's
+     * layer (see `Local/Sidecar.ts`); the sidecar imports it on first use.
+     */
     readonly get: <R extends ResourceLike>(
-      serverEntryUrl: string,
+      providersUrl: string,
       providerName: R["Type"],
     ) => Effect.Effect<ProviderService<R>, never, AlchemyContext | Stack>;
   }
@@ -31,23 +36,25 @@ export class RpcProviderProxy extends Context.Service<
 export const SPAWNER_URL_ENV_KEY = "ALCHEMY_RPC_SPAWNER_URL" as const;
 
 /**
- * Separator for the session-cache key. `\u0000` cannot appear in either half:
- * JSON.stringify escapes control characters and URLs cannot carry raw NULs.
+ * The one sidecar entry every RPC-backed provider is served from.
+ * Resolve through package exports so this also works when the proxy is
+ * bundled into `bin/exec.js`. The active export conditions select `src/`
+ * under Bun or the dev loader and `lib/` in a published Node install.
  */
-const SESSION_KEY_SEPARATOR = "\u0000";
+export const SIDECAR_ENTRY_URL = import.meta.resolve("alchemy/Local/Sidecar");
 
 const make = Effect.fn(function* (spawnerUrl: string) {
   const client = yield* HttpClient.HttpClient;
 
   const getSession = Effect.fn(
-    function* (serverEntryUrl: string, sessionEnv: string) {
-      const payload: RpcSpawnPayload = { serverEntryUrl };
+    function* (sessionEnv: string) {
+      const payload: RpcSpawnPayload = { serverEntryUrl: SIDECAR_ENTRY_URL };
       const response = yield* client.post(spawnerUrl, {
         body: yield* HttpBody.json(payload),
       });
-      // The spawner returns one shared child per entry URL; the stack-specific
+      // The spawner returns the one shared sidecar; the stack-specific
       // environment rides the session websocket so the child can build (and
-      // memoize) a provider context per stack.
+      // memoize) a provider context per stack and provider group.
       const body = yield* response.text;
       if (response.status !== 200) {
         return yield* Effect.fail(
@@ -76,11 +83,11 @@ const make = Effect.fn(function* (spawnerUrl: string) {
       websocketUrl.searchParams.set(SESSION_ENV_PARAM, sessionEnv);
       return newWebSocketRpcSession<RpcProxyApi>(websocketUrl.toString());
     },
-    (effect, serverEntryUrl) =>
+    (effect) =>
       Effect.catch(effect, (error) =>
         Effect.die(
           new Error(
-            `Failed to create provider RPC session for "${serverEntryUrl}"`,
+            "Failed to create a provider RPC session with the sidecar",
             {
               cause: error,
             },
@@ -97,33 +104,33 @@ const make = Effect.fn(function* (spawnerUrl: string) {
   // died). Assigned after the cache exists; the callback only fires on live
   // sessions, which the cache must already contain.
   let evictBrokenSession: (key: string) => void = () => {};
+  // One session per stack environment, shared by every provider group.
   const cache = yield* Cache.make({
-    lookup: (key: string) => {
-      const separator = key.indexOf(SESSION_KEY_SEPARATOR);
-      return getSession(key.slice(0, separator), key.slice(separator + 1)).pipe(
+    lookup: (sessionEnv: string) =>
+      getSession(sessionEnv).pipe(
         Effect.tap((session) =>
-          Effect.sync(() => session.onRpcBroken(() => evictBrokenSession(key))),
+          Effect.sync(() =>
+            session.onRpcBroken(() => evictBrokenSession(sessionEnv)),
+          ),
         ),
-      );
-    },
+      ),
     capacity: Infinity,
   });
   evictBrokenSession = (key) => Effect.runFork(Cache.invalidate(cache, key));
 
   return RpcProviderProxy.of({
-    get: Effect.fn(function* (mainUrl, providerName) {
+    get: Effect.fn(function* (providersUrl, providerName) {
       const alchemyContext = yield* AlchemyContext;
       const stack = yield* Stack;
-      const sessionEnv = encodeSessionEnvironment({
+      const key = encodeSessionEnvironment({
         alchemyContext,
         stack: { name: stack.name, stage: stack.stage },
       });
-      const key = mainUrl + SESSION_KEY_SEPARATOR + sessionEnv;
       const fetchProvider = Effect.gen(function* () {
         const session = yield* Cache.get(cache, key);
         return yield* Effect.tryPromise(
           () =>
-            session.getProvider(providerName) as ReturnType<
+            session.getProvider(providerName, providersUrl) as ReturnType<
               RpcProxyApi["getProvider"]
             >,
         );
@@ -150,5 +157,5 @@ export const layer = (url: string) => Layer.effect(RpcProviderProxy, make(url));
 export const fromEnv = () =>
   Layer.effect(
     RpcProviderProxy,
-    Config.string(SPAWNER_URL_ENV_KEY).pipe(Effect.flatMap(make)),
+    Config.String(SPAWNER_URL_ENV_KEY).pipe(Effect.flatMap(make)),
   );

package/src/Local/RpcServer.ts

@@ -3,8 +3,10 @@ import * as Context from "effect/Context";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
 import type * as Scope from "effect/Scope";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { makePlainConsoleSink } from "../Util/ConsoleSink.ts";
 import type { HttpClient } from "effect/unstable/http/HttpClient";
 import { ArtifactStore, createArtifactStore } from "../Artifacts.ts";
 import type { ProviderService } from "../Provider.ts";
@@ -49,12 +51,38 @@ export interface RpcProxyApi {
   /**
    * Retrieves a provider from the RPC server context.
    * The consumer must unwrap the provider using {@link RpcSerialization.unwrapRpcHandlers} before using it.
+   *
+   * `group` names the provider group the type belongs to: for a server
+   * launched with a group loader (the dev sidecar, see `Local/Sidecar.ts`)
+   * it is the URL of the module whose default export is that group's
+   * provider layer, imported and built on first use per session. A server
+   * launched with a static layer ignores it.
    */
   readonly getProvider: <R extends ResourceLike>(
     type: R["Type"],
+    group: string,
   ) => Promise<RpcSerialization.RpcWrapped<RpcProviderService<R>>>;
 }
 
+/** The layer shape a served provider group must have. */
+export type ProviderLayer = Layer.Layer<
+  any,
+  any,
+  | Scope.Scope
+  | RpcServerEnvironment.RpcEnvironmentServices
+  | PlatformServices
+  | HttpClient
+  | ArtifactStore
+>;
+
+/**
+ * Resolves a provider group to its layer. Receives the `group` the client
+ * passed to {@link RpcProxyApi.getProvider}.
+ */
+export type ProviderGroupLoader = (
+  group: string,
+) => Effect.Effect<ProviderLayer, unknown>;
+
 const serverPlatformLayer = platformLayer({
   bun: async () => {
     const { RpcServerBun } = await import("./RpcServerBun.ts");
@@ -68,11 +96,12 @@ const serverPlatformLayer = platformLayer({
 
 /**
  * Per-session provider contexts. One sidecar process serves every stack in
- * a run (the test harness shares a single child across all test files), so
- * the providers layer is built lazily per distinct {@link SessionEnvironment}
- * — each build gets its own MemoMap (a shared one would dedupe the whole
- * providers layer to the first stack's build) and lives in the process's
- * root scope.
+ * a run (the test harness shares a single child across all test files) and
+ * every provider group, so each group's layer is built lazily per distinct
+ * {@link SessionEnvironment} — each build gets its own MemoMap (a shared
+ * one would dedupe the whole providers layer to the first stack's build)
+ * and lives in the process's root scope. A group whose types a session
+ * never asks for is never loaded.
  */
 export class SessionProviders extends Context.Service<
   SessionProviders,
@@ -80,21 +109,12 @@ export class SessionProviders extends Context.Service<
     readonly get: (
       sessionEnv: string | undefined,
       type: string,
+      group: string,
     ) => Promise<RpcSerialization.RpcWrapped<RpcProviderService<any>>>;
   }
 >()("alchemy/Local/SessionProviders") {}
 
-const sessionProviders = <ROut, E>(
-  providers: Layer.Layer<
-    ROut,
-    E,
-    | Scope.Scope
-    | RpcServerEnvironment.RpcEnvironmentServices
-    | PlatformServices
-    | HttpClient
-    | ArtifactStore
-  >,
-) =>
+const sessionProviders = (resolve: ProviderGroupLoader) =>
   Layer.effect(
     SessionProviders,
     Effect.gen(function* () {
@@ -106,13 +126,19 @@ const sessionProviders = <ROut, E>(
       const base = yield* RpcServerEnvironment.fromProcessEnv.pipe(
         Effect.orDie,
       );
-      const builds = new Map<string, Promise<Context.Context<ROut>>>();
+      // Built contexts by session environment, then by provider group.
+      const builds = new Map<
+        string | undefined,
+        Map<string, Promise<Context.Context<any>>>
+      >();
 
       const contextFor = (
         sessionEnv: string | undefined,
-      ): Promise<Context.Context<ROut>> => {
-        const key = sessionEnv ?? "";
-        const existing = builds.get(key);
+        group: string,
+      ): Promise<Context.Context<any>> => {
+        const session = builds.get(sessionEnv) ?? new Map();
+        builds.set(sessionEnv, session);
+        const existing = session.get(group);
         if (existing !== undefined) {
           return existing;
         }
@@ -130,40 +156,45 @@ const sessionProviders = <ROut, E>(
           );
         }
         const build = Effect.runPromise(
-          Layer.buildWithScope(
-            providers.pipe(
-              Layer.provide(
-                RpcServerEnvironment.layer({
-                  profile: base.profile,
-                  envFile: base.envFile,
-                  ...resolved,
-                }),
+          resolve(group).pipe(
+            Effect.flatMap((providers) =>
+              Layer.buildWithScope(
+                providers.pipe(
+                  Layer.provide(
+                    RpcServerEnvironment.layer({
+                      profile: base.profile,
+                      envFile: base.envFile,
+                      ...resolved,
+                    }),
+                  ),
+                ),
+                scope,
               ),
             ),
-            scope,
-          ).pipe(
             Effect.provideContext(ambient as Context.Context<any>),
-          ) as Effect.Effect<Context.Context<ROut>>,
+          ) as Effect.Effect<Context.Context<any>>,
         );
-        builds.set(key, build);
+        session.set(group, build);
         // Don't poison the memo with a transient build failure — the next
         // session for this stack retries.
         build.catch(() => {
-          if (builds.get(key) === build) {
-            builds.delete(key);
+          if (session.get(group) === build) {
+            session.delete(group);
           }
         });
         return build;
       };
 
       return SessionProviders.of({
-        get: async (sessionEnv, type) => {
-          const context = await contextFor(sessionEnv);
+        get: async (sessionEnv, type, group) => {
+          const context = await contextFor(sessionEnv, group);
           const provider = context.mapUnsafe.get(type) as
             | ProviderService<any>
             | undefined;
           if (!provider) {
-            throw new Error(`Provider "${type}" not found`);
+            throw new Error(
+              `Provider "${type}" not found in provider group ${group}`,
+            );
           }
           // Strip the process-local variant machinery (see
           // RpcProviderService above) — lazy Effects don't serialize.
@@ -178,10 +209,16 @@ const sessionProviders = <ROut, E>(
   );
 
 /**
- * Launches an RPC server that serves the given providers.
+ * Launches an RPC server that serves providers.
  * Alchemy globals such as `AlchemyContext`, `Profile`, and `Stack` are inherited from the parent via {@link RpcServerEnvironment.fromEnv} and should not be provided manually.
  * `PlatformServices` and `HttpClient` are also included.
  *
+ * Pass a layer to serve a fixed set of providers, or a
+ * {@link ProviderGroupLoader} to resolve the group each client names — the
+ * dev sidecar (`Local/Sidecar.ts`) imports the group module on demand, so
+ * one process serves every provider group without loading the ones a run
+ * never touches.
+ *
  * @example
  * ```ts
  * RpcServer.launch(
@@ -192,21 +229,16 @@ const sessionProviders = <ROut, E>(
  * );
  * ```
  *
- * @param providers - A layer containing the providers to serve.
+ * @param providers - A layer containing the providers to serve, or a loader
+ *   from group to layer.
  */
-export const launch = <ROut, E>(
-  providers: Layer.Layer<
-    ROut,
-    E,
-    | Scope.Scope
-    | RpcServerEnvironment.RpcEnvironmentServices
-    | PlatformServices
-    | HttpClient
-    | ArtifactStore
-  >,
-) =>
+export const launch = (providers: ProviderLayer | ProviderGroupLoader) =>
   serverPlatformLayer.pipe(
-    Layer.provide(sessionProviders(providers)),
+    Layer.provide(
+      sessionProviders(
+        Layer.isLayer(providers) ? () => Effect.succeed(providers) : providers,
+      ),
+    ),
     Layer.provide(
       Layer.mergeAll(
         PlatformServices,
@@ -214,6 +246,15 @@ export const launch = <ROut, E>(
         Layer.sync(ArtifactStore, createArtifactStore),
       ),
     ),
+    // Sidecar stdio is piped, so effect's default pretty logger disables
+    // colors (it only checks `isTTY`, never FORCE_COLOR). The spawner sets
+    // FORCE_COLOR exactly when the destination terminal supports color —
+    // honor it here so sidecar log lines match the rest of the dev output.
+    Layer.provide(
+      process.env.FORCE_COLOR
+        ? Logger.layer([makePlainConsoleSink(true)])
+        : Layer.empty,
+    ),
     Layer.launch,
     Effect.scoped,
     runMain,
@@ -250,8 +291,15 @@ export const layerServer = (
       const { url } = yield* serve({
         createRpcSession: (ws, sessionEnv) =>
           makeServerRpcSession<RpcProxyApi>(ws, {
-            getProvider: (<R extends ResourceLike>(type: R["Type"]) =>
-              providers.get(sessionEnv, type)) as RpcProxyApi["getProvider"],
+            getProvider: (<R extends ResourceLike>(
+              type: R["Type"],
+              group: string,
+            ) =>
+              providers.get(
+                sessionEnv,
+                type,
+                group,
+              )) as RpcProxyApi["getProvider"],
           }),
         parentConnected: () => Deferred.doneUnsafe(connected, Effect.void),
         parentDisconnected: () =>

package/src/Local/RpcServerEnvironment.ts

@@ -6,7 +6,8 @@ import * as Option from "effect/Option";
 import { AlchemyContext } from "../AlchemyContext.ts";
 import { AuthProviders } from "../Auth/AuthProvider.ts";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
-import { ProfileLive, withProfileOverride } from "../Auth/Profile.ts";
+import { ProfileStoreLive } from "../Auth/Profile.ts";
+import { withProfileOverride } from "../Auth/Resolve.ts";
 import { Stack } from "../Stack.ts";
 import { Stage } from "../Stage.ts";
 import { loadConfigProvider } from "../Util/ConfigProvider.ts";
@@ -57,7 +58,7 @@ export const layer = (
     SessionEnvironment,
 ) =>
   Layer.mergeAll(
-    ProfileLive,
+    ProfileStoreLive,
     CredentialsStoreLive,
     Layer.succeed(AuthProviders, {}),
     ConfigProvider.layer(
@@ -81,7 +82,7 @@ export const RPC_SERVER_ENVIRONMENT_KEY =
 
 /** The spawn-time environment the parent baked into the child's process env. */
 export const fromProcessEnv: Effect.Effect<RpcServerEnvironment, unknown> =
-  Config.string(RPC_SERVER_ENVIRONMENT_KEY).pipe(
+  Config.String(RPC_SERVER_ENVIRONMENT_KEY).pipe(
     Config.map((raw) => JSON.parse(raw) as RpcServerEnvironment),
   );