@flowscripter/dynamic-cli-framework 1.1.6 → 1.2.1

package/src/terminal/ImageRenderer.ts

@@ -0,0 +1,199 @@
+import process from "node:process";
+import supportsTerminalGraphics from "supports-terminal-graphics";
+import { decodePngToRGBA } from "./PngDecoder.ts";
+import {
+  BACKGROUND_COLOR_END,
+  backgroundColorStart,
+  FOREGROUND_COLOR_END,
+  foregroundColorStart,
+} from "./Ansi.ts";
+import type Terminal from "./Terminal.ts";
+import { Buffer } from "node:buffer";
+
+export default class ImageRenderer {
+  #terminal: Terminal;
+
+  constructor(terminal: Terminal) {
+    this.#terminal = terminal;
+  }
+
+  renderImage(
+    imageBuffer: Uint8Array,
+    widthPercentage: number = 100,
+    hexFormattedBackgroundColor?: string,
+  ): Promise<string> {
+    if (!this.#isMultiplexer()) {
+      if (supportsTerminalGraphics.stdout.kitty) {
+        return this.#renderKitty(imageBuffer, widthPercentage);
+      }
+      if (supportsTerminalGraphics.stdout.iterm2) {
+        return this.#renderITerm2(imageBuffer, widthPercentage);
+      }
+    }
+    return this.#renderAnsiBlocks(
+      imageBuffer,
+      widthPercentage,
+      hexFormattedBackgroundColor,
+    );
+  }
+
+  #isMultiplexer(): boolean {
+    const term = (process.env.TERM || "").toLowerCase();
+    const termProgram = (process.env.TERM_PROGRAM || "").toLowerCase();
+    return termProgram === "tmux" || termProgram === "screen" ||
+      term.startsWith("tmux") || term.startsWith("screen");
+  }
+
+  // https://sw.kovidgoyal.net/kitty/graphics-protocol/
+  async #renderKitty(
+    imageBuffer: Uint8Array,
+    widthPercentage: number,
+  ): Promise<string> {
+    const pngBytes = await new Bun.Image(imageBuffer).png().bytes();
+    const columns = Math.floor(
+      this.#terminal.columns() * widthPercentage / 100,
+    );
+    const base64 = Buffer.from(pngBytes).toString("base64");
+    const chunks: string[] = [];
+    for (let i = 0; i < base64.length; i += 4096) {
+      chunks.push(base64.slice(i, i + 4096));
+    }
+    let result = "";
+    for (let i = 0; i < chunks.length; i++) {
+      const isLast = i === chunks.length - 1;
+      if (i === 0) {
+        result += `\x1b_Gf=100,a=T,c=${columns},m=${isLast ? 0 : 1};${
+          chunks[i]
+        }\x1b\\`;
+      } else {
+        result += `\x1b_Gm=${isLast ? 0 : 1};${chunks[i]}\x1b\\`;
+      }
+    }
+    return result;
+  }
+
+  // https://iterm2.com/documentation-images.html
+  async #renderITerm2(
+    imageBuffer: Uint8Array,
+    widthPercentage: number,
+  ): Promise<string> {
+    const pngBytes = await new Bun.Image(imageBuffer).png().bytes();
+    const base64 = Buffer.from(pngBytes).toString("base64");
+    return `\x1b]1337;File=inline=1;width=${widthPercentage}%:${base64}\x07`;
+  }
+
+  static #parseHexColor(
+    hex: string,
+  ): { r: number; g: number; b: number } | undefined {
+    const match = hex.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+    if (!match) return undefined;
+    return {
+      r: Number.parseInt(match[1]!, 16),
+      g: Number.parseInt(match[2]!, 16),
+      b: Number.parseInt(match[3]!, 16),
+    };
+  }
+
+  async #renderAnsiBlocks(
+    imageBuffer: Uint8Array,
+    widthPercentage: number,
+    hexFormattedBackgroundColor?: string,
+  ): Promise<string> {
+    const bg = hexFormattedBackgroundColor
+      ? ImageRenderer.#parseHexColor(hexFormattedBackgroundColor)
+      : undefined;
+    const columns = this.#terminal.columns();
+    const rows = this.#terminal.rows();
+    const targetWidth = Math.floor(columns * widthPercentage / 100);
+
+    const meta = await new Bun.Image(imageBuffer).metadata();
+    const aspectRatio = meta.height! / meta.width!;
+    let targetHeight = Math.round(targetWidth * aspectRatio);
+    if (targetHeight % 2 !== 0) targetHeight++;
+    const maxHeight = (rows - 2) * 2;
+    if (targetHeight > maxHeight) targetHeight = maxHeight;
+
+    const resizedPng = await new Bun.Image(imageBuffer)
+      .resize(targetWidth, targetHeight, { fit: "inside" })
+      .png()
+      .bytes();
+    const { width, height, pixels } = decodePngToRGBA(resizedPng);
+
+    const lines: string[] = [];
+    for (let y = 0; y < height; y += 2) {
+      let line = "";
+      const hasBottom = y + 1 < height;
+      for (let x = 0; x < width; x++) {
+        const topIdx = (y * width + x) * 4;
+        const r = pixels[topIdx]!;
+        const g = pixels[topIdx + 1]!;
+        const b = pixels[topIdx + 2]!;
+        const a = pixels[topIdx + 3]!;
+
+        if (hasBottom) {
+          const botIdx = ((y + 1) * width + x) * 4;
+          const r2 = pixels[botIdx]!;
+          const g2 = pixels[botIdx + 1]!;
+          const b2 = pixels[botIdx + 2]!;
+          const a2 = pixels[botIdx + 3]!;
+
+          if (a === 0 && a2 === 0) {
+            if (bg) {
+              line += backgroundColorStart(
+                bg.r,
+                bg.g,
+                bg.b,
+              ) + " " + BACKGROUND_COLOR_END;
+            } else {
+              line += " ";
+            }
+          } else if (a === 0) {
+            if (bg) {
+              line += backgroundColorStart(
+                bg.r,
+                bg.g,
+                bg.b,
+              ) + foregroundColorStart(r2, g2, b2) + "▄" +
+                FOREGROUND_COLOR_END + BACKGROUND_COLOR_END;
+            } else {
+              line += foregroundColorStart(r2, g2, b2) + "▄" +
+                FOREGROUND_COLOR_END;
+            }
+          } else if (a2 === 0) {
+            if (bg) {
+              line += backgroundColorStart(
+                bg.r,
+                bg.g,
+                bg.b,
+              ) + foregroundColorStart(r, g, b) + "▀" +
+                FOREGROUND_COLOR_END + BACKGROUND_COLOR_END;
+            } else {
+              line += foregroundColorStart(r, g, b) + "▀" +
+                FOREGROUND_COLOR_END;
+            }
+          } else {
+            line += backgroundColorStart(r, g, b) +
+              foregroundColorStart(r2, g2, b2) + "▄" +
+              FOREGROUND_COLOR_END + BACKGROUND_COLOR_END;
+          }
+        } else {
+          if (a === 0) {
+            if (bg) {
+              line += backgroundColorStart(
+                bg.r,
+                bg.g,
+                bg.b,
+              ) + " " + BACKGROUND_COLOR_END;
+            } else {
+              line += " ";
+            }
+          } else {
+            line += backgroundColorStart(r, g, b) + " " + BACKGROUND_COLOR_END;
+          }
+        }
+      }
+      lines.push(line);
+    }
+    return lines.join("\n");
+  }
+}

package/src/terminal/KeyReader.ts

@@ -0,0 +1,23 @@
+export enum SpecialKey {
+  UP = 0,
+  DOWN = 1,
+  LEFT = 2,
+  RIGHT = 3,
+  ENTER = 4,
+  SPACE = 5,
+  BACKSPACE = 6,
+  ESCAPE = 7,
+  TAB = 8,
+  INTERRUPT = 9,
+}
+
+export interface KeyEvent {
+  readonly key?: string;
+  readonly specialKey?: SpecialKey;
+}
+
+export default interface KeyReader {
+  enableRawMode(): void;
+  disableRawMode(): void;
+  readKey(): Promise<KeyEvent>;
+}

package/src/terminal/PngDecoder.ts

@@ -0,0 +1,143 @@
+// Minimal PNG-to-RGBA pixel extractor. Supports 8-bit RGB and RGBA only.
+import { inflateSync } from "node:zlib";
+
+function paethPredictor(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  if (pb <= pc) return b;
+  return c;
+}
+
+export function decodePngToRGBA(
+  pngBytes: Uint8Array,
+): { width: number; height: number; pixels: Uint8Array } {
+  const sig = [137, 80, 78, 71, 13, 10, 26, 10];
+  for (let i = 0; i < 8; i++) {
+    if (pngBytes[i] !== sig[i]) throw new Error("Invalid PNG signature");
+  }
+
+  const view = new DataView(
+    pngBytes.buffer,
+    pngBytes.byteOffset,
+    pngBytes.byteLength,
+  );
+  let offset = 8;
+
+  let width = 0;
+  let height = 0;
+  let bitDepth = 0;
+  let colorType = 0;
+  const idatChunks: Uint8Array[] = [];
+
+  while (offset < pngBytes.length) {
+    const length = view.getUint32(offset);
+    const type = String.fromCharCode(
+      pngBytes[offset + 4]!,
+      pngBytes[offset + 5]!,
+      pngBytes[offset + 6]!,
+      pngBytes[offset + 7]!,
+    );
+    const dataStart = offset + 8;
+
+    if (type === "IHDR") {
+      width = view.getUint32(dataStart);
+      height = view.getUint32(dataStart + 4);
+      bitDepth = pngBytes[dataStart + 8]!;
+      colorType = pngBytes[dataStart + 9]!;
+      const interlace = pngBytes[dataStart + 12]!;
+      if (bitDepth !== 8) {
+        throw new Error(
+          `Unsupported bit depth: ${bitDepth} (only 8 supported)`,
+        );
+      }
+      if (colorType !== 2 && colorType !== 6) {
+        throw new Error(
+          `Unsupported color type: ${colorType} (only RGB=2 and RGBA=6 supported)`,
+        );
+      }
+      if (interlace !== 0) {
+        throw new Error("Interlaced PNGs are not supported");
+      }
+    } else if (type === "IDAT") {
+      idatChunks.push(pngBytes.subarray(dataStart, dataStart + length));
+    } else if (type === "IEND") {
+      break;
+    }
+
+    offset = dataStart + length + 4; // +4 for CRC
+  }
+
+  if (width === 0 || height === 0) throw new Error("Missing IHDR chunk");
+  if (idatChunks.length === 0) throw new Error("Missing IDAT chunks");
+
+  const bpp = colorType === 6 ? 4 : 3;
+  const compressed = new Uint8Array(
+    idatChunks.reduce((sum, c) => sum + c.length, 0),
+  );
+  let pos = 0;
+  for (const chunk of idatChunks) {
+    compressed.set(chunk, pos);
+    pos += chunk.length;
+  }
+
+  const raw = inflateSync(compressed);
+  const stride = bpp * width;
+  const pixels = new Uint8Array(width * height * 4);
+  const prevRow = new Uint8Array(stride);
+  const currRow = new Uint8Array(stride);
+
+  let rawOffset = 0;
+
+  for (let y = 0; y < height; y++) {
+    const filterType = raw[rawOffset++]!;
+
+    for (let x = 0; x < stride; x++) {
+      currRow[x] = raw[rawOffset++]!;
+    }
+
+    for (let x = 0; x < stride; x++) {
+      const left = x >= bpp ? currRow[x - bpp]! : 0;
+      const up = prevRow[x]!;
+      const upperLeft = x >= bpp ? prevRow[x - bpp]! : 0;
+
+      switch (filterType) {
+        case 0:
+          break;
+        case 1:
+          currRow[x] = (currRow[x]! + left) & 0xff;
+          break;
+        case 2:
+          currRow[x] = (currRow[x]! + up) & 0xff;
+          break;
+        case 3:
+          currRow[x] = (currRow[x]! + ((left + up) >> 1)) & 0xff;
+          break;
+        case 4:
+          currRow[x] = (currRow[x]! + paethPredictor(left, up, upperLeft)) &
+            0xff;
+          break;
+        default:
+          throw new Error(`Unknown filter type: ${filterType}`);
+      }
+    }
+
+    const rowStart = y * width * 4;
+    if (bpp === 4) {
+      pixels.set(currRow, rowStart);
+    } else {
+      for (let x = 0; x < width; x++) {
+        pixels[rowStart + x * 4] = currRow[x * 3]!;
+        pixels[rowStart + x * 4 + 1] = currRow[x * 3 + 1]!;
+        pixels[rowStart + x * 4 + 2] = currRow[x * 3 + 2]!;
+        pixels[rowStart + x * 4 + 3] = 255;
+      }
+    }
+
+    prevRow.set(currRow);
+  }
+
+  return { width, height, pixels };
+}

package/src/{service/printer/terminal → terminal}/Styler.ts

@@ -1,5 +1,8 @@
 export default interface Styler {
   colorEnabled: boolean;
+  hyperlinksEnabled: boolean;
   colorText(text: string, colorValue: number): string;
+  backgroundColorText(text: string, colorValue: number): string;
   italicText(text: string): string;
+  hyperlink(text: string, url: string): string;
 }

package/src/{service/printer/terminal → terminal}/Terminal.ts

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

package/src/terminal/TtyKeyReader.ts

@@ -0,0 +1,83 @@
+import { ReadStream } from "node:tty";
+import { Buffer } from "node:buffer";
+import type KeyReader from "./KeyReader.ts";
+import { type KeyEvent, SpecialKey } from "./KeyReader.ts";
+
+export default class TtyKeyReader implements KeyReader {
+  readonly #ttyReadStream: ReadStream;
+
+  constructor(ttyReadStream: ReadStream) {
+    if (ttyReadStream.isTTY === false) {
+      throw new Error("The provided ReadStream is not a TTY");
+    }
+    this.#ttyReadStream = ttyReadStream;
+  }
+
+  enableRawMode(): void {
+    this.#ttyReadStream.setRawMode(true);
+    this.#ttyReadStream.resume();
+  }
+
+  disableRawMode(): void {
+    this.#ttyReadStream.setRawMode(false);
+    this.#ttyReadStream.pause();
+  }
+
+  readKey(): Promise<KeyEvent> {
+    return new Promise((resolve) => {
+      const onData = (data: Buffer): void => {
+        this.#ttyReadStream.removeListener("data", onData);
+        resolve(TtyKeyReader.#decodeKeyEvent(data));
+      };
+      this.#ttyReadStream.on("data", onData);
+    });
+  }
+
+  static #decodeKeyEvent(data: Buffer): KeyEvent {
+    if (data.length === 0) {
+      return {};
+    }
+
+    // escape sequences
+    if (data[0] === 0x1b) {
+      if (data.length === 1) {
+        return { specialKey: SpecialKey.ESCAPE };
+      }
+      if (data.length >= 3 && data[1] === 0x5b) {
+        switch (data[2]) {
+          case 0x41:
+            return { specialKey: SpecialKey.UP };
+          case 0x42:
+            return { specialKey: SpecialKey.DOWN };
+          case 0x43:
+            return { specialKey: SpecialKey.RIGHT };
+          case 0x44:
+            return { specialKey: SpecialKey.LEFT };
+        }
+      }
+      return { specialKey: SpecialKey.ESCAPE };
+    }
+
+    // control characters
+    switch (data[0]) {
+      case 0x0d:
+        return { specialKey: SpecialKey.ENTER };
+      case 0x20:
+        return { specialKey: SpecialKey.SPACE };
+      case 0x7f:
+        return { specialKey: SpecialKey.BACKSPACE };
+      case 0x09:
+        return { specialKey: SpecialKey.TAB };
+      case 0x03:
+        return { specialKey: SpecialKey.INTERRUPT };
+    }
+
+    // printable characters
+    const str = data.toString("utf8");
+    if (str.length > 0) {
+      return { key: str };
+    }
+
+    return {};
+  }
+}

package/src/terminal/TtyStyler.ts

@@ -0,0 +1,78 @@
+import {
+  BACKGROUND_COLOR_END,
+  FOREGROUND_COLOR_END,
+  HYPERLINK_END,
+  hyperlinkStart,
+  ITALIC_END,
+  ITALIC_START,
+} from "./Ansi.ts";
+import type Styler from "./Styler.ts";
+
+export default class TtyStyler implements Styler {
+  colorEnabled: boolean = true;
+  hyperlinksEnabled: boolean;
+
+  readonly colorLevel: number;
+
+  /**
+   * The color level in use.
+   *
+   * 1 = 16 color
+   * 2 = 256 color
+   * 3 = 16 million color
+   */
+  constructor(colorLevel: number = 1, hyperlinksEnabled: boolean = true) {
+    this.colorLevel = colorLevel;
+    this.hyperlinksEnabled = hyperlinksEnabled;
+  }
+
+  colorText(text: string, colorValue: number): string {
+    if (!this.colorEnabled) {
+      return text;
+    }
+
+    if (this.colorLevel === 3) {
+      return Bun.color(colorValue, "ansi-16m") + text + FOREGROUND_COLOR_END;
+    }
+
+    if (this.colorLevel === 2) {
+      return Bun.color(colorValue, "ansi-256") + text + FOREGROUND_COLOR_END;
+    }
+
+    return Bun.color(colorValue, "ansi-16") + text + FOREGROUND_COLOR_END;
+  }
+
+  backgroundColorText(text: string, colorValue: number): string {
+    if (!this.colorEnabled) {
+      return text;
+    }
+
+    if (this.colorLevel === 3) {
+      const r = (colorValue >> 16) & 0xFF;
+      const g = (colorValue >> 8) & 0xFF;
+      const b = colorValue & 0xFF;
+      return `\x1b[48;2;${r};${g};${b}m${text}${BACKGROUND_COLOR_END}`;
+    }
+
+    if (this.colorLevel === 2) {
+      return Bun.color(colorValue, "ansi-256")!.replace("[38;", "[48;") + text +
+        BACKGROUND_COLOR_END;
+    }
+
+    return Bun.color(colorValue, "ansi-16")!.replace(
+      /\[(\d+)m/,
+      (_, n) => `[${Number(n) + 10}m`,
+    ) + text + BACKGROUND_COLOR_END;
+  }
+
+  italicText(text: string): string {
+    return ITALIC_START + text + ITALIC_END;
+  }
+
+  hyperlink(text: string, url: string): string {
+    if (!this.hyperlinksEnabled) {
+      return `${text}: ${url}`;
+    }
+    return hyperlinkStart(url) + text + HYPERLINK_END;
+  }
+}

package/src/{service/printer/terminal → terminal}/TtyTerminal.ts

@@ -57,9 +57,17 @@ export default class TtyTerminal implements Terminal {
 
   columns(): number {
     try {
-      return this.#ttyWriteStream.columns;
+      return this.#ttyWriteStream.columns || 80;
     } catch {
       return 80;
     }
   }
+
+  rows(): number {
+    try {
+      return this.#ttyWriteStream.rows || 24;
+    } catch {
+      return 24;
+    }
+  }
 }

package/src/terminal/supportsHyperlinks.ts

@@ -0,0 +1,110 @@
+import process from "node:process";
+import type { WriteStream } from "node:tty";
+
+function parseVersion(versionString = ""): {
+  major: number;
+  minor: number;
+  patch: number;
+} {
+  if (/^\d{3,4}$/.test(versionString)) {
+    const match = /(\d{1,2})(\d{2})/.exec(versionString) ?? [];
+    return {
+      major: 0,
+      minor: Number.parseInt(match[1] ?? "0", 10),
+      patch: Number.parseInt(match[2] ?? "0", 10),
+    };
+  }
+
+  const versions = (versionString ?? "").split(".").map((n) =>
+    Number.parseInt(n, 10)
+  );
+  return {
+    major: versions[0] ?? 0,
+    minor: versions[1] ?? 0,
+    patch: versions[2] ?? 0,
+  };
+}
+
+export default function supportsHyperlinks(
+  stream: WriteStream | undefined,
+): boolean {
+  const {
+    CI,
+    CURSOR_TRACE_ID,
+    FORCE_HYPERLINK,
+    TEAMCITY_VERSION,
+    TERM_PROGRAM,
+    TERM_PROGRAM_VERSION,
+    VTE_VERSION,
+    TERM,
+  } = process.env;
+
+  if (FORCE_HYPERLINK) {
+    return !(FORCE_HYPERLINK.length > 0 &&
+      Number.parseInt(FORCE_HYPERLINK, 10) === 0);
+  }
+
+  if (stream && !stream.isTTY) {
+    return false;
+  }
+
+  if ("WT_SESSION" in process.env) {
+    return true;
+  }
+
+  if (CI) {
+    return false;
+  }
+
+  if (TEAMCITY_VERSION) {
+    return false;
+  }
+
+  if (TERM_PROGRAM) {
+    const version = parseVersion(TERM_PROGRAM_VERSION);
+
+    switch (TERM_PROGRAM) {
+      case "iTerm.app": {
+        if (version.major === 3) {
+          return version.minor >= 1;
+        }
+        return version.major > 3;
+      }
+      case "WezTerm": {
+        if (/^0-unstable-\d{4}-\d{2}-\d{2}$/.test(TERM_PROGRAM_VERSION!)) {
+          const date = TERM_PROGRAM_VERSION!.slice("0-unstable-".length);
+          return date >= "2020-06-20";
+        }
+        return version.major >= 20200620;
+      }
+      case "vscode": {
+        if (CURSOR_TRACE_ID) {
+          return true;
+        }
+        return version.major > 1 ||
+          (version.major === 1 && version.minor >= 72);
+      }
+      case "ghostty":
+        return true;
+      case "zed":
+        return true;
+    }
+  }
+
+  if (VTE_VERSION) {
+    if (VTE_VERSION === "0.50.0") {
+      return false;
+    }
+    const version = parseVersion(VTE_VERSION);
+    return version.major > 0 || version.minor >= 50;
+  }
+
+  switch (TERM) {
+    case "alacritty":
+      return true;
+    case "xterm-kitty":
+      return true;
+  }
+
+  return false;
+}

package/src/util/configHelper.ts

@@ -9,7 +9,7 @@ function getKeySegment(segment: string, isCustom = false, isArray = false) {
   let keySegment = segment;
   if (!isCustom) {
     keySegment = keySegment.replace("-", "_").toUpperCase();
-    if (keySegment[0].match(/[0-9]/)) {
+    if (keySegment[0]!.match(/[0-9]/)) {
       keySegment = `_${keySegment}`;
     }
   }
@@ -43,7 +43,7 @@ export function getSubCommandArgumentConfigurationKey(
   }
 
   const keySegments: Array<string> = [];
-  const firstArgument = argumentAncestry[0];
+  const firstArgument = argumentAncestry[0]!;
   if (firstArgument.configurationKey === undefined) {
     keySegments.push(getKeySegment(cliConfig.name));
     keySegments.push(getKeySegment(command.name));