@flowscripter/dynamic-cli-framework 1.0.0

package/src/service/printer/terminal/Progress.ts

@@ -0,0 +1,373 @@
+import Styler from "./Styler.ts";
+import type Terminal from "./Terminal.ts";
+
+const RATE_SMOOTHING_FACTOR = 0.005;
+
+interface Bar {
+  name: string;
+  current: number;
+  total: number;
+  units: string;
+  lastMillis?: number;
+  startMillis?: number;
+  endMillis?: number;
+  rate?: number;
+}
+
+export default class Progress {
+  readonly #terminal: Terminal;
+  readonly #styler: Styler;
+  readonly #bars: Map<number, Bar> = new Map();
+  #timer: Timer | undefined;
+  #isDirty = false;
+  #currentRenderedBarCount = 0;
+  #lastRenderTime = 0;
+  #comColor = 0x5f8700;
+  #remColor = 0x585858;
+  #labColor = 0x585858;
+  #valColor = 0x808080;
+
+  public constructor(terminal: Terminal, styler: Styler) {
+    this.#terminal = terminal;
+    this.#styler = styler;
+  }
+
+  public add(
+    units: string,
+    message: string,
+    total: number,
+    current: number,
+  ): number {
+    if (total < 0) {
+      total = 100;
+    }
+    if (current < 0) {
+      current = 0;
+    }
+    if (current > total) {
+      current = total;
+    }
+
+    this.#bars.set(this.#bars.size + 1, {
+      name: message,
+      current,
+      total,
+      units,
+      startMillis: Date.now(),
+    });
+
+    // force render on next timeout
+    this.#isDirty = true;
+
+    // start rendering timer
+    if (this.#timer === undefined) {
+      this.#timer = setInterval(async () => {
+        await this.#renderBars();
+      }, 100);
+    }
+
+    return this.#bars.size;
+  }
+
+  #updateRate(bar: Bar, current: number): void {
+    const now = Date.now();
+    if (bar.lastMillis === undefined) {
+      bar.rate = ((current - bar.current) * 1000) / (now - bar.startMillis!);
+    } else {
+      let currentRate = ((current - bar.current) * 1000) /
+        (now - bar.lastMillis!);
+      if (!isFinite(currentRate)) {
+        currentRate = 0;
+      }
+      bar.rate = (currentRate * RATE_SMOOTHING_FACTOR) +
+        (bar.rate! * (1 - RATE_SMOOTHING_FACTOR));
+    }
+    bar.lastMillis = now;
+  }
+
+  public update(handle: number, current: number, message?: string): void {
+    if (!this.#bars.has(handle)) {
+      return;
+    }
+    const bar = this.#bars.get(handle)!;
+    if (current < 0) {
+      current = 0;
+    }
+    if (current > bar.total) {
+      current = bar.total;
+    }
+    if ((current === bar.total) && (bar.endMillis === undefined)) {
+      bar.endMillis = Date.now();
+    }
+
+    this.#updateRate(bar, current);
+
+    bar.current = current;
+
+    if (message !== undefined) {
+      bar.name = message;
+    }
+
+    // force render on next timeout
+    this.#isDirty = true;
+  }
+
+  public async hide(handle: number): Promise<void> {
+    // clear specified bar
+    if (this.#bars.has(handle)) {
+      this.#bars.delete(handle);
+    }
+
+    // if no more bars, effectively this is a pause
+    if (this.#bars.size === 0) {
+      await this.pause();
+
+      return;
+    }
+
+    // otherwise, force render on next timeout
+    this.#isDirty = true;
+  }
+
+  public async hideAll(): Promise<void> {
+    // clear all bars
+    this.#bars.clear();
+
+    await this.pause();
+  }
+
+  public async pause(): Promise<void> {
+    if (this.#timer === undefined) {
+      return;
+    }
+
+    this.#isDirty = false;
+
+    // stop rendering timer
+    clearInterval(this.#timer);
+    this.#timer = undefined;
+
+    // clear the previously rendered bars
+    await this.#terminal.clearUpLines(this.#currentRenderedBarCount * 2);
+
+    this.#currentRenderedBarCount = 0;
+
+    // restore the cursor
+    await this.#terminal.showCursor();
+  }
+
+  public resume(): void {
+    // don't resume if nothing to render
+    if (this.#bars.size === 0) {
+      return;
+    }
+
+    // force render on next timeout
+    this.#isDirty = true;
+
+    // start rendering timer
+    if (this.#timer === undefined) {
+      this.#timer = setInterval(async () => {
+        await this.#renderBars();
+      }, 100);
+    }
+  }
+
+  async #renderBars(): Promise<void> {
+    const now = Date.now();
+
+    // force render after one second to update newly calculated eta
+    if ((now - this.#lastRenderTime >= 1000) && !this.#isDirty) {
+      this.#bars.forEach((bar) => this.#updateRate(bar, bar.current));
+      this.#isDirty = true;
+    }
+
+    // don't render if we don't need to
+    if (!this.#isDirty) {
+      return;
+    }
+
+    this.#lastRenderTime = now;
+
+    const consoleWidth = this.#terminal.columns();
+    const lines: Array<string> = [];
+
+    const barInfo: Array<
+      {
+        name: string;
+        prefix: string;
+        available: number;
+        suffix: string;
+        bar: Bar;
+      }
+    > = [];
+
+    this.#bars.forEach((bar) => {
+      const name = `${this.#styler.colorText(bar.name, this.#valColor)}${
+        this.#styler.colorText(":", this.#labColor)
+      }`;
+      const prefix = `${this.#styler.colorText("[", this.#labColor)}`;
+      let visibleWidth = 1;
+      const percentString = ((bar.current / bar.total) * 100).toFixed(2);
+      const percent = this.#styler.colorText(
+        percentString,
+        this.#valColor,
+      ) + this.#styler.colorText("%,", this.#labColor);
+      visibleWidth += percentString.length + 1;
+
+      const rate = `${
+        this.#styler.colorText(
+          (bar.rate === undefined) ? "-" : bar.rate.toFixed(2) + "",
+          this.#valColor,
+        )
+      }`;
+
+      let suffix = `${this.#styler.colorText("]", this.#labColor)} ${percent} `;
+      visibleWidth += 3;
+      if (bar.current === bar.total) {
+        const taken = this.#formatTime(bar.endMillis! - bar.startMillis!);
+        const totalString = bar.total + "";
+        suffix += `${this.#styler.colorText(totalString, this.#valColor)}${
+          this.#styler.colorText(bar.units + ", rate:", this.#labColor)
+        } ${rate}${
+          this.#styler.colorText(
+            bar.units + "/s, time taken:",
+            this.#labColor,
+          )
+        } ${taken}`;
+        visibleWidth + totalString.length + bar.units.length + 7 + 1 +
+          rate.length + bar.units.length + 15 + 1 + taken.length;
+      } else {
+        const remaining = ((bar.rate === undefined) || (bar.rate === 0))
+          ? "-"
+          : this.#formatTime(((bar.total - bar.current) / bar.rate) * 1000);
+        const currentString = bar.current + "";
+        const totalString = bar.total + "";
+        suffix += `${this.#styler.colorText(currentString, this.#valColor)}${
+          this.#styler.colorText("/", this.#labColor)
+        }${this.#styler.colorText(totalString, this.#valColor)}${
+          this.#styler.colorText(bar.units + ", rate:", this.#labColor)
+        } ${rate}${
+          this.#styler.colorText(
+            bar.units + "/s, time remaining:",
+            this.#labColor,
+          )
+        } ${remaining}`;
+        visibleWidth + currentString.length + 1 + totalString.length +
+          bar.units.length + 7 + 1 + rate.length + bar.units.length + 19 + 1 +
+          remaining.length;
+      }
+      let available = consoleWidth - visibleWidth;
+      if (available < 0) {
+        available = 0;
+      }
+      barInfo.push({
+        name,
+        prefix,
+        available,
+        suffix,
+        bar,
+      });
+    });
+
+    let totalLength = consoleWidth;
+    barInfo.forEach((barInfo) => {
+      if (barInfo.available < totalLength) {
+        totalLength = barInfo.available;
+      }
+    });
+    totalLength = Math.min(50, totalLength);
+
+    barInfo.forEach((barInfo) => {
+      const completeLength = Math.floor(
+        totalLength * barInfo.bar.current / barInfo.bar.total,
+      );
+      const complete = this.#styler.colorText(
+        "=".repeat(completeLength),
+        this.#comColor,
+      );
+      const remaining = this.#styler.colorText(
+        "-".repeat(totalLength - completeLength),
+        this.#remColor,
+      );
+
+      lines.push(barInfo.name);
+      lines.push(barInfo.prefix + complete + remaining + barInfo.suffix);
+    });
+
+    // hide the cursor before rendering
+    await this.#terminal.hideCursor();
+
+    // clear the previously rendered bars
+    await this.#terminal.clearUpLines(this.#currentRenderedBarCount * 2);
+
+    // rendere the new bars
+    await this.#terminal.write(lines.join("\n") + "\n");
+
+    // save count rendered bars so we can clear on the next render cycle
+    this.#currentRenderedBarCount = barInfo.length;
+
+    // show the cursor if there are no bars or the timer is not running
+    if (this.#bars.size === 0 || this.#timer === undefined) {
+      await this.#terminal.showCursor();
+    }
+
+    this.#isDirty = false;
+  }
+
+  set completeColor(color: number) {
+    this.#comColor = color;
+  }
+
+  set remainingColor(color: number) {
+    this.#remColor = color;
+  }
+
+  set labelColor(color: number) {
+    this.#labColor = color;
+  }
+
+  set valueColor(color: number) {
+    this.#valColor = color;
+  }
+
+  #formatTime(millis: number): string {
+    let sec = millis / 1000;
+    if (sec < 60) {
+      return `${this.#styler.colorText(sec.toFixed(0), this.#valColor)}${
+        this.#styler.colorText("s", this.#labColor)
+      }`;
+    }
+    let min = Math.floor(sec / 60);
+    sec %= 60;
+    if (min < 60) {
+      return `${this.#styler.colorText(min.toFixed(0), this.#valColor)}${
+        this.#styler.colorText("m", this.#labColor)
+      } ${this.#styler.colorText(sec.toFixed(0), this.#valColor)}${
+        this.#styler.colorText("s", this.#labColor)
+      }`;
+    }
+    let hour = Math.floor(min / 60);
+    min %= 60;
+    if (hour < 24) {
+      return `${this.#styler.colorText(hour.toFixed(0), this.#valColor)}${
+        this.#styler.colorText("h", this.#labColor)
+      } ${this.#styler.colorText(min.toFixed(0), this.#valColor)}${
+        this.#styler.colorText("m", this.#labColor)
+      } ${this.#styler.colorText(sec.toFixed(0), this.#valColor)}${
+        this.#styler.colorText("s", this.#labColor)
+      }`;
+    }
+    const day = Math.floor(hour / 24);
+    hour %= 24;
+    return `${this.#styler.colorText(day.toFixed(0), this.#valColor)}${
+      this.#styler.colorText("d", this.#labColor)
+    } ${this.#styler.colorText(hour.toFixed(0), this.#valColor)}${
+      this.#styler.colorText("h", this.#labColor)
+    } ${this.#styler.colorText(min.toFixed(0), this.#valColor)}${
+      this.#styler.colorText("m", this.#labColor)
+    } ${this.#styler.colorText(sec.toFixed(0), this.#valColor)}${
+      this.#styler.colorText("s", this.#labColor)
+    }`;
+  }
+}

package/src/service/printer/terminal/Spinner.ts

@@ -0,0 +1,100 @@
+import Styler from "./Styler.ts";
+import type Terminal from "./Terminal.ts";
+
+const FRAMES = [
+  "⠋",
+  "⠙",
+  "⠹",
+  "⠸",
+  "⠼",
+  "⠴",
+  "⠦",
+  "⠧",
+  "⠇",
+  "⠏",
+];
+
+export default class Spinner {
+  #isShown = false;
+  #message: string | undefined;
+  #frameIndex = 0;
+  #timer: Timer | undefined;
+  #spinColor = 0x8a8a8a;
+  #msgColor = 0x808080;
+  readonly #terminal: Terminal;
+  readonly #styler: Styler;
+
+  public constructor(terminal: Terminal, styler: Styler) {
+    this.#terminal = terminal;
+    this.#styler = styler;
+  }
+
+  async #nextFrame(): Promise<void> {
+    if (!this.#isShown) {
+      return;
+    }
+    await this.#terminal.clearLine();
+    if (this.#message) {
+      await this.#terminal.write(
+        `${this.#styler.colorText(FRAMES[this.#frameIndex], this.#spinColor)} ${
+          this.#styler.colorText(this.#message!, this.#msgColor)
+        }`,
+      );
+    } else {
+      await this.#terminal.write(
+        this.#styler.colorText(FRAMES[this.#frameIndex], this.#spinColor),
+      );
+    }
+    this.#frameIndex = (this.#frameIndex + 1) % FRAMES.length;
+  }
+
+  public async show(message?: string): Promise<void> {
+    this.#message = message;
+    if (this.#isShown) {
+      return Promise.resolve();
+    }
+    this.#isShown = true;
+    this.#frameIndex = 0;
+    this.#timer = setInterval(async () => {
+      await this.#nextFrame();
+    }, 100);
+    await this.#terminal.hideCursor();
+  }
+
+  public async hide(): Promise<void> {
+    if (!this.#isShown) {
+      return Promise.resolve();
+    }
+    this.#isShown = false;
+    clearInterval(this.#timer);
+    await this.#terminal.clearLine();
+    await this.#terminal.showCursor();
+    this.#message = undefined;
+  }
+
+  public async pause(): Promise<void> {
+    if (!this.#isShown) {
+      return Promise.resolve();
+    }
+    clearInterval(this.#timer);
+    this.#timer = undefined;
+    await this.#terminal.clearLine();
+  }
+
+  public resume(): void {
+    if ((!this.#isShown) || (this.#timer !== undefined)) {
+      return;
+    }
+    this.#timer = setInterval(async () => {
+      await this.#nextFrame();
+    }, 100);
+  }
+
+  set spinnerColor(color: number) {
+    this.#spinColor = color;
+  }
+
+  set messageColor(color: number) {
+    this.#msgColor = color;
+  }
+}

package/src/service/printer/terminal/Styler.ts

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

package/src/service/printer/terminal/Terminal.ts

@@ -0,0 +1,8 @@
+export default interface Terminal {
+  clearLine(): Promise<void>;
+  clearUpLines(count: number): Promise<void>;
+  hideCursor(): Promise<void>;
+  showCursor(): Promise<void>;
+  write(text: string): Promise<void>;
+  columns(): number;
+}

package/src/service/printer/terminal/Theme.ts

@@ -0,0 +1,34 @@
+import { Color } from "./Color";
+
+const commonTheme: Array<number> = [];
+
+commonTheme[Color.YELLOW] = 0xb58900;
+commonTheme[Color.ORANGE] = 0xcb4b16;
+commonTheme[Color.RED] = 0xdc322f;
+commonTheme[Color.MAGENTA] = 0xd33682;
+commonTheme[Color.VIOLET] = 0x6c71c4;
+commonTheme[Color.BLUE] = 0x268bd2;
+commonTheme[Color.CYAN] = 0x2aa198;
+commonTheme[Color.GREEN] = 0x859900;
+
+export function getLightModeTheme(): Array<number> {
+  const lightModeTheme: Array<number> = [...commonTheme];
+
+  lightModeTheme[Color.PRIMARY] = 0x657b83;
+  lightModeTheme[Color.SECONDARY] = 0x93a1a1;
+  lightModeTheme[Color.EMPHASISED] = 0x586e75;
+  lightModeTheme[Color.SELECTED] = 0xeee8d5;
+
+  return lightModeTheme;
+}
+
+export function getDarkModeTheme(): Array<number> {
+  const darkModeTheme: Array<number> = [...commonTheme];
+
+  darkModeTheme[Color.PRIMARY] = 0x839496;
+  darkModeTheme[Color.SECONDARY] = 0x586e75;
+  darkModeTheme[Color.EMPHASISED] = 0x93a1a1;
+  darkModeTheme[Color.SELECTED] = 0x073642;
+
+  return darkModeTheme;
+}

package/src/service/printer/terminal/TtyStyler.ts

@@ -0,0 +1,39 @@
+import { COLOR_END, ITALIC_END, ITALIC_START } from "./Ansi.ts";
+import Styler from "./Styler.ts";
+
+export default class TtyStyler implements Styler {
+  colorEnabled: boolean = true;
+
+  readonly colorLevel: number;
+
+  /**
+   * The color level in use.
+   *
+   * 1 = 16 color
+   * 2 = 256 color
+   * 3 = 16 million color
+   */
+  constructor(colorLevel: number = 1) {
+    this.colorLevel = colorLevel;
+  }
+
+  colorText(text: string, colorValue: number): string {
+    if (!this.colorEnabled) {
+      return text;
+    }
+
+    if (this.colorLevel === 3) {
+      return Bun.color(colorValue, "ansi-16m") + text + COLOR_END;
+    }
+
+    if (this.colorLevel === 2) {
+      return Bun.color(colorValue, "ansi-256") + text + COLOR_END;
+    }
+
+    return Bun.color(colorValue, "ansi-16") + text + COLOR_END;
+  }
+
+  italicText(text: string): string {
+    return ITALIC_START + text + ITALIC_END;
+  }
+}

package/src/service/printer/terminal/TtyTerminal.ts

@@ -0,0 +1,65 @@
+import { WriteStream } from "node:tty";
+import type Terminal from "./Terminal.ts";
+
+import {
+  CLEAR_LINE,
+  CURSOR_LEFT,
+  CURSOR_UP,
+  HIDE_CURSOR,
+  SHOW_CURSOR,
+} from "./Ansi.ts";
+
+export default class TtyTerminal implements Terminal {
+  readonly #ttyWriteStream: WriteStream;
+  readonly #encoder = new TextEncoder();
+
+  constructor(ttyWriteStream: WriteStream) {
+    if (ttyWriteStream.isTTY === false) {
+      throw new Error("The provided WriteStream is not a TTY");
+    }
+
+    this.#ttyWriteStream = ttyWriteStream;
+  }
+
+  #writeAll(message: string): void {
+    const encoded = this.#encoder.encode(message);
+
+    this.#ttyWriteStream.write(encoded);
+  }
+
+  clearLine(): Promise<void> {
+    this.#writeAll(CLEAR_LINE + CURSOR_LEFT);
+
+    return Promise.resolve();
+  }
+
+  clearUpLines(count: number): Promise<void> {
+    this.#writeAll(
+      (CURSOR_UP + CLEAR_LINE).repeat(count) + CLEAR_LINE + CURSOR_LEFT,
+    );
+    return Promise.resolve();
+  }
+
+  hideCursor(): Promise<void> {
+    this.#writeAll(HIDE_CURSOR);
+    return Promise.resolve();
+  }
+
+  showCursor(): Promise<void> {
+    this.#writeAll(SHOW_CURSOR);
+    return Promise.resolve();
+  }
+
+  write(text: string): Promise<void> {
+    this.#writeAll(text);
+    return Promise.resolve();
+  }
+
+  columns(): number {
+    try {
+      return this.#ttyWriteStream.columns;
+    } catch {
+      return 80;
+    }
+  }
+}

package/src/service/shutdown/DefaultShutdownService.ts

@@ -0,0 +1,9 @@
+import type ShutdownService from "../../api/service/core/ShutdownService.ts";
+
+export default class DefaultShutdownService implements ShutdownService {
+  static readonly callbacks: Array<() => Promise<void>> = [];
+
+  addShutdownListener(callback: () => Promise<void>): void {
+    DefaultShutdownService.callbacks.push(callback);
+  }
+}

package/src/service/shutdown/ShutdownServiceProvider.ts

@@ -0,0 +1,55 @@
+import process from "node:process";
+import type {
+  ServiceInfo,
+  ServiceProvider,
+} from "../../api/service/ServiceProvider.ts";
+import DefaultShutdownService from "./DefaultShutdownService.ts";
+import type ShutdownService from "../../api/service/core/ShutdownService.ts";
+import { SHUTDOWN_SERVICE_ID } from "../../api/service/core/ShutdownService.ts";
+import type Context from "../../api/Context.ts";
+import getLogger from "../../util/logger.ts";
+import type CLIConfig from "../../api/CLIConfig.ts";
+
+const logger = getLogger("ShutdownServiceProvider");
+
+/**
+ * Provides a {@link ShutdownService}.
+ */
+export default class ShutdownServiceProvider implements ServiceProvider {
+  readonly serviceId: string = SHUTDOWN_SERVICE_ID;
+  readonly #shutdownService: ShutdownService;
+
+  /**
+   * Create an instance of the service provider with the specified details.
+   *
+   * @param servicePriority the priority of the service.
+   */
+  public constructor(
+    readonly servicePriority: number,
+  ) {
+    this.#shutdownService = new DefaultShutdownService();
+    process.on("beforeExit", ShutdownServiceProvider.shutdown);
+  }
+
+  public provide(_cliConfig: CLIConfig): Promise<ServiceInfo> {
+    return Promise.resolve({
+      service: this.#shutdownService,
+      commands: [],
+    });
+  }
+
+  initService(_context: Context): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  static async shutdown() {
+    try {
+      process.removeListener("beforeExit", ShutdownServiceProvider.shutdown);
+      for await (const callback of DefaultShutdownService.callbacks) {
+        await callback();
+      }
+    } catch (error) {
+      logger.error("shutdown error: %s", (error as Error).message);
+    }
+  }
+}