@bemoje/cli 0.2.1 → 0.3.0

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/Command';
+export * from './lib/CommandHelpAdapter';
+export * from './lib/CommanderHelpAdapter';
+export * from './lib/Help';
+export * from './lib/renderHelp';
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,6 @@
+export * from "./lib/Command";
+export * from "./lib/CommandHelpAdapter";
+export * from "./lib/CommanderHelpAdapter";
+export * from "./lib/Help";
+export * from "./lib/renderHelp";
+//# sourceMappingURL=index.js.map

package/lib/Command.d.ts

@@ -0,0 +1,293 @@
+import type { ParseArgsOptionDescriptor } from 'node:util';
+import type { IHelp } from './Help';
+import { CommandHelpAdapter } from './CommandHelpAdapter';
+/**
+ * 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')
+ *   .argument('<input>', 'input file')
+ *   .argument('[output]', 'output file', 'out.txt')
+ *   .option('-v, --verbose', 'verbose output')
+ *   .option('-f, --format <type>', 'output format')
+ *
+ * const result = cmd.parse(['input.txt', '-v', '-f', 'json'])
+ * ```
+ */
+export declare class Command implements CommandDescriptor {
+    /** Command name used for invocation */
+    name: string;
+    /** Optional version string */
+    version?: string;
+    /** Alternative names for this command */
+    aliases: string[];
+    /** Brief single-line description */
+    summary?: string;
+    /** Full command description */
+    description: string;
+    /** Whether command should be hidden from help */
+    hidden?: boolean;
+    /** Group name for organizing commands in help */
+    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);
+    /** 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 */
+    setAliases(...aliases: (string | string[])[]): this;
+    /** Adds aliases to existing ones */
+    addAliases(...aliases: (string | string[])[]): this;
+    /** Sets the command version */
+    setVersion(version?: string): this;
+    /** Sets the command summary */
+    setSummary(summary?: string): this;
+    /** Sets command description, joining multiple 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?: 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 */
+    subcommand(name: string): Command;
+    /** Add required argument. Usage: `<name>` */
+    argument(usage: `<${string}>`, description: string, options?: ArgOpts<RequiredArgumentDescriptor>): this;
+    /** Add optional argument with default. Usage: `[name]` */
+    argument(usage: `[${string}]`, description: string, options?: ArgOpts<OptionalArgumentDescriptor>): this;
+    /** Add required variadic argument. Usage: `<name...>` */
+    argument(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;
+    /** Add required string option. Usage: `-f, --file <path>` */
+    option(usage: `-${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;
+    /** Add required variadic option. Usage: `-i, --include <patterns...>` */
+    option(usage: `-${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;
+    /** Add boolean flag option. Usage: `-v, --verbose` */
+    option(usage: `-${string}, --${string}`, description: string, options?: OptOpts<BooleanOptionDescriptor>): this;
+    /**
+     * Parses command-line arguments with subcommand support and type-safe validation.
+     *
+     * @example
+     * ```typescript
+     * const result = cmd.parse(['input.txt', '-v', '--format', 'json'])
+     * // { arguments: ['input.txt'], options: { verbose: true, format: 'json' } }
+     * ```
+     */
+    parse(argv?: string[], globalOptions?: OptionDescriptor[]): {
+        command: Command;
+        arguments: (string | string[])[];
+        options: {
+            [x: string]: string | boolean | (string | boolean)[] | undefined;
+        };
+    };
+    /** 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(): OptionDescriptor[];
+    /** 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;
+}
+/** 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 {
+    name: string;
+    required: boolean;
+    description: string;
+    multiple: boolean;
+    choices?: string[];
+    defaultValue?: string | string[] | never;
+    defaultValueDescription?: string | never;
+}
+/** Required positional argument descriptor. Usage: `<name>` */
+interface RequiredArgumentDescriptor extends ArgumentDescriptorBase {
+    multiple: false;
+    required: true;
+    defaultValue?: never;
+    defaultValueDescription?: never;
+}
+/** Optional positional argument with string default. Usage: `[name]` */
+interface OptionalArgumentDescriptor extends ArgumentDescriptorBase {
+    required: false;
+    multiple: false;
+    defaultValue?: string;
+    defaultValueDescription?: string;
+}
+/** Required variadic argument accepting multiple values. Usage: `<name...>` */
+interface RequiredVariadicArgumentDescriptor extends ArgumentDescriptorBase {
+    required: true;
+    multiple: true;
+    defaultValue?: never;
+    defaultValueDescription?: never;
+}
+/** Optional variadic argument with array default. Usage: `[name...]` */
+interface OptionalVariadicArgumentDescriptor extends ArgumentDescriptorBase {
+    required: false;
+    multiple: true;
+    defaultValue?: string[];
+    defaultValueDescription?: string;
+}
+/** Base descriptor for command-line options with shared properties */
+interface OptionDescriptorBase extends ParseArgsOptionDescriptor {
+    type: 'boolean' | 'string';
+    short: string;
+    name: string;
+    argName?: string | never;
+    description: string;
+    required: boolean;
+    multiple: boolean;
+    defaultValue?: boolean | string | string[] | never;
+    defaultValueDescription?: string | never;
+    env?: string;
+    hidden?: boolean;
+    choices?: string[];
+    group?: string;
+}
+/** Boolean flag option. Usage: `-v, --verbose` */
+interface BooleanOptionDescriptor extends OptionDescriptorBase {
+    type: 'boolean';
+    argName?: never;
+    required: false;
+    multiple: false;
+    defaultValue?: boolean;
+    defaultValueDescription?: string;
+}
+/** Required string option. Usage: `-f, --file <path>` */
+interface RequiredOptionDescriptor extends OptionDescriptorBase {
+    type: 'string';
+    argName: string;
+    required: true;
+    multiple: false;
+    defaultValue?: never;
+    defaultValueDescription?: never;
+}
+/** Optional string option with default. Usage: `-o, --output [path]` */
+interface OptionalOptionDescriptor extends OptionDescriptorBase {
+    type: 'string';
+    argName: string;
+    required: false;
+    multiple: false;
+    defaultValue?: string;
+    defaultValueDescription?: string;
+}
+/** Required option accepting multiple values. Usage: `-i, --include <patterns...>` */
+interface RequiredVariadicOptionDescriptor extends OptionDescriptorBase {
+    type: 'string';
+    argName: string;
+    required: true;
+    multiple: true;
+    defaultValue?: never;
+    defaultValueDescription?: never;
+}
+/** Optional option accepting multiple values with defaults. Usage: `-e, --exclude [patterns...]` */
+interface OptionalVariadicOptionDescriptor extends OptionDescriptorBase {
+    type: 'string';
+    argName: string;
+    required: false;
+    multiple: true;
+    defaultValue?: string[];
+    defaultValueDescription?: string;
+}
+/** 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: Command | null;
+    commands: Command[];
+    arguments: ArgumentDescriptor[];
+    options: OptionDescriptor[];
+    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 {};
+//# sourceMappingURL=Command.d.ts.map