fontist 3.0.1 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afb1c6bc21c216e16a0a2bb42de770866575bbf424bd8d3d49bf99d5eec80cb5
-  data.tar.gz: 5d72a4edb96a6f39e2d058cbe312d392f62e50d73bdfbf8a168b82492155e9b4
+  metadata.gz: b68f4d4d083a0e2f73df389c0698800b4a4d519428cbf59ddd98f493630a3342
+  data.tar.gz: 76cc6dd8420deb15d8b5fd872e17550c4b31dc31585834f2290a0e3f36d130ba
 SHA512:
-  metadata.gz: 77746091e20120805c19eb0a912c3f0a9eb101d88522afc4dd3cc45902922ce301bcf8aa909b23bb6ef664c615fb648dc5990e314a36227c774cfa63d0714e09
-  data.tar.gz: 7b900979917db2a7b973c9541bb2be9ff6b1dac5016128f9e082763136f648f0647a3519868efb6fa665b9d094d8377981cb6d7f3101f33262d8ea898c5e3718
+  metadata.gz: 72c687e0c3c81823d1e0edf131f9af115564e5d7b60b296d84dad7c297e5ea6e8f5fd6995f18961b6a6d048fb630eeba1e74d7beb942bad0abf97b9922112435
+  data.tar.gz: 57c8dde9259414c129e83c5fea0b7d50b2970c0062a756ffd9f8dbf91738508c154e0372f7b4a9d30139abb17d650a98954db0cc8764bd8871c7c5611221e4f9

data/.github/workflows/discover-fonts.yml

@@ -69,6 +69,8 @@ jobs:
         version: [2022, 2025]
       fail-fast: false
     steps:
+      - uses: actions/checkout@v6
+
       - name: List ALL Windows Fonts
         shell: pwsh
         run: |
@@ -78,6 +80,80 @@ jobs:
           Write-Host "=== Total Count ==="
           (Get-ChildItem -Path "C:\Windows\Fonts\" -Include *.ttf,*.ttc,*.otf -Recurse).Count
 
+      - name: List FOD font capabilities
+        shell: pwsh
+        run: |
+          Write-Host "=== Windows FOD Font Capabilities ==="
+          $caps = Get-WindowsCapability -Online -Name "Language.Fonts.*"
+          $caps | Format-Table -AutoSize Name, State
+          Write-Host ""
+          Write-Host "=== Summary ==="
+          $installed = ($caps | Where-Object { $_.State -eq "Installed" }).Count
+          $notPresent = ($caps | Where-Object { $_.State -eq "NotPresent" }).Count
+          $staged = ($caps | Where-Object { $_.State -eq "Staged" }).Count
+          Write-Host "Installed: $installed"
+          Write-Host "NotPresent: $notPresent"
+          Write-Host "Staged: $staged"
+          Write-Host "Total: $($caps.Count)"
+          Write-Host ""
+          Write-Host "=== Saving results ==="
+          New-Item -ItemType Directory -Force -Path artifacts | Out-Null
+          $caps | Select-Object Name, State | ConvertTo-Csv -NoTypeInformation | Out-File -FilePath artifacts/fod-capabilities.csv
+          $caps | ConvertTo-Json | Out-File -FilePath artifacts/fod-capabilities.json
+          Write-Host "Saved to artifacts/fod-capabilities.csv and artifacts/fod-capabilities.json"
+
+      - name: Cross-check FOD capabilities with our YAML
+        shell: pwsh
+        run: |
+          Write-Host "=== Cross-checking fod_capabilities.yml against live Windows ==="
+
+          # Get live capabilities from Windows
+          $liveCaps = Get-WindowsCapability -Online -Name "Language.Fonts.*"
+          $liveNames = $liveCaps | ForEach-Object { $_.Name }
+
+          # Parse our YAML capability names (simple text extraction)
+          $yamlPath = "lib/fontist/import/windows/fod_capabilities.yml"
+          $yamlContent = Get-Content $yamlPath -Raw
+          $yamlNames = [regex]::Matches($yamlContent, '^\s+"([^"]+)":', [System.Text.RegularExpressions.RegexOptions]::Multiline) |
+            ForEach-Object { $_.Groups[1].Value }
+
+          Write-Host ""
+          Write-Host "Live capabilities: $($liveNames.Count)"
+          Write-Host "YAML capabilities: $($yamlNames.Count)"
+          Write-Host ""
+
+          # Find matches
+          $matched = $yamlNames | Where-Object { $liveNames -contains $_ }
+          Write-Host "=== Matched ($($matched.Count)) ==="
+          $matched | ForEach-Object { Write-Host "  OK: $_" }
+
+          # Find missing from our YAML (present on Windows but not in our file)
+          $missingFromYaml = $liveNames | Where-Object { $yamlNames -notcontains $_ }
+          if ($missingFromYaml.Count -gt 0) {
+            Write-Host ""
+            Write-Host "=== Missing from our YAML ($($missingFromYaml.Count)) ==="
+            $missingFromYaml | ForEach-Object { Write-Host "  MISSING: $_" }
+          }
+
+          # Find extra in our YAML (in our file but not on Windows)
+          $extraInYaml = $yamlNames | Where-Object { $liveNames -notcontains $_ }
+          if ($extraInYaml.Count -gt 0) {
+            Write-Host ""
+            Write-Host "=== Extra in our YAML ($($extraInYaml.Count)) ==="
+            $extraInYaml | ForEach-Object { Write-Host "  EXTRA: $_" }
+          }
+
+          Write-Host ""
+          Write-Host "=== Cross-check complete ==="
+
+      - name: Upload FOD capability results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-fod-capabilities-${{ matrix.version }}
+          path: artifacts/
+          if-no-files-found: warn
+
   discover-linux:
     name: Linux fonts
     runs-on: ubuntu-latest

data/.github/workflows/rake.yml

@@ -214,6 +214,104 @@ jobs:
           echo "   Test Complete"
           echo "========================================================================="
 
+      - name: Test Windows FOD font installation
+        if: startsWith(matrix.os, 'windows')
+        continue-on-error: true
+        shell: pwsh
+        run: |
+          Write-Host "========================================================================="
+          Write-Host "   Windows FOD (Features on Demand) Font Installation Test"
+          Write-Host "========================================================================="
+          Write-Host ""
+          Write-Host "Platform: Windows $(([System.Environment]::OSVersion.Version).ToString())"
+          Write-Host "Runner: ${{ matrix.os }}"
+          Write-Host ""
+
+          Write-Host "--- Step 1: Generate Windows FOD Formulas into formulas repo ---"
+          $formulasRepo = bundle exec ruby -e "require 'fontist'; puts Fontist.formulas_path"
+          $formulasRepo = $formulasRepo.Trim()
+          $windowsDir = Join-Path $formulasRepo "windows"
+          Write-Host "Formulas path: $formulasRepo"
+          Write-Host "Generating FOD formulas into: $windowsDir"
+          bundle exec ruby script/generate_windows_formulas.rb $windowsDir
+          $formulaCount = (Get-ChildItem -Path $windowsDir -Filter "*.yml" -ErrorAction SilentlyContinue).Count
+          Write-Host "Generated $formulaCount formula files"
+          Write-Host ""
+
+          Write-Host "--- Step 2: Rebuild formula index to include FOD formulas ---"
+          bundle exec ruby -e "require 'fontist'; Fontist::Index.rebuild; puts 'Formula index rebuilt'; f = Fontist::Formula.find('Arial Nova'); puts f ? 'Verified: Arial Nova found -> ' + f.name : 'WARNING: Arial Nova NOT found in index'"
+          if ($LASTEXITCODE -ne 0) {
+            Write-Host "WARNING: Formula index rebuild failed with exit code $LASTEXITCODE"
+          }
+          Write-Host ""
+
+          Write-Host "--- Step 2b: Verify formula index ---"
+          $indexPath = bundle exec ruby -e "require 'fontist'; puts Fontist.formula_index_path"
+          $indexPath = $indexPath.Trim()
+          Write-Host "Formula index path: $indexPath"
+          if (Test-Path $indexPath) {
+            $lineCount = (Get-Content $indexPath).Count
+            Write-Host "Formula index exists: $lineCount lines"
+            Write-Host "First 20 lines:"
+            Get-Content $indexPath -Head 20
+          } else {
+            Write-Host "WARNING: Formula index file does NOT exist at $indexPath"
+          }
+          Write-Host ""
+
+          Write-Host "--- Step 2c: Verify formula files on disk ---"
+          $formulasDir = bundle exec ruby -e "require 'fontist'; puts Fontist.formulas_path"
+          $formulasDir = $formulasDir.Trim()
+          Write-Host "Formulas directory: $formulasDir"
+          if (Test-Path $formulasDir) {
+            $ymlFiles = Get-ChildItem -Path $formulasDir -Filter "*.yml" -Recurse
+            Write-Host "Total .yml files: $($ymlFiles.Count)"
+            $ymlFiles | Select-Object -First 30 | ForEach-Object { Write-Host "  $($_.FullName)" }
+          } else {
+            Write-Host "WARNING: Formulas directory does NOT exist"
+          }
+          Write-Host ""
+
+          Write-Host "--- Step 3: List FOD Font Capabilities ---"
+          $caps = Get-WindowsCapability -Online -Name "Language.Fonts.*"
+          $installed = ($caps | Where-Object { $_.State -eq "Installed" })
+          $notPresent = ($caps | Where-Object { $_.State -eq "NotPresent" })
+          Write-Host "Installed: $($installed.Count)"
+          Write-Host "NotPresent: $($notPresent.Count)"
+          Write-Host "Total: $($caps.Count)"
+          Write-Host ""
+
+          Write-Host "--- Step 4: Run Cross-Check Validation ---"
+          bundle exec ruby script/validate_windows_fod_ci.rb
+          Write-Host ""
+
+          Write-Host "--- Step 5: Install Plantagenet Cherokee via fontist (small FOD) ---"
+          Write-Host "Running: fontist install 'Plantagenet Cherokee' --accept-all-licenses"
+          bundle exec fontist install "Plantagenet Cherokee" --accept-all-licenses
+          if ($LASTEXITCODE -eq 0) {
+            Write-Host "fontist install succeeded"
+          } else {
+            Write-Host "WARNING: fontist install exited with code $LASTEXITCODE"
+          }
+          Write-Host ""
+
+          Write-Host "--- Step 6: Verify Plantagenet Cherokee via fontist list ---"
+          bundle exec fontist list "Plantagenet Cherokee"
+          Write-Host ""
+
+          Write-Host "--- Step 7: Verify font file on disk ---"
+          $path = Join-Path "C:\Windows\Fonts" "Plantc.ttf"
+          if (Test-Path $path) {
+            Write-Host "  OK: Plantc.ttf"
+          } else {
+            Write-Host "  MISSING: Plantc.ttf"
+          }
+          Write-Host ""
+
+          Write-Host "========================================================================="
+          Write-Host "   Test Complete"
+          Write-Host "========================================================================="
+
       - name: Upload system index as artifact
         if: always()
         uses: actions/upload-artifact@v4
@@ -237,17 +335,14 @@ jobs:
 
     steps:
       - name: Setup packages
-        run: pacman -Syu --noconfirm git binutils gcc autoconf make libffi libyaml gmp
+        run: |
+          pacman -Syu --noconfirm git binutils gcc autoconf make libffi libyaml gmp ruby ruby-stdlib
 
       - uses: actions/checkout@v4
 
-      - uses: asdf-vm/actions/install@v3
-        with:
-          tool_versions: ruby ${{ needs.prepare.outputs.default-ruby-version }}
-
       - run: |
-          gem install bundler
-          bundle install
+          gem install --no-document --user-install bundler
+          PATH="$(ruby -e 'puts Gem.user_dir')/bin:$PATH" bundle install
 
       - name: Test
-        run: bundle exec rake
+        run: PATH="$(ruby -e 'puts Gem.user_dir')/bin:$PATH" bundle exec rake

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