brXM Upgrade Tool

AI-powered CLI tool for Bloomreach Experience Manager (brXM) version upgrades.

Overview

The brXM Upgrade Tool simplifies version upgrades by:

• Analyzing your project to understand its structure and customizations
• Planning upgrades based on version-specific manifests
• Executing transformations with AI assistance
• Guiding you through manual steps when needed

Installation

Via npx (recommended)

The package is published publicly on npmjs.com — no authentication or registry configuration required. Run from any brXM project directory:

npx @bloomreach/brxm-upgrade discover
npx @bloomreach/brxm-upgrade plan

To force a fresh fetch (bypass npx cache):

npx --yes @bloomreach/brxm-upgrade@latest <command>

MCP Server (Claude Code integration)

Add to your .mcp.json:

{
  "mcpServers": {
    "brxm-upgrade": {
      "command": "npx",
      "args": ["-p", "@bloomreach/brxm-upgrade", "brxm-upgrade-mcp"]
    }
  }
}

From source

cd tools/brxm-upgrade
npm install
npm run build

Quick Start

# Navigate to your brXM project root
cd /path/to/your/brxm-project

# Check tool information
brxm-upgrade info

# Analyze your project
brxm-upgrade discover

# Generate upgrade plan
brxm-upgrade plan --to 16.3

# Execute the upgrade
brxm-upgrade execute

Configuration

Create a .brxmrc file in your project root or home directory:

ai:
  provider: anthropic
  model: claude-sonnet-4-20250514
  apiKeyEnv: ANTHROPIC_API_KEY

upgrade:
  source: bundled

output:
  verbose: false
  color: true
  exportPath: ./.brxm-upgrade

See fixtures/.brxmrc.example.yaml for a complete example.

Supported AI Providers

The tool supports multiple AI providers (BYOK - Bring Your Own Key):

| Provider | Environment Variable | Default Model | |----------|---------------------|---------------| | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-20250514 | | OpenAI | OPENAI_API_KEY | gpt-4-turbo | | Google | GOOGLE_AI_API_KEY | gemini-pro |

Commands

| Command | Description | Status | |---------|-------------|--------| | info | Display tool information | Available | | discover | Analyze project structure | Available | | plan | Generate upgrade plan | Available | | execute | Execute upgrade steps | Available | | log-change | Create manifest entries | Available | | finalize | Promote unreleased manifest to versioned release | Available | | export | Export for manual AI use | Available |

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Lint code
npm run lint

License

Apache-2.0 - See LICENSE file for details.