alchemy 2.0.0-beta.35 → 2.0.0-beta.37

package/src/State/LocalState.ts

@@ -46,6 +46,9 @@ export const makeLocalState = () =>
       fqn: string;
     }) => path.join(stateDir, stack, stage, `${encodeFqn(fqn)}.json`);
 
+    const outputFile = ({ stack, stage }: { stack: string; stage: string }) =>
+      path.join(stateDir, stack, stage, `__stack_output__.json`);
+
     const created = new Set<string>();
 
     const ensure = (dir: string) =>
@@ -107,11 +110,32 @@ export const makeLocalState = () =>
       list: (request) =>
         fs.readDirectory(stageDir(request)).pipe(
           recover,
-          Effect.map(
-            (files) =>
-              files?.map((file) => decodeFqn(file.replace(/\.json$/, ""))) ??
-              [],
+          Effect.map((files) =>
+            (files ?? [])
+              // Filter the bookkeeping file before decoding — `decodeFqn`
+              // replaces `__` with `/`, which would turn the literal name
+              // `__stack_output__` into `/stack_output/` and slip past the
+              // filter, leaving the engine to look up a non-existent
+              // resource.
+              .filter((file) => file !== "__stack_output__.json")
+              .map((file) => decodeFqn(file.replace(/\.json$/, ""))),
+          ),
+        ),
+      getOutput: (request) =>
+        fs.readFile(outputFile(request)).pipe(
+          Effect.map((file) => JSON.parse(file.toString(), reviveState)),
+          recover,
+        ),
+      setOutput: (request) =>
+        ensure(stageDir(request)).pipe(
+          Effect.flatMap(() =>
+            fs.writeFileString(
+              outputFile(request),
+              JSON.stringify(encodeState(request.value as any), null, 2),
+            ),
           ),
+          recover,
+          Effect.map(() => request.value),
         ),
     };
     return state;

package/src/State/State.ts

@@ -87,4 +87,25 @@ export interface StateService {
     stack: string;
     stage: string;
   }): Effect.Effect<readonly string[], StateStoreError, never>;
+  /**
+   * Read the persisted stack output for `(stack, stage)`. Returns
+   * `undefined` when the stack has not been deployed (or has been
+   * destroyed) at this stage.
+   *
+   * Stack outputs are written by `apply` once the deploy succeeds and
+   * read by cross-stack references (`yield* OtherStack` /
+   * `OtherStack.stage.<name>` / `Output.stackRef(...)`).
+   */
+  getOutput(request: {
+    stack: string;
+    stage: string;
+  }): Effect.Effect<unknown, StateStoreError, never>;
+  /**
+   * Persist the resolved stack output for `(stack, stage)`.
+   */
+  setOutput(request: {
+    stack: string;
+    stage: string;
+    value: unknown;
+  }): Effect.Effect<unknown, StateStoreError, never>;
 }

package/src/Test/Bun.ts

@@ -1,12 +1,17 @@
 import bun from "bun:test";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
 import type { HookOptions } from "node:test";
 
 import type { AlchemyContext } from "../AlchemyContext.ts";
 import type { CompiledStack } from "../Stack.ts";
 import type { Stage } from "../Stage.ts";
+import { installLocalhostDns } from "../Util/LocalhostDns.ts";
 import * as Core from "./Core.ts";
 
+installLocalhostDns();
+
 export type MakeOptions<ROut = any> = Core.MakeOptions<ROut>;
 export type ScratchStack = Core.ScratchStack;
 export type TestEffect<A, R = never> = Core.TestEffect<A, R>;
@@ -106,7 +111,15 @@ const DEFAULT_HOOK_TIMEOUT: HookOptions = { timeout: 120_000 };
  * ```
  */
 export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
-  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options);
+  // Single scope shared across `beforeAll`, every `test`, and `afterAll`.
+  // Scoped resources in dev mode (the Cloudflare sidecar process and its
+  // workerd children) must outlive a single `Effect.runPromise` boundary,
+  // otherwise the proxy is killed the moment `beforeAll(deploy(Stack))`
+  // resolves and every later `HttpClient.get(workerUrl)` hits a dead port.
+  // The scope is closed by `destroy(...)` (or never — the next test run
+  // reclaims any leaked sidecar via the lock file).
+  const sharedScope = Scope.makeUnsafe("sequential");
+  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options, sharedScope);
 
   const test = ((name, eff, opts) => {
     bun.test(name, () => runEff(eff), opts);
@@ -130,10 +143,11 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
   ) => {
     const scratch = Core.scratchStack(options, name);
-    return Core.run(Core.withProviders(fn(scratch), options, scratch.name), {
-      ...options,
-      state: scratch.state,
-    });
+    return Core.run(
+      Core.withProviders(fn(scratch), options, scratch.name),
+      { ...options, state: scratch.state },
+      sharedScope,
+    );
   };
 
   const provider = ((name, fn, opts) => {
@@ -175,13 +189,35 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     bun.afterEach(() => runEff(eff), hookOptions);
   };
 
+  // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`
+  // for each worker. We close the shared scope only AFTER destroy completes.
+  // `Scope.close` on an already-closed scope is a no-op, so it's safe for both
+  // the destroy wrapper AND the fallback cleanup hook below to call it.
+  const closeScope = Effect.suspend(() =>
+    Scope.close(sharedScope, Exit.void),
+  ).pipe(Effect.ignore);
+
+  // Fallback cleanup: if the user never calls `destroy(Stack)` (e.g.
+  // `NO_DESTROY=1`), nothing else closes the shared scope and the sidecar
+  // child process leaks past the test process. Register an `afterAll` that
+  // closes it. We defer registration to a microtask so it runs AFTER any
+  // user-registered `afterAll` (including `destroy(Stack)`); bun runs
+  // afterAll hooks in registration order.
+  queueMicrotask(() => {
+    bun.afterAll(() => Effect.runPromise(closeScope), DEFAULT_HOOK_TIMEOUT);
+  });
+
   return {
     test,
     beforeAll,
     beforeEach,
     afterAll,
     afterEach,
-    deploy: (stack, callOpts) => Core.deploy(options, stack, callOpts),
-    destroy: (stack, callOpts) => Core.destroy(options, stack, callOpts),
+    deploy: (stack, callOpts) =>
+      Core.deploy(options, stack, { ...callOpts, scope: sharedScope }),
+    destroy: (stack, callOpts) =>
+      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
+        Effect.ensuring(closeScope),
+      ),
   };
 };

package/src/Test/Core.ts

@@ -2,6 +2,7 @@ import { ConfigProvider } from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Scope from "effect/Scope";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 
 import { AdoptPolicy } from "../AdoptPolicy.ts";
@@ -90,14 +91,22 @@ const alchemyLayer = Layer.mergeAll(LoggingCli, AlchemyContextLive);
  * registry that the user's `providers` layer populates, the platform layers,
  * and the configured state store. Adapters wrap this into runner-specific
  * thunks (`bun.test` -> `runPromise`, `it.live` -> as-is).
+ *
+ * When `scope` is provided, scoped resources (like the Cloudflare dev
+ * sidecar) survive past this effect and are tied to the lifetime of the
+ * provided scope instead. The runner is responsible for closing it.
+ *
+ * When `scope` is omitted, the effect runs with `Effect.scoped` and any
+ * scoped resources are torn down as soon as it resolves.
  */
 export const toEffect = <A>(
   effect: TestEffect<A>,
   options: MakeOptions,
-): Effect.Effect<A, any, never> =>
-  Effect.gen(function* () {
-    const base = yield* loadConfigProvider(Option.none());
-    const configProvider = withProfileOverride(base, options.profile);
+  scope?: Scope.Scope,
+): Effect.Effect<A, any, never> => {
+  const base = Effect.gen(function* () {
+    const cfg = yield* loadConfigProvider(Option.none());
+    const configProvider = withProfileOverride(cfg, options.profile);
     return yield* effect.pipe(
       provideFreshArtifactStore,
       Effect.provide(Layer.succeed(ConfigProvider, configProvider)),
@@ -112,14 +121,19 @@ export const toEffect = <A>(
     Effect.provide(options.state ?? State.localState()),
     Effect.provideService(AuthProviders, {}),
     Effect.provide(Layer.provideMerge(alchemyLayer, platformLayer)),
-    Effect.scoped,
+  );
+
+  return (
+    scope === undefined ? Effect.scoped(base) : Scope.provide(base, scope)
   ) as Effect.Effect<A, any, never>;
+};
 
 /** Promise wrapper around {@link toEffect} for `bun.test`-style runners. */
 export const run = <A>(
   effect: TestEffect<A>,
   options: MakeOptions,
-): Promise<A> => Effect.runPromise(toEffect(effect, options));
+  scope?: Scope.Scope,
+): Promise<A> => Effect.runPromise(toEffect(effect, options, scope));
 
 /**
  * Wrap an effect so it runs with `options.providers` + a placeholder Stack +
@@ -148,27 +162,34 @@ export const withProviders = <A, E, R, ROut>(
  * Curried `deploy` for the test factory: bakes in the configured stage and
  * adds the telemetry layer the CLI uses, so `beforeAll(deploy(Stack))` works
  * the same way as `alchemy deploy`.
+ *
+ * `scope`, when supplied, is forwarded down so the dev sidecar (and other
+ * scoped resources) lives until the caller closes it instead of dying as
+ * soon as `deploy` resolves. The test harness uses this to keep workerd
+ * alive across `beforeAll` → tests → `afterAll`.
  */
 export const deploy = <A>(
   options: MakeOptions,
   stack: TestEffect<CompiledStack<A>, Stage | AlchemyContext>,
-  callOptions?: { stage?: string },
+  callOptions?: { stage?: string; scope?: Scope.Scope },
 ) =>
   _deploy({
     stack: stack as Effect.Effect<CompiledStack<A>, never, any>,
     stage: callOptions?.stage ?? options.stage ?? "test",
     dev: resolveDev(options),
+    scope: callOptions?.scope,
   }).pipe(Effect.provide(TelemetryLive));
 
 export const destroy = (
   options: MakeOptions,
   stack: TestEffect<CompiledStack, Stage | AlchemyContext>,
-  callOptions?: { stage?: string },
+  callOptions?: { stage?: string; scope?: Scope.Scope },
 ) =>
   _destroy({
     stack: stack as Effect.Effect<CompiledStack, never, any>,
     stage: callOptions?.stage ?? options.stage ?? "test",
     dev: resolveDev(options),
+    scope: callOptions?.scope,
   }).pipe(Effect.provide(TelemetryLive));
 
 /**

package/src/Test/Vitest.ts

@@ -1,5 +1,7 @@
 import { it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
 import {
   afterAll as vitestAfterAll,
   afterEach as vitestAfterEach,
@@ -10,8 +12,11 @@ import {
 import type { AlchemyContext } from "../AlchemyContext.ts";
 import type { CompiledStack } from "../Stack.ts";
 import type { Stage } from "../Stage.ts";
+import { installLocalhostDns } from "../Util/LocalhostDns.ts";
 import * as Core from "./Core.ts";
 
+installLocalhostDns();
+
 export type MakeOptions<ROut = any> = Core.MakeOptions<ROut>;
 export type ScratchStack = Core.ScratchStack;
 export type TestEffect<A, R = never> = Core.TestEffect<A, R>;
@@ -95,8 +100,13 @@ const DEFAULT_TIMEOUT = 120_000;
  * Effect-aware tests stay first-class.
  */
 export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
-  const wrap = <A>(eff: TestEffect<A>) => Core.toEffect(eff, options);
-  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options);
+  // See `Test/Bun.ts` for the rationale: the dev sidecar must outlive a
+  // single `runPromise` boundary, so all hooks share one scope that's only
+  // closed after `destroy(...)` runs.
+  const sharedScope = Scope.makeUnsafe("sequential");
+  const wrap = <A>(eff: TestEffect<A>) =>
+    Core.toEffect(eff, options, sharedScope);
+  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options, sharedScope);
 
   const test = ((name, eff, opts) => {
     it.live(name, () => wrap(eff), timeoutOf(opts));
@@ -127,6 +137,7 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     return Core.toEffect(
       Core.withProviders(fn(scratch), options, scratch.name),
       { ...options, state: scratch.state },
+      sharedScope,
     );
   };
 
@@ -179,13 +190,34 @@ export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
     vitestAfterEach(() => runEff(eff), timeoutOf(hookOptions));
   };
 
+  // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`.
+  // `Scope.close` on an already-closed scope is a no-op, so the destroy
+  // wrapper AND the fallback cleanup hook below can both call it safely.
+  const closeScope = Effect.suspend(() =>
+    Scope.close(sharedScope, Exit.void),
+  ).pipe(Effect.ignore);
+
+  // Fallback cleanup: if the user never calls `destroy(Stack)` (e.g.
+  // `NO_DESTROY=1`), nothing else closes the shared scope and the sidecar
+  // child process leaks past the test process. Register an `afterAll` that
+  // closes it. We defer registration to a microtask so it runs AFTER any
+  // user-registered `afterAll` (including `destroy(Stack)`); vitest runs
+  // afterAll hooks in registration order.
+  queueMicrotask(() => {
+    vitestAfterAll(() => Effect.runPromise(closeScope), DEFAULT_TIMEOUT);
+  });
+
   return {
     test,
     beforeAll,
     beforeEach,
     afterAll,
     afterEach,
-    deploy: (stack, callOpts) => Core.deploy(options, stack, callOpts),
-    destroy: (stack, callOpts) => Core.destroy(options, stack, callOpts),
+    deploy: (stack, callOpts) =>
+      Core.deploy(options, stack, { ...callOpts, scope: sharedScope }),
+    destroy: (stack, callOpts) =>
+      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
+        Effect.ensuring(closeScope),
+      ),
   };
 };

package/src/Util/LocalhostDns.ts

@@ -0,0 +1,52 @@
+/**
+ * Process-level DNS shim that makes `*.localhost` resolve to 127.0.0.1
+ * for any HTTP client that goes through undici (Node's global `fetch`,
+ * undici-based clients, etc.).
+ *
+ * Background: macOS's `getaddrinfo` does not honor RFC 6761 for arbitrary
+ * `*.localhost` names — only the bare `localhost` is mapped to loopback.
+ * The Cloudflare local proxy returns URLs like
+ * `http://my-worker.localhost:1337` and dispatches by the URL hostname,
+ * so we cannot rewrite the URL client-side to `127.0.0.1` (and `Host` is
+ * a forbidden fetch header). The fix is to make the host resolvable at
+ * the network layer.
+ *
+ * On Bun, `globalThis.fetch` is the native (Zig) implementation and does
+ * not consult undici's global dispatcher; Bun resolves `*.localhost`
+ * itself on Darwin/Linux, so this shim is effectively a no-op there for
+ * the global `fetch` and only matters if user code reaches for `undici`
+ * directly.
+ *
+ * Calling `installLocalhostDns()` is idempotent.
+ */
+
+import * as dns from "node:dns";
+import * as undici from "undici";
+
+let installed = false;
+
+const isLocalhost = (hostname: string): boolean =>
+  hostname === "localhost" ||
+  hostname === "[::1]" ||
+  hostname.endsWith(".localhost");
+
+export const installLocalhostDns = (): void => {
+  if (installed) return;
+  installed = true;
+
+  undici.setGlobalDispatcher(
+    new undici.Agent({
+      connect: {
+        lookup: (hostname, options, cb) => {
+          if (isLocalhost(hostname)) {
+            if (options && (options as { all?: boolean }).all) {
+              return cb(null, [{ address: "127.0.0.1", family: 4 }]);
+            }
+            return cb(null, "127.0.0.1", 4);
+          }
+          return dns.lookup(hostname, options, cb);
+        },
+      },
+    }),
+  );
+};

package/src/Util/PlatformServices.ts

@@ -9,6 +9,7 @@ import type { HttpServer } from "effect/unstable/http/HttpServer";
 import type { ServeError } from "effect/unstable/http/HttpServerError";
 import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
 import type { WebSocketConstructor } from "effect/unstable/socket/Socket";
+import { installLocalhostDns } from "./LocalhostDns.ts";
 
 const isBun = typeof Bun !== "undefined";
 
@@ -52,6 +53,7 @@ export const runMain = <E, A>(
     readonly teardown?: Teardown | undefined;
   },
 ): void => {
+  installLocalhostDns();
   if (isBun) {
     void import("@effect/platform-bun/BunRuntime").then((BunRuntime) =>
       BunRuntime.runMain(effect, options),

package/src/Util/effect.ts

@@ -64,6 +64,31 @@ export const taggedFunction = <
   }) as Tag & Fn;
 };
 
+export const isYieldableEffect = (
+  value: unknown,
+): value is Effect.Effect<unknown, unknown, unknown> =>
+  Effect.isEffect(value) &&
+  typeof (value as { [Symbol.iterator]?: unknown })[Symbol.iterator] ===
+    "function";
+
+export type YieldableEffectLike<A = unknown, E = unknown, R = unknown> =
+  | Effect.Effect<A, E, R>
+  | {
+      asEffect: () => Effect.Effect<A, E, R>;
+      [Symbol.iterator]: () => Iterator<unknown>;
+    };
+
+export const isEffectClassLike = (
+  value: unknown,
+): value is YieldableEffectLike =>
+  typeof value === "function" &&
+  typeof (value as { asEffect?: unknown }).asEffect === "function";
+
+export const isYieldableEffectLike = (
+  value: unknown,
+): value is YieldableEffectLike =>
+  isYieldableEffect(value) || isEffectClassLike(value);
+
 export type UnwrapEffect<T> =
   T extends Effect.Effect<infer A, any, any> ? A : T;
 

package/src/Variable.ts

@@ -0,0 +1,44 @@
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Output from "./Output.ts";
+import { toOutput } from "./Secret.ts";
+
+/**
+ * The shapes a {@link variable} can be derived from.
+ */
+export type VariableInput<T, R = never> =
+  | T
+  | Effect.Effect<T, any, R>
+  | Config.Config<T>;
+
+/**
+ * Bind a non-secret value into the active {@link RuntimeContext} (e.g. a
+ * Cloudflare Worker's `env`) under the given `name`. Counterpart to
+ * {@link Secret} for plain (non-redacted) values — the resource provider
+ * deploys it as `plain_text` / `json` rather than `secret_text`.
+ *
+ * The result is an `Output<T>` — `yield*`-ing it returns an `Accessor<T>`
+ * that resolves the value at runtime.
+ *
+ * @example One-arg shortcut — reads `Config.string("DATABASE_URL")`
+ * ```ts
+ * const url = yield* Alchemy.Variable("DATABASE_URL");
+ * ```
+ *
+ * @example From a literal
+ * ```ts
+ * const port = yield* Alchemy.Variable("PORT", 3000);
+ * ```
+ */
+export function Variable(name: string): Output.Output<string, never>;
+export function Variable<T, R = never>(
+  name: string,
+  value: VariableInput<T, R>,
+): Output.Output<T, R>;
+export function Variable<T = string, R = never>(
+  name: string,
+  value?: VariableInput<T, R>,
+): Output.Output<T, R> {
+  const source: any = value ?? Config.string(name);
+  return Output.named(toOutput<T, R>(source), name);
+}

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./Diff.ts";
 export * from "./Input.ts";
 export * from "./InstanceId.ts";
 export * from "./Namespace.ts";
+export { stackRef } from "./Output.ts";
 export type { Output } from "./Output.ts";
 export * from "./PhysicalName.ts";
 export * as Plan from "./Plan.ts";
@@ -23,12 +24,14 @@ export * from "./Ref.ts";
 export * as RemovalPolicy from "./RemovalPolicy.ts";
 export * from "./Resource.ts";
 export * as Schema from "./Schema.ts";
+export { Secret } from "./Secret.ts";
 export * as Server from "./Server/index.ts";
 export * as Serverless from "./Serverless/index.ts";
 export { Stack } from "./Stack.ts";
 export * from "./Stage.ts";
 export { inMemoryState, localState } from "./State/index.ts";
 export * from "./Trait.ts";
+export { Variable } from "./Variable.ts";
 
 export * as Construct from "./Construct.ts";