@guanghechen/commander 1.0.12 → 2.0.1

package/lib/types/index.d.ts

@@ -1,137 +1,217 @@
-import { ICommandConfigurationOptions } from '@guanghechen/cli';
-export * from '@guanghechen/cli';
-import { Command as Command$1, OptionValues, CommandOptions } from 'commander';
-import { IReporter } from '@guanghechen/reporter.types';
-
 /**
- * Callback for handling the command
+ * Type definitions for @guanghechen/commander
  *
- * @param args    command arguments
- * @param options command options
- * @param extra   extra args (neither declared command arguments nor command options)
- * @param self    current command
+ * @module @guanghechen/commander
+ */
+/**
+ * Reporter interface for logging.
+ * Users should provide their own implementation.
  */
-type ICommandActionCallback<T extends ICommandConfigurationOptions> = (args: string[], options: T, extra: string[], self: Command) => void | Promise<void> | never;
-declare class Command extends Command$1 {
-    protected _actionHandler: ((args: string[]) => void) | null | undefined;
-    protected _optionValues: object;
-    protected _storeOptionsAsProperties: boolean;
-    protected _version: string | undefined;
-    protected _versionOptionName: string | undefined;
-    constructor();
-    /**
-     * Register callback `fn` for the command.
-     *
-     * @example
-     * program
-     *   .command('serve')
-     *   .description('start service')
-     *   .action(function() {
-     *      // do work here
-     *   });
-     *
-     * @param {Function} fn
-     * @return {Command} `this` command for chaining
-     */
-    action<T extends ICommandConfigurationOptions>(fn: ICommandActionCallback<T>): this;
-    opts<T extends OptionValues>(): T;
+interface IReporter {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
 }
-
-type IMainCommandProcessor<O extends ICommandConfigurationOptions> = (options: O) => void | Promise<void>;
-type IMainCommandCreator<O extends ICommandConfigurationOptions> = (handle?: IMainCommandProcessor<O>) => Command;
-type IMainCommandMounter = (parentCommand: Command, opts?: CommandOptions) => void;
-type IMainCommandExecutor<V = void> = (args: string[]) => Promise<V>;
+/** Supported option value types */
+type IOptionType = 'boolean' | 'string' | 'number' | 'string[]' | 'number[]';
 /**
- * Create main command mounter
- *
- * @param create  main command creator
- * @param handle  main command processor
+ * Option definition.
+ * @template T - The type of the option value
  */
-declare function createMainCommandMounter<O extends ICommandConfigurationOptions>(create: IMainCommandCreator<O>, handle: IMainCommandProcessor<O>): IMainCommandMounter;
+interface IOption<T = unknown> {
+    /** Long option (e.g., 'verbose' for --verbose), also used as merge key */
+    long: string;
+    /** Short option (single character, e.g., 'v' for -v) */
+    short?: string;
+    /** Value type, defaults to 'string' */
+    type?: IOptionType;
+    /** Description for help text */
+    description: string;
+    /** Whether this option is required (cannot be used with default or boolean type) */
+    required?: boolean;
+    /** Default value when not provided */
+    default?: T;
+    /** Allowed values for validation and completion */
+    choices?: T extends Array<infer U> ? U[] : T[];
+    /** Single value transformation (ignored when resolver is present) */
+    coerce?: (rawValue: string) => T extends Array<infer U> ? U : T;
+    /** Custom resolver that fully replaces builtin parsing (ignores type/coerce) */
+    resolver?: (argv: string[]) => {
+        value: T;
+        remaining: string[];
+    };
+    /** Callback after parsing, applies value to context */
+    apply?: (value: T, ctx: ICommandContext) => void;
+}
+/** Argument kind */
+type IArgumentKind = 'required' | 'optional' | 'variadic';
+/** Positional argument definition */
+interface IArgument {
+    /** Argument name */
+    name: string;
+    /** Argument description */
+    description: string;
+    /** Argument kind: required / optional / variadic */
+    kind: IArgumentKind;
+}
+/** Command configuration */
+interface ICommandConfig {
+    /** Command name (used for routing) */
+    name: string;
+    /** Command aliases */
+    aliases?: string[];
+    /** Command description */
+    description: string;
+    /** Version (only effective for root command) */
+    version?: string;
+}
+/** Forward declaration for Command class */
+interface ICommand {
+    readonly name: string;
+    readonly aliases: string[];
+    readonly description: string;
+    readonly version: string | undefined;
+    readonly parent: ICommand | undefined;
+    readonly options: IOption[];
+    readonly arguments: IArgument[];
+}
+/** Execution context */
+interface ICommandContext {
+    /** Current command node */
+    cmd: ICommand;
+    /** Environment variables passed in */
+    envs: Record<string, string | undefined>;
+    /** Reporter instance */
+    reporter: IReporter;
+    /** Original argv */
+    argv: string[];
+}
+/** Action parameters */
+interface IActionParams {
+    /** Execution context */
+    ctx: ICommandContext;
+    /** Parsed options */
+    opts: Record<string, unknown>;
+    /** Parsed positional arguments */
+    args: string[];
+}
+/** Action handler function */
+type IAction = (params: IActionParams) => void | Promise<void>;
+/** run() method parameters */
+interface IRunParams {
+    /** Command line arguments (usually process.argv.slice(2)) */
+    argv: string[];
+    /** Environment variables (usually process.env) */
+    envs: Record<string, string | undefined>;
+    /** Optional reporter for logging (defaults to console reporter) */
+    reporter?: IReporter;
+}
+/** parse() method result */
+interface IParseResult {
+    /** Parsed options */
+    opts: Record<string, unknown>;
+    /** Parsed positional arguments */
+    args: string[];
+}
+/** Error kinds for command parsing */
+type ICommanderErrorKind = 'UnknownOption' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'ConfigurationError';
+/** Commander error with structured information */
+declare class CommanderError extends Error {
+    readonly kind: ICommanderErrorKind;
+    readonly commandPath: string;
+    constructor(kind: ICommanderErrorKind, message: string, commandPath: string);
+    /** Format error with help hint */
+    format(): string;
+}
+/** Shell type for completion */
+type IShellType = 'bash' | 'fish' | 'pwsh';
+/** Option metadata for completion */
+interface ICompletionOptionMeta {
+    long: string;
+    short?: string;
+    description: string;
+    takesValue: boolean;
+    choices?: string[];
+}
+/** Command metadata for completion */
+interface ICompletionMeta {
+    name: string;
+    description: string;
+    aliases: string[];
+    options: ICompletionOptionMeta[];
+    subcommands: ICompletionMeta[];
+}
+/** CompletionCommand configuration */
+interface ICompletionCommandConfig {
+    /** Subcommand name, defaults to 'completion' */
+    name?: string;
+}
+
 /**
- * Create main command executor
+ * Command class - CLI command builder with fluent API
  *
- * @param create  main command creator
- * @param handle  main command processor
+ * @module @guanghechen/commander
  */
-declare function createMainCommandExecutor<O extends ICommandConfigurationOptions>(create: IMainCommandCreator<O>, handle: IMainCommandProcessor<O>): IMainCommandExecutor;
 
-interface ISubCommandOptions extends ICommandConfigurationOptions {
-}
-interface ISubCommandProcessor<O extends ISubCommandOptions> {
-    /**
-     * Process the command arguments and options.
-     * @param args      Command arguments.
-     * @param options   Command options.
-     */
-    process(args: string[], options: O): Promise<void>;
-}
-interface ISubCommand<O extends ISubCommandOptions> extends ISubCommandProcessor<O> {
-    /**
-     * Sub command name.
-     */
-    readonly subCommandName: string;
-    /**
-     * Sub command alias.
-     */
-    readonly aliases: string[];
-    /**
-     * Create an commander instance.
-     * @param processor
-     */
-    command(processor: ISubCommandProcessor<O>): Command;
-    /**
-     * Create a sub-command instance and execute it immediately.
-     * @param args      Command arguments.
-     * @param options   Command options.
-     */
-    execute(parentCommand: Command, rawArgs: string[]): Promise<void>;
-    /**
-     * Create a sub-command instance and mount it to the parentCommand.
-     * @param parentCommand
-     * @param opts
-     */
-    mount(parentCommand: Command, opts: CommandOptions | undefined): void;
-    /**
-     * Process the command options and rawArgs.
-     * @param args      Command arguments.
-     * @param options   Command options.
-     */
-    process(args: string[], options: O): Promise<void>;
-    /**
-     * Resolve a processor for process the command.
-     * @param args
-     * @param options
-     */
-    resolveProcessor(args: string[], options: O): Promise<ISubCommandProcessor<O>>;
-}
-declare abstract class SubCommand<O extends ISubCommandOptions> implements ISubCommand<O> {
-    abstract subCommandName: string;
-    abstract aliases: string[];
-    abstract command(processor: ISubCommandProcessor<O>): Command;
-    mount(parentCommand: Command, opts: CommandOptions | undefined): void;
-    execute(parentCommand: Command, rawArgs: string[]): Promise<void>;
-    process(args: string[], options: O): Promise<void>;
-    abstract resolveProcessor(args: string[], options: O): Promise<ISubCommandProcessor<O>>;
+declare class Command {
+    #private;
+    constructor(config: ICommandConfig);
+    get name(): string;
+    get aliases(): string[];
+    get description(): string;
+    get version(): string | undefined;
+    get parent(): Command | undefined;
+    get options(): IOption[];
+    get arguments(): IArgument[];
+    option(opt: IOption): this;
+    argument(arg: IArgument): this;
+    action(fn: IAction): this;
+    subcommand(cmd: Command): this;
+    run(params: IRunParams): Promise<void>;
+    parse(argv: string[]): IParseResult;
+    formatHelp(): string;
+    getCompletionMeta(): ICompletionMeta;
 }
 
 /**
- * Create top command
- * @param commandName
- * @param version
+ * Shell completion generators
+ *
+ * @module @guanghechen/commander
  */
-declare function createTopCommand(commandName: string, version: string): Command;
 
-declare const hasGitInstalled: () => boolean;
-interface IInstallDependenciesParams {
-    readonly cwd: string;
-    readonly plopBypass: string[];
-    readonly reporter?: IReporter;
-}
 /**
- * Run `npm/yarn install` to Install node.js dependencies
+ * Built-in completion command that generates shell completion scripts.
+ *
+ * @example
+ * ```typescript
+ * const root = new Command({ name: 'mycli', description: 'My CLI' })
+ * root.subcommand(new CompletionCommand(root))
+ *
+ * // Usage:
+ * // mycli completion --bash > ~/.local/share/bash-completion/completions/mycli
+ * // mycli completion --fish > ~/.config/fish/completions/mycli.fish
+ * // mycli completion --pwsh >> $PROFILE
+ * ```
  */
-declare function installDependencies(params: IInstallDependenciesParams): Promise<void>;
+declare class CompletionCommand extends Command {
+    constructor(root: Command, config?: ICompletionCommandConfig);
+}
+declare class BashCompletion {
+    #private;
+    constructor(meta: ICompletionMeta, programName: string);
+    generate(): string;
+}
+declare class FishCompletion {
+    #private;
+    constructor(meta: ICompletionMeta, programName: string);
+    generate(): string;
+}
+declare class PwshCompletion {
+    #private;
+    constructor(meta: ICompletionMeta, programName: string);
+    generate(): string;
+}
 
-export { Command, SubCommand, createMainCommandExecutor, createMainCommandMounter, createTopCommand, hasGitInstalled, installDependencies };
-export type { ICommandActionCallback, IInstallDependenciesParams, IMainCommandCreator, IMainCommandExecutor, IMainCommandMounter, IMainCommandProcessor, ISubCommand, ISubCommandOptions, ISubCommandProcessor };
+export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion };
+export type { IAction, IActionParams, IArgument, IArgumentKind, ICommand, ICommandConfig, ICommandContext, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, IOption, IOptionType, IParseResult, IReporter, IRunParams, IShellType };

package/package.json

@@ -1,27 +1,30 @@
 {
   "name": "@guanghechen/commander",
-  "version": "1.0.12",
-  "description": "A wrapper of commander.js with some utilities",
+  "version": "2.0.1",
+  "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",
     "url": "https://github.com/guanghechen/"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/guanghechen/node-scaffolds/tree/@guanghechen/commander@1.0.11",
+    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/commander@2.0.0",
     "directory": "packages/commander"
   },
-  "homepage": "https://github.com/guanghechen/node-scaffolds/tree/@guanghechen/commander@1.0.11/packages/commander#readme",
+  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/commander@2.0.0/packages/commander#readme",
   "keywords": [
-    "commander"
+    "cli",
+    "command",
+    "commander",
+    "completion"
   ],
   "type": "module",
   "exports": {
     ".": {
+      "types": "./lib/types/index.d.ts",
       "source": "./src/index.ts",
       "import": "./lib/esm/index.mjs",
-      "require": "./lib/cjs/index.cjs",
-      "types": "./lib/types/index.d.ts"
+      "require": "./lib/cjs/index.cjs"
     }
   },
   "source": "./src/index.ts",
@@ -29,9 +32,6 @@
   "module": "./lib/esm/index.mjs",
   "types": "./lib/types/index.d.ts",
   "license": "MIT",
-  "engines": {
-    "node": ">= 20.0.0"
-  },
   "files": [
     "lib/",
     "!lib/**/*.map",
@@ -40,12 +40,11 @@
     "LICENSE",
     "README.md"
   ],
-  "dependencies": {
-    "@guanghechen/cli": "^1.0.8",
-    "@guanghechen/exec": "^1.0.9",
-    "@guanghechen/reporter.types": "^1.0.5",
-    "@inquirer/select": "4.3.2",
-    "commander": "12.1.0"
-  },
-  "gitHead": "26026650aac329e6342b68d80111d82fd0213a20"
-}
+  "scripts": {
+    "build": "rollup -c ../../rollup.config.mjs",
+    "clean": "rimraf lib",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
+    "test:update": "vitest run --config ../../vitest.config.ts -u"
+  }
+}

package/CHANGELOG.md

@@ -1,115 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-## <small>1.0.12 (2025-08-29)</small>
-
-* improve: refine READMEs ([c41c1f2](https://github.com/guanghechen/node-scaffolds/commit/c41c1f2))
-* :wrench: chore: upgrade dependencies & update the node requirement from ([8ddfde1](https://github.com/guanghechen/node-scaffolds/commit/8ddfde1))
-
-
-
-
-
-## <small>1.0.11 (2025-07-04)</small>
-
-* :bookmark:  release ([2313a96](https://github.com/guanghechen/node-scaffolds/commit/2313a96))
-* :bookmark:  release ([fbef5fd](https://github.com/guanghechen/node-scaffolds/commit/fbef5fd))
-* :wrench: chore: upgrade dependencies ([8623304](https://github.com/guanghechen/node-scaffolds/commit/8623304))
-* chore: upgrade dependencies ([a5b7a87](https://github.com/guanghechen/node-scaffolds/commit/a5b7a87))
-
-
-
-
-
-## <small>1.0.10 (2025-03-30)</small>
-
-* chore: upgrade dependencies ([a5b7a87](https://github.com/guanghechen/node-scaffolds/commit/a5b7a87))
-
-
-
-
-
-## <small>1.0.9 (2025-02-26)</small>
-
-* :bookmark:  release ([9d47297](https://github.com/guanghechen/node-scaffolds/commit/9d47297))
-* chore: sharp dependencies ([914ba6f](https://github.com/guanghechen/node-scaffolds/commit/914ba6f))
-
-
-
-
-
-## <small>1.0.8 (2025-02-26)</small>
-
-* chore: sharp dependencies ([914ba6f](https://github.com/guanghechen/node-scaffolds/commit/914ba6f))
-* chore: upgrade devDependencies ([ca5de6d](https://github.com/guanghechen/node-scaffolds/commit/ca5de6d))
-* :bookmark:  release ([6fe5681](https://github.com/guanghechen/node-scaffolds/commit/6fe5681))
-
-
-
-
-
-## <small>1.0.7 (2025-02-07)</small>
-
-* chore: upgrade devDependencies ([ca5de6d](https://github.com/guanghechen/node-scaffolds/commit/ca5de6d))
-* :arrow_up: chore: upgrade dependencies & no longer rely on globby since it breaking build ([b5d0fdd](https://github.com/guanghechen/node-scaffolds/commit/b5d0fdd))
-* :bookmark:  release ([6524942](https://github.com/guanghechen/node-scaffolds/commit/6524942))
-
-
-
-
-
-## <small>1.0.6 (2025-01-09)</small>
-
-* :arrow_up: chore: upgrade dependencies & no longer rely on globby since it breaking build ([b5d0fdd](https://github.com/guanghechen/node-scaffolds/commit/b5d0fdd))
-
-
-
-
-
-## <small>1.0.5 (2024-10-03)</small>
-
-* :arrow_up:  chore: upgrade dependencies ([ba63623](https://github.com/guanghechen/node-scaffolds/commit/ba63623))
-
-
-
-
-
-## <small>1.0.4 (2024-10-03)</small>
-
-* :arrow_up:  chore: upgrade dependencies ([e41de75](https://github.com/guanghechen/node-scaffolds/commit/e41de75))
-* :wrench:  chore: don't gen sourcemap in production env ([f7075d1](https://github.com/guanghechen/node-scaffolds/commit/f7075d1))
-
-
-
-
-
-## <small>1.0.3 (2024-09-29)</small>
-
-**Note:** Version bump only for package @guanghechen/commander
-
-
-
-
-
-## <small>1.0.2 (2024-09-29)</small>
-
-* :art:  improve(commander): remove unnecessary third-party dependencies ([d5cb553](https://github.com/guanghechen/node-scaffolds/commit/d5cb553))
-
-
-
-
-
-## <small>1.0.1 (2024-09-28)</small>
-
-* :art:  improve: reuse @guanghechen/cli ([6c8e6a0](https://github.com/guanghechen/node-scaffolds/commit/6c8e6a0))
-* :wrench:  chore: fix publish issues ([7316526](https://github.com/guanghechen/node-scaffolds/commit/7316526))
-
-
-
-
-
-## <small>1.0.1 (2024-09-28)</small>
-
-* :art:  improve: reuse @guanghechen/cli ([6c8e6a0](https://github.com/guanghechen/node-scaffolds/commit/6c8e6a0))