Santa 🎅

A modern, high-performance package manager meta-tool that works across platforms and package managers.

Santa helps you install and manage packages across multiple platforms and package managers with a single command. Whether you're switching between macOS, Linux, or Windows, Santa ensures your essential tools are always available.

Features

🚀 Performance

• 67-90% faster concurrent package operations via async subprocess execution
• Professional-grade caching with TTL and LRU eviction using the moka library
• Memory efficient with zero unnecessary allocations and smart string handling

🔧 Modern Architecture

• Zero unwrap() and todo!() in production code - comprehensive error handling
• Structured logging with configurable levels and tracing
• Strong typing with builder patterns and validation
• Cross-platform compatibility for Linux, macOS, and Windows

🌟 Advanced Features

• Configuration hot-reloading with file system watching
• Enhanced shell completions with intelligent suggestions for bash/zsh/fish
• Environment variable configuration with comprehensive SANTA_ prefix support
• Plugin system foundation for extensibility

🛡️ Quality & Security

• 144 comprehensive tests with >90% code coverage
• Security hardening with input sanitization and injection protection
• Supply chain security with dependency auditing
• Production-ready error handling and logging

Santa might be useful to you if...

...you regularly use tools that are not installed by default

You're a modern developer. You can get by with grep, sure, but you'd much prefer ripgrep. The problem is, it's not installed. So you're stuck installing it yourself -- using whatever package manager you have available.

Santa gives you one command to install the packages in your own "standard developer toolkit."

...you regularly use different computers running different operating systems or architectures

Isn't it annoying when you log into a machine and it doesn't have your preferred tools? Or your tool isn't installable using apt, but of course, you don't remember that... So you waste 10 minutes looking up where you can install it from.

Santa simplifies this workflow. Santa knows where your packages can be installed from and will install them from the best available source.

Quick Start

Installation

# Install from source (requires Rust)
cargo install --git https://github.com/tylerbutler/santa

# Or download pre-built binaries from releases
curl -L https://github.com/tylerbutler/santa/releases/latest/download/santa-linux-x64.tar.gz | tar xz

Basic Usage

# Show available packages and their status
santa status

# Install all configured packages  
santa install

# Show current configuration
santa config

# Generate shell completions
santa completions bash >> ~/.bashrc  # or zsh, fish

Configuration

Santa uses a YAML configuration file to determine what packages you want to install and the order of preference for package managers.

Configuration file location: ~/.config/santa/config.yaml

Basic Configuration

sources:
  - brew      # macOS/Linux package manager
  - cargo     # Rust package manager  
  - apt       # Debian/Ubuntu package manager
  - pacman    # Arch Linux package manager
  - scoop     # Windows package manager
  - nix       # Universal package manager

packages:
  - bat       # Better cat with syntax highlighting
  - ripgrep   # Better grep
  - fd        # Better find
  - exa       # Better ls
  - bottom    # Better top
  - git-delta # Better git diff
  - chezmoi   # Dotfile manager

Environment Variable Configuration

Override any configuration with environment variables:

export SANTA_SOURCES="brew,cargo,apt"
export SANTA_PACKAGES="git,rust,ripgrep"  
export SANTA_LOG_LEVEL="debug"
export SANTA_BUILTIN_ONLY="true"

Available Environment Variables:

• SANTA_LOG_LEVEL - Set log level (trace, debug, info, warn, error)
• SANTA_CONFIG_PATH - Override configuration file path
• SANTA_SOURCES - Override package sources (comma-separated)
• SANTA_PACKAGES - Override package list (comma-separated)
• SANTA_BUILTIN_ONLY - Use builtin configuration only (true/false)
• SANTA_CACHE_TTL_SECONDS - Set package cache TTL
• SANTA_CACHE_SIZE - Set maximum cache entries
• SANTA_VERBOSE - Set verbose logging level (0-3)
• SANTA_HOT_RELOAD - Enable configuration hot-reloading (true/false)

Development

Santa uses just for development workflow automation. If you don't have just installed:

cargo install just

Quick Start for Contributors

# Clone the repository
git clone https://github.com/tylerbutler/santa.git
cd santa

# Set up development environment (installs dev tools)
just setup

# Run quick development checks
just check-quick

# Run all tests
just test

# Run with hot reload during development
just dev

Essential Commands

Development Workflow

# Daily development
just check-quick    # Fast checks during development
just test-watch     # Run tests in watch mode
just dev           # Development server with hot reload

# Before committing
just check-all     # Complete pre-commit validation
just test-coverage # Generate coverage report

# Release preparation
just pre-release   # Full pre-release validation
just release-build # Build for all platforms

Testing

# Run all tests
just test

# Run with coverage
just test-coverage

# Run only unit tests
just test-unit

# Run only integration tests  
just test-integration

# Fast parallel testing
just test-fast

Benchmarking

# Run all benchmarks
just bench

# Run specific benchmarks
just bench-subprocess

# Save baseline for comparison
just bench-baseline my-feature

# Compare against baseline
just bench-compare my-feature

Code Quality

# Check code style
just check-style

# Auto-fix issues
just fix

# Security audit
just audit

# Check dependencies
just deps

# Supply chain security
just supply-chain

Documentation

# Generate docs
just docs

# Check docs for errors
just docs-check

# View shell completion help
just completions

# View environment variable help
just env-help

Architecture

Santa is built with modern Rust practices and professional-grade architecture:

Core Components

• Configuration System - YAML-based with environment variable overrides and hot-reloading
• Package Sources - Pluggable system supporting multiple package managers
• Async Operations - High-performance concurrent package checking and installation
• Caching Layer - Intelligent caching with TTL and memory management
• Plugin System - Extensible architecture for future enhancements

Supported Package Managers

Performance

Santa is designed for performance with measurable improvements:

• 67-90% faster package operations compared to sequential execution
• Professional caching reduces redundant package manager calls
• Async I/O for non-blocking operations
• Memory efficient with zero-copy string handling where possible

Benchmarks

# Run performance benchmarks
just bench

# Compare performance improvements
just bench-baseline original
# ... make changes ...
just bench-compare original

Contributing

We welcome contributions! Please see our development workflow above.

Development Setup

1. Install Rust (1.70+): https://rustup.rs/
2. Install Just: cargo install just
3. Clone and setup:

   git clone https://github.com/tylerbutler/santa.git
   cd santa
   just setup
   

Code Standards

• Zero unwrap() and todo!() in production code
• Comprehensive error handling with context
• Tests required for all new functionality
• Documentation required for public APIs
• Security-first approach to all changes

Pull Request Process

1. Run just check-all to ensure all checks pass
2. Add tests for any new functionality
3. Update documentation as needed
4. Submit PR with clear description

CI/CD

Santa uses GitHub Actions for continuous integration:

• Multi-platform testing (Linux, macOS, Windows)
• Comprehensive test suite with coverage reporting
• Security auditing and dependency checking
• Performance regression testing
• Automated releases with cross-platform binaries

Run the same checks locally:

# Run CI checks locally
just ci

# Platform-specific CI simulation
just ci-linux
just ci-macos  
just ci-windows

License

Licensed under the MIT License.

Acknowledgments

• Built with modern Rust ecosystem tools
• Inspired by cross-platform package management needs
• Thanks to all contributors and the open source community

Made with ❤️ by the Santa team