@bemoje/cli 1.1.1 → 2.0.0

package/lib/Command.d.ts

@@ -1,47 +1,48 @@
-import type { ParseArgsOptionDescriptor } from 'node:util';
-import { type IHelp } from './Help';
-import type { AllUnionFields } from 'type-fest';
+import type { CamelCase, SetFieldType, Simplify, SetRequired } from 'type-fest';
+import { Help } from './Help';
+import type { Arguments, Argument, ICommand, Option, Options, SubCommands } from './types';
+import type { ActionHandler, BooleanOptionOptions, AllowedArgumentUsage, InferAddedArgumentType, InferAddOptionResult, OptionalArgumentOptions, OptionalArgumentOptionsWithDefaultValue, OptionalOptionOptions, OptionalVariadicArgumentOptions, OptionalVariadicOptionOptions, RequiredArgumentOptions, RequiredOptionOptions, RequiredVariadicArgumentOptions, RequiredVariadicOptionOptions, ParseArgvResult, HookDefinition, HookActionHandler } from './types';
 /**
- * Command-line argument parser with fluent API and type-safe validation.
- * Enforces CLI argument ordering rules and provides structured parsing results.
- *
- * @example
- * ```typescript
- * const cmd = new Command('myapp')
- *   .addArgument('<input>', 'input file')
- *   .addArgument('[output]', 'output file', 'out.txt')
- *   .addOption('-v, --verbose', 'verbose output')
- *   .addOption('-f, --format <type>', 'output format')
- *
- * cmd.parseArgv(['input.txt', '-v', '-f', 'json'])
- * ```
+ * A type-safe CLI composer that can parse argv and generate help without execution coupling.
  */
-export declare class Command implements CommandDescriptor {
-    /** Command name used for invocation */
+export declare class Command<A extends Arguments = [], O extends Options = {
+    help?: boolean;
+    debug?: boolean;
+}, Subs extends SubCommands = SubCommands> implements ICommand {
+    /** Parent command in the hierarchy, undefined for root command */
+    parent?: Command<Arguments, Options & O>;
+    /** The command name used to invoke it */
     name: string;
-    /** Optional version string */
+    /** Semantic version string displayed by --version flag */
     version?: string;
-    /** Alternative names for this command */
+    /** Alternative names for invoking this command */
     aliases: string[];
-    /** Brief single-line description */
+    /** Brief one-line description shown in command lists */
     summary?: string;
-    /** Full command description */
+    /** Full description displayed in help text */
     description: string;
-    /** Whether command should be hidden from help */
+    /** Whether to exclude from help listings */
     hidden?: boolean;
-    /** Group name for organizing commands in help */
+    /** Category for organizing related commands in help output */
     group?: string;
-    /** Parent command if this is a subcommand */
-    parent: Command | null;
-    /** Child subcommands */
-    commands: Command[];
-    /** Positional arguments */
-    arguments: ArgumentDescriptor[];
-    /** Named options/flags */
-    options: OptionDescriptor[];
-    /** Help system configuration */
-    helpConfiguration: Partial<IHelp>;
-    constructor(name?: string, parent?: Command | null);
+    /** Positional arguments this command accepts */
+    arguments: Argument[];
+    /** CLI options (flags) this command recognizes */
+    options: Option[];
+    /** Subcommands registered with this command */
+    commands: Subs;
+    /** Main action handler executed when command is invoked */
+    protected action?: ActionHandler<A, O, Subs>;
+    /** Option-driven actions (e.g., --help, --version) executed when their conditions match */
+    protected hooks: HookDefinition<Arguments, Options & O>[];
+    constructor(name: string, parent?: ICommand);
+    protected get help(): Help;
+    /** Configure how the help is rendered */
+    helpConfiguration(cb?: (help: Help) => void): this;
+    /** Renders formatted help text using provided help definition */
+    renderHelp(config?: {
+        noColor?: boolean;
+    }): string;
     /** Sets the command name */
     setName(name: string): void;
     /** Sets command aliases, flattening nested arrays */
@@ -49,7 +50,9 @@ export declare class Command implements CommandDescriptor {
     /** Adds aliases to existing ones */
     addAliases(...aliases: (string | string[])[]): this;
     /** Sets the command version */
-    setVersion(version?: string): this;
+    setVersion(version: string): InferAddOptionResult<A, O, {
+        version?: boolean;
+    }, Subs>;
     /** Sets the command summary */
     setSummary(summary?: string): this;
     /** Sets command description, joining variadic lines */
@@ -57,234 +60,66 @@ export declare class Command implements CommandDescriptor {
     /** Sets whether command is hidden from help */
     setHidden(hidden?: boolean | undefined): this;
     /** Sets the command group for help organization */
-    setGroup(group?: Exclude<string, 'Options' | 'Global Options'>): this;
-    /** Sets the parent command */
-    setParent(parent: Command | null): this;
-    /** Extends existing help configuration with new settings */
-    extendHelpConfiguration(config: Partial<IHelp>): this;
-    /** Sets help configuration, using defaults if not provided */
-    setHelpConfiguration(config?: Partial<IHelp>): this;
-    /** Creates and adds a subcommand */
-    addSubcommand(name: string): Command;
-    /** Add required argument. Usage: `<name>` */
-    addArgument(usage: `<${string}>`, description: string, options?: ArgOpts<RequiredArgumentDescriptor>): this;
-    /** Add optional argument with default. Usage: `[name]` */
-    addArgument(usage: `[${string}]`, description: string, options?: ArgOpts<OptionalArgumentDescriptor>): this;
-    /** Add required variadic argument. Usage: `<name...>` */
-    addArgument(usage: `<${string}...>`, description: string, options?: ArgOpts<RequiredVariadicArgumentDescriptor>): this;
-    /** Add optional variadic argument with defaults. Usage: `[name...]` */
-    addArgument(usage: `[${string}...]`, description: string, options?: ArgOpts<OptionalVariadicArgumentDescriptor>): this;
-    /** Add required string option. Usage: `-f, --file <path>` */
-    addOption(flags: `-${string}, --${string} <${string}>`, description: string, options?: OptOpts<RequiredOptionDescriptor>): this;
-    /** Add optional string option with default. Usage: `-o, --output [path]` */
-    addOption(flags: `-${string}, --${string} [${string}]`, description: string, options?: OptOpts<OptionalOptionDescriptor>): this;
-    /** Add required variadic option. Usage: `-i, --include <patterns...>` */
-    addOption(flags: `-${string}, --${string} <${string}...>`, description: string, options?: OptOpts<RequiredVariadicOptionDescriptor>): this;
-    /** Add optional variadic option with defaults. Usage: `-e, --exclude [patterns...]` */
-    addOption(flags: `-${string}, --${string} [${string}...]`, description: string, options?: OptOpts<OptionalVariadicOptionDescriptor>): this;
-    /** Add boolean flag option. Usage: `-v, --verbose` */
-    addOption(flags: `-${string}, --${string}`, description: string, options?: OptOpts<BooleanOptionDescriptor>): this;
-    private _addOption;
+    setGroup(group?: string): this;
+    /** Add a subcommand and return the subcommand. All options are inherited by the subcommand. */
+    command<Name extends string, Sub extends Command<any, any, any> = Command<[], O, {}>>(name: Name, cb?: (cmd: Command<[], O, {}>, parent: this) => Sub): Sub;
+    /** Add a subcommand and return the subcommand. All options are inherited by the subcommand. */
+    addCommand<Name extends string, Sub extends Command<any, any, any> = Command<[], O, {}>>(name: Name, cb: (cmd: Command<[], O, {}>, parent: this) => Sub): Command<A, O, (SubCommands extends Subs ? {} : Subs) & {
+        [K in Name]: Sub;
+    }>;
+    /** Add required variadic argument, eg.: `<name...>` */
+    addArgument<const Opts extends RequiredVariadicArgumentOptions>(usage: AllowedArgumentUsage<this, `<${string}...>`>, options?: Opts): Command<[...A, InferAddedArgumentType<Opts>[]], O, Subs>;
+    /** Add required argument, eg.: `<name>` */
+    addArgument<const Opts extends RequiredArgumentOptions>(usage: AllowedArgumentUsage<this, `<${string}>`>, options?: Opts): Command<[...A, InferAddedArgumentType<Opts>], O, Subs>;
+    /** Add optional variadic argument with defaults, eg.: `[name...]` */
+    addArgument<const Opts extends OptionalVariadicArgumentOptions>(usage: AllowedArgumentUsage<this, `[${string}...]`>, options?: Opts): Command<[...A, InferAddedArgumentType<Opts>[]], O, Subs>;
+    /** Add optional argument with default, eg.: `[name]` */
+    addArgument<const Opts extends OptionalArgumentOptionsWithDefaultValue>(usage: AllowedArgumentUsage<this, `[${string}]`>, options: Opts): Command<[...A, InferAddedArgumentType<Opts>], O, Subs>;
+    /** Add optional argument, eg.: `[name]` */
+    addArgument<const Opts extends OptionalArgumentOptions>(usage: AllowedArgumentUsage<this, `[${string}]`>, options?: Opts): Command<[...A, InferAddedArgumentType<Opts> | undefined], O, Subs>;
+    /** Add optional string option, eg.: `-o, --output [path]` */
+    addOption<Long extends string>(flags: `-${string}, --${Long} [${string}]`, options?: SetFieldType<OptionalOptionOptions, 'defaultValue', undefined | never>): Command<A, Simplify<{
+        [K in CamelCase<Long>]?: string;
+    } & O>, Subs>;
+    /** Add optional string option with default, eg.: `-o, --output [path]` */
+    addOption<Long extends string>(flags: `-${string}, --${Long} [${string}]`, options: SetFieldType<SetRequired<OptionalOptionOptions, 'defaultValue'>, 'defaultValue', string>): Command<A, Simplify<{
+        [K in CamelCase<Long>]: string;
+    } & O>, Subs>;
+    /** Add required variadic option, eg.: `-i, --include <patterns...>` */
+    addOption<Long extends string>(flags: `-${string}, --${Long} <${string}...>`, options?: RequiredVariadicOptionOptions): Command<A, Simplify<{
+        [K in CamelCase<Long>]: string[];
+    } & O>, Subs>;
+    /** Add optional variadic option with defaults, eg.: `-e, --exclude [patterns...]` */
+    addOption<Long extends string>(flags: `-${string}, --${Long} [${string}...]`, options?: OptionalVariadicOptionOptions): Command<A, Simplify<{
+        [K in CamelCase<Long>]: string[];
+    } & O>, Subs>;
+    /** Add required string option, eg.: `-f, --file <path>` */
+    addOption<Long extends string>(flags: `-${string}, --${Long} <${string}>`, options?: RequiredOptionOptions): Command<A, Simplify<{
+        [K in CamelCase<Long>]: string;
+    } & O>, Subs>;
+    /** Add boolean flag option with default, eg.: `-v, --verbose` */
+    addOption<Long extends string>(flags: `-${string}, --${Long}`, options: SetFieldType<SetRequired<BooleanOptionOptions, 'defaultValue'>, 'defaultValue', boolean>): Command<A, Simplify<{
+        [K in CamelCase<Long>]: boolean;
+    } & O>, Subs>;
+    /** Add boolean flag option, eg.: `-v, --verbose` */
+    addOption<Long extends string>(flags: `-${string}, --${Long}`, options?: SetFieldType<BooleanOptionOptions, 'defaultValue', undefined | never>): Command<A, Simplify<{
+        [K in CamelCase<Long>]?: boolean;
+    } & O>, Subs>;
     /**
-     * Parses command-line arguments with subcommand support and type-safe validation.
+     * Register an action to be invoked when an option is set to true or string value.
      *
-     * @example
-     * ```typescript
-     * const result = cmd.parse(['input.txt', '-v', '--format', 'json'])
-     * // { arguments: ['input.txt'], options: { verbose: true, format: 'json' } }
-     * ```
+     * Hooks execute in addition to or instead of the main action handler,
+     * allowing for option-driven behavior. For example, `--help` and `--version`
+     * are implemented as hooks.
      */
-    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 */
-    protected assertNoVariadicArgument(): void;
-    /** Ensures only one variadic argument per command */
-    protected assertNoMultipleVariadicArguments(): void;
-    /** Ensures unique argument names across arguments and options */
-    protected assertArgumentNameNotInUse(name: string): void;
-    /** Validates option short names are single alphanumeric characters */
-    protected assertOptionShortNameIsValid(short: string): void;
-    /** Validates option short names are unique across command hierarchy */
-    protected assertOptionShortNameNotInUse(short: string): void;
-    /** Validates option names are unique across command hierarchy */
-    protected assertOptionNameNotInUse(name: string): void;
-    /** Returns command and all ancestor commands in hierarchy */
-    getCommandAndAncestors(): Command[];
-    /** Returns all ancestor commands excluding this command */
-    getAncestors(): Command[];
-    /** Returns all options from this command and ancestors */
-    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;
+    addOptionHook(optionName: keyof O, action: HookActionHandler<Arguments, O>): this;
+    /** Parses command-line arguments with subcommand support and type-safe validation. */
+    parseArgv(argv?: string[]): ParseArgvResult<Arguments, Options & O>;
+    /**
+     * Sets the main action handler for this command, which is executed after any matching option hooks when the command is invoked.
+     * The handler receives parsed arguments and options with correct typings.
+     */
+    setAction(fn: ActionHandler<A, O, Subs>): this;
     /** Returns a new Command instance. Override this method in subclasses. */
-    createCommand(name?: string, parent?: Command | null): Command;
-}
-/** Base descriptor for command-line arguments with shared properties */
-export interface ArgumentDescriptorBase {
-    name: string;
-    description: string;
-    required?: boolean;
-    variadic?: boolean;
-    choices?: string[];
-    defaultValue?: string | string[];
-    defaultValueDescription?: string;
-}
-/** Required positional argument descriptor. Usage: `<name>` */
-interface RequiredArgumentDescriptor extends ArgumentDescriptorBase {
-    variadic?: false;
-    required: true;
-    defaultValue?: undefined;
-    defaultValueDescription?: undefined;
-}
-/** Optional positional argument with string default. Usage: `[name]` */
-interface OptionalArgumentDescriptor extends ArgumentDescriptorBase {
-    required?: false;
-    variadic?: false;
-    defaultValue?: string;
-    defaultValueDescription?: string;
-}
-/** Required variadic argument accepting variadic values. Usage: `<name...>` */
-interface RequiredVariadicArgumentDescriptor extends ArgumentDescriptorBase {
-    required: true;
-    variadic: true;
-    defaultValue?: undefined;
-    defaultValueDescription?: undefined;
-}
-/** Optional variadic argument with array default. Usage: `[name...]` */
-interface OptionalVariadicArgumentDescriptor extends ArgumentDescriptorBase {
-    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 */
-export interface OptionDescriptorBase extends Omit<ParseArgsOptionDescriptor, 'type'> {
-    type?: ParseArgsOptionDescriptor['type'];
-    flags: string;
-    short: string;
-    long: string;
-    name: string;
-    argName?: string;
-    description: string;
-    required?: boolean;
-    optional?: boolean;
-    variadic?: boolean;
-    negate?: boolean;
-    defaultValue?: boolean | string | string[];
-    defaultValueDescription?: string;
-    env?: string;
-    hidden?: boolean;
-    choices?: string[];
-    group?: string;
-}
-/** Boolean flag option. Usage: `-v, --verbose` */
-interface BooleanOptionDescriptor extends OptionDescriptorBase {
-    type: 'boolean';
-    argName?: undefined;
-    required?: false;
-    optional: true;
-    variadic?: false;
-    negate: boolean;
-    defaultValue?: boolean;
-    defaultValueDescription?: string;
-}
-/** Required string option. Usage: `-f, --file <path>` */
-interface RequiredOptionDescriptor extends OptionDescriptorBase {
-    type: 'string';
-    argName: string;
-    required: true;
-    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;
-    optional: true;
-    variadic?: false;
-    negate?: false;
-    defaultValue?: string;
-    defaultValueDescription?: string;
-}
-/** Required option accepting variadic values. Usage: `-i, --include <patterns...>` */
-interface RequiredVariadicOptionDescriptor extends OptionDescriptorBase {
-    type: 'string';
-    argName: string;
-    required: true;
-    optional?: false;
-    variadic: true;
-    negate?: false;
-    defaultValue?: undefined;
-    defaultValueDescription?: undefined;
-}
-/** Optional option accepting variadic values with defaults. Usage: `-e, --exclude [patterns...]` */
-interface OptionalVariadicOptionDescriptor extends OptionDescriptorBase {
-    type: 'string';
-    argName: string;
-    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;
-    version?: string;
-    aliases: string[];
-    summary?: string;
-    description: string;
-    hidden?: boolean;
-    group?: string;
-    parent: CommandDescriptor | null;
-    commands: CommandDescriptor[];
-    arguments: ArgumentDescriptorBase[];
-    options: OptionDescriptorBase[];
-    helpConfiguration: Partial<IHelp>;
+    protected createSubcommand(name: string): Command<[], O, {}>;
 }
-export type OptionDescriptor = AllUnionFields<OptionDescriptorStrict>;
-export type ArgumentDescriptor = AllUnionFields<ArgumentDescriptorStrict>;
-export {};
-//# sourceMappingURL=Command.d.ts.map

package/lib/Help.d.ts

@@ -1,95 +1,92 @@
-import type { ArgumentDescriptorBase, CommandDescriptor, OptionDescriptorBase } from './Command';
+import type { IHelp, Argument, ICommand, Option } from './types';
 /**
- * Although this is a class, methods are static in style to allow override using subclass or just functions.
+ * This is a fork of the Help class from the 'commander' npm package. The Help class method names as well as the
+ * expected interface of the Command instance to parse, are both similar, but different and not compatible without
+ * custom adaptations, @see ICommand
  */
 export declare class Help implements IHelp {
+    protected readonly cmd: ICommand;
     /** output helpWidth, long lines are wrapped to fit */
     helpWidth: number;
     minWidthToWrap: number;
-    sortSubcommands?: boolean;
-    sortOptions?: boolean;
-    showGlobalOptions?: boolean;
+    sortSubcommands: boolean;
+    sortOptions: boolean;
+    usageDisplayOptionsAs: string;
+    usageDisplaySubcommandAs: string;
+    constructor(cmd: ICommand);
     /**
      * Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one.
      */
-    visibleCommands(cmd: CommandDescriptor): CommandDescriptor[];
+    visibleCommands(): ICommand[];
     /**
      * Compare options for sort.
      */
-    compareOptions(a: OptionDescriptorBase, b: OptionDescriptorBase): number;
+    compareOptions(a: Option, b: Option): number;
     /**
      * Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one.
      */
-    visibleOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
-    /**
-     * Get an array of the visible global options. (Not including help.)
-     */
-    visibleGlobalOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
+    visibleOptions(): Option[];
     /**
      * Get an array of the arguments if any have a description.
      */
-    visibleArguments(cmd: CommandDescriptor): ArgumentDescriptorBase[];
+    visibleArguments(): Argument[];
     /**
      * Get the command term to show in the list of subcommands.
      */
-    subcommandTerm(cmd: CommandDescriptor): string;
+    subcommandTerm(sub: ICommand): string;
     /**
      * Get the option term to show in the list of options.
      */
-    optionTerm(option: OptionDescriptorBase): string;
+    optionTerm(option: Option): string;
     /**
      * Get the argument term to show in the list of arguments.
      */
-    argumentTerm(argument: ArgumentDescriptorBase): string;
+    argumentTerm(argument: Argument): string;
     /**
-     * Get the longest command term length.
+     * Get the longest subcommand primary alias length.
      */
-    longestSubcommandTermLength(cmd: CommandDescriptor, helper: Help): number;
+    longestSubcommandAliasLength(): number;
     /**
-     * Get the longest option term length.
+     * Get the longest subcommand term length.
      */
-    longestOptionTermLength(cmd: CommandDescriptor, helper: Help): number;
+    longestSubcommandTermLength(): number;
     /**
-     * Get the longest global option term length.
+     * Get the longest option term length.
      */
-    longestGlobalOptionTermLength(cmd: CommandDescriptor, helper: Help): number;
+    longestOptionTermLength(): number;
     /**
      * Get the longest argument term length.
      */
-    longestArgumentTermLength(cmd: CommandDescriptor, helper: Help): number;
+    longestArgumentTermLength(): number;
     /**
      * Get the command usage to be displayed at the top of the built-in help.
      */
-    commandUsage(cmd: CommandDescriptor): string;
+    commandUsage(): string;
     /**
      * Get the description for the command.
      */
-    commandDescription(cmd: CommandDescriptor): string;
+    commandDescription(): string;
     /**
      * Get the subcommand summary to show in the list of subcommands.
      * (Fallback to description for backwards compatibility.)
      */
-    subcommandDescription(cmd: CommandDescriptor): string;
+    subcommandDescription(sub: ICommand): string;
     /**
      * Get the option description to show in the list of options.
      */
-    optionDescription(option: OptionDescriptorBase): string;
+    optionDescription(option: Option): string;
     /**
      * Get the argument description to show in the list of arguments.
      */
-    argumentDescription(argument: ArgumentDescriptorBase): string;
+    argumentDescription(argument: Argument): string;
     /**
      * Format a list of items, given a heading and an array of formatted items.
      */
-    formatItemList(heading: string, items: string[], helper: Help): string[];
+    formatItemList(heading: string, items: string[]): string[];
     /**
      * Group items by their help group heading.
      */
-    groupItems<T extends CommandDescriptor | OptionDescriptorBase>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
-    /**
-     * Generate the built-in help text.
-     */
-    formatHelp(cmd: CommandDescriptor, helper: IHelp): string;
+    groupItems<T extends ICommand | Option>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
     /**
      * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
      */
@@ -153,7 +150,7 @@ export declare class Help implements IHelp {
     /**
      * Calculate the pad width from the maximum term length.
      */
-    padWidth(cmd: CommandDescriptor, helper: Help): number;
+    padWidth(): number;
     /**
      * Detect manually wrapped and indented strings by checking for line break followed by whitespace.
      */
@@ -165,57 +162,14 @@ export declare class Help implements IHelp {
      *   TTT  DDD DDDD
      *        DD DDD
      */
-    formatItem(term: string, termWidth: number, description: string, helper: Help): string;
+    formatItem(term: string, termWidth: number, description: string): string;
     /**
      * Wrap a string at whitespace, preserving existing line breaks.
      * Wrapping is skipped if the width is less than `minWidthToWrap`.
      */
     boxWrap(str: string, width: number): string;
+    /**
+     * Generate the built-in help text.
+     */
+    render(): string;
 }
-export interface IHelp {
-    helpWidth: number;
-    minWidthToWrap: number;
-    sortSubcommands?: boolean;
-    sortOptions?: boolean;
-    showGlobalOptions?: boolean;
-    subcommandTerm(cmd: CommandDescriptor): string;
-    subcommandDescription(cmd: CommandDescriptor): string;
-    optionTerm(option: OptionDescriptorBase): string;
-    optionDescription(option: OptionDescriptorBase): string;
-    argumentTerm(argument: ArgumentDescriptorBase): string;
-    argumentDescription(argument: ArgumentDescriptorBase): string;
-    commandUsage(cmd: CommandDescriptor): string;
-    commandDescription(cmd: CommandDescriptor): string;
-    visibleCommands(cmd: CommandDescriptor): CommandDescriptor[];
-    visibleOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
-    visibleGlobalOptions(cmd: CommandDescriptor): OptionDescriptorBase[];
-    visibleArguments(cmd: CommandDescriptor): ArgumentDescriptorBase[];
-    longestSubcommandTermLength(cmd: CommandDescriptor, helper: IHelp): number;
-    longestOptionTermLength(cmd: CommandDescriptor, helper: IHelp): number;
-    longestGlobalOptionTermLength(cmd: CommandDescriptor, helper: IHelp): number;
-    longestArgumentTermLength(cmd: CommandDescriptor, helper: IHelp): number;
-    displayWidth(str: string): number;
-    styleTitle(title: string): string;
-    styleUsage(str: string): string;
-    styleCommandText(str: string): string;
-    styleCommandDescription(str: string): string;
-    styleOptionDescription(str: string): string;
-    styleSubcommandDescription(str: string): string;
-    styleArgumentDescription(str: string): string;
-    styleDescriptionText(str: string): string;
-    styleOptionTerm(str: string): string;
-    styleSubcommandTerm(str: string): string;
-    styleArgumentTerm(str: string): string;
-    styleOptionText(str: string): string;
-    styleSubcommandText(str: string): string;
-    styleArgumentText(str: string): string;
-    compareOptions(a: OptionDescriptorBase, b: OptionDescriptorBase): number;
-    padWidth(cmd: CommandDescriptor, helper: IHelp): number;
-    boxWrap(str: string, width: number): string;
-    preformatted(str: string): boolean;
-    formatItem(term: string, termWidth: number, description: string, helper: IHelp): string;
-    formatItemList(heading: string, items: string[], helper: IHelp): string[];
-    groupItems<T extends CommandDescriptor | OptionDescriptorBase>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
-    formatHelp(cmd: CommandDescriptor, helper: IHelp): string;
-}
-//# sourceMappingURL=Help.d.ts.map

package/lib/helpers/findCommand.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from '../Command';
+import type { ICommand } from '../types';
+/**
+ * Finds subcommand by name or alias
+ */
+export declare function findCommand<C extends Command = Command>(cmd: ICommand, nameOrAlias: string): C | undefined;

package/lib/helpers/findOption.d.ts

@@ -0,0 +1,5 @@
+import type { ICommand, Option } from '../types';
+/**
+ * Finds option by name, short name or long name
+ */
+export declare function findOption<C extends ICommand>(cmd: C, nameOrShortOrLong: string): Option | undefined;

package/lib/helpers/getCommandAncestors.d.ts

@@ -0,0 +1,5 @@
+import type { ICommand } from '../types';
+/**
+ * Returns all ancestor commands excluding this command
+ */
+export declare function getCommandAncestors<C extends ICommand>(cmd: C): C[];

package/lib/helpers/getCommandAndAncestors.d.ts

@@ -0,0 +1,5 @@
+import type { ICommand } from '../types';
+/**
+ * Returns command and all ancestor commands in hierarchy
+ */
+export declare function getCommandAndAncestors<C extends ICommand>(cmd: C): [typeof cmd, ...ICommand[]];

package/lib/helpers/parseOptionFlags.d.ts

@@ -0,0 +1,11 @@
+import type { CamelCase } from 'type-fest';
+import type { OptionUsage } from '../types';
+/**
+ * Parses option flags string into its components
+ */
+export declare function parseOptionFlags<Long extends string>(flags: OptionUsage<Long>): {
+    short: string;
+    long: Long;
+    name: CamelCase<Long>;
+    argName: string | undefined;
+};

package/lib/internal/collectVariadicOptionValues.d.ts

@@ -0,0 +1,7 @@
+import type { Option } from '../types';
+/** Collect consecutive positional tokens into variadic string option values */
+export declare function collectVariadicOptionValues(parsed: {
+    tokens: any[];
+    values: any;
+    positionals: string[];
+}, options: Option[]): void;

package/lib/internal/mergeOptionDefaults.d.ts

@@ -0,0 +1,3 @@
+import type { Option } from '../types';
+/** Merge default option values into parsed values where not already set */
+export declare function mergeOptionDefaults(values: Record<string, unknown>, options: Option[]): void;

package/lib/internal/normalizeArgv.d.ts

@@ -0,0 +1,3 @@
+import type { Option } from '../types';
+/** Map long option names (kebab-case) to their camelCased equivalents in argv */
+export declare function normalizeArgv(argv: string[], options: Option[]): string[];