Update documentation and scripts for font addition process; introduce uv run add-font CLI command for streamlined font management. Enhance formula generation with improved class name formatting and validation steps. Remove outdated font formula files.

PROJECT.md

@@ -27,9 +27,13 @@ A **Homebrew tap** that serves a personal collection of fonts. Users add the tap
 ```
 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
+│   ├── 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
@@ -61,26 +65,28 @@ Every font lives in `font_files/` in a folder named **`font-<name>`**. Inside th
 
 | 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<Name>` with formula name normalized (e.g. `font-graham_hand` → `FontGraham_hand`). |
+| `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 a temp folder.
-2. Rename the folder to **`font-<name>`** (lowercase, hyphens for spaces).
-3. Move the folder into **`font_files/`**.
-4. Run the cleanup script so files go into `ttf/`, `otf/`, `web/`, `other_files/`:
-   - From repo root:  
-     `python3 .fontfoldercleanup/cleanup_font_folders.py --path font_files`  
-   - Or from `.fontfoldercleanup/`:  
-     `python3 cleanup_font_folders.py --path ../font_files`
-5. Generate/update the formula:  
-   `python3 .fontfoldercleanup/create_homebrew_formula.py`
-6. Commit `font_files/font-<name>/` and `Formula/font-<name>.rb`.
+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
 
@@ -90,7 +96,21 @@ From repo root:
 python3 .fontfoldercleanup/create_homebrew_formula.py
 ```
 
-This overwrites Formula files for every `font-*` directory in `font_files/`.
+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)
 
@@ -103,7 +123,7 @@ 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<Name>` where `<Name>` is the part after `font-`, with hyphens/underscores kept as in the folder name (e.g. `FontGraham_hand`, `FontMba-slice-mono`).
+- **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-main/` and fonts live under `homebrew-fonts-main/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.
 
@@ -116,7 +136,8 @@ python3 .fontfoldercleanup/cleanup_font_folders.py --path font_files
 
 ## Quick Reference for Agents
 
-- To **add a font:** ensure a `font-<name>` folder exists in `font_files/` with the required four subdirs and files in the right places; run `cleanup_font_folders.py` then `create_homebrew_formula.py`.
+- 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/`.