sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Command/ Build.ts

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 * as Redacted from "effect/Redacted";
import { havePropsChanged, isResolved } from "../Diff.ts";
import * as Provider from "../Provider.ts";
import { Resource } from "../Resource.ts";
import { initialCwd } from "../Util/Node.ts";
import { sha256Object } from "../Util/sha256.ts";
import {
  CommandExecutor,
  OutputNotFound,
  makeCommandError,
  type CommandRunProps,
} from "./Command.ts";
import { hashDirectory, type MemoOptions } from "./Memo.ts";

export interface BuildProps extends CommandRunProps {
  /**
   * 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 the process's initial working
     * directory (`initialCwd` — captured at startup, immune to transient
     * chdir by tools sharing the process).
     *
     * 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 resolve it against `initialCwd` 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.
 *
 * ### 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 the initial cwd
 * yield* Console.log(build.hash.output); // hash of the output files (when memo is enabled)
 * ```
 *
 * ### 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",
 *   },
 * });
 * ```
 *
 * ### 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"] },
 * });
 * ```
 *
 * @resource
 */
export const Build = Resource<Build>("Command.Build");

/**
 * Resolves `Redacted` env values to their plain string so that a change in a
 * secret's value still busts the memo hash (the hash is one-way, so the secret
 * itself is never recoverable from state). `undefined`-valued entries are
 * dropped (they mean "unset").
 */
const resolveEnv = (env: CommandRunProps["env"]) =>
  env
    ? Object.fromEntries(
        Object.entries(env)
          .filter(
            (entry): entry is [string, string | Redacted.Redacted<string>] =>
              entry[1] !== undefined,
          )
          .map(([key, value]) => [key, Redacted.isRedacted(value) ? Redacted.value(value) : value]),
      )
    : undefined;

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) {
        // Anchored to the initial cwd: a live `process.cwd()` read can race
        // a concurrent tool's transient chdir (framework source builds),
        // and the relative `outdir` stored here is resolved again later
        // (assets read) — mismatched bases corrupt the path.
        const cwd = path.resolve(initialCwd, props.cwd ?? ".");
        const outdir = path.resolve(cwd, props.outdir);
        if (!(yield* fs.exists(outdir))) {
          return yield* makeCommandError(
            props,
            new OutputNotFound({
              outdir: props.outdir,
            }),
          );
        }
        return {
          outdir: path.relative(initialCwd, outdir),
          hash:
            props.memo === false
              ? { input: undefined, output: undefined }
              : yield* Effect.all(
                  {
                    // Fold the resolved command + env into the input hash so
                    // two builds that share the same source tree + `outdir`
                    // but differ in their command or environment (e.g.
                    // per-stage builds baking different `EXPO_PUBLIC_*` /
                    // API ids) are never judged reusable. Without this the
                    // second build silently reuses the first's stale output.
                    input: hashDirectory({
                      cwd,
                      memo: props.memo === true ? {} : props.memo,
                    }).pipe(
                      Effect.flatMap((files) =>
                        sha256Object({
                          files,
                          command: props.command,
                          env: resolveEnv(props.env),
                        }),
                      ),
                    ),
                    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 }) {
          // `output.outdir` is persisted relative to the initial cwd.
          const outdir = path.resolve(initialCwd, output.outdir);
          if (!(yield* fs.exists(outdir))) return;
          yield* fs.remove(outdir, { recursive: true });
        }),
      };
    }),
  );