@flowscripter/dynamic-cli-framework 1.7.5 → 2.0.0

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

@@ -1,63 +0,0 @@
-import type {
-  VersionedPluginDescriptor,
-  SearchQuery,
-} from "@flowscripter/dynamic-plugin-framework";
-
-/**
- * Service ID for {@link PluginService}.
- *
- * Pass to {@link Context.getServiceById} to retrieve the active {@link PluginService} instance.
- */
-export const PLUGIN_SERVICE_ID = "PLUGIN_SERVICE";
-
-/**
- * Service providing plugin lifecycle management for a CLI with dynamic plugin support.
- *
- * Exposes search, install, uninstall, list, and update operations backed by a
- * {@link MarketplacePluginManager}. Provided by {@link DefaultPluginServiceProvider}
- * when plugin support is enabled via {@link DynamicPluginRuntimeCLI}.
- *
- * After {@link install} or an upgrade, the CLI must be restarted for new or updated
- * plugin commands and service providers to become active.
- */
-export default interface PluginService {
-  /**
-   * Search the remote marketplace for plugins matching the given query.
-   *
-   * @param query criteria to filter results by.
-   * @returns an async iterable of matching {@link VersionedPluginDescriptor} entries.
-   */
-  search(query: Readonly<SearchQuery>): AsyncIterable<Readonly<VersionedPluginDescriptor>>;
-
-  /**
-   * Install a plugin from the remote marketplace into the local plugin store.
-   *
-   * @param descriptor the plugin to install, as returned by {@link search}.
-   */
-  install(descriptor: Readonly<VersionedPluginDescriptor>): Promise<void>;
-
-  /**
-   * Remove a previously installed plugin from the local plugin store.
-   *
-   * @param pluginId the package identifier of the plugin to remove (e.g. `@scope/my-plugin`).
-   */
-  uninstall(pluginId: string): Promise<void>;
-
-  /**
-   * List all plugins currently installed in the local plugin store.
-   *
-   * @returns an async iterable of {@link VersionedPluginDescriptor} entries for each installed plugin.
-   */
-  listInstalled(): AsyncIterable<Readonly<VersionedPluginDescriptor>>;
-
-  /**
-   * Check each installed plugin for a newer version available on the remote marketplace.
-   *
-   * @returns an async iterable of objects pairing the installed plugin descriptor with the
-   * latest available version string for plugins that have an update available.
-   */
-  checkForUpdates(): AsyncIterable<{
-    descriptor: Readonly<VersionedPluginDescriptor>;
-    availableVersion: string;
-  }>;
-}

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

@@ -1,39 +0,0 @@
-export const PRETTY_PRINTER_SERVICE_ID =
-  "@flowscripter/dynamic-cli-framework/pretty-printer-service";
-
-import type { Plugin } from "prettier";
-
-/**
- * Service providing syntax based pretty printing of text for the CLI using [prettier](https://github.com/prettier/prettier).
- */
-export default interface PrettyPrinterService {
-  /**
-   * Register a new syntax.
-   *
-   * The recommended way to define a new language syntax plugin is to follow the instructions here:
-   *
-   * https://prettier.io/docs/plugins#developing-plugins
-   *
-   * There is a list of already defined languages available for import here:
-   *
-   * * https://prettier.io/docs/
-   * * https://prettier.io/docs/plugins
-   *
-   * @param syntaxName the name used to refer to the syntax.
-   * @param syntaxDefinition the definition for the syntax conforming to the Prettier plugin interface.
-   */
-  registerSyntax(syntaxName: string, syntaxDefinition: Plugin<unknown>): Promise<void>;
-
-  /**
-   * Return the names of the currently registered syntaxes.
-   */
-  getRegisteredSyntaxes(): Promise<ReadonlyArray<string>>;
-
-  /**
-   * Return a pretty printed version of the provided text using the specified syntax.
-   *
-   * @param text the text to prettify.
-   * @param syntaxName the syntax to use.
-   */
-  prettify(text: string, syntaxName: string): Promise<string>;
-}

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

@@ -1,400 +0,0 @@
-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;
-
-  /**
-   * 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/api/service/core/PrompterService.ts

@@ -1,42 +0,0 @@
-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

@@ -1,27 +0,0 @@
-/**
- * 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

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

@@ -1,54 +0,0 @@
-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;
-}