commander 12.0.0-0 → 12.0.0-1

package/Readme.md

@@ -37,7 +37,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [.usage](#usage)
     - [.description and .summary](#description-and-summary)
     - [.helpOption(flags, description)](#helpoptionflags-description)
-    - [.addHelpCommand()](#addhelpcommand)
+    - [.helpCommand()](#helpcommand)
     - [More configuration](#more-configuration-2)
   - [Custom event listeners](#custom-event-listeners)
   - [Bits and pieces](#bits-and-pieces)
@@ -904,16 +904,20 @@ program
   .helpOption('-e, --HELP', 'read more information');
 ```
 
-### .addHelpCommand()
+(Or use `.addHelpOption()` to add an option you construct yourself.)
 
-A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.addHelpCommand()` and `.addHelpCommand(false)`.
+### .helpCommand()
+
+A help command is added by default if your command has subcommands. You can explicitly turn on or off the implicit help command with `.helpCommand(true)` and `.helpCommand(false)`.
 
 You can both turn on and customise the help command by supplying the name and description:
 
 ```js
-program.addHelpCommand('assist [command]', 'show assistance');
+program.helpCommand('assist [command]', 'show assistance');
 ```
 
+(Or use `.addHelpCommand()` to add a command you construct yourself.)
+
 ### More configuration
 
 The built-in help is formatted using the Help class.

package/lib/command.js

@@ -7,7 +7,7 @@ const process = require('process');
 const { Argument, humanReadableArgName } = require('./argument.js');
 const { CommanderError } = require('./error.js');
 const { Help } = require('./help.js');
-const { Option, splitOptionFlags, DualOptions } = require('./option.js');
+const { Option, DualOptions } = require('./option.js');
 const { suggestSimilar } = require('./suggestSimilar');
 
 class Command extends EventEmitter {
@@ -52,7 +52,7 @@ class Command extends EventEmitter {
     this._enablePositionalOptions = false;
     this._passThroughOptions = false;
     this._lifeCycleHooks = {}; // a hash of arrays
-    /** @type {boolean | string} */
+    /** @type {(boolean | string)} */
     this._showHelpAfterError = false;
     this._showSuggestionAfterError = true;
 
@@ -66,15 +66,11 @@ class Command extends EventEmitter {
     };
 
     this._hidden = false;
-    this._hasHelpOption = true;
-    this._helpFlags = '-h, --help';
-    this._helpDescription = 'display help for command';
-    this._helpShortFlag = '-h';
-    this._helpLongFlag = '--help';
-    this._addImplicitHelpCommand = undefined; // Deliberately undefined, not decided whether true or false
-    this._helpCommandName = 'help';
-    this._helpCommandnameAndArgs = 'help [command]';
-    this._helpCommandDescription = 'display help for command';
+    /** @type {(Option | null | undefined)} */
+    this._helpOption = undefined; // Lazy created on demand. May be null if help option is disabled.
+    this._addImplicitHelpCommand = undefined; // undecided whether true or false yet, not inherited
+    /** @type {Command} */
+    this._helpCommand = undefined; // lazy initialised, inherited
     this._helpConfiguration = {};
   }
 
@@ -88,14 +84,8 @@ class Command extends EventEmitter {
    */
   copyInheritedSettings(sourceCommand) {
     this._outputConfiguration = sourceCommand._outputConfiguration;
-    this._hasHelpOption = sourceCommand._hasHelpOption;
-    this._helpFlags = sourceCommand._helpFlags;
-    this._helpDescription = sourceCommand._helpDescription;
-    this._helpShortFlag = sourceCommand._helpShortFlag;
-    this._helpLongFlag = sourceCommand._helpLongFlag;
-    this._helpCommandName = sourceCommand._helpCommandName;
-    this._helpCommandnameAndArgs = sourceCommand._helpCommandnameAndArgs;
-    this._helpCommandDescription = sourceCommand._helpCommandDescription;
+    this._helpOption = sourceCommand._helpOption;
+    this._helpCommand = sourceCommand._helpCommand;
     this._helpConfiguration = sourceCommand._helpConfiguration;
     this._exitCallback = sourceCommand._exitCallback;
     this._storeOptionsAsProperties = sourceCommand._storeOptionsAsProperties;
@@ -141,7 +131,7 @@ class Command extends EventEmitter {
    *   .command('stop [service]', 'stop named service, or all if no name supplied');
    *
    * @param {string} nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
-   * @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
+   * @param {(Object|string)} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
    * @param {Object} [execOpts] - configuration options (for executable)
    * @return {Command} returns new command for action handler, or `this` for executable command
    */
@@ -203,7 +193,7 @@ class Command extends EventEmitter {
    * or with a subclass of Help by overriding createHelp().
    *
    * @param {Object} [configuration] - configuration options
-   * @return {Command|Object} `this` command for chaining, or stored configuration
+   * @return {(Command|Object)} `this` command for chaining, or stored configuration
    */
 
   configureHelp(configuration) {
@@ -229,7 +219,7 @@ class Command extends EventEmitter {
    *     outputError(str, write) // used for displaying errors, and not used for displaying help
    *
    * @param {Object} [configuration] - configuration options
-   * @return {Command|Object} `this` command for chaining, or stored configuration
+   * @return {(Command|Object)} `this` command for chaining, or stored configuration
    */
 
   configureOutput(configuration) {
@@ -242,7 +232,7 @@ class Command extends EventEmitter {
   /**
    * Display the help or a custom message after an error occurs.
    *
-   * @param {boolean|string} [displayHelp]
+   * @param {(boolean|string)} [displayHelp]
    * @return {Command} `this` command for chaining
    */
   showHelpAfterError(displayHelp = true) {
@@ -316,7 +306,7 @@ class Command extends EventEmitter {
    *
    * @param {string} name
    * @param {string} [description]
-   * @param {Function|*} [fn] - custom argument processing function
+   * @param {(Function|*)} [fn] - custom argument processing function
    * @param {*} [defaultValue]
    * @return {Command} `this` command for chaining
    */
@@ -369,39 +359,76 @@ class Command extends EventEmitter {
   }
 
   /**
-   * Override default decision whether to add implicit help command.
+   * Customise or override default help command. By default a help command is automatically added if your command has subcommands.
    *
-   *    addHelpCommand() // force on
-   *    addHelpCommand(false); // force off
-   *    addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+   *    program.helpCommand('help [cmd]');
+   *    program.helpCommand('help [cmd]', 'show help');
+   *    program.helpCommand(false); // suppress default help command
+   *    program.helpCommand(true); // add help command even if no subcommands
    *
+   * @param {string|boolean} enableOrNameAndArgs - enable with custom name and/or arguments, or boolean to override whether added
+   * @param {string} [description] - custom description
    * @return {Command} `this` command for chaining
    */
 
-  addHelpCommand(enableOrNameAndArgs, description) {
-    if (enableOrNameAndArgs === false) {
-      this._addImplicitHelpCommand = false;
-    } else {
-      this._addImplicitHelpCommand = true;
-      if (typeof enableOrNameAndArgs === 'string') {
-        this._helpCommandName = enableOrNameAndArgs.split(' ')[0];
-        this._helpCommandnameAndArgs = enableOrNameAndArgs;
-      }
-      this._helpCommandDescription = description || this._helpCommandDescription;
+  helpCommand(enableOrNameAndArgs, description) {
+    if (typeof enableOrNameAndArgs === 'boolean') {
+      this._addImplicitHelpCommand = enableOrNameAndArgs;
+      return this;
     }
+
+    enableOrNameAndArgs = enableOrNameAndArgs ?? 'help [command]';
+    const [, helpName, helpArgs] = enableOrNameAndArgs.match(/([^ ]+) *(.*)/);
+    const helpDescription = description ?? 'display help for command';
+
+    const helpCommand = this.createCommand(helpName);
+    helpCommand.helpOption(false);
+    if (helpArgs) helpCommand.arguments(helpArgs);
+    if (helpDescription) helpCommand.description(helpDescription);
+
+    this._addImplicitHelpCommand = true;
+    this._helpCommand = helpCommand;
+
     return this;
   }
 
   /**
-   * @return {boolean}
-   * @package internal use only
+   * Add prepared custom help command.
+   *
+   * @param {(Command|string|boolean)} helpCommand - custom help command, or deprecated enableOrNameAndArgs as for `.helpCommand()`
+   * @param {string} [deprecatedDescription] - deprecated custom description used with custom name only
+   * @return {Command} `this` command for chaining
+   */
+  addHelpCommand(helpCommand, deprecatedDescription) {
+    // If not passed an object, call through to helpCommand for backwards compatibility,
+    // as addHelpCommand was originally used like helpCommand is now.
+    if (typeof helpCommand !== 'object') {
+      this.helpCommand(helpCommand, deprecatedDescription);
+      return this;
+    }
+
+    this._addImplicitHelpCommand = true;
+    this._helpCommand = helpCommand;
+    return this;
+  }
+
+  /**
+   * Lazy create help command.
+   *
+   * @return {(Command|null)}
+   * @package
    */
+  _getHelpCommand() {
+    const hasImplicitHelpCommand = this._addImplicitHelpCommand ??
+      (this.commands.length && !this._actionHandler && !this._findCommand('help'));
 
-  _hasImplicitHelpCommand() {
-    if (this._addImplicitHelpCommand === undefined) {
-      return this.commands.length && !this._actionHandler && !this._findCommand('help');
+    if (hasImplicitHelpCommand) {
+      if (this._helpCommand === undefined) {
+        this.helpCommand(undefined, undefined); // use default name and description
+      }
+      return this._helpCommand;
     }
-    return this._addImplicitHelpCommand;
+    return null;
   }
 
   /**
@@ -517,7 +544,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Wrap parseArgs to catch 'commander.invalidArgument'.
    *
-   * @param {Option | Argument} target
+   * @param {(Option | Argument)} target
    * @param {string} value
    * @param {*} previous
    * @param {string} invalidArgumentMessage
@@ -691,7 +718,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * @param {string} flags
    * @param {string} [description]
-   * @param {Function|*} [parseArg] - custom option processing function or default value
+   * @param {(Function|*)} [parseArg] - custom option processing function or default value
    * @param {*} [defaultValue]
    * @return {Command} `this` command for chaining
    */
@@ -708,7 +735,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   *
   * @param {string} flags
   * @param {string} [description]
-  * @param {Function|*} [parseArg] - custom option processing function or default value
+  * @param {(Function|*)} [parseArg] - custom option processing function or default value
   * @param {*} [defaultValue]
   * @return {Command} `this` command for chaining
   */
@@ -725,7 +752,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * program.combineFlagAndOptionalValue(true);  // `-f80` is treated like `--flag=80`, this is the default behaviour
    * program.combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
    *
-   * @param {Boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
+   * @param {boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
    */
   combineFlagAndOptionalValue(combine = true) {
     this._combineFlagAndOptionalValue = !!combine;
@@ -735,7 +762,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Allow unknown options on the command line.
    *
-   * @param {Boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown
+   * @param {boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown
    * for unknown options.
    */
   allowUnknownOption(allowUnknown = true) {
@@ -746,7 +773,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
    *
-   * @param {Boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown
+   * @param {boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown
    * for excess arguments.
    */
   allowExcessArguments(allowExcess = true) {
@@ -759,7 +786,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.
    * The default behaviour is non-positional and global options may appear anywhere on the command line.
    *
-   * @param {Boolean} [positional=true]
+   * @param {boolean} [positional=true]
    */
   enablePositionalOptions(positional = true) {
     this._enablePositionalOptions = !!positional;
@@ -772,7 +799,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * positional options to have been enabled on the program (parent commands).
    * The default behaviour is non-positional and options may appear before or after command-arguments.
    *
-   * @param {Boolean} [passThrough=true]
+   * @param {boolean} [passThrough=true]
    * for unknown options.
    */
   passThroughOptions(passThrough = true) {
@@ -1155,7 +1182,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     // Fallback to parsing the help flag to invoke the help.
     return this._dispatchSubcommand(subcommandName, [], [
-      this._helpLongFlag || this._helpShortFlag
+      this._getHelpOption()?.long ?? this._getHelpOption()?.short ?? '--help'
     ]);
   }
 
@@ -1229,9 +1256,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Once we have a promise we chain, but call synchronously until then.
    *
-   * @param {Promise|undefined} promise
+   * @param {(Promise|undefined)} promise
    * @param {Function} fn
-   * @return {Promise|undefined}
+   * @return {(Promise|undefined)}
    * @private
    */
 
@@ -1247,9 +1274,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   /**
    *
-   * @param {Promise|undefined} promise
+   * @param {(Promise|undefined)} promise
    * @param {string} event
-   * @return {Promise|undefined}
+   * @return {(Promise|undefined)}
    * @private
    */
 
@@ -1278,10 +1305,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   /**
    *
-   * @param {Promise|undefined} promise
+   * @param {(Promise|undefined)} promise
    * @param {Command} subCommand
    * @param {string} event
-   * @return {Promise|undefined}
+   * @return {(Promise|undefined)}
    * @private
    */
 
@@ -1315,7 +1342,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (operands && this._findCommand(operands[0])) {
       return this._dispatchSubcommand(operands[0], operands.slice(1), unknown);
     }
-    if (this._hasImplicitHelpCommand() && operands[0] === this._helpCommandName) {
+    if (this._getHelpCommand() && operands[0] === this._getHelpCommand().name()) {
       return this._dispatchHelpCommand(operands[1]);
     }
     if (this._defaultCommandName) {
@@ -1477,8 +1504,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *     sub --unknown uuu op => [sub], [--unknown uuu op]
    *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    *
-   * @param {String[]} argv
-   * @return {{operands: String[], unknown: String[]}}
+   * @param {string[]} argv
+   * @return {{operands: string[], unknown: string[]}}
    */
 
   parseOptions(argv) {
@@ -1572,7 +1599,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           operands.push(arg);
           if (args.length > 0) unknown.push(...args);
           break;
-        } else if (arg === this._helpCommandName && this._hasImplicitHelpCommand()) {
+        } else if (this._getHelpCommand() && arg === this._getHelpCommand().name()) {
           operands.push(arg);
           if (args.length > 0) operands.push(...args);
           break;
@@ -1857,7 +1884,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {string} [str]
    * @param {string} [flags]
    * @param {string} [description]
-   * @return {this | string | undefined} `this` command for chaining, or version string if no arguments
+   * @return {(this | string | undefined)} `this` command for chaining, or version string if no arguments
    */
 
   version(str, flags, description) {
@@ -1881,7 +1908,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * @param {string} [str]
    * @param {Object} [argsDescription]
-   * @return {string|Command}
+   * @return {(string|Command)}
    */
   description(str, argsDescription) {
     if (str === undefined && argsDescription === undefined) return this._description;
@@ -1896,7 +1923,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Set the summary. Used when listed as subcommand of parent.
    *
    * @param {string} [str]
-   * @return {string|Command}
+   * @return {(string|Command)}
    */
   summary(str) {
     if (str === undefined) return this._summary;
@@ -1910,7 +1937,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.
    *
    * @param {string} [alias]
-   * @return {string|Command}
+   * @return {(string|Command)}
    */
 
   alias(alias) {
@@ -1941,7 +1968,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Only the first alias is shown in the auto-generated help.
    *
    * @param {string[]} [aliases]
-   * @return {string[]|Command}
+   * @return {(string[]|Command)}
    */
 
   aliases(aliases) {
@@ -1956,7 +1983,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Set / get the command usage `str`.
    *
    * @param {string} [str]
-   * @return {String|Command}
+   * @return {(string|Command)}
    */
 
   usage(str) {
@@ -1967,7 +1994,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         return humanReadableArgName(arg);
       });
       return [].concat(
-        (this.options.length || this._hasHelpOption ? '[options]' : []),
+        (this.options.length || (this._helpOption !== null) ? '[options]' : []),
         (this.commands.length ? '[command]' : []),
         (this.registeredArguments.length ? args : [])
       ).join(' ');
@@ -1981,7 +2008,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Get or set the name of the command.
    *
    * @param {string} [str]
-   * @return {string|Command}
+   * @return {(string|Command)}
    */
 
   name(str) {
@@ -2018,7 +2045,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * program.executableDir('subcommands');
    *
    * @param {string} [path]
-   * @return {string|null|Command}
+   * @return {(string|null|Command)}
    */
 
   executableDir(path) {
@@ -2088,35 +2115,69 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     context.write(helpInformation);
 
-    if (this._helpLongFlag) {
-      this.emit(this._helpLongFlag); // deprecated
+    if (this._getHelpOption()?.long) {
+      this.emit(this._getHelpOption().long); // deprecated
     }
     this.emit('afterHelp', context);
     this._getCommandAndAncestors().forEach(command => command.emit('afterAllHelp', context));
   }
 
   /**
-   * You can pass in flags and a description to override the help
-   * flags and help description for your command. Pass in false to
-   * disable the built-in help option.
+   * You can pass in flags and a description to customise the built-in help option.
+   * Pass in false to disable the built-in help option.
+   *
+   * @example
+   * program.helpOption('-?, --help' 'show help'); // customise
+   * program.helpOption(false); // disable
    *
-   * @param {string | boolean} [flags]
+   * @param {(string | boolean)} flags
    * @param {string} [description]
    * @return {Command} `this` command for chaining
    */
 
   helpOption(flags, description) {
+    // Support disabling built-in help option.
     if (typeof flags === 'boolean') {
-      this._hasHelpOption = flags;
+      if (flags) {
+        this._helpOption = this._helpOption ?? undefined; // preserve existing option
+      } else {
+        this._helpOption = null; // disable
+      }
       return this;
     }
-    this._helpFlags = flags || this._helpFlags;
-    this._helpDescription = description || this._helpDescription;
 
-    const helpFlags = splitOptionFlags(this._helpFlags);
-    this._helpShortFlag = helpFlags.shortFlag;
-    this._helpLongFlag = helpFlags.longFlag;
+    // Customise flags and description.
+    flags = flags ?? '-h, --help';
+    description = description ?? 'display help for command';
+    this._helpOption = this.createOption(flags, description);
+
+    return this;
+  }
+
+  /**
+   * Lazy create help option.
+   * Returns null if has been disabled with .helpOption(false).
+   *
+   * @returns {(Option | null)} the help option
+   * @package internal use only
+   */
+  _getHelpOption() {
+    // Lazy create help option on demand.
+    if (this._helpOption === undefined) {
+      this.helpOption(undefined, undefined);
+    }
+    return this._helpOption;
+  }
 
+  /**
+   * Supply your own option to use for the built-in help option.
+   * This is an alternative to using helpOption() to customise the flags and description etc.
+   *
+   * @param {Option} option
+   * @return {Command} `this` command for chaining
+   */
+  addHelpOption(option) {
+    this._helpOption = option;
     return this;
   }
 
@@ -2145,7 +2206,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.
    *
    * @param {string} position - before or after built-in help
-   * @param {string | Function} text - string to add, or a function returning a string
+   * @param {(string | Function)} text - string to add, or a function returning a string
    * @return {Command} `this` command for chaining
    */
   addHelpText(position, text) {
@@ -2178,8 +2239,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   _outputHelpIfRequested(args) {
-    const helpOption = this._hasHelpOption && args.find(arg => arg === this._helpLongFlag || arg === this._helpShortFlag);
-    if (helpOption) {
+    const helpOption = this._getHelpOption();
+    const helpRequested = helpOption && args.find(arg => helpOption.is(arg));
+    if (helpRequested) {
       this.outputHelp();
       // (Do not have all displayed text available so only passing placeholder.)
       this._exit(0, 'commander.helpDisplayed', '(outputHelp)');

package/lib/help.js

@@ -26,13 +26,8 @@ class Help {
 
   visibleCommands(cmd) {
     const visibleCommands = cmd.commands.filter(cmd => !cmd._hidden);
-    if (cmd._hasImplicitHelpCommand()) {
-      // Create a command matching the implicit help command.
-      const [, helpName, helpArgs] = cmd._helpCommandnameAndArgs.match(/([^ ]+) *(.*)/);
-      const helpCommand = cmd.createCommand(helpName)
-        .helpOption(false);
-      helpCommand.description(cmd._helpCommandDescription);
-      if (helpArgs) helpCommand.arguments(helpArgs);
+    const helpCommand = cmd._getHelpCommand();
+    if (helpCommand && !helpCommand._hidden) {
       visibleCommands.push(helpCommand);
     }
     if (this.sortSubcommands) {
@@ -68,19 +63,19 @@ class Help {
 
   visibleOptions(cmd) {
     const visibleOptions = cmd.options.filter((option) => !option.hidden);
-    // Implicit help
-    const showShortHelpFlag = cmd._hasHelpOption && cmd._helpShortFlag && !cmd._findOption(cmd._helpShortFlag);
-    const showLongHelpFlag = cmd._hasHelpOption && !cmd._findOption(cmd._helpLongFlag);
-    if (showShortHelpFlag || showLongHelpFlag) {
-      let helpOption;
-      if (!showShortHelpFlag) {
-        helpOption = cmd.createOption(cmd._helpLongFlag, cmd._helpDescription);
-      } else if (!showLongHelpFlag) {
-        helpOption = cmd.createOption(cmd._helpShortFlag, cmd._helpDescription);
-      } else {
-        helpOption = cmd.createOption(cmd._helpFlags, cmd._helpDescription);
+    // Built-in help option.
+    const helpOption = cmd._getHelpOption();
+    if (helpOption && !helpOption.hidden) {
+      // Automatically hide conflicting flags. Bit dubious but a historical behaviour that is convenient for single-command programs.
+      const removeShort = helpOption.short && cmd._findOption(helpOption.short);
+      const removeLong = helpOption.long && cmd._findOption(helpOption.long);
+      if (!removeShort && !removeLong) {
+        visibleOptions.push(helpOption); // no changes needed
+      } else if (helpOption.long && !removeLong) {
+        visibleOptions.push(cmd.createOption(helpOption.long, helpOption.description));
+      } else if (helpOption.short && !removeShort) {
+        visibleOptions.push(cmd.createOption(helpOption.short, helpOption.description));
       }
-      visibleOptions.push(helpOption);
     }
     if (this.sortOptions) {
       visibleOptions.sort(this.compareOptions);

package/lib/option.js

@@ -74,7 +74,7 @@ class Option {
    * new Option('--rgb').conflicts('cmyk');
    * new Option('--js').conflicts(['ts', 'jsx']);
    *
-   * @param {string | string[]} names
+   * @param {(string | string[])} names
    * @return {Option}
    */
 
@@ -324,5 +324,4 @@ function splitOptionFlags(flags) {
 }
 
 exports.Option = Option;
-exports.splitOptionFlags = splitOptionFlags;
 exports.DualOptions = DualOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "12.0.0-0",
+  "version": "12.0.0-1",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -16,7 +16,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/tj/commander.js.git"
+    "url": "git+https://github.com/tj/commander.js.git"
   },
   "scripts": {
     "lint": "npm run lint:javascript && npm run lint:typescript",
@@ -62,7 +62,7 @@
     "@typescript-eslint/parser": "^6.7.5",
     "eslint": "^8.30.0",
     "eslint-config-standard": "^17.0.0",
-    "eslint-config-standard-with-typescript": "^39.1.1",
+    "eslint-config-standard-with-typescript": "^40.0.0",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-jest": "^27.1.7",
     "eslint-plugin-n": "^16.2.0",

package/typings/index.d.ts

@@ -419,18 +419,27 @@ export class Command {
   arguments(names: string): this;
 
   /**
-   * Override default decision whether to add implicit help command.
+   * Customise or override default help command. By default a help command is automatically added if your command has subcommands.
    *
    * @example
+   * ```ts
+   * program.helpCommand('help [cmd]');
+   * program.helpCommand('help [cmd]', 'show help');
+   * program.helpCommand(false); // suppress default help command
+   * program.helpCommand(true); // add help command even if no subcommands
    * ```
-   * addHelpCommand() // force on
-   * addHelpCommand(false); // force off
-   * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
-   * ```
-   *
-   * @returns `this` command for chaining
    */
-  addHelpCommand(enableOrNameAndArgs?: string | boolean, description?: string): this;
+  helpCommand(nameAndArgs: string, description?: string): this;
+  helpCommand(enable: boolean): this;
+
+  /**
+   * Add prepared custom help command.
+   */
+  addHelpCommand(cmd: Command): this;
+  /** @deprecated since v12, instead use helpCommand */
+  addHelpCommand(nameAndArgs: string, description?: string): this;
+  /** @deprecated since v12, instead use helpCommand */
+  addHelpCommand(enable?: boolean): this;
 
   /**
    * Add hook for life cycle event.
@@ -838,6 +847,12 @@ export class Command {
    */
   helpOption(flags?: string | boolean, description?: string): this;
 
+  /**
+   * Supply your own option to use for the built-in help option.
+   * This is an alternative to using helpOption() to customise the flags and description etc.
+   */
+  addHelpOption(option: Option): this;
+
   /**
    * Output help information and exit.
    *