@flowscripter/dynamic-cli-framework 1.7.4 → 2.0.0

package/src/api/argument/Option.ts

@@ -1,32 +0,0 @@
-import type { ArgumentValueType } from "./ArgumentValueTypes.ts";
-import type SubCommandArgument from "./SubCommandArgument.ts";
-
-/**
- * Interface for {@link SubCommand} option arguments.
- */
-export default interface Option extends SubCommandArgument {
-  /**
-   * Optional short alias for the option.
-   *
-   * Must consist of a single alphanumeric non-whitespace ASCII character.
-   */
-  readonly shortAlias?: string;
-
-  /**
-   * Default value for the argument if not specified.
-   */
-  readonly defaultValue?: ArgumentValueType;
-
-  /**
-   * If this is `true` the option does not need to be specified nor have a default value.
-   */
-  readonly isOptional?: boolean;
-
-  /**
-   * If this is `true` the option can be specified multiple times and all values will be returned in an array
-   * matching the order provided.
-   *
-   * NOTE: If {@link isOptional} is `false`, at least one instance of the option must be specified.
-   */
-  readonly isArray?: boolean;
-}

package/src/api/argument/Positional.ts

@@ -1,27 +0,0 @@
-import type SubCommandArgument from "./SubCommandArgument.ts";
-
-/**
- * Interface for {@link SubCommand} positional arguments.
- */
-export default interface Positional extends SubCommandArgument {
-  /**
-   * If this is `true` the argument can be specified one or multiple times and all values will be returned in
-   * an array matching the order provided.
-   *
-   * NOTE: If {@link isVarargOptional} is `true`, the argument can specified zero, one or multiple times.
-   *
-   * NOTE: There can be only one positional with this set and it must be the last the last item if there
-   * are multiple positionals defined.
-   */
-  readonly isVarargMultiple?: boolean;
-
-  /**
-   * If this is `true` the argument can be specified zero or once i.e. it does not need to be specified.
-   *
-   * NOTE: If {@link isVarargMultiple} is `true`, the argument can specified zero, one or multiple times.
-   *
-   * NOTE: There can be only one positional with this set and it must be the last the last item if there
-   * are multiple positionals defined.
-   */
-  readonly isVarargOptional?: boolean;
-}

package/src/api/argument/SubCommandArgument.ts

@@ -1,20 +0,0 @@
-import type Argument from "./Argument.ts";
-
-export const MAXIMUM_ARGUMENT_ARRAY_SIZE = 255;
-
-/**
- * Interface to be implemented by all {@link SubCommand} arguments.
- */
-export default interface SubCommandArgument extends Argument {
-  /**
-   * Name of the argument.
-   *
-   * Must consist of alphanumeric non-whitespace ASCII or `_` and `-` characters. Cannot start with `-`.
-   */
-  readonly name: string;
-
-  /**
-   * Optional description of the argument.
-   */
-  readonly description?: string;
-}

package/src/api/command/Command.ts

@@ -1,28 +0,0 @@
-/**
- * Common interface for all command types.
- */
-export default interface Command {
-  /**
-   * Name of the command.
-   *
-   * Must consist of alphanumeric non-whitespace ASCII or `_` and `-` characters. Cannot start with `-`.
-   */
-  readonly name: string;
-
-  /**
-   * Optional description of the command.
-   */
-  readonly description?: string;
-
-  /**
-   * Optionally enable support for populating argument values via configuration. If this is `true` then
-   * default argument values may be sourced using a configuration source provided by the CLI runtime.
-   */
-  readonly enableConfiguration?: boolean;
-
-  /**
-   * Optionally hide the command from generic help listings. The command remains registered and
-   * executable, and its own usage help (`help <command>`) is still shown if explicitly requested.
-   */
-  readonly disableGenericHelpDisplay?: boolean;
-}

package/src/api/command/GlobalCommand.ts

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

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

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

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

@@ -1,21 +0,0 @@
-/**
- * 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/plugin/CLIPlugin.ts

@@ -1,35 +0,0 @@
-import type { Plugin, ExtensionDescriptor } from "@flowscripter/dynamic-plugin-framework";
-import type CommandFactory from "./CommandFactory.ts";
-import { DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT } from "./CommandFactory.ts";
-import type ServiceProviderFactory from "./ServiceProviderFactory.ts";
-import { DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT } from "./ServiceProviderFactory.ts";
-
-/**
- * {@link ExtensionDescriptor} for a {@link CommandFactory} extension.
- */
-export interface CommandFactoryExtensionDescriptor extends ExtensionDescriptor {
-  readonly extensionPoint: typeof DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT;
-  readonly factory: {
-    create(hostData?: Map<string, string>): Promise<CommandFactory>;
-  };
-}
-
-/**
- * {@link ExtensionDescriptor} for a {@link ServiceProviderFactory} extension.
- */
-export interface ServiceProviderFactoryExtensionDescriptor extends ExtensionDescriptor {
-  readonly extensionPoint: typeof DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT;
-  readonly factory: {
-    create(hostData?: Map<string, string>): Promise<ServiceProviderFactory>;
-  };
-}
-
-/**
- * A {@link Plugin} for {@link DynamicPluginRuntimeCLI} whose {@link extensionDescriptors} are
- * limited to the {@link CommandFactory} and {@link ServiceProviderFactory} extension points.
- */
-export default interface CLIPlugin extends Plugin {
-  readonly extensionDescriptors: ReadonlyArray<
-    CommandFactoryExtensionDescriptor | ServiceProviderFactoryExtensionDescriptor
-  >;
-}

package/src/api/plugin/CommandFactory.ts

@@ -1,25 +0,0 @@
-import type Command from "../command/Command.ts";
-
-/**
- * Extension point identifier for {@link CommandFactory} extensions.
- *
- * Plugins register against this extension point to supply {@link Command} instances
- * that are added to the CLI before execution begins.
- */
-export const DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT =
-  "DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY";
-
-/**
- * Extension interface implemented by a plugin to provide {@link Command} instances.
- *
- * A plugin registers an {@link CommandFactory} against
- * {@link DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT}. On startup,
- * {@link DynamicPluginRuntimeCLI} instantiates each factory and adds the returned
- * commands to the CLI registry before the runner executes.
- */
-export default interface CommandFactory {
-  /**
-   * Return the {@link Command} instances provided by this factory.
-   */
-  getCommands(): ReadonlyArray<Command>;
-}

package/src/api/plugin/ServiceProviderFactory.ts

@@ -1,27 +0,0 @@
-import type { ServiceProvider } from "../service/ServiceProvider.ts";
-
-/**
- * Extension point identifier for {@link ServiceProviderFactory} extensions.
- *
- * Plugins register against this extension point to supply {@link ServiceProvider} instances
- * that are initialised by the runner as part of the normal service lifecycle.
- */
-export const DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT =
-  "DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY";
-
-/**
- * Extension interface implemented by a plugin to provide {@link ServiceProvider} instances.
- *
- * A plugin registers a {@link ServiceProviderFactory} against
- * {@link DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT}. On startup,
- * {@link DynamicPluginRuntimeCLI} instantiates each factory and adds the returned
- * service providers to the CLI registry before the runner executes, so they participate
- * in the full initialization lifecycle (including {@link GlobalModifierCommand} scanning
- * and {@link ServiceProvider.initService}).
- */
-export default interface ServiceProviderFactory {
-  /**
-   * Return the {@link ServiceProvider} instances provided by this factory.
-   */
-  getServiceProviders(): ReadonlyArray<ServiceProvider>;
-}

package/src/api/plugin/createCLIPlugin.ts

@@ -1,47 +0,0 @@
-import type CommandFactory from "./CommandFactory.ts";
-import { DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT } from "./CommandFactory.ts";
-import type ServiceProviderFactory from "./ServiceProviderFactory.ts";
-import { DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT } from "./ServiceProviderFactory.ts";
-import type CLIPlugin from "./CLIPlugin.ts";
-
-export interface CLIPluginOptions {
-  readonly commandFactory?: CommandFactory | (() => Promise<CommandFactory>);
-  readonly serviceProviderFactory?:
-    | ServiceProviderFactory
-    | (() => Promise<ServiceProviderFactory>);
-  readonly pluginData?: ReadonlyMap<string, string>;
-}
-
-/**
- * Build a {@link CLIPlugin} from optional {@link CommandFactory} and {@link ServiceProviderFactory}
- * instances (or factory functions), without needing to hand-construct extension descriptors.
- */
-export default function createCLIPlugin(options: CLIPluginOptions): CLIPlugin {
-  const extensionDescriptors: CLIPlugin["extensionDescriptors"][number][] = [];
-
-  if (options.commandFactory) {
-    const commandFactory = options.commandFactory;
-    extensionDescriptors.push({
-      extensionPoint: DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT,
-      factory: {
-        create: async () =>
-          typeof commandFactory === "function" ? commandFactory() : commandFactory,
-      },
-    });
-  }
-
-  if (options.serviceProviderFactory) {
-    const serviceProviderFactory = options.serviceProviderFactory;
-    extensionDescriptors.push({
-      extensionPoint: DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT,
-      factory: {
-        create: async () =>
-          typeof serviceProviderFactory === "function"
-            ? serviceProviderFactory()
-            : serviceProviderFactory,
-      },
-    });
-  }
-
-  return { extensionDescriptors, pluginData: options.pluginData };
-}

package/src/api/service/ServiceProvider.ts

@@ -1,52 +0,0 @@
-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 a service 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 it provides which should be registered in the CLI.
-   *
-   * @param cliConfig the {@link CLIConfig} for the CLI.
-   */
-  getServiceInfo(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/ArgumentPrompterService.ts

@@ -1,8 +0,0 @@
-import type { ParseResult } from "../../../runtime/parser.ts";
-
-export const ARGUMENT_PROMPTER_SERVICE_ID =
-  "@flowscripter/dynamic-cli-framework/argument-prompter-service";
-
-export default interface ArgumentPrompterService {
-  promptForMissingArguments(parseResult: ParseResult): Promise<ParseResult>;
-}

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

@@ -1,69 +0,0 @@
-export const ASCII_BANNER_GENERATOR_SERVICE_ID =
-  "@flowscripter/dynamic-cli-framework/ascii-banner-generator-service";
-
-export type ColorEffectDirection = "horizontal" | "vertical";
-
-export interface FixedColorEffect {
-  type: "fixed";
-  color: string; // hex "#rrggbb"
-}
-
-export interface GradientColorEffect {
-  type: "gradient";
-  colors: string[]; // 2+ hex color stops
-  direction: ColorEffectDirection;
-}
-
-export interface RainbowColorEffect {
-  type: "rainbow";
-  spread?: number; // default 8.0
-  frequency?: number; // default 0.3
-  seed?: number; // default 0 = random seed
-  direction: ColorEffectDirection;
-}
-
-export type ColorEffect = FixedColorEffect | GradientColorEffect | RainbowColorEffect;
-
-export interface BannerColorEffects {
-  background?: ColorEffect;
-  messageForeground?: ColorEffect;
-  subMessageForeground?: ColorEffect;
-}
-
-export interface BannerGenerateOptions {
-  fontName?: string;
-  subMessage?: string;
-  colorEffects?: BannerColorEffects;
-}
-
-/**
- * Service allowing a text string to be rendered using an ASCII banner 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.
-   */
-  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 options.
-   *
-   * @param message the message to output.
-   * @param options optional generation options.
-   */
-  generate(message: string, options?: BannerGenerateOptions): Promise<string>;
-}

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

@@ -1,32 +0,0 @@
-export const COMPLETION_SERVICE_ID = "@flowscripter/dynamic-cli-framework/completion-service";
-
-export enum ShellType {
-  BASH = "bash",
-  ZSH = "zsh",
-  FISH = "fish",
-  POWERSHELL = "powershell",
-}
-
-export interface CompletionItem {
-  readonly value: string;
-  readonly description?: string;
-}
-
-/**
- * Interface for a service providing shell auto-completion support.
- */
-export default interface CompletionService {
-  generateCompletions(
-    shellType: ShellType,
-    line: string,
-    cursorPosition: number,
-  ): Promise<ReadonlyArray<CompletionItem>>;
-
-  getBootstrapScript(shellType: ShellType, cliName: string, executablePath: string): string;
-
-  getDefaultConfigPath(shellType: ShellType): string;
-
-  validateShellEnvironment(shellType: ShellType): Promise<boolean>;
-
-  formatCompletions(shellType: ShellType, completions: ReadonlyArray<CompletionItem>): string;
-}

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

@@ -1,27 +0,0 @@
-import { Buffer } from "node:buffer";
-
-export const DATA_DUMP_GENERATOR_SERVICE_ID =
-  "@flowscripter/dynamic-cli-framework/data-dump-generator-service";
-
-export enum DumpFormat {
-  HEX = "HEX",
-  ASCII = "ASCII",
-}
-
-export interface ByteRangeColor {
-  start: number;
-  end: number;
-  color: string;
-}
-
-export interface HexDumpGenerateOptions {
-  format?: DumpFormat;
-  bytesPerGroup?: number;
-  groupsPerRow?: number;
-  spacesBetweenGroups?: number;
-  colorScheme?: ByteRangeColor[];
-}
-
-export default interface DataDumpGeneratorService {
-  generate(data: Buffer, options?: HexDumpGenerateOptions): string;
-}

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

@@ -1,25 +0,0 @@
-export const IMAGE_PRINTER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/image-printer-service";
-
-/**
- * Service for rendering images in the terminal.
- *
- * Uses the Kitty or iTerm2 graphics protocol when supported, otherwise falls back
- * to ANSI half-block character rendering. Terminal multiplexers (tmux, screen) always
- * use the ANSI fallback as they do not pass through graphics protocol escape sequences.
- */
-export default interface ImagePrinterService {
-  /**
-   * Render an image as a string suitable for terminal output.
-   *
-   * @param imageBuffer the raw image data (e.g. PNG file contents).
-   * @param widthPercentage the percentage of terminal width to use for rendering. Defaults to 100.
-   * @param hexFormattedBackgroundColor optional background color for transparent pixels.
-   *   This should be a valid hex formatted string e.g. "#rrggbb". If not specified,
-   *   transparent pixels show through to the terminal background.
-   */
-  image(
-    imageBuffer: Uint8Array,
-    widthPercentage?: number,
-    hexFormattedBackgroundColor?: string,
-  ): Promise<string>;
-}

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

@@ -1,44 +0,0 @@
-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}.
- *
- * 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): 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, isSecret?: boolean): Promise<void>;
-
-  /**
-   * Check if a value for a specified key exists in the keystore.
-   */
-  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): Promise<void>;
-}