@augment-vir/node 31.3.0 → 31.5.0

package/dist/augments/npm/find-bin-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the path to an npm package executable bin by searching in all ancestor `node_modules/.bin`
+ * folders, starting at the given `startPath`.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findNpmBinPath({ binName, startPath, }: {
+    startPath: string;
+    binName: string;
+}): string | undefined;

package/dist/augments/npm/find-bin-path.js

@@ -0,0 +1,21 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { findAncestor } from '../path/ancestor.js';
+/**
+ * Finds the path to an npm package executable bin by searching in all ancestor `node_modules/.bin`
+ * folders, starting at the given `startPath`.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function findNpmBinPath({ binName, startPath, }) {
+    const binPath = join('node_modules', '.bin', binName);
+    const ancestor = findAncestor(startPath, (ancestor) => {
+        return existsSync(join(ancestor, binPath));
+    });
+    if (!ancestor) {
+        return undefined;
+    }
+    return join(ancestor, binPath);
+}

package/dist/augments/prisma.d.ts

@@ -12,17 +12,17 @@ export type { PrismaMigrationStatus } from '../prisma/prisma-migrations.js';
  *
  * - Deploy to production
  *
- *   - {@link prisma.migration.applyProd}
+ *   - `prisma.migration.applyProd()`
  * - Update dev environment
  *
- *   - Apply migrations: {@link prisma.migration.applyDev}
+ *   - Apply migrations: `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}
+ *               `prisma.migration.create`
+ *       - If throws {@link PrismaResetNeededError}, reset the database with `prisma.database.resetDev`
  *   - Generate client: `prisma.client.isCurrent`
  *
- *       - If `false`, run {@link prisma.client.generate}
+ *       - If `false`, run `prisma.client.generate`
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node
@@ -50,7 +50,7 @@ export declare const prisma: {
         applyProd: typeof applyPrismaMigrationsToProd;
         /**
          * Apply all migrations. Meant for a development environment, with less protections than
-         * {@link prisma.migration.applyProd}.
+         * `prisma.migration.applyProd()`
          *
          * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
          *   to input a name.
@@ -70,8 +70,8 @@ export declare const prisma: {
          */
         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.
+         * Uses `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;
         /**
@@ -102,8 +102,8 @@ export declare const prisma: {
          */
         isCurrent: typeof isGeneratedPrismaClientCurrent;
         /**
-         * Adds a collection of create data to a database through a `PrismaClient` instance. This is
-         * particularly useful for setting up mocks in a mock PrismaClient.
+         * Adds a collection of create data entries to a database through a `PrismaClient` instance.
+         * This is particularly useful for setting up mocks in a mock PrismaClient.
          *
          * @example
          *

package/dist/augments/prisma.js

@@ -10,17 +10,17 @@ export * from '../prisma/prisma-errors.js';
  *
  * - Deploy to production
  *
- *   - {@link prisma.migration.applyProd}
+ *   - `prisma.migration.applyProd()`
  * - Update dev environment
  *
- *   - Apply migrations: {@link prisma.migration.applyDev}
+ *   - Apply migrations: `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}
+ *               `prisma.migration.create`
+ *       - If throws {@link PrismaResetNeededError}, reset the database with `prisma.database.resetDev`
  *   - Generate client: `prisma.client.isCurrent`
  *
- *       - If `false`, run {@link prisma.client.generate}
+ *       - If `false`, run `prisma.client.generate`
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node
@@ -48,7 +48,7 @@ export const prisma = {
         applyProd: applyPrismaMigrationsToProd,
         /**
          * Apply all migrations. Meant for a development environment, with less protections than
-         * {@link prisma.migration.applyProd}.
+         * `prisma.migration.applyProd()`
          *
          * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
          *   to input a name.
@@ -68,8 +68,8 @@ export const prisma = {
          */
         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.
+         * Uses `prisma.database.diff` to detect if there are any differences between the current
+         * database and the Prisma schema that should control it.
          */
         hasDiff: doesPrismaDiffExist,
         /**
@@ -100,8 +100,8 @@ export const prisma = {
          */
         isCurrent: isGeneratedPrismaClientCurrent,
         /**
-         * Adds a collection of create data to a database through a `PrismaClient` instance. This is
-         * particularly useful for setting up mocks in a mock PrismaClient.
+         * Adds a collection of create data entries to a database through a `PrismaClient` instance.
+         * This is particularly useful for setting up mocks in a mock PrismaClient.
          *
          * @example
          *
@@ -142,7 +142,7 @@ export const prisma = {
          * ]);
          * ```
          */
-        addData: addData,
+        addData,
         /**
          * Dump data from the current database through a `PrismaClient` instance.
          *

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

@@ -6,7 +6,9 @@
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export declare const ExtensionToRunner: Record<string, string>;
+export declare const ExtensionToRunner: Record<string, string | {
+    npx: string;
+}>;
 /**
  * Runs a script path as if it had been run directly, as much as possible.
  *
@@ -14,7 +16,7 @@ export declare const ExtensionToRunner: Record<string, string>;
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export declare function runCliScript(path: string, 
+export declare function runCliScript(scriptPath: string, 
 /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
 cliScriptFilePath: string, 
 /**

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

@@ -1,6 +1,8 @@
 /* node:coverage disable */
 /** This file cannot be tested because it calls `process.exit`. */
-import { extname } from 'node:path';
+import { check } from '@augment-vir/assert';
+import { dirname, extname } from 'node:path';
+import { findNpmBinPath } from '../npm/find-bin-path.js';
 import { interpolationSafeWindowsPath } from '../path/os-path.js';
 import { extractRelevantArgs } from './relevant-args.js';
 import { runShellCommand } from './shell.js';
@@ -12,7 +14,9 @@ import { runShellCommand } from './shell.js';
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export const ExtensionToRunner = {
-    '.ts': 'tsx',
+    '.ts': {
+        npx: 'tsx',
+    },
     '.js': 'node',
     '.sh': 'bash',
 };
@@ -23,7 +27,7 @@ export const ExtensionToRunner = {
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export async function runCliScript(path, 
+export async function runCliScript(scriptPath, 
 /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
 cliScriptFilePath, 
 /**
@@ -36,12 +40,18 @@ binName) {
         binName,
         fileName: cliScriptFilePath,
     });
-    const extension = extname(path);
+    const extension = extname(scriptPath);
     const runner = ExtensionToRunner[extension];
     if (!runner) {
         throw new Error("No runner configured for file extension '${extension}' in '${path}'");
     }
-    const results = await runShellCommand(interpolationSafeWindowsPath([runner, path, ...args].join(' ')), {
+    const runnerPath = check.isString(runner)
+        ? runner
+        : findNpmBinPath({
+            binName: runner.npx,
+            startPath: dirname(cliScriptFilePath),
+        }) || runner.npx;
+    const results = await runShellCommand(interpolationSafeWindowsPath([runnerPath, scriptPath, ...args].join(' ')), {
         hookUpToConsole: true,
     });
     process.exit(results.exitCode || 0);

package/dist/docker/containers/container-info.d.ts

@@ -1,7 +1,7 @@
 import type { JsonCompatibleArray, JsonCompatibleObject } from '@augment-vir/common';
 import type { DockerContainerStatus } from './container-status.js';
 /**
- * Properties on {@link DockerContainerInfo}.State, retrieved from {@link getContainerInfo}.
+ * Properties on {@link DockerContainerInfo}.State, retrieved from `docker.container.getInfo()`.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node
@@ -22,8 +22,8 @@ export type DockerContainerInfoState = {
 };
 /** This type signature is incomplete. Add to it as necessary. */
 /**
- * Properties on the output from {@link getContainerInfo}. Not all these properties are filled in all
- * the way, particularly most of properties with nested objects.
+ * Properties on the output from `docker.container.getInfo()`. Not all these properties are filled
+ * in all the way, particularly most of properties with nested objects.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
+export * from './augments/npm/find-bin-path.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
+export * from './augments/npm/find-bin-path.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';

package/dist/prisma/model-data.d.ts

@@ -1,8 +1,8 @@
 import { BasePrismaClient, PrismaAllModelsCreate, type PartialWithUndefined, type PrismaAllBasicModels, type PrismaModelName } from '@augment-vir/common';
 import type { IsAny } from 'type-fest';
 /**
- * Params for {@link addData}. This is similar to {@link PrismaAllModelsCreate} but allows an array of
- * {@link PrismaAllModelsCreate} for sequential data creation.
+ * Params for `prisma.client.addData()`. This is similar to {@link PrismaAllModelsCreate} but allows
+ * an array of {@link PrismaAllModelsCreate} for sequential data creation.
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "31.3.0",
+    "version": "31.5.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": "^31.3.0",
-        "@augment-vir/common": "^31.3.0",
+        "@augment-vir/assert": "^31.5.0",
+        "@augment-vir/common": "^31.5.0",
         "@date-vir/duration": "^7.1.1",
         "ansi-styles": "^6.2.1",
         "terminate": "^2.8.0",
@@ -46,9 +46,9 @@
         "typed-event-target": "^4.0.2"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.3.0",
+        "@augment-vir/test": "^31.5.0",
         "@prisma/client": "^6.1.0",
-        "@types/node": "^22.10.2",
+        "@types/node": "^22.10.5",
         "@web/dev-server-esbuild": "^1.0.3",
         "@web/test-runner": "^0.19.0",
         "@web/test-runner-commands": "^0.9.0",

package/src/augments/npm/find-bin-path.ts

@@ -0,0 +1,31 @@
+import {existsSync} from 'node:fs';
+import {join} from 'node:path';
+import {findAncestor} from '../path/ancestor.js';
+
+/**
+ * Finds the path to an npm package executable bin by searching in all ancestor `node_modules/.bin`
+ * folders, starting at the given `startPath`.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function findNpmBinPath({
+    binName,
+    startPath,
+}: {
+    startPath: string;
+    binName: string;
+}): string | undefined {
+    const binPath = join('node_modules', '.bin', binName);
+
+    const ancestor = findAncestor(startPath, (ancestor) => {
+        return existsSync(join(ancestor, binPath));
+    });
+
+    if (!ancestor) {
+        return undefined;
+    }
+
+    return join(ancestor, binPath);
+}

package/src/augments/prisma.ts

@@ -29,17 +29,17 @@ export type {PrismaMigrationStatus} from '../prisma/prisma-migrations.js';
  *
  * - Deploy to production
  *
- *   - {@link prisma.migration.applyProd}
+ *   - `prisma.migration.applyProd()`
  * - Update dev environment
  *
- *   - Apply migrations: {@link prisma.migration.applyDev}
+ *   - Apply migrations: `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}
+ *               `prisma.migration.create`
+ *       - If throws {@link PrismaResetNeededError}, reset the database with `prisma.database.resetDev`
  *   - Generate client: `prisma.client.isCurrent`
  *
- *       - If `false`, run {@link prisma.client.generate}
+ *       - If `false`, run `prisma.client.generate`
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node
@@ -67,7 +67,7 @@ export const prisma = {
         applyProd: applyPrismaMigrationsToProd,
         /**
          * Apply all migrations. Meant for a development environment, with less protections than
-         * {@link prisma.migration.applyProd}.
+         * `prisma.migration.applyProd()`
          *
          * @throws `PrismaMigrationNeededError` when a new migration is required so the user needs
          *   to input a name.
@@ -87,8 +87,8 @@ export const prisma = {
          */
         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.
+         * Uses `prisma.database.diff` to detect if there are any differences between the current
+         * database and the Prisma schema that should control it.
          */
         hasDiff: doesPrismaDiffExist,
         /**
@@ -119,8 +119,8 @@ export const prisma = {
          */
         isCurrent: isGeneratedPrismaClientCurrent,
         /**
-         * Adds a collection of create data to a database through a `PrismaClient` instance. This is
-         * particularly useful for setting up mocks in a mock PrismaClient.
+         * Adds a collection of create data entries to a database through a `PrismaClient` instance.
+         * This is particularly useful for setting up mocks in a mock PrismaClient.
          *
          * @example
          *
@@ -161,7 +161,7 @@ export const prisma = {
          * ]);
          * ```
          */
-        addData: addData,
+        addData,
         /**
          * Dump data from the current database through a `PrismaClient` instance.
          *

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

@@ -1,7 +1,9 @@
 /* node:coverage disable */
 /** This file cannot be tested because it calls `process.exit`. */
 
-import {extname} from 'node:path';
+import {check} from '@augment-vir/assert';
+import {dirname, extname} from 'node:path';
+import {findNpmBinPath} from '../npm/find-bin-path.js';
 import {interpolationSafeWindowsPath} from '../path/os-path.js';
 import {extractRelevantArgs} from './relevant-args.js';
 import {runShellCommand} from './shell.js';
@@ -13,8 +15,10 @@ import {runShellCommand} from './shell.js';
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
-export const ExtensionToRunner: Record<string, string> = {
-    '.ts': 'tsx',
+export const ExtensionToRunner: Record<string, string | {npx: string}> = {
+    '.ts': {
+        npx: 'tsx',
+    },
     '.js': 'node',
     '.sh': 'bash',
 };
@@ -27,7 +31,7 @@ export const ExtensionToRunner: Record<string, string> = {
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function runCliScript(
-    path: string,
+    scriptPath: string,
     /** This should just be `__filename` (for CJS) or `import.meta.filename` (for ESM). */
     cliScriptFilePath: string,
     /**
@@ -42,7 +46,7 @@ export async function runCliScript(
         fileName: cliScriptFilePath,
     });
 
-    const extension = extname(path);
+    const extension = extname(scriptPath);
 
     const runner = ExtensionToRunner[extension];
 
@@ -50,8 +54,15 @@ export async function runCliScript(
         throw new Error("No runner configured for file extension '${extension}' in '${path}'");
     }
 
+    const runnerPath = check.isString(runner)
+        ? runner
+        : findNpmBinPath({
+              binName: runner.npx,
+              startPath: dirname(cliScriptFilePath),
+          }) || runner.npx;
+
     const results = await runShellCommand(
-        interpolationSafeWindowsPath([runner, path, ...args].join(' ')),
+        interpolationSafeWindowsPath([runnerPath, scriptPath, ...args].join(' ')),
         {
             hookUpToConsole: true,
         },

package/src/docker/containers/container-info.ts

@@ -3,7 +3,7 @@ import {runShellCommand} from '../../augments/terminal/shell.js';
 import type {DockerContainerStatus} from './container-status.js';
 
 /**
- * Properties on {@link DockerContainerInfo}.State, retrieved from {@link getContainerInfo}.
+ * Properties on {@link DockerContainerInfo}.State, retrieved from `docker.container.getInfo()`.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node
@@ -26,8 +26,8 @@ export type DockerContainerInfoState = {
 /** This type signature is incomplete. Add to it as necessary. */
 
 /**
- * Properties on the output from {@link getContainerInfo}. Not all these properties are filled in all
- * the way, particularly most of properties with nested objects.
+ * Properties on the output from `docker.container.getInfo()`. Not all these properties are filled
+ * in all the way, particularly most of properties with nested objects.
  *
  * @category Node : Docker : Util
  * @category Package : @augment-vir/node

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './augments/fs/read-dir.js';
 export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
+export * from './augments/npm/find-bin-path.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';

package/src/prisma/model-data.ts

@@ -20,8 +20,8 @@ import {
 import type {IsAny} from 'type-fest';
 
 /**
- * Params for {@link addData}. This is similar to {@link PrismaAllModelsCreate} but allows an array of
- * {@link PrismaAllModelsCreate} for sequential data creation.
+ * Params for `prisma.client.addData()`. This is similar to {@link PrismaAllModelsCreate} but allows
+ * an array of {@link PrismaAllModelsCreate} for sequential data creation.
  *
  * @category Prisma : Node
  * @category Package : @augment-vir/node