@optique/run 1.3.0-dev.2529 → 1.3.0-dev.2530

package/dist/print.cjs

@@ -1,6 +1,6 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
 const node_process = require_rolldown_runtime.__toESM(require("node:process"));
-const __optique_core_message = require_rolldown_runtime.__toESM(require("@optique/core/message"));
+const __optique_core_internal_terminal = require_rolldown_runtime.__toESM(require("@optique/core/internal/terminal"));
 
 //#region src/print.ts
 /**
@@ -29,6 +29,7 @@ const __optique_core_message = require_rolldown_runtime.__toESM(require("@optiqu
 */
 function print(message, options = {}) {
 	const printer = createPrinter({
+		...options,
 		stream: options.stream ?? "stdout",
 		colors: options.colors,
 		quotes: options.quotes,
@@ -40,17 +41,27 @@ function printError(message, options = {}) {
 	const stream = options.stream ?? "stderr";
 	const output = node_process.default[stream];
 	const quotes = options.quotes ?? !output.isTTY;
-	const printer = createPrinter({
-		stream,
-		colors: options.colors,
+	const colors = options.colors ?? output.isTTY;
+	const useColors = typeof colors === "object" ? true : colors;
+	const maxWidth = options.maxWidth ?? output.columns;
+	const occupied = options.initialWidth ?? 0;
+	if (!Number.isFinite(occupied) || !Number.isInteger(occupied)) throw new TypeError("Initial width must be a finite integer.");
+	if (occupied < 0) throw new RangeError("Initial width must be nonnegative.");
+	let prefix = (0, __optique_core_internal_terminal.renderTerminalTerm)({
+		type: "errorLabel",
+		label: "Error:"
+	}, options.theme, useColors) + " ";
+	if (maxWidth != null && occupied > 0 && occupied + (0, __optique_core_internal_terminal.getDisplayWidth)(prefix.split("\n")[0]) > maxWidth) prefix = "\n" + prefix;
+	const prefixLines = prefix.split("\n");
+	const initialWidth = (0, __optique_core_internal_terminal.getDisplayWidth)(prefixLines.at(-1) ?? "") + (prefixLines.length === 1 ? options.initialWidth ?? 0 : 0);
+	const formatMessage = (0, __optique_core_internal_terminal.resolveMessageFormatter)(options);
+	const formatted = formatMessage(message, {
+		colors,
 		quotes,
-		maxWidth: options.maxWidth
+		maxWidth,
+		initialWidth
 	});
-	const errorMessage = [{
-		type: "text",
-		text: "Error: "
-	}, ...message];
-	printer(errorMessage);
+	output.write(prefix + formatted + "\n");
 	if (options.exitCode != null) node_process.default.exit(options.exitCode);
 }
 /**
@@ -83,13 +94,15 @@ function printError(message, options = {}) {
 function createPrinter(options = {}) {
 	const stream = options.stream ?? "stdout";
 	const output = node_process.default[stream];
+	const formatMessage = (0, __optique_core_internal_terminal.resolveMessageFormatter)(options);
 	const formatOptions = {
+		initialWidth: options.initialWidth,
 		colors: options.colors ?? output.isTTY,
 		quotes: options.quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	};
 	return (message) => {
-		const formatted = (0, __optique_core_message.formatMessage)(message, formatOptions);
+		const formatted = formatMessage(message, formatOptions);
 		if (stream === "stderr") node_process.default.stderr.write(formatted + "\n");
 		else node_process.default.stdout.write(formatted + "\n");
 	};

package/dist/print.d.cts

@@ -1,4 +1,5 @@
-import { Message, MessageFormatOptions } from "@optique/core/message";
+import { Message, MessageFormatOptions, MessageFormatter } from "@optique/core/message";
+import { TerminalTheme } from "@optique/core/terminal";
 
 //#region src/print.d.ts
 
@@ -7,6 +8,10 @@ import { Message, MessageFormatOptions } from "@optique/core/message";
  * @since 0.3.0
  */
 interface PrintOptions extends MessageFormatOptions {
+  /** Custom message renderer, taking precedence over theme for messages. @since 1.3.0 */
+  readonly messageFormatter?: MessageFormatter;
+  /** Semantic terminal theme. @since 1.3.0 */
+  readonly theme?: TerminalTheme;
   /**
    * The output stream to write to.
    * @default `"stdout"`
@@ -34,6 +39,10 @@ interface PrintErrorOptions extends PrintOptions {
  * @since 0.3.0
  */
 interface PrinterOptions extends MessageFormatOptions {
+  /** Custom message renderer, taking precedence over theme for messages. @since 1.3.0 */
+  readonly messageFormatter?: MessageFormatter;
+  /** Semantic terminal theme. @since 1.3.0 */
+  readonly theme?: TerminalTheme;
   /**
    * The output stream to write to.
    * @default `"stdout"`
@@ -80,6 +89,8 @@ 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 {TypeError} If initialWidth is not a finite integer.
+ * @throws {RangeError} If initialWidth is negative or a theme color is invalid.
  *
  * @example
  * ```typescript

package/dist/print.d.ts

@@ -1,4 +1,5 @@
-import { Message, MessageFormatOptions } from "@optique/core/message";
+import { Message, MessageFormatOptions, MessageFormatter } from "@optique/core/message";
+import { TerminalTheme } from "@optique/core/terminal";
 
 //#region src/print.d.ts
 
@@ -7,6 +8,10 @@ import { Message, MessageFormatOptions } from "@optique/core/message";
  * @since 0.3.0
  */
 interface PrintOptions extends MessageFormatOptions {
+  /** Custom message renderer, taking precedence over theme for messages. @since 1.3.0 */
+  readonly messageFormatter?: MessageFormatter;
+  /** Semantic terminal theme. @since 1.3.0 */
+  readonly theme?: TerminalTheme;
   /**
    * The output stream to write to.
    * @default `"stdout"`
@@ -34,6 +39,10 @@ interface PrintErrorOptions extends PrintOptions {
  * @since 0.3.0
  */
 interface PrinterOptions extends MessageFormatOptions {
+  /** Custom message renderer, taking precedence over theme for messages. @since 1.3.0 */
+  readonly messageFormatter?: MessageFormatter;
+  /** Semantic terminal theme. @since 1.3.0 */
+  readonly theme?: TerminalTheme;
   /**
    * The output stream to write to.
    * @default `"stdout"`
@@ -80,6 +89,8 @@ 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 {TypeError} If initialWidth is not a finite integer.
+ * @throws {RangeError} If initialWidth is negative or a theme color is invalid.
  *
  * @example
  * ```typescript

package/dist/print.js

@@ -1,5 +1,5 @@
 import process from "node:process";
-import { formatMessage } from "@optique/core/message";
+import { getDisplayWidth, renderTerminalTerm, resolveMessageFormatter } from "@optique/core/internal/terminal";
 
 //#region src/print.ts
 /**
@@ -26,30 +26,41 @@ import { formatMessage } from "@optique/core/message";
 *
 * @since 0.3.0
 */
-function print(message$1, options = {}) {
+function print(message, options = {}) {
 	const printer = createPrinter({
+		...options,
 		stream: options.stream ?? "stdout",
 		colors: options.colors,
 		quotes: options.quotes,
 		maxWidth: options.maxWidth
 	});
-	printer(message$1);
+	printer(message);
 }
-function printError(message$1, options = {}) {
+function printError(message, options = {}) {
 	const stream = options.stream ?? "stderr";
 	const output = process[stream];
 	const quotes = options.quotes ?? !output.isTTY;
-	const printer = createPrinter({
-		stream,
-		colors: options.colors,
+	const colors = options.colors ?? output.isTTY;
+	const useColors = typeof colors === "object" ? true : colors;
+	const maxWidth = options.maxWidth ?? output.columns;
+	const occupied = options.initialWidth ?? 0;
+	if (!Number.isFinite(occupied) || !Number.isInteger(occupied)) throw new TypeError("Initial width must be a finite integer.");
+	if (occupied < 0) throw new RangeError("Initial width must be nonnegative.");
+	let prefix = renderTerminalTerm({
+		type: "errorLabel",
+		label: "Error:"
+	}, options.theme, useColors) + " ";
+	if (maxWidth != null && occupied > 0 && occupied + getDisplayWidth(prefix.split("\n")[0]) > maxWidth) prefix = "\n" + prefix;
+	const prefixLines = prefix.split("\n");
+	const initialWidth = getDisplayWidth(prefixLines.at(-1) ?? "") + (prefixLines.length === 1 ? options.initialWidth ?? 0 : 0);
+	const formatMessage = resolveMessageFormatter(options);
+	const formatted = formatMessage(message, {
+		colors,
 		quotes,
-		maxWidth: options.maxWidth
+		maxWidth,
+		initialWidth
 	});
-	const errorMessage = [{
-		type: "text",
-		text: "Error: "
-	}, ...message$1];
-	printer(errorMessage);
+	output.write(prefix + formatted + "\n");
 	if (options.exitCode != null) process.exit(options.exitCode);
 }
 /**
@@ -82,13 +93,15 @@ function printError(message$1, options = {}) {
 function createPrinter(options = {}) {
 	const stream = options.stream ?? "stdout";
 	const output = process[stream];
+	const formatMessage = resolveMessageFormatter(options);
 	const formatOptions = {
+		initialWidth: options.initialWidth,
 		colors: options.colors ?? output.isTTY,
 		quotes: options.quotes,
 		maxWidth: options.maxWidth ?? output.columns
 	};
-	return (message$1) => {
-		const formatted = formatMessage(message$1, formatOptions);
+	return (message) => {
+		const formatted = formatMessage(message, formatOptions);
 		if (stream === "stderr") process.stderr.write(formatted + "\n");
 		else process.stdout.write(formatted + "\n");
 	};

package/dist/run.cjs

@@ -152,6 +152,8 @@ function buildCoreOptions(options, programMetadata) {
 	const coreOptions = {
 		stderr,
 		stdout,
+		messageFormatter: options.messageFormatter,
+		theme: options.theme,
 		colors,
 		maxWidth,
 		termWidth,

package/dist/run.d.cts

@@ -1,10 +1,11 @@
+import { Message, MessageFormatter } from "@optique/core/message";
+import { TerminalTheme } from "@optique/core/terminal";
 import { ShellCompletion } from "@optique/core/completion";
 import { SourceContext } from "@optique/core/context";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, OptionSubConfig } from "@optique/core/facade";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
 import { Program } from "@optique/core/program";
 import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
-import { Message } from "@optique/core/message";
 import { Usage } from "@optique/core/usage";
 
 //#region src/run.d.ts
@@ -13,6 +14,10 @@ import { Usage } from "@optique/core/usage";
  * Configuration options for the {@link run} function.
  */
 interface RunOptions {
+  /** Custom message renderer, taking precedence over theme for messages. @since 1.3.0 */
+  readonly messageFormatter?: MessageFormatter;
+  /** Semantic terminal theme. @since 1.3.0 */
+  readonly theme?: TerminalTheme;
   /**
    * The name of the program to display in usage and help messages.
    *

package/dist/run.d.ts

@@ -1,5 +1,6 @@
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, OptionSubConfig } from "@optique/core/facade";
-import { Message } from "@optique/core/message";
+import { Message, MessageFormatter } from "@optique/core/message";
+import { TerminalTheme } from "@optique/core/terminal";
 import { ShellCompletion } from "@optique/core/completion";
 import { SourceContext } from "@optique/core/context";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
@@ -13,6 +14,10 @@ import { Usage } from "@optique/core/usage";
  * Configuration options for the {@link run} function.
  */
 interface RunOptions {
+  /** Custom message renderer, taking precedence over theme for messages. @since 1.3.0 */
+  readonly messageFormatter?: MessageFormatter;
+  /** Semantic terminal theme. @since 1.3.0 */
+  readonly theme?: TerminalTheme;
   /**
    * The name of the program to display in usage and help messages.
    *

package/dist/run.js

@@ -151,6 +151,8 @@ function buildCoreOptions(options, programMetadata) {
 	const coreOptions = {
 		stderr,
 		stdout,
+		messageFormatter: options.messageFormatter,
+		theme: options.theme,
 		colors,
 		maxWidth,
 		termWidth,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.3.0-dev.2529",
+  "version": "1.3.0-dev.2530",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -76,11 +76,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.3.0-dev.2529+48afcdff"
+    "@optique/core": "1.3.0-dev.2530+970f0e16"
   },
   "devDependencies": {
-    "@optique/config": "1.3.0-dev.2529+48afcdff",
-    "@optique/env": "1.3.0-dev.2529+48afcdff",
+    "@optique/config": "1.3.0-dev.2530+970f0e16",
+    "@optique/env": "1.3.0-dev.2530+970f0e16",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",