@augment-vir/node 32.2.0 → 32.2.2

package/dist/augments/fs/dir-contents.d.ts

@@ -30,6 +30,10 @@ export declare function resetDirContents(rootDir: string, contents: Readonly<Dir
 /**
  * Write {@link DirContents} to a directory.
  *
+ * Keys are always relative to `rootDir`. A key that traverses above it (such as `'../escaped.txt'`)
+ * throws instead of writing, so contents built from an untrusted source cannot reach outside the
+ * directory they were meant for.
+ *
  * @category Node : File
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)

package/dist/augments/fs/dir-contents.js

@@ -2,6 +2,7 @@ import { check } from '@augment-vir/assert';
 import { getObjectTypedEntries } from '@augment-vir/common';
 import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { doesPathContain } from '../path/contains.js';
 import { writeFileAndDir } from './write.js';
 /**
  * Read all contents within a directory and store them in an object. Optionally recursive.
@@ -26,7 +27,7 @@ export async function readAllDirContents(dir, { recursive = false, excludeList,
         }
         const isFile = (await stat(filePath)).isFile();
         const contents = isFile
-            ? (await readFile(filePath)).toString()
+            ? await readFile(filePath, 'utf8')
             : recursive
                 ? await readAllDirContents(filePath, {
                     recursive,
@@ -63,6 +64,10 @@ export async function resetDirContents(rootDir, contents) {
 /**
  * Write {@link DirContents} to a directory.
  *
+ * Keys are always relative to `rootDir`. A key that traverses above it (such as `'../escaped.txt'`)
+ * throws instead of writing, so contents built from an untrusted source cannot reach outside the
+ * directory they were meant for.
+ *
  * @category Node : File
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
@@ -70,6 +75,12 @@ export async function resetDirContents(rootDir, contents) {
 export async function writeDirContents(rootDir, contents) {
     await Promise.all(getObjectTypedEntries(contents).map(async ([relativePath, content,]) => {
         const fullPath = join(rootDir, relativePath);
+        if (!doesPathContain({
+            potentialParentPath: rootDir,
+            potentialChildPath: fullPath,
+        })) {
+            throw new Error(`Cannot write '${relativePath}': it resolves outside of '${rootDir}'.`);
+        }
         if (check.isString(content)) {
             await writeFileAndDir(fullPath, content);
         }

package/dist/augments/fs/grep.js

@@ -1,31 +1,26 @@
 import { assert, check } from '@augment-vir/assert';
-import { awaitedBlockingMap, getObjectTypedKeys, log, typedObjectFromEntries, } from '@augment-vir/common';
+import { awaitedBlockingMap, getObjectTypedKeys, log, shellQuote, typedObjectFromEntries, } from '@augment-vir/common';
 import { spawn } from 'node:child_process';
 import { lstat, readdir, stat } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { isOperatingSystem, OperatingSystem } from '../os/operating-system.js';
 const grepBinPath = '/usr/bin/grep';
-function shellQuote(input) {
-    return [
-        "'",
-        input.replaceAll("'", String.raw `'\''`),
-        "'",
-    ].join('');
-}
 function recursiveFlag({ recursive, followSymLinks, }) {
     if (!recursive) {
         return '';
     }
-    else if (!followSymLinks) {
+    else if (followSymLinks) {
+        /**
+         * BSD `grep` (macOS) requires `-S` to follow symlinks while recursing, but GNU `grep`
+         * (Linux) has no `-S` flag and instead follows all symlinks with `-R`. Only one of these
+         * branches can run on a given operating system.
+         */
+        /* node:coverage ignore next */
+        return isOperatingSystem(OperatingSystem.Mac) ? '-RS' : '-R';
+    }
+    else {
         return '--recursive';
     }
-    /**
-     * BSD `grep` (macOS) requires `-S` to follow symlinks while recursing, but GNU `grep` (Linux)
-     * has no `-S` flag and instead follows all symlinks with `-R`. Only one of these branches can
-     * run on a given operating system.
-     */
-    /* node:coverage ignore next */
-    return isOperatingSystem(OperatingSystem.Mac) ? '-RS' : '-R';
 }
 function isValidMaxCount(maxCount) {
     return (maxCount == undefined ||
@@ -156,12 +151,14 @@ function formatGrepCommand(args) {
     const operandDelimiterIndex = args.indexOf('--');
     return [
         'grep',
-        ...args.map((arg, index) => shellQuote(redactGrepArgForLogging({
-            arg,
-            index,
-            operandDelimiterIndex,
-            previousArg: args[index - 1],
-        }))),
+        ...args.map((arg, index) => {
+            return shellQuote(redactGrepArgForLogging({
+                arg,
+                index,
+                operandDelimiterIndex,
+                previousArg: args[index - 1],
+            }));
+        }),
     ].join(' ');
 }
 function replaceGrepCountOutputArg({ args, replacement, }) {
@@ -186,7 +183,9 @@ function extractOptionalStringArray(input) {
     else if (!check.isArray(input) || !input.every(check.isString)) {
         return undefined;
     }
-    return input.filter(check.isTruthy);
+    else {
+        return input.filter(check.isTruthy);
+    }
 }
 function extractString(input) {
     return check.isString(input) && input ? input : undefined;
@@ -247,18 +246,20 @@ function createSearchLocation(grepSearchLocation) {
             ],
         };
     }
-    else if (grepSearchLocation.dirs != undefined) {
+    else if (grepSearchLocation.dirs == undefined) {
+        return dir
+            ? {
+                dirs: [
+                    dir,
+                ],
+            }
+            : undefined;
+    }
+    else {
         return {
             dirs: extractStringArray(grepSearchLocation.dirs),
         };
     }
-    return dir
-        ? {
-            dirs: [
-                dir,
-            ],
-        }
-        : undefined;
 }
 function resolveSearchPart({ cwd, searchPart, }) {
     return cwd && !isAbsolute(searchPart) ? resolve(cwd, searchPart) : searchPart;
@@ -322,11 +323,13 @@ async function createSearchParts({ cwd, followSymLinks, recursive, searchLocatio
     return searchLocation.dirs
         ? recursive
             ? filteredSearchParts
-            : (await awaitedBlockingMap(filteredSearchParts, (dir) => readDirectDirSearchParts({
-                cwd,
-                dir,
-                followSymLinks,
-            }))).flat()
+            : (await awaitedBlockingMap(filteredSearchParts, (dir) => {
+                return readDirectDirSearchParts({
+                    cwd,
+                    dir,
+                    followSymLinks,
+                });
+            })).flat()
         : filteredSearchParts;
 }
 function createGrepCountEntry({ countString, fileName }) {
@@ -364,7 +367,7 @@ function parseNullDelimitedGrepRecords({ stdout }) {
     }
     return records;
 }
-/* node:coverage ignore next 26 */
+/* node:coverage ignore next 28 */
 function parseColonDelimitedGrepCountOutput(stdout) {
     return typedObjectFromEntries(stdout
         .trimEnd()
@@ -380,12 +383,14 @@ function parseColonDelimitedGrepCountOutput(stdout) {
         });
     })
         .filter(check.isTruthy)
-        .map((entry) => [
-        entry.key,
-        entry.value,
-    ]));
+        .map((entry) => {
+        return [
+            entry.key,
+            entry.value,
+        ];
+    }));
 }
-/* node:coverage ignore next 20 */
+/* node:coverage ignore next 22 */
 function parseGrepCountOutput(stdout) {
     return stdout.includes('\0')
         ? typedObjectFromEntries(parseNullDelimitedGrepRecords({
@@ -398,10 +403,12 @@ function parseGrepCountOutput(stdout) {
             });
         })
             .filter(check.isTruthy)
-            .map((entry) => [
-            entry.key,
-            entry.value,
-        ]))
+            .map((entry) => {
+            return [
+                entry.key,
+                entry.value,
+            ];
+        }))
         : parseColonDelimitedGrepCountOutput(stdout);
 }
 /* node:coverage ignore next 7 */
@@ -478,20 +485,24 @@ async function runGrepCountFallback({ cwd, grepArgs, }) {
         });
     }))
         .filter(check.isTruthy)
-        .map((entry) => [
-        entry.key,
-        entry.value,
-    ]));
+        .map((entry) => {
+        return [
+            entry.key,
+            entry.value,
+        ];
+    }));
 }
 function parseGrepFilesOnlyOutput(stdout) {
     return typedObjectFromEntries(
     /* node:coverage ignore next */
     (stdout.includes('\0') ? stdout.split('\0') : stdout.trimEnd().split('\n'))
         .filter(check.isTruthy)
-        .map((entry) => [
-        entry,
-        [],
-    ]));
+        .map((entry) => {
+        return [
+            entry,
+            [],
+        ];
+    }));
 }
 function parseGrepNormalOutput(stdout) {
     const fileMatches = new Map();
@@ -580,10 +591,12 @@ export async function grep(grepSearchPattern, grepSearchLocation, options = {})
             ? grepOptionArrays.includeFiles.map((includeFile) => `--include=${includeFile}`)
             : []),
         grepOptions.binary ? '--binary' : '',
-        ...searchPatterns.flatMap((searchPattern) => [
-            '-e',
-            searchPattern,
-        ]),
+        ...searchPatterns.flatMap((searchPattern) => {
+            return [
+                '-e',
+                searchPattern,
+            ];
+        }),
         '--',
         ...searchParts,
     ].filter(check.isTruthy);

package/dist/augments/fs/json.js

@@ -15,7 +15,7 @@ import { writeFileAndDir } from './write.js';
  */
 export async function readJsonFile(path) {
     try {
-        const contents = (await readFile(path)).toString();
+        const contents = await readFile(path, 'utf8');
         return JSON.parse(contents);
     }
     catch {

package/dist/augments/fs/read-dir.js

@@ -41,5 +41,7 @@ export async function readDirRecursive(dirPath) {
 export async function readDirFilesByExtension({ dirPath, extension, extensions, }) {
     const extensionsToCheck = extensions || [extension];
     const fileNames = await readdir(dirPath);
-    return fileNames.filter((fileName) => extensionsToCheck.some((extensionToCheck) => fileName.endsWith(extensionToCheck)));
+    return fileNames.filter((fileName) => {
+        return extensionsToCheck.some((extensionToCheck) => fileName.endsWith(extensionToCheck));
+    });
 }

package/dist/augments/fs/read-file.js

@@ -10,7 +10,7 @@ import { readFile } from 'node:fs/promises';
  */
 export async function readFileIfExists(path) {
     if (existsSync(path)) {
-        return (await readFile(path)).toString();
+        return await readFile(path, 'utf8');
     }
     else {
         return undefined;

package/dist/augments/npm/package-json.js

@@ -15,7 +15,9 @@ import { findAncestor, joinFilesToDir } from '../path/ancestor.js';
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function findAllPackageJsonFilePaths(startDirPath) {
-    const packageRootDir = findAncestor(startDirPath, (dir) => existsSync(join(dir, 'package-lock.json')));
+    const packageRootDir = findAncestor(startDirPath, (dir) => {
+        return existsSync(join(dir, 'package-lock.json'));
+    });
     if (!packageRootDir) {
         throw new Error(`Cannot find all package.json files: failed to find any directory with a package-lock.json file. Started at '${startDirPath}'.`);
     }

package/dist/augments/npm/read-package-json.js

@@ -16,8 +16,10 @@ export async function readPackageJson(dirPath) {
     if (!packageJson) {
         throw new TypeError(`package.json file does not exist in '${dirPath}'`);
     }
-    else if (!check.isObject(packageJson)) {
+    else if (check.isObject(packageJson)) {
+        return packageJson;
+    }
+    else {
         throw new TypeError(`Parsing package.json file did not return an object in '${dirPath}'`);
     }
-    return packageJson;
 }

package/dist/augments/path/contains.js

@@ -23,8 +23,10 @@ export function doesPathContain({ potentialParentPath, potentialChildPath, optio
         /** On Windows, paths on different drives yield an absolute relative path. */
         return false;
     }
-    /** Contained if it does not traverse up out of parent. */
-    return relativePath !== '..' && !relativePath.startsWith('..' + sep);
+    else {
+        /** Contained if it does not traverse up out of parent. */
+        return relativePath !== '..' && !relativePath.startsWith('..' + sep);
+    }
 }
 function normalizePath(inputPath) {
     const absolutePath = normalize(resolve(inputPath));

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

@@ -18,6 +18,12 @@ export declare function toPosixPath(maybeWindowsPath: string): string;
  * Use this to interpolate paths into bash commands. If the given path is not a Windows path, the
  * path structure will not be modified.
  *
+ * Each round of bash parsing halves the backslashes, so the count here assumes _two_ rounds: a
+ * command string that bash parses and then hands to something which parses it again. Four
+ * backslashes arrive as one. For a command that bash parses only once, this over-escapes; use
+ * `shellQuote` from `@augment-vir/common` instead, which needs no multiplication because bash does
+ * no escape processing inside single quotes.
+ *
  * @category Path : Node
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)

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

@@ -34,6 +34,12 @@ export function toPosixPath(maybeWindowsPath) {
  * Use this to interpolate paths into bash commands. If the given path is not a Windows path, the
  * path structure will not be modified.
  *
+ * Each round of bash parsing halves the backslashes, so the count here assumes _two_ rounds: a
+ * command string that bash parses and then hands to something which parses it again. Four
+ * backslashes arrive as one. For a command that bash parses only once, this over-escapes; use
+ * `shellQuote` from `@augment-vir/common` instead, which needs no multiplication because bash does
+ * no escape processing inside single quotes.
+ *
  * @category Path : Node
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)

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

@@ -1,9 +1,9 @@
 /* node:coverage disable */
 /** This file cannot be tested because it calls `process.exit`. */
 import { check } from '@augment-vir/assert';
+import { shellQuote } from '@augment-vir/common';
 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';
 /**
@@ -44,11 +44,13 @@ export async function runCliScript({ scriptPath, cliScriptFilePath, binName, })
             binName: runner.npx,
             startPath: dirname(cliScriptFilePath),
         }) || runner.npx;
-    const results = await runShellCommand(interpolationSafeWindowsPath([
+    const results = await runShellCommand([
         runnerPath,
         scriptPath,
         ...args,
-    ].join(' ')), {
+    ]
+        .map(shellQuote)
+        .join(' '), {
         hookUpToConsole: true,
     });
     process.exit(results.exitCode || 0);

package/dist/augments/typescript/read-tsconfig.js

@@ -11,7 +11,9 @@ import { findAncestor } from '../path/ancestor.js';
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export function readTsconfig(startingPath) {
-    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) => existsSync(join(ancestorPath, 'tsconfig.json')));
+    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) => {
+        return existsSync(join(ancestorPath, 'tsconfig.json'));
+    });
     const tsconfigPath = tsconfigDirPath ? join(tsconfigDirPath, 'tsconfig.json') : undefined;
     if (!tsconfigPath) {
         return undefined;

package/dist/scripts/fix-src-imports.script.js

@@ -57,7 +57,7 @@ async function updateAllPackageJsonPaths(monoRepoPath) {
 async function fixAllSrcImports(monoRepoPath) {
     const filePaths = await findFilesThatNeedImportFixes(monoRepoPath);
     await Promise.all(filePaths.map(async (filePath) => {
-        const contents = String(await readFile(filePath));
+        const contents = await readFile(filePath, 'utf8');
         const fixedContents = contents.replaceAll(/(from ["'][^'"]+?)\/src\/([^'"]+)['"];/g, "$1/dist/$2';");
         await writeFile(filePath, fixedContents);
         log.faint(`Fixed imports in ${relative(monoRepoPath, filePath)}`);

package/dist/scripts/fix-ts-bin.script.js

@@ -15,8 +15,7 @@
  * ```
  */
 import { log } from '@augment-vir/common';
-import { interpolationSafeWindowsPath, runShellCommand } from '@augment-vir/node';
-import { readFile, rm, writeFile } from 'node:fs/promises';
+import { chmod, readFile, rm, writeFile } from 'node:fs/promises';
 import { join, sep } from 'node:path/posix';
 const packagesToFix = [
     {
@@ -63,7 +62,7 @@ async function fixTsBin(packageToFix) {
         force: true,
     });
     await writeFile(binFilePath, createBinFileContents(packageToFix));
-    await runShellCommand(`chmod +x ${interpolationSafeWindowsPath(binFilePath)}`);
+    await chmod(binFilePath, 0o755);
     await fixPackageJson(packageToFix);
     log.success(`Fixed ${packageToFix.packageName} bin.`);
 }
@@ -72,7 +71,7 @@ async function fixPackageJson(packageToFix) {
         return;
     }
     const packageJsonPath = join(process.cwd(), 'node_modules', packageToFix.packageName, 'package.json');
-    const original = String(await readFile(packageJsonPath));
+    const original = await readFile(packageJsonPath, 'utf8');
     await writeFile(packageJsonPath, original
         .replace('"main": "dist/index.js"', '"main": "src/index.ts"')
         .replace('"module": "dist/index.js"', '"module": "src/index.ts"'));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "32.2.0",
+    "version": "32.2.2",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -38,22 +38,22 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^32.2.0",
-        "@augment-vir/common": "^32.2.0",
-        "@date-vir/duration": "^8.6.1",
-        "ansi-styles": "^6.2.3",
+        "@augment-vir/assert": "^32.2.2",
+        "@augment-vir/common": "^32.2.2",
+        "@date-vir/duration": "^9.0.0",
+        "ansi-styles": "^7.0.0",
         "sanitize-filename": "^1.6.4",
         "terminate": "^2.8.0",
-        "tsx": "^4.22.4",
-        "typed-event-target": "^4.3.1"
+        "tsx": "^4.23.11",
+        "typed-event-target": "^4.3.3"
     },
     "devDependencies": {
-        "@augment-vir/test": "^32.2.0",
-        "@types/node": "^26.0.1",
-        "@web/dev-server-esbuild": "^1.0.5",
-        "@web/test-runner": "^0.20.2",
-        "@web/test-runner-playwright": "^0.11.1",
-        "c8": "^11.0.0",
+        "@augment-vir/test": "^32.2.2",
+        "@types/node": "^26.2.0",
+        "@web/dev-server-esbuild": "^2.0.0",
+        "@web/test-runner": "^1.0.0",
+        "@web/test-runner-playwright": "^1.0.0",
+        "c8": "^12.0.0",
         "istanbul-smart-text-reporter": "^1.1.5",
         "typescript": "^6.0.3"
     },

package/src/augments/fs/dir-contents.ts

@@ -2,6 +2,7 @@ import {check} from '@augment-vir/assert';
 import {getObjectTypedEntries} from '@augment-vir/common';
 import {readdir, readFile, rm, stat} from 'node:fs/promises';
 import {join} from 'node:path';
+import {doesPathContain} from '../path/contains.js';
 import {writeFileAndDir} from './write.js';
 
 /**
@@ -52,7 +53,7 @@ export async function readAllDirContents(
 
             const isFile = (await stat(filePath)).isFile();
             const contents = isFile
-                ? (await readFile(filePath)).toString()
+                ? await readFile(filePath, 'utf8')
                 : recursive
                   ? await readAllDirContents(filePath, {
                         recursive,
@@ -98,6 +99,10 @@ export async function resetDirContents(
 /**
  * Write {@link DirContents} to a directory.
  *
+ * Keys are always relative to `rootDir`. A key that traverses above it (such as `'../escaped.txt'`)
+ * throws instead of writing, so contents built from an untrusted source cannot reach outside the
+ * directory they were meant for.
+ *
  * @category Node : File
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
@@ -113,6 +118,18 @@ export async function writeDirContents(
                 content,
             ]) => {
                 const fullPath = join(rootDir, relativePath);
+
+                if (
+                    !doesPathContain({
+                        potentialParentPath: rootDir,
+                        potentialChildPath: fullPath,
+                    })
+                ) {
+                    throw new Error(
+                        `Cannot write '${relativePath}': it resolves outside of '${rootDir}'.`,
+                    );
+                }
+
                 if (check.isString(content)) {
                     await writeFileAndDir(fullPath, content);
                 } else {

package/src/augments/fs/grep.ts

@@ -3,6 +3,7 @@ import {
     awaitedBlockingMap,
     getObjectTypedKeys,
     log,
+    shellQuote,
     typedObjectFromEntries,
     type IsEqual,
     type PartialWithUndefined,
@@ -180,31 +181,23 @@ export type GrepSearchPattern = RequireExactlyOne<{
 
 const grepBinPath = '/usr/bin/grep';
 
-function shellQuote(input: string) {
-    return [
-        "'",
-        input.replaceAll("'", String.raw`'\''`),
-        "'",
-    ].join('');
-}
-
 function recursiveFlag({
     recursive,
     followSymLinks,
 }: Readonly<Pick<GrepOptions, 'recursive' | 'followSymLinks'>>): string {
     if (!recursive) {
         return '';
-    } else if (!followSymLinks) {
+    } else if (followSymLinks) {
+        /**
+         * BSD `grep` (macOS) requires `-S` to follow symlinks while recursing, but GNU `grep`
+         * (Linux) has no `-S` flag and instead follows all symlinks with `-R`. Only one of these
+         * branches can run on a given operating system.
+         */
+        /* node:coverage ignore next */
+        return isOperatingSystem(OperatingSystem.Mac) ? '-RS' : '-R';
+    } else {
         return '--recursive';
     }
-
-    /**
-     * BSD `grep` (macOS) requires `-S` to follow symlinks while recursing, but GNU `grep` (Linux)
-     * has no `-S` flag and instead follows all symlinks with `-R`. Only one of these branches can
-     * run on a given operating system.
-     */
-    /* node:coverage ignore next */
-    return isOperatingSystem(OperatingSystem.Mac) ? '-RS' : '-R';
 }
 
 function isValidMaxCount(maxCount: unknown) {
@@ -380,16 +373,16 @@ function formatGrepCommand(args: ReadonlyArray<string>) {
 
     return [
         'grep',
-        ...args.map((arg, index) =>
-            shellQuote(
+        ...args.map((arg, index) => {
+            return shellQuote(
                 redactGrepArgForLogging({
                     arg,
                     index,
                     operandDelimiterIndex,
                     previousArg: args[index - 1],
                 }),
-            ),
-        ),
+            );
+        }),
     ].join(' ');
 }
 
@@ -430,9 +423,9 @@ function extractOptionalStringArray(input: unknown) {
         return [];
     } else if (!check.isArray(input) || !input.every(check.isString)) {
         return undefined;
+    } else {
+        return input.filter(check.isTruthy);
     }
-
-    return input.filter(check.isTruthy);
 }
 
 function extractString(input: unknown) {
@@ -519,19 +512,19 @@ function createSearchLocation(
                 file,
             ],
         };
-    } else if (grepSearchLocation.dirs != undefined) {
+    } else if (grepSearchLocation.dirs == undefined) {
+        return dir
+            ? {
+                  dirs: [
+                      dir,
+                  ],
+              }
+            : undefined;
+    } else {
         return {
             dirs: extractStringArray(grepSearchLocation.dirs),
         };
     }
-
-    return dir
-        ? {
-              dirs: [
-                  dir,
-              ],
-          }
-        : undefined;
 }
 
 function resolveSearchPart({
@@ -657,13 +650,13 @@ async function createSearchParts({
         ? recursive
             ? filteredSearchParts
             : (
-                  await awaitedBlockingMap(filteredSearchParts, (dir) =>
-                      readDirectDirSearchParts({
+                  await awaitedBlockingMap(filteredSearchParts, (dir) => {
+                      return readDirectDirSearchParts({
                           cwd,
                           dir,
                           followSymLinks,
-                      }),
-                  )
+                      });
+                  })
               ).flat()
         : filteredSearchParts;
 }
@@ -724,7 +717,7 @@ function parseNullDelimitedGrepRecords({stdout}: Readonly<{stdout: string}>) {
     return records;
 }
 
-/* node:coverage ignore next 26 */
+/* node:coverage ignore next 28 */
 function parseColonDelimitedGrepCountOutput(stdout: string) {
     return typedObjectFromEntries(
         stdout
@@ -745,14 +738,16 @@ function parseColonDelimitedGrepCountOutput(stdout: string) {
                 });
             })
             .filter(check.isTruthy)
-            .map((entry) => [
-                entry.key,
-                entry.value,
-            ]),
+            .map((entry) => {
+                return [
+                    entry.key,
+                    entry.value,
+                ];
+            }),
     );
 }
 
-/* node:coverage ignore next 20 */
+/* node:coverage ignore next 22 */
 function parseGrepCountOutput(stdout: string) {
     return stdout.includes('\0')
         ? typedObjectFromEntries(
@@ -766,10 +761,12 @@ function parseGrepCountOutput(stdout: string) {
                       });
                   })
                   .filter(check.isTruthy)
-                  .map((entry) => [
-                      entry.key,
-                      entry.value,
-                  ]),
+                  .map((entry) => {
+                      return [
+                          entry.key,
+                          entry.value,
+                      ];
+                  }),
           )
         : parseColonDelimitedGrepCountOutput(stdout);
 }
@@ -885,10 +882,12 @@ async function runGrepCountFallback({
             )
         )
             .filter(check.isTruthy)
-            .map((entry) => [
-                entry.key,
-                entry.value,
-            ]),
+            .map((entry) => {
+                return [
+                    entry.key,
+                    entry.value,
+                ];
+            }),
     );
 }
 
@@ -897,10 +896,12 @@ function parseGrepFilesOnlyOutput(stdout: string) {
         /* node:coverage ignore next */
         (stdout.includes('\0') ? stdout.split('\0') : stdout.trimEnd().split('\n'))
             .filter(check.isTruthy)
-            .map((entry) => [
-                entry,
-                [],
-            ]),
+            .map((entry) => {
+                return [
+                    entry,
+                    [],
+                ];
+            }),
     );
 }
 
@@ -1025,10 +1026,12 @@ export async function grep<const CountOnly extends boolean = false>(
             ? grepOptionArrays.includeFiles.map((includeFile) => `--include=${includeFile}`)
             : []),
         grepOptions.binary ? '--binary' : '',
-        ...searchPatterns.flatMap((searchPattern) => [
-            '-e',
-            searchPattern,
-        ]),
+        ...searchPatterns.flatMap((searchPattern) => {
+            return [
+                '-e',
+                searchPattern,
+            ];
+        }),
         '--',
         ...searchParts,
     ].filter(check.isTruthy);

package/src/augments/fs/json.ts

@@ -22,7 +22,7 @@ import {writeFileAndDir} from './write.js';
  */
 export async function readJsonFile(path: string): Promise<JsonCompatibleValue | undefined> {
     try {
-        const contents = (await readFile(path)).toString();
+        const contents = await readFile(path, 'utf8');
         return JSON.parse(contents);
     } catch {
         return undefined;

package/src/augments/fs/read-dir.ts

@@ -63,7 +63,7 @@ export async function readDirFilesByExtension({
 
     const fileNames = await readdir(dirPath);
 
-    return fileNames.filter((fileName) =>
-        extensionsToCheck.some((extensionToCheck) => fileName.endsWith(extensionToCheck)),
-    );
+    return fileNames.filter((fileName) => {
+        return extensionsToCheck.some((extensionToCheck) => fileName.endsWith(extensionToCheck));
+    });
 }

package/src/augments/fs/read-file.ts

@@ -11,7 +11,7 @@ import {readFile} from 'node:fs/promises';
  */
 export async function readFileIfExists(path: string): Promise<string | undefined> {
     if (existsSync(path)) {
-        return (await readFile(path)).toString();
+        return await readFile(path, 'utf8');
     } else {
         return undefined;
     }

package/src/augments/npm/package-json.ts

@@ -16,9 +16,9 @@ import {findAncestor, joinFilesToDir} from '../path/ancestor.js';
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export async function findAllPackageJsonFilePaths(startDirPath: string) {
-    const packageRootDir = findAncestor(startDirPath, (dir) =>
-        existsSync(join(dir, 'package-lock.json')),
-    );
+    const packageRootDir = findAncestor(startDirPath, (dir) => {
+        return existsSync(join(dir, 'package-lock.json'));
+    });
 
     if (!packageRootDir) {
         throw new Error(

package/src/augments/npm/read-package-json.ts

@@ -18,9 +18,9 @@ export async function readPackageJson(dirPath: string): Promise<PackageJson> {
 
     if (!packageJson) {
         throw new TypeError(`package.json file does not exist in '${dirPath}'`);
-    } else if (!check.isObject(packageJson)) {
+    } else if (check.isObject(packageJson)) {
+        return packageJson;
+    } else {
         throw new TypeError(`Parsing package.json file did not return an object in '${dirPath}'`);
     }
-
-    return packageJson;
 }

package/src/augments/path/contains.ts

@@ -41,10 +41,10 @@ export function doesPathContain({
     } else if (isAbsolute(relativePath)) {
         /** On Windows, paths on different drives yield an absolute relative path. */
         return false;
+    } else {
+        /** Contained if it does not traverse up out of parent. */
+        return relativePath !== '..' && !relativePath.startsWith('..' + sep);
     }
-
-    /** Contained if it does not traverse up out of parent. */
-    return relativePath !== '..' && !relativePath.startsWith('..' + sep);
 }
 
 function normalizePath(inputPath: string): string {

package/src/augments/path/os-path.ts

@@ -36,6 +36,12 @@ export function toPosixPath(maybeWindowsPath: string): string {
  * Use this to interpolate paths into bash commands. If the given path is not a Windows path, the
  * path structure will not be modified.
  *
+ * Each round of bash parsing halves the backslashes, so the count here assumes _two_ rounds: a
+ * command string that bash parses and then hands to something which parses it again. Four
+ * backslashes arrive as one. For a command that bash parses only once, this over-escapes; use
+ * `shellQuote` from `@augment-vir/common` instead, which needs no multiplication because bash does
+ * no escape processing inside single quotes.
+ *
  * @category Path : Node
  * @category Package : @augment-vir/node
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)

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

@@ -2,9 +2,9 @@
 /** This file cannot be tested because it calls `process.exit`. */
 
 import {check} from '@augment-vir/assert';
+import {shellQuote} from '@augment-vir/common';
 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';
 
@@ -57,13 +57,13 @@ export async function runCliScript({
           }) || runner.npx;
 
     const results = await runShellCommand(
-        interpolationSafeWindowsPath(
-            [
-                runnerPath,
-                scriptPath,
-                ...args,
-            ].join(' '),
-        ),
+        [
+            runnerPath,
+            scriptPath,
+            ...args,
+        ]
+            .map(shellQuote)
+            .join(' '),
         {
             hookUpToConsole: true,
         },

package/src/augments/typescript/read-tsconfig.ts

@@ -12,9 +12,9 @@ import {findAncestor} from '../path/ancestor.js';
  * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
  */
 export function readTsconfig(startingPath: string) {
-    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) =>
-        existsSync(join(ancestorPath, 'tsconfig.json')),
-    );
+    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) => {
+        return existsSync(join(ancestorPath, 'tsconfig.json'));
+    });
     const tsconfigPath = tsconfigDirPath ? join(tsconfigDirPath, 'tsconfig.json') : undefined;
 
     if (!tsconfigPath) {

package/src/scripts/fix-src-imports.script.ts

@@ -76,7 +76,7 @@ async function fixAllSrcImports(monoRepoPath: string) {
 
     await Promise.all(
         filePaths.map(async (filePath) => {
-            const contents = String(await readFile(filePath));
+            const contents = await readFile(filePath, 'utf8');
             const fixedContents = contents.replaceAll(
                 /(from ["'][^'"]+?)\/src\/([^'"]+)['"];/g,
                 "$1/dist/$2';",

package/src/scripts/fix-ts-bin.script.ts

@@ -17,8 +17,7 @@
  */
 
 import {log} from '@augment-vir/common';
-import {interpolationSafeWindowsPath, runShellCommand} from '@augment-vir/node';
-import {readFile, rm, writeFile} from 'node:fs/promises';
+import {chmod, readFile, rm, writeFile} from 'node:fs/promises';
 import {join, sep} from 'node:path/posix';
 
 type PackageToFix = {
@@ -75,7 +74,7 @@ async function fixTsBin(packageToFix: Readonly<PackageToFix>) {
         force: true,
     });
     await writeFile(binFilePath, createBinFileContents(packageToFix));
-    await runShellCommand(`chmod +x ${interpolationSafeWindowsPath(binFilePath)}`);
+    await chmod(binFilePath, 0o755);
     await fixPackageJson(packageToFix);
     log.success(`Fixed ${packageToFix.packageName} bin.`);
 }
@@ -91,7 +90,7 @@ async function fixPackageJson(packageToFix: Readonly<PackageToFix>) {
         packageToFix.packageName,
         'package.json',
     );
-    const original = String(await readFile(packageJsonPath));
+    const original = await readFile(packageJsonPath, 'utf8');
     await writeFile(
         packageJsonPath,
         original