@mikeyt23/node-cli-utils 1.4.1 → 2.0.0-beta.2

package/dist/cjs/dotnetUtils.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureDotnetDevCerts = exports.installOrUpdateDotnetEfTool = exports.dotnetPublish = exports.dotnetBuild = void 0;
+const generalUtils_js_1 = require("./generalUtils.js");
+/**
+ * Runs dotnet build on the specified project.
+ * @param projectPath Path to project file (like .csproj) or directory of project to build
+ * @throws A {@link SpawnError} if the spawned process exits with a non-zero exit code
+ */
+async function dotnetBuild(projectPath) {
+    (0, generalUtils_js_1.requireValidPath)('projectPath', projectPath);
+    await (0, generalUtils_js_1.spawnAsync)('dotnet', ['build', projectPath], { throwOnNonZero: true });
+}
+exports.dotnetBuild = dotnetBuild;
+/**
+ * Helper method to spawn a process and run 'dotnet publish'.
+ * @param projectPath Path to project file (like .csproj) or directory of project to build
+ * @param configuration Build configuration, such as 'Release'
+ * @param outputDir The relative or absolute path for the build output
+ * @param cwd Optionally run the command from another current working directory
+ */
+async function dotnetPublish(projectPath = './', configuration = 'Release', outputDir = 'publish', cwd) {
+    (0, generalUtils_js_1.requireValidPath)('projectPath', projectPath);
+    (0, generalUtils_js_1.requireString)('outputDir', outputDir);
+    (0, generalUtils_js_1.requireString)('configuration', configuration);
+    if (cwd) {
+        (0, generalUtils_js_1.requireValidPath)('cwd', cwd);
+    }
+    const args = ['publish', projectPath, '-c', configuration, '-o', outputDir];
+    const traceMessage = `running dotnet ${args.join(' ')}`;
+    const traceAdditional = cwd ? ` in cwd ${cwd}` : '';
+    (0, generalUtils_js_1.trace)(`${traceMessage}${traceAdditional}`);
+    await (0, generalUtils_js_1.spawnAsync)('dotnet', args, { cwd: cwd });
+}
+exports.dotnetPublish = dotnetPublish;
+/**
+ * Spawns a process that runs the necessary commands to install or update the dotnet-ef tool globally on the system.
+ */
+async function installOrUpdateDotnetEfTool() {
+    const installed = (0, generalUtils_js_1.whichSync)('dotnet-ef').location;
+    if (installed) {
+        (0, generalUtils_js_1.log)('dotnet-ef tool already installed, updating...');
+    }
+    else {
+        (0, generalUtils_js_1.log)('dotnet-ef tool not installed, installing...');
+    }
+    const args = ['tool', installed ? 'update' : 'install', '--global', 'dotnet-ef'];
+    await (0, generalUtils_js_1.spawnAsync)('dotnet', args);
+}
+exports.installOrUpdateDotnetEfTool = installOrUpdateDotnetEfTool;
+/**
+ * Spawns a process that runs the following commands to clean and re-install the dotnet dev certs:
+ * - dotnet dev-certs https --clean
+ * - dotnet dev-certs https -t
+ */
+async function configureDotnetDevCerts() {
+    await (0, generalUtils_js_1.spawnAsync)('dotnet', ['dev-certs', 'https', '--clean']);
+    await (0, generalUtils_js_1.spawnAsync)('dotnet', ['dev-certs', 'https', '-t']);
+}
+exports.configureDotnetDevCerts = configureDotnetDevCerts;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZG90bmV0VXRpbHMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZG90bmV0VXRpbHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsdURBQXNHO0FBTXRHOzs7O0dBSUc7QUFDSSxLQUFLLFVBQVUsV0FBVyxDQUFDLFdBQW1CO0lBQ25ELElBQUEsa0NBQWdCLEVBQUMsYUFBYSxFQUFFLFdBQVcsQ0FBQyxDQUFBO0lBQzVDLE1BQU0sSUFBQSw0QkFBVSxFQUFDLFFBQVEsRUFBRSxDQUFDLE9BQU8sRUFBRSxXQUFXLENBQUMsRUFBRSxFQUFFLGNBQWMsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFBO0FBQzlFLENBQUM7QUFIRCxrQ0FHQztBQUVEOzs7Ozs7R0FNRztBQUNJLEtBQUssVUFBVSxhQUFhLENBQUMsY0FBc0IsSUFBSSxFQUFFLGdCQUF3QixTQUFTLEVBQUUsWUFBb0IsU0FBUyxFQUFFLEdBQVk7SUFDNUksSUFBQSxrQ0FBZ0IsRUFBQyxhQUFhLEVBQUUsV0FBVyxDQUFDLENBQUE7SUFDNUMsSUFBQSwrQkFBYSxFQUFDLFdBQVcsRUFBRSxTQUFTLENBQUMsQ0FBQTtJQUNyQyxJQUFBLCtCQUFhLEVBQUMsZUFBZSxFQUFFLGFBQWEsQ0FBQyxDQUFBO0lBQzdDLElBQUksR0FBRyxFQUFFO1FBQ1AsSUFBQSxrQ0FBZ0IsRUFBQyxLQUFLLEVBQUUsR0FBRyxDQUFDLENBQUE7S0FDN0I7SUFDRCxNQUFNLElBQUksR0FBRyxDQUFDLFNBQVMsRUFBRSxXQUFXLEVBQUUsSUFBSSxFQUFFLGFBQWEsRUFBRSxJQUFJLEVBQUUsU0FBUyxDQUFDLENBQUE7SUFDM0UsTUFBTSxZQUFZLEdBQUcsa0JBQWtCLElBQUksQ0FBQyxJQUFJLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQTtJQUN2RCxNQUFNLGVBQWUsR0FBRyxHQUFHLENBQUMsQ0FBQyxDQUFDLFdBQVcsR0FBRyxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQTtJQUNuRCxJQUFBLHVCQUFLLEVBQUMsR0FBRyxZQUFZLEdBQUcsZUFBZSxFQUFFLENBQUMsQ0FBQTtJQUMxQyxNQUFNLElBQUEsNEJBQVUsRUFBQyxRQUFRLEVBQUUsSUFBSSxFQUFFLEVBQUUsR0FBRyxFQUFFLEdBQUcsRUFBRSxDQUFDLENBQUE7QUFDaEQsQ0FBQztBQVpELHNDQVlDO0FBRUQ7O0dBRUc7QUFDSSxLQUFLLFVBQVUsMkJBQTJCO0lBQy9DLE1BQU0sU0FBUyxHQUFHLElBQUEsMkJBQVMsRUFBQyxXQUFXLENBQUMsQ0FBQyxRQUFRLENBQUE7SUFDakQsSUFBSSxTQUFTLEVBQUU7UUFDYixJQUFBLHFCQUFHLEVBQUMsK0NBQStDLENBQUMsQ0FBQTtLQUNyRDtTQUFNO1FBQ0wsSUFBQSxxQkFBRyxFQUFDLDZDQUE2QyxDQUFDLENBQUE7S0FDbkQ7SUFDRCxNQUFNLElBQUksR0FBRyxDQUFDLE1BQU0sRUFBRSxTQUFTLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsU0FBUyxFQUFFLFVBQVUsRUFBRSxXQUFXLENBQUMsQ0FBQTtJQUNoRixNQUFNLElBQUEsNEJBQVUsRUFBQyxRQUFRLEVBQUUsSUFBSSxDQUFDLENBQUE7QUFDbEMsQ0FBQztBQVRELGtFQVNDO0FBRUQ7Ozs7R0FJRztBQUNJLEtBQUssVUFBVSx1QkFBdUI7SUFDM0MsTUFBTSxJQUFBLDRCQUFVLEVBQUMsUUFBUSxFQUFFLENBQUMsV0FBVyxFQUFFLE9BQU8sRUFBRSxTQUFTLENBQUMsQ0FBQyxDQUFBO0lBQzdELE1BQU0sSUFBQSw0QkFBVSxFQUFDLFFBQVEsRUFBRSxDQUFDLFdBQVcsRUFBRSxPQUFPLEVBQUUsSUFBSSxDQUFDLENBQUMsQ0FBQTtBQUMxRCxDQUFDO0FBSEQsMERBR0MifQ==

package/dist/cjs/esmSpecific.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Only dynamically import this if ESM is detected. This allows a CJS-specific build to avoid
+ * an error it would otherwise encounter when parsing import.meta.url.
+ * @returns the file path of the currently executing script
+ */
+export declare const getImportMetaUrlFilePath: () => string;
+//# sourceMappingURL=esmSpecific.d.mts.map

package/dist/cjs/esmSpecific.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"esmSpecific.d.mts","sourceRoot":"","sources":["../../src/esmSpecific.mts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,cAGpC,CAAA"}

package/dist/cjs/esmSpecific.mjs

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getImportMetaUrlFilePath = void 0;
+const node_url_1 = require("node:url");
+/**
+ * Only dynamically import this if ESM is detected. This allows a CJS-specific build to avoid
+ * an error it would otherwise encounter when parsing import.meta.url.
+ * @returns the file path of the currently executing script
+ */
+const getImportMetaUrlFilePath = () => {
+    // @ts-ignore
+    return (0, node_url_1.fileURLToPath)(import.meta.url);
+};
+exports.getImportMetaUrlFilePath = getImportMetaUrlFilePath;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXNtU3BlY2lmaWMubWpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2VzbVNwZWNpZmljLm10cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSx1Q0FBd0M7QUFFeEM7Ozs7R0FJRztBQUNJLE1BQU0sd0JBQXdCLEdBQUcsR0FBRyxFQUFFO0lBQzNDLGFBQWE7SUFDYixPQUFPLElBQUEsd0JBQWEsRUFBQyxNQUFNLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFBO0FBQ3ZDLENBQUMsQ0FBQTtBQUhZLFFBQUEsd0JBQXdCLDRCQUdwQyJ9

package/dist/cjs/generalUtils.d.ts

@@ -0,0 +1,565 @@
+/// <reference types="node" />
+import { SpawnOptions } from 'node:child_process';
+/**
+ * Just a wrapper for console.log() to type less.
+ * @param data The data to log
+ * @param moreData More data to log
+ */
+export declare function log(data: unknown, ...moreData: unknown[]): void;
+/**
+ * Log conditionally. Useful for methods that have an option to either suppress output or to show it when it normally isn't.
+ * @param data The data to log
+ * @param moreData More data to log
+ */
+export declare function logIf(shouldLog: boolean, data: unknown, ...moreData: unknown[]): void;
+/**
+ * Wrapper for console.log() that is suppressed if NodeCliUtilsConfig.logEnabled is false.
+ * @param data The data to log
+ * @param moreData More data to log
+ */
+export declare function trace(data?: unknown, ...moreData: unknown[]): void;
+/**
+ * Type guard for a string keyed dictionary.
+ */
+export type StringKeyedDictionary = {
+    [name: string]: string;
+};
+/**
+ * Options for the {@link spawnAsync} wrapper function for NodeJS spawn.
+ */
+export interface SpawnResult {
+    /**
+     * The exit code of the spawned process. Rather than allowing null, this will be set to 1 if the process exits with null, or 0 if user cancels with ctrl+c.
+     */
+    code: number;
+    /**
+     * The stdout of the spawned process. **Warning:** this will be empty by default without changing SpawnOptions stdio (see {@link spawnAsync}).
+     */
+    stdout: string;
+    /**
+     * The stderr of the spawned process. **Warning:** this will be empty by default without changing SpawnOptions stdio (see {@link spawnAsync}).
+     */
+    stderr: string;
+    /**
+     * Not an error from the child process stderr, but rather an error thrown when attempting to spawn the child process.
+     */
+    error?: Error;
+    /**
+     * The current working directory of the spawned process. Not changed by method, so just repeating your SpawnOptions.cwd back to you, but helpful for debugging.
+     */
+    cwd?: string;
+}
+/**
+ * Error throw by {@link spawnAsync} when the spawned process exits with a non-zero exit code and options.throwOnNonZero is true.
+ *
+ * Contains a {@link SpawnResult} with the exit code, stdout, stderr, and error (if any).
+ */
+export declare class SpawnError extends Error {
+    result: SpawnResult;
+    constructor(message: string, result: SpawnResult);
+}
+/**
+ * Spawn result for calls to {@link simpleSpawnSync} and {@link simpleCmdSync}.
+ *
+ * Contains the same properties as {@link SpawnResult} plus stdoutLines, which is stdout split into lines from stdout that weren't empty.
+ */
+export interface SimpleSpawnResult extends SpawnResult {
+    stdoutLines: string[];
+}
+/**
+ * Error throw by {@link simpleSpawnSync} and {@link simpleCmdSync} when the spawned process exits with a non-zero exit code and throwOnNonZero param is true (the default).
+ *
+ * Contains a {@link SimpleSpawnResult} with the exit code, stdout, stderr, and error (if any) in addition to stdoutLines, which is stdout split into lines from stdout that weren't empty.
+ */
+export declare class SimpleSpawnError extends Error {
+    result: SimpleSpawnResult;
+    constructor(message: string, result: SimpleSpawnResult);
+}
+/**
+ * The result type for {@link whichSync}. Contains the location of the command, any additional locations, and an error if one occurred.
+ */
+export interface WhichResult {
+    location: string | undefined;
+    additionalLocations: string[] | undefined;
+    error: Error | undefined;
+}
+/**
+ * Type guard for command passed to {@link spawnDockerCompose}.
+ */
+export type DockerComposeCommand = 'build' | 'config' | 'cp' | 'create' | 'down' | 'events' | 'exec' | 'images' | 'kill' | 'logs' | 'ls' | 'pause' | 'port' | 'ps' | 'pull' | 'push' | 'restart' | 'rm' | 'run' | 'start' | 'stop' | 'top' | 'unpause' | 'up' | 'version';
+/**
+ * Sleeps for the specified number of milliseconds.
+ * @param ms The number of milliseconds to sleep
+ * @returns A Promise that resolves after the specified number of milliseconds
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * An extension of the built-in SpawnOptions with an extra option to specify whether a non-zero exit code should throw an error.
+ */
+export interface SpawnOptionsWithThrow extends SpawnOptions {
+    throwOnNonZero: boolean;
+    simpleErrorMsg?: string;
+}
+/**
+ * This is a wrapper function for NodeJS spawn. Defaults stdio to inherit so that output is visible in the console,
+ * but note that this means stdout and stderr will not be available in the returned SpawnResult. To hide the output
+ * from the console but collect the stdout and stderr in the SpawnResult, use stdio: 'pipe'.
+ *
+ * When spawning long-running processes, use {@link spawnAsyncLongRunning} instead so that unexpected
+ * termination of the parent process will not orphan the child process tree on windows.
+ *
+ * **Warning:** Do NOT use this for generating commands dynamically from user input as it could be used to execute arbitrary code.
+ * This is meant solely for building up known commands that are not made up of unsanitized user input, and only at compile time.
+ * See {@link winInstallCert} and {@link winUninstallCert} for examples of taking user input and inserting it safely into known commands.
+ * @param command The command to spawn
+ * @param args The arguments to pass to the command
+ * @param options The options to pass to the command
+ * @returns A Promise that resolves to a {@link SpawnResult}
+ */
+export declare function spawnAsync(command: string, args?: string[], options?: Partial<SpawnOptionsWithThrow>): Promise<SpawnResult>;
+/**
+ * Use this alternate spawn wrapper instead of {@link spawnAsync} when spawning long-running processes to
+ * avoid orphaned child process trees on Windows.
+ *
+ * **Warning:** Do NOT use this for generating commands dynamically from user input as it could be used to execute arbitrary code.
+ * This is meant solely for building up known commands that are not made up of unsanitized user input, and only at compile time.
+ * See {@link winInstallCert} and {@link winUninstallCert} for examples of taking user input and inserting it safely into known commands.
+ * @param command The command to spawn
+ * @param args The arguments to pass to the command
+ * @param cwd The current working directory to run the command from - defaults to process.cwd()
+ * @returns A Promise that resolves to a {@link SpawnResult}
+ */
+export declare function spawnAsyncLongRunning(command: string, args?: string[], cwd?: string): Promise<SpawnResult>;
+/**
+ * Ensure the directory exists. Similar to `mkdir -p` (creates parent directories if they don't exist).
+ * @param dir The directory to ensure exists. If it does not exist, it will be created.
+ */
+export declare function ensureDirectory(dir: string): Promise<void>;
+/**
+ * Create a directory. Will create parent directory structure if it don't exist. Similar to `mkdir -p`.
+ * @param dir The directory to create.
+ */
+export declare function mkdirp(dir: string): Promise<void>;
+/**
+ * Create a directory. Will create parent directory structure if it don't exist. Similar to `mkdir -p`.
+ * @param dir The directory to create.
+ */
+export declare function mkdirpSync(dir: string): Promise<void>;
+/**
+ * Empties a directory of all files and subdirectories.
+ *
+ * Optionally skips files and directories at the top level.
+ * @param directoryToEmpty The directory to empty.
+ * @param fileAndDirectoryNamesToSkip An optional array of file and directory names to skip, but only at the top level of the directoryToEmpty.
+ */
+export declare function emptyDirectory(directoryToEmpty: string, fileAndDirectoryNamesToSkip?: string[]): Promise<void>;
+/**
+ * Copies the contents of a directory to another directory (not including the top-level directory itself).
+ *
+ * If the destination directory does not exist, it will be created.
+ * @param sourceDirectory Directory to copy from
+ * @param destinationDirectory Directory to copy to
+ */
+export declare function copyDirectoryContents(sourceDirectory: string, destinationDirectory: string): Promise<void>;
+/**
+ * Helper method to validate that a non-falsy and non-empty value is provided for a parameter that should be a string.
+ * @param paramName The name of the parameter to be used in the error message
+ * @param paramValue The value of the parameter
+ */
+export declare function requireString(paramName: string, paramValue: string): void;
+/**
+ * Helper method to validate that the path actually exists for the provided value.
+ * @param paramName The name of the parameter, for logging purposes
+ * @param paramValue The value of the parameter
+ */
+export declare function requireValidPath(paramName: string, paramValue: string): void;
+/**
+ * Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit.
+ *
+ * See https://docs.docker.com/compose/environment-variables/envvars/#compose_project_name.
+ * @param projectName The string to validate
+ * @returns `true` if it's a valid docker compose project name and `false` otherwise
+ */
+export declare function isDockerComposeProjectNameValid(projectName: string): boolean;
+/**
+ * Options for {@link spawnDockerCompose}.
+ * @param projectName
+ * Note that there are other better options such as using the environment variable `COMPOSE_PROJECT_NAME`. See https://docs.docker.com/compose/environment-variables/envvars/#compose_project_name.
+ * @param attached Default: false. All commands that support the detached option wil use it unless attached is specified as true (-d support: exec, logs, ps, restart, run, start, stop, up)
+ * @param useDockerComposeFileDirectoryAsCwd Default: false. If true, the docker compose command will be run in the directory containing the docker compose file.
+ */
+export interface DockerComposeOptions {
+    /** Additional arguments to pass to the docker-compose command. */
+    args: string[];
+    /**
+     * Defaults to `false`. Controls whether or not the `--detach` option is passed. Note that this only applies to
+     * some commands (exec, logs, ps, restart, run, start, stop, up).
+     */
+    attached: boolean;
+    /**
+    * If not provided, it will default to using the directory that the docker-compose.yml is located in.
+    * Specifies what current working directory to use with the spawn command.
+    */
+    cwd?: string;
+    /**
+     * Optional. If provided, projectName will be passed as the `--project-name` param to `docker compose` so that generated containers will use it as a prefix
+     * instead of the default, which is the directory name where the docker-compose.yml is located.
+     *
+     * Alternate approaches for setting the docker compose project name:
+     *
+     * - Locate your docker-compose.yml file in the root of your project so that docker will use that directory name for prefixing generated containers
+     * - OR, locate your docker-compose.yml in a sub-directory named appropriately for use as a prefix for generated containers
+     * - OR, put a `.env` file in the same directory as your docker-compose.yml
+     * with the entry `COMPOSE_PROJECT_NAME=your-project-name`
+     *
+     * Additional note on docker compose project names form the official docker compose docs: "Project names must contain only lowercase letters, decimal digits,
+     * dashes, and underscores, and must begin with a lowercase letter or decimal digit". See https://docs.docker.com/compose/environment-variables/envvars/#compose_project_name.
+     *
+     */
+    projectName?: string;
+    /**
+     * Optional. If provided, profile is passed to docker compose along with `--profile` param. Must match this regex: `[a-zA-Z0-9][a-zA-Z0-9_.-]+`.
+     *
+     * See https://docs.docker.com/compose/profiles/.
+     */
+    profile?: string;
+}
+/**
+ * For docker compose commands, see https://docs.docker.com/compose/reference/. For available options for this wrapper function, see {@link DockerComposeOptions}.
+ *
+ * The current working directory will be the directory of the {@link dockerComposePath} unless specified in the options. This ensures relative paths in the
+ * docker compose file will be relative to itself by default.
+ *
+ * See {@link DockerComposeOptions.projectName} for info on where to locate your docker compose file and how to specify the docker project name.
+ * @param dockerComposePath Path to docker-compose.yml
+ * @param dockerComposeCommand The docker-compose command to run
+ * @param options {@link DockerComposeOptions} to use, including additional arguments to pass to the docker compose command and the project name
+ */
+export declare function spawnDockerCompose(dockerComposePath: string, dockerComposeCommand: DockerComposeCommand, options?: Partial<DockerComposeOptions>): Promise<void>;
+/**
+ * Splits a string into lines, removing `\n` and `\r` characters. Does not return empty lines. Also see {@link stringToLines}.
+ * @param str String to split into lines
+ * @returns An array of lines from the string, with empty lines removed
+ */
+export declare function stringToNonEmptyLines(str: string): string[];
+/**
+ * Splits a string into lines, removing `\n` and `\r` characters. Returns empty lines. Also see {@link stringToNonEmptyLines}.
+ * @param str String to split into lines
+ * @returns An array of lines from the string, with empty lines removed
+ */
+export declare function stringToLines(str: string): string[];
+/**
+ * Runs the requested command using NodeJS spawnSync wrapped in an outer Windows CMD.exe command and returns the result with stdout split into lines.
+ *
+ * Use this for simple quick commands that don't require a lot of control.
+ *
+ * For commands that aren't Windows and CMD specific, use {@link simpleSpawnSync}.
+ *
+ * **Warning:** Do NOT use this for generating commands dynamically from user input as it could be used to execute arbitrary code.
+ * This is meant solely for building up known commands that are not made up of unsanitized user input, and only at compile time.
+ * See {@link winInstallCert} and {@link winUninstallCert} for examples of taking user input and inserting it safely into known commands.
+ * @param command Command to run
+ * @param args Arguments to pass to the command
+ * @returns An object with the status code, stdout, stderr, and error (if any)
+ * @throws {@link SimpleSpawnError} if the command fails and throwOnNonZero is true
+ */
+export declare function simpleCmdSync(command: string, args?: string[], throwOnNonZero?: boolean): SimpleSpawnResult;
+/**
+ * Runs the requested command using {@link spawnAsync} wrapped in an outer Windows CMD.exe command and returns the result with stdout split into lines.
+ *
+ * Use this for simple quick commands that don't require a lot of control.
+ *
+ * For commands that aren't Windows and CMD specific, use {@link simpleSpawnAsync}.
+ *
+ * **Warning:** Do NOT use this for generating commands dynamically from user input as it could be used to execute arbitrary code.
+ * This is meant solely for building up known commands that are not made up of unsanitized user input, and only at compile time.
+ * See {@link winInstallCert} and {@link winUninstallCert} for examples of taking user input and inserting it safely into known commands.
+ * @param command Command to run
+ * @param args Arguments to pass to the command
+ * @returns An object with the status code, stdout, stderr, and error (if any)
+ * @throws {@link SimpleSpawnError} if the command fails and throwOnNonZero is true
+ */
+export declare function simpleCmdAsync(command: string, args?: string[], throwOnNonZero?: boolean): Promise<SimpleSpawnResult>;
+/**
+ * Runs the requested command using NodeJS spawnSync and returns the result with stdout split into lines.
+ *
+ * Use this for simple quick commands that don't require a lot of control.
+ *
+ * For commands that are Windows and CMD specific, use {@link simpleCmdSync}.
+ *
+ * **Warning:** Do NOT use this for generating commands dynamically from user input as it could be used to execute arbitrary code.
+ * This is meant solely for building up known commands that are not made up of unsanitized user input, and only at compile time.
+ * See {@link winInstallCert} and {@link winUninstallCert} for examples of taking user input and inserting it safely into known commands.
+ * @param command Command to run
+ * @param args Arguments to pass to the command
+ * @returns An object with the status code, stdout, stderr, and error (if any)
+ * @throws {@link SimpleSpawnError} if the command fails and throwOnNonZero is true
+ */
+export declare function simpleSpawnSync(command: string, args?: string[], throwOnNonZero?: boolean): SimpleSpawnResult;
+/**
+ * Runs the requested command using {@link spawnAsync} and returns the result with stdout split into lines.
+ *
+ * Use this for simple quick commands that don't require a lot of control.
+ *
+ * For commands that are Windows and CMD specific, use {@link simpleCmdSync}.
+ *
+ * **Warning:** Do NOT use this for generating commands dynamically from user input as it could be used to execute arbitrary code.
+ * This is meant solely for building up known commands that are not made up of unsanitized user input, and only at compile time.
+ * See {@link winInstallCert} and {@link winUninstallCert} for examples of taking user input and inserting it safely into known commands.
+ * @param command Command to run
+ * @param args Arguments to pass to the command
+ * @returns An object with the status code, stdout, stderr, and error (if any)
+ * @throws {@link SimpleSpawnError} if the command fails and throwOnNonZero is true
+ */
+export declare function simpleSpawnAsync(command: string, args?: string[], throwOnNonZero?: boolean): Promise<SimpleSpawnResult>;
+/**
+ * @returns `true` if platform() is 'win32', `false` otherwise
+ */
+export declare function isPlatformWindows(): boolean;
+/**
+ *
+ * @returns `true` if platform() is 'darwin', `false` otherwise
+ */
+export declare function isPlatformMac(): boolean;
+/**
+ *
+ * @returns `true` if {@link isPlatformWindows} and {@link isPlatformMac} are both `false, otherwise returns `true`
+ */
+export declare function isPlatformLinux(): boolean;
+/**
+ * This is a cross-platform method to get the location of a system command. Useful for checking if software
+ * is installed, where it's installed and whether there are multiple locations.
+ * @param commandName The name of the command to find
+ * @returns The location of the command, any additional locations, and an error if one occurred
+ */
+export declare function which(commandName: string): Promise<WhichResult>;
+/**
+ * This is a cross-platform method to get the location of a system command. Useful for checking if software
+ * is installed, where it's installed and whether there are multiple locations.
+ * @param commandName The name of the command to find
+ * @returns The location of the command, any additional locations, and an error if one occurred
+ */
+export declare function whichSync(commandName: string): WhichResult;
+/**
+ * First checks if docker is installed and if not immediately returns false. Then runs the `docker info`
+ * command and looks for "error during connect" in the output to determine if docker is running.
+ * @returns `true` if docker is installed and running, `false` otherwise
+ */
+export declare function isDockerRunning(): Promise<boolean>;
+/**
+ * Uses built-in NodeJS readline to ask a question and return the user's answer.
+ * @param query The question to ask
+ * @returns A Promise that resolves to the user's answer
+ */
+export declare function askQuestion(query: string): Promise<string>;
+/**
+ * A simple CLI prompt using the built-in NodeJS readline functionality to ask for confirmation.
+ * @param question The question to ask
+ * @returns A Promise that resolves to true if the user answers 'y' or 'yes', false otherwise
+ */
+export declare function getConfirmation(question: string): Promise<boolean>;
+/**
+ * Example of using {@link getConfirmation}.
+ */
+export declare function getConfirmationExample(): Promise<void>;
+/**
+ * Copy entries from a source .env file to a destination .env file for which the destination .env file does not already have entries.
+ * If the destination .env file does not exist, it will be created and populated with the source .env file's values.
+ *
+ * This is useful for copying values from a .env.template file to a root .env file.
+ *
+ * For copying root .env files to other locations, use {@link overwriteEnvFile}.
+ * @param sourcePath The path to the source .env file such as a `.env.template` file (use {@link overwriteEnvFile} for copying root .env files to other locations)
+ * @param destinationPath The path to the destination .env file, such as the root .env file
+ */
+export declare function copyNewEnvValues(sourcePath: string, destinationPath: string): Promise<void>;
+/**
+ * Copy entries from a source .env file to a destination .env file, overwriting any existing entries in the destination .env file.
+ * If the destination .env file does not exist, it will be created and populated with the source .env file's values.
+ *
+ * This is useful for copying values from a root .env file to additional locations (server, client, docker-compose directory, etc.)
+ * throughout your solution so you only have to manage one .env file.
+ *
+ * Note that this does not delete any existing entries in the destination .env file, which is useful if you have additional entries in
+ * the destination .env file that you don't want to overwrite.
+ *
+ * For copying .env.template files to root .env files, use {@link copyNewEnvValues}.
+ * @param sourcePath The path to the source .env file such as a root .env file (use {@link copyNewEnvValues} for .env.template files)
+ * @param destinationPath The path to the destination .env file
+ * @param suppressAddKeysMessages If true, messages about adding missing keys will not be logged (useful if you're always calling {@link copyModifiedEnv} after this call)
+ */
+export declare function overwriteEnvFile(sourcePath: string, destinationPath: string, suppressAddKeysMessages?: boolean): Promise<void>;
+/**
+ * Copy entries from a source .env file to a destination .env file, but only for the keys specified in keepKeys.
+ * Will also modify entries in the destination .env file as specified in modifyEntries.
+ * @param sourcePath The path to the source .env file
+ * @param destinationPath The path to the destination .env file
+ * @param keepKeys The keys to keep from the source .env file
+ * @param modifyEntries The entries to modify in the destination .env file
+ */
+export declare function copyModifiedEnv(sourcePath: string, destinationPath: string, keepKeys: string[], modifyEntries?: StringKeyedDictionary): Promise<void>;
+/**
+ * Filters a dictionary by key.
+ * @param dict The dictionary to filter
+ * @param predicate A function that returns true if the key should be included in the filtered dictionary
+ * @returns A new dictionary with only the keys that passed the predicate
+ */
+export declare function filterDictionary(dict: StringKeyedDictionary, predicate: (key: string) => boolean): StringKeyedDictionary;
+/**
+ * Sorts a dictionary by key in ascending order.
+ * @param dict The dictionary to sort
+ * @returns A new dictionary sorted by key in ascending order
+ */
+export declare function sortDictionaryByKeyAsc(dict: StringKeyedDictionary): StringKeyedDictionary;
+/**
+ * Helper method to delete a .env file if it exists.
+ * @param envPath The path to the .env file to delete
+ */
+export declare function deleteEnvIfExists(envPath: string): Promise<void>;
+export interface FindFilesOptions {
+    maxDepth: number;
+    excludeDirectoryNames: string[];
+    returnForwardSlashRelativePaths: boolean;
+}
+/**
+ * Searches a directory recursively for files that match the specified pattern.
+ * The filenamePattern is a simple text string with asterisks (*) for wildcards.
+ * @param dir The directory to find files in
+ * @param filenamePattern The pattern to match files against
+ * @param options Specify a max depth to search, defaults to 5
+ * @returns A Promise that resolves to an array of file paths that match the pattern
+ */
+export declare function findFilesRecursively(dir: string, filenamePattern: string, options?: Partial<FindFilesOptions>): Promise<string[]>;
+/** Utility function to escape a string for use within regex */
+export declare function escapeStringForRegex(str: string): string;
+/**
+ * Logs the provided 2-dimensional string array as a formatted table.
+ *
+ * @param data 2-dimensional string array where the first row is the column headers
+ * @example
+ *
+ * logTable([
+ *   ['Name', 'Age', 'Country'],
+ *   ['Alice', '28', 'USA'],
+ *   ['Bob', '22', 'Canada']
+ * ])
+ */
+export declare function logTable(data: string[][]): void;
+/**
+ * See {@link getPowershellHackArgs}.
+ */
+export declare const powershellHackPrefix = "$env:PSModulePath = [Environment]::GetEnvironmentVariable('PSModulePath', 'Machine'); ";
+/**
+ * Powershell doesn't load the system PSModulePath when running in a non-interactive shell.
+ * This is a workaround to set the PSModulePath environment variable to the system value before running a powershell command.
+ *
+ * **Warning:** Do NOT use this for generating commands dynamically from user input as it could be used to execute arbitrary code.
+ * This is meant solely for building up known commands that are not made up of unsanitized user input, and only at compile time.
+ * See {@link winInstallCert} and {@link winUninstallCert} for examples of taking user input and inserting it safely into known commands.
+ * @param command The powershell command to run
+ * @returns An array of arguments to pass to {@link spawnAsync} with the "powershell" command as the first argument
+ */
+export declare function getPowershellHackArgs(command: string): string[];
+/**
+ * Returns a humanized string representation of the number of milliseconds using ms, seconds, minutes, or hours.
+ * @param milliseconds The number of milliseconds to humanize
+ * @returns A humanized string representation of the number
+ */
+export declare function humanizeTime(milliseconds: number): string;
+export declare class ExtendedError extends Error {
+    innerError: Error | null;
+    constructor(message: string, innerError?: Error);
+}
+export declare function getHostname(url: string): string;
+export declare function isDirectory(path: string): Promise<boolean>;
+export declare function isDirectorySync(path: string): boolean;
+export type PlatformCode = 'win' | 'linux' | 'mac';
+/**
+ * This is a somewhat naive method but is useful if you rarely or never deal with unusual operating systems.
+ * @returns `win`, `mac` or `linux`
+ */
+export declare function getPlatformCode(): PlatformCode;
+/**
+ * Tries connecting to a port to see if it's being listened on or not. It's likely that this won't work in a lot of scenarios, so use it at your own risk.
+ * @param port The port to check
+ * @returns `true` if the port is available, `false` otherwise
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Returns the value for an environment variable or throws if it's undefined or null. Pass optional {@param throwOnEmpty} to throw when the key exists but has an empty value.
+ * @param varName The name of the environment variable to get.
+ * @param throwOnEmpty Throw an error if key exists (not undefined or null) but is empty.
+ * @returns
+ */
+export declare function getRequiredEnvVar(varName: string, throwOnEmpty?: boolean): string;
+/** Options for {@link withRetryAsync}. */
+export interface WithRetryOptions {
+    /**
+     * Number of milliseconds to wait before the first attempt.
+     */
+    initialDelayMilliseconds: number;
+    /**
+     * Use this in log messages instead of the function name (useful for passing lambdas which would otherwise display as "anonymous").
+     */
+    functionLabel?: string;
+    /**
+     * If NodeCliUtilsConfig.traceEnabled is `true` then messages will be logged even if this option is `false`.
+     * Set to `true` to log messages even if Node ]
+     */
+    traceEnabled: boolean;
+}
+export declare function getNormalizedError(err: unknown): Error;
+/**
+ * Call a function until it succeeds. Will stop after the number of calls specified by {@param maxCalls}, or forever if -1 is passed.
+ * @param func The function to call
+ * @param maxCalls The maximum number of times to call the function before giving up. Pass -1 to retry forever.
+ * @param delayMilliseconds The number of milliseconds to wait between calls
+ * @param options Options for controlling the behavior of the retry. See {@link WithRetryOptions}.
+ */
+export declare function withRetryAsync(func: () => Promise<void>, maxCalls: number, delayMilliseconds: number, options?: Partial<WithRetryOptions>): Promise<void>;
+/**
+ * Collapses each instance of consecutive whitespace characters into a single space.
+ */
+export declare function collapseWhitespace(str: string): string;
+/**
+ * Check if a string is a valid directory name. This is a very simple check that just makes sure the string doesn't contain any invalid characters.
+ * @param dirName The directory name to check
+ * @returns `true` if the directory name is valid, `false` otherwise
+ */
+export declare function isValidDirName(dirName: string): boolean;
+export declare function hasWhitespace(str: string): boolean;
+export declare function stripShellMetaCharacters(input: string): string;
+export declare enum AnsiColor {
+    RESET = "\u001B[0m",
+    RED = "\u001B[31m",
+    GREEN = "\u001B[32m",
+    YELLOW = "\u001B[33m",
+    CYAN = "\u001B[96m",
+    GRAY = "\u001B[90m",
+    PURPLE = "\u001B[35m"
+}
+export declare const color: (str: string, colorAnsiCode: AnsiColor) => string;
+export declare const red: (str: string) => string;
+export declare const green: (str: string) => string;
+export declare const cyan: (str: string) => string;
+export declare const gray: (str: string) => string;
+export declare const purple: (str: string) => string;
+export declare const yellow: (str: string) => string;
+export declare enum Emoji {
+    RightArrow = "\u27A1\uFE0F",
+    LeftArrow = "\u2B05\uFE0F",
+    GreenCheck = "\u2705",
+    Warning = "\u26A0\uFE0F",
+    Lightning = "\u26A1",
+    Exclamation = "\u2757",
+    RedQuestion = "\u2753",
+    RedX = "\u274C",
+    Info = "\u2139\uFE0F",
+    SadFace = "\uD83D\uDE22",
+    Tools = "\uD83D\uDEE0\uFE0F",
+    NoEntry = "\u26D4",
+    Stop = "\uD83D\uDED1",
+    Certificate = "\uD83D\uDCDC",
+    Key = "\uD83D\uDD11"
+}
+//# sourceMappingURL=generalUtils.d.ts.map