@flowscripter/dynamic-cli-framework 1.0.0

package/bun.lock

@@ -0,0 +1,63 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@flowscripter/dynamic-plugin-framework",
+      "dependencies": {
+        "emphasize": "^7.0.0",
+        "fastest-levenshtein": "^1.0.16",
+        "figlet": "^1.8.0",
+        "highlight.js": "^11.11.1",
+        "supports-color": "^10.0.0",
+        "ts-log": "^2.2.7",
+      },
+      "devDependencies": {
+        "@types/bun": "^1.2.2",
+      },
+      "peerDependencies": {
+        "typescript": "^5.7.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.2", "", { "dependencies": { "bun-types": "1.2.2" } }, "sha512-tr74gdku+AEDN5ergNiBnplr7hpDp3V1h7fqI2GcR/rsUaM39jpSeKH0TFibRvU0KwniRx5POgaYnaXbk0hU+w=="],
+
+    "@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ=="],
+
+    "@types/node": ["@types/node@22.13.4", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-ywP2X0DYtX3y08eFVx5fNIw7/uIv8hYUKgXoK8oayJlLnKcRfEYCxWMVE1XagUdVtCJlZT1AU4LXEABW+L1Peg=="],
+
+    "@types/unist": ["@types/unist@3.0.3", "", {}, "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q=="],
+
+    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+
+    "bun-types": ["bun-types@1.2.2", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-RCbMH5elr9gjgDGDhkTTugA21XtJAy/9jkKe/G3WR2q17VPGhcquf9Sir6uay9iW+7P/BV0CAHA1XlHXMAVKHg=="],
+
+    "chalk": ["chalk@5.4.1", "", {}, "sha512-zgVZuo2WcZgfUEmsn6eO3kINexW8RAE4maiQ8QNs8CtpPCSyMiYsULR3HQYkm3w8FIA3SberyMJMSldGsW+U3w=="],
+
+    "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
+
+    "devlop": ["devlop@1.1.0", "", { "dependencies": { "dequal": "^2.0.0" } }, "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA=="],
+
+    "emphasize": ["emphasize@7.0.0", "", { "dependencies": { "@types/hast": "^3.0.0", "chalk": "^5.0.0", "highlight.js": "~11.9.0", "lowlight": "~3.1.0" } }, "sha512-jdFCDyt+YetBXO12VwK4AiLsMCvkZ3IBxMVIJddB+25EwIL0VETBgpvPkJl63+JyAgaQ5Wja10qWMoXXC95JNg=="],
+
+    "fastest-levenshtein": ["fastest-levenshtein@1.0.16", "", {}, "sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg=="],
+
+    "figlet": ["figlet@1.8.0", "", { "bin": { "figlet": "bin/index.js" } }, "sha512-chzvGjd+Sp7KUvPHZv6EXV5Ir3Q7kYNpCr4aHrRW79qFtTefmQZNny+W1pW9kf5zeE6dikku2W50W/wAH2xWgw=="],
+
+    "highlight.js": ["highlight.js@11.11.1", "", {}, "sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w=="],
+
+    "lowlight": ["lowlight@3.1.0", "", { "dependencies": { "@types/hast": "^3.0.0", "devlop": "^1.0.0", "highlight.js": "~11.9.0" } }, "sha512-CEbNVoSikAxwDMDPjXlqlFYiZLkDJHwyGu/MfOsJnF3d7f3tds5J3z8s/l9TMXhzfsJCCJEAsD78842mwmg0PQ=="],
+
+    "supports-color": ["supports-color@10.0.0", "", {}, "sha512-HRVVSbCCMbj7/kdWF9Q+bbckjBHLtHMEoJWlkmYzzdwhYMkjkOwubLM6t7NbWKjgKamGDrWL1++KrjUO1t9oAQ=="],
+
+    "ts-log": ["ts-log@2.2.7", "", {}, "sha512-320x5Ggei84AxzlXp91QkIGSw5wgaLT6GeAH0KsqDmRZdVWW2OiSeVvElVoatk3f7nicwXlElXsoFkARiGE2yg=="],
+
+    "typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
+
+    "undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
+
+    "emphasize/highlight.js": ["highlight.js@11.9.0", "", {}, "sha512-fJ7cW7fQGCYAkgv4CPfwFHrfd/cLS4Hau96JuJ+ZTOWhjnhoeN1ub1tFmALm/+lW5z4WCAuAV9bm05AP0mS6Gw=="],
+
+    "lowlight/highlight.js": ["highlight.js@11.9.0", "", {}, "sha512-fJ7cW7fQGCYAkgv4CPfwFHrfd/cLS4Hau96JuJ+ZTOWhjnhoeN1ub1tFmALm/+lW5z4WCAuAV9bm05AP0mS6Gw=="],
+  }
+}

package/index.ts

@@ -0,0 +1,89 @@
+// Argument API
+export type { default as Argument } from "./src/api/argument/Argument.ts";
+export type {
+  ArgumentSingleValueType,
+  ArgumentValues,
+  ArgumentValueType,
+  PopulatedArgumentSingleValueType,
+  PopulatedArgumentValues,
+  PopulatedArgumentValueType,
+} from "./src/api/argument/ArgumentValueTypes.ts";
+export {
+  ArgumentValueTypeName,
+  ComplexValueTypeName,
+} from "./src/api/argument/ArgumentValueTypes.ts";
+export type { default as ComplexOption } from "./src/api/argument/ComplexOption.ts";
+export type { default as SubCommandArgument } from "./src/api/argument/SubCommandArgument.ts";
+export type { default as GlobalCommandArgument } from "./src/api/argument/GlobalCommandArgument.ts";
+export type { default as Option } from "./src/api/argument/Option.ts";
+export type { default as Positional } from "./src/api/argument/Positional.ts";
+
+// Command API
+export type { default as Command } from "./src/api/command/Command.ts";
+export type { default as GlobalCommand } from "./src/api/command/GlobalCommand.ts";
+export type { default as GlobalModifierCommand } from "./src/api/command/GlobalModifierCommand.ts";
+export type { default as GroupCommand } from "./src/api/command/GroupCommand.ts";
+export type { default as SubCommand } from "./src/api/command/SubCommand.ts";
+export type { default as UsageExample } from "./src/api/command/UsageExample.ts";
+
+// Service API
+export type {
+  ServiceInfo,
+  ServiceProvider,
+} from "./src/api/service/ServiceProvider.ts";
+
+// Registry API
+export type { default as CommandRegistry } from "./src/runtime/registry/CommandRegistry.ts";
+export type { default as ServiceProviderRegistry } from "./src/runtime/registry/ServiceProviderRegistry.ts";
+
+// Core Services
+export { ASCII_BANNER_GENERATOR_SERVICE_ID } from "./src/api/service/core/AsciiBannerGeneratorService.ts";
+export type { default as AsciiBannerGeneratorService } from "./src/api/service/core/AsciiBannerGeneratorService.ts";
+export { default as DefaultAsciiBannerGeneratorService } from "./src/service/asciiBannerGenerator/DefaultAsciiBannerGeneratorService.ts";
+export { default as AsciiBannerGeneratorServiceProvider } from "./src/service/asciiBannerGenerator/AsciiBannerGeneratorServiceProvider.ts";
+
+export { default as BannerServiceProvider } from "./src/service/banner/BannerServiceProvider.ts";
+
+export { KEY_VALUE_SERVICE_ID } from "./src/api/service/core/KeyValueService.ts";
+export type { default as KeyValueService } from "./src/api/service/core/KeyValueService.ts";
+export { default as DefaultKeyValueService } from "./src/service/configuration/DefaultKeyValueService.ts";
+export { default as ConfigurationServiceProvider } from "./src/service/configuration/ConfigurationServiceProvider.ts";
+
+export { PRINTER_SERVICE_ID } from "./src/api/service/core/PrinterService.ts";
+export type {
+  default as PrinterService,
+} from "./src/api/service/core/PrinterService.ts";
+export { Icon, Level } from "./src/api/service/core/PrinterService.ts";
+export { default as DefaultPrinterService } from "./src/service/printer/DefaultPrinterService.ts";
+export { default as PrinterServiceProvider } from "./src/service/printer/PrinterServiceProvider.ts";
+
+export { SHUTDOWN_SERVICE_ID } from "./src/api/service/core/ShutdownService.ts";
+export type { default as ShutdownService } from "./src/api/service/core/ShutdownService.ts";
+export { default as DefaultShutdownService } from "./src/service/shutdown/DefaultShutdownService.ts";
+export { default as ShutdownServiceProvider } from "./src/service/shutdown/ShutdownServiceProvider.ts";
+
+export { SYNTAX_HIGHLIGHTER_SERVICE_ID } from "./src/api/service/core/SyntaxHighlighterService.ts";
+export type { default as SyntaxHighlighterService } from "./src/api/service/core/SyntaxHighlighterService.ts";
+export { default as DefaultSyntaxHighlighterService } from "./src/service/syntaxHighlighter/DefaultSyntaxHighlighterService.ts";
+export { default as SyntaxHighlighterServiceProvider } from "./src/service/syntaxHighlighter/SyntaxHighlighterServiceProvider.ts";
+
+// CLI API
+export type { InvalidArgument } from "./src/api/RunResult.ts";
+export type { default as Context } from "./src/api/Context.ts";
+export type {
+  default as RunResult,
+  InvalidArgumentReason,
+  RunState,
+} from "./src/api/RunResult.ts";
+export type { default as CLIConfig } from "./src/api/CLIConfig.ts";
+export type { default as CLI } from "./src/api/CLI.ts";
+
+// Core CLI
+export { default as BaseCLI } from "./src/cli/BaseCLI.ts";
+export { default as DefaultRuntimeCLI } from "./src/cli/DefaultRuntimeCLI.ts";
+
+// Convenience functions
+export {
+  launchMultiCommandCLI,
+  launchSingleCommandCLI,
+} from "./src/launcher.ts";

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@flowscripter/dynamic-cli-framework",
+  "module": "index.ts",
+  "type": "module",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "emphasize": "^7.0.0",
+    "fastest-levenshtein": "^1.0.16",
+    "figlet": "^1.8.0",
+    "highlight.js": "^11.11.1",
+    "supports-color": "^10.0.0",
+    "ts-log": "^2.2.7"
+  }
+}

package/src/api/CLI.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface to be implemented by a CLI application.
+ */
+import type RunResult from "./RunResult.ts";
+import type CLIConfig from "./CLIConfig.ts";
+
+export default interface CLI {
+  /**
+   * Run the CLI with the provided arguments which do not include the invoked executable name.
+   *
+   * @param args the arguments to parse.
+   * @param cliConfig the {@link CLIConfig} for the CLI application.
+   *
+   * @return result of parsing arguments and running appropriate {@link Command} instances.
+   */
+  run(args: ReadonlyArray<string>, cliConfig: CLIConfig): Promise<RunResult>;
+}

package/src/api/CLIConfig.ts

@@ -0,0 +1,19 @@
+/**
+ * Interface specifying common configuration for a {@link CLI} application.
+ */
+export default interface CLIConfig {
+  /**
+   * Name of the CLI application.
+   */
+  readonly name: string;
+
+  /**
+   * Optional description of the CLI application.
+   */
+  readonly description?: string;
+
+  /**
+   * Version of the CLI application.
+   */
+  readonly version: string;
+}

package/src/api/Context.ts

@@ -0,0 +1,25 @@
+/**
+ * Interface allowing a {@link CLI} to pass context to a {@link Command} instance.
+ */
+import type CLIConfig from "./CLIConfig.ts";
+
+export default interface Context {
+  /**
+   * The {@link CLIConfig} in use by the {@link CLI}.
+   */
+  readonly cliConfig: CLIConfig;
+
+  /**
+   * Return the service identified by the specified ID.
+   *
+   * @param id the ID of the service to retrieve.
+   */
+  getServiceById(id: string): unknown;
+
+  /**
+   * Check if the specified service exists in the context.
+   *
+   * @param id the ID of the desired service.
+   */
+  doesServiceExist(id: string): boolean;
+}

package/src/api/RunResult.ts

@@ -0,0 +1,142 @@
+/**
+ * State of a {@link CLI} after invocation.
+ */
+import type Command from "./command/Command.ts";
+import type Argument from "./argument/Argument.ts";
+import type ComplexOption from "./argument/ComplexOption.ts";
+import type {
+  PopulatedArgumentValues,
+  PopulatedArgumentValueType,
+} from "./argument/ArgumentValueTypes.ts";
+
+export enum RunState {
+  /**
+   * Arguments were successfully parsed and the specified command(s) were successfully executed.
+   */
+  SUCCESS = 0,
+
+  /**
+   * The arguments supplied were invalid or could not be parsed.
+   */
+  PARSE_ERROR = 1,
+
+  /**
+   * Arguments were successfully parsed but no command was discovered.
+   */
+  NO_COMMAND = 2,
+
+  /**
+   * Arguments were successfully parsed and command(s) discovered but command execution failed.
+   */
+  EXECUTION_ERROR = 3,
+
+  /**
+   * General runtime error related to the framework.
+   */
+  RUNTIME_ERROR = 4,
+}
+
+/**
+ * Possible reasons for an invalid argument.
+ */
+export enum InvalidArgumentReason {
+  /**
+   * The argument value was not specified.
+   */
+  MISSING_VALUE = 0,
+
+  /**
+   * The value specified was not the correct type for the argument.
+   */
+  INCORRECT_VALUE_TYPE = 1,
+
+  /**
+   * The argument does not support multiple values.
+   */
+  ILLEGAL_MULTIPLE_VALUES = 2,
+
+  /**
+   * The value specified was not one of the defined allowable values for the argument.
+   */
+  ILLEGAL_VALUE = 3,
+
+  /**
+   * The arguments specified resulted in a sparse array of values.
+   */
+  ILLEGAL_SPARSE_ARRAY = 4,
+
+  /**
+   * The argument specified an unknown complex option property.
+   */
+  UNKNOWN_PROPERTY = 5,
+
+  /**
+   * Complex option nesting exceeds maximum of {@link MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH}.
+   */
+  NESTING_DEPTH_EXCEEDED = 6,
+
+  /**
+   * Array value nesting exceeds maximum of {@link MAXIMUM_ARGUMENT_ARRAY_SIZE}.
+   */
+  ARRAY_SIZE_EXCEEDED = 7,
+
+  /**
+   * Attempt to set a primitive value on a complex object object.
+   */
+  OPTION_IS_COMPLEX = 8,
+}
+
+/**
+ * Details of an invalid parsed argument.
+ */
+export interface InvalidArgument {
+  /**
+   * A reason for the parsing error
+   */
+  readonly reason: InvalidArgumentReason;
+
+  /**
+   * The name of the argument specified (if it was able to be populated)
+   */
+  readonly name?: string;
+
+  /**
+   * The {@link Argument} (if it was able to be populated)
+   */
+  readonly argument?: Argument | ComplexOption;
+
+  /**
+   * The argument value (if it was able to be populated).
+   *
+   * NOTE: This value is unlikely to be valid as it is the cause of the invalid argument error.
+   */
+  readonly value?:
+    | PopulatedArgumentValues
+    | PopulatedArgumentValueType
+    | Array<PopulatedArgumentValues | PopulatedArgumentValueType>;
+}
+
+/**
+ * Result of a {@link CLI} invocation.
+ */
+export default interface RunResult {
+  /**
+   * The state after processing the invocation.
+   */
+  readonly runState: RunState;
+
+  /**
+   * Populated if {@link runState} is {@link RunState.SUCCESS}, {@link RunState.PARSE_ERROR} or {@link RunState.EXECUTION_ERROR}.
+   */
+  readonly command?: Command;
+
+  /**
+   * Populated if {@link runState} is {@link RunState.PARSE_ERROR}
+   */
+  readonly invalidArguments?: ReadonlyArray<InvalidArgument>;
+
+  /**
+   * Populated if {@link runState} is {@link RunState.EXECUTION_ERROR} or {@link RunState.RUNTIME_ERROR}.
+   */
+  readonly error?: Error;
+}

package/src/api/argument/Argument.ts

@@ -0,0 +1,36 @@
+import type {
+  ArgumentSingleValueType,
+  ArgumentValueTypeName,
+} from "./ArgumentValueTypes.ts";
+
+/**
+ * Interface to be implemented by all {@link Command} arguments.
+ */
+export default interface Argument {
+  /**
+   * Type of the argument value.
+   */
+  readonly type: ArgumentValueTypeName;
+
+  /**
+   * Optional list of values that the value must match.
+   */
+  readonly allowableValues?: ReadonlyArray<ArgumentSingleValueType>;
+
+  /**
+   * Optional configuration key to use for the argument. Must consist of alphanumeric non-whitespace uppercase
+   * ASCII or `_` characters. Must not start with a digit.
+   *
+   * If not specified a default configuration key is determined as follows: The {@link Argument.name} is capitalized
+   * and any `-` characters are replaced with `_` characters. If the result starts with a digit, it is
+   * prefixed with `_`. Some examples:
+   *
+   * * name: `FooBar` => configuration key: `FOOBAR`
+   * * name: `Hello-World-` => configuration key: `HELLO_WORLD_`
+   * * name: `3` => configuration key: `_3`
+   *
+   * NOTE: Regardless of whether a {@link configurationKey} is specified, or the default is relied upon,
+   * it will only be used if the parent {@link Command} has specified {@link Command.enableConfiguration} as `true`.
+   */
+  readonly configurationKey?: string;
+}

package/src/api/argument/ArgumentValueTypes.ts

@@ -0,0 +1,87 @@
+/**
+ * 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,
+}
+
+/**
+ * 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/api/argument/ComplexOption.ts

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

@@ -0,0 +1,22 @@
+/**
+ * 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;
+}