@flowscripter/dynamic-cli-framework-api 1.0.0

package/dist/src/service/core/Table.js

@@ -0,0 +1,49 @@
+export default class Table {
+    rowCount;
+    columnCount;
+    options;
+    #columnOptions = new Map();
+    #rowOptions = new Map();
+    #cells = new Map();
+    constructor(rowCount, columnCount, options) {
+        this.rowCount = rowCount;
+        this.columnCount = columnCount;
+        this.options = options ?? {};
+    }
+    row(rowIndex, rowOptions) {
+        if (rowIndex < 0 || rowIndex >= this.rowCount) {
+            throw new Error(`Row index ${rowIndex} out of bounds [0, ${this.rowCount})`);
+        }
+        this.#rowOptions.set(rowIndex, rowOptions);
+        return this;
+    }
+    column(columnIndex, columnOptions) {
+        if (columnIndex < 0 || columnIndex >= this.columnCount) {
+            throw new Error(`Column index ${columnIndex} out of bounds [0, ${this.columnCount})`);
+        }
+        this.#columnOptions.set(columnIndex, columnOptions);
+        return this;
+    }
+    cell(rowIndex, columnIndex, contents, cellOptions) {
+        if (rowIndex < 0 || rowIndex >= this.rowCount) {
+            throw new Error(`Row index ${rowIndex} out of bounds [0, ${this.rowCount})`);
+        }
+        if (columnIndex < 0 || columnIndex >= this.columnCount) {
+            throw new Error(`Column index ${columnIndex} out of bounds [0, ${this.columnCount})`);
+        }
+        this.#cells.set(`${rowIndex},${columnIndex}`, {
+            contents,
+            options: cellOptions,
+        });
+        return this;
+    }
+    getColumnOptions(columnIndex) {
+        return this.#columnOptions.get(columnIndex);
+    }
+    getRowOptions(rowIndex) {
+        return this.#rowOptions.get(rowIndex);
+    }
+    getCell(rowIndex, columnIndex) {
+        return this.#cells.get(`${rowIndex},${columnIndex}`);
+    }
+}

package/dist/src/service/core/TableGeneratorService.d.ts

@@ -0,0 +1,32 @@
+export declare const TABLE_GENERATOR_SERVICE_ID = "@flowscripter/dynamic-cli-framework/table-generator-service";
+export declare enum Align {
+    LEFT = 0,
+    CENTER = 1,
+    RIGHT = 2
+}
+export interface TableOptions {
+    border?: boolean;
+    borderColor?: string;
+    borderBackgroundColor?: string;
+    padding?: number;
+    maxWidth?: number;
+    align?: Align;
+}
+export interface ColumnOptions {
+    flexWeight?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    align?: Align;
+}
+export interface RowOptions {
+    align?: Align;
+}
+export interface CellOptions {
+    align?: Align;
+}
+export default interface TableGeneratorService {
+    createTable(rowCount: number, columnCount: number, options?: TableOptions): Table;
+    render(table: Table): string;
+}
+import type Table from "./Table.ts";
+//# sourceMappingURL=TableGeneratorService.d.ts.map

package/dist/src/service/core/TableGeneratorService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TableGeneratorService.d.ts","sourceRoot":"","sources":["../../../../src/service/core/TableGeneratorService.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,gEACwB,CAAC;AAEhE,oBAAY,KAAK;IACf,IAAI,IAAI;IACR,MAAM,IAAI;IACV,KAAK,IAAI;CACV;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,CAAC,OAAO,WAAW,qBAAqB;IAC5C,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,CAAC;IAClF,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;CAC9B;AAED,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC"}

package/dist/src/service/core/TableGeneratorService.js

@@ -0,0 +1,7 @@
+export const TABLE_GENERATOR_SERVICE_ID = "@flowscripter/dynamic-cli-framework/table-generator-service";
+export var Align;
+(function (Align) {
+    Align[Align["LEFT"] = 0] = "LEFT";
+    Align[Align["CENTER"] = 1] = "CENTER";
+    Align[Align["RIGHT"] = 2] = "RIGHT";
+})(Align || (Align = {}));

package/dist/src/service/core/TreePrinterService.d.ts

@@ -0,0 +1,9 @@
+export declare const TREE_PRINTER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/tree-printer-service";
+export interface TreeNode {
+    label: string;
+    children?: Array<TreeNode | string>;
+}
+export default interface TreePrinterService {
+    print(node: TreeNode): string;
+}
+//# sourceMappingURL=TreePrinterService.d.ts.map

package/dist/src/service/core/TreePrinterService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreePrinterService.d.ts","sourceRoot":"","sources":["../../../../src/service/core/TreePrinterService.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,6DAA6D,CAAC;AAElG,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,CAAC,OAAO,WAAW,kBAAkB;IACzC,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC/B"}

package/dist/src/service/core/TreePrinterService.js

@@ -0,0 +1 @@
+export const TREE_PRINTER_SERVICE_ID = "@flowscripter/dynamic-cli-framework/tree-printer-service";

package/index.ts

@@ -0,0 +1,138 @@
+// Argument API
+export type { default as Argument } from "./src/argument/Argument.ts";
+export type {
+  ArgumentSingleValueType,
+  ArgumentValues,
+  ArgumentValueType,
+  PopulatedArgumentSingleValueType,
+  PopulatedArgumentValues,
+  PopulatedArgumentValueType,
+} from "./src/argument/ArgumentValueTypes.ts";
+export { ArgumentValueTypeName, ComplexValueTypeName } from "./src/argument/ArgumentValueTypes.ts";
+export type { default as ComplexOption } from "./src/argument/ComplexOption.ts";
+export { MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH } from "./src/argument/ComplexOption.ts";
+export type { default as SubCommandArgument } from "./src/argument/SubCommandArgument.ts";
+export { MAXIMUM_ARGUMENT_ARRAY_SIZE } from "./src/argument/SubCommandArgument.ts";
+export type { default as GlobalCommandArgument } from "./src/argument/GlobalCommandArgument.ts";
+export type { default as Option } from "./src/argument/Option.ts";
+export type { default as Positional } from "./src/argument/Positional.ts";
+
+// Command API
+export type { default as Command } from "./src/command/Command.ts";
+export type { default as GlobalCommand } from "./src/command/GlobalCommand.ts";
+export type { default as GlobalModifierCommand } from "./src/command/GlobalModifierCommand.ts";
+export type { default as GroupCommand } from "./src/command/GroupCommand.ts";
+export type { default as SubCommand } from "./src/command/SubCommand.ts";
+export type { default as UsageExample } from "./src/command/UsageExample.ts";
+
+// Service API
+export type { ServiceInfo, ServiceProvider } from "./src/service/ServiceProvider.ts";
+
+// Registry API
+export type { default as CommandRegistry } from "./src/registry/CommandRegistry.ts";
+export type { default as ServiceProviderRegistry } from "./src/registry/ServiceProviderRegistry.ts";
+
+// Core Service IDs and types
+export { ASCII_BANNER_GENERATOR_SERVICE_ID } from "./src/service/core/AsciiBannerGeneratorService.ts";
+export type { default as AsciiBannerGeneratorService } from "./src/service/core/AsciiBannerGeneratorService.ts";
+export type {
+  BannerColorEffects,
+  BannerGenerateOptions,
+  ColorEffect,
+  ColorEffectDirection,
+  FixedColorEffect,
+  GradientColorEffect,
+  RainbowColorEffect,
+} from "./src/service/core/AsciiBannerGeneratorService.ts";
+
+export { KEY_VALUE_SERVICE_ID } from "./src/service/core/KeyValueService.ts";
+export { SECRET_SENTINEL_PREFIX } from "./src/service/core/KeyValueService.ts";
+export type { default as KeyValueService } from "./src/service/core/KeyValueService.ts";
+export type { default as SecretService } from "./src/service/core/SecretService.ts";
+
+export { PRINTER_SERVICE_ID } from "./src/service/core/PrinterService.ts";
+export type { default as PrinterService } from "./src/service/core/PrinterService.ts";
+export { Icon, Level, ProgressStyle, SpinnerStyle } from "./src/service/core/PrinterService.ts";
+
+export { SHUTDOWN_SERVICE_ID } from "./src/service/core/ShutdownService.ts";
+export type { default as ShutdownService } from "./src/service/core/ShutdownService.ts";
+
+export { SYNTAX_HIGHLIGHTER_SERVICE_ID } from "./src/service/core/SyntaxHighlighterService.ts";
+export type { default as SyntaxHighlighterService } from "./src/service/core/SyntaxHighlighterService.ts";
+export type { ColorScheme } from "./src/service/core/SyntaxHighlighterService.ts";
+
+export { PRETTY_PRINTER_SERVICE_ID } from "./src/service/core/PrettyPrinterService.ts";
+export type { default as PrettyPrinterService } from "./src/service/core/PrettyPrinterService.ts";
+
+export { IMAGE_PRINTER_SERVICE_ID } from "./src/service/core/ImagePrinterService.ts";
+export type { default as ImagePrinterService } from "./src/service/core/ImagePrinterService.ts";
+
+export { TREE_PRINTER_SERVICE_ID } from "./src/service/core/TreePrinterService.ts";
+export type { default as TreePrinterService } from "./src/service/core/TreePrinterService.ts";
+export type { TreeNode } from "./src/service/core/TreePrinterService.ts";
+
+export { TABLE_GENERATOR_SERVICE_ID } from "./src/service/core/TableGeneratorService.ts";
+export type { default as TableGeneratorService } from "./src/service/core/TableGeneratorService.ts";
+export {
+  Align,
+  type CellOptions,
+  type ColumnOptions,
+  type RowOptions,
+  type TableOptions,
+} from "./src/service/core/TableGeneratorService.ts";
+export { default as Table } from "./src/service/core/Table.ts";
+
+export { DATA_DUMP_GENERATOR_SERVICE_ID } from "./src/service/core/DataDumpGeneratorService.ts";
+export type { default as DataDumpGeneratorService } from "./src/service/core/DataDumpGeneratorService.ts";
+export {
+  type ByteRangeColor,
+  DumpFormat,
+  type HexDumpGenerateOptions,
+} from "./src/service/core/DataDumpGeneratorService.ts";
+
+export { COMPLETION_SERVICE_ID } from "./src/service/core/CompletionService.ts";
+export type { default as CompletionService } from "./src/service/core/CompletionService.ts";
+export { type CompletionItem, ShellType } from "./src/service/core/CompletionService.ts";
+
+export { PROMPTER_SERVICE_ID } from "./src/service/core/PrompterService.ts";
+export type { default as PrompterService } from "./src/service/core/PrompterService.ts";
+export {
+  type Prompt,
+  type PromptOption,
+  type PromptResult,
+  PromptType,
+} from "./src/service/core/PrompterService.ts";
+
+export { ARGUMENT_PROMPTER_SERVICE_ID } from "./src/service/core/ArgumentPrompterService.ts";
+export type { default as ArgumentPrompterService } from "./src/service/core/ArgumentPrompterService.ts";
+export type { ParseResult } from "./src/ParseResult.ts";
+
+// CLI API
+export type { InvalidArgument } from "./src/RunResult.ts";
+export type { default as Context } from "./src/Context.ts";
+export type { default as RunResult } from "./src/RunResult.ts";
+export { InvalidArgumentReason, RunState } from "./src/RunResult.ts";
+export type { default as CLIConfig } from "./src/CLIConfig.ts";
+export type { default as CLI } from "./src/CLI.ts";
+
+// Plugin API
+export type { default as CommandFactory } from "./src/plugin/CommandFactory.ts";
+export { DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT } from "./src/plugin/CommandFactory.ts";
+export type { default as ServiceProviderFactory } from "./src/plugin/ServiceProviderFactory.ts";
+export { DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT } from "./src/plugin/ServiceProviderFactory.ts";
+export type {
+  Plugin,
+  ExtensionDescriptor,
+  ExtensionFactory,
+  VersionedPluginDescriptor,
+  SearchQuery,
+} from "@flowscripter/dynamic-plugin-framework";
+export type {
+  default as CLIPlugin,
+  CommandFactoryExtensionDescriptor,
+  ServiceProviderFactoryExtensionDescriptor,
+} from "./src/plugin/CLIPlugin.ts";
+export { default as createCLIPlugin } from "./src/plugin/createCLIPlugin.ts";
+export type { CLIPluginOptions } from "./src/plugin/createCLIPlugin.ts";
+export { PLUGIN_SERVICE_ID } from "./src/service/core/PluginService.ts";
+export type { default as PluginService } from "./src/service/core/PluginService.ts";

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@flowscripter/dynamic-cli-framework-api",
+  "version": "1.0.0",
+  "description": "API for https://github.com/flowscripter/dynamic-cli-framework",
+  "keywords": [
+    "bun",
+    "cli",
+    "dynamic",
+    "dynamic-cli-framework",
+    "framework",
+    "import",
+    "plugin"
+  ],
+  "homepage": "https://github.com/flowscripter/dynamic-cli-framework-api#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowscripter/dynamic-cli-framework-api.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@flowscripter/dynamic-plugin-framework": "1.10.1",
+    "@types/bun": "^1.3.14",
+    "highlight.js": "^11.11.1",
+    "oxfmt": "0.57.0",
+    "oxlint": "1.72.0",
+    "prettier": "^3.9.5"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "typedocOptions": {
+    "readme": "none",
+    "exclude": [
+      "tests/**"
+    ],
+    "externalSymbolLinkMappings": {
+      "@flowscripter/dynamic-plugin-framework": {
+        "default": "https://flowscripter.github.io/dynamic-plugin-framework/interfaces/PluginDescriptor.html"
+      }
+    }
+  }
+}

package/src/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/CLIConfig.ts

@@ -0,0 +1,24 @@
+/**
+ * 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;
+
+  /**
+   * Optional sub-message to display below the banner.
+   */
+  readonly subMessage?: string;
+
+  /**
+   * Version of the CLI application.
+   */
+  readonly version: string;
+}

package/src/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/ParseResult.ts

@@ -0,0 +1,40 @@
+import type Command from "./command/Command.ts";
+import type GroupCommand from "./command/GroupCommand.ts";
+import type {
+  PopulatedArgumentSingleValueType,
+  PopulatedArgumentValues,
+} from "./argument/ArgumentValueTypes.ts";
+import type { InvalidArgument } from "./RunResult.ts";
+
+/**
+ * A container holding the result of a command clause parsing operation.
+ */
+export interface ParseResult {
+  /**
+   * The {@link Command} to execute if the parse result is valid (i.e. {@link invalidArguments} is empty).
+   */
+  readonly command: Command;
+
+  /**
+   * Optional parent {@link GroupCommand} if the parsed {@link command} was a member {@link SubCommand},
+   */
+  readonly groupCommand?: GroupCommand;
+
+  /**
+   * The argument values populated from the command line args. If the parse result is valid
+   * (i.e. {@link invalidArguments} is empty), this can be used to execute the specified {@link command}.
+   * {@link PopulatedArgumentSingleValueType} is for {@link GlobalCommand} values, {@link PopulatedArgumentValues} is for
+   * {@link SubCommand} values.
+   */
+  readonly populatedArgumentValues: PopulatedArgumentValues | PopulatedArgumentSingleValueType;
+
+  /**
+   * Any arguments which were invalid.
+   */
+  readonly invalidArguments: ReadonlyArray<InvalidArgument>;
+
+  /**
+   * Any arguments which were unused in the parsing operation.
+   */
+  readonly unusedArgs: ReadonlyArray<string>;
+}

package/src/RunResult.ts

@@ -0,0 +1,158 @@
+/**
+ * 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,
+
+  /**
+   * Execution was interrupted by a signal (e.g. Ctrl-C or SIGTERM).
+   */
+  INTERRUPTED = 130,
+}
+
+/**
+ * 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,
+
+  /**
+   * The value failed a custom validation function defined on the argument.
+   */
+  CUSTOM_VALIDATION = 9,
+}
+
+/**
+ * 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>;
+
+  /**
+   * An optional message providing detail about the validation failure.
+   * Populated when {@link reason} is {@link InvalidArgumentReason.CUSTOM_VALIDATION}.
+   */
+  readonly message?: string;
+}
+
+/**
+ * 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/argument/Argument.ts

@@ -0,0 +1,75 @@
+import type {
+  ArgumentSingleValueType,
+  ArgumentValues,
+  ArgumentValueType,
+  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. This is not supported for {@link ArgumentValueTypeName.BOOLEAN}.
+   */
+  readonly allowableValues?: ReadonlyArray<ArgumentSingleValueType>;
+
+  /**
+   * Optional (default is `false`) for {@link ArgumentValueTypeName.STRING} when comparing a value against {@link allowableValues}.
+   */
+  readonly isCaseInsensitive?: boolean;
+
+  /**
+   * Optional for {@link ArgumentValueTypeName.INTEGER} or {@link ArgumentValueTypeName.NUMBER} when validating a value.
+   */
+  readonly minValueInclusive?: number;
+
+  /**
+   * Optional for {@link ArgumentValueTypeName.INTEGER} or {@link ArgumentValueTypeName.NUMBER} when validating a value.
+   */
+  readonly maxValueInclusive?: number;
+
+  /**
+   * 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 SubCommandArgument.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;
+
+  /**
+   * Optional custom validation function invoked after all built-in validation
+   * has passed. Receives the validated and type-converted value.
+   *
+   * Return `undefined` if the value is valid, or a string describing the
+   * validation error. The error string is associated with
+   * {@link InvalidArgumentReason.CUSTOM_VALIDATION}.
+   *
+   * Example: ensure array values are unique:
+   * ```typescript
+   * validate: (value) => {
+   *   const arr = value as string[];
+   *   return new Set(arr).size !== arr.length
+   *     ? "values must be unique"
+   *     : undefined;
+   * }
+   * ```
+   */
+  readonly validate?: (
+    value: ArgumentValueType | ArgumentValues | Array<ArgumentValues>,
+  ) => string | undefined;
+}