Package Exports

baseguard
baseguard/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (baseguard) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

BaseGuard 🛡️

Never ship incompatible code again - Intelligent browser compatibility enforcement with AI-powered analysis and autonomous fixing.

What is BaseGuard?

BaseGuard is a comprehensive browser compatibility tool that prevents incompatible code from reaching production. It combines official Baseline data with AI-powered analysis and code fixing to ensure your web applications work across all target browsers.

Key Features

🔍 Universal Framework Support - Works with React, Vue, Svelte, vanilla JS/CSS, and more
🤖 Dual AI Coding Agents - Choose between Jules (GitHub repos) or Gemini 2.5 Pro (any files)
📊 Official Baseline Data - Uses web-features package for accurate compatibility checking
🔧 Intelligent Code Fixing - AI generates progressive enhancement and polyfill solutions
🪝 Git Integration - Automated pre-commit/pre-push hooks with violation blocking
📈 Graceful Degradation - Works offline and handles service failures intelligently
🎨 Beautiful CLI - Colorful terminal output with progress indicators and detailed reports

Installation

npm install -g baseguard

Requirements:

Node.js 18 or higher
Git (for automation features)
API keys for AI services (setup guide below)

Quick Start

1. Initialize BaseGuard in Your Project

cd your-project
base init

This will:

Create .baseguardrc.json configuration file
Set up browser compatibility targets
Guide you through API key setup
Optionally install git hooks for automation

2. Check for Compatibility Issues

# Check all supported files
base check

# Check specific files or patterns
base check --files "src/**/*.ts"

# Strict mode (exit with error if violations found)
base check --strict

3. Fix Issues with AI

# Interactive fixing with preview
base fix

# Automatic fixing (no prompts)
base fix --auto

# Analysis only (no code changes)
base fix --analyze-only

🚀 Getting Started with AI Services

BaseGuard offers two AI coding agents for fixing compatibility issues. You can choose the one that best fits your workflow:

Option 1: Gemini 2.5 Pro (Recommended for Most Users)

Best for: Any codebase, local development, uncommitted files

Setup Steps:

Get your Gemini API key:
- Go to Google AI Studio
- Sign in with your Google account
- Click "Get API key" in the left sidebar
- Click "Create API key" → "Create API key in new project"
- Copy your API key

Configure BaseGuard:

base config set-keys
# Follow the prompts to enter your Gemini API key

# Set Gemini as your primary coding agent
base config coding-agent --agent gemini

Advantages:

✅ Works with any files (GitHub, local, uncommitted)
✅ Immediate processing and results
✅ No repository requirements
✅ Grounded with real-time web search
✅ Perfect for local development

Option 2: Jules (Google's Autonomous Coding Agent)

Best for: GitHub repositories, autonomous cloud-based fixing

Setup Steps:

Get your Jules API key:
- Go to Jules Dashboard
- Sign in with your Google account
- Connect your GitHub account and authorize repositories
- Get your API key from the dashboard

Configure BaseGuard:

base config set-keys
# Follow the prompts to enter your Jules API key

# Set Jules as your primary coding agent
base config coding-agent --agent jules

Advantages:

✅ Autonomous operation in cloud VMs
✅ Full repository context understanding
✅ Asynchronous processing
❌ Requires GitHub repository
❌ Cannot work with local/uncommitted files

Dual Agent Setup (Recommended)

You can configure both agents and BaseGuard will automatically choose the best one:

base config set-keys
# Enter both Gemini and Jules API keys

base config coding-agent
# Choose your preferred primary agent
# BaseGuard will fallback to the other when needed

📋 Complete Command Reference

Core Commands

# Project initialization
base init                           # Interactive setup
base init --preset baseline-widely  # Use specific browser preset
base init --skip-hooks             # Skip git hook installation

# Compatibility checking
base check                          # Check all supported files
base check --strict                 # Exit with error if violations found
base check --files "src/**/*.ts"    # Check specific file patterns
base check --format json           # Output results as JSON
base check --offline                # Run without network requests

# AI-powered fixing
base fix                            # Interactive fixing with previews
base fix --auto                     # Apply all fixes automatically
base fix --analyze-only             # Only analyze, don't generate fixes
base fix --files "src/**/*.css"     # Fix specific file patterns

Configuration Management

# View configuration
base config show                    # Detailed configuration display
base config list                    # Quick configuration summary
base config list --format json     # Export configuration as JSON

# API key management
base config set-keys                # Interactive API key setup
base config coding-agent            # Manage coding agent selection
base config coding-agent --show     # Show current agent configuration
base config coding-agent --agent gemini  # Set specific agent

# Browser targets
base config targets --add "chrome 100"           # Add browser target
base config targets --remove chrome              # Remove browser targets
base config targets --preset baseline-widely    # Set browser preset

# Configuration maintenance
base config validate               # Check configuration for errors
base config recover                # Attempt automatic recovery
base config recover --backup       # Create backup before recovery

Git Automation

# Automation control
base automation enable              # Enable git hooks with setup wizard
base automation enable --trigger pre-push  # Enable with specific trigger
base automation disable            # Disable automation and remove hooks
base automation status             # Show detailed automation status
base automation configure          # Interactive automation setup

# Manual automation testing
base automation run --trigger pre-commit   # Test pre-commit behavior
base automation run --trigger pre-push     # Test pre-push behavior

System Management

# System health and diagnostics
base status                         # Show system health overview
base status --verbose               # Detailed system information
base status --services              # Check external service availability
base diagnostics                    # Run comprehensive system diagnostics

# Quick shortcuts
base add "firefox 90"              # Quick browser target addition
base remove safari                  # Quick browser target removal
base list                          # Quick configuration summary
base version                       # Show version information
base help [command]                # Get help for specific commands

🎯 Browser Compatibility Targets

BaseGuard supports flexible browser targeting strategies:

Preset Configurations

# Baseline Widely (Recommended)
# Features supported across browsers for 30+ months
base config targets --preset baseline-widely

# Baseline Newly  
# Recently available Baseline features (cutting-edge)
base config targets --preset baseline-newly

# Last 2 Years
# Browsers released in the last 2 years
base config targets --preset last-2-years

Custom Browser Targets

# Specific browser versions
base add "chrome 100"              # Chrome 100 and above
base add "firefox 90"              # Firefox 90 and above
base add "safari 15"               # Safari 15 and above

# Baseline keyword support
base add "chrome baseline"         # Chrome with Baseline support
base add "safari baseline"         # Safari with Baseline support

Example Configurations

Conservative (Maximum Compatibility):

{
  "targets": [
    "chrome 88",
    "firefox 78", 
    "safari 14",
    "edge 88"
  ]
}

Modern (Baseline Widely):

{
  "targets": [
    "chrome baseline",
    "firefox baseline",
    "safari baseline"
  ]
}

Cutting-edge (Latest Features):

{
  "targets": [
    "chrome 120",
    "firefox 120",
    "safari 17"
  ]
}

🔧 Git Integration & Automation

BaseGuard can automatically check your code before commits or pushes:

Setup Git Hooks

# Enable automation with interactive setup
base automation enable

# Choose your trigger:
# - pre-commit: Check before each commit (faster feedback)
# - pre-push: Check before each push (less frequent)

# Enable with specific settings
base automation enable --trigger pre-commit --auto-fix

Automation Features

Violation Detection: Automatically scans staged files (pre-commit) or all files (pre-push)
Commit Blocking: Prevents commits/pushes when violations are found
Auto-fixing: Optionally applies AI fixes automatically
Manual Override: Use git commit --no-verify to bypass when needed

Automation Workflow

Developer makes changes and runs git commit
BaseGuard hook triggers and scans the staged files
If violations found:
- Shows detailed violation report
- Blocks the commit
- Suggests running base fix to resolve issues
If no violations: Commit proceeds normally

🛠️ Advanced Usage

Environment Variables

# Performance tuning
export BASEGUARD_MAX_WORKERS=4      # Limit concurrent file processing
export BASEGUARD_MAX_FILES=1000     # Limit total files processed
export BASEGUARD_CACHE_SIZE=500     # Limit cache size

# Memory optimization
export NODE_OPTIONS="--max-old-space-size=512"  # Limit Node.js memory

CI/CD Integration

# In your CI pipeline
base check --strict --format junit > baseguard-results.xml

# Exit codes:
# 0 = No violations found
# 1 = Violations found (in strict mode)

Offline Development

BaseGuard works offline for baseline checking:

# Run in offline mode (no AI analysis)
base check --offline

# Baseline checking works without network
# AI features require internet connection

🔍 What BaseGuard Checks

BaseGuard analyzes your code for browser compatibility issues across:

Web Platform Features

CSS Properties & Selectors: Grid, Flexbox, custom properties, modern selectors
JavaScript APIs: Fetch, Promises, async/await, ES6+ features
HTML Elements & Attributes: Modern form inputs, semantic elements
Web APIs: Canvas, WebGL, WebRTC, WebAssembly, Service Workers

Framework Support

React/JSX: Ignores React-specific syntax, focuses on web platform usage
Vue: Analyzes <script> and <style> blocks for web platform features
Svelte: Extracts web platform usage from component files
Vanilla: Direct analysis of JS, CSS, and HTML files

Example Violations

// ❌ Will be flagged for older browsers
const data = await fetch('/api/data');
const result = data.json();

// ✅ BaseGuard can suggest fixes like:
const data = window.fetch ? 
  await fetch('/api/data') : 
  await fetchPolyfill('/api/data');

/* ❌ Will be flagged for older browsers */
.container {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
}

/* ✅ BaseGuard can suggest progressive enhancement */
.container {
  display: flex; /* Fallback */
  flex-wrap: wrap;
}

@supports (display: grid) {
  .container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  }
}

🚨 Troubleshooting

Common Issues

"No files found to check"

# Check your file pattern
base check --files "**/*.{js,ts,jsx,tsx}"

# Verify you're in the right directory
ls -la  # Should see your source files

"Configuration not found"

# Initialize BaseGuard in your project
base init

# Or recover corrupted configuration
base config recover

"API key invalid"

# Reconfigure your API keys
base config set-keys

# Verify your keys are correct:
# - Gemini: Should start with "AIza"
# - Jules: Get from jules.google.com dashboard

"Git hooks not working"

# Check automation status
base automation status

# Reinstall hooks
base automation disable
base automation enable

Getting Help

# System health check
base status --verbose

# Comprehensive diagnostics
base diagnostics

# Debug mode for detailed logging
base check --debug
base fix --debug

Support Resources

Documentation: GitHub Repository
Issues: Report bugs and request features
API Documentation:
- Gemini API
- Jules Documentation

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by the BaseGuard Team

Never ship incompatible code again! 🛡️