bumpr-cli-preview

v0.0.1

Published

6 months ago

Modern dependency update tool with 8 production-ready ecosystems and 47 in beta

0High
0Medium
0Low

dependency analysis lockfile updater npm docker github-actions python multi-ecosystem vulnerability-scanning monorepo enterprise

Bumpr

A local, lightweight universal dependency update tool with comprehensive ecosystem support

Current Status: Early development - 2 ecosystems with strong Alpha+ testing (PHP/Composer, npm), 8 additional ecosystems in various Alpha stages. See ecosystem maturity matrix for detailed audit results.

Features

Plan, execute and update dependencies locally in a nice CLI -- no PRs needed

🧠 Intelligent Planning: Generate strategic upgrade plans with smart dependency grouping
Multi-ecosystem support: 10+ implemented ecosystems with tested foundations
Private Registry / Auth Support: Authentication, proxy support, and private registry handling (Alpha+ for npm/PHP)
Monorepo support: Workspace detection and coordination across ecosystems
Strategic Grouping: Smart dependency grouping for efficient reviews and reduced risk

📦 Installation

Option 1: NPM Package (When Published)

# Install globally via npm (coming soon)
npm i -g bumpr-cli-preview

# Verify installation
bumpr --version

Option 2: Direct from Source

# Clone and build locally
git clone https://github.com/fossas/bumpr.git
cd bumpr
npm run build:prod
npm link

# Verify installation
bumpr --version

Option 3: Download Release

# Download from GitHub releases (coming soon)
curl -L https://github.com/fossas/bumpr/releases/latest/download/bumpr-cli -o bumpr
chmod +x bumpr
./bumpr --version

Usage

Quick Start

# Scan current directory for all dependencies
bumpr

# Scan specific directory
bumpr scan-all --path /path/to/project

# Show only updates (default behavior)
bumpr scan-all

# Show all dependencies including up-to-date
bumpr scan-all --all

🧠 Intelligent Upgrade Planning

Generate strategic upgrade plans that group updates intelligently and minimize risk:

# Generate upgrade plan (requires ANTHROPIC_API_KEY)
export ANTHROPIC_API_KEY=your-api-key
bumpr plan

# Interactive planning with feedback
bumpr plan --interactive

# Customize plan parameters
bumpr plan --max-prs 5 --model claude-opus-4-20250514

# Get plan in JSON format
bumpr plan --json

The plan command analyzes your dependencies and creates strategic upgrade groups:

Security & Critical Patches - Vulnerabilities and urgent fixes
Stability & Bug Fixes - Bug fixes and stability improvements
Ecosystem Updates - Tool updates and minor version bumps
Performance & Features - Performance improvements and new features

Individual Operations

# Extract dependencies from a manifest file
bumpr extract --path package.json
bumpr extract --path requirements.txt --json
bumpr extract --path Dockerfile --ecosystem docker

# Resolve available versions for a dependency
bumpr resolve express --ecosystem npm
bumpr resolve postgres --ecosystem docker
bumpr resolve actions/checkout --ecosystem github-actions

# Update specific dependency
bumpr update --path package.json --dependency express --version 4.18.2

# Update all dependencies (with confirmation)
bumpr update-all
bumpr update-all --dry-run  # Preview changes

Advanced Usage

# Performance tuning
bumpr scan-all --concurrency 20

# Filter by ecosystem
bumpr scan-all --ecosystem npm
bumpr update-all --ecosystem docker

# Configuration
bumpr init  # Create config file
bumpr help auth  # Authentication setup
bumpr help config  # Configuration options

# Output formats
bumpr scan-all --json  # Machine-readable output
bumpr scan-all --format decisions  # Detailed upgrade analysis
bumpr scan-all --format summary  # Concise summary only
bumpr scan-all --debug  # Detailed logging

⚙️ Configuration

Initialize Configuration

# Create default config file
bumpr init

# Create with specific format
bumpr init --format yaml
bumpr init --minimal

Configuration Example

{
  "discovery": {
    "ignorePaths": ["node_modules/**", "vendor/**"],
    "respectGitignore": true
  },
  "registryAuth": [
    {
      "registryType": "npm",
      "token": "${NPM_TOKEN}"
    }
  ],
  "updates": {
    "versionStrategy": "range",
    "grouping": {
      "enabled": true
    }
  }
}

Environment Variables

# Intelligent planning (required for `bumpr plan`)
export ANTHROPIC_API_KEY="your-anthropic-api-key"  # Advanced planning features

# Use ecosystem-native authentication (preferred)
export NPM_TOKEN="your-npm-token"            # Standard npm authentication
export PYPI_USERNAME="your-pypi-username"    # Standard PyPI authentication
export PYPI_PASSWORD="your-pypi-password"

# Global proxy configuration (use .bumprrc.json for complex setups)
export HTTP_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

See Authentication Guide for comprehensive setup.

📊 Output Examples

Default Scan Output

  ╭─────────────────────────────────────────╮
  │  👊 Bumpr - Modern Dependency Tool      │
  ╰─────────────────────────────────────────╯

✓ Scan complete: resolved 45 dependencies across 3 files in 2.3s

package.json (npm):
  ↑ [email protected] → 4.18.2
  ↑ [email protected] → 4.17.21
  ✓ [email protected] (up to date)

Dockerfile (docker):
  ↑ node@16-alpine → 22.9.0-alpine
  ↑ postgres@13 → 16.1

.github/workflows/ci.yml (github-actions):
  ↑ actions/checkout@v3 → v4.2.2
  ↑ actions/setup-node@v3 → v4.4.0

╭─────────────────────────────────────────────────╮
│  👊 Bumpr Summary & Results                     │
├─────────────────────────────────────────────────┤
│   Total dependencies: 45                        │
│   Files scanned: 3                              │
│   Updates available: 5                          │
│   ⚡ Updates ready to apply!                    │
╰─────────────────────────────────────────────────╯

Intelligent Upgrade Plan Output

╭────────────────────────────────────────────╮
│  👊 Bumpr Dependency Upgrade Plan          │
╰────────────────────────────────────────────╯

Summary:
Strategic upgrade plan covering 12 dependencies across 3 PRs. Prioritizes security fixes and stability improvements while grouping related packages for efficient review.

Statistics:
  Total updates available: 15
  Updates included in plan: 12
  Updates deferred: 3
  Number of PRs: 3

Pull Requests (in priority order):

🔴 PR 1: Security & Critical Patches (CRITICAL)
Description: Address security vulnerabilities and critical bug fixes that should be deployed immediately.

Dependencies:
  • [email protected] → 4.17.21 (npm) - Security patch for CVE-2021-23337
  • [email protected] → 4.17.3 (npm) - Critical security update
  • actions/checkout@v3 → v4.2.2 (github-actions) - Security improvements

Grouping rationale: All dependencies contain security fixes that should be prioritized
Testing notes: Run full security scan and integration tests

🟡 PR 2: Ecosystem Tools & Build Updates (MEDIUM)  
Description: Update development tools and build dependencies to latest stable versions.

Dependencies:
  • @types/[email protected] → 18.19.4 (npm) - TypeScript definitions update
  • [email protected] → 8.56.0 (npm) - ESLint rule engine updates
  • [email protected] → 3.1.1 (npm) - Code formatter major version

Grouping rationale: Development tools that can be updated together safely
Testing notes: Verify linting rules and code formatting consistency

🟢 PR 3: Runtime Dependencies (LOW)
Description: Minor and patch updates to runtime dependencies with low risk.

Dependencies:
  • [email protected] → 18.2.1 (npm) - React patch release
  • [email protected] → 13.5.6 (npm) - Next.js minor updates
  • node@18-alpine → 20.10.0-alpine (docker) - Node.js LTS update

Grouping rationale: Stable runtime updates with good compatibility
Testing notes: Run full test suite and check for deprecation warnings

Deferred Updates:
  ⏸ [email protected] → 5.3.0 - Major version with breaking changes requiring code updates
  ⏸ [email protected] → 19.0.0 - Major version not yet stable, wait for ecosystem adoption
  ⏸ [email protected] → 5.89.0 - Recent release, defer for stability assessment

Recommendations:
  1. Execute PRs in the order listed to minimize conflicts
  2. Test each PR independently before merging the next
  3. Monitor the deferred TypeScript 5.x update for future planning

JSON Output Structure

[
  {
    "file": "package.json",
    "ecosystem": "npm",
    "dependencies": [
      {
        "dependency": {
          "ecosystem": "npm",
          "dependencyName": "express",
          "declaredRange": "^4.17.1",
          "packageFile": "/path/to/package.json",
          "depType": "prod"
        },
        "availableVersions": [
          {
            "version": "4.18.2",
            "published": "2023-01-01T00:00:00Z"
          }
        ]
      }
    ]
  }
]

Decisions Output Format

Use --format decisions to get detailed upgrade analysis with strategy recommendations:

bumpr scan-all --format decisions

Example output:

📊 Upgrade Decision Analysis

Summary:
  Files: 3
  Dependencies: 45
  Update candidates: 7
  Ecosystems: npm, docker, github-actions

package.json (npm):

  [email protected]:
    → 4.17.2 (patch) [minimal-change, compatible-change] - low risk
      ✓ Bug fixes only
      ✓ No breaking changes
      ✓ 2.3M weekly downloads
    
    → 4.18.2 (minor) [compatible-change] - medium risk
      ⚠ New features added
      ✓ Backward compatible
      ✓ Well-tested release (6 months old)
    
    → 5.0.0 (major) [breaking-change, latest-stable] - high risk
      ⚠ Breaking changes
      ⚠ Migration required
      ℹ Performance improvements

  [email protected]:
    → 4.17.21 (patch) [minimal-change, security-only] - low risk
      🔒 Security patch (CVE-2021-xxxxx)
      ✓ Drop-in replacement
      ⚡ Recommended update

Dockerfile (docker):

  node@16-alpine:
    → 18.20.5-alpine (major) [lts-preferred] - medium risk
      ✓ Current LTS version
      ⚠ Node.js 16 → 18 migration
      ✓ Extended support until 2025
    
    → 22.9.0-alpine (major) [latest-stable] - high risk
      ⚠ Latest version
      ⚠ Not LTS
      ℹ Newest features

Risk Factors:
  ⚠ 2 major version updates available
  🔒 1 security update recommended
  ℹ Consider grouping: All GitHub Actions can be updated together

The decisions format provides:

Multiple upgrade paths for each dependency
Strategy alignment showing which strategies recommend each version
Risk assessment (low/medium/high) for each option
Detailed reasoning with pros/cons for each choice
Security indicators for patches fixing vulnerabilities
Grouping opportunities for coordinated updates

Development

Build & Test

# Development setup
npm install
npm run build

# Testing
npm test
npm run test:coverage
npm run benchmark

# Code quality
npm run lint
npm run typecheck
npm run format

Project Structure

src/
├── ecosystems/          # Ecosystem implementations
│   ├── php/              # Alpha+ (160 tests)
│   ├── npm/              # Alpha+ (126 tests)
│   ├── java/             # Alpha (gradle: 78, maven: 61 tests)
│   └── .../              # Alpha/Experimental ecosystems
├── resolvers/            # Version resolution logic
├── utils/                # Shared utilities
└── cli.ts                # CLI interface