What Gets Upgraded

Homebrew

• Homebrew formulae and casks
• Safe packages upgraded automatically
• Major/minor version upgrades require confirmation
• Runs brew cleanup after upgrades

Conda

• Conda package manager itself
• Runs conda clean --all after upgrades

Python

• Automatically detects Python source (Conda, Homebrew, or System)
• Conda Python: Upgraded via conda update python
• Homebrew Python: Upgraded via brew upgrade python@3
• System Python: Not upgraded (macOS system Python should not be modified)
• Other sources (pyenv, asdf, etc.): Not supported
• Major version changes require confirmation
• Displays Python path and source for transparency

npm

• Global npm packages first
• npm itself upgraded last (as recommended)
• Runs npm cache verify after upgrades

Logs and Snapshots

All logs and snapshots are saved to ~/upgrade-logs/:

~/upgrade-logs/
├── upgrade_20250605_143022.log     # Detailed execution log
├── snapshot_20250605_143022.json   # Pre-upgrade system state
├── upgrade_20250605_151533.log
└── snapshot_20250605_151533.json

Snapshot Format

{
  "homebrew": {
    "version": "4.2.10",
    "outdated_count": 2,
    "outdated_packages": [...]
  },
  "conda": {
    "current": "25.9.1",
    "latest": "25.9.1"
  },
  "python": {
    "current": "3.12.12",
    "latest": "3.12.12"
  },
  "npm": {
    "current": "11.6.2",
    "latest": "11.6.2",
    "outdated_count": 0,
    "outdated_packages": []
  }
}

Manual Rollback

If you need to rollback to a previous version:

1. Check the snapshot file: cat ~/upgrade-logs/snapshot_<timestamp>.json
2. Manually reinstall the previous version:

# Homebrew
brew install <package>@<version>

# Conda
conda install conda=<version>

# Python
conda install python=<version>

# npm
npm install -g npm@<version>
npm install -g <package>@<version>

Example Session

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                   Welcome                   ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

System Upgrade Manager

Log file: ~/upgrade-logs/upgrade_20250605_143022.log
Snapshot: ~/upgrade-logs/snapshot_20250605_143022.json

This tool will help you safely upgrade your system packages.

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                 Main Menu                   ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

System Upgrade Manager

1. Upgrade Homebrew
2. Upgrade Conda
3. Upgrade Python
4. Upgrade npm
5. Check All (no upgrades)
6. Upgrade All
0. Exit

Select option [0/1/2/3/4/5/6]: 5

Checking Homebrew...
✓ All Homebrew packages up to date

Checking Conda...
✓ Conda 25.9.1 (up to date)

Checking Python...
✓ Python 3.12.12 (up to date)

Checking npm...
npm: 11.6.2 → Latest: 11.6.2
✓ All global npm packages up to date

✓ Snapshot saved to: ~/upgrade-logs/snapshot_20250605_143022.json

Tips

• Run option 5 (Check All) first to see what needs updating
• Use option 6 (Upgrade All) for routine maintenance
• Always review logs in ~/upgrade-logs/ after major upgrades
• Keep snapshots for at least 30 days for rollback capability
• Test your development environment after major upgrades

Troubleshooting

"rich library not found"

Install with: pip install rich The script will work without it but with plain text output.

Script name issues

Make sure you're running safe_update.py (not the old system_upgrade.py name).

Conda upgrade conflicts

If Conda dependencies conflict, try:

conda update -n base -c defaults conda --force-reinstall

Homebrew permission errors

Fix with: sudo chown -R $(whoami) $(brew --prefix)/*

npm permission errors

Fix with: sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Requirements

• Python 3.7+
• macOS (tested on macOS 15.1+)
• zsh shell
• Homebrew, Conda, and/or npm installed
• Optional: rich library for enhanced UI (pip install -r requirements.txt)

Security Features

Command Injection Prevention

• Package Name Validation: All package names validated before use in shell commands
• Controlled Execution: Uses shell=True only for pipes/redirects with validated inputs
• Input Sanitization: Comprehensive validation using regex patterns

Safe Defaults

• System Python Protection: Never modifies macOS system Python
• Backup First: Always creates snapshots before making changes
• Comprehensive Logging: All actions logged for audit trail
• Error Handling: Graceful failure handling with proper error messages

Secure Dependencies

• Pinned Requirements: requirements.txt with version constraints
• Minimal Dependencies: Only rich library for UI (optional)
• No Untrusted Input: All commands are hardcoded or validated

License

Free to use and modify.