@augment-vir/node 31.43.2 → 31.44.0

package/dist/docker/containers/run-command.js

@@ -1,24 +0,0 @@
-import { check } from '@augment-vir/assert';
-import { runShellCommand } from '../../augments/terminal/shell.js';
-import { makeEnvFlags } from './docker-command-inputs.js';
-export async function runContainerCommand({ tty, containerNameOrId, command, envMapping, executionEnv, dockerFlags = [], }) {
-    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/dist/docker/containers/run-container.d.ts

@@ -1,23 +0,0 @@
-import { type DockerEnvMap, type DockerPortMap, type DockerVolumeMap } from './docker-command-inputs.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 declare function runContainer({ containerName, imageName, detach, command, portMapping, volumeMapping, envMapping, executionEnv, removeWhenDone, useCurrentUser, dockerFlags, platform, }: RunDockerContainerParams): Promise<void>;

package/dist/docker/containers/run-container.js

@@ -1,47 +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 { makeEnvFlags, makePortMapFlags, makeVolumeFlags, } from './docker-command-inputs.js';
-import { killContainer } from './kill-container.js';
-export async function runContainer({ containerName, imageName, detach, command, portMapping, volumeMapping, envMapping, executionEnv, removeWhenDone, useCurrentUser, dockerFlags = [], platform, }) {
-    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/dist/docker/containers/run-container.mock.d.ts

@@ -1,2 +0,0 @@
-import { type RunDockerContainerParams } from './run-container.js';
-export declare function runMockLongLivingContainer(containerName: string, args?: Partial<RunDockerContainerParams>): Promise<void>;

package/dist/docker/containers/run-container.mock.js

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

package/dist/docker/containers/try-or-kill-container.d.ts

@@ -1,6 +0,0 @@
-import { type MaybePromise } from '@augment-vir/core';
-/**
- * Runs a callback (which presumably runs a command within the given `containerName`) and kills the
- * given `containerName` container if the callback fails.
- */
-export declare function tryOrKillContainer<T>(containerNameOrId: string, callback: (containerNameOrId: string) => MaybePromise<T>): Promise<Awaited<T>>;

package/dist/docker/containers/try-or-kill-container.js

@@ -1,14 +0,0 @@
-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(containerNameOrId, callback) {
-    try {
-        return await callback(containerNameOrId);
-    }
-    catch (error) {
-        await killContainer(containerNameOrId);
-        throw error;
-    }
-}

package/dist/docker/docker-image.d.ts

@@ -1,9 +0,0 @@
-export declare function updateImage(
-/** @example 'alpine:3.20.2' */
-imageName: string, platform?: string): Promise<void>;
-export declare function isImageInLocalRegistry(
-/** @example 'alpine:3.20.2' */
-imageName: string): Promise<boolean>;
-export declare function removeImageFromLocalRegistry(
-/** @example 'alpine:3.20.2' */
-imageName: string): Promise<void>;

package/dist/docker/docker-image.js

@@ -1,50 +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, platform) {
-    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) {
-    const output = await runShellCommand(`docker inspect '${imageName}'`);
-    return output.exitCode === 0;
-}
-export async function removeImageFromLocalRegistry(
-/** @example 'alpine:3.20.2' */
-imageName) {
-    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/dist/docker/docker-startup.d.ts

@@ -1,2 +0,0 @@
-export declare function isDockerRunning(): Promise<boolean>;
-export declare function startDocker(): Promise<void>;

package/dist/docker/docker-startup.js

@@ -1,39 +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 = {
-    /**
-     * 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/dist/docker/run-docker-test.mock.d.ts

@@ -1,2 +0,0 @@
-import { type MaybePromise } from '@augment-vir/common';
-export declare function dockerTest(callback: () => MaybePromise<void>): () => MaybePromise<void>;

package/dist/docker/run-docker-test.mock.js

@@ -1,23 +0,0 @@
-import { isOperatingSystem, OperatingSystem } from '../augments/os/operating-system.js';
-export function dockerTest(callback) {
-    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;
-}

package/src/augments/docker.ts

@@ -1,119 +0,0 @@
-import {getContainerInfo} from '../docker/containers/container-info.js';
-import {
-    getContainerLogs,
-    getContainerStatus,
-    waitUntilContainerExited,
-    waitUntilContainerRemoved,
-    waitUntilContainerRunning,
-} from '../docker/containers/container-status.js';
-import {copyToContainer} from '../docker/containers/copy-to-container.js';
-import {
-    makeEnvFlags,
-    makePortMapFlags,
-    makeVolumeFlags,
-} from '../docker/containers/docker-command-inputs.js';
-import {killContainer} from '../docker/containers/kill-container.js';
-import {runContainerCommand} from '../docker/containers/run-command.js';
-import {runContainer} from '../docker/containers/run-container.js';
-import {tryOrKillContainer} from '../docker/containers/try-or-kill-container.js';
-import {
-    isImageInLocalRegistry,
-    removeImageFromLocalRegistry,
-    updateImage,
-} from '../docker/docker-image.js';
-import {isDockerRunning, startDocker} from '../docker/docker-startup.js';
-
-export {
-    type DockerContainerInfo,
-    type DockerContainerInfoState,
-} from '../docker/containers/container-info.js';
-export {
-    DockerContainerStatus,
-    exitedDockerContainerStatuses,
-} from '../docker/containers/container-status.js';
-export {type CopyToDockerContainerParams} from '../docker/containers/copy-to-container.js';
-export {
-    type DockerEnvMap,
-    type DockerPortMap,
-    type DockerVolumeMap,
-    type DockerVolumeMappingType,
-} from '../docker/containers/docker-command-inputs.js';
-export {type RunDockerContainerCommandParams} from '../docker/containers/run-command.js';
-export {type RunDockerContainerParams} from '../docker/containers/run-container.js';
-
-/**
- * Centralized Docker API.
- *
- * @deprecated Use the [docker-vir](https://www.npmjs.com/package/docker-vir) package instead.
- * @category Node : Docker
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export const docker = {
-    /** Detects if the Docker service is running. */
-    isRunning: isDockerRunning,
-    /**
-     * Tries to start Docker based ont he current operating system's supported commands. The success
-     * of this operation is heavily dependent on how you have Docker setup on your system.
-     */
-    start: startDocker,
-    image: {
-        /** Downloads an image if it is missing from the local registry. */
-        update: updateImage,
-        /** Removes an image from the local registry. */
-        remove: removeImageFromLocalRegistry,
-        /** Detects if an image exists in the local registry. */
-        exists: isImageInLocalRegistry,
-    },
-    container: {
-        /**
-         * Get the current status of a container. If the container does not exist at all, the status
-         * will be {@link DockerContainerStatus.Removed}.
-         */
-        getStatus: getContainerStatus,
-        /** Wait until a container is running and responsive. */
-        waitUntilRunning: waitUntilContainerRunning,
-        /**
-         * Wait until a container has a status that can be classified as "exited".
-         *
-         * @see {@link exitedDockerContainerStatuses}
-         */
-        waitUntilExited: waitUntilContainerExited,
-        /** Wait until a container is completely removed. */
-        waitUntilRemoved: waitUntilContainerRemoved,
-        /**
-         * Runs a callback (which presumably will run a command within the given `containerName`)
-         * and kills the container if the callback fails.
-         */
-        tryOrKill: tryOrKillContainer,
-        /** Run a container that isn't already running. */
-        run: runContainer,
-        /** Kill a container. */
-        kill: killContainer,
-        /** Copy a file or directory to a container. */
-        copyTo: copyToContainer,
-        /** Run a command on a container that is already running. */
-        runCommand: runContainerCommand,
-        /** Run `docker inspect` on a container and return its output. */
-        getInfo: getContainerInfo,
-        /** Get a container's logs. */
-        getLogs: getContainerLogs,
-    },
-    util: {
-        /**
-         * Manually create a string of volume mapping flags. This is automatically done already
-         * inside the run container methods.
-         */
-        makeVolumeFlags,
-        /**
-         * Manually create a string of port mapping flags. This is automatically done already inside
-         * the run container methods.
-         */
-        makePortMapFlags,
-        /**
-         * Manually create a string of env mapping flags. This is automatically done already inside
-         * the run container methods.
-         */
-        makeEnvFlags,
-    },
-};

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

@@ -1,83 +0,0 @@
-import {type JsonCompatibleArray, type JsonCompatibleObject} from '@augment-vir/common';
-import {runShellCommand} from '../../augments/terminal/shell.js';
-import {type DockerContainerStatus} from './container-status.js';
-
-/**
- * Properties on {@link DockerContainerInfo}.State, retrieved from `docker.container.getInfo()`.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type DockerContainerInfoState = {
-    Status: DockerContainerStatus;
-    Running: boolean;
-    Paused: boolean;
-    Restarting: boolean;
-    OOMKilled: boolean;
-    Dead: boolean;
-    Pid: number;
-    ExitCode: number;
-    Error: string;
-    StartedAt: string;
-    FinishedAt: string;
-};
-
-/** This type signature is incomplete. Add to it as necessary. */
-
-/**
- * Properties on the output from `docker.container.getInfo()`. Not all these properties are filled
- * in all the way, particularly most of properties with nested objects.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type DockerContainerInfo = Readonly<{
-    Id: string;
-    Created: string;
-    Path: string;
-    Args: ReadonlyArray<string>;
-    State: DockerContainerInfoState;
-    Image: string;
-    ResolvConfPath: string;
-    HostnamePath: string;
-    HostsPath: string;
-    LogPath: string;
-    Name: string;
-    RestartCount: number;
-    Driver: string;
-    Platform: string;
-    MountLabel: string;
-    ProcessLabel: string;
-    AppArmorProfile: string;
-    ExecIDs: unknown;
-    HostConfig: JsonCompatibleObject;
-    GraphDriver: JsonCompatibleObject;
-    Mounts: JsonCompatibleArray;
-    Config: JsonCompatibleObject;
-    NetworkSettings: JsonCompatibleObject;
-}>;
-
-export async function getContainerInfo(
-    containerNameOrId: string,
-): Promise<DockerContainerInfo | undefined> {
-    const command = `docker inspect '${containerNameOrId}'`;
-    const output = await runShellCommand(command);
-
-    if (output.stderr.includes('Error: No such object')) {
-        return undefined;
-    }
-
-    const parsedOutput = JSON.parse(output.stdout) as ReadonlyArray<DockerContainerInfo>;
-
-    /** Edge cases that I don't know how to intentionally trigger. */
-    /* node:coverage ignore next 5 */
-    if (parsedOutput.length === 0) {
-        throw new Error(`Got no output from "${command}"`);
-    } else if (parsedOutput.length > 1) {
-        throw new Error(`Got more than one output from "${command}"`);
-    }
-
-    return parsedOutput[0];
-}

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

@@ -1,110 +0,0 @@
-import {assert, waitUntil} from '@augment-vir/assert';
-import {runShellCommand} from '../../augments/terminal/shell.js';
-
-export async function getContainerLogs(
-    containerNameOrId: string,
-    latestLineCount?: number,
-): Promise<string> {
-    const latestLinesArg = latestLineCount == undefined ? '' : `--tail ${latestLineCount}`;
-    const logResult = await runShellCommand(
-        `docker logs ${latestLinesArg} '${containerNameOrId}'`,
-        {rejectOnError: true},
-    );
-    return logResult.stdout;
-}
-
-/**
- * All possible statuses for an existing container.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export enum DockerContainerStatus {
-    Created = 'created',
-    Running = 'running',
-    Paused = 'paused',
-    Restarting = 'restarting',
-    Exited = 'exited',
-    Removing = 'removing',
-    Dead = 'dead',
-
-    /** This is not a native Docker status but indicates that the container does not exist. */
-    Removed = 'removed',
-}
-
-/**
- * Statuses from {@link DockerContainerStatus} that indicate that a container has been exited in some
- * way.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export const exitedDockerContainerStatuses = [
-    DockerContainerStatus.Dead,
-    DockerContainerStatus.Removed,
-    DockerContainerStatus.Exited,
-];
-
-export async function getContainerStatus(
-    containerNameOrId: string,
-): Promise<DockerContainerStatus> {
-    const statusResult = await runShellCommand(
-        `docker container inspect -f '{{.State.Status}}' '${containerNameOrId}'`,
-    );
-
-    if (statusResult.exitCode !== 0) {
-        return DockerContainerStatus.Removed;
-    }
-
-    const status = statusResult.stdout.trim();
-    assert.isEnumValue(status, DockerContainerStatus, 'Unexpected container status value');
-
-    return status;
-}
-
-export async function waitUntilContainerRunning(
-    containerNameOrId: string,
-    failureMessage?: string | undefined,
-): Promise<void> {
-    await waitUntil.isTrue(
-        async (): Promise<boolean> => {
-            /** Check if logs can be accessed yet. */
-            await getContainerLogs(containerNameOrId, 1);
-            const status = await getContainerStatus(containerNameOrId);
-
-            return status === DockerContainerStatus.Running;
-        },
-        {},
-        failureMessage,
-    );
-}
-
-export async function waitUntilContainerRemoved(
-    containerNameOrId: string,
-    failureMessage?: string | undefined,
-): Promise<void> {
-    await waitUntil.isTrue(
-        async (): Promise<boolean> => {
-            const status = await getContainerStatus(containerNameOrId);
-            return status === DockerContainerStatus.Removed;
-        },
-        {},
-        failureMessage,
-    );
-}
-
-export async function waitUntilContainerExited(
-    containerNameOrId: string,
-    failureMessage?: string | undefined,
-): Promise<void> {
-    await waitUntil.isTrue(
-        async (): Promise<boolean> => {
-            const status = await getContainerStatus(containerNameOrId);
-            return exitedDockerContainerStatuses.includes(status);
-        },
-        {},
-        failureMessage,
-    );
-}

package/src/docker/containers/copy-to-container.ts

@@ -1,34 +0,0 @@
-import {addSuffix} from '@augment-vir/common';
-import {stat} from 'node:fs/promises';
-import {runShellCommand} from '../../augments/terminal/shell.js';
-
-/**
- * Parameters for `docker.container.copyTo`.
- *
- * @category Node : Docker : Util
- * @category Package : @augment-vir/node
- * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
- */
-export type CopyToDockerContainerParams = {
-    hostPath: string;
-    containerAbsolutePath: string;
-    containerNameOrId: string;
-    dockerFlags?: ReadonlyArray<string>;
-};
-
-export async function copyToContainer({
-    containerAbsolutePath,
-    hostPath,
-    containerNameOrId,
-    dockerFlags = [],
-}: CopyToDockerContainerParams): Promise<void> {
-    const isDir = (await stat(hostPath)).isDirectory();
-    const suffix = isDir ? '/.' : '';
-    const fullHostPath = addSuffix({value: hostPath, suffix});
-    const extraInputs: string = dockerFlags.join(' ');
-
-    await runShellCommand(
-        `docker cp ${extraInputs} '${fullHostPath}' '${containerNameOrId}:${containerAbsolutePath}'`,
-        {rejectOnError: true},
-    );
-}