$ xdbr

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

📋 Commands Overview

Quick reference for all available XDBR tools and commands:

Setup & Configuration

Development Tools

Code Quality

Codehealth

Codehealth is an app that evaluates your codebase and provides a score along with enhancement suggestions. It uses GenAI to enable a holistic analysis.

Testing Frameworks

[!TIP] New to XDBR? Start with xdbr setup ghpat to configure your GitHub access, then explore the tools you need for your project.

Table of Contents

• Commands Overview
• 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 setup 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 setup ghpat

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

xdbr setup 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 setup npmrc

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

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

# Update or create a global .npmrc with minimal output
npx xdbr setup npmrc --quiet

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 add cursor-rules

Automates the setup of BCG's standardized Cursor AI coding rules and configurations. This command clones the @bcgx-build/cursor-rules repository and copies the .cursor folder to your current project, providing developers with consistent AI coding assistance across all BCG projects.

# Set up Cursor AI rules in the current directory
npx xdbr add cursor-rules

[!NOTE] This command requires a GitHub Personal Access Token (GHPAT) with access to the @bcgx-build/cursor-rules repository. Run npx xdbr setup ghpat first if you haven't configured your token.

The command will:

• Clone the latest cursor-rules repository temporarily
• Copy the .cursor configuration folder to your project
• Clean up temporary files automatically
• Overwrite existing configurations to ensure you have the latest standards
• This command will not overwrite or delete custom rules outside of the default @bcgx-build/cursor-rules rules

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 add eslint [destPath]

Install eslint linter tool and copies configurations, for more customization check the congiguration documentation

# Install eslint
npx xdbr add eslint

# Install eslint and copies configuration on `destPath`
npx xdbr add eslint [destPath]

After installation you can use eslint with:

# Run eslint checks
npx eslint .

# Run eslint checks and fixes it if possible
npx eslint . --fix

xdbr add prettier [destPath]

Install prettier code styling tool and copies configurations, for more customization check the congiguration documentation.

The -e/--with-eslint flag integrates prettier with eslint, more information here.

# Install prettier
npx xdbr add prettier

# Install prettier and copies configuration on `destPath`
npx xdbr add prettier [destPath]

# Install prettier and integrates with eslint
npx xdbr add prettier --with-eslint

After installation you can use prettier by running:

# Run prettier checks
npx prettier [pathPattern] --check

# Run prettier checks and fixes it if possible
npx prettier [pathPattern] --write

xdbr add husky [destPath]

Install husky and lint-staged pre-commit tools.

# Install husky
npx xdbr add husky

# Install husky and copies configuration on `destPath`
npx xdbr add husky [destPath]

Husky automatically runs tests and linter tools to check if there's any issues on the staged files before committing.

[!WARNING] If you are using yarn, lint-staged will not be installed, you'll need to git commit <pathPattern> --amend --no-edit any files husky has changed during linter execution.

Codehealth Monitor

Codehealth Monitor is an internal app that uses Generative AI to evaluate qualitative code standards.

xdbr run codehealth

This command runs Codehealth Monitor using Docker Compose. If the repository is not cloned or you use --dest or --force, it will clone it first. The default path is os.homedir/codehealth-dir/.

# Run Codehealth Monitor
npx xdbr run codehealth

# Run and clone to a specific destination if not already present
npx xdbr run codehealth -d <destPath>

# Force re-clone and run, even if the directory is not empty
npx xdbr run codehealth -f

# Run quietly (minimal output)
npx xdbr run codehealth -q

xdbr add codehealth

This command clones the bcgx-build/code-health-monitor repository. The default path is os.homedir/codehealth-dir/.

# Clones Codehealth
npx xdbr add codehealth

# Clones Codehealth inside the destPath/app
npx xdbr add codehealth -d <destPath>

# Clones Codehealth and fill the OPENAI_API_KEY into .env
npx xdbr add codehealth -k <OpenAIKey>

# Clones Codehealth and set GitHub OAuth Client ID
npx xdbr add codehealth -c <githubClientId>

# Clones Codehealth and set GitHub OAuth Client Secret
npx xdbr add codehealth -s <githubSecret>

# Clones Codehealth without showing prompts and messages
npx xdbr add codehealth -q

# Remove everything inside the destination directory, then clone Codehealth
npx xdbr add codehealth -f

xdbr set codehealth-path

This command sets the path to your local bcgx-build/code-health-monitor installation. It is required for other Codehealth commands to work (except add).

# Set the path to your codehealth directory
npx xdbr set codehealth-path <path/to/codehealth>

xdbr set codehealth-env

This command sets or updates an environment variable in the .env file of your Codehealth installation.

# Prompt for the inputs and set an enviroment variable in codehealth's .env
npx xdbr set codehealth-env

# Set an environment variable in codehealth's .env
npx xdbr set codehealth-env <ENV_NAME> <ENV_VALUE>

# Set an environment variable quietly (no output)
npx xdbr set codehealth-env <ENV_NAME> <ENV_VALUE> -q

xdbr stop codehealth

This command stops the running Codehealth Monitor Docker containers.

# Stop Codehealth Monitor
npx xdbr stop codehealth

# Stop quietly (minimal output)
npx xdbr stop codehealth -q

xdbr setup code-quality

Setup code quality tools (e.g. linters, pre-commit hooks) interactively

npx xdbr setup code-quality

xdbr help [command]

Displays help information for a specific command.

# Display general help
npx xdbr help add

# Display help for command
npx xdbr help setup 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 clone 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
│   │   ├── cursor-rules.js  # Automates setup of BCG's Cursor AI coding rules and configurations
│   │   ├── 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 . setup npmrc
   • etc.

2. Using npm:

   • npm run xdbr help
   • npm run xdbr setup 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

Unit 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 # run vitest in watch mode with coverage
npm run test -- --coverage # run vitest once with coverage

Testing CLI interface locally

If you want to test the CLI interface without having to install xdbr, you can run:

node bin/cli.js <command>

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