@flowscripter/dynamic-cli-framework 1.1.5 → 1.2.0

package/src/api/service/core/KeyValueService.ts

@@ -1,28 +1,45 @@
 export const KEY_VALUE_SERVICE_ID =
   "@flowscripter/dynamic-cli-framework/key-value-service";
 
+/**
+ * The sentinel prefix used to indicate a value is stored as an OS-native secret.
+ * Values starting with this prefix are resolved via the {@link SecretService}.
+ * This prefix is reserved and must not be used for regular key-value data.
+ */
+export const SECRET_SENTINEL_PREFIX = "__SECRET__:";
+
 /**
  * Service providing keystore functionality for the CLI. The keystore data is scoped to the
- * service or {@link Command} instances accessing this service via {@link Context.getServiceById}
+ * service or {@link Command} instances accessing this service via {@link Context.getServiceById}.
+ *
+ * Values can optionally be stored as OS-native secrets using the `isSecret` parameter on
+ * {@link setKey}. Secret values are stored via {@link SecretService} and only a sentinel
+ * reference is kept in the key-value Map. The sentinel prefix `__SECRET__:` is reserved.
  */
 export default interface KeyValueService {
   /**
    * Get a value for a specified key in the keystore.
+   * If the stored value is a secret sentinel, the actual value is retrieved from the OS secret store.
    */
-  getKey(key: string): string;
+  getKey(key: string): Promise<string>;
 
   /**
    * Set a value for a specified key in the keystore.
+   *
+   * @param isSecret if true, the value is stored in the OS-native secret store and a sentinel
+   *   reference is kept in the key-value Map. Requires that the service was constructed with
+   *   secret support enabled.
    */
-  setKey(key: string, value: string): void;
+  setKey(key: string, value: string, isSecret?: boolean): Promise<void>;
 
   /**
    * Check if a value for a specified key exists in the keystore.
    */
-  hasKey(key: string): boolean;
+  hasKey(key: string): Promise<boolean>;
 
   /**
    * Delete the value for a specified key in the keystore.
+   * If the stored value is a secret sentinel, the secret is also deleted from the OS secret store.
    */
-  deleteKey(key: string): void;
+  deleteKey(key: string): Promise<void>;
 }

package/src/api/service/core/PrinterService.ts

@@ -12,6 +12,22 @@ export enum Level {
   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.
  */
@@ -38,6 +54,11 @@ export default interface PrinterService {
    */
   colorEnabled: boolean;
 
+  /**
+   * Disable or enable hyperlink output for messages.
+   */
+  hyperlinksEnabled: boolean;
+
   /**
    * Enable or disable dark mode. Default is disabled i.e. `false`.
    */
@@ -143,6 +164,108 @@ export default interface PrinterService {
    */
   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;
+
+  /**
+   * 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`.
@@ -215,8 +338,9 @@ export default interface PrinterService {
    * 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): Promise<void>;
+  showSpinner(message: string, style?: SpinnerStyle): Promise<void>;
 
   /**
    * Hide the spinner.
@@ -238,6 +362,7 @@ export default interface PrinterService {
    * @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}.
    */
@@ -246,6 +371,7 @@ export default interface PrinterService {
     message?: string,
     total?: number,
     current?: number,
+    style?: ProgressStyle,
   ): Promise<number>;
 
   /**

package/src/api/service/core/PrompterService.ts

@@ -0,0 +1,49 @@
+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/api/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 {@link DefaultKeyValueService}.
+ */
+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/api/service/core/ShutdownService.ts

@@ -6,7 +6,23 @@ export const SHUTDOWN_SERVICE_ID =
  */
 export default interface ShutdownService {
   /**
-   * Register a callback method for CLI shutdown.
+   * 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/api/service/core/Table.ts

@@ -0,0 +1,85 @@
+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/api/service/core/TableGeneratorService.ts

@@ -0,0 +1,38 @@
+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 {
+  render(table: Table): string;
+}
+
+import type Table from "./Table.ts";

package/src/api/service/core/TreePrinterService.ts

@@ -0,0 +1,11 @@
+export const TREE_PRINTER_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/tree-printer-service";
+
+export interface TreeNode {
+  label: string;
+  children?: Array<TreeNode | string>;
+}
+
+export default interface TreePrinterService {
+  print(node: TreeNode): string;
+}