commander 12.1.0 → 13.0.0

package/Readme.md

@@ -79,7 +79,8 @@ const { program } = require('commander');
 
 program
   .option('--first')
-  .option('-s, --separator <char>');
+  .option('-s, --separator <char>')
+  .argument('<string>');
 
 program.parse();
 
@@ -678,8 +679,7 @@ async function main() {
 }
 ```
 
-A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments will be reported as an error. You can suppress the unknown option checks with `.allowUnknownOption()`. By default, it is not an error to
-pass more arguments than declared, but you can make this an error with `.allowExcessArguments(false)`.
+A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments or excess arguments will be reported as an error. You can suppress the unknown option check with `.allowUnknownOption()`. You can suppress the excess arguments check with `.allowExcessArguments()`.
 
 ### Stand-alone executable (sub)commands
 
@@ -696,7 +696,7 @@ Example file: [pm](./examples/pm)
 program
   .name('pm')
   .version('0.1.0')
-  .command('install [name]', 'install one or more packages')
+  .command('install [package-names...]', 'install one or more packages')
   .command('search [query]', 'search with optional query')
   .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
   .command('list', 'list packages installed', { isDefault: true });
@@ -921,25 +921,11 @@ program.helpCommand('assist [command]', 'show assistance');
 ### More configuration
 
 The built-in help is formatted using the Help class.
-You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.
+You can configure the help by modifying data properties and methods using `.configureHelp()`, or by subclassing Help using `.createHelp()` .
 
-The data properties are:
+Simple properties include `sortSubcommands`, `sortOptions`, and `showGlobalOptions`. You can add color using the style methods like `styleTitle()`.
 
-- `helpWidth`: specify the wrap width, useful for unit tests
-- `sortSubcommands`: sort the subcommands alphabetically
-- `sortOptions`: sort the options alphabetically
-- `showGlobalOptions`: show a section with the global options from the parent command(s)
-
-You can override any method on the [Help](./lib/help.js) class. There are methods getting the visible lists of arguments, options, and subcommands. There are methods for formatting the items in the lists, with each item having a _term_ and _description_. Take a look at `.formatHelp()` to see how they are used.
-
-Example file: [configure-help.js](./examples/configure-help.js)
-
-```js
-program.configureHelp({
-  sortSubcommands: true,
-  subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
-});
-```
+For more detail and examples of changing the displayed text, color, and layout see (./docs/help-in-depth.md)
 
 ## Custom event listeners
 
@@ -973,8 +959,6 @@ program.parse(['--port', '80'], { from: 'user' }); // just user supplied argumen
 
 Use parseAsync instead of parse if any of your action handlers are async.
 
-If you want to parse multiple times, create a new program each time. Calling parse does not clear out any previous state.
-
 ### Parsing Configuration
 
 If the default parsing does not suit your needs, there are some behaviours to support other usage patterns.

package/lib/command.js

@@ -6,7 +6,7 @@ const process = require('node:process');
 
 const { Argument, humanReadableArgName } = require('./argument.js');
 const { CommanderError } = require('./error.js');
-const { Help } = require('./help.js');
+const { Help, stripColor } = require('./help.js');
 const { Option, DualOptions } = require('./option.js');
 const { suggestSimilar } = require('./suggestSimilar');
 
@@ -25,7 +25,7 @@ class Command extends EventEmitter {
     this.options = [];
     this.parent = null;
     this._allowUnknownOption = false;
-    this._allowExcessArguments = true;
+    this._allowExcessArguments = false;
     /** @type {Argument[]} */
     this.registeredArguments = [];
     this._args = this.registeredArguments; // deprecated old name
@@ -55,16 +55,22 @@ class Command extends EventEmitter {
     /** @type {(boolean | string)} */
     this._showHelpAfterError = false;
     this._showSuggestionAfterError = true;
+    this._savedState = null; // used in save/restoreStateBeforeParse
 
-    // see .configureOutput() for docs
+    // see configureOutput() for docs
     this._outputConfiguration = {
       writeOut: (str) => process.stdout.write(str),
       writeErr: (str) => process.stderr.write(str),
+      outputError: (str, write) => write(str),
       getOutHelpWidth: () =>
         process.stdout.isTTY ? process.stdout.columns : undefined,
       getErrHelpWidth: () =>
         process.stderr.isTTY ? process.stderr.columns : undefined,
-      outputError: (str, write) => write(str),
+      getOutHasColors: () =>
+        useColor() ?? (process.stdout.isTTY && process.stdout.hasColors?.()),
+      getErrHasColors: () =>
+        useColor() ?? (process.stderr.isTTY && process.stderr.hasColors?.()),
+      stripColor: (str) => stripColor(str),
     };
 
     this._hidden = false;
@@ -213,14 +219,18 @@ class Command extends EventEmitter {
    *
    * The configuration properties are all functions:
    *
-   *     // functions to change where being written, stdout and stderr
+   *     // change how output being written, defaults to stdout and stderr
    *     writeOut(str)
    *     writeErr(str)
-   *     // matching functions to specify width for wrapping help
+   *     // change how output being written for errors, defaults to writeErr
+   *     outputError(str, write) // used for displaying errors and not used for displaying help
+   *     // specify width for wrapping help
    *     getOutHelpWidth()
    *     getErrHelpWidth()
-   *     // functions based on what is being written out
-   *     outputError(str, write) // used for displaying errors, and not used for displaying help
+   *     // color support, currently only used with Help
+   *     getOutHasColors()
+   *     getErrHasColors()
+   *     stripColor() // used to remove ANSI escape codes if output does not have colors
    *
    * @param {object} [configuration] - configuration options
    * @return {(Command | object)} `this` command for chaining, or stored configuration
@@ -1060,6 +1070,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   parse(argv, parseOptions) {
+    this._prepareForParse();
     const userArgs = this._prepareUserArgs(argv, parseOptions);
     this._parseCommand([], userArgs);
 
@@ -1088,12 +1099,82 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   async parseAsync(argv, parseOptions) {
+    this._prepareForParse();
     const userArgs = this._prepareUserArgs(argv, parseOptions);
     await this._parseCommand([], userArgs);
 
     return this;
   }
 
+  _prepareForParse() {
+    if (this._savedState === null) {
+      this.saveStateBeforeParse();
+    } else {
+      this.restoreStateBeforeParse();
+    }
+  }
+
+  /**
+   * Called the first time parse is called to save state and allow a restore before subsequent calls to parse.
+   * Not usually called directly, but available for subclasses to save their custom state.
+   *
+   * This is called in a lazy way. Only commands used in parsing chain will have state saved.
+   */
+  saveStateBeforeParse() {
+    this._savedState = {
+      // name is stable if supplied by author, but may be unspecified for root command and deduced during parsing
+      _name: this._name,
+      // option values before parse have default values (including false for negated options)
+      // shallow clones
+      _optionValues: { ...this._optionValues },
+      _optionValueSources: { ...this._optionValueSources },
+    };
+  }
+
+  /**
+   * Restore state before parse for calls after the first.
+   * Not usually called directly, but available for subclasses to save their custom state.
+   *
+   * This is called in a lazy way. Only commands used in parsing chain will have state restored.
+   */
+  restoreStateBeforeParse() {
+    if (this._storeOptionsAsProperties)
+      throw new Error(`Can not call parse again when storeOptionsAsProperties is true.
+- either make a new Command for each call to parse, or stop storing options as properties`);
+
+    // clear state from _prepareUserArgs
+    this._name = this._savedState._name;
+    this._scriptPath = null;
+    this.rawArgs = [];
+    // clear state from setOptionValueWithSource
+    this._optionValues = { ...this._savedState._optionValues };
+    this._optionValueSources = { ...this._savedState._optionValueSources };
+    // clear state from _parseCommand
+    this.args = [];
+    // clear state from _processArguments
+    this.processedArgs = [];
+  }
+
+  /**
+   * Throw if expected executable is missing. Add lots of help for author.
+   *
+   * @param {string} executableFile
+   * @param {string} executableDir
+   * @param {string} subcommandName
+   */
+  _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
+    if (fs.existsSync(executableFile)) return;
+
+    const executableDirMessage = executableDir
+      ? `searched for local subcommand relative to directory '${executableDir}'`
+      : 'no directory for search for local subcommand, use .executableDir() to supply a custom directory';
+    const executableMissing = `'${executableFile}' does not exist
+ - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
+ - if the default executable name is not suitable, use the executableFile option to supply a custom name or path
+ - ${executableDirMessage}`;
+    throw new Error(executableMissing);
+  }
+
   /**
    * Execute a sub-command executable.
    *
@@ -1134,7 +1215,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       let resolvedScriptPath; // resolve possible symlink for installed npm binary
       try {
         resolvedScriptPath = fs.realpathSync(this._scriptPath);
-      } catch (err) {
+      } catch {
         resolvedScriptPath = this._scriptPath;
       }
       executableDir = path.resolve(
@@ -1177,6 +1258,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         proc = childProcess.spawn(executableFile, args, { stdio: 'inherit' });
       }
     } else {
+      this._checkForMissingExecutable(
+        executableFile,
+        executableDir,
+        subcommand._name,
+      );
       args.unshift(executableFile);
       // add executable arguments to spawn
       args = incrementNodeInspectorPort(process.execArgv).concat(args);
@@ -1215,14 +1301,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
     proc.on('error', (err) => {
       // @ts-ignore: because err.code is an unknown property
       if (err.code === 'ENOENT') {
-        const executableDirMessage = executableDir
-          ? `searched for local subcommand relative to directory '${executableDir}'`
-          : 'no directory for search for local subcommand, use .executableDir() to supply a custom directory';
-        const executableMissing = `'${executableFile}' does not exist
- - if '${subcommand._name}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
- - if the default executable name is not suitable, use the executableFile option to supply a custom name or path
- - ${executableDirMessage}`;
-        throw new Error(executableMissing);
+        this._checkForMissingExecutable(
+          executableFile,
+          executableDir,
+          subcommand._name,
+        );
         // @ts-ignore: because err.code is an unknown property
       } else if (err.code === 'EACCES') {
         throw new Error(`'${executableFile}' not executable`);
@@ -1252,6 +1335,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     const subCommand = this._findCommand(commandName);
     if (!subCommand) this.help({ error: true });
 
+    subCommand._prepareForParse();
     let promiseChain;
     promiseChain = this._chainOrCallSubCommandHook(
       promiseChain,
@@ -1629,6 +1713,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * Parse options from `argv` removing known options,
    * and return argv split into operands and unknown arguments.
    *
+   * Side effects: modifies command by storing options. Does not reset state if called again.
+   *
    * Examples:
    *
    *     argv => operands, unknown
@@ -2254,31 +2340,49 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   helpInformation(contextOptions) {
     const helper = this.createHelp();
-    if (helper.helpWidth === undefined) {
-      helper.helpWidth =
-        contextOptions && contextOptions.error
-          ? this._outputConfiguration.getErrHelpWidth()
-          : this._outputConfiguration.getOutHelpWidth();
-    }
-    return helper.formatHelp(this, helper);
+    const context = this._getOutputContext(contextOptions);
+    helper.prepareContext({
+      error: context.error,
+      helpWidth: context.helpWidth,
+      outputHasColors: context.hasColors,
+    });
+    const text = helper.formatHelp(this, helper);
+    if (context.hasColors) return text;
+    return this._outputConfiguration.stripColor(text);
   }
 
   /**
+   * @typedef HelpContext
+   * @type {object}
+   * @property {boolean} error
+   * @property {number} helpWidth
+   * @property {boolean} hasColors
+   * @property {function} write - includes stripColor if needed
+   *
+   * @returns {HelpContext}
    * @private
    */
 
-  _getHelpContext(contextOptions) {
+  _getOutputContext(contextOptions) {
     contextOptions = contextOptions || {};
-    const context = { error: !!contextOptions.error };
-    let write;
-    if (context.error) {
-      write = (arg) => this._outputConfiguration.writeErr(arg);
+    const error = !!contextOptions.error;
+    let baseWrite;
+    let hasColors;
+    let helpWidth;
+    if (error) {
+      baseWrite = (str) => this._outputConfiguration.writeErr(str);
+      hasColors = this._outputConfiguration.getErrHasColors();
+      helpWidth = this._outputConfiguration.getErrHelpWidth();
     } else {
-      write = (arg) => this._outputConfiguration.writeOut(arg);
+      baseWrite = (str) => this._outputConfiguration.writeOut(str);
+      hasColors = this._outputConfiguration.getOutHasColors();
+      helpWidth = this._outputConfiguration.getOutHelpWidth();
     }
-    context.write = contextOptions.write || write;
-    context.command = this;
-    return context;
+    const write = (str) => {
+      if (!hasColors) str = this._outputConfiguration.stripColor(str);
+      return baseWrite(str);
+    };
+    return { error, write, hasColors, helpWidth };
   }
 
   /**
@@ -2295,14 +2399,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
       deprecatedCallback = contextOptions;
       contextOptions = undefined;
     }
-    const context = this._getHelpContext(contextOptions);
+
+    const outputContext = this._getOutputContext(contextOptions);
+    /** @type {HelpTextEventContext} */
+    const eventContext = {
+      error: outputContext.error,
+      write: outputContext.write,
+      command: this,
+    };
 
     this._getCommandAndAncestors()
       .reverse()
-      .forEach((command) => command.emit('beforeAllHelp', context));
-    this.emit('beforeHelp', context);
+      .forEach((command) => command.emit('beforeAllHelp', eventContext));
+    this.emit('beforeHelp', eventContext);
 
-    let helpInformation = this.helpInformation(context);
+    let helpInformation = this.helpInformation({ error: outputContext.error });
     if (deprecatedCallback) {
       helpInformation = deprecatedCallback(helpInformation);
       if (
@@ -2312,14 +2423,14 @@ Expecting one of '${allowedValues.join("', '")}'`);
         throw new Error('outputHelp callback must return a string or a Buffer');
       }
     }
-    context.write(helpInformation);
+    outputContext.write(helpInformation);
 
     if (this._getHelpOption()?.long) {
       this.emit(this._getHelpOption().long); // deprecated
     }
-    this.emit('afterHelp', context);
+    this.emit('afterHelp', eventContext);
     this._getCommandAndAncestors().forEach((command) =>
-      command.emit('afterAllHelp', context),
+      command.emit('afterAllHelp', eventContext),
     );
   }
 
@@ -2339,6 +2450,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
   helpOption(flags, description) {
     // Support disabling built-in help option.
     if (typeof flags === 'boolean') {
+      // true is not an expected value. Do something sensible but no unit-test.
+      // istanbul ignore if
       if (flags) {
         this._helpOption = this._helpOption ?? undefined; // preserve existing option
       } else {
@@ -2392,7 +2505,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   help(contextOptions) {
     this.outputHelp(contextOptions);
-    let exitCode = process.exitCode || 0;
+    let exitCode = Number(process.exitCode ?? 0); // process.exitCode does allow a string or an integer, but we prefer just a number
     if (
       exitCode === 0 &&
       contextOptions &&
@@ -2405,6 +2518,15 @@ Expecting one of '${allowedValues.join("', '")}'`);
     this._exit(exitCode, 'commander.help', '(outputHelp)');
   }
 
+  /**
+   * // Do a little typing to coordinate emit and listener for the help text events.
+   * @typedef HelpTextEventContext
+   * @type {object}
+   * @property {boolean} error
+   * @property {Command} command
+   * @property {function} write
+   */
+
   /**
    * Add additional text to be displayed with the built-in help.
    *
@@ -2415,14 +2537,16 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {(string | Function)} text - string to add, or a function returning a string
    * @return {Command} `this` command for chaining
    */
+
   addHelpText(position, text) {
     const allowedValues = ['beforeAll', 'before', 'after', 'afterAll'];
     if (!allowedValues.includes(position)) {
       throw new Error(`Unexpected value for position to addHelpText.
 Expecting one of '${allowedValues.join("', '")}'`);
     }
+
     const helpEvent = `${position}Help`;
-    this.on(helpEvent, (context) => {
+    this.on(helpEvent, (/** @type {HelpTextEventContext} */ context) => {
       let helpStr;
       if (typeof text === 'function') {
         helpStr = text({ error: context.error, command: context.command });
@@ -2506,4 +2630,33 @@ function incrementNodeInspectorPort(args) {
   });
 }
 
+/**
+ * @returns {boolean | undefined}
+ * @package
+ */
+function useColor() {
+  // Test for common conventions.
+  // NB: the observed behaviour is in combination with how author adds color! For example:
+  //   - we do not test NODE_DISABLE_COLORS, but util:styletext does
+  //   - we do test NO_COLOR, but Chalk does not
+  //
+  // References:
+  // https://no-color.org
+  // https://bixense.com/clicolors/
+  // https://github.com/nodejs/node/blob/0a00217a5f67ef4a22384cfc80eb6dd9a917fdc1/lib/internal/tty.js#L109
+  // https://github.com/chalk/supports-color/blob/c214314a14bcb174b12b3014b2b0a8de375029ae/index.js#L33
+  // (https://force-color.org recent web page from 2023, does not match major javascript implementations)
+
+  if (
+    process.env.NO_COLOR ||
+    process.env.FORCE_COLOR === '0' ||
+    process.env.FORCE_COLOR === 'false'
+  )
+    return false;
+  if (process.env.FORCE_COLOR || process.env.CLICOLOR_FORCE !== undefined)
+    return true;
+  return undefined;
+}
+
 exports.Command = Command;
+exports.useColor = useColor; // exporting for tests

package/lib/help.js

@@ -12,11 +12,24 @@ const { humanReadableArgName } = require('./argument.js');
 class Help {
   constructor() {
     this.helpWidth = undefined;
+    this.minWidthToWrap = 40;
     this.sortSubcommands = false;
     this.sortOptions = false;
     this.showGlobalOptions = false;
   }
 
+  /**
+   * prepareContext is called by Commander after applying overrides from `Command.configureHelp()`
+   * and just before calling `formatHelp()`.
+   *
+   * Commander just uses the helpWidth and the rest is provided for optional use by more complex subclasses.
+   *
+   * @param {{ error?: boolean, helpWidth?: number, outputHasColors?: boolean }} contextOptions
+   */
+  prepareContext(contextOptions) {
+    this.helpWidth = this.helpWidth ?? contextOptions.helpWidth ?? 80;
+  }
+
   /**
    * Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one.
    *
@@ -191,7 +204,12 @@ class Help {
 
   longestSubcommandTermLength(cmd, helper) {
     return helper.visibleCommands(cmd).reduce((max, command) => {
-      return Math.max(max, helper.subcommandTerm(command).length);
+      return Math.max(
+        max,
+        this.displayWidth(
+          helper.styleSubcommandTerm(helper.subcommandTerm(command)),
+        ),
+      );
     }, 0);
   }
 
@@ -205,7 +223,10 @@ class Help {
 
   longestOptionTermLength(cmd, helper) {
     return helper.visibleOptions(cmd).reduce((max, option) => {
-      return Math.max(max, helper.optionTerm(option).length);
+      return Math.max(
+        max,
+        this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))),
+      );
     }, 0);
   }
 
@@ -219,7 +240,10 @@ class Help {
 
   longestGlobalOptionTermLength(cmd, helper) {
     return helper.visibleGlobalOptions(cmd).reduce((max, option) => {
-      return Math.max(max, helper.optionTerm(option).length);
+      return Math.max(
+        max,
+        this.displayWidth(helper.styleOptionTerm(helper.optionTerm(option))),
+      );
     }, 0);
   }
 
@@ -233,7 +257,12 @@ class Help {
 
   longestArgumentTermLength(cmd, helper) {
     return helper.visibleArguments(cmd).reduce((max, argument) => {
-      return Math.max(max, helper.argumentTerm(argument).length);
+      return Math.max(
+        max,
+        this.displayWidth(
+          helper.styleArgumentTerm(helper.argumentTerm(argument)),
+        ),
+      );
     }, 0);
   }
 
@@ -350,11 +379,11 @@ class Help {
       );
     }
     if (extraInfo.length > 0) {
-      const extraDescripton = `(${extraInfo.join(', ')})`;
+      const extraDescription = `(${extraInfo.join(', ')})`;
       if (argument.description) {
-        return `${argument.description} ${extraDescripton}`;
+        return `${argument.description} ${extraDescription}`;
       }
-      return extraDescripton;
+      return extraDescription;
     }
     return argument.description;
   }
@@ -369,71 +398,73 @@ class Help {
 
   formatHelp(cmd, helper) {
     const termWidth = helper.padWidth(cmd, helper);
-    const helpWidth = helper.helpWidth || 80;
-    const itemIndentWidth = 2;
-    const itemSeparatorWidth = 2; // between term and description
-    function formatItem(term, description) {
-      if (description) {
-        const fullText = `${term.padEnd(termWidth + itemSeparatorWidth)}${description}`;
-        return helper.wrap(
-          fullText,
-          helpWidth - itemIndentWidth,
-          termWidth + itemSeparatorWidth,
-        );
-      }
-      return term;
-    }
-    function formatList(textArray) {
-      return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth));
+    const helpWidth = helper.helpWidth ?? 80; // in case prepareContext() was not called
+
+    function callFormatItem(term, description) {
+      return helper.formatItem(term, termWidth, description, helper);
     }
 
     // Usage
-    let output = [`Usage: ${helper.commandUsage(cmd)}`, ''];
+    let output = [
+      `${helper.styleTitle('Usage:')} ${helper.styleUsage(helper.commandUsage(cmd))}`,
+      '',
+    ];
 
     // Description
     const commandDescription = helper.commandDescription(cmd);
     if (commandDescription.length > 0) {
       output = output.concat([
-        helper.wrap(commandDescription, helpWidth, 0),
+        helper.boxWrap(
+          helper.styleCommandDescription(commandDescription),
+          helpWidth,
+        ),
         '',
       ]);
     }
 
     // Arguments
     const argumentList = helper.visibleArguments(cmd).map((argument) => {
-      return formatItem(
-        helper.argumentTerm(argument),
-        helper.argumentDescription(argument),
+      return callFormatItem(
+        helper.styleArgumentTerm(helper.argumentTerm(argument)),
+        helper.styleArgumentDescription(helper.argumentDescription(argument)),
       );
     });
     if (argumentList.length > 0) {
-      output = output.concat(['Arguments:', formatList(argumentList), '']);
+      output = output.concat([
+        helper.styleTitle('Arguments:'),
+        ...argumentList,
+        '',
+      ]);
     }
 
     // Options
     const optionList = helper.visibleOptions(cmd).map((option) => {
-      return formatItem(
-        helper.optionTerm(option),
-        helper.optionDescription(option),
+      return callFormatItem(
+        helper.styleOptionTerm(helper.optionTerm(option)),
+        helper.styleOptionDescription(helper.optionDescription(option)),
       );
     });
     if (optionList.length > 0) {
-      output = output.concat(['Options:', formatList(optionList), '']);
+      output = output.concat([
+        helper.styleTitle('Options:'),
+        ...optionList,
+        '',
+      ]);
     }
 
-    if (this.showGlobalOptions) {
+    if (helper.showGlobalOptions) {
       const globalOptionList = helper
         .visibleGlobalOptions(cmd)
         .map((option) => {
-          return formatItem(
-            helper.optionTerm(option),
-            helper.optionDescription(option),
+          return callFormatItem(
+            helper.styleOptionTerm(helper.optionTerm(option)),
+            helper.styleOptionDescription(helper.optionDescription(option)),
           );
         });
       if (globalOptionList.length > 0) {
         output = output.concat([
-          'Global Options:',
-          formatList(globalOptionList),
+          helper.styleTitle('Global Options:'),
+          ...globalOptionList,
           '',
         ]);
       }
@@ -441,18 +472,103 @@ class Help {
 
     // Commands
     const commandList = helper.visibleCommands(cmd).map((cmd) => {
-      return formatItem(
-        helper.subcommandTerm(cmd),
-        helper.subcommandDescription(cmd),
+      return callFormatItem(
+        helper.styleSubcommandTerm(helper.subcommandTerm(cmd)),
+        helper.styleSubcommandDescription(helper.subcommandDescription(cmd)),
       );
     });
     if (commandList.length > 0) {
-      output = output.concat(['Commands:', formatList(commandList), '']);
+      output = output.concat([
+        helper.styleTitle('Commands:'),
+        ...commandList,
+        '',
+      ]);
     }
 
     return output.join('\n');
   }
 
+  /**
+   * Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
+   *
+   * @param {string} str
+   * @returns {number}
+   */
+  displayWidth(str) {
+    return stripColor(str).length;
+  }
+
+  /**
+   * Style the title for displaying in the help. Called with 'Usage:', 'Options:', etc.
+   *
+   * @param {string} str
+   * @returns {string}
+   */
+  styleTitle(str) {
+    return str;
+  }
+
+  styleUsage(str) {
+    // Usage has lots of parts the user might like to color separately! Assume default usage string which is formed like:
+    //    command subcommand [options] [command] <foo> [bar]
+    return str
+      .split(' ')
+      .map((word) => {
+        if (word === '[options]') return this.styleOptionText(word);
+        if (word === '[command]') return this.styleSubcommandText(word);
+        if (word[0] === '[' || word[0] === '<')
+          return this.styleArgumentText(word);
+        return this.styleCommandText(word); // Restrict to initial words?
+      })
+      .join(' ');
+  }
+  styleCommandDescription(str) {
+    return this.styleDescriptionText(str);
+  }
+  styleOptionDescription(str) {
+    return this.styleDescriptionText(str);
+  }
+  styleSubcommandDescription(str) {
+    return this.styleDescriptionText(str);
+  }
+  styleArgumentDescription(str) {
+    return this.styleDescriptionText(str);
+  }
+  styleDescriptionText(str) {
+    return str;
+  }
+  styleOptionTerm(str) {
+    return this.styleOptionText(str);
+  }
+  styleSubcommandTerm(str) {
+    // This is very like usage with lots of parts! Assume default string which is formed like:
+    //    subcommand [options] <foo> [bar]
+    return str
+      .split(' ')
+      .map((word) => {
+        if (word === '[options]') return this.styleOptionText(word);
+        if (word[0] === '[' || word[0] === '<')
+          return this.styleArgumentText(word);
+        return this.styleSubcommandText(word); // Restrict to initial words?
+      })
+      .join(' ');
+  }
+  styleArgumentTerm(str) {
+    return this.styleArgumentText(str);
+  }
+  styleOptionText(str) {
+    return str;
+  }
+  styleArgumentText(str) {
+    return str;
+  }
+  styleSubcommandText(str) {
+    return str;
+  }
+  styleCommandText(str) {
+    return str;
+  }
+
   /**
    * Calculate the pad width from the maximum term length.
    *
@@ -471,50 +587,123 @@ class Help {
   }
 
   /**
-   * Wrap the given string to width characters per line, with lines after the first indented.
-   * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.
+   * Detect manually wrapped and indented strings by checking for line break followed by whitespace.
    *
    * @param {string} str
-   * @param {number} width
-   * @param {number} indent
-   * @param {number} [minColumnWidth=40]
-   * @return {string}
-   *
+   * @returns {boolean}
    */
+  preformatted(str) {
+    return /\n[^\S\r\n]/.test(str);
+  }
 
-  wrap(str, width, indent, minColumnWidth = 40) {
-    // Full \s characters, minus the linefeeds.
-    const indents =
-      ' \\f\\t\\v\u00a0\u1680\u2000-\u200a\u202f\u205f\u3000\ufeff';
-    // Detect manually wrapped and indented strings by searching for line break followed by spaces.
-    const manualIndent = new RegExp(`[\\n][${indents}]+`);
-    if (str.match(manualIndent)) return str;
-    // Do not wrap if not enough room for a wrapped column of text (as could end up with a word per line).
-    const columnWidth = width - indent;
-    if (columnWidth < minColumnWidth) return str;
-
-    const leadingStr = str.slice(0, indent);
-    const columnText = str.slice(indent).replace('\r\n', '\n');
-    const indentString = ' '.repeat(indent);
-    const zeroWidthSpace = '\u200B';
-    const breaks = `\\s${zeroWidthSpace}`;
-    // Match line end (so empty lines don't collapse),
-    // or as much text as will fit in column, or excess text up to first break.
-    const regex = new RegExp(
-      `\n|.{1,${columnWidth - 1}}([${breaks}]|$)|[^${breaks}]+?([${breaks}]|$)`,
-      'g',
+  /**
+   * 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
+   *
+   * @param {string} term
+   * @param {number} termWidth
+   * @param {string} description
+   * @param {Help} helper
+   * @returns {string}
+   */
+  formatItem(term, termWidth, description, helper) {
+    const itemIndent = 2;
+    const itemIndentStr = ' '.repeat(itemIndent);
+    if (!description) return itemIndentStr + term;
+
+    // Pad the term out to a consistent width, so descriptions are aligned.
+    const paddedTerm = term.padEnd(
+      termWidth + term.length - helper.displayWidth(term),
     );
-    const lines = columnText.match(regex) || [];
+
+    // Format the description.
+    const spacerWidth = 2; // between term and description
+    const helpWidth = this.helpWidth ?? 80; // in case prepareContext() was not called
+    const remainingWidth = helpWidth - termWidth - spacerWidth - itemIndent;
+    let formattedDescription;
+    if (
+      remainingWidth < this.minWidthToWrap ||
+      helper.preformatted(description)
+    ) {
+      formattedDescription = description;
+    } else {
+      const wrappedDescription = helper.boxWrap(description, remainingWidth);
+      formattedDescription = wrappedDescription.replace(
+        /\n/g,
+        '\n' + ' '.repeat(termWidth + spacerWidth),
+      );
+    }
+
+    // Construct and overall indent.
     return (
-      leadingStr +
-      lines
-        .map((line, i) => {
-          if (line === '\n') return ''; // preserve empty lines
-          return (i > 0 ? indentString : '') + line.trimEnd();
-        })
-        .join('\n')
+      itemIndentStr +
+      paddedTerm +
+      ' '.repeat(spacerWidth) +
+      formattedDescription.replace(/\n/g, `\n${itemIndentStr}`)
     );
   }
+
+  /**
+   * Wrap a string at whitespace, preserving existing line breaks.
+   * Wrapping is skipped if the width is less than `minWidthToWrap`.
+   *
+   * @param {string} str
+   * @param {number} width
+   * @returns {string}
+   */
+  boxWrap(str, width) {
+    if (width < this.minWidthToWrap) return str;
+
+    const rawLines = str.split(/\r\n|\n/);
+    // split up text by whitespace
+    const chunkPattern = /[\s]*[^\s]+/g;
+    const wrappedLines = [];
+    rawLines.forEach((line) => {
+      const chunks = line.match(chunkPattern);
+      if (chunks === null) {
+        wrappedLines.push('');
+        return;
+      }
+
+      let sumChunks = [chunks.shift()];
+      let sumWidth = this.displayWidth(sumChunks[0]);
+      chunks.forEach((chunk) => {
+        const visibleWidth = this.displayWidth(chunk);
+        // Accumulate chunks while they fit into width.
+        if (sumWidth + visibleWidth <= width) {
+          sumChunks.push(chunk);
+          sumWidth += visibleWidth;
+          return;
+        }
+        wrappedLines.push(sumChunks.join(''));
+
+        const nextChunk = chunk.trimStart(); // trim space at line break
+        sumChunks = [nextChunk];
+        sumWidth = this.displayWidth(nextChunk);
+      });
+      wrappedLines.push(sumChunks.join(''));
+    });
+
+    return wrappedLines.join('\n');
+  }
+}
+
+/**
+ * Strip style ANSI escape sequences from the string. In particular, SGR (Select Graphic Rendition) codes.
+ *
+ * @param {string} str
+ * @returns {string}
+ * @package
+ */
+
+function stripColor(str) {
+  // eslint-disable-next-line no-control-regex
+  const sgrPattern = /\x1b\[\d*(;\d*)*m/g;
+  return str.replace(sgrPattern, '');
 }
 
 exports.Help = Help;
+exports.stripColor = stripColor;

package/lib/option.js

@@ -207,13 +207,16 @@ class Option {
 
   /**
    * Return option name, in a camelcase format that can be used
-   * as a object attribute key.
+   * as an object attribute key.
    *
    * @return {string}
    */
 
   attributeName() {
-    return camelcase(this.name().replace(/^no-/, ''));
+    if (this.negate) {
+      return camelcase(this.name().replace(/^no-/, ''));
+    }
+    return camelcase(this.name());
   }
 
   /**
@@ -312,17 +315,32 @@ function camelcase(str) {
 function splitOptionFlags(flags) {
   let shortFlag;
   let longFlag;
-  // Use original very loose parsing to maintain backwards compatibility for now,
-  // which allowed for example unintended `-sw, --short-word` [sic].
-  const flagParts = flags.split(/[ |,]+/);
-  if (flagParts.length > 1 && !/^[[<]/.test(flagParts[1]))
-    shortFlag = flagParts.shift();
-  longFlag = flagParts.shift();
-  // Add support for lone short flag without significantly changing parsing!
-  if (!shortFlag && /^-[^-]$/.test(longFlag)) {
-    shortFlag = longFlag;
-    longFlag = undefined;
-  }
+  // short flag, single dash and single character
+  const shortFlagExp = /^-[^-]$/;
+  // long flag, double dash and at least one character
+  const longFlagExp = /^--[^-]/;
+
+  const flagParts = flags.split(/[ |,]+/).concat('guard');
+  if (shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();
+  if (longFlagExp.test(flagParts[0])) longFlag = flagParts.shift();
+
+  // Check for some unsupported flags that people try.
+  if (/^-[^-][^-]/.test(flagParts[0]))
+    throw new Error(
+      `invalid Option flags, short option is dash and single character: '${flags}'`,
+    );
+  if (shortFlag && shortFlagExp.test(flagParts[0]))
+    throw new Error(
+      `invalid Option flags, more than one short flag: '${flags}'`,
+    );
+  if (longFlag && longFlagExp.test(flagParts[0]))
+    throw new Error(
+      `invalid Option flags, more than one long flag: '${flags}'`,
+    );
+  // Generic error if failed to find a flag or an unexpected flag left over.
+  if (!(shortFlag || longFlag) || flagParts[0].startsWith('-'))
+    throw new Error(`invalid Option flags: '${flags}'`);
+
   return { shortFlag, longFlag };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "12.1.0",
+  "version": "13.0.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -60,21 +60,19 @@
     }
   },
   "devDependencies": {
-    "@eslint/js": "^8.56.0",
+    "@eslint/js": "^9.4.0",
     "@types/jest": "^29.2.4",
-    "@types/node": "^20.2.5",
-    "eslint": "^8.30.0",
+    "@types/node": "^22.7.4",
+    "eslint": "^9.17.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-jest": "^28.3.0",
-    "eslint-plugin-jsdoc": "^48.1.0",
-    "globals": "^13.24.0",
+    "globals": "^15.7.0",
     "jest": "^29.3.1",
     "prettier": "^3.2.5",
-    "prettier-plugin-jsdoc": "^1.3.0",
     "ts-jest": "^29.0.3",
     "tsd": "^0.31.0",
     "typescript": "^5.0.4",
-    "typescript-eslint": "^7.0.1"
+    "typescript-eslint": "^8.12.2"
   },
   "types": "typings/index.d.ts",
   "engines": {

package/typings/index.d.ts

@@ -1,8 +1,6 @@
 // Type definitions for commander
 // Original definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>, Jules Randolph <https://github.com/sveinburne>
 
-// Using method rather than property for method-signature-style, to document method overloads separately. Allow either.
-/* eslint-disable @typescript-eslint/method-signature-style */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 // This is a trick to encourage editor to suggest the known literals while still
@@ -190,7 +188,7 @@ export class Option {
 
   /**
    * Return option name, in a camelcase format that can be used
-   * as a object attribute key.
+   * as an object attribute key.
    */
   attributeName(): string;
 
@@ -205,12 +203,25 @@ export class Option {
 export class Help {
   /** output helpWidth, long lines are wrapped to fit */
   helpWidth?: number;
+  minWidthToWrap: number;
   sortSubcommands: boolean;
   sortOptions: boolean;
   showGlobalOptions: boolean;
 
   constructor();
 
+  /*
+   * prepareContext is called by Commander after applying overrides from `Command.configureHelp()`
+   * and just before calling `formatHelp()`.
+   *
+   * Commander just uses the helpWidth and the others are provided for subclasses.
+   */
+  prepareContext(contextOptions: {
+    error?: boolean;
+    helpWidth?: number;
+    outputHasColors?: boolean;
+  }): void;
+
   /** Get the command term to show in the list of subcommands. */
   subcommandTerm(cmd: Command): string;
   /** Get the command summary to show in the list of subcommands. */
@@ -246,18 +257,60 @@ export class Help {
   longestGlobalOptionTermLength(cmd: Command, helper: Help): number;
   /** Get the longest argument term length. */
   longestArgumentTermLength(cmd: Command, helper: Help): number;
+
+  /** Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations. */
+  displayWidth(str: string): number;
+
+  /** Style the titles. Called with 'Usage:', 'Options:', etc. */
+  styleTitle(title: string): string;
+
+  /** Usage: <str> */
+  styleUsage(str: string): string;
+  /** Style for command name in usage string.  */
+  styleCommandText(str: string): string;
+
+  styleCommandDescription(str: string): string;
+  styleOptionDescription(str: string): string;
+  styleSubcommandDescription(str: string): string;
+  styleArgumentDescription(str: string): string;
+  /** Base style used by descriptions. */
+  styleDescriptionText(str: string): string;
+
+  styleOptionTerm(str: string): string;
+  styleSubcommandTerm(str: string): string;
+  styleArgumentTerm(str: string): string;
+
+  /** Base style used in terms and usage for options. */
+  styleOptionText(str: string): string;
+  /** Base style used in terms and usage for subcommands. */
+  styleSubcommandText(str: string): string;
+  /** Base style used in terms and usage for arguments. */
+  styleArgumentText(str: string): string;
+
   /** Calculate the pad width from the maximum term length. */
   padWidth(cmd: Command, helper: Help): number;
 
   /**
-   * Wrap the given string to width characters per line, with lines after the first indented.
-   * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.
+   * 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;
+
+  /** 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
    */
-  wrap(
-    str: string,
-    width: number,
-    indent: number,
-    minColumnWidth?: number,
+  formatItem(
+    term: string,
+    termWidth: number,
+    description: string,
+    helper: Help,
   ): string;
 
   /** Generate the built-in help text. */
@@ -280,9 +333,14 @@ export interface AddHelpTextContext {
 export interface OutputConfiguration {
   writeOut?(str: string): void;
   writeErr?(str: string): void;
+  outputError?(str: string, write: (str: string) => void): void;
+
   getOutHelpWidth?(): number;
   getErrHelpWidth?(): number;
-  outputError?(str: string, write: (str: string) => void): void;
+
+  getOutHasColors?(): boolean;
+  getErrHasColors?(): boolean;
+  stripColor?(str: string): string;
 }
 
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
@@ -544,7 +602,7 @@ export class Command {
    *
    * @returns `this` command for chaining
    */
-  action(fn: (...args: any[]) => void | Promise<void>): this;
+  action(fn: (this: this, ...args: any[]) => void | Promise<void>): this;
 
   /**
    * Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both.
@@ -763,10 +821,28 @@ export class Command {
     parseOptions?: ParseOptions,
   ): Promise<this>;
 
+  /**
+   * Called the first time parse is called to save state and allow a restore before subsequent calls to parse.
+   * Not usually called directly, but available for subclasses to save their custom state.
+   *
+   * This is called in a lazy way. Only commands used in parsing chain will have state saved.
+   */
+  saveStateBeforeParse(): void;
+
+  /**
+   * Restore state before parse for calls after the first.
+   * Not usually called directly, but available for subclasses to save their custom state.
+   *
+   * This is called in a lazy way. Only commands used in parsing chain will have state restored.
+   */
+  restoreStateBeforeParse(): void;
+
   /**
    * Parse options from `argv` removing known options,
    * and return argv split into operands and unknown arguments.
    *
+   * Side effects: modifies command by storing options. Does not reset state if called again.
+   *
    *     argv => operands, unknown
    *     --known kkk op => [op], []
    *     op --known kkk => [op], []