@augment-vir/node 30.0.0 → 30.0.2

package/dist/augments/{shell.d.ts → terminal/shell.d.ts}

@@ -2,6 +2,13 @@ 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';
+/**
+ * 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;
@@ -17,6 +24,13 @@ declare const ShellStdoutEvent_base: (new (eventInitDict: import("typed-event-ta
     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">;
+/**
+ * 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 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<{
@@ -27,6 +41,13 @@ declare const ShellStderrEvent_base: (new (eventInitDict: import("typed-event-ta
     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">;
+/**
+ * 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 declare class ShellStderrEvent extends ShellStderrEvent_base {
 }
 declare const ShellDoneEvent_base: (new (eventInitDict: import("typed-event-target").TypedCustomEventInit<{
@@ -47,8 +68,13 @@ declare const ShellDoneEvent_base: (new (eventInitDict: import("typed-event-targ
     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.
+ * 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 declare class ShellDoneEvent extends ShellDoneEvent_base {
 }
@@ -60,28 +86,85 @@ declare const ShellErrorEvent_base: (new (eventInitDict: import("typed-event-tar
     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">;
+/**
+ * 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 declare class ShellErrorEvent extends ShellErrorEvent_base {
 }
+/**
+ * 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 declare class ShellTarget extends ListenTarget<ShellStdoutEvent | ShellStderrEvent | ShellDoneEvent | ShellErrorEvent> {
     readonly childProcess: ChildProcess;
     constructor(childProcess: ChildProcess);
 }
+/**
+ * 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 declare function streamShellCommand(command: string, cwd?: string, shell?: string, env?: NodeJS.ProcessEnv, hookUpToConsole?: boolean): ShellTarget;
-export type RunShellCommandParams = {
+/**
+ * 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;
 };
-export declare function runShellCommand(command: string, options?: RunShellCommandParams): Promise<ShellOutput>;
+/**
+ * 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 declare function runShellCommand(command: string, options?: RunShellCommandOptions): Promise<ShellOutput>;
+/**
+ * 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;
 }>;
+/**
+ * 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 declare function logShellOutput(shellOutput: PartialWithUndefined<Omit<ShellOutput, 'exitSignal'>>, { ignoreError, logger, withLabels, }?: LogShellOutputOptions): void;
 export {};

package/dist/augments/{shell.js → terminal/shell.js}

@@ -1,18 +1,51 @@
 import { combineErrors, log } from '@augment-vir/common';
 import { spawn } from 'node:child_process';
 import { defineTypedCustomEvent, ListenTarget } from 'typed-event-target';
+/**
+ * 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()('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()('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.
+ * 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()('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()('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 {
     childProcess;
     constructor(childProcess) {
@@ -20,6 +53,17 @@ export class ShellTarget extends ListenTarget {
         this.childProcess = childProcess;
     }
 }
+/**
+ * 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, cwd, shell = 'bash', env = process.env, hookUpToConsole = false) {
     const stdio = hookUpToConsole ? [process.stdin] : undefined;
     const childProcess = spawn(command, { shell, cwd, env, stdio });
@@ -75,6 +119,15 @@ function prepareChunkForLogging(chunk, trimEndingLine) {
     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, options = {}) {
     return new Promise((resolve, reject) => {
         let stdout = '';
@@ -126,7 +179,7 @@ export async function runShellCommand(command, options = {}) {
         shellTarget.listen(ShellDoneEvent, ({ detail: { exitCode, exitSignal } }) => {
             shellTarget.destroy();
             resolve({
-                error: combineErrors(errors),
+                error: errors.length ? combineErrors(errors) : undefined,
                 stdout,
                 stderr,
                 exitCode,
@@ -140,6 +193,13 @@ const defaultLogShellOutputOptions = {
     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, { 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);

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

@@ -1,10 +1,14 @@
-/** There may be other possible values for Status. */
-export declare enum DockerContainerStatusEnum {
-    exited = "exited",
-    running = "running"
-}
+import type { JsonCompatibleArray, JsonCompatibleObject } from '@augment-vir/common';
+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: DockerContainerStatusEnum;
+    Status: DockerContainerStatus;
     Running: boolean;
     Paused: boolean;
     Restarting: boolean;
@@ -17,12 +21,37 @@ export type DockerContainerInfoState = {
     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 declare function getContainerInfo(containerNameOrId: string): Promise<DockerContainerInfo | undefined>;

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

@@ -1,10 +1,4 @@
-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 = {}));
+import { runShellCommand } from '../../augments/terminal/shell.js';
 export async function getContainerInfo(containerNameOrId) {
     const command = `docker inspect '${containerNameOrId}'`;
     const output = await runShellCommand(command);

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

@@ -1,4 +1,11 @@
 export declare function getContainerLogs(containerNameOrId: string, latestLineCount?: number): Promise<string>;
+/**
+ * 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 declare enum DockerContainerStatus {
     Created = "created",
     Running = "running",
@@ -10,6 +17,14 @@ export declare enum DockerContainerStatus {
     /** 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 declare const exitedDockerContainerStatuses: DockerContainerStatus[];
 export declare function getContainerStatus(containerNameOrId: string): Promise<DockerContainerStatus>;
 export declare function waitUntilContainerRunning(containerNameOrId: string, failureMessage?: string | undefined): Promise<void>;

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

@@ -1,10 +1,17 @@
 import { assert, waitUntil } from '@augment-vir/assert';
-import { runShellCommand } from '../../augments/shell.js';
+import { runShellCommand } from '../../augments/terminal/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;
 }
+/**
+ * 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 var DockerContainerStatus;
 (function (DockerContainerStatus) {
     DockerContainerStatus["Created"] = "created";
@@ -17,6 +24,14 @@ export var DockerContainerStatus;
     /** This is not a native Docker status but indicates that the container does not exist. */
     DockerContainerStatus["Removed"] = "removed";
 })(DockerContainerStatus || (DockerContainerStatus = {}));
+/**
+ * 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,

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

@@ -1,3 +1,10 @@
+/**
+ * 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;

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

@@ -1,6 +1,6 @@
 import { addSuffix } from '@augment-vir/common';
 import { stat } from 'node:fs/promises';
-import { runShellCommand } from '../../augments/shell.js';
+import { runShellCommand } from '../../augments/terminal/shell.js';
 export async function copyToContainer({ containerAbsolutePath, hostPath, containerNameOrId, dockerFlags = [], }) {
     const isDir = (await stat(hostPath)).isDirectory();
     const suffix = isDir ? '/.' : '';

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

@@ -1,17 +1,71 @@
+/**
+ * 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 declare 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 declare function makeVolumeFlags(volumeMapping?: ReadonlyArray<DockerVolumeMap>): string;
+/**
+ * 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;

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

@@ -1,4 +1,13 @@
 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 var DockerVolumeMappingType;
 (function (DockerVolumeMappingType) {
     DockerVolumeMappingType["Cached"] = "cached";

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

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

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

@@ -1,4 +1,11 @@
 import { DockerEnvMap } 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;
@@ -8,5 +15,4 @@ export type RunDockerContainerCommandParams = {
     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>;
+export declare function runContainerCommand({ tty, containerNameOrId, command, envMapping, executionEnv, dockerFlags, }: RunDockerContainerCommandParams): Promise<import("../../augments/terminal/shell.js").ShellOutput>;

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

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

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

@@ -1,4 +1,11 @@
 import { DockerEnvMap, DockerPortMap, DockerVolumeMap } from './docker-command-inputs.js';
+/**
+ * Parameters for `docker.container.run`.
+ *
+ * @category Node : Docker : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export type RunDockerContainerParams = {
     imageName: string;
     detach: boolean;

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

@@ -1,5 +1,5 @@
 import { check } from '@augment-vir/assert';
-import { runShellCommand } from '../../augments/shell.js';
+import { runShellCommand } from '../../augments/terminal/shell.js';
 import { updateImage } from '../docker-image.js';
 import { waitUntilContainerRunning } from './container-status.js';
 import { makeEnvFlags, makePortMapFlags, makeVolumeFlags, } from './docker-command-inputs.js';

package/dist/docker/docker-image.js

@@ -1,5 +1,5 @@
 import { ensureError } from '@augment-vir/core';
-import { runShellCommand } from '../augments/shell.js';
+import { runShellCommand } from '../augments/terminal/shell.js';
 export async function updateImage(
 /** @example 'alpine:3.20.2' */
 imageName) {
@@ -21,7 +21,9 @@ export async function removeImageFromLocalRegistry(
 /** @example 'alpine:3.20.2' */
 imageName) {
     try {
-        await runShellCommand(`docker image rm '${imageName}'`, { rejectOnError: true });
+        await runShellCommand(`docker image rm '${imageName}'`, {
+            rejectOnError: true,
+        });
     }
     catch (caught) {
         const error = ensureError(caught);

package/dist/docker/docker-startup.js

@@ -1,6 +1,6 @@
 import { waitUntil } from '@augment-vir/assert';
 import { currentOperatingSystem, OperatingSystem } from '../augments/os/operating-system.js';
-import { runShellCommand } from '../augments/shell.js';
+import { runShellCommand } from '../augments/terminal/shell.js';
 export async function isDockerRunning() {
     const output = await runShellCommand('docker info');
     return output.exitCode === 0;
@@ -20,7 +20,6 @@ const startDockerCommands = {
 };
 export async function startDocker() {
     const command = startDockerCommands[currentOperatingSystem];
-    /** We */
     /* node:coverage disable */
     if (await isDockerRunning()) {
         /** Docker is already running. Nothing to do. */

package/dist/docker/run-docker-test.mock.d.ts

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

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

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

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-export * from './augments/console/question.js';
 export * from './augments/docker.js';
-export * from './augments/download.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';
@@ -13,4 +12,5 @@ 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/shell.js';
+export * from './augments/terminal/question.js';
+export * from './augments/terminal/shell.js';

package/dist/index.js

@@ -1,6 +1,5 @@
-export * from './augments/console/question.js';
 export * from './augments/docker.js';
-export * from './augments/download.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';
@@ -13,4 +12,5 @@ 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/shell.js';
+export * from './augments/terminal/question.js';
+export * from './augments/terminal/shell.js';

package/dist/prisma/disable-ci-env.mock.d.ts

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