@alchemy.run/docker 0.0.0 → 2.0.0-beta.85

package/src/Docker.ts

@@ -0,0 +1,1173 @@
+import { createPhysicalName } from "alchemy/PhysicalName";
+import type { ScopedPlanStatusSession } from "alchemy/Report";
+import * as Config from "effect/Config";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import { Base64 } from "effect/encoding";
+import * as FileSystem from "effect/FileSystem";
+import { flow } from "effect/Function";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { PlatformError, SystemError, type SystemErrorTag } from "effect/PlatformError";
+import * as ChildProcess from "effect/process/ChildProcess";
+import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
+import * as Redacted from "effect/Redacted";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { classifyDockerRegistryError, type DockerImagePublicationError } from "./RegistryError.ts";
+
+/** Credentials for a single image registry, scoped to a Docker command. */
+export interface RegistryCredentials {
+  /** Registry hostname, without a URL scheme. */
+  server: string;
+  /** Registry authentication username. */
+  username: string;
+  /** Registry password or access token. */
+  password: string | Redacted.Redacted<string>;
+}
+
+const RegistryAuth = Schema.String.pipe(
+  Schema.check(
+    Schema.makeFilter((value) => {
+      const decoded = Base64.decode(value);
+      return Result.isSuccess(decoded) && decoded.success.indexOf(58) > 0;
+    }),
+  ),
+);
+
+const decodeRegistryAuthConfig = Schema.Struct({
+  auths: Schema.Record(Schema.String, Schema.Struct({ auth: RegistryAuth })).pipe(
+    Schema.NullOr,
+    Schema.optional,
+  ),
+}).pipe(Schema.fromJsonString, (schema) =>
+  Schema.decodeEffect(schema, { onExcessProperty: "error" }),
+);
+
+export class Docker extends Context.Service<
+  Docker,
+  {
+    /** Runs a Docker command and returns the output. Use this to run a command that doesn't have a dedicated method. */
+    readonly run: (args: Array<string>) => Effect.Effect<CommandOutput, PlatformError>;
+    /** Writes build files and an inline Dockerfile to the given context directory. */
+    readonly materialize: (options: {
+      context: string;
+      dockerfile: string;
+      files: ReadonlyArray<{ path: string; content: string | Uint8Array }>;
+    }) => Effect.Effect<void, PlatformError>;
+    readonly container: {
+      /** Creates a new container. */
+      readonly create: (options: {
+        name: string;
+        image: string;
+        volume: Array<string> | undefined;
+        env: Record<string, string> | undefined;
+        /** Paths to Docker env files, forwarded as repeated `--env-file`. */
+        "env-file"?: Array<string> | undefined;
+        restart: "no" | "always" | "on-failure" | "unless-stopped";
+        rm: boolean;
+        "health-cmd": string | undefined;
+        /** `--no-healthcheck`: disable any healthcheck defined by the image. */
+        "no-healthcheck"?: boolean;
+        "health-interval": string | undefined;
+        "health-timeout": string | undefined;
+        "health-retries": number | undefined;
+        "health-start-period": string | undefined;
+        "health-start-interval": string | undefined;
+        "stop-timeout": string | undefined;
+        p: Array<string> | undefined;
+        /** `--add-host` entries, each `hostname:address`. */
+        "add-host"?: Array<string> | undefined;
+        /** Docker network namespace, including `container:<id>`. */
+        network?: string | undefined;
+        /** Linux capabilities to add. */
+        "cap-add"?: Array<string> | undefined;
+        /** Linux capabilities to drop. */
+        "cap-drop"?: Array<string> | undefined;
+        /** Hard memory limit in Docker's byte-suffix format. */
+        memory?: string | undefined;
+        /** Combined memory-and-swap limit in Docker's byte-suffix format. */
+        "memory-swap"?: string | undefined;
+        /** Soft memory reservation for memory contention. */
+        "memory-reservation"?: string | undefined;
+        /** CPU quota, in cores. */
+        cpus?: number | undefined;
+        /** Per-container process and thread limit. */
+        "pids-limit"?: number | undefined;
+        /** Mount the root filesystem read-only. */
+        "read-only"?: boolean | undefined;
+        /** Security options such as `no-new-privileges` and seccomp/AppArmor profiles. */
+        "security-opt"?: Array<string> | undefined;
+        /** Per-container user namespace; "host" disables daemon user remapping. */
+        userns?: string | undefined;
+        /** Supplemental Linux groups. */
+        "group-add"?: Array<string> | undefined;
+        /** Per-process soft/hard resource limits. */
+        ulimit?: Array<string> | undefined;
+        /** Docker log driver. */
+        "log-driver"?: string | undefined;
+        /** Driver-specific Docker logging options. */
+        "log-opt"?: Array<string> | undefined;
+        /** Kernel OOM score adjustment. */
+        "oom-score-adj"?: number | undefined;
+        /** Signal used on container stop. */
+        "stop-signal"?: string | undefined;
+        /** Run Docker's tiny init process. */
+        init?: boolean | undefined;
+        /** Runtime UID/GID or named user. */
+        user?: string | undefined;
+        /** Docker tmpfs mount expressions (target[:options]). */
+        tmpfs?: Array<string> | undefined;
+        /** Host devices in Docker's `host:container[:permissions]` form. */
+        device?: Array<string> | undefined;
+        command: Array<string> | undefined;
+        label?: Record<string, string>;
+        context?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Inspects a container. */
+      readonly inspect: (
+        name: string,
+        context?: string,
+      ) => Effect.Effect<Docker.Container, PlatformError>;
+      /** Removes a container. */
+      readonly remove: (
+        name: string,
+        force?: boolean,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Starts a container. */
+      readonly start: (
+        name: string,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Stops a container. */
+      readonly stop: (
+        name: string,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+    };
+    readonly image: {
+      /**
+       * Builds locally, or publishes to a registry when credentials are
+       * supplied. With Buildx 0.26.0 or newer the image is exported straight
+       * from BuildKit (`buildx build --push`); older plugins build into the
+       * local image store and then `push`. If a session is provided, build
+       * logs will be emitted as session notes.
+       */
+      readonly build: (
+        options: {
+          context: string;
+          /** Image tags to build and publish together. */
+          tag: string | [string, ...string[]];
+          file?: string;
+          platform?: string;
+          target?: string;
+          "build-arg"?: Record<string, string>;
+          /**
+           * BuildKit secrets, keyed by id (`RUN --mount=type=secret,id=<id>`).
+           * Values reach `docker` through its environment, never its argv,
+           * and are not written to the image.
+           */
+          secrets?: Record<string, string | Redacted.Redacted<string>>;
+          "cache-from"?: Array<string>;
+          "cache-to"?: Array<string>;
+          args?: Array<string>;
+          engineContext?: string;
+          /** Registry auth for the build itself (base images, caches); publishes nothing. */
+          credentials?: RegistryCredentials;
+        },
+        session?: ScopedPlanStatusSession,
+        registry?: RegistryCredentials,
+      ) => Effect.Effect<CommandOutput, DockerImagePublicationError>;
+      /** Pulls an image. */
+      readonly pull: (
+        ref: string,
+        platform?: string,
+        context?: string,
+        session?: Pick<ScopedPlanStatusSession, "note">,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+      /**
+       * Pushes an image to a registry. When `platform` is given, only that
+       * platform's manifest is pushed (`docker push --platform`) — with the
+       * containerd image store, a bare push sends every locally-present
+       * variant of a multi-arch tag, so a stale other-arch variant in the
+       * local cache would otherwise reach the registry. Engines whose store
+       * doesn't support the flag fall back to a plain push (their local tag
+       * is already narrowed by `pull --platform`).
+       */
+      readonly push: (
+        ref: string,
+        credentials: RegistryCredentials,
+        platform?: string,
+        context?: string,
+        session?: Pick<ScopedPlanStatusSession, "note">,
+      ) => Effect.Effect<CommandOutput, DockerImagePublicationError>;
+      /** Tags an image. */
+      readonly tag: (
+        source: string,
+        target: string,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Inspects an image. */
+      readonly inspect: (
+        ref: string,
+        context?: string,
+      ) => Effect.Effect<Docker.Image, PlatformError>;
+      /** Removes an image. */
+      readonly remove: (
+        ref: string | Array<string>,
+        force?: boolean,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+    };
+    readonly volume: {
+      /** Creates a new volume. */
+      readonly create: (options: {
+        name: string;
+        driver?: string;
+        opt?: Record<string, string>;
+        label?: Record<string, string>;
+        context?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Removes a volume. */
+      readonly remove: (
+        name: string,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Inspects a volume. */
+      readonly inspect: (
+        name: string,
+        context?: string,
+      ) => Effect.Effect<Docker.Volume, PlatformError>;
+    };
+    readonly context: {
+      /** Creates a new Docker context. */
+      readonly create: (options: {
+        name: string;
+        description?: string;
+        /** Raw value for `--docker`, for example `host=ssh://user@host`. */
+        docker?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Updates an existing Docker context. */
+      readonly update: (options: {
+        name: string;
+        description?: string;
+        /** Raw value for `--docker`, for example `host=ssh://user@host`. */
+        docker?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Inspects a Docker context. */
+      readonly inspect: (name: string) => Effect.Effect<Docker.Context, PlatformError>;
+      /** Removes a Docker context. */
+      readonly remove: (
+        name: string,
+        force?: boolean,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+    };
+    readonly network: {
+      /** Creates a new network. */
+      readonly create: (options: {
+        name: string;
+        driver: string;
+        ipv6?: boolean;
+        label?: Record<string, string>;
+        context?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Connects a container to a network. */
+      readonly connect: (options: {
+        network: string;
+        container: string;
+        alias?: string[];
+        context?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Disconnects a container from a network. */
+      readonly disconnect: (options: {
+        network: string;
+        container: string;
+        context?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Inspects a network. */
+      readonly inspect: (
+        name: string,
+        context?: string,
+      ) => Effect.Effect<Docker.Network, PlatformError>;
+      /** Removes a network. */
+      readonly remove: (
+        id: string,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+    };
+    readonly swarm: {
+      /** Initializes swarm mode on the engine (`docker swarm init`). */
+      readonly init: (options: {
+        context?: string;
+        "advertise-addr"?: string;
+        "listen-addr"?: string;
+        "default-addr-pool"?: string[];
+        "default-addr-pool-mask-length"?: number;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Reads the engine's swarm state (`docker info --format '{{json .Swarm}}'`). */
+      readonly info: (context?: string) => Effect.Effect<Docker.SwarmInfo, PlatformError>;
+      /** Leaves the swarm (`docker swarm leave`). */
+      readonly leave: (
+        force?: boolean,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+    };
+    readonly service: {
+      /** Creates a new service. */
+      readonly create: (options: {
+        name: string;
+        image: string;
+        context?: string;
+        replicas?: number;
+        "endpoint-mode"?: "vip" | "dnsrr";
+        network?: string[];
+        constraint?: string[];
+        "replicas-max-per-node"?: number;
+        "placement-pref"?: string[];
+        "update-parallelism"?: number;
+        "update-delay"?: string;
+        "update-monitor"?: string;
+        "update-failure-action"?: "pause" | "continue" | "rollback";
+        "update-max-failure-ratio"?: number;
+        "update-order"?: "stop-first" | "start-first";
+        "rollback-parallelism"?: number;
+        "rollback-delay"?: string;
+        "rollback-monitor"?: string;
+        "rollback-failure-action"?: "pause" | "continue" | "rollback";
+        "rollback-max-failure-ratio"?: number;
+        "rollback-order"?: "stop-first" | "start-first";
+        "restart-condition"?: "none" | "on-failure" | "any";
+        "restart-delay"?: string;
+        "restart-max-attempts"?: number;
+        "restart-window"?: string;
+        "health-cmd"?: string;
+        /** `--no-healthcheck`: disable any healthcheck defined by the image. */
+        "no-healthcheck"?: boolean;
+        "health-interval"?: string;
+        "health-timeout"?: string;
+        "health-retries"?: number;
+        "health-start-period"?: string;
+        "stop-grace-period"?: string;
+        mount?: string[];
+        secret?: string[];
+        config?: string[];
+        "read-only"?: boolean;
+        publish?: string[];
+        label?: Record<string, string>;
+        env?: Record<string, string>;
+        command?: string[];
+        args?: string[];
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Updates an existing service. */
+      readonly update: (options: {
+        id: string;
+        image: string;
+        context?: string;
+        replicas?: number;
+        "endpoint-mode"?: "vip" | "dnsrr";
+        /** Networks to detach, by name or id; applied before `network-add`. */
+        "network-rm"?: string[];
+        "network-add"?: string[];
+        "constraint-add"?: string[];
+        "constraint-rm"?: string[];
+        "replicas-max-per-node"?: number;
+        "update-parallelism"?: number;
+        "update-delay"?: string;
+        "update-monitor"?: string;
+        "update-failure-action"?: "pause" | "continue" | "rollback";
+        "update-max-failure-ratio"?: number;
+        "update-order"?: "stop-first" | "start-first";
+        "rollback-parallelism"?: number;
+        "rollback-delay"?: string;
+        "rollback-monitor"?: string;
+        "rollback-failure-action"?: "pause" | "continue" | "rollback";
+        "rollback-max-failure-ratio"?: number;
+        "rollback-order"?: "stop-first" | "start-first";
+        "restart-condition"?: "none" | "on-failure" | "any";
+        "restart-delay"?: string;
+        "restart-max-attempts"?: number;
+        "restart-window"?: string;
+        "health-cmd"?: string;
+        /** `--no-healthcheck`: disable any healthcheck defined by the image. */
+        "no-healthcheck"?: boolean;
+        "health-interval"?: string;
+        "health-timeout"?: string;
+        "health-retries"?: number;
+        "health-start-period"?: string;
+        "stop-grace-period"?: string;
+        "mount-add"?: string[];
+        /** Mount targets to remove. */
+        "mount-rm"?: string[];
+        "secret-add"?: string[];
+        /** Secret names to remove; applied before `secret-add`. */
+        "secret-rm"?: string[];
+        "config-add"?: string[];
+        /** Config names to remove; applied before `config-add`. */
+        "config-rm"?: string[];
+        "read-only"?: boolean;
+        "publish-add"?: string[];
+        /** Published ports to remove, as `target=<port>,protocol=<p>,mode=<m>`. */
+        "publish-rm"?: string[];
+        "label-add"?: Record<string, string>;
+        "label-rm"?: string[];
+        "env-add"?: Record<string, string>;
+        /** Environment variable names to remove. */
+        "env-rm"?: string[];
+        args?: string;
+      }) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Inspects a service. */
+      readonly inspect: (
+        id: string,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+      /** Removes a service. */
+      readonly remove: (
+        id: string,
+        context?: string,
+      ) => Effect.Effect<CommandOutput, PlatformError>;
+    };
+  }
+>()("@alchemy/Docker") {}
+
+export declare namespace Docker {
+  export type ContextRef = string | { name: string };
+
+  /**
+   * A reference to the Docker engine an operation runs against: a context
+   * name, a `Docker.Context` resource, or a `Docker.Swarm` resource
+   * (narrowed structurally by its `nodeId` attribute) — passing the swarm
+   * also orders the operation after the swarm is initialized.
+   */
+  export type EngineRef = ContextRef | { nodeId: string; context?: string };
+
+  export interface SwarmInfo {
+    NodeID: string;
+    LocalNodeState: "inactive" | "pending" | "active" | "error" | "locked" | (string & {});
+    ControlAvailable: boolean;
+    Cluster?: { ID: string; CreatedAt?: string } | null;
+    RemoteManagers?: Array<{ NodeID: string; Addr: string }> | null;
+    Managers?: number;
+    Nodes?: number;
+  }
+
+  export type ContainerStatus =
+    | "created"
+    | "running"
+    | "paused"
+    | "restarting"
+    | "removing"
+    | "exited"
+    | "dead";
+
+  export interface Container {
+    Id: string;
+    Image: string;
+    Name?: string;
+    State: {
+      Status: ContainerStatus;
+      /** Present when the container has a healthcheck. */
+      Health?: { Status: "starting" | "healthy" | "unhealthy" };
+    };
+    Created: string;
+    Config: {
+      Image: string;
+      Cmd: string[] | null;
+      Env: string[] | null;
+      User?: string;
+      StopSignal?: string;
+      Labels: Record<string, string> | null;
+      StopTimeout?: number;
+      Healthcheck?: {
+        Test: string[] | null;
+        Interval?: number;
+        Timeout?: number;
+        Retries?: number;
+        StartPeriod?: number;
+        StartInterval?: number;
+      } | null;
+    };
+    HostConfig: {
+      PortBindings: Record<string, Array<{ HostIp: string; HostPort: string }> | null> | null;
+      Binds: string[] | null;
+      ExtraHosts: string[] | null;
+      RestartPolicy: { Name: string; MaximumRetryCount: number };
+      AutoRemove: boolean;
+      NetworkMode?: string;
+      CapAdd?: string[] | null;
+      CapDrop?: string[] | null;
+      Memory?: number;
+      MemorySwap?: number;
+      MemoryReservation?: number;
+      NanoCpus?: number;
+      PidsLimit?: number;
+      ReadonlyRootfs?: boolean;
+      SecurityOpt?: string[] | null;
+      UsernsMode?: string;
+      GroupAdd?: string[] | null;
+      Ulimits?: Array<{ Name: string; Soft: number; Hard: number }> | null;
+      LogConfig?: { Type: string; Config: Record<string, string> | null };
+      OomScoreAdj?: number;
+      Init?: boolean | null;
+      Tmpfs?: Record<string, string> | null;
+      Devices?: Array<{
+        PathOnHost: string;
+        PathInContainer: string;
+        CgroupPermissions: string;
+      }> | null;
+    };
+    AppArmorProfile?: string;
+    NetworkSettings: {
+      Networks: Record<string, { NetworkID: string; Aliases: string[] | null }> | null;
+      Ports?: Record<string, Array<{ HostIp: string; HostPort: string }> | null> | null;
+    };
+  }
+
+  export interface Image {
+    Id: string;
+    Created?: string;
+    RepoTags?: string[] | null;
+    RepoDigests?: string[] | null;
+  }
+
+  export interface Volume {
+    CreatedAt: string;
+    Driver: string;
+    Labels: Record<string, string> | null;
+    Mountpoint: string;
+    Name: string;
+    Options: Record<string, string> | null;
+    Scope: string;
+  }
+
+  export interface Context {
+    Name: string;
+    Metadata?: { Description?: string };
+    Endpoints?: { docker?: string };
+  }
+
+  export interface Network {
+    Name: string;
+    Id: string;
+    Created: string;
+    Scope: string;
+    Driver: string;
+    EnableIPv6: boolean;
+    Labels: Record<string, string> | null;
+  }
+}
+
+export interface CommandOutput {
+  exitCode: ChildProcessSpawner.ExitCode;
+  stdout: string;
+  stderr: string;
+}
+
+export interface DockerOptions {
+  /**
+   * The Docker-compatible CLI to run, e.g. `"podman"`. The `DOCKER_BIN`
+   * environment variable, when set, overrides it (per machine or CI).
+   * @default "docker"
+   */
+  bin?: string;
+}
+
+/**
+ * Extra environment for every Docker CLI invocation, layered over the
+ * process environment (per-call variables still win). Scope it with
+ * `Effect.provideService(DockerEnvironment, { BUILDX_BUILDER: "ci" })` to
+ * target a buildx builder or Docker context without mutating `process.env`.
+ * @default {}
+ */
+export const DockerEnvironment = Context.Reference<Record<string, string>>(
+  "alchemy/Docker/DockerEnvironment",
+  { defaultValue: () => ({}) },
+);
+
+/** The Docker CLI client, running `options.bin` (`DOCKER_BIN` overrides). */
+export const dockerLive = (options: DockerOptions = {}) =>
+  Layer.effect(Docker, makeDocker(options));
+
+const makeDocker = (options: DockerOptions) =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const bin = yield* Config.String("DOCKER_BIN").pipe(
+      Effect.orElseSucceed(() => options.bin ?? "docker"),
+    );
+
+    const run = (
+      args: Array<string>,
+      env?: Record<string, string>,
+      tap: (
+        stream: Stream.Stream<string, PlatformError, never>,
+      ) => Stream.Stream<string, PlatformError, never> = Stream.tap(Effect.logDebug),
+    ) =>
+      Effect.gen(function* () {
+        const ambient = yield* DockerEnvironment;
+        return yield* spawner.spawn(
+          ChildProcess.make(bin, args, {
+            stdin: "ignore",
+            stdout: "pipe",
+            stderr: "pipe",
+            detached: false,
+            env: { ...ambient, ...env },
+            extendEnv: true,
+          }),
+        );
+      }).pipe(
+        Effect.flatMap((child) =>
+          Effect.all(
+            {
+              exitCode: child.exitCode,
+              stdout: child.stdout.pipe(
+                Stream.decodeText,
+                tap,
+                Stream.mkString,
+                Effect.map((stdout) => stdout.trim()),
+              ),
+              stderr: child.stderr.pipe(
+                Stream.decodeText,
+                tap,
+                Stream.mkString,
+                Effect.map((stderr) => stderr.trim()),
+              ),
+            },
+            { concurrency: "unbounded" },
+          ),
+        ),
+        Effect.mapError((error) =>
+          systemError({
+            _tag: "Unknown",
+            args,
+            // Name the CLI: a misconfigured `bin` / DOCKER_BIN fails here.
+            description: `Failed to run \`${bin}\`; is it installed and on PATH?`,
+            cause: error.reason,
+          }),
+        ),
+        Effect.tap((result) => {
+          if (result.exitCode === 0) return Effect.void;
+          const stderr = result.stderr.replace(/^Error response from daemon: /, "");
+          if (stderr.match(/not found|not known|no such/i)) {
+            return systemError({ _tag: "NotFound", args, description: stderr });
+          }
+          if (stderr.match(/already exists/i)) {
+            return systemError({ _tag: "AlreadyExists", args, description: stderr });
+          }
+          return systemError({
+            _tag: "Unknown",
+            args,
+            description: `Command exited with code ${result.exitCode}: ${failureOutput(
+              stderr,
+              result.stdout,
+            )}`,
+          });
+        }),
+        Effect.scoped,
+      );
+
+    const runInspect = <T>(args: Array<string>) =>
+      run(args).pipe(
+        Effect.map((result) => {
+          const [item] = JSON.parse(result.stdout) as T[];
+          return item;
+        }),
+      );
+
+    // Merge `credentials` into the ambient auth config: the process's
+    // DOCKER_AUTH_CONFIG, overlaid by one provided through DockerEnvironment
+    // (as `run` layers DockerEnvironment over the process environment).
+    // Merging, not replacing, keeps the user's own registry logins.
+    const registryEnvironment = Effect.fn("registryEnvironment")(
+      (credentials: RegistryCredentials) =>
+        Effect.gen(function* () {
+          const value = yield* Config.Redacted("DOCKER_AUTH_CONFIG").pipe(
+            Config.withDefault(Redacted.make("{}")),
+          );
+          const base = yield* decodeRegistryAuthConfig(Redacted.value(value) || "{}");
+          const ambient = yield* DockerEnvironment;
+          const overlay =
+            ambient.DOCKER_AUTH_CONFIG === undefined
+              ? undefined
+              : yield* decodeRegistryAuthConfig(ambient.DOCKER_AUTH_CONFIG || "{}");
+          return { auths: { ...base.auths, ...overlay?.auths } };
+        }).pipe(
+          // Schema diagnostics may include credential input. Do not retain them.
+          Effect.mapError(() =>
+            systemError({
+              _tag: "InvalidData",
+              args: ["buildx", "build"],
+              description: "Invalid DOCKER_AUTH_CONFIG; expected an auths map.",
+            }),
+          ),
+          Effect.map((current) => {
+            const password = Redacted.isRedacted(credentials.password)
+              ? Redacted.value(credentials.password)
+              : credentials.password;
+            const auth = Base64.encode(`${credentials.username}:${password}`);
+            // Preserve Docker's file/helper fallback, contexts, and builders.
+            return {
+              DOCKER_AUTH_CONFIG: JSON.stringify({
+                auths: { ...current.auths, [credentials.server]: { auth } },
+              }),
+            };
+          }),
+        ),
+    );
+
+    // How a build reaches a registry. Buildx 0.26 is the first release
+    // embedding Docker CLI 28.3's DOCKER_AUTH_CONFIG credential store, so it
+    // can `buildx build --push` straight from BuildKit. Older plugins (e.g.
+    // the buildx bundled with Docker Desktop < 4.44) silently ignore the
+    // variable, so the image is instead `--load`ed into the local store and
+    // published with the isolated-config `push`. Without any buildx plugin
+    // the legacy builder always loads, so a plain `image build` suffices.
+    // Probed once per Docker service instance.
+    const publication = yield* Effect.cached(
+      Effect.gen(function* () {
+        const version = yield* run(["buildx", "version"]).pipe(Effect.option);
+        if (Option.isNone(version)) return "legacy" as const;
+        // Numeric template captures can consume version separators as decimals.
+        const match =
+          /^github\.com\/docker\/buildx v?(\d+)\.(\d+)\.\d+(?:[-+][^\s]+)?(?:\s.*)?$/.exec(
+            version.value.stdout,
+          );
+        if (!match) return "load" as const;
+        const major = Number(match[1]);
+        const minor = Number(match[2]);
+        return major >= 1 || minor >= 26 ? ("export" as const) : ("load" as const);
+      }),
+    );
+
+    const outputTap = (session?: Pick<ScopedPlanStatusSession, "note">) =>
+      session
+        ? Stream.tapSink(
+            Sink.make<string>()(
+              flow(
+                Stream.splitLines,
+                Stream.runForEach((line) => session.note(line, { kind: "output" })),
+              ),
+            ),
+          )
+        : undefined;
+
+    // `podman push` prints no `digest:` line, and Podman's RepoDigests can
+    // list a source digest under the pushed name, so Podman pushes report the
+    // published digest through `--digestfile` instead. Probed once.
+    const isPodman = yield* Effect.cached(
+      run(["--version"]).pipe(
+        Effect.map((result) => /^podman\b/i.test(result.stdout.trim())),
+        Effect.orElseSucceed(() => false),
+      ),
+    );
+
+    const push: Docker["Service"]["image"]["push"] = Effect.fn(
+      function* (ref, credentials, platform, context, session) {
+        // Write the registry credentials directly into an isolated docker config
+        // as a plaintext `auths` entry and skip `docker login` entirely.
+        //
+        // `docker login` is the wrong tool here: on macOS Docker Desktop it routes
+        // through the shared `osxkeychain`/`desktop` credential helper *regardless*
+        // of an isolated DOCKER_CONFIG, so concurrent deploys either race the system
+        // keychain (`The specified item already exists in the keychain (-25299)`) or
+        // land the credential in the helper — leaving this isolated config without
+        // an `auths` entry, so the subsequent `docker push` fails with "no basic
+        // auth credentials". Embedding the base64 `auth` inline (the same thing
+        // `docker login` would write when no credsStore is configured) makes each
+        // deploy fully self-contained: no credential helper, no keychain, no login
+        // race. Only `push` reads this config; `build`/`pull`/`tag` keep using the
+        // global docker config (buildx builders, `docker context`, etc. intact).
+        const dir = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-" });
+        // The isolated DOCKER_CONFIG holds none of the CLI's contexts. Ask the CLI
+        // (same environment as the push) which context it would use, and copy just
+        // that context's metadata and TLS material in.
+        const selected =
+          context ??
+          (yield* run(["context", "show"]).pipe(
+            Effect.map((result) => result.stdout),
+            Effect.orElseSucceed(() => "default"),
+          ));
+        if (selected && selected !== "default") {
+          const inspected = yield* runInspect<{
+            Storage: { MetadataPath: string; TLSPath: string };
+          }>(["context", "inspect", selected]);
+          for (const [kind, source] of [
+            ["meta", inspected.Storage.MetadataPath],
+            ["tls", inspected.Storage.TLSPath],
+          ] as const) {
+            if (!(yield* fs.exists(source))) continue;
+            const target = path.join(dir, "contexts", kind, path.basename(source));
+            yield* fs.makeDirectory(path.dirname(target), { recursive: true });
+            yield* fs.copy(source, target);
+          }
+        }
+        const pushContext = selected && selected !== "default" ? selected : context;
+        const config = yield* Effect.sync(() => {
+          const password = Redacted.isRedacted(credentials.password)
+            ? Redacted.value(credentials.password)
+            : credentials.password;
+          const auth = Buffer.from(`${credentials.username}:${password}`).toString("base64");
+          return JSON.stringify({ auths: { [credentials.server]: { auth } } });
+        });
+        yield* fs.writeFileString(path.join(dir, "config.json"), config);
+        const digestFile = path.join(dir, "digest");
+        const digestArgs = (yield* isPodman) ? ["--digestfile", digestFile] : [];
+        const result =
+          platform === undefined
+            ? yield* run(
+                [...formatArgs({ context: pushContext }), "push", ...digestArgs, ref],
+                { DOCKER_CONFIG: dir },
+                outputTap(session),
+              )
+            : yield* run(
+                [
+                  ...formatArgs({ context: pushContext }),
+                  "push",
+                  "--platform",
+                  platform,
+                  ...digestArgs,
+                  ref,
+                ],
+                { DOCKER_CONFIG: dir },
+                outputTap(session),
+              ).pipe(
+                // Engines without the containerd image store reject `--platform`
+                // on push; their local tag is already narrowed to the requested
+                // platform by `pull --platform`, so a plain push is equivalent.
+                Effect.catchIf(
+                  (error) => /--platform|unknown flag|containerd/i.test(String(error)),
+                  () =>
+                    run(
+                      [...formatArgs({ context: pushContext }), "push", ...digestArgs, ref],
+                      { DOCKER_CONFIG: dir },
+                      outputTap(session),
+                    ),
+                ),
+              );
+        if (digestArgs.length === 0) return result;
+        const digest = (yield* fs
+          .readFileString(digestFile)
+          .pipe(Effect.orElseSucceed(() => ""))).trim();
+        // Report it the way `docker push` does, so callers parse one format.
+        return digest ? { ...result, stdout: `${result.stdout}\ndigest: ${digest}` } : result;
+      },
+      Effect.scoped,
+      Effect.mapError(classifyDockerRegistryError),
+    );
+
+    return Docker.of({
+      run,
+      materialize: Effect.fn((options) =>
+        Effect.forEach(
+          [...options.files, { path: "Dockerfile", content: options.dockerfile }],
+          (file) => {
+            const fullPath = path.join(options.context, file.path);
+            return fs
+              .makeDirectory(path.dirname(fullPath), { recursive: true })
+              .pipe(
+                Effect.andThen(
+                  typeof file.content === "string"
+                    ? fs.writeFileString(fullPath, file.content)
+                    : fs.writeFile(fullPath, file.content),
+                ),
+              );
+          },
+          { concurrency: "unbounded" },
+        ),
+      ),
+      container: {
+        create: ({ image, env, command, context, ...options }) =>
+          // `--env KEY` (name-only) keeps values off CLI arguments; Docker
+          // copies each value from the CLI process environment, so the
+          // normalized container env must be passed to the child process.
+          run(
+            [
+              ...formatArgs({ context }),
+              "container",
+              "create",
+              ...formatArgs({ ...options, env: env ? Object.keys(env) : undefined }),
+              image,
+              ...(command ?? []),
+            ],
+            env,
+          ),
+        inspect: (name, context) =>
+          runInspect<Docker.Container>([...formatArgs({ context }), "container", "inspect", name]),
+        remove: (name, force, context) =>
+          run([...formatArgs({ context }), "container", "rm", name, ...(force ? ["-f"] : [])]),
+        start: (name, context) => run([...formatArgs({ context }), "container", "start", name]),
+        stop: (name, context) => run([...formatArgs({ context }), "container", "stop", name]),
+      },
+      image: {
+        build: Effect.fn("Docker.image.build")(function* (
+          { context: buildContext, engineContext, args, credentials, secrets, ...options },
+          session,
+          registry,
+        ) {
+          const tap = outputTap(session);
+          const secret = buildSecrets(secrets);
+          const buildArgs = [buildContext, ...formatArgs(options), ...secret.args, ...(args ?? [])];
+          const engine = formatArgs({ context: engineContext });
+          if (registry === undefined) {
+            return yield* run(
+              [...engine, "image", "build", ...buildArgs],
+              {
+                ...(credentials ? yield* registryEnvironment(credentials) : undefined),
+                ...secret.env,
+              },
+              tap,
+            );
+          }
+          const mode = yield* publication;
+          if (mode === "export") {
+            // Export straight from BuildKit to the registry; the image never
+            // round-trips through the local image store.
+            const env = yield* registryEnvironment(registry);
+            return yield* run(
+              [...engine, "buildx", "build", "--push", ...buildArgs],
+              { ...env, ...secret.env },
+              tap,
+            ).pipe(Effect.mapError(classifyDockerRegistryError));
+          }
+          // Older Buildx ignores DOCKER_AUTH_CONFIG, so a `--push` export
+          // would fail with "no basic auth credentials". Build into the local
+          // store and publish with the isolated-config `push` instead.
+          // `--load` matters for non-loading builders (docker-container):
+          // without it the result stays in the build cache and `push` sees no
+          // such tag.
+          yield* run(
+            [
+              ...engine,
+              ...(mode === "load" ? ["buildx", "build", "--load"] : ["image", "build"]),
+              ...buildArgs,
+            ],
+            secret.env,
+            tap,
+          );
+          const [tag, ...tags] =
+            typeof options.tag === "string" ? ([options.tag] as const) : options.tag;
+          return yield* push(tag, registry, options.platform, engineContext, session).pipe(
+            Effect.tap(() =>
+              Effect.forEach(tags, (tag) =>
+                push(tag, registry, options.platform, engineContext, session),
+              ),
+            ),
+          );
+        }),
+        pull: (ref, platform, context, session) =>
+          run(
+            [
+              ...formatArgs({ context }),
+              "image",
+              "pull",
+              ref,
+              ...(platform ? ["--platform", platform] : []),
+            ],
+            undefined,
+            outputTap(session),
+          ),
+        inspect: (ref, context) =>
+          runInspect<Docker.Image>([...formatArgs({ context }), "image", "inspect", ref]),
+        remove: (ref, force, context) =>
+          run([
+            ...formatArgs({ context }),
+            "image",
+            "rm",
+            ...(Array.isArray(ref) ? ref : [ref]),
+            ...(force ? ["-f"] : []),
+          ]),
+        tag: (source, target, context) =>
+          run([...formatArgs({ context }), "image", "tag", source, target]),
+        push,
+      },
+      volume: {
+        create: ({ context, ...options }) =>
+          run([...formatArgs({ context }), "volume", "create", ...formatArgs(options)]),
+        remove: (name, context) => run([...formatArgs({ context }), "volume", "rm", name]),
+        inspect: (name, context) =>
+          runInspect<Docker.Volume>([...formatArgs({ context }), "volume", "inspect", name]),
+      },
+      context: {
+        create: ({ name, description, docker }) =>
+          run(["context", "create", name, ...formatArgs({ description, docker })]),
+        update: ({ name, description, docker }) =>
+          run(["context", "update", name, ...formatArgs({ description, docker })]),
+        inspect: (name) => runInspect<Docker.Context>(["context", "inspect", name]),
+        remove: (name, force) => run(["context", "rm", ...(force ? ["-f"] : []), name]),
+      },
+      network: {
+        create: ({ name, driver, ipv6, label, context }) =>
+          run([
+            ...formatArgs({ context }),
+            "network",
+            "create",
+            name,
+            ...formatArgs({ driver, ipv6, label }),
+          ]),
+        connect: ({ network, container, alias, context }) =>
+          run([
+            ...formatArgs({ context }),
+            "network",
+            "connect",
+            network,
+            container,
+            ...(alias ? alias.flatMap((a) => ["--alias", a]) : []),
+          ]),
+        disconnect: ({ network, container, context }) =>
+          run([...formatArgs({ context }), "network", "disconnect", network, container]),
+        inspect: (name, context) =>
+          runInspect<Docker.Network>([...formatArgs({ context }), "network", "inspect", name]),
+        remove: (id, context) => run([...formatArgs({ context }), "network", "rm", id]),
+      },
+      swarm: {
+        init: ({ context, ...options }) =>
+          run([...formatArgs({ context }), "swarm", "init", ...formatArgs(options)]),
+        info: (context) =>
+          run([...formatArgs({ context }), "info", "--format", "{{json .Swarm}}"]).pipe(
+            Effect.map((result) => JSON.parse(result.stdout) as Docker.SwarmInfo),
+          ),
+        leave: (force, context) =>
+          run([...formatArgs({ context }), "swarm", "leave", ...(force ? ["--force"] : [])]),
+      },
+      service: {
+        create: ({ context, image, command, args, ...options }) =>
+          run([
+            ...formatArgs({ context }),
+            "service",
+            "create",
+            ...formatArgs({ ...options }),
+            image,
+            ...(command ?? []),
+            ...(args ?? []),
+          ]),
+        update: ({ context, id, ...options }) =>
+          run([
+            ...formatArgs({ context }),
+            "service",
+            "update",
+            "--detach=false",
+            ...formatArgs({ ...options }),
+            id,
+          ]),
+        inspect: (id, context) =>
+          runInspect([...formatArgs({ context }), "service", "inspect", id]),
+        remove: (id, context) => run([...formatArgs({ context }), "service", "rm", id]),
+      },
+    });
+  });
+
+/** The Docker CLI client, running `docker` (or `DOCKER_BIN`). */
+export const DockerLive = dockerLive();
+
+export const dockerContextName = (context: Docker.ContextRef | undefined): string | undefined => {
+  const value = typeof context === "string" ? context : context?.name;
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : undefined;
+};
+
+/**
+ * Resolve an {@link Docker.EngineRef} to a context name. A `Docker.Swarm`
+ * reference (narrowed by its `nodeId` attribute) contributes the context the
+ * swarm was initialized on.
+ */
+export const dockerEngineContextName = (ref: Docker.EngineRef | undefined): string | undefined => {
+  if (typeof ref === "object" && ref !== null && "nodeId" in ref) {
+    return dockerContextName((ref as { context?: string }).context);
+  }
+  return dockerContextName(ref as Docker.ContextRef | undefined);
+};
+
+export const dockerPhysicalName = (
+  id: string,
+  props: { name?: string } | undefined,
+  instanceId: string,
+  // Swarm service names are capped at 63 characters; other Docker object
+  // names accept much longer values.
+  maxLength = 128,
+) =>
+  props?.name
+    ? Effect.succeed(props.name)
+    : createPhysicalName({ id, instanceId, maxLength, lowercase: true });
+
+/**
+ * A failing `docker` command splits its diagnosis over both streams: the
+ * builder writes the step log to one and the reason it stopped to the other,
+ * and which carries which depends on the builder, the progress mode and
+ * whether the output is a terminal. A build that fails inside a `RUN` step
+ * therefore reports nothing but its exit code when only `stderr` is kept.
+ * Keep both, the reason first, so the error says why the build failed.
+ */
+const failureOutput = (stderr: string, stdout: string) => {
+  const output = [stderr, stdout].filter((text) => text.length > 0);
+  return output.length > 0 ? output.join("\n") : "the command wrote no output.";
+};
+
+/** Constructs a PlatformError from a command execution result. */
+const systemError = (input: {
+  _tag: SystemErrorTag;
+  args: Array<string>;
+  description?: string;
+  cause?: unknown;
+}) =>
+  new PlatformError(
+    new SystemError({
+      _tag: input._tag,
+      module: "Docker",
+      method: input.args.slice(0, 2).join("."),
+      pathOrDescriptor: input.args.join(" "),
+      description: input.description,
+      cause: input.cause,
+    }),
+  );
+
+/**
+ * `--secret id=<id>,env=<var>` per secret, with each value under a generated
+ * variable name: an id is the Dockerfile author's choice and may collide with
+ * the environment Docker itself reads (`PATH`, `DOCKER_HOST`).
+ */
+const buildSecrets = (secrets: Record<string, string | Redacted.Redacted<string>> | undefined) => {
+  const args: Array<string> = [];
+  const env: Record<string, string> = {};
+  Object.entries(secrets ?? {}).forEach(([id, value], index) => {
+    const variable = `ALCHEMY_BUILD_SECRET_${index}`;
+    args.push("--secret", `id=${id},env=${variable}`);
+    env[variable] = Redacted.isRedacted(value) ? Redacted.value(value) : value;
+  });
+  return { args, env };
+};
+
+/** Formats a set of options into a list of command-line arguments. */
+const formatArgs = (
+  options: Record<
+    string,
+    boolean | string | number | undefined | Record<string, string> | Array<string>
+  >,
+) => {
+  const args: Array<string> = [];
+  for (const [key, value] of Object.entries(options)) {
+    // `0` is meaningful (`--replicas 0`, `--update-parallelism 0`), so only
+    // absent, `false` and empty values are omitted.
+    if (value === undefined || value === false || value === "") continue;
+    const prefix = key.length > 1 ? `--${key}` : `-${key}`;
+    if (value === true) {
+      args.push(prefix);
+    } else if (typeof value === "string") {
+      args.push(prefix, value);
+    } else if (typeof value === "number") {
+      args.push(prefix, String(value));
+    } else if (Array.isArray(value)) {
+      for (const item of value) {
+        args.push(prefix, item);
+      }
+    } else if (value !== null && typeof value === "object") {
+      for (const [k, v] of Object.entries(value)) {
+        args.push(prefix, `${k}=${v}`);
+      }
+    }
+  }
+  return args;
+};