@mikeyt23/node-cli-utils 1.4.0 → 2.0.0-beta.1

package/README.md

@@ -1,107 +1,65 @@
-# @mikeyt23/node-cli-utils
-
-Simple node cli utils to:
-
-- Wait for a node spawned process
-- Copy env template file to env file
-- Sync new env values from template to "real" env files
-- Manage all env values in root files that then get copied to other locations
-- Dotnet helper methods:
-  - Pack and publish a NuGet package
-  - Wrapper commands to install or update dotnet ef tool
-  - Wrapper commands to spawn dotnet run and publish
-  - Helper methods for DB migration commands (see [mikey-t/db-migrations-dotnet](https://github.com/mikey-t/db-migrations-dotnet))
-
-# Env Utility Function Notes
-
-A project can have multiple locations that require the same env values. For example, you might have a database that needs to be used by a docker project, your main app and also a db migration project. Rather than having to remember where each of the .env files is, we want to use the root directory and overwrite subdirectory env files with the ones in the root. We also want to add new `.env.template` values to the root `.env` files and propagate them to subdirectories - all without having to know about anything about any of the .env files except the ones in the root of the project.
-
-# Examples
-
-An example syncEnvFiles gulp task function:
-
-```JavaScript
-const projectDir = 'src/YourProjectDir/'
-const serverAppDir = `src/${projectDir}`
-const clientAppDir = `src/${projectDir}client-app/`
-const dockerDir = 'docker/'
-
-async function syncEnvFiles() {
-  const rootServerEnv = './.env.server'
-  const rootClientEnv = './.env.client'
-  
-  // Copy new values from root .env.[category].template to .env.[category]
-  await copyNewEnvValues('./.env.server.template', rootServerEnv)
-  await copyNewEnvValues('./.env.client.template', rootClientEnv)
-
-  // Copy root .env.[category] to subdirectory .env files (overwrites target env file)
-  // Server env to server app and docker directories
-  await overwriteEnvFile(rootServerEnv, path.join(serverAppDir, '.env'))
-  await overwriteEnvFile(rootServerEnv, path.join(dockerDir, '.env'))
-  // Client env to client app directory
-  await overwriteEnvFile(rootClientEnv, path.join(clientAppDir, '.env'))
-}
-
-exports.syncEnvFiles = syncEnvFiles
+# node-cli-utils
+
+This library is a collection of miscellaneous utility functions for Node CLI scripting.
+
+I primarily use this library with [swig-cli](https://github.com/mikey-t/swig) to automate project dev tasks and generally to glue all the things together. Check out an example project that uses both swig-cli and node-cli-utils: [dotnet-react-sandbox](https://github.com/mikey-t/dotnet-react-sandbox).
+
+The auto-generated portion of this project's documentation is auto-generated from JSDoc using [TypeDoc](https://github.com/TypeStrong/typedoc).
+
+## Install
+
+```
+npm install @mikeyt23/node-cli-utils --save-dev
 ```
 
-> **WARNING**: Be sure to .gitignore `.env`, `.env.server` and `.env.client` files in the root **AND** the location they're being copied to. Only the template files with placeholder values should go in source control. For example, your .gitignore could have `**/.env*` and then `!.env.server.template` and `!.env.client.template`, etc.
+## Exported Modules
 
-Example gulp task calling docker-compose:
+Utility functions are loosely grouped into 4 modules:
 
-```JavaScript
-const spawnOptions = {...defaultSpawnOptions}
+| Module | Description |
+|--------|-------------|
+| @mikeyt23/node-cli-util | General utils |
+| @mikeyt23/node-cli-util/dbMigrationUtils  | DB migration utils (see [db-migrations-dotnet](https://github.com/mikey-t/db-migrations-dotnet)) |
+| @mikeyt23/node-cli-util/dotnetUtils | Dotnet utils |
+| @mikeyt23/node-cli-util/certUtils | Cert utils |
 
-const dockerDirPath = 'docker/'
-const dockerDepsProjectName = 'your_project'
-const dockerDepsComposeName = 'docker-compose.deps.yml'
+## Reasoning
 
-const dockerSpawnOptions = {...spawnOptions, cwd: path.resolve(__dirname, dockerDirPath)}
+NodeJS projects are out-of-control with the depth of their dependency trees. Rather than giving in to that trend, I'm attempting to maintain a small set of simple helper methods using built-in NodeJS functionality whenever possible, and only importing things when I simply can't easily reproduce the functionality myself. And when I do import a dependency, it will preferably be one with a shallow dependency tree.
 
-async function dockerDepsUpDetached() {
-  return waitForProcess(spawn('docker-compose', ['--project-name', dockerDepsProjectName, '-f', dockerDepsComposeName, 'up', '-d'], dockerSpawnOptions))
-}
+In some ways this is bad because I'm obviously re-inventing the wheel and there's other libraries that do some of this stuff way better. But here's what I'm getting by doing it this way:
 
-exports.dockerDepsUpDetached = series(syncEnvFiles, dockerDepsUpDetached)
-```
+- Significantly less work to keep things up to date - I don't have to audit dozens or hundreds or thousands of dependency and transitive dependency updates on a regular basis
+- Significantly less (or zero) risk of NPM supply chain attacks
+- Getting more hands-on XP with the fundamentals of NodeJS Typescript development
+- Control. Do I know who to talk to for bug fixes or feature improvements? Of course I know him - he's me!
 
-Example gulp task using util method `throwIfDockerNotRunning`:
+Originally I made an exception to this rule for [node-tar](https://github.com/isaacs/node-tar). However, I replaced this with a system call to the OS built-in `tar` utility since even Windows has this built-in since 2018.
 
+Also - just my personal opinion - every serious developer should create and maintain libraries like this. It's not always about reinventing the wheel or not. Sometimes it's about learning about different types of wheels by creating some yourself.
 
-```JavaScript
-async function dockerDepsUp() {
-  await throwIfDockerNotRunning()
-  return waitForProcess(spawn('docker-compose', ['--project-name', dockerDepsProjectName, '-f', dockerDepsComposeName, 'up'], dockerSpawnOptions))
-}
+## Noteworthy Features
 
-exports.dockerDepsUp = series(syncEnvFiles, dockerDepsUp)
-```
+### Process Spawning Cross-Platform Workarounds
 
-Example gulp task using util method `dockerContainerIsRunning`:
+Dev automation tasks in all my projects make heavy use of spawning child processes, but unfortunately there's a lot of issues that cause this to be inconsistent across platforms. I've attempted to normalize some of the more annoying edge cases. 
 
-```JavaScript
-async function throwIfDockerDepsNotUp() {
-  const postgresIsRunning = await dockerContainerIsRunning(`${dockerDepsProjectName}_postgresql`)
-  if (!postgresIsRunning) {
-    throw 'Docker dependencies are not running'
-  }
-}
+For example, sometimes the only way to get a command to work how you want on windows is to pass the `shell: true` option. One case where this is useful is for running commands for a long running process that you want to be able to terminate with `ctrl+c` when you're done with it. These are commands like `docker compose up`, or running a dev web server, or anything that runs until you stop it. But on windows when you use `ctrl+c` to terminate a process spawned without the `shell: true` option, it immediately kills all the processes in the tree without warning or signaling, which is bad if those processes need to shut down gracefully before exiting. For example, on windows if you use `ctrl+c` on `docker compose up` spawned by Node, you'll notice that the containers are still running even after the attached command exits. But if you do the same thing on a nix machine, docker is given the `SIGINT` signal and it gracefully stops the containers before shutting down.
 
-async function runDbMigrator() {
-  return waitForProcess(spawn('dotnet', [`publish/${DotnetNamespace}.DbMigrator.dll`], migratorSpawnOptions))
-}
+But this issue is of the whack-a-mole variety, because if you do go ahead and pass the `shell: true` option, then unexpected termination of the parent process will simply orphan your child process tree, forcing you to kill it yourself manually, or with some other scripting.
 
-exports.dbMigrate = series(throwIfDockerDepsNotUp, parallel(syncEnvFiles, deleteMigratorPublishDir), publishMigrator, runDbMigrator)
-```
+So normally you can do one of a couple things so that your process spawning code works well on windows in addition to nix machines:
 
-Example gulp task using util method `bashIntoRunningDockerContainer` and `argv` to pass in param `--imageName`:
+- Use another library where someone claims to have solved this completely in a cross-platform way (`press x to doubt`), and accept a non-trivial number of dependencies into your project
+- Use the non-shell option and just deal with some commands terminating non-gracefully
+- Use the shell option and just deal with long running processes sometimes getting orphaned
 
-```JavaScript
-async function dockerBashRunningContainer() {
-  await throwIfDockerNotRunning()
-  await bashIntoRunningDockerContainer(`${dockerDepsProjectName}_${argv['imageName']}`)
-}
+Instead I've chosen to create a couple of different wrapper methods for Node's spawn method. One calls spawn fairly normally (`spawnAsync` in [./src/generalUtils.ts](./src/generalUtils.ts)), with an additional option to get the exec-like functionality of throwing on non-zero return code if you want. And another wrapper that is used for long running processes that uses the shell option, but if you're on windows does a nifty little hack to spawn a "middle" watchdog process that polls for whether the parent is alive or not and kills the child process tree if it becomes orphaned (`spawnAsyncLongRunning` in [./src/generalUtils.ts](./src/generalUtils.ts)).
 
-exports.dockerBash = dockerBashRunningContainer
-```
+In the future I may go research how others have solved cross-platform process spawning, but for now this little hack works fine.
+
+## TODO
 
+- More unit tests
+- Build out example projects that use both CommonJS and ESM
+- Move the DB migration utils out of this library into it's own space

package/dist/cjs/NodeCliUtilsConfig.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Config to control a few misc settings in the node-cli-utils package. This module exports a singleton instance.
+ */
+export declare class NodeCliUtilsConfig {
+    private _traceEnabled;
+    private _orphanProtectionPollingIntervalMillis;
+    private _orphanProtectionLoggingEnabled;
+    private _orphanProtectionLoggingPath;
+    get traceEnabled(): boolean;
+    set traceEnabled(value: boolean);
+    get orphanProtectionPollingIntervalMillis(): number;
+    set orphanProtectionPollingIntervalMillis(value: number);
+    get orphanProtectionLoggingEnabled(): boolean;
+    set orphanProtectionLoggingEnabled(value: boolean);
+    get orphanProtectionLoggingPath(): string;
+}
+/**
+ * Singleton instance of {@link NodeCliUtilsConfig}.
+ */
+export declare const config: NodeCliUtilsConfig;
+//# sourceMappingURL=NodeCliUtilsConfig.d.ts.map

package/dist/cjs/NodeCliUtilsConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeCliUtilsConfig.d.ts","sourceRoot":"","sources":["../../src/NodeCliUtilsConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,sCAAsC,CAAQ;IACtD,OAAO,CAAC,+BAA+B,CAAQ;IAC/C,OAAO,CAAC,4BAA4B,CAA2B;IAE/D,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,IAAI,YAAY,CAAC,KAAK,EAAE,OAAO,EAE9B;IAED,IAAI,qCAAqC,IAAI,MAAM,CAElD;IAED,IAAI,qCAAqC,CAAC,KAAK,EAAE,MAAM,EAEtD;IAED,IAAI,8BAA8B,IAAI,OAAO,CAE5C;IAED,IAAI,8BAA8B,CAAC,KAAK,EAAE,OAAO,EAEhD;IAED,IAAI,2BAA2B,IAAI,MAAM,CAExC;CACF;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,oBAA2B,CAAA"}

package/dist/cjs/NodeCliUtilsConfig.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = exports.NodeCliUtilsConfig = void 0;
+/**
+ * Config to control a few misc settings in the node-cli-utils package. This module exports a singleton instance.
+ */
+class NodeCliUtilsConfig {
+    constructor() {
+        this._traceEnabled = false;
+        this._orphanProtectionPollingIntervalMillis = 15000;
+        this._orphanProtectionLoggingEnabled = false;
+        this._orphanProtectionLoggingPath = './orphanProtection.log';
+    }
+    get traceEnabled() {
+        return this._traceEnabled;
+    }
+    set traceEnabled(value) {
+        this._traceEnabled = value;
+    }
+    get orphanProtectionPollingIntervalMillis() {
+        return this._orphanProtectionPollingIntervalMillis;
+    }
+    set orphanProtectionPollingIntervalMillis(value) {
+        this._orphanProtectionPollingIntervalMillis = value;
+    }
+    get orphanProtectionLoggingEnabled() {
+        return this._orphanProtectionLoggingEnabled;
+    }
+    set orphanProtectionLoggingEnabled(value) {
+        this._orphanProtectionLoggingEnabled = value;
+    }
+    get orphanProtectionLoggingPath() {
+        return this._orphanProtectionLoggingPath;
+    }
+}
+exports.NodeCliUtilsConfig = NodeCliUtilsConfig;
+/**
+ * Singleton instance of {@link NodeCliUtilsConfig}.
+ */
+exports.config = new NodeCliUtilsConfig();
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiTm9kZUNsaVV0aWxzQ29uZmlnLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL05vZGVDbGlVdGlsc0NvbmZpZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQTs7R0FFRztBQUNILE1BQWEsa0JBQWtCO0lBQS9CO1FBQ1Usa0JBQWEsR0FBWSxLQUFLLENBQUM7UUFDL0IsMkNBQXNDLEdBQUcsS0FBSyxDQUFBO1FBQzlDLG9DQUErQixHQUFHLEtBQUssQ0FBQTtRQUN2QyxpQ0FBNEIsR0FBRyx3QkFBd0IsQ0FBQTtJQTZCakUsQ0FBQztJQTNCQyxJQUFJLFlBQVk7UUFDZCxPQUFPLElBQUksQ0FBQyxhQUFhLENBQUE7SUFDM0IsQ0FBQztJQUVELElBQUksWUFBWSxDQUFDLEtBQWM7UUFDN0IsSUFBSSxDQUFDLGFBQWEsR0FBRyxLQUFLLENBQUE7SUFDNUIsQ0FBQztJQUVELElBQUkscUNBQXFDO1FBQ3ZDLE9BQU8sSUFBSSxDQUFDLHNDQUFzQyxDQUFBO0lBQ3BELENBQUM7SUFFRCxJQUFJLHFDQUFxQyxDQUFDLEtBQWE7UUFDckQsSUFBSSxDQUFDLHNDQUFzQyxHQUFHLEtBQUssQ0FBQTtJQUNyRCxDQUFDO0lBRUQsSUFBSSw4QkFBOEI7UUFDaEMsT0FBTyxJQUFJLENBQUMsK0JBQStCLENBQUE7SUFDN0MsQ0FBQztJQUVELElBQUksOEJBQThCLENBQUMsS0FBYztRQUMvQyxJQUFJLENBQUMsK0JBQStCLEdBQUcsS0FBSyxDQUFBO0lBQzlDLENBQUM7SUFFRCxJQUFJLDJCQUEyQjtRQUM3QixPQUFPLElBQUksQ0FBQyw0QkFBNEIsQ0FBQTtJQUMxQyxDQUFDO0NBQ0Y7QUFqQ0QsZ0RBaUNDO0FBRUQ7O0dBRUc7QUFDVSxRQUFBLE1BQU0sR0FBRyxJQUFJLGtCQUFrQixFQUFFLENBQUEifQ==

package/dist/cjs/TarballUtility.d.ts

@@ -0,0 +1,53 @@
+import { whichSync } from './generalUtils.js';
+export interface CreateTarballOptions {
+    /**
+     * A list of files or directories to exclude from the tarball.
+     * The paths should be relative to the directoryToTarball.
+     */
+    excludes?: string[];
+}
+export interface TarballUnpackOptions {
+    createDirIfNotExists?: boolean;
+    stripComponents?: number;
+    throwOnNonEmptyUnpackDir?: boolean;
+}
+/**
+ * This utility class exists so we can mock the `which` dependency in unit tests without resorting to libraries that hack the import system.
+ */
+export declare class TarballUtility {
+    private whichSyncFn;
+    constructor(whichSyncFn: typeof whichSync);
+    /**
+     * Creates a gzipped tarball from a directory by spawning a process to run OS-installed `tar` to avoid pulling in npm package dependencies.
+     * Note that Windows has tar since Windows 10 1803 (see https://devblogs.microsoft.com/commandline/windows10v1803/.
+     *
+     * It's possible this isn't 100% reliable due to differences in `tar` versions across platforms. If better normalization
+     * is required, consider using the npm package `node-tar` instead.
+     * @param directoryToTarball The directory to tarball. The directory name will be used as the root directory in the tarball
+     * @param tarballPath The path to the tarball to create - must end with '.tar.gz'
+     * @param options See {@link CreateTarballOptions}
+     */
+    createTarball: (directoryToTarball: string, tarballPath: string, options?: CreateTarballOptions) => Promise<void>;
+    /**
+     * Unpacks a gzipped tarball by spawning a process to run OS-installed `tar` to avoid pulling in npm package dependencies.
+     * This method will throw an error if the unpackDirectory is not empty, unless the `throwOnNonEmptyUnpackDir` option is set to false.
+     * @param tarballPath The path to the tarball to unpack
+     * @param unpackDirectory The directory to unpack the tarball into
+     * @param options The options to use when unpacking the tarball. See {@link TarballUnpackOptions}.
+     */
+    unpackTarball: (tarballPath: string, unpackDirectory: string, options?: TarballUnpackOptions) => Promise<void>;
+    /**
+     * A more opinionated version of {@link unpackTarball} that assumes you want to create the directory and strip the first directory out of the unpacked files.
+     * @param tarballPath The path to the tarball to unpack
+     * @param unpackDirectory The directory to unpack the tarball into - will be created if it doesn't exist and will throw if it exists but is not empty
+     * @param stripComponents The number of leading directories to strip out of the unpacked files, defaults to 1
+     */
+    unpackTarballContents: (tarballPath: string, unpackDirectory: string, stripComponents?: number) => Promise<void>;
+    private isDirectory;
+    private dirIsNotEmpty;
+    private tryCreateDirectory;
+}
+export declare const createTarball: (directoryToTarball: string, tarballPath: string, options?: CreateTarballOptions) => Promise<void>;
+export declare const unpackTarball: (tarballPath: string, unpackDirectory: string, options?: TarballUnpackOptions) => Promise<void>;
+export declare const unpackTarballContents: (tarballPath: string, unpackDirectory: string, stripComponents?: number) => Promise<void>;
+//# sourceMappingURL=TarballUtility.d.ts.map

package/dist/cjs/TarballUtility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TarballUtility.d.ts","sourceRoot":"","sources":["../../src/TarballUtility.ts"],"names":[],"mappings":"AAGA,OAAO,EAA8D,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAGzG,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wBAAwB,CAAC,EAAE,OAAO,CAAA;CACnC;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAkB;gBAEzB,WAAW,EAAE,OAAO,SAAS;IAIzC;;;;;;;;;OASG;IACH,aAAa,uBAA8B,MAAM,eAAe,MAAM,YAAY,oBAAoB,mBA4CrG;IAED;;;;;;OAMG;IACH,aAAa,gBAAuB,MAAM,mBAAmB,MAAM,YAAY,oBAAoB,mBA0ClG;IAED;;;;;OAKG;IACH,qBAAqB,gBAAuB,MAAM,mBAAmB,MAAM,oBAAmB,MAAM,mBAEnG;IAED,OAAO,CAAC,WAAW,CAOlB;IAED,OAAO,CAAC,aAAa,CAOpB;IAED,OAAO,CAAC,kBAAkB,CAUzB;CACF;AAID,eAAO,MAAM,aAAa,uBA5ImB,MAAM,eAAe,MAAM,YAAY,oBAAoB,kBA4IlD,CAAA;AACtD,eAAO,MAAM,aAAa,gBAxFY,MAAM,mBAAmB,MAAM,YAAY,oBAAoB,kBAwF/C,CAAA;AACtD,eAAO,MAAM,qBAAqB,gBAvCY,MAAM,mBAAmB,MAAM,oBAAmB,MAAM,kBAuChC,CAAA"}

package/dist/cjs/TarballUtility.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unpackTarballContents = exports.unpackTarball = exports.createTarball = exports.TarballUtility = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const generalUtils_js_1 = require("./generalUtils.js");
+const NodeCliUtilsConfig_js_1 = require("./NodeCliUtilsConfig.js");
+/**
+ * This utility class exists so we can mock the `which` dependency in unit tests without resorting to libraries that hack the import system.
+ */
+class TarballUtility {
+    constructor(whichSyncFn) {
+        /**
+         * Creates a gzipped tarball from a directory by spawning a process to run OS-installed `tar` to avoid pulling in npm package dependencies.
+         * Note that Windows has tar since Windows 10 1803 (see https://devblogs.microsoft.com/commandline/windows10v1803/.
+         *
+         * It's possible this isn't 100% reliable due to differences in `tar` versions across platforms. If better normalization
+         * is required, consider using the npm package `node-tar` instead.
+         * @param directoryToTarball The directory to tarball. The directory name will be used as the root directory in the tarball
+         * @param tarballPath The path to the tarball to create - must end with '.tar.gz'
+         * @param options See {@link CreateTarballOptions}
+         */
+        this.createTarball = async (directoryToTarball, tarballPath, options) => {
+            (0, generalUtils_js_1.requireValidPath)('directoryToTarball', directoryToTarball);
+            (0, generalUtils_js_1.requireString)('tarballPath', tarballPath);
+            const defaultOptions = { excludes: [] };
+            const mergedOptions = { ...defaultOptions, ...options };
+            if (!this.whichSyncFn('tar').location) {
+                throw new Error('tar command not found - please install tar on your OS to use this method, or consider using the npm package node-tar instead');
+            }
+            if (!node_fs_1.default.existsSync(directoryToTarball)) {
+                throw new Error(`directoryToTarball does not exist: ${directoryToTarball}`);
+            }
+            if (tarballPath.endsWith('.tar.gz') === false) {
+                throw new Error(`tarballPath must end with '.tar.gz': ${tarballPath}`);
+            }
+            const directoryToTarballParentDir = node_path_1.default.dirname(directoryToTarball);
+            const directoryToTarballName = node_path_1.default.basename(directoryToTarball);
+            const outputDirectory = node_path_1.default.dirname(tarballPath);
+            const tarballName = node_path_1.default.basename(tarballPath);
+            if (!node_fs_1.default.existsSync(outputDirectory)) {
+                (0, generalUtils_js_1.trace)(`tarballPath directory does not exist - creating '${outputDirectory}'`);
+                await (0, generalUtils_js_1.mkdirp)(outputDirectory);
+            }
+            else if (node_fs_1.default.existsSync(tarballPath)) {
+                (0, generalUtils_js_1.trace)(`removing existing tarball '${tarballName}' before creating new one`);
+                await promises_1.default.unlink(tarballPath);
+            }
+            const excludesArgs = mergedOptions.excludes.length > 0 ? mergedOptions.excludes.map(exclude => `--exclude=${exclude}`) : [];
+            const verboseFlag = NodeCliUtilsConfig_js_1.config.traceEnabled ? ['-v'] : [];
+            const args = [...(verboseFlag), '-czf', tarballPath, '-C', directoryToTarballParentDir, ...excludesArgs, directoryToTarballName];
+            const result = await (0, generalUtils_js_1.spawnAsync)('tar', args);
+            if (result.code !== 0) {
+                throw new Error(`tar command failed with code ${result.code}`);
+            }
+            (0, generalUtils_js_1.trace)('tarball created: ' + tarballPath);
+        };
+        /**
+         * Unpacks a gzipped tarball by spawning a process to run OS-installed `tar` to avoid pulling in npm package dependencies.
+         * This method will throw an error if the unpackDirectory is not empty, unless the `throwOnNonEmptyUnpackDir` option is set to false.
+         * @param tarballPath The path to the tarball to unpack
+         * @param unpackDirectory The directory to unpack the tarball into
+         * @param options The options to use when unpacking the tarball. See {@link TarballUnpackOptions}.
+         */
+        this.unpackTarball = async (tarballPath, unpackDirectory, options) => {
+            (0, generalUtils_js_1.requireValidPath)('tarballPath', tarballPath);
+            (0, generalUtils_js_1.requireString)('unpackDirectory', unpackDirectory);
+            if (!this.whichSyncFn('tar').location) {
+                throw new Error('tar command not found - please install tar on your OS to use this method, or consider using the npm package node-tar instead');
+            }
+            const defaultOptions = { createDirIfNotExists: false, stripComponents: 0, throwOnNonEmptyUnpackDir: true };
+            const mergedOptions = { ...defaultOptions, ...options };
+            if (mergedOptions.stripComponents < 0) {
+                throw new Error('stripComponents must be greater than or equal to 0 if provided');
+            }
+            const unpackedDirExists = node_fs_1.default.existsSync(unpackDirectory);
+            if (unpackedDirExists && !this.isDirectory(unpackDirectory)) {
+                throw new Error(`unpackDirectory exists but is not a directory: ${unpackDirectory}`);
+            }
+            if (mergedOptions.createDirIfNotExists && !unpackedDirExists) {
+                await this.tryCreateDirectory(unpackDirectory);
+            }
+            if (!mergedOptions.createDirIfNotExists && !unpackedDirExists) {
+                throw new Error(`unpackDirectory does not exist: ${unpackDirectory}`);
+            }
+            if (mergedOptions.throwOnNonEmptyUnpackDir && this.dirIsNotEmpty(unpackDirectory)) {
+                throw new Error(`unpackDirectory exists but is not empty: ${unpackDirectory}`);
+            }
+            const verboseFlag = NodeCliUtilsConfig_js_1.config.traceEnabled ? ['-v'] : [];
+            const args = [...(verboseFlag), '-xzf', tarballPath, '-C', unpackDirectory, '--strip-components', mergedOptions.stripComponents.toString()];
+            const result = await (0, generalUtils_js_1.spawnAsync)('tar', args);
+            if (result.code !== 0) {
+                throw new Error(`tar command failed with code ${result.code}`);
+            }
+            (0, generalUtils_js_1.trace)(`tarball unpacked at ${unpackDirectory}`);
+        };
+        /**
+         * A more opinionated version of {@link unpackTarball} that assumes you want to create the directory and strip the first directory out of the unpacked files.
+         * @param tarballPath The path to the tarball to unpack
+         * @param unpackDirectory The directory to unpack the tarball into - will be created if it doesn't exist and will throw if it exists but is not empty
+         * @param stripComponents The number of leading directories to strip out of the unpacked files, defaults to 1
+         */
+        this.unpackTarballContents = async (tarballPath, unpackDirectory, stripComponents = 1) => {
+            await this.unpackTarball(tarballPath, unpackDirectory, { stripComponents, createDirIfNotExists: true });
+        };
+        this.isDirectory = (path) => {
+            try {
+                const stats = node_fs_1.default.statSync(path);
+                return stats.isDirectory();
+            }
+            catch (err) {
+                return false;
+            }
+        };
+        this.dirIsNotEmpty = (dirPath) => {
+            try {
+                const stats = node_fs_1.default.statSync(dirPath);
+                return stats.isDirectory() && node_fs_1.default.readdirSync(dirPath).length > 0;
+            }
+            catch (err) {
+                return false;
+            }
+        };
+        this.tryCreateDirectory = async (dirPath) => {
+            try {
+                await (0, generalUtils_js_1.mkdirp)(dirPath);
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    throw new Error(`Error creating unpackDirectory: ${err.message}`);
+                }
+                else {
+                    throw new Error(`Error creating unpackDirectory: ${err}`);
+                }
+            }
+        };
+        this.whichSyncFn = whichSyncFn;
+    }
+}
+exports.TarballUtility = TarballUtility;
+const defaultUtil = new TarballUtility(generalUtils_js_1.whichSync);
+exports.createTarball = defaultUtil.createTarball;
+exports.unpackTarball = defaultUtil.unpackTarball;
+exports.unpackTarballContents = defaultUtil.unpackTarballContents;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiVGFyYmFsbFV0aWxpdHkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvVGFyYmFsbFV0aWxpdHkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7O0FBQUEsc0RBQXdCO0FBQ3hCLGdFQUFrQztBQUNsQywwREFBNEI7QUFDNUIsdURBQXlHO0FBQ3pHLG1FQUFnRDtBQWdCaEQ7O0dBRUc7QUFDSCxNQUFhLGNBQWM7SUFHekIsWUFBWSxXQUE2QjtRQUl6Qzs7Ozs7Ozs7O1dBU0c7UUFDSCxrQkFBYSxHQUFHLEtBQUssRUFBRSxrQkFBMEIsRUFBRSxXQUFtQixFQUFFLE9BQThCLEVBQUUsRUFBRTtZQUN4RyxJQUFBLGtDQUFnQixFQUFDLG9CQUFvQixFQUFFLGtCQUFrQixDQUFDLENBQUE7WUFDMUQsSUFBQSwrQkFBYSxFQUFDLGFBQWEsRUFBRSxXQUFXLENBQUMsQ0FBQTtZQUV6QyxNQUFNLGNBQWMsR0FBRyxFQUFFLFFBQVEsRUFBRSxFQUFFLEVBQUUsQ0FBQTtZQUN2QyxNQUFNLGFBQWEsR0FBRyxFQUFFLEdBQUcsY0FBYyxFQUFFLEdBQUcsT0FBTyxFQUFFLENBQUE7WUFFdkQsSUFBSSxDQUFDLElBQUksQ0FBQyxXQUFXLENBQUMsS0FBSyxDQUFDLENBQUMsUUFBUSxFQUFFO2dCQUNyQyxNQUFNLElBQUksS0FBSyxDQUFDLDhIQUE4SCxDQUFDLENBQUE7YUFDaEo7WUFFRCxJQUFJLENBQUMsaUJBQUUsQ0FBQyxVQUFVLENBQUMsa0JBQWtCLENBQUMsRUFBRTtnQkFDdEMsTUFBTSxJQUFJLEtBQUssQ0FBQyxzQ0FBc0Msa0JBQWtCLEVBQUUsQ0FBQyxDQUFBO2FBQzVFO1lBRUQsSUFBSSxXQUFXLENBQUMsUUFBUSxDQUFDLFNBQVMsQ0FBQyxLQUFLLEtBQUssRUFBRTtnQkFDN0MsTUFBTSxJQUFJLEtBQUssQ0FBQyx3Q0FBd0MsV0FBVyxFQUFFLENBQUMsQ0FBQTthQUN2RTtZQUVELE1BQU0sMkJBQTJCLEdBQUcsbUJBQUks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

package/dist/cjs/certUtils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wrapper function for calling openssl to generate a self-signed cert to be used for developing a local website with trusted https.
+ * @param url The url to generate a cert for. This will be used as the common name (CN) in the cert as well as the filename for the generated cert files.
+ * @param outputDirectory The directory to write the generated cert files to. Defaults to './cert'.
+ */
+export declare function generateCertWithOpenSsl(url: string, outputDirectory?: string): Promise<void>;
+/**
+ * Uses Powershell to install a cert to the local machine's trusted root store. Must have admin permissions.
+ *
+ * If the cert is already installed, this method will do nothing.
+ * @param urlOrCertFilename The url or cert filename to install. The url + '.pfx' or the cert filename passed must match a file that exists in the certDirectory.
+ * @param certDirectory The directory to look for the cert file in. Defaults to './cert'.
+ */
+export declare function winInstallCert(urlOrCertFilename: string, certDirectory?: string): Promise<void>;
+/**
+ * Uses Powershell to uninstall a cert from the local machine's trusted root store. Must have admin permissions.
+ * @param urlOrSubject The url or subject of the cert to uninstall. If the cert was installed with the winInstallCert method, this will be the url passed to that method.
+ */
+export declare function winUninstallCert(urlOrSubject: string): Promise<void>;
+/**
+ * Does not actually do anything - just outputs the manual instructions for installing a cert for use by chrome on linux.
+ */
+export declare function linuxInstallCert(): void;
+/**
+ * Uses Powershell to check if a cert is already installed to the local machine's trusted root store.
+ * @param urlOrSubject The url or subject of the cert to check. If the cert was installed with the winInstallCert method, this will be the url passed to that method.
+ * @returns `true` if the cert is already installed, `false` otherwise.
+ */
+export declare function winCertAlreadyInstalled(urlOrSubject: string): Promise<boolean>;
+//# sourceMappingURL=certUtils.d.ts.map

package/dist/cjs/certUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certUtils.d.ts","sourceRoot":"","sources":["../../src/certUtils.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,GAAE,MAAiB,iBAuD5F;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,iBAAiB,EAAE,MAAM,EAAE,aAAa,SAAW,iBA8BvF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,iBAY1D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,SAU/B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBpF"}