@flowscripter/dynamic-cli-framework-api 1.0.0

package/src/service/core/PrinterService.ts

@@ -0,0 +1,446 @@
+export const PRINTER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/printer-service";
+import { WritableStream } from "node:stream/web";
+
+/**
+ * Enum of message importance level.
+ */
+export enum Level {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+/**
+ * Enum of spinner animation styles.
+ */
+export enum SpinnerStyle {
+  BOX = "BOX",
+  STAR = "STAR",
+}
+
+/**
+ * Enum of progress bar rendering styles.
+ */
+export enum ProgressStyle {
+  STROKE = "STROKE",
+  FILL = "FILL",
+}
+
+/**
+ * Enum of message icons.
+ */
+export enum Icon {
+  // Will be displayed in green if {@link Printer.colorEnabled} is `true`.
+  SUCCESS = 0,
+  // Will be displayed in red if {@link Printer.colorEnabled} is `true`.
+  FAILURE = 1,
+  // Will be displayed in yellow if {@link Printer.colorEnabled} is `true`.
+  ALERT = 2,
+  // Will be displayed in blue if {@link Printer.colorEnabled} is `true`.
+  INFORMATION = 3,
+}
+
+/**
+ * Service allowing a {@link Command} to output user messages to `stdout` and/or `stderr`.
+ *
+ * Output to `stdout` is via {@link print} whilst output to `stderr` is via a filtered logging mechanism
+ * using {@link debug}, {@link info}, {@link warn} and {@link error}.
+ */
+export default interface PrinterService {
+  /**
+   * Disable or enable color output for messages.
+   */
+  colorEnabled: boolean;
+
+  /**
+   * Disable or enable hyperlink output for messages.
+   */
+  hyperlinksEnabled: boolean;
+
+  /**
+   * Enable or disable dark mode. Default is disabled i.e. `false`.
+   */
+  darkMode: boolean;
+
+  /**
+   * The WritableStream used for `stdout`. Can be accessed directly for output of binary data etc.
+   */
+  stdoutWritable: WritableStream;
+
+  /**
+   * The WritableStream used for `stderr`. Can be accessed directly for output of binary data etc.
+   */
+  stderrWritable: WritableStream;
+
+  /**
+   * Return the provided message so that the foreground is colored as primary content. This is the default
+   * calor applied. The actual color will depend on the value of {@link darkMode}.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  primary(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is colored as secondary content.
+   * The actual color will depend on the value of {@link darkMode}.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  secondary(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is colored as emphasised content.
+   * The actual color will depend on the value of {@link darkMode}.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  emphasised(message: string): string;
+
+  /**
+   * Return the provided message so that the background is colored as selected content.
+   * The actual color will depend on the value of {@link darkMode}.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  selected(message: string): string;
+
+  /**
+   * Return the provided message so that the text is displayed in italic.
+   */
+  italic(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is yellow.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  yellow(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is orange.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  orange(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is red.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  red(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is magenta.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  magenta(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is violet.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  violet(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is blue.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  blue(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is cyan.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  cyan(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is green.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  green(message: string): string;
+
+  /**
+   * Return the provided message so that the foreground is the specified color.
+   * Has no effect if {@link colorEnabled} is `false`.
+   *
+   * @param message the message to color.
+   * @param hexFormattedColor the color to use. This should be a valid hex formatted string e.g. "#rrggbb".
+   */
+  color(message: string, hexFormattedColor: string): string;
+
+  /**
+   * Return the provided message so that the background is colored as primary content.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundPrimary(message: string): string;
+
+  /**
+   * Return the provided message so that the background is colored as secondary content.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundSecondary(message: string): string;
+
+  /**
+   * Return the provided message so that the background is colored as emphasised content.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundEmphasised(message: string): string;
+
+  /**
+   * Return the provided message so that the background is colored as selected content.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundSelected(message: string): string;
+
+  /**
+   * Return the provided message so that the background is yellow.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundYellow(message: string): string;
+
+  /**
+   * Return the provided message so that the background is orange.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundOrange(message: string): string;
+
+  /**
+   * Return the provided message so that the background is red.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundRed(message: string): string;
+
+  /**
+   * Return the provided message so that the background is magenta.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundMagenta(message: string): string;
+
+  /**
+   * Return the provided message so that the background is violet.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundViolet(message: string): string;
+
+  /**
+   * Return the provided message so that the background is blue.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundBlue(message: string): string;
+
+  /**
+   * Return the provided message so that the background is cyan.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundCyan(message: string): string;
+
+  /**
+   * Return the provided message so that the background is green.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  backgroundGreen(message: string): string;
+
+  /**
+   * Return the provided message so that the background is the specified color.
+   * Has no effect if {@link colorEnabled} is `false`.
+   *
+   * @param message the message to color.
+   * @param hexFormattedColor the color to use. This should be a valid hex formatted string e.g. "#rrggbb".
+   */
+  backgroundColor(message: string, hexFormattedColor: string): string;
+
+  /**
+   * Return the provided text wrapped in an OSC 8 hyperlink to the specified URL.
+   * Has no effect if {@link hyperlinksEnabled} is `false`, in which case the text is returned unchanged.
+   *
+   * @param text the text to display as the hyperlink.
+   * @param url the URL target of the hyperlink.
+   */
+  hyperlink(text: string, url: string): string;
+
+  /**
+   * Start a quoted, indented block of output. While active, every line written via {@link print},
+   * {@link debug}, {@link info}, {@link warn} or {@link error} is prefixed with box-drawing indent
+   * characters. Quotes can be nested by calling {@link startQuote} again before calling
+   * {@link endQuote}; each nesting level renders in its own color and adds another indent column.
+   *
+   * @param hexFormattedColor optional color for this level's indent characters, e.g. "#rrggbb".
+   * Defaults to the {@link secondary} theme color if not specified.
+   */
+  startQuote(hexFormattedColor?: string): void;
+
+  /**
+   * End the most recently started quote level (see {@link startQuote}).
+   *
+   * Throws if called without a matching {@link startQuote}.
+   */
+  endQuote(): void;
+
+  /**
+   * Start tracking the terminal rows occupied by subsequent writes so they can later be erased via
+   * {@link clearMarked}. Only one mark region can be active at a time.
+   *
+   * Throws if called while already marking.
+   */
+  startMark(): void;
+
+  /**
+   * Stop tracking rows for the current mark region (see {@link startMark}). The tracked row count is
+   * frozen; further writes are not counted. Use {@link clearMarked} to erase the tracked rows.
+   *
+   * Throws if called without a matching {@link startMark}.
+   */
+  endMark(): void;
+
+  /**
+   * Erase the terminal rows tracked since the last {@link startMark}/{@link endMark} pair, moving any
+   * following content up.
+   *
+   * @param minimumDisplayTimeMs optional minimum time (in milliseconds) that must have elapsed since
+   * {@link endMark} was called before the rows are erased; if less time has elapsed, waits for the
+   * remainder before clearing. Defaults to `0`.
+   *
+   * Throws if called without a preceding {@link endMark}.
+   */
+  clearMarked(minimumDisplayTimeMs?: number): Promise<void>;
+
+  /**
+   * The number of columns available on the stdout terminal.
+   * Defaults to 80 if the terminal width cannot be determined.
+   */
+  stdoutColumns(): number;
+
+  /**
+   * The number of columns available on the stderr terminal.
+   * Defaults to 80 if the terminal width cannot be determined.
+   */
+  stderrColumns(): number;
+
+  /**
+   * Print a message on `stdout`.
+   * Will be displayed as primary content if {@link colorEnabled} is `true`.
+   *
+   * @param message the message to output.
+   * @param icon optional icon to display with the message.
+   */
+  print(message: string, icon?: Icon): Promise<void>;
+
+  /**
+   * Print a {@link Level.DEBUG} level message on `stderr`.
+   * Will be displayed as secondary content if {@link colorEnabled} is `true`.
+   *
+   * @param message the message to output.
+   * @param icon optional icon to display with the message.
+   */
+  debug(message: string, icon?: Icon): Promise<void>;
+
+  /**
+   * Print an {@link Level.INFO} level message on `stderr`.
+   * Will be displayed as primary content if {@link colorEnabled} is `true`.
+   *
+   * @param message the message to output.
+   * @param icon optional icon to display with the message.
+   */
+  info(message: string, icon?: Icon): Promise<void>;
+
+  /**
+   * Print a {@link Level.WARN} level message on `stderr`.
+   * Will be displayed as yellow content if {@link colorEnabled} is `true`.
+   *
+   * @param message the message to output.
+   * @param icon optional icon to display with the message.
+   */
+  warn(message: string, icon?: Icon): Promise<void>;
+
+  /**
+   * Print an {@link Level.ERROR} level message on `stderr`.
+   * Will be displayed as red content if {@link colorEnabled} is `true`.
+   *
+   * @param message the message to output.
+   * @param icon optional icon to display with the message.
+   */
+  error(message: string, icon?: Icon): Promise<void>;
+
+  /**
+   * Set the output threshold {@link Level} for `stderr`.
+   *
+   * Default level is {@link Level.INFO}.
+   *
+   * @param level any message below this level will be filtered from output,
+   */
+  setLevel(level: Level): void;
+
+  /**
+   * Get the output threshold {@link Level} for `stderr`.
+   */
+  getLevel(): Level;
+
+  /**
+   * Display the spinner on `stderr`.
+   *
+   * The spinner will be displayed as emphasised content and the message will
+   * be displayed as primary content if {@link colorEnabled} is `true`.
+   *
+   * NOTE: The spinner and message will be displayed at {@link Level.INFO} level.
+   *
+   * NOTE: If the spinner is already displayed the message will be updated to that specified.
+   *
+   * NOTE: If any progress bars are currently displayed they will be hidden.
+   *
+   * @param message the message to output after the spinner.
+   * @param style optional spinner animation style, defaults to {@link SpinnerStyle.BOX}.
+   */
+  showSpinner(message: string, style?: SpinnerStyle): Promise<void>;
+
+  /**
+   * Hide the spinner.
+   *
+   * NOTE: Showing a progress bar will also hide the spinner.
+   */
+  hideSpinner(): Promise<void>;
+
+  /**
+   * Display a progress bar on `stderr`.
+   *
+   * The progress will be displayed in green if {@link colorEnabled} is `true`.
+   *
+   * NOTE: The progress bar and message will be displayed at {@link Level.INFO} level.
+   *
+   * NOTE: If the spinner is currently displayed it will be hidden.
+   *
+   * @param units the units to display for progress indication e.g. 'MB' or 'Kb'.
+   * @param message an optional message for the progress bar.
+   * @param total the total value which equates to 100% complete, defaults to `100`.
+   * @param current the current value which is a portion of the total value, defaults to `0`.
+   * @param style optional progress bar rendering style, defaults to {@link ProgressStyle.STROKE}.
+   *
+   * @return a handle to use when invoking {@link updateProgressBar}.
+   */
+  showProgressBar(
+    units: string,
+    message?: string,
+    total?: number,
+    current?: number,
+    style?: ProgressStyle,
+  ): Promise<number>;
+
+  /**
+   * Hides a specified progress bar.
+   *
+   * NOTE: Showing the spinner will also hide ALL progress bars.
+   *
+   * @param handle the handle referring to the progress bar to be hidden.
+   */
+  hideProgressBar(handle: number): Promise<void>;
+
+  /**
+   * Hides all progress bars.
+   *
+   * NOTE: Showing the spinner will also hide ALL progress bars.
+   */
+  hideAllProgressBars(): Promise<void>;
+
+  /**
+   * Update a specific progress bar.
+   *
+   * @param handle the handle referring to the progress bar to be updated.
+   * @param current the current value to set on the progress bar.
+   * @param message an optional message to set on the progress bar, if not specified the initially specified message will be displayed.
+   */
+  updateProgressBar(handle: number, current: number, message?: string): void;
+}

package/src/service/core/PrompterService.ts

@@ -0,0 +1,42 @@
+import type { ArgumentSingleValueType } from "../../argument/ArgumentValueTypes.ts";
+
+export const PROMPTER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/prompter-service";
+
+export enum PromptType {
+  SINGLE_SELECT = 0,
+  MULTI_SELECT = 1,
+  ACKNOWLEDGE = 2,
+  TOGGLE = 3,
+  TEXT = 4,
+  OPEN_URL = 5,
+}
+
+export interface PromptOption {
+  readonly displayValue: string;
+  readonly returnedValue: ArgumentSingleValueType;
+  readonly min?: number;
+  readonly max?: number;
+  readonly validate?: (value: ArgumentSingleValueType) => string | undefined;
+}
+
+export interface Prompt {
+  readonly name: string;
+  readonly promptText: string;
+  readonly type: PromptType;
+  readonly description?: string;
+  readonly defaultOption?: PromptOption;
+  readonly options: ReadonlyArray<PromptOption>;
+}
+
+export interface PromptResult {
+  readonly name: string;
+  readonly value: ArgumentSingleValueType | ReadonlyArray<ArgumentSingleValueType>;
+}
+
+export default interface PrompterService {
+  promptEnabled: boolean;
+
+  prompt(prompt: Prompt): Promise<PromptResult>;
+
+  promptAll(prompts: ReadonlyArray<Prompt>): Promise<ReadonlyArray<PromptResult>>;
+}

package/src/service/core/SecretService.ts

@@ -0,0 +1,27 @@
+/**
+ * Internal service providing secret storage via OS-native credential stores.
+ * Not registered in Context -- used internally by `DefaultKeyValueService` (see dynamic-cli-framework).
+ */
+export default interface SecretService {
+  /**
+   * Store a secret value. Constructs the Bun secret name from the current scope and key.
+   *
+   * @returns the constructed Bun secret name (used as part of the sentinel value in the key-value Map).
+   */
+  setSecret(key: string, value: string): Promise<string>;
+
+  /**
+   * Retrieve a secret value by its full Bun secret name.
+   */
+  getSecret(bunSecretName: string): Promise<string | null>;
+
+  /**
+   * Delete a secret by its full Bun secret name.
+   */
+  deleteSecret(bunSecretName: string): Promise<boolean>;
+
+  /**
+   * Check if a secret exists by its full Bun secret name.
+   */
+  hasSecret(bunSecretName: string): Promise<boolean>;
+}

package/src/service/core/ShutdownService.ts

@@ -0,0 +1,27 @@
+export const SHUTDOWN_SERVICE_ID = "@flowscripter/dynamic-cli-framework/shutdown-service";
+
+/**
+ * Service allowing registration of callbacks for CLI shutdown.
+ */
+export default interface ShutdownService {
+  /**
+   * Register a callback to be invoked during graceful shutdown.
+   */
+  addShutdownListener(callback: () => Promise<void>): void;
+
+  /**
+   * Enter long-running mode where the first Ctrl-C sets a cooperative flag
+   * instead of exiting, and a third Ctrl-C forces exit.
+   */
+  enterLongRunningMode(): void;
+
+  /**
+   * Leave long-running mode, restoring default single Ctrl-C exit behavior.
+   */
+  leaveLongRunningMode(): void;
+
+  /**
+   * True once shutdown has been requested (e.g. first Ctrl-C in long-running mode).
+   */
+  readonly isShutdownRequested: boolean;
+}

package/src/service/core/SyntaxHighlighterService.ts

@@ -0,0 +1,54 @@
+import type { LanguageFn as HighlightSyntax } from "highlight.js";
+
+export const SYNTAX_HIGHLIGHTER_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/syntax-highlighter-service";
+
+/**
+ * Color scheme for syntax highlighting.
+ *
+ * The keys are the names of the defined [highlight.js scopes](https://highlightjs.readthedocs.io/en/latest/css-classes-reference.html).
+ *
+ * The values are colors expressed as a hex formatted string e.g. "#rrggbb".
+ *
+ * The scheme does not need to list all scopes exhaustively.
+ */
+export type ColorScheme = Record<string, string>;
+
+/**
+ * Service providing syntax based color highlighting of text for the CLI using [highlight.js](https://github.com/highlightjs/highlight.js).
+ */
+export default interface SyntaxHighlighterService {
+  /**
+   * Register a new syntax.
+   *
+   * The recommended way to define a new language syntax is to follow the instructions here:
+   *
+   * * https://highlightjs.readthedocs.io/en/latest/language-contribution.html
+   * * https://highlightjs.readthedocs.io/en/latest/building-testing.html
+   * * https://github.com/highlightjs/highlight.js/blob/main/docs/language-guide.rst
+   *
+   * There is a list of already defined languages available for import here:
+   *
+   * https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md
+   *
+   * @param syntaxName the name used to refer to the syntax.
+   * @param syntaxDefinition the definition for the syntax conforming to the Highlight JS
+   * language definition syntax.
+   */
+  registerSyntax(syntaxName: string, syntaxDefinition: HighlightSyntax): void;
+
+  /**
+   * Return the names of the currently registered syntaxes.
+   */
+  getRegisteredSyntaxes(): ReadonlyArray<string>;
+
+  /**
+   * Return a syntactically highlighted version of the provided text using the specified syntax.
+   * The returned text will include appropriate color styling. An optional {@link ColorScheme} can be provided.
+   *
+   * @param text the text to highlight.
+   * @param syntaxName the syntax to use.
+   * @param colorScheme the color scheme to use.
+   */
+  highlight(text: string, syntaxName: string, colorScheme?: ColorScheme): string;
+}

package/src/service/core/Table.ts

@@ -0,0 +1,67 @@
+import type {
+  CellOptions,
+  ColumnOptions,
+  RowOptions,
+  TableOptions,
+} from "./TableGeneratorService.ts";
+
+export default class Table {
+  readonly rowCount: number;
+  readonly columnCount: number;
+  readonly options: TableOptions;
+
+  readonly #columnOptions: Map<number, ColumnOptions> = new Map();
+  readonly #rowOptions: Map<number, RowOptions> = new Map();
+  readonly #cells: Map<string, { contents: string; options?: CellOptions }> = new Map();
+
+  constructor(rowCount: number, columnCount: number, options?: TableOptions) {
+    this.rowCount = rowCount;
+    this.columnCount = columnCount;
+    this.options = options ?? {};
+  }
+
+  row(rowIndex: number, rowOptions: RowOptions): Table {
+    if (rowIndex < 0 || rowIndex >= this.rowCount) {
+      throw new Error(`Row index ${rowIndex} out of bounds [0, ${this.rowCount})`);
+    }
+    this.#rowOptions.set(rowIndex, rowOptions);
+    return this;
+  }
+
+  column(columnIndex: number, columnOptions: ColumnOptions): Table {
+    if (columnIndex < 0 || columnIndex >= this.columnCount) {
+      throw new Error(`Column index ${columnIndex} out of bounds [0, ${this.columnCount})`);
+    }
+    this.#columnOptions.set(columnIndex, columnOptions);
+    return this;
+  }
+
+  cell(rowIndex: number, columnIndex: number, contents: string, cellOptions?: CellOptions): Table {
+    if (rowIndex < 0 || rowIndex >= this.rowCount) {
+      throw new Error(`Row index ${rowIndex} out of bounds [0, ${this.rowCount})`);
+    }
+    if (columnIndex < 0 || columnIndex >= this.columnCount) {
+      throw new Error(`Column index ${columnIndex} out of bounds [0, ${this.columnCount})`);
+    }
+    this.#cells.set(`${rowIndex},${columnIndex}`, {
+      contents,
+      options: cellOptions,
+    });
+    return this;
+  }
+
+  getColumnOptions(columnIndex: number): ColumnOptions | undefined {
+    return this.#columnOptions.get(columnIndex);
+  }
+
+  getRowOptions(rowIndex: number): RowOptions | undefined {
+    return this.#rowOptions.get(rowIndex);
+  }
+
+  getCell(
+    rowIndex: number,
+    columnIndex: number,
+  ): { contents: string; options?: CellOptions } | undefined {
+    return this.#cells.get(`${rowIndex},${columnIndex}`);
+  }
+}

package/src/service/core/TableGeneratorService.ts

@@ -0,0 +1,39 @@
+export const TABLE_GENERATOR_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/table-generator-service";
+
+export enum Align {
+  LEFT = 0,
+  CENTER = 1,
+  RIGHT = 2,
+}
+
+export interface TableOptions {
+  border?: boolean;
+  borderColor?: string;
+  borderBackgroundColor?: string;
+  padding?: number;
+  maxWidth?: number;
+  align?: Align;
+}
+
+export interface ColumnOptions {
+  flexWeight?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  align?: Align;
+}
+
+export interface RowOptions {
+  align?: Align;
+}
+
+export interface CellOptions {
+  align?: Align;
+}
+
+export default interface TableGeneratorService {
+  createTable(rowCount: number, columnCount: number, options?: TableOptions): Table;
+  render(table: Table): string;
+}
+
+import type Table from "./Table.ts";