From 274459499712043e6aa2f9d1e34a05c396365e93 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Mon, 6 May 2024 11:13:38 +0200 Subject: [PATCH 1/2] chore: ensure that usage text in README files is up-to-date MONGOSH-741 --- .github/workflows/cron-tasks.yml | 6 ++++++ README.md | 3 +++ package.json | 1 + packages/cli-repl/README.md | 4 ++++ packages/mongosh/README.md | 7 +++++++ scripts/update-cli-usage-text.js | 15 +++++++++++++++ 6 files changed, 36 insertions(+) create mode 100755 scripts/update-cli-usage-text.js diff --git a/.github/workflows/cron-tasks.yml b/.github/workflows/cron-tasks.yml index d8960c4150..75f860ea93 100644 --- a/.github/workflows/cron-tasks.yml +++ b/.github/workflows/cron-tasks.yml @@ -63,6 +63,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 diff --git a/README.md b/README.md index d0b6d28dab..f7c04c903c 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ 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 + + ```shell $ mongosh [options] [db address] [file names (ending in .js or .mongodb)] @@ -96,6 +98,7 @@ variable. For detailed instructions for each of our supported platforms, please For more information on usage: https://docs.mongodb.com/mongodb-shell. ``` + ## Local Development diff --git a/package.json b/package.json index 417637b843..1ac16fda94 100644 --- a/package.json +++ b/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", diff --git a/packages/cli-repl/README.md b/packages/cli-repl/README.md index 349ba67f0d..395d196ed9 100644 --- a/packages/cli-repl/README.md +++ b/packages/cli-repl/README.md @@ -9,6 +9,8 @@ of mongosh, visit https://www.mongodb.com/try/download/shell. ## Usage + + ```shell $ mongosh [options] [db address] [file names (ending in .js or .mongodb)] @@ -83,6 +85,8 @@ of mongosh, visit https://www.mongodb.com/try/download/shell. ``` + + ### Log Format CLI REPL listens to a few events via a message bus that are then logged to diff --git a/packages/mongosh/README.md b/packages/mongosh/README.md index ae836756e9..f81cc03df6 100644 --- a/packages/mongosh/README.md +++ b/packages/mongosh/README.md @@ -8,3 +8,10 @@ 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 + + + diff --git a/scripts/update-cli-usage-text.js b/scripts/update-cli-usage-text.js new file mode 100755 index 0000000000..c8e2232bf2 --- /dev/null +++ b/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(/().*()/gs, + (_match, p1, p2) => `${p1}\n\n\`\`\`shell${usage}\`\`\`\n\n${p2}`); + fs.writeFileSync(file, contents); +} From e45f4168af6da9bdd8f392ef635b305f26dccc17 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Mon, 6 May 2024 11:16:27 +0200 Subject: [PATCH 2/2] fixup: first run of `npm run update-cli-usage-text packages/*/*.md *.md` --- README.md | 5 +++ packages/cli-repl/README.md | 5 ++- packages/mongosh/README.md | 78 +++++++++++++++++++++++++++++++++++++ 3 files changed, 87 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f7c04c903c..036739f50c 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ variable. For detailed instructions for each of our supported platforms, please ## CLI Usage + ```shell $ mongosh [options] [db address] [file names (ending in .js or .mongodb)] @@ -51,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: @@ -98,6 +102,7 @@ variable. For detailed instructions for each of our supported platforms, please For more information on usage: https://docs.mongodb.com/mongodb-shell. ``` + ## Local Development diff --git a/packages/cli-repl/README.md b/packages/cli-repl/README.md index 395d196ed9..94d30e4219 100644 --- a/packages/cli-repl/README.md +++ b/packages/cli-repl/README.md @@ -37,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: @@ -47,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 @@ -82,7 +86,6 @@ 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. - ``` diff --git a/packages/mongosh/README.md b/packages/mongosh/README.md index f81cc03df6..6d71da411a 100644 --- a/packages/mongosh/README.md +++ b/packages/mongosh/README.md @@ -14,4 +14,82 @@ of mongosh, visit https://www.mongodb.com/try/download/shell. ## 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. +``` +