The best way to control Claude Code, Codex and more from any computer or phone

main
ts 872 lines 35.3 KB
Raw
1 import { stripVTControlCharacters } from "node:util";
2 import { AdoptPolicy } from "alchemy/AdoptPolicy";
3 import { AlchemyContext, AlchemyContextLive } from "alchemy/AlchemyContext";
4 import { ArtifactStore, provideFreshArtifactStore } from "alchemy/Artifacts";
5 import { AuthProviders } from "alchemy/Auth/AuthProvider";
6 import { CredentialsStoreLive } from "alchemy/Auth/Credentials";
7 import { ProfileStoreLive } from "alchemy/Auth/Profile";
8 import { withProfileOverride } from "alchemy/Auth/Resolve";
9 import { userStage } from "alchemy/Cli/commands/flags";
10 import { LoggingCli } from "alchemy/Cli/LoggingCli";
11 import * as Contributions from "alchemy/Contributions";
12 import * as AlchemyDeploy from "alchemy/Deploy";
13 import * as AlchemyDestroy from "alchemy/Destroy";
14 import type { Input } from "alchemy/Input";
15 import * as Interaction from "alchemy/Interaction";
16 import * as RpcProviderProxy from "alchemy/Local/RpcProviderProxy";
17 import * as RpcSpawner from "alchemy/Local/RpcSpawner";
18 import { ALCHEMY_DEV } from "alchemy/Phase";
19 import * as Plan from "alchemy/Plan";
20 import type { ResourceSelection, SelectionOutput } from "alchemy/ResourceSelection";
21 import {
22 type CompiledStack,
23 make as makeStack,
24 Stack,
25 type StackDefinition,
26 type StackEffect,
27 type StackServices,
28 } from "alchemy/Stack";
29 import { Stage } from "alchemy/Stage";
30 import * as State from "alchemy/State";
31 import { TelemetryLive } from "alchemy/Telemetry/Layer";
32 import { loadConfigProvider, StackConfigOverrides } from "alchemy/Util/ConfigProvider";
33 import { kindOf, recordOf } from "alchemy/Util/LogRecord";
34 import { PlatformServices } from "alchemy/Util/PlatformServices";
35 /** @effect-diagnostics anyUnknownInErrorContext:off */
36 import * as Config from "effect/Config";
37 import { ConfigProvider } from "effect/ConfigProvider";
38 import * as Context from "effect/Context";
39 import * as Effect from "effect/Effect";
40 import * as Exit from "effect/Exit";
41 import * as FetchHttpClient from "effect/http/FetchHttpClient";
42 import * as HttpClient from "effect/http/HttpClient";
43 import * as Layer from "effect/Layer";
44 import * as Logger from "effect/Logger";
45 import * as Option from "effect/Option";
46 import * as Scope from "effect/Scope";
47
48 /**
49 * Configuration shared by every test in a file. Pass to `Test.make(...)`.
50 */
51 export interface MakeOptions<ROut = any> {
52 /** Provider layer for the stack — e.g. `AWS.providers()`, `Cloudflare.providers()`. */
53 providers: Layer.Layer<ROut, never, StackServices>;
54 /** State store for top-level `deploy(Stack)` / `destroy(Stack)`; defaults to {@link State.localState}. */
55 state?: Layer.Layer<State.State, never, StackServices>;
56 /** Override the current profile; otherwise resolved from env or the built-in `default`. */
57 profile?: string;
58 /**
59 * Default stage for deploy/destroy. Defaults to `test_$USER` (or
60 * `test_$USERNAME` on Windows, `test_unknown` if neither is set) so two
61 * people running the same suite against one account don't collide.
62 * Does **not** read `$ALCHEMY_STAGE` — that is the CLI deploy/dev stage.
63 */
64 stage?: string;
65 /**
66 * Engine-level adoption policy for this test run. When `true`, resources
67 * without prior state will be adopted from the cloud via `provider.read`
68 * (matching the CLI's `--adopt` flag). Defaults to `false`.
69 */
70 adopt?: boolean;
71 /**
72 * Run providers in local-dev mode (matching the CLI's `alchemy dev` flag).
73 * When `true`, resources like Cloudflare Workers run locally via workerd
74 * instead of being deployed to the cloud. When omitted, falls back to the
75 * `ALCHEMY_DEV` environment variable (`"1"` / `"true"` enable it).
76 *
77 * {@link ALCHEMY_TEST_DEV} (`ALCHEMY_TEST_DEV=1`) overrides this — use it
78 * to force an entire existing live suite through local providers without
79 * editing each `Test.make({ dev: true })`.
80 */
81 dev?: boolean;
82 /**
83 * Run local providers behind the RPC sidecar proxy, matching the process
84 * topology of the real `alchemy dev` command: an {@link RpcProviderProxy}
85 * is installed, so `RpcProvider.providerServicesEffect` layers (e.g.
86 * Cloudflare's `localRuntimeServices()`) are EMPTY in the test process and
87 * RPC-backed providers run their lifecycle in a spawned sidecar process.
88 *
89 * Defaults to the resolved `dev` flag — dev tests run the real `alchemy
90 * dev` topology unless they opt out. In-process dev (`sidecar: false`)
91 * masks missing main-process lifecycle dependencies (the class of bug
92 * behind #1007, where D1's local migrations only failed under `alchemy
93 * dev`); it remains available because it IS still a real production path —
94 * a plain `alchemy deploy` deleting a `providerMode: "local"` state row
95 * runs the local provider in-process — and because in-process runs are
96 * easier to debug.
97 *
98 * Fully lazy: only the proxy facade is installed up front. The spawner
99 * HTTP server starts — and a sidecar child process is forked — on the
100 * first provider session request (a deploy/destroy building an RPC-backed
101 * local provider); a dev file that never does starts no processes at all.
102 * Once started, the sidecar lives for the whole test file (its own scope,
103 * closed by the adapter's final cleanup hook), so `beforeAll(deploy(Stack))`
104 * + per-test requests work the same way they do under a real `alchemy dev`
105 * session.
106 *
107 * Pass an object to run the sidecar with options: `omitEnv` lists prefixes
108 * of environment variables the sidecar must not inherit (e.g.
109 * `["CLOUDFLARE_"]` to exercise credential-free dev while the shell
110 * exports credentials).
111 */
112 sidecar?: boolean | SidecarOptions;
113 }
114
115 /** Options for the dev sidecar process — see {@link MakeOptions.sidecar}. */
116 export interface SidecarOptions {
117 /** Prefixes of environment variables withheld from the sidecar. */
118 readonly omitEnv?: ReadonlyArray<string>;
119 }
120
121 /**
122 * The RPC sidecar topology used by the real `alchemy dev` command, in one
123 * process-local layer: an {@link RpcSpawner} HTTP server that forks sidecar
124 * processes on demand, and an {@link RpcProviderProxy} pointed at it.
125 */
126 export const sidecarProxy = (options: { profile?: string; omitEnv?: ReadonlyArray<string> }) =>
127 Layer.unwrap(
128 Effect.map(RpcSpawner.RpcSpawner, (spawner) => RpcProviderProxy.layer(spawner.url)),
129 ).pipe(
130 Layer.provideMerge(
131 RpcSpawner.layerServer({
132 profile: options.profile ?? process.env.ALCHEMY_PROFILE,
133 envFile: undefined,
134 omitEnv: options.omitEnv,
135 }),
136 ),
137 );
138
139 /**
140 * Force every `Test.make` into (or out of) local-dev mode, regardless of
141 * the file's `dev` option. Unset leaves the option / `ALCHEMY_DEV` fallback
142 * in place. Accepts the usual truthy/falsey strings (`true`/`1`/`yes`/`on`,
143 * `false`/`0`/`no`/`off`).
144 */
145 export const ALCHEMY_TEST_DEV = Config.Boolean("ALCHEMY_TEST_DEV").pipe(Config.option);
146
147 /** The `ALCHEMY_TEST_DEV` override, if the env var is set. */
148 export const alchemyTestDevOverride = (): Option.Option<boolean> =>
149 Effect.runSync(ALCHEMY_TEST_DEV);
150
151 /** Resolve the effective `dev` flag: `ALCHEMY_TEST_DEV`, then options, then `ALCHEMY_DEV`. */
152 export const resolveDev = (options: { dev?: boolean }): boolean => {
153 const override = alchemyTestDevOverride();
154 if (Option.isSome(override)) return override.value;
155 if (options.dev !== undefined) return options.dev;
156 return Effect.runSync(ALCHEMY_DEV);
157 };
158
159 /** Resolve the effective `sidecar` flag: defaults to the resolved `dev` flag. */
160 export const resolveSidecar = (options: MakeOptions): boolean =>
161 options.sidecar === undefined ? resolveDev(options) : options.sidecar !== false;
162
163 /** The sidecar's withheld env prefixes, sorted so equal sets share a key. */
164 const sidecarOmitEnv = (options: MakeOptions): ReadonlyArray<string> =>
165 typeof options.sidecar === "object" ? [...(options.sidecar.omitEnv ?? [])].sort() : [];
166
167 /**
168 * Default test stage: `ALCHEMY_TEST_STAGE`, then `test_$USER` (or
169 * `test_$USERNAME` / `test_unknown`). The runner sets ALCHEMY_TEST_STAGE to
170 * `test_$USER_<worktree>` in a linked git worktree, so concurrent worktrees
171 * sharing a cloud account stay isolated.
172 * Matches the CLI's `live_$USER` / `dev_$USER` per-developer isolation.
173 */
174 export const defaultStage = (): string =>
175 process.env.ALCHEMY_TEST_STAGE || Effect.runSync(userStage("test"));
176
177 /** File-level stage: a string override, otherwise {@link defaultStage}. */
178 export const resolveStage = (options: { stage?: string }): string =>
179 // Configured stacks carry a cross-stack reference proxy, not a stage override.
180 typeof options.stage === "string" ? options.stage : defaultStage();
181
182 /**
183 * The sidecar runtime handed to each adapter's `make(...)`.
184 *
185 * `provide` installs a lazy {@link RpcProviderProxy} facade into an effect.
186 * Installing the facade is free: the spawner HTTP server only starts (and,
187 * downstream of it, a sidecar child process is only forked) when a provider
188 * actually requests a session — i.e. when a deploy/destroy builds an
189 * RPC-backed local provider. A dev file that never does starts nothing.
190 *
191 * The spawner (and the sidecar children it forks) is a PROCESS-WIDE
192 * SINGLETON shared by every test file, refcounted per handle: all files run
193 * in one bun process, and a per-file sidecar means a per-file bun child that
194 * imports the entire alchemy + distilled module graph — dozens of concurrent
195 * files at hundreds of MB each OOMs the machine. Stack isolation is
196 * preserved because each RPC session carries its own stack environment (see
197 * `SESSION_ENV_PARAM` in Local/RpcServerEnvironment.ts) and the child builds
198 * a provider context per stack. The singleton's scope closes when the LAST
199 * handle closes; `Test.make` runs at collection time (before any test), so
200 * the refcount cannot dip to zero while later files still need it. Adapters
201 * run `close` from the same final cleanup hook that closes the shared scope.
202 */
203 export interface SidecarHandle {
204 readonly provide: <A, E, R>(eff: Effect.Effect<A, E, R>) => Effect.Effect<A, any, any>;
205 readonly close: Effect.Effect<void>;
206 }
207
208 interface SidecarSingleton {
209 readonly real: ReturnType<typeof sidecarProxy>;
210 readonly memoMap: Layer.MemoMap;
211 readonly scope: Scope.Closeable;
212 proxy?: RpcProviderProxy.RpcProviderProxy["Service"];
213 refs: number;
214 }
215
216 const sidecarSingletons = new Map<string, SidecarSingleton>();
217
218 /** Payload-free counts; observing them never starts the singleton. */
219 export const sidecarDiagnostics = Effect.gen(function* () {
220 const instances = [...sidecarSingletons.values()];
221 const counts = { sessions: 0, testSessions: 0, owners: 0, connections: 0 };
222 for (const instance of instances) {
223 if (instance.proxy === undefined) continue;
224 const current = yield* instance.proxy.diagnostics;
225 counts.sessions += current.sessions;
226 counts.testSessions += current.testSessions;
227 counts.owners += current.owners;
228 counts.connections += current.connections;
229 }
230 return {
231 singletons: instances.length,
232 reservations: instances.reduce((sum, instance) => sum + instance.refs, 0),
233 started: instances.filter((instance) => instance.proxy !== undefined).length,
234 ...counts,
235 };
236 });
237
238 export const makeSidecarHandle = <ROut = any>(
239 options: MakeOptions<ROut>,
240 ): SidecarHandle | undefined => {
241 if (!resolveSidecar(options)) return undefined;
242 const profile = options.profile ?? process.env.ALCHEMY_PROFILE ?? "";
243 const omitEnv = sidecarOmitEnv(options);
244 // Files only share a sidecar when it was started with the same environment.
245 const key = JSON.stringify([profile, omitEnv]);
246 let singleton = sidecarSingletons.get(key);
247 if (singleton === undefined) {
248 singleton = {
249 real: sidecarProxy({ profile: options.profile, omitEnv }),
250 memoMap: Layer.makeMemoMapUnsafe(),
251 scope: Scope.makeUnsafe("sequential"),
252 refs: 0,
253 };
254 sidecarSingletons.set(key, singleton);
255 }
256 singleton.refs += 1;
257 let runtime:
258 | {
259 instance: SidecarSingleton;
260 owner: RpcProviderProxy.SessionOwner;
261 contexts: Set<{ ambient?: Context.Context<any> }>;
262 }
263 | undefined = {
264 instance: singleton,
265 owner: RpcProviderProxy.makeSessionOwner(),
266 contexts: new Set(),
267 };
268 const lazy = Layer.effect(
269 RpcProviderProxy.RpcProviderProxy,
270 Effect.gen(function* () {
271 if (runtime === undefined) {
272 return yield* Effect.die("Test sidecar handle is closed");
273 }
274 // Never pin the singleton to a file's scope, artifacts, or layer builds.
275 const context = {
276 ambient: Context.omit(
277 Scope.Scope,
278 ArtifactStore,
279 Layer.CurrentMemoMap,
280 )(yield* Effect.context<never>()) as Context.Context<any> | undefined,
281 };
282 if (runtime === undefined) {
283 return yield* Effect.die("Test sidecar handle is closed");
284 }
285 runtime.contexts.add(context);
286 return RpcProviderProxy.RpcProviderProxy.of({
287 diagnostics: Effect.suspend(
288 () =>
289 runtime?.instance.proxy?.diagnostics ??
290 Effect.succeed({
291 sessions: 0,
292 testSessions: 0,
293 owners: 0,
294 connections: 0,
295 }),
296 ),
297 serverDiagnostics: Effect.suspend(
298 () => runtime?.instance.proxy?.serverDiagnostics ?? Effect.succeed(undefined),
299 ),
300 get: Effect.fn(function* (providersUrl, providerName) {
301 if (runtime === undefined) {
302 return yield* Effect.die("Test sidecar handle is closed");
303 }
304 const { instance, owner } = runtime;
305 let proxy = instance.proxy;
306 if (proxy === undefined) {
307 const built = yield* Layer.buildWithMemoMap(
308 instance.real,
309 instance.memoMap,
310 instance.scope,
311 ).pipe(
312 Effect.provideContext(context.ambient!),
313 Scope.provide(instance.scope),
314 Effect.orDie,
315 );
316 proxy = Context.get(built, RpcProviderProxy.RpcProviderProxy);
317 instance.proxy = proxy;
318 }
319 context.ambient = undefined;
320 runtime?.contexts.delete(context);
321 // A handle may have closed while the singleton was building.
322 return yield* proxy.get(providersUrl, providerName, owner);
323 }),
324 });
325 }),
326 );
327 return {
328 provide: (eff) => Effect.provide(eff, lazy),
329 close: Effect.suspend(() => {
330 if (runtime === undefined) return Effect.void;
331 const { instance, owner, contexts } = runtime;
332 runtime = undefined;
333 for (const context of contexts) context.ambient = undefined;
334 contexts.clear();
335 return RpcProviderProxy.closeSessionOwner(owner).pipe(
336 Effect.ensuring(
337 Effect.suspend(() => {
338 instance.refs -= 1;
339 if (instance.refs > 0) return Effect.void;
340 if (sidecarSingletons.get(key) === instance) sidecarSingletons.delete(key);
341 instance.proxy = undefined;
342 return Scope.close(instance.scope, Exit.void);
343 }),
344 ),
345 );
346 }).pipe(Effect.uninterruptible, Effect.ignore),
347 };
348 };
349
350 const overrideAlchemyContext = (overrides: { dev: boolean }) =>
351 Layer.effect(
352 AlchemyContext,
353 AlchemyContext.pipe(Effect.map((ctx) => ({ ...ctx, ...overrides }))),
354 );
355
356 export type TestEffect<A, Req = never> = StackEffect<A, any, Req>;
357
358 const testDev = Option.getOrElse(alchemyTestDevOverride(), () => false);
359
360 /**
361 * Every provider's test services (e.g. AWS's Floci emulator), applied under
362 * {@link ALCHEMY_TEST_DEV} only.
363 */
364 const testServices: ReadonlyArray<Contributions.TestServices> = testDev
365 ? await Effect.runPromise(
366 Contributions.load().pipe(
367 Effect.flatMap((providers) =>
368 Effect.forEach(providers, (provider) =>
369 provider.testServices
370 ? Contributions.resolve(provider, "testServices", provider.testServices)
371 : Effect.succeed(undefined),
372 ),
373 ),
374 Effect.map((services) => services.filter((service) => service !== undefined)),
375 Effect.provide(PlatformServices),
376 ),
377 )
378 : [];
379
380 if (testDev) {
381 // Emulators rewrite WebSocket invoke URLs onto their self-signed gateway;
382 // Bun/Node would otherwise reject the upgrade. Scoped to ALCHEMY_TEST_DEV
383 // only.
384 process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
385 // Set here — before the RPC spawner or any vite child forks — so the whole
386 // dev process tree inherits it.
387 for (const services of testServices) {
388 for (const [key, value] of Object.entries(services.env ?? {})) process.env[key] ??= value;
389 }
390 }
391
392 /** The test services' layers, closest wins over the stack's own. */
393 const testServicesLayer =
394 testServices.length === 0
395 ? undefined
396 : testServices
397 .map((services) => services.layer)
398 .reduce((merged, layer) => Layer.merge(merged, layer));
399
400 const provideTestServices = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
401 // Test services override services already present in R.
402 testServicesLayer === undefined
403 ? effect
404 : // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- the layer overrides services already present in R
405 (Effect.provide(effect, testServicesLayer) as Effect.Effect<A, E, R>);
406
407 const testHttp = Layer.effect(
408 HttpClient.HttpClient,
409 Effect.map(HttpClient.HttpClient, (client) =>
410 testServices.reduce(
411 (mapped, services) =>
412 services.mapRequest ? HttpClient.mapRequest(mapped, services.mapRequest) : mapped,
413 client,
414 ),
415 ),
416 ).pipe(Layer.provide(FetchHttpClient.layer));
417
418 const platformLayer = () =>
419 Layer.mergeAll(
420 PlatformServices,
421 testDev ? testHttp : FetchHttpClient.layer,
422 Layer.provide(ProfileStoreLive, PlatformServices),
423 Layer.provide(CredentialsStoreLive, PlatformServices),
424 );
425
426 const alchemyLayer = Layer.mergeAll(
427 LoggingCli,
428 Interaction.layerNonInteractive(),
429 AlchemyContextLive,
430 );
431
432 /** Most lines one capture keeps; older ones are dropped first. */
433 const RESOURCE_LOG_LIMIT = 5_000;
434
435 /** The open {@link captureResourceLog} buffers, by resource fqn. */
436 const resourceCaptures = new Map<string, Set<Array<string>>>();
437
438 /**
439 * Copies each record tagged with a captured resource (`fqn`) into its open
440 * captures. Installed beside the runner's loggers, so it also sees the shared
441 * sidecar's records, which the spawner logs in whichever file started the
442 * sidecar rather than in the test that deployed the resource.
443 */
444 const resourceRecorder = Logger.make<unknown, void>((options) => {
445 if (resourceCaptures.size === 0) return;
446 const record = recordOf(options);
447 const fqn = record.attributes.fqn;
448 const captures = typeof fqn === "string" ? resourceCaptures.get(fqn) : undefined;
449 if (captures === undefined || (record.kind !== "log" && record.kind !== "output")) return;
450 const line = stripVTControlCharacters(
451 record.kind === "log" ? record.data.message : record.data.text,
452 );
453 for (const lines of captures) {
454 lines.push(line);
455 if (lines.length > RESOURCE_LOG_LIMIT) lines.splice(0, lines.length - RESOURCE_LOG_LIMIT);
456 }
457 });
458
459 /**
460 * Start capturing what the resource `fqn` logs — its processes' output (a dev
461 * Worker's console, a Vite dev server) and alchemy's lines about it — whether
462 * its provider runs in the dev sidecar or in-process. Start it before the
463 * deploy; the returned effect reads every line since, without ANSI styling.
464 * The capture ends with the enclosing scope.
465 */
466 export const captureResourceLog = (
467 fqn: string,
468 ): Effect.Effect<Effect.Effect<string>, never, Scope.Scope> =>
469 Effect.acquireRelease(
470 Effect.sync(() => {
471 const lines: Array<string> = [];
472 let captures = resourceCaptures.get(fqn);
473 if (captures === undefined) resourceCaptures.set(fqn, (captures = new Set()));
474 captures.add(lines);
475 return lines;
476 }),
477 (lines) =>
478 Effect.sync(() => {
479 const captures = resourceCaptures.get(fqn);
480 captures?.delete(lines);
481 if (captures?.size === 0) resourceCaptures.delete(fqn);
482 }),
483 ).pipe(Effect.map((lines) => Effect.sync(() => lines.join("\n"))));
484
485 /**
486 * The runner's loggers, minus typed event records: deploys draw their
487 * progress through `AlchemyDeploy.applyAndRender` (the `LoggingCli` lines), so printing each
488 * event object too would only repeat it. `onEvent` subscribers installed
489 * inside still see every event. Adds the {@link resourceRecorder}.
490 */
491 const withoutEventRecords = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
492 Effect.flatMap(Logger.CurrentLoggers, (loggers) =>
493 effect.pipe(
494 Effect.provideService(
495 Logger.CurrentLoggers,
496 new Set([
497 ...[...loggers]
498 .filter((logger) => logger !== resourceRecorder)
499 .map((logger) =>
500 Logger.make<unknown, void>((options) => {
501 if (kindOf(options) !== "event") logger.log(options);
502 }),
503 ),
504 resourceRecorder,
505 ]),
506 ),
507 ),
508 );
509
510 /**
511 * Build the per-test runtime and return a self-contained Effect.
512 *
513 * Mirrors {@link "../bin/alchemy.js"} composition: ConfigProvider via
514 * `loadConfigProvider` + `withProfileOverride`, an empty `AuthProviders`
515 * registry that the user's `providers` layer populates, the platform layers,
516 * and the configured state store. Adapters wrap this into runner-specific
517 * thunks (`bun.test` -> `runPromise`, `it.live` -> as-is).
518 *
519 * When `scope` is provided, scoped resources (like the Cloudflare dev
520 * sidecar) survive past this effect and are tied to the lifetime of the
521 * provided scope instead. The runner is responsible for closing it.
522 *
523 * When `scope` is omitted, the effect runs with `Effect.scoped` and any
524 * scoped resources are torn down as soon as it resolves.
525 */
526 export const toEffect = <A, ROut = any>(
527 effect: TestEffect<A>,
528 options: MakeOptions<ROut>,
529 scope?: Scope.Scope,
530 sidecar?: SidecarHandle,
531 ): Effect.Effect<A, any, never> => {
532 const base = Effect.gen(function* () {
533 const cfg = yield* loadConfigProvider(Option.none());
534 const configProvider = withProfileOverride(cfg, options.profile);
535 // `ALCHEMY_TEST_DEV=1` forces local providers AND points the test
536 // process's distilled AWS clients at the emulator. Otherwise
537 // out-of-band `describeTable` / `getFunction` calls still hit the
538 // live account and fail with ResourceNotFound. Existing
539 // `Test.make({ dev: true })` files are unchanged (mixed
540 // `Alchemy.remote()` suites keep their live SDK).
541 const body = sidecar ? sidecar.provide(effect) : effect;
542 const locally = testDev ? provideTestServices(body) : body;
543 return yield* locally.pipe(
544 withoutEventRecords,
545 provideFreshArtifactStore,
546 Effect.provideService(ConfigProvider, configProvider),
547 Effect.provideService(StackConfigOverrides, { profile: options.profile }),
548 );
549 }).pipe(
550 Effect.provideService(AdoptPolicy, options.adopt ?? false),
551 Effect.provide(overrideAlchemyContext({ dev: resolveDev(options) })),
552 // `options.state` (e.g. `Cloudflare.state()`) itself requires
553 // `AuthProviders` to read credentials, so AuthProviders must be provided
554 // AFTER the state layer or the state layer's requirement is never
555 // satisfied — which surfaces as `Service not found: AuthProviders`.
556 Effect.provide(options.state ?? State.localState()),
557 Effect.provideService(AuthProviders, {}),
558 Effect.provide(Layer.provideMerge(alchemyLayer, platformLayer())),
559 );
560
561 return (scope === undefined ? Effect.scoped(base) : Scope.provide(base, scope)) as Effect.Effect<
562 A,
563 any,
564 never
565 >;
566 };
567
568 /** Promise wrapper around {@link toEffect} for `bun.test`-style runners. */
569 export const run = <A, ROut = any>(
570 effect: TestEffect<A>,
571 options: MakeOptions<ROut>,
572 scope?: Scope.Scope,
573 sidecar?: SidecarHandle,
574 ): Promise<A> => Effect.runPromise(toEffect(effect, options, scope, sidecar));
575
576 /**
577 * Wrap an effect so it runs with `options.providers` + a placeholder Stack +
578 * Stage in scope. Used by `test.provider` so user code can call provider SDK
579 * APIs (e.g. `DynamoDB.describeTable`) directly inside the test body.
580 */
581 export const withProviders = <A, E, R, ROut>(
582 effect: Effect.Effect<A, E, R>,
583 options: MakeOptions<ROut>,
584 stackName: string,
585 ): Effect.Effect<A, E, Exclude<R, ROut | Stack | Stage>> => {
586 // Closest wins: when `ALCHEMY_TEST_DEV=1`, pin the test body's
587 // distilled AWS clients to the emulator BEFORE `options.providers`
588 // (which still carries the live `AWSEnvironment`).
589 const body = testDev ? provideTestServices(effect) : effect;
590 const stage = resolveStage(options);
591 // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- providers layer is typed `any`; requirements are satisfied by it
592 return body.pipe(
593 Effect.provide(
594 (options.providers as Layer.Layer<any, never, any>).pipe(
595 Layer.provideMerge(
596 Layer.succeed(Stack, {
597 name: stackName,
598 stage,
599 resources: {},
600 bindings: {},
601 actions: {},
602 }),
603 ),
604 Layer.provideMerge(Layer.succeed(Stage, stage)),
605 ),
606 ),
607 ) as Effect.Effect<A, E, Exclude<R, ROut | Stack | Stage>>;
608 };
609
610 /**
611 * Curried `deploy` for the test factory: bakes in the configured stage and
612 * adds the telemetry layer the CLI uses, so `beforeAll(deploy(Stack))` works
613 * the same way as `alchemy deploy`.
614 *
615 * `scope`, when supplied, is forwarded down so the dev sidecar (and other
616 * scoped resources) lives until the caller closes it instead of dying as
617 * soon as `deploy` resolves. The test harness uses this to keep workerd
618 * alive across `beforeAll` → tests → `afterAll`.
619 */
620 export interface DeployCallOptions extends Plan.MakePlanOptions {
621 stage?: string;
622 scope?: Scope.Scope;
623 }
624
625 export type DeployResult<A> = Effect.Effect<
626 Input.Resolve<A>,
627 Effect.Error<ReturnType<typeof deployStack<A>>>,
628 Effect.Services<ReturnType<typeof deployStack<A>>>
629 >;
630
631 export interface FilteredDeployCallOptions
632 extends Omit<DeployCallOptions, keyof ResourceSelection>, ResourceSelection {}
633
634 type FullDeployCall = [options?: DeployCallOptions];
635
636 /**
637 * Filtered deploys return void; the whole declaration still evaluates.
638 * With an explicit output type, filtering also requires the Call tuple type.
639 */
640 export interface Deploy {
641 <A, Call extends [options?: FilteredDeployCallOptions] = FullDeployCall>(
642 stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
643 ...call: Call
644 ): DeployResult<SelectionOutput<A, Call[0]>>;
645 }
646
647 export function deploy<A, Call extends [options?: FilteredDeployCallOptions] = FullDeployCall>(
648 options: MakeOptions,
649 stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
650 ...call: Call
651 ): DeployResult<SelectionOutput<A, Call[0]>>;
652 export function deploy<A>(
653 options: MakeOptions,
654 stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
655 callOptions?: FilteredDeployCallOptions,
656 ) {
657 return deployStack(options, stack, callOptions);
658 }
659
660 const deployStack = <A>(
661 options: MakeOptions,
662 stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
663 callOptions?: FilteredDeployCallOptions,
664 ) =>
665 AlchemyDeploy.deploy({
666 stack: stack as Effect.Effect<CompiledStack<A>, never, any>,
667 stage: callOptions?.stage ?? resolveStage(options),
668 dev: resolveDev(options),
669 scope: callOptions?.scope,
670 force: callOptions?.force,
671 include: callOptions?.include,
672 exclude: callOptions?.exclude,
673 }).pipe(Effect.provide(TelemetryLive));
674
675 /** Bind test-file options and the shared runtime scope without erasing output types. */
676 export const makeDeploy = (options: MakeOptions, scope: Scope.Scope): Deploy => {
677 function run<A, Call extends [options?: FilteredDeployCallOptions] = FullDeployCall>(
678 stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
679 ...call: Call
680 ): DeployResult<SelectionOutput<A, Call[0]>>;
681 function run<A>(
682 stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
683 callOptions?: FilteredDeployCallOptions,
684 ) {
685 return deployStack(options, stack, { ...callOptions, scope });
686 }
687 return run;
688 };
689
690 export const destroy = <ROut>(
691 options: MakeOptions,
692 stack: StackDefinition<ROut>,
693 callOptions?: { stage?: string; scope?: Scope.Scope; include?: never; exclude?: never },
694 ) =>
695 AlchemyDestroy.destroy({
696 include: callOptions?.include,
697 exclude: callOptions?.exclude,
698 stack,
699 stage: callOptions?.stage ?? resolveStage(options),
700 dev: resolveDev(options),
701 scope: callOptions?.scope,
702 }).pipe(Effect.provide(TelemetryLive));
703
704 /**
705 * In-test scratch stack handed to `test.provider(name, (stack) => ...)`.
706 *
707 * Each scratch stack owns a private state store that is shared between
708 * successive `deploy`/`destroy` calls AND visible to the user's test body
709 * (so `yield* State` / `state.get(...)` see the same store the deploys
710 * mutated). This makes create / update / replace / delete paths exercisable
711 * without polluting other tests in the same file.
712 *
713 * When the adapter can name the test file (the alchemy-test runner), the
714 * store is DURABLE — rows live under `.alchemy/state/{file}-{test}/{stage}`
715 * on disk. Durability is what makes an interrupted destroy recoverable: the
716 * engine persists a `deleting` row before every `provider.delete` and only
717 * drops it on success, so a run killed mid-delete (e.g. the runner's
718 * teardown-abandonment after a test timeout) leaves resumable rows that the
719 * NEXT run's leading `stack.destroy()` (or the `Effect.ensuring` teardown)
720 * picks up and drains. An in-memory scratch dies with the process, silently
721 * orphaning every cloud resource whose delete was still in flight.
722 */
723 export interface ScratchStack<ROut = any> {
724 readonly name: string;
725 /** Stage this scratch deploys to ({@link resolveStage} of the file options). */
726 readonly stage: string;
727 /** The shared in-memory state Layer for this scratch. @internal */
728 readonly state: Layer.Layer<State.State, never, never>;
729 /** Filters leave other rows and stack outputs untouched; declaration still runs. */
730 deploy<A, E, R, Call extends [options?: Plan.FilteredPlanOptions] = []>(
731 effect: Effect.Effect<A, E, R>,
732 ...call: Call
733 ): Effect.Effect<
734 SelectionOutput<Input.Resolve<A>, Call[0]>,
735 any,
736 Exclude<R, ROut | StackServices>
737 >;
738 /**
739 * Build a plan against the scratch's shared state WITHOUT applying it.
740 *
741 * Use this to assert on the planned action for a resource (e.g. that a
742 * downstream dependency stays `noop` when only an upstream resource
743 * changes) without mutating the cloud. Plans run against whatever state
744 * prior `deploy(...)` calls persisted.
745 */
746 plan<A, E, R, Call extends [options?: Plan.FilteredPlanOptions] = []>(
747 effect: Effect.Effect<A, E, R>,
748 ...call: Call
749 ): Effect.Effect<Plan.Plan<SelectionOutput<A, Call[0]>>, any, Exclude<R, ROut | StackServices>>;
750 destroy(options?: { include?: never; exclude?: never }): Effect.Effect<void, any, never>;
751 }
752
753 const sanitizeStackName = (name: string) =>
754 name.replaceAll(/[^a-zA-Z0-9_]/g, "-").replace(/-+/g, "-");
755
756 /**
757 * Turn a test-file path (relative to the run root) into a stack-name
758 * namespace: `test/AWS/Website/Router.test.ts` -> `AWS/Website/Router`.
759 * Test names repeat across files (e.g. "create and delete bucket with
760 * default props"), so the durable per-test store MUST be namespaced by file
761 * or two concurrently-running same-named tests would read, write and — far
762 * worse — destroy each other's rows.
763 */
764 const scratchNamespace = (file: string) =>
765 file.replace(/^test[/\\]/, "").replace(/\.test\.ts$/, "");
766
767 /**
768 * Build a fresh `ScratchStack` for `test.provider`.
769 *
770 * With `file` (the registration-time test file, supplied by the
771 * alchemy-test adapter): the store is the durable `.alchemy/state` local
772 * store and the stack name is namespaced by file so interrupted destroys
773 * leave resumable rows for the next run (see {@link ScratchStack}).
774 *
775 * Without `file` (bun/vitest adapters, which cannot name their file at
776 * registration time): falls back to a private in-memory store — isolated,
777 * but discarded with the process.
778 */
779 export const scratchStack = <ROut>(
780 options: MakeOptions<ROut>,
781 name: string,
782 file?: string,
783 ): ScratchStack<ROut> => {
784 const stage = resolveStage(options);
785 const stackName = sanitizeStackName(
786 file === undefined ? name : `${scratchNamespace(file)}-${name}`,
787 );
788 const stateLayer: Layer.Layer<State.State> =
789 file === undefined
790 ? Layer.succeed(State.State, State.InMemoryService({}))
791 : Layer.provide(State.localState(), PlatformServices);
792
793 // `withProviders` already pins the test body to the test services, but the
794 // stack program and its later plan/apply phase run under the providers'
795 // live services. Pin both phases separately: Actions execute during apply,
796 // after the stack program has finished. This override must be inside
797 // `compiled.services` so Effect's closest-layer precedence selects the test
798 // services for Action data-plane calls.
799 const pinToTestServices = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
800 testDev ? provideTestServices(effect) : effect;
801
802 // TODO(unify stack builds): build scratch stacks through `Alchemist.plan` /
803 // `Alchemist.apply` instead of `makeStack` and the hand-built destroy layers
804 // below (which skip the stack's secrets and auth providers); see the TODO in
805 // `alchemy/src/EvalStack.ts`.
806 const buildAndApply = (
807 effect: Effect.Effect<any, any, any>,
808 planOptions?: Plan.FilteredPlanOptions,
809 ) =>
810 (pinToTestServices(effect) as Effect.Effect<any, any, never>).pipe(
811 makeStack({ name: stackName, providers: options.providers, state: stateLayer } as any) as any,
812 Effect.flatMap((compiled: any) =>
813 Plan.make(compiled, planOptions ?? {}).pipe(
814 Effect.flatMap(AlchemyDeploy.applyAndRender),
815 pinToTestServices,
816 Effect.provide(compiled.services),
817 ),
818 ),
819 Effect.provideService(Stage, stage),
820 provideFreshArtifactStore,
821 );
822
823 const buildPlan = (
824 effect: Effect.Effect<any, any, any>,
825 planOptions?: Plan.FilteredPlanOptions,
826 ) =>
827 (pinToTestServices(effect) as Effect.Effect<any, any, never>).pipe(
828 makeStack({ name: stackName, providers: options.providers, state: stateLayer } as any) as any,
829 Effect.flatMap((compiled: any) =>
830 pinToTestServices(Plan.make(compiled, planOptions ?? {})).pipe(
831 Effect.provide(compiled.services),
832 ),
833 ),
834 Effect.provideService(Stage, stage),
835 provideFreshArtifactStore,
836 );
837
838 return {
839 name: stackName,
840 stage,
841 state: stateLayer,
842 deploy: ((effect: Effect.Effect<any, any, any>, planOptions?: Plan.FilteredPlanOptions) =>
843 buildAndApply(effect, planOptions)) as ScratchStack<ROut>["deploy"],
844 plan: ((effect: Effect.Effect<any, any, any>, planOptions?: Plan.FilteredPlanOptions) =>
845 buildPlan(effect, planOptions)) as ScratchStack<ROut>["plan"],
846 destroy: (callOptions) =>
847 callOptions?.include !== undefined || callOptions?.exclude !== undefined
848 ? Effect.die(
849 new Plan.InvalidResourceSelection({ message: "Filtered destroy is not supported." }),
850 )
851 : (Plan.destroy({ name: stackName, stage }).pipe(
852 Effect.flatMap(AlchemyDeploy.applyAndRender),
853 Effect.asVoid,
854 Effect.provide(
855 stateLayer.pipe(
856 Layer.provideMerge(options.providers as Layer.Layer<any, never, any>),
857 Layer.provideMerge(
858 Layer.succeed(Stack, {
859 name: stackName,
860 stage,
861 resources: {},
862 bindings: {},
863 actions: {},
864 }),
865 ),
866 Layer.provideMerge(Layer.succeed(Stage, stage)),
867 ),
868 ),
869 provideFreshArtifactStore,
870 ) as Effect.Effect<void, any, never>),
871 };
872 };