@optique/run 1.3.0-dev.2559 → 1.3.0-dev.2563

package/dist/run.cjs

@@ -1,4 +1,5 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_terminal = require('./terminal.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"));
@@ -72,8 +73,8 @@ function buildCoreOptions(options, programMetadata) {
 		node_process.default.stderr.write(`${line}\n`);
 	});
 	const onExit = options.onExit ?? ((exitCode) => node_process.default.exit(exitCode));
-	const colors = options.colors ?? node_process.default.stdout.isTTY;
-	const maxWidth = options.maxWidth ?? node_process.default.stdout.columns;
+	const colors = options.colors ?? require_terminal.detectColorSupport(node_process.default.stdout, require_terminal.readEnvironmentVariable);
+	const maxWidth = options.maxWidth ?? require_terminal.detectTerminalWidth(node_process.default.stdout, require_terminal.readEnvironmentVariable);
 	const termWidth = options.termWidth;
 	const showDefault = options.showDefault;
 	const showChoices = options.showChoices;

package/dist/run.d.cts

@@ -53,14 +53,22 @@ interface RunOptions {
   /**
    * Whether to enable colored output in help and error messages.
    *
-   * @default `process.stdout.isTTY` (auto-detect based on terminal)
+   * Explicit values override environment variables and terminal detection.
+   * A nonempty `FORCE_COLOR` enables colors (including `0`); otherwise a
+   * nonempty `NO_COLOR` or any `NODE_DISABLE_COLORS` disables them.
+   * Inaccessible environment variables are ignored.
+   *
+   * @default Environment preferences, then `process.stdout.isTTY`
    */
   readonly colors?: boolean;
   /**
    * Maximum width for output formatting. Text will be wrapped to fit within
-   * this width. If not specified, uses the terminal width.
+   * this width. If not specified, uses a positive finite integer from the
+   * terminal width, then a positive decimal integer from `COLUMNS`. Invalid
+   * or inaccessible detected values are ignored; explicit values retain the
+   * formatter's validation.
    *
-   * @default `process.stdout.columns` (auto-detect terminal width)
+   * @default Valid `process.stdout.columns`, then `COLUMNS`, or no wrapping
    */
   readonly maxWidth?: number;
   /**

package/dist/run.d.ts

@@ -53,14 +53,22 @@ interface RunOptions {
   /**
    * Whether to enable colored output in help and error messages.
    *
-   * @default `process.stdout.isTTY` (auto-detect based on terminal)
+   * Explicit values override environment variables and terminal detection.
+   * A nonempty `FORCE_COLOR` enables colors (including `0`); otherwise a
+   * nonempty `NO_COLOR` or any `NODE_DISABLE_COLORS` disables them.
+   * Inaccessible environment variables are ignored.
+   *
+   * @default Environment preferences, then `process.stdout.isTTY`
    */
   readonly colors?: boolean;
   /**
    * Maximum width for output formatting. Text will be wrapped to fit within
-   * this width. If not specified, uses the terminal width.
+   * this width. If not specified, uses a positive finite integer from the
+   * terminal width, then a positive decimal integer from `COLUMNS`. Invalid
+   * or inaccessible detected values are ignored; explicit values retain the
+   * formatter's validation.
    *
-   * @default `process.stdout.columns` (auto-detect terminal width)
+   * @default Valid `process.stdout.columns`, then `COLUMNS`, or no wrapping
    */
   readonly maxWidth?: number;
   /**

package/dist/run.js

@@ -1,3 +1,4 @@
+import { detectColorSupport, detectTerminalWidth, readEnvironmentVariable } from "./terminal.js";
 import { runParser, runWith, runWithSync } from "@optique/core/facade";
 import path from "node:path";
 import process from "node:process";
@@ -71,8 +72,8 @@ function buildCoreOptions(options, programMetadata) {
 		process.stderr.write(`${line}\n`);
 	});
 	const onExit = options.onExit ?? ((exitCode) => process.exit(exitCode));
-	const colors = options.colors ?? process.stdout.isTTY;
-	const maxWidth = options.maxWidth ?? process.stdout.columns;
+	const colors = options.colors ?? detectColorSupport(process.stdout, readEnvironmentVariable);
+	const maxWidth = options.maxWidth ?? detectTerminalWidth(process.stdout, readEnvironmentVariable);
 	const termWidth = options.termWidth;
 	const showDefault = options.showDefault;
 	const showChoices = options.showChoices;

package/dist/terminal.cjs

@@ -0,0 +1,59 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_process = require_rolldown_runtime.__toESM(require("node:process"));
+
+//#region src/terminal.ts
+/**
+* Resolves automatic color settings without changing the supplied environment.
+* @param stream The output stream's TTY status.
+* @param readEnv Reads one environment variable at a time.
+* @returns The color preference, preserving an unspecified TTY fallback.
+* @internal
+*/
+function detectColorSupport(stream, readEnv) {
+	const forceColor = readEnv("FORCE_COLOR");
+	if (forceColor != null && forceColor !== "") return true;
+	const noColor = readEnv("NO_COLOR");
+	if (noColor != null && noColor !== "") return false;
+	if (readEnv("NODE_DISABLE_COLORS") != null) return false;
+	return stream.isTTY;
+}
+/**
+* Resolves a usable reported width, leaving unknown widths unwrapped.
+* @param stream The output stream's reported width.
+* @param readEnv Reads COLUMNS if the stream has no valid width.
+* @returns A positive finite integer, or undefined when neither source is valid.
+* @internal
+*/
+function detectTerminalWidth(stream, readEnv) {
+	const columns = stream.columns;
+	if (columns != null && Number.isInteger(columns) && columns > 0) return columns;
+	const value = readEnv("COLUMNS");
+	if (value == null || value === "" || /[^0-9]/u.test(value)) return void 0;
+	const width = Number(value);
+	return Number.isInteger(width) && width > 0 ? width : void 0;
+}
+/**
+* Reads an optional terminal setting without requesting runtime permissions.
+* @param name The environment variable to read.
+* @returns Its value, or undefined when absent or inaccessible.
+* @internal
+*/
+function readEnvironmentVariable(name) {
+	try {
+		if (name === "NODE_DISABLE_COLORS" || name === "COLUMNS") {
+			const deno = globalThis.Deno;
+			if (deno != null && deno.permissions?.querySync?.({
+				name: "env",
+				variable: name
+			}).state !== "granted") return void 0;
+		}
+		return node_process.default.env[name];
+	} catch {
+		return void 0;
+	}
+}
+
+//#endregion
+exports.detectColorSupport = detectColorSupport;
+exports.detectTerminalWidth = detectTerminalWidth;
+exports.readEnvironmentVariable = readEnvironmentVariable;

package/dist/terminal.js

@@ -0,0 +1,56 @@
+import process from "node:process";
+
+//#region src/terminal.ts
+/**
+* Resolves automatic color settings without changing the supplied environment.
+* @param stream The output stream's TTY status.
+* @param readEnv Reads one environment variable at a time.
+* @returns The color preference, preserving an unspecified TTY fallback.
+* @internal
+*/
+function detectColorSupport(stream, readEnv) {
+	const forceColor = readEnv("FORCE_COLOR");
+	if (forceColor != null && forceColor !== "") return true;
+	const noColor = readEnv("NO_COLOR");
+	if (noColor != null && noColor !== "") return false;
+	if (readEnv("NODE_DISABLE_COLORS") != null) return false;
+	return stream.isTTY;
+}
+/**
+* Resolves a usable reported width, leaving unknown widths unwrapped.
+* @param stream The output stream's reported width.
+* @param readEnv Reads COLUMNS if the stream has no valid width.
+* @returns A positive finite integer, or undefined when neither source is valid.
+* @internal
+*/
+function detectTerminalWidth(stream, readEnv) {
+	const columns = stream.columns;
+	if (columns != null && Number.isInteger(columns) && columns > 0) return columns;
+	const value = readEnv("COLUMNS");
+	if (value == null || value === "" || /[^0-9]/u.test(value)) return void 0;
+	const width = Number(value);
+	return Number.isInteger(width) && width > 0 ? width : void 0;
+}
+/**
+* Reads an optional terminal setting without requesting runtime permissions.
+* @param name The environment variable to read.
+* @returns Its value, or undefined when absent or inaccessible.
+* @internal
+*/
+function readEnvironmentVariable(name) {
+	try {
+		if (name === "NODE_DISABLE_COLORS" || name === "COLUMNS") {
+			const deno = globalThis.Deno;
+			if (deno != null && deno.permissions?.querySync?.({
+				name: "env",
+				variable: name
+			}).state !== "granted") return void 0;
+		}
+		return process.env[name];
+	} catch {
+		return void 0;
+	}
+}
+
+//#endregion
+export { detectColorSupport, detectTerminalWidth, readEnvironmentVariable };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "1.3.0-dev.2559",
+  "version": "1.3.0-dev.2563",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -76,11 +76,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.3.0-dev.2559+02079a47"
+    "@optique/core": "1.3.0-dev.2563+56de9f1b"
   },
   "devDependencies": {
-    "@optique/config": "1.3.0-dev.2559+02079a47",
-    "@optique/env": "1.3.0-dev.2559+02079a47",
+    "@optique/config": "1.3.0-dev.2563+56de9f1b",
+    "@optique/env": "1.3.0-dev.2563+56de9f1b",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",