@node-core/utils 4.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2017 node-core-utils contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# Node.js Core Utilities
+[![npm](https://img.shields.io/npm/v/node-core-utils.svg?style=flat-square)](https://npmjs.org/package/node-core-utils)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/nodejs/node-core-utils/nodejs.yml?branch=main&style=flat-square)](https://github.com/nodejs/node-core-utils/workflows/Node.js%20CI/badge.svg?branch=main)
+[![codecov](https://img.shields.io/codecov/c/github/nodejs/node-core-utils.svg?style=flat-square)](https://codecov.io/gh/nodejs/node-core-utils)
+[![Known Vulnerabilities](https://snyk.io/test/github/nodejs/node-core-utils/badge.svg?style=flat-square)](https://snyk.io/test/github/nodejs/node-core-utils)
+
+CLI tools for Node.js Core collaborators.
+
+<!-- TOC -->
+
+- [Tools](#tools)
+- [Usage](#usage)
+  - [Install](#install)
+  - [Setting up GitHub credentials](#setting-up-github-credentials)
+  - [Setting up Jenkins credentials](#setting-up-jenkins-credentials)
+  - [Make sure your credentials won't be committed](#make-sure-your-credentials-wont-be-committed)
+  - [Shell autocomplete](#shell-autocomplete)
+  - [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+<!-- /TOC -->
+
+## Tools
+
+- [`git-node`](./docs/git-node.md): Custom Git commands for working with Node.js
+  core, e.g. landing Pull Requests.
+- [`ncu-config`](./docs/ncu-config.md): Configure variables for node-core-utils
+  to use.
+- [`ncu-team`](./docs/ncu-team.md): Listing members of a team, synchronizing
+  special blocks in files with the list of members.
+- [`get-metadata`](./docs/get-metadata.md): Retrieving metadata for a Pull Request.
+  **DEPRECATED**: use [`git node metadata`](./docs/git-node.md#git-node-metadata)
+  instead.
+- [`ncu-ci`](./docs/ncu-ci.md): Parse the results of a Jenkins CI run and display a summary for all the failures.
+
+## Usage
+
+### Install
+
+```
+npm install -g @node-core/utils
+```
+
+If you would prefer to build from the source, install and link:
+
+```
+git clone git@github.com:nodejs/node-core-utils.git
+cd node-core-utils
+npm install
+npm link
+```
+
+### Setting up GitHub credentials
+
+Most of the tools need your GitHub credentials to work. You can either
+
+1. Run any of the tools and you will be asked in a prompt to provide your
+   username and password in order to create a personal access token.
+2. Or, create a personal access token yourself on GitHub, then set them up
+   using an editor.
+
+
+If you prefer option 2, [follow these instructions](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
+to create the token.
+
+When creating the token, the following boxes need to be checked:
+
+- `user:email`: Used by `git-node` and `get-metadata` to read the email of the
+  PR author in order to check if it matches the email of the commit author.
+- `read:org`: Used by `ncu-team` to read the list of team members.
+
+Optionally, if you want to grant write access so `git-node` can write comments:
+
+- `public_repo` (or `repo` if you intend to work with private repositories).
+
+You can also edit the permission of existing tokens later.
+
+After the token is generated, create an rc file with the following content:
+(`~/.ncurc` or `$XDG_CONFIG_HOME/ncurc`):
+
+```json
+{
+  "username": "your_github_username",
+  "token": "token_that_you_created"
+}
+```
+
+Note: you could use `ncu-config` to configure these variables, but it's not
+recommended to leave your tokens in your command line history.
+
+### Setting up Jenkins credentials
+
+The `git-node` and `ncu-ci` commands need to query the Node.js Jenkins API for
+CI results, so you'll need to configure the Jenkins API token before using
+these commands.
+
+To obtain the Jenkins API token
+
+1. Open
+   `https://ci.nodejs.org/user/<your-github-username>/configure` (replace
+   \<your-github-username\> with your own GitHub username).
+2. Click on the `ADD NEW TOKEN` button in the `API Token` section.
+3. Enter an identifiable name (for example, `node-core-utils`) for this
+   token in the inbox that appears, and click `GENERATE`.
+4. Copy the generated token.
+5. Add it into your `ncurc` file (`~/.ncurc` or `$XDG_CONFIG_HOME/ncurc`)
+   with `jenkins_token` as key, like this:
+
+   ```json
+   {
+     "username": "your_github_username",
+     "token": "your_github_token",
+     "jenkins_token": "your_jenkins_token"
+   }
+   ```
+
+
+### Make sure your credentials won't be committed
+
+Put the following entries into your
+[global `gitignore` file](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreexcludesFile)
+(`$XDG_CONFIG_HOME/git/ignore` or a file specified by `core.excludesFile`):
+
+```
+# node-core-utils configuration file
+.ncurc
+# node-core-utils working directory
+.ncu
+```
+
+Mind that `.ncu/land` could contain your access token since it contains the
+serialized configurations.
+
+If you ever accidentally commit your access token on GitHub, you can simply
+revoke that token and use a new one.
+
+### Shell autocomplete
+
+To add autocomplete just run `git-node completion` and follow the instructions.
+(same for the rest of the tools)
+
+### Troubleshooting
+
+If you encounter an error that you cannot fix by yourself, please
+
+1. Make sure you update NCU to the latest version
+2. Try again with the `NCU_VERBOSITY=debug` environment variable set and
+   open an issue at https://github.com/nodejs/node-core-utils/issues with
+   detailed logs.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/bin/get-metadata.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+
+import { runAsync } from '../lib/run.js';
+import { setVerbosityFromEnv } from '../lib/verbosity.js';
+
+setVerbosityFromEnv();
+
+const script = fileURLToPath(new URL('git-node.js', import.meta.url));
+runAsync(process.execPath, [script, 'metadata', ...process.argv.slice(2)]);

package/bin/git-node.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { readdirSync } from 'fs';
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import epilogue from '../components/git/epilogue.js';
+import { setVerbosityFromEnv } from '../lib/verbosity.js';
+
+setVerbosityFromEnv();
+
+const commandFiles = readdirSync(new URL('../components/git', import.meta.url))
+  .filter(file => file !== 'epilogue.js');
+
+function importCommand(commandFile) {
+  return import(new URL(`../components/git/${commandFile}`, import.meta.url));
+}
+
+Promise.all(commandFiles.map(importCommand)).then((commands) => {
+  const args = yargs(hideBin(process.argv));
+  commands.forEach(command => args.command(command));
+  args.command('help', false, () => {}, (yargs) => { yargs.showHelp(); })
+    .completion('completion')
+    .demandCommand(1)
+    .strict()
+    .epilogue(epilogue)
+    .help('help')
+    .parse();
+});