@travetto/terminal 8.0.0-alpha.9 → 8.0.0

package/README.md

@@ -13,20 +13,20 @@ npm install @travetto/terminal
 yarn add @travetto/terminal
 ```
 
-This module provides basic support for interacting with the terminal, and provides the basis for output colorization and the basic command line interactions.  The functionality can be broken down into:
+This module provides basic support for interacting with the terminal, and provides the basis for output colorization and the basic command line interactions. The functionality can be broken down into:
    *  Output Colorization
    *  Terminal Interactions
 
 ## Output Colorization
-Oddly enough, colorizing output in a terminal is a fairly complex process.  The standards are somewhat inconsistent and detection can be a tricky process. For terminals, [Node](https://nodejs.org) supports 4 different levels of coloring:
+Oddly enough, colorizing output in a terminal is a fairly complex process. The standards are somewhat inconsistent and detection can be a tricky process. For terminals, [Node](https://nodejs.org) supports 4 different levels of coloring:
    *  0 - One color, essentially uncolored output
    *  1 - Basic color support, 16 colors
    *  2 - Enhanced color support, 225 colors, providing a fair representation of most colors
-   *  3 - True color, 24bit color with R, G, B each getting 8-bits.  Can represent any color needed
+   *  3 - True color, 24bit color with R, G, B each getting 8-bits. Can represent any color needed
 
-This module provides the ability to define color palettes using RGB colors, and additionally provides support for palettes based on a dark or light background for a given terminal.  Support for this is widespread, but when it fails, it will gracefully assume a dark background. 
+This module provides the ability to define color palettes using RGB colors, and additionally provides support for palettes based on a dark or light background for a given terminal. Support for this is widespread, but when it fails, it will gracefully assume a dark background. 
 
-These palettes then are usable at runtime, with the module determining light or dark palettes, as well as falling back to the closest color value based on what the existing terminal supports.  This means a color like 'olivegreen', will get the proper output in 24bit color support, a close approximation in enhanced color support, fall back to green in basic color support, and will be color less at level 0.
+These palettes then are usable at runtime, with the module determining light or dark palettes, as well as falling back to the closest color value based on what the existing terminal supports. This means a color like 'olivegreen', will get the proper output in 24bit color support, a close approximation in enhanced color support, fall back to green in basic color support, and will be color less at level 0.
 
 **Code: CLI Color Palette**
 ```typescript
@@ -73,11 +73,11 @@ NODE_DISABLE_COLORS         set to 1 to disable colors in the REPL
 ```
 
 ## Terminal Interactions
-Within the [Travetto](https://travetto.dev) framework, there are plenty of command line interactions that are enhanced with additional interactivity.  This mainly revolves around indicating progress while a program is executing.  The module provides support for:
+Within the [Travetto](https://travetto.dev) framework, there are plenty of command line interactions that are enhanced with additional interactivity. This mainly revolves around indicating progress while a program is executing. The module provides support for:
    *  Progress Bars
    *  Waiting Indicators
    *  Streaming Content
 
-This is generally meant for use within the framework, and so is highly tailored to the specific needs and scenarios.  You can see this pattern play out in the [Compiler](https://github.com/travetto/travetto/tree/main/module/compiler#readme "The compiler infrastructure for the Travetto framework") progress output, or in [Pack](https://github.com/travetto/travetto/tree/main/module/pack#readme "Code packing utilities")'s output. 
+This is generally meant for use within the framework, and so is highly tailored to the specific needs and scenarios. You can see this pattern play out in the [Compiler](https://github.com/travetto/travetto/tree/main/module/compiler#readme "The compiler infrastructure for the Travetto framework") progress output, or in [Pack](https://github.com/travetto/travetto/tree/main/module/pack#readme "Code packing utilities")'s output. 
 
-In these scenarios, the dynamic behaviors are dependent on having an interactive TTY.  When running without access to a proper stdin, the output will default to basic line printing.    This dynamic behavior can also be disabled using the environment variable `TRV_QUIET`.  When set to `1` will provide a minimal text-based experience.
+In these scenarios, the dynamic behaviors are dependent on having an interactive TTY. When running without access to a proper stdin, the output will default to basic line printing. This dynamic behavior can also be disabled using the environment variable `TRV_QUIET`. When set to `1` will provide a minimal text-based experience.

package/__index__.ts

@@ -1,5 +1,6 @@
-import type { } from './src/trv.d.ts';
+import type {} from './src/trv.d.ts';
+
 export * from './src/style.ts';
 export * from './src/terminal.ts';
+export * from './src/util.ts';
 export * from './src/writer.ts';
-export * from './src/util.ts';

package/package.json

@@ -1,38 +1,38 @@
 {
   "name": "@travetto/terminal",
-  "version": "8.0.0-alpha.9",
-  "type": "module",
+  "version": "8.0.0",
+  "private": false,
   "description": "General terminal support",
   "keywords": [
-    "terminal",
     "ansi256",
+    "terminal",
     "travetto",
     "typescript"
   ],
   "homepage": "https://travetto.io",
   "license": "MIT",
   "author": {
-    "email": "travetto.framework@gmail.com",
-    "name": "Travetto Framework"
+    "name": "Travetto Framework",
+    "email": "travetto.framework@gmail.com"
+  },
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/terminal"
   },
   "files": [
     "__index__.ts",
     "src"
   ],
+  "type": "module",
   "main": "__index__.ts",
-  "repository": {
-    "url": "git+https://github.com/travetto/travetto.git",
-    "directory": "module/terminal"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@travetto/runtime": "^8.0.0-alpha.9",
-    "chalk": "^5.6.2"
+    "@travetto/runtime": "^8.0.0",
+    "chalk": "^6.0.0"
   },
   "travetto": {
     "displayName": "Terminal"
-  },
-  "private": false,
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/style.ts

@@ -4,17 +4,34 @@ import { Env, TypedObject } from '@travetto/runtime';
 
 type TemplatePrim = number | string | bigint | boolean | RegExp;
 type Color = `#${string}`;
-export type TermStyleInput = Color | { text: Color, background?: Color, inverse?: boolean, bold?: boolean, italic?: boolean, underline?: boolean };
+export type TermStyleInput =
+  | Color
+  | { text: Color; background?: Color; inverse?: boolean; bold?: boolean; italic?: boolean; underline?: boolean };
 type TermStylePairInput = [dark: TermStyleInput, light?: TermStyleInput] | readonly [dark: TermStyleInput, light?: TermStyleInput];
 export type TermStyleFn = (input: TemplatePrim) => string;
-export type TermStyledTemplate<T extends string> = (values: TemplateStringsArray, ...keys: (Partial<Record<T, TemplatePrim>> | string)[]) => string;
+export type TermStyledTemplate<T extends string> = (
+  values: TemplateStringsArray,
+  ...keys: (Partial<Record<T, TemplatePrim>> | string)[]
+) => string;
 export type ColorLevel = 0 | 1 | 2 | 3;
 
 const ANSI_16_RGB: [number, number, number][] = [
-  [0, 0, 0], [128, 0, 0], [0, 128, 0], [128, 128, 0],
-  [0, 0, 128], [128, 0, 128], [0, 128, 128], [192, 192, 192],
-  [128, 128, 128], [255, 0, 0], [0, 255, 0], [255, 255, 0],
-  [0, 0, 255], [255, 0, 255], [0, 255, 255], [255, 255, 255]
+  [0, 0, 0],
+  [128, 0, 0],
+  [0, 128, 0],
+  [128, 128, 0],
+  [0, 0, 128],
+  [128, 0, 128],
+  [0, 128, 128],
+  [192, 192, 192],
+  [128, 128, 128],
+  [255, 0, 0],
+  [0, 255, 0],
+  [255, 255, 0],
+  [0, 0, 255],
+  [255, 0, 255],
+  [0, 255, 255],
+  [255, 255, 255]
 ];
 
 const toLinear = (v: number): number => {
@@ -25,7 +42,6 @@ const toLinear = (v: number): number => {
 const ESC = '\x1b';
 
 export class StyleUtil {
-
   /** Compute RGB values for ANSI 256 color code */
   static computeRGBForAnsi256(code: number): [number, number, number] {
     if (code < 16) {
@@ -49,7 +65,7 @@ export class StyleUtil {
     return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
   }
 
-  static #scheme: { key: string, dark: boolean } = { key: '', dark: true };
+  static #scheme: { key: string; dark: boolean } = { key: '', dark: true };
 
   /**
    * Create text render function from style input using current color levels
@@ -61,9 +77,15 @@ export class StyleUtil {
       let style = chalk;
       for (const key of TypedObject.keys(input)) {
         switch (key) {
-          case 'text': style = style.hex(input[key]!); break;
-          case 'background': style = style.bgHex(input[key]!); break;
-          default: style = (input[key] ? style[key] : style); break;
+          case 'text':
+            style = style.hex(input[key]!);
+            break;
+          case 'background':
+            style = style.bgHex(input[key]!);
+            break;
+          default:
+            style = input[key] ? style[key] : style;
+            break;
         }
       }
       return style;
@@ -106,8 +128,7 @@ export class StyleUtil {
    * Build style palette, with support for background theme awareness
    */
   static getPalette<K extends string>(input: Record<K, TermStylePairInput>): Record<K, TermStyleFn> {
-    return TypedObject.fromEntries(
-      TypedObject.entries(input).map(([key, value]) => [key, this.getThemedStyle(value)]));
+    return TypedObject.fromEntries(TypedObject.entries(input).map(([key, value]) => [key, this.getThemedStyle(value)]));
   }
 
   /**
@@ -149,4 +170,4 @@ export class StyleUtil {
       return `${ESC}]8;;${url}${ESC}\\${text}${ESC}]8;;${ESC}\\`;
     }
   }
-}
+}

package/src/terminal.ts

@@ -4,8 +4,8 @@ import { Env, Util } from '@travetto/runtime';
 
 import { TerminalWriter } from './writer.ts';
 
-type TerminalStreamingConfig = { minDelay?: number, outputStreamToMain?: boolean };
-type Coord = { x: number, y: number };
+type TerminalStreamingConfig = { minDelay?: number; outputStreamToMain?: boolean };
+type Coord = { x: number; y: number };
 
 export const WAIT_TOKEN = '%WAIT%';
 const STD_WAIT_STATES = '⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'.split('');
@@ -15,7 +15,6 @@ const lineMain = (line: string): string => line.replace(WAIT_TOKEN, '').trim();
 
 /** An basic tty wrapper */
 export class Terminal {
-
   #interactive: boolean;
   #writer: TerminalWriter;
   #width: number;
@@ -24,15 +23,18 @@ export class Terminal {
 
   async #showWaitingIndicator(position: Coord, signal: AbortSignal): Promise<void> {
     let done = false;
-    signal.addEventListener('abort', () => done = true);
+    signal.addEventListener('abort', () => (done = true));
     let i = 0;
     while (!done) {
-      await this.#writer.setPosition(position).write(STD_WAIT_STATES[i++ % STD_WAIT_STATES.length]).commit(true);
+      await this.#writer
+        .setPosition(position)
+        .write(STD_WAIT_STATES[(i += 1 % STD_WAIT_STATES.length)])
+        .commit(true);
       await Util.blockingTimeout(100);
     }
   }
 
-  constructor(output?: tty.WriteStream, config?: { width?: number, height?: number }) {
+  constructor(output?: tty.WriteStream, config?: { width?: number; height?: number }) {
     this.#output = output ?? process.stdout;
     this.#interactive = this.#output.isTTY && !Env.TRV_QUIET.isTrue;
     this.#width = config?.width ?? (this.#output.isTTY ? this.#output.columns : 120);
@@ -40,11 +42,21 @@ export class Terminal {
     this.#writer = new TerminalWriter(this);
   }
 
-  get output(): tty.WriteStream { return this.#output; }
-  get width(): number { return this.#width; }
-  get height(): number { return this.#height; }
-  get writer(): TerminalWriter { return this.#writer; }
-  get interactive(): boolean { return this.#interactive; }
+  get output(): tty.WriteStream {
+    return this.#output;
+  }
+  get width(): number {
+    return this.#width;
+  }
+  get height(): number {
+    return this.#height;
+  }
+  get writer(): TerminalWriter {
+    return this.#writer;
+  }
+  get interactive(): boolean {
+    return this.#interactive;
+  }
 
   /**
    * Stream lines if interactive, with waiting indicator, otherwise print out
@@ -57,7 +69,10 @@ export class Terminal {
         }
       }
     } else {
-      await this.streamToBottom(Util.mapAsyncIterable(source, line => `%WAIT% ${line}`), { outputStreamToMain: true });
+      await this.streamToBottom(
+        Util.mapAsyncIterable(source, line => `%WAIT% ${line}`),
+        { outputStreamToMain: true }
+      );
     }
   }
 
@@ -73,9 +88,13 @@ export class Terminal {
     let start = Date.now();
 
     try {
-      await this.#writer.hideCursor()
-        .storePosition().scrollRange({ end: -2 }).restorePosition()
-        .changePosition({ y: -1 }).write('\n')
+      await this.#writer
+        .hideCursor()
+        .storePosition()
+        .scrollRange({ end: -2 })
+        .restorePosition()
+        .changePosition({ y: -1 })
+        .write('\n')
         .commit();
 
       for await (const line of source) {
@@ -84,7 +103,7 @@ export class Terminal {
           await this.writer.writeLine(lineMain(previous)).commit();
         }
 
-        if (line && (Date.now() - start) >= minDelay) {
+        if (line && Date.now() - start >= minDelay) {
           start = Date.now();
           stop?.abort();
           this.writer.setPosition(writePosition).write(lineStatus(line)).clearLine(1).commit(true);
@@ -113,7 +132,7 @@ export class Terminal {
   /**
    * Consumes a stream, of events, tied to specific list indices, and updates in place
    */
-  async streamList(source: AsyncIterable<{ idx: number, text: string, done?: boolean }>): Promise<void> {
+  async streamList(source: AsyncIterable<{ idx: number; text: string; done?: boolean }>): Promise<void> {
     if (!this.#interactive) {
       const collected = [];
       for await (const event of source) {
@@ -133,7 +152,11 @@ export class Terminal {
         await this.#writer.write('\n'.repeat(idx)).setPosition({ x: 0 }).write(text).clearLine(1).changePosition({ y: -idx }).commit();
       }
     } finally {
-      await this.#writer.changePosition({ y: max + 1 }).writeLine('\n').reset().commit();
+      await this.#writer
+        .changePosition({ y: max + 1 })
+        .writeLine('\n')
+        .reset()
+        .commit();
     }
   }
-}
+}

package/src/trv.d.ts

@@ -6,16 +6,16 @@ declare module '@travetto/runtime' {
      * Flag for node to disable colors
      */
     NODE_DISABLE_COLORS: boolean;
-    /** 
+    /**
      * Terminal colors provided as ansi 256 color schemes
      */
     COLORFGBG: string;
-    /** 
-     * Enables color, even if `tty` is not available 
+    /**
+     * Enables color, even if `tty` is not available
      * @default undefined
      */
     FORCE_COLOR: boolean | ColorLevel;
-    /** 
+    /**
      * Disables color even if `tty` is available
      * @default false
      */
@@ -25,8 +25,8 @@ declare module '@travetto/runtime' {
      */
     COLORTERM: string;
     /**
-      * Terminal operation mode, false means simple output
-      */
+     * Terminal operation mode, false means simple output
+     */
     TRV_QUIET: boolean;
   }
-}
+}

package/src/util.ts

@@ -1,10 +1,35 @@
+import rl from 'node:readline/promises';
+
+import { Env } from '@travetto/runtime';
+
 import { StyleUtil, type TermStyleFn, type TermStyleInput } from './style.ts';
 import { type Terminal, WAIT_TOKEN } from './terminal.ts';
 
-type ProgressEvent<T> = { total?: number, idx: number, value: T };
-type ProgressStyle = { complete: TermStyleFn, incomplete?: TermStyleFn };
+export type ProgressEvent<T> = { total?: number; completed: number; value: T; failed?: number };
+type ProgressStyle = { complete: TermStyleFn; failed: TermStyleFn; incomplete?: TermStyleFn };
 
 export class TerminalUtil {
+  /**
+   * Determine if the terminal session is interactive
+   */
+  static isInteractive(): boolean {
+    return process.stdout.isTTY && process.stdin.isTTY && !Env.TRV_QUIET.isTrue;
+  }
+
+  /**
+   * Prompt the user for input
+   */
+  static async prompt(message: string): Promise<string> {
+    if (!this.isInteractive()) {
+      return '';
+    }
+    const reader = rl.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      return (await reader.question(message)).trim();
+    } finally {
+      reader.close();
+    }
+  }
 
   /**
    * Create a progress bar updater, suitable for streaming to the bottom of the screen
@@ -13,31 +38,41 @@ export class TerminalUtil {
     term: Terminal,
     config?: {
       withWaiting?: boolean;
-      style?: { complete: TermStyleInput, incomplete?: TermStyleInput } | (() => ProgressStyle);
+      style?: { complete: TermStyleInput; failed?: TermStyleInput; incomplete?: TermStyleInput } | (() => ProgressStyle);
     }
   ): (event: ProgressEvent<string>) => string {
-    const styleBase = typeof config?.style !== 'function' ? {
-      complete: StyleUtil.getStyle(config?.style?.complete ?? { background: '#248613', text: '#ffffff' }),
-      incomplete: config?.style?.incomplete ? StyleUtil.getStyle(config.style.incomplete) : undefined,
-    } : undefined;
+    const styleBase =
+      typeof config?.style !== 'function'
+        ? {
+            complete: StyleUtil.getStyle(config?.style?.complete ?? { background: '#248613', text: '#ffffff' }),
+            failed: StyleUtil.getStyle({ background: '#880000', text: '#ffffff', inverse: false }),
+            incomplete: config?.style?.incomplete ? StyleUtil.getStyle(config.style.incomplete) : undefined
+          }
+        : undefined;
 
     const style = typeof config?.style === 'function' ? config.style : (): ProgressStyle => styleBase!;
 
     let width: number;
     return event => {
-      const text = event.value ?? (event.total ? '%idx/%total' : '%idx');
-      const progress = event.total === undefined ? 0 : (event.idx / event.total);
+      const text = event.value ?? (event.total ? '%completed/%total' : '%completed');
+      const progress = event.total === undefined ? 0 : event.completed / event.total;
       if (event.total) {
         width ??= Math.trunc(Math.ceil(Math.log10(event.total ?? 10000)));
       }
-      const state: Record<string, string> = { total: `${event.total}`, idx: `${event.idx}`.padStart(width ?? 0), progress: `${Math.trunc(progress * 100)}` };
-      const line = ` ${text.replace(/[%](idx|total|progress)/g, (_, key) => state[key])} `;
+      const state: Record<string, string> = {
+        total: `${event.total}`,
+        completed: `${event.completed}`.padStart(width ?? 0),
+        progress: `${Math.trunc(progress * 100)}`,
+        failed: `${event.failed ?? 0}`
+      };
+      const line = ` ${text.replace(/[%](completed|total|progress|failed)/g, (_, key) => state[key])} `;
       const full = term.writer.padToWidth(line, config?.withWaiting ? 2 : 0);
       const mid = Math.trunc(progress * term.width);
       const [left, right] = [full.substring(0, mid), full.substring(mid)];
 
-      const { complete, incomplete } = style();
-      return `${config?.withWaiting ? `${WAIT_TOKEN} ` : ''}${complete(left)}${incomplete?.(right) ?? right}`;
+      const { complete, incomplete, failed } = style();
+      const color = event.failed ? failed : complete;
+      return `${config?.withWaiting ? `${WAIT_TOKEN} ` : ''}${color(left)}${incomplete?.(right) ?? right}`;
     };
   }
-}
+}

package/src/writer.ts

@@ -2,8 +2,8 @@ import type tty from 'node:tty';
 
 import { ShutdownManager } from '@travetto/runtime';
 
-type State = { output: tty.WriteStream, height: number, width: number };
-type TermCoord = { x: number, y: number };
+type State = { output: tty.WriteStream; height: number; width: number };
+type TermCoord = { x: number; y: number };
 
 const ESC = '\x1b[';
 const clamp = (input: number, size: number): number => Math.max(Math.min(input + (input < 0 ? size : 0), size - 1), 0);
@@ -23,10 +23,9 @@ const Codes = {
 
   DEBUG: (text: string): string => text.replaceAll(ESC, '<ESC>').replaceAll('\n', '<NL>'),
   CURSOR_MOVE: (x?: number, y?: number): string => `${delta(x, 'C', 'D')}${delta(y, 'B', 'A')}`,
-  POSITION_SET: (x: number, y: number | undefined, maxX: number, maxY: number): string => y !== undefined ?
-    `${ESC}${clamp(y, maxY) + 1};${clamp(x, maxX) + 1}H` : `${ESC}${clamp(x, maxX) + 1}G`,
-  SCROLL_RANGE_SET: (start: number, end: number, max: number): string =>
-    `${ESC}${clamp(start, max) + 1};${clamp(end, max) + 1}r`
+  POSITION_SET: (x: number, y: number | undefined, maxX: number, maxY: number): string =>
+    y !== undefined ? `${ESC}${clamp(y, maxY) + 1};${clamp(x, maxX) + 1}H` : `${ESC}${clamp(x, maxX) + 1}G`,
+  SCROLL_RANGE_SET: (start: number, end: number, max: number): string => `${ESC}${clamp(start, max) + 1};${clamp(end, max) + 1}r`
 };
 
 /**
@@ -63,7 +62,7 @@ export class TerminalWriter {
 
   /** Pad to width of terminal */
   padToWidth(text: string, offset = 0, ellipsis = '...'): string {
-    if (text.length > (this.#term.width - offset)) {
+    if (text.length > this.#term.width - offset) {
       return `${text.substring(0, this.#term.width - (offset + ellipsis.length))}${ellipsis}`;
     }
     return text.padEnd(this.#term.width - offset, ' ');
@@ -107,9 +106,12 @@ export class TerminalWriter {
   /** Clear line, -1 (left), 0 (both), 1 (right), from current cursor */
   clearLine(dir: -1 | 0 | 1 = 0): this {
     switch (dir) {
-      case 0: return this.write(Codes.ERASE_LINE_ALL);
-      case 1: return this.write(Codes.ERASE_LINE_RIGHT);
-      case -1: return this.write(Codes.ERASE_LINE_LEFT);
+      case 0:
+        return this.write(Codes.ERASE_LINE_ALL);
+      case 1:
+        return this.write(Codes.ERASE_LINE_RIGHT);
+      case -1:
+        return this.write(Codes.ERASE_LINE_LEFT);
     }
   }
 
@@ -152,7 +154,7 @@ export class TerminalWriter {
   }
 
   /** Set scrolling range */
-  scrollRange({ start = 0, end = -1 }: { start?: number, end?: number }): this {
+  scrollRange({ start = 0, end = -1 }: { start?: number; end?: number }): this {
     return this.trackDirty(true).write(Codes.SCROLL_RANGE_SET(start, end, this.#term.height));
   }
 
@@ -165,4 +167,4 @@ export class TerminalWriter {
   reset(): this {
     return this.trackDirty(false).write(Codes.SOFT_RESET).write(Codes.SHOW_CURSOR);
   }
-}
+}