Print output with verbose option

Author: ehmicky

docs/scripts.md

@@ -404,7 +404,8 @@ $.verbose = true;
 // Execa
 import {$ as $_} from 'execa';
 
-const $ = $_({verbose: true});
+// `verbose: 'short'` is also available
+const $ = $_({verbose: 'full'});
 
 await $`echo example`;
 ```
@@ -418,7 +419,8 @@ NODE_DEBUG=execa node file.js
 Which prints:
 
 ```
-[19:49:00.360] $ echo example
+[19:49:00.360] [0] $ echo example
+example
 ```
 
 ### Piping stdout to another command

index.d.ts

@@ -543,13 +543,18 @@ type CommonOptions<IsSync extends boolean = boolean> = {
 	readonly windowsHide?: boolean;
 
 	/**
-	Print each command on `stderr` before executing it.
+	If `verbose` is `'short'` or `'full'`, prints each command on `stderr` before executing it.
 
-	This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
+	If `verbose` is `'full'`, the command's `stdout` and `stderr` are printed too, unless either:
+	- the `stdout`/`stderr` option is `ignore` or `inherit`.
+	- the `stdout`/`stderr` is redirected to [a stream](https://nodejs.org/api/stream.html#readablepipedestination-options), a file, a file descriptor, or another child process.
+	- the `encoding` option is set.
 
-	@default false
+	This can also be set to `'full'` by setting the `NODE_DEBUG=execa` environment variable in the current process.
+
+	@default 'none'
 	*/
-	readonly verbose?: boolean;
+	readonly verbose?: 'none' | 'short' | 'full';
 
 	/**
 	Kill the spawned process when the parent process exits unless either:
@@ -1028,7 +1033,7 @@ export function execa<OptionsType extends Options = {}>(
 /**
 Same as `execa()` but synchronous.
 
-Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal`, `lines` and `verbose: 'full'`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable, a transform or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 
@@ -1129,7 +1134,7 @@ export function execaCommand<OptionsType extends Options = {}>(
 /**
 Same as `execaCommand()` but synchronous.
 
-Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal`, `lines` and `verbose: 'full'`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable, a transform or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 
@@ -1187,7 +1192,7 @@ type Execa$<OptionsType extends CommonOptions = {}> = {
 	/**
 	Same as $\`command\` but synchronous.
 
-	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal`, `lines` and `verbose: 'full'`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable, a transform or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 	Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 
@@ -1241,7 +1246,7 @@ type Execa$<OptionsType extends CommonOptions = {}> = {
 	/**
 	Same as $\`command\` but synchronous.
 
-	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal` and `lines`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
+	Cannot use the following options: `all`, `cleanup`, `buffer`, `detached`, `ipc`, `serialization`, `cancelSignal`, `lines` and `verbose: 'full'`. Also, the `stdin`, `stdout`, `stderr`, `stdio` and `input` options cannot be an array, an iterable, a transform or a web stream. Node.js streams must have a file descriptor unless the `input` option is used.
 
 	Returns or throws a `childProcessResult`. The `childProcess` is not returned: its methods and properties are not available. This includes [`.kill()`](https://nodejs.org/api/child_process.html#subprocesskillsignal), [`.pid`](https://nodejs.org/api/child_process.html#subprocesspid), `.pipe()` and the [`.stdin`/`.stdout`/`.stderr`](https://nodejs.org/api/child_process.html#subprocessstdout) streams.
 

index.test-d.ts

@@ -1440,8 +1440,12 @@ execa('unicorns', {windowsVerbatimArguments: true});
 execaSync('unicorns', {windowsVerbatimArguments: true});
 execa('unicorns', {windowsHide: false});
 execaSync('unicorns', {windowsHide: false});
-execa('unicorns', {verbose: false});
-execaSync('unicorns', {verbose: false});
+execa('unicorns', {verbose: 'none'});
+execaSync('unicorns', {verbose: 'none'});
+execa('unicorns', {verbose: 'short'});
+execaSync('unicorns', {verbose: 'short'});
+execa('unicorns', {verbose: 'full'});
+execaSync('unicorns', {verbose: 'full'});
 expectError(execa('unicorns', {verbose: 'other'}));
 expectError(execaSync('unicorns', {verbose: 'other'}));
 /* eslint-enable @typescript-eslint/no-floating-promises */

lib/arguments/options.js

@@ -6,6 +6,7 @@ import isPlainObject from 'is-plain-obj';
 import {normalizeForceKillAfterDelay} from '../exit/kill.js';
 import {validateTimeout} from '../exit/timeout.js';
 import {logCommand} from '../verbose/start.js';
+import {getVerboseInfo} from '../verbose/info.js';
 import {handleNodeOption} from './node.js';
 import {joinCommand} from './escape.js';
 import {normalizeCwd, safeNormalizeFileUrl, normalizeFileUrl} from './cwd.js';
@@ -39,8 +40,9 @@ export const normalizeArguments = (rawFile, rawArgs = [], rawOptions = {}) => {
 
 export const handleCommand = (filePath, rawArgs, rawOptions) => {
 	const {command, escapedCommand} = joinCommand(filePath, rawArgs);
-	logCommand(escapedCommand, rawOptions);
-	return {command, escapedCommand};
+	const verboseInfo = getVerboseInfo(rawOptions);
+	logCommand(escapedCommand, verboseInfo, rawOptions);
+	return {command, escapedCommand, verboseInfo};
 };
 
 export const handleArguments = (filePath, rawArgs, rawOptions) => {

lib/async.js

@@ -14,8 +14,8 @@ import {getSpawnedResult} from './stream/resolve.js';
 import {mergePromise} from './promise.js';
 
 export const execa = (rawFile, rawArgs, rawOptions) => {
-	const {file, args, command, escapedCommand, options, stdioStreamsGroups} = handleAsyncArguments(rawFile, rawArgs, rawOptions);
-	const {spawned, promise} = spawnProcessAsync({file, args, options, command, escapedCommand, stdioStreamsGroups});
+	const {file, args, command, escapedCommand, options, stdioStreamsGroups, stdioState} = handleAsyncArguments(rawFile, rawArgs, rawOptions);
+	const {spawned, promise} = spawnProcessAsync({file, args, options, command, escapedCommand, stdioStreamsGroups, stdioState});
 	spawned.pipe = pipeToProcess.bind(undefined, {source: spawned, sourcePromise: promise, stdioStreamsGroups, destinationOptions: {}});
 	mergePromise(spawned, promise);
 	PROCESS_OPTIONS.set(spawned, options);
@@ -24,11 +24,11 @@ export const execa = (rawFile, rawArgs, rawOptions) => {
 
 const handleAsyncArguments = (rawFile, rawArgs, rawOptions) => {
 	[rawFile, rawArgs, rawOptions] = normalizeArguments(rawFile, rawArgs, rawOptions);
-	const {command, escapedCommand} = handleCommand(rawFile, rawArgs, rawOptions);
+	const {command, escapedCommand, verboseInfo} = handleCommand(rawFile, rawArgs, rawOptions);
 	const {file, args, options: normalizedOptions} = handleArguments(rawFile, rawArgs, rawOptions);
 	const options = handleAsyncOptions(normalizedOptions);
-	const stdioStreamsGroups = handleInputAsync(options);
-	return {file, args, command, escapedCommand, options, stdioStreamsGroups};
+	const {stdioStreamsGroups, stdioState} = handleInputAsync(options, verboseInfo);
+	return {file, args, command, escapedCommand, options, stdioStreamsGroups, stdioState};
 };
 
 // Prevent passing the `timeout` option directly to `child_process.spawn()`
@@ -40,7 +40,7 @@ const handleAsyncOptions = ({timeout, signal, cancelSignal, ...options}) => {
 	return {...options, timeoutDuration: timeout, signal: cancelSignal};
 };
 
-const spawnProcessAsync = ({file, args, options, command, escapedCommand, stdioStreamsGroups}) => {
+const spawnProcessAsync = ({file, args, options, command, escapedCommand, stdioStreamsGroups, stdioState}) => {
 	let spawned;
 	try {
 		spawned = spawn(file, args, options);
@@ -52,7 +52,7 @@ const spawnProcessAsync = ({file, args, options, command, escapedCommand, stdioS
 	setMaxListeners(Number.POSITIVE_INFINITY, controller.signal);
 
 	const originalStreams = [...spawned.stdio];
-	pipeOutputAsync(spawned, stdioStreamsGroups, controller);
+	pipeOutputAsync(spawned, stdioStreamsGroups, stdioState, controller);
 	cleanupOnExit(spawned, options, controller);
 
 	spawned.kill = spawnedKill.bind(undefined, {kill: spawned.kill.bind(spawned), spawned, options, controller});

lib/stdio/async.js

@@ -8,7 +8,7 @@ import {TYPE_TO_MESSAGE} from './type.js';
 import {generatorToDuplexStream, pipeGenerator} from './generator.js';
 
 // Handle `input`, `inputFile`, `stdin`, `stdout` and `stderr` options, before spawning, in async mode
-export const handleInputAsync = options => handleInput(addPropertiesAsync, options, false);
+export const handleInputAsync = (options, verboseInfo) => handleInput(addPropertiesAsync, options, verboseInfo, false);
 
 const forbiddenIfAsync = ({type, optionName}) => {
 	throw new TypeError(`The \`${optionName}\` option cannot be ${TYPE_TO_MESSAGE[type]}.`);
@@ -36,7 +36,8 @@ const addPropertiesAsync = {
 
 // Handle `input`, `inputFile`, `stdin`, `stdout` and `stderr` options, after spawning, in async mode
 // When multiple input streams are used, we merge them to ensure the output stream ends only once each input stream has ended
-export const pipeOutputAsync = (spawned, stdioStreamsGroups, controller) => {
+export const pipeOutputAsync = (spawned, stdioStreamsGroups, stdioState, controller) => {
+	stdioState.spawned = spawned;
 	const inputStreamsGroups = {};
 
 	for (const stdioStreams of stdioStreamsGroups) {

lib/stdio/forward.js

@@ -6,7 +6,7 @@ export const forwardStdio = stdioStreamsGroups => stdioStreamsGroups.map(stdioSt
 // Whether `childProcess.std*` will be set
 export const willPipeStreams = stdioStreams => PIPED_STDIO_VALUES.has(forwardStdioItem(stdioStreams));
 
-const PIPED_STDIO_VALUES = new Set(['pipe', 'overlapped', undefined, null]);
+export const PIPED_STDIO_VALUES = new Set(['pipe', 'overlapped', undefined, null]);
 
 const forwardStdioItem = stdioStreams => {
 	if (stdioStreams.length > 1) {

lib/stdio/handle.js

@@ -1,3 +1,4 @@
+import {handleStreamsVerbose} from '../verbose/output.js';
 import {getStdioOptionType, isRegularUrl, isUnknownStdioString} from './type.js';
 import {addStreamDirection} from './direction.js';
 import {normalizeStdio} from './option.js';
@@ -9,18 +10,20 @@ import {normalizeGenerators} from './generator.js';
 import {forwardStdio} from './forward.js';
 
 // Handle `input`, `inputFile`, `stdin`, `stdout` and `stderr` options, before spawning, in async/sync mode
-export const handleInput = (addProperties, options, isSync) => {
+export const handleInput = (addProperties, options, verboseInfo, isSync) => {
+	const stdioState = {};
 	const stdio = normalizeStdio(options);
 	const [stdinStreams, ...otherStreamsGroups] = stdio.map((stdioOption, fdNumber) => getStdioStreams(stdioOption, fdNumber));
 	const stdioStreamsGroups = [[...stdinStreams, ...handleInputOptions(options)], ...otherStreamsGroups]
 		.map(stdioStreams => validateStreams(stdioStreams))
 		.map(stdioStreams => addStreamDirection(stdioStreams))
+		.map(stdioStreams => handleStreamsVerbose({stdioStreams, options, isSync, stdioState, verboseInfo}))
 		.map(stdioStreams => handleStreamsLines(stdioStreams, options, isSync))
 		.map(stdioStreams => handleStreamsEncoding(stdioStreams, options, isSync))
 		.map(stdioStreams => normalizeGenerators(stdioStreams))
 		.map(stdioStreams => addStreamsProperties(stdioStreams, addProperties));
 	options.stdio = forwardStdio(stdioStreamsGroups);
-	return stdioStreamsGroups;
+	return {stdioStreamsGroups, stdioState};
 };
 
 // We make sure passing an array with a single item behaves the same as passing that item without an array.

lib/stdio/sync.js

@@ -4,8 +4,8 @@ import {handleInput} from './handle.js';
 import {TYPE_TO_MESSAGE} from './type.js';
 
 // Handle `input`, `inputFile`, `stdin`, `stdout` and `stderr` options, before spawning, in sync mode
-export const handleInputSync = options => {
-	const stdioStreamsGroups = handleInput(addPropertiesSync, options, true);
+export const handleInputSync = (options, verboseInfo) => {
+	const {stdioStreamsGroups} = handleInput(addPropertiesSync, options, verboseInfo, true);
 	addInputOptionSync(stdioStreamsGroups, options);
 	return stdioStreamsGroups;
 };

lib/sync.js

@@ -13,11 +13,11 @@ export const execaSync = (rawFile, rawArgs, rawOptions) => {
 
 const handleSyncArguments = (rawFile, rawArgs, rawOptions) => {
 	[rawFile, rawArgs, rawOptions] = normalizeArguments(rawFile, rawArgs, rawOptions);
-	const {command, escapedCommand} = handleCommand(rawFile, rawArgs, rawOptions);
+	const {command, escapedCommand, verboseInfo} = handleCommand(rawFile, rawArgs, rawOptions);
 	const syncOptions = normalizeSyncOptions(rawOptions);
 	const {file, args, options} = handleArguments(rawFile, rawArgs, syncOptions);
 	validateSyncOptions(options);
-	const stdioStreamsGroups = handleInputSync(options);
+	const stdioStreamsGroups = handleInputSync(options, verboseInfo);
 	return {file, args, command, escapedCommand, options, stdioStreamsGroups};
 };
 

lib/verbose/info.js

@@ -0,0 +1,19 @@
+import {debuglog} from 'node:util';
+
+export const getVerboseInfo = ({verbose = verboseDefault}) => {
+	if (verbose === 'none') {
+		return {verbose};
+	}
+
+	const verboseId = VERBOSE_ID++;
+	return {verbose, verboseId};
+};
+
+const verboseDefault = debuglog('execa').enabled ? 'full' : 'none';
+
+// Prepending the `pid` is useful when multiple commands print their output at the same time.
+// However, we cannot use the real PID since this is not available with `child_process.spawnSync()`.
+// Also, we cannot use the real PID if we want to print it before `child_process.spawn()` is run.
+// As a pro, it is shorter than a normal PID and never re-uses the same id.
+// As a con, it cannot be used to send signals.
+let VERBOSE_ID = 0n;

lib/verbose/log.js

@@ -2,10 +2,25 @@ import {writeFileSync} from 'node:fs';
 import process from 'node:process';
 
 // Write synchronously to ensure lines are properly ordered and not interleaved with `stdout`
-export const verboseLog = (string, icon) => {
-	writeFileSync(process.stderr.fd, `[${getTimestamp()}] ${ICONS[icon]} ${string}\n`);
+export const verboseLog = (string, verboseId, icon) => {
+	const prefixedLines = addPrefix(string, verboseId, icon);
+	writeFileSync(process.stderr.fd, `${prefixedLines}\n`);
 };
 
+const addPrefix = (string, verboseId, icon) => string.includes('\n')
+	? string
+		.split('\n')
+		.map(line => addPrefixToLine(line, verboseId, icon))
+		.join('\n')
+	: addPrefixToLine(string, verboseId, icon);
+
+const addPrefixToLine = (line, verboseId, icon) => [
+	`[${getTimestamp()}]`,
+	`[${verboseId}]`,
+	ICONS[icon],
+	line,
+].join(' ');
+
 // Prepending the timestamp allows debugging the slow paths of a process
 const getTimestamp = () => {
 	const date = new Date();
@@ -17,4 +32,5 @@ const padField = (field, padding) => String(field).padStart(padding, '0');
 const ICONS = {
 	command: '$',
 	pipedCommand: '|',
+	output: ' ',
 };