build-strap 6.0.1 → 6.1.0

package/README.md

@@ -120,13 +120,35 @@ publish(
 ```
 
 ### buildLog
-Write out to the console in a timestamp prefixed format consistent with the rest of the build output.
+Write out to the console in a timestamp prefixed format consistent with the rest of the build output. Output goes to `stderr` by default, so that `stdout` can be reserved for machine readable output.
 ```
 import { buildLog } from 'build-strap';
 
 buildLog('Hello world');
 ```
 
+Pass a `Date` (as before) or an options object to control the timestamp and destination:
+```
+buildLog('Hello world', new Date());
+buildLog('to stdout instead', { stream: 'stdout' });
+buildLog('to any writable stream', { stream: myWriteStream });
+buildLog('or handle it yourself', { stream: (msg) => myLogger.info(msg) });
+```
+
+The default destination can be changed globally (affects `run`/`runCli` logging too):
+```
+import { getBuildLogStream, setBuildLogStream } from 'build-strap';
+
+setBuildLogStream('stdout');
+setBuildLogStream(process.stderr);
+setBuildLogStream((msg) => myLogger.info(msg));
+getBuildLogStream(); // current default
+```
+
+CLI flags:
+- `--buildLog-stdout` — default to `stdout` instead of `stderr`
+- `--silence-buildLog` — suppress all `buildLog` output
+
 ## NPM Credentials
 In order to publish to NPM, proper credentials must be provided to the script. By default, these are read from the `NPM_CREDS` environment variable, but it is also possible to pass them as an argument to most functions. This is expected to be a JSON encoded string in the following format:
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "build-strap",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "Node scripts for building things",
   "license": "MIT",
   "author": "Justin Murray <justin@murrayju.com>",
@@ -16,17 +16,17 @@
   },
   "dependencies": {
     "bytes": "^3.1.1",
-    "chokidar": "^3.6.0",
+    "chokidar": "^5.0.0",
     "cross-spawn": "^7.0.3",
     "fs-extra": "^11.2.0",
     "get-port": "^7.1.0",
-    "glob": "^10.3.14",
-    "is-reachable": "^5.1.1",
-    "js-yaml": "^4.1.0",
+    "glob": "^13.0.6",
+    "is-reachable": "^6.1.0",
+    "js-yaml": "^5.4.0",
     "lodash-es": "^4.17.21",
     "moment": "^2.30.1",
     "node-fetch": "^3.3.2",
-    "rimraf": "^5.0.5",
+    "rimraf": "^6.1.3",
     "stream-counter": "1",
     "tar": "^7.1.0"
   }

package/src/cert.d.ts

@@ -3,8 +3,8 @@ export interface CertConfig {
     countryName?: string;
     emailAddress?: string;
     localityName?: string;
-    organizationName?: string;
     organizationalUnitName?: string;
+    organizationName?: string;
     stateOrProvinceName?: string;
 }
 export declare const getCertConfig: () => CertConfig;

package/src/cert.js

@@ -21,7 +21,7 @@ export async function generateCert(targetDir, force = process.argv.includes('--f
         return;
     }
     buildLog('Generating self-signed certificate...');
-    const { commonName = 'app.company.com', countryName = 'US', emailAddress = 'contact@company.com', localityName = 'SomeCity', organizationName = 'Company', organizationalUnitName = 'Product', stateOrProvinceName = 'Pennsylvania', } = getCertConfig();
+    const { commonName = 'app.company.com', countryName = 'US', emailAddress = 'contact@company.com', localityName = 'SomeCity', organizationalUnitName = 'Product', organizationName = 'Company', stateOrProvinceName = 'Pennsylvania', } = getCertConfig();
     const hostname = os.hostname();
     buildLog(`hostname: ${hostname}`);
     const ipAddresses = getIpAddresses();

package/src/copy.d.ts

@@ -1,5 +1,10 @@
+/**
+ * Callback invoked after a copy completes. May be sync or async; a returned
+ * promise is awaited.
+ */
+export type CopySrcCallback = () => Promise<void> | void;
 export interface CopySrcOptions {
-    cbFn?: () => void;
+    cbFn?: CopySrcCallback;
     from: string;
     to: string;
     watch?: boolean;

package/src/copy.js

@@ -1,11 +1,11 @@
-import chokidar from 'chokidar';
+import { watch as chokidarWatch } from 'chokidar';
 import fs from 'fs-extra';
 import path from 'path';
 import { onKillSignal } from './cp.js';
 import { cleanDir, copyDir } from './fs.js';
-import { buildLog } from './run.js';
+import { buildLog, errorMessage } from './run.js';
 let timer = null;
-async function throttledCallback(cbFn) {
+function throttledCallback(cbFn) {
     if (!cbFn || typeof cbFn !== 'function') {
         return;
     }
@@ -15,7 +15,16 @@ async function throttledCallback(cbFn) {
     }
     timer = setTimeout(() => {
         timer = null;
-        cbFn();
+        // the callback may be async, so surface a rejection instead of leaving it
+        // floating on the timer
+        void (async () => {
+            try {
+                await cbFn();
+            }
+            catch (e) {
+                buildLog(`Error in copySrc callback: ${errorMessage(e)}`);
+            }
+        })();
     }, 200);
 }
 export async function copySrc({ cbFn, from, to, watch = process.argv.includes('--watch'), }) {
@@ -23,10 +32,13 @@ export async function copySrc({ cbFn, from, to, watch = process.argv.includes('-
     if (cbFn)
         await cbFn();
     if (watch) {
-        const watcher = chokidar.watch([path.join(from, '/**/*')], {
+        // chokidar v4 removed glob support; watch the directory recursively instead
+        const watcher = chokidarWatch(from, {
             ignoreInitial: true,
         });
-        watcher.on('all', async (event, filePath) => {
+        // chokidar's typings expect a void-returning listener, so the async work
+        // is wrapped and its rejection handled rather than left floating
+        const handleEvent = async (event, filePath) => {
             const start = new Date();
             const src = path.relative(from, filePath);
             const dest = path.join(to, src);
@@ -38,7 +50,9 @@ export async function copySrc({ cbFn, from, to, watch = process.argv.includes('-
                     break;
                 case 'unlink':
                 case 'unlinkDir':
-                    cleanDir(dest, { dot: true });
+                    // must be awaited: otherwise the log below (and the throttled
+                    // callback) can fire before the delete actually completes
+                    await cleanDir(dest, { dot: true });
                     break;
                 default:
                     return;
@@ -47,7 +61,14 @@ export async function copySrc({ cbFn, from, to, watch = process.argv.includes('-
             const time = end.getTime() - start.getTime();
             buildLog(`${event} '${dest}' after ${time} ms`, end);
             throttledCallback(cbFn);
+        };
+        watcher.on('all', (event, filePath) => {
+            handleEvent(event, filePath).catch((e) => {
+                buildLog(`Error handling ${event} for ${filePath}: ${errorMessage(e)}`);
+            });
+        });
+        onKillSignal(() => {
+            void watcher.close();
         });
-        onKillSignal(() => watcher.close());
     }
 }

package/src/cp.js

@@ -63,7 +63,6 @@ export async function spawn(command, args, opts) {
             p.on('close', handleExit);
             p.on('exit', handleExit);
             // only fires if we failed to spawn
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             p.on('error', (err) => {
                 // Here we have a workaround that reverses a "feature" of cross-spawn on Windows. See:
                 // https://github.com/moxystudio/node-cross-spawn/blob/master/lib/enoent.js#L23
@@ -79,7 +78,7 @@ export async function spawn(command, args, opts) {
             });
         }
         catch (err) {
-            reject(err);
+            reject(err instanceof Error ? err : new Error(String(err)));
         }
     });
 }

package/src/docker.container.js

@@ -2,7 +2,7 @@ import bytes from 'bytes';
 import { throttle } from 'lodash-es';
 import { spawn } from './cp.js';
 import { parseDockerDate } from './docker.js';
-import { buildLog } from './run.js';
+import { buildLog, errorMessage } from './run.js';
 // calling this function in rapid succession can lead to errors.
 // prefer throttled version
 export async function unthrottledDockerContainerLs({ all, filter, } = {}) {
@@ -31,7 +31,7 @@ export async function unthrottledDockerContainerLs({ all, filter, } = {}) {
                     return false;
                 }
             },
-            exited: /^Exited/.test(status),
+            exited: status.startsWith('Exited'),
             id,
             image,
             inspect: async () => (await dockerContainerInspect(id))?.[0],
@@ -50,7 +50,7 @@ export async function unthrottledDockerContainerLs({ all, filter, } = {}) {
             names,
             networks: Networks.split(',').map((n) => n.trim()),
             ports: Ports.split(',').map((p) => {
-                const [, iface, src, dest] = p.match(/^([^:]+):(\d+)-\\u003e(\d+)/i) || [];
+                const [, iface, src, dest] = /^([^:]+):(\d+)-\\u003e(\d+)/i.exec(p) || [];
                 return {
                     dest: parseInt(dest, 10),
                     iface,
@@ -73,14 +73,14 @@ export async function unthrottledDockerContainerLs({ all, filter, } = {}) {
                         log(`<${this.name}> container stopped.`);
                     }
                     catch (e1) {
-                        log(`Failed to stop <${this.name}> container: ${e1 instanceof Error && e1.message}`);
+                        log(`Failed to stop <${this.name}> container: ${errorMessage(e1)}`);
                         try {
                             log(`Killing container: <${this.name}>...`);
                             await this.kill(false);
                             log(`<${this.name}> container killed.`);
                         }
                         catch (e2) {
-                            log(`Failed to kill <${this.name}> container: ${e2 instanceof Error && e2.message}`);
+                            log(`Failed to kill <${this.name}> container: ${errorMessage(e2)}`);
                         }
                     }
                 }
@@ -113,7 +113,9 @@ export async function dockerContainerStop(id, ignoreErrors = true) {
     }
     catch (e) {
         if (!ignoreErrors) {
-            throw new Error(`Failed to stop container(s): ${e instanceof Error && e.message}`);
+            throw new Error(`Failed to stop container(s): ${errorMessage(e)}`, {
+                cause: e,
+            });
         }
     }
 }
@@ -124,7 +126,9 @@ export async function dockerContainerKill(id, ignoreErrors = true) {
     }
     catch (e) {
         if (!ignoreErrors) {
-            throw new Error(`Failed to kill container(s): ${e instanceof Error && e.message}`);
+            throw new Error(`Failed to kill container(s): ${errorMessage(e)}`, {
+                cause: e,
+            });
         }
     }
 }
@@ -134,7 +138,7 @@ export async function dockerTryStopContainer(id, name = '') {
             await dockerContainerStop(id, false);
         }
         catch (e) {
-            buildLog(`Failed to stop ${name} container: ${e instanceof Error && e.message}`);
+            buildLog(`Failed to stop ${name} container: ${errorMessage(e)}`);
         }
     }
 }
@@ -145,10 +149,12 @@ export async function dockerContainerRm(id, ignoreErrors = true) {
     }
     catch (e) {
         if (ignoreErrors) {
-            buildLog(`Warning (ignored Error): Failed to remove container(s): ${e instanceof Error && e.message}`);
+            buildLog(`Warning (ignored Error): Failed to remove container(s): ${errorMessage(e)}`);
         }
         else {
-            throw new Error(`Failed to remove container(s): ${e instanceof Error && e.message}`);
+            throw new Error(`Failed to remove container(s): ${errorMessage(e)}`, {
+                cause: e,
+            });
         }
     }
 }
@@ -191,7 +197,6 @@ export async function dockerContainerRunDaemon({ cmd = [], image, runArgs = [],
     let container = await dockerContainerFind(id);
     let attempts = 0;
     // containers don't always show up in the list right away
-    /* eslint-disable no-await-in-loop */
     while (!container && attempts < waitAttempts) {
         await new Promise((resolve) => {
             setTimeout(resolve, waitDuration);
@@ -199,7 +204,6 @@ export async function dockerContainerRunDaemon({ cmd = [], image, runArgs = [],
         container = await dockerContainerFind(id);
         attempts += 1;
     }
-    /* eslint-enable no-await-in-loop */
     if (!container) {
         throw new Error(`Failed to find newly created container: ${id}`);
     }
@@ -221,27 +225,34 @@ export const dockerContainerWaitForStart = async (container, testFn, timeoutMs =
     curIndicator = (curIndicator + 1) % indicators.length;
     const { name } = container;
     buildLog(`Waiting for ${name} to fully start... ${indicator}`);
-    await new Promise((resolve, reject) => {
-        const check = (tries = 0) => {
-            process.stdout.write(indicator);
-            setTimeout(async () => {
-                try {
-                    if (!(await container.isRunning())) {
-                        return reject(new Error(`The '${name}' container is no longer running.`));
-                    }
-                    if (await testFn(container)) {
-                        return resolve();
-                    }
-                }
-                catch {
-                    // ignore
-                }
-                return tries < maxAttempts
-                    ? check(tries + 1)
-                    : reject(new Error(`Timeout waiting for '${name}' container to start.`));
-            }, timeoutMs);
-        };
-        check();
-    });
-    process.stdout.write('\n');
+    for (let tries = 0; tries <= maxAttempts; tries += 1) {
+        process.stdout.write(indicator);
+        await new Promise((resolve) => {
+            setTimeout(resolve, timeoutMs);
+        });
+        // A container that has definitively gone away will never become ready, so
+        // that case is terminal. An error from either check just means the state is
+        // currently unknown, so keep polling until maxAttempts is exhausted.
+        let gone = false;
+        let ready = false;
+        try {
+            if (await container.isRunning()) {
+                ready = await testFn(container);
+            }
+            else {
+                gone = true;
+            }
+        }
+        catch {
+            // state unknown; keep polling
+        }
+        if (gone) {
+            throw new Error(`The '${name}' container is no longer running.`);
+        }
+        if (ready) {
+            process.stdout.write('\n');
+            return;
+        }
+    }
+    throw new Error(`Timeout waiting for '${name}' container to start.`);
 };

package/src/docker.js

@@ -11,7 +11,7 @@ import { cmdExists, isArm, isMac } from './env.js';
 import { downloadFile } from './fetch.js';
 import { mountDmg, unmountDmg } from './macos.js';
 import { getCfg, getPkgName, getPkgScope } from './pkg.js';
-import { buildLog } from './run.js';
+import { buildLog, errorMessage } from './run.js';
 import { getMainBranch, getVersion } from './version.js';
 export function getDockerConfig() {
     return getCfg().docker || {};
@@ -51,12 +51,7 @@ export async function dockerTagVersion(imageId, repo = getDockerRepo()) {
     if (isRelease) {
         await dockerTag(imageId, prerelease
             ? [npm, `latest-${prerelease.split('.')[0]}`]
-            : [
-                'latest',
-                `${major}`,
-                `${major}.${minor}`,
-                `${major}.${minor}.${patch}`,
-            ], repo);
+            : ['latest', major, `${major}.${minor}`, `${major}.${minor}.${patch}`], repo);
     }
     else if (branch === getMainBranch()) {
         await dockerTag(imageId, [`latest-${branch}`], repo);
@@ -77,8 +72,7 @@ export async function dockerImages(repo = getDockerRepo(), filter = null) {
             tag,
         };
     })
-        .filter((m) => (m && m.id) != null &&
-        (typeof filter === 'function' ? filter(m) : true));
+        .filter((m) => m?.id != null && (typeof filter === 'function' ? filter(m) : true));
 }
 export async function getDockerId(tag = 'latest', repo = null) {
     return (await dockerImages(repo, (m) => m.tag === tag)).map((m) => m.id)[0];
@@ -106,7 +100,7 @@ export async function dockerPush(tags = ['latest'], repo = getDockerRepo()) {
 }
 export async function dockerPull({ image, offline = process.argv.includes('--offline'), testUrl, }) {
     if (offline || !(await isReachable(testUrl || 'https://hub.docker.com'))) {
-        if (offline === false) {
+        if (!offline) {
             throw new Error('Offline, cannot docker pull');
         }
         buildLog('It looks like you are offline, skipping docker pull');
@@ -122,7 +116,7 @@ export async function dockerRmi(images = [], ignoreErrors = true) {
         await prev;
         await spawn('docker', ['rmi', image], { stdio: 'inherit' }).catch((err) => {
             if (ignoreErrors) {
-                buildLog(`Warning (ignored Error): Failed to rm image(s): ${err.message}`);
+                buildLog(`Warning (ignored Error): Failed to rm image(s): ${errorMessage(err)}`);
             }
             else {
                 throw err;
@@ -169,7 +163,9 @@ export async function copyFilesFromDockerImage({ filePaths, ignoreErrors, imageI
     };
     const copyErrors = [];
     try {
-        filePaths.forEach(async (fp) => {
+        // must be awaited: with forEach the copies were never waited on, so the
+        // container was killed mid-copy and copyErrors was always empty below
+        await Promise.all(filePaths.map(async (fp) => {
             // Try to copy from the Debug Folder
             try {
                 await spawn('docker', ['cp', `${container.id}:${fp.from}`, fp.to], spawnOptions);
@@ -179,7 +175,7 @@ export async function copyFilesFromDockerImage({ filePaths, ignoreErrors, imageI
                 copyErrors.push(error);
                 buildLog(`Error copying file ${fp.from}`);
             }
-        });
+        }));
     }
     finally {
         try {

package/src/docker.network.d.ts

@@ -1,9 +1,9 @@
 export interface DockerNetwork {
-    IPv6: boolean;
     created: Date;
     driver: string;
     exists: () => Promise<boolean>;
     id: string;
+    IPv6: boolean;
     labels: string[];
     name: string;
     rm: () => Promise<void>;

package/src/docker.network.js

@@ -12,11 +12,11 @@ export async function unthrottledDockerNetworkLs({ filter, } = {}) {
         .map((line) => {
         const { CreatedAt, Driver: driver, ID: id, IPv6, Labels, Name: name, Scope: scope, } = JSON.parse(line.trim());
         return {
-            IPv6: IPv6 === 'true',
             created: parseDockerDate(CreatedAt),
             driver,
             exists: async () => !!(await dockerNetworkFind(id)),
             id,
+            IPv6: IPv6 === 'true',
             labels: Labels.split(',').map((l) => l.trim()),
             name,
             rm: async () => dockerNetworkRm(id),
@@ -65,9 +65,8 @@ export async function dockerNetworkRm(id) {
  */
 export async function dockerNetworkDelete(networkName) {
     let existing;
-    // eslint-disable-next-line no-cond-assign, no-await-in-loop
+    // extra parens satisfy no-cond-assign's `except-parens` option
     while ((existing = await dockerNetworkFind(networkName))) {
-        // eslint-disable-next-line no-await-in-loop
         await existing.rm();
     }
 }

package/src/docker.volume.js

@@ -1,5 +1,6 @@
 import { throttle } from 'lodash-es';
 import { spawn } from './cp.js';
+import { errorMessage } from './run.js';
 // calling this function in rapid succession can lead to errors.
 // prefer throttled version
 export async function unthrottledDockerVolumeLs({ filter, } = {}) {
@@ -49,7 +50,9 @@ export async function dockerVolumeRm(id, ignoreErrors = true) {
     }
     catch (e) {
         if (!ignoreErrors) {
-            throw new Error(`Failed to remove volume(s): ${e instanceof Error && e.message}`);
+            throw new Error(`Failed to remove volume(s): ${errorMessage(e)}`, {
+                cause: e,
+            });
         }
     }
 }

package/src/dockerCleanup.js

@@ -5,6 +5,10 @@ import { dockerImages, dockerRmi, getDockerRepo, getDockerTags, getUntaggedDocke
 import { buildLog } from './run.js';
 // flattens arrays of promises and/or promises for arrays
 // into a single array of (awaited) values
+// The recursive shape here defeats both the type checker and the type-aware
+// await rules: `input` may itself be an array of promises, so the awaits are
+// load-bearing even where the static type looks non-thenable.
+/* eslint-disable @typescript-eslint/await-thenable */
 async function flatten(input) {
     const result = await input;
     return Array.isArray(result)
@@ -40,7 +44,7 @@ export const dockerContainerCleanup = async ({ dryRun = process.argv.includes('-
  */
 export const dockerImageCleanup = async ({ buildImageIds = [], dryRun = process.argv.includes('--dry-run'), images = [], purgeAll = process.argv.includes('--purge-all'), purgeOld = !process.argv.includes('--keep-old'), repos = [getDockerRepo()], } = {}) => {
     // only match images without a :latest tag
-    const filterLatest = (m) => purgeAll || !m.tag.match(/^latest(-\w+)?$/);
+    const filterLatest = (m) => purgeAll || !/^latest(-\w+)?$/.exec(m.tag);
     // only match images more than an hour old, AND without a :latest* tag
     const filterOld = (m) => purgeAll ||
         (filterLatest(m) && moment().subtract(1, 'h').isAfter(m.created));

package/src/dockerCompose.d.ts

@@ -1,13 +1,13 @@
 import { DockerContainer } from './docker.container.js';
 import { DockerNetwork, DockerNetworkCreateOptions } from './docker.network.js';
 import { DockerVolume, DockerVolumeCreateOptions } from './docker.volume.js';
-export type DockerComposeResourceTracker = {
+export interface DockerComposeResourceTracker {
     cleaning: null | Promise<void>;
     containers: Map<string, DockerContainer>;
     networks: Map<string, DockerNetwork>;
     services: Map<string, DockerComposeService>;
     volumes: Map<string, DockerVolume>;
-};
+}
 export declare const dockerComposeCreateResourceTracker: () => DockerComposeResourceTracker;
 type DockerComposeEnvDef = string[] | Record<string, string>;
 type DockerComposeULimitDef = number | {

package/src/dockerCompose.js

@@ -1,6 +1,6 @@
 import fs from 'fs-extra';
 import getPort from 'get-port';
-import yaml from 'js-yaml';
+import { load as yamlLoad } from 'js-yaml';
 import path from 'path';
 import { dockerContainerFind, dockerContainerRunDaemon, } from './docker.container.js';
 import { dockerPull } from './docker.js';
@@ -21,7 +21,7 @@ const defaultTracker = dockerComposeCreateResourceTracker();
  * Parse a docker-compose.yml file into a pojo representation
  * @param {string} filePath Path to the docker-compose.yml file
  */
-export const dockerComposeParse = async (filePath = './docker-compose.yml') => yaml.load(await fs.readFile(filePath, 'utf8'));
+export const dockerComposeParse = async (filePath = './docker-compose.yml') => yamlLoad(await fs.readFile(filePath, 'utf8'));
 let dc = null;
 /**
  * Get the main docker-compose.yml from the root of the repo
@@ -153,7 +153,6 @@ export class DockerComposeService {
      * @param {number} max maximum number of names to try
      */
     async getNames(avoidConflicts = false, max = 100) {
-        /* eslint-disable no-await-in-loop */
         for (let i = 0; i < max; i += 1) {
             const suffix = i ? `-${i}` : '';
             const testName = `${this.defaultContainerName}${suffix}`;
@@ -166,7 +165,6 @@ export class DockerComposeService {
                 };
             }
         }
-        /* eslint-enable no-await-in-loop */
         throw new Error(`Failed to find available container name for ${this.defaultContainerName}`);
     }
     // Get (available) port mappings

package/src/env.js

@@ -8,7 +8,6 @@ const cacheBool = (key, fn) => {
     if (!boolCache.has(key)) {
         boolCache.set(key, fn());
     }
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     return boolCache.get(key);
 };
 export const isMac = () => cacheBool('isMac', () => os.platform() === 'darwin');
@@ -22,7 +21,6 @@ const cacheString = (key, fn) => {
     if (!stringCache.has(key)) {
         stringCache.set(key, fn());
     }
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     return stringCache.get(key);
 };
 export const shellType = () => cacheString('shellType', () => os.userInfo().shell?.split('/').pop() || null);

package/src/fs.js

@@ -35,7 +35,7 @@ export const cleanDir = async (pattern, globOptions) => rimraf(pattern, { glob:
 export const producedPathExists = async (producer) => {
     try {
         const result = (await producer()).trim();
-        return !!result && fs.pathExists(result);
+        return !!result && (await fs.pathExists(result));
     }
     catch {
         return false;

package/src/git.d.ts

@@ -21,10 +21,10 @@ export declare function gitTagsAtCommit(commitish?: string): Promise<string[]>;
  * Useful for verifying that a release tag lives on the main branch.
  */
 export declare function gitIsAncestor(ancestorCommitish: string, descendantCommitish: string): Promise<boolean>;
-type GitInfo = {
+interface GitInfo {
     branch: null | string;
     revision: string;
-};
+}
 export declare function gitInfo(noCache?: boolean): Promise<GitInfo>;
 export declare const ensureGitLfsInstalled: () => Promise<void>;
 export declare const gitConfigRead: (key: string, global?: boolean) => Promise<string>;

package/src/npm.d.ts

@@ -1,16 +1,16 @@
 import { SpawnOptions, SpawnResult } from './cp.js';
-export type NpmCreds = {
+export interface NpmCreds {
     email?: string;
     password?: string;
     username?: string;
-};
-export type NpmConfig = {
+}
+export interface NpmConfig {
     access?: 'public' | 'restricted';
     dryRun?: boolean;
     name?: string;
     publish?: boolean;
     registry?: string;
-};
+}
 export declare function getNpmConfig(): NpmConfig;
 export declare const envNpmCreds: null | NpmCreds;
 export interface NpmOptions {

package/src/orbstack.js

@@ -67,16 +67,12 @@ export const ensureOrbStackConfigured = async (desiredConfig) => {
         };
         if (!Object.entries(desiredConfig).every(([key, value]) => effectiveConfig[key] === value)) {
             buildLog('Adjusting OrbStack config...');
-            const newConfig = {
+            const defaults = defaultConfig;
+            // Don't write values that already match the defaults
+            const newConfig = Object.fromEntries(Object.entries({
                 ...existingConfig,
                 ...desiredConfig,
-            };
-            for (const [key, value] of Object.entries(defaultConfig)) {
-                if (newConfig[key] === value) {
-                    // Don't write default values
-                    delete newConfig[key];
-                }
-            }
+            }).filter(([key, value]) => defaults[key] !== value));
             await fs.writeJson(configPath, newConfig, { spaces: 2 });
             changed = true;
         }

package/src/pkg.js

@@ -21,7 +21,7 @@ export function getPkgName(includeScope = false) {
     if (includeScope) {
         return pkg.name;
     }
-    const [, , shortName] = pkg.name.match(pkgNameRegex) || [];
+    const [, , shortName] = pkgNameRegex.exec(pkg.name) || [];
     if (!shortName) {
         throw new Error('Package name in package.json has invalid format.');
     }
@@ -29,11 +29,11 @@ export function getPkgName(includeScope = false) {
 }
 export function getPkgScope() {
     const pkgName = getPkgName(true);
-    return pkgName.match(pkgNameRegex)?.[1] || null;
+    return pkgNameRegex.exec(pkgName)?.[1] || null;
 }
 export function getPkgSafeName() {
     const pkgName = getPkgName(true);
-    const match = pkgName.match(pkgNameRegex);
+    const match = pkgNameRegex.exec(pkgName);
     if (!match) {
         return null;
     }

package/src/run.d.ts

@@ -1,5 +1,30 @@
 export declare function format(time?: Date): string;
-export declare function buildLog(msg: string, time?: Date): void;
+/**
+ * Extract a human readable message from an unknown caught value.
+ *
+ * `catch` and promise rejections are typed `unknown`, and anything can be
+ * thrown. Interpolating such a value directly is unsafe: the common
+ * `${e instanceof Error && e.message}` shorthand renders the string "false"
+ * whenever the thrown value is not an Error, hiding the real cause.
+ */
+export declare function errorMessage(err: unknown): string;
+/**
+ * Where `buildLog` output should be written. Either the name of one of the
+ * standard streams, any writable stream, or a function that receives the
+ * fully formatted message.
+ */
+export type BuildLogStream = 'stderr' | 'stdout' | NodeJS.WritableStream | ((msg: string) => void);
+export interface BuildLogOptions {
+    /** Override the destination for this message only. */
+    stream?: BuildLogStream;
+    /** Timestamp to prefix the message with (defaults to now). */
+    time?: Date;
+}
+/** Change the destination used by `buildLog` when none is specified. */
+export declare function setBuildLogStream(stream: BuildLogStream): void;
+/** The destination currently used by `buildLog` when none is specified. */
+export declare function getBuildLogStream(): BuildLogStream;
+export declare function buildLog(msg: string, timeOrOptions?: BuildLogOptions | Date): void;
 export type RunnableModule<Args extends string[], Result> = ((...args: Args) => Promise<Result>) | {
     default: (...args: Args) => Promise<Result>;
 };

package/src/run.js

@@ -1,16 +1,67 @@
 export function format(time = new Date()) {
     return time.toTimeString().replace(/.*(\d{2}:\d{2}:\d{2}).*/, '$1');
 }
+/**
+ * Extract a human readable message from an unknown caught value.
+ *
+ * `catch` and promise rejections are typed `unknown`, and anything can be
+ * thrown. Interpolating such a value directly is unsafe: the common
+ * `${e instanceof Error && e.message}` shorthand renders the string "false"
+ * whenever the thrown value is not an Error, hiding the real cause.
+ */
+export function errorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    try {
+        return JSON.stringify(err) ?? String(err);
+    }
+    catch {
+        return String(err);
+    }
+}
 const silenceLogs = process.argv.includes('--silence-buildLog');
-export function buildLog(msg, time) {
+// stderr by default, so that stdout can be used for machine readable output.
+let defaultStream = process.argv.includes('--buildLog-stdout')
+    ? 'stdout'
+    : 'stderr';
+/** Change the destination used by `buildLog` when none is specified. */
+export function setBuildLogStream(stream) {
+    defaultStream = stream;
+}
+/** The destination currently used by `buildLog` when none is specified. */
+export function getBuildLogStream() {
+    return defaultStream;
+}
+function writeLog(msg, stream) {
+    if (typeof stream === 'function') {
+        stream(msg);
+    }
+    else if (stream === 'stdout') {
+        process.stdout.write(`${msg}\n`);
+    }
+    else if (stream === 'stderr') {
+        process.stderr.write(`${msg}\n`);
+    }
+    else {
+        stream.write(`${msg}\n`);
+    }
+}
+export function buildLog(msg, timeOrOptions) {
     if (silenceLogs) {
         return;
     }
-    console.info(`[${format(time || new Date())}] ${msg}`);
+    const { stream = defaultStream, time } = timeOrOptions instanceof Date
+        ? { time: timeOrOptions }
+        : (timeOrOptions ?? {});
+    writeLog(`[${format(time || new Date())}] ${msg}`, stream);
 }
 export async function run(fn, ...options) {
     if (fn == null) {
-        throw new Error(`Invalid argument passed to run(${fn})`);
+        throw new Error(`Invalid argument passed to run(${String(fn)})`);
     }
     const task = typeof fn === 'function' ? fn : fn.default;
     if (typeof task !== 'function') {
@@ -38,7 +89,7 @@ export async function runCli({ argv = process.argv, defaultAction = 'build', pas
             ? argv.slice(3)
             : [];
     return run(module, ...args).catch((err) => {
-        console.error((err && err.stack) || err);
+        console.error(err instanceof Error ? err.stack : err);
         process.exit(1);
     });
 }

package/src/tgz.d.ts

@@ -1,12 +1,12 @@
 import { Readable } from 'stream';
-import { TarOptionsWithAliasesNoFile } from 'tar/dist/commonjs/options.js';
-export type ArtifactInfo = {
+import { type TarOptionsWithAliasesAsyncNoFile } from 'tar';
+export interface ArtifactInfo {
     contentType?: string;
     md5: string;
     sha1: string;
     sha512: string;
     size: number;
-};
+}
 export declare const generateFileHash: (filePath: string, type: "md5" | "sha1" | "sha512") => Promise<string>;
 export declare function getArtifactInfo(artifact: string | Pick<Readable, 'pipe'>): Promise<ArtifactInfo>;
-export declare function tgzDir(srcDir: string, outPath: string, options?: TarOptionsWithAliasesNoFile): Promise<ArtifactInfo>;
+export declare function tgzDir(srcDir: string, outPath: string, options?: TarOptionsWithAliasesAsyncNoFile): Promise<ArtifactInfo>;

package/src/tgz.js

@@ -13,16 +13,24 @@ const generateHash = async (stream, type) => new Promise((resolve, reject) => {
         .on('end', function onEnd() {
         resolve(this.read());
     })
-        .on('error', (err) => reject(err));
+        .on('error', (err) => {
+        reject(err);
+    });
 });
 export const generateFileHash = async (filePath, type) => generateHash(fs.createReadStream(filePath), type);
 const countBytes = async (stream) => new Promise((resolve, reject) => {
     const counter = new StreamCounter();
     stream
         .pipe(counter)
-        .on('finish', () => resolve(counter.bytes))
-        .on('end', () => resolve(counter.bytes))
-        .on('error', (err) => reject(err));
+        .on('finish', () => {
+        resolve(counter.bytes);
+    })
+        .on('end', () => {
+        resolve(counter.bytes);
+    })
+        .on('error', (err) => {
+        reject(err);
+    });
 });
 const writeStreamToFile = async (stream, filePath) => new Promise((resolve, reject) => {
     stream
@@ -31,7 +39,9 @@ const writeStreamToFile = async (stream, filePath) => new Promise((resolve, reje
         buildLog(`Successfully wrote file: ${filePath}`);
         resolve();
     })
-        .on('error', (err) => reject(err));
+        .on('error', (err) => {
+        reject(err);
+    });
 });
 // Take the given file (path or stream) and compute metadata for it.
 // md5 + sha hashes, and size in bytes
@@ -58,7 +68,7 @@ export async function tgzDir(srcDir, outPath, options) {
     // write the file to disk (outPath)
     const [info] = await Promise.all([
         getArtifactInfo(tgzStream),
-        writeStreamToFile(tgzStream, `${outPath}`),
+        writeStreamToFile(tgzStream, outPath),
     ]);
     return {
         ...info,

package/src/version.d.ts

@@ -11,10 +11,10 @@ declare enum RepoType {
     unknown = "unknown"
 }
 export declare function getRepoType(): Promise<RepoType>;
-type RepoInfo = {
+interface RepoInfo {
     branch: null | string;
     revision: string;
-};
+}
 export declare function getRepoInfo(): Promise<RepoInfo>;
 export interface SemverTag {
     major: string;

package/src/version.js

@@ -4,7 +4,7 @@ import { getCfg, getPkg } from './pkg.js';
 import { buildLog } from './run.js';
 export function getBuild() {
     const arg = process.argv.find((el) => /^--buildNum=\d+$/.test(el));
-    return (arg && arg.substring(11)) || process.env.BUILD_NUMBER || '0';
+    return arg?.substring(11) || process.env.BUILD_NUMBER || '0';
 }
 /**
  * The one long-lived branch of the repository. All work happens on short-lived
@@ -21,9 +21,11 @@ var RepoType;
     RepoType["hg"] = "hg";
     RepoType["unknown"] = "unknown";
 })(RepoType || (RepoType = {}));
-export async function getRepoType() {
+// Returns a promise (rather than being `async`) because the body is synchronous
+// but the exported signature is awaited by callers and must stay thenable.
+export function getRepoType() {
     const { repoType } = getCfg();
-    return (repoType ||
+    return Promise.resolve(repoType ||
         (fs.existsSync('./.git')
             ? RepoType.git
             : fs.existsSync('./.hg')
@@ -47,7 +49,7 @@ const semverTagRegex = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-
  * semver version tag (an optional leading `v` is allowed).
  */
 export function parseSemverTag(tag) {
-    const [, major, minor, patch, prerelease] = tag.match(semverTagRegex) || [];
+    const [, major, minor, patch, prerelease] = semverTagRegex.exec(tag) || [];
     if (!major || !minor || !patch) {
         return null;
     }
@@ -113,7 +115,6 @@ export async function assertReleaseCommitIsOnMainBranch(mainBranch = getMainBran
     const { revision } = await getRepoInfo();
     const candidateRefs = [mainBranch, `origin/${mainBranch}`];
     for (const ref of candidateRefs) {
-        // eslint-disable-next-line no-await-in-loop
         if (await gitIsAncestor(revision, ref)) {
             return;
         }