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

import * as Effect from "effect/Effect";
import { havePropsChanged, isResolved } from "../Diff.ts";
import * as Provider from "../Provider.ts";
import { Resource } from "../Resource.ts";
import { CommandExecutor, type CommandRunProps } from "./Command.ts";
import { hashDirectory, type MemoOptions } from "./Memo.ts";

export interface ExecProps extends CommandRunProps {
  /**
   * Controls which files are hashed to decide whether the command 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 re-run on every deploy.
   *
   * @see {@link MemoOptions}
   * @default true
   */
  memo?: MemoOptions | boolean;
}

export interface Exec extends Resource<
  "Command.Exec",
  ExecProps,
  {
    /**
     * Hash of the input files for this command, if memoization is enabled.
     */
    hash: {
      input: string | undefined;
    };
  }
> {}

/**
 * An `Exec` runs a shell command purely for its side effects — it has no
 * output contract. Unlike `Build`, it does not produce or track an output
 * asset; `reconcile` runs the command and the resource succeeds as long as the
 * command exits with code `0` (a non-zero exit fails with a `CommandError`).
 *
 * Use it for one-off setup steps — running migrations, seeding data, code
 * generation, or any command whose result lives outside Alchemy's state. By
 * default the input files are content-hashed so the command only re-runs when
 * its inputs (or `command`/`cwd`/`env`) change; set `memo: false` to re-run on
 * every deploy.
 *
 * ### Running a Command
 * **Example:** Run a One-Off Command
 * ```typescript
 * yield* Exec("codegen", {
 *   command: "npm run codegen",
 *   cwd: "./packages/api",
 * });
 * ```
 *
 * ### Running with Custom Environment
 * **Example:** Run Database Migrations
 * ```typescript
 * yield* Exec("migrate", {
 *   command: "npm run db:migrate",
 *   env: {
 *     DATABASE_URL: Redacted.make("postgres://..."),
 *   },
 * });
 * ```
 *
 * ### Memoizing Re-Runs
 * **Example:** Only Re-Run When Inputs Change
 * ```typescript
 * yield* Exec("codegen", {
 *   command: "npm run codegen",
 *   memo: { include: ["schema/**"] },
 * });
 * ```
 *
 * ### Bounding Command Runtime
 * **Example:** Time Out a Migration
 * ```typescript
 * yield* Exec("migrate", {
 *   command: "npm run db:migrate",
 *   timeout: "5 minutes",
 * });
 * ```
 *
 * @resource
 */
export const Exec = Resource<Exec>("Command.Exec");

export const ExecProvider = () =>
  Provider.effect(
    Exec,
    Effect.gen(function* () {
      const { run } = yield* CommandExecutor;

      return {
        list: () => Effect.succeed([]),
        diff: Effect.fn(function* ({ olds, news, output }) {
          if (!output || !isResolved(news)) return undefined;

          // Always update if memoization is disabled or input hash is not available.
          if (news.memo === false || !output.hash.input) return { action: "update" };

          // Optimization: short-circuit if props have changed to avoid unnecessary file system operations.
          if (havePropsChanged(olds, news)) return { action: "update" };

          const newHash = yield* hashDirectory({
            cwd: news.cwd,
            memo: news.memo === true ? {} : news.memo,
          });
          return {
            action: newHash === output.hash.input ? "noop" : "update",
          };
        }),
        reconcile: Effect.fn(function* ({ news, session }) {
          yield* run(news, session);
          return {
            hash: {
              input:
                news.memo === false
                  ? undefined
                  : yield* hashDirectory({
                      cwd: news.cwd,
                      memo: news.memo === true ? {} : news.memo,
                    }),
            },
          };
        }),
        delete: () => Effect.void,
      };
    }),
  );