@bemoje/cli 1.0.6 → 1.1.0

package/lib/Command.d.ts

@@ -1,6 +1,6 @@
 import type { ParseArgsOptionDescriptor } from 'node:util';
 import type { IHelp } from './Help';
-import { CommandHelpAdapter } from './CommandHelpAdapter';
+import type { AllUnionFields } from 'type-fest';
 /**
  * Command-line argument parser with fluent API and type-safe validation.
  * Enforces CLI argument ordering rules and provides structured parsing results.
@@ -8,12 +8,12 @@ import { CommandHelpAdapter } from './CommandHelpAdapter';
  * @example
  * ```typescript
  * const cmd = new Command('myapp')
- *   .argument('<input>', 'input file')
- *   .argument('[output]', 'output file', 'out.txt')
- *   .option('-v, --verbose', 'verbose output')
- *   .option('-f, --format <type>', 'output format')
+ *   .addArgument('<input>', 'input file')
+ *   .addArgument('[output]', 'output file', 'out.txt')
+ *   .addOption('-v, --verbose', 'verbose output')
+ *   .addOption('-f, --format <type>', 'output format')
  *
- * const result = cmd.parse(['input.txt', '-v', '-f', 'json'])
+ * cmd.parseArgv(['input.txt', '-v', '-f', 'json'])
  * ```
  */
 export declare class Command implements CommandDescriptor {
@@ -42,22 +42,6 @@ export declare class Command implements CommandDescriptor {
     /** Help system configuration */
     helpConfiguration: Partial<IHelp>;
     constructor(name?: string, parent?: Command | null);
-    /** Updates multiple command properties at once */
-    setState(state: Partial<CommandDescriptor>): this;
-    /** Serializes command to JSON, maintaining compatibility with previous state-based structure */
-    toJSON(): {
-        name: string;
-        version: string;
-        aliases: string[];
-        summary: string;
-        description: string;
-        hidden: boolean;
-        group: string;
-        commands: Command[];
-        arguments: ArgumentDescriptor[];
-        options: OptionDescriptor[];
-        helpConfiguration: Partial<IHelp>;
-    };
     /** Sets the command name */
     setName(name: string): void;
     /** Sets command aliases, flattening nested arrays */
@@ -68,7 +52,7 @@ export declare class Command implements CommandDescriptor {
     setVersion(version?: string): this;
     /** Sets the command summary */
     setSummary(summary?: string): this;
-    /** Sets command description, joining multiple lines */
+    /** Sets command description, joining variadic lines */
     setDescription(...lines: string[]): this;
     /** Sets whether command is hidden from help */
     setHidden(hidden?: boolean | undefined): this;
@@ -81,25 +65,26 @@ export declare class Command implements CommandDescriptor {
     /** Sets help configuration, using defaults if not provided */
     setHelpConfiguration(config?: Partial<IHelp>): this;
     /** Creates and adds a subcommand */
-    subcommand(name: string): Command;
+    addSubcommand(name: string): Command;
     /** Add required argument. Usage: `<name>` */
-    argument(usage: `<${string}>`, description: string, options?: ArgOpts<RequiredArgumentDescriptor>): this;
+    addArgument(usage: `<${string}>`, description: string, options?: ArgOpts<RequiredArgumentDescriptor>): this;
     /** Add optional argument with default. Usage: `[name]` */
-    argument(usage: `[${string}]`, description: string, options?: ArgOpts<OptionalArgumentDescriptor>): this;
+    addArgument(usage: `[${string}]`, description: string, options?: ArgOpts<OptionalArgumentDescriptor>): this;
     /** Add required variadic argument. Usage: `<name...>` */
-    argument(usage: `<${string}...>`, description: string, options?: ArgOpts<RequiredVariadicArgumentDescriptor>): this;
+    addArgument(usage: `<${string}...>`, description: string, options?: ArgOpts<RequiredVariadicArgumentDescriptor>): this;
     /** Add optional variadic argument with defaults. Usage: `[name...]` */
-    argument(usage: `[${string}...]`, description: string, options?: ArgOpts<OptionalVariadicArgumentDescriptor>): this;
+    addArgument(usage: `[${string}...]`, description: string, options?: ArgOpts<OptionalVariadicArgumentDescriptor>): this;
     /** Add required string option. Usage: `-f, --file <path>` */
-    option(usage: `-${string}, --${string} <${string}>`, description: string, options?: OptOpts<RequiredOptionDescriptor>): this;
+    addOption(flags: `-${string}, --${string} <${string}>`, description: string, options?: OptOpts<RequiredOptionDescriptor>): this;
     /** Add optional string option with default. Usage: `-o, --output [path]` */
-    option(usage: `-${string}, --${string} [${string}]`, description: string, options?: OptOpts<OptionalOptionDescriptor>): this;
+    addOption(flags: `-${string}, --${string} [${string}]`, description: string, options?: OptOpts<OptionalOptionDescriptor>): this;
     /** Add required variadic option. Usage: `-i, --include <patterns...>` */
-    option(usage: `-${string}, --${string} <${string}...>`, description: string, options?: OptOpts<RequiredVariadicOptionDescriptor>): this;
+    addOption(flags: `-${string}, --${string} <${string}...>`, description: string, options?: OptOpts<RequiredVariadicOptionDescriptor>): this;
     /** Add optional variadic option with defaults. Usage: `-e, --exclude [patterns...]` */
-    option(usage: `-${string}, --${string} [${string}...]`, description: string, options?: OptOpts<OptionalVariadicOptionDescriptor>): this;
+    addOption(flags: `-${string}, --${string} [${string}...]`, description: string, options?: OptOpts<OptionalVariadicOptionDescriptor>): this;
     /** Add boolean flag option. Usage: `-v, --verbose` */
-    option(usage: `-${string}, --${string}`, description: string, options?: OptOpts<BooleanOptionDescriptor>): this;
+    addOption(flags: `-${string}, --${string}`, description: string, options?: OptOpts<BooleanOptionDescriptor>): this;
+    private _addOption;
     /**
      * Parses command-line arguments with subcommand support and type-safe validation.
      *
@@ -109,13 +94,15 @@ export declare class Command implements CommandDescriptor {
      * // { arguments: ['input.txt'], options: { verbose: true, format: 'json' } }
      * ```
      */
-    parse(argv?: string[], globalOptions?: OptionDescriptor[]): {
+    parseArgv(argv?: string[], globalOptions?: OptionDescriptor[]): {
         command: Command;
         arguments: (string | string[])[];
         options: {
             [x: string]: string | boolean | (string | boolean)[] | undefined;
         };
     };
+    /** Renders formatted help text using provided help definition */
+    renderHelp(help: IHelp): string;
     /** Validates CLI argument ordering */
     protected assertNoOptionalOrVariadicArguments(): void;
     /** Validates optional args don't follow variadic args */
@@ -135,87 +122,89 @@ export declare class Command implements CommandDescriptor {
     /** Returns all ancestor commands excluding this command */
     getAncestors(): Command[];
     /** Returns all options from this command and ancestors */
-    getOptionsInclAncestors(): OptionDescriptor[];
+    getOptionsInclAncestors(): {
+        name: string;
+        long: string;
+        short: string;
+        required?: boolean;
+        type: "string" | "boolean";
+        optional?: boolean;
+        negate?: boolean;
+        hidden?: boolean;
+        description: string;
+        group?: string;
+        variadic?: boolean;
+        defaultValue?: string | boolean | string[];
+        flags: string;
+        defaultValueDescription?: string;
+        choices?: string[];
+        argName?: string;
+        env?: string;
+    }[];
     /** Finds subcommand by name or alias */
     findCommand(this: Command, name: string): Command;
     /** Finds option by short or long name */
     findOption(this: Command, arg: string): OptionDescriptor | undefined;
-    /** Returns a view that is compliant with the CommandHelp interface */
-    createHelpAdapter(): CommandHelpAdapter;
-    /** Renders formatted help text using provided help definition */
-    renderHelp(help: IHelp): string;
+    /** Returns a new Command instance. Override this method in subclasses. */
+    createCommand(name?: string, parent?: Command | null): Command;
 }
-/** Usage patterns for boolean flag options */
-type BooleanOptionUsage = `-${string}, --${string}`;
-/** Usage patterns for required string options */
-type RequiredOptionUsage = `-${string}, --${string} <${string}>`;
-/** Usage patterns for optional string options */
-type OptionalOptionUsage = `-${string}, --${string} [${string}]`;
-/** Usage patterns for required variadic options */
-type RequiredVariadicOptionUsage = `-${string}, --${string} <${string}...>`;
-/** Usage patterns for optional variadic options */
-type OptionalVariadicOptionUsage = `-${string}, --${string} [${string}...]`;
-/** Union of all option usage pattern types */
-export type OptionUsage = BooleanOptionUsage | RequiredOptionUsage | OptionalOptionUsage | RequiredVariadicOptionUsage | OptionalVariadicOptionUsage;
-/** Usage pattern for required positional arguments */
-type RequiredArgumentUsage = `<${string}>`;
-/** Usage pattern for optional positional arguments */
-type OptionalArgumentUsage = `[${string}]`;
-/** Usage pattern for required variadic arguments */
-type RequiredVariadicArgumentUsage = `<${string}...>`;
-/** Usage pattern for optional variadic arguments */
-type OptionalVariadicArgumentUsage = `[${string}...]`;
-/** Union of all argument usage pattern types */
-export type ArgumentUsage = RequiredArgumentUsage | OptionalArgumentUsage | RequiredVariadicArgumentUsage | OptionalVariadicArgumentUsage;
 /** Base descriptor for command-line arguments with shared properties */
-interface ArgumentDescriptorBase {
+export interface ArgumentDescriptorBase {
     name: string;
-    required: boolean;
     description: string;
-    multiple: boolean;
+    required?: boolean;
+    variadic?: boolean;
     choices?: string[];
-    defaultValue?: string | string[] | never;
-    defaultValueDescription?: string | never;
+    defaultValue?: string | string[];
+    defaultValueDescription?: string;
 }
 /** Required positional argument descriptor. Usage: `<name>` */
 interface RequiredArgumentDescriptor extends ArgumentDescriptorBase {
-    multiple: false;
+    variadic?: false;
     required: true;
-    defaultValue?: never;
-    defaultValueDescription?: never;
+    defaultValue?: undefined;
+    defaultValueDescription?: undefined;
 }
 /** Optional positional argument with string default. Usage: `[name]` */
 interface OptionalArgumentDescriptor extends ArgumentDescriptorBase {
-    required: false;
-    multiple: false;
+    required?: false;
+    variadic?: false;
     defaultValue?: string;
     defaultValueDescription?: string;
 }
-/** Required variadic argument accepting multiple values. Usage: `<name...>` */
+/** Required variadic argument accepting variadic values. Usage: `<name...>` */
 interface RequiredVariadicArgumentDescriptor extends ArgumentDescriptorBase {
     required: true;
-    multiple: true;
-    defaultValue?: never;
-    defaultValueDescription?: never;
+    variadic: true;
+    defaultValue?: undefined;
+    defaultValueDescription?: undefined;
 }
 /** Optional variadic argument with array default. Usage: `[name...]` */
 interface OptionalVariadicArgumentDescriptor extends ArgumentDescriptorBase {
-    required: false;
-    multiple: true;
+    required?: false;
+    variadic: true;
     defaultValue?: string[];
     defaultValueDescription?: string;
 }
+/** Union type for all argument descriptor variants */
+type ArgumentDescriptorStrict = RequiredArgumentDescriptor | OptionalArgumentDescriptor | RequiredVariadicArgumentDescriptor | OptionalVariadicArgumentDescriptor;
+/** Helper type for extracting argument configuration options */
+type ArgOpts<T extends ArgumentDescriptorStrict> = Omit<T, 'name' | 'description' | 'required' | 'variadic'>;
 /** Base descriptor for command-line options with shared properties */
-interface OptionDescriptorBase extends ParseArgsOptionDescriptor {
-    type: 'boolean' | 'string';
+export interface OptionDescriptorBase extends Omit<ParseArgsOptionDescriptor, 'type'> {
+    type?: ParseArgsOptionDescriptor['type'];
+    flags: string;
     short: string;
+    long: string;
     name: string;
-    argName?: string | never;
+    argName?: string;
     description: string;
-    required: boolean;
-    multiple: boolean;
-    defaultValue?: boolean | string | string[] | never;
-    defaultValueDescription?: string | never;
+    required?: boolean;
+    optional?: boolean;
+    variadic?: boolean;
+    negate?: boolean;
+    defaultValue?: boolean | string | string[];
+    defaultValueDescription?: string;
     env?: string;
     hidden?: boolean;
     choices?: string[];
@@ -224,9 +213,11 @@ interface OptionDescriptorBase extends ParseArgsOptionDescriptor {
 /** Boolean flag option. Usage: `-v, --verbose` */
 interface BooleanOptionDescriptor extends OptionDescriptorBase {
     type: 'boolean';
-    argName?: never;
-    required: false;
-    multiple: false;
+    argName?: undefined;
+    required?: false;
+    optional: true;
+    variadic?: false;
+    negate: boolean;
     defaultValue?: boolean;
     defaultValueDescription?: string;
 }
@@ -235,37 +226,49 @@ interface RequiredOptionDescriptor extends OptionDescriptorBase {
     type: 'string';
     argName: string;
     required: true;
-    multiple: false;
-    defaultValue?: never;
-    defaultValueDescription?: never;
+    optional?: false;
+    variadic?: false;
+    negate?: false;
+    defaultValue?: undefined;
+    defaultValueDescription?: undefined;
 }
 /** Optional string option with default. Usage: `-o, --output [path]` */
 interface OptionalOptionDescriptor extends OptionDescriptorBase {
     type: 'string';
     argName: string;
-    required: false;
-    multiple: false;
+    required?: false;
+    optional: true;
+    variadic?: false;
+    negate?: false;
     defaultValue?: string;
     defaultValueDescription?: string;
 }
-/** Required option accepting multiple values. Usage: `-i, --include <patterns...>` */
+/** Required option accepting variadic values. Usage: `-i, --include <patterns...>` */
 interface RequiredVariadicOptionDescriptor extends OptionDescriptorBase {
     type: 'string';
     argName: string;
     required: true;
-    multiple: true;
-    defaultValue?: never;
-    defaultValueDescription?: never;
+    optional?: false;
+    variadic: true;
+    negate?: false;
+    defaultValue?: undefined;
+    defaultValueDescription?: undefined;
 }
-/** Optional option accepting multiple values with defaults. Usage: `-e, --exclude [patterns...]` */
+/** Optional option accepting variadic values with defaults. Usage: `-e, --exclude [patterns...]` */
 interface OptionalVariadicOptionDescriptor extends OptionDescriptorBase {
     type: 'string';
     argName: string;
-    required: false;
-    multiple: true;
+    required?: false;
+    optional: true;
+    variadic: true;
+    negate?: false;
     defaultValue?: string[];
     defaultValueDescription?: string;
 }
+/** Union type for all option descriptor variants */
+type OptionDescriptorStrict = BooleanOptionDescriptor | RequiredOptionDescriptor | OptionalOptionDescriptor | RequiredVariadicOptionDescriptor | OptionalVariadicOptionDescriptor;
+/** Helper type for extracting option configuration options */
+type OptOpts<T extends OptionDescriptorStrict> = Omit<T, 'name' | 'description' | 'required' | 'variadic' | 'negate' | 'optional' | 'type' | 'argName' | 'short' | 'long' | 'flags'>;
 /** Complete command configuration including all properties and substructures */
 export interface CommandDescriptor {
     name: string;
@@ -275,19 +278,13 @@ export interface CommandDescriptor {
     description: string;
     hidden?: boolean;
     group?: string;
-    parent: Command | null;
-    commands: Command[];
-    arguments: ArgumentDescriptor[];
-    options: OptionDescriptor[];
+    parent: CommandDescriptor | null;
+    commands: CommandDescriptor[];
+    arguments: ArgumentDescriptorBase[];
+    options: OptionDescriptorBase[];
     helpConfiguration: Partial<IHelp>;
 }
-/** Union type for all argument descriptor variants */
-export type ArgumentDescriptor = RequiredArgumentDescriptor | OptionalArgumentDescriptor | RequiredVariadicArgumentDescriptor | OptionalVariadicArgumentDescriptor;
-/** Union type for all option descriptor variants */
-export type OptionDescriptor = BooleanOptionDescriptor | RequiredOptionDescriptor | OptionalOptionDescriptor | RequiredVariadicOptionDescriptor | OptionalVariadicOptionDescriptor;
-/** Helper type for extracting argument configuration options */
-type ArgOpts<T extends ArgumentDescriptor> = Omit<T, 'name' | 'description' | 'required' | 'multiple'>;
-/** Helper type for extracting option configuration options */
-type OptOpts<T extends OptionDescriptor> = Omit<T, 'name' | 'description' | 'required' | 'multiple' | 'type' | 'argName' | 'short' | 'long'>;
+export type OptionDescriptor = AllUnionFields<OptionDescriptorStrict>;
+export type ArgumentDescriptor = AllUnionFields<ArgumentDescriptorStrict>;
 export {};
 //# sourceMappingURL=Command.d.ts.map