@augment-vir/node 30.7.0 → 30.8.0

package/dist/augments/terminal/relevant-args.d.ts

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

package/dist/augments/terminal/relevant-args.js

@@ -0,0 +1,49 @@
+import { basename } from 'node:path';
+/**
+ * Trims arguments list to remove all arguments that take place before the script's file name or
+ * executable bin name.
+ *
+ * @category Node : Terminal
+ * @category Package : @augment-vir/node
+ * @example
+ *
+ * ```ts
+ * extractRelevantArgs({
+ *     rawArgs: [
+ *         'npx',
+ *         'ts-node',
+ *         './my-script.ts',
+ *         'arg1',
+ *         '--arg2',
+ *     ], // typically will be process.argv
+ *     binName: 'my-script', // should be your package.json "bin" property name, can be undefined
+ *     fileName: 'my-script.ts', // should be __filename from the script that will be executed
+ * });
+ * // will output ['arg1', '--arg2']
+ * ```
+ *
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function extractRelevantArgs({ rawArgs, binName, fileName, errorIfNotFound, }) {
+    const baseFileName = basename(fileName);
+    if (!baseFileName) {
+        throw new Error(`Given file name produced no base file name (with path.basename()): '${fileName}'`);
+    }
+    const lastIrrelevantArgIndex = rawArgs.findIndex((arg) => {
+        const baseArgName = basename(arg);
+        const matchesFileName = baseArgName === baseFileName;
+        const matchesBinName = binName ? baseArgName === binName : false;
+        return matchesFileName || matchesBinName;
+    });
+    if (lastIrrelevantArgIndex === -1) {
+        if (errorIfNotFound) {
+            throw new Error('Failed to find position of file or bin name in provided args list.');
+        }
+        else {
+            return [...rawArgs];
+        }
+    }
+    else {
+        return rawArgs.slice(lastIrrelevantArgIndex + 1);
+    }
+}

package/dist/augments/terminal/run-cli-script.d.ts

@@ -0,0 +1,22 @@
+/** This file cannot be tested because it calls `process.exit`. */
+/**
+ * A map of file extensions to their known runners for {@link runCliScript}.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare const ExtensionToRunner: Record<string, string>;
+/**
+ * Runs a script path as if it had been run directly, as much as possible.
+ *
+ * @category Node : Terminal : Util
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function runCliScript(path: string, 
+/**
+ * This should be the bin name of the package that is calling this function. Set to `undefined`
+ * if there isn't one.
+ */
+binName: string | undefined): Promise<void>;

package/dist/augments/terminal/run-cli-script.js

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

package/dist/index.d.ts

@@ -14,4 +14,6 @@ export * from './augments/path/os-path.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
+export * from './augments/terminal/relevant-args.js';
+export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';

package/dist/index.js

@@ -14,4 +14,6 @@ export * from './augments/path/os-path.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
+export * from './augments/terminal/relevant-args.js';
+export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "30.7.0",
+    "version": "30.8.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -37,8 +37,8 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^30.7.0",
-        "@augment-vir/common": "^30.7.0",
+        "@augment-vir/assert": "^30.8.0",
+        "@augment-vir/common": "^30.8.0",
         "@date-vir/duration": "^7.0.1",
         "ansi-styles": "^6.2.1",
         "terminate": "^2.8.0",
@@ -46,7 +46,7 @@
         "typed-event-target": "^4.0.2"
     },
     "devDependencies": {
-        "@augment-vir/test": "^30.7.0",
+        "@augment-vir/test": "^30.8.0",
         "@prisma/client": "^5.22.0",
         "@types/node": "^22.9.0",
         "@web/dev-server-esbuild": "^1.0.3",