.eslintrc.js

@@ -14,7 +14,7 @@ const javascriptSettings = {
 };
 
 const typescriptSettings = {
-  files: ['*.ts'],
+  files: ['*.ts', '*.mts'],
   parserOptions: {
     project: './tsconfig.json'
   },

.github/workflows/tests.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [12.x, 14.x, 16.x, 18.x]
+        node-version: [16.x, 18.x, 20.x]
         os: [ubuntu-latest, windows-latest, macos-latest]
 
     steps:

CHANGELOG.md

@@ -8,6 +8,61 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [11.0.0] (2023-06-16)
+
+### Fixed
+
+- help command works when help option is disabled ([#1864])
+
+### Changed
+
+- leading and trailing spaces are now ignored by the .arguments() method ([#1874])
+- refine "types" exports for ESM to follow TypeScript guidelines ([#1886])
+- *Breaking:* Commander 11 requires Node.js v16 or higher
+
+## [10.0.1] (2023-04-15)
+
+### Added
+
+- improvements to documentation ([#1858], [#1859], [#1860])
+
+### Fixed
+
+- remove unused `Option.optionFlags` property from TypeScript definition ([#1844])
+
+### Changed
+
+- assume boolean option intended if caller passes string instead of hash to `.implies()` ([#1854])
+
+## [10.0.0] (2023-01-13)
+
+### Added
+
+- wrap command description in help ([#1804])
+
+### Changed
+
+- *Breaking:* Commander 10 requires Node.js v14 or higher
+
+## [9.5.0] (2023-01-07)
+
+### Added
+
+- `.getOptionValueSourceWithGlobals()` ([#1832])
+- `showGlobalOptions` for `.configureHelp{}` and `Help` ([#1828])
+
+## [9.4.1] (2022-09-30)
+
+### Fixed
+
+- `.setOptionValue()` now also clears option source ([#1795])
+- TypeScript: add `implied` to `OptionValueSource` for option values set by using `.implies()` ([#1794])
+- TypeScript : add `undefined` to return type of `.getOptionValueSource()` ([#1794])
+
+### Changed
+
+- additions to README
+
 ## [9.4.0] (2022-07-15)
 
 ### Added
@@ -81,8 +136,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - use command name as prefix for subcommand stand-alone executable name (with fallback to script name for backwards compatibility) ([#1571])
 - allow absolute path with `executableFile` ([#1571])
 - removed restriction that nested subcommands must specify `executableFile` ([#1571])
-- TypeScript: allow passing readonly string array to `.choices()` [(#1667)]
-- TypeScript: allow passing readonly string array to `.parse()`, `.parseAsync()`, `.aliases()` [(#1669)]
+- TypeScript: allow passing readonly string array to `.choices()` ([#1667])
+- TypeScript: allow passing readonly string array to `.parse()`, `.parseAsync()`, `.aliases()` ([#1669])
 
 ### Fixed
 
@@ -92,7 +147,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - *Breaking:* removed internal fallback to `require.main.filename` when script not known from arguments passed to `.parse()` (can supply details using `.name()`, and `.executableDir()` or `executableFile`) ([#1571])
 
-
 ## [9.0.0-1] (2022-01-15)
 
 (Released in 9.0.0)
@@ -274,8 +328,8 @@ program.showHelpAfterError();
 ### Changed
 
 - *Breaking:* options are stored safely by default, not as properties on the command ([#1409])
-    - this especially affects accessing options on program, use `program.opts()`
-    - revert behaviour with `.storeOptionsAsProperties()`
+  - this especially affects accessing options on program, use `program.opts()`
+  - revert behaviour with `.storeOptionsAsProperties()`
 - *Breaking:* action handlers are passed options and command separately ([#1409])
 - deprecated callback parameter to `.help()` and `.outputHelp()` (removed from README) ([#1296])
 - *Breaking:* errors now displayed using `process.stderr.write()` instead of `console.error()`
@@ -294,9 +348,9 @@ program.showHelpAfterError();
 ### Deleted
 
 - *Breaking:* `.passCommandToAction()` ([#1409])
-    - no longer needed as action handler is passed options and command
+  - no longer needed as action handler is passed options and command
 - *Breaking:* "extra arguments" parameter to action handler ([#1409])
-    - if being used to detect excess arguments, there is now an error available by setting `.allowExcessArguments(false)`
+  - if being used to detect excess arguments, there is now an error available by setting `.allowExcessArguments(false)`
 
 ### Migration Tips
 
@@ -381,7 +435,7 @@ program
 
 ### Fixed
 
-- some tests failed if directory path included a space ([1390])
+- some tests failed if directory path included a space ([#1390])
 
 ## [6.2.0] (2020-10-25)
 
@@ -1053,6 +1107,7 @@ program
 [#1490]: https://github.com/tj/commander.js/pull/1490
 [#1497]: https://github.com/tj/commander.js/pull/1497
 [#1500]: https://github.com/tj/commander.js/pull/1500
+[#1502]: https://github.com/tj/commander.js/pull/1502
 [#1508]: https://github.com/tj/commander.js/pull/1508
 [#1513]: https://github.com/tj/commander.js/pull/1513
 [#1514]: https://github.com/tj/commander.js/pull/1514
@@ -1095,6 +1150,19 @@ program
 [#1756]: https://github.com/tj/commander.js/pull/1756
 [#1763]: https://github.com/tj/commander.js/pull/1763
 [#1767]: https://github.com/tj/commander.js/pull/1767
+[#1794]: https://github.com/tj/commander.js/pull/1794
+[#1795]: https://github.com/tj/commander.js/pull/1795
+[#1804]: https://github.com/tj/commander.js/pull/1804
+[#1832]: https://github.com/tj/commander.js/pull/1832
+[#1828]: https://github.com/tj/commander.js/pull/1828
+[#1844]: https://github.com/tj/commander.js/pull/1844
+[#1854]: https://github.com/tj/commander.js/pull/1854
+[#1858]: https://github.com/tj/commander.js/pull/1858
+[#1859]: https://github.com/tj/commander.js/pull/1859
+[#1860]: https://github.com/tj/commander.js/pull/1860
+[#1864]: https://github.com/tj/commander.js/pull/1864
+[#1874]: https://github.com/tj/commander.js/pull/1874
+[#1886]: https://github.com/tj/commander.js/pull/1886
 
 <!-- Referenced in 5.x -->
 [#1]: https://github.com/tj/commander.js/issues/1
@@ -1135,6 +1203,7 @@ program
 [#1248]: https://github.com/tj/commander.js/pull/1248
 
 <!-- Referenced in 4.x -->
+[#933]: https://github.com/tj/commander.js/pull/933
 [#1027]: https://github.com/tj/commander.js/pull/1027
 [#1035]: https://github.com/tj/commander.js/pull/1035
 [#1040]: https://github.com/tj/commander.js/pull/1040
@@ -1173,6 +1242,11 @@ program
 [#1028]: https://github.com/tj/commander.js/pull/1028
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[11.0.0]: https://github.com/tj/commander.js/compare/v10.0.1...v11.0.0
+[10.0.1]: https://github.com/tj/commander.js/compare/v10.0.0...v10.0.1
+[10.0.0]: https://github.com/tj/commander.js/compare/v9.5.0...v10.0.0
+[9.5.0]: https://github.com/tj/commander.js/compare/v9.4.1...v9.5.0
+[9.4.1]: https://github.com/tj/commander.js/compare/v9.4.0...v9.4.1
 [9.4.0]: https://github.com/tj/commander.js/compare/v9.3.0...v9.4.0
 [9.3.0]: https://github.com/tj/commander.js/compare/v9.2.0...v9.3.0
 [9.2.0]: https://github.com/tj/commander.js/compare/v9.1.0...v9.2.0

Readme.md

@@ -48,6 +48,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [createCommand()](#createcommand)
     - [Node options such as `--harmony`](#node-options-such-as---harmony)
     - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
+    - [npm run-script](#npm-run-script)
     - [Display error](#display-error)
     - [Override exit and output handling](#override-exit-and-output-handling)
     - [Additional documentation](#additional-documentation)
@@ -330,7 +331,7 @@ For information about possible ambiguous cases, see [options taking varying argu
 
 ### Required option
 
-You may specify a required (mandatory) option using `.requiredOption`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option` in format, taking flags and description, and optional default value or custom processing.
+You may specify a required (mandatory) option using `.requiredOption()`. The option must have a value after parsing, usually specified on the command line, or perhaps from a default value (say from environment). The method is otherwise the same as `.option()` in format, taking flags and description, and optional default value or custom processing.
 
 Example file: [options-required.js](./examples/options-required.js)
 
@@ -441,6 +442,8 @@ $ extra --disable-server --port 8000
 error: option '--disable-server' cannot be used with option '-p, --port <number>'
 ```
 
+Specify a required (mandatory) option using the `Option` method `.makeOptionMandatory()`. This matches the `Command` method [.requiredOption()](#required-option).
+
 ### Custom option processing
 
 You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
@@ -541,6 +544,10 @@ Configuration options can be passed with the call to `.command()` and `.addComma
 remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
 subcommand is specified ([example](./examples/defaultCommand.js)).
 
+You can add alternative names for a command with `.alias()`. ([example](./examples/alias.js))
+
+For safety, `.addCommand()` does not automatically copy the inherited settings from the parent command. There is a helper routine `.copyInheritedSettings()` for copying the settings when they are wanted.
+
 ### Command-arguments
 
 For subcommands, you can specify the argument syntax in the call to `.command()` (as shown above). This
@@ -724,6 +731,8 @@ The supported events are:
 | `preAction`, `postAction` |  before/after action handler for this command and its nested subcommands |   `(thisCommand, actionCommand)` |
 | `preSubcommand` | before parsing direct subcommand  | `(thisCommand, subcommand)` |
 
+For an overview of the life cycle events see [parsing life cycle and hooks](./docs/parsing-and-hooks.md).
+
 ## Automated help
 
 The help information is auto-generated based on the information commander already knows about your program. The default
@@ -755,6 +764,8 @@ shell help spawn
 shell spawn --help
 ```
 
+Long descriptions are wrapped to fit the available width. (However, a  description that includes a line-break followed by whitespace is assumed to be pre-formatted and not wrapped.)
+
 ### Custom help
 
 You can add extra text to be displayed along with the built-in help.
@@ -911,8 +922,9 @@ 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)
 
-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.
+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)
 
@@ -1007,7 +1019,15 @@ program
 
 ### TypeScript
 
-If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.
+extra-typings: There is an optional project to infer extra type information from the option and argument definitions.
+This adds strong typing to the options returned by `.opts()` and the parameters to `.action()`.
+See [commander-js/extra-typings](https://github.com/commander-js/extra-typings) for more.
+
+```
+import { Command } from '@commander-js/extra-typings';
+```
+
+ts-node: If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.
 
 ```sh
 node -r ts-node/register pm.ts
@@ -1042,6 +1062,17 @@ the inspector port is incremented by 1 for the spawned subcommand.
 
 If you are using VSCode to debug executable subcommands you need to set the `"autoAttachChildProcesses": true` flag in your launch.json configuration.
 
+### npm run-script
+
+By default when you call your program using run-script, `npm` will parse any options on the command-line and they will not reach your program. Use
+ `--` to stop the npm option parsing and pass through all the arguments.
+
+ The synopsis for [npm run-script](https://docs.npmjs.com/cli/v9/commands/npm-run-script) explicitly shows the `--` for this reason:
+
+```console
+npm run-script <command> [-- <args>]
+```
+
 ### Display error
 
 This routine is available to invoke the Commander error handling for your own error conditions. (See also the next section about exit handling.)
@@ -1099,10 +1130,11 @@ There is more information available about:
 
 - [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
 - [options taking varying arguments](./docs/options-taking-varying-arguments.md)
+- [parsing life cycle and hooks](./docs/parsing-and-hooks.md)
 
 ## Support
 
-The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v12.20.0.
+The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v16.
 (For older versions of Node.js, use an older version of Commander.)
 
 The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

Readme_zh-CN.md

@@ -1059,7 +1059,7 @@ program
 
 ## 支持
 
-当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v12.20.0。
+当前版本的 Commander 在 LTS 版本的 Node.js 上完全支持。并且至少需要 v16。
 （使用更低版本 Node.js 的用户建议安装更低版本的 Commander）
 
 社区支持请访问项目的 [Issues](https://github.com/tj/commander.js/issues)。

SECURITY.md

@@ -6,8 +6,8 @@ Old versions receive security updates for six months.
 
 | Version | Supported                                  |
 | ------- | ------------------------------------------ |
-| 8.x     | :white_check_mark: support ends 2022-07-31 |
-| < 8     | :x:                                        |
+| 10.x    | :white_check_mark: support ends 2024-01-16 |
+| < 10    | :x:                                        |
 
 Pull Requests for security issues will be considered for older versions back to 2.x.
 

docs/deprecated.md

@@ -9,11 +9,12 @@ They are currently still available for backwards compatibility, but should not b
   - [Default import of global Command object](#default-import-of-global-command-object)
   - [Callback to .help() and .outputHelp()](#callback-to-help-and-outputhelp)
   - [.on('--help')](#on--help)
-  - [.on('command:*')](#oncommand)
-  - [.command('*')](#command)
+  - [.on('command:\*')](#oncommand)
+  - [.command('\*')](#command)
   - [cmd.description(cmdDescription, argDescriptions)](#cmddescriptioncmddescription-argdescriptions)
   - [InvalidOptionArgumentError](#invalidoptionargumenterror)
   - [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character)
+  - [Import from `commander/esm.mjs`](#import-from-commanderesmmjs)
 
 ## RegExp .option() parameter
 
@@ -190,3 +191,19 @@ Deprecated from Commander v8.
 Short option flags like `-ws` were never supported, but the old README did not make this clear. The README now states that short options are a single character.
 
 README updated in Commander v3. Deprecated from Commander v9.
+
+## Import from `commander/esm.mjs`
+
+The first support for named imports required an explicit entry file.
+
+```js
+import { Command } from 'commander/esm.mjs';
+```
+
+This is no longer required, just import directly from the module.
+
+```js
+import { Command } from 'commander';
+```
+
+README updated in Commander v9. Deprecated from Commander v9.

docs/parsing-and-hooks.md

@@ -0,0 +1,23 @@
+# Parsing life cycle and hooks
+
+The processing starts with an array of args. Each command processes and removes the options it understands, and passes the remaining args to the next subcommand.
+The final command calls the action handler.
+
+Starting with top-level command (program):
+
+- parse options: parse recognised options (for this command) and remove from args
+- parse env: look for environment variables (for this command)
+- process implied: set any implied option values (for this command)
+- if the first arg is a subcommand
+    - call `preSubcommand` hooks
+    - pass remaining arguments to subcommand, and process same way
+
+Once reach final (leaf) command:
+
+- check for missing mandatory options
+- check for conflicting options
+- check for unknown options
+- process remaining args as command-arguments
+- call `preAction` hooks
+- call action handler
+- call `postAction` hooks