@alchemy.run/docker 0.0.0-stage → 2.0.0-beta.84

package/lib/Image.d.ts

@@ -0,0 +1,151 @@
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { Docker } from "./Docker.ts";
+import type { Providers } from "./Providers.ts";
+import { type ImageRegistry } from "./Registry.ts";
+export interface DockerBuildOptions {
+    /**
+     * Build context directory.
+     *
+     * @default Current working directory.
+     */
+    context?: string;
+    /**
+     * Dockerfile path, relative to the context unless absolute.
+     *
+     * @default "Dockerfile"
+     */
+    dockerfile?: string;
+    /** Target platform, e.g. `"linux/amd64"`. */
+    platform?: string;
+    /** Docker build arguments. */
+    args?: Record<string, string>;
+    /** Multi-stage build target. */
+    target?: string;
+    /** Cache sources passed as `--cache-from`. */
+    cacheFrom?: string[];
+    /** Cache destinations passed as `--cache-to`. */
+    cacheTo?: string[];
+    /** Additional Docker build options. */
+    options?: string[];
+}
+export interface ImageProps {
+    /**
+     * Repository/name for the built image.
+     *
+     * @default Generated from stack, stage, logical id, and instance id.
+     */
+    name?: string;
+    /** Image tag. @default "latest" */
+    tag?: string;
+    /**
+     * Registry credentials. The image is pushed to this registry (unless
+     * `skipPush`), and the build itself authenticates with them, so private
+     * base images and `type=registry` caches hosted there resolve without a
+     * host `docker login`. Credentials already in `DOCKER_AUTH_CONFIG` for
+     * other registries are kept. Build-time authentication needs Buildx 0.26+
+     * (Docker Desktop 4.44+) or the legacy builder; older Buildx plugins ignore
+     * it, so a private base image there still needs `docker login`.
+     */
+    registry?: ImageRegistry;
+    /** Skip registry push even when `registry` is set. @default false */
+    skipPush?: boolean;
+    /** Docker context name or context resource. */
+    context?: Docker.ContextRef;
+    /** Docker build configuration. */
+    build: DockerBuildOptions;
+}
+export interface Image extends Resource<"Docker.Image", ImageProps, {
+    /** Image repository/name without tag. */
+    name: string;
+    /** Final image reference. Includes registry host when pushed there. */
+    imageRef: string;
+    /** Local image id after build/tag. */
+    imageId: string;
+    /** Registry digest after push when available. */
+    repoDigest?: string;
+    /** Tag used for the local image. */
+    tag: string;
+    /** Build timestamp in milliseconds since epoch. */
+    builtAt: number;
+}, never, Providers> {
+}
+/**
+ * Builds, tags, and optionally pushes Docker images through the active Docker
+ * context.
+ *
+ * This resource uses the Docker CLI and whatever daemon or remote context the
+ * CLI is configured to target. It is separate from `Cloudflare.Container`;
+ * registry image references are the boundary between Docker-managed images and
+ * cloud container platforms.
+ *
+ * `Image` always builds from a Dockerfile. To pull (and optionally re-tag and
+ * push) an existing registry image, use `Docker.RemoteImage`.
+ *
+ *
+ * ### Building Images
+ * **Example:** Build from a Dockerfile
+ * ```typescript
+ * const image = yield* Docker.Image("app", {
+ *   name: "my-app",
+ *   tag: "latest",
+ *   build: {
+ *     context: "./app",
+ *     dockerfile: "Dockerfile",
+ *     args: { NODE_ENV: "production" },
+ *   },
+ * });
+ * ```
+ *
+ * ### Registry Push
+ * **Example:** Push with Redacted credentials
+ * ```typescript
+ * const image = yield* Docker.Image("app", {
+ *   name: "my-app",
+ *   build: { context: "./app" },
+ *   registry: {
+ *     server: "ghcr.io",
+ *     username: "octocat",
+ *     password: Config.Redacted("GITHUB_TOKEN"),
+ *   },
+ * });
+ * ```
+ *
+ * ### Private Base Images and Registry Caches
+ * **Example:** Build FROM a private base image with a registry cache
+ * ```typescript
+ * // Dockerfile: FROM registry.example.com/base:v1
+ * const image = yield* Docker.Image("app", {
+ *   name: "registry.example.com/app",
+ *   build: {
+ *     context: "./app",
+ *     cacheFrom: ["type=registry,ref=registry.example.com/app:buildcache"],
+ *     cacheTo: ["type=registry,ref=registry.example.com/app:buildcache,mode=max"],
+ *   },
+ *   // Authenticates the base-image pull and cache import/export, then the push.
+ *   registry: {
+ *     server: "registry.example.com",
+ *     username: "deploy",
+ *     password: Config.Redacted("REGISTRY_PASSWORD"),
+ *   },
+ * });
+ * ```
+ *
+ * ### Docker Context
+ * **Example:** Build in a named Docker context
+ * ```typescript
+ * const image = yield* Docker.Image("app", {
+ *   name: "my-app",
+ *   context: "remote-build",
+ *   build: { context: "./app" },
+ * });
+ * ```
+ *
+ * @resource
+ * @product Image
+ */
+export declare const Image: import("alchemy/Resource").ResourceClass<Image>;
+export declare const ImageProvider: () => import("effect/Layer").Layer<Provider.Provider<Image>, never, Docker | FileSystem.FileSystem | Path.Path | import("alchemy/Stack").Stack | import("alchemy/Stage").Stage>;
+//# sourceMappingURL=Image.d.ts.map

package/lib/Image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.d.ts","sourceRoot":"","sources":["../src/Image.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,MAAM,EAAyC,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC5B,kCAAkC;IAClC,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,WAAW,KAAM,SAAQ,QAAQ,CACrC,cAAc,EACd,UAAU,EACV;IACE,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB,EACD,KAAK,EACL,SAAS,CACV;CAAG;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,eAAO,MAAM,KAAK,iDAAkC,CAAC;AAErD,eAAO,MAAM,aAAa,iLA4HvB,CAAC"}

package/lib/Image.js

@@ -0,0 +1,192 @@
+import * as Artifacts from "alchemy/Artifacts";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { Docker, dockerContextName, dockerPhysicalName } from "./Docker.js";
+import { parseCreatedAt, publishedRepoDigest, repositoryFromImageRef, withRegistryHost, } from "./Registry.js";
+/**
+ * Builds, tags, and optionally pushes Docker images through the active Docker
+ * context.
+ *
+ * This resource uses the Docker CLI and whatever daemon or remote context the
+ * CLI is configured to target. It is separate from `Cloudflare.Container`;
+ * registry image references are the boundary between Docker-managed images and
+ * cloud container platforms.
+ *
+ * `Image` always builds from a Dockerfile. To pull (and optionally re-tag and
+ * push) an existing registry image, use `Docker.RemoteImage`.
+ *
+ *
+ * ### Building Images
+ * **Example:** Build from a Dockerfile
+ * ```typescript
+ * const image = yield* Docker.Image("app", {
+ *   name: "my-app",
+ *   tag: "latest",
+ *   build: {
+ *     context: "./app",
+ *     dockerfile: "Dockerfile",
+ *     args: { NODE_ENV: "production" },
+ *   },
+ * });
+ * ```
+ *
+ * ### Registry Push
+ * **Example:** Push with Redacted credentials
+ * ```typescript
+ * const image = yield* Docker.Image("app", {
+ *   name: "my-app",
+ *   build: { context: "./app" },
+ *   registry: {
+ *     server: "ghcr.io",
+ *     username: "octocat",
+ *     password: Config.Redacted("GITHUB_TOKEN"),
+ *   },
+ * });
+ * ```
+ *
+ * ### Private Base Images and Registry Caches
+ * **Example:** Build FROM a private base image with a registry cache
+ * ```typescript
+ * // Dockerfile: FROM registry.example.com/base:v1
+ * const image = yield* Docker.Image("app", {
+ *   name: "registry.example.com/app",
+ *   build: {
+ *     context: "./app",
+ *     cacheFrom: ["type=registry,ref=registry.example.com/app:buildcache"],
+ *     cacheTo: ["type=registry,ref=registry.example.com/app:buildcache,mode=max"],
+ *   },
+ *   // Authenticates the base-image pull and cache import/export, then the push.
+ *   registry: {
+ *     server: "registry.example.com",
+ *     username: "deploy",
+ *     password: Config.Redacted("REGISTRY_PASSWORD"),
+ *   },
+ * });
+ * ```
+ *
+ * ### Docker Context
+ * **Example:** Build in a named Docker context
+ * ```typescript
+ * const image = yield* Docker.Image("app", {
+ *   name: "my-app",
+ *   context: "remote-build",
+ *   build: { context: "./app" },
+ * });
+ * ```
+ *
+ * @resource
+ * @product Image
+ */
+export const Image = Resource("Docker.Image");
+export const ImageProvider = () => Provider.effect(Image, Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const docker = yield* Docker;
+    const buildAndInspectImage = Effect.fn(function* (id, props, instanceId) {
+        const name = yield* dockerPhysicalName(id, props, instanceId);
+        const engineContext = dockerContextName(props.context);
+        const tag = props.tag ?? "latest";
+        const ref = `${name}:${tag}`;
+        const paths = yield* resolveBuildPaths(props.build);
+        yield* docker.image.build({
+            tag: ref,
+            context: paths.context,
+            file: paths.dockerfile,
+            platform: props.build.platform,
+            target: props.build.target,
+            "build-arg": props.build.args,
+            "cache-from": props.build.cacheFrom,
+            "cache-to": props.build.cacheTo,
+            args: props.build.options,
+            engineContext,
+            // Base images and registry caches may live in the same registry;
+            // the push itself stays in `reconcile`.
+            credentials: props.registry,
+        });
+        // Read the freshly built image's id and creation time straight from
+        // Docker rather than synthesizing a wall-clock timestamp.
+        return {
+            name,
+            tag,
+            image: yield* docker.image.inspect(ref, engineContext),
+            ref,
+        };
+    }, Artifacts.cached("build"));
+    const resolveBuildPaths = Effect.fn(function* (build) {
+        const cwd = yield* Effect.sync(() => process.cwd());
+        const context = path.resolve(build.context ?? cwd);
+        const dockerfile = build.dockerfile
+            ? path.isAbsolute(build.dockerfile)
+                ? build.dockerfile
+                : path.resolve(context, build.dockerfile)
+            : path.resolve(context, "Dockerfile");
+        if (!(yield* fs.exists(context))) {
+            return yield* Effect.die(`Docker build context does not exist: ${context}`);
+        }
+        if (!(yield* fs.exists(dockerfile))) {
+            return yield* Effect.die(`Dockerfile does not exist: ${dockerfile}`);
+        }
+        return { context, dockerfile };
+    });
+    return Image.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
+            const context = dockerContextName(olds.context);
+            const ref = output?.imageRef ??
+                (yield* dockerPhysicalName(id, olds, instanceId).pipe(Effect.map((name) => `${name}:${olds.tag ?? "latest"}`)));
+            const image = yield* docker.image
+                .inspect(ref, context)
+                .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.undefined));
+            if (!image)
+                return undefined;
+            return {
+                name: output?.name ?? repositoryFromImageRef(ref),
+                imageRef: ref,
+                imageId: image.Id,
+                repoDigest: output?.repoDigest,
+                tag: output?.tag ?? olds.tag ?? "latest",
+                builtAt: output?.builtAt ?? parseCreatedAt(image.Created),
+            };
+        }),
+        diff: Effect.fn(function* ({ id, instanceId, news, output, olds }) {
+            if (!isResolved(news) || !output)
+                return undefined;
+            if (dockerContextName(olds.context) !== dockerContextName(news.context)) {
+                return { action: "update" };
+            }
+            const { image } = yield* buildAndInspectImage(id, news, instanceId);
+            if (output?.imageId !== image.Id) {
+                return { action: "update" };
+            }
+        }),
+        reconcile: Effect.fn(function* ({ id, instanceId, news, session }) {
+            const context = dockerContextName(news.context);
+            const { name, tag, image, ref } = yield* buildAndInspectImage(id, news, instanceId);
+            let repoDigest;
+            let targetImageRef = ref;
+            if (news.registry && !news.skipPush) {
+                yield* session.note(`Pushing image to registry "${news.registry.server}"`);
+                targetImageRef = withRegistryHost(ref, news.registry);
+                const pushed = yield* docker.image.push(ref, news.registry, undefined, context);
+                const published = yield* docker.image.inspect(ref, context);
+                repoDigest = publishedRepoDigest(ref, pushed, published.RepoDigests, targetImageRef);
+            }
+            return {
+                name,
+                imageRef: targetImageRef,
+                imageId: image.Id,
+                repoDigest,
+                tag,
+                builtAt: parseCreatedAt(image.Created),
+            };
+        }),
+        delete: Effect.fn(({ olds, output }) => docker.image
+            .remove(output.imageRef, undefined, dockerContextName(olds.context))
+            .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.void))),
+    });
+}));
+//# sourceMappingURL=Image.js.map

package/lib/Image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.js","sourceRoot":"","sources":["../src/Image.ts"],"names":[],"mappings":"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"}

package/lib/ImageSource.d.ts

@@ -0,0 +1,234 @@
+import { AlchemyContext } from "alchemy/AlchemyContext";
+import * as Bundle from "alchemy/Bundle/Bundle";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type * as rolldown from "rolldown";
+import { Docker, type RegistryCredentials } from "./Docker.ts";
+import { type InlineDockerfile } from "./Dockerfile.ts";
+/**
+ * INTERNAL — registry-agnostic container image-source machinery shared by
+ * the container platforms (`AWS.ECS.*`, `AWS.EKS.*` via ECR, and
+ * `Kubernetes.*` workloads pushing to any registry).
+ *
+ * NOT exported from any barrel. Consumers import the module path directly.
+ *
+ * A platform's props separate the ENVIRONMENT (what the container is) from
+ * the PROGRAM (`main` — "and run my bundled Effect program in it"):
+ *
+ * - environment (at most one): `image` (registry ref) | `context` +
+ *   `dockerfile`-as-path (docker build) | inline `dockerfile` content
+ *   (`Dockerfile.inline`) | the default bun base when `main` stands alone.
+ * - `main` present → the bundle is injected into the environment (COPY +
+ *   ENTRYPOINT) and pushed as a derived image. `main` absent → the
+ *   environment runs verbatim: `image` is mirrored (docker pull → tag →
+ *   push, content-addressed on the ref), a Dockerfile builds as-is.
+ *
+ * Where images land is an {@link ImageRegistryTarget}: ECR supplies one that
+ * auto-creates a private repository; a plain registry (a local `registry`
+ * container, GHCR, Docker Hub, …) supplies one that pushes to
+ * `<server>/<name>`.
+ */
+/**
+ * Bundle an Effect program into a generated image. Alchemy bundles `main`
+ * with rolldown and bakes it into a Dockerfile generated from the
+ * environment (`image`, `dockerfile`, or the default bun base).
+ */
+export interface BundledImageSource {
+    /**
+     * Module entrypoint for the bundled program. This should typically be
+     * `import.meta.url` from an inline Effect program.
+     */
+    main: string;
+    /**
+     * Environment image: used as the generated Dockerfile's `FROM`. Any
+     * registry ref works (private non-ECR registries require docker
+     * credentials on the build machine); the image must be able to run the
+     * bun runtime. Exclusive with {@link dockerfile} / {@link context}.
+     * @default "oven/bun:1"
+     */
+    image?: string;
+    /**
+     * Environment Dockerfile: a string is a PATH (built in {@link context},
+     * then the bundle is layered on top in a second stage); an
+     * {@link InlineDockerfile} is inline content used as the environment
+     * preamble (built with no context — its own `COPY`s are unsupported).
+     * The resulting environment must be able to run the bun runtime.
+     * Exclusive with {@link image}.
+     */
+    dockerfile?: string | InlineDockerfile;
+    /**
+     * Build context for a path {@link dockerfile} environment. Exclusive
+     * with {@link image} and inline dockerfiles.
+     */
+    context?: string;
+    /**
+     * Named export to load from `main`.
+     * @default "default"
+     */
+    handler?: string;
+    /**
+     * Bundler configuration for the entrypoint. Unused code is tree-shaken.
+     * `effect`, alchemy, and `@distilled.cloud` are marked pure so unused
+     * parts prune more aggressively. List extra packages with
+     * `pure.packages`, or disable with `pure: false`.
+     */
+    build?: Bundle.BundleConfig;
+}
+/**
+ * Build the image from the user's own Dockerfile and build context — no
+ * Effect program is bundled.
+ */
+export interface DockerfileImageSource {
+    /**
+     * Docker build context directory. Optional when {@link dockerfile} is
+     * inline content (which builds with an empty context).
+     */
+    context?: string;
+    /**
+     * Path to the Dockerfile relative to the cwd (NOT the context), or
+     * {@link InlineDockerfile} content. The Dockerfile must define its own
+     * `CMD`/`ENTRYPOINT` (no program is injected).
+     * @default `${context}/Dockerfile`
+     */
+    dockerfile?: string | InlineDockerfile;
+}
+/**
+ * Run a pre-built registry image. Registry-backed platforms may mirror it
+ * into their own registry (ECR: docker pull → tag → push).
+ */
+export interface RegistryImageSource {
+    /**
+     * A pre-built image reference, e.g.
+     * `public.ecr.aws/docker/library/busybox:stable`.
+     */
+    image: string;
+}
+/**
+ * The image-source union. Discriminated by presence: exactly one of
+ * `main`, `context`, or `image`.
+ */
+export type ImageSourceProps = BundledImageSource | DockerfileImageSource | RegistryImageSource;
+/** Loose bag shape used to sniff which source variant a props object is. */
+export interface ImageSourceLike {
+    main?: string;
+    handler?: string;
+    build?: BundledImageSource["build"];
+    context?: string;
+    dockerfile?: string | InlineDockerfile;
+    image?: string;
+}
+export type ImageSourceKind = "main" | "context" | "image";
+/**
+ * Which image source a props bag declares. `main` always wins (the other
+ * fields then describe its ENVIRONMENT); without `main`, `image` is the
+ * mirrored-verbatim source and any `context`/`dockerfile` (path or inline)
+ * is an external docker build.
+ */
+export declare const imageSourceKind: (source: ImageSourceLike) => ImageSourceKind | undefined;
+/**
+ * Validate environment-source exclusivity. Dies (plan-time defect) on
+ * `image`+`dockerfile`, `image`+`context`, or inline-`dockerfile`+`context`.
+ */
+export declare const validateImageSource: (id: string, source: ImageSourceLike) => Effect.Effect<void>;
+/**
+ * Where a resolved image is pushed. Each field is an Effect so a target can
+ * create resources lazily (ECR creates the repository on first use).
+ */
+export interface ImageRegistryTarget<R = never> {
+    /** The repository URI images are tagged into (`<repositoryUri>:<hash>`). */
+    readonly repositoryUri: Effect.Effect<string, any, R>;
+    /**
+     * Whether the content-addressed tag is already in the registry. `true`
+     * skips the build and push entirely.
+     */
+    readonly hasTag: (tag: string) => Effect.Effect<boolean, any, R>;
+    /**
+     * Push credentials. `undefined` pushes with the build machine's own
+     * Docker configuration (`docker login`, credential helpers).
+     */
+    readonly credentials: Effect.Effect<RegistryCredentials | undefined, any, R>;
+}
+export interface ResolveContainerImageOptions {
+    /** Logical resource id — keys the stable build-context directory. */
+    id: string;
+    /**
+     * The props bag carrying the image source fields (`main` / `context` /
+     * `image` plus their modifiers).
+     */
+    source: ImageSourceLike;
+    /**
+     * Target image platform.
+     * @default "linux/amd64"
+     */
+    platform?: string;
+    /**
+     * Port the generated Dockerfile should `ENV PORT=` + `EXPOSE`
+     * (`main` source only).
+     */
+    port?: number;
+    /**
+     * True when the resource was declared without an inline Effect impl —
+     * `main` is then bundled as-is without the virtual-entry bootstrap.
+     */
+    isExternal?: boolean;
+    /**
+     * The virtual-entry bootstrap wrapped around `main` for Effect-native
+     * programs: receives the resolved entry import path and returns the
+     * generated entry module source.
+     */
+    bootstrap: (importPath: string) => string;
+    /** Plan-status session used to emit build/push progress notes. */
+    session: {
+        note: (message: string) => Effect.Effect<void>;
+    };
+}
+/**
+ * Content hash for the sources whose identity is computable WITHOUT running
+ * a bundler:
+ *
+ * - `context` — hash of the build-context directory + Dockerfile content +
+ *   platform.
+ * - `image` — hash of the image reference + platform (re-mirror only when
+ *   the ref changes).
+ * - `main` — `undefined`: the hash comes from the bundle output, so it is
+ *   only known inside `resolve`.
+ *
+ * Providers use this in `diff` to surface content drift (files changed under
+ * an unchanged `context` path) as an update.
+ */
+export declare const computeStaticSourceHash: (source: ImageSourceLike, platform?: string | undefined) => Effect.Effect<string | undefined, import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
+/**
+ * Init-time constructor for the image-source resolver. Resolves the services
+ * that are only available at provider-layer construction (Docker, the
+ * `.alchemy` directory, the rolldown virtual-entry plugin) and returns
+ * `resolve` (build/mirror + push to an {@link ImageRegistryTarget}), `hash`,
+ * and `watchMain`.
+ */
+export declare const makeContainerImageSource: Effect.Effect<{
+    resolve: <R>(options: ResolveContainerImageOptions, target: ImageRegistryTarget<R>) => Effect.Effect<{
+        imageUri: string;
+        repositoryUri: string;
+        codeHash: string;
+    }, any, R | FileSystem.FileSystem | Path.Path | import("alchemy/Stack").Stack | import("alchemy/Stage").Stage>;
+    hash: (options: {
+        source: ImageSourceLike;
+        platform?: string;
+        port?: number;
+        isExternal?: boolean;
+        bootstrap: (importPath: string) => string;
+    }) => Effect.Effect<string | undefined, Bundle.BundleError | import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
+    watchMain: (options: {
+        source: BundledImageSource;
+        isExternal?: boolean;
+        bootstrap: (importPath: string) => string;
+    }) => Effect.Effect<{
+        inputOptions: rolldown.InputOptions;
+        outputOptions: rolldown.OutputOptions;
+        extra: Bundle.BundleConfig | undefined;
+    }, import("effect/PlatformError").PlatformError, FileSystem.FileSystem | Path.Path>;
+}, never, AlchemyContext | Docker | Path.Path>;
+/** The resolver service returned by {@link makeContainerImageSource}. */
+export interface ContainerImageSource extends Effect.Success<typeof makeContainerImageSource> {
+}
+//# sourceMappingURL=ImageSource.d.ts.map

package/lib/ImageSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageSource.d.ts","sourceRoot":"","sources":["../src/ImageSource.ts"],"names":[],"mappings":"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"}