sailfork / t3code-github / .repos/ alchemy-effect/ packages/ docker/ src/ Docker.ts

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;
};