@rslib/core 0.2.2 → 0.3.0

package/compiled/commander/index.js

@@ -41,10 +41,10 @@ module.exports = require("node:process");
 
 /***/ }),
 
-/***/ 654:
+/***/ 429:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
-const { InvalidArgumentError } = __nccwpck_require__(829);
+const { InvalidArgumentError } = __nccwpck_require__(848);
 
 class Argument {
   /**
@@ -197,7 +197,7 @@ exports.humanReadableArgName = humanReadableArgName;
 
 /***/ }),
 
-/***/ 955:
+/***/ 745:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
 const EventEmitter = (__nccwpck_require__(673).EventEmitter);
@@ -206,11 +206,11 @@ const path = __nccwpck_require__(411);
 const fs = __nccwpck_require__(561);
 const process = __nccwpck_require__(742);
 
-const { Argument, humanReadableArgName } = __nccwpck_require__(654);
-const { CommanderError } = __nccwpck_require__(829);
-const { Help } = __nccwpck_require__(567);
-const { Option, DualOptions } = __nccwpck_require__(230);
-const { suggestSimilar } = __nccwpck_require__(241);
+const { Argument, humanReadableArgName } = __nccwpck_require__(429);
+const { CommanderError } = __nccwpck_require__(848);
+const { Help, stripColor } = __nccwpck_require__(613);
+const { Option, DualOptions } = __nccwpck_require__(234);
+const { suggestSimilar } = __nccwpck_require__(824);
 
 class Command extends EventEmitter {
   /**
@@ -227,7 +227,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
@@ -257,16 +257,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;
@@ -415,14 +421,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
@@ -1262,6 +1272,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   parse(argv, parseOptions) {
+    this._prepareForParse();
     const userArgs = this._prepareUserArgs(argv, parseOptions);
     this._parseCommand([], userArgs);
 
@@ -1290,12 +1301,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.
    *
@@ -1336,7 +1417,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(
@@ -1379,6 +1460,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);
@@ -1417,14 +1503,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`);
@@ -1454,6 +1537,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,
@@ -1831,6 +1915,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
@@ -2456,31 +2542,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 };
   }
 
   /**
@@ -2497,14 +2601,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 (
@@ -2514,14 +2625,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),
     );
   }
 
@@ -2541,6 +2652,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 {
@@ -2594,7 +2707,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 &&
@@ -2607,6 +2720,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.
    *
@@ -2617,14 +2739,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 });
@@ -2708,12 +2832,41 @@ 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
 
 
 /***/ }),
 
-/***/ 829:
+/***/ 848:
 /***/ ((__unused_webpack_module, exports) => {
 
 /**
@@ -2759,10 +2912,10 @@ exports.InvalidArgumentError = InvalidArgumentError;
 
 /***/ }),
 
-/***/ 567:
+/***/ 613:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
-const { humanReadableArgName } = __nccwpck_require__(654);
+const { humanReadableArgName } = __nccwpck_require__(429);
 
 /**
  * TypeScript import types for JSDoc, used by Visual Studio Code IntelliSense and `npm run typescript-checkJS`
@@ -2776,11 +2929,24 @@ const { humanReadableArgName } = __nccwpck_require__(654);
 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.
    *
@@ -2955,7 +3121,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);
   }
 
@@ -2969,7 +3140,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);
   }
 
@@ -2983,7 +3157,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);
   }
 
@@ -2997,7 +3174,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);
   }
 
@@ -3114,11 +3296,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;
   }
@@ -3133,71 +3315,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,
           '',
         ]);
       }
@@ -3205,18 +3389,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.
    *
@@ -3235,61 +3504,134 @@ 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);
+  }
+
+  /**
+   * 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;
 
-  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',
+    // 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;
 
 
 /***/ }),
 
-/***/ 230:
+/***/ 234:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
-const { InvalidArgumentError } = __nccwpck_require__(829);
+const { InvalidArgumentError } = __nccwpck_require__(848);
 
 class Option {
   /**
@@ -3498,13 +3840,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());
   }
 
   /**
@@ -3603,17 +3948,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 };
 }
 
@@ -3623,7 +3983,7 @@ exports.DualOptions = DualOptions;
 
 /***/ }),
 
-/***/ 241:
+/***/ 824:
 /***/ ((__unused_webpack_module, exports) => {
 
 const maxDistance = 3;
@@ -3773,11 +4133,11 @@ var __webpack_exports__ = {};
 // This entry need to be wrapped in an IIFE because it need to be isolated against other modules in the chunk.
 (() => {
 var exports = __webpack_exports__;
-const { Argument } = __nccwpck_require__(654);
-const { Command } = __nccwpck_require__(955);
-const { CommanderError, InvalidArgumentError } = __nccwpck_require__(829);
-const { Help } = __nccwpck_require__(567);
-const { Option } = __nccwpck_require__(230);
+const { Argument } = __nccwpck_require__(429);
+const { Command } = __nccwpck_require__(745);
+const { CommanderError, InvalidArgumentError } = __nccwpck_require__(848);
+const { Help } = __nccwpck_require__(613);
+const { Option } = __nccwpck_require__(234);
 
 exports.program = new Command();