fontist 3.0.0 → 3.0.2

data/TODO.audit-docs.md

@@ -0,0 +1,164 @@
+# TODO: Documentation Audit
+
+## Purpose
+Audit all Fontist Ruby gem functionality to ensure complete documentation coverage.
+
+## Reference Files
+- docs/guide/how-it-works.md
+- docs/api/
+- docs/cli/
+- docs/guide/concepts/
+
+**Last Updated:** 2026-03-10
+
+---
+
+## ✅ COMPLETED
+
+### 1. Configuration Priority System
+Documented in `/guide/how-it-works.md`
+
+**Priority Order (Highest to Lowest):**
+
+| Priority | Source | Example | Notes |
+|----------|--------|---------|-------|
+| 1 | ENV VAR | `FONTIST_PATH=/custom` | Always wins |
+| 2 | Config file | `~/.fontist/config.yml` | Persistent settings |
+| 3 | CLI option | `--location user` | Per-command override |
+| 4 | Ruby API | `Fontist.preferred_family = true` | Programmatic |
+| 5 | Default | Built-in defaults | Fallback |
+
+### 2. Installation Locations
+Documented in `/guide/how-it-works.md`
+
+| Type | Path | Managed? | Use Case |
+|------|------|----------|----------|
+| fontist | `~/.fontist/fonts/{formula}/` | ✅ Yes | Default, isolated |
+| user | `~/Library/Fonts/fontist/` (macOS) | ✅ Yes | User-wide access |
+| system | `/Library/Fonts/fontist/` (macOS) | ✅ Yes | All users |
+
+### 3. Font Indexes
+Documented in `/guide/how-it-works.md`
+
+- Formula Index: Maps font names → formula files
+- System Index: OS-installed fonts
+- Fontist Index: Fonts installed via Fontist
+- User Index: User-installed fonts
+
+### 4. Formula Repository
+Documented in `/guide/formulas.md`
+
+- Location: `~/.fontist/versions/v4/formulas/`
+- Git clone from `https://github.com/fontist/formulas.git`
+- Auto-updates via `fontist update`
+- Private repos via `fontist repo`
+
+### 5. CLI Commands
+All documented in `/docs/cli/`
+
+### 6. Ruby API Classes
+All documented in `/docs/api/`
+
+---
+
+## 🔄 IN PROGRESS
+
+- [ ] Add configuration priority table to how-it-works.md
+- [ ] Add managed vs non-managed location explanation
+- [ ] Document all ENV variables in reference page
+
+---
+
+## Configuration Reference
+
+### All Configuration Settings
+
+| Setting | ENV VAR | Config Key | CLI Option | Default |
+|---------|---------|------------|------------|---------|
+| Base path | `FONTIST_PATH` | - | - | `~/.fontist` |
+| Fonts path | - | `fonts_path` | - | `~/.fontist/fonts` |
+| Formulas path | `FONTIST_FORMULAS_PATH` | - | `--formulas-path` | (auto) |
+| Install location | `FONTIST_INSTALL_LOCATION` | `fonts_install_location` | `--location` | `fontist` |
+| User fonts path | `FONTIST_USER_FONTS_PATH` | `user_fonts_path` | - | Platform default |
+| System fonts path | `FONTIST_SYSTEM_FONTS_PATH` | `system_fonts_path` | - | Platform default |
+| Preferred family | - | `preferred_family` | `--preferred-family` | `false` |
+| No cache | - | - | `--no-cache` | `false` |
+| Quiet mode | - | - | `--quiet` | `false` |
+| Verbose | - | - | `--verbose` | `false` |
+| Open timeout | - | `open_timeout` | - | `60` |
+| Read timeout | - | `read_timeout` | - | `60` |
+| Google Fonts key | `GOOGLE_FONTS_API_KEY` | `google_fonts_key` | - | `nil` |
+| Import cache | `FONTIST_IMPORT_CACHE` | - | - | `~/.fontist/import_cache` |
+
+---
+
+## Environment Variables Reference
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FONTIST_PATH` | Base directory for all Fontist data | `~/.fontist` |
+| `FONTIST_FORMULAS_PATH` | Custom formulas directory | (auto) |
+| `FONTIST_INSTALL_LOCATION` | Default install location (`fontist`, `user`, `system`) | `fontist` |
+| `FONTIST_USER_FONTS_PATH` | Custom user fonts path | Platform default |
+| `FONTIST_SYSTEM_FONTS_PATH` | Custom system fonts path | Platform default |
+| `FONTIST_IMPORT_CACHE` | Import cache directory | `~/.fontist/import_cache` |
+| `FONTIST_NO_MIRRORS` | Disable formula index mirrors | `false` |
+| `GOOGLE_FONTS_API_KEY` | Google Fonts API key | (none) |
+
+---
+
+## Managed vs Non-Managed Locations
+
+### Managed Locations (Fontist controls)
+- `~/.fontist/fonts/` - Always managed
+- `~/Library/Fonts/fontist/` - Managed subdirectory
+- `/Library/Fonts/fontist/` - Managed subdirectory
+
+**Behavior:** Safe to replace existing fonts
+
+### Non-Managed Locations (custom paths via ENV)
+- `FONTIST_USER_FONTS_PATH=~/Library/Fonts` → installs directly
+- `FONTIST_SYSTEM_FONTS_PATH=/Library/Fonts` → installs directly
+
+**Behavior:** Uses unique filenames (`-fontist` suffix) to avoid conflicts
+
+---
+
+## Directory Structure
+
+```
+~/.fontist/
+├── fonts/                          # Installed font files
+│   └── {formula-key}/
+│       └── *.ttf
+├── versions/
+│   └── v4/
+│       ├── formulas/               # Git clone of formulas repo
+│       │   └── Formulas/
+│       │       ├── roboto.yml
+│       │       └── private/        # Custom formula repos
+│       ├── formula_index.default_family.yml
+│       ├── formula_index.preferred_family.yml
+│       └── filename_index.yml
+├── config.yml                      # User configuration
+├── downloads/                      # Temporary downloads
+├── import_cache/                   # Imported font cache
+├── system_index.default_family.yml # System fonts index
+├── fontist_index.default_family.yml # Fontist fonts index
+└── user_index.default_family.yml   # User fonts index
+```
+
+---
+
+## Remaining Minor Gaps
+
+- [ ] Document import system (`fontist import`) internals
+- [ ] Document cache system internals
+- [ ] Document formula picker algorithm
+- [ ] Document locking mechanism (for concurrent operations)
+
+---
+
+## Status: Nearly Complete
+**Priority:** High
+**Notes:** Core functionality documented, minor gaps remain

data/TODO.improve-docs.md

@@ -0,0 +1,114 @@
+# Fontist Documentation Improvement Plan
+
+**Goal:** Achieve 100% documentation coverage of README.adoc content in docs/
+
+**Status:** ✅ Complete
+
+---
+
+## Phase 1: Platform-Specific Guides (Critical)
+
+### 1.1 Create macOS Platform Guide
+- [x] Create `/docs/guide/platforms/macos.md`
+- [x] Document supplementary fonts framework
+- [x] Document framework versioning (Font3-Font8)
+- [x] Document platform tags (`macos-fontX`)
+- [x] Document version compatibility checking
+- [x] Include macOS version → framework table
+- [x] Add link to Fontist blog post
+
+### 1.2 Create Windows Platform Guide
+- [x] Create `/docs/guide/platforms/windows.md`
+- [x] Document Windows font management differences
+- [x] Document Windows font locations
+- [x] Document file locking considerations
+- [x] Document path handling
+- [x] Document registry integration
+- [x] Document administrator privileges
+- [x] Include platform compatibility table
+
+---
+
+## Phase 2: Installation Improvements
+
+### 2.1 Update Installation Guide
+- [x] Add detailed dependency table (json, brotli, seven-zip, libmspack, ffi-libarchive-binary)
+- [x] Add Windows RubyInstaller DevKit steps (`ridk install`)
+- [x] Add Git as prerequisite for update/repo commands
+- [x] Add note about native extension compilation
+
+---
+
+## Phase 3: Formula Advanced Features
+
+### 3.1 Update Formulas Guide
+- [x] Add `override:` key documentation (already present)
+- [x] Add Frutiger fonts example (already present)
+- [x] Add HTTP authentication for private repos (already present)
+- [x] Add authorization headers example (already present)
+- [x] Add token scope requirements (already present)
+
+### 3.2 Update create-formula CLI
+- [x] Add `--name-prefix` option with example (already documented)
+
+---
+
+## Phase 4: How It Works Improvements
+
+### 4.1 Update How It Works Guide
+- [x] Add managed vs non-managed locations section (already present)
+- [x] Add font discovery behavior explanation (already present)
+- [x] Add import cache environment variables (already present)
+
+---
+
+## Phase 5: Maintainer Documentation (Clearly Marked)
+
+### 5.1 Create Maintainer Import Guide
+- [x] Create `/docs/guide/maintainer/index.md`
+- [x] Create `/docs/guide/maintainer/import.md`
+- [x] Mark as "Maintainer Only" clearly
+- [x] Document `fontist import google` command
+- [x] Document Google Fonts API integration
+- [x] Document import source architecture
+- [x] Document versioned filenames
+- [x] Document import cache Ruby API
+
+### 5.2 Update CLI Import Reference
+- [x] Add `fontist import google` to `/docs/cli/import.md` (already present)
+- [x] Add maintainer-only notice
+
+---
+
+## Phase 6: Navigation Updates
+
+### 6.1 Update VitePress Config
+- [x] Add Platforms section to Guide sidebar
+- [x] Add Maintainer section to Guide sidebar (collapsed)
+- [x] Update navigation as needed
+
+---
+
+## Phase 7: Verification
+
+### 7.1 Build and Test
+- [x] Run `npm run build` to verify no errors
+- [x] Run lychee link checker (manual verification with curl - lychee crashed)
+- [x] Verify all new pages are accessible
+- [x] Cross-check against README.adoc
+
+---
+
+## Progress Tracking
+
+| Phase | Status | Items Done | Items Total |
+|-------|--------|------------|-------------|
+| 1. Platform Guides | ✅ Complete | 14 | 14 |
+| 2. Installation | ✅ Complete | 4 | 4 |
+| 3. Formula Features | ✅ Complete | 7 | 7 |
+| 4. How It Works | ✅ Complete | 3 | 3 |
+| 5. Maintainer Docs | ✅ Complete | 10 | 10 |
+| 6. Navigation | ✅ Complete | 3 | 3 |
+| 7. Verification | ✅ Complete | 4 | 4 |
+
+**Total Progress: 45/45 items (100%)**

data/TODO.upgrade-excavate.md

@@ -0,0 +1,107 @@
+# TODO: Fix Excavate Memory Leaks and Upgrade Fontist
+
+## Problem
+Fontist CI tests pass but fail at the end with:
+```
+failed to allocate memory (NoMemoryError)
+```
+
+This happens after repeated archive extractions during test runs.
+
+## Root Cause Analysis
+Memory leaks in Excavate gem due to:
+1. Temp directories not cleaned up on errors
+2. Incorrect `ensure`/`rescue` order in `extract_and_replace` method
+
+## Remaining Work
+
+### 1. Fix Excavate Gem (in /Users/mulgogi/src/fontist/excavate)
+
+#### archive.rb - Fix `extract_and_replace` method (lines 217-229)
+Current broken code has `ensure` BEFORE `rescue` which is invalid Ruby syntax:
+```ruby
+def extract_and_replace(archive)
+  target = Dir.mktmpdir
+  extract_recursively(archive, target)
+  replace_archive_with_contents(archive, target)
+ensure                    # <-- WRONG: ensure must come AFTER rescue
+  FileUtils.rm_rf(target)
+rescue StandardError      # <-- This causes syntax error
+  raise unless TYPES.key?(normalized_extension(archive))
+end
+```
+
+Fix - swap order so `rescue` comes before `ensure`:
+```ruby
+def extract_and_replace(archive)
+  target = Dir.mktmpdir
+  extract_recursively(archive, target)
+  replace_archive_with_contents(archive, target)
+rescue StandardError
+  raise unless TYPES.key?(normalized_extension(archive))
+ensure
+  FileUtils.rm_rf(target)
+end
+```
+
+### 2. Run Excavate Tests
+```bash
+cd /Users/mulgogi/src/fontist/excavate
+bundle exec rspec
+```
+All 65 tests should pass.
+
+### 3. Bump Excavate Version
+Edit `/Users/mulgogi/src/fontist/excavate/lib/excavate/version.rb`:
+```ruby
+VERSION = "1.0.3"
+```
+
+### 4. Commit and Push Excavate
+```bash
+cd /Users/mulgogi/src/fontist/excavate
+git add -A
+git commit -m "fix: prevent memory leaks by ensuring proper resource cleanup
+
+- Fix extract_and_replace to use correct rescue/ensure order
+- Add ensure block to extract_by_filter for temp dir cleanup"
+git push origin main
+```
+
+### 5. Release Excavate Gem
+```bash
+cd /Users/mulgogi/src/fontist/excavate
+# Tag and push to rubygems
+git tag v1.0.3
+git push --tags
+gem build excavate.gemspec
+gem push excavate-1.0.3.gem
+```
+
+### 6. Update Fontist to Use New Excavate
+```bash
+cd /Users/mulgogi/src/fontist/fontist
+# Update Gemfile.lock to use excavate >= 1.0.3
+bundle update excavate
+```
+
+### 7. Run Fontist Tests
+```bash
+cd /Users/mulgogi/src/fontist/fontist
+bundle exec rspec
+```
+Tests should pass WITHOUT the `NoMemoryError` at the end.
+
+### 8. Create PR and Merge
+- Create PR in fontist repository
+- Reference issue #451
+- Merge after CI passes
+
+## Files Modified
+
+### Excavate
+- `lib/excavate/archive.rb` - Fix `extract_and_replace` method
+
+## Notes
+- Do NOT add `ensure` blocks with `reader&.close` to extractors - the Omnizip readers don't have a `close` method
+- The fix is simple: correct the `rescue`/`ensure` order in `extract_and_replace`

data/docs/guide/formulas.md

@@ -26,7 +26,7 @@ The main formula repository is [fontist/formulas](https://github.com/fontist/for
 - Google Fonts (Roboto, Open Sans, etc.)
 - SIL Fonts
 - macOS system fonts
-- Windows fonts
+- Windows fonts (including Windows Features on Demand)
 - Many other open source fonts
 
 ### Local Storage
@@ -257,6 +257,42 @@ fontist create-formula https://dl.winehq.org/wine/source/10.x/wine-10.18.tar.xz
 
 This generates a formula where all fonts have names prefixed with "Wine ", making it clear these are Wine compatibility fonts rather than the original Microsoft fonts.
 
+### Windows Features on Demand (FOD) Formulas
+
+Windows FOD formulas use `source: windows_fod` to install fonts via PowerShell's `Add-WindowsCapability`. These formulas don't have download URLs — instead, they specify a Windows capability name:
+
+```yaml
+schema_version: 5
+name: Japanese Supplemental Fonts
+platforms:
+  - windows
+resources:
+  japanese_supplemental_fonts:
+    source: windows_fod
+    capability_name: "Language.Fonts.Jpan~~~und-JPAN~0.0.1.0"
+fonts:
+  - name: Meiryo
+    styles:
+      - family_name: Meiryo
+        type: Regular
+        font: Meiryo.ttc
+import_source:
+  type: windows
+  capability_name: "Language.Fonts.Jpan~~~und-JPAN~0.0.1.0"
+  min_windows_version: "10.0"
+```
+
+Key fields for Windows FOD formulas:
+
+| Field | Description |
+|-------|-------------|
+| `resources.*.source` | Must be `windows_fod` |
+| `resources.*.capability_name` | The Windows FOD capability identifier (e.g., `Language.Fonts.Jpan~~~und-JPAN~0.0.1.0`) |
+| `import_source.type` | Must be `windows` |
+| `import_source.min_windows_version` | Minimum Windows version required (default: `10.0`) |
+
+These formulas are restricted to the `windows` platform. Attempting to install them on macOS or Linux raises a `PlatformMismatchError`.
+
 ## Related
 
 - [How Fontist Works](/guide/how-it-works) - Internal architecture and indexes

data/docs/guide/how-it-works.md

@@ -291,6 +291,19 @@ When you run `fontist install "Open Sans"`:
 └─────────────────────────────────────────────────────────────┘
 ```
 
+### Resource Dispatch
+
+Fontist selects a download strategy based on the formula's `source` field:
+
+| Source | Resource Class | Behavior |
+|--------|---------------|----------|
+| `google` | `GoogleResource` | Downloads from Google Fonts API |
+| `apple_cdn` | `AppleCDNResource` | Downloads from Apple CDN |
+| `windows_fod` | `WindowsFodResource` | Installs via PowerShell `Add-WindowsCapability` |
+| (default) | `ArchiveResource` | Downloads and extracts archive via excavate |
+
+For Windows FOD fonts, the flow differs from archives — instead of downloading a file, Fontist checks if the Windows capability is installed and installs it via PowerShell if needed. Font files are then read from `C:\Windows\Fonts`.
+
 ---
 
 ## Index Management

data/docs/guide/platforms/windows.md

@@ -78,6 +78,73 @@ fontist install "Roboto" --location=system
 
 ---
 
+## Windows Features on Demand (FOD) Fonts
+
+Windows includes supplementary fonts that aren't pre-installed but can be enabled through **Features on Demand** (FOD). These include fonts for Japanese, Korean, Arabic, Pan-European, and other scripts.
+
+### What Are FOD Fonts?
+
+Windows FOD fonts are installed using `Add-WindowsCapability`, which downloads font packages from Windows Update. Fontist automates this process — when a formula specifies `source: windows_fod`, Fontist calls the appropriate PowerShell command to install the capability.
+
+### Installing FOD Fonts
+
+```powershell
+# Install a specific supplemental font
+fontist install "Meiryo"
+
+# Install Pan-European supplemental fonts
+fontist install "Arial Nova"
+```
+
+Fontist checks whether the capability is already installed. If not, it runs:
+
+```powershell
+Add-WindowsCapability -Online -Name 'Language.Fonts.Jpan~~~und-JPAN~0.0.1.0'
+```
+
+### Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| Windows version | Windows 10 or later |
+| Internet connection | Required (fonts download from Windows Update) |
+| Administrator | Required on Windows 10 for system-wide installation |
+| WSUS/SCCM | Must not block Features on Demand |
+
+### Available FOD Fonts
+
+Fontist includes metadata for all Windows FOD font capabilities. Some common ones:
+
+| Capability | Fonts Included |
+|------------|---------------|
+| Japanese Supplemental Fonts | Meiryo, MS Gothic, MS Mincho |
+| Korean Supplemental Fonts | Batang, Dotum, Gulim |
+| Arabic Script Supplemental Fonts | Sakkal Majalla, Simplified Arabic |
+| Pan-European Supplemental Fonts | Arial Nova, Georgia Pro, Gill Sans Nova |
+| Traditional Chinese Supplemental Fonts | MingLiU, DFKai-SB |
+
+### FOD Font Installation Flow
+
+1. Fontist looks up the font in the formula index
+2. Checks if the Windows FOD capability is already installed via `Get-WindowsCapability`
+3. If not installed, runs `Add-WindowsCapability` to download and install it
+4. Returns paths to the installed font files in `C:\Windows\Fonts`
+
+### Troubleshooting FOD Installation
+
+If you see a `WindowsFodInstallError`:
+
+1. **No internet connection** — FOD fonts require Windows Update access
+2. **Insufficient permissions** — Run as Administrator on Windows 10
+3. **WSUS/SCCM policy** — Your organization may block FOD downloads; contact your IT administrator
+4. **Capability not found** — The capability name may differ on your Windows version; run `Get-WindowsCapability -Online -Name 'Language.Fonts.*'` to list available capabilities
+
+::: info Platform Restriction
+Windows FOD fonts are only installable on Windows. Fontist will raise a `PlatformMismatchError` if you attempt to install them on macOS or Linux.
+:::
+
+---
+
 ## Windows-Specific Considerations
 
 ### File Locking

data/fontist.gemspec

@@ -31,11 +31,11 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "down", "~> 5.0"
   spec.add_dependency "excavate", "~> 1.0", ">= 1.0.3"
-  spec.add_dependency "fontisan", "~> 0.2", ">= 0.2.11"
+  spec.add_dependency "fontisan", "~> 0.2", ">= 0.2.16"
   spec.add_dependency "fuzzy_match", "~> 2.1"
   spec.add_dependency "git", "> 1.0"
   spec.add_dependency "json", "~> 2.0"
-  spec.add_dependency "lutaml-model", "~> 0.7"
+  spec.add_dependency "lutaml-model", "~> 0.8.0"
   spec.add_dependency "marcel", "~> 1.0"
   spec.add_dependency "nokogiri", "~> 1.0"
   spec.add_dependency "octokit", "~> 4.0"

data/lib/fontist/cache/store.rb

@@ -57,7 +57,7 @@ module Fontist
       attr_reader :cache_dir
 
       def ensure_cache_dir
-        FileUtils.mkdir_p(@cache_dir) unless Dir.exist?(@cache_dir)
+        FileUtils.mkdir_p(@cache_dir)
       end
 
       def cache_path(key)

data/lib/fontist/cli.rb

@@ -338,7 +338,8 @@ module Fontist
                                 "Uses `fnmatch` patterns."
     option :name_prefix, desc: "Prefix to add to all font family names, " \
                                "e.g. 'Wine ' for compatibility fonts"
-    option :schema_version, type: :numeric, default: 5, desc: "Formula schema version (default: 5)"
+    option :schema_version, type: :numeric, default: 5,
+                            desc: "Formula schema version (default: 5)"
     def create_formula(url)
       handle_class_options(options)
       name = Fontist::Import::CreateFormula.new(url, options).call

data/lib/fontist/errors.rb

@@ -159,9 +159,30 @@ module Fontist
 
       def build_message(font_name)
         "Font '#{font_name}' is only available for: #{@required_platforms.join(', ')}. " \
-        "Your current platform is: #{@current_platform}. " \
-        "This font is licensed exclusively for the specified platform(s) and " \
-        "cannot be installed on your system."
+          "Your current platform is: #{@current_platform}. " \
+          "This font is licensed exclusively for the specified platform(s) and " \
+          "cannot be installed on your system."
+      end
+    end
+
+    class WindowsFodInstallError < GeneralError
+      attr_reader :capability_name
+
+      def initialize(capability_name, stderr_output = nil)
+        @capability_name = capability_name
+        super(build_message(capability_name, stderr_output))
+      end
+
+      private
+
+      def build_message(cap_name, stderr)
+        msg = "Failed to install Windows font capability '#{cap_name}'."
+        msg += "\n#{stderr}" if stderr && !stderr.strip.empty?
+        msg += "\n\nPossible causes:" \
+               "\n  - No internet connection (Windows Update required)" \
+               "\n  - Insufficient permissions (admin required on Windows 10)" \
+               "\n  - WSUS/SCCM policy blocking Features on Demand"
+        msg
       end
     end
 

data/lib/fontist/extract.rb

@@ -32,6 +32,7 @@ module Fontist
       return true if options.nil?
       return options.empty? if options.respond_to?(:empty?)
       return options.file.nil? && options.fonts_sub_dir.nil? if options.is_a?(ExtractOptions)
+
       false
     end
   end

data/lib/fontist/font.rb

@@ -338,9 +338,9 @@ module Fontist
       all_fonts = [fontist_fonts, user_fonts, system_fonts].compact.flatten
       return unless all_fonts && !all_fonts.empty?
 
-      uninstalled_paths = all_fonts.map do |font|
+      uninstalled_paths = all_fonts.filter_map do |font|
         uninstall_font_at_location(font.path)
-      end.compact
+      end
 
       return if uninstalled_paths.empty?
 

data/lib/fontist/font_finder.rb

@@ -75,7 +75,7 @@ module Fontist
     def extract_resource_names(formula)
       return [] unless formula.resources
 
-      Array(formula.resources).map(&:name).compact
+      Array(formula.resources).filter_map(&:name)
     end
 
     def build_font_match(formula, name, resource)
@@ -123,7 +123,6 @@ module Fontist
       matcher = FormatMatcher.new(@format_spec)
       matcher.filter_resources(resources)
     end
-
   end
 
   # Result object for font matches