@augment-vir/node 31.43.3 → 31.44.0

package/src/docker/containers/docker-command-inputs.ts

@@ -1,122 +0,0 @@
-import {wrapString} from '@augment-vir/common';
-
-/**
- * Used for `type` in {@link DockerVolumeMap}. These types are apparently only relevant for running
- * Docker on macOS and are potentially irrelevant now. It's likely best to leave the `type` property
- * empty (`undefined`).
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export enum DockerVolumeMappingType {
-    Cached = 'cached',
-    Delegated = 'delegated',
-}
-
-/**
- * A mapping of a single docker volume for mounting host files to a container.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type DockerVolumeMap = {
-    hostAbsolutePath: string;
-    containerAbsolutePath: string;
-    type?: DockerVolumeMappingType | undefined;
-};
-
-export function makeVolumeFlags(volumeMapping?: ReadonlyArray<DockerVolumeMap>): string {
-    if (!volumeMapping) {
-        return '';
-    }
-
-    const parts = volumeMapping.map((volume) => {
-        const mountType = volume.type ? `:${volume.type}` : '';
-        return `-v '${volume.hostAbsolutePath}':'${volume.containerAbsolutePath}'${mountType}`;
-    });
-
-    return parts.join(' ');
-}
-/**
- * A single docker container port mapping. This is usually used in an array.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type DockerPortMap = {
-    hostPort: number;
-    containerPort: number;
-};
-
-/**
- * A set of environment mappings for a docker container.
- *
- * - Each key in this object represents the env var name within the Docker container.
- * - Each `value` property can be either the value that the env var should be set to _or_ an existing
- *   env var's interpolation into the value.
- * - If the value string is meant to be interpolated within the shell context, make sure to set
- *   `allowInterpolation` to `true`. Otherwise, it's best to leave it as `false`.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @example
- *
- * ```ts
- * const envMapping: DockerEnvMap = {
- *     VAR_1: {
- *         value: 'hi',
- *         // set to false because this is a raw string value that is not meant to be interpolated
- *         allowInterpolation: false,
- *     },
- *     VAR_2: {
- *         // the value here will be interpolated from the current shell's value for `EXISTING_VAR`
- *         value: '$EXISTING_VAR',
- *         // set to true to allow '$EXISTING_VAR' to be interpolated by the shell
- *         allowInterpolation: true,
- *     },
- * };
- * ```
- *
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type DockerEnvMap<RequiredKeys extends string = string> = Readonly<
-    Record<
-        RequiredKeys | string,
-        {
-            value: string;
-            allowInterpolation: boolean;
-        }
-    >
->;
-
-export function makePortMapFlags(portMapping?: ReadonlyArray<DockerPortMap> | undefined): string {
-    if (!portMapping) {
-        return '';
-    }
-
-    return portMapping
-        .map((portMap) => {
-            return `-p ${portMap.hostPort}:${portMap.containerPort}`;
-        })
-        .join(' ');
-}
-
-export function makeEnvFlags(envMapping?: DockerEnvMap | undefined): string {
-    if (!envMapping) {
-        return '';
-    }
-    const flags: ReadonlyArray<string> = Object.entries(envMapping).map(
-        ([
-            key,
-            {value, allowInterpolation},
-        ]) => {
-            const quote = allowInterpolation ? '"' : "'";
-            return `-e ${key}=${wrapString({value, wrapper: quote})}`;
-        },
-    );
-
-    return flags.join(' ');
-}

package/src/docker/containers/kill-container.ts

@@ -1,25 +0,0 @@
-import {type PartialWithUndefined} from '@augment-vir/core';
-import {runShellCommand} from '../../augments/terminal/shell.js';
-import {waitUntilContainerExited, waitUntilContainerRemoved} from './container-status.js';
-
-export async function killContainer(
-    containerNameOrId: string,
-    options: PartialWithUndefined<{
-        /**
-         * If set to `true`, the container will be killed but won't be removed. (You'll still see it
-         * in your Docker Dashboard but it'll have a status of exited.)
-         *
-         * @default false
-         */
-        keepContainer: boolean;
-    }> = {},
-): Promise<void> {
-    await runShellCommand(`docker kill '${containerNameOrId}'`);
-
-    if (options.keepContainer) {
-        await waitUntilContainerExited(containerNameOrId);
-    } else {
-        await runShellCommand(`docker rm '${containerNameOrId}'`);
-        await waitUntilContainerRemoved(containerNameOrId);
-    }
-}

package/src/docker/containers/run-command.ts

@@ -1,51 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {runShellCommand} from '../../augments/terminal/shell.js';
-import {type DockerEnvMap, makeEnvFlags} from './docker-command-inputs.js';
-
-/**
- * Parameters for `docker.container.runCommand`.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type RunDockerContainerCommandParams = {
-    /** Creates an interactive shell connection. */
-    tty?: boolean | undefined;
-    containerNameOrId: string;
-    command: string;
-    envMapping?: DockerEnvMap | undefined;
-    executionEnv?: Record<string, string> | undefined;
-    dockerFlags?: ReadonlyArray<string> | undefined;
-};
-
-export async function runContainerCommand({
-    tty,
-    containerNameOrId,
-    command,
-    envMapping,
-    executionEnv,
-    dockerFlags = [],
-}: RunDockerContainerCommandParams) {
-    const envFlags = makeEnvFlags(envMapping);
-    /** Can't test tty in automated tests. */
-    /* node:coverage ignore next 1 */
-    const ttyFlag = tty ? '-it' : '';
-
-    const fullCommand = [
-        'docker',
-        'exec',
-        ttyFlag,
-        envFlags,
-        ...dockerFlags,
-        containerNameOrId,
-        command,
-    ]
-        .filter(check.isTruthy)
-        .join(' ');
-
-    return await runShellCommand(fullCommand, {
-        env: executionEnv,
-        rejectOnError: true,
-    });
-}

package/src/docker/containers/run-container.mock.ts

@@ -1,22 +0,0 @@
-/* eslint-disable @typescript-eslint/no-deprecated */
-
-import {docker} from '../../augments/docker.js';
-import {type RunDockerContainerParams} from './run-container.js';
-
-export async function runMockLongLivingContainer(
-    containerName: string,
-    args: Partial<RunDockerContainerParams> = {},
-) {
-    await docker.container.run({
-        containerName,
-        detach: true,
-        imageName: 'alpine:3.20.2',
-        dockerFlags: [
-            '-i',
-            '-t',
-        ],
-        command: 'sh',
-        platform: 'amd64',
-        ...args,
-    });
-}

package/src/docker/containers/run-container.ts

@@ -1,92 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {runShellCommand} from '../../augments/terminal/shell.js';
-import {updateImage} from '../docker-image.js';
-import {waitUntilContainerRunning} from './container-status.js';
-import {
-    type DockerEnvMap,
-    type DockerPortMap,
-    type DockerVolumeMap,
-    makeEnvFlags,
-    makePortMapFlags,
-    makeVolumeFlags,
-} from './docker-command-inputs.js';
-import {killContainer} from './kill-container.js';
-
-/**
- * Parameters for `docker.container.run`.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type RunDockerContainerParams = {
-    imageName: string;
-    detach: boolean;
-    command?: string;
-    containerName: string;
-    volumeMapping?: ReadonlyArray<DockerVolumeMap> | undefined;
-    portMapping?: ReadonlyArray<DockerPortMap> | undefined;
-    envMapping?: DockerEnvMap | undefined;
-    executionEnv?: Record<string, string>;
-    removeWhenDone?: boolean;
-    dockerFlags?: ReadonlyArray<string>;
-    useCurrentUser?: boolean;
-    platform?: string;
-};
-
-export async function runContainer({
-    containerName,
-    imageName,
-    detach,
-    command,
-    portMapping,
-    volumeMapping,
-    envMapping,
-    executionEnv,
-    removeWhenDone,
-    useCurrentUser,
-    dockerFlags = [],
-    platform,
-}: RunDockerContainerParams) {
-    try {
-        const portMapFlags = makePortMapFlags(portMapping);
-        const envFlags = makeEnvFlags(envMapping);
-        const detachFlag = detach ? '-d' : '';
-        const volumeMapFlags = makeVolumeFlags(volumeMapping);
-        const rmFlag = removeWhenDone ? '--rm' : '';
-        const userFlag = useCurrentUser ? '--user "$(id -u)":"$(id -g)"' : '';
-
-        await updateImage(imageName, platform);
-
-        const fullCommand = [
-            'docker',
-            'run',
-            portMapFlags,
-            userFlag,
-            volumeMapFlags,
-            envFlags,
-            rmFlag,
-            detachFlag,
-            `--name='${containerName}'`,
-            ...dockerFlags,
-            imageName,
-            command,
-        ]
-            .filter(check.isTruthy)
-            .join(' ');
-
-        await runShellCommand(fullCommand, {
-            env: executionEnv,
-            rejectOnError: true,
-        });
-
-        if (removeWhenDone) {
-            await killContainer(containerName);
-        } else if (detach) {
-            await waitUntilContainerRunning(containerName);
-        }
-    } catch (error) {
-        await killContainer(containerName);
-        throw error;
-    }
-}

package/src/docker/containers/try-or-kill-container.ts

@@ -1,18 +0,0 @@
-import {type MaybePromise} from '@augment-vir/core';
-import {killContainer} from './kill-container.js';
-
-/**
- * Runs a callback (which presumably runs a command within the given `containerName`) and kills the
- * given `containerName` container if the callback fails.
- */
-export async function tryOrKillContainer<T>(
-    containerNameOrId: string,
-    callback: (containerNameOrId: string) => MaybePromise<T>,
-): Promise<Awaited<T>> {
-    try {
-        return await callback(containerNameOrId);
-    } catch (error) {
-        await killContainer(containerNameOrId);
-        throw error;
-    }
-}

package/src/docker/docker-image.ts

@@ -1,61 +0,0 @@
-import {wrapString} from '@augment-vir/common';
-import {ensureError} from '@augment-vir/core';
-import {runShellCommand} from '../augments/terminal/shell.js';
-
-export async function updateImage(
-    /** @example 'alpine:3.20.2' */
-    imageName: string,
-    platform?: string,
-) {
-    if (await isImageInLocalRegistry(imageName)) {
-        /** If image already exists then we don't need to update it. */
-        return;
-    }
-
-    const command = [
-        'docker',
-        'pull',
-        ...(platform
-            ? [
-                  '--platform',
-                  platform,
-              ]
-            : []),
-        wrapString({value: imageName, wrapper: "'"}),
-    ].join(' ');
-
-    await runShellCommand(command, {
-        rejectOnError: true,
-    });
-}
-
-export async function isImageInLocalRegistry(
-    /** @example 'alpine:3.20.2' */
-    imageName: string,
-): Promise<boolean> {
-    const output = await runShellCommand(`docker inspect '${imageName}'`);
-
-    return output.exitCode === 0;
-}
-
-export async function removeImageFromLocalRegistry(
-    /** @example 'alpine:3.20.2' */
-    imageName: string,
-) {
-    try {
-        await runShellCommand(`docker image rm '${imageName}'`, {
-            rejectOnError: true,
-        });
-    } catch (caught) {
-        const error = ensureError(caught);
-
-        if (error.message.includes('No such image:')) {
-            /** Ignore the case where the image has already been deleted. */
-            return;
-        }
-
-        /** An edge case that I don't know how to intentionally trigger. */
-        /* node:coverage ignore next 2 */
-        throw error;
-    }
-}

package/src/docker/docker-startup.ts

@@ -1,49 +0,0 @@
-import {waitUntil} from '@augment-vir/assert';
-import {currentOperatingSystem, OperatingSystem} from '../augments/os/operating-system.js';
-import {runShellCommand} from '../augments/terminal/shell.js';
-
-export async function isDockerRunning() {
-    const output = await runShellCommand('docker info');
-
-    return output.exitCode === 0;
-}
-
-const startDockerCommands: Record<OperatingSystem, string> = {
-    /**
-     * Officially supported for the following distros:
-     *
-     * - [Ubuntu](https://docs.docker.com/desktop/install/ubuntu/#launch-docker-desktop)
-     * - [Debian](https://docs.docker.com/desktop/install/debian/#launch-docker-desktop)
-     * - [Fedora](https://docs.docker.com/desktop/install/fedora/#launch-docker-desktop)
-     * - [Arch](https://docs.docker.com/desktop/install/archlinux/#launch-docker-desktop)
-     */
-    [OperatingSystem.Linux]: 'systemctl --user start docker-desktop',
-    [OperatingSystem.Mac]: 'open -a Docker',
-    [OperatingSystem.Windows]: String.raw`/c/Program\ Files/Docker/Docker/Docker\ Desktop.exe`,
-};
-
-export async function startDocker() {
-    const command = startDockerCommands[currentOperatingSystem];
-
-    /* node:coverage disable */
-    if (await isDockerRunning()) {
-        /** Docker is already running. Nothing to do. */
-        return;
-    }
-
-    await waitUntil.isTrue(
-        async () => {
-            await runShellCommand(command, {rejectOnError: true});
-            return isDockerRunning();
-        },
-        {
-            interval: {
-                seconds: 1,
-            },
-            timeout: {
-                minutes: 1,
-            },
-        },
-        'Failed to start Docker.',
-    );
-}

package/src/docker/run-docker-test.mock.ts

@@ -1,26 +0,0 @@
-import {type MaybePromise} from '@augment-vir/common';
-import {isOperatingSystem, OperatingSystem} from '../augments/os/operating-system.js';
-
-export function dockerTest(callback: () => MaybePromise<void>) {
-    if (!isOperatingSystem(OperatingSystem.Linux) && process.env.CI) {
-        /**
-         * We cannot test Docker on macOS GitHub Actions runners.
-         *
-         * @see
-         * - https://github.com/actions/runner-images/issues/8104
-         * - https://github.com/douglascamata/setup-docker-macos-action?tab=readme-ov-file#arm64-processors-m1-m2-m3-series-used-on-macos-14-images-are-unsupported
-         * - https://github.com/actions/runner-images/issues/2150
-         * - https://github.com/actions/runner/issues/1456
-         */
-        /**
-         * We cannot test Docker on Windows GitHub Actions runners because Docker cannot run in
-         * Linux container mode on Windows GitHub Actions runners.
-         *
-         * @see
-         * - https://github.com/orgs/community/discussions/25491#discussioncomment-3248089
-         */
-        return () => {};
-    }
-
-    return callback;
-}