# Plan: Create Homebrew-Installable Python CLI Tool - "silo"

## Overview
Create a Python CLI tool called **silo** that can be installed via Homebrew on macOS, with subcommands that perform file manipulations.

## Technology Choices
- **CLI Framework**: Typer (modern, type-hint based, built on Click)
- **Dependency Management**: uv (fast Rust-based tool from Astral, with lock files)
- **Packaging**: pyproject.toml (modern standard, setup.py is deprecated)
- **Distribution**: Personal Homebrew tap (no approval process needed)

---

## Step 0: Install uv

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew
brew install uv

# Verify installation
uv --version
```

---

## Step 1: Create Project Structure

```
silo/
├── src/
│   └── silo/
│       ├── __init__.py
│       ├── __main__.py
│       └── cli.py
├── tests/
│   └── test_cli.py
├── pyproject.toml
├── uv.lock
├── README.md
└── LICENSE
```

Initialize the project with uv:
```bash
# Initialize project (creates pyproject.toml)
uv init --name silo

# Create src layout
mkdir -p src/silo tests
touch src/silo/__init__.py
touch src/silo/__main__.py
touch src/silo/cli.py
touch README.md LICENSE
```

---

## Step 2: Implement the CLI (src/silo/cli.py)

```python
import typer
from pathlib import Path

app = typer.Typer(
    name="silo",
    help="Silo - your file manipulation tool",
    add_completion=False,
)

@app.command()
def abc(
    target: Path = typer.Argument(..., help="Target file or directory"),
    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
):
    """
    The abc command - performs file manipulations.
    """
    # Your file manipulation logic here
    if verbose:
        typer.echo(f"Processing: {target}")

    # Example: read, modify, write files
    if target.is_file():
        content = target.read_text()
        # ... manipulate content ...
        typer.echo(f"Processed file: {target}")
    elif target.is_dir():
        for file in target.glob("*"):
            typer.echo(f"Found: {file}")

@app.command()
def another_command():
    """Another subcommand example."""
    typer.echo("Running another command...")

if __name__ == "__main__":
    app()
```

---

## Step 3: Create Entry Points

**src/silo/__main__.py**:
```python
from .cli import app

if __name__ == "__main__":
    app()
```

**src/silo/__init__.py**:
```python
__version__ = "0.1.0"
```

---

## Step 4: Configure pyproject.toml

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "silo"
version = "0.1.0"
description = "Silo - your file manipulation tool"
readme = "README.md"
requires-python = ">=3.13"
license = {text = "MIT"}
authors = [
    {name = "Karol Kaminski", email = "you@example.com"}
]
dependencies = [
    "typer>=0.9.0",
]

[project.scripts]
silo = "silo.cli:app"

[project.urls]
Homepage = "https://github.com/yourusername/silo"
Repository = "https://github.com/yourusername/silo.git"

[tool.hatch.build.targets.wheel]
packages = ["src/silo"]

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.4.0",
]
```

---

## Step 5: Install Dependencies & Test Locally

```bash
# Add typer dependency (updates pyproject.toml and uv.lock)
uv add typer

# Add dev dependencies
uv add --dev pytest ruff

# Sync environment (creates .venv automatically)
uv sync

# Install in development mode (editable)
uv pip install -e .

# Test the CLI
uv run silo --help
uv run silo abc ./some-file.txt
uv run silo abc ./some-directory --verbose

# Or activate venv and run directly
source .venv/bin/activate
silo --help
```

---

## Step 6: Publish to PyPI

```bash
# Build the package
uv build

# Upload to PyPI (requires PyPI account and API token)
uv publish

# Or use twine if preferred
uv pip install twine
twine upload dist/*
```

**Note**: Configure PyPI credentials via environment variables or `~/.pypirc`:
```bash
export UV_PUBLISH_TOKEN=pypi-your-token-here
```

---

## Step 7: Create Homebrew Tap

1. **Create GitHub repository**: `homebrew-silo`

2. **Create Formula directory**:
```bash
mkdir -p Formula
```

3. **Create formula file** (Formula/silo.rb):
```ruby
class Silo < Formula
  include Language::Python::Virtualenv

  desc "Silo - your file manipulation tool"
  homepage "https://github.com/yourusername/silo"
  url "https://files.pythonhosted.org/packages/.../silo-0.1.0.tar.gz"
  sha256 "YOUR_SHA256_HERE"
  license "MIT"

  depends_on "python@3.13"

  resource "typer" do
    url "https://files.pythonhosted.org/packages/.../typer-0.9.0.tar.gz"
    sha256 "TYPER_SHA256_HERE"
  end

  resource "click" do
    url "https://files.pythonhosted.org/packages/.../click-8.1.7.tar.gz"
    sha256 "CLICK_SHA256_HERE"
  end

  # Add all transitive dependencies as resources

  def install
    virtualenv_install_with_resources
  end

  test do
    assert_match "Silo", shell_output("#{bin}/silo --help")
  end
end
```

4. **Generate dependency resources automatically**:
```bash
# Create a temporary venv with uv and install poet
uv venv /tmp/poet-env
uv pip install --python /tmp/poet-env/bin/python homebrew-pypi-poet silo

# Generate formula
/tmp/poet-env/bin/poet -f silo > Formula/silo.rb

# Alternative: After creating initial formula, use brew
brew update-python-resources Formula/silo.rb
```

5. **Push to GitHub**:
```bash
cd homebrew-silo
git init
git add .
git commit -m "Add silo formula"
git remote add origin https://github.com/yourusername/homebrew-silo.git
git push -u origin main
```

---

## Step 8: Users Install Your Tool

```bash
# Add your tap
brew tap yourusername/silo

# Install
brew install silo

# Use immediately
silo --help
silo abc /path/to/file
```

Or one-liner:
```bash
brew install yourusername/silo/silo
```

---

## Verification Checklist

- [ ] `uv run silo --help` shows description and available commands
- [ ] `uv run silo abc <target>` executes file manipulation logic
- [ ] `uv.lock` exists and is committed to git
- [ ] Package builds: `uv build` creates dist/*.tar.gz and dist/*.whl
- [ ] Homebrew formula installs: `brew install --build-from-source Formula/silo.rb`
- [ ] After Homebrew install, command is available system-wide

---

## File Summary

| File | Purpose |
|------|---------|
| `src/silo/cli.py` | Main CLI logic with Typer commands |
| `src/silo/__main__.py` | Enables `python -m silo` |
| `pyproject.toml` | Package configuration, dependencies, and entry points |
| `uv.lock` | Locked dependency versions for reproducible builds |
| `Formula/silo.rb` | Homebrew formula (in separate tap repo) |

---

## Common uv Commands Reference

```bash
uv add <package>        # Add dependency
uv add --dev <package>  # Add dev dependency
uv remove <package>     # Remove dependency
uv sync                 # Install all dependencies from lock file
uv lock                 # Update lock file
uv run <command>        # Run command in project environment
uv build                # Build package (sdist + wheel)
uv publish              # Publish to PyPI
uv pip install -e .     # Editable install
```

---

## Notes

- The formula requires PyPI publication first (Homebrew downloads from PyPI)
- Commit `uv.lock` to version control for reproducible builds
- Use `homebrew-pypi-poet` to auto-generate dependency resources
- Start with personal tap; submit to homebrew-core later if tool gains popularity
- Replace `yourusername` with your actual GitHub username
