The best way to control Claude Code, Codex and more from any computer or phone

main
ts 322 lines 10.9 KB
Raw
1 import * as Artifacts from "alchemy/Artifacts";
2 import { isResolved } from "alchemy/Diff";
3 import * as Provider from "alchemy/Provider";
4 import { Resource } from "alchemy/Resource";
5 import * as Effect from "effect/Effect";
6 import * as FileSystem from "effect/FileSystem";
7 import * as Path from "effect/Path";
8 import type * as Redacted from "effect/Redacted";
9 import { Docker, dockerContextName, dockerPhysicalName } from "./Docker.ts";
10 import type { Providers } from "./Providers.ts";
11 import {
12 type ImageRegistry,
13 parseCreatedAt,
14 publishedRepoDigest,
15 repositoryFromImageRef,
16 withRegistryHost,
17 } from "./Registry.ts";
18
19 export interface DockerBuildOptions {
20 /**
21 * Build context directory.
22 *
23 * @default Current working directory.
24 */
25 context?: string;
26 /**
27 * Dockerfile path, relative to the context unless absolute.
28 *
29 * @default "Dockerfile"
30 */
31 dockerfile?: string;
32 /** Target platform, e.g. `"linux/amd64"`. */
33 platform?: string;
34 /**
35 * Docker build arguments (`--build-arg`). Never pass secrets here: build
36 * args are visible in the image history. Use {@link secrets} instead.
37 */
38 args?: Record<string, string>;
39 /**
40 * BuildKit secrets, keyed by id. Mount one in a `RUN` step with
41 * `--mount=type=secret,id=<id>` and read it from `/run/secrets/<id>`, or
42 * add `env=<NAME>` to expose it as an environment variable for that step.
43 * A secret never enters the image, its build history, or `docker`'s argv.
44 */
45 secrets?: Record<string, Redacted.Redacted<string>>;
46 /** Multi-stage build target. */
47 target?: string;
48 /** Cache sources passed as `--cache-from`. */
49 cacheFrom?: string[];
50 /** Cache destinations passed as `--cache-to`. */
51 cacheTo?: string[];
52 /** Additional Docker build options. */
53 options?: string[];
54 }
55
56 export interface ImageProps {
57 /**
58 * Repository/name for the built image.
59 *
60 * @default Generated from stack, stage, logical id, and instance id.
61 */
62 name?: string;
63 /** Image tag. @default "latest" */
64 tag?: string;
65 /**
66 * Registry credentials. The image is pushed to this registry (unless
67 * `skipPush`), and the build itself authenticates with them, so private
68 * base images and `type=registry` caches hosted there resolve without a
69 * host `docker login`. Credentials already in `DOCKER_AUTH_CONFIG` for
70 * other registries are kept. Build-time authentication needs Buildx 0.26+
71 * (Docker Desktop 4.44+) or the legacy builder; older Buildx plugins ignore
72 * it, so a private base image there still needs `docker login`.
73 */
74 registry?: ImageRegistry;
75 /** Skip registry push even when `registry` is set. @default false */
76 skipPush?: boolean;
77 /** Docker context name or context resource. */
78 context?: Docker.ContextRef;
79 /** Docker build configuration. */
80 build: DockerBuildOptions;
81 }
82
83 export interface Image extends Resource<
84 "Docker.Image",
85 ImageProps,
86 {
87 /** Image repository/name without tag. */
88 name: string;
89 /** Final image reference. Includes registry host when pushed there. */
90 imageRef: string;
91 /** Local image id after build/tag. */
92 imageId: string;
93 /** Registry digest after push when available. */
94 repoDigest?: string;
95 /** Tag used for the local image. */
96 tag: string;
97 /** Build timestamp in milliseconds since epoch. */
98 builtAt: number;
99 },
100 never,
101 Providers
102 > {}
103
104 /**
105 * Builds, tags, and optionally pushes Docker images through the active Docker
106 * context.
107 *
108 * This resource uses the Docker CLI and whatever daemon or remote context the
109 * CLI is configured to target. It is separate from `Cloudflare.Container`;
110 * registry image references are the boundary between Docker-managed images and
111 * cloud container platforms.
112 *
113 * `Image` always builds from a Dockerfile. To pull (and optionally re-tag and
114 * push) an existing registry image, use `Docker.RemoteImage`.
115 *
116 *
117 * ### Building Images
118 * **Example:** Build from a Dockerfile
119 * ```typescript
120 * const image = yield* Docker.Image("app", {
121 * name: "my-app",
122 * tag: "latest",
123 * build: {
124 * context: "./app",
125 * dockerfile: "Dockerfile",
126 * args: { NODE_ENV: "production" },
127 * },
128 * });
129 * ```
130 *
131 * ### Build Secrets
132 * **Example:** Install from a private npm registry
133 * ```typescript
134 * // Dockerfile:
135 * // RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
136 * const image = yield* Docker.Image("app", {
137 * name: "my-app",
138 * build: {
139 * context: "./app",
140 * secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
141 * },
142 * });
143 * ```
144 *
145 * The secret is mounted only into the `RUN` step that asks for it; it never
146 * lands in an image layer or the build history.
147 *
148 * ### Registry Push
149 * **Example:** Push with Redacted credentials
150 * ```typescript
151 * const image = yield* Docker.Image("app", {
152 * name: "my-app",
153 * build: { context: "./app" },
154 * registry: {
155 * server: "ghcr.io",
156 * username: "octocat",
157 * password: Config.Redacted("GITHUB_TOKEN"),
158 * },
159 * });
160 * ```
161 *
162 * ### Private Base Images and Registry Caches
163 * **Example:** Build FROM a private base image with a registry cache
164 * ```typescript
165 * // Dockerfile: FROM registry.example.com/base:v1
166 * const image = yield* Docker.Image("app", {
167 * name: "registry.example.com/app",
168 * build: {
169 * context: "./app",
170 * cacheFrom: ["type=registry,ref=registry.example.com/app:buildcache"],
171 * cacheTo: ["type=registry,ref=registry.example.com/app:buildcache,mode=max"],
172 * },
173 * // Authenticates the base-image pull and cache import/export, then the push.
174 * registry: {
175 * server: "registry.example.com",
176 * username: "deploy",
177 * password: Config.Redacted("REGISTRY_PASSWORD"),
178 * },
179 * });
180 * ```
181 *
182 * ### Docker Context
183 * **Example:** Build in a named Docker context
184 * ```typescript
185 * const image = yield* Docker.Image("app", {
186 * name: "my-app",
187 * context: "remote-build",
188 * build: { context: "./app" },
189 * });
190 * ```
191 *
192 * @resource
193 * @product Image
194 */
195 export const Image = Resource<Image>("Docker.Image");
196
197 export const ImageProvider = () =>
198 Provider.effect(
199 Image,
200 Effect.gen(function* () {
201 const fs = yield* FileSystem.FileSystem;
202 const path = yield* Path.Path;
203 const docker = yield* Docker;
204
205 const buildAndInspectImage = Effect.fn(function* (
206 id: string,
207 props: ImageProps,
208 instanceId: string,
209 ) {
210 const name = yield* dockerPhysicalName(id, props, instanceId);
211 const engineContext = dockerContextName(props.context);
212 const tag = props.tag ?? "latest";
213 const ref = `${name}:${tag}`;
214
215 const paths = yield* resolveBuildPaths(props.build);
216 yield* docker.image.build({
217 tag: ref,
218 context: paths.context,
219 file: paths.dockerfile,
220 platform: props.build.platform,
221 target: props.build.target,
222 "build-arg": props.build.args,
223 secrets: props.build.secrets,
224 "cache-from": props.build.cacheFrom,
225 "cache-to": props.build.cacheTo,
226 args: props.build.options,
227 engineContext,
228 // Base images and registry caches may live in the same registry;
229 // the push itself stays in `reconcile`.
230 credentials: props.registry,
231 });
232
233 // Read the freshly built image's id and creation time straight from
234 // Docker rather than synthesizing a wall-clock timestamp.
235 return {
236 name,
237 tag,
238 image: yield* docker.image.inspect(ref, engineContext),
239 ref,
240 };
241 }, Artifacts.cached("build"));
242
243 const resolveBuildPaths = Effect.fn(function* (build: DockerBuildOptions) {
244 const cwd = yield* Effect.sync(() => process.cwd());
245 const context = path.resolve(build.context ?? cwd);
246 const dockerfile = build.dockerfile
247 ? path.isAbsolute(build.dockerfile)
248 ? build.dockerfile
249 : path.resolve(context, build.dockerfile)
250 : path.resolve(context, "Dockerfile");
251 if (!(yield* fs.exists(context))) {
252 return yield* Effect.die(`Docker build context does not exist: ${context}`);
253 }
254 if (!(yield* fs.exists(dockerfile))) {
255 return yield* Effect.die(`Dockerfile does not exist: ${dockerfile}`);
256 }
257 return { context, dockerfile };
258 });
259
260 return Image.Provider.of({
261 list: () => Effect.succeed([]),
262 read: Effect.fn(function* ({ id, instanceId, olds, output }) {
263 const context = dockerContextName(olds.context);
264 const ref =
265 output?.imageRef ??
266 (yield* dockerPhysicalName(id, olds, instanceId).pipe(
267 Effect.map((name) => `${name}:${olds.tag ?? "latest"}`),
268 ));
269 const image = yield* docker.image
270 .inspect(ref, context)
271 .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.undefined));
272 if (!image) return undefined;
273 return {
274 name: output?.name ?? repositoryFromImageRef(ref),
275 imageRef: ref,
276 imageId: image.Id,
277 repoDigest: output?.repoDigest,
278 tag: output?.tag ?? olds.tag ?? "latest",
279 builtAt: output?.builtAt ?? parseCreatedAt(image.Created),
280 };
281 }),
282 diff: Effect.fn(function* ({ id, instanceId, news, output, olds }) {
283 if (!isResolved(news) || !output) return undefined;
284 if (dockerContextName(olds.context) !== dockerContextName(news.context)) {
285 return { action: "update" };
286 }
287 const { image } = yield* buildAndInspectImage(id, news, instanceId);
288 if (output?.imageId !== image.Id) {
289 return { action: "update" };
290 }
291 }),
292 reconcile: Effect.fn(function* ({ id, instanceId, news, session }) {
293 const context = dockerContextName(news.context);
294 const { name, tag, image, ref } = yield* buildAndInspectImage(id, news, instanceId);
295
296 let repoDigest: string | undefined;
297 let targetImageRef: string = ref;
298 if (news.registry && !news.skipPush) {
299 yield* session.note(`Pushing image to registry "${news.registry.server}"`);
300 targetImageRef = withRegistryHost(ref, news.registry);
301 const pushed = yield* docker.image.push(ref, news.registry, undefined, context);
302 const published = yield* docker.image.inspect(ref, context);
303 repoDigest = publishedRepoDigest(ref, pushed, published.RepoDigests, targetImageRef);
304 }
305
306 return {
307 name,
308 imageRef: targetImageRef,
309 imageId: image.Id,
310 repoDigest,
311 tag,
312 builtAt: parseCreatedAt(image.Created),
313 };
314 }),
315 delete: Effect.fn(({ olds, output }) =>
316 docker.image
317 .remove(output.imageRef, undefined, dockerContextName(olds.context))
318 .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.void)),
319 ),
320 });
321 }),
322 );