@npmcli/stafftools NPM

@npmcli/stafftools

The npm CLI Team's Internal Tools

Usage

npx -p @npmcli/stafftools <command> [...args]

Commands

`gh`

Run commands across all npm-cli repos on your local machine using working threads.

npx -p @npmcli/stafftools@latest gh <subcommand> [...args]

Note: The gh cli needs to be installed and authenticated.

Examples

Merge and publish all pending minor and patch release pull requests

npx -p @npmcli/stafftools@latest gh pending-release publish-release \
  --reject 'title: /\d+\.0\.0/' \ # Filter out PR titles matching \d.0.0 (major releases)
  --reject 'id: npm/cli' \ # Filter out npm itself
  --merge-strategy=rebase \ # Merge all PRs with rebase
  --otp=OP # Use the 1Password `op` cli to get one time passwords
  # OR specify an otp with --otp=XXXXXX

Queries

All the .mjs files in the queries dir return some sort of data from the GitHub api.

Each query is responsible for exporting:

default: a function that will return data of some shape
args: an object that will be passed to yargs to set the options
type: the type of data that this query returns. should be value or array of values from types.mjs

Any query can be run directly by name, or a custom query file can be passed in by path.

Without any other arguments, a query will print its data. A query --template option can be provided to change how the data is displayed. For example:

# Will return the result of the `repos` query
npx -p @npmcli/stafftools@latest gh repos

# Add --help to see what subcommands are available
npx -p @npmcli/stafftools@latest gh repos --help
# Commands:
#   npx -p @npmcli/stafftools@latest gh repos clone          Clone repos into a directory
#   npx -p @npmcli/stafftools@latest gh repos publish-repo   Publish repos from their default branch
#   npx -p @npmcli/stafftools@latest gh repos pull           Checkout and pull default branch of repos
#   npx -p @npmcli/stafftools@latest gh repos repo-settings  Set common settings on all repos

Workers

All the .mjs files in the workers dir operate on data returned from a query.

Each worker is reponsible for exporting:

default: an array of commands to run on the data
args: an object that will be passed to yargs to set the options
type: the type of data that this worker operates. should be a value or array of values from types.mjs or a string that is the name of a query or path to a query
success: a function that will display the success message for each item from the query. can be useful for displaying the url to a pull request, name of a repo, etc

Note that for type if a worker specifies an exact query by name, then the worker can be run as it's own top level command. For example:

# This worker exports `type = 'template-oss'` so it can
# be run as a single positional command
npx -p @npmcli/stafftools@latest gh template-oss-fix

# The above is equivalent to
npx -p @npmcli/stafftools@latest gh template-oss template-oss-fix