@flowscripter/dynamic-cli-framework-api 1.0.0

package/src/argument/ArgumentValueTypes.ts

@@ -0,0 +1,80 @@
+/**
+ * The type of single {@link Argument} values which are supported.
+ *
+ * NOTE: JavaScript does not have a special runtime value for INTEGER so this is covered by `number`.
+ * NOTE: `string` is also used for PASSWORD values.
+ */
+export type ArgumentSingleValueType = number | string | boolean;
+
+/**
+ * The type of the value to be parsed as an argument can be: `boolean`, `number` or `string` or an array of these.
+ */
+export type ArgumentValueType = ArgumentSingleValueType | Array<ArgumentSingleValueType>;
+
+/**
+ * A container object for populated argument values.
+ *
+ * The following are all valid examples:
+ *
+ * * `{ }`
+ * * `{ foo: 1 }`
+ * * `{ foo: true }`
+ * * `{ foo: 'bar' }`
+ * * `{ foo: [ 1, 2 ] }`
+ * * `{ foo: [ true, true ] }`
+ * * `{ foo: [ 'bar', 'gar' ] }`
+ * * `{ foo: { a: 1 } }`
+ * * `{ foo: { a: { b: 'c'} } }`
+ * * `{ foo: [ { a: { b: 'c'} }, { a: { b: 'c'} } ] }`
+ *
+ * An array of arrays is not allowed, so the following is an INVALID example:
+ *
+ * * `{ foo: [ [ 1, 2 ], [3, 4 ] ] }`
+ */
+export type ArgumentValues = {
+  [argName: string]: ArgumentValueType | ArgumentValues | Array<ArgumentValues>;
+};
+
+/**
+ * Enum of possible {@link Argument} value types.
+ */
+export enum ArgumentValueTypeName {
+  STRING = 0,
+  NUMBER = 1,
+  INTEGER = 2,
+  BOOLEAN = 3,
+  SECRET = 4,
+}
+
+/**
+ * Only possible value for {@link ComplexOption.type}.
+ */
+export enum ComplexValueTypeName {
+  COMPLEX = 5,
+}
+
+/**
+ * Populated single value type is very similar to {@link ArgumentSingleValueType} but allows for an illegal
+ * undefined value.
+ */
+export type PopulatedArgumentSingleValueType = ArgumentSingleValueType | undefined;
+
+/**
+ * Populated argument value types are very similar to {@link ArgumentValueType} but allow for illegal
+ * undefined values.
+ */
+export type PopulatedArgumentValueType =
+  | PopulatedArgumentSingleValueType
+  | Array<PopulatedArgumentSingleValueType>;
+
+/**
+ * Populated values are very similar to {@link ArgumentValues} but allow for illegal
+ * undefined properties and array entries.
+ */
+export interface PopulatedArgumentValues {
+  [argName: string]:
+    | PopulatedArgumentValueType
+    | PopulatedArgumentValues
+    | Array<PopulatedArgumentValues | undefined>
+    | undefined;
+}

package/src/argument/ComplexOption.ts

@@ -0,0 +1,27 @@
+import type Option from "./Option.ts";
+import type { ArgumentValues, ComplexValueTypeName } from "./ArgumentValueTypes.ts";
+
+export const MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH = 10;
+
+/**
+ * A container option argument for defining {@link SubCommand} nested argument hierarchies.
+ */
+export default interface ComplexOption extends Omit<
+  Option,
+  "type" | "defaultValue" | "allowableValues"
+> {
+  /**
+   * Type of the argument value.
+   */
+  readonly type: ComplexValueTypeName;
+
+  /**
+   * List of child {@link Option} properties.
+   */
+  readonly properties: ReadonlyArray<Option | ComplexOption>;
+
+  /**
+   * Default value for the argument if not specified.
+   */
+  readonly defaultValue?: ArgumentValues | Array<ArgumentValues>;
+}

package/src/argument/GlobalCommandArgument.ts

@@ -0,0 +1,17 @@
+import type Argument from "./Argument.ts";
+import type { ArgumentSingleValueType } from "./ArgumentValueTypes.ts";
+
+/**
+ * Interface to be implemented by a single {@link Argument} defined by a {@link GlobalCommand}.
+ */
+export default interface GlobalCommandArgument extends Argument {
+  /**
+   * Default value for the argument if not specified.
+   */
+  readonly defaultValue?: ArgumentSingleValueType;
+
+  /**
+   * If this is `true` the argument does not need to be specified nor have a default value. The default is `false`.
+   */
+  readonly isOptional?: boolean;
+}

package/src/argument/Option.ts

@@ -0,0 +1,32 @@
+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/argument/Positional.ts

@@ -0,0 +1,27 @@
+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/argument/SubCommandArgument.ts

@@ -0,0 +1,20 @@
+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/command/Command.ts

@@ -0,0 +1,28 @@
+/**
+ * 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/command/GlobalCommand.ts

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

@@ -0,0 +1,36 @@
+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 `DynamicPluginRuntimeCLI` (see dynamic-cli-framework) 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/plugin/CommandFactory.ts

@@ -0,0 +1,25 @@
+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,
+ * `DynamicPluginRuntimeCLI` (see dynamic-cli-framework) 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/plugin/ServiceProviderFactory.ts

@@ -0,0 +1,27 @@
+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,
+ * `DynamicPluginRuntimeCLI` (see dynamic-cli-framework) 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/plugin/createCLIPlugin.ts

@@ -0,0 +1,47 @@
+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/registry/CommandRegistry.ts

@@ -0,0 +1,116 @@
+import type GroupCommand from "../command/GroupCommand.ts";
+import type SubCommand from "../command/SubCommand.ts";
+import type GlobalCommand from "../command/GlobalCommand.ts";
+import type GlobalModifierCommand from "../command/GlobalModifierCommand.ts";
+import type Command from "../command/Command.ts";
+
+/**
+ * Interface used by a {@link CLI} to register {@link Command} instances.
+ */
+export default interface CommandRegistry {
+  /**
+   * Get all registered {@link SubCommand} instances.
+   */
+  getSubCommands(): ReadonlyArray<SubCommand>;
+
+  /**
+   * Get all registered {@link GroupCommand} instances.
+   */
+  getGroupCommands(): ReadonlyArray<GroupCommand>;
+
+  /**
+   * Get all registered {@link GlobalCommand} instances.
+   */
+  getGlobalCommands(): ReadonlyArray<GlobalCommand>;
+
+  /**
+   * Get all registered {@link GlobalModifierCommand} instances.
+   */
+  getGlobalModifierCommands(): ReadonlyArray<GlobalModifierCommand>;
+
+  /**
+   * Get a registered {@link SubCommand} by name.
+   */
+  getSubCommandByName(name: string): SubCommand | undefined;
+
+  /**
+   * Get a registered {@link GroupCommand} by name.
+   */
+  getGroupCommandByName(name: string): GroupCommand | undefined;
+
+  /**
+   * Get a registered {@link GroupCommand} and member {@link SubCommand} by
+   * combined name e.g. `<group-command-name>:<member-sub-command-name>`.
+   */
+  getGroupCommandAndMemberSubCommandByJoinedName(
+    getGroupCommandAndMemberSubCommandByName: string,
+  ): { groupCommand: GroupCommand; command: SubCommand } | undefined;
+
+  /**
+   * Get a registered {@link GlobalCommand} by name.
+   */
+  getGlobalCommandByName(name: string): GlobalCommand | undefined;
+
+  /**
+   * Get a registered {@link GlobalCommand} by short alias.
+   */
+  // getGlobalCommandByShortAlias(shortAlias: string): GlobalCommand | undefined;
+
+  /**
+   * Get a registered {@link GlobalModifierCommand} by name.
+   */
+  getGlobalModifierCommandByName(name: string): GlobalModifierCommand | undefined;
+
+  /**
+   * Get a registered {@link GlobalModifierCommand} by short alias.
+   */
+  // getGlobalModifierCommandByShortAlias(
+  //   shortAlias: string,
+  // ): GlobalModifierCommand | undefined;
+
+  /**
+   * Get a map of all registered {@link GroupCommand} and member {@link SubCommand} instance combinations by
+   * combined name e.g. `<group-command-name>:<member-sub-command-name>`.
+   */
+  getGroupAndMemberCommandsByJoinedName(): ReadonlyMap<
+    string,
+    { groupCommand: GroupCommand; command: SubCommand }
+  >;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by name provided by the specified service.
+   */
+  getGlobalModifierCommandsByNameProvidedByService(
+    serviceId: string,
+  ): ReadonlyMap<string, GlobalModifierCommand>;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by short alias provided by the specified service.
+   */
+  getGlobalModifierCommandsByShortAliasProvidedByService(
+    serviceId: string,
+  ): ReadonlyMap<string, GlobalModifierCommand>;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by name not provided by a service.
+   */
+  getGlobalModifierCommandsByNameNotProvidedByService(): ReadonlyMap<string, GlobalModifierCommand>;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by short alias not provided by a service.
+   */
+  getGlobalModifierCommandsByShortAliasNotProvidedByService(): ReadonlyMap<
+    string,
+    GlobalModifierCommand
+  >;
+
+  /**
+   * Get a map of all registered non-modifier {@link Command} instances by name.
+   */
+  getNonModifierCommandsByName(): ReadonlyMap<string, Command>;
+
+  /**
+   * Get a map of all registered {@link GlobalCommand} instances by short alias.
+   */
+  getGlobalCommandsByShortAlias(): ReadonlyMap<string, GlobalCommand>;
+}

package/src/registry/ServiceProviderRegistry.ts

@@ -0,0 +1,11 @@
+import type { ServiceProvider } from "../service/ServiceProvider.ts";
+
+/**
+ * Interface used by a {@link CLI} to register {@link ServiceProvider} instances.
+ */
+export default interface ServiceProviderRegistry {
+  /**
+   * Return all {@link ServiceProvider} instances registered in order of descending {@link ServiceProvider.servicePriority}
+   */
+  getServiceProviders(): ReadonlyArray<ServiceProvider>;
+}