@augment-vir/node 30.0.0 → 30.0.1

package/dist/augments/path/os-path.d.ts

@@ -1,9 +1,25 @@
-/** Convert a given path to a windows path if the current system doesn't use `/`. */
+/**
+ * Convert a given path to a windows path if the current system doesn't use `/`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function replaceWithWindowsPathIfNeeded(input: string): string;
-/** Convert a Windows path to a posix path. */
+/**
+ * Convert a Windows path to a posix path.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function toPosixPath(maybeWindowsPath: string): string;
 /**
- * Use this to interpolate paths into bash commands. If the given path is not a window path, the
+ * Use this to interpolate paths into bash commands. If the given path is not a Windows path, the
  * path structure will not be modified.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export declare function interpolationSafeWindowsPath(input: string): string;

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

@@ -1,5 +1,11 @@
 import { sep } from 'node:path';
-/** Convert a given path to a windows path if the current system doesn't use `/`. */
+/**
+ * Convert a given path to a windows path if the current system doesn't use `/`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function replaceWithWindowsPathIfNeeded(input) {
     if (sep === '/') {
         return input;
@@ -10,7 +16,13 @@ export function replaceWithWindowsPathIfNeeded(input) {
         return input.replace(/\//g, sep);
     }
 }
-/** Convert a Windows path to a posix path. */
+/**
+ * Convert a Windows path to a posix path.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function toPosixPath(maybeWindowsPath) {
     return maybeWindowsPath
         .replace(/^(.+?):\\+/, (match, captureGroup) => {
@@ -19,8 +31,12 @@ export function toPosixPath(maybeWindowsPath) {
         .replace(/\\+/g, '/');
 }
 /**
- * Use this to interpolate paths into bash commands. If the given path is not a window path, the
+ * Use this to interpolate paths into bash commands. If the given path is not a Windows path, the
  * path structure will not be modified.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export function interpolationSafeWindowsPath(input) {
     return input.replace(/\\/g, '\\\\\\\\');

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

@@ -1 +1,8 @@
+/**
+ * The root path of the system containing the cwd.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare const systemRootPath: string;

package/dist/augments/path/root.js

@@ -2,4 +2,11 @@ import { parse } from 'node:path';
 function getSystemRootPath() {
     return parse(process.cwd()).root;
 }
+/**
+ * The root path of the system containing the cwd.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export const systemRootPath = getSystemRootPath();

package/dist/augments/prisma.d.ts

@@ -1,21 +1,95 @@
 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 * from '../prisma/prisma-errors.js';
+export type { PrismaMigrationStatus } from '../prisma/prisma-migrations.js';
+/**
+ * Centralized Prisma API from `@augment-vir/node`.
+ *
+ * ## Prisma flows
+ *
+ * - Deploy to production
+ *
+ *   - {@link prisma.migration.applyProd}
+ * - Update dev environment
+ *
+ *   - Apply migrations: {@link prisma.migration.applyDev}
+ *
+ *       - If throws {@link PrismaMigrationNeededError}, prompt user for a new migration name and pass it to
+ *               {@link prisma.migration.create}
+ *       - If throws {@link PrismaResetNeededError}, reset the database with {@link prisma.database.resetDev}
+ *   - Generate client: `prisma.client.isCurrent`
+ *
+ *       - If `false`, run {@link prisma.client.generate}
+ *
+ * @category Prisma : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare const prisma: {
     migration: {
+        /**
+         * Get current migration status.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-status
+         */
         status: typeof getMigrationStatus;
+        /**
+         * Creates a new migration.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-dev
+         */
         create: typeof createPrismaMigration;
+        /**
+         * Apply all migrations. Meant for a production environment.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-deploy
+         */
         applyProd: typeof applyPrismaMigrationsToProd;
+        /**
+         * Apply all migrations. Meant for a development environment, with less protections than
+         * {@link prisma.migration.applyProd}.
+         *
+         * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
+         *   to input a name.
+         * @throws `PrismaResetNeededError` when there's a migration mismatch with the database and
+         *   it needs to be reset.
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-dev
+         */
         applyDev: typeof applyPrismaMigrationsToDev;
     };
     database: {
+        /**
+         * Force resets a dev database to match the current Prisma schema and migrations.
+         *
+         * **This will destroy all data. Do not use in production.**
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-reset
+         */
         resetDev: typeof resetDevPrismaDatabase;
+        /**
+         * Uses {@link prisma.database.diff} to detect if there are any differences between the
+         * current database and the Prisma schema that should control it.
+         */
         hasDiff: typeof doesPrismaDiffExist;
+        /**
+         * Gets a string list of all differences between the current database and the Prisma schema
+         * that should control it.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-diff
+         */
         diff: typeof getPrismaDiff;
     };
     client: {
+        /**
+         * Runs Prisma generators included in the given Prisma schema (which usually includes the
+         * Prisma JS client). This will work even if the database doesn't exist yet.
+         */
         generate: typeof generatePrismaClient;
+        /**
+         * Detects if the current generated Prisma JS Client was generated from the current Prisma
+         * schema.
+         */
         isCurrent: typeof isGeneratedPrismaClientCurrent;
     };
 };

package/dist/augments/prisma.js

@@ -1,21 +1,94 @@
 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 * from '../prisma/prisma-errors.js';
+/**
+ * Centralized Prisma API from `@augment-vir/node`.
+ *
+ * ## Prisma flows
+ *
+ * - Deploy to production
+ *
+ *   - {@link prisma.migration.applyProd}
+ * - Update dev environment
+ *
+ *   - Apply migrations: {@link prisma.migration.applyDev}
+ *
+ *       - If throws {@link PrismaMigrationNeededError}, prompt user for a new migration name and pass it to
+ *               {@link prisma.migration.create}
+ *       - If throws {@link PrismaResetNeededError}, reset the database with {@link prisma.database.resetDev}
+ *   - Generate client: `prisma.client.isCurrent`
+ *
+ *       - If `false`, run {@link prisma.client.generate}
+ *
+ * @category Prisma : Node
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export const prisma = {
     migration: {
+        /**
+         * Get current migration status.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-status
+         */
         status: getMigrationStatus,
+        /**
+         * Creates a new migration.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-dev
+         */
         create: createPrismaMigration,
+        /**
+         * Apply all migrations. Meant for a production environment.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-deploy
+         */
         applyProd: applyPrismaMigrationsToProd,
+        /**
+         * Apply all migrations. Meant for a development environment, with less protections than
+         * {@link prisma.migration.applyProd}.
+         *
+         * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
+         *   to input a name.
+         * @throws `PrismaResetNeededError` when there's a migration mismatch with the database and
+         *   it needs to be reset.
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-dev
+         */
         applyDev: applyPrismaMigrationsToDev,
     },
     database: {
+        /**
+         * Force resets a dev database to match the current Prisma schema and migrations.
+         *
+         * **This will destroy all data. Do not use in production.**
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-reset
+         */
         resetDev: resetDevPrismaDatabase,
+        /**
+         * Uses {@link prisma.database.diff} to detect if there are any differences between the
+         * current database and the Prisma schema that should control it.
+         */
         hasDiff: doesPrismaDiffExist,
+        /**
+         * Gets a string list of all differences between the current database and the Prisma schema
+         * that should control it.
+         *
+         * @see https://www.prisma.io/docs/orm/reference/prisma-cli-reference#migrate-diff
+         */
         diff: getPrismaDiff,
     },
     client: {
+        /**
+         * Runs Prisma generators included in the given Prisma schema (which usually includes the
+         * Prisma JS client). This will work even if the database doesn't exist yet.
+         */
         generate: generatePrismaClient,
+        /**
+         * Detects if the current generated Prisma JS Client was generated from the current Prisma
+         * schema.
+         */
         isCurrent: isGeneratedPrismaClientCurrent,
     },
 };

package/dist/augments/terminal/question.d.ts

@@ -0,0 +1,50 @@
+import { type AnyDuration } from '@date-vir/duration';
+/** Can't test requiring user input. */
+/**
+ * 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;
+};
+/**
+ * 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 declare function askQuestion(questionToAsk: string, { hideUserInput, timeout, }?: Partial<AskQuestionOptions>): Promise<string>;
+/**
+ * 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 declare function askQuestionUntilConditionMet({ questionToAsk, verifyResponseCallback, invalidInputMessage, tryCountMax, ...options }: QuestionUntilConditionMetOptions): Promise<string>;

package/dist/augments/{console → terminal}/question.js

@@ -5,6 +5,16 @@ const defaultAskQuestionOptions = {
     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, { hideUserInput = defaultAskQuestionOptions.hideUserInput, timeout = defaultAskQuestionOptions.timeout, } = defaultAskQuestionOptions) {
     const cliInterface = createInterface({
         input: process.stdin,
@@ -44,13 +54,24 @@ export async function askQuestion(questionToAsk, { hideUserInput = defaultAskQue
         });
     });
 }
-export async function askQuestionUntilConditionMet({ questionToAsk, conditionCallback, invalidInputMessage, tryCountMax = 5, ...options }) {
+/**
+ * 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 }) {
     let wasConditionMet = false;
     let retryCount = 0;
     let response = '';
     while (!wasConditionMet && retryCount <= tryCountMax) {
         response = (await askQuestion(questionToAsk, options)).trim();
-        wasConditionMet = await conditionCallback(response);
+        wasConditionMet = await verifyResponseCallback(response);
         if (!wasConditionMet) {
             log.error(invalidInputMessage);
         }

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);