Add installable-font catalog and fontpkg search command

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: etjones

.github/workflows/generate.yml

@@ -51,12 +51,12 @@ jobs:
             exit 0
           fi
           uv publish "${wheels[@]}"
-      - name: Commit updated state manifest
+      - name: Commit updated state manifest and catalog
         run: |
-          if ! git diff --quiet state.json 2>/dev/null || [ -n "$(git ls-files --others state.json)" ]; then
+          if ! git diff --quiet state.json catalog.json 2>/dev/null || [ -n "$(git ls-files --others state.json catalog.json)" ]; then
             git config user.name "github-actions[bot]"
             git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            git add state.json
-            git commit -m "Update font state manifest"
+            git add state.json catalog.json
+            git commit -m "Update font state manifest and catalog"
             git push
           fi

CONVERSATION.md

@@ -115,3 +115,12 @@ Open decisions: project/package naming (`fontgrab` vs `pyfontsource`), PyPI scal
 **User:** Put PYPI_TOKEN in .env; asked Claude to publish the first 10 MVP font packages.
 
 **Claude:** Added .env to .gitignore first (it wasn't ignored). Built wheels+sdists for all 10, published with the token via UV_PUBLISH_TOKEN. fontpkg-fira-code and fontpkg-inter landed immediately; PyPI's new-project creation throttle (429) hit on the third, so the remaining 8 are publishing via a background retry loop (idempotent with --check-url, 120s backoff).
+
+---
+
+**User:** Asked about discoverability (fontsource-style search/specimens), requested a CLI query for installable (not just installed) fonts, a README usage update, and further suggestions.
+
+**Claude:** Built the catalog layer:
+- catalog.json at repo root: index of installable families (family/slug/package/version/license/category/styles/variable/weights), generated by sync alongside state.json, committed by the weekly workflow; seeded from a fresh sync of the 10 families. build.py now records category+subsets in metadata.json.
+- `fontpkg search <query>` in the core CLI: fetches catalog from GitHub raw (--catalog-url / FONTPKG_CATALOG_URL override, local paths supported), matches family/slug/category, marks [installed], prints uv add hints. Only networked CLI command; library API stays offline.
+- READMEs updated with normal usage (uv add fontpkg-inter; fontpkg.path("inter")) and CLI examples. 45 tests passing.

DESIGN.md

@@ -252,6 +252,14 @@ Recorded while implementing the MVP; deviations from or refinements of the secti
   runs) because **each new `fontpkg-<slug>` name needs a pending trusted publisher added
   on PyPI first** — PyPI has no bulk API for this, so the MVP names are a one-time manual
   step (or a first local `uv publish` with a token per package).
+- **Discoverability (Phase 3 started):** `catalog.json` at the repo root is the
+  machine-readable index of installable families (family, slug, package, version,
+  license, category, styles, variable/weights), updated by the same sync that builds
+  packages and committed by CI alongside `state.json`. The core CLI's `fontpkg search
+  <query>` fetches it from GitHub raw (override with `--catalog-url` or
+  `FONTPKG_CATALOG_URL`; accepts a local path) and marks installed families — the only
+  CLI command that touches the network; the library API stays offline. The catalog is
+  the intended data source for a future docs site with rendered specimens.
 - **Tests:** no network anywhere; fixture fonts are built in-memory with fontTools
   `FontBuilder`; generator↔core schema compatibility is covered by a roundtrip test.
   Live verification (fetch → build → wheel → clean-venv install → resolve → PIL render)

README.md

@@ -3,20 +3,30 @@
 [![CI](https://github.com/Fontpkg/fontpkg/actions/workflows/ci.yml/badge.svg)](https://github.com/Fontpkg/fontpkg/actions/workflows/ci.yml)
 
 Fonts as ordinary Python project dependencies — a [Fontsource](https://fontsource.org)
-analog for PyPI. `uv add fontpkg-roboto` and the font is pinned, offline, and
-resolvable at runtime.
+analog for PyPI.
+
+## Usage
+
+```bash
+uv add fontpkg fontpkg-inter
+```
 
 ```python
 import fontpkg
 
-fontpkg.path("Roboto", weight=700, style="italic")   # -> Path to the .ttf
+font_path = fontpkg.path("inter")                    # Path to Inter 400/normal
+fontpkg.path("Inter", weight=700, style="italic")    # names are case/space-insensitive
 fontpkg.families()                                    # everything installed
 ```
 
+The font is pinned in your lockfile, downloaded at install time (never at runtime),
+and works offline forever.
+
 There is also a small CLI:
 
 ```bash
-fontpkg list
+fontpkg list                             # installed families
+fontpkg search mono                      # installable families (fetches the catalog)
 fontpkg path "Open Sans" --weight bold
 ```
 

catalog.json

@@ -0,0 +1,211 @@
+{
+  "fira-code": {
+    "category": [
+      "MONOSPACE"
+    ],
+    "family": "Fira Code",
+    "license": "OFL-1.1",
+    "package": "fontpkg-fira-code",
+    "slug": "fira-code",
+    "styles": [
+      "normal"
+    ],
+    "variable": true,
+    "version": "5.002",
+    "weight_range": [
+      300,
+      700
+    ],
+    "weights": []
+  },
+  "inter": {
+    "category": [
+      "SANS_SERIF"
+    ],
+    "family": "Inter",
+    "license": "OFL-1.1",
+    "package": "fontpkg-inter",
+    "slug": "inter",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "4.001",
+    "weight_range": [
+      100,
+      900
+    ],
+    "weights": []
+  },
+  "jetbrains-mono": {
+    "category": [
+      "MONOSPACE"
+    ],
+    "family": "JetBrains Mono",
+    "license": "OFL-1.1",
+    "package": "fontpkg-jetbrains-mono",
+    "slug": "jetbrains-mono",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "2.211",
+    "weight_range": [
+      100,
+      800
+    ],
+    "weights": []
+  },
+  "lato": {
+    "category": [
+      "SANS_SERIF"
+    ],
+    "family": "Lato",
+    "license": "OFL-1.1",
+    "package": "fontpkg-lato",
+    "slug": "lato",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": false,
+    "version": "2.015",
+    "weight_range": [
+      100,
+      900
+    ],
+    "weights": [
+      100,
+      200,
+      300,
+      400,
+      500,
+      600,
+      700,
+      800,
+      900
+    ]
+  },
+  "merriweather": {
+    "category": [
+      "SERIF"
+    ],
+    "family": "Merriweather",
+    "license": "OFL-1.1",
+    "package": "fontpkg-merriweather",
+    "slug": "merriweather",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "2.100",
+    "weight_range": [
+      300,
+      900
+    ],
+    "weights": []
+  },
+  "noto-sans": {
+    "category": [
+      "SANS_SERIF"
+    ],
+    "family": "Noto Sans",
+    "license": "OFL-1.1",
+    "package": "fontpkg-noto-sans",
+    "slug": "noto-sans",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "2.015",
+    "weight_range": [
+      100,
+      900
+    ],
+    "weights": []
+  },
+  "open-sans": {
+    "category": [
+      "SANS_SERIF"
+    ],
+    "family": "Open Sans",
+    "license": "OFL-1.1",
+    "package": "fontpkg-open-sans",
+    "slug": "open-sans",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "3.003",
+    "weight_range": [
+      300,
+      800
+    ],
+    "weights": []
+  },
+  "playfair-display": {
+    "category": [
+      "SERIF"
+    ],
+    "family": "Playfair Display",
+    "license": "OFL-1.1",
+    "package": "fontpkg-playfair-display",
+    "slug": "playfair-display",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "1.203",
+    "weight_range": [
+      400,
+      900
+    ],
+    "weights": []
+  },
+  "roboto": {
+    "category": [
+      "SANS_SERIF"
+    ],
+    "family": "Roboto",
+    "license": "OFL-1.1",
+    "package": "fontpkg-roboto",
+    "slug": "roboto",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "3.015",
+    "weight_range": [
+      100,
+      900
+    ],
+    "weights": []
+  },
+  "source-sans-3": {
+    "category": [
+      "SANS_SERIF"
+    ],
+    "family": "Source Sans 3",
+    "license": "OFL-1.1",
+    "package": "fontpkg-source-sans-3",
+    "slug": "source-sans-3",
+    "styles": [
+      "italic",
+      "normal"
+    ],
+    "variable": true,
+    "version": "3.052",
+    "weight_range": [
+      200,
+      900
+    ],
+    "weights": []
+  }
+}

core/README.md

@@ -3,20 +3,24 @@
 Fonts as ordinary Python project dependencies. Inspired by [Fontsource](https://fontsource.org).
 
 ```bash
-uv add fontpkg fontpkg-roboto
+uv add fontpkg fontpkg-inter
 ```
 
 ```python
 import fontpkg
 
-fontpkg.path("Roboto")                            # Path to 400/normal
-fontpkg.path("Roboto", weight=700, style="italic")
-fontpkg.path("Roboto", weight=650, nearest=True)
+font_path = fontpkg.path("inter")                 # Path to 400/normal
+fontpkg.path("Inter", weight=700, style="italic") # names are case/space-insensitive
+fontpkg.path("Inter", weight=650, nearest=True)
 
-fam = fontpkg.family("Roboto")   # .weights, .styles, .axes, .is_variable, .license
+fam = fontpkg.family("Inter")    # .weights, .styles, .axes, .is_variable, .license
 fontpkg.families()               # everything installed in the environment
 ```
 
+Find installable families with `fontpkg search <query>` (matches family, slug, or
+category; the only CLI command that touches the network) or `fontpkg list` for what
+is already installed.
+
 Integrations (extras `fontpkg[pil]`, `fontpkg[matplotlib]`):
 
 ```python

core/src/fontpkg/__main__.py

@@ -1,8 +1,10 @@
 import argparse
 import sys
+import urllib.error
 
 from fontpkg import FontpkgError, families
 from fontpkg import path as font_path
+from fontpkg._catalog import fetch_catalog, search_catalog
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -14,10 +16,17 @@ def main(argv: list[str] | None = None) -> int:
     path_cmd.add_argument("--weight", default="400")
     path_cmd.add_argument("--style", default="normal")
     path_cmd.add_argument("--nearest", action="store_true")
+    search_cmd = sub.add_parser("search", help="search installable font families (network)")
+    search_cmd.add_argument("query", nargs="?", help="match against family, slug, or category")
+    search_cmd.add_argument(
+        "--catalog-url", default=None, help="catalog URL or file path (default: fontpkg repo)"
+    )
     args = parser.parse_args(argv)
 
     if args.command in (None, "list"):
         return _list()
+    if args.command == "search":
+        return _search(args)
     return _path(args)
 
 
@@ -37,6 +46,31 @@ def _list() -> int:
     return 0
 
 
+def _search(args: argparse.Namespace) -> int:
+    try:
+        catalog = fetch_catalog(args.catalog_url)
+    except (urllib.error.URLError, OSError) as err:
+        print(f"error: could not fetch catalog: {err}", file=sys.stderr)
+        return 1
+    matches = search_catalog(catalog, args.query)
+    if not matches:
+        print(f"no installable families match {args.query!r}")
+        return 0
+    installed = set(families())
+    width = max(len(e["slug"]) for e in matches)
+    for e in matches:
+        if e["variable"] and e["weight_range"]:
+            weights = f"wght {e['weight_range'][0]}-{e['weight_range'][1]}"
+        else:
+            weights = ",".join(map(str, e["weights"]))
+        mark = "  [installed]" if e["slug"] in installed else ""
+        print(
+            f"{e['slug']:{width}}  {e['license']:10} styles={'/'.join(e['styles'])} "
+            f"{weights}  uv add {e['package']}{mark}"
+        )
+    return 0
+
+
 def _path(args: argparse.Namespace) -> int:
     weight: int | str = int(args.weight) if args.weight.isdigit() else args.weight
     try: