build-strap 6.0.0 → 6.0.1-buildlog-stderr.142

package/README.md

@@ -32,8 +32,8 @@ By default, the build tools read project-specific configuration from your `packa
   "name": "your-project-name",
   "version": "1.2.3",
   "buildStrap": {
-    "nodeVersion": "12.18.2",
-    "yarnVersion": "1.22.4",
+    "nodeVersion": "24.18.0",
+    "yarnVersion": "1.22.22",
     "repoType": "git",
     "copyright": "your company",
     "mainBranch": "main",
@@ -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.0",
+  "version": "6.0.1-buildlog-stderr.142",
   "description": "Node scripts for building things",
   "license": "MIT",
   "author": "Justin Murray <justin@murrayju.com>",
@@ -12,7 +12,7 @@
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   },
   "dependencies": {
     "bytes": "^3.1.1",

package/src/docker.container.js

@@ -233,7 +233,7 @@ export const dockerContainerWaitForStart = async (container, testFn, timeoutMs =
                         return resolve();
                     }
                 }
-                catch (err) {
+                catch {
                     // ignore
                 }
                 return tries < maxAttempts

package/src/orbstack.d.ts

@@ -1,4 +1,4 @@
-import { SpawnOptions, SpawnResult } from './cp';
+import { SpawnOptions, SpawnResult } from './cp.js';
 export declare const ensureOrbStackInstalled: (options?: SpawnOptions) => Promise<SpawnResult | null>;
 export declare const ensureOrbStackRunning: (timeoutSeconds?: number) => Promise<void>;
 export declare const ensureOrbStackConfigured: (desiredConfig?: null | Record<string, unknown>) => Promise<void>;

package/src/orbstack.js

@@ -1,11 +1,11 @@
 import fs from 'fs-extra';
 import os from 'os';
 import path from 'path';
-import { brew } from './brew';
-import { spawn } from './cp';
-import { dockerIsRunning } from './docker';
-import { cmdExists, isMac } from './env';
-import { buildLog } from './run';
+import { brew } from './brew.js';
+import { spawn } from './cp.js';
+import { dockerIsRunning } from './docker.js';
+import { cmdExists, isMac } from './env.js';
+import { buildLog } from './run.js';
 export const ensureOrbStackInstalled = async (options) => {
     if (!isMac()) {
         throw new Error('OrbStack is only supported on macOS');

package/src/run.d.ts

@@ -1,5 +1,21 @@
 export declare function format(time?: Date): string;
-export declare function buildLog(msg: string, time?: Date): void;
+/**
+ * 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

@@ -2,11 +2,40 @@ export function format(time = new Date()) {
     return time.toTimeString().replace(/.*(\d{2}:\d{2}:\d{2}).*/, '$1');
 }
 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) {