@augment-vir/node 31.43.3 → 31.45.0

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},
-    );
-}

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;
-    }
-}