chore: ensure that usage text in README files is up-to-date MONGOSH-741 (#1982)

* chore: ensure that usage text in README files is up-to-date MONGOSH-741

* fixup: first run of `npm run update-cli-usage-text packages/*/*.md *.md`

Author: addaleax

.github/workflows/cron-tasks.yml

@@ -66,6 +66,12 @@ jobs:
           git add .evergreen.yml
           git commit --no-allow-empty -m "chore: update evergreen config" || true
 
+      - name: Regenerate CLI usage text in README files
+        run: |
+          npm run update-cli-usage-text packages/*/*.md *.md
+          git add packages/*/*.md *.md
+          git commit --no-allow-empty -m "chore: update CLI usage text" || true
+
       - name: Create pull request
         id: cpr
         uses: peter-evans/create-pull-request@v6

README.md

@@ -23,6 +23,9 @@ variable. For detailed instructions for each of our supported platforms, please
 [installation documentation](https://docs.mongodb.com/mongodb-shell/install#mdb-shell-install).
 
 ## CLI Usage
+
+<!-- AUTOMATICALLY_INSERT_CLI_USAGE -->
+
 ```shell
   $ mongosh [options] [db address] [file names (ending in .js or .mongodb)]
 
@@ -49,6 +52,9 @@ variable. For detailed instructions for each of our supported platforms, please
         --authenticationDatabase [arg]         User source (defaults to dbname)
         --authenticationMechanism [arg]        Authentication mechanism
         --awsIamSessionToken [arg]             AWS IAM Temporary Session Token ID
+        --gssapiServiceName [arg]              Service name to use when authenticating using GSSAPI/Kerberos
+        --sspiHostnameCanonicalization [arg]   Specify the SSPI hostname canonicalization (none or forward, available on Windows)
+        --sspiRealmOverride [arg]              Specify the SSPI server realm (available on Windows)
 
   TLS Options:
 
@@ -97,6 +103,8 @@ variable. For detailed instructions for each of our supported platforms, please
   For more information on usage: https://docs.mongodb.com/mongodb-shell.
 ```
 
+<!-- /AUTOMATICALLY_INSERT_CLI_USAGE -->
+
 ## Local Development
 
 ### Requirements

package.json

@@ -52,6 +52,7 @@
     "update-third-party-notices": "mongodb-sbom-tools generate-3rd-party-notices --product='mongosh' --dependencies=.sbom/dependencies.json > THIRD_PARTY_NOTICES.md",
     "update-node-js-versions": "npx @pkgjs/nv ls v20 > .evergreen/node-20-latest.json && npx @pkgjs/nv ls v16 > .evergreen/node-16-latest.json",
     "update-evergreen-config": "npm run test-evergreen-expansions && node .evergreen/generate-evergreen-yml.js .evergreen/evergreen.yml.in > .evergreen.yml",
+    "update-cli-usage-text": "node scripts/update-cli-usage-text.js",
     "mark-ci-required-optional-dependencies": "ts-node scripts/mark-ci-required-optional-dependencies.ts",
     "write-node-js-dep": "node scripts/write-nodejs-dep > .sbom/node-js-dep.json",
     "scan-node-js": "mongodb-sbom-tools scan-node-js --version=$NODE_JS_VERSION > .sbom/node-js-vuln.json",

packages/cli-repl/README.md

@@ -9,6 +9,8 @@ of mongosh, visit https://www.mongodb.com/try/download/shell.
 
 ## Usage
 
+<!-- AUTOMATICALLY_INSERT_CLI_USAGE -->
+
 ```shell
   $ mongosh [options] [db address] [file names (ending in .js or .mongodb)]
 
@@ -35,6 +37,9 @@ of mongosh, visit https://www.mongodb.com/try/download/shell.
         --authenticationDatabase [arg]         User source (defaults to dbname)
         --authenticationMechanism [arg]        Authentication mechanism
         --awsIamSessionToken [arg]             AWS IAM Temporary Session Token ID
+        --gssapiServiceName [arg]              Service name to use when authenticating using GSSAPI/Kerberos
+        --sspiHostnameCanonicalization [arg]   Specify the SSPI hostname canonicalization (none or forward, available on Windows)
+        --sspiRealmOverride [arg]              Specify the SSPI server realm (available on Windows)
 
   TLS Options:
 
@@ -45,6 +50,7 @@ of mongosh, visit https://www.mongodb.com/try/download/shell.
         --tlsAllowInvalidHostnames             Allow connections to servers with non-matching hostnames
         --tlsAllowInvalidCertificates          Allow connections to servers with invalid certificates
         --tlsCertificateSelector [arg]         TLS Certificate in system store (Windows and macOS only)
+        --tlsCRLFile [arg]                     Specifies the .pem file that contains the Certificate Revocation List
         --tlsDisabledProtocols [arg]           Comma separated list of TLS protocols to disable [TLS1_0,TLS1_1,TLS1_2]
         --tlsUseSystemCA                       Load the operating system trusted certificate list
         --tlsFIPSMode                          Enable the system TLS library's FIPS mode
@@ -80,9 +86,10 @@ of mongosh, visit https://www.mongodb.com/try/download/shell.
         $ mongosh mongodb://192.168.0.5:9999/ships
 
   For more information on usage: https://docs.mongodb.com/mongodb-shell.
-
 ```
 
+<!-- /AUTOMATICALLY_INSERT_CLI_USAGE -->
+
 ### Log Format
 
 CLI REPL listens to a few events via a message bus that are then logged to

packages/mongosh/README.md

@@ -8,3 +8,88 @@ npm i -g mongosh
 
 This package is a convenience distribution of mongosh. To download a fully supported version
 of mongosh, visit https://www.mongodb.com/try/download/shell.
+
+## Usage
+
+## CLI Usage
+
+<!-- AUTOMATICALLY_INSERT_CLI_USAGE -->
+
+```shell
+  $ mongosh [options] [db address] [file names (ending in .js or .mongodb)]
+
+  Options:
+
+    -h, --help                                 Show this usage information
+    -f, --file [arg]                           Load the specified mongosh script
+        --host [arg]                           Server to connect to
+        --port [arg]                           Port to connect to
+        --build-info                           Show build information
+        --version                              Show version information
+        --quiet                                Silence output from the shell during the connection process
+        --shell                                Run the shell after executing files
+        --nodb                                 Don't connect to mongod on startup - no 'db address' [arg] expected
+        --norc                                 Will not run the '.mongoshrc.js' file on start up
+        --eval [arg]                           Evaluate javascript
+        --json[=canonical|relaxed]             Print result of --eval as Extended JSON, including errors
+        --retryWrites[=true|false]             Automatically retry write operations upon transient network errors (Default: true)
+
+  Authentication Options:
+
+    -u, --username [arg]                       Username for authentication
+    -p, --password [arg]                       Password for authentication
+        --authenticationDatabase [arg]         User source (defaults to dbname)
+        --authenticationMechanism [arg]        Authentication mechanism
+        --awsIamSessionToken [arg]             AWS IAM Temporary Session Token ID
+        --gssapiServiceName [arg]              Service name to use when authenticating using GSSAPI/Kerberos
+        --sspiHostnameCanonicalization [arg]   Specify the SSPI hostname canonicalization (none or forward, available on Windows)
+        --sspiRealmOverride [arg]              Specify the SSPI server realm (available on Windows)
+
+  TLS Options:
+
+        --tls                                  Use TLS for all connections
+        --tlsCertificateKeyFile [arg]          PEM certificate/key file for TLS
+        --tlsCertificateKeyFilePassword [arg]  Password for key in PEM file for TLS
+        --tlsCAFile [arg]                      Certificate Authority file for TLS
+        --tlsAllowInvalidHostnames             Allow connections to servers with non-matching hostnames
+        --tlsAllowInvalidCertificates          Allow connections to servers with invalid certificates
+        --tlsCertificateSelector [arg]         TLS Certificate in system store (Windows and macOS only)
+        --tlsCRLFile [arg]                     Specifies the .pem file that contains the Certificate Revocation List
+        --tlsDisabledProtocols [arg]           Comma separated list of TLS protocols to disable [TLS1_0,TLS1_1,TLS1_2]
+        --tlsUseSystemCA                       Load the operating system trusted certificate list
+        --tlsFIPSMode                          Enable the system TLS library's FIPS mode
+
+  API version options:
+
+        --apiVersion [arg]                     Specifies the API version to connect with
+        --apiStrict                            Use strict API version mode
+        --apiDeprecationErrors                 Fail deprecated commands for the specified API version
+
+  FLE Options:
+
+        --awsAccessKeyId [arg]                 AWS Access Key for FLE Amazon KMS
+        --awsSecretAccessKey [arg]             AWS Secret Key for FLE Amazon KMS
+        --awsSessionToken [arg]                Optional AWS Session Token ID
+        --keyVaultNamespace [arg]              database.collection to store encrypted FLE parameters
+        --kmsURL [arg]                         Test parameter to override the URL of the KMS endpoint
+
+  DB Address Examples:
+
+        foo                                    Foo database on local machine
+        192.168.0.5/foo                        Foo database on 192.168.0.5 machine
+        192.168.0.5:9999/foo                   Foo database on 192.168.0.5 machine on port 9999
+        mongodb://192.168.0.5:9999/foo         Connection string URI can also be used
+
+  File Names:
+
+        A list of files to run. Files must end in .js and will exit after unless --shell is specified.
+
+  Examples:
+
+        Start mongosh using 'ships' database on specified connection string:
+        $ mongosh mongodb://192.168.0.5:9999/ships
+
+  For more information on usage: https://docs.mongodb.com/mongodb-shell.
+```
+
+<!-- /AUTOMATICALLY_INSERT_CLI_USAGE -->

scripts/update-cli-usage-text.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const child_process = require('child_process');
+
+const usage = child_process.execFileSync(process.execPath, [path.resolve(__dirname, '..', 'packages', 'cli-repl', 'bin', 'mongosh.js'), '--help'],
+{encoding: 'utf8'})
+
+for (const file of process.argv.slice(2)) {
+  let contents = fs.readFileSync(file, 'utf8');
+  contents = contents.replaceAll(/(<!--\s*AUTOMATICALLY_INSERT_CLI_USAGE\s*-->).*(<!--\s*\/AUTOMATICALLY_INSERT_CLI_USAGE\s*-->)/gs,
+    (_match, p1, p2) => `${p1}\n\n\`\`\`shell${usage}\`\`\`\n\n${p2}`);
+  fs.writeFileSync(file, contents);
+}