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: root-level rules; points to PROJECT.md.
.github/copilot-instructions.md	GitHub Copilot (VS Code, Visual Studio, GitHub.com): workspace instructions; references PROJECT.md.
.claude/skills/project-context/SKILL.md	Claude Code / Claude Agent SDK: 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:

   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:

python3 .fontfoldercleanup/create_homebrew_formula.py

Then run the test suite to confirm:

uv run pytest tests/

Running tests

From repo root:

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/):

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:8085/clancy/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/.