@flowscripter/dynamic-cli-framework 11.0.0 → 12.0.0

package/src/service/printer/command/ThemeCommand.ts

@@ -0,0 +1,47 @@
+import type { GlobalModifierCommand } from "@flowscripter/dynamic-cli-framework-api";
+import type { GlobalCommandArgument } from "@flowscripter/dynamic-cli-framework-api";
+import { type SingleValueType, ValueTypeName } from "@flowscripter/dynamic-cli-framework-api";
+import type { Context } from "@flowscripter/dynamic-cli-framework-api";
+import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
+import { PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+
+/**
+ * Command allowing the specification of the dark/light theme for the {@link PrinterService}.
+ *
+ * With the `auto` value the terminal background is detected and light is used if it cannot be determined.
+ */
+export default class ThemeCommand implements GlobalModifierCommand {
+  readonly name = "theme";
+  readonly description = "Theme for output";
+  readonly enableConfiguration = true;
+  readonly argument: GlobalCommandArgument = {
+    type: ValueTypeName.STRING,
+    defaultValue: "auto",
+    allowableValues: ["auto", "dark", "light"],
+    configurationKey: "THEME",
+  };
+  readonly executePriority: number;
+  readonly #detect: (() => Promise<boolean | undefined>) | undefined;
+
+  /**
+   * @param executePriority the priority of the command.
+   * @param detect optional function detecting whether the terminal background is dark.
+   */
+  public constructor(executePriority: number, detect?: () => Promise<boolean | undefined>) {
+    this.executePriority = executePriority;
+    this.#detect = detect;
+  }
+
+  public async execute(context: Context, argumentValue: SingleValueType): Promise<void> {
+    const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
+
+    if (argumentValue === "auto") {
+      printerService.darkMode =
+        printerService.colorEnabled && this.#detect !== undefined
+          ? ((await this.#detect()) ?? false)
+          : false;
+    } else {
+      printerService.darkMode = argumentValue === "dark";
+    }
+  }
+}

package/src/terminal/Ansi.ts

@@ -1,6 +1,8 @@
-const CSI = "\x1b[";
-const OSC = "\x1b]";
-const BEL = "\x07";
+export const ESC = "\x1b";
+export const BEL = "\x07";
+const CSI = ESC + "[";
+const OSC = ESC + "]";
+const ST = ESC + "\\";
 const SEP = ";";
 
 export const CLEAR_LINE = CSI + "2K";
@@ -12,6 +14,8 @@ export const ITALIC_START = CSI + "3m";
 export const ITALIC_END = CSI + "23m";
 export const FOREGROUND_COLOR_END = CSI + "39m";
 export const BACKGROUND_COLOR_END = CSI + "49m";
+export const QUERY_BACKGROUND_COLOR = `${OSC}11;?${ST}`;
+export const QUERY_DEVICE_ATTRIBUTES = CSI + "c";
 export const HYPERLINK_END = `${OSC}8${SEP}${SEP}${BEL}`;
 
 export function foregroundColorStart(r: number, g: number, b: number): string {

package/src/terminal/BackgroundDetector.ts

@@ -0,0 +1,78 @@
+import process from "node:process";
+import type KeyReader from "./KeyReader.ts";
+import type Terminal from "./Terminal.ts";
+import { BEL, ESC, QUERY_BACKGROUND_COLOR, QUERY_DEVICE_ATTRIBUTES } from "./Ansi.ts";
+
+const OSC_11_REPLY = new RegExp(
+  `${ESC}\\]11;rgb:([0-9a-fA-F]{1,4})/([0-9a-fA-F]{1,4})/([0-9a-fA-F]{1,4})(?:${BEL}|${ESC}\\\\)`,
+);
+const DA1_REPLY = new RegExp(`${ESC}\\[\\?[0-9;]*c`);
+
+export const DEFAULT_DETECTION_TIMEOUT_MS = 150;
+
+/**
+ * Parse the COLORFGBG environment variable value into a dark background flag.
+ *
+ * @returns `true` for a dark background, `false` for a light background or `undefined` if not determinable.
+ */
+export function parseColorFgBg(value: string | undefined): boolean | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const parts = value.split(";");
+  const background = parts[parts.length - 1]!;
+  if (!/^\d{1,2}$/.test(background)) {
+    return undefined;
+  }
+  const index = Number(background);
+  if (index > 15) {
+    return undefined;
+  }
+  return index <= 6 || index === 8;
+}
+
+/**
+ * Parse an OSC 11 background colour reply into a dark background flag.
+ *
+ * @returns `true` for a dark background, `false` for a light background or `undefined` if no reply is present.
+ */
+export function parseOsc11Reply(data: string): boolean | undefined {
+  const match = OSC_11_REPLY.exec(data);
+  if (match === null) {
+    return undefined;
+  }
+  const [r, g, b] = [match[1]!, match[2]!, match[3]!].map(
+    (channel) => parseInt(channel, 16) / (16 ** channel.length - 1),
+  ) as [number, number, number];
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.5;
+}
+
+/**
+ * Detect whether the terminal background is dark.
+ *
+ * Checks COLORFGBG first and then queries the terminal for its background colour (OSC 11).
+ * The query is skipped unless the terminal is a TTY and is bounded by a timeout.
+ *
+ * @returns `true` for a dark background, `false` for a light background or `undefined` if not determinable.
+ */
+export async function detectDarkBackground(
+  keyReader: KeyReader,
+  terminal: Terminal,
+  env: Record<string, string | undefined> = process.env,
+  timeoutMs: number = DEFAULT_DETECTION_TIMEOUT_MS,
+): Promise<boolean | undefined> {
+  if (!terminal.isTty() || env.TERM === "dumb") {
+    return undefined;
+  }
+  const fromEnv = parseColorFgBg(env.COLORFGBG);
+  if (fromEnv !== undefined) {
+    return fromEnv;
+  }
+  try {
+    const reply = keyReader.readRaw((received) => DA1_REPLY.test(received), timeoutMs);
+    await terminal.write(QUERY_BACKGROUND_COLOR + QUERY_DEVICE_ATTRIBUTES);
+    return parseOsc11Reply(await reply);
+  } catch {
+    return undefined;
+  }
+}

package/src/terminal/KeyReader.ts

@@ -20,4 +20,11 @@ export default interface KeyReader {
   enableRawMode(): void;
   disableRawMode(): void;
   readKey(): Promise<KeyEvent>;
+  /**
+   * Read raw input until `isComplete` returns `true` for the accumulated input or `timeoutMs` elapses.
+   * Raw mode and paused state are restored afterwards.
+   *
+   * @returns the accumulated input.
+   */
+  readRaw(isComplete: (received: string) => boolean, timeoutMs: number): Promise<string>;
 }

package/src/terminal/TtyKeyReader.ts

@@ -52,6 +52,41 @@ export default class TtyKeyReader implements KeyReader {
     });
   }
 
+  readRaw(isComplete: (received: string) => boolean, timeoutMs: number): Promise<string> {
+    const stream = this.#ttyReadStream;
+    const wasRaw = stream.isRaw === true;
+    const wasPaused = stream.isPaused();
+
+    return new Promise((resolve) => {
+      let received = "";
+      let timer: ReturnType<typeof setTimeout>;
+
+      const finish = (): void => {
+        clearTimeout(timer);
+        stream.removeListener("data", onData);
+        if (!wasRaw) {
+          stream.setRawMode(false);
+        }
+        if (wasPaused) {
+          stream.pause();
+        }
+        resolve(received);
+      };
+
+      const onData = (data: Buffer | string): void => {
+        received += data.toString();
+        if (isComplete(received)) {
+          finish();
+        }
+      };
+
+      stream.setRawMode(true);
+      stream.on("data", onData);
+      stream.resume();
+      timer = setTimeout(finish, timeoutMs);
+    });
+  }
+
   static #decodeKeyEvent(data: Buffer): KeyEvent {
     if (data.length === 0) {
       return {};

package/dist/src/service/printer/command/DarkModeCommand.d.ts

@@ -1,17 +0,0 @@
-import type { GlobalModifierCommand } from "@flowscripter/dynamic-cli-framework-api";
-import type { GlobalCommandArgument } from "@flowscripter/dynamic-cli-framework-api";
-import { type SingleValueType } from "@flowscripter/dynamic-cli-framework-api";
-import type { Context } from "@flowscripter/dynamic-cli-framework-api";
-/**
- * Command allowing the specification of dark/light mode for the {@link PrinterService}.
- */
-export default class DarkModeCommand implements GlobalModifierCommand {
-    readonly name = "dark-mode";
-    readonly description = "Enable dark mode for output";
-    readonly enableConfiguration = true;
-    readonly argument: GlobalCommandArgument;
-    readonly executePriority: number;
-    constructor(executePriority: number);
-    execute(context: Context, argumentValue: SingleValueType): Promise<void>;
-}
-//# sourceMappingURL=DarkModeCommand.d.ts.map

package/dist/src/service/printer/command/DarkModeCommand.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DarkModeCommand.d.ts","sourceRoot":"","sources":["../../../../../src/service/printer/command/DarkModeCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,yCAAyC,CAAC;AAC9F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAIvE;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,YAAW,qBAAqB;IACnE,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,WAAW,iCAAiC;IACrD,QAAQ,CAAC,mBAAmB,QAAQ;IACpC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAItC;IACF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,YAAmB,eAAe,EAAE,MAAM,EAEzC;IAEM,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9E;CACF"}

package/dist/src/service/printer/command/DarkModeCommand.js

@@ -1,24 +0,0 @@
-import { ValueTypeName } from "@flowscripter/dynamic-cli-framework-api";
-import { PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
-/**
- * Command allowing the specification of dark/light mode for the {@link PrinterService}.
- */
-export default class DarkModeCommand {
-    name = "dark-mode";
-    description = "Enable dark mode for output";
-    enableConfiguration = true;
-    argument = {
-        type: ValueTypeName.BOOLEAN,
-        defaultValue: false,
-        configurationKey: "DARK_MODE",
-    };
-    executePriority;
-    constructor(executePriority) {
-        this.executePriority = executePriority;
-    }
-    execute(context, argumentValue) {
-        const printerService = context.getServiceById(PRINTER_SERVICE_ID);
-        printerService.darkMode = argumentValue;
-        return Promise.resolve();
-    }
-}

package/src/service/printer/command/DarkModeCommand.ts

@@ -1,32 +0,0 @@
-import type { GlobalModifierCommand } from "@flowscripter/dynamic-cli-framework-api";
-import type { GlobalCommandArgument } from "@flowscripter/dynamic-cli-framework-api";
-import { type SingleValueType, ValueTypeName } from "@flowscripter/dynamic-cli-framework-api";
-import type { Context } from "@flowscripter/dynamic-cli-framework-api";
-import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
-import { PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
-
-/**
- * Command allowing the specification of dark/light mode for the {@link PrinterService}.
- */
-export default class DarkModeCommand implements GlobalModifierCommand {
-  readonly name = "dark-mode";
-  readonly description = "Enable dark mode for output";
-  readonly enableConfiguration = true;
-  readonly argument: GlobalCommandArgument = {
-    type: ValueTypeName.BOOLEAN,
-    defaultValue: false,
-    configurationKey: "DARK_MODE",
-  };
-  readonly executePriority: number;
-
-  public constructor(executePriority: number) {
-    this.executePriority = executePriority;
-  }
-
-  public execute(context: Context, argumentValue: SingleValueType): Promise<void> {
-    const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
-    printerService.darkMode = argumentValue as boolean;
-
-    return Promise.resolve();
-  }
-}