@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/adr/ADR-004-cli-architecture.md

@@ -0,0 +1,171 @@
+---
+render_with_liquid: false
+---
+
+# ADR-004: Chezmoi + Custom CLI Wrapper Architecture
+
+**Status**: Accepted
+**Date**: 2026-02-09
+**Authors**: @sebastienrousseau
+
+## Context
+
+Managing dotfiles requires:
+
+- Tracking file changes and applying them consistently
+- Handling platform-specific configurations
+- Supporting encrypted secrets
+- Providing a good developer experience
+
+Options considered:
+
+1. **Bare git repository**: Simple but poor UX, no templating
+2. **GNU Stow**: Symlink-based, limited features
+3. **Chezmoi only**: Powerful but complex CLI
+4. **Custom from scratch**: High maintenance burden
+5. **Chezmoi + wrapper**: Best of both worlds
+
+## Decision
+
+Use **Chezmoi as the core engine** with a **custom `dot` CLI wrapper** that:
+
+### Architecture
+
+```text
+┌─────────────────────────────────────────────┐
+│                 dot CLI                      │
+│  (User-friendly interface, custom commands)  │
+├─────────────────────────────────────────────┤
+│              Command Modules                 │
+│  core │ diagnostics │ tools │ appearance    │
+│  secrets │ security │ meta                   │
+├─────────────────────────────────────────────┤
+│              Shared Library                  │
+│  utils.sh (resolve_source_dir, run_script)  │
+├─────────────────────────────────────────────┤
+│                 Chezmoi                      │
+│  (Template engine, state management, apply)  │
+└─────────────────────────────────────────────┘
+```
+
+### Core Principles
+
+**1. Chezmoi handles complexity:**
+
+- Template rendering with Go text/template
+- Encrypted secrets with age
+- State tracking (what's applied vs source)
+- Cross-platform path handling
+
+**2. dot CLI handles UX:**
+
+- Memorable command names (`dot sync` vs `chezmoi apply`)
+- Domain-specific commands (`dot doctor`, `dot theme`)
+- Integration with external tools (Nix, Docker, Neovim)
+- Consistent help and error messages
+
+**3. Modular command structure:**
+
+```text
+scripts/dot/
+├── lib/
+│   └── utils.sh          # Shared functions
+└── commands/
+    ├── core.sh           # apply, sync, update, add, diff
+    ├── diagnostics.sh    # doctor, heal, health, benchmark
+    ├── tools.sh          # tools, new, packages
+    ├── appearance.sh     # theme, wallpaper, fonts
+    ├── secrets.sh        # secrets-init, secrets
+    ├── security.sh       # firewall, backup, encrypt-check
+    └── meta.sh           # upgrade, docs, learn
+```
+
+**4. Delegation pattern:**
+
+```bash
+# Main dispatcher in dot CLI
+dispatch() {
+  local module="$1" cmd="$2"
+  shift 2
+  exec bash "$src_dir/scripts/dot/commands/$module.sh" "$cmd" "$@"
+}
+```
+
+### Chezmoi Integration Points
+
+| Feature | Chezmoi | dot CLI |
+|---------|---------|---------|
+| Apply changes | `chezmoi apply` | `dot sync` |
+| View diff | `chezmoi diff` | `dot diff` |
+| Edit secrets | `chezmoi edit --encrypted` | `dot secrets` |
+| Source directory | `chezmoi source-path` | `dot cd` |
+| Health check | `chezmoi doctor` | `dot doctor` (extended) |
+
+### Extension Points
+
+Custom commands can:
+
+1. Wrap chezmoi commands with better defaults
+2. Add entirely new functionality (benchmarks, themes)
+3. Integrate with system tools (nix, docker, brew)
+4. Provide interactive experiences (tour, learn)
+
+## Consequences
+
+### Positive
+
+- Leverage Chezmoi's battle-tested engine
+- User-friendly interface for common tasks
+- Easy to add domain-specific commands
+- Modular structure enables testing and maintenance
+- Single entry point (`dot`) for all operations
+
+### Negative
+
+- Two layers to understand (chezmoi + dot)
+- Version coupling between chezmoi and scripts
+- Some chezmoi features not exposed via dot
+
+### Neutral
+
+- Advanced users can still use chezmoi directly
+- Documentation needed for both layers
+- Upgrade path when chezmoi adds new features
+
+## Implementation Notes
+
+### Adding a New Command
+
+1. Identify the appropriate module (or create new one)
+2. Add function `cmd_<name>()` to module
+3. Add case to module's dispatch
+4. Add case to main dot CLI dispatcher
+5. Update help text
+6. Add tests if complex
+
+### Module Template
+
+```bash
+#!/usr/bin/env bash
+# Dotfiles CLI - <Category> Commands
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/utils.sh"
+
+cmd_example() {
+  # Implementation
+}
+
+case "${1:-}" in
+  example) shift; cmd_example "$@" ;;
+  *) echo "Unknown command: ${1:-}" >&2; exit 1 ;;
+esac
+```
+
+## References
+
+- [Chezmoi Documentation](https://www.chezmoi.io/)
+- [Command Pattern](https://refactoring.guru/design-patterns/command)
+- [Unix Philosophy](https://en.wikipedia.org/wiki/Unix_philosophy)

package/docs/adr/ADR-005-chezmoi-choice.md

@@ -0,0 +1,99 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
+# ADR-005: Chezmoi as Dotfiles Manager
+
+**Status**: Accepted
+**Date**: 2026-02-09
+**Authors**: @sebastienrousseau
+
+## Context
+
+Managing dotfiles across multiple machines requires:
+
+- Version control for configuration files
+- Template support for machine-specific values
+- Cross-platform compatibility (macOS, Linux, WSL)
+- Encrypted secrets management
+- Easy installation and updates
+
+Several approaches were considered for dotfiles management.
+
+## Decision
+
+Use **chezmoi** as the primary dotfiles management tool.
+
+### Alternatives Considered
+
+| Tool | Pros | Cons |
+|------|------|------|
+| **GNU Stow** | Simple, no dependencies | No templating, symlink-only |
+| **yadm** | Git-based, encryption | Limited templating |
+| **Bare Git** | Simple, no tools | No templating, manual management |
+| **Ansible** | Powerful, idempotent | Heavy, complex for dotfiles |
+| **Nix Home Manager** | Declarative, reproducible | Steep learning curve, Nix dependency |
+
+### Why Chezmoi
+
+1. **Template Support**: Go text/template for machine-specific configuration
+2. **Encryption**: Built-in age/gpg encryption for secrets
+3. **Cross-Platform**: Native support for macOS, Linux, Windows
+4. **Single Binary**: No runtime dependencies
+5. **Git Integration**: Works with any Git host
+6. **Dry-Run**: Preview changes before applying
+7. **Active Development**: Well-maintained with responsive maintainer
+
+## Implementation
+
+```bash
+# Installation
+sh -c "$(curl -fsLS get.chezmoi.io)"
+
+# Initialize from repository
+chezmoi init https://github.com/user/dotfiles.git
+
+# Apply configuration
+chezmoi apply
+```
+
+### Template Example
+
+```go
+{{- if eq .chezmoi.os "darwin" }}
+# macOS-specific configuration
+{{- else if eq .chezmoi.os "linux" }}
+# Linux-specific configuration
+{{- end }}
+```
+
+## Consequences
+
+### Positive
+
+- Consistent configuration across all machines
+- Secure secrets management with age encryption
+- Easy to add new machines to the fleet
+- Template-driven configuration reduces duplication
+- Built-in diff and dry-run for safe updates
+
+### Negative
+
+- Learning curve for Go templates
+- Additional abstraction layer over raw Git
+- Requires chezmoi binary installation
+- Some features (scripts) require careful ordering
+
+### Neutral
+
+- Configuration stored in `~/.local/share/chezmoi` by default
+- Custom wrapper CLI (`dot`) provides simpler interface
+- Regular `git` commands still work in source directory
+
+## References
+
+- [Chezmoi Documentation](https://www.chezmoi.io/)
+- [Chezmoi Quick Start](https://www.chezmoi.io/quick-start/)
+- [Comparison with Other Tools](https://www.chezmoi.io/comparison-table/)
+{% endraw %}

package/docs/adr/ADR-006-shell-selection.md

@@ -0,0 +1,124 @@
+---
+render_with_liquid: false
+---
+
+# ADR-006: Zsh as Default Shell
+
+**Status**: Accepted
+**Date**: 2026-02-09
+**Authors**: @sebastienrousseau
+
+## Context
+
+Choosing a default shell impacts:
+
+- Developer productivity and workflow
+- Plugin ecosystem and extensibility
+- Cross-platform compatibility
+- Startup performance
+- Learning curve for new users
+
+## Decision
+
+Use **Zsh** as the default interactive shell with **Zinit** as the plugin manager.
+
+### Alternatives Considered
+
+| Shell | Pros | Cons |
+|-------|------|------|
+| **Bash** | Universal, stable, POSIX | Limited interactive features |
+| **Zsh** | Rich features, great plugins | Slower than bash (mitigated) |
+| **Fish** | Modern, user-friendly | Not POSIX, less portable |
+| **Nushell** | Structured data, modern | Breaking changes, immature |
+
+### Why Zsh
+
+1. **Default on macOS**: Pre-installed since Catalina
+2. **Plugin Ecosystem**: Massive library of plugins and themes
+3. **Compatibility**: POSIX-compatible, smooth migration from bash
+4. **Completion System**: Superior tab completion
+5. **Customization**: Highly configurable prompt and behavior
+6. **Community**: Large community, well-documented
+
+### Why Zinit
+
+| Plugin Manager | Load Time | Features |
+|----------------|-----------|----------|
+| Oh-My-Zsh | ~800ms | Monolithic, many plugins |
+| Prezto | ~400ms | Faster, modular |
+| **Zinit** | ~200ms | Turbo mode, fine control |
+| Antibody | ~300ms | Simple, fast |
+
+Zinit provides:
+
+- **Turbo Mode**: Deferred loading after prompt
+- **Ice Modifiers**: Fine-grained control over plugin loading
+- **Binary Installation**: Install completions and binaries
+- **Profiling**: Built-in load time profiling
+
+## Implementation
+
+### Shell Layer System
+
+```text
+dot_config/zsh/rc.d/
+├── 00-10: Core (env, history, options)
+├── 20-49: Middleware (zinit, completions)
+├── 50-89: Toolchain (languages, tools)
+└── 90-99: UX (prompt, aliases, keybindings)
+```
+
+### Zinit Configuration
+
+```zsh
+# Turbo mode: load after prompt displays
+zinit ice wait lucid
+zinit light zsh-users/zsh-autosuggestions
+
+# Synchronous: needed immediately
+zinit light zdharma-continuum/fast-syntax-highlighting
+```
+
+### Performance Targets
+
+| Metric | Target | Achieved |
+|--------|--------|----------|
+| Cold Start | <500ms | ~300ms |
+| Warm Start | <200ms | ~150ms |
+| Plugin Load | Async | Yes |
+
+## Consequences
+
+### Positive
+
+- Fast, responsive shell experience
+- Rich plugin ecosystem (autosuggestions, syntax highlighting)
+- Powerful completion system
+- Compatible with existing bash scripts
+- Modern prompt with Starship
+
+### Negative
+
+- Requires zsh installation on some Linux distros
+- Plugin manager adds complexity
+- Some bash-isms need adjustment
+- Turbo mode can cause brief visual delay
+
+### Neutral
+
+- Users can still use bash for scripts
+- Configuration more complex than vanilla shell
+- Performance monitoring needed
+
+## Performance Optimizations
+
+1. **Caching**: Compile zsh files to `.zwc` bytecode
+2. **Lazy Loading**: Defer heavy tools (nvm, rvm) until first use
+3. **Turbo Mode**: Load plugins after prompt displays
+4. **Conditional Loading**: Skip unused features
+
+## References
+
+- [Zsh Documentation](https://zsh.sourceforge.io/Doc/)
+- [Zinit Wiki](https://zdharma-continuum.github.io/zinit/wiki/)
+- [Starship Prompt](https://starship.rs/)

package/docs/adr/ADR-007-multi-shell-parity.md

@@ -0,0 +1,62 @@
+---
+render_with_liquid: false
+---
+
+# ADR-007: Multi-Shell Parity Strategy
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-08
+
+## Context
+
+The dotfiles distribution supports three shells: Zsh (default since macOS Catalina), Fish (modern interactive shell), and Nushell (structured data shell). The codebase has 98 alias files and 52+ functions written in POSIX/Bash. Without a parity strategy, each shell gets a fragmented subset of functionality.
+
+**Problem:** Fish had zero access to the alias/function library until v0.2.501 added bridge templates. Nushell had only 6 hardcoded aliases and no function access.
+
+**Constraints:**
+
+- Nushell's `source` is parse-time evaluated (no dynamic sourcing)
+- Fish syntax differs significantly from POSIX (no `$()`, different `if`, no `[[`)
+- Maintaining N copies of every alias/function is unsustainable
+
+## Decision
+
+Adopt a **hub-and-spoke bridge architecture**:
+
+1. **Hub:** Canonical definitions live in `.chezmoitemplates/aliases/` (Bash/POSIX) and `.chezmoitemplates/functions/` (Bash)
+2. **Bash/Zsh spoke:** Direct inclusion via `90-ux-aliases.sh.tmpl` and `50-logic-functions.sh.tmpl`
+3. **Fish spoke:** Runtime bash bridge with caching (`aliases.fish.tmpl`, `functions.fish.tmpl`)
+4. **Nushell spoke:** Hybrid approach:
+   - Aliases: Runtime bash extraction cached to `~/.cache/nushell/bash-aliases.nu` (in `env.nu.tmpl`), sourced by `aliases.nu.tmpl`
+   - Functions: Chezmoi template-generated `def` wrappers delegating to bash (in `functions.nu.tmpl`)
+
+**Parity tiers:**
+
+- **Tier 1 (Full):** Zsh, Bash — all aliases, functions, lazy loading, cached eval
+- **Tier 2 (Bridged):** Fish — all simple aliases, all functions via wrappers, `_cached_eval` caching
+- **Tier 3 (Compatible):** Nushell — simple aliases (no complex bash syntax), all functions via bash delegation
+
+## Consequences
+
+### Positive
+
+- Single source of truth for aliases and functions
+- Adding a new alias/function automatically propagates to all shells
+- Nushell users get access to 40+ functions that were previously unavailable
+- Fish users get mtime-aware caching via `_cached_eval`
+
+### Negative
+
+- Complex bash aliases (pipes, conditionals) are skipped for Nushell
+- Function calls in Fish/Nushell incur bash subprocess overhead (~5ms per call)
+- Cache invalidation requires shell restart or manual cache clear
+
+### Risks
+
+- Nushell's rapid development may break bridge syntax in future versions
+- Very large alias sets may slow Nushell startup during cache generation

package/docs/adr/ADR-008-alias-system-architecture.md

@@ -0,0 +1,95 @@
+---
+render_with_liquid: false
+---
+
+# ADR-008: Alias System Architecture
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-08
+
+## Context
+
+The dotfiles manage 98 alias files across 30+ categories (git, docker, kubernetes, python, security, etc.). These need to load fast, support per-machine toggling, and work across Zsh, Bash, Fish, and Nushell.
+
+**Design questions:**
+
+1. How to organize alias files for maintainability?
+2. How to control which aliases load on which machines?
+3. How to balance startup speed with alias availability?
+4. How to bridge POSIX aliases to non-POSIX shells?
+
+## Decision
+
+### Organization
+
+Aliases are organized by tool/domain in `.chezmoitemplates/aliases/<category>/<name>.aliases.sh`:
+
+```text
+aliases/
+  git/git.aliases.sh, signing.aliases.sh
+  docker/docker.aliases.sh
+  kubernetes/kubernetes.aliases.sh
+  security/crypto-utils.aliases.sh, ssh-keys.aliases.sh, ...
+  default/default.aliases.sh
+  ...
+```
+
+### Profile Tiers
+
+Three profiles control alias scope (set in `.chezmoidata.toml`):
+
+| Profile | Scope | Use Case |
+|---------|-------|----------|
+| `minimal` | Core only, excludes interactive/sudo | Servers, containers |
+| `standard` | All core + selected ecosystem | Laptops, workstations |
+| `full` | Everything including heavy/specialized | Dev machines |
+
+### Bucket Toggles
+
+Per-category flags in `.chezmoidata.toml` under `[aliases.buckets]`:
+
+```toml
+[aliases.buckets]
+system = true
+svn = false    # disable on machines without SVN
+```
+
+### Two-Phase Loading
+
+1. **Eager (90-ux-aliases.sh):** Core categories loaded at shell startup (~40KB). Includes: archives, cd, clear, configuration, default, diagnostics, disk-usage, editor, git, interactive, installer, mkdir, modern, ps, rsync, sudo, system.
+
+2. **Lazy (91-ux-aliases-lazy.sh):** Ecosystem aliases deferred until first prompt via `precmd` hook. Includes: docker, kubernetes, terraform, gcloud, python, npm, rust, security, etc.
+
+### Function Groups (groups.json)
+
+Functions use a parallel system with `groups.json` as a registry:
+
+- Groups: api, curl, text, system, files, interactive, nav, security, misc
+- Lazy-loaded per group on first invocation
+- Stub functions replaced with real implementations on first call
+
+## Consequences
+
+### Positive
+
+- Adding aliases is self-service: create a file in the right category
+- Per-machine customization without forking
+- Lazy loading keeps startup under 200ms even with 98 alias files
+- `groups.json` enables automated bridge generation for Fish/Nushell
+
+### Negative
+
+- Alias definitions wrap in functions (`set_default_aliases()`) for sourcing safety, adding complexity
+- Two-phase loading means some aliases aren't available until after first prompt
+- Profile/bucket system requires understanding .chezmoidata.toml
+
+### Trade-offs
+
+- Chose file-per-category over monolithic alias file for maintainability
+- Chose runtime extraction for Fish/Nushell over maintaining parallel definitions
+- Chose lazy loading over compile-time bundling for flexibility

package/docs/adr/ADR-009-wallpaper-driven-theming.md

@@ -0,0 +1,131 @@
+---
+render_with_liquid: false
+---
+
+# ADR-009: Wallpaper-Driven Theming Engine
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-12
+
+## Context
+
+Most dotfiles distributions ship a small fixed palette (Solarized, Gruvbox,
+Tokyo Night) chosen once and recycled across every terminal, editor, and
+status bar. When the user changes wallpapers — a daily occurrence on macOS
+with HEIC dark/light variants and on Linux with `swww`/`hyprpaper` —
+terminal chrome stays static, creating visual incoherence between the
+chosen wallpaper and the surrounding tooling.
+
+Manual palette switching solves coherence but adds friction: it requires
+the user to (a) generate a palette, (b) regenerate config for every tool
+(`alacritty.toml`, `kitty.conf`, `wezterm.lua`, neovim themes, …), and
+(c) reload each tool. Tools like pywal/wal automate (a) and (b), but
+pywal palettes routinely fail WCAG contrast thresholds (especially for
+bright wallpapers) and lack support for many of the format files this
+project ships.
+
+**Problem:** Reuse the user's chosen wallpaper as the single source of
+truth for terminal + status-bar colors, with accessibility guaranteed and
+no manual regeneration step.
+
+**Constraints:**
+
+- Output must satisfy **WCAG 2.2 AAA contrast** (≥ 7:1 for normal text,
+  ≥ 4.5:1 for large text) — non-negotiable, the dotfiles ship as
+  workstation infrastructure.
+- Palette extraction must work offline on both macOS (HEIC, dynamic
+  wallpapers with embedded dark/light variants) and Linux (PNG/JPEG via
+  `swww`, `hyprpaper`, `feh`, GNOME).
+- Total time from "user changes wallpaper" → "all terminals retinted"
+  must be ≤ 3 seconds (rebuild trigger + write of templated configs).
+- Targets include Warp, iTerm2, Alacritty, Ghostty, Kitty, Wezterm,
+  Tmux, Neovim (multiple themes), VS Code, Firefox theme JSON, Niri
+  borders, Waybar, GTK/Qt (matugen pipeline).
+
+## Decision
+
+Build a self-contained theming engine — `dot theme rebuild` —
+implemented in `scripts/theme/` with the following pipeline:
+
+1. **Source detection** — locate the active wallpaper across macOS
+   (`defaults read … wallpaper`), GNOME/dconf, KDE, Niri, swww,
+   hyprpaper. HEIC dynamic wallpapers decompose into dark and light
+   variants; both feed the engine.
+
+2. **Color extraction** — **K-Means clustering in CIELAB** (not RGB).
+   CIELAB is perceptually uniform, so distances correlate with the way
+   humans see color similarity. 8-cluster K-Means yields a 16-color
+   ANSI palette (8 normal + 8 bright) plus 4 accent slots.
+
+3. **Contrast enforcement** — compute WCAG 2.2 contrast against the
+   chosen background; nudge each foreground hue along the lightness
+   axis until the ratio passes AAA. The nudge stays within the cluster
+   to preserve aesthetic intent. If AAA cannot be reached, fall back to
+   AA with a logged warning (never silently regress).
+
+4. **Format generation** — emit one canonical TOML palette to
+   `.chezmoidata/themes.toml`, then run `chezmoi apply` so every
+   theme-aware template (terminals, editors, status bars, browsers)
+   regenerates from a single declarative source.
+
+5. **Companion pipelines** — `dot-theme-sync` feeds the same accent
+   colors to **matugen** for Material You-style GTK/Qt theming on
+   Linux, keeping desktop chrome in lockstep with the terminal.
+
+The whole flow is idempotent (`chezmoi apply` is no-op if nothing
+changed), repeatable, and tested under `tests/unit/theme/`.
+
+## Consequences
+
+### Positive
+
+- Single source of truth: change the wallpaper, every tool retints in
+  one keystroke.
+- Accessibility is structural, not opt-in — every shipped palette
+  passes WCAG AAA before it touches a config file.
+- No competing "premium" dotfiles distribution (mathiasbynens, holman,
+  paulirish, omakub) ships anything similar. The engine is a defining
+  differentiator and surfaced in the README hero.
+- Reuses chezmoi's templating — no new templating layer to maintain.
+
+### Negative
+
+- K-Means on a 4K wallpaper takes ~500–800 ms; cached after first run,
+  but the cold path is non-trivial.
+- HEIC handling on Linux requires `libheif` (extra dep on Debian/Ubuntu
+  before 24.04).
+- Contrast enforcement can produce slightly different palettes from the
+  same wallpaper across major OS versions when system color profiles
+  differ (mitigated by snapshot tests).
+
+### Risks
+
+- Wallpapers with extreme dynamic range (pure-white backgrounds, deep
+  monochrome) may fail to produce an aesthetically pleasing 16-color
+  palette even when WCAG AAA is satisfied. Mitigation: maintainer
+  curation of a fallback theme set in `.chezmoidata/themes.toml`.
+- Future Wayland compositors may not expose a stable wallpaper-detection
+  API. The engine isolates source detection in a single module so the
+  blast radius of compositor churn is one file.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| pywal/wal | RGB K-Means, no WCAG enforcement, limited target list. |
+| matugen alone | Excellent for GTK/Qt; not terminal-aware. We use it *in addition*, not instead. |
+| Static curated themes (Tokyo Night et al.) | Loses the "wallpaper coherence" property that motivates the whole project. |
+| Hand-roll per-terminal scripts | Doesn't compose with chezmoi; loses the single-source-of-truth invariant. |
+
+## References
+
+- WCAG 2.2 contrast: <https://www.w3.org/TR/WCAG22/#contrast-minimum>
+- CIELAB color space: <https://en.wikipedia.org/wiki/CIELAB_color_space>
+- `scripts/theme/` — engine source
+- `.chezmoidata/themes.toml` — output palette schema
+- Issue #873 — captures this ADR alongside `llms.txt`