The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }; |