alchemy-effect 0.5.0 → 0.6.2

package/src/Bundle/Bundle.ts

@@ -0,0 +1,215 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import * as Queue from "effect/Queue";
+import * as Result from "effect/Result";
+import * as Stream from "effect/Stream";
+import assert from "node:assert";
+import * as rolldown from "rolldown";
+import { sha256, sha256Object } from "../Util/sha256.ts";
+
+export interface BundleOutput {
+  /**
+   * The files in the bundle.
+   * The first file is the entry.
+   */
+  readonly files: [BundleFile, ...BundleFile[]];
+  /**
+   * The SHA-256 hash of all files in the bundle.
+   */
+  readonly hash: string;
+}
+
+export interface BundleFile {
+  readonly path: string;
+  readonly content: string | Uint8Array<ArrayBufferLike>;
+  readonly hash: string;
+}
+
+export class BundleError extends Data.TaggedError("BundleError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/**
+ * Build a bundle using rolldown from the given input options and output options.
+ * @param inputOptions - The input options for the bundle.
+ * @param outputOptions - The output options for the bundle.
+ * @returns The bundle output.
+ */
+export const build = (
+  inputOptions: rolldown.InputOptions,
+  outputOptions?: rolldown.OutputOptions,
+): Effect.Effect<BundleOutput, BundleError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const bundle = await rolldown.rolldown({
+        ...inputOptions,
+        optimization: inputOptions.optimization ?? {
+          inlineConst: {
+            mode: "smart",
+            pass: 3,
+          },
+        },
+      });
+      const result = await bundle.generate(outputOptions);
+      await bundle.close();
+      return result.output;
+    },
+    catch: bundleErrorFromUnknown,
+  }).pipe(
+    Effect.flatMap(Effect.forEach(bundleFileFromOutputChunk)),
+    Effect.flatMap(bundleOutputFromFiles),
+  );
+
+/**
+ * Watch for changes in the bundle and return a stream of bundle output.
+ * @param inputOptions - The input options for the bundle.
+ * @param outputOptions - The output options for the bundle.
+ * @returns A stream of Result instances containing either the bundle output or an error.
+ */
+export const watch = (
+  inputOptions: rolldown.InputOptions,
+  outputOptions?: rolldown.OutputOptions,
+): Stream.Stream<Result.Result<BundleOutput, BundleError>> =>
+  Stream.callback<Result.Result<rolldown.OutputBundle, BundleError>>((queue) =>
+    Effect.acquireRelease(
+      Effect.sync(() => {
+        const watcher = rolldown.watch({
+          ...inputOptions,
+          plugins: [
+            inputOptions.plugins,
+            // The watcher event listener does not receive the bundle output, so we grab it using a plugin.
+            {
+              name: "alchemy:watch-bundle",
+              generateBundle(_outputOptions, bundle) {
+                Queue.offerUnsafe(queue, Result.succeed(bundle));
+              },
+            },
+          ],
+          output: outputOptions,
+        });
+        watcher.on("event", (event) => {
+          if (event.code === "ERROR") {
+            Queue.offerUnsafe(
+              queue,
+              Result.fail(bundleErrorFromUnknown(event.error)),
+            );
+          } else if (event.code === "BUNDLE_END") {
+            // This must be called to avoid resource leaks.
+            event.result.close().catch(() => {});
+          }
+        });
+        return watcher;
+      }),
+      (watcher) => Effect.promise(() => watcher.close()),
+    ),
+  ).pipe(
+    Stream.mapEffect((result) =>
+      Effect.gen(function* () {
+        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),
+          Effect.map(Result.succeed),
+        );
+      }),
+    ),
+    Stream.changesWith((left, right) => {
+      if (left._tag === "Success" && right._tag === "Success") {
+        return left.success.hash === right.success.hash;
+      }
+      return false;
+    }),
+  );
+
+const ENTRY_MODULE_ID = "virtual:alchemy-entry";
+const ENTRY_MODULE_REGEX = new RegExp(`^${ENTRY_MODULE_ID}$`);
+
+export const virtualEntryPlugin = Effect.gen(function* () {
+  const path = yield* Path.Path;
+  return (content: (importPath: string) => string) => {
+    let importPath: string | undefined;
+    return {
+      name: "alchemy:virtual-entry",
+      options(inputOptions) {
+        assert(
+          typeof inputOptions.input === "string",
+          "input must be a string",
+        );
+        importPath = `./${path.relative(inputOptions.cwd ?? process.cwd(), inputOptions.input)}`;
+        inputOptions.input = ENTRY_MODULE_ID;
+      },
+      resolveId: {
+        filter: { id: ENTRY_MODULE_REGEX },
+        handler() {
+          return { id: ENTRY_MODULE_ID };
+        },
+      },
+      load: {
+        filter: { id: ENTRY_MODULE_REGEX },
+        handler() {
+          assert(importPath !== undefined, "importPath must be defined");
+          return { code: content(importPath), moduleType: "ts" };
+        },
+      },
+    } satisfies rolldown.Plugin;
+  };
+});
+
+function bundleErrorFromUnknown(error: unknown): BundleError {
+  const message = error instanceof Error ? error.message : String(error);
+  return new BundleError({
+    message,
+    cause: error,
+  });
+}
+
+function bundleOutputFromFiles(
+  files: [BundleFile, ...BundleFile[]],
+): Effect.Effect<BundleOutput> {
+  return Effect.map(
+    sha256Object(
+      files.map((file) => ({
+        path: file.path,
+        hash: file.hash,
+      })),
+    ),
+    (hash) => ({ files, hash }),
+  );
+}
+
+function bundleFileFromOutputChunk(
+  chunk: rolldown.OutputChunk | rolldown.OutputAsset,
+): Effect.Effect<BundleFile> {
+  switch (chunk.type) {
+    case "chunk":
+      return Effect.map(sha256(chunk.code), (hash) => ({
+        path: chunk.fileName,
+        content: chunk.code,
+        hash,
+      }));
+    case "asset":
+      return Effect.map(sha256(chunk.source), (hash) => ({
+        path: chunk.fileName,
+        content: chunk.source,
+        hash,
+      }));
+  }
+}

package/src/Bundle/Docker.ts

@@ -0,0 +1,213 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { ChildProcess } from "effect/unstable/process";
+import { exec } from "../Agent/util/exec.ts";
+
+export class DockerCommandError extends Data.TaggedError("DockerCommandError")<{
+  readonly command: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+  readonly message: string;
+}> {}
+
+export interface RegistryAuth {
+  readonly username: string;
+  readonly password: string;
+  /**
+   * Registry host only (no `https://`, no path), e.g. `123456789.dkr.ecr.us-east-1.amazonaws.com`.
+   */
+  readonly server: string;
+}
+
+export interface DockerBuildOptions {
+  /** Image reference passed to `docker build -t`. */
+  readonly tag: string;
+  /** Build context directory (`.` argument to `docker build`). */
+  readonly context: string;
+  readonly platform?: string;
+  readonly target?: string;
+  readonly buildArgs?: Record<string, string>;
+  /** Appended to `docker build` before the final context path. */
+  readonly extraArgs?: ReadonlyArray<string>;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export const materializeDockerfile = Effect.fn(function* (
+  dockerfile: string,
+  dir: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  yield* fs.makeDirectory(dir, { recursive: true });
+  const target = path.join(dir, "Dockerfile");
+  yield* fs.writeFileString(target, dockerfile);
+  return target;
+});
+
+export const writeContextFiles = Effect.fn(function* (
+  dir: string,
+  files: ReadonlyArray<{
+    readonly path: string;
+    readonly content: string | Uint8Array;
+  }>,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  for (const file of files) {
+    const fullPath = path.join(dir, file.path);
+    yield* fs.makeDirectory(path.dirname(fullPath), { recursive: true });
+    if (typeof file.content === "string") {
+      yield* fs.writeFileString(fullPath, file.content);
+    } else {
+      yield* fs.writeFile(fullPath, file.content);
+    }
+  }
+});
+
+const shellQuote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
+
+export const runDockerCommand = Effect.fn(function* (
+  args: ReadonlyArray<string>,
+  options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    /** Passed to the process stdin (e.g. for `docker login --password-stdin`). */
+    stdin?: string;
+  },
+) {
+  const command = `docker ${args.map(shellQuote).join(" ")}`;
+  const shellCommand =
+    options?.stdin === undefined
+      ? command
+      : `printf '%s' "$ALCHEMY_DOCKER_STDIN" | ${command}`;
+  const env = {
+    ...process.env,
+    ...options?.env,
+    ...(options?.stdin === undefined
+      ? {}
+      : { ALCHEMY_DOCKER_STDIN: options.stdin }),
+  };
+  const child = options?.cwd
+    ? ChildProcess.setCwd(
+        ChildProcess.make(shellCommand, [], { shell: true, env }),
+        options.cwd,
+      )
+    : ChildProcess.make(shellCommand, [], { shell: true, env });
+
+  const { stdout, stderr, exitCode } = yield* exec(child).pipe(
+    Effect.catch((e) =>
+      Effect.fail(
+        new DockerCommandError({
+          command,
+          stderr: e instanceof Error ? e.message : String(e),
+          exitCode: 1,
+          message: e instanceof Error ? e.message : String(e),
+        }),
+      ),
+    ),
+  );
+
+  if (exitCode !== 0) {
+    return yield* Effect.fail(
+      new DockerCommandError({
+        command,
+        stderr,
+        exitCode,
+        message:
+          `Docker command failed (${exitCode}): ${command}\n${stderr}`.trim(),
+      }),
+    );
+  }
+
+  return { stdout, stderr };
+});
+
+/**
+ * Run `docker build` with standard flags from {@link DockerBuildOptions}.
+ */
+export const dockerBuild = Effect.fn(function* (options: DockerBuildOptions) {
+  const args: string[] = ["build", "-t", options.tag];
+  if (options.platform) {
+    args.push("--platform", options.platform);
+  }
+  if (options.target) {
+    args.push("--target", options.target);
+  }
+  if (options.buildArgs) {
+    for (const [k, v] of Object.entries(options.buildArgs)) {
+      args.push("--build-arg", `${k}=${v}`);
+    }
+  }
+  if (options.extraArgs?.length) {
+    args.push(...options.extraArgs);
+  }
+  args.push(options.context);
+
+  yield* runDockerCommand(args, { env: options.env });
+});
+
+/**
+ * Get the image ID (content-addressable digest) of a locally-built image.
+ */
+export const getDockerImageId = Effect.fn(function* (tag: string) {
+  const { stdout } = yield* runDockerCommand([
+    "inspect",
+    "--format",
+    "{{.Id}}",
+    tag,
+  ]);
+  return stdout.trim();
+});
+
+/**
+ * Tag a local image with a new reference.
+ */
+export const dockerTag = Effect.fn(function* (source: string, target: string) {
+  yield* runDockerCommand(["tag", source, target]);
+});
+
+/**
+ * Log in to a registry using `docker login --password-stdin` (no password on argv).
+ */
+export const dockerLogin = Effect.fn(function* (
+  auth: RegistryAuth,
+  options?: { env?: Record<string, string | undefined> },
+) {
+  yield* runDockerCommand(
+    ["login", "-u", auth.username, "--password-stdin", auth.server],
+    {
+      env: options?.env,
+      stdin: auth.password,
+    },
+  );
+});
+
+/**
+ * Push an image ref. When `auth` is set, uses an isolated `DOCKER_CONFIG`
+ * directory so concurrent deploys do not race on global docker credentials.
+ */
+export const pushImage = Effect.fn(function* (
+  imageRef: string,
+  auth?: RegistryAuth,
+) {
+  if (auth) {
+    const fs = yield* FileSystem.FileSystem;
+    const configDir = yield* fs.makeTempDirectory({
+      prefix: "alchemy-docker-",
+    });
+    const env = { ...process.env, DOCKER_CONFIG: configDir };
+    return yield* Effect.gen(function* () {
+      yield* dockerLogin(auth, { env });
+      yield* runDockerCommand(["push", imageRef], { env });
+    }).pipe(
+      Effect.ensuring(
+        fs
+          .remove(configDir, { recursive: true })
+          .pipe(Effect.catch(() => Effect.void)),
+      ),
+    );
+  }
+  yield* runDockerCommand(["push", imageRef]);
+});

package/src/Bundle/TempRoot.ts

@@ -0,0 +1,104 @@
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as crypto from "node:crypto";
+import { Stack } from "../Stack.ts";
+import { Stage } from "../Stage.ts";
+
+/**
+ * Creates a unique bundle staging directory under the nearest package-local
+ * `.alchemy/tmp` root. Each invocation gets its own directory (via a random
+ * nonce) so concurrent bundle operations for the same resource never collide.
+ * Stale directories from previous crashed runs are cleaned up best-effort.
+ */
+export const createTempBundleDir = (
+  entry: string,
+  dotAlchemy: string,
+  id: string,
+) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const stack = yield* Stack;
+    const stage = yield* Stage;
+    const tempRoot = yield* findBundleTempRoot(entry, dotAlchemy);
+    yield* fs.makeDirectory(tempRoot, { recursive: true });
+
+    const nonce = crypto.randomUUID().slice(0, 8);
+    const bundleId = `${stack.name}-${stage}-${id}-${nonce}`;
+    const tempDir = path.join(tempRoot, bundleId);
+    yield* fs.makeDirectory(tempDir, { recursive: true });
+
+    return tempDir;
+  });
+
+/**
+ * Returns a deterministic bundle staging directory without clearing it first.
+ * Useful for Docker build contexts where keeping the directory stable avoids
+ * unnecessary file churn between builds.
+ */
+export const getStableContextDir = (
+  entry: string,
+  dotAlchemy: string,
+  id: string,
+) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const stack = yield* Stack;
+    const stage = yield* Stage;
+    const tempRoot = yield* findBundleTempRoot(entry, dotAlchemy);
+    const bundleId = `${stack.name}-${stage}-${id}`;
+    const tempDir = path.join(tempRoot, bundleId);
+
+    yield* fs.makeDirectory(tempDir, { recursive: true });
+
+    return tempDir;
+  });
+
+/**
+ * Cleans up a bundle's private temp directory.
+ */
+export const cleanupBundleTempDir = (tempDir: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.remove(tempDir, { recursive: true }).pipe(Effect.ignore);
+  });
+
+const findBundleTempRoot = (entry: string, dotAlchemy: string) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+
+    let current = path.dirname(entry);
+    while (true) {
+      // `node_modules` acts as the package/workspace anchor for temp bundles.
+      if (yield* fs.exists(path.join(current, "node_modules"))) {
+        return path.join(current, path.basename(dotAlchemy), "tmp");
+      }
+
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+
+    return path.join(path.dirname(entry), path.basename(dotAlchemy), "tmp");
+  });
+
+export const findCwdForBundle = Effect.fnUntraced(function* (entry: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  let current = path.dirname(entry);
+  while (true) {
+    if (yield* fs.exists(path.join(current, "package.json"))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return process.cwd();
+    }
+    current = parent;
+  }
+});

package/src/Bundle/index.ts

@@ -0,0 +1,3 @@
+export * from "./Bundle.ts";
+export * from "./Docker.ts";
+export * from "./TempRoot.ts";

package/src/Cli/Cli.ts

@@ -0,0 +1,23 @@
+import * as Effect from "effect/Effect";
+import * as ServiceMap from "effect/ServiceMap";
+import type { Plan } from "../Plan.ts";
+import type { ApplyEvent } from "./Event.ts";
+
+export interface PlanStatusSession {
+  emit: (event: ApplyEvent) => Effect.Effect<void>;
+  done: () => Effect.Effect<void>;
+}
+
+export interface ScopedPlanStatusSession extends PlanStatusSession {
+  note: (note: string) => Effect.Effect<void>;
+}
+
+export interface CLIService {
+  approvePlan: <P extends Plan>(plan: P) => Effect.Effect<boolean>;
+  displayPlan: <P extends Plan>(plan: P) => Effect.Effect<void>;
+  startApplySession: <P extends Plan>(
+    plan: P,
+  ) => Effect.Effect<PlanStatusSession>;
+}
+
+export class Cli extends ServiceMap.Service<Cli, CLIService>()("CLI") {}

package/src/Cli/Event.ts

@@ -0,0 +1,32 @@
+export type ApplyStatus =
+  | "attaching"
+  | "post-attach"
+  | "pending"
+  | "pre-creating"
+  | "creating"
+  | "creating replacement"
+  | "created"
+  | "updating"
+  | "updated"
+  | "deleting"
+  | "deleted"
+  | "replacing"
+  | "replaced"
+  | "fail";
+
+export type ApplyEvent = AnnotateEvent | StatusChangeEvent;
+
+export interface AnnotateEvent {
+  kind: "annotate";
+  id: string;
+  message: string;
+}
+
+export interface StatusChangeEvent {
+  kind: "status-change";
+  id: string; // resource id (e.g. "messages", "api")
+  type: string; // resource type (e.g. "AWS::Lambda::Function", "Cloudflare::Worker")
+  status: ApplyStatus;
+  message?: string; // optional details
+  bindingId?: string; // if this event is for a binding
+}

package/src/Cli/InkCLI.tsx

@@ -0,0 +1,60 @@
+/** @jsxImportSource react */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { render } from "ink";
+import type { Plan } from "../Plan.ts";
+import { type PlanStatusSession, Cli } from "./Cli.ts";
+import type { ApplyEvent } from "./Event.ts";
+import { ApprovePlan } from "./components/ApprovePlan.tsx";
+import { Plan as PlanComponent } from "./components/Plan.tsx";
+import { PlanProgress } from "./components/PlanProgress.tsx";
+
+export const inkCLI = () =>
+  Layer.succeed(
+    Cli,
+    Cli.of({
+      approvePlan,
+      displayPlan,
+      startApplySession,
+    }),
+  );
+
+const approvePlan = Effect.fn(function* <P extends Plan>(plan: P) {
+  let approved = false;
+  const { waitUntilExit } = render(
+    <ApprovePlan plan={plan} approve={(a) => (approved = a)} />,
+  );
+  yield* Effect.promise(waitUntilExit);
+  return approved;
+});
+
+const displayPlan = <P extends Plan>(plan: P): Effect.Effect<void> =>
+  Effect.sync(() => {
+    const { unmount } = render(<PlanComponent plan={plan} />);
+    unmount();
+  });
+
+const startApplySession = Effect.fn(function* <P extends Plan>(plan: P) {
+  const listeners = new Set<(event: ApplyEvent) => void>();
+  const { unmount } = render(
+    <PlanProgress
+      plan={plan}
+      source={{
+        subscribe(listener) {
+          listeners.add(listener);
+          return () => listeners.delete(listener);
+        },
+      }}
+    />,
+  );
+  return {
+    done: Effect.fn(function* () {
+      yield* Effect.sleep(10); // give the react event loop time to re-render
+      yield* Effect.sync(() => unmount());
+    }),
+    emit: (event) =>
+      Effect.sync(() => {
+        for (const listener of listeners) listener(event);
+      }),
+  } satisfies PlanStatusSession;
+});