@augment-vir/node 31.0.0 → 31.1.0

package/src/augments/terminal/question.ts

@@ -0,0 +1,142 @@
+import {log} from '@augment-vir/common';
+import {convertDuration, type AnyDuration} from '@date-vir/duration';
+import {createInterface} from 'node:readline';
+
+/** Can't test requiring user input. */
+/* node:coverage disable */
+
+/**
+ * Options for {@link askQuestion}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type AskQuestionOptions = {
+    timeout: AnyDuration;
+    hideUserInput: boolean;
+};
+
+const defaultAskQuestionOptions: AskQuestionOptions = {
+    timeout: {seconds: 60},
+    hideUserInput: false,
+};
+
+/**
+ * Asks the user a question in their terminal and then waits for them to type something in response.
+ * The response is accepted once the user inputs a new line.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link askQuestionUntilConditionMet}: ask a question on loop until the user provides a valid response.
+ */
+export async function askQuestion(
+    questionToAsk: string,
+    {
+        hideUserInput = defaultAskQuestionOptions.hideUserInput,
+        timeout = defaultAskQuestionOptions.timeout,
+    }: Partial<AskQuestionOptions> = defaultAskQuestionOptions,
+): Promise<string> {
+    const cliInterface = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    if (hideUserInput) {
+        let promptWritten = false;
+        /** _writeToOutput is not in the types OR in the Node.js documentation but is a thing. */
+        (cliInterface as unknown as {_writeToOutput: (prompt: string) => void})._writeToOutput = (
+            prompt,
+        ) => {
+            if (!promptWritten) {
+                (
+                    cliInterface as unknown as {output: {write: (output: string) => void}}
+                ).output.write(prompt);
+                promptWritten = true;
+            }
+        };
+    }
+
+    // handle killing the process
+    cliInterface.on('SIGINT', () => {
+        cliInterface.close();
+        process.stdout.write('\n');
+        process.kill(process.pid, 'SIGINT');
+    });
+
+    return new Promise((resolve, reject) => {
+        const timeoutMs = convertDuration(timeout, {milliseconds: true}).milliseconds;
+
+        const timeoutId = timeoutMs
+            ? setTimeout(() => {
+                  cliInterface.close();
+                  reject(
+                      new Error(
+                          `Took too long to respond (over "${Math.floor(timeoutMs / 1000)}" seconds)`,
+                      ),
+                  );
+              }, timeoutMs)
+            : undefined;
+
+        process.stdout.write(questionToAsk + '\n');
+        cliInterface.question('', (response) => {
+            if (timeoutId != undefined) {
+                clearTimeout(timeoutId);
+            }
+            cliInterface.close();
+            resolve(response);
+        });
+    });
+}
+
+/**
+ * Options for {@link askQuestionUntilConditionMet}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type QuestionUntilConditionMetOptions = {
+    questionToAsk: string;
+    /** Callback to call with the user's response to verify if their response is valid. */
+    verifyResponseCallback: (response: string) => boolean | Promise<boolean>;
+    invalidInputMessage: string;
+    tryCountMax?: number;
+} & Partial<AskQuestionOptions>;
+
+/**
+ * Asks the user a question in their terminal and then waits for them to type something in response.
+ * The response is submitted once the user inputs a new line. If the response fails validation, the
+ * question is presented again.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ * @see
+ *  - {@link askQuestion}: ask a question and accept any response.
+ */
+export async function askQuestionUntilConditionMet({
+    questionToAsk,
+    verifyResponseCallback,
+    invalidInputMessage,
+    tryCountMax = 5,
+    ...options
+}: QuestionUntilConditionMetOptions): Promise<string> {
+    let wasConditionMet = false;
+    let retryCount = 0;
+    let response = '';
+    while (!wasConditionMet && retryCount <= tryCountMax) {
+        response = (await askQuestion(questionToAsk, options)).trim();
+        wasConditionMet = await verifyResponseCallback(response);
+        if (!wasConditionMet) {
+            log.error(invalidInputMessage);
+        }
+        retryCount++;
+    }
+    if (retryCount > tryCountMax) {
+        throw new Error(`Max input attempts (${tryCountMax}) exceeded.`);
+    }
+    return response;
+}

package/src/augments/terminal/relevant-args.ts

@@ -0,0 +1,81 @@
+import {basename} from 'node:path';
+
+/**
+ * Input for extractRelevantArgs.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export type RelevantArgsInput = {
+    /** Raw arguments passed to the CLI. Typically this will simply be process.argv. */
+    rawArgs: ReadonlyArray<string>;
+    /**
+     * Executable bin name for your script. This should be the "bin" name in your package.json, or
+     * simply your package name if you have no custom bin name defined.
+     *
+     * See https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin for details on the bin
+     * field of package.json
+     */
+    binName: string | undefined;
+    /**
+     * The name or path of your script file that will be executed via the CLI. This should almost
+     * always simply be __filename in CJS or `import.meta.filename` in ESM.
+     */
+    fileName: string;
+    /**
+     * If set to true, this function with throw an error if the given file or bin name was not found
+     * in the given arguments list.
+     */
+    errorIfNotFound?: boolean | undefined;
+};
+
+/**
+ * Trims arguments list to remove all arguments that take place before the script's file name or
+ * executable bin name.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * extractRelevantArgs({
+ *     rawArgs: ['npx', 'ts-node', './my-script.ts', 'arg1', '--arg2'], // typically will be process.argv
+ *     binName: 'my-script', // should be your package.json "bin" property name, can be undefined
+ *     fileName: 'my-script.ts', // should be __filename from the script that will be executed
+ * });
+ * // will output ['arg1', '--arg2']
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function extractRelevantArgs({
+    rawArgs,
+    binName,
+    fileName,
+    errorIfNotFound,
+}: Readonly<RelevantArgsInput>): string[] {
+    const baseFileName = basename(fileName);
+
+    if (!baseFileName) {
+        throw new Error(
+            `Given file name produced no base file name (with path.basename()): '${fileName}'`,
+        );
+    }
+
+    const lastIrrelevantArgIndex = rawArgs.findIndex((arg) => {
+        const baseArgName = basename(arg);
+        const matchesFileName = baseArgName === baseFileName;
+        const matchesBinName = binName ? baseArgName === binName : false;
+        return matchesFileName || matchesBinName;
+    });
+    if (lastIrrelevantArgIndex === -1) {
+        if (errorIfNotFound) {
+            throw new Error('Failed to find position of file or bin name in provided args list.');
+        } else {
+            return [...rawArgs];
+        }
+    } else {
+        return rawArgs.slice(lastIrrelevantArgIndex + 1);
+    }
+}

package/src/augments/terminal/run-cli-script.ts

@@ -0,0 +1,60 @@
+/* node:coverage disable */
+/** This file cannot be tested because it calls `process.exit`. */
+
+import {extname} from 'node:path';
+import {interpolationSafeWindowsPath} from '../path/os-path.js';
+import {extractRelevantArgs} from './relevant-args.js';
+import {runShellCommand} from './shell.js';
+
+/**
+ * A map of file extensions to their known runners for {@link runCliScript}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export const ExtensionToRunner: Record<string, string> = {
+    '.ts': 'tsx',
+    '.js': 'node',
+    '.sh': 'bash',
+};
+
+/**
+ * Runs a script path as if it had been run directly, as much as possible.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function runCliScript(
+    path: string,
+    /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
+    cliScriptFilePath: string,
+    /**
+     * This should be the bin name of the package that is calling this function. Set to `undefined`
+     * if there isn't one.
+     */
+    binName: string | undefined,
+) {
+    const args = extractRelevantArgs({
+        rawArgs: process.argv,
+        binName,
+        fileName: cliScriptFilePath,
+    });
+
+    const extension = extname(path);
+
+    const runner = ExtensionToRunner[extension];
+
+    if (!runner) {
+        throw new Error("No runner configured for file extension '${extension}' in '${path}'");
+    }
+
+    const results = await runShellCommand(
+        interpolationSafeWindowsPath([runner, path, ...args].join(' ')),
+        {
+            hookUpToConsole: true,
+        },
+    );
+    process.exit(results.exitCode || 0);
+}

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