commander 12.1.0 → 13.0.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 });
@@ -923,23 +923,7 @@ program.helpCommand('assist [command]', 'show assistance');
 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.
 
-The data properties are:
-
-- `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 see (./docs/help-in-depth.md)
 
 ## Custom event listeners
 

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
@@ -56,15 +56,20 @@ class Command extends EventEmitter {
     this._showHelpAfterError = false;
     this._showSuggestionAfterError = true;
 
-    // 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 +218,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
@@ -1134,7 +1143,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(
@@ -2254,31 +2263,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 +2322,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 +2346,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 +2373,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 +2428,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 +2441,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 +2460,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 +2553,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-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": "^8.57.1",
     "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

@@ -190,7 +190,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 +205,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 +259,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`.
    */
-  wrap(
-    str: string,
-    width: number,
-    indent: number,
-    minColumnWidth?: number,
+  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
+   */
+  formatItem(
+    term: string,
+    termWidth: number,
+    description: string,
+    helper: Help,
   ): string;
 
   /** Generate the built-in help text. */
@@ -280,9 +335,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 +604,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.