@flowscripter/dynamic-cli-framework 1.0.0

package/src/api/command/GlobalCommand.ts

@@ -0,0 +1,33 @@
+import type Command from "./Command.ts";
+import type GlobalCommandArgument from "../argument/GlobalCommandArgument.ts";
+import type Context from "../Context.ts";
+import type { ArgumentSingleValueType } from "../argument/ArgumentValueTypes.ts";
+
+/**
+ * Interface for a global command.
+ */
+export default interface GlobalCommand extends Command {
+  /**
+   * Optional short alias for the global command.
+   *
+   * Must consist of a single alphanumeric non-whitespace ASCII character.
+   */
+  readonly shortAlias?: string;
+
+  /**
+   * Optional {@link GlobalCommandArgument} for the command.
+   */
+  readonly argument?: GlobalCommandArgument;
+
+  /**
+   * Execute the command.
+   *
+   * @param context the {@link Context} in which to execute the command.
+   * @param argumentValue optional argument value for the command. This will be populated unless
+   * the command's {@link GlobalCommandArgument} is optional and the argument value was not provided.
+   */
+  execute(
+    context: Context,
+    argumentValue?: ArgumentSingleValueType,
+  ): Promise<void>;
+}

package/src/api/command/GlobalModifierCommand.ts

@@ -0,0 +1,12 @@
+import type GlobalCommand from "./GlobalCommand.ts";
+
+/**
+ * Interface for a global modifier command.
+ */
+export default interface GlobalModifierCommand extends GlobalCommand {
+  /**
+   * Used to determine the order in which multiple global modifier command instances
+   * parsed from the provided arguments will be executed. Higher values will execute before lower values.
+   */
+  readonly executePriority: number;
+}

package/src/api/command/GroupCommand.ts

@@ -0,0 +1,20 @@
+import type SubCommand from "./SubCommand.ts";
+import type Command from "./Command.ts";
+import type Context from "../Context.ts";
+
+/**
+ * Interface for a group command.
+ */
+export default interface GroupCommand extends Command {
+  /**
+   * Array of {@link SubCommand} instances for this group command. Must contain at least one sub-command.
+   */
+  readonly memberSubCommands: ReadonlyArray<SubCommand>;
+
+  /**
+   * Execute the command.
+   *
+   * @param context the {@link Context} in which to execute the command.
+   */
+  execute(context: Context): Promise<void>;
+}

package/src/api/command/SubCommand.ts

@@ -0,0 +1,41 @@
+import type Command from "./Command.ts";
+import type Option from "../argument/Option.ts";
+import type Positional from "../argument/Positional.ts";
+import type UsageExample from "./UsageExample.ts";
+import type ComplexOption from "../argument/ComplexOption.ts";
+import type { ArgumentValues } from "../argument/ArgumentValueTypes.ts";
+import type Context from "../Context.ts";
+
+/**
+ * Interface for a sub-command.
+ */
+export default interface SubCommand extends Command {
+  /**
+   * {@link Option} or {@link ComplexOption} argument definitions for the sub-command.
+   */
+  readonly options: ReadonlyArray<Option | ComplexOption>;
+
+  /**
+   * {@link Positional} argument definitions for the sub-command.
+   */
+  readonly positionals: ReadonlyArray<Positional>;
+
+  /**
+   * Optional grouping topic of the command to structuring of help output.
+   */
+  readonly helpTopic?: string;
+
+  /**
+   * Optional usage examples for the command to support help output.
+   */
+  readonly usageExamples?: ReadonlyArray<UsageExample>;
+
+  /**
+   * Execute the command.
+   *
+   * @param context the {@link Context} in which to execute the command.
+   * @param argumentValues the argument values for the command. This may be empty if
+   * the command's {@link Option} and {@link Positional} instances are all optional and no argument values were provided.
+   */
+  execute(context: Context, argumentValues: ArgumentValues): Promise<void>;
+}

package/src/api/command/UsageExample.ts

@@ -0,0 +1,21 @@
+/**
+ * A usage example for a {@link SubCommand} to be used in help output.
+ */
+export default interface UsageExample {
+  /**
+   * The example arguments used to generate an example invocation.
+   *
+   * This should not include the CLI or command name.
+   */
+  readonly exampleArguments: string;
+
+  /**
+   * Optional description of the command example.
+   */
+  readonly description?: string;
+
+  /**
+   * Optional output result of executing the example command.
+   */
+  readonly output?: ReadonlyArray<string>;
+}

package/src/api/service/ServiceProvider.ts

@@ -0,0 +1,52 @@
+import type Command from "../command/Command.ts";
+import type Context from "../Context.ts";
+import type CLIConfig from "../CLIConfig.ts";
+
+/**
+ * Information regarding a service instance provided by a {@link ServiceProvider}.
+ */
+export interface ServiceInfo {
+  /**
+   * Optional, a service in the {@link Context}.
+   */
+  readonly service?: unknown;
+
+  /**
+   * Zero or more {@link Command} instances related to the service which should be registered.
+   */
+  readonly commands: ReadonlyArray<Command>;
+}
+
+/**
+ * Interface allowing services to be provided to the CLI.
+ */
+export interface ServiceProvider {
+  /**
+   * The ID which identifies the service provided.
+   */
+  readonly serviceId: string;
+
+  /**
+   * Used to determine the order in which multiple service instances will be initialised. Higher values
+   * will be initialised before lower values.
+   */
+  readonly servicePriority: number;
+
+  /**
+   * Return {@link ServiceInfo} containing the service and any commands which should be registered in the CLI.
+   *
+   * @param cliConfig the {@link CLIConfig} for the CLI.
+   */
+  provide(cliConfig: CLIConfig): Promise<ServiceInfo>;
+
+  /**
+   * Initialise the service. This will be invoked AFTER any {@link GlobalModifierCommand} provided in the
+   * {@link ServiceInfo} have been invoked (if specified as CLI arguments or CLI configuration).
+   *
+   * NOTE: Other services within the provided context will only have been initialised if they have a higher
+   * {@link servicePriority} value than the current service.
+   *
+   * @param context the {@link Context} in which the CLI is running.
+   */
+  initService(context: Context): Promise<void>;
+}

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

@@ -0,0 +1,35 @@
+export const ASCII_BANNER_GENERATOR_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/ascii-banner-generator-service";
+
+/**
+ * Service allowing a text string to be rendered using an ASCII banner [FIGlet](http://www.figlet.org) font.
+ */
+export default interface AsciiBannerGeneratorService {
+  /**
+   * Register a new font.
+   *
+   * The recommended way to load the font definition is to convert the font definition to a JSON string
+   * (replacing newlines with `\n`) and placing in a simple JSON file: `{ "font": "<figlet font definition>" }`.
+   * This can then be imported as follows:
+   *
+   * `import { font as myFont } from "./myfont.json" with { type: "json" };
+   *
+   * @param fontName the name used to refer to the font.
+   * @param fontDefinition the definition for the syntax conforming to the
+   * [FIGfont format](http://www.jave.de/figlet/figfont.html#creating).
+   */
+  registerFont(fontName: string, fontDefinition: string): void;
+
+  /**
+   * Return the names of the currently registered fonts.
+   */
+  getRegisteredFonts(): ReadonlyArray<string>;
+
+  /**
+   * Generate an ASCII banner text for the message using the specified font.
+   *
+   * @param message the message to output.
+   * @param fontName the font to use.
+   */
+  generate(message: string, fontName: string): Promise<string>;
+}

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

@@ -0,0 +1,28 @@
+export const KEY_VALUE_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/key-value-service";
+
+/**
+ * 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}
+ */
+export default interface KeyValueService {
+  /**
+   * Get a value for a specified key in the keystore.
+   */
+  getKey(key: string): string;
+
+  /**
+   * Set a value for a specified key in the keystore.
+   */
+  setKey(key: string, value: string): void;
+
+  /**
+   * Check if a value for a specified key exists in the keystore.
+   */
+  hasKey(key: string): boolean;
+
+  /**
+   * Delete the value for a specified key in the keystore.
+   */
+  deleteKey(key: string): void;
+}

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

@@ -0,0 +1,266 @@
+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 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;
+
+  /**
+   * 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 it the foreground is green.
+   * Has no effect if {@link colorEnabled} is `false`.
+   */
+  green(message: string): string;
+
+  /**
+   * 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 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 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 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 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 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 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.
+   */
+  showSpinner(message: string): 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 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`.
+   *
+   * @return a handle to use when invoking {@link updateProgressBar}.
+   */
+  showProgressBar(
+    units: string,
+    message?: string,
+    total?: number,
+    current?: number,
+  ): 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/ShutdownService.ts

@@ -0,0 +1,12 @@
+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 method for CLI shutdown.
+   */
+  addShutdownListener(callback: () => Promise<void>): void;
+}

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

@@ -0,0 +1,42 @@
+import type { LanguageFn as HighlightSyntax } from "highlight.js";
+
+export const SYNTAX_HIGHLIGHTER_SERVICE_ID =
+  "@flowscripter/dynamic-cli-framework/highlighter-service";
+
+/**
+ * Service providing syntax based color highlighting of text for the CLI using [highlight.js](https://highlightjs.org).
+ */
+export default interface SyntaxHighlighterService {
+  /**
+   * Register a new syntax.
+   *
+   * The recommended way to define a new language syntax is 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 ASCII color codes.
+   *
+   * @param text the text to highlight.
+   * @param syntaxName the syntax to use.
+   */
+  highlight(text: string, syntaxName: string): string;
+}