Metadata-Version: 2.4
Name: brew-migrator
Version: 0.1.0
Summary: Migrate applications from /Applications to Homebrew Casks
Author-email: Christopher Zimbizi <chriszimbizi@gmail.com>
License: # The MIT License (MIT)
        
        Copyright (c) 2025 Christopher Zimbizi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://github.com/chriszimbizi/brew-migrator
Project-URL: Repository, https://github.com/chriszimbizi/brew-migrator
Project-URL: Bug Tracker, https://github.com/chriszimbizi/brew-migrator/issues
Project-URL: Author Website, https://www.chriszimbizi.com/
Keywords: homebrew,mac,migration,cask
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Environment :: Console
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Homebrew App Migrator

[![PyPI version](https://img.shields.io/pypi/v/brew-migrator.svg)](https://pypi.org/project/brew-migrator/)
[![Python versions](https://img.shields.io/pypi/pyversions/brew-migrator.svg)](https://pypi.org/project/brew-migrator/)
[![License](https://img.shields.io/github/license/chriszimbizi/brew-migrator.svg)](https://github.com/chriszimbizi/brew-migrator/blob/main/LICENSE)

A retro-styled CLI tool to migrate manually installed macOS applications from `/Applications` to Homebrew Casks.

## Why this tool?

If you've ever bought a new Mac and spent hours manually downloading `.dmg` files, dragging them to `/Applications`, and trying to remember everything you had installed, this tool is for you.

**Homebrew** is the gold standard for managing software on macOS, but it only works if your apps are installed as "Casks." Most people have a mix of apps they downloaded from websites and apps installed via Homebrew.

### The Power of the Brewfile

Once your apps are migrated to Homebrew Casks using this tool, you can run:

```bash
brew bundle dump
```

This generates a `Brewfile` (like [this example](examples/example_brewfile.rb)). This single file is like a "save game" for your entire Mac setup. On a new machine, you just run `brew bundle` and **every single app** is automatically installed for you in minutes.

## Features

- **Retro UI**: A terminal-based interface that feels like an old-school computer system.
- **Progress Bar**: Visual feedback during Homebrew operations with a custom pulsing activity bar.
- **App Ignoring**: Permanently exclude system apps or non-caskable software from future scans.
- **Multi-Column Layout**: High-density grid-style listing for auditing large application histories.
- **Intelligent Search**: Automatically finds the correct Homebrew Cask for your installed apps.
- **Dry Run Mode**: Safe simulation mode to see what would happen without making any changes.
- **Migration History**: Remembers what you've already migrated, skipped, or failed.
- **Batch Mode**: Quick-install the best matches for all your apps at once.
- **Paginated Results**: Easily browse through multiple search results.

## Installation

### Via PyPI (Recommended)

Install the latest stable version from PyPI with [pipx](https://pipx.pypa.io) or [uv](https://docs.astral.sh/uv/):

```bash
pipx install brew-migrator
# or
uv tool install brew-migrator
```

To upgrade later:

```bash
pipx upgrade brew-migrator
# or
uv tool upgrade brew-migrator
```

### From Source (Development)

1. Clone the repository:

   ```bash
   git clone https://github.com/chriszimbizi/brew-migrator.git
   cd brew-migrator
   ```

2. Create a virtual environment and install in editable mode:

   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .
   ```

## Usage

After installation, you can run the tool using the `brew-migrator` command:

```bash
brew-migrator [OPTIONS]
```

### Options

- `--dry-run`: **(Highly Recommended)** Simulate the migration without installing anything or writing to the history file.
- `--list-apps`: List all applications found in `/Applications` and `~/Applications`.
- `--list-pending`: List applications not yet managed by Homebrew (apps already installed as casks are skipped automatically).
- `--list-installed`: List all applications successfully migrated to Homebrew.
- `--list-skipped`: List all applications currently in the skipped history.
- `--list-ignored`: List all applications explicitly marked as ignored.
- `--app "AppName"`: Process a specific application by name.
- `--batch`: Run in batch mode. Installs only casks whose name exactly matches the app (e.g. `Visual Studio Code` → `visual-studio-code`); other apps are skipped for review with `--retry-skipped`.
- `--retry-skipped`: Retry apps that were previously skipped.
- `--retry-ignored`: Re-process apps that were previously marked as ignored.
- `--reset-history`: Clear the migration history file.

### Examples

**Safe Simulation:**

```bash
brew-migrator --dry-run
```

**List all apps:**

```bash
brew-migrator --list-apps
```

**Run in batch mode:**

```bash
brew-migrator --batch
```

## How it Works

1. **Scan**: The tool looks at everything in `/Applications` and `~/Applications`, skipping apps already installed as Homebrew Casks.
2. **Search**: It loads the Homebrew Cask index once and finds matching Casks for each app, best match first.
3. **Selection**: You choose the correct match from a list (or let Batch Mode install exact matches).
4. **Log**: The tool records the migration in a JSON history file to prevent double-work.

## Project Structure

```text
.
├── LICENSE
├── README.md
├── pyproject.toml
├── src
│   └── brew_migrator
│       ├── cli.py
│       ├── core
│       │   ├── brew.py
│       │   └── history.py
│       └── ui
│           └── console.py
└── tests
```

Run the tests with `pip install -e ".[dev]" && pytest`.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
