@augment-vir/node 30.0.0

package/dist/augments/path/os-path.js

@@ -0,0 +1,27 @@
+import { sep } from 'node:path';
+/** Convert a given path to a windows path if the current system doesn't use `/`. */
+export function replaceWithWindowsPathIfNeeded(input) {
+    if (sep === '/') {
+        return input;
+        /** Can't test on Windows. */
+        /* node:coverage ignore next 3 */
+    }
+    else {
+        return input.replace(/\//g, sep);
+    }
+}
+/** Convert a Windows path to a posix path. */
+export function toPosixPath(maybeWindowsPath) {
+    return maybeWindowsPath
+        .replace(/^(.+?):\\+/, (match, captureGroup) => {
+        return `/${captureGroup.toLowerCase()}/`;
+    })
+        .replace(/\\+/g, '/');
+}
+/**
+ * Use this to interpolate paths into bash commands. If the given path is not a window path, the
+ * path structure will not be modified.
+ */
+export function interpolationSafeWindowsPath(input) {
+    return input.replace(/\\/g, '\\\\\\\\');
+}

package/dist/augments/path/root.d.ts

@@ -0,0 +1 @@
+export declare const systemRootPath: string;

package/dist/augments/path/root.js

@@ -0,0 +1,5 @@
+import { parse } from 'node:path';
+function getSystemRootPath() {
+    return parse(process.cwd()).root;
+}
+export const systemRootPath = getSystemRootPath();

package/dist/augments/prisma.d.ts

@@ -0,0 +1,21 @@
+import { generatePrismaClient, isGeneratedPrismaClientCurrent } from '../prisma/prisma-client.js';
+import { doesPrismaDiffExist, getPrismaDiff, resetDevPrismaDatabase } from '../prisma/prisma-database.js';
+import { applyPrismaMigrationsToDev, applyPrismaMigrationsToProd, createPrismaMigration, getMigrationStatus } from '../prisma/prisma-migrations.js';
+/** Centralized Prisma API from `@augment-vir/node`. */
+export declare const prisma: {
+    migration: {
+        status: typeof getMigrationStatus;
+        create: typeof createPrismaMigration;
+        applyProd: typeof applyPrismaMigrationsToProd;
+        applyDev: typeof applyPrismaMigrationsToDev;
+    };
+    database: {
+        resetDev: typeof resetDevPrismaDatabase;
+        hasDiff: typeof doesPrismaDiffExist;
+        diff: typeof getPrismaDiff;
+    };
+    client: {
+        generate: typeof generatePrismaClient;
+        isCurrent: typeof isGeneratedPrismaClientCurrent;
+    };
+};

package/dist/augments/prisma.js

@@ -0,0 +1,21 @@
+import { generatePrismaClient, isGeneratedPrismaClientCurrent } from '../prisma/prisma-client.js';
+import { doesPrismaDiffExist, getPrismaDiff, resetDevPrismaDatabase, } from '../prisma/prisma-database.js';
+import { applyPrismaMigrationsToDev, applyPrismaMigrationsToProd, createPrismaMigration, getMigrationStatus, } from '../prisma/prisma-migrations.js';
+/** Centralized Prisma API from `@augment-vir/node`. */
+export const prisma = {
+    migration: {
+        status: getMigrationStatus,
+        create: createPrismaMigration,
+        applyProd: applyPrismaMigrationsToProd,
+        applyDev: applyPrismaMigrationsToDev,
+    },
+    database: {
+        resetDev: resetDevPrismaDatabase,
+        hasDiff: doesPrismaDiffExist,
+        diff: getPrismaDiff,
+    },
+    client: {
+        generate: generatePrismaClient,
+        isCurrent: isGeneratedPrismaClientCurrent,
+    },
+};

package/dist/augments/shell.d.ts

@@ -0,0 +1,87 @@
+import { type Logger } from '@augment-vir/common';
+import type { MaybePromise, PartialWithUndefined } from '@augment-vir/core';
+import { ChildProcess } from 'node:child_process';
+import { ListenTarget } from 'typed-event-target';
+export type ShellOutput = {
+    error: undefined | Error;
+    stderr: string;
+    stdout: string;
+    exitCode: number | undefined;
+    exitSignal: NodeJS.Signals | undefined;
+};
+declare const ShellStdoutEvent_base: (new (eventInitDict: import("typed-event-target").TypedCustomEventInit<string | Buffer>) => import("typed-event-target").TypedCustomEvent<string | Buffer, "shell-stdout">) & Pick<{
+    new (type: string, eventInitDict?: EventInit | undefined): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedCustomEvent<string | Buffer, "shell-stdout">, "type">;
+export declare class ShellStdoutEvent extends ShellStdoutEvent_base {
+}
+declare const ShellStderrEvent_base: (new (eventInitDict: import("typed-event-target").TypedCustomEventInit<string | Buffer>) => import("typed-event-target").TypedCustomEvent<string | Buffer, "shell-stderr">) & Pick<{
+    new (type: string, eventInitDict?: EventInit | undefined): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedCustomEvent<string | Buffer, "shell-stderr">, "type">;
+export declare class ShellStderrEvent extends ShellStderrEvent_base {
+}
+declare const ShellDoneEvent_base: (new (eventInitDict: import("typed-event-target").TypedCustomEventInit<{
+    exitCode: number | undefined;
+    exitSignal: NodeJS.Signals | undefined;
+}>) => import("typed-event-target").TypedCustomEvent<{
+    exitCode: number | undefined;
+    exitSignal: NodeJS.Signals | undefined;
+}, "shell-done">) & Pick<{
+    new (type: string, eventInitDict?: EventInit | undefined): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedCustomEvent<{
+    exitCode: number | undefined;
+    exitSignal: NodeJS.Signals | undefined;
+}, "shell-done">, "type">;
+/**
+ * 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.
+ */
+export declare class ShellDoneEvent extends ShellDoneEvent_base {
+}
+declare const ShellErrorEvent_base: (new (eventInitDict: import("typed-event-target").TypedCustomEventInit<Error>) => import("typed-event-target").TypedCustomEvent<Error, "shell-error">) & Pick<{
+    new (type: string, eventInitDict?: EventInit | undefined): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedCustomEvent<Error, "shell-error">, "type">;
+export declare class ShellErrorEvent extends ShellErrorEvent_base {
+}
+export declare class ShellTarget extends ListenTarget<ShellStdoutEvent | ShellStderrEvent | ShellDoneEvent | ShellErrorEvent> {
+    readonly childProcess: ChildProcess;
+    constructor(childProcess: ChildProcess);
+}
+export declare function streamShellCommand(command: string, cwd?: string, shell?: string, env?: NodeJS.ProcessEnv, hookUpToConsole?: boolean): ShellTarget;
+export type RunShellCommandParams = {
+    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;
+    stdoutCallback?: (stdout: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
+    stderrCallback?: (stderr: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
+};
+export declare function runShellCommand(command: string, options?: RunShellCommandParams): Promise<ShellOutput>;
+export type LogShellOutputOptions = PartialWithUndefined<{
+    logger: Logger;
+    withLabels: boolean;
+    ignoreError: boolean;
+}>;
+export declare function logShellOutput(shellOutput: PartialWithUndefined<Omit<ShellOutput, 'exitSignal'>>, { ignoreError, logger, withLabels, }?: LogShellOutputOptions): void;
+export {};

package/dist/augments/shell.js

@@ -0,0 +1,152 @@
+import { combineErrors, log } from '@augment-vir/common';
+import { spawn } from 'node:child_process';
+import { defineTypedCustomEvent, ListenTarget } from 'typed-event-target';
+export class ShellStdoutEvent extends defineTypedCustomEvent()('shell-stdout') {
+}
+export class ShellStderrEvent extends defineTypedCustomEvent()('shell-stderr') {
+}
+/**
+ * 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.
+ */
+export class ShellDoneEvent extends defineTypedCustomEvent()('shell-done') {
+}
+export class ShellErrorEvent extends defineTypedCustomEvent()('shell-error') {
+}
+export class ShellTarget extends ListenTarget {
+    childProcess;
+    constructor(childProcess) {
+        super();
+        this.childProcess = childProcess;
+    }
+}
+export function streamShellCommand(command, cwd, shell = 'bash', env = process.env, hookUpToConsole = false) {
+    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 = inputExitCode ?? undefined;
+        const exitSignal = inputExitSignal ?? undefined;
+        if ((exitCode !== undefined && exitCode !== 0) || exitSignal !== undefined) {
+            const execException = 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;
+}
+function prepareChunkForLogging(chunk, trimEndingLine) {
+    const stringified = chunk.toString();
+    return trimEndingLine ? stringified.replace(/\n$/, '') : stringified;
+}
+export async function runShellCommand(command, options = {}) {
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        const errors = [];
+        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 = 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: combineErrors(errors),
+                stdout,
+                stderr,
+                exitCode,
+                exitSignal,
+            });
+        });
+    });
+}
+const defaultLogShellOutputOptions = {
+    ignoreError: false,
+    logger: log,
+    withLabels: false,
+};
+export function logShellOutput(shellOutput, { ignoreError = defaultLogShellOutputOptions.ignoreError, logger = defaultLogShellOutputOptions.logger, withLabels = defaultLogShellOutputOptions.withLabels, } = 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/dist/docker/containers/container-info.d.ts

@@ -0,0 +1,28 @@
+/** There may be other possible values for Status. */
+export declare enum DockerContainerStatusEnum {
+    exited = "exited",
+    running = "running"
+}
+export type DockerContainerInfoState = {
+    Status: DockerContainerStatusEnum;
+    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. */
+export type DockerContainerInfo = Readonly<{
+    Id: string;
+    Created: string;
+    Path: string;
+    Args: ReadonlyArray<string>;
+    State: DockerContainerInfoState;
+    Name: string;
+}>;
+export declare function getContainerInfo(containerNameOrId: string): Promise<DockerContainerInfo | undefined>;

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

@@ -0,0 +1,24 @@
+import { runShellCommand } from '../../augments/shell.js';
+/** There may be other possible values for Status. */
+export var DockerContainerStatusEnum;
+(function (DockerContainerStatusEnum) {
+    DockerContainerStatusEnum["exited"] = "exited";
+    DockerContainerStatusEnum["running"] = "running";
+})(DockerContainerStatusEnum || (DockerContainerStatusEnum = {}));
+export async function getContainerInfo(containerNameOrId) {
+    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);
+    /** 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/dist/docker/containers/container-status.d.ts

@@ -0,0 +1,17 @@
+export declare function getContainerLogs(containerNameOrId: string, latestLineCount?: number): Promise<string>;
+export declare 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"
+}
+export declare const exitedDockerContainerStatuses: DockerContainerStatus[];
+export declare function getContainerStatus(containerNameOrId: string): Promise<DockerContainerStatus>;
+export declare function waitUntilContainerRunning(containerNameOrId: string, failureMessage?: string | undefined): Promise<void>;
+export declare function waitUntilContainerRemoved(containerNameOrId: string, failureMessage?: string | undefined): Promise<void>;
+export declare function waitUntilContainerExited(containerNameOrId: string, failureMessage?: string | undefined): Promise<void>;

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

@@ -0,0 +1,53 @@
+import { assert, waitUntil } from '@augment-vir/assert';
+import { runShellCommand } from '../../augments/shell.js';
+export async function getContainerLogs(containerNameOrId, latestLineCount) {
+    const latestLinesArg = latestLineCount == undefined ? '' : `--tail ${latestLineCount}`;
+    const logResult = await runShellCommand(`docker logs ${latestLinesArg} '${containerNameOrId}'`, { rejectOnError: true });
+    return logResult.stdout;
+}
+export var DockerContainerStatus;
+(function (DockerContainerStatus) {
+    DockerContainerStatus["Created"] = "created";
+    DockerContainerStatus["Running"] = "running";
+    DockerContainerStatus["Paused"] = "paused";
+    DockerContainerStatus["Restarting"] = "restarting";
+    DockerContainerStatus["Exited"] = "exited";
+    DockerContainerStatus["Removing"] = "removing";
+    DockerContainerStatus["Dead"] = "dead";
+    /** This is not a native Docker status but indicates that the container does not exist. */
+    DockerContainerStatus["Removed"] = "removed";
+})(DockerContainerStatus || (DockerContainerStatus = {}));
+export const exitedDockerContainerStatuses = [
+    DockerContainerStatus.Dead,
+    DockerContainerStatus.Removed,
+    DockerContainerStatus.Exited,
+];
+export async function getContainerStatus(containerNameOrId) {
+    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, failureMessage) {
+    await waitUntil.isTrue(async () => {
+        /** 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, failureMessage) {
+    await waitUntil.isTrue(async () => {
+        const status = await getContainerStatus(containerNameOrId);
+        return status === DockerContainerStatus.Removed;
+    }, {}, failureMessage);
+}
+export async function waitUntilContainerExited(containerNameOrId, failureMessage) {
+    await waitUntil.isTrue(async () => {
+        const status = await getContainerStatus(containerNameOrId);
+        return exitedDockerContainerStatuses.includes(status);
+    }, {}, failureMessage);
+}

package/dist/docker/containers/copy-to-container.d.ts

@@ -0,0 +1,7 @@
+export type CopyToDockerContainerParams = {
+    hostPath: string;
+    containerAbsolutePath: string;
+    containerNameOrId: string;
+    dockerFlags?: ReadonlyArray<string>;
+};
+export declare function copyToContainer({ containerAbsolutePath, hostPath, containerNameOrId, dockerFlags, }: CopyToDockerContainerParams): Promise<void>;

package/dist/docker/containers/copy-to-container.js

@@ -0,0 +1,10 @@
+import { addSuffix } from '@augment-vir/common';
+import { stat } from 'node:fs/promises';
+import { runShellCommand } from '../../augments/shell.js';
+export async function copyToContainer({ containerAbsolutePath, hostPath, containerNameOrId, dockerFlags = [], }) {
+    const isDir = (await stat(hostPath)).isDirectory();
+    const suffix = isDir ? '/.' : '';
+    const fullHostPath = addSuffix({ value: hostPath, suffix });
+    const extraInputs = dockerFlags.join(' ');
+    await runShellCommand(`docker cp ${extraInputs} '${fullHostPath}' '${containerNameOrId}:${containerAbsolutePath}'`, { rejectOnError: true });
+}

package/dist/docker/containers/docker-command-inputs.d.ts

@@ -0,0 +1,20 @@
+export declare enum DockerVolumeMappingType {
+    Cached = "cached",
+    Delegated = "delegated"
+}
+export type DockerVolumeMap = {
+    hostAbsolutePath: string;
+    containerAbsolutePath: string;
+    type?: DockerVolumeMappingType | undefined;
+};
+export declare function makeVolumeFlags(volumeMapping?: ReadonlyArray<DockerVolumeMap>): string;
+export type DockerPortMap = {
+    hostPort: number;
+    containerPort: number;
+};
+export type DockerEnvMap<RequiredKeys extends string = string> = Readonly<Record<RequiredKeys | string, {
+    value: string;
+    allowInterpolation: boolean;
+}>>;
+export declare function makePortMapFlags(portMapping?: ReadonlyArray<DockerPortMap> | undefined): string;
+export declare function makeEnvFlags(envMapping?: DockerEnvMap | undefined): string;

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

@@ -0,0 +1,36 @@
+import { wrapString } from '@augment-vir/common';
+export var DockerVolumeMappingType;
+(function (DockerVolumeMappingType) {
+    DockerVolumeMappingType["Cached"] = "cached";
+    DockerVolumeMappingType["Delegated"] = "delegated";
+})(DockerVolumeMappingType || (DockerVolumeMappingType = {}));
+export function makeVolumeFlags(volumeMapping) {
+    if (!volumeMapping) {
+        return '';
+    }
+    const parts = volumeMapping.map((volume) => {
+        const mountType = volume.type ? `:${volume.type}` : '';
+        return `-v '${volume.hostAbsolutePath}':'${volume.containerAbsolutePath}'${mountType}`;
+    });
+    return parts.join(' ');
+}
+export function makePortMapFlags(portMapping) {
+    if (!portMapping) {
+        return '';
+    }
+    return portMapping
+        .map((portMap) => {
+        return `-p ${portMap.hostPort}:${portMap.containerPort}`;
+    })
+        .join(' ');
+}
+export function makeEnvFlags(envMapping) {
+    if (!envMapping) {
+        return '';
+    }
+    const flags = Object.entries(envMapping).map(([key, { value, allowInterpolation },]) => {
+        const quote = allowInterpolation ? '"' : "'";
+        return `-e ${key}=${wrapString({ value, wrapper: quote })}`;
+    });
+    return flags.join(' ');
+}

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

@@ -0,0 +1,10 @@
+import type { PartialWithUndefined } from '@augment-vir/core';
+export declare 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>;

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

@@ -0,0 +1,12 @@
+import { runShellCommand } from '../../augments/shell.js';
+import { waitUntilContainerExited, waitUntilContainerRemoved } from './container-status.js';
+export async function killContainer(containerNameOrId, options = {}) {
+    await runShellCommand(`docker kill '${containerNameOrId}'`);
+    if (options.keepContainer) {
+        await waitUntilContainerExited(containerNameOrId);
+    }
+    else {
+        await runShellCommand(`docker rm '${containerNameOrId}'`);
+        await waitUntilContainerRemoved(containerNameOrId);
+    }
+}

package/dist/docker/containers/run-command.d.ts

@@ -0,0 +1,12 @@
+import { DockerEnvMap } from './docker-command-inputs.js';
+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;
+};
+/** Run a command on a container that is already running. */
+export declare function runContainerCommand({ tty, containerNameOrId, command, envMapping, executionEnv, dockerFlags, }: RunDockerContainerCommandParams): Promise<import("../../augments/shell.js").ShellOutput>;

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

@@ -0,0 +1,25 @@
+import { check } from '@augment-vir/assert';
+import { runShellCommand } from '../../augments/shell.js';
+import { makeEnvFlags } from './docker-command-inputs.js';
+/** Run a command on a container that is already running. */
+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

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

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

@@ -0,0 +1,47 @@
+import { check } from '@augment-vir/assert';
+import { runShellCommand } from '../../augments/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 = [], }) {
+    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);
+        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;
+    }
+}