@optique/run 1.0.12-dev.2687 → 1.0.12-dev.2694

package/dist/output.cjs

@@ -0,0 +1,124 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
+const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+
+//#region src/output.ts
+let sleepCell;
+function sleepSync(ms) {
+	sleepCell ??= new Int32Array(new SharedArrayBuffer(4));
+	Atomics.wait(sleepCell, 0, 0, ms);
+}
+function getErrorCode(error) {
+	return typeof error === "object" && error != null && "code" in error ? error.code : void 0;
+}
+/**
+* Writes all of the given bytes to a file descriptor synchronously.
+*
+* Partial writes resume from the next unwritten byte.  When the descriptor
+* is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
+* briefly and retries, blocking the current thread until the reader catches
+* up.  When the reader has closed the pipe (`EPIPE`) or reset the socket
+* (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
+* silently.
+*
+* @param fd The file descriptor to write to.
+* @param bytes The bytes to write.
+* @param deps Dependencies to use instead of the defaults, for testing.
+* @throws {Error} If writing fails for any other reason, or if a write makes
+*         no progress.
+* @internal
+*/
+function writeAllSync(fd, bytes, deps = {}) {
+	const writeSync = deps.writeSync ?? node_fs.writeSync;
+	const sleep = deps.sleep ?? sleepSync;
+	let offset = 0;
+	while (offset < bytes.length) {
+		let written;
+		try {
+			written = writeSync(fd, bytes, offset, bytes.length - offset);
+		} catch (error) {
+			const code = getErrorCode(error);
+			if (code === "EAGAIN" || code === "EWOULDBLOCK") {
+				sleep(1);
+				continue;
+			}
+			if (code === "EINTR") continue;
+			if (code === "EPIPE" || code === "ECONNRESET") return;
+			throw error;
+		}
+		if (written <= 0) throw new Error(`Failed to write output to file descriptor ${fd}: no bytes were written.`);
+		offset += written;
+	}
+}
+/**
+* Reads the encoding a writable stream applies to strings, which
+* `setDefaultEncoding()` changes.  Node.js and Bun expose it only through
+* the stream's internal state, so this returns `undefined` when that is not
+* available.
+*
+* @param stream The stream to inspect.
+* @returns The default encoding, or `undefined` if it cannot be read.
+* @internal
+*/
+function getDefaultEncoding(stream) {
+	if (!("_writableState" in stream)) return void 0;
+	const state = stream._writableState;
+	return typeof state === "object" && state != null && "defaultEncoding" in state ? state.defaultEncoding : void 0;
+}
+function isUtf8Encoding(encoding) {
+	return encoding === void 0 || typeof encoding === "string" && ["utf8", "utf-8"].includes(encoding.toLowerCase());
+}
+/**
+* Decides whether output for the given stream should bypass the stream and
+* be written directly to its file descriptor.
+*
+* TTYs keep going through the stream, since terminal writes are synchronous
+* on POSIX and Windows consoles need the stream's own handling.  Windows is
+* excluded altogether.  Streams without a file descriptor, such as
+* `process.stdout` in a Node.js worker thread, also keep going through the
+* stream, since writing to fd 1 or 2 would bypass the worker's redirection.
+* Deno is excluded as well: its streams do not lose queued output on exit,
+* and its `fs.writeSync()` can write part of the buffer to a non-blocking
+* pipe and then throw `EAGAIN` without reporting how much it wrote, which
+* would make retrying duplicate output.  Finally, streams whose default
+* encoding is not UTF-8 keep going through the stream, since direct writes
+* always encode the text as UTF-8.
+*
+* @param stream The stream to inspect.
+* @param platform The value of `process.platform`.
+* @param deno Whether the current runtime is Deno.
+* @returns `true` if output should be written directly to `stream.fd`.
+* @internal
+*/
+function shouldWriteDirectly(stream, platform, deno) {
+	const fd = stream.fd;
+	return !deno && platform !== "win32" && !stream.isTTY && typeof fd === "number" && Number.isInteger(fd) && fd >= 0 && isUtf8Encoding(stream.defaultEncoding);
+}
+const encoder = new TextEncoder();
+/**
+* Writes text to standard output or standard error such that, when the
+* stream is a pipe or a file, the text has been completely handed to the
+* operating system by the time this returns (unless the reader closed the
+* pipe).  Otherwise, it falls back to the stream's `write()` method.
+*
+* Note that output queued in the stream by earlier `write()` calls is not
+* flushed, and that text written directly can overtake it.
+*
+* @param streamName The stream to write to.
+* @param text The text to write.
+* @throws {Error} If writing to the file descriptor fails.
+* @internal
+*/
+function writeOutput(streamName, text) {
+	const stream = node_process.default[streamName];
+	const streamLike = {
+		isTTY: stream.isTTY,
+		fd: stream.fd,
+		defaultEncoding: getDefaultEncoding(stream)
+	};
+	if (shouldWriteDirectly(streamLike, node_process.default.platform, "Deno" in globalThis)) writeAllSync(stream.fd, encoder.encode(text));
+	else stream.write(text);
+}
+
+//#endregion
+exports.writeOutput = writeOutput;

package/dist/output.js

@@ -0,0 +1,123 @@
+import { writeSync } from "node:fs";
+import process from "node:process";
+
+//#region src/output.ts
+let sleepCell;
+function sleepSync(ms) {
+	sleepCell ??= new Int32Array(new SharedArrayBuffer(4));
+	Atomics.wait(sleepCell, 0, 0, ms);
+}
+function getErrorCode(error) {
+	return typeof error === "object" && error != null && "code" in error ? error.code : void 0;
+}
+/**
+* Writes all of the given bytes to a file descriptor synchronously.
+*
+* Partial writes resume from the next unwritten byte.  When the descriptor
+* is non-blocking and temporarily full (`EAGAIN`/`EWOULDBLOCK`), this sleeps
+* briefly and retries, blocking the current thread until the reader catches
+* up.  When the reader has closed the pipe (`EPIPE`) or reset the socket
+* (`ECONNRESET`), the rest of the output cannot be delivered, so this returns
+* silently.
+*
+* @param fd The file descriptor to write to.
+* @param bytes The bytes to write.
+* @param deps Dependencies to use instead of the defaults, for testing.
+* @throws {Error} If writing fails for any other reason, or if a write makes
+*         no progress.
+* @internal
+*/
+function writeAllSync(fd, bytes, deps = {}) {
+	const writeSync$1 = deps.writeSync ?? writeSync;
+	const sleep = deps.sleep ?? sleepSync;
+	let offset = 0;
+	while (offset < bytes.length) {
+		let written;
+		try {
+			written = writeSync$1(fd, bytes, offset, bytes.length - offset);
+		} catch (error) {
+			const code = getErrorCode(error);
+			if (code === "EAGAIN" || code === "EWOULDBLOCK") {
+				sleep(1);
+				continue;
+			}
+			if (code === "EINTR") continue;
+			if (code === "EPIPE" || code === "ECONNRESET") return;
+			throw error;
+		}
+		if (written <= 0) throw new Error(`Failed to write output to file descriptor ${fd}: no bytes were written.`);
+		offset += written;
+	}
+}
+/**
+* Reads the encoding a writable stream applies to strings, which
+* `setDefaultEncoding()` changes.  Node.js and Bun expose it only through
+* the stream's internal state, so this returns `undefined` when that is not
+* available.
+*
+* @param stream The stream to inspect.
+* @returns The default encoding, or `undefined` if it cannot be read.
+* @internal
+*/
+function getDefaultEncoding(stream) {
+	if (!("_writableState" in stream)) return void 0;
+	const state = stream._writableState;
+	return typeof state === "object" && state != null && "defaultEncoding" in state ? state.defaultEncoding : void 0;
+}
+function isUtf8Encoding(encoding) {
+	return encoding === void 0 || typeof encoding === "string" && ["utf8", "utf-8"].includes(encoding.toLowerCase());
+}
+/**
+* Decides whether output for the given stream should bypass the stream and
+* be written directly to its file descriptor.
+*
+* TTYs keep going through the stream, since terminal writes are synchronous
+* on POSIX and Windows consoles need the stream's own handling.  Windows is
+* excluded altogether.  Streams without a file descriptor, such as
+* `process.stdout` in a Node.js worker thread, also keep going through the
+* stream, since writing to fd 1 or 2 would bypass the worker's redirection.
+* Deno is excluded as well: its streams do not lose queued output on exit,
+* and its `fs.writeSync()` can write part of the buffer to a non-blocking
+* pipe and then throw `EAGAIN` without reporting how much it wrote, which
+* would make retrying duplicate output.  Finally, streams whose default
+* encoding is not UTF-8 keep going through the stream, since direct writes
+* always encode the text as UTF-8.
+*
+* @param stream The stream to inspect.
+* @param platform The value of `process.platform`.
+* @param deno Whether the current runtime is Deno.
+* @returns `true` if output should be written directly to `stream.fd`.
+* @internal
+*/
+function shouldWriteDirectly(stream, platform, deno) {
+	const fd = stream.fd;
+	return !deno && platform !== "win32" && !stream.isTTY && typeof fd === "number" && Number.isInteger(fd) && fd >= 0 && isUtf8Encoding(stream.defaultEncoding);
+}
+const encoder = new TextEncoder();
+/**
+* Writes text to standard output or standard error such that, when the
+* stream is a pipe or a file, the text has been completely handed to the
+* operating system by the time this returns (unless the reader closed the
+* pipe).  Otherwise, it falls back to the stream's `write()` method.
+*
+* Note that output queued in the stream by earlier `write()` calls is not
+* flushed, and that text written directly can overtake it.
+*
+* @param streamName The stream to write to.
+* @param text The text to write.
+* @throws {Error} If writing to the file descriptor fails.
+* @internal
+*/
+function writeOutput(streamName, text) {
+	const stream = process[streamName];
+	const streamLike = {
+		isTTY: stream.isTTY,
+		fd: stream.fd,
+		defaultEncoding: getDefaultEncoding(stream)
+	};
+	if (shouldWriteDirectly(streamLike, process.platform, "Deno" in globalThis)) writeAllSync(stream.fd, encoder.encode(text));
+	else stream.write(text);
+}
+
+//#endregion
+export { writeOutput };

package/dist/print.cjs

@@ -1,4 +1,5 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_output = require('./output.cjs');
 const node_process = require_rolldown_runtime.__toESM(require("node:process"));
 const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
 
@@ -40,7 +41,7 @@ function printError(message, options = {}) {
 	const stream = options.stream ?? "stderr";
 	const output = node_process.default[stream];
 	const quotes = options.quotes ?? !output.isTTY;
-	const printer = createPrinter({
+	const format = createFormatter({
 		stream,
 		colors: options.colors,
 		quotes,
@@ -50,8 +51,12 @@ function printError(message, options = {}) {
 		type: "text",
 		text: "Error: "
 	}, ...message];
-	printer(errorMessage);
-	if (options.exitCode != null) node_process.default.exit(options.exitCode);
+	const text = format(errorMessage) + "\n";
+	if (options.exitCode == null) output.write(text);
+	else {
+		require_output.writeOutput(stream, text);
+		node_process.default.exit(options.exitCode);
+	}
 }
 /**
 * Creates a custom printer function with predefined formatting options.
@@ -82,17 +87,23 @@ function printError(message, options = {}) {
 */
 function createPrinter(options = {}) {
 	const stream = options.stream ?? "stdout";
-	const output = node_process.default[stream];
+	const format = createFormatter(options);
+	return (message) => {
+		node_process.default[stream].write(format(message) + "\n");
+	};
+}
+/**
+* Creates a function that formats messages for the given stream, resolving
+* terminal-dependent defaults once, at creation time.
+*/
+function createFormatter(options) {
+	const output = node_process.default[options.stream ?? "stdout"];
 	const formatOptions = {
 		colors: options.colors ?? output.isTTY,
 		quotes: options.quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	};
-	return (message) => {
-		const formatted = (0, __optique_core_message.formatMessage)(message, formatOptions);
-		if (stream === "stderr") node_process.default.stderr.write(formatted + "\n");
-		else node_process.default.stdout.write(formatted + "\n");
-	};
+	return (message) => (0, __optique_core_message.formatMessage)(message, formatOptions);
 }
 
 //#endregion

package/dist/print.d.cts

@@ -26,6 +26,12 @@ interface PrintErrorOptions extends PrintOptions {
   /**
    * Exit code to use when exiting the process.
    * If specified, the process will exit with this code after printing the error.
+   *
+   * When the output stream is a pipe or a file on POSIX systems under Node.js
+   * or Bun, the error message is written directly to its file descriptor, and
+   * the process exits only after the whole message has been written, even if
+   * the reader is slow.  Output that earlier calls queued in the stream is not
+   * flushed.
    */
   readonly exitCode?: number;
 }
@@ -80,6 +86,9 @@ declare function print(message: Message, options?: PrintOptions): void;
  *
  * @param message The structured error message to print.
  * @param options Optional formatting options and exit code.
+ * @throws {Error} If `exitCode` is specified and writing the message directly
+ *         to the output stream's file descriptor fails for a reason other
+ *         than the reader having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript

package/dist/print.d.ts

@@ -26,6 +26,12 @@ interface PrintErrorOptions extends PrintOptions {
   /**
    * Exit code to use when exiting the process.
    * If specified, the process will exit with this code after printing the error.
+   *
+   * When the output stream is a pipe or a file on POSIX systems under Node.js
+   * or Bun, the error message is written directly to its file descriptor, and
+   * the process exits only after the whole message has been written, even if
+   * the reader is slow.  Output that earlier calls queued in the stream is not
+   * flushed.
    */
   readonly exitCode?: number;
 }
@@ -80,6 +86,9 @@ declare function print(message: Message, options?: PrintOptions): void;
  *
  * @param message The structured error message to print.
  * @param options Optional formatting options and exit code.
+ * @throws {Error} If `exitCode` is specified and writing the message directly
+ *         to the output stream's file descriptor fails for a reason other
+ *         than the reader having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript

package/dist/print.js

@@ -1,3 +1,4 @@
+import { writeOutput } from "./output.js";
 import process from "node:process";
 import { formatMessage } from "@optique/core/message";
 
@@ -39,7 +40,7 @@ function printError(message$1, options = {}) {
 	const stream = options.stream ?? "stderr";
 	const output = process[stream];
 	const quotes = options.quotes ?? !output.isTTY;
-	const printer = createPrinter({
+	const format = createFormatter({
 		stream,
 		colors: options.colors,
 		quotes,
@@ -49,8 +50,12 @@ function printError(message$1, options = {}) {
 		type: "text",
 		text: "Error: "
 	}, ...message$1];
-	printer(errorMessage);
-	if (options.exitCode != null) process.exit(options.exitCode);
+	const text$1 = format(errorMessage) + "\n";
+	if (options.exitCode == null) output.write(text$1);
+	else {
+		writeOutput(stream, text$1);
+		process.exit(options.exitCode);
+	}
 }
 /**
 * Creates a custom printer function with predefined formatting options.
@@ -81,17 +86,23 @@ function printError(message$1, options = {}) {
 */
 function createPrinter(options = {}) {
 	const stream = options.stream ?? "stdout";
-	const output = process[stream];
+	const format = createFormatter(options);
+	return (message$1) => {
+		process[stream].write(format(message$1) + "\n");
+	};
+}
+/**
+* Creates a function that formats messages for the given stream, resolving
+* terminal-dependent defaults once, at creation time.
+*/
+function createFormatter(options) {
+	const output = process[options.stream ?? "stdout"];
 	const formatOptions = {
 		colors: options.colors ?? output.isTTY,
 		quotes: options.quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	};
-	return (message$1) => {
-		const formatted = formatMessage(message$1, formatOptions);
-		if (stream === "stderr") process.stderr.write(formatted + "\n");
-		else process.stdout.write(formatted + "\n");
-	};
+	return (message$1) => formatMessage(message$1, formatOptions);
 }
 
 //#endregion

package/dist/run.cjs

@@ -1,7 +1,8 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_output = require('./output.cjs');
 const __optique_core_facade = require_rolldown_runtime.__toESM(require("@optique/core/facade"));
-const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 
 //#region src/run.ts
 function getProgramHelpMetadata(metadata) {
@@ -66,10 +67,10 @@ function buildCoreOptions(options, programMetadata) {
 	const programName = options.programName ?? node_path.default.basename(node_process.default.argv[1] ?? "cli");
 	const args = options.args ?? node_process.default.argv.slice(2);
 	const stdout = options.stdout ?? ((line) => {
-		node_process.default.stdout.write(`${line}\n`);
+		require_output.writeOutput("stdout", `${line}\n`);
 	});
 	const stderr = options.stderr ?? ((line) => {
-		node_process.default.stderr.write(`${line}\n`);
+		require_output.writeOutput("stderr", `${line}\n`);
 	});
 	const onExit = options.onExit ?? ((exitCode) => node_process.default.exit(exitCode));
 	const colors = options.colors ?? node_process.default.stdout.isTTY;

package/dist/run.d.cts

@@ -28,6 +28,14 @@ interface RunOptions {
    * Function used to output help and usage messages.  Assumes it prints the
    * ending newline.
    *
+   * When `process.stdout` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.log()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stdout` with a trailing newline
    */
   readonly stdout?: (text: string) => void;
@@ -35,12 +43,32 @@ interface RunOptions {
    * Function used to output error messages.  Assumes it prints the ending
    * newline.
    *
+   * When `process.stderr` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.error()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stderr` with a trailing newline
    */
   readonly stderr?: (text: string) => void;
   /**
    * Function used to exit the process on help/version display or parse error.
    *
+   * This hook is synchronous and runs immediately after an output handler
+   * returns.  With the default `process.exit()` handler, custom `stdout` and
+   * `stderr` handlers must finish writing synchronously before returning.
+   * The default exit handler also does not wait for writes queued by
+   * application code.
+   *
+   * To wait for asynchronous writes, record their completion promises and
+   * throw an exception carrying the exit code from `onExit`.  Catch that
+   * exception outside the runner, await the recorded promises, then call
+   * `process.exit()` with that code.
+   * An arbitrary delay does not guarantee that output has been flushed.
+   *
    * @default `process.exit`
    */
   readonly onExit?: (exitCode: number) => never;
@@ -285,12 +313,33 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * - Exit the process with appropriate codes on help or error
  * - Format output according to terminal capabilities
  *
+ * On affected Bun versions, importing `@optique/run` can cause large
+ * application `console.log()` output to be silently truncated when piped,
+ * even after successful parsing and natural process exit.  This is
+ * [Bun issue #36419](https://github.com/oven-sh/bun/issues/36419), reported
+ * on macOS arm64 with Bun 1.3.14 and 1.4.2.  Use `process.stdout.write()`
+ * instead of `console.log()` for application data, and `process.stderr.write()`
+ * instead of `console.error()` for diagnostics.  Both console methods can lose
+ * large piped output.  Let the process exit naturally.  If explicit termination
+ * is necessary, wait for the completion callbacks of all pending stdout/stderr
+ * writes before calling `process.exit()`; a delay is not a flush guarantee.  Waiting after `console.log()` or `console.error()` cannot
+ * recover dropped bytes.
+ *
+ * Setting `colors` and `maxWidth` explicitly does not avoid this Bun bug:
+ * importing `node:process`, which this module does, was enough to trigger it
+ * in Bun 1.3.14.  The upstream fix was merged in
+ * [Bun PR #43868](https://github.com/oven-sh/bun/pull/43868); check whether
+ * your Bun release includes it.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  *                See {@link RunOptions} for available settings.
  * @returns The parsed result if successful. On help display or parse errors,
  *          the function will call `process.exit()` and not return.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript
@@ -365,12 +414,17 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * Use this when you know your parser is sync-only to get direct return values
  * without Promise wrappers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The sync parser type being executed.
  * @param parser The synchronous command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
  * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
@@ -390,10 +444,15 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * Promise. Use this when working with parsers that may contain async
  * value parsers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @returns A Promise of the parsed result if successful.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {

package/dist/run.d.ts

@@ -28,6 +28,14 @@ interface RunOptions {
    * Function used to output help and usage messages.  Assumes it prints the
    * ending newline.
    *
+   * When `process.stdout` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.log()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stdout` with a trailing newline
    */
   readonly stdout?: (text: string) => void;
@@ -35,12 +43,32 @@ interface RunOptions {
    * Function used to output error messages.  Assumes it prints the ending
    * newline.
    *
+   * When `process.stderr` is a pipe or a file on POSIX systems under Node.js or
+   * Bun, the default writes directly to its file descriptor and returns only
+   * after the whole text has been written, even if the reader is slow, so that
+   * exiting the process right afterward does not truncate the output.
+   *
+   * A custom writer using `console.error()` can lose large piped output on
+   * affected Bun versions.  See the Bun output warning on {@link run}.
+   *
    * @default Writes to `process.stderr` with a trailing newline
    */
   readonly stderr?: (text: string) => void;
   /**
    * Function used to exit the process on help/version display or parse error.
    *
+   * This hook is synchronous and runs immediately after an output handler
+   * returns.  With the default `process.exit()` handler, custom `stdout` and
+   * `stderr` handlers must finish writing synchronously before returning.
+   * The default exit handler also does not wait for writes queued by
+   * application code.
+   *
+   * To wait for asynchronous writes, record their completion promises and
+   * throw an exception carrying the exit code from `onExit`.  Catch that
+   * exception outside the runner, await the recorded promises, then call
+   * `process.exit()` with that code.
+   * An arbitrary delay does not guarantee that output has been flushed.
+   *
    * @default `process.exit`
    */
   readonly onExit?: (exitCode: number) => never;
@@ -285,12 +313,33 @@ type AcceptExactOptionalRunOptions<TOptions> = [TOptions] extends [RunOptions |
  * - Exit the process with appropriate codes on help or error
  * - Format output according to terminal capabilities
  *
+ * On affected Bun versions, importing `@optique/run` can cause large
+ * application `console.log()` output to be silently truncated when piped,
+ * even after successful parsing and natural process exit.  This is
+ * [Bun issue #36419](https://github.com/oven-sh/bun/issues/36419), reported
+ * on macOS arm64 with Bun 1.3.14 and 1.4.2.  Use `process.stdout.write()`
+ * instead of `console.log()` for application data, and `process.stderr.write()`
+ * instead of `console.error()` for diagnostics.  Both console methods can lose
+ * large piped output.  Let the process exit naturally.  If explicit termination
+ * is necessary, wait for the completion callbacks of all pending stdout/stderr
+ * writes before calling `process.exit()`; a delay is not a flush guarantee.  Waiting after `console.log()` or `console.error()` cannot
+ * recover dropped bytes.
+ *
+ * Setting `colors` and `maxWidth` explicitly does not avoid this Bun bug:
+ * importing `node:process`, which this module does, was enough to trigger it
+ * in Bun 1.3.14.  The upstream fix was merged in
+ * [Bun PR #43868](https://github.com/oven-sh/bun/pull/43868); check whether
+ * your Bun release includes it.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  *                See {@link RunOptions} for available settings.
  * @returns The parsed result if successful. On help display or parse errors,
  *          the function will call `process.exit()` and not return.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  *
  * @example
  * ```typescript
@@ -365,12 +414,17 @@ declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, option
  * Use this when you know your parser is sync-only to get direct return values
  * without Promise wrappers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The sync parser type being executed.
  * @param parser The synchronous command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
  * @throws {TypeError} If an async parser (or a {@link Program} wrapping one)
  * is passed at runtime.  Use {@link run} or {@link runAsync} instead.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runSync<T extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {
@@ -390,10 +444,15 @@ declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T,
  * Promise. Use this when working with parsers that may contain async
  * value parsers.
  *
+ * See {@link run} for Bun's piped console output warning and workarounds.
+ *
  * @template T The parser type being executed.
  * @param parser The command-line parser to execute.
  * @param options Configuration options for customizing behavior.
  * @returns A Promise of the parsed result if successful.
+ * @throws {Error} If the default `stdout` or `stderr` writer fails to write
+ *         to the stream's file descriptor for a reason other than the reader
+ *         having gone away (for example, `ENOSPC`).
  * @since 0.9.0
  */
 declare function runAsync<T extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[]>(parser: T, options: RunOptions & {

package/dist/run.js

@@ -1,6 +1,7 @@
+import { writeOutput } from "./output.js";
 import { runParser, runWith, runWithSync } from "@optique/core/facade";
-import path from "node:path";
 import process from "node:process";
+import path from "node:path";
 
 //#region src/run.ts
 function getProgramHelpMetadata(metadata) {
@@ -65,10 +66,10 @@ function buildCoreOptions(options, programMetadata) {
 	const programName = options.programName ?? path.basename(process.argv[1] ?? "cli");
 	const args = options.args ?? process.argv.slice(2);
 	const stdout = options.stdout ?? ((line) => {
-		process.stdout.write(`${line}\n`);
+		writeOutput("stdout", `${line}\n`);
 	});
 	const stderr = options.stderr ?? ((line) => {
-		process.stderr.write(`${line}\n`);
+		writeOutput("stderr", `${line}\n`);
 	});
 	const onExit = options.onExit ?? ((exitCode) => process.exit(exitCode));
 	const colors = options.colors ?? process.stdout.isTTY;

package/dist/valueparser.cjs

@@ -1,8 +1,8 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
 const __optique_core_nonempty = require_rolldown_runtime.__toESM(require("@optique/core/nonempty"));
-const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 
 //#region src/valueparser.ts
 /**

package/dist/valueparser.js

@@ -1,7 +1,7 @@
+import { existsSync, statSync } from "node:fs";
 import { basename, dirname, extname } from "node:path";
 import { message, text } from "@optique/core/message";
 import { ensureNonEmptyString } from "@optique/core/nonempty";
-import { existsSync, statSync } from "node:fs";
 
 //#region src/valueparser.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.0.12-dev.2687",
+  "version": "1.0.12-dev.2694",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.12-dev.2687+d6cc206f"
+    "@optique/core": "1.0.12-dev.2694+de298ac0"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",