@flowscripter/dynamic-cli-framework 2.0.0 → 2.1.0

package/README.md

@@ -40,6 +40,9 @@
   configuration management, and user input prompting.
 - Graceful signal handling (SIGINT/SIGTERM) with shutdown hooks, cooperative
   cancellation for long-running commands, and triple-interrupt force exit.
+- Graceful degradation when piped or run non-interactively: color,
+  hyperlinks, prompting, spinners/progress bars and image rendering are
+  automatically disabled based on which of `stdin`/`stdout`/`stderr` are TTYs.
 - Core (but optional) support for dynamic discovery and installation of commands
   and services using
   [dynamic-plugin-framework](https://github.com/flowscripter/dynamic-plugin-framework)

package/dist/src/cli/BaseCLI.d.ts

@@ -25,6 +25,12 @@ import type BaseCLIFeatureOptions from "./BaseCLIFeatureOptions.ts";
  *
  * * {@link ImagePrinterServiceProvider}
  *
+ * `keyReader` is optional. If omitted, or if the stderr {@link Terminal} is not a TTY, prompting is
+ * unavailable: {@link PrompterServiceProvider} (and {@link ArgumentPrompterServiceProvider}, if
+ * enabled) are simply not registered. If `promptingEnabled` is `true` in that situation, {@link run}
+ * throws rather than failing later inside a prompt. Similarly {@link ImagePrinterServiceProvider} is
+ * only registered if the stdout {@link Terminal} is a TTY.
+ *
  * By default the following commands are added:
  *
  * * {@link SingleCommandCliHelpSubCommand} or {@link MultiCommandCliHelpSubCommand}
@@ -34,7 +40,7 @@ import type BaseCLIFeatureOptions from "./BaseCLIFeatureOptions.ts";
  */
 export default class BaseCLI implements CLI {
     #private;
-    constructor(cliConfig: CLIConfig, stdoutWritableStream: WritableStream, stderrWritableStream: WritableStream, stdoutIsColor: boolean, stderrIsColor: boolean, stdoutTerminal: Terminal, stderrTerminal: Terminal, styler: Styler, keyReader: KeyReader, options?: BaseCLIFeatureOptions);
+    constructor(cliConfig: CLIConfig, stdoutWritableStream: WritableStream, stderrWritableStream: WritableStream, stdoutIsColor: boolean, stderrIsColor: boolean, stdoutTerminal: Terminal, stderrTerminal: Terminal, styler: Styler, keyReader: KeyReader | undefined, options?: BaseCLIFeatureOptions);
     /**
      * Add a {@link ServiceProvider} to the CLI's {@link ServiceProviderRegistry}.
      *

package/dist/src/cli/BaseCLI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA4BzE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAYpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,YAAW,GAAG;;gBAavC,SAAS,EAAE,SAAS,EACpB,oBAAoB,EAAE,cAAc,EACpC,oBAAoB,EAAE,cAAc,EACpC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,QAAQ,EACxB,cAAc,EAAE,QAAQ,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,qBAAqB;IA2DjC;;;;;;;OAOG;IACI,kBAAkB,CAAC,eAAe,EAAE,eAAe;IAI1D;;;;;;;;OAQG;IACI,UAAU,CAAC,OAAO,EAAE,OAAO;IAU5B,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;CAuJ3D"}
+{"version":3,"file":"BaseCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA4BzE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAYpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,YAAW,GAAG;;gBAavC,SAAS,EAAE,SAAS,EACpB,oBAAoB,EAAE,cAAc,EACpC,oBAAoB,EAAE,cAAc,EACpC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,QAAQ,EACxB,cAAc,EAAE,QAAQ,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE,qBAAqB;IA2DjC;;;;;;;OAOG;IACI,kBAAkB,CAAC,eAAe,EAAE,eAAe;IAI1D;;;;;;;;OAQG;IACI,UAAU,CAAC,OAAO,EAAE,OAAO;IAU5B,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;CAmL3D"}

package/dist/src/cli/BaseCLI.js

@@ -43,6 +43,12 @@ const logger = getLogger("BaseCLI");
  *
  * * {@link ImagePrinterServiceProvider}
  *
+ * `keyReader` is optional. If omitted, or if the stderr {@link Terminal} is not a TTY, prompting is
+ * unavailable: {@link PrompterServiceProvider} (and {@link ArgumentPrompterServiceProvider}, if
+ * enabled) are simply not registered. If `promptingEnabled` is `true` in that situation, {@link run}
+ * throws rather than failing later inside a prompt. Similarly {@link ImagePrinterServiceProvider} is
+ * only registered if the stdout {@link Terminal} is a TTY.
+ *
  * By default the following commands are added:
  *
  * * {@link SingleCommandCliHelpSubCommand} or {@link MultiCommandCliHelpSubCommand}
@@ -145,15 +151,35 @@ export default class BaseCLI {
         this.addServiceProvider(new ShutdownServiceProvider(100));
         this.addServiceProvider(new PrinterServiceProvider(80, this.#printerService));
         this.addServiceProvider(new TableGeneratorServiceProvider(70));
-        const prompterService = new DefaultPrompterService(DEFAULT_PROMPTER_CONFIG, this.#stderrTerminal, this.#keyReader, this.#printerService);
-        prompterService.promptEnabled = this.#options.promptingEnabled;
-        this.addServiceProvider(new PrompterServiceProvider(75, prompterService));
+        const canPrompt = this.#keyReader !== undefined && this.#stderrTerminal.isTty();
+        if (this.#options.promptingEnabled && !canPrompt) {
+            throw new Error("promptingEnabled requires a keyReader and a TTY stderr terminal");
+        }
+        let prompterService;
+        if (canPrompt) {
+            prompterService = new DefaultPrompterService(DEFAULT_PROMPTER_CONFIG, this.#stderrTerminal, this.#keyReader, this.#printerService);
+            prompterService.promptEnabled = this.#options.promptingEnabled;
+            this.addServiceProvider(new PrompterServiceProvider(75, prompterService));
+        }
+        else {
+            logger.debug(() => `Skipping PrompterServiceProvider: keyReader present: ${this.#keyReader !== undefined}, stderr isTty: ${this.#stderrTerminal.isTty()}`);
+        }
         if (this.#options.argumentPrompterServiceEnabled) {
-            const argumentPrompterService = new DefaultArgumentPrompterService(prompterService);
-            this.addServiceProvider(new ArgumentPrompterServiceProvider(65, argumentPrompterService));
+            if (prompterService !== undefined) {
+                const argumentPrompterService = new DefaultArgumentPrompterService(prompterService);
+                this.addServiceProvider(new ArgumentPrompterServiceProvider(65, argumentPrompterService));
+            }
+            else {
+                logger.debug("Skipping ArgumentPrompterServiceProvider: argumentPrompterServiceEnabled is true but prompting is unavailable");
+            }
         }
         if (this.#options.imagePrinterServiceEnabled) {
-            this.addServiceProvider(new ImagePrinterServiceProvider(55, this.#stdoutTerminal));
+            if (this.#stdoutTerminal.isTty()) {
+                this.addServiceProvider(new ImagePrinterServiceProvider(55, this.#stdoutTerminal));
+            }
+            else {
+                logger.debug("Skipping ImagePrinterServiceProvider: imagePrinterServiceEnabled is true but stdout is not a TTY");
+            }
         }
         if (this.#options.completionServiceEnabled) {
             const completionService = new DefaultCompletionService();

package/dist/src/cli/DefaultRuntimeCLI.d.ts

@@ -4,6 +4,10 @@ import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
 import type BaseCLIFeatureOptions from "./BaseCLIFeatureOptions.ts";
 /**
  * Default Bun implementation of a {@link CLI} using `process.stdout`, `process.stderr` and `process.argv`.
+ *
+ * Degrades gracefully when `stdin`, `stdout` or `stderr` are not TTYs (e.g. piped or redirected):
+ * color and hyperlinks are disabled, prompting is disabled, and non-TTY streams are wrapped in a
+ * {@link NonTtyTerminal} rather than the usual {@link TtyTerminal}.
  */
 export default class DefaultRuntimeCLI extends BaseCLI {
     constructor(cliConfig: CLIConfig, options?: BaseCLIFeatureOptions);

package/dist/src/cli/DefaultRuntimeCLI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultRuntimeCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/DefaultRuntimeCLI.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAQpE;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,OAAO;gBACxC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,qBAAqB;IAkBlD,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC;CAIzC"}
+{"version":3,"file":"DefaultRuntimeCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/DefaultRuntimeCLI.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAYpE;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAkB,SAAQ,OAAO;gBACxC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,qBAAqB;IAsDlD,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC;CAIzC"}

package/dist/src/cli/DefaultRuntimeCLI.js

@@ -2,16 +2,44 @@ import process from "node:process";
 import BaseCLI from "./BaseCLI.js";
 import { Writable } from "node:stream";
 import TtyTerminal from "../terminal/TtyTerminal.js";
+import NonTtyTerminal from "../terminal/NonTtyTerminal.js";
 import TtyKeyReader from "../terminal/TtyKeyReader.js";
 import TtyStyler from "../terminal/TtyStyler.js";
 import supportsColor from "supports-color";
 import supportsHyperlinks from "../terminal/supportsHyperlinks.js";
+import getLogger from "../util/logger.js";
+const logger = getLogger("DefaultRuntimeCLI");
 /**
  * Default Bun implementation of a {@link CLI} using `process.stdout`, `process.stderr` and `process.argv`.
+ *
+ * Degrades gracefully when `stdin`, `stdout` or `stderr` are not TTYs (e.g. piped or redirected):
+ * color and hyperlinks are disabled, prompting is disabled, and non-TTY streams are wrapped in a
+ * {@link NonTtyTerminal} rather than the usual {@link TtyTerminal}.
  */
 export default class DefaultRuntimeCLI extends BaseCLI {
     constructor(cliConfig, options) {
-        super(cliConfig, Writable.toWeb(process.stdout), Writable.toWeb(process.stderr), supportsColor.stdout !== false, supportsColor.stderr !== false, new TtyTerminal(process.stdout), new TtyTerminal(process.stderr), new TtyStyler(supportsColor.stderr === false ? 1 : supportsColor.stderr.level, supportsHyperlinks(process.stderr)), new TtyKeyReader(process.stdin), { promptingEnabled: process.stdin.isTTY === true, ...options });
+        const stdinIsTty = process.stdin.isTTY === true;
+        const stdoutIsTty = process.stdout.isTTY === true;
+        const stderrIsTty = process.stderr.isTTY === true;
+        logger.debug(() => `stdin isTTY: ${stdinIsTty}, stdout isTTY: ${stdoutIsTty}, stderr isTTY: ${stderrIsTty}`);
+        const stdoutTerminal = stdoutIsTty
+            ? new TtyTerminal(process.stdout)
+            : new NonTtyTerminal(process.stdout);
+        const stderrTerminal = stderrIsTty
+            ? new TtyTerminal(process.stderr)
+            : new NonTtyTerminal(process.stderr);
+        logger.debug(() => `stdout terminal: ${stdoutIsTty ? "TtyTerminal" : "NonTtyTerminal"}, stderr terminal: ${stderrIsTty ? "TtyTerminal" : "NonTtyTerminal"}`);
+        const colorLevel = stderrIsTty
+            ? supportsColor.stderr === false
+                ? 1
+                : supportsColor.stderr.level
+            : 0;
+        logger.debug(() => `color level: ${colorLevel}`);
+        const keyReader = stdinIsTty ? new TtyKeyReader(process.stdin) : undefined;
+        logger.debug(() => `keyReader constructed: ${keyReader !== undefined}`);
+        const promptingEnabled = stdinIsTty && stderrIsTty;
+        logger.debug(() => `promptingEnabled default: ${promptingEnabled}`);
+        super(cliConfig, Writable.toWeb(process.stdout), Writable.toWeb(process.stderr), supportsColor.stdout !== false, supportsColor.stderr !== false, stdoutTerminal, stderrTerminal, new TtyStyler(colorLevel, supportsHyperlinks(process.stderr)), keyReader, { promptingEnabled, ...options });
     }
     async run() {
         const runResult = await super.run(process.argv.slice(2));

package/dist/src/service/printer/DefaultPrinterService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultPrinterService.d.ts","sourceRoot":"","sources":["../../../../src/service/printer/DefaultPrinterService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DefaultPrinterService.d.ts","sourceRoot":"","sources":["../../../../src/service/printer/DefaultPrinterService.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EACL,KAAK,IAAI,EACT,KAAK,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,4BAA4B,CAAC;AAGvD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,MAAM,MAAM,0BAA0B,CAAC;AAEnD,MAAM,CAAC,OAAO,OAAO,qBAAsB,YAAW,cAAc;;IAClE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;gBAyCtC,oBAAoB,EAAE,cAAc,EACpC,oBAAoB,EAAE,cAAc,EACpC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,QAAQ,EACxB,cAAc,EAAE,QAAQ,EACxB,MAAM,EAAE,MAAM;IAgBhB,IAAI,YAAY,CAAC,OAAO,EAAE,OAAO,EAQhC;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,IAAI,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAErC;IAED,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAEM,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAI5C,aAAa,IAAI,MAAM;IAIvB,aAAa,IAAI,MAAM;IAI9B,IAAI,QAAQ,CAAC,UAAU,EAAE,OAAO,EAa/B;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAEM,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIhC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIlC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAInC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIjC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI/B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI/B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI/B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI5B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIhC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI/B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAe9B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM;IAIzD,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI1C,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI5C,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI7C,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI3C,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIzC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIzC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAItC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI1C,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIzC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIvC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIvC,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIxC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM;IAI7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBxD,UAAU,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI;IAO5C,QAAQ,IAAI,IAAI;IAIhB,SAAS,IAAI,IAAI;IAQjB,OAAO,IAAI,IAAI;IAOT,WAAW,CAAC,oBAAoB,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpD,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3C,QAAQ,IAAI,KAAK;IAIX,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAclE,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,eAAe,CAC1B,KAAK,EAAE,MAAM,EACb,OAAO,SAAK,EACZ,KAAK,SAAM,EACX,OAAO,SAAI,EACX,KAAK,CAAC,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC;IAeL,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1C,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;CAMlF"}

package/dist/src/service/printer/DefaultPrinterService.js

@@ -22,16 +22,14 @@ export default class DefaultPrinterService {
     #quote;
     #markedLineCount;
     #markEndedAt;
-    #markedTerminal;
     #countLines(message) {
         return message.split("\n").length - (message.endsWith("\n") ? 1 : 0);
     }
-    #recordMarkedWrite(terminal, message) {
+    #recordMarkedWrite(message) {
         if (this.#markedLineCount === undefined) {
             return;
         }
         this.#markedLineCount += this.#countLines(message);
-        this.#markedTerminal = terminal;
     }
     async #log(level, message, icon) {
         if (this.#threshold > level) {
@@ -40,7 +38,7 @@ export default class DefaultPrinterService {
         await this.#spinner.pause();
         await this.#progress.pause();
         const composed = `${icon !== undefined ? `${this.#iconDefinitions[icon]} ` : ""}${message}`;
-        this.#recordMarkedWrite(this.#stderrTerminal, composed);
+        this.#recordMarkedWrite(composed);
         await this.#stderrTerminal.write(this.#quote.prefixLines(composed));
         this.#spinner.resume();
         this.#progress.resume();
@@ -214,8 +212,7 @@ export default class DefaultPrinterService {
         const writer = this.stdoutWritable.getWriter();
         const colorMessage = this.#stdoutIsColor ? this.primary(message) : message;
         const composed = `${icon !== undefined ? `${this.#iconDefinitions[icon]} ` : ""}${colorMessage}`;
-        this.#recordMarkedWrite(this.#stdoutTerminal, composed);
-        const encoded = this.#encoder.encode(this.#quote.prefixLines(composed));
+        const encoded = this.#encoder.encode(composed);
         await writer.ready;
         await writer.write(encoded);
         writer.releaseLock();
@@ -248,16 +245,18 @@ export default class DefaultPrinterService {
         if (this.#markedLineCount === undefined || this.#markEndedAt === undefined) {
             throw new Error("clearMarked() called without a preceding endMark()");
         }
+        if (!this.#stderrTerminal.isTty()) {
+            this.#markedLineCount = undefined;
+            this.#markEndedAt = undefined;
+            return;
+        }
         const remaining = minimumDisplayTimeMs - (Date.now() - this.#markEndedAt);
         if (remaining > 0) {
             await new Promise((resolve) => setTimeout(resolve, remaining));
         }
-        if (this.#markedTerminal !== undefined) {
-            await this.#markedTerminal.clearUpLines(this.#markedLineCount);
-        }
+        await this.#stderrTerminal.clearUpLines(this.#markedLineCount);
         this.#markedLineCount = undefined;
         this.#markEndedAt = undefined;
-        this.#markedTerminal = undefined;
     }
     async setLevel(level) {
         if (this.#threshold > Level.INFO) {
@@ -270,6 +269,9 @@ export default class DefaultPrinterService {
         return this.#threshold;
     }
     async showSpinner(message, style) {
+        if (!this.#stderrTerminal.isTty()) {
+            return;
+        }
         await this.#progress.hideAll();
         if (this.#threshold > Level.INFO) {
             return;
@@ -283,6 +285,9 @@ export default class DefaultPrinterService {
         await this.#spinner.hide();
     }
     async showProgressBar(units, message = "", total = 100, current = 0, style) {
+        if (!this.#stderrTerminal.isTty()) {
+            return -1;
+        }
         await this.#spinner.hide();
         if (this.#threshold > Level.INFO) {
             return -1;

package/dist/src/terminal/NonTtyTerminal.d.ts

@@ -0,0 +1,14 @@
+import type Terminal from "./Terminal.ts";
+export default class NonTtyTerminal implements Terminal {
+    #private;
+    constructor(writeStream: NodeJS.WritableStream);
+    write(text: string): Promise<void>;
+    columns(): number;
+    rows(): number;
+    clearLine(): Promise<void>;
+    clearUpLines(_count: number): Promise<void>;
+    hideCursor(): Promise<void>;
+    showCursor(): Promise<void>;
+    isTty(): boolean;
+}
+//# sourceMappingURL=NonTtyTerminal.d.ts.map

package/dist/src/terminal/NonTtyTerminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NonTtyTerminal.d.ts","sourceRoot":"","sources":["../../../src/terminal/NonTtyTerminal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAE1C,MAAM,CAAC,OAAO,OAAO,cAAe,YAAW,QAAQ;;gBAIzC,WAAW,EAAE,MAAM,CAAC,cAAc;IAQ9C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,OAAO,IAAI,MAAM;IAIjB,IAAI,IAAI,MAAM;IAId,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,KAAK,IAAI,OAAO;CAGjB"}

package/dist/src/terminal/NonTtyTerminal.js

@@ -0,0 +1,36 @@
+import { WriteStream } from "node:tty";
+export default class NonTtyTerminal {
+    #writeStream;
+    #encoder = new TextEncoder();
+    constructor(writeStream) {
+        if (writeStream.isTTY === true) {
+            throw new Error("The provided WriteStream is a TTY");
+        }
+        this.#writeStream = writeStream;
+    }
+    write(text) {
+        this.#writeStream.write(this.#encoder.encode(text));
+        return Promise.resolve();
+    }
+    columns() {
+        return 80;
+    }
+    rows() {
+        return 24;
+    }
+    clearLine() {
+        return Promise.reject(new Error("clearLine() is not supported on a non-TTY terminal"));
+    }
+    clearUpLines(_count) {
+        return Promise.reject(new Error("clearUpLines() is not supported on a non-TTY terminal"));
+    }
+    hideCursor() {
+        return Promise.reject(new Error("hideCursor() is not supported on a non-TTY terminal"));
+    }
+    showCursor() {
+        return Promise.reject(new Error("showCursor() is not supported on a non-TTY terminal"));
+    }
+    isTty() {
+        return false;
+    }
+}

package/dist/src/terminal/Terminal.d.ts

@@ -6,5 +6,6 @@ export default interface Terminal {
     write(text: string): Promise<void>;
     columns(): number;
     rows(): number;
+    isTty(): boolean;
 }
 //# sourceMappingURL=Terminal.d.ts.map

package/dist/src/terminal/Terminal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Terminal.d.ts","sourceRoot":"","sources":["../../../src/terminal/Terminal.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,WAAW,QAAQ;IAC/B,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,IAAI,MAAM,CAAC;IAClB,IAAI,IAAI,MAAM,CAAC;CAChB"}
+{"version":3,"file":"Terminal.d.ts","sourceRoot":"","sources":["../../../src/terminal/Terminal.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,WAAW,QAAQ;IAC/B,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,OAAO,IAAI,MAAM,CAAC;IAClB,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,IAAI,OAAO,CAAC;CAClB"}

package/dist/src/terminal/TtyStyler.d.ts

@@ -6,6 +6,7 @@ export default class TtyStyler implements Styler {
     /**
      * The color level in use.
      *
+     * 0 = no color
      * 1 = 16 color
      * 2 = 256 color
      * 3 = 16 million color

package/dist/src/terminal/TtyStyler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TtyStyler.d.ts","sourceRoot":"","sources":["../../../src/terminal/TtyStyler.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,MAAM,CAAC,OAAO,OAAO,SAAU,YAAW,MAAM;IAC9C,YAAY,EAAE,OAAO,CAAQ;IAC7B,iBAAiB,EAAE,OAAO,CAAC;IAE3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;OAMG;gBACS,UAAU,GAAE,MAAU,EAAE,iBAAiB,GAAE,OAAc;IAKrE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAgBnD,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAyB7D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIhC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;CAM7C"}
+{"version":3,"file":"TtyStyler.d.ts","sourceRoot":"","sources":["../../../src/terminal/TtyStyler.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,MAAM,CAAC,OAAO,OAAO,SAAU,YAAW,MAAM;IAC9C,YAAY,EAAE,OAAO,CAAQ;IAC7B,iBAAiB,EAAE,OAAO,CAAC;IAE3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;;OAOG;gBACS,UAAU,GAAE,MAAU,EAAE,iBAAiB,GAAE,OAAc;IAKrE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAgBnD,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAyB7D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAOhC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;CAM7C"}

package/dist/src/terminal/TtyStyler.js

@@ -6,6 +6,7 @@ export default class TtyStyler {
     /**
      * The color level in use.
      *
+     * 0 = no color
      * 1 = 16 color
      * 2 = 256 color
      * 3 = 16 million color
@@ -15,7 +16,7 @@ export default class TtyStyler {
         this.hyperlinksEnabled = hyperlinksEnabled;
     }
     colorText(text, colorValue) {
-        if (!this.colorEnabled) {
+        if (!this.colorEnabled || this.colorLevel === 0) {
             return text;
         }
         if (this.colorLevel === 3) {
@@ -27,7 +28,7 @@ export default class TtyStyler {
         return Bun.color(colorValue, "ansi-16") + text + FOREGROUND_COLOR_END;
     }
     backgroundColorText(text, colorValue) {
-        if (!this.colorEnabled) {
+        if (!this.colorEnabled || this.colorLevel === 0) {
             return text;
         }
         if (this.colorLevel === 3) {
@@ -44,6 +45,9 @@ export default class TtyStyler {
             BACKGROUND_COLOR_END);
     }
     italicText(text) {
+        if (!this.colorEnabled || this.colorLevel === 0) {
+            return text;
+        }
         return ITALIC_START + text + ITALIC_END;
     }
     hyperlink(text, url) {

package/dist/src/terminal/TtyTerminal.d.ts

@@ -10,5 +10,6 @@ export default class TtyTerminal implements Terminal {
     write(text: string): Promise<void>;
     columns(): number;
     rows(): number;
+    isTty(): boolean;
 }
 //# sourceMappingURL=TtyTerminal.d.ts.map

package/dist/src/terminal/TtyTerminal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TtyTerminal.d.ts","sourceRoot":"","sources":["../../../src/terminal/TtyTerminal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAI1C,MAAM,CAAC,OAAO,OAAO,WAAY,YAAW,QAAQ;;gBAItC,cAAc,EAAE,WAAW;IAcvC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAM1B,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,OAAO,IAAI,MAAM;IAQjB,IAAI,IAAI,MAAM;CAOf"}
+{"version":3,"file":"TtyTerminal.d.ts","sourceRoot":"","sources":["../../../src/terminal/TtyTerminal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAI1C,MAAM,CAAC,OAAO,OAAO,WAAY,YAAW,QAAQ;;gBAItC,cAAc,EAAE,WAAW;IAcvC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAM1B,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,OAAO,IAAI,MAAM;IAQjB,IAAI,IAAI,MAAM;IAQd,KAAK,IAAI,OAAO;CAGjB"}

package/dist/src/terminal/TtyTerminal.js

@@ -49,4 +49,7 @@ export default class TtyTerminal {
             return 24;
         }
     }
+    isTty() {
+        return true;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A framework for developing CLI applications which supports dynamic discovery and installation of new commands",
   "keywords": [
     "bun",

package/src/cli/BaseCLI.ts

@@ -70,6 +70,12 @@ const logger = getLogger("BaseCLI");
  *
  * * {@link ImagePrinterServiceProvider}
  *
+ * `keyReader` is optional. If omitted, or if the stderr {@link Terminal} is not a TTY, prompting is
+ * unavailable: {@link PrompterServiceProvider} (and {@link ArgumentPrompterServiceProvider}, if
+ * enabled) are simply not registered. If `promptingEnabled` is `true` in that situation, {@link run}
+ * throws rather than failing later inside a prompt. Similarly {@link ImagePrinterServiceProvider} is
+ * only registered if the stdout {@link Terminal} is a TTY.
+ *
  * By default the following commands are added:
  *
  * * {@link SingleCommandCliHelpSubCommand} or {@link MultiCommandCliHelpSubCommand}
@@ -80,7 +86,7 @@ const logger = getLogger("BaseCLI");
 export default class BaseCLI implements CLI {
   readonly #cliConfig: CLIConfig;
   readonly #options: Required<BaseCLIFeatureOptions>;
-  readonly #keyReader: KeyReader;
+  readonly #keyReader: KeyReader | undefined;
   readonly #stderrTerminal: Terminal;
   readonly #addedNonModifierCommands: Array<Command>;
   readonly #serviceProviderRegistry: DefaultServiceProviderRegistry;
@@ -98,7 +104,7 @@ export default class BaseCLI implements CLI {
     stdoutTerminal: Terminal,
     stderrTerminal: Terminal,
     styler: Styler,
-    keyReader: KeyReader,
+    keyReader: KeyReader | undefined,
     options?: BaseCLIFeatureOptions,
   ) {
     if (cliConfig.name.length === 0) {
@@ -210,22 +216,50 @@ export default class BaseCLI implements CLI {
     this.addServiceProvider(new PrinterServiceProvider(80, this.#printerService));
     this.addServiceProvider(new TableGeneratorServiceProvider(70));
 
-    const prompterService = new DefaultPrompterService(
-      DEFAULT_PROMPTER_CONFIG,
-      this.#stderrTerminal,
-      this.#keyReader,
-      this.#printerService,
-    );
-    prompterService.promptEnabled = this.#options.promptingEnabled;
-    this.addServiceProvider(new PrompterServiceProvider(75, prompterService));
+    const canPrompt = this.#keyReader !== undefined && this.#stderrTerminal.isTty();
+
+    if (this.#options.promptingEnabled && !canPrompt) {
+      throw new Error("promptingEnabled requires a keyReader and a TTY stderr terminal");
+    }
+
+    let prompterService: DefaultPrompterService | undefined;
+    if (canPrompt) {
+      prompterService = new DefaultPrompterService(
+        DEFAULT_PROMPTER_CONFIG,
+        this.#stderrTerminal,
+        this.#keyReader!,
+        this.#printerService,
+      );
+      prompterService.promptEnabled = this.#options.promptingEnabled;
+      this.addServiceProvider(new PrompterServiceProvider(75, prompterService));
+    } else {
+      logger.debug(
+        () =>
+          `Skipping PrompterServiceProvider: keyReader present: ${
+            this.#keyReader !== undefined
+          }, stderr isTty: ${this.#stderrTerminal.isTty()}`,
+      );
+    }
 
     if (this.#options.argumentPrompterServiceEnabled) {
-      const argumentPrompterService = new DefaultArgumentPrompterService(prompterService);
-      this.addServiceProvider(new ArgumentPrompterServiceProvider(65, argumentPrompterService));
+      if (prompterService !== undefined) {
+        const argumentPrompterService = new DefaultArgumentPrompterService(prompterService);
+        this.addServiceProvider(new ArgumentPrompterServiceProvider(65, argumentPrompterService));
+      } else {
+        logger.debug(
+          "Skipping ArgumentPrompterServiceProvider: argumentPrompterServiceEnabled is true but prompting is unavailable",
+        );
+      }
     }
 
     if (this.#options.imagePrinterServiceEnabled) {
-      this.addServiceProvider(new ImagePrinterServiceProvider(55, this.#stdoutTerminal));
+      if (this.#stdoutTerminal.isTty()) {
+        this.addServiceProvider(new ImagePrinterServiceProvider(55, this.#stdoutTerminal));
+      } else {
+        logger.debug(
+          "Skipping ImagePrinterServiceProvider: imagePrinterServiceEnabled is true but stdout is not a TTY",
+        );
+      }
     }
 
     if (this.#options.completionServiceEnabled) {

package/src/cli/DefaultRuntimeCLI.ts

@@ -5,30 +5,74 @@ import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
 import type BaseCLIFeatureOptions from "./BaseCLIFeatureOptions.ts";
 import { Writable } from "node:stream";
 import TtyTerminal from "../terminal/TtyTerminal.ts";
+import NonTtyTerminal from "../terminal/NonTtyTerminal.ts";
 import TtyKeyReader from "../terminal/TtyKeyReader.ts";
 import TtyStyler from "../terminal/TtyStyler.ts";
 import supportsColor from "supports-color";
 import supportsHyperlinks from "../terminal/supportsHyperlinks.ts";
+import getLogger from "../util/logger.ts";
+
+const logger = getLogger("DefaultRuntimeCLI");
 
 /**
  * Default Bun implementation of a {@link CLI} using `process.stdout`, `process.stderr` and `process.argv`.
+ *
+ * Degrades gracefully when `stdin`, `stdout` or `stderr` are not TTYs (e.g. piped or redirected):
+ * color and hyperlinks are disabled, prompting is disabled, and non-TTY streams are wrapped in a
+ * {@link NonTtyTerminal} rather than the usual {@link TtyTerminal}.
  */
 export default class DefaultRuntimeCLI extends BaseCLI {
   constructor(cliConfig: CLIConfig, options?: BaseCLIFeatureOptions) {
+    const stdinIsTty = process.stdin.isTTY === true;
+    const stdoutIsTty = process.stdout.isTTY === true;
+    const stderrIsTty = process.stderr.isTTY === true;
+
+    logger.debug(
+      () =>
+        `stdin isTTY: ${stdinIsTty}, stdout isTTY: ${stdoutIsTty}, stderr isTTY: ${stderrIsTty}`,
+    );
+
+    const stdoutTerminal = stdoutIsTty
+      ? new TtyTerminal(process.stdout)
+      : new NonTtyTerminal(process.stdout);
+    const stderrTerminal = stderrIsTty
+      ? new TtyTerminal(process.stderr)
+      : new NonTtyTerminal(process.stderr);
+
+    logger.debug(
+      () =>
+        `stdout terminal: ${
+          stdoutIsTty ? "TtyTerminal" : "NonTtyTerminal"
+        }, stderr terminal: ${stderrIsTty ? "TtyTerminal" : "NonTtyTerminal"}`,
+    );
+
+    const colorLevel = stderrIsTty
+      ? supportsColor.stderr === false
+        ? 1
+        : supportsColor.stderr.level
+      : 0;
+
+    logger.debug(() => `color level: ${colorLevel}`);
+
+    const keyReader = stdinIsTty ? new TtyKeyReader(process.stdin) : undefined;
+
+    logger.debug(() => `keyReader constructed: ${keyReader !== undefined}`);
+
+    const promptingEnabled = stdinIsTty && stderrIsTty;
+
+    logger.debug(() => `promptingEnabled default: ${promptingEnabled}`);
+
     super(
       cliConfig,
       Writable.toWeb(process.stdout),
       Writable.toWeb(process.stderr),
       supportsColor.stdout !== false,
       supportsColor.stderr !== false,
-      new TtyTerminal(process.stdout),
-      new TtyTerminal(process.stderr),
-      new TtyStyler(
-        supportsColor.stderr === false ? 1 : supportsColor.stderr.level,
-        supportsHyperlinks(process.stderr),
-      ),
-      new TtyKeyReader(process.stdin),
-      { promptingEnabled: process.stdin.isTTY === true, ...options },
+      stdoutTerminal,
+      stderrTerminal,
+      new TtyStyler(colorLevel, supportsHyperlinks(process.stderr)),
+      keyReader,
+      { promptingEnabled, ...options },
     );
   }
 

package/src/service/printer/DefaultPrinterService.ts

@@ -13,6 +13,7 @@ import { Color } from "./terminal/Color.ts";
 import { getDarkModeTheme, getLightModeTheme } from "./terminal/Theme.ts";
 import { WritableStream } from "node:stream/web";
 import type Styler from "../../terminal/Styler.ts";
+
 export default class DefaultPrinterService implements PrinterService {
   readonly stdoutWritable: WritableStream;
   readonly stderrWritable: WritableStream;
@@ -30,18 +31,16 @@ export default class DefaultPrinterService implements PrinterService {
   #quote: Quote;
   #markedLineCount: number | undefined;
   #markEndedAt: number | undefined;
-  #markedTerminal: Terminal | undefined;
 
   #countLines(message: string): number {
     return message.split("\n").length - (message.endsWith("\n") ? 1 : 0);
   }
 
-  #recordMarkedWrite(terminal: Terminal, message: string): void {
+  #recordMarkedWrite(message: string): void {
     if (this.#markedLineCount === undefined) {
       return;
     }
     this.#markedLineCount += this.#countLines(message);
-    this.#markedTerminal = terminal;
   }
 
   async #log(level: number, message: string, icon?: Icon): Promise<void> {
@@ -51,7 +50,7 @@ export default class DefaultPrinterService implements PrinterService {
     await this.#spinner.pause();
     await this.#progress.pause();
     const composed = `${icon !== undefined ? `${this.#iconDefinitions[icon]} ` : ""}${message}`;
-    this.#recordMarkedWrite(this.#stderrTerminal, composed);
+    this.#recordMarkedWrite(composed);
     await this.#stderrTerminal.write(this.#quote.prefixLines(composed));
     this.#spinner.resume();
     this.#progress.resume();
@@ -277,8 +276,7 @@ export default class DefaultPrinterService implements PrinterService {
     const composed = `${
       icon !== undefined ? `${this.#iconDefinitions[icon]} ` : ""
     }${colorMessage}`;
-    this.#recordMarkedWrite(this.#stdoutTerminal, composed);
-    const encoded = this.#encoder.encode(this.#quote.prefixLines(composed));
+    const encoded = this.#encoder.encode(composed);
 
     await writer.ready;
     await writer.write(encoded);
@@ -318,16 +316,18 @@ export default class DefaultPrinterService implements PrinterService {
     if (this.#markedLineCount === undefined || this.#markEndedAt === undefined) {
       throw new Error("clearMarked() called without a preceding endMark()");
     }
+    if (!this.#stderrTerminal.isTty()) {
+      this.#markedLineCount = undefined;
+      this.#markEndedAt = undefined;
+      return;
+    }
     const remaining = minimumDisplayTimeMs - (Date.now() - this.#markEndedAt);
     if (remaining > 0) {
       await new Promise((resolve) => setTimeout(resolve, remaining));
     }
-    if (this.#markedTerminal !== undefined) {
-      await this.#markedTerminal.clearUpLines(this.#markedLineCount);
-    }
+    await this.#stderrTerminal.clearUpLines(this.#markedLineCount);
     this.#markedLineCount = undefined;
     this.#markEndedAt = undefined;
-    this.#markedTerminal = undefined;
   }
 
   public async setLevel(level: Level): Promise<void> {
@@ -343,6 +343,9 @@ export default class DefaultPrinterService implements PrinterService {
   }
 
   public async showSpinner(message?: string, style?: SpinnerStyle): Promise<void> {
+    if (!this.#stderrTerminal.isTty()) {
+      return;
+    }
     await this.#progress.hideAll();
     if (this.#threshold > Level.INFO) {
       return;
@@ -364,6 +367,9 @@ export default class DefaultPrinterService implements PrinterService {
     current = 0,
     style?: ProgressStyle,
   ): Promise<number> {
+    if (!this.#stderrTerminal.isTty()) {
+      return -1;
+    }
     await this.#spinner.hide();
     if (this.#threshold > Level.INFO) {
       return -1;

package/src/terminal/NonTtyTerminal.ts

@@ -0,0 +1,48 @@
+import { WriteStream } from "node:tty";
+import type Terminal from "./Terminal.ts";
+
+export default class NonTtyTerminal implements Terminal {
+  readonly #writeStream: NodeJS.WritableStream;
+  readonly #encoder = new TextEncoder();
+
+  constructor(writeStream: NodeJS.WritableStream) {
+    if ((writeStream as WriteStream).isTTY === true) {
+      throw new Error("The provided WriteStream is a TTY");
+    }
+
+    this.#writeStream = writeStream;
+  }
+
+  write(text: string): Promise<void> {
+    this.#writeStream.write(this.#encoder.encode(text));
+    return Promise.resolve();
+  }
+
+  columns(): number {
+    return 80;
+  }
+
+  rows(): number {
+    return 24;
+  }
+
+  clearLine(): Promise<void> {
+    return Promise.reject(new Error("clearLine() is not supported on a non-TTY terminal"));
+  }
+
+  clearUpLines(_count: number): Promise<void> {
+    return Promise.reject(new Error("clearUpLines() is not supported on a non-TTY terminal"));
+  }
+
+  hideCursor(): Promise<void> {
+    return Promise.reject(new Error("hideCursor() is not supported on a non-TTY terminal"));
+  }
+
+  showCursor(): Promise<void> {
+    return Promise.reject(new Error("showCursor() is not supported on a non-TTY terminal"));
+  }
+
+  isTty(): boolean {
+    return false;
+  }
+}

package/src/terminal/Terminal.ts

@@ -6,4 +6,5 @@ export default interface Terminal {
   write(text: string): Promise<void>;
   columns(): number;
   rows(): number;
+  isTty(): boolean;
 }

package/src/terminal/TtyStyler.ts

@@ -17,6 +17,7 @@ export default class TtyStyler implements Styler {
   /**
    * The color level in use.
    *
+   * 0 = no color
    * 1 = 16 color
    * 2 = 256 color
    * 3 = 16 million color
@@ -27,7 +28,7 @@ export default class TtyStyler implements Styler {
   }
 
   colorText(text: string, colorValue: number): string {
-    if (!this.colorEnabled) {
+    if (!this.colorEnabled || this.colorLevel === 0) {
       return text;
     }
 
@@ -43,7 +44,7 @@ export default class TtyStyler implements Styler {
   }
 
   backgroundColorText(text: string, colorValue: number): string {
-    if (!this.colorEnabled) {
+    if (!this.colorEnabled || this.colorLevel === 0) {
       return text;
     }
 
@@ -68,6 +69,9 @@ export default class TtyStyler implements Styler {
   }
 
   italicText(text: string): string {
+    if (!this.colorEnabled || this.colorLevel === 0) {
+      return text;
+    }
     return ITALIC_START + text + ITALIC_END;
   }
 

package/src/terminal/TtyTerminal.ts

@@ -62,4 +62,8 @@ export default class TtyTerminal implements Terminal {
       return 24;
     }
   }
+
+  isTty(): boolean {
+    return true;
+  }
 }