@bemoje/cli 2.1.3 → 2.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bemoje/cli",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "A type-safe CLI composer that can parse argv and generate help without execution coupling.",
   "type": "module",
   "sideEffects": false,

package/lib/Command.d.ts

@@ -1,149 +0,0 @@
-import type { ActionHandler } from './types';
-import type { AllowedArgumentUsage } from './types';
-import type { Argument } from './types';
-import type { Arguments } from './types';
-import type { BooleanOptionOptions } from './types';
-import type { CamelCase } from 'type-fest';
-import { Help } from './Help';
-import type { HookActionHandler } from './types';
-import type { HookDefinition } from './types';
-import type { ICommand } from './types';
-import type { InferAddOptionResult } from './types';
-import type { InferAddedArgumentType } from './types';
-import type { Option } from './types';
-import type { OptionalArgumentOptions } from './types';
-import type { OptionalArgumentOptionsWithDefaultValue } from './types';
-import type { OptionalOptionOptions } from './types';
-import type { OptionalVariadicArgumentOptions } from './types';
-import type { OptionalVariadicOptionOptions } from './types';
-import type { Options } from './types';
-import type { ParseArgvResult } from './types';
-import type { RequiredArgumentOptions } from './types';
-import type { RequiredOptionOptions } from './types';
-import type { RequiredVariadicArgumentOptions } from './types';
-import type { RequiredVariadicOptionOptions } from './types';
-import type { SetFieldType } from 'type-fest';
-import type { SetRequired } from 'type-fest';
-import type { Simplify } from 'type-fest';
-import type { SubCommands } from './types';
-/**
- * a type-safe CLI composer that can parse argv and generate help without execution coupling.
- */
-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;
-    /** semantic version string displayed by --version flag */
-    version?: string;
-    /** alternative names for invoking this command */
-    aliases: string[];
-    /** brief one-line description shown in command lists */
-    summary?: string;
-    /** full description displayed in help text */
-    description: string;
-    /** whether to exclude from help listings */
-    hidden?: boolean;
-    /** category for organizing related commands in help output */
-    group?: string;
-    /** 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 */
-    setAliases(...aliases: (string | string[])[]): this;
-    /** adds aliases to existing ones */
-    addAliases(...aliases: (string | string[])[]): this;
-    /** sets the command version */
-    setVersion(version: string): InferAddOptionResult<A, O, {
-        version?: boolean;
-    }, Subs>;
-    /** sets the command summary */
-    setSummary(summary?: string): this;
-    /** sets command description, joining variadic lines */
-    setDescription(...lines: string[]): this;
-    /** sets whether command is hidden from help */
-    setHidden(hidden?: boolean | undefined): this;
-    /** sets the command group for help organization */
-    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>;
-    /**
-     * register an action to be invoked when an option is set to true or string value.
-     *
-     * 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.
-     */
-    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. */
-    protected createSubcommand(name: string): Command<[], O, {}>;
-}

package/lib/Help.d.ts

@@ -1,178 +0,0 @@
-import type { Argument } from './types';
-import type { ICommand } from './types';
-import type { IHelp } from './types';
-import type { Option } from './types';
-/**
- * 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;
-    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(): ICommand[];
-    /**
-     * Compare options for sort.
-     */
-    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(): Option[];
-    /**
-     * Get an array of the arguments if any have a description.
-     */
-    visibleArguments(): Argument[];
-    /**
-     * Get the command term to show in the list of subcommands.
-     */
-    subcommandTerm(sub: ICommand): string;
-    /**
-     * Get the option term to show in the list of options.
-     */
-    optionTerm(option: Option): string;
-    /**
-     * Get the argument term to show in the list of arguments.
-     */
-    argumentTerm(argument: Argument): string;
-    /**
-     * Get the longest subcommand primary alias length.
-     */
-    longestSubcommandAliasLength(): number;
-    /**
-     * Get the longest subcommand term length.
-     */
-    longestSubcommandTermLength(): number;
-    /**
-     * Get the longest option term length.
-     */
-    longestOptionTermLength(): number;
-    /**
-     * Get the longest argument term length.
-     */
-    longestArgumentTermLength(): number;
-    /**
-     * Get the command usage to be displayed at the top of the built-in help.
-     */
-    commandUsage(): string;
-    /**
-     * Get the description for the command.
-     */
-    commandDescription(): string;
-    /**
-     * Get the subcommand summary to show in the list of subcommands.
-     * (Fallback to description for backwards compatibility.)
-     */
-    subcommandDescription(sub: ICommand): string;
-    /**
-     * Get the option description to show in the list of options.
-     */
-    optionDescription(option: Option): string;
-    /**
-     * Get the argument description to show in the list of arguments.
-     */
-    argumentDescription(argument: Argument): string;
-    /**
-     * Format a list of items, given a heading and an array of formatted items.
-     */
-    formatItemList(heading: string, items: string[]): string[];
-    /**
-     * Group items by their help group heading.
-     */
-    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.
-     */
-    displayWidth(str: string): number;
-    /**
-     * Style the title for displaying in the help. Called with 'Usage:', 'Options:', etc.
-     */
-    styleTitle(str: string): string;
-    /**
-     * Style the usage line for displaying in the help. Applies specific styling to different parts like options, commands, and arguments.
-     */
-    styleUsage(str: string): string;
-    /**
-     * Style command descriptions for display in help output.
-     */
-    styleCommandDescription(str: string): string;
-    /**
-     * Style option descriptions for display in help output.
-     */
-    styleOptionDescription(str: string): string;
-    /**
-     * Style subcommand descriptions for display in help output.
-     */
-    styleSubcommandDescription(str: string): string;
-    /**
-     * Style argument descriptions for display in help output.
-     */
-    styleArgumentDescription(str: string): string;
-    /**
-     * Base style used by descriptions. Override in subclass to apply custom formatting.
-     */
-    styleDescriptionText(str: string): string;
-    /**
-     * Style option terms (flags) for display in help output.
-     */
-    styleOptionTerm(str: string): string;
-    /**
-     * Style subcommand terms for display in help output. Applies specific styling to different parts like options and arguments.
-     */
-    styleSubcommandTerm(str: string): string;
-    /**
-     * Style argument terms for display in help output.
-     */
-    styleArgumentTerm(str: string): string;
-    /**
-     * Base style used in terms and usage for options. Override in subclass to apply custom formatting.
-     */
-    styleOptionText(str: string): string;
-    /**
-     * Base style used in terms and usage for arguments. Override in subclass to apply custom formatting.
-     */
-    styleArgumentText(str: string): string;
-    /**
-     * Base style used in terms and usage for subcommands. Override in subclass to apply custom formatting.
-     */
-    styleSubcommandText(str: string): string;
-    /**
-     * Base style used in terms and usage for commands. Override in subclass to apply custom formatting.
-     */
-    styleCommandText(str: string): string;
-    /**
-     * Calculate the pad width from the maximum term length.
-     */
-    padWidth(): number;
-    /**
-     * Detect manually wrapped and indented strings by checking for line break followed by whitespace.
-     */
-    preformatted(str: string): boolean;
-    /**
-     * Format the "item", which consists of a term and description. Pad the term and wrap the description, indenting the following lines.
-     *
-     * So "TTT", 5, "DDD DDDD DD DDD" might be formatted for this.helpWidth=17 like so:
-     *   TTT  DDD DDDD
-     *        DD DDD
-     */
-    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;
-}

package/lib/helpers/findCommand.d.ts

@@ -1,6 +0,0 @@
-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

@@ -1,6 +0,0 @@
-import type { ICommand } from '../types';
-import type { 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

@@ -1,5 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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[];

package/lib/internal/resolveArguments.d.ts

@@ -1,3 +0,0 @@
-import type { Argument } from '../types';
-/** Map positional strings to argument definitions, trimming trailing undefineds */
-export declare function resolveArguments(positionals: string[], args: Argument[]): unknown[];

package/lib/internal/validateParsed.d.ts

@@ -1,4 +0,0 @@
-import type { Argument } from '../types';
-import type { Option } from '../types';
-/** Validate parsed arguments and option values, returning errors or undefined */
-export declare function validateParsed(args: unknown[], optionValues: Record<string, unknown>, argDefs: Argument[], optionDefs: Option[]): string[] | undefined;