alchemy 0.35.0 → 0.36.0

package/src/docker/image.ts

@@ -0,0 +1,200 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { DockerApi } from "./api.ts";
+
+/**
+ * Options for building a Docker image
+ */
+export interface DockerBuildOptions {
+  /**
+   * Path to the build context directory
+   */
+  context: string;
+
+  /**
+   * Path to the Dockerfile, relative to context
+   */
+  dockerfile?: string;
+
+  /**
+   * Target build platform (e.g., linux/amd64)
+   */
+  platform?: string;
+
+  /**
+   * Build arguments as key-value pairs
+   */
+  buildArgs?: Record<string, string>;
+
+  /**
+   * Target build stage in multi-stage builds
+   */
+  target?: string;
+
+  /**
+   * List of images to use for cache
+   */
+  cacheFrom?: string[];
+}
+
+/**
+ * Properties for creating a Docker image
+ */
+export interface ImageProps {
+  /**
+   * Repository name for the image (e.g., "username/image")
+   */
+  name: string;
+
+  /**
+   * Tag for the image (e.g., "latest")
+   */
+  tag?: string;
+
+  /**
+   * Build configuration
+   */
+  build: DockerBuildOptions;
+
+  /**
+   * Whether to skip pushing the image to registry
+   */
+  skipPush?: boolean;
+}
+
+/**
+ * Docker Image resource
+ */
+export interface Image extends Resource<"docker::Image">, ImageProps {
+  /**
+   * Full image reference (name:tag)
+   */
+  imageRef: string;
+
+  /**
+   * Image ID
+   */
+  imageId?: string;
+
+  /**
+   * Repository digest if pushed
+   */
+  repoDigest?: string;
+
+  /**
+   * Time when the image was built
+   */
+  builtAt: number;
+}
+
+/**
+ * Build and manage a Docker image from a Dockerfile
+ *
+ * @example
+ * // Build a Docker image from a Dockerfile
+ * const appImage = await Image("app-image", {
+ *   name: "myapp",
+ *   tag: "latest",
+ *   build: {
+ *     context: "./app",
+ *     dockerfile: "Dockerfile",
+ *     buildArgs: {
+ *       NODE_ENV: "production"
+ *     }
+ *   }
+ * });
+ */
+export const Image = Resource(
+  "docker::Image",
+  async function (
+    this: Context<Image>,
+    _id: string,
+    props: ImageProps,
+  ): Promise<Image> {
+    // Initialize Docker API client
+    const api = new DockerApi();
+
+    if (this.phase === "delete") {
+      // No action needed for delete as Docker images aren't automatically removed
+      // This is intentional as other resources might depend on the same image
+      return this.destroy();
+    } else {
+      // Normalize properties
+      const tag = props.tag || "latest";
+      const imageRef = `${props.name}:${tag}`;
+
+      // Validate build context
+      const { context } = props.build;
+      await fs.access(context);
+
+      // Determine Dockerfile path
+      const dockerfile = props.build.dockerfile || "Dockerfile";
+      const dockerfilePath = path.join(context, dockerfile);
+      await fs.access(dockerfilePath);
+
+      // Prepare build options
+      const buildOptions: Record<string, string> = props.build.buildArgs || {};
+
+      // Add platform if specified
+      let buildArgs = ["build", "-t", imageRef];
+
+      if (props.build.platform) {
+        buildArgs.push("--platform", props.build.platform);
+      }
+
+      // Add target if specified
+      if (props.build.target) {
+        buildArgs.push("--target", props.build.target);
+      }
+
+      // Add cache sources if specified
+      if (props.build.cacheFrom && props.build.cacheFrom.length > 0) {
+        for (const cacheSource of props.build.cacheFrom) {
+          buildArgs.push("--cache-from", cacheSource);
+        }
+      }
+
+      // Add build arguments
+      for (const [key, value] of Object.entries(buildOptions)) {
+        buildArgs.push("--build-arg", `${key}="${value}"`);
+      }
+
+      // Add dockerfile if not the default
+      if (props.build.dockerfile && props.build.dockerfile !== "Dockerfile") {
+        buildArgs.push("-f", props.build.dockerfile);
+      }
+
+      // Add context path
+      buildArgs.push(props.build.context);
+
+      // Execute build command
+      console.log(`Building Docker image: ${imageRef}`);
+      const { stdout } = await api.exec(buildArgs);
+
+      // Extract image ID from build output if available
+      const imageIdMatch = /Successfully built ([a-f0-9]+)/.exec(stdout);
+      const imageId = imageIdMatch ? imageIdMatch[1] : undefined;
+
+      console.log(`Successfully built Docker image: ${imageRef}`);
+
+      // Handle push if required
+      let repoDigest: string | undefined;
+      if (!props.skipPush) {
+        console.log(`Pushing Docker image: ${imageRef}`);
+        // TODO: Implement push once API supports it
+        console.warn("Image pushing is not yet implemented");
+      }
+
+      // Return the resource using this() to construct output
+      return this({
+        ...props,
+        imageRef,
+        imageId,
+        repoDigest,
+        builtAt: Date.now(),
+      });
+    }
+  },
+);

package/src/docker/index.ts

@@ -0,0 +1,6 @@
+export * from "./api.ts";
+export * from "./remote-image.ts";
+export * from "./container.ts";
+export * from "./network.ts";
+export * from "./volume.ts";
+export * from "./image.ts";

package/src/docker/network.ts

@@ -0,0 +1,101 @@
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { DockerApi } from "./api.ts";
+
+/**
+ * Properties for creating a Docker network
+ */
+export interface NetworkProps {
+  /**
+   * Network name
+   */
+  name: string;
+
+  /**
+   * Network driver to use
+   * @default "bridge"
+   */
+  driver?: "bridge" | "host" | "none" | "overlay" | "macvlan" | (string & {});
+
+  /**
+   * Enable IPv6 on the network
+   * @default false
+   */
+  enableIPv6?: boolean;
+
+  /**
+   * Network-scoped alias for containers
+   */
+  labels?: Record<string, string>;
+}
+
+/**
+ * Docker Network resource
+ */
+export interface Network extends Resource<"docker::Network">, NetworkProps {
+  /**
+   * Network ID
+   */
+  id: string;
+
+  /**
+   * Time when the network was created
+   */
+  createdAt: number;
+}
+
+/**
+ * Create and manage a Docker Network
+ *
+ * @see https://docs.docker.com/engine/network/
+ *
+ * @example
+ * // Create a simple bridge network
+ * const appNetwork = await Network("app-network", {
+ *   name: "app-network"
+ * });
+ *
+ * @example
+ * // Create a custom network with driver
+ * const overlayNetwork = await Network("overlay-network", {
+ *   name: "overlay-network",
+ *   driver: "overlay",
+ *   enableIPv6: true,
+ *   labels: {
+ *     "com.example.description": "Network for application services"
+ *   }
+ * });
+ */
+export const Network = Resource(
+  "docker::Network",
+  async function (
+    this: Context<Network>,
+    _id: string,
+    props: NetworkProps,
+  ): Promise<Network> {
+    // Initialize Docker API client
+    const api = new DockerApi();
+
+    // Handle delete phase
+    if (this.phase === "delete") {
+      if (this.output?.id) {
+        // Remove network
+        await api.removeNetwork(this.output.id);
+      }
+
+      // Return destroyed state
+      return this.destroy();
+    } else {
+      // Create the network
+      props.driver = props.driver || "bridge";
+      const networkId = await api.createNetwork(props.name, props.driver);
+
+      // Return the resource using this() to construct output
+      return this({
+        ...props,
+        id: networkId,
+        createdAt: Date.now(),
+      });
+    }
+  },
+);

package/src/docker/remote-image.ts

@@ -0,0 +1,83 @@
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { DockerApi } from "./api.ts";
+
+/**
+ * Properties for creating a Docker image
+ */
+export interface RemoteImageProps {
+  /**
+   * Docker image name (e.g., "nginx")
+   */
+  name: string;
+
+  /**
+   * Tag for the image (e.g., "latest" or "1.19-alpine")
+   */
+  tag?: string;
+
+  /**
+   * Always attempt to pull the image, even if it exists locally
+   */
+  alwaysPull?: boolean;
+}
+
+/**
+ * Docker Remote Image resource
+ */
+export interface RemoteImage
+  extends Resource<"docker::RemoteImage">,
+    RemoteImageProps {
+  /**
+   * Full image reference (name:tag)
+   */
+  imageRef: string;
+
+  /**
+   * Time when the image was created or pulled
+   */
+  createdAt: number;
+}
+
+/**
+ * Create or reference a Docker Remote Image
+ *
+ * @example
+ * // Pull the nginx image
+ * const nginxImage = await RemoteImage("nginx", {
+ *   name: "nginx",
+ *   tag: "latest"
+ * });
+ *
+ */
+export const RemoteImage = Resource(
+  "docker::RemoteImage",
+  async function (
+    this: Context<RemoteImage>,
+    _id: string,
+    props: RemoteImageProps,
+  ): Promise<RemoteImage> {
+    // Initialize Docker API client
+    const api = new DockerApi();
+
+    if (this.phase === "delete") {
+      // No action needed for delete as Docker images aren't automatically removed
+      // This is intentional as other resources might depend on the same image
+      return this.destroy();
+    } else {
+      // Normalize properties
+      const tag = props.tag || "latest";
+      const imageRef = `${props.name}:${tag}`;
+
+      // Pull image
+      await api.pullImage(imageRef);
+
+      // Return the resource using this() to construct output
+      return this({
+        ...props,
+        imageRef,
+        createdAt: Date.now(),
+      });
+    }
+  },
+);

package/src/docker/volume.ts

@@ -0,0 +1,154 @@
+import type { Context } from "../context.ts";
+import { Resource } from "../resource.ts";
+import { DockerApi } from "./api.ts";
+
+/**
+ * Interface for volume label
+ */
+export interface VolumeLabel {
+  /**
+   * Label name
+   */
+  name: string;
+
+  /**
+   * Label value
+   */
+  value: string;
+}
+
+/**
+ * Properties for creating a Docker volume
+ */
+export interface VolumeProps {
+  /**
+   * Volume name
+   */
+  name: string;
+
+  /**
+   * Volume driver to use
+   * @default "local"
+   */
+  driver?: string;
+
+  /**
+   * Driver-specific options
+   */
+  driverOpts?: Record<string, string>;
+
+  /**
+   * Custom metadata labels for the volume
+   */
+  labels?: VolumeLabel[] | Record<string, string>;
+}
+
+/**
+ * Docker Volume resource
+ */
+export interface Volume extends Resource<"docker::Volume">, VolumeProps {
+  /**
+   * Volume ID (same as name for Docker volumes)
+   */
+  id: string;
+
+  /**
+   * Volume mountpoint path on the host
+   */
+  mountpoint?: string;
+
+  /**
+   * Time when the volume was created
+   */
+  createdAt: number;
+}
+
+/**
+ * Create and manage a Docker Volume
+ *
+ * @see https://docs.docker.com/engine/reference/commandline/volume/
+ *
+ * @example
+ * // Create a simple Docker volume
+ * const dataVolume = await Volume("data-volume", {
+ *   name: "data-volume"
+ * });
+ *
+ * @example
+ * // Create a Docker volume with custom driver and options
+ * const dbVolume = await Volume("db-data", {
+ *   name: "db-data",
+ *   driver: "local",
+ *   driverOpts: {
+ *     "type": "nfs",
+ *     "o": "addr=10.0.0.1,rw",
+ *     "device": ":/path/to/dir"
+ *   },
+ *   labels: [
+ *     { name: "com.example.usage", value: "database-storage" },
+ *     { name: "com.example.backup", value: "weekly" }
+ *   ]
+ * });
+ */
+export const Volume = Resource(
+  "docker::Volume",
+  async function (
+    this: Context<Volume>,
+    _id: string,
+    props: VolumeProps,
+  ): Promise<Volume> {
+    // Initialize Docker API client
+    const api = new DockerApi();
+
+    // Process labels to ensure consistent format
+    const processedLabels: Record<string, string> = {};
+    if (props.labels) {
+      if (Array.isArray(props.labels)) {
+        // Convert array of label objects to Record
+        for (const label of props.labels) {
+          processedLabels[label.name] = label.value;
+        }
+      } else {
+        // Use Record directly
+        Object.assign(processedLabels, props.labels);
+      }
+    }
+
+    // Handle delete phase
+    if (this.phase === "delete") {
+      if (this.output?.name) {
+        // Remove volume
+        await api.removeVolume(this.output.name);
+      }
+
+      // Return destroyed state
+      return this.destroy();
+    } else {
+      // Set default driver if not provided
+      props.driver = props.driver || "local";
+      const driverOpts = props.driverOpts || {};
+
+      // Create the volume
+      const volumeName = await api.createVolume(
+        props.name,
+        props.driver,
+        driverOpts,
+        processedLabels,
+      );
+
+      // Get volume details to retrieve mountpoint
+      const volumeInfos = await api.inspectVolume(volumeName);
+      const mountpoint = volumeInfos[0].Mountpoint;
+
+      // Return the resource using this() to construct output
+      return this({
+        ...props,
+        id: volumeName,
+        mountpoint,
+        createdAt: Date.now(),
+        labels: Array.isArray(props.labels) ? props.labels : undefined,
+        driverOpts: props.driverOpts,
+      });
+    }
+  },
+);

package/src/fs/file-system-state-store.ts

@@ -7,6 +7,7 @@ import { deserializeState, type State, type StateStore } from "../state.ts";
 import { ignore } from "../util/ignore.ts";
 
 const stateRootDir = path.join(process.cwd(), ".alchemy");
+const ALCHEMY_SEPERATOR_CHAR = process.platform === "win32" ? "-" : ":";
 
 export class FileSystemStateStore implements StateStore {
   public readonly dir: string;
@@ -128,7 +129,10 @@ export class FileSystemStateStore implements StateStore {
       throw new Error(`ID cannot include colons: ${key}`);
     }
     if (key.includes("/")) {
-      key = key.replaceAll("/", ":");
+      //todo(michael): remove this next time we do a breaking change
+      //* windows doesn't support ":" in file paths, but we already use ":"
+      //* so now we use both to prevent breaking changes`
+      key = key.replaceAll("/", ALCHEMY_SEPERATOR_CHAR);
     }
     return path.join(this.dir, `${key}.json`);
   }

package/src/fs/file.ts

@@ -184,9 +184,12 @@ export const File = Resource(
     }
 
     // Create directory and write file
-    await fs.promises.mkdir(path.dirname(filePath), {
-      recursive: true,
-    });
+    const dirName = path.dirname(filePath);
+    if (dirName !== ".") {
+      await fs.promises.mkdir(dirName, {
+        recursive: true,
+      });
+    }
 
     await fs.promises.writeFile(filePath, props.content);
 

package/src/os/exec.ts

@@ -266,30 +266,72 @@ const defaultOptions: SpawnOptions = {
   shell: true,
 };
 
+/**
+ * Options for exec function
+ */
+export interface ExecOptions extends Partial<SpawnOptions> {
+  /**
+   * Whether to capture stdout and stderr
+   * @default false
+   */
+  captureOutput?: boolean;
+}
+
 /**
  * Execute a shell command.
+ *
+ * @param command The command to execute
+ * @param options Options for the command execution
+ * @returns Promise that resolves when the command completes.
+ *          If captureOutput is true, resolves with { stdout, stderr } strings.
  */
 export async function exec(
   command: string,
-  options?: Partial<SpawnOptions>,
-): Promise<void> {
+  options?: ExecOptions,
+): Promise<{ stdout: string; stderr: string } | undefined> {
   const [cmd, ...args] = command.split(/\s+/);
+  const captureOutput = options?.captureOutput === true;
 
   return new Promise((resolve, reject) => {
-    const child = spawn(cmd, args, {
+    // Set stdio to pipe only if we're capturing output
+    const spawnOptions = {
       ...defaultOptions,
       ...options,
       env: {
         ...defaultOptions.env,
         ...options?.env,
       },
-    });
+      stdio: captureOutput ? "pipe" : defaultOptions.stdio,
+    };
+
+    const child = spawn(cmd, args, spawnOptions);
+
+    let stdout = "";
+    let stderr = "";
+
+    if (captureOutput) {
+      child.stdout?.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      child.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+    }
 
     child.on("close", (code) => {
       if (code === 0) {
-        resolve();
+        if (captureOutput) {
+          resolve({ stdout, stderr });
+        } else {
+          resolve(undefined);
+        }
       } else {
-        reject(new Error(`Command failed with exit code ${code}`));
+        reject(
+          new Error(
+            `Command failed with exit code ${code}${stderr ? `: ${stderr}` : ""}`,
+          ),
+        );
       }
     });
 

package/src/util/cli.ts

@@ -17,9 +17,7 @@ type ColorName = keyof typeof colors;
 
 // Check if colors should be disabled
 const shouldDisableColors = (): boolean => {
-  return Boolean(
-    process.env.CI || process.env.NO_COLOR || !process.stdout.isTTY,
-  );
+  return Boolean(process.env.NO_COLOR);
 };
 
 // Apply color if colors are enabled