.github/dependabot.yml

@@ -1,6 +1,7 @@
 version: 2
 updates:
 - package-ecosystem: "github-actions"
+  target-branch: "develop"
   directory: "/"
   schedule:
       interval: "weekly"

.github/workflows/codeql-analysis.yml

@@ -2,10 +2,10 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, develop ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ master ]
+    branches: [ master, develop ]
   schedule:
     - cron: '27 5 * * 6'
 
@@ -25,11 +25,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v2
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -40,7 +40,7 @@ jobs:
     # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
+      uses: github/codeql-action/autobuild@v2
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -54,4 +54,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v2

.github/workflows/tests.yml

@@ -16,9 +16,9 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v2
+      uses: actions/setup-node@v3
       with:
         cache: 'npm'
         node-version: ${{ matrix.node-version }}

CHANGELOG.md

@@ -8,6 +8,20 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [9.4.0] (2022-07-15)
+
+### Added
+
+- `preSubcommand` hook called before direct subcommands ([#1763])
+
+### Fixed
+
+- export `InvalidOptionArgumentError` in esm ([#1756])
+
+### Changed
+
+- update dependencies ([#1767])
+
 ## [9.3.0] (2022-05-28)
 
 ### Added
@@ -1078,6 +1092,9 @@ program
 [#1724]: https://github.com/tj/commander.js/pull/1724
 [#1726]: https://github.com/tj/commander.js/pull/1726
 [#1727]: https://github.com/tj/commander.js/pull/1727
+[#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
 
 <!-- Referenced in 5.x -->
 [#1]: https://github.com/tj/commander.js/issues/1
@@ -1156,6 +1173,7 @@ program
 [#1028]: https://github.com/tj/commander.js/pull/1028
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[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
 [9.1.0]: https://github.com/tj/commander.js/compare/v9.0.0...v9.1.0

Readme.md

@@ -719,10 +719,10 @@ The callback hook can be `async`, in which case you call `.parseAsync` rather th
 
 The supported events are:
 
-- `preAction`: called before action handler for this command and its subcommands
-- `postAction`: called after action handler for this command and its subcommands
-
-The hook is passed the command it was added to, and the command running the action handler.
+| event name | when hook called | callback parameters |
+| :-- | :-- | :-- |
+| `preAction`, `postAction` |  before/after action handler for this command and its nested subcommands |   `(thisCommand, actionCommand)` |
+| `preSubcommand` | before parsing direct subcommand  | `(thisCommand, subcommand)` |
 
 ## Automated help
 

Readme_zh-CN.md

@@ -696,10 +696,10 @@ program
 
 支持的事件有：
 
-- `preAction`：在本命令或其子命令的处理函数执行前
-- `postAction`：在本命令或其子命令的处理函数执行后
-
-钩子函数的参数为添加上钩子的命令，及实际执行的命令。
+| 事件名称 | 触发时机 | 参数列表 |
+| :-- | :-- | :-- |
+| `preAction`, `postAction` | 本命令或其子命令的处理函数执行前/后 |   `(thisCommand, actionCommand)` |
+| `preSubcommand` | 在其直接子命令解析之前调用  | `(thisCommand, subcommand)` |
 
 ## 自动化帮助信息
 

esm.mjs

@@ -8,6 +8,7 @@ export const {
   createOption,
   CommanderError,
   InvalidArgumentError,
+  InvalidOptionArgumentError, // deprecated old name
   Command,
   Argument,
   Option,

examples/hook.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 // const commander = require('commander'); // (normal include)
-const commander = require('../'); // include commander in git clone of commander repo
-const program = new commander.Command();
+const { Command, Option } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
 
 // This example shows using some hooks for life cycle events.
 
 const timeLabel = 'command duration';
 program
-  .option('-p, --profile', 'show how long command takes')
+  .option('--profile', 'show how long command takes')
   .hook('preAction', (thisCommand) => {
     if (thisCommand.opts().profile) {
       console.time(timeLabel);
@@ -21,7 +21,7 @@ program
   });
 
 program
-  .option('-t, --trace', 'display trace statements for commands')
+  .option('--trace', 'display trace statements for commands')
   .hook('preAction', (thisCommand, actionCommand) => {
     if (thisCommand.opts().trace) {
       console.log('>>>>');
@@ -32,25 +32,34 @@ program
     }
   });
 
-program.command('delay')
-  .option('--message <value>', 'custom message to display', 'Thanks for waiting')
-  .argument('[seconds]', 'how long to delay', '1')
-  .action(async(waitSeconds, options) => {
-    await new Promise(resolve => setTimeout(resolve, parseInt(waitSeconds) * 1000));
-    console.log(options.message);
+program
+  .option('--env <filename>', 'specify environment file')
+  .hook('preSubcommand', (thisCommand, subcommand) => {
+    if (thisCommand.opts().env) {
+      // One use case for this hook is modifying environment variables before
+      // parsing the subcommand, say by reading .env file.
+      console.log(`Reading ${thisCommand.opts().env}...`);
+      process.env.PORT = 80;
+      console.log(`About to call subcommand: ${subcommand.name()}`);
+    }
   });
 
-program.command('hello')
-  .option('-e, --example')
-  .action(() => console.log('Hello, world'));
+program.command('start')
+  .argument('[script]', 'script name', 'server.js')
+  .option('-d, --delay <seconds>', 'how long to delay before starting')
+  .addOption(new Option('-p, --port <number>', 'port number').default(8080).env('PORT'))
+  .action(async(script, options) => {
+    if (options.delay) {
+      await new Promise(resolve => setTimeout(resolve, parseInt(options.delay) * 1000));
+    }
+    console.log(`Starting ${script} on port ${options.port}`);
+  });
 
 // Some of the hooks or actions are async, so call parseAsync rather than parse.
 program.parseAsync().then(() => {});
 
 // Try the following:
-//    node hook.js hello
-//    node hook.js --profile hello
-//    node hook.js --trace hello --example
-//    node hook.js delay
-//    node hook.js --trace delay 5 --message bye
-//    node hook.js --profile delay
+//    node hook.js start
+//    node hook.js --trace start --port 9000 test.js
+//    node hook.js --profile start --delay 5
+//    node hook.js --env=production.env start

lib/command.js

@@ -399,7 +399,7 @@ class Command extends EventEmitter {
    */
 
   hook(event, listener) {
-    const allowedValues = ['preAction', 'postAction'];
+    const allowedValues = ['preSubcommand', 'preAction', 'postAction'];
     if (!allowedValues.includes(event)) {
       throw new Error(`Unexpected value for event passed to hook : '${event}'.
 Expecting one of '${allowedValues.join("', '")}'`);
@@ -1054,11 +1054,16 @@ Expecting one of '${allowedValues.join("', '")}'`);
     const subCommand = this._findCommand(commandName);
     if (!subCommand) this.help({ error: true });
 
-    if (subCommand._executableHandler) {
-      this._executeSubCommand(subCommand, operands.concat(unknown));
-    } else {
-      return subCommand._parseCommand(operands, unknown);
-    }
+    let hookResult;
+    hookResult = this._chainOrCallSubCommandHook(hookResult, subCommand, 'preSubcommand');
+    hookResult = this._chainOrCall(hookResult, () => {
+      if (subCommand._executableHandler) {
+        this._executeSubCommand(subCommand, operands.concat(unknown));
+      } else {
+        return subCommand._parseCommand(operands, unknown);
+      }
+    });
+    return hookResult;
   }
 
   /**
@@ -1185,6 +1190,27 @@ Expecting one of '${allowedValues.join("', '")}'`);
     return result;
   }
 
+  /**
+   *
+   * @param {Promise|undefined} promise
+   * @param {Command} subCommand
+   * @param {string} event
+   * @return {Promise|undefined}
+   * @api private
+   */
+
+  _chainOrCallSubCommandHook(promise, subCommand, event) {
+    let result = promise;
+    if (this._lifeCycleHooks[event] !== undefined) {
+      this._lifeCycleHooks[event].forEach((hook) => {
+        result = this._chainOrCall(result, () => {
+          return hook(this, subCommand);
+        });
+      });
+    }
+    return result;
+  }
+
   /**
    * Process arguments in context of this command.
    * Returns action result, in case it is a promise.