@guanghechen/commander 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -3,7 +3,13 @@
 All notable changes to this project will be documented in this file. See
 [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## 2.1.0 (2025-02-08)
+## 3.0.0 (2026-02-08)
+
+### BREAKING CHANGES
+
+- Change subcommand registration API to `subcommand(name, cmd)`
+
+## 2.1.0 (2026-02-08)
 
 ### Features
 
@@ -30,4 +36,3 @@ All notable changes to this project will be documented in this file. See
 ### Features
 
 - Initial stable release: A minimal, type-safe command-line interface builder with fluent API
-

package/lib/cjs/index.cjs

@@ -67,34 +67,25 @@ class Command {
     #name;
     #description;
     #version;
-    #aliases;
     #helpSubcommandEnabled;
     #options = [];
     #arguments = [];
     #subcommands = [];
     #action;
-    #parent;
     constructor(config) {
-        this.#name = config.name;
+        this.#name = config.name ?? '';
         this.#description = config.description;
         this.#version = config.version;
-        this.#aliases = config.aliases ?? [];
         this.#helpSubcommandEnabled = config.help ?? false;
     }
     get name() {
         return this.#name;
     }
-    get aliases() {
-        return this.#aliases;
-    }
     get description() {
         return this.#description;
     }
     get version() {
-        return this.#version ?? this.#parent?.version;
-    }
-    get parent() {
-        return this.#parent;
+        return this.#version;
     }
     get options() {
         return [...this.#options];
@@ -117,12 +108,18 @@ class Command {
         this.#action = fn;
         return this;
     }
-    subcommand(cmd) {
-        if (this.#helpSubcommandEnabled && (cmd.#name === 'help' || cmd.#aliases.includes('help'))) {
+    subcommand(name, cmd) {
+        if (this.#helpSubcommandEnabled && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
         }
-        cmd.#parent = this;
-        this.#subcommands.push(cmd);
+        const existing = this.#subcommands.find(e => e.command === cmd);
+        if (existing) {
+            existing.aliases.push(name);
+        }
+        else {
+            cmd.#name = name;
+            this.#subcommands.push({ name, aliases: [], command: cmd });
+        }
         return this;
     }
     async run(params) {
@@ -313,12 +310,12 @@ class Command {
             if (showHelpSubcommand) {
                 cmdLines.push({ name: 'help', desc: 'Show help for a command' });
             }
-            for (const sub of this.#subcommands) {
-                let name = sub.#name;
-                if (sub.#aliases.length > 0) {
-                    name += `, ${sub.#aliases.join(', ')}`;
+            for (const entry of this.#subcommands) {
+                let name = entry.name;
+                if (entry.aliases.length > 0) {
+                    name += `, ${entry.aliases.join(', ')}`;
                 }
-                cmdLines.push({ name, desc: sub.#description });
+                cmdLines.push({ name, desc: entry.command.#description });
             }
             const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
             for (const { name, desc } of cmdLines) {
@@ -345,9 +342,16 @@ class Command {
         return {
             name: this.#name,
             description: this.#description,
-            aliases: this.#aliases,
+            aliases: [],
             options,
-            subcommands: this.#subcommands.map(sub => sub.getCompletionMeta()),
+            subcommands: this.#subcommands.map(entry => {
+                const subMeta = entry.command.getCompletionMeta();
+                return {
+                    ...subMeta,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                };
+            }),
         };
     }
     #processHelpSubcommand(argv) {
@@ -359,8 +363,8 @@ class Command {
             return ['--help'];
         }
         const subName = argv[1];
-        const sub = this.#subcommands.find(c => c.#name === subName || c.#aliases.includes(subName));
-        if (sub) {
+        const entry = this.#subcommands.find(e => e.name === subName || e.aliases.includes(subName));
+        if (entry) {
             return [subName, '--help', ...argv.slice(2)];
         }
         return argv;
@@ -372,10 +376,10 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const sub = current.#subcommands.find(c => c.#name === token || c.#aliases.includes(token));
-            if (!sub)
+            const entry = current.#subcommands.find(e => e.name === token || e.aliases.includes(token));
+            if (!entry)
                 break;
-            current = sub;
+            current = entry.command;
             idx += 1;
         }
         return { command: current, remaining: argv.slice(idx) };
@@ -489,33 +493,17 @@ class Command {
         }
     }
     #getMergedOptions() {
-        const ancestors = [];
-        for (let node = this; node; node = node.#parent) {
-            ancestors.unshift(node);
-        }
         const optionMap = new Map();
-        const hasUserHelp = ancestors.some(c => c.#options.some(o => o.long === 'help'));
-        const hasUserVersion = ancestors.some(c => c.#options.some(o => o.long === 'version'));
+        const hasUserHelp = this.#options.some(o => o.long === 'help');
+        const hasUserVersion = this.#options.some(o => o.long === 'version');
         if (!hasUserHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
         if (!hasUserVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
-        for (const ancestor of ancestors) {
-            for (const opt of ancestor.#options) {
-                optionMap.set(opt.long, opt);
-            }
-        }
-        const shortToLong = new Map();
-        for (const [long, opt] of optionMap) {
-            if (opt.short) {
-                const existing = shortToLong.get(opt.short);
-                if (existing && existing !== long) {
-                    throw new CommanderError('OptionConflict', `short option "-${opt.short}" is used by both "--${existing}" and "--${long}"`, this.#getCommandPath());
-                }
-                shortToLong.set(opt.short, long);
-            }
+        for (const opt of this.#options) {
+            optionMap.set(opt.long, opt);
         }
         return Array.from(optionMap.values());
     }
@@ -654,20 +642,15 @@ class Command {
         return result;
     }
     #getCommandPath() {
-        const parts = [];
-        for (let node = this; node; node = node.#parent) {
-            parts.unshift(node.#name);
-        }
-        return parts.join(' ');
+        return this.#name;
     }
 }
 
 class CompletionCommand extends Command {
     constructor(root, config) {
-        const name = config.name ?? 'completion';
         const paths = config.paths;
+        const programName = config.programName ?? root.name;
         super({
-            name,
             description: 'Generate shell completion script',
         });
         this.option({
@@ -694,7 +677,6 @@ class CompletionCommand extends Command {
         })
             .action(({ opts }) => {
             const meta = root.getCompletionMeta();
-            const programName = root.name;
             const selectedShells = [
                 opts['bash'] && 'bash',
                 opts['fish'] && 'fish',

package/lib/esm/index.mjs

@@ -45,34 +45,25 @@ class Command {
     #name;
     #description;
     #version;
-    #aliases;
     #helpSubcommandEnabled;
     #options = [];
     #arguments = [];
     #subcommands = [];
     #action;
-    #parent;
     constructor(config) {
-        this.#name = config.name;
+        this.#name = config.name ?? '';
         this.#description = config.description;
         this.#version = config.version;
-        this.#aliases = config.aliases ?? [];
         this.#helpSubcommandEnabled = config.help ?? false;
     }
     get name() {
         return this.#name;
     }
-    get aliases() {
-        return this.#aliases;
-    }
     get description() {
         return this.#description;
     }
     get version() {
-        return this.#version ?? this.#parent?.version;
-    }
-    get parent() {
-        return this.#parent;
+        return this.#version;
     }
     get options() {
         return [...this.#options];
@@ -95,12 +86,18 @@ class Command {
         this.#action = fn;
         return this;
     }
-    subcommand(cmd) {
-        if (this.#helpSubcommandEnabled && (cmd.#name === 'help' || cmd.#aliases.includes('help'))) {
+    subcommand(name, cmd) {
+        if (this.#helpSubcommandEnabled && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
         }
-        cmd.#parent = this;
-        this.#subcommands.push(cmd);
+        const existing = this.#subcommands.find(e => e.command === cmd);
+        if (existing) {
+            existing.aliases.push(name);
+        }
+        else {
+            cmd.#name = name;
+            this.#subcommands.push({ name, aliases: [], command: cmd });
+        }
         return this;
     }
     async run(params) {
@@ -291,12 +288,12 @@ class Command {
             if (showHelpSubcommand) {
                 cmdLines.push({ name: 'help', desc: 'Show help for a command' });
             }
-            for (const sub of this.#subcommands) {
-                let name = sub.#name;
-                if (sub.#aliases.length > 0) {
-                    name += `, ${sub.#aliases.join(', ')}`;
+            for (const entry of this.#subcommands) {
+                let name = entry.name;
+                if (entry.aliases.length > 0) {
+                    name += `, ${entry.aliases.join(', ')}`;
                 }
-                cmdLines.push({ name, desc: sub.#description });
+                cmdLines.push({ name, desc: entry.command.#description });
             }
             const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
             for (const { name, desc } of cmdLines) {
@@ -323,9 +320,16 @@ class Command {
         return {
             name: this.#name,
             description: this.#description,
-            aliases: this.#aliases,
+            aliases: [],
             options,
-            subcommands: this.#subcommands.map(sub => sub.getCompletionMeta()),
+            subcommands: this.#subcommands.map(entry => {
+                const subMeta = entry.command.getCompletionMeta();
+                return {
+                    ...subMeta,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                };
+            }),
         };
     }
     #processHelpSubcommand(argv) {
@@ -337,8 +341,8 @@ class Command {
             return ['--help'];
         }
         const subName = argv[1];
-        const sub = this.#subcommands.find(c => c.#name === subName || c.#aliases.includes(subName));
-        if (sub) {
+        const entry = this.#subcommands.find(e => e.name === subName || e.aliases.includes(subName));
+        if (entry) {
             return [subName, '--help', ...argv.slice(2)];
         }
         return argv;
@@ -350,10 +354,10 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const sub = current.#subcommands.find(c => c.#name === token || c.#aliases.includes(token));
-            if (!sub)
+            const entry = current.#subcommands.find(e => e.name === token || e.aliases.includes(token));
+            if (!entry)
                 break;
-            current = sub;
+            current = entry.command;
             idx += 1;
         }
         return { command: current, remaining: argv.slice(idx) };
@@ -467,33 +471,17 @@ class Command {
         }
     }
     #getMergedOptions() {
-        const ancestors = [];
-        for (let node = this; node; node = node.#parent) {
-            ancestors.unshift(node);
-        }
         const optionMap = new Map();
-        const hasUserHelp = ancestors.some(c => c.#options.some(o => o.long === 'help'));
-        const hasUserVersion = ancestors.some(c => c.#options.some(o => o.long === 'version'));
+        const hasUserHelp = this.#options.some(o => o.long === 'help');
+        const hasUserVersion = this.#options.some(o => o.long === 'version');
         if (!hasUserHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
         if (!hasUserVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
-        for (const ancestor of ancestors) {
-            for (const opt of ancestor.#options) {
-                optionMap.set(opt.long, opt);
-            }
-        }
-        const shortToLong = new Map();
-        for (const [long, opt] of optionMap) {
-            if (opt.short) {
-                const existing = shortToLong.get(opt.short);
-                if (existing && existing !== long) {
-                    throw new CommanderError('OptionConflict', `short option "-${opt.short}" is used by both "--${existing}" and "--${long}"`, this.#getCommandPath());
-                }
-                shortToLong.set(opt.short, long);
-            }
+        for (const opt of this.#options) {
+            optionMap.set(opt.long, opt);
         }
         return Array.from(optionMap.values());
     }
@@ -632,20 +620,15 @@ class Command {
         return result;
     }
     #getCommandPath() {
-        const parts = [];
-        for (let node = this; node; node = node.#parent) {
-            parts.unshift(node.#name);
-        }
-        return parts.join(' ');
+        return this.#name;
     }
 }
 
 class CompletionCommand extends Command {
     constructor(root, config) {
-        const name = config.name ?? 'completion';
         const paths = config.paths;
+        const programName = config.programName ?? root.name;
         super({
-            name,
             description: 'Generate shell completion script',
         });
         this.option({
@@ -672,7 +655,6 @@ class CompletionCommand extends Command {
         })
             .action(({ opts }) => {
             const meta = root.getCompletionMeta();
-            const programName = root.name;
             const selectedShells = [
                 opts['bash'] && 'bash',
                 opts['fish'] && 'fish',

package/lib/types/index.d.ts

@@ -57,10 +57,8 @@ interface IArgument {
 }
 /** Command configuration */
 interface ICommandConfig {
-    /** Command name (used for routing) */
-    name: string;
-    /** Command aliases */
-    aliases?: string[];
+    /** Command name (only effective for root command) */
+    name?: string;
     /** Command description */
     description: string;
     /** Version (only effective for root command) */
@@ -71,10 +69,8 @@ interface ICommandConfig {
 /** 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[];
 }
@@ -155,8 +151,8 @@ interface ICompletionPaths {
 }
 /** CompletionCommand configuration */
 interface ICompletionCommandConfig {
-    /** Subcommand name, defaults to 'completion' */
-    name?: string;
+    /** Program name for completion scripts (defaults to root.name) */
+    programName?: string;
     /** Default completion file paths for each shell (required for --write support) */
     paths: ICompletionPaths;
 }
@@ -171,16 +167,14 @@ declare class Command implements ICommand {
     #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;
+    subcommand(name: string, cmd: Command): this;
     run(params: IRunParams): Promise<void>;
     parse(argv: string[]): IParseResult;
     formatHelp(): string;
@@ -199,7 +193,7 @@ declare class Command implements ICommand {
  * @example
  * ```typescript
  * const root = new Command({ name: 'mycli', description: 'My CLI' })
- * root.subcommand(new CompletionCommand(root, {
+ * root.subcommand('completion', new CompletionCommand(root, {
  *   paths: {
  *     bash: `~/.local/share/bash-completion/completions/mycli`,
  *     fish: `~/.config/fish/completions/mycli.fish`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",