alchemy-effect 0.6.3 → 0.7.0

package/src/Artifacts.ts

@@ -0,0 +1,147 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as ServiceMap from "effect/ServiceMap";
+
+/**
+ * Per-resource in-memory artifacts shared across a single `Plan.make -> apply`
+ * execution.
+ *
+ * The engine scopes this service by resource `FQN` before invoking lifecycle
+ * handlers, so providers should treat it as a resource-local bag for expensive,
+ * deterministic intermediate results that can be reused across phases.
+ *
+ * Expected usage:
+ *
+ * - `diff` computes an expensive artifact once and stores it
+ * - `create` / `update` reads the same artifact and skips recomputing it
+ * - artifacts are ephemeral and must never be required for correctness on a
+ *   later deploy because the bag is reset between runs
+ *
+ * Example:
+ *
+ * ```ts
+ * const artifacts = yield* Artifacts;
+ * const cached = yield* artifacts.get<PreparedBundle>("bundle");
+ * if (cached) return cached;
+ *
+ * const bundle = yield* prepareBundle();
+ * yield* artifacts.set("bundle", bundle);
+ * return bundle;
+ * ```
+ */
+export class Artifacts extends ServiceMap.Service<
+  Artifacts,
+  {
+    /**
+     * Get an artifact by key from the current resource's bag.
+     */
+    get<T>(key: string): Effect.Effect<T | undefined>;
+    /**
+     * Store an artifact by key in the current resource's bag.
+     */
+    set<T>(key: string, value: T): Effect.Effect<void>;
+    /**
+     * Delete an artifact by key from the current resource's bag.
+     */
+    delete(key: string): Effect.Effect<void>;
+  }
+>()("Artifacts") {}
+
+type ArtifactBag = Map<string, unknown>;
+
+export class ArtifactStore extends ServiceMap.Service<
+  ArtifactStore,
+  Map<string, ArtifactBag>
+>()("Artifacts/Store") {}
+
+/**
+ * Create a fresh root store for one deploy/test run.
+ */
+export const createArtifactStore = (): ArtifactStore["Service"] =>
+  new Map<string, ArtifactBag>();
+
+const getOrCreateBag = (
+  store: Map<string, ArtifactBag>,
+  fqn: string,
+): ArtifactBag => {
+  const existing = store.get(fqn);
+  if (existing) {
+    return existing;
+  }
+  const bag = new Map<string, unknown>();
+  store.set(fqn, bag);
+  return bag;
+};
+
+export const makeScopedArtifacts = (
+  store: Map<string, ArtifactBag>,
+  fqn: string,
+): typeof Artifacts.Service => {
+  const bag = getOrCreateBag(store, fqn);
+  return {
+    get: <T>(key: string) => Effect.sync(() => bag.get(key) as T | undefined),
+    set: <T>(key: string, value: T) =>
+      Effect.sync(() => {
+        bag.set(key, value);
+      }),
+    delete: (key: string) =>
+      Effect.sync(() => {
+        bag.delete(key);
+      }),
+  };
+};
+
+export const scopedArtifacts = (
+  fqn: string,
+): Layer.Layer<Artifacts, never, ArtifactStore> =>
+  Layer.effect(
+    Artifacts,
+    ArtifactStore.asEffect().pipe(
+      Effect.map((store) => makeScopedArtifacts(store, fqn)),
+    ),
+  );
+
+/**
+ * Run an effect with a fresh artifact root, replacing any existing store.
+ * Use this at top-level entrypoints that intentionally define a new deploy run.
+ */
+export const provideFreshArtifactStore = <A, E, R>(
+  effect: Effect.Effect<A, E, R | ArtifactStore>,
+): Effect.Effect<A, E, R> =>
+  effect.pipe(
+    Effect.provideServiceEffect(
+      ArtifactStore,
+      Effect.sync(createArtifactStore),
+    ),
+  );
+
+/**
+ * Ensure an artifact root exists, reusing the ambient store when one is already
+ * present. This lets nested helpers participate in the same run-scoped cache.
+ */
+export const ensureArtifactStore = <A, E, R>(
+  effect: Effect.Effect<A, E, R | ArtifactStore>,
+): Effect.Effect<A, E, R> =>
+  Effect.serviceOption(ArtifactStore).pipe(
+    Effect.map(Option.getOrUndefined),
+    Effect.flatMap((existing) =>
+      effect.pipe(
+        Effect.provideService(ArtifactStore, existing ?? createArtifactStore()),
+      ),
+    ),
+  );
+
+export const cached =
+  (id: string) =>
+  <A, Err = never, Req = never>(eff: Effect.Effect<A, Err, Req>) =>
+    Effect.gen(function* () {
+      const artifacts = yield* Artifacts;
+      const cached = yield* artifacts.get<A>(id);
+      if (cached) {
+        return cached;
+      }
+      const result = yield* eff;
+      yield* artifacts.set(id, result);
+      return result;
+    });

package/src/Build/Command.ts

@@ -5,7 +5,7 @@ import * as Stream from "effect/Stream";
 import { ChildProcess } from "effect/unstable/process";
 import { isResolved } from "../Diff.ts";
 import { Resource } from "../Resource.ts";
-import { sha256, sha256Object } from "../Util/sha256.ts";
+import { hashDirectory, type MemoOptions } from "./Memo.ts";
 
 export interface CommandProps {
   /**
@@ -20,16 +20,13 @@ export interface CommandProps {
    */
   cwd?: string;
   /**
-   * Glob patterns to match input files for hashing.
-   * When the hash of matched files changes, the build will re-run.
-   * @example ["src/*.ts", "src/*.tsx", "package.json"]
+   * 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.
+   *
+   * @see {@link MemoOptions}
    */
-  hash: string[];
-  /**
-   * Glob patterns to exclude from input hashing.
-   * Defaults to node_modules and .git directories.
-   */
-  exclude?: string[];
+  memo?: MemoOptions;
   /**
    * The output path (file or directory) produced by the build.
    * This path is relative to the working directory.
@@ -67,8 +64,7 @@ export interface Command extends Resource<
  * const build = yield* Build("vite-build", {
  *   command: "npm run build",
  *   cwd: "./frontend",
- *   include: ["src/*.ts", "src/*.tsx", "index.html", "package.json", "vite.config.ts"],
- *   output: "dist",
+ *   outdir: "dist",
  * });
  * yield* Console.log(build.path); // absolute path to dist directory
  * yield* Console.log(build.hash); // hash of input files
@@ -80,7 +76,6 @@ export interface Command extends Resource<
  * const build = yield* Build("production-build", {
  *   command: "npm run build",
  *   cwd: "./app",
- *   include: ["src/*", "package.json"],
  *   output: "dist",
  *   env: {
  *     NODE_ENV: "production",
@@ -88,6 +83,16 @@ export interface Command extends Resource<
  *   },
  * });
  * ```
+ *
+ * @section Customizing Memoization
+ * @example Customize Memoization
+ * ```typescript
+ * const build = yield* Build("custom-build", {
+ *   command: "npm run build",
+ *   cwd: "./app",
+ *   output: "dist",
+ *   memo: { include: ["src/*", "package.json"], exclude: ["node_modules", "dist"] },
+ * });
  */
 export const Command = Resource<Command>("Build.Command");
 
@@ -97,26 +102,6 @@ export const CommandProvider = () =>
       const fs = yield* FileSystem.FileSystem;
       const pathModule = yield* Path.Path;
 
-      const computeInputHash = (props: CommandProps) =>
-        Effect.gen(function* () {
-          const cwd = props.cwd ? pathModule.resolve(props.cwd) : process.cwd();
-          const files = yield* listBuildFiles({
-            cwd,
-            include: props.hash,
-            exclude: props.exclude ?? defaultBuildExclude,
-          });
-          const fileHashes = yield* hashBuildFiles({
-            cwd,
-            files,
-          });
-          const hash = yield* sha256Object({
-            command: props.command,
-            env: props.env,
-            files: fileHashes,
-          });
-          return hash;
-        });
-
       const runBuild = (props: CommandProps) =>
         Effect.gen(function* () {
           const cwd = props.cwd ? pathModule.resolve(props.cwd) : process.cwd();
@@ -139,7 +124,7 @@ export const CommandProvider = () =>
           if (!output) {
             return undefined;
           }
-          const newHash = yield* computeInputHash(news);
+          const newHash = yield* hashDirectory(news);
           if (newHash !== output.hash) {
             return { action: "update" as const };
           }
@@ -156,7 +141,7 @@ export const CommandProvider = () =>
           return output;
         }),
         create: Effect.fnUntraced(function* ({ news, session }) {
-          const hash = yield* computeInputHash(news);
+          const hash = yield* hashDirectory(news);
           const outputPath = getOutputPath(news);
 
           yield* session.note(`Running build: ${news.command}`);
@@ -177,7 +162,7 @@ export const CommandProvider = () =>
           };
         }),
         update: Effect.fnUntraced(function* ({ news, session }) {
-          const hash = yield* computeInputHash(news);
+          const hash = yield* hashDirectory(news);
           const outputPath = getOutputPath(news);
 
           yield* session.note(`Rebuilding: ${news.command}`);
@@ -208,69 +193,6 @@ export const CommandProvider = () =>
     }),
   );
 
-export const defaultBuildExclude = ["**/node_modules/**", "**/.git/**"];
-
-export interface BuildFileGlobOptions {
-  cwd: string;
-  include: ReadonlyArray<string>;
-  exclude?: ReadonlyArray<string>;
-}
-
-export const listBuildFiles = Effect.fnUntraced(function* ({
-  cwd,
-  include,
-  exclude = defaultBuildExclude,
-}: BuildFileGlobOptions) {
-  const mod = yield* Effect.promise(() => import("fast-glob"));
-  const fg = mod.default ?? mod;
-  const files = yield* Effect.promise(() =>
-    fg.glob(Array.from(include), {
-      cwd,
-      ignore: Array.from(exclude),
-      onlyFiles: true,
-      dot: true,
-    }),
-  );
-  files.sort();
-  return files.map((file) => file.replaceAll("\\", "/"));
-});
-
-export interface HashBuildFilesOptions {
-  cwd: string;
-  files: ReadonlyArray<string>;
-}
-
-export const hashBuildFiles = Effect.fnUntraced(function* ({
-  cwd,
-  files,
-}: HashBuildFilesOptions) {
-  const fs = yield* FileSystem.FileSystem;
-  const pathModule = yield* Path.Path;
-  const parts = yield* Effect.all(
-    files.map((file) =>
-      fs.readFile(pathModule.join(cwd, file)).pipe(
-        Effect.flatMap((content) =>
-          sha256(content).pipe(Effect.map((hash) => `${file}:${hash}`)),
-        ),
-        Effect.catch(() => Effect.succeed(undefined)),
-      ),
-    ),
-    { concurrency: 10 },
-  );
-  return parts.filter((part): part is string => part !== undefined);
-});
-
-export const hashBuildDirectory = Effect.fnUntraced(function* (
-  directory: string,
-) {
-  const files = yield* listBuildFiles({
-    cwd: directory,
-    include: ["**/*"],
-    exclude: [],
-  });
-  return yield* hashBuildFiles({ cwd: directory, files });
-});
-
 export interface RunBuildCommandOptions {
   command: string;
   cwd?: string;

package/src/Build/Memo.ts

@@ -0,0 +1,187 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+import fg from "fast-glob";
+import { gitignoreRulesToGlobs } from "../Util/gitignore-rules-to-globs.ts";
+import { sha256, sha256Object } from "../Util/sha256.ts";
+
+/**
+ * Controls which files are included in the content hash that determines
+ * whether a build needs to re-run.
+ *
+ * By default (no options), every non-gitignored file in the working directory
+ * is hashed, plus the nearest package-manager lockfile. Provide explicit
+ * `include`/`exclude` globs to narrow the scope when the default is too broad.
+ */
+export interface MemoOptions {
+  /**
+   * Glob patterns of files to hash. Paths are relative to the working directory.
+   *
+   * @default ["**\/*"] (all files, filtered by `exclude`)
+   * @example ["src/**", "package.json", "tsconfig.json"]
+   */
+  include?: string[];
+  /**
+   * Glob patterns to exclude from hashing. Paths are relative to the working directory.
+   *
+   * @default gitignore rules collected from the working directory up to the repo root
+   */
+  exclude?: string[];
+  /**
+   * Whether to include the nearest package-manager lockfile (`bun.lock`,
+   * `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`) in the hash,
+   * even when it lives above the working directory (e.g. monorepo root).
+   *
+   * @default true when both `include` and `exclude` are unset; false otherwise
+   */
+  lockfile?: boolean;
+}
+
+interface ResolvedMemoOptions {
+  cwd: string;
+  include: string[];
+  exclude: string[];
+  lockfile: boolean;
+}
+
+/**
+ * Internal service that resolves memo options, lists matching files, and
+ * produces a single SHA-256 content hash. Constructed as an Effect so it
+ * can access the platform `FileSystem` and `Path` services.
+ */
+const Memo = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+
+  const findUp = Effect.fnUntraced(function* (
+    cwd: string,
+    filenames: string[],
+  ): Effect.fn.Return<string | undefined, PlatformError> {
+    const [file] = yield* Effect.filter(
+      filenames.map((filename) => path.join(cwd, filename)),
+      fs.exists,
+      { concurrency: "unbounded" },
+    );
+    if (file) {
+      return file;
+    }
+    const parent = path.dirname(cwd);
+    if (parent === cwd) {
+      return undefined;
+    }
+    return yield* findUp(parent, filenames);
+  });
+
+  const readGitIgnoreRules = Effect.fnUntraced(function* (
+    cwd: string,
+  ): Effect.fn.Return<string[], PlatformError> {
+    const rules = yield* fs.readFileString(path.join(cwd, ".gitignore")).pipe(
+      Effect.map((file) => file.split("\n")),
+      Effect.catchIf(
+        (error) =>
+          error._tag === "PlatformError" && error.reason._tag === "NotFound",
+        () => Effect.succeed([]),
+      ),
+    );
+    const parent = path.dirname(cwd);
+    if (parent === cwd || (yield* fs.exists(path.join(cwd, ".git")))) {
+      return rules;
+    }
+    return [...(yield* readGitIgnoreRules(parent)), ...rules];
+  });
+
+  const resolveMemoOptions = Effect.fnUntraced(function* (
+    cwd: string | undefined,
+    options: MemoOptions,
+  ): Effect.fn.Return<ResolvedMemoOptions, PlatformError> {
+    const resolvedCwd = cwd ? path.resolve(cwd) : process.cwd();
+    return {
+      cwd: resolvedCwd,
+      include: options.include ?? ["**/*"],
+      exclude:
+        options.exclude ??
+        (yield* readGitIgnoreRules(resolvedCwd).pipe(
+          Effect.map(gitignoreRulesToGlobs),
+          Effect.map((globs) => ["**/.git/**", ...globs]),
+        )),
+      lockfile: options.lockfile ?? !(options.exclude || options.include),
+    };
+  });
+
+  const listFiles = Effect.fnUntraced(function* (
+    options: ResolvedMemoOptions,
+  ): Effect.fn.Return<string[], PlatformError> {
+    const [files, lockfile] = yield* Effect.all(
+      [
+        Effect.promise(() =>
+          fg.glob(options.include, {
+            cwd: options.cwd,
+            ignore: options.exclude,
+            onlyFiles: true,
+            dot: true,
+          }),
+        ),
+        options.lockfile
+          ? findUp(options.cwd, [
+              "bun.lock",
+              "bun.lockb",
+              "package-lock.json",
+              "pnpm-lock.yaml",
+              "yarn.lock",
+            ]).pipe(
+              Effect.map((lockfile) =>
+                lockfile ? path.relative(options.cwd, lockfile) : undefined,
+              ),
+            )
+          : Effect.succeed(undefined),
+      ],
+      { concurrency: "unbounded" },
+    );
+    if (lockfile && !files.includes(lockfile)) {
+      files.push(lockfile);
+    }
+    return files.sort();
+  });
+
+  const hashFiles = Effect.fnUntraced(function* (
+    cwd: string,
+    files: string[],
+  ): Effect.fn.Return<string, PlatformError> {
+    const hashes = yield* Effect.forEach(
+      files,
+      (file) =>
+        fs.readFile(path.join(cwd, file)).pipe(
+          Effect.flatMap(sha256),
+          Effect.map((hash) => `${file}:${hash}`),
+        ),
+      { concurrency: "unbounded" },
+    );
+    return yield* sha256Object(hashes);
+  });
+
+  return {
+    resolveMemoOptions,
+    listFiles,
+    hashFiles,
+  };
+});
+
+/**
+ * Produces a deterministic SHA-256 hash of all files matched by the given
+ * memo options. The hash changes if and only if the content of the matched
+ * files changes, making it suitable for cache-busting build outputs.
+ */
+export const hashDirectory = Effect.fn(function* (props: {
+  cwd?: string;
+  memo?: MemoOptions;
+}): Effect.fn.Return<string, PlatformError, FileSystem.FileSystem | Path.Path> {
+  const service = yield* Memo;
+  const resolvedOptions = yield* service.resolveMemoOptions(
+    props.cwd,
+    props.memo ?? {},
+  );
+  const files = yield* service.listFiles(resolvedOptions);
+  const hash = yield* service.hashFiles(resolvedOptions.cwd, files);
+  return hash;
+});

package/src/Bundle/Bundle.ts

@@ -110,24 +110,9 @@ export const watch = (
         if (result._tag === "Failure") {
           return Result.fail(result.failure);
         }
-        const files = Object.values(result.success);
-        // These are sanity checks - with rolldown, the first file is always an entry chunk.
-        if (!files[0] || files[0].type !== "chunk" || !files[0].isEntry) {
-          return Result.fail(
-            new BundleError({
-              message: "Invalid bundle output",
-            }),
-          );
-        }
-        return yield* Effect.forEach(
-          files as [
-            rolldown.OutputChunk,
-            ...(rolldown.OutputChunk | rolldown.OutputAsset)[],
-          ],
-          bundleFileFromOutputChunk,
-        ).pipe(
-          Effect.flatMap(bundleOutputFromFiles),
+        return yield* bundleOutputFromRolldownOutputBundle(result.success).pipe(
           Effect.map(Result.succeed),
+          Effect.catch((error) => Effect.succeed(Result.fail(error))),
         );
       }),
     ),
@@ -173,6 +158,27 @@ export const virtualEntryPlugin = Effect.gen(function* () {
   };
 });
 
+export function bundleOutputFromRolldownOutputBundle(
+  bundle: rolldown.OutputBundle,
+): Effect.Effect<BundleOutput, BundleError> {
+  const files = Object.values(bundle);
+  // These are sanity checks - with rolldown, the first file is always an entry chunk.
+  if (!files[0] || files[0].type !== "chunk" || !files[0].isEntry) {
+    return Effect.fail(
+      new BundleError({
+        message: "Invalid bundle output",
+      }),
+    );
+  }
+  return Effect.forEach(
+    files as [
+      rolldown.OutputChunk,
+      ...(rolldown.OutputChunk | rolldown.OutputAsset)[],
+    ],
+    bundleFileFromOutputChunk,
+  ).pipe(Effect.flatMap(bundleOutputFromFiles));
+}
+
 function bundleErrorFromUnknown(error: unknown): BundleError {
   const message = error instanceof Error ? error.message : String(error);
   return new BundleError({

package/src/Cloudflare/Website/Vite.ts

@@ -0,0 +1,65 @@
+import type { MemoOptions } from "../../Build/Memo.ts";
+import { Worker, type WorkerProps } from "../Workers/Worker.ts";
+
+export interface ViteProps extends Omit<WorkerProps, "vite" | "main"> {
+  /**
+   * Root directory passed to Vite's `root` option.
+   * Defaults to the current working directory (`process.cwd()`).
+   */
+  rootDir?: string;
+  /**
+   * Controls which files are hashed to decide whether a rebuild is needed.
+   * By default every non-gitignored file in `cwd` is hashed, plus the nearest
+   * lockfile. Provide explicit globs to narrow the scope.
+   *
+   * @see {@link MemoOptions}
+   */
+  memo?: MemoOptions;
+}
+
+/**
+ * A Cloudflare Worker deployed from a Vite project.
+ *
+ * `Vite` uses the Cloudflare Vite plugin to build both the server bundle and
+ * client assets in a single `vite build` invocation — no manual `main`
+ * entrypoint, build command, output directory, or Wrangler configuration
+ * required.
+ *
+ * Input files are content-hashed (respecting `.gitignore` by default) so
+ * unchanged projects skip the build and deploy entirely.
+ *
+ * @section Deploying a Static Site
+ * @example Basic Static Site
+ * ```typescript
+ * const site = yield* Cloudflare.Vite("Website");
+ * ```
+ *
+ * @section Deploying a TanStack Start App
+ * @example TanStack Start with SSR
+ * ```typescript
+ * const app = yield* Cloudflare.Vite("TanStackStart", {
+ *   compatibility: {
+ *     flags: ["nodejs_compat"],
+ *   },
+ * });
+ * ```
+ *
+ * @section Custom Rebuild Scope
+ * @example Narrow the Memo Scope
+ * ```typescript
+ * const site = yield* Cloudflare.Vite("Docs", {
+ *   memo: {
+ *     include: ["src/**", "content/**", "package.json"],
+ *   },
+ * });
+ * ```
+ */
+export const Vite = (id: string, props: ViteProps = {}) =>
+  Worker(id, {
+    ...props,
+    main: undefined!,
+    vite: {
+      rootDir: props.rootDir,
+      memo: props.memo,
+    },
+  });

package/src/Cloudflare/Website/index.ts

@@ -1,2 +1,2 @@
 export * from "./StaticSite.ts";
-export * from "./TanstackStart.ts";
+export * from "./Vite.ts";

package/src/Cloudflare/Workers/Assets.ts

@@ -7,7 +7,7 @@ import * as Path from "effect/Path";
 import type { PlatformError } from "effect/PlatformError";
 import * as ServiceMap from "effect/ServiceMap";
 import type { ScopedPlanStatusSession } from "../../Cli/Cli.ts";
-import { sha256 } from "../../Util/index.ts";
+import { sha256, sha256Object } from "../../Util/index.ts";
 
 const MAX_ASSET_SIZE = 1024 * 1024 * 25; // 25MB
 const MAX_ASSET_COUNT = 20_000;
@@ -23,6 +23,7 @@ export interface AssetReadResult {
   manifest: Record<string, { hash: string; size: number }>;
   _headers: string | undefined;
   _redirects: string | undefined;
+  hash: string;
 }
 
 export interface AssetsProps {
@@ -190,7 +191,7 @@ export const AssetsProvider = () =>
               });
             }),
           );
-          return {
+          const result = {
             directory: props.directory,
             config: props.config,
             manifest: Object.fromEntries(
@@ -201,6 +202,10 @@ export const AssetsProvider = () =>
             _headers,
             _redirects,
           };
+          return {
+            ...result,
+            hash: yield* sha256Object(result),
+          };
         }),
         upload: Effect.fnUntraced(function* (
           accountId: string,