@augment-vir/node 31.0.1 → 31.1.1

package/src/augments/terminal/shell.ts

@@ -0,0 +1,312 @@
+import {combineErrors, log, type Logger} from '@augment-vir/common';
+import {type MaybePromise, PartialWithUndefined, RequiredAndNotNull} from '@augment-vir/core';
+import {ChildProcess, ExecException, spawn} from 'node:child_process';
+import {defineTypedCustomEvent, ListenTarget} from 'typed-event-target';
+
+/**
+ * All output from {@link runShellCommand}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type ShellOutput = {
+    error: undefined | Error;
+    stderr: string;
+    stdout: string;
+    exitCode: number | undefined;
+    exitSignal: NodeJS.Signals | undefined;
+};
+
+/**
+ * An event that indicates that the shell command just wrote to stdout.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class ShellStdoutEvent extends defineTypedCustomEvent<string | Buffer>()('shell-stdout') {}
+/**
+ * An event that indicates that the shell command just wrote to stderr.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class ShellStderrEvent extends defineTypedCustomEvent<string | Buffer>()('shell-stderr') {}
+/**
+ * An event that indicates that the shell command is finished. This contains an exit code or an exit
+ * signal. Based on the Node.js documentation, either one or the other is defined, never both at the
+ * same time.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class ShellDoneEvent extends defineTypedCustomEvent<{
+    exitCode: number | undefined;
+    exitSignal: NodeJS.Signals | undefined;
+}>()('shell-done') {}
+/**
+ * An event that indicates that the shell command errored.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class ShellErrorEvent extends defineTypedCustomEvent<Error>()('shell-error') {}
+
+/**
+ * A shell command listen target that emits events.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export class ShellTarget extends ListenTarget<
+    ShellStdoutEvent | ShellStderrEvent | ShellDoneEvent | ShellErrorEvent
+> {
+    constructor(public readonly childProcess: ChildProcess) {
+        super();
+    }
+}
+
+/**
+ * Runs a shell command and returns a {@link ShellTarget} instance for directly hooking into shell
+ * events. This allows instant reactions to shell events but in a less convenient API compared to
+ * {@link runShellCommand}.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ * - {@link runShellCommand}: a higher level and more succinct way of running a shell command.
+ */
+export function streamShellCommand(
+    command: string,
+    cwd?: string,
+    shell = 'bash',
+    env: NodeJS.ProcessEnv = process.env,
+    hookUpToConsole = false,
+): ShellTarget {
+    const stdio = hookUpToConsole ? [process.stdin] : undefined;
+
+    const childProcess = spawn(command, {shell, cwd, env, stdio});
+    const shellTarget = new ShellTarget(childProcess);
+
+    /** Type guards. */
+    /* node:coverage ignore next 5 */
+    if (!childProcess.stdout) {
+        throw new Error(`stdout emitter was not created by exec for some reason.`);
+    } else if (!childProcess.stderr) {
+        throw new Error(`stderr emitter was not created by exec for some reason.`);
+    }
+
+    childProcess.stdout.on('data', (chunk) => {
+        shellTarget.dispatch(new ShellStdoutEvent({detail: chunk}));
+    });
+    childProcess.stderr.on('data', (chunk) => {
+        shellTarget.dispatch(new ShellStderrEvent({detail: chunk}));
+    });
+
+    /** Idk how to trigger the 'error' event. */
+    /* node:coverage ignore next 3 */
+    childProcess.on('error', (error) => {
+        shellTarget.dispatch(new ShellErrorEvent({detail: error}));
+    });
+    /**
+     * Based on the Node.js documentation, we should listen to "close" instead of "exit" because the
+     * io streams will be finished when "close" emits. Also "close" always emits after "exit"
+     * anyway.
+     */
+    childProcess.on('close', (inputExitCode, inputExitSignal) => {
+        /** Idk how to control exitCode or exitSignal being null or not-null. */
+        /* node:coverage ignore next 2 */
+        const exitCode: number | undefined = inputExitCode ?? undefined;
+        const exitSignal: NodeJS.Signals | undefined = inputExitSignal ?? undefined;
+
+        if ((exitCode !== undefined && exitCode !== 0) || exitSignal !== undefined) {
+            const execException: ExecException & {cwd?: string | undefined} = new Error(
+                `Command failed: ${command}`,
+            );
+            execException.code = exitCode;
+            execException.signal = exitSignal;
+            execException.cmd = command;
+            execException.killed = childProcess.killed;
+            execException.cwd = cwd;
+            shellTarget.dispatch(new ShellErrorEvent({detail: execException}));
+        }
+        shellTarget.dispatch(
+            new ShellDoneEvent({
+                detail: {
+                    exitCode,
+                    exitSignal,
+                },
+            }),
+        );
+    });
+
+    return shellTarget;
+}
+
+/**
+ * Options for {@link runShellCommand}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type RunShellCommandOptions = {
+    cwd?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    shell?: string | undefined;
+    /** Automatically hook up stdout and stderr printing to the caller's console methods. */
+    hookUpToConsole?: boolean | undefined;
+    rejectOnError?: boolean | undefined;
+    /** Callback to call whenever the shell logs to stdout. */
+    stdoutCallback?: (stdout: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
+    /** Callback to call whenever the shell logs to stderr. */
+    stderrCallback?: (stderr: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
+};
+
+function prepareChunkForLogging(chunk: string | Buffer, trimEndingLine: boolean): string {
+    const stringified = chunk.toString();
+
+    return trimEndingLine ? stringified.replace(/\n$/, '') : stringified;
+}
+
+/**
+ * Runs a shell command and returns its output.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ * - {@link streamShellCommand}: a lower level way of running a shell command that allows instant reactions to shell events.
+ */
+export async function runShellCommand(
+    command: string,
+    options: RunShellCommandOptions = {},
+): Promise<ShellOutput> {
+    return new Promise<ShellOutput>((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        const errors: Error[] = [];
+
+        const shellTarget = streamShellCommand(
+            command,
+            options.cwd,
+            options.shell,
+            options.env,
+            options.hookUpToConsole,
+        );
+
+        shellTarget.listen(ShellStdoutEvent, ({detail: chunk}) => {
+            if (options.stdoutCallback) {
+                void options.stdoutCallback(
+                    prepareChunkForLogging(chunk, false),
+                    shellTarget.childProcess,
+                );
+            }
+            if (options.hookUpToConsole) {
+                process.stdout.write(prepareChunkForLogging(chunk, true) + '\n');
+            }
+            stdout += String(chunk);
+        });
+        shellTarget.listen(ShellStderrEvent, ({detail: chunk}) => {
+            if (options.stderrCallback) {
+                void options.stderrCallback(
+                    prepareChunkForLogging(chunk, false),
+                    shellTarget.childProcess,
+                );
+            }
+            if (options.hookUpToConsole) {
+                process.stderr.write(prepareChunkForLogging(chunk, true) + '\n');
+            }
+            stderr += String(chunk);
+        });
+        shellTarget.listen(ShellErrorEvent, ({detail: error}) => {
+            errors.push(error);
+            if (!options.rejectOnError) {
+                return;
+            }
+
+            /** Covering edge cases. */
+            /* node:coverage disable */
+            if (shellTarget.childProcess.connected) {
+                shellTarget.childProcess.disconnect();
+            }
+            if (
+                shellTarget.childProcess.exitCode == null &&
+                shellTarget.childProcess.signalCode == null &&
+                !shellTarget.childProcess.killed
+            ) {
+                shellTarget.childProcess.kill();
+            }
+            /* node:coverage enable */
+
+            shellTarget.destroy();
+
+            const rejectionErrorMessage: Error = combineErrors([new Error(stderr), ...errors]);
+            /** Reject now because the "done" listener won't get fired after killing the process. */
+            reject(rejectionErrorMessage);
+        });
+        shellTarget.listen(ShellDoneEvent, ({detail: {exitCode, exitSignal}}) => {
+            shellTarget.destroy();
+            resolve({
+                error: errors.length ? combineErrors(errors) : undefined,
+                stdout,
+                stderr,
+                exitCode,
+                exitSignal,
+            });
+        });
+    });
+}
+
+/**
+ * Options for {@link logShellOutput}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type LogShellOutputOptions = PartialWithUndefined<{
+    logger: Logger;
+    withLabels: boolean;
+    ignoreError: boolean;
+}>;
+
+const defaultLogShellOutputOptions: RequiredAndNotNull<LogShellOutputOptions> = {
+    ignoreError: false,
+    logger: log,
+    withLabels: false,
+};
+
+/**
+ * Log the output of running a shell command. This is useful for quick debugging of shell commands.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function logShellOutput(
+    shellOutput: PartialWithUndefined<Omit<ShellOutput, 'exitSignal'>>,
+    {
+        ignoreError = defaultLogShellOutputOptions.ignoreError,
+        logger = defaultLogShellOutputOptions.logger,
+        withLabels = defaultLogShellOutputOptions.withLabels,
+    }: LogShellOutputOptions = defaultLogShellOutputOptions,
+) {
+    logger.if(withLabels).info('exit code');
+    logger.if(shellOutput.exitCode != undefined || withLabels).plain(shellOutput.exitCode || 0);
+
+    logger.if(withLabels).info('stdout');
+    logger.if(!!shellOutput.stdout || withLabels).plain(shellOutput.stdout || '');
+
+    logger.if(withLabels).info('stderr');
+    logger.if(!!shellOutput.stderr || withLabels).error(shellOutput.stderr || '');
+
+    logger.if(withLabels && !ignoreError).info('error');
+    logger.if((!!shellOutput.error || withLabels) && !ignoreError).error(shellOutput.error);
+}

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

@@ -0,0 +1,83 @@
+import type {JsonCompatibleArray, 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 {@link getContainerInfo}.
+ *
+ * @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 {@link getContainerInfo}. 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

@@ -0,0 +1,110 @@
+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

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,119 @@
+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

@@ -0,0 +1,25 @@
+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);
+    }
+}