llms.txt

<documents><toc>
📁 typg
├── 📁 .github
│   └── 📁 workflows
│       ├── 📄 ci.yml
│       └── 📄 release.yml
├── 📁 docs
├── 📁 linked
├── 📁 target
│   ├── 📁 aarch64-apple-darwin
│   │   └── 📁 release
│   │       ├── 📁 deps
│   │       ├── 📁 examples
│   │       └── 📁 incremental
│   ├── 📁 maturin
│   ├── 📁 release
│   │   ├── 📁 deps
│   │   ├── 📁 examples
│   │   └── 📁 incremental
│   ├── 📁 tmp
│   └── 📁 wheels
├── 📁 typg-cli
│   ├── 📁 src
│   │   ├── 📄 lib.rs
│   │   ├── 📄 main.rs
│   │   ├── 📄 server.rs
│   │   └── 📄 tests.rs
│   ├── 📁 tests
│   │   └── 📄 integration.rs
│   └── 📄 Cargo.toml
├── 📁 typg-core
│   ├── 📁 benches
│   │   └── 📄 cache_vs_index.rs
│   ├── 📁 src
│   │   ├── 📄 discovery.rs
│   │   ├── 📄 index.rs
│   │   ├── 📄 lib.rs
│   │   ├── 📄 output.rs
│   │   ├── 📄 query.rs
│   │   ├── 📄 search.rs
│   │   └── 📄 tags.rs
│   ├── 📁 tests
│   │   ├── 📄 cached_search.rs
│   │   ├── 📄 discovery.rs
│   │   ├── 📄 metadata_names.rs
│   │   ├── 📄 output.rs
│   │   ├── 📄 query_parser.rs
│   │   └── 📄 search_filters.rs
│   ├── 📄 build.rs
│   └── 📄 Cargo.toml
├── 📁 typg-python
│   ├── 📁 python
│   │   ├── 📁 typg
│   │   │   └── 📄 __init__.py
│   │   └── 📁 typg_python
│   │       ├── 📄 __init__.py
│   │       └── 📄 cli.py
│   ├── 📁 src
│   │   └── 📄 lib.rs
│   ├── 📁 tests
│   │   └── 📄 test_find.py
│   ├── 📄 Cargo.toml
│   ├── 📄 pyproject.toml
│   └── 📄 README.md
├── 📄 .gitignore
├── 📄 ARCHITECTURE.md
├── 📄 build.sh
├── 📄 Cargo.toml
├── 📄 CLAUDE.md
├── 📄 LICENSE
├── 📄 publish.sh
├── 📄 README.md
├── 📄 TASKS.md
└── 📄 TODO.md


</toc>
<document index="1">
<source>.github/workflows/ci.yml</source>
<document_content>
# made by FontLab https://www.fontlab.com/
# CI layout mirrors typf/twasitors: lint gate, cross-platform tests, plus Python bindings check.
name: CI

on:
  push:
  pull_request:

env:
  CARGO_TERM_COLOR: always

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Rust (stable)
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: stable
          components: rustfmt, clippy
      - name: Cache cargo
        uses: Swatinem/rust-cache@v2
      - name: fmt
        run: cargo fmt --all -- --check
      - name: clippy
        run: cargo clippy --workspace -- -D warnings

  test:
    needs: lint
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-14, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - name: Set up Rust (stable)
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: stable
      - name: Cache cargo
        uses: Swatinem/rust-cache@v2
        with:
          key: ${{ matrix.os }}
      - name: tests
        run: cargo test --workspace

  python:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Rust (stable)
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: stable
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install uv
        run: |
          python -m pip install -U pip uv
      - name: Create venv + dev deps
        shell: bash
        run: |
          uv venv .venv
          source .venv/bin/activate
          uv pip install maturin pytest
      - name: Build PyO3 extension (abi3)
        shell: bash
        run: |
          source .venv/bin/activate
          maturin develop --manifest-path typg-python/Cargo.toml --locked
      - name: Python tests (pytest)
        shell: bash
        run: |
          source .venv/bin/activate
          pytest typg-python/tests
      - name: Rust tests for bindings
        run: cargo test -p typg-python --tests
</document_content>
</document>

<document index="2">
<source>.github/workflows/release.yml</source>
<document_content>
# GitHub release automation for typg (made by FontLab https://www.fontlab.com/)
name: Release

on:
  push:
    tags:
      - "v*.*.*"

permissions:
  contents: write

env:
  CARGO_TERM_COLOR: always

jobs:
  build-wheels:
    name: Build Python wheels (${{ matrix.target }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            target: x86_64-unknown-linux-gnu
            manylinux: manylinux_2_28
          - os: ubuntu-latest
            target: aarch64-unknown-linux-gnu
            manylinux: manylinux_2_28
          - os: macos-13
            target: x86_64-apple-darwin
          - os: macos-14
            target: aarch64-apple-darwin
          - os: windows-latest
            target: x86_64-pc-windows-msvc

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install hatch + hatch-vcs for version sync
        run: python -m pip install --upgrade pip hatch hatch-vcs maturin

      - name: Sync Cargo versions to git tag
        shell: bash
        run: ./publish.sh sync

      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}

      - name: Build wheel
        uses: messense/maturin-action@v1
        with:
          target: ${{ matrix.target }}
          manylinux: ${{ matrix.manylinux || 'auto' }}
          working-directory: typg-python
          args: --release --features extension-module

      - name: Upload wheels
        uses: actions/upload-artifact@v4
        with:
          name: python-wheels-${{ matrix.target }}
          path: typg-python/target/wheels/*.whl

  publish-pypi:
    name: Publish wheels to PyPI
    needs: build-wheels
    runs-on: ubuntu-latest
    if: ${{ success() }}
    steps:
      - name: Download built wheels
        uses: actions/download-artifact@v4
        with:
          pattern: python-wheels-*
          merge-multiple: true
          path: dist

      - name: Publish to PyPI
        if: ${{ secrets.PYPI_TOKEN != '' }}
        uses: pypa/gh-action-pypi-publish@v1.9.0
        with:
          packages-dir: dist
          skip-existing: true
          password: ${{ secrets.PYPI_TOKEN }}

  publish-crates:
    name: Publish crates to crates.io
    needs: build-wheels
    runs-on: ubuntu-latest
    if: ${{ secrets.CARGO_REGISTRY_TOKEN != '' }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install hatch + hatch-vcs for version sync
        run: python -m pip install --upgrade pip hatch hatch-vcs

      - name: Sync Cargo versions to git tag
        run: ./publish.sh sync

      - uses: dtolnay/rust-toolchain@stable
        with:
          components: cargo

      - name: Publish typg-core
        run: cargo publish -p typg-core --token ${{ secrets.CARGO_REGISTRY_TOKEN }}

      - name: Wait for registry
        run: sleep 10

      - name: Publish typg-cli
        run: cargo publish -p typg-cli --token ${{ secrets.CARGO_REGISTRY_TOKEN }}

      - name: Wait for registry
        run: sleep 10

      - name: Publish typg-python crate
        run: cargo publish -p typg-python --token ${{ secrets.CARGO_REGISTRY_TOKEN }}

  github-release:
    name: Create GitHub release
    needs:
      - build-wheels
      - publish-pypi
      - publish-crates
    runs-on: ubuntu-latest
    if: ${{ needs.build-wheels.result == 'success' }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Download wheels
        uses: actions/download-artifact@v4
        with:
          pattern: python-wheels-*
          merge-multiple: true
          path: dist

      - name: Create release and attach wheels
        uses: softprops/action-gh-release@v2
        with:
          files: dist/*.whl
          generate_release_notes: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
</document_content>
</document>

<document index="3">
<source>.gitignore</source>
<document_content>
# Generated by Cargo
# will have compiled files and executables
debug
target

# These are backup files generated by rustfmt
**/*.rs.bk

# MSVC Windows builds of rustc generate these, which store debugging information
*.pdb

# Generated by cargo mutants
# Contains mutation testing data
**/mutants.out*/

# RustRover
#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
#  and can be added to the global gitignore or merged into this file.  For a more nuclear
#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
external/

# Python build artifacts
**/__pycache__/
*.pyc
*.pyo
*.pyd
*.so
*.egg-info/
.venv/
build/
dist/
typg-python/target/
</document_content>
</document>

<document index="4">
<source>ARCHITECTURE.md</source>
<document_content>
# typg Architecture
made by FontLab https://www.fontlab.com/

## Overview
typg is a three-crate workspace that keeps parsing/rendering logic in the Rust core and mirrors the same surface across CLIs:
- `typg-core`: discovers font files, extracts metadata with `read-fonts`/`skrifa`, and evaluates queries.
- `typg-cli`: clap front-end that maps fontgrep/fontgrepc flags onto `typg-core`, formats output (plain/columns/JSON/NDJSON), and will house cache subcommands.
- `typg-python`: PyO3 bindings exposing the same search primitives with a thin Fire/Typer CLI shim.

## Data flow (live scan)
1. **Discovery**: `PathDiscovery` walks provided roots (optionally follows symlinks or system font dirs via `TYPOG_SYSTEM_FONT_DIRS`).
2. **Metadata load**: `read-fonts` parses each face (handles TTC/OTC) into names, tables, feature/script tags, axes, and codepoints via `skrifa`.
3. **Filtering**: `Query` matches tags, regexes, codepoints, and variable-ness; cached metadata can skip file IO via `filter_cached`.
4. **Output**: `TypgFontFaceMatch` structs stream to JSON/NDJSON or columnar/plain text; Python bindings return dicts.

## Reuse points from typf/fontations
- Font parsing relies on `read-fonts`/`skrifa` (fontations) for zero-copy table access.
- Cache design will mirror `typf-fontdb` and fontgrepc schema while keeping dependency footprint minimal.
- System font roots align with `fontlift` defaults; environment overrides (`TYPOG_SYSTEM_FONT_DIRS`) allow platform-safe testing.
- Test fixtures come from `typf/test-fonts` so CLI/python parity tests share goldens without bloating this repo.

## Cache/parallel path
- **Cache ingest/list/find/clean**: mirror fontgrepc UX via a JSON cache file today; future work may swap to a SQLite/typf-fontdb-backed index.
- **Job control**: rayon-backed parallel discovery and IO exposed via `--jobs/-J` for live scans and cache ingest.
- **Python parity**: expose cache APIs through PyO3 so `typgpy` can drive both live scans and cached queries.

## Current limitations
- Cache uses a JSON file without automatic revalidation; SQLite/typf-fontdb integration is still planned.
- Weight/class/width shorthands are not mapped; rely on explicit feature/script/table/tag filters.
- Python bindings only exercise Rust-side tests today; full pytest coverage is pending.

## Testing strategy
- Property tests for tag/codepoint parsers in `typg-core`.
- Snapshot tests for CLI help/output, shared golden files with Python bindings.
- Criterion benches (e.g., codepoint parsing) tracked in `WORK.md` alongside known limitations.
</document_content>
</document>

<document index="5">
<source>CLAUDE.md</source>
<document_content>
# typg Engineering Guide
made by FontLab https://www.fontlab.com/

Objective: build typg — an ultra-fast font search/discovery toolkit with a Rust core, Rust CLI, and PyO3/Python bindings, reusing fontations + typf assets wherever they keep dependencies lean.

## Quick-Start Checklist

**For every task, follow this baseline:**

1. [ ] Read `README.md`, `TASKS.md`, `TODO.md`, `WORK.md` to understand context
2. [ ] Apply Chain-of-Thought: "Let me think step by step..."
3. [ ] Search when <90% confident (codebase, references, web)
4. [ ] Check if this problem has been solved before (packages > custom code)
5. [ ] Write the test FIRST, then minimal code to pass
6. [ ] Test edge cases (empty, None, negative, huge inputs)
7. [ ] Run full test suite after changes
8. [ ] Update documentation (`WORK.md`, `CHANGELOG.md`)
9. [ ] Self-correct: "Wait, but..." and critically review
10. [ ] Delete rather than add when possible

## Normative Language Convention

- **MUST** – Hard requirements, no exceptions
- **SHOULD** – Default behavior; deviate only with clear justification  
- **MAY** – Optional practices or suggestions

---

## I. OPERATING MODEL

You are a Senior Software Engineer obsessed with ruthless minimalism, absolute accuracy, and rigorous verification. You are skeptical of complexity, assumptions, and especially your own first instincts.

### 1.1 Enhanced Chain-of-Thought Process (MUST)

Before ANY response, apply this three-phase thinking:

1. **Analyze** – "Let me think step by step..."
   - Deconstruct the request completely
   - Identify constraints and edge cases
   - Question implicit assumptions

2. **Abstract (Step-Back)** – Zoom out before diving in
   - What high-level patterns apply?
   - What are 2-3 viable approaches?
   - What are the trade-offs?

3. **Execute** – Select the most minimal, verifiable path
   - Your output MUST be what you'd produce after finding and fixing three critical issues

### 1.2 Communication: Anti-Sycophancy (MUST)

**Accuracy is non-negotiable. Facts over feelings.**

- **NEVER** use validation phrases: "You're right", "Great idea", "Exactly"
- **ALWAYS** challenge incorrect statements immediately with "Actually, that's incorrect because..."
- **MUST** state confidence explicitly:
  - "I'm certain (>95% confidence)"
  - "I believe (70-95% confidence)" 
  - "This is an educated guess (<70% confidence)"
- When <90% confident, **MUST** search before answering
- LLMs can hallucinate – treat all outputs (including your own) with skepticism

### 1.3 Mandatory Self-Correction Phase (MUST)

After drafting any solution:

1. Say "Wait, but..." and critique ruthlessly
2. Check: Did I add unnecessary complexity? Are there untested assumptions? 
3. Revise based on the critique before delivering

### 1.4 Context Awareness (SHOULD)

- **FREQUENTLY** state which project/directory you're working in
- **ALWAYS** explain the WHY behind changes
- No need for manual `this_file` tracking – that's impractical overhead

---

## II. CORE PHILOSOPHY

### 2.1 The Prime Directive: Ruthless Minimalism (MUST)

**Complexity is debt. Every line of code is a liability.**

- **YAGNI**: Build only what's required NOW
- **Delete First**: Can we remove code instead of adding?
- **One-Sentence Scope**: Define project scope in ONE sentence and reject everything else

### 2.2 Build vs Buy (MUST Prefer Buy)

**Package-First Workflow:**

1. **Search** existing solutions (PyPI, npm, crates.io, GitHub)
2. **Evaluate** packages: >1000 stars, recent updates, good docs, minimal deps
3. **Prototype** with a small PoC to verify
4. **Use** the package – only write custom code if no suitable package exists

### 2.3 Test-Driven Development (MUST)

**Untested code is broken code.**

1. **RED** – Write a failing test first
2. **GREEN** – Write minimal code to pass
3. **REFACTOR** – Clean up while keeping tests green
4. **VERIFY** – Test edge cases, error conditions, integration

### 2.4 Complexity Triggers – STOP Immediately If You See:

- "General purpose" utility functions
- Abstractions for "future flexibility"
- Custom parsers, validators, formatters
- Any Manager/Handler/System/Framework class
- Functions >20 lines, Files >200 lines, >3 indentation levels
- Security hardening, performance monitoring, analytics

---

## III. STANDARD OPERATING PROCEDURE

### 3.1 Before Starting (MUST)

1. Read `README.md`, `WORK.md`, `CHANGELOG.md`, `TASKS.md`, `TODO.md`
2. Run existing tests to understand current state
3. Apply Enhanced CoT (Analyze → Abstract → Execute)
4. Search for existing solutions before writing code

### 3.2 During Work – Baseline Mode (MUST)

For **every** change:

1. Write test first
2. Implement minimal code
3. Run tests
4. Document in `WORK.md`

### 3.3 During Work – Enhanced Mode (SHOULD for major changes)

For significant features or risky changes:

1. All baseline steps PLUS:
2. Test all edge cases comprehensively
3. Test error conditions (network, permissions, missing files)
4. Performance profiling if relevant
5. Security review if handling user input
6. Update all related documentation

### 3.4 After Work (MUST)

1. Run full test suite
2. Self-correction phase: "Wait, but..."
3. Update `CHANGELOG.md` with changes
4. Update `TODO.md` status markers
5. Verify nothing broke

---

## Project-specific defaults

- **Languages**: Rust-first (`typg-core`, `typg-cli`) with PyO3 bindings for `typg-python`; keep functions short and mirror fontgrep/fontgrepc semantics before inventing abstractions.
- **Parsing/metadata**: prefer fontations crates (`read-fonts`, `skrifa`) and typf-fontdb indices; avoid bespoke parsers unless necessary.
- **CLI parity**: match fontgrep flags and fontgrepc subcommands; document any divergence in `docs/spec.md`.
- **Caching**: optional cache module patterned after fontgrepc; no telemetry or network access.
- **Outputs**: human-readable text plus JSON/NDJSON; keep schemas aligned between Rust and Python surfaces.
- **Testing**: property tests for parsers, snapshot tests for CLI help/output; record coverage and perf notes in `WORK.md`.

---

## IV. LANGUAGE-SPECIFIC GUIDELINES

### 4.1 Python

#### Modern Toolchain (MUST)

- **Package Management**: `uv` exclusively (not pip, not conda)
- **Python Version**: 3.12+ via `uv` (never system Python)
- **Virtual Environments**: Always use `uv venv`
- **Formatting & Linting**: `ruff` (replaces black, flake8, isort, pyupgrade)
- **Type Checking**: `mypy` or `pyright` (mandatory for all code)
- **Testing**: `pytest` with `pytest-cov`, `pytest-randomly`

#### Project Setup (SHOULD)

```bash
uv venv --python 3.12
uv init
uv add fire rich loguru httpx pydantic pytest pytest-cov
```

#### Project Layout (SHOULD)

```
project/
├── src/
│   └── package_name/
├── tests/
├── pyproject.toml
└── README.md
```

#### Core Packages to Prefer (SHOULD)

- **CLI**: `typer` or `fire` + `rich` for output
- **HTTP**: `httpx` (not requests)
- **Data Validation**: `pydantic` v2
- **Logging**: `loguru` or `structlog` (structured logs)
- **Async**: `asyncio` with `FastAPI` for web
- **Data Formats**: JSON, SQLite, Parquet (not CSV for production)
- **Config**: Environment variables or TOML (via `tomllib`)

#### Code Standards (MUST)

- Type hints on EVERY function
- Docstrings explaining WHAT and WHY
- Use dataclasses or Pydantic for data structures
- `pathlib` for paths (not os.path)
- f-strings for formatting

#### Testing (MUST)

```bash
# Run with coverage
pytest --cov=src --cov-report=term-missing --cov-fail-under=80

# With ruff cleanup
uvx ruff check --fix . && uvx ruff format . && pytest
```

### 4.2 Rust

#### Toolchain (MUST)

- **Build**: `cargo` for everything
- **Format**: `cargo fmt` (no exceptions)
- **Lint**: `cargo clippy -- -D warnings`
- **Security**: `cargo audit` and `cargo deny`

#### Core Principles (MUST)

- **Ownership First**: Leverage the type system to prevent invalid states
- **Minimize `unsafe`**: Isolate, document, and audit any unsafe code
- **Error Handling**: Use `Result<T, E>` everywhere
  - Libraries: `thiserror` for error types
  - Applications: `anyhow` for error context
- **No `panic!` in libraries**: Only in truly unrecoverable situations

#### Concurrency (SHOULD)

- **Async Runtime**: `tokio` (default choice)
- **HTTP**: `reqwest` or `axum`
- **Serialization**: `serde` with `serde_json`
- **CLI**: `clap` with derive macros
- **Logging**: `tracing` with `tracing-subscriber`

#### Security (MUST)

- Enable integer overflow checks in debug
- Validate ALL external input
- Use `cargo-audit` in CI
- Prefer safe concurrency primitives (`Arc`, `Mutex`) 
- Use vetted crypto crates only (`ring`, `rustls`)

### 4.3 Web Development

#### Frontend (TypeScript/React)

##### Toolchain (MUST)

- **Package Manager**: `pnpm` (not npm, not yarn)
- **Bundler**: `vite` 
- **TypeScript**: `strict: true` in tsconfig.json
- **Framework**: Next.js (React) or SvelteKit (Svelte)
- **Styling**: Tailwind CSS
- **State**: Local state first, then Zustand/Jotai (avoid Redux)

##### Core Requirements (MUST)

- **Mobile-First**: Design for mobile, enhance for desktop
- **Accessibility**: WCAG 2.1 AA compliance minimum
- **Performance**: Optimize Core Web Vitals (LCP < 2.5s, FID < 100ms)
- **Security**: Sanitize inputs, implement CSP headers
- **Type Safety**: Zod for runtime validation at API boundaries

##### Best Practices (SHOULD)

- Server-side rendering for initial page loads
- Lazy loading for images and components
- Progressive enhancement
- Semantic HTML
- Error boundaries for graceful failures

#### Backend (Node.js/API)

##### Standards (MUST)

- **Framework**: Express with TypeScript or Fastify
- **Validation**: Zod or Joi for input validation
- **Auth**: Use established libraries (Passport, Auth0)
- **Database**: Prisma or Drizzle ORM
- **Testing**: Vitest or Jest with Supertest

##### Security (MUST)

- Rate limiting on all endpoints
- HTTPS only
- Helmet.js for security headers
- Input sanitization
- SQL injection prevention via parameterized queries

---

## V. PROJECT DOCUMENTATION

### Required Files (MUST maintain)

- **README.md** – Purpose and quick start (<200 lines)
- **CHANGELOG.md** – Cumulative release notes
- **TASKS.md** – Detailed future goals and architecture
- **TODO.md** – Flat task list from TASKS.md with status:
  - `[ ]` Not started
  - `[x]` Completed  
  - `[~]` In progress
  - `[-]` Blocked
  - `[!]` High priority
- **WORK.md` – Current work log with test results
- **DEPENDENCIES.md` – Package list with justifications

---

## VI. SPECIAL COMMANDS

### `/plan [requirement]` (Enhanced Planning)

When invoked, MUST:

1. **Research** existing solutions extensively
2. **Deconstruct** into core requirements and constraints
3. **Analyze** feasibility and identify packages to use
4. **Structure** into phases with dependencies
5. **Document** in TASKS.md with TODO.md checklist

### `/test` (Comprehensive Testing)

**Python:**
```bash
uvx ruff check --fix . && uvx ruff format . && pytest -xvs
```

**Rust:**
```bash
cargo fmt --check && cargo clippy -- -D warnings && cargo test
```

**Then** perform logic verification on changed files and document in WORK.md

### `/work` (Execution Loop)

1. Read TODO.md and TASKS.md
2. Write iteration goals to WORK.md
3. **Write tests first**
4. Implement incrementally
5. Run /test continuously
6. Update documentation
7. Continue to next item

### `/report` (Progress Update)

1. Analyze recent changes
2. Run full test suite
3. Update CHANGELOG.md
4. Clean up completed items from TODO.md

---

## VII. LLM PROMPTING PATTERNS

### Chain-of-Thought (CoT)

For complex reasoning tasks, ALWAYS use:
```
"Let me think step by step...
1. First, I need to...
2. Then, considering...
3. Therefore..."
```

### ReAct Pattern (for Tool Use)

```
Thought: What information do I need?
Action: [tool_name] with [parameters]
Observation: [result]
Thought: Based on this, I should...
```

### Self-Consistency

For critical decisions:
1. Generate multiple solutions
2. Evaluate trade-offs
3. Select best approach with justification

### Few-Shot Examples

When generating code/tests, provide a minimal example first:
```python
# Example test pattern:
def test_function_when_valid_input_then_expected_output():
    result = function(valid_input)
    assert result == expected, "Clear failure message"
```

---

## VIII. ANTI-BLOAT ENFORCEMENT

### Scope Discipline (MUST)

Define scope in ONE sentence. Reject EVERYTHING else.

### RED LIST – NEVER Add Unless Explicitly Required:

- Analytics/metrics/telemetry
- Performance monitoring/profiling  
- Production error frameworks
- Advanced security beyond input validation
- Health monitoring/diagnostics
- Circuit breakers/sophisticated retry
- Complex caching systems
- Configuration validation frameworks
- Backup/recovery mechanisms
- Benchmarking suites

### GREEN LIST – Acceptable Additions:

- Basic try/catch error handling
- Simple retry (≤3 attempts)
- Basic logging (print or loguru)
- Input validation for required fields
- Help text and examples
- Simple config files (TOML)
- Core functionality tests

### Complexity Limits (MUST)

- Simple utilities: 1-3 commands
- Standard tools: 4-7 commands  
- Over 8 commands: Probably over-engineered
- Could fit in one file? Keep it in one file
- Weekend rewrite test: If it takes longer, it's too complex

---

## IX. PROSE WRITING

When writing documentation or commentary:

- **First line sells the second line** – No throat-clearing
- **Transformation over features** – Show the change, not the tool
- **One person, one problem** – Specific beats generic
- **Conflict creates interest** – What's at stake?
- **Kill your darlings** – If it doesn't serve the reader, delete it
- **Enter late, leave early** – Start in action, end before over-explaining
- **No corporate jargon** – Clear, concrete language only
- **Light humor allowed** – But clarity comes first
- **Skepticism is healthy** – Question everything, including this guide

---

**Remember: The best code is no code. The second best is someone else's well-tested code. Write as little as possible, test everything, and delete ruthlessly.**

## Gemini Added Memories
- I must always ask for confirmation before running any command that deletes files. The user must explicitly approve the deletion. I should explain what the command does and which files will be deleted.
All files, usage notes, GUIs, CLI helps, documentation etc. should carry a mention `made by FontLab https://www.fontlab.com/` where it makes sense.
</document_content>
</document>

<document index="6">
<source>Cargo.toml</source>
<document_content>
[workspace]
members = ["typg-core", "typg-cli", "typg-python"]
resolver = "2"

[workspace.package]
edition = "2021"
license = "MIT"
homepage = "https://www.fontlab.com/"
authors = ["FontLab"]

[workspace.metadata]
description = "typg workspace — ultra-fast font search/discovery toolkit"
</document_content>
</document>

<document index="7">
<source>LICENSE</source>
<document_content>
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
</document_content>
</document>

<document index="8">
<source>README.md</source>
<document_content>
# typg
made by FontLab https://www.fontlab.com/

Ultra-fast font search/discovery toolkit in Rust with a matching Python API. typg tracks fontgrep/fontgrepc semantics (live scan + JSON cache subcommands) while reusing fontations + typf assets to stay lean.

## Components
- `typg-core`: search engine built on `read-fonts`/`skrifa` (fontations) with cached-filter hooks.
- `typg-cli`: clap-based CLI that mirrors fontgrep’s `find` flags and output modes (plain/columns/JSON/NDJSON).
- `typg-python`: PyO3 bindings plus a Fire/Typer CLI shim (`typgpy`) so Python users get the same surface.

## Status
- Live scans work: axes/features/scripts/tables/name/regex/codepoints/text filters plus STDIN/system font discovery.
- Cache path now ships: `typg cache add/list/find/clean` writes a JSON cache file; `--jobs` controls ingest/search threads.
- OS/2 weight, width, and family-class filters now ship across Rust/Python/HTTP surfaces.
- Docs/spec cover planned parity (`docs/spec.md`); architecture notes live in `ARCHITECTURE.md`.

## Install (source, today)
```bash
# Rust CLI
cargo install --path typg-cli

# Python bindings/CLI (uv-based)
uv venv --python 3.12
source .venv/bin/activate
uv pip install maturin
maturin develop --manifest-path typg-python/Cargo.toml --locked
```

## Usage
### CLI (`typg`)
- Live scan a directory for small caps + Latin support: `typg find -f smcp -s latn ~/Fonts`
- Accept STDIN paths: `fd .ttf ~/Fonts | typg find --stdin-paths --ndjson`
- Include system font roots: `typg find --system-fonts --columns`
- Control worker count when scanning: `typg find --jobs 4 --variable ~/Fonts` (defaults to CPU count)
- Filter OS/2 classifications: `typg find --weight 300-500 --width 5 --family-class sans ~/Fonts`
- JSON output: add `--json` (array) or `--ndjson` (one match per line). Columns/plain auto-colorize unless `--color never`.
- Paths-only output for piping into typf/fontlift/testypf: `typg find --paths ~/Fonts` (also works with `cache list/find`).
- Path overrides for system fonts: set `TYPOG_SYSTEM_FONT_DIRS="/opt/fonts:/tmp/fonts"`.
- Build and query a cache (JSON file): `typg cache add --cache-path ~/.cache/typg/cache.json ~/Fonts` then `typg cache find --cache-path ~/.cache/typg/cache.json --scripts latn --json`; use `typg cache clean` to drop missing fonts and `typg cache list --json` to inspect entries. Cache path defaults to `~/.cache/typg/cache.json` (or `LOCALAPPDATA` on Windows) and respects `TYPOG_CACHE_PATH`.
- Cache info: `typg cache info` shows cache/index statistics (path, type, font count, size). Supports `--json` and `--index`.
- Count-only queries: `typg cache find --scripts latn --count` outputs just the number of matching fonts (useful for scripting).
- Quiet mode: `typg -q cache add ~/Fonts` suppresses informational stderr messages.
- **High-performance index** (optional `hpindex` feature): For 100k+ font collections, use LMDB-backed index instead of JSON cache. Build with `cargo build --features hpindex`, then use `--index` flag:
  - Ingest: `typg cache add --index ~/Fonts` (indexes to `~/.cache/typg/index/` by default).
  - Query: `typg cache find --index --scripts latn --features smcp` (O(K) tag intersection via Roaring Bitmaps).
  - List: `typg cache list --index` (lists all indexed fonts).
  - Clean: `typg cache clean --index` (removes entries for missing files).
  - Custom location: `typg cache add --index --index-path /path/to/index ~/Fonts`. Respects `TYPOG_INDEX_PATH` env var.
- Remote querying: `typg serve --bind 127.0.0.1:8765` exposes `/health` and `/search` (POST JSON with paths/filters, set `paths_only:true` to get a newline-ready list). With hpindex feature, `/search` also accepts `use_index:true` and optional `index_path` to query the LMDB index instead of live scanning.

### Python (`typg` / `typgpy`)
```python
from typg import find, find_paths

matches = find(paths=["~/Fonts"], scripts=["latn"], features=["smcp"], variable=True)
for m in matches:
    print(m["path"], m["names"][0])

paths_only = find_paths(paths=["~/Fonts"], scripts=["latn"])
print("first path:", paths_only[0])

weighted = find(paths=["~/Fonts"], weight="400-700", width="5")
print("weighted matches:", len(weighted))

family = find(paths=["~/Fonts"], family_class="sans")
print("sans-serif matches:", len(family))

# Indexed search (requires hpindex feature in build)
try:
    from typg import find_indexed, list_indexed, count_indexed
    matches = find_indexed(index_path="~/.cache/typg/index", scripts=["latn"])
    count = count_indexed(index_path="~/.cache/typg/index")
    all_fonts = list_indexed(index_path="~/.cache/typg/index")
except ImportError:
    print("hpindex feature not enabled in build")
```

CLI parity from Python: `typgpy find --paths ~/Fonts --scripts latn --features smcp --variable --paths_only True`.

### Rust library (`typg-core`)
```rust
use std::path::PathBuf;
use typg_core::query::Query;
use typg_core::search::{search, SearchOptions};
use typg_core::tags::tag4;

let paths = vec![PathBuf::from("~/Fonts")];
let query = Query::new().with_features(vec![tag4("smcp").unwrap()]);
let matches = search(&paths, &query, &SearchOptions::default())?;
```

## Migration (fontgrep/fontgrepc)
- `typg find` mirrors `fontgrep find` flags already shipped (axes/features/scripts/tables/name/regex/codepoints/text, STDIN, system fonts, JSON/NDJSON, columns/plain).
- Cache subcommands mirror fontgrepc (`add/list/find/clean`) using a JSON cache file; keep using fontgrepc if you need SQLite today.
- Weight/class/width shorthands are still planned; use explicit tag filters for now.
- Output layout matches fontgrepc NDJSON; column widths are stable for downstream tooling.

## Build & release
- macOS local builds: `./build.sh [release|debug]` emits the `typg` Rust CLI and the `typg` Python wheel/`typgpy` CLI (version comes from git tags via hatch-vcs).
- Manual publishing: `./publish.sh [publish|rust-only|python-only|sync|check]` syncs Cargo crate versions to the current semver git tag, then pushes crates to crates.io and wheels to PyPI when credentials are present.
- GitHub Actions: `release.yml` triggers on `vN.N.N` tags to build manylinux/macOS/Windows wheels, publish to PyPI, publish crates (`typg-core`, `typg-cli`, `typg-python`) to crates.io, and attach wheels to the GitHub release.

## Migration notes (fontgrep/fontgrepc → typg)
- Flags mirror fontgrep; see `docs/spec.md` for any divergence.
- Cache subcommands are available: `typg cache add/list/find/clean` manage a JSON cache file; live scans remain available via `typg find`.
- NDJSON output matches fontgrepc conventions so log pipelines stay compatible.

## Contributing
- Keep functions short and prefer deleting over adding.
- Match fontgrep/fontgrepc semantics unless a deviation is documented in `docs/spec.md`.
- Add tests (property for parsers, snapshot for CLI) before marking tasks done.

## Project links
- Plan: `TASKS.md`
- Tasks: `TODO.md`
- Spec: `docs/spec.md`
- Architecture: `ARCHITECTURE.md`
- Work log: `WORK.md`
</document_content>
</document>

<document index="9">
<source>TASKS.md</source>
<document_content>
# typg Plan

made by FontLab https://www.fontlab.com/

## Scope (one sentence)
Build typg as an ultra-fast font search/discovery toolkit (Rust core + CLI + Python API) that matches fontgrep/fontgrepc capabilities while reusing typf/fontations assets wherever possible.

## Phase -1 — Housekeeping (status)
- [x] Create TASKS.md, WORK.md, and CHANGELOG.md for project tracking

## Phase 0 — Reuse inventory and early decisions

### typf repo (linked/typf)
- Crates to mine: `typf-core` (render pipeline types), `typf-fontdb` (font index/cache), `typf-unicode` (script detection), `typf-input` (path handling). Prefer reusing `typf-fontdb` indexes to avoid duplicating catalog builds.
- Decision: Inspect `typf-fontdb` APIs first for catalog ingestion; only fork if dependency footprint is too large for a lean search-only crate.

### fontgrep (linked/fontgrep)
- Provides battle-tested CLI syntax and filters (axes, features, scripts, tables, Unicode ranges, name regex, text coverage). Plan to mirror flag semantics and reuse parsing patterns.
- Decision: Copy/adapt CLI flag mapping and progressive output structure; avoid taking the crate as a direct dependency to keep control over query execution.

### fontgrepc (linked/fontgrepc)
- Adds SQLite-backed cache and bulk ingest (`add`, `find`, `list`, `clean`) with job parallelism. Useful reference for cache schema and cache-vs-live search UX.
- Decision: Borrow schema and cache management patterns; implement our own cache module to keep typg’s dependency tree minimal.

### fontations (linked/fontations)
- Core crates `read-fonts`, `write-fonts`, and `skrifa` deliver zero-copy parsing plus glyph/metadata access; match typg’s need for fast metadata extraction.
- Decision: Build typg-core on `read-fonts`/`skrifa`; keep `write-fonts` optional (only if we need patching/export flows).

### fontlift (linked/fontlift)
- Cross-platform font discovery/installation layers with OS-specific implementations and CLI. Valuable for enumerating system font roots cleanly on macOS/Windows.
- Decision: Reuse platform enumeration logic (without install/remove features) to seed search paths safely.

### Additional external crates
- `fontdb` offers a lightweight, cacheable font metadata index that can be prebuilt and queried without disk rescans; keep as fallback if typf-fontdb coupling is too heavy.

## Success metrics (initial)
- P50 search latency: ≤50 ms over 10k fonts on SSD; ≤250 ms over 100k-font cache.
- Feature parity: supports all fontgrep/fontgrepc query flags and JSON/NDJSON output.
- Catalog freshness: cache rebuild detects file changes within one run; no stale results after updates.
- Resource footprint: CLI binary ≤10 MB release build; memory ≤256 MB during a 100k-font query.

## Near-term steps (Phase 1 preview)
- [x] Catalog fontgrep/fontgrepc flags against desired typg behavior and capture in docs/spec.md.
- [x] Choose crate layout (`typg-core`, `typg-cli`, `typg-python`) and dependency boundaries.
- [x] Draft search use-cases (family/name, axes presence, glyph coverage, Unicode ranges, weight/class filters) and map to APIs.

## Phase 2 — Rust core (status)
- [x] Scaffolded `typg-core` with a filesystem discovery stub and tests to exercise font extension filtering.
- [x] Implemented query parsers and filter matching in `typg-core`.
- [x] Added baseline search pipeline (metadata extraction + streaming JSON/NDJSON output).
- [x] Documented why typf-fontdb is not yet used for caching (no persistent index, in-memory only) and added a cached-filter path in `typg-core` to accept precomputed metadata without touching the filesystem.

## Phase 3 — CLI (status)
- [x] `typg-cli` argument surface tracks fontgrep/fontgrepc for `find`; cache subcommands now ship (JSON cache file with add/list/find/clean).
- [x] Columnar/colorized output for `find` with JSON/NDJSON toggles, plus help coverage.

## Phase 3 — Rust CLI (status)
- [x] `typg-cli find` now accepts STDIN paths and a `--system-fonts` toggle while retaining recursive walk defaults; added `--text` filter to cover fontgrep parity.
- [x] Cache subcommands (`add/list/find/clean`) now ingest/search JSON cache files; job controls land alongside cache ingest for parity.

## Phase 4 — Python bindings (status)
- [x] Added `typg-python` crate with PyO3 bindings that expose `find` and cached filtering, returning dict-friendly structures for Fire/CLI use.
- [x] Created `pyproject.toml` (maturin) and Fire-based CLI wrapper (`typgpy`) under `python/typg_python`.
- [x] Added pytest coverage for typg-python (live scan + system font env override) using shared test fonts.

## Phase 5 — Docs & CI (status)
- [x] Updated README with overview/install/usage across Rust CLI, Python bindings, and library surfaces, plus migration guidance for fontgrep/fontgrepc users.
- [x] Expanded ARCHITECTURE.md to spell out data flow, typf/fontations reuse points, and current limitations.
- [x] Added CI workflow patterned after typf/twasitors (lint gate, cross-OS Rust tests, Python binding build/tests).
- [x] Logged microbenchmarks and current limitations in WORK.md/CHANGELOG.md for traceability.

## Phase 6 — Integrations & Service (status)
- [x] Path-only output flags and Python `find_paths` helper added so typg results feed directly into typf/fontlift/testypf pipelines without post-processing.
- [x] Optional HTTP server (`typg serve`) exposes `/health` and `/search` (JSON or paths-only) for remote querying once core parity is achieved.

## Phase 7 — Parity polish (status)
- [x] Add OS/2 classification filters (weight and width) across core, CLI/cache, Python bindings, and HTTP server with tests.
- [x] Quiet clippy lint noise in typg-python by reducing argument lists (shared query params helper).
- [x] Harden validation and health checks with targeted tests (e.g., reject jobs=0, assert `/health` endpoint).

## Phase 8 — Validation polish (status)
- [x] Cover HTTP `/search` error paths (missing paths, jobs=0) with Axum tests.
- [x] Guard `--paths` output against ANSI when color is forced; add CLI test.
- [x] Exercise Python path-only surfaces (`find_paths`, `paths_only` flag in CLI) with fixtures.

## Phase 9 — Classification polish & hygiene (status)
- [x] Add OS/2 family-class filter (major + subclass, named aliases) across core/CLI/cache/HTTP/Python with tests.
- [x] Refresh docs/spec/README examples to show family-class usage.
- [x] Ignore Python build artifacts and remove stray compiled outputs from the repo.

## Phase 10 — Metadata polish (status)
- [x] Pull Unicode name-table entries (family/typo/full/PostScript) into search metadata so name regex filters hit real names instead of filenames.
- [x] Deduplicate and sort tags/codepoints/name lists for deterministic cache/CLI output.
- [x] Fix integration fixtures to find repo-level test fonts and add name-filter regression tests across CLI/core.

## Phase 11 — High-Performance Embedded Index (status)

**Objective:** Replace JSON cache with specialized embedded database for O(K) query performance on massive font collections (>100k fonts).

### Rationale
The JSON cache imposes O(N) linear scan on every query, parsing overhead at startup, and unbounded memory usage. This phase introduces:
- **LMDB via `heed`**: Memory-mapped, zero-copy reads, ACID transactions
- **Roaring Bitmaps**: Ultra-fast set intersections for tag queries
- **bincode serialization**: Fast, compact metadata storage (simplified from rkyv)
- **Roaring Bitmap cmap**: Deterministic Unicode coverage filtering (simplified from Cuckoo Filter)

### Expected Impact
- **Query speed**: 100x-1000x speedup for selective queries on large collections
- **Memory efficiency**: Usage independent of total font count
- **Scalability**: Millisecond responsiveness on 100k+ font libraries

### Architecture

#### Database Layout (LMDB Environment)
```
DB_METADATA:      FontID (u64) -> bincode<IndexedFontMeta>
DB_INVERTED_TAGS: Tag (u32)    -> RoaringBitmap<FontID>
DB_PATH_TO_ID:    PathHash     -> (FontID, mtime)
```

#### Ingestion Pipeline (`cache add --index`)
1. Use `heed` write transactions for atomic updates
2. Check `DB_PATH_TO_ID` for incremental updates via xxhash + mtime
3. Store Roaring Bitmap of cmap codepoints in metadata
4. Serialize metadata with bincode into `DB_METADATA`
5. Update Roaring Bitmaps in `DB_INVERTED_TAGS`
6. Run `RoaringBitmap::run_optimize()` before commit

#### Query Execution (`cache find --index`)
1. Use `heed` read transactions (non-blocking)
2. Retrieve bitmaps for query tags, perform intersection
3. Iterate result FontIDs, deserialize metadata via bincode
4. Apply numeric filters (weight/width/family-class) directly
5. For text queries, check Roaring Bitmap cmap coverage
6. Apply name regex on metadata strings

### Implementation Tasks (Completed)
- [x] Add `heed`, `roaring`, `bincode`, `bytemuck`, `xxhash-rust`, `byteorder` dependencies to `typg-core` (simplified from original plan)
- [x] Create `typg-core/src/index.rs` with core types (`FontID`, `FontIndex`, `IndexedFontMeta`)
- [x] Implement inverted index for tag → RoaringBitmap<FontID> mapping
- [x] Implement Roaring Bitmap for cmap coverage (simplified from Cuckoo Filter)
- [x] Implement `IndexWriter` for atomic ingestion pipeline with mtime-based incremental updates
- [x] Implement `IndexReader` for optimized query execution with bitmap intersection
- [x] Add `--index` and `--index-path` flags to CLI cache commands (`add`, `find`, `list`)
- [x] Maintain JSON cache as default fallback for backwards compatibility
- [x] Add unit tests for bitmap operations and integration tests for CLI

### Future Work
- [x] Add benchmarks comparing live scan vs Index performance (benches/cache_vs_index.rs)
- [x] Update Python bindings for indexed search (`find_indexed()`, `list_indexed()`, `count_indexed()`)
</document_content>
</document>

<document index="10">
<source>TODO.md</source>
<document_content>
# typg TODO

made by FontLab https://www.fontlab.com/

**Scope:** In this folder ( /Users/adam/Developer/vcs/github.fontlaborg/typg ) Build `typg`, a sister project to @./linked/typf/ , focused on ultra-fast font search/discovery with a Rust library, CLI, and Python API. 

## Phase -1 – Housekeeping

- [x] Create `TASKS.md` to capture scope, phases, and reuse decisions
- [x] Create `WORK.md` with a simple iteration log (date, goal, tests run)
- [x] Create `CHANGELOG.md` seeded with initial planning entry (v0.0.0, not released)

## Phase 0 – Groundwork

- [x] Inventory relevant crates inside @./linked/typf/ for potential reuse instead of reimplementing logic
- [x] Inventory and analyze @./linked/fontgrep/ and @./linked/fontgrepc/ for potential reuse instead of reimplementing logic
- [x] Inventory and analyze @./linked/fontations/ for potential reuse instead of reimplementing logic
- [x] Inventory and analyze @./linked/fontlift/ for potential reuse instead of reimplementing logic
- [x] Capture findings + tech choices in `TASKS.md` for typg 
- [x] Define success metrics (latency per query, supported filters, CLI parity with fontgrep/fontgrepc)

## Phase 1 – Source Analysis & Specification

- [x] Deep-dive @./linked/fontgrep/ and @./linked/fontgrepc/ to catalog every flag, filter, and output format
- [x] Don’t build a dependency on @./linked/fontgrep/ and @./linked/fontgrepc/ (just copy & adapt code from these two), but you may depend on their dependencies. 
- [x] Produce a comparison matrix (fontgrep/fontgrepc/typg) and store it in `docs/spec.md`
- [x] Specify crate layout (e.g., `typg-core`, `typg-cli`, `typg-python`) and dependency relationships
- [x] Document search use-cases (family name, axes presence, glyph coverage, Unicode range, weight/class filters)
- [x] Update @./CLAUDE.md so it’s specific to this project, explains briefly its objective and organization and coding style
- [x] Update @./README.md so that it describes the planned project in detail (what, how, why; how to install, how to use, how to contribute)

## Phase 2 – Rust Library
- [x] Scaffold `typg-core` crate with typf-compatible font discovery abstractions (build.rs to reuse fontdb indexes?)
- [x] Implement parsers for CLI query syntax (borrow from fontgrep) with property tests
- [x] Implement search pipeline: font loading → metadata extraction → filter evaluation → result ranking
- [x] Documented why typf-fontdb is not used yet (in-memory only, no persistent cache) and added a cached-filter hook in typg-core for precomputed metadata
- [x] Add streaming JSON/JSONL output plus structured Rust types
- [x] Write criterion benchmarks comparing against original fontgrep; target parity before refactors

## Phase 3 – Rust CLI
- [x] Build `typg-cli` crate with argument parser (clap/lexopt) mirroring fontgrep/fontgrepc options for `find`, including `--jobs`
- [x] `typg-cli` find subcommand scaffolded (axes/features/scripts/tables/name/codepoints/variable flags + json/ndjson/plain output)
- [x] Ensure CLI supports recursive directory walks, system font discovery, and STDIN/STDOUT piping
- [x] Implement colorized/columnar output plus `--json` / `--ndjson` toggles
- [x] Add snapshot tests for CLI help plus representative queries using `typf/test-fonts`
- [x] Add cache subcommands (`add/list/clean/find`) mirroring fontgrepc once cache module lands (JSON cache file, dedup + clean)

## Phase 4 – Python Bindings & Fire CLI
- [x] Design minimal PyO3 bindings that wrap `typg-core` search API (async-friendly if needed)
- [x] Provide `fire`-based CLI mirroring Rust CLI semantics (optionally Typer if richer UX needed)
- [x] Publish packaging metadata (pyproject via `maturin`) and document install flow in README
- [x] Add pytest suite hitting bindings + CLIs with golden files shared with Rust tests

## Phase 5 – Documentation & Verification
- [x] Update `README.md` with overview, install, usage examples (Rust, CLI, Python)
- [x] Create `ARCHITECTURE.md` describing data flow + reuse points from typf
- [x] Add CI workflow referencing typf + twasitors pipelines
- [x] Add release workflow to publish crates (typg-core/typg-cli/typg-python) and PyPI wheels on semver tags
- [x] Document migration guidance for existing fontgrep/fontgrepc users
- [x] Record benchmarks + known limitations in `WORK.md` and `CHANGELOG.md`

## Phase 6 – Stretch
- [x] Explore integration hooks so typg can directly feed fonts into typf/fontlift/testypf workflows
- [x] Add optional gRPC/HTTP server mode for remote querying (only after core parity achieved)

## Phase 7 – Parity polish
- [x] Add OS/2 classification filters (weight + width) end-to-end (core, CLI/cache, Python, HTTP) with tests.
- [x] Quiet clippy lint noise in typg-python by consolidating query params to avoid `too_many_arguments`.
- [x] Harden validation and health checks with explicit tests (jobs=0 rejection, `/health` endpoint).

## Phase 8 – Validation polish

- [x] Add Axum tests for HTTP `/search` errors (no paths, jobs=0) to lock validation.
- [x] Ensure `--paths` output stays ANSI-free even when `--color always`; cover with CLI test.
- [x] Add Python tests for `find_paths` and CLI `paths_only` to guarantee path-only surfaces.

## Phase 9 – Classification & Hygiene
- [x] Add OS/2 family-class filtering (major + subclass aliases) across core/CLI/cache/HTTP/Python with tests.
- [x] Document family-class usage in README/spec/examples.
- [x] Ignore Python build artifacts and drop stray compiled outputs from the repo.

## Phase 10 – Metadata polish
- [x] Read Unicode name-table strings (family/typo/full/PostScript) into metadata so name regex filters match real names, not just filenames.
- [x] Deduplicate and sort metadata lists (tags, codepoints, names) for deterministic cache/CLI output.
- [x] Point integration fixtures at repo-level test fonts and add name-filter regression tests (core + CLI).

## Phase 11 – High-Performance Embedded Index

### Core Infrastructure
- [x] Add `heed`, `roaring`, `bytemuck`, `xxhash-rust`, `bincode`, `byteorder` dependencies to `typg-core/Cargo.toml` (simplified from original plan)
- [x] Create `typg-core/src/index.rs` module with core types:
  - [x] `FontID` (u64) for persistent font identification
  - [x] `FontIndex` struct holding LMDB environment and database handles
  - [x] `IndexedFontMeta` for serialized font metadata

### Inverted Index Implementation
- [x] Implement `DB_INVERTED_TAGS` database (Tag → RoaringBitmap<FontID>)
- [x] Add methods for inserting tags during ingestion
- [x] Add methods for bitmap intersection during queries

### Unicode Coverage Filtering
- [x] Implement Roaring Bitmap for cmap coverage (simplified from Cuckoo Filter)
- [x] Store serialized Roaring Bitmap in `DB_METADATA`
- [x] Add fast-path codepoint checking during queries

### Metadata Storage (bincode)
- [x] Define `IndexedFontMeta` with serde derives (simplified from rkyv)
- [x] Implement bincode serialization/deserialization
- [x] Store font paths, names, classification data

### Path-to-ID Mapping
- [x] Implement `DB_PATH_TO_ID` for incremental updates
- [x] Store path hash → (FontID, mtime) mappings via xxhash
- [x] Use mtime comparison to skip unchanged files

### Ingestion Pipeline (`IndexWriter`)
- [x] Implement atomic write transactions
- [x] Support parallel font processing with rayon
- [x] Merge new entries with existing index (update-in-place)

### Query Execution (`IndexReader`)
- [x] Implement read transactions (non-blocking)
- [x] Query planner: tag bitmap intersection first
- [x] Apply numeric filters (weight/width/family-class)
- [x] Apply Roaring Bitmap cmap check for text queries
- [x] Apply name regex on metadata strings

### CLI Integration
- [x] Add `--index` flag to `cache add` (opt-in index mode)
- [x] Add `--index` flag to `cache find` (opt-in index mode)
- [x] Add `--index` flag to `cache list` (opt-in index mode)
- [x] Maintain JSON cache as default for backwards compatibility
- [x] Add `--index-path` flag for custom index location

### Testing
- [x] Unit tests for bitmap operations
- [x] Unit tests for cmap bitmap coverage
- [x] Unit tests for incremental update detection
- [x] Integration tests for full index round-trip (CLI)

### Future Work
- [x] Python bindings for indexed search (`find_indexed()`, `list_indexed()`, `count_indexed()`)
- [x] Cache clean --index support with `prune_missing()` for LMDB
- [x] Criterion benchmarks: live scan vs LMDB index query speed (benches/cache_vs_index.rs)
- [x] HTTP server `/search` index support (`use_index` and `index_path` fields)
- [ ] Benchmark: index build time on 10k/100k fonts (requires large font collection)

**Implementation Note:** Simplified from original plan by using bincode instead of rkyv (simpler API, sufficient performance) and Roaring Bitmap for cmap instead of Cuckoo Filter (deterministic, no false positives).
</document_content>
</document>

<document index="11">
<source>build.sh</source>
<document_content>
#!/bin/bash
# build.sh - robust build script for typg on macOS
# made by FontLab https://www.fontlab.com/

set -euo pipefail

# Configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$SCRIPT_DIR"
TARGET_DIR="$PROJECT_ROOT/target"
BUILD_TYPE="${1:-release}"  # Default to release build
PYTHON_VERSION="${2:-3.13}" # Default Python version for bindings
SKIP_PYTHON=false           # Set to true if maturin is missing

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Logging functions
log_info() {
    echo -e "${BLUE}[INFO]${NC} $1"
}

log_success() {
    echo -e "${GREEN}[SUCCESS]${NC} $1"
}

log_warning() {
    echo -e "${YELLOW}[WARNING]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1"
}

# Usage information
usage() {
    cat << EOF
Usage: $0 [BUILD_TYPE] [PYTHON_VERSION]

Build script for typg - ultra-fast font search/discovery toolkit

BUILD_TYPE:
    debug      Build with debugging information (faster compile)
    release    Optimized release build (default)
    check      Run checks without building
    clean      Clean build artifacts

PYTHON_VERSION:
    3.10, 3.11, 3.12, or 3.13 (default: 3.13)
    Used only for Python bindings compilation

Examples:
    $0                    # Release build with Python 3.13
    $0 debug             # Debug build with Python 3.13
    $0 release 3.12      # Release build with Python 3.12
    $0 clean             # Clean build artifacts

EOF
}

# Check dependencies
check_dependencies() {
    log_info "Checking dependencies..."
    
    local missing_deps=()
    
    # Check for Rust toolchain
    if ! command -v cargo >/dev/null 2>&1; then
        missing_deps+=("cargo")
    fi
    
    if ! command -v rustc >/dev/null 2>&1; then
        missing_deps+=("rustc")
    fi
    
    # Check for Python
    if ! command -v "python${PYTHON_VERSION}" >/dev/null 2>&1; then
        missing_deps+=("python${PYTHON_VERSION}")
    fi
    
    # Check for maturin (needed for Python bindings, warn only)
    if ! command -v maturin >/dev/null 2>&1; then
        log_warning "maturin not found - Python bindings will be skipped"
        log_info "  Install with: pip${PYTHON_VERSION} install maturin"
        SKIP_PYTHON=true
    fi

    if [[ ${#missing_deps[@]} -gt 0 ]]; then
        log_error "Missing dependencies: ${missing_deps[*]}"
        log_info "Install missing dependencies:"

        if [[ " ${missing_deps[*]} " =~ " cargo " ]] || [[ " ${missing_deps[*]} " =~ " rustc " ]]; then
            log_info "  Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh"
        fi

        if [[ " ${missing_deps[*]} " =~ " python${PYTHON_VERSION} " ]]; then
            log_info "  Python: Install via Homebrew or python.org"
        fi

        return 1
    fi
    
    log_success "All dependencies found"
    return 0
}

# Detect macOS architecture
detect_arch() {
    local arch=$(uname -m)
    case "$arch" in
        arm64)
            echo "aarch64-apple-darwin"
            ;;
        x86_64)
            echo "x86_64-apple-darwin"
            ;;
        *)
            log_error "Unsupported architecture: $arch"
            return 1
            ;;
    esac
}

# Clean build artifacts
clean_build() {
    log_info "Cleaning build artifacts..."
    
    # Clean Rust workspace
    cargo clean
    
    # Clean Python build artifacts if they exist
    if [[ -f "$PROJECT_ROOT/typg-python/pyproject.toml" ]]; then
        (cd "$PROJECT_ROOT/typg-python" && rm -rf build/ dist/ *.egg-info/)
    fi
    
    log_success "Build artifacts cleaned"
}

# Run checks without building
run_checks() {
    log_info "Running code quality checks..."
    
    local failed_checks=0
    
    # Rust formatting check (only check workspace members, exclude linked)
    log_info "Checking Rust formatting..."
    if cargo fmt -p typg-core -p typg-cli -p typg-python -- --check; then
        log_success "Formatting check passed"
    else
        log_error "Formatting check failed"
        ((failed_checks++))
    fi
    
    # Rust linting (only workspace members, exclude benchmarks and linked)
    log_info "Running Rust linter..."
    if cargo clippy -p typg-core -p typg-cli -p typg-python --all-targets --all-features -- -W warnings; then
        log_success "Linting check passed"
    else
        log_error "Linting check failed (warnings found)"
        ((failed_checks++))
    fi
    
    if [[ $failed_checks -eq 0 ]]; then
        log_success "All checks passed"
        return 0
    else
        log_warning "$failed_checks check(s) failed. Fix issues before proceeding with release build."
        return 1
    fi
}

# Build Rust components
build_rust() {
    local build_flags=""
    if [[ "$BUILD_TYPE" == "release" ]]; then
        build_flags="--release"
        log_info "Building Rust workspace in release mode..."
    else
        log_info "Building Rust workspace in debug mode..."
    fi
    
    # Build workspace (excluding Python bindings which need maturin)
    cargo build $build_flags --workspace --exclude typg-python
    
    log_success "Rust components built successfully"
}

# Build Python bindings
build_python() {
    log_info "Building Python bindings for Python $PYTHON_VERSION..."
    
    cd "$PROJECT_ROOT/typg-python"
    
    # Verify we're targeting the right Python version
    local python_exe="python${PYTHON_VERSION}"
    local python_lib_dir=$("$python_exe" -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
    
    if [[ -z "$python_lib_dir" ]]; then
        log_error "Could not determine Python library directory for Python $PYTHON_VERSION"
        return 1
    fi
    
    log_info "Using Python library directory: $python_lib_dir"
    
    # Build Python extension
    local target=$(detect_arch)
    log_info "Targeting architecture: $target"
    
    # Determine if we're building release or debug
    local maturin_release_flag=""
    if [[ "$BUILD_TYPE" == "release" ]]; then
        maturin_release_flag="--release"
    fi
    
    # Build using maturin
    maturin build $maturin_release_flag \
        --target $target \
        --interpreter "python${PYTHON_VERSION}" \
        --features extension-module
    
    cd "$PROJECT_ROOT"
    
    log_success "Python bindings built successfully"
}

# Install Python bindings locally (development)
install_python_dev() {
    log_info "Installing Python bindings in development mode..."
    
    cd "$PROJECT_ROOT/typg-python"
    
    # Try to install in development mode using maturin develop
    if maturin develop --features extension-module 2>/dev/null; then
        log_success "Python bindings installed in development mode via maturin develop"
    else
        # If maturin develop fails, build wheel and install with pip
        log_warning "No virtualenv detected, building wheel and installing with pip..."
        
        # Build wheel
        local target=$(detect_arch)
        local maturin_release_flag=""
        if [[ "$BUILD_TYPE" == "release" ]]; then
            maturin_release_flag="--release"
        fi
        
        maturin build $maturin_release_flag \
            --target $target \
            --interpreter "python${PYTHON_VERSION}" \
            --features extension-module
            
        # Find the built wheel and install it
        local wheel_file=$(find "$PROJECT_ROOT/target/wheels" -name "typg-*.whl" -type f | head -n1)
        if [[ -n "$wheel_file" ]]; then
            "pip${PYTHON_VERSION}" install "$wheel_file" --user
            log_success "Python bindings installed via pip install"
        else
            log_error "Could not find built wheel to install"
            cd "$PROJECT_ROOT"
            return 1
        fi
    fi
    
    cd "$PROJECT_ROOT"
}

# Verify build
verify_build() {
    log_info "Verifying build..."
    
    # Check if core library was built
    local target_path="$TARGET_DIR"
    if [[ "$BUILD_TYPE" == "release" ]]; then
        target_path="$target_path/release"
    else
        target_path="$target_path/debug"
    fi
    
    if [[ ! -f "$target_path/libtypg_core.a" ]] && [[ ! -f "$target_path/libtypg_core.rlib" ]]; then
        log_error "Core library not found at $target_path"
        return 1
    fi
    
    # Check CLI binary
    if [[ ! -f "$target_path/typg" ]]; then
        log_error "CLI binary not found at $target_path/typg"
        return 1
    fi
    
    log_success "Build verification passed"
}

# Main build function
main() {
    log_info "Starting typg build process..."
    log_info "Project root: $PROJECT_ROOT"
    log_info "Build type: $BUILD_TYPE"
    
    # Handle special commands
    case "$BUILD_TYPE" in
        help|--help|-h)
            usage
            exit 0
            ;;
        check|--check	)
            check_dependencies
            run_checks
            exit 0
            ;;
        clean|--clean)
            check_dependencies
            clean_build
            exit 0
            ;;
        debug|--debug)
			BUILD_TYPE="debug"
            # Valid build types, continue
            ;;
        release|--release)
			BUILD_TYPE="release"
            # Valid build types, continue
            ;;
        *)
            log_error "Unknown build type: $BUILD_TYPE"
            usage
            exit 1
            ;;
    esac
    
    # Dependencies check
    check_dependencies
    
    # Build components
    build_rust
    if [[ "$SKIP_PYTHON" != "true" ]]; then
        build_python
    fi
    
    # Verify
    verify_build
    
    log_success "Build completed successfully!"
    
    # Show artifact locations
    local target_path="$TARGET_DIR"
    if [[ "$BUILD_TYPE" == "release" ]]; then
        target_path="$target_path/release"
    else
        target_path="$target_path/debug"
    fi
    
    echo
    log_info "Build artifacts:"
    echo "  Core library: $target_path/libtypg_core.rlib"
    echo "  CLI binary: $target_path/typg"
    echo "  Python wheel: $TARGET_DIR/wheels/"
    echo
    
    log_info "To install Python bindings in development mode, run:"
    echo "  $0 dev-install $BUILD_TYPE $PYTHON_VERSION"
}

# Additional commands
case "${1:-}" in
    dev-install)
        BUILD_TYPE="${2:-release}"
        PYTHON_VERSION="${3:-3.13}"
        check_dependencies
        install_python_dev
        exit 0
        ;;
    *)
        main
        ;;
esac
</document_content>
</document>

<document index="12">
<source>publish.sh</source>
<document_content>
#!/bin/bash
# publish.sh - robust publishing script for typg workspace
# made by FontLab https://www.fontlab.com/

set -euo pipefail

# Configuration
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$SCRIPT_DIR"
DRY_RUN="${DRY_RUN:-false}"
BUILD_TYPE="${BUILD_TYPE:-release}"
PYTHON_VERSION="${PYTHON_VERSION:-3.12}"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Logging functions
log_info() {
    echo -e "${BLUE}[INFO]${NC} $1"
}

log_success() {
    echo -e "${GREEN}[SUCCESS]${NC} $1"
}

log_warning() {
    echo -e "${YELLOW}[WARNING]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1"
}

log_dry() {
    echo -e "${YELLOW}[DRY-RUN]${NC} $1"
}

# Usage information
usage() {
    cat << EOF
Usage: $0 [OPTIONS] [COMMAND]

Publish script for typg workspace - handles Rust crates and PyPI publishing

COMMANDS:
    publish          Publish all packages (default)
    rust-only        Publish only Rust crates
    python-only      Publish only Python package
    sync             Sync Cargo crate versions to git tag (no publish)
    check            Check if packages need publishing
    clean            Clean build artifacts

OPTIONS:
    --dry-run       Show what would be published without actually publishing
    --build-type    Build type: debug or release (default: release)
    --python-version Python version for bindings (default: 3.12)
    --help, -h      Show this help message

ENVIRONMENT VARIABLES:
    DRY_RUN=true    Enable dry-run mode
    BUILD_TYPE      Set build type
    PYTHON_VERSION  Set Python version

EXAMPLES:
    $0                           # Publish all packages
    $0 --dry-run                # Show what would be published
    $0 rust-only                 # Publish only Rust crates
    $0 python-only               # Publish only Python package
    $0 check                     # Check publishing status

EOF
}

# Check dependencies
check_dependencies() {
    log_info "Checking publishing dependencies..."
    
    local missing_deps=()
    
    # Check for Rust toolchain
    if ! command -v cargo >/dev/null 2>&1; then
        missing_deps+=("cargo")
    fi
    
    # Check for cargo-publish utilities
    if ! cargo publish --help >/dev/null 2>&1; then
        log_warning "cargo publish may not be available"
    fi
    
    # Check for Python and uv
    if ! command -v "python${PYTHON_VERSION}" >/dev/null 2>&1; then
        missing_deps+=("python${PYTHON_VERSION}")
    fi
    
    if ! command -v uv >/dev/null 2>&1; then
        missing_deps+=("uv")
    fi

    # Check for maturin
    if ! command -v maturin >/dev/null 2>&1; then
        missing_deps+=("maturin")
    fi

    # Check for hatch (hatch-vcs supplies the version)
    if ! command -v hatch >/dev/null 2>&1; then
        missing_deps+=("hatch")
    fi
    
    if [[ ${#missing_deps[@]} -gt 0 ]]; then
        log_error "Missing dependencies: ${missing_deps[*]}"
        log_info "Install missing dependencies:"
        
        if [[ " ${missing_deps[*]} " =~ " maturin " ]]; then
            log_info "  Maturin: pip${PYTHON_VERSION} install maturin"
        fi
        
        if [[ " ${missing_deps[*]} " =~ " uv " ]]; then
            log_info "  UV: pip install uv"
        fi

        if [[ " ${missing_deps[*]} " =~ " hatch " ]]; then
            log_info "  Hatch + hatch-vcs: pip install hatch hatch-vcs"
        fi

        if [[ " ${missing_deps[*]} " =~ " python${PYTHON_VERSION} " ]]; then
            log_info "  Python: Install via Homebrew or python.org"
        fi
        
        return 1
    fi

    if [[ -z "${CARGO_REGISTRY_TOKEN:-}" ]]; then
        log_warning "CARGO_REGISTRY_TOKEN not set; crates.io publish will fail"
    fi

    if [[ -z "${UV_PUBLISH_TOKEN:-}" && -z "${PYPI_TOKEN:-}" ]]; then
        log_warning "No PyPI token (UV_PUBLISH_TOKEN or PYPI_TOKEN) detected; PyPI publish may fail"
    fi
    
    log_success "All publishing dependencies found"
    return 0
}

# Get current version from Cargo.toml
get_crate_version() {
    local crate_dir="$1"
    local cargo_toml="$crate_dir/Cargo.toml"
    
    if [[ ! -f "$cargo_toml" ]]; then
        echo "0.0.0"
        return 1
    fi
    
    # Extract version using grep and sed
    grep '^version = ' "$cargo_toml" | sed 's/version = "\(.*\)"/\1/' | head -n1
}

# Get published version from crates.io
get_published_version() {
    local crate_name="$1"
    
    # Check if crate exists on crates.io using cargo search
    if cargo search "$crate_name" --limit 1 2>/dev/null | grep -q "$crate_name"; then
        # Extract current version from crates.io API
        curl -s "https://crates.io/api/v1/crates/$crate_name" 2>/dev/null | \
            jq -r '.crate.max_stable_version' 2>/dev/null || echo "unknown"
    else
        echo "none"
    fi
}

# Get published Python version from PyPI
get_python_published_version() {
    local package_name="$1"
    
    # Check PyPI API
    local response=$(curl -s "https://pypi.org/pypi/$package_name/json" 2>/dev/null || echo "")
    if [[ -n "$response" ]] && echo "$response" | jq -e '.info.version' >/dev/null 2>&1; then
        echo "$response" | jq -r '.info.version' 2>/dev/null || echo "unknown"
    else
        echo "none"
    fi
}

# Derive version from git tags via hatch-vcs (required)
get_semver_version() {
    if ! command -v hatch >/dev/null 2>&1; then
        log_error "hatch is required to compute the version via hatch-vcs"
        return 1
    fi

    local raw_version
    pushd "$PROJECT_ROOT/typg-python" >/dev/null
    if ! raw_version=$(uvx hatch version 2>/dev/null); then
        popd >/dev/null
        log_error "Failed to read version from hatch-vcs; ensure git tags exist"
        return 1
    fi
    popd >/dev/null

    # Strip leading 'v' if present
    raw_version="${raw_version#v}"

    if [[ "$raw_version" == *dev* ]] || [[ "$raw_version" == *+* ]]; then
        log_error "Version $raw_version is not a clean tag; create/checkout a semver tag before publishing"
        return 1
    fi

    echo "$raw_version"
}

# Write the resolved version into Cargo manifests and path deps
sync_versions_to_cargo() {
    local version="$1"

    log_info "Syncing Cargo.toml versions to ${version}"

    perl -0pi -e "s/^version = \"[^\"]*\"/version = \"${version}\"/m" "$PROJECT_ROOT/typg-core/Cargo.toml"
    perl -0pi -e "s/^version = \"[^\"]*\"/version = \"${version}\"/m" "$PROJECT_ROOT/typg-cli/Cargo.toml"
    perl -0pi -e "s/^version = \"[^\"]*\"/version = \"${version}\"/m" "$PROJECT_ROOT/typg-python/Cargo.toml"

    perl -0pi -e "s|typg-core = \{[^}]*path = \"\.\./typg-core\"[^}]*\}|typg-core = { version = \"=${version}\", path = \"../typg-core\" }|" "$PROJECT_ROOT/typg-cli/Cargo.toml"
    perl -0pi -e "s|typg-core = \{[^}]*path = \"\.\./typg-core\"[^}]*\}|typg-core = { version = \"=${version}\", path = \"../typg-core\" }|" "$PROJECT_ROOT/typg-python/Cargo.toml"
}

sync_only() {
    log_info "Syncing versions from git tag via hatch-vcs (no publish)"

    if ! command -v hatch >/dev/null 2>&1; then
        log_error "hatch is required to resolve version from git tags"
        return 1
    fi

    local resolved_version
    resolved_version=$(get_semver_version)
    log_info "Resolved version: ${resolved_version}"

    sync_versions_to_cargo "$resolved_version"

    log_success "Cargo manifest versions updated to ${resolved_version}"
}

# Check if version needs publishing
check_version_needs_publish() {
    local current="$1"
    local published="$2"
    local package_name="$3"
    
    case "$published" in
        "none")
            log_info "$package_name has not been published yet"
            return 0
            ;;
        "unknown")
            log_warning "Could not determine published version for $package_name"
            return 2
            ;;
        *)
            if [[ "$current" == "$published" ]]; then
                log_info "$package_name version $current is already published"
                return 1
            else
                log_info "$package_name needs publishing (current: $current, published: $published)"
                return 0
            fi
            ;;
    esac
}

# Check if repository is clean for publishing
check_repo_clean() {
    log_info "Checking repository state..."
    
    # Check git status
    if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
        log_error "Repository has uncommitted changes"
        log_info "Commit or stash changes before publishing"
        return 1
    fi
    
    # Check if we're on main branch
    local current_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
    if [[ "$current_branch" != "main" ]] && [[ "$current_branch" != "master" ]]; then
        log_warning "Not on main/master branch (current: $current_branch)"
    fi
    
    log_success "Repository state is clean"
    return 0
}

# Build packages before publishing
build_packages() {
    log_info "Building packages for publishing..."
    
    # Use existing build script
    if [[ -f "$PROJECT_ROOT/build.sh" ]]; then
        if ! bash "$PROJECT_ROOT/build.sh" "$BUILD_TYPE" "$PYTHON_VERSION"; then
            log_error "Build failed"
            return 1
        fi
    else
        log_error "build.sh not found"
        return 1
    fi
    
    log_success "Build completed successfully"
}

# Publish Rust crate
publish_rust_crate() {
    local crate_dir="$1"
    local crate_name="$2"
    
    log_info "Publishing Rust crate: $crate_name"
    
    if [[ "$DRY_RUN" == "true" ]]; then
        log_dry "Would publish: $crate_name from $crate_dir"
        return 0
    fi
    
    cd "$crate_dir"
    
    # Ensure the crate builds
    if ! cargo build --release; then
        log_error "Failed to build $crate_name"
        cd "$PROJECT_ROOT"
        return 1
    fi
    
    # Publish to crates.io
    if cargo publish; then
        log_success "Published $crate_name to crates.io"
        cd "$PROJECT_ROOT"
        return 0
    else
        log_error "Failed to publish $crate_name"
        cd "$PROJECT_ROOT"
        return 1
    fi
}

# Publish Python package
publish_python_package() {
    local package_dir="$1"
    local package_name="$2"
    
    log_info "Publishing Python package: $package_name"
    
    if [[ "$DRY_RUN" == "true" ]]; then
        log_dry "Would publish: $package_name from $package_dir"
        return 0
    fi
    
    cd "$package_dir"
    
    # Build Python package
    if ! maturin build --release --features extension-module; then
        log_error "Failed to build Python package"
        cd "$PROJECT_ROOT"
        return 1
    fi
    
    # Find the built wheel
    local wheel_file=$(find "$PROJECT_ROOT/target/wheels" -name "typg-*.whl" -type f | head -n1)
    if [[ -z "$wheel_file" ]]; then
        log_error "Could not find built Python wheel"
        cd "$PROJECT_ROOT"
        return 1
    fi

    # Publish to PyPI using uv
    local publish_token="${PYPI_TOKEN:-${UV_PUBLISH_TOKEN:-}}"
    local publish_args=()
    if [[ -n "$publish_token" ]]; then
        publish_args+=(--token "$publish_token")
    fi

    if uv publish "${publish_args[@]}" "$wheel_file"; then
        log_success "Published $package_name to PyPI"
        cd "$PROJECT_ROOT"
        return 0
    else
        log_error "Failed to publish $package_name"
        cd "$PROJECT_ROOT"
        return 1
    fi
}

# Main publish function
publish_all() {
    local rust_only="${1:-false}"
    local python_only="${2:-false}"
    
    log_info "Starting publishing process..."
    log_info "Dry run: $DRY_RUN"
    log_info "Build type: $BUILD_TYPE"
    
    # Check repository state
    check_repo_clean
    
    # Check dependencies
    check_dependencies

    # Resolve version from git tags via hatch-vcs and sync manifests
    local resolved_version
    resolved_version=$(get_semver_version)
    log_info "Using version: ${resolved_version} (from git tags via hatch-vcs)"
    sync_versions_to_cargo "$resolved_version"
    
    # Check what needs publishing
    local needs_publishing=false
    local rust_needs=false
    local python_needs=false
    
    # Check Rust crates
    if [[ "$python_only" != "true" ]]; then
        log_info "Checking Rust crate versions..."
        
        for crate in typg-core typg-cli typg-python; do
            local current_version=$(get_crate_version "$PROJECT_ROOT/$crate")
            local published_version=$(get_published_version "$crate")
            
            if check_version_needs_publish "$current_version" "$published_version" "$crate"; then
                needs_publishing=true
                rust_needs=true
                break
            fi
        done
    fi
    
    # Check Python package
    if [[ "$rust_only" != "true" ]]; then
        log_info "Checking Python package version..."
        
        local current_python_version=$(get_crate_version "$PROJECT_ROOT/typg-python")
        local published_python_version=$(get_python_published_version "typg")
        
        if check_version_needs_publish "$current_python_version" "$published_python_version" "typg-python"; then
            needs_publishing=true
            python_needs=true
        fi
    fi
    
    if [[ "$needs_publishing" != "true" ]]; then
        log_success "All packages are up to date - nothing to publish"
        return 0
    fi
    
    # Build packages
    build_packages
    
    # Publish in correct order
    local failed_packages=()
    
    # First publish typg-core (dependency of others)
    if [[ "$python_only" != "true" ]] && [[ "$rust_needs" == "true" ]]; then
        local core_version=$(get_crate_version "$PROJECT_ROOT/typg-core")
        local core_published=$(get_published_version "typg-core")
        
        if check_version_needs_publish "$core_version" "$core_published" "typg-core"; then
            if ! publish_rust_crate "$PROJECT_ROOT/typg-core" "typg-core"; then
                failed_packages+=("typg-core")
            fi
        fi
        
        # Wait a bit for crates.io to update
        sleep 3
    fi
    
    # Then publish other Rust crates
    for crate in typg-cli typg-python; do
        if [[ "$python_only" != "true" ]] && [[ "$rust_needs" == "true" ]]; then
            local current_version=$(get_crate_version "$PROJECT_ROOT/$crate")
            local published_version=$(get_published_version "$crate")

            if check_version_needs_publish "$current_version" "$published_version" "$crate"; then
                if ! publish_rust_crate "$PROJECT_ROOT/$crate" "$crate"; then
                    failed_packages+=("$crate")
                fi
            fi

            sleep 2
        fi
    done
    
    # Finally publish Python package
    if [[ "$rust_only" != "true" ]] && [[ "$python_needs" == "true" ]]; then
        local current_python_version=$(get_crate_version "$PROJECT_ROOT/typg-python")
        local published_python_version=$(get_python_published_version "typg")
        
        if check_version_needs_publish "$current_python_version" "$published_python_version" "typg (PyPI)"; then
            if ! publish_python_package "$PROJECT_ROOT/typg-python" "typg"; then
                failed_packages+=("typg (PyPI)")
            fi
        fi
    fi
    
    # Report results
    if [[ ${#failed_packages[@]} -eq 0 ]]; then
        log_success "All packages published successfully!"
        return 0
    else
        log_error "Failed to publish: ${failed_packages[*]}"
        log_error "Publishing aborted - check logs above for details"
        return 1
    fi
}

# Check publishing status
check_status() {
    log_info "Checking publishing status..."
    
    log_info "Rust crates:"
    for crate in typg-core typg-cli typg-python; do
        local current_version=$(get_crate_version "$PROJECT_ROOT/$crate")
        local published_version=$(get_published_version "$crate")
        local status=""
        
        if check_version_needs_publish "$current_version" "$published_version" "$crate"; then
            status="${YELLOW}NEEDS PUBLISH${NC}"
        else
            status="${GREEN}UP TO DATE${NC}"
        fi
        
        echo -e "  $crate: $current_version (published: $published_version) [$status]"
    done
    
    log_info "Python package:"
    local current_python_version=$(get_crate_version "$PROJECT_ROOT/typg-python")
    local published_python_version=$(get_python_published_version "typg")
    local python_status=""
    
    if check_version_needs_publish "$current_python_version" "$published_python_version" "typg-python"; then
        python_status="${YELLOW}NEEDS PUBLISH${NC}"
    else
        python_status="${GREEN}UP TO DATE${NC}"
    fi
    
    echo -e "  typg (PyPI): $current_python_version (published: $published_python_version) [$python_status]"
}

# Main execution
main() {
    local command="${1:-publish}"
    local rust_only=false
    local python_only=false
    
    # Parse arguments
    while [[ $# -gt 0 ]]; do
        case "$1" in
            --dry-run)
                export DRY_RUN=true
                shift
                ;;
            --build-type)
                export BUILD_TYPE="$2"
                shift 2
                ;;
            --python-version)
                export PYTHON_VERSION="$2"
                shift 2
                ;;
            --help|-h)
                usage
                exit 0
                ;;
            publish|rust-only|python-only|check|clean|sync)
                command="$1"
                shift
                ;;
            *)
                log_error "Unknown option: $1"
                usage
                exit 1
                ;;
        esac
    done
    
    # Set flags for specific commands
    case "$command" in
        rust-only)
            rust_only=true
            ;;
        python-only)
            python_only=true
            ;;
        sync)
            command="sync"
            ;;
    esac
    
    # Execute command
    case "$command" in
        publish|rust-only|python-only)
            publish_all "$rust_only" "$python_only"
            ;;
        sync)
            sync_only
            ;;
        check)
            check_status
            ;;
        clean)
            log_info "Cleaning build artifacts..."
            bash "$PROJECT_ROOT/build.sh" clean
            ;;
        *)
            log_error "Unknown command: $command"
            usage
            exit 1
            ;;
    esac
}

# Run main function with all arguments
main "$@"
</document_content>
</document>

<document index="13">
<source>typg-cli/Cargo.toml</source>
<document_content>
[package]
name = "typg-cli"
version = "1.0.1"
edition = "2021"
authors = ["FontLab"]
description = "CLI for typg (made by FontLab https://www.fontlab.com/)"
license = "MIT"
homepage = "https://www.fontlab.com/"

[[bin]]
name = "typg"
path = "src/main.rs"

[features]
default = []
# High-performance embedded index using LMDB and Roaring Bitmaps
hpindex = ["typg-core/hpindex"]

[dependencies]
anyhow = "1.0"
axum = { version = "0.7", features = ["macros"] }
clap = { version = "4.5", features = ["derive"] }
rayon = "1.10"
regex = "1.11"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
typg-core = { version = "=1.0.1", path = "../typg-core" }

[dev-dependencies]
http-body-util = "0.1"
tempfile = "3.10"
tower = { version = "0.4", features = ["util"] }
</document_content>
</document>

# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-cli/src/lib.rs
# Language: rust

mod server;

mod tests;

struct Cli {
}

struct ServeArgs {
}

struct CacheAddArgs {
}

struct OutputArgs {
}

struct CacheListArgs {
}

struct CacheFindArgs {
}

struct CacheCleanArgs {
}

struct CacheInfoArgs {
}

struct FindArgs {
}

struct OutputFormat {
}


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-cli/src/main.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-cli/src/server.rs
# Language: rust

mod tests;

struct SearchRequest {
}

struct SearchResponse {
}


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-cli/src/tests.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-cli/tests/integration.rs
# Language: rust



<document index="14">
<source>typg-core/Cargo.toml</source>
<document_content>
[package]
name = "typg-core"
version = "1.0.1"
edition = "2021"
authors = ["FontLab"]
description = "Core search/discovery engine for typg (made by FontLab https://www.fontlab.com/)"
license = "MIT"
homepage = "https://www.fontlab.com/"
repository = "https://github.com/fontlaborg/typg"
build = "build.rs"

[features]
default = ["fontations"]
fontations = ["read-fonts", "skrifa"]
typf-fontdb = []
# High-performance embedded index using LMDB and Roaring Bitmaps
hpindex = ["heed", "roaring", "bytemuck", "xxhash-rust", "bincode", "byteorder"]

[dependencies]
anyhow = "1.0"
walkdir = "2.5.0"
read-fonts = { version = "0.36.0", optional = true }
skrifa = { version = "0.39.0", optional = true }
regex = "1.11"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
rayon = "1.10"

# High-performance index dependencies (optional)
heed = { version = "0.21", optional = true }
roaring = { version = "0.10", optional = true }
bytemuck = { version = "1.18", optional = true, features = ["derive"] }
xxhash-rust = { version = "0.8", optional = true, features = ["xxh3"] }
bincode = { version = "1.3", optional = true }
byteorder = { version = "1.5", optional = true }

[dev-dependencies]
tempfile = "3.10"
proptest = "1.5"
criterion = "0.5"

[[bench]]
name = "cache_vs_index"
harness = false
required-features = ["hpindex"]
</document_content>
</document>

# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/benches/cache_vs_index.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/build.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/src/discovery.rs
# Language: rust

mod tests;

struct TypgFontSourceRef {
}

struct PathDiscovery {
}

trait FontDiscovery {
}


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/src/index.rs
# Language: rust

mod tests;

struct IndexedFontMeta {
}

struct PathEntry {
}

struct FontIndex {
}

struct IndexWriter {
}

struct IndexReader {
}


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/src/lib.rs
# Language: rust

mod discovery;

mod index;

mod output;

mod query;

mod search;

mod tags;


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/src/output.rs
# Language: rust

mod tests;


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/src/query.rs
# Language: rust

struct Query {
}

struct FamilyClassFilter {
}


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/src/search.rs
# Language: rust

mod tests;

struct TypgFontFaceMeta {
}

struct TypgFontSource {
}

struct TypgFontFaceMatch {
}

struct SearchOptions {
}


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/src/tags.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/tests/cached_search.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/tests/discovery.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/tests/metadata_names.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/tests/output.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/tests/query_parser.rs
# Language: rust



# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-core/tests/search_filters.rs
# Language: rust



<document index="15">
<source>typg-python/Cargo.toml</source>
<document_content>
[package]
name = "typg-python"
version = "1.0.1"
edition = "2021"
authors = ["FontLab"]
description = "PyO3 bindings for typg-core (made by FontLab https://www.fontlab.com/)"
license = "MIT"
homepage = "https://www.fontlab.com/"
repository = "https://github.com/fontlaborg/typg"

[lib]
name = "typg_python"
crate-type = ["cdylib", "rlib"]

[features]
default = []
extension-module = ["pyo3/extension-module"]
# Forward hpindex feature to typg-core for indexed search
hpindex = ["typg-core/hpindex"]

[dependencies]
anyhow = "1.0"
pyo3 = { version = "0.26", features = ["abi3-py310"] }
regex = "1.11"
typg-core = { version = "=1.0.1", path = "../typg-core" }

[dev-dependencies]
indoc = "2.0"
pyo3 = { version = "0.26", features = ["abi3-py310"] }
tempfile = "3.10"
read-fonts = "0.36.0"
</document_content>
</document>

<document index="16">
<source>typg-python/README.md</source>
<document_content>
# typg (PyPI)

PyO3 bindings for `typg-core` (made by FontLab https://www.fontlab.com/), exposed on PyPI as `typg` with a Fire-based CLI wrapper.

## Build

```bash
uv venv --python 3.12
uv pip install maturin
uv run maturin develop --features extension-module
```

## Usage

```python
from typg import find, filter_cached

results = find([\"/Library/Fonts\"], axes=[\"wght\"], variable=True, jobs=4)
print(len(results))

weighted = find([\"/Library/Fonts\"], weight=\"300-500\", width=\"5\")
print(\"weight/width matches\", len(weighted))
```

CLI:

```bash
typgpy find --paths /Library/Fonts --axes wght --weight 300-500 --variable --jobs 4
```
</document_content>
</document>

<document index="17">
<source>typg-python/pyproject.toml</source>
<document_content>
[build-system]
# maturin builds the Rust extension; hatch-vcs supplies the version from git tags
requires = ["maturin>=1.7,<2.0", "hatchling>=1.21", "hatch-vcs>=0.4"]
build-backend = "maturin"

[project]
name = "typg"
dynamic = ["version"]
description = "PyO3 bindings for typg-core (made by FontLab https://www.fontlab.com/)"
authors = [{ name = "FontLab" }]
license = "MIT"
readme = "README.md"
requires-python = ">=3.10"
dependencies = ["fire>=0.7.1"]

[project.scripts]
typgpy = "typg_python.cli:main"

[tool.hatch.version]
source = "vcs"
tag-pattern = "^v(?P<version>\\d+\\.\\d+\\.\\d+(?:[.-].*)?)$"
[tool.hatch.version.raw-options]
root = ".."
local_scheme = "no-local-version"


[tool.maturin]
features = ["extension-module"]
python-source = "python"
module-name = "typg_python._typg_python"
</document_content>
</document>

# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-python/python/typg/__init__.py
# Language: python

from importlib import metadata
from typg_python import filter_cached, find, find_paths
from typg_python import count_indexed, find_indexed, list_indexed


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-python/python/typg_python/__init__.py
# Language: python

from ._typg_python import filter_cached_py as filter_cached
from ._typg_python import find_py as find
from ._typg_python import find_paths_py as find_paths
from ._typg_python import count_indexed_py as count_indexed
from ._typg_python import find_indexed_py as find_indexed
from ._typg_python import list_indexed_py as list_indexed


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-python/python/typg_python/cli.py
# Language: python

import os
import sys
from pathlib import Path
from typing import Iterable, List, Sequence
import fire
from . import find, find_paths

def _dedup_paths((paths: Iterable[Path])) -> List[Path]:

def _system_font_roots(()) -> List[Path]:

def _gather_paths((
    paths: Sequence[Path | str] | None,
    stdin_paths: bool,
    include_system: bool,
)) -> List[str]:

def find_cli((
    paths: Sequence[Path | str] | None = None,
    axes: Sequence[str] | None = None,
    features: Sequence[str] | None = None,
    scripts: Sequence[str] | None = None,
    tables: Sequence[str] | None = None,
    names: Sequence[str] | None = None,
    codepoints: Sequence[str] | None = None,
    text: str | None = None,
    weight: str | None = None,
    width: str | None = None,
    family_class: str | None = None,
    variable: bool = False,
    follow_symlinks: bool = False,
    jobs: int | None = None,
    stdin_paths: bool = False,
    system_fonts: bool = False,
    paths_only: bool = False,
)):

def main(()):


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-python/src/lib.rs
# Language: rust

mod tests;

struct MetadataInput {
}


# File: /Users/adam/Developer/vcs3/github.fontlaborg/typg/typg-python/tests/test_find.py
# Language: python

import os
from pathlib import Path
from types import SimpleNamespace
import pytest
import typg_python
from typg_python import cli

def fonts_dir(()) -> Path:

def test_find_filters_variable_flag((fonts_dir: Path)) -> None:

def test_cli_uses_system_font_env_override((fonts_dir: Path, monkeypatch: pytest.MonkeyPatch)) -> None:

def test_find_accepts_jobs((fonts_dir: Path)) -> None:

def test_find_rejects_zero_jobs((fonts_dir: Path)) -> None:

def test_find_paths_returns_strings_only((fonts_dir: Path)) -> None:

def test_cli_paths_only_returns_paths((fonts_dir: Path)) -> None:

def _metadata((
    path: str,
    weight_class: int | None = None,
    width_class: int | None = None,
    family_class: tuple[int, int] | None = None,
)) -> dict:

def test_filter_cached_handles_weight_and_width(()) -> None:

def test_filter_cached_family_class_filters_major_and_subclass(()) -> None:


</documents>