homebrew-fonts/PROJECT.md

# Project: Custom Font Homebrew Tap

This document describes the repository for Cursor, other LLMs, and automation agents. Read this first to understand structure, conventions, and workflows.

## LLM / agent context files (conventions)

This repo follows common conventions so multiple tools can discover project context:

| File | Used by |
|------|--------|
| **PROJECT.md** (this file) | Canonical project description; any LLM or agent. |
| **.cursorrules** | [Cursor](https://cursor.com): root-level rules; points to PROJECT.md. |
| **.github/copilot-instructions.md** | [GitHub Copilot](https://docs.github.com/en/copilot) (VS Code, Visual Studio, GitHub.com): workspace instructions; references PROJECT.md. |
| **.claude/skills/project-context/SKILL.md** | [Claude Code](https://code.claude.com) / [Claude Agent SDK](https://docs.anthropic.com/en/docs/agent-sdk/overview): project skill; references PROJECT.md. |

When adding or changing project rules, update **PROJECT.md** first, then sync the tool-specific files above if needed.

## What This Repo Is

A **Homebrew tap** that serves a personal collection of fonts. Users add the tap once, then install fonts with `brew install font-<name>`. The repo is the tap source: it contains font assets and Homebrew Formula (Ruby) files that install them.

- **Tap name (from README):** `clancy/fonts`
- **Install flow:** `brew tap ...` → `brew install font-<name>`

## Repository Layout

```
custom_font_tap/
├── PROJECT.md              # This file — canonical project overview for LLMs/agents
├── pyproject.toml          # uv project; add-font CLI and pytest
├── tap_cli/                # add-font CLI (uv run add-font)
├── tests/                  # Repo-level tests (every font: structure, formula)
├── .cursorrules            # Cursor: root rules (points here)
├── .github/
│   ├── copilot-instructions.md   # GitHub Copilot / VS Code
│   └── workflows/               # CI (pytest, brew audit)
├── .claude/skills/project-context/
│   └── SKILL.md            # Claude Code / Agent SDK
├── README.md               # User-facing install instructions
├── .gitignore
├── font_files/             # Canonical font data (one folder per font)
│   └── font-<name>/        # Each font: ttf/, otf/, web/, other_files/
├── Formula/                # Homebrew formulae (*.rb), one per font
├── To Sort/                # Staging: new downloads not yet in font_files
├── .fontfoldercleanup/     # Scripts to organize folders and generate formulae
└── .cursor/rules/          # Cursor rule(s) for font folder structure
```

## Font Folder Structure (Required)

Every font lives in `font_files/` in a folder named **`font-<name>`**. Inside that folder only these four subdirectories are allowed:

| Directory     | Purpose |
|---------------|--------|
| `ttf/`        | `.ttf` files |
| `otf/`        | `.otf` files |
| `web/`        | `.woff`, `.woff2`, `.eot`, `.svg` |
| `other_files/`| Everything else (licenses, PDFs, docs, etc.) |

- All font folders **must** use the `font-` prefix.
- No other top-level files or dirs; anything else goes under `other_files/`.
- The rule and cleanup script are documented in `.cursor/rules/font-folder-structure.mdc`.

## Key Files and Scripts

| Path | Purpose |
|------|--------|
| **`uv run add-font`** | CLI: add or update a font (cleanup + formula + tests). Use `uv run add-font <path_or_name>`. Optional: `uv tool install .` for global `add-font`. |
| `tests/` | Repo-level test suite (pytest). Run with `uv run pytest tests/`. Validates every font: structure, formula exists, formula content. |
| `.fontfoldercleanup/cleanup_font_folders.py` | Organizes a font tree into `ttf/`, `otf/`, `web/`, `other_files/`. Run with `--path` (default `../font_files` relative to script). |
| `.fontfoldercleanup/create_homebrew_formula.py` | Scans `font_files/` for `font-*` dirs and writes/updates one `.rb` per font in `Formula/`. |
| `.fontfoldercleanup/tap_config.rb` | Reference tap config (meta-formula); not the main installer. |
| `Formula/font-<name>.rb` | Generated; do not edit by hand. Class name is `Font<PascalCase>` (e.g. `font-acrylic-hand` → `FontAcrylicHand`). |

## Workflows

### Adding a new font

1. Get the font (e.g. extract a zip) into **`To Sort/`** or keep it in a temp folder.
2. From repo root, run:
   ```bash
   uv run add-font <path_or_name>
   ```
   - **`<path_or_name>`** can be:
     - A path to an unpacked font folder (or one already in `font_files/`). Name is inferred from the folder (e.g. `font-my-font`).
     - A font name (e.g. `font-acrylic-hand` or `acrylic-hand`) if the folder is already in `font_files/` (update flow).
3. The CLI runs cleanup, formula generator, and the test suite. Fix any test failures, then commit `font_files/font-<name>/` and `Formula/font-<name>.rb`.

To install the CLI globally: `uv tool install .` from the repo root; then you can run `add-font <path_or_name>` anywhere.

### Regenerating all formulae

From repo root:

```bash
python3 .fontfoldercleanup/create_homebrew_formula.py
```

Then run the test suite to confirm:

```bash
uv run pytest tests/
```

### Running tests

From repo root:

```bash
uv run pytest tests/
```

Tests are parametrized over every font: structure (four subdirs, at least one file), formula exists, formula content (paths and valid Ruby class name). Global tests ensure no orphan formulae and no duplicates.

### Only reorganizing folders (no formula changes)

Point the cleanup script at the directory that contains font folders (e.g. `font_files` or a folder under `To Sort/`):

```bash
python3 .fontfoldercleanup/cleanup_font_folders.py --path font_files
```

## Formula Conventions

- **File:** `Formula/font-<name>.rb` (e.g. `font-pixelon.rb`, `font-graham_hand.rb`).
- **Class:** `Font<PascalCase>` — the part after `font-` is converted to valid Ruby (e.g. `font-acrylic-hand` → `FontAcrylicHand`, `font-graham_hand` → `FontGrahamHand`). No hyphens in the class name.
- **Source:** Formulae assume the archive unpacks as `homebrew-fonts/` and fonts live under `homebrew-fonts/font_files/font-<name>/`.
- **Comment in formulae:** "This file was generated by the font folder cleanup script — Do not edit this file directly." Edits should go in the generator (`.fontfoldercleanup/create_homebrew_formula.py`) or in font folder structure/scripts.

## Technical Notes

- **Python:** Scripts are Python 3, standard library only (pathlib, shutil, argparse).
- **Ruby:** Formulae are standard Homebrew Formula; they use `share/"fonts/truetype"`, etc., and optional `share/"<formula_name>"` for `other_files` content.
- **Homebrew URL in formulae:** `http://clancy.genet-godzilla.ts.net:3000/trtmn/homebrew-fonts/archive/main.tar.gz` (may need updating if the server or repo path changes).
- **Ignored (`.gitignore`):** `*.ofm`, `*.cfg`, `*.g2n`, `.DS_Store`, `.setup_complete`, `.env/`, `.idea/`.

## Quick Reference for Agents

- To **add a font:** run `uv run add-font <path_or_name>` (or add `font_files/font-<name>/` then run `cleanup_font_folders.py` and `create_homebrew_formula.py`).
- To **fix folder structure:** run `cleanup_font_folders.py` on the directory containing the `font-*` folders.
- To **sync Formula with font_files:** run `create_homebrew_formula.py`; do not edit Formula `*.rb` files by hand.
- To **validate:** run `uv run pytest tests/` (and optionally `brew audit` on touched formulae).
- **To Sort/** is for unsorted downloads; fonts are only “in the tap” when they are under `font_files/` and have a matching file in `Formula/`.