# 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.
[](https://github.com/tylerbutler/santa/actions)
[](https://codecov.io/gh/tylerbutler/santa)
[](https://opensource.org/licenses/MIT)
## 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
```bash
# Install from source (requires Rust)
cargo install --git https://github.com/tylerbutler/santa
# Or download pre-built binaries from releases
### Basic Usage
```bash
# 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
```yaml
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:
```bash
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`](https://github.com/casey/just) for development workflow automation. If you don't have `just` installed:
```bash
cargo install just
```
### Quick Start for Contributors
```bash
# 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
| `just` | Show all available commands |
| `just build` | Build debug binary |
| `just test` | Run all tests |
| `just lint` | Run clippy linting |
| `just check-all` | Run complete pre-commit checks |
| `just bench` | Run performance benchmarks |
| `just docs` | Generate and open documentation |
### Development Workflow
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
| **Homebrew** | macOS, Linux | ✅ Full Support |
| **Cargo** | All | ✅ Full Support |
| **APT** | Debian, Ubuntu | ✅ Full Support |
| **Pacman** | Arch Linux | ✅ Full Support |
| **AUR** | Arch Linux | ✅ Full Support |
| **Scoop** | Windows | ✅ Full Support |
| **Nix** | All | ✅ Full Support |
## 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
```bash
# 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**:
```bash
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:
```bash
# 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](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**