@augment-vir/node 31.0.0 → 31.1.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);
+    }
+}

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

@@ -0,0 +1,51 @@
+import {check} from '@augment-vir/assert';
+import {runShellCommand} from '../../augments/terminal/shell.js';
+import {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

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

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

@@ -0,0 +1,92 @@
+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 {
+    DockerEnvMap,
+    DockerPortMap,
+    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

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

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

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

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

package/src/file-paths.mock.ts

@@ -0,0 +1,29 @@
+import {dirname, join} from 'node:path';
+
+export const monoRepoDirPath = dirname(dirname(dirname(import.meta.dirname)));
+export const notCommittedDirPath = join(monoRepoDirPath, '.not-committed');
+
+export const nodePackageDir = dirname(import.meta.dirname);
+
+export const testFilesDir = join(nodePackageDir, 'test-files');
+const longRunningFileDir = join(testFilesDir, 'long-running-test-file');
+export const dirContentsTestDir = join(testFilesDir, 'dir-contents-test');
+export const longRunningFilePath = join(longRunningFileDir, 'long-running-file.ts');
+export const longRunningFileWithStderr = join(
+    longRunningFileDir,
+    'long-running-file-with-stderr.ts',
+);
+export const workspaceQueryDir = join(testFilesDir, 'workspace-query');
+export const workspaceQueryPackageJsonPath = join(workspaceQueryDir, 'package.json');
+export const tempWorkspaceQueryFile = join(workspaceQueryDir, 'temp-workspace-query-output.ts');
+
+export const recursiveFileReadDir = join(testFilesDir, 'recursive-reading');
+
+export const invalidPackageDirPath = join(testFilesDir, 'invalid-package');
+
+export const testPrismaSchemaPath = join(testFilesDir, 'schema.prisma');
+export const testPrismaSchema2Path = join(testFilesDir, 'schema2.prisma');
+export const testInvalidPrismaSchemaPath = join(testFilesDir, 'invalid-schema.prisma');
+export const testSqliteDbPath = join(notCommittedDirPath, 'dev.db');
+export const generatedPrismaClientDirPath = join(nodePackageDir, 'node_modules', '.prisma');
+export const testPrismaMigrationsDirPath = join(testFilesDir, 'migrations');

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './augments/docker.js';
+export * from './augments/fs/dir-contents.js';
+export * from './augments/fs/download.js';
+export * from './augments/fs/json.js';
+export * from './augments/fs/read-dir.js';
+export * from './augments/fs/read-file.js';
+export * from './augments/fs/symlink.js';
+export * from './augments/fs/write.js';
+export * from './augments/npm/query-workspace.js';
+export * from './augments/npm/read-package-json.js';
+export * from './augments/os/operating-system.js';
+export * from './augments/path/ancestor.js';
+export * from './augments/path/os-path.js';
+export * from './augments/path/root.js';
+export * from './augments/prisma.js';
+export * from './augments/terminal/question.js';
+export * from './augments/terminal/relevant-args.js';
+export * from './augments/terminal/run-cli-script.js';
+export * from './augments/terminal/shell.js';