🍺 Implement Homebrew package manager support (macOS)

[loonghao]

Overview

Implement Homebrew package manager support for macOS system packages as part of the universal package management ecosystem.

Background

Homebrew is the most popular package manager for macOS, providing easy installation of command-line tools, applications, and libraries. It's essential for macOS development workflows.

Requirements

Core Functionality

• Implement HomebrewPackageManager struct that implements UniversalPackageManager trait
• Support basic brew commands:
  • brew install <package>
  • brew uninstall <package>
  • brew upgrade [package]
  • brew list
  • brew search <query>
  • brew info <package>

System Integration

• Register Homebrew in the System(macOS) ecosystem
• Handle both formulae (command-line tools) and casks (GUI applications)
• Support Homebrew services (brew services)
• Handle multiple Homebrew installations (Intel vs Apple Silicon)

Advanced Features

• Brewfile support for declarative package management
• Tap management (third-party repositories)
• Bundle support (brew bundle)
• Cleanup and maintenance commands

Command Examples

# Direct homebrew usage
vx brew install git
vx brew install --cask visual-studio-code
vx brew uninstall node
vx brew upgrade
vx brew services start postgresql

# System package management
vx pkg system install git
vx pkg system search python
vx pkg system list

# Auto-detection for system tools
vx pkg install git  # Uses brew on macOS if no project context

Technical Details

Package Manager Config

PackageManagerConfig {
    name: "brew",
    supports_lockfiles: false,  // Brewfile is optional
    supports_workspaces: false,
    isolation_level: IsolationLevel::Global,
    lock_file_name: "Brewfile",  // Optional
}

Platform Detection

• Detect macOS platform
• Handle Intel vs Apple Silicon differences
• Support custom Homebrew installation paths
• Detect Homebrew availability

Package Types

• Formulae: Command-line tools and libraries
• Casks: GUI applications and large binaries
• Services: Background services managed by launchd

Testing

• Unit tests for HomebrewPackageManager implementation
• Integration tests with real brew commands
• Formula and cask installation tests
• Service management tests
• Brewfile support tests
• Intel vs Apple Silicon compatibility tests
• Performance benchmarks

Documentation

• Add Homebrew examples to user documentation
• Document formula vs cask differences
• Update command reference
• Add troubleshooting guide for Homebrew issues
• Document Brewfile usage
• Service management documentation

Platform Considerations

macOS Specific

• Only available on macOS
• Different installation paths for Intel vs Apple Silicon
• Integration with macOS system services
• Xcode Command Line Tools dependency

Architecture Support

• Intel Macs: /usr/local/bin/brew
• Apple Silicon Macs: /opt/homebrew/bin/brew
• Handle both architectures gracefully

Permissions

• Homebrew typically doesn't require sudo
• Handle permission issues gracefully
• Provide clear error messages for permission problems

Integration Points

With vx Tool Management

• Coordinate with vx-managed tools (avoid conflicts)
• Provide option to use Homebrew for tool installation
• Handle cases where tools are available via both vx and Homebrew

With Project Detection

• Use Homebrew for system dependencies
• Integrate with project-specific tool requirements
• Support Brewfile in project roots

Acceptance Criteria

• All major Homebrew commands work through vx interface
• Both formulae and casks are supported
• Service management works correctly
• Works on both Intel and Apple Silicon Macs
• Brewfile support is functional
• Performance is comparable to direct brew usage
• Comprehensive test coverage
• Documentation is complete
• Error handling is robust

Related Issues

• Epic: 🏗️ [Epic] Universal Package Management Ecosystem Implementation #10
• Related: System package managers (Chocolatey, APT, etc.)
• Depends on: Universal package ecosystem architecture (completed)
• Blocks: Complete system package management support

---

Labels: enhancement, package-management, system, macos, homebrew
Milestone: Phase 3 - System Package Managers
Priority: High

[loonghao]

This feature has been implemented. Homebrew provider is fully available at crates/vx-providers/brew/ with complete provider.star and system_install() support. Closing as completed.