@lakutata/docker 3.0.0-beta.0

package/dist/types/docker/lib/ParseBaseImages.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The images of the FROM instructions of a Dockerfile, pulled before a build with credentials: their flags (--platform)
+ * and their stage names (AS build) are skipped, the stages of the Dockerfile and scratch are not images, the variables
+ * are the ARG declared before the first FROM (with their defaults) and the build arguments. The images whose variables
+ * are unknown are skipped
+ * @param dockerfile the content of the Dockerfile
+ * @param buildargs
+ */
+export declare function parseBaseImages(dockerfile: string, buildargs?: Record<string, string>): string[];

package/dist/types/docker/lib/ParseEnvToRecord.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Turn a list of environment variables as the Engine API gives them (`['PATH=/usr/bin', 'MODE=a=b']`) into a record by
+ * name. A variable is split at its first `=`; an entry without `=` is skipped; a repeated name keeps its last value.
+ * @param rawEnv The `NAME=value` entries; `null` or `undefined` for none.
+ * @returns The values by name (`{PATH: '/usr/bin', MODE: 'a=b'}`).
+ * @example
+ * ```typescript
+ * import {parseEnvToRecord} from 'lakutata/com/docker'
+ *
+ * const env: Record<string, string> = parseEnvToRecord(['PATH=/usr/bin', 'MODE=a=b', 'EMPTY='])
+ * console.log(env) //{PATH: '/usr/bin', MODE: 'a=b', EMPTY: ''}
+ * ```
+ */
+export declare function parseEnvToRecord(rawEnv?: string[] | null): Record<string, string>;

package/dist/types/docker/lib/ParseRepositoryTag.d.ts

@@ -0,0 +1,17 @@
+import { type RepositoryTag } from '../types/RepositoryTag.js';
+/**
+ * Split an image reference into its repository and its tag (or digest). A digest (`@`) wins over a tag; the port of a
+ * registry (`registry:5000/app`) is not taken for a tag.
+ * @param input The image reference: `alpine`, `alpine:3.20`, `registry.example.com:5000/team/app:1.0`,
+ * `alpine@sha256:…`.
+ * @returns The repository, and the tag (or the digest, without its `@`) when the reference has one.
+ * @example
+ * ```typescript
+ * import {parseRepositoryTag, type RepositoryTag} from 'lakutata/com/docker'
+ *
+ * const reference: RepositoryTag = parseRepositoryTag('registry.example.com:5000/team/app:1.0')
+ * console.log(reference) //{repo: 'registry.example.com:5000/team/app', tag: '1.0'}
+ * console.log(parseRepositoryTag('registry.example.com:5000/team/app')) //{repo: 'registry.example.com:5000/team/app'}
+ * ```
+ */
+export declare function parseRepositoryTag(input: string): RepositoryTag;

package/dist/types/docker/lib/RegistryAuth.d.ts

@@ -0,0 +1,8 @@
+import { type DockerRegistryAuth } from '../../client/DockerClient.js';
+import { type DockerAuthOptions } from '../options/auth/DockerAuthOptions.js';
+/**
+ * The registry credentials sent to the daemon (the login, the pulls, the pushes and the builds), the tokens included
+ * @param auth
+ */
+export declare function registryAuth(auth: DockerAuthOptions): DockerRegistryAuth;
+export declare function registryAuth(auth?: DockerAuthOptions): DockerRegistryAuth | undefined;

package/dist/types/docker/options/DockerPruneOptions.d.ts

@@ -0,0 +1,38 @@
+import { DTO } from '@lakutata/core';
+/**
+ * Which unused resources {@link Docker.prune} removes, each kind as its `docker … prune` command does without options.
+ * Called without options, it prunes the containers and the images; the networks and the volumes only when asked (the
+ * volumes, as `docker system prune --volumes`).
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * //The stopped containers and the unused networks, keeping the images and the volumes
+ * await docker.prune({containers: true, images: false, networks: true, volumes: false})
+ * ```
+ */
+export declare class DockerPruneOptions extends DTO {
+    /**
+     * Remove the stopped containers (`docker container prune`).
+     * @default true
+     */
+    containers?: boolean;
+    /**
+     * Remove the dangling images, untagged and not used by a container (`docker image prune`, without `--all`).
+     * @default true
+     */
+    images?: boolean;
+    /**
+     * Remove the networks no container uses (`docker network prune`).
+     * @default false
+     */
+    networks?: boolean;
+    /**
+     * Remove the volumes no container uses (`docker volume prune`): the anonymous ones only on Docker Engine 23 and
+     * later (API 1.42), the named ones too before.
+     * @default false
+     */
+    volumes?: boolean;
+}

package/dist/types/docker/options/auth/DockerAuthOptions.d.ts

@@ -0,0 +1,46 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The credentials of an image registry: checked by {@link Docker.loginRepository} and
+ * {@link Docker.checkRepositoryAuth}, and sent with the image pulls ({@link ImagePullOptions.auth}), pushes
+ * ({@link ImagePushOptions.auth}) and builds ({@link ImageBuildOptions.auth}), each of them given every field set
+ * (the tokens included). Only `serverAddress` is required.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const valid: boolean = await docker.checkRepositoryAuth({
+ *     serverAddress: 'registry.example.com:5000',
+ *     username: 'ci',
+ *     password: process.env.REGISTRY_PASSWORD ?? ''
+ * })
+ * ```
+ */
+export declare class DockerAuthOptions extends DTO {
+    /**
+     * The user name.
+     */
+    username?: string;
+    /**
+     * The password, or a personal access token of the registry.
+     */
+    password?: string;
+    /**
+     * The registry address, a host name or an IP address with its port when it is not the default one, without a
+     * protocol (`registry.example.com`, `10.0.0.5:5000`). Required.
+     */
+    serverAddress: string;
+    /**
+     * The e-mail address of the account, for the old registries asking for it; the current ones ignore it.
+     */
+    email?: string | undefined;
+    /**
+     * An identity token (an OAuth refresh token) the registry gave at a previous login, used instead of the password.
+     */
+    identityToken?: string | undefined;
+    /**
+     * A bearer token the registry gave, used instead of the user name and the password.
+     */
+    registryToken?: string | undefined;
+}

package/dist/types/docker/options/container/ContainerCommitOptions.d.ts

@@ -0,0 +1,28 @@
+import { DTO } from '@lakutata/core';
+/**
+ * How `DockerContainer.commit()` creates an image of the container's current file system (`docker commit`), the
+ * created image returned.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * const image = await container.commit({repoTag: 'web-snapshot:2026-10-04'})
+ * console.log(image.id)
+ * ```
+ */
+export declare class ContainerCommitOptions extends DTO {
+    /**
+     * The repository and tag of the image, `repo:tag` (`my-app:snapshot`, `registry.example.com:5000/team/app:1.0`); a
+     * repository without a tag is tagged `latest`. Without it, the image has no name (dangling) and is known by its ID
+     * only.
+     */
+    repoTag?: string;
+    /**
+     * Pause the container while the image is created, for a consistent file system; it resumes after.
+     * @default true
+     */
+    pauseBeforeCommitting?: boolean;
+}

package/dist/types/docker/options/container/ContainerCreateTTYOptions.d.ts

@@ -0,0 +1,32 @@
+import { DTO } from '@lakutata/core';
+import { ContainerTTYConsoleSizeOptions } from './ContainerTTYConsoleSizeOptions.js';
+/**
+ * The interactive command `DockerContainer.createTTY()` runs in a running container with a terminal (`docker exec -it`),
+ * read and written through the returned `DockerContainerTTY`.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * const tty = await container.createTTY({cmd: ['/bin/bash', '-l'], consoleSize: {cols: 120, rows: 40}})
+ * tty.onData((chunk: Buffer): void => {
+ *     process.stdout.write(chunk)
+ * })
+ * tty.write('ls -la\n')
+ * ```
+ */
+export declare class ContainerCreateTTYOptions extends DTO {
+    /**
+     * The command: the executable followed by its arguments (`['/bin/bash', '-l']`, at least one item), run as they
+     * are; or a command line (`'top -d 1'`), run by `/bin/sh -c`. The default needs a shell in the image (not in the
+     * distroless ones).
+     * @default ['/bin/sh']
+     */
+    cmd?: string | string[];
+    /**
+     * The terminal's initial size; without it, Docker's default size, until `DockerContainerTTY.resize()` is called.
+     */
+    consoleSize?: ContainerTTYConsoleSizeOptions;
+}

package/dist/types/docker/options/container/ContainerExecOptions.d.ts

@@ -0,0 +1,26 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The command `DockerContainer.exec()` runs in a running container, without a terminal nor an input (`docker exec`); it
+ * resolves once the command exits, with its exit code and its standard output and error output apart.
+ * @example
+ * ```typescript
+ * import {Docker, type ContainerExecResult} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * const listing: ContainerExecResult = await container.exec({cmd: ['ls', '-la', '/app']})
+ * //A command line, run by /bin/sh -c
+ * const count: ContainerExecResult = await container.exec({cmd: 'ls /app | wc -l'})
+ * if (count.exitCode !== 0) console.error(count.stderr)
+ * console.log(listing.stdout, count.stdout)
+ * ```
+ */
+export declare class ContainerExecOptions extends DTO {
+    /**
+     * The command: the executable followed by its arguments (`['ls', '-la', '/app']`, at least one item), run as they
+     * are; or a command line (`'ls /app | wc -l'`), run by `/bin/sh -c`, which needs a shell in the container.
+     * Required.
+     */
+    cmd: string | string[];
+}

package/dist/types/docker/options/container/ContainerExportDirectoryOptions.d.ts

@@ -0,0 +1,27 @@
+import { DTO } from '@lakutata/core';
+import { Writable } from 'node:stream';
+/**
+ * What `DockerContainer.exportDirectory()` copies out of a container (`docker cp`): a file or directory of the
+ * container, written as an uncompressed tar archive to a file or a stream. The container may be stopped.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * await container.exportDirectory({path: '/var/log/nginx', destination: '/backup/nginx-logs.tar'})
+ * ```
+ */
+export declare class ContainerExportDirectoryOptions extends DTO {
+    /**
+     * The absolute path of the file or directory in the container (`/var/log/nginx`); the archive holds it under its
+     * base name (`nginx/…`). Required.
+     */
+    path: string;
+    /**
+     * Where the tar archive is written: the path of a host file, created or replaced, or a writable stream, ended once
+     * the archive is written. Required.
+     */
+    destination: string | Writable;
+}

package/dist/types/docker/options/container/ContainerKillOptions.d.ts

@@ -0,0 +1,25 @@
+import { DTO } from '@lakutata/core';
+/**
+ * How `DockerContainer.kill()` kills a running container (`docker kill`).
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * //Reload the configuration of the main process
+ * await container.kill({signal: 'SIGHUP'})
+ * //SIGKILL
+ * await container.kill()
+ * ```
+ */
+export declare class ContainerKillOptions extends DTO {
+    /**
+     * The signal sent to the container's main process: a name (`'SIGHUP'`, `'SIGTERM'`, also without its `SIG` prefix)
+     * or a number (`15`, `'15'`). A signal the daemon does not know is refused by it (`DockerRequestException`,
+     * HTTP 400 or 500).
+     * @default 'SIGKILL'
+     */
+    signal?: string | number;
+}

package/dist/types/docker/options/container/ContainerLogsOptions.d.ts

@@ -0,0 +1,48 @@
+import { DTO } from '@lakutata/core';
+/**
+ * Which logs `DockerContainer.logs()` reads (`docker logs`): a readable stream of the container's standard output and
+ * error output, interleaved, as text (the multiplexing of a container without a terminal removed).
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * //The last 100 lines of the past hour, then the new ones as they are written
+ * const logs: NodeJS.ReadableStream = await container.logs({
+ *     since: Math.floor(Date.now() / 1000) - 3600,
+ *     tail: 100,
+ *     timestamps: true
+ * })
+ * logs.pipe(process.stdout)
+ * ```
+ */
+export declare class ContainerLogsOptions extends DTO {
+    /**
+     * Keep the stream open and give the new lines as the container writes them (`docker logs --follow`): the stream
+     * ends when the container stops. `false` ends the stream after the existing lines.
+     * @default true
+     */
+    follow?: boolean;
+    /**
+     * Only the lines written from this time on, a UNIX timestamp in seconds; `0` for no lower bound.
+     * @default 0
+     */
+    since?: number;
+    /**
+     * Only the lines written before this time, a UNIX timestamp in seconds; `0` for no upper bound.
+     * @default 0
+     */
+    until?: number;
+    /**
+     * Prefix each line with the time it was written, an RFC 3339 date with nanoseconds
+     * (`2026-10-04T08:15:30.123456789Z `).
+     * @default false
+     */
+    timestamps?: boolean;
+    /**
+     * Only this number of lines, from the end of the existing logs; all the lines when absent.
+     */
+    tail?: number;
+}

package/dist/types/docker/options/container/ContainerRemoveOptions.d.ts

@@ -0,0 +1,22 @@
+import { DTO } from '@lakutata/core';
+/**
+ * How `DockerContainer.remove()` removes a container (`docker rm -v`): its anonymous volumes are removed with it, the
+ * named volumes are kept.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * await container.remove({force: true})
+ * ```
+ */
+export declare class ContainerRemoveOptions extends DTO {
+    /**
+     * Kill the container first when it is running (`docker rm --force`); without it, removing a running container
+     * fails.
+     * @default false
+     */
+    force?: boolean;
+}

package/dist/types/docker/options/container/ContainerSettingOptions.d.ts

@@ -0,0 +1,137 @@
+import { DTO } from '@lakutata/core';
+import { ContainerDevice } from '../../types/ContainerDevice.js';
+import { type ContainerRestartPolicy } from '../../types/ContainerRestartPolicy.js';
+import { ContainerPort } from '../../types/ContainerPort.js';
+import { ContainerBind } from '../../types/ContainerBind.js';
+import { ContainerNetwork } from '../../types/ContainerNetwork.js';
+import { ContainerCapability } from '../../types/ContainerCapability.js';
+/**
+ * The settings of a container: given to {@link Docker.createContainer} and `DockerImage.run()` (create, then start),
+ * which use the image's defaults (command, environment…) for the settings absent, and to `DockerContainer.update()`,
+ * which changes the settings given and keeps the others: the limits and the restart policy live, the others by
+ * recreating the container. Every option is optional.
+ * @example
+ * ```typescript
+ * import {Docker, ContainerCapability} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image = await docker.pullImage({repo: 'nginx', tag: '1.27'})
+ * const container = await image.run({
+ *     name: 'web',
+ *     env: {TZ: 'UTC'},
+ *     memoryLimit: 256 * 1024 * 1024,
+ *     restartPolicy: 'unless-stopped',
+ *     ports: [{port: 80, type: 'tcp', hostPorts: [8080]}],
+ *     binds: [{hostPath: '/srv/web/html', containerPath: '/usr/share/nginx/html', rw: false}],
+ *     networks: [{networkName: 'front'}],
+ *     capabilities: [ContainerCapability.NET_ADMIN]
+ * })
+ * //The same container, with 512 MiB of memory, restarted 3 times at most when it fails
+ * await container.update({memoryLimit: 512 * 1024 * 1024, restartPolicy: 'on-failure:3'})
+ * ```
+ */
+export declare class ContainerSettingOptions extends DTO {
+    /**
+     * The container name, unique on the Docker host: letters, digits, `_`, `.` and `-`, starting with a letter or a
+     * digit. Docker generates one (`happy_turing`) when absent.
+     */
+    name?: string;
+    /**
+     * The host name seen in the container; Docker uses the first 12 characters of the container ID when absent.
+     */
+    hostname?: string;
+    /**
+     * Run the container privileged (`docker run --privileged`): every capability and every host device, without the
+     * security restrictions. It gives the container full access to the host.
+     */
+    privileged?: boolean;
+    /**
+     * Give the container's main process a terminal (`docker run -t`): its output is then not multiplexed, and
+     * `DockerContainer.logs()` gives it as written.
+     */
+    tty?: boolean;
+    /**
+     * The environment variables, by name (`{NODE_ENV: 'production'}`), added to the image's ones; the values are
+     * strings.
+     */
+    env?: Record<string, string>;
+    /**
+     * The memory limit, in bytes (`256 * 1024 * 1024` for 256 MiB); Docker requires at least 6 MiB. `0` or absent for
+     * no limit. The swap limit is Docker's default: as much swap as memory.
+     * @default 0
+     */
+    memoryLimit?: number;
+    /**
+     * The indexes of the host CPUs the container may run on (`[0, 1]`, sent to Docker as `"0,1"`); all of them when
+     * absent. Each one is an integer.
+     */
+    cpuSet?: number[];
+    /**
+     * When Docker restarts the container after it exits: `''`, `'no'`, `'always'`, `'unless-stopped'`,
+     * `'on-failure'` (with no limit on the retries) or `'on-failure:N'` (`N` retries at most, `'on-failure:3'`); another
+     * value fails the validation. `''` or absent for no restart.
+     */
+    restartPolicy?: ContainerRestartPolicy;
+    /**
+     * The container ports published on the host (`docker run -p`), each one required to have a `port` (a valid port
+     * number) and a `type` (`'tcp'` or `'udp'`), sent to Docker as `"80/tcp"`. Its `hostPorts` are the host ports
+     * forwarded to it, bound on every host address (`[8080]`, each one once); empty, or absent, it is published on no
+     * host port.
+     */
+    ports?: (Pick<ContainerPort, 'port' | 'type'> & Partial<Pick<ContainerPort, 'hostPorts'>>)[];
+    /**
+     * The host files and directories mounted into the container (`docker run -v`), each one required to have its
+     * `hostPath`, its `containerPath` and `rw` (`false` for read-only); sent to Docker as
+     * `"hostPath:containerPath:rw"` or `"hostPath:containerPath:ro"`.
+     */
+    binds?: ContainerBind[];
+    /**
+     * The host devices made available in the container (`docker run --device`), each one required to have its
+     * `hostPath` and its `containerPath`; its `cgroupPermissions`, a combination of `r`, `w` and `m`, is `'rwm'` by
+     * default.
+     */
+    devices?: (Pick<ContainerDevice, 'hostPath' | 'containerPath'> & Partial<Pick<ContainerDevice, 'cgroupPermissions'>>)[];
+    /**
+     * The networks the container is connected to, each one required to have its `networkName`; the default `bridge`
+     * network when absent. On a user-defined network, `ip` (an IPv4 address) and `ipv6` (an IPv6 address) set the
+     * container's static addresses, within the network's range; empty or absent, Docker allocates them. They are
+     * ignored on `bridge`, `host` and `none`.
+     */
+    networks?: (Pick<ContainerNetwork, 'networkName'> & Partial<Pick<ContainerNetwork, 'ip' | 'ipv6'>>)[];
+    /**
+     * Keep the kernel's OOM killer from killing the container's processes when it runs out of memory; set it with a
+     * memory limit only, or the host may kill its own processes instead.
+     */
+    OOMKillDisable?: boolean;
+    /**
+     * The Linux capabilities added to Docker's default set (`docker run --cap-add`); a value outside
+     * {@link ContainerCapability} fails the validation. None added when absent (`update()` keeps the container's).
+     */
+    capabilities?: ContainerCapability[];
+    /**
+     * The cgroup the container runs in (the Docker Engine's `HostConfig.Cgroup`): `'container:<name|id>'` shares
+     * another container's cgroup; its own when absent.
+     */
+    cgroup?: string;
+    /**
+     * The parent cgroup the container's cgroup is created under (`docker run --cgroup-parent`); a relative path is
+     * relative to the cgroup of the init process. The cgroups are created when missing.
+     */
+    cgroupParent?: string;
+    /**
+     * The PID namespace of the container (`docker run --pid`): `'container:<name|id>'` joins another container's,
+     * `'host'` uses the host's; its own when absent.
+     */
+    pidMode?: string;
+    /**
+     * The command, replacing the image's `CMD`: the executable followed by its arguments (`['node', 'server.js']`), an
+     * array only.
+     */
+    cmd?: string[];
+    /**
+     * The entry point, replacing the image's `ENTRYPOINT`: the executable followed by its arguments, an array only.
+     * `['']` removes the image's entry point: the command runs alone.
+     */
+    entrypoint?: string[];
+}

package/dist/types/docker/options/container/ContainerStopOptions.d.ts

@@ -0,0 +1,28 @@
+import { DTO } from '@lakutata/core';
+/**
+ * How `DockerContainer.stop()` and `DockerContainer.restart()` stop a running container (`docker stop`): Docker sends
+ * the stop signal to its main process, then kills it with `SIGKILL` when it has not exited after the timeout.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * //Up to 30 seconds to finish the requests in progress
+ * await container.stop({signal: 'SIGINT', timeout: 30})
+ * await container.restart({timeout: 5})
+ * ```
+ */
+export declare class ContainerStopOptions extends DTO {
+    /**
+     * The signal sent first, a name (`'SIGINT'`) or a number (`'2'`); the container's stop signal when absent (its
+     * image's `STOPSIGNAL`, `SIGTERM` by default).
+     */
+    signal?: string;
+    /**
+     * The time given to the container to exit before it is killed, in seconds (a whole number); the container's stop
+     * timeout when absent, 10 seconds by default.
+     */
+    timeout?: number;
+}

package/dist/types/docker/options/container/ContainerTTYConsoleSizeOptions.d.ts

@@ -0,0 +1,26 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The size of a container terminal, in characters: its initial size ({@link ContainerCreateTTYOptions.consoleSize}),
+ * and its new size given to `DockerContainerTTY.resize()` when the user's terminal is resized. Both are required.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * const tty = await container.createTTY({cmd: 'sh', consoleSize: {cols: 120, rows: 40}})
+ * //The user's terminal was resized
+ * await tty.resize({cols: 160, rows: 50})
+ * ```
+ */
+export declare class ContainerTTYConsoleSizeOptions extends DTO {
+    /**
+     * The width, in columns (characters). Required.
+     */
+    cols: number;
+    /**
+     * The height, in rows (lines). Required.
+     */
+    rows: number;
+}

package/dist/types/docker/options/image/ImageBuildOptions.d.ts

@@ -0,0 +1,117 @@
+import { DTO } from '@lakutata/core';
+import type { DockerOutputCallback } from '../../types/DockerOutputCallback.js';
+import { DockerAuthOptions } from '../auth/DockerAuthOptions.js';
+/**
+ * How {@link Docker.buildImage} builds an image with BuildKit (`docker build`), the built image returned. The build
+ * context is the listed files and directories of the working directory, without the ones its `.dockerignore` excludes;
+ * the Dockerfile is always sent. `workdir` and `files` are required.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image = await docker.buildImage({
+ *     workdir: '/srv/projects/api',
+ *     files: ['package.json', 'package-lock.json', 'dist'],
+ *     repoTag: 'api:1.4.0',
+ *     platform: 'linux/amd64',
+ *     buildargs: {NODE_VERSION: '22'},
+ *     outputCallback: (output: Record<string, any>): void => {
+ *         if (output.stream) console.log(output.stream)
+ *     }
+ * })
+ * console.log(image.id)
+ * ```
+ */
+export declare class ImageBuildOptions extends DTO {
+    /**
+     * The directory of the build context on this machine, holding the Dockerfile and its `.dockerignore`. Required.
+     */
+    workdir: string;
+    /**
+     * The files and directories of `workdir` sent as the build context, their paths relative to it (`['package.json',
+     * 'dist']`); the directories are sent with their content, the files excluded by `.dockerignore` are skipped, and
+     * the Dockerfile is added. Required.
+     */
+    files: string[];
+    /**
+     * The path of the Dockerfile in the build context, relative to `workdir`. Ignored when `remote` points to a
+     * Dockerfile.
+     * @default 'Dockerfile'
+     */
+    dockerfile?: string;
+    /**
+     * The repository and tag of the image, `name:tag` (`api:1.4.0`); a name without a tag is tagged `latest`. When
+     * absent, the image is named `unnamed_img_<random hexadecimal>:latest`.
+     */
+    repoTag?: string;
+    /**
+     * The platform of the image, `os[/arch[/variant]]` (`linux/amd64`, `linux/arm64/v8`); `''` for the Docker host's
+     * platform.
+     * @default ''
+     */
+    platform?: string;
+    /**
+     * The stage of a multi-stage Dockerfile to build (`FROM … AS <stage>`); `''` for the last stage.
+     * @default ''
+     */
+    target?: string;
+    /**
+     * A remote build context: a Git repository URL or an HTTP/HTTPS URL. A URL of a text file is used as the
+     * Dockerfile; a URL of a tarball is downloaded by Docker and used as the context, which must then hold the
+     * `dockerfile` path.
+     */
+    remote?: string;
+    /**
+     * Suppress the verbose build output (`docker build --quiet`).
+     * @default false
+     */
+    quiet?: boolean;
+    /**
+     * The former, misspelt name of {@link ImageBuildOptions.quiet}: the build is quiet when either is `true`.
+     * @deprecated Use `quiet`.
+     */
+    quite?: boolean;
+    /**
+     * Build without the build cache (`docker build --no-cache`).
+     * @default false
+     */
+    nocache?: boolean;
+    /**
+     * Remove the intermediate containers after a successful build (the legacy builder's `--rm`; BuildKit creates
+     * none).
+     * @default true
+     */
+    rm?: boolean;
+    /**
+     * Always remove the intermediate containers, even after a failure (the legacy builder's `--force-rm`; BuildKit
+     * creates none).
+     * @default false
+     */
+    forcerm?: boolean;
+    /**
+     * The size of `/dev/shm` in the build containers, in bytes, greater than 0; 64 MiB when absent.
+     */
+    shmsize?: number;
+    /**
+     * The build arguments, by name (`{NODE_VERSION: '22'}`): the values of the Dockerfile's `ARG` instructions, in the
+     * environment of its `RUN` instructions and expanded in its other instructions. They stay visible in the image's
+     * history: not for the secrets.
+     */
+    buildargs?: {
+        [key: string]: string;
+    };
+    /**
+     * The credentials of a private registry the base images come from. When given, the images of the Dockerfile's
+     * `FROM` instructions are pulled first with them (on `platform`, their progress given to `outputCallback`), and
+     * BuildKit is given them (the tokens included) for `auth.serverAddress`.
+     */
+    auth?: DockerAuthOptions;
+    /**
+     * Receive the build progress as it arrives: the BuildKit progress as the lines of `docker build --progress=plain`
+     * (`{id: 'moby.buildkit.trace', stream: '#2 [1/2] FROM alpine'}`), and the other messages of Docker as they are
+     * sent (the built image's ID, `{aux: {ID: 'sha256:…'}}`, the errors, `{error: '…'}`).
+     */
+    outputCallback?: DockerOutputCallback;
+}