$ xdbr

A CLI tool for managing BCG X Delivery Brazil Inner Source. This tool simplifies tasks such as setting up a GitHub Personal Access Token, configuring .npmrc for internal packages, installing packages, etc.

Table of Contents

• Quickstart
• Global Installation
• Command Usage
• Differences between xdbr and xdc
• Contributing
  • Your first command
  • Project Structure
  • Libraries Used
  • Commit Guidelines
  • Running the Project Locally
  • Node Version
  • Tests
• License
• Authors

Quickstart

You can use xdbr directly with npx (no global install required):

npx xdbr [command]

[!NOTE] Node.js 20.15.0 or above is required as specified in the package.json.

Installing globally

Global installation is not necessary, but if you prefer, you can install the tool globally:

npm install -g xdbr

Then you can run:

xdbr [command]

Usage

General usage

# Using npx (no global installation)
npx xdbr [command]

# If installed globally
xdbr [command]

xdbr add ghpat

Add a GitHub Personal Access Token to your .xdbr config. This token will be used to set up .npmrc and to clone repositories from the bcgx-build organization.

npx xdbr add ghpat

The CLI will help you to create a GitHub Personal Access Token.

xdbr add npmrc [destPath] [--global, -g]

Create or update a .npmrc file with the X Delivery Brazil GitHub npm registry and auth token. You can optionally pass the destination path otherwise it will try to install in the current folder. If the flag --global is passed, the application will set up .npmrc globally.

# Update or create a .npmrc in the current directory
npx xdbr add npmrc

# Update or create a .npmrc in a specific directory
npx xdbr add npmrc path/to/project

# Update or create a global .npmrc in your user directory
npx xdbr add npmrc --global

xdbr add mui-theme [destPath]

Installs the @bcgx-build/mui-theme package using your project’s package manager. If destPath is provided, the command will use that path to install and configure the theme; otherwise, it will try to install in the current path.

# Install the mui-theme in the current directory
npx xdbr add mui-theme

# Install the mui-theme in a specific directory
npx xdbr add mui-theme path/to/project

xdbr copy mui-theme [destPath]

Copies the entire theme source into your project, rather than installing the @bcgx-build/mui-theme package. This is particularly useful when:

• You need to hand over the project to the client for maintenance.
• You are collaborating with external teams that cannot install private packages.

# Copy the mui-theme to the current directory
npx xdbr copy mui-theme

# Copy the mui-theme to a specified destination
npx xdbr copy mui-theme path/to/project

[!TIP] If installing via add mui-theme is an option, that is often simpler and keeps your theme updates centralized. Only use copy mui-theme if you absolutely need to maintain the theme code directly.

xdbr add playwright [destPath]

Installs Playwright and scaffolds a BCG-specific Page Object Model (POM) testing setup. This includes:

• An e2e/ test folder with structured pages/ and ui-tests/ directories.
• A basic test that navigates to bcg.com and asserts the page title.
• A pre-configured playwright.config.ts for running tests with Chromium.
• Automatic installation of browser dependencies using npx playwright install.

xdbr add cypress [destPath]

Installs Cypress and scaffolds tutorial test examples, which includes:

• A cypress/ test folder with structured e2e/, fixtures/ and support/ directories.
• A basic test that navigates to Cypress Example Project and asserts the documentation link.
• A pre-configured cypress.config.{ts,js} for running tests with Electron (or any browser installed on your machine).
• Automatic installation of browser dependencies using npx cypress install.
• add cypress command also auto-checks if you're using typescript on your project or alternatively, you can add --typescript / -t flag to force the typescript version of the setup.

# Set up Playwright in the current directory
npx xdbr add playwright

# Set up Playwright in a specific directory
npx xdbr add playwright path/to/project

After the installation is complete, you can run tests with

npx playwright test

# Or, if you want to have a dashboard to look at
npx playwright test --ui

xdbr add locust [destPath]

Installs the Locust load testing framework and scaffolds a Python-based test setup. This includes:

• A load-tests/ folder with a ready-to-use locustfile.py example.
• A README.md with instructions for running Locust.
• Automatic installation of Locust using uv (if available) or pip/pip3.

# Set up Locust in the current directory
npx xdbr add locust

# Set up Locust in a specific directory
npx xdbr add locust path/to/project

After the installation is complete, you can run Locust with:

# Start the Locust web UI
locust -f load-tests/locustfile.py --host=http://localhost:3000

# Or run headlessly
locust -f load-tests/locustfile.py --headless --users 10 --spawn-rate 1 --host=http://localhost:3000

[!NOTE] Requires Python and either uv or pip to be installed on your system.

xdbr help [command]

Displays help information for a specific command.

# Display general help
npx xdbr help add

# Display help for command
npx xdbr help add npmrc

Differences between xdbr and xdc

xdc stands for X Delivery Cookiecutter, a scaffolding tool that helps you kickstart new projects by prescribing best practices and providing productivity tools.

xdbr is named after X Delivery Brazil, making it easy to remember. It helps you manage inner source initiatives. Use this tool when you have an existing project and want to enhance it with inner source libraries or perform tasks such as setting up tests, linters, and static checkers.

Contributing

If you would like to contribute to this project, please fork the repository and submit a pull request. We welcome all contributions!

Project Structure

The project is organized as follows:

├── assets                   # Store any assets your commands may need
├── bin
│   └── cli.js               # CLI entry point - loads commands, parses arguments, and dispatches them
├── commands                 # CLI commands organized by folder structure
│   ├── add
│   │   ├── ghpat.js         # Adds a GitHub Personal Access Token to your .xdbr config
│   │   ├── mui-theme.js     # Installs the @bcgx-build/mui-theme package
│   │   ├── npmrc.js         # Creates or updates a .npmrc file with the GitHub npm registry from X Delivery Brazil
│   │   └── playwright.js    # Installs Playwright and scaffolds a test structure
│   ├── copy
│   │   └── mui-theme.js     # Copies the source code of mui-theme to a project
│   └── help.js              # Displays help information
├── tests                    # Test folder
└── utils                    # Helper functions
    ├── askBoolean.js        # Prompts a Y/N question to the user
    ├── askString.js         # Asks a question and returns a string response
    ├── getAssetsDir.js      # Gets the path for the assets directory
    ├── JSPackageManager.js  # Helper class for manipulating JavaScript package managers
    ├── readCommands.js      # Loads commands and is used by the entry point
    ├── readGHPAT.js         # Reads the saved GitHub Personal Access Token
    └── tokenPath.js         # Retrieves the token file path

Your first command

Creating a new command is simple. For example, if you want to create the command npx xdbr add hello, you should create a file at ./commands/add/hello.js with the following content:

import { Command } from 'commander';

const hello = new Command('hello') // Define the command to be called via the CLI.
  .summary('My cool new function.') // A short description for the general help.
  .description('My really cool new function.') // A detailed description for specific help.
  .action(() => {
    console.log('Hello World!'); // Execute your function logic here.
  });

export default { command: hello }; // Export an object containing your command.

Now you can run your command locally using:

npx . add hello

Libraries Used

commander.js

The main library used in this project is commander.js, which you will interact with to build your command.

Some commonly used methods include:

const myCommand = new Command('command-used-on-cli')

  // Required for displaying a brief description in the general help
  .summary('Short summary of the command')

  // Optional but recommended for more detailed help.
  .description('Detailed description explaining what the command does.')

  // Include only if you need mandatory arguments.
  .argument('<mandatoryArg>', 'This is a mandatory argument')

  // Include only if you need optional arguments.
  .argument('[optionalArg]', 'This is an optional argument')

  // Include only if you need mandatory options (flags).
  .requiredOption('-m, --mandatoryOption <value>', 'This is a mandatory option')

  // Include only if you need optional options (flags).
  .option('-o, --optionalOption [value]', 'This is an optional option')

  .action(() => {
    doSomething();
  });

fs

You'll also need the Node.js fs module for interacting with the file system. Here are some useful functions:

Importing the Module

import fs from 'fs';

Reading a File

fs.readFile('file.txt', 'utf8', (err, data) => {
  if (err) throw err;
  console.log(data);
});

Writing to a File

fs.writeFile('file.txt', 'Hello World!', err => {
  if (err) throw err;
  console.log('File written successfully.');
});

Copying a File

fs.copyFile('source.txt', 'destination.txt', err => {
  if (err) throw err;
  console.log('File copied.');
});

Creating a Directory

fs.mkdir('newDir', { recursive: true }, err => {
  if (err) throw err;
  console.log('Directory created.');
});

For a concise cheat sheet, refer to this gist.

Another library you'll use in conjunction with fs is path. Check the Node.js path documentation and the Node.js fs documentation.

Commit Guidelines

We use the semantic-release library to generate releases, versions, and changelogs. It is VERY important that commit messages follow the Angular Commit Message Conventions. Below is a cheat sheet:

• build: Changes that affect the build system or external dependencies (e.g., gulp, broccoli, npm).
• ci: Changes to our CI configuration files and scripts (e.g., Circle, BrowserStack, SauceLabs).
• docs: Documentation only changes.
• feat: A new feature.
• fix: A bug fix.
• perf: A code change that improves performance.
• refactor: A code change that neither fixes a bug nor adds a feature.
• style: Changes that do not affect the meaning of the code (e.g., white-space, formatting, missing semicolons).
• test: Adding missing tests or correcting existing tests.

Examples:

• feat: add command hello-world to print a cool message on the user screen
• fix: corrected the hello-world command not displaying the greeting on LCD screens
• docs: added a development section to the README
• ci: add a coverage report for PRs to the main branch
• test: improved test reliability for the npmrc command

Pre-Commit Configuration

We are using Husky for running pre-commit verification.

• Step 1: Run lint and prettier
• Step 2: Run tests
• Step 3: Verify commit lint format follows Commit Guidelines

Running the Project Locally

There are two ways to run the project locally:

1. Using npx:

   • npx . help
   • npx . add npmrc
   • etc.

2. Using npm:

   • npm run xdbr help
   • npm run xdbr add npmrc
   • etc.

Running with npx provides an environment closer to the published version, though it might be slower due to execution delays. Running with npm is faster but may have some discrepancies with the published environment.

Node Version

We standardize on the latest LTS version for development: v22.14.0.

Tests

The project uses Vitest for testing. It maintains 100% test coverage, and we aim to keep this as high as possible.

To run tests:

npm run test

To check coverage:

npm run coverage

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Authors

• Silvio Paganini - paganini.silvio@bcg.com
• Guilherme Mori - mori.guilherme@bcg.com
• Júlia Souza - souza.julia@bcg.com
• Caue Melo - melo.caue@bcg.com
• Samuel Oh - oh.samuel@bcg.com
• Mauricio de Souza - souza.mauricio@bcg.com
• Gustavo Teruya 🥔 - teruya.gustavo@bcg.com