alchemy 2.0.0-beta.57 → 2.0.0-beta.58

package/src/Cloudflare/Workers/Workflow.ts

@@ -9,6 +9,7 @@ import { ALCHEMY_PHASE } from "../../Phase.ts";
 import type { PlatformServices } from "../../Platform.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
 import { effectClass, taggedFunction } from "../../Util/effect.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import { Worker, WorkerEnvironment, type WorkerServices } from "./Worker.ts";
@@ -115,7 +116,10 @@ export type WorkflowRunServices =
   | WorkerServices
   | ExecutionContext;
 
-export type WorkflowServices = WorkflowRunServices | PlatformServices;
+export type WorkflowServices =
+  | WorkflowRunServices
+  | PlatformServices
+  | RuntimeContext;
 
 /**
  * Metadata stored in the worker export map to distinguish workflow exports
@@ -275,7 +279,7 @@ export class WorkflowScope extends Context.Service<
  *
  * ```typescript
  * Effect.gen(function* () {
- *   const kv = yield* Cloudflare.KVNamespace.bind(KV);
+ *   const kv = yield* Cloudflare.KV.ReadWriteNamespace(KV);
  *
  *   return Effect.fn(function* (input: { roomId: string; message: string }) {
  *     const { roomId, message } = input;
@@ -522,13 +526,13 @@ export const WorkflowProvider = () =>
               ),
             );
           }),
-        diff: Effect.fnUntraced(function* ({ output }) {
+        diff: Effect.fn(function* ({ output }) {
           // If the workflowId starts with "dev:", and we're not in dev mode, trigger an update so the workflow is created.
           if (output?.workflowId.startsWith("dev:") && !ctx.dev) {
             return { action: "update" };
           }
         }),
-        reconcile: Effect.fnUntraced(function* ({ news, output }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
           const { accountId } = yield* yield* CloudflareEnvironment;
           const acct = output?.accountId ?? accountId;
           yield* Effect.logInfo(
@@ -561,7 +565,7 @@ export const WorkflowProvider = () =>
             accountId: acct,
           };
         }),
-        delete: Effect.fnUntraced(function* ({ output }) {
+        delete: Effect.fn(function* ({ output }) {
           yield* Effect.logInfo(
             `Cloudflare Workflow delete: ${output.workflowName}`,
           );

package/src/Cloudflare/Workers/index.ts

@@ -3,11 +3,9 @@ export * from "./Assets.ts";
 export * from "./ConfigProvider.ts";
 export * from "./CronEventSource.ts";
 export * from "./DurableObjectBridge.ts";
-export * from "./DurableObjectChatPersistence.ts";
 export * from "./DurableObjectNamespace.ts";
 export * from "./DurableObjectState.ts";
 export * from "./DurableObjectStorage.ts";
-export * from "./DynamicWorkerLoader.ts";
 export * from "./Fetch.ts";
 export * from "./GitHubRepositoryEventSource.ts";
 export * from "./HttpServer.ts";
@@ -27,5 +25,7 @@ export * from "./WebSocket.ts";
 export * from "./Worker.ts";
 export * from "./WorkerBinding.ts";
 export * from "./WorkerBridge.ts";
+export * from "./WorkerLoader.ts";
+export * from "./WorkerProvider.ts";
 export * from "./Workflow.ts";
 export * from "./WorkflowBridge.ts";

package/src/Cloudflare/Zaraz/ZarazConfig.ts

@@ -291,7 +291,7 @@ export const ZarazConfigProvider = () =>
     }),
   });
 
-const resolve = Effect.fnUntraced(function* (zone: ZoneReference) {
+const resolve = Effect.fn(function* (zone: ZoneReference) {
   const { accountId } = yield* yield* CloudflareEnvironment;
   return yield* resolveZoneId({
     accountId,

package/src/Cloudflare/Zone/Hold.ts

@@ -1,6 +1,7 @@
 import * as zones from "@distilled.cloud/cloudflare/zones";
 import * as Effect from "effect/Effect";
 import * as Predicate from "effect/Predicate";
+import * as Schedule from "effect/Schedule";
 
 import { Unowned } from "../../AdoptPolicy.ts";
 import * as Provider from "../../Provider.ts";
@@ -105,6 +106,14 @@ export const ZoneHold = Resource<ZoneHold>(ZoneHoldTypeId);
 export const isZoneHold = (value: unknown): value is ZoneHold =>
   Predicate.hasProperty(value, "Type") && value.Type === ZoneHoldTypeId;
 
+// Cloudflare can transiently fail to authenticate a valid token, surfacing as
+// `Forbidden`. Retry with exponential backoff capped at 5s, bounded to ~8
+// attempts so a persistently-unauthorized call still fails fast.
+const forbiddenRetrySchedule = Schedule.exponential("500 millis").pipe(
+  Schedule.either(Schedule.spaced("5 seconds")),
+  Schedule.both(Schedule.recurs(8)),
+);
+
 export const ZoneHoldProvider = () =>
   Provider.succeed(ZoneHold, {
     stables: ["zoneId"],
@@ -119,6 +128,15 @@ export const ZoneHoldProvider = () =>
         allZones.map((zone) => zone.id),
         (zoneId) =>
           zones.getHold({ zoneId }).pipe(
+            // Cloudflare intermittently rejects a *valid* token with
+            // `Forbidden` (a transient edge auth failure). It is retryable —
+            // back off and try again rather than dropping the zone, so a
+            // genuinely accessible zone (e.g. the standing test zone) never
+            // silently falls out of the enumeration on a blip.
+            Effect.retry({
+              while: (e) => e._tag === "Forbidden",
+              schedule: forbiddenRetrySchedule,
+            }),
             Effect.map((observed) => toAttributes(zoneId, observed)),
             // Zone deleted out-of-band mid-enumeration — drop it.
             Effect.catchTag("InvalidZoneIdentifier", () =>

package/src/Cloudflare/index.ts

@@ -69,6 +69,7 @@ export * from "./Images/index.ts";
 export * from "./Intel/index.ts";
 export * from "./KeylessCertificate/index.ts";
 export * from "./KV/index.ts";
+export * as KV from "./KV/index.ts";
 export * from "./LeakedCredentialCheck/index.ts";
 export * from "./LoadBalancer/index.ts";
 export * from "./Logpush/index.ts";
@@ -89,7 +90,9 @@ export * from "./PageShield/index.ts";
 export * from "./Pipelines/index.ts";
 export * from "./Providers.ts";
 export * from "./Queue/index.ts";
+export * as Queues from "./Queue/index.ts";
 export * from "./R2/index.ts";
+export * as R2 from "./R2/index.ts";
 export * from "./R2DataCatalog/index.ts";
 export * from "./RateLimit/index.ts";
 export * from "./RealtimeKit/index.ts";

package/src/Command/Build.ts

@@ -0,0 +1,187 @@
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { havePropsChanged, isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import {
+  CommandError,
+  CommandExecutor,
+  OutputNotFound,
+  type CommandProps,
+} from "./Command.ts";
+import { hashDirectory, type MemoOptions } from "./Memo.ts";
+
+export interface BuildProps extends CommandProps {
+  /**
+   * The output path (file or directory) produced by the build.
+   * This path is relative to the working directory.
+   * @example "dist"
+   */
+  outdir: string;
+  /**
+   * Controls which files are hashed to decide whether the build should re-run.
+   * By default every non-gitignored file in `cwd` is hashed, plus the nearest
+   * lockfile. Provide explicit globs to narrow the scope, or set `false` to
+   * disable memoization and rebuild on every deploy.
+   *
+   * @see {@link MemoOptions}
+   * @default true
+   */
+  memo?: MemoOptions | boolean;
+}
+
+export interface Build extends Resource<
+  "Command.Build",
+  BuildProps,
+  {
+    /**
+     * Path to the build output, relative to `process.cwd()`.
+     *
+     * Stored relative (rather than absolute) so the value is portable across
+     * machines — state written by a CI runner
+     * (`/home/runner/work/.../dist`) resolves correctly on a local laptop and
+     * vice versa. Consumers should `path.resolve()` it against their own cwd
+     * to obtain an absolute path.
+     */
+    outdir: string;
+    hash: {
+      /**
+       * Hash of the input files that produced this build.
+       */
+      input: string | undefined;
+      /**
+       * Hash of the output files from this build.
+       */
+      output: string | undefined;
+    };
+  }
+> {}
+
+/**
+ * A `Build` runs a shell command that produces an output asset (a file or
+ * directory) and tracks that asset in state. Unlike `Exec`, a `Build` has an
+ * output contract: `reconcile` verifies the command actually produced `outdir`
+ * and exposes its location so downstream resources (e.g. a `Cloudflare.Worker`'s
+ * static assets) can consume it.
+ *
+ * Inputs are content-hashed by default so an unchanged project skips the
+ * rebuild entirely; set `memo: false` to rebuild on every deploy.
+ *
+ * @resource
+ * @section Building a Vite App
+ * @example Basic Vite Build
+ * ```typescript
+ * const build = yield* Build("vite-build", {
+ *   command: "npm run build",
+ *   cwd: "./frontend",
+ *   outdir: "dist",
+ * });
+ * yield* Console.log(build.outdir); // path to the dist directory, relative to process.cwd()
+ * yield* Console.log(build.hash.output); // hash of the output files (when memo is enabled)
+ * ```
+ *
+ * @section Building with Custom Environment
+ * @example Build with Environment Variables
+ * ```typescript
+ * const build = yield* Build("production-build", {
+ *   command: "npm run build",
+ *   cwd: "./app",
+ *   outdir: "dist",
+ *   env: {
+ *     NODE_ENV: "production",
+ *     API_URL: "https://api.example.com",
+ *   },
+ * });
+ * ```
+ *
+ * @section Customizing Memoization
+ * @example Customize Memoization
+ * ```typescript
+ * const build = yield* Build("custom-build", {
+ *   command: "npm run build",
+ *   cwd: "./app",
+ *   outdir: "dist",
+ *   memo: { include: ["src/**", "package.json"], exclude: ["node_modules", "dist"] },
+ * });
+ * ```
+ */
+export const Build = Resource<Build>("Command.Build");
+
+export const BuildProvider = () =>
+  Provider.effect(
+    Build,
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const fs = yield* FileSystem.FileSystem;
+      const { run } = yield* CommandExecutor;
+
+      const makeOutput = Effect.fn(function* (props: BuildProps) {
+        const cwd = path.resolve(props.cwd ?? process.cwd());
+        const outdir = path.resolve(cwd, props.outdir);
+        if (!(yield* fs.exists(outdir))) {
+          return yield* new CommandError({
+            command: props.command,
+            reason: new OutputNotFound({
+              outdir: props.outdir,
+            }),
+          });
+        }
+        return {
+          outdir: path.relative(process.cwd(), outdir),
+          hash:
+            props.memo === false
+              ? { input: undefined, output: undefined }
+              : yield* Effect.all(
+                  {
+                    input: hashDirectory({
+                      cwd,
+                      memo: props.memo === true ? {} : props.memo,
+                    }),
+                    output: hashDirectory({
+                      cwd: outdir,
+                      memo: {
+                        exclude: [],
+                        lockfile: false,
+                      },
+                    }),
+                  },
+                  { concurrency: "unbounded" },
+                ),
+        };
+      });
+
+      return {
+        list: () => Effect.succeed([]),
+        diff: Effect.fn(function* ({ olds, news, output }) {
+          if (!output || !isResolved(news)) return undefined;
+
+          // Always update if memoization is disabled or hashes are not available.
+          if (news.memo === false || !output.hash.input || !output.hash.output)
+            return { action: "update" };
+
+          // Optimization: short-circuit if props have changed to avoid unnecessary file system operations.
+          if (havePropsChanged(olds, news)) return { action: "update" };
+
+          const newOutput = yield* makeOutput(news).pipe(
+            Effect.catchReason(
+              "CommandError",
+              "OutputNotFound",
+              () => Effect.undefined,
+            ),
+          );
+          return {
+            action: Equal.equals(newOutput, output) ? "noop" : "update",
+          };
+        }),
+        reconcile: ({ news, session }) =>
+          run(news, session).pipe(Effect.andThen(makeOutput(news))),
+        delete: Effect.fn(function* ({ output }) {
+          const outdir = path.resolve(output.outdir);
+          if (!(yield* fs.exists(outdir))) return;
+          yield* fs.remove(outdir, { recursive: true });
+        }),
+      };
+    }),
+  );

package/src/Command/Command.ts

@@ -0,0 +1,244 @@
+/**
+ * Contains props, error tags, and the live service for executing commands.
+ * Shared between the `Build`, `Dev`, and `Exec` resources.
+ */
+
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { flow } from "effect/Function";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
+import type { PlatformError, SystemError } from "effect/PlatformError";
+import { BadArgument } from "effect/PlatformError";
+import * as Predicate from "effect/Predicate";
+import * as Redacted from "effect/Redacted";
+import type * as Scope from "effect/Scope";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
+import type { ScopedPlanStatusSession } from "../Cli/Cli.ts";
+import { isNonInteractive } from "../Util/interactive.ts";
+
+/**
+ * Base properties for a command resource.
+ */
+export interface CommandProps {
+  /**
+   * The command to run.
+   */
+  command: string;
+  /**
+   * Working directory for the command. Defaults to `process.cwd()`.
+   */
+  cwd?: string;
+  /**
+   * If set to true, runs the command inside of a shell, defaulting to /bin/sh on UNIX systems and cmd.exe on Windows.
+   * It is generally discouraged to use this option, as it can lead to security vulnerabilities and is not portable.
+   * If set to a string, runs the command inside of the specified shell.
+   * @default false
+   */
+  shell?: string | boolean;
+  /**
+   * Extra environment variables passed to the command on top of `process.env`.
+   */
+  env?: Record<string, string | Redacted.Redacted<string>>;
+}
+
+export class CommandExecutor extends Context.Service<
+  CommandExecutor,
+  {
+    /**
+     * Spawns a command, returning the child process handle.
+     */
+    readonly spawn: (
+      props: CommandProps,
+    ) => Effect.Effect<
+      ChildProcessSpawner.ChildProcessHandle,
+      CommandError,
+      Scope.Scope
+    >;
+    /**
+     * Executes a command, returning the exit code, stdout, and stderr.
+     * Throws a {@link CommandError} if the command exits with a non-zero exit code.
+     */
+    readonly run: (
+      props: CommandProps,
+      session: ScopedPlanStatusSession,
+    ) => Effect.Effect<
+      { exitCode: number; stdout: string; stderr: string },
+      CommandError
+    >;
+  }
+>()("alchemy/Command/CommandExecutor") {}
+
+/**
+ * Extends Effect's `PlatformError` to include the command that failed and some command-specific error reasons.
+ */
+export class CommandError extends Data.TaggedError("CommandError")<{
+  command: string;
+  reason: SystemError | BadArgument | UnexpectedExit | OutputNotFound;
+  cause?: unknown;
+}> {
+  constructor({
+    command,
+    reason,
+  }: {
+    command: string;
+    reason: CommandError["reason"];
+  }) {
+    if ("cause" in reason) {
+      super({ command, reason, cause: reason.cause });
+    } else {
+      super({ command, reason });
+    }
+  }
+
+  override get message() {
+    return `Failed to execute command "${this.command}": ${this.reason.message}`;
+  }
+}
+
+export const isCommandError = (error: unknown): error is CommandError =>
+  Predicate.isTagged(error, "CommandError");
+
+/**
+ * Represents when a command exits unexpectedly.
+ */
+export class UnexpectedExit extends Data.TaggedError("UnexpectedExit")<{
+  exitCode: number;
+  stderr: string;
+}> {
+  override get message() {
+    return `The command exited with code ${this.exitCode}. Standard error output: ${this.stderr}`;
+  }
+}
+
+/**
+ * Represents when the output directory does not exist.
+ */
+export class OutputNotFound extends Data.TaggedError("OutputNotFound")<{
+  outdir: string;
+}> {
+  override get message() {
+    return `The output directory "${this.outdir}" does not exist.`;
+  }
+}
+
+export const CommandExecutorLive = () =>
+  Layer.effect(
+    CommandExecutor,
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+      /** Parses a command string into a binary and arguments, unless {@link CommandProps.shell} is true. */
+      const parseCommand = (
+        props: CommandProps,
+      ): Effect.Effect<{ bin: string; args: string[] }, CommandError> => {
+        if (props.shell) {
+          return Effect.succeed({ bin: props.command, args: [] });
+        }
+        const [bin, ...args] = props.command
+          .split(/(\s+)/)
+          .filter((part) => !!part.trim());
+        if (!bin) {
+          return Effect.fail(
+            new CommandError({
+              command: props.command,
+              reason: new BadArgument({
+                module: "Command",
+                method: "parseCommand",
+                description: "Command is empty",
+              }),
+            }),
+          );
+        }
+        return Effect.succeed({ bin, args });
+      };
+
+      /** Spawns a command, returning the child process handle. */
+      const spawn = (props: CommandProps) =>
+        parseCommand(props).pipe(
+          Effect.flatMap(({ bin, args }) =>
+            spawner.spawn(
+              ChildProcess.make(bin, args, {
+                cwd: path.resolve(props.cwd ?? process.cwd()),
+                shell: props.shell ?? false,
+                env: Object.fromEntries(
+                  Object.entries(props.env ?? {}).map(([k, v]) => [
+                    k,
+                    Redacted.isRedacted(v) ? Redacted.value(v) : v,
+                  ]),
+                ),
+                extendEnv: true,
+                stdin: isNonInteractive() ? "ignore" : "inherit",
+                stdout: "pipe",
+                stderr: "pipe",
+                detached: false,
+              }),
+            ),
+          ),
+          mapError(props.command),
+        );
+
+      /** Collects the output of a stream, tapping each line to a sink. */
+      const collect = (
+        stream: Stream.Stream<Uint8Array, PlatformError>,
+        tap: (chunk: string) => Effect.Effect<void>,
+      ) =>
+        stream.pipe(
+          Stream.decodeText,
+          Stream.tapSink(
+            Sink.make<string>()(
+              flow(Stream.splitLines, Stream.runForEach(tap)),
+            ),
+          ),
+          Stream.mkString,
+        );
+
+      /** Maps a PlatformError to a CommandError. */
+      const mapError = (command: string) =>
+        Effect.mapError((error: PlatformError | CommandError) =>
+          error._tag === "CommandError"
+            ? error
+            : new CommandError({
+                command,
+                reason: error.reason,
+              }),
+        );
+
+      return CommandExecutor.of({
+        spawn,
+        /** Executes a command, returning the exit code, stdout, and stderr. */
+        run: (props: CommandProps, session: ScopedPlanStatusSession) =>
+          spawn(props).pipe(
+            Effect.flatMap((child) =>
+              Effect.all(
+                {
+                  exitCode: child.exitCode,
+                  stdout: collect(child.stdout, session.note),
+                  stderr: collect(child.stderr, session.note),
+                },
+                { concurrency: "unbounded" },
+              ).pipe(mapError(props.command)),
+            ),
+            Effect.tap(({ exitCode, stderr }) =>
+              exitCode !== 0
+                ? Effect.fail(
+                    new CommandError({
+                      command: props.command,
+                      reason: new UnexpectedExit({
+                        exitCode,
+                        stderr,
+                      }),
+                    }),
+                  )
+                : Effect.void,
+            ),
+            Effect.scoped,
+          ),
+      });
+    }),
+  );