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): genet-godzilla/fonts
Install flow: brew tap ... → brew install font-<name>

Repository Layout

custom_font_tap/
├── PROJECT.md              # This file — canonical project overview for LLMs/agents
├── .cursorrules            # Cursor: root rules (points here)
├── .github/
│   └── copilot-instructions.md   # GitHub Copilot / VS Code
├── .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
`.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`).

Workflows

Adding a new font

Get the font (e.g. extract a zip) into To Sort/ or a temp folder.
Rename the folder to font-<name> (lowercase, hyphens for spaces).
Move the folder into font_files/.
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
Generate/update the formula:
python3 .fontfoldercleanup/create_homebrew_formula.py
Commit font_files/font-<name>/ and Formula/font-<name>.rb.

Regenerating all formulae

From repo root:

python3 .fontfoldercleanup/create_homebrew_formula.py

This overwrites Formula files for every font-* directory in font_files/.

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<Name> where <Name> is the part after font-, with hyphens/underscores kept as in the folder name (e.g. FontGraham_hand, FontMba-slice-mono).
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.

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:3002/Fonts/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: 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 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 Sort/ is for unsorted downloads; fonts are only “in the tap” when they are under font_files/ and have a matching file in Formula/.

6.5 KiB Raw Blame History