alchemy 2.0.0-beta.51 → 2.0.0-beta.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alchemy",
-  "version": "2.0.0-beta.51",
+  "version": "2.0.0-beta.52",
   "homepage": "https://alchemy.run",
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
@@ -21,7 +21,7 @@
   "sideEffects": false,
   "scripts": {
     "dev": "tsdown --watch",
-    "build": "bun bundle",
+    "build": "tsc -b && tsc -b tsconfig.bin.json && bun bundle",
     "bundle": "tsdown",
     "bundle:watch": "tsdown --watch",
     "publish:npm": "cp ../README.md . && bun publish && rm README.md",
@@ -291,16 +291,16 @@
     "@alchemy.run/node-utils": "0.0.4",
     "@aws-sdk/credential-providers": "^3.0.0",
     "@clack/prompts": "^0.11.0",
-    "@distilled.cloud/aws": "^0.22.4",
-    "@distilled.cloud/axiom": "^0.22.4",
-    "@distilled.cloud/cloudflare": "^0.22.4",
-    "@distilled.cloud/cloudflare-rolldown-plugin": "0.10.2",
-    "@distilled.cloud/cloudflare-runtime": "0.10.2",
-    "@distilled.cloud/cloudflare-vite-plugin": "0.10.2",
-    "@distilled.cloud/core": "^0.22.4",
-    "@distilled.cloud/neon": "^0.22.4",
-    "@distilled.cloud/planetscale": "^0.22.4",
-    "@effect/vitest": ">=4.0.0-beta.74 || >=4.0.0",
+    "@distilled.cloud/aws": "^0.23.1",
+    "@distilled.cloud/axiom": "^0.23.1",
+    "@distilled.cloud/cloudflare": "^0.23.1",
+    "@distilled.cloud/cloudflare-rolldown-plugin": "0.10.5",
+    "@distilled.cloud/cloudflare-runtime": "0.10.5",
+    "@distilled.cloud/cloudflare-vite-plugin": "0.10.5",
+    "@distilled.cloud/core": "^0.23.1",
+    "@distilled.cloud/neon": "^0.23.1",
+    "@distilled.cloud/planetscale": "^0.23.1",
+    "@effect/vitest": ">=4.0.0-beta.78 || >=4.0.0",
     "@libsql/client": "^0.17.0",
     "@octokit/rest": "^22.0.1",
     "@smithy/node-config-provider": "^4.0.0",
@@ -328,9 +328,9 @@
     "@clack/prompts": "^0.11.0",
     "@cloudflare/workers-types": "^4.20250805.0",
     "@cloudflare/puppeteer": "^1.1.0",
-    "@effect/platform-bun": ">=4.0.0-beta.74 || >=4.0.0",
-    "@effect/platform-node": ">=4.0.0-beta.74 || >=4.0.0",
-    "@effect/platform-node-shared": ">=4.0.0-beta.74 || >=4.0.0",
+    "@effect/platform-bun": ">=4.0.0-beta.78 || >=4.0.0",
+    "@effect/platform-node": ">=4.0.0-beta.78 || >=4.0.0",
+    "@effect/platform-node-shared": ">=4.0.0-beta.78 || >=4.0.0",
     "@oxc-project/types": "^0.127.0",
     "@types/pg": "^8.11.0",
     "@types/aws-lambda": "^8.10.152",
@@ -340,7 +340,7 @@
     "@types/react": "^19.2.2",
     "@types/ws": "^8.18.1",
     "better-auth": "^1.6.2",
-    "effect": ">=4.0.0-beta.74 || >=4.0.0",
+    "effect": ">=4.0.0-beta.78 || >=4.0.0",
     "react-devtools-core": "^7.0.1",
     "solid-js": "latest",
     "tsconfig-paths": "^4.2.0",
@@ -350,12 +350,12 @@
     "ws": "^8.20.0"
   },
   "peerDependencies": {
-    "@effect/platform-bun": ">=4.0.0-beta.74 || >=4.0.0",
-    "@effect/platform-node": ">=4.0.0-beta.74 || >=4.0.0",
-    "@effect/sql-pg": ">=4.0.0-beta.74 || >=4.0.0",
+    "@effect/platform-bun": ">=4.0.0-beta.78 || >=4.0.0",
+    "@effect/platform-node": ">=4.0.0-beta.78 || >=4.0.0",
+    "@effect/sql-pg": ">=4.0.0-beta.78 || >=4.0.0",
     "drizzle-kit": ">=1.0.0-rc.1",
     "drizzle-orm": ">=1.0.0-rc.1",
-    "effect": ">=4.0.0-beta.74 || >=4.0.0",
+    "effect": ">=4.0.0-beta.78 || >=4.0.0",
     "vite": "^8.0.7",
     "ws": "^8.20.0"
   },

package/src/Apply.ts

@@ -1544,7 +1544,20 @@ const collectGarbage = Effect.fnUntraced(function* (
               });
             }
 
-            if (attr !== undefined) {
+            // Honor `retain` for the old generation of a replacement, mirroring
+            // the orphan-delete path above. Delete-node retain is already
+            // handled with an early return; this guards the replaced
+            // old-generation physical delete.
+            const retainOldGeneration =
+              !isDeleteNode(node) && node.removalPolicy === "retain";
+
+            if (retainOldGeneration) {
+              yield* scopedSession.note(
+                "Retaining replaced resource (removal policy: retain)...",
+              );
+            }
+
+            if (attr !== undefined && !retainOldGeneration) {
               yield* provider
                 .delete({
                   id: logicalId,
@@ -1573,7 +1586,9 @@ const collectGarbage = Effect.fnUntraced(function* (
               });
               yield* report("deleted");
             } else {
-              yield* scopedSession.note("Cleaning up replaced resource...");
+              if (!retainOldGeneration) {
+                yield* scopedSession.note("Cleaning up replaced resource...");
+              }
               if (
                 node.old.status === "replacing" ||
                 node.old.status === "replaced"
@@ -1613,7 +1628,11 @@ const collectGarbage = Effect.fnUntraced(function* (
                   removalPolicy: node.removalPolicy,
                 });
               }
-              yield* scopedSession.note("Replaced resource cleanup complete.");
+              yield* scopedSession.note(
+                retainOldGeneration
+                  ? "Replaced resource retained."
+                  : "Replaced resource cleanup complete.",
+              );
             }
           }),
         ));

package/src/Auth/AuthProvider.ts

@@ -33,7 +33,7 @@ export class AuthError extends Schema.TaggedErrorClass<AuthError>()(
   "AuthError",
   {
     message: Schema.String,
-    cause: Schema.optional(Schema.Defect),
+    cause: Schema.optional(Schema.Defect()),
   },
 ) {}
 

package/src/Binding.ts

@@ -1,8 +1,8 @@
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Effectable from "effect/Effectable";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
-import { SingleShotGen } from "effect/Utils";
 import type { Input } from "./Input.ts";
 import * as Namespace from "./Namespace.ts";
 import { ALCHEMY_PHASE } from "./Phase.ts";
@@ -157,7 +157,7 @@ export const Policy =
       ),
     );
 
-    const asEffect = () =>
+    const evaluate = () =>
       Effect.all([Self, Service]).pipe(
         Effect.map(
           ([resource, fn]) =>
@@ -176,44 +176,51 @@ export const Policy =
         ),
       );
     // @ts-expect-error
-    return Object.assign(self, {
-      [Symbol.iterator]() {
-        return new SingleShotGen(asEffect());
-      },
-      asEffect,
-      bind: (...args: any[]) =>
-        asEffect().pipe(Effect.flatMap((fn) => fn(...args))),
-      layer: {
-        succeed: (
-          fn: (
-            self: ResourceLike,
-            ...args: Parameters<Shape>
-          ) => Effect.Effect<void>,
-        ) =>
-          Layer.succeed(
-            self,
-            // @ts-expect-error
-            (...args: Parameters<Shape>) =>
-              Self.use((self) => fn(self as ResourceLike, ...args)),
-          ),
-        effect: (
-          fn: Effect.Effect<
-            (
+    return Object.assign(
+      self,
+      // `self` is a Context tag (already an Effect). Spreading the Effect
+      // prototype retargets `yield* Policy` from the raw tag to the resolved
+      // bind-function while keeping `Effect.isEffect(Policy)` true so
+      // `Effect.all`/`forEach` behave.
+      Effectable.Prototype({
+        label: `Policy<${Identifier}>`,
+        evaluate,
+      }),
+      {
+        bind: (...args: any[]) =>
+          evaluate().pipe(Effect.flatMap((fn) => fn(...args))),
+        layer: {
+          succeed: (
+            fn: (
               self: ResourceLike,
               ...args: Parameters<Shape>
-            ) => Effect.Effect<void>
-          >,
-        ) =>
-          Layer.effect(
-            self,
-            // @ts-expect-error
-            Effect.map(
-              fn,
-              (fn) =>
-                (...args: Parameters<Shape>) =>
-                  Self.use((self) => fn(self as ResourceLike, ...args)),
+            ) => Effect.Effect<void>,
+          ) =>
+            Layer.succeed(
+              self,
+              // @ts-expect-error
+              (...args: Parameters<Shape>) =>
+                Self.use((self) => fn(self as ResourceLike, ...args)),
+            ),
+          effect: (
+            fn: Effect.Effect<
+              (
+                self: ResourceLike,
+                ...args: Parameters<Shape>
+              ) => Effect.Effect<void>
+            >,
+          ) =>
+            Layer.effect(
+              self,
+              // @ts-expect-error
+              Effect.map(
+                fn,
+                (fn) =>
+                  (...args: Parameters<Shape>) =>
+                    Self.use((self) => fn(self as ResourceLike, ...args)),
+              ),
             ),
-          ),
+        },
       },
-    });
+    );
   };

package/src/Build/DevServer.ts

@@ -0,0 +1,330 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Hash from "effect/Hash";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import { ChildProcess } from "effect/unstable/process";
+import {
+  ChildProcessSpawner,
+  type ChildProcessHandle,
+} from "effect/unstable/process/ChildProcessSpawner";
+import { AlchemyContext } from "../AlchemyContext.ts";
+import { isResolved } from "../Diff.ts";
+import * as RpcProvider from "../Local/RpcProvider.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+
+export interface DevServerProps {
+  /**
+   * Shell command to run as a long-lived dev process (e.g. `npm run dev`).
+   */
+  command: string;
+  /**
+   * Working directory for the command. Defaults to `process.cwd()`.
+   */
+  cwd?: string;
+  /**
+   * Extra environment variables passed to the command on top of `process.env`.
+   */
+  env?: Record<string, string | Redacted.Redacted<string>>;
+}
+
+/**
+ * A long-lived shell process scoped to a stack instance, started during
+ * `alchemy dev`, restarted when inputs are changes.
+ *
+ * The provider runs inside the dev sidecar (see `Build/Local.ts`) so the
+ * child process survives user-code HMR — Alchemy's user process can restart
+ * without killing your `npm run dev` server. During deploy this performs a no-op
+ *
+ * The child's stdout/stderr are mirrored to the sidecar's terminal so the
+ * user still sees colored dev-server output, and each line is scanned for
+ * the first `http(s)://…` URL. The first match (with ANSI escapes stripped)
+ * is exposed as `url` — useful for surfacing a dev server's local URL back
+ * out to whatever resource declared this `DevServer`.
+ */
+export interface DevServer extends Resource<
+  "Build.DevServer",
+  DevServerProps,
+  {
+    /**
+     * URL extracted from the first matching stdout/stderr line. Best-effort:
+     * `undefined` if no URL appeared within {@link URL_EXTRACT_TIMEOUT}.
+     */
+    url?: string;
+  }
+> {}
+
+/**
+ * A long-lived shell process scoped to a stack instance, started during
+ * `alchemy dev` and restarted when inputs change. During deploy this is
+ * a no-op — `DevServer` resources only run in dev mode.
+ *
+ * The child process runs inside the dev sidecar so it survives
+ * user-code HMR restarts. Its stdout/stderr are mirrored to the
+ * terminal and scanned for the first `http(s)://…` URL, which is
+ * exposed as the `url` output attribute.
+ *
+ * @resource
+ *
+ * @section Basic Usage
+ * Pass a shell command that starts a long-lived dev server. Alchemy
+ * runs it in the background and extracts the first URL it prints.
+ *
+ * @example Start a Vite dev server
+ * ```typescript
+ * const dev = yield* DevServer("Frontend", {
+ *   command: "npm run dev",
+ * });
+ * console.log(dev.url); // e.g. "http://localhost:5173"
+ * ```
+ *
+ * @section Working Directory
+ * Use `cwd` to run the command in a subdirectory — useful in
+ * monorepos where each package has its own dev server.
+ *
+ * @example Monorepo package
+ * ```typescript
+ * const dev = yield* DevServer("Web", {
+ *   command: "npm run dev",
+ *   cwd: "apps/web",
+ * });
+ * ```
+ *
+ * @section Environment Variables
+ * Extra environment variables are merged on top of `process.env`.
+ * Sensitive values can be wrapped in `Redacted` to keep them out
+ * of logs and state files.
+ *
+ * @example Custom port and env
+ * ```typescript
+ * const dev = yield* DevServer("Api", {
+ *   command: "npm run dev",
+ *   env: {
+ *     PORT: "4000",
+ *     DATABASE_URL: Redacted.make("postgres://..."),
+ *   },
+ * });
+ * ```
+ */
+export const DevServer = Resource<DevServer>("Build.DevServer");
+
+/**
+ * How long reconcile waits for a URL to appear in the child's output
+ * before giving up and returning `{ url: undefined }`. The child keeps
+ * running either way — this only bounds how long the deploy plan waits.
+ *
+ * Kept small because dev servers (vite, next, zola, …) print their URL
+ * within ~1s, and a long wait here just stalls `alchemy dev` startup
+ * for commands that never produce a URL.
+ */
+const URL_EXTRACT_TIMEOUT = "5 seconds";
+
+// Matches the first plain http(s) URL. Stops at whitespace and at a small
+// set of punctuation typically used to wrap URLs in log output.
+const URL_REGEX = /https?:\/\/[^\s)\],"'`]+/;
+
+// ECMA-262 ANSI/VT100 escape sequences — `Vite`, `Next`, etc. surround the
+// URL with color codes that would otherwise be eaten by the URL regex.
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\x1b\[[0-9;]*m/g;
+
+/**
+ * Live-mode no-op. `DevServer` resources should only be created in dev mode;
+ * if one slips into a deploy, this is a noisy no-op rather than a crash.
+ */
+export const LiveDevServerProvider = () =>
+  Provider.effect(
+    DevServer,
+    Effect.succeed(
+      DevServer.Provider.of({
+        diff: () => Effect.succeed({ action: "noop" }),
+        reconcile: () => Effect.succeed({}),
+        delete: () => Effect.void,
+      }),
+    ),
+  );
+
+/**
+ * Dev-mode provider. Runs inside the RPC sidecar so the child process
+ * outlives user-code restarts. Tracks instances in a module-level closure
+ * keyed by resource id; on `reconcile`, it diffs the props hash and either
+ * reuses the existing process or interrupts + respawns.
+ */
+export const LocalDevServerProvider = () =>
+  RpcProvider.effect(
+    DevServer,
+    import.meta.resolve(
+      // See LocalWorkerProvider — must match the on-disk extension of the
+      // sidecar entry file.
+      import.meta.url.endsWith(".ts") ? "./Local.ts" : "./Local.js",
+      import.meta.url,
+    ),
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner;
+      // The provider's outer scope lives for the lifetime of the sidecar,
+      // which is exactly what we want: child processes get forked into
+      // sub-scopes off of this one, so they survive any single user-code
+      // restart but die when the sidecar shuts down.
+      const rootScope = yield* Effect.scope;
+
+      const instances = new Map<
+        string,
+        {
+          hash: number;
+          handle: ChildProcessHandle;
+          scope: Scope.Closeable;
+          /**
+           * Resolves with the first URL found in the child's output. Stored
+           * on the instance so that no-op reconciles (same hash, process
+           * still running) can await it too — even if the URL hadn't yet
+           * appeared at the previous reconcile.
+           */
+          urlDeferred: Deferred.Deferred<string>;
+        }
+      >();
+
+      const spawn = Effect.fn(function* (
+        props: DevServerProps,
+        urlDeferred: Deferred.Deferred<string>,
+      ) {
+        const [command, ...args] = props.command.split(" ");
+
+        const handle = yield* spawner.spawn(
+          ChildProcess.make(command, args, {
+            cwd: props.cwd ?? process.cwd(),
+            env: {
+              ...process.env,
+              ...Object.fromEntries(
+                Object.entries(props.env ?? {}).map(([k, v]) => [
+                  k,
+                  Redacted.isRedacted(v) ? Redacted.value(v) : v,
+                ]),
+              ),
+            },
+            stdin: "inherit",
+            // Leave stdout/stderr piped so we can both mirror to the parent
+            // terminal AND parse lines for the first URL.
+          }),
+        );
+
+        // Mirror + extract on both streams, forked into the current scope so
+        // they're interrupted when the instance scope closes.
+        yield* mirrorAndExtract(handle.stdout, "stdout", urlDeferred).pipe(
+          Effect.forkScoped,
+        );
+        yield* mirrorAndExtract(handle.stderr, "stderr", urlDeferred).pipe(
+          Effect.forkScoped,
+        );
+
+        return handle;
+      });
+
+      const stop = Effect.fn(function* (id: string) {
+        const existing = instances.get(id);
+        if (existing) {
+          yield* existing.handle.kill();
+          yield* Scope.close(existing.scope, Exit.void);
+          instances.delete(id);
+        }
+      });
+
+      const awaitUrl = (deferred: Deferred.Deferred<string>) =>
+        Deferred.await(deferred).pipe(
+          Effect.timeoutOption(URL_EXTRACT_TIMEOUT),
+          Effect.map(Option.getOrUndefined),
+        );
+
+      return DevServer.Provider.of({
+        diff: Effect.fn(function* ({ id, news }) {
+          if (!isResolved(news)) return undefined;
+          const hash = Hash.structure(news);
+          if (instances.get(id)?.hash === hash) {
+            return { action: "noop" };
+          }
+          return { action: "update" };
+        }),
+        reconcile: Effect.fn(function* ({ id, news }) {
+          const hash = Hash.structure(news);
+          const existing = instances.get(id);
+
+          if (existing) {
+            if (existing.hash === hash && (yield* existing.handle.isRunning)) {
+              const url = yield* awaitUrl(existing.urlDeferred);
+              return { url };
+            }
+
+            yield* stop(id);
+          }
+
+          const scope = yield* Scope.fork(rootScope);
+          const urlDeferred = yield* Deferred.make<string>();
+          const handle = yield* spawn(news, urlDeferred).pipe(
+            Scope.provide(scope),
+          );
+          instances.set(id, { hash, handle, scope, urlDeferred });
+          const url = yield* awaitUrl(urlDeferred);
+          return { url };
+        }),
+        delete: Effect.fn(function* ({ id }) {
+          yield* stop(id);
+        }),
+      });
+    }),
+  );
+
+/**
+ * Drains a child stdout/stderr stream into the matching parent stream while
+ * scanning each completed line for the first URL. Resolves `urlDeferred`
+ * the first time a URL is found (subsequent calls are no-ops).
+ *
+ * Modeled on `idempotent-spawn.ts`'s `extract` hook — single-pass over each
+ * line, ANSI escapes stripped before matching, with a buffer for incomplete
+ * trailing lines across chunk boundaries.
+ */
+const mirrorAndExtract = (
+  source: Stream.Stream<Uint8Array, any>,
+  sink: "stdout" | "stderr",
+  urlDeferred: Deferred.Deferred<string>,
+) =>
+  Effect.gen(function* () {
+    let lineBuffer = "";
+    const decoder = new TextDecoder("utf-8");
+    yield* Stream.runForEach(source, (chunk) =>
+      Effect.sync(() => {
+        // Pass the raw bytes through so terminal colors, cursor moves,
+        // progress bars etc. keep working.
+        process[sink].write(chunk);
+
+        lineBuffer += decoder.decode(chunk, { stream: true });
+        let newlineIdx = lineBuffer.indexOf("\n");
+        while (newlineIdx !== -1) {
+          const line = lineBuffer.slice(0, newlineIdx);
+          lineBuffer = lineBuffer.slice(newlineIdx + 1);
+          newlineIdx = lineBuffer.indexOf("\n");
+          const match = line.replace(ANSI_REGEX, "").match(URL_REGEX);
+          if (match) {
+            // Deferred.doneUnsafe is a synchronous fire-and-forget — first
+            // caller wins, subsequent calls are dropped, which is exactly
+            // what we want for "record the FIRST URL".
+            Deferred.doneUnsafe(urlDeferred, Effect.succeed(match[0]));
+            return;
+          }
+        }
+      }),
+    );
+  });
+
+/**
+ * Selects the live or dev DevServer provider based on `AlchemyContext.dev`.
+ */
+export const DevServerProvider = () =>
+  Layer.unwrap(
+    AlchemyContext.useSync((context) =>
+      context.dev ? LocalDevServerProvider() : LiveDevServerProvider(),
+    ),
+  );

package/src/Build/Local.ts

@@ -0,0 +1,4 @@
+import { LocalDevServerProvider } from "../Build/DevServer.ts";
+import * as RpcServer from "../Local/RpcServer.ts";
+
+LocalDevServerProvider().pipe(RpcServer.launch);

package/src/Bundle/Bundle.ts

@@ -63,7 +63,7 @@ export class BundleError extends Schema.TaggedErrorClass<BundleError>()(
   "BundleError",
   {
     message: Schema.String,
-    cause: Schema.optional(Schema.DefectWithStack),
+    cause: Schema.optional(Schema.Defect({ includeStack: true })),
   },
 ) {}
 

package/src/Cloudflare/Access.ts

@@ -12,7 +12,7 @@ export class AccessError extends Schema.TaggedErrorClass<AccessError>()(
   "AccessError",
   {
     message: Schema.String,
-    cause: Schema.optional(Schema.Defect),
+    cause: Schema.optional(Schema.Defect()),
   },
 ) {}
 

package/src/Cloudflare/AiGateway/AiGateway.ts

@@ -277,7 +277,7 @@ export const isAiGateway = (value: unknown): value is AiGateway =>
  *
  * export default class Api extends Cloudflare.Worker<Api>()(
  *   "Api",
- *   { main: import.meta.path },
+ *   { main: import.meta.filename },
  *   Effect.gen(function* () {
  *     const aiGateway = yield* Cloudflare.AiGateway.bind(Gateway);
  *