feat: introduce meta-configs pattern and relocate fonts config

- Move fonts.toml from deployed location to meta/ directory - Update install-fonts.ts to read from meta/ and support extras array - Add comprehensive documentation explaining meta-configs pattern - Add ZedMono NF font and update Zed editor keybindings/settings
2026-01-31 02:24:11 -06:00 · 2026-01-02 18:38:35 -06:00
parent ed10dae8fa
commit 2cf33f7a24
7 changed files with 207 additions and 56 deletions
@@ -0,0 +1,98 @@
+# Meta-Configs Pattern
+
+This repository uses a **meta-config pattern** for configuration files that drive imperative actions during `chezmoi apply`, rather than being deployed directly to the filesystem.
+
+## What are Meta-Configs?
+
+Meta-configs are configuration files that:
+
+1. **Are NOT deployed** to the target system
+2. **Drive scripts** that perform imperative actions (downloads, installations, modifications)
+3. **Live in `meta/`** at the repository root (outside `home/`)
+4. **Trigger `run_onchange_*` scripts** when their content changes
+
+This pattern separates "what to configure" from "configuration files that get deployed."
+
+## Directory Structure
+
+```
+chezmoi/
+├── meta/                    # Meta-configs (NOT deployed)
+│   ├── fonts.toml           # Drives font installation
+│   └── ...                  # Future meta-configs
+├── home/                    # Deployed to $HOME
+│   ├── .config/
+│   ├── .local/
+│   └── ...
+└── docs/
+    └── meta-configs.md      # This file
+```
+
+## Current Meta-Configs
+
+### `meta/fonts.toml`
+
+Drives the `install-fonts.ts` script to download and install fonts.
+
+```toml
+[ui]
+primary = "Inter"
+fallback = "Noto Sans"
+
+[mono]
+primary = "Geist Mono"
+fallback = "JetBrains Mono"
+
+[extras]
+# Fonts to install without category assignment
+fonts = ["ZedMono NF"]
+```
+
+**Triggered by:** `run_onchange_after_install-fonts.sh.tmpl`
+
+**Script:** `~/.local/bin/install-fonts.ts`
+
+## How It Works
+
+1. Edit a meta-config in `meta/` (e.g., `meta/fonts.toml`)
+2. Run `chezmoi apply`
+3. Chezmoi detects the file changed via `{{ include "../meta/fonts.toml" | sha256sum }}`
+4. The corresponding `run_onchange_*` script executes
+5. The script reads the meta-config and performs imperative actions
+
+## Why This Pattern?
+
+### Problem
+
+Some configuration requires imperative actions:
+- Downloading files from the internet
+- Installing packages
+- Modifying system state
+
+These don't fit the declarative "deploy this file" model of chezmoi.
+
+### Solution
+
+Meta-configs provide:
+- **Centralized configuration** - Easy to edit, version-controlled
+- **Imperative execution** - Scripts perform the actual work
+- **Change detection** - `run_onchange_*` only runs when config changes
+- **Clear separation** - Meta-configs are clearly not "files to deploy"
+
+## Adding a New Meta-Config
+
+1. Create `meta/<name>.toml` with your configuration schema
+2. Create a script in `home/dot_local/bin/` to process the config
+3. Create `home/run_onchange_after_<name>.sh.tmpl` that:
+   - Includes a hash comment: `# hash: {{ include "../meta/<name>.toml" | sha256sum }}`
+   - Calls your processing script
+4. Document the meta-config in this file
+
+## Comparison with `.managed/`
+
+| Aspect       | `meta/`                            | `.managed/`                             |
+| ------------ | ---------------------------------- | --------------------------------------- |
+| Deployed     | No                                 | Yes (via symlinks)                      |
+| Purpose      | Drive imperative scripts           | Source of truth for app configs         |
+| Consumed by  | Chezmoi scripts                    | Applications (via symlinks)             |
+| Location     | Repo root                          | Inside `home/`                          |