@sebastienrousseau/dotfiles 0.2.469 → 0.2.481

package/docs/adr/ADR-001-ci-cd-pipeline.md

@@ -0,0 +1,101 @@
+# ADR-001: Multi-stage CI/CD Pipeline Design
+
+**Status**: Accepted
+**Date**: 2026-02-09
+**Authors**: @sebastienrousseau
+
+## Context
+
+The dotfiles repository requires a CI/CD pipeline that:
+- Validates changes across multiple platforms (Linux, macOS)
+- Runs security scans to detect secrets and vulnerabilities
+- Tests shell scripts, Lua configurations, and Nix expressions
+- Maintains fast feedback loops for developers
+- Minimizes GitHub Actions costs (runner minutes)
+
+Traditional approaches run all checks on every commit, leading to:
+- Wasted compute on unrelated changes (e.g., running Lua linting when only docs change)
+- High costs from macOS runners ($0.08/min vs $0.008/min for Linux)
+- Long feedback times from sequential job execution
+
+## Decision
+
+Implement a **5-stage progressive CI pipeline** with path-based filtering:
+
+### Stage 1: Change Detection
+Use `dorny/paths-filter` to detect which file categories changed:
+- `shell`: *.sh, scripts/**, install/**
+- `lua`: dot_config/nvim/**, *.lua
+- `nix`: nix/**, *.nix
+- `config`: dot_*/**, .chezmoitemplates/**
+
+### Stage 2: Lint (Parallel, Conditional)
+- **lint-shell**: Only runs if shell files changed
+- **lint-lua**: Only runs if Lua files changed
+- Run in parallel to minimize wall-clock time
+
+### Stage 3: Security (Always on PRs)
+- **secrets-scan**: Gitleaks on every PR (critical)
+- **link-check**: Only on schedule (expensive)
+
+### Stage 4: Test (Conditional Matrix)
+- Linux-only for PRs (cheapest)
+- Full matrix (Linux + macOS) on schedule/manual trigger
+- Docker container tests for installation validation
+
+### Stage 5: Quality (Schedule/Manual Only)
+- Idempotency verification
+- Performance benchmarks
+- Nix flake checks
+
+### Cost Optimization Strategies
+
+1. **Path filters**: Skip jobs when files don't match
+2. **Concurrency groups**: Cancel in-progress runs on new pushes
+3. **Conditional matrices**: Expensive OS testing only on schedule
+4. **Aggressive caching**: Tools, dependencies, databases
+
+## Consequences
+
+### Positive
+- ~50% reduction in GitHub Actions minutes
+- Fast feedback for most changes (1-3 minutes)
+- Comprehensive testing still available via schedule/manual
+- Clear separation of concerns between stages
+
+### Negative
+- Complexity in workflow configuration
+- Some bugs might only surface in scheduled runs
+- Path filter maintenance required as repo structure evolves
+
+### Neutral
+- Developers can trigger full CI manually with `workflow_dispatch`
+- Breaking changes to CI require testing across all stages
+
+## Implementation
+
+```yaml
+# Key patterns used
+on:
+  push:
+    paths:
+      - '**.sh'  # Only trigger on shell changes
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  changes:
+    outputs:
+      shell: ${{ steps.filter.outputs.shell }}
+
+  lint-shell:
+    needs: changes
+    if: needs.changes.outputs.shell == 'true'
+```
+
+## References
+
+- [GitHub Actions Path Filtering](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)
+- [dorny/paths-filter](https://github.com/dorny/paths-filter)

package/docs/adr/ADR-002-shell-performance.md

@@ -0,0 +1,121 @@
+# ADR-002: Shell Performance Optimization Strategy
+
+**Status**: Accepted
+**Date**: 2026-02-09
+**Authors**: @sebastienrousseau
+
+## Context
+
+Shell startup time directly impacts developer productivity. Every new terminal,
+tmux pane, or shell command execution incurs this cost. With rich shell
+configurations (completions, prompts, plugins), startup can easily exceed 1-2
+seconds.
+
+Goals:
+- Target startup time: <500ms for interactive shells
+- Maintain full functionality (completions, syntax highlighting, git info)
+- Support both zsh and bash
+- Work across macOS and Linux
+
+## Decision
+
+Implement a **multi-layer performance optimization strategy**:
+
+### Layer 1: Compilation and Caching
+
+```bash
+# Compile zsh files to .zwc format
+_cached_eval() {
+  local cache="$HOME/.cache/zsh/$1.zwc"
+  if [[ ! -f "$cache" || "$2" -nt "$cache" ]]; then
+    eval "$($2)" > "$cache.tmp"
+    zcompile "$cache.tmp" "$cache"
+  fi
+  source "$cache"
+}
+```
+
+- Compile frequently-sourced files to bytecode
+- Cache command output (brew shellenv, mise activate)
+- Invalidate cache when source files change
+
+### Layer 2: Lazy Loading
+
+Defer loading of heavy components until first use:
+
+```bash
+# Lazy load completions
+function kubectl() {
+  unfunction kubectl
+  source <(kubectl completion zsh)
+  kubectl "$@"
+}
+```
+
+- Completions loaded on first command use
+- NVM/RVM loaded only when node/ruby commands invoked
+- Heavy plugins deferred via zinit's `wait` modifier
+
+### Layer 3: Zinit Turbo Mode
+
+```zsh
+zinit ice wait lucid
+zinit light zsh-users/zsh-autosuggestions
+```
+
+- Plugins load asynchronously after prompt
+- Critical plugins (syntax highlighting) load synchronously
+- Most plugins have 0ms impact on startup
+
+### Layer 4: Conditional Loading
+
+```bash
+# Only load if command exists
+[[ -x /opt/homebrew/bin/brew ]] && eval "$(/opt/homebrew/bin/brew shellenv)"
+
+# Skip in non-interactive shells
+[[ $- != *i* ]] && return
+```
+
+- Platform-specific code guarded by OS detection
+- Heavy features opt-in via environment variables
+- Non-interactive shells get minimal config
+
+### Monitoring
+
+Benchmark script to track startup time:
+```bash
+hyperfine --warmup 3 --runs 10 "zsh -i -c exit"
+```
+
+CI enforces 500ms threshold with warnings.
+
+## Consequences
+
+### Positive
+- Consistent <500ms startup across platforms
+- Full functionality preserved
+- Easy to add new tools without performance regression
+- Clear patterns for contributors to follow
+
+### Negative
+- First invocation of lazy-loaded commands is slower
+- Cache invalidation bugs can cause stale behavior
+- Complexity in understanding load order
+
+### Neutral
+- Profiling required when adding new plugins
+- Trade-off between convenience and performance explicit
+
+## Measurements
+
+| Configuration | Startup Time |
+|---------------|--------------|
+| Vanilla zsh | ~50ms |
+| With oh-my-zsh | ~800ms |
+| This approach | ~200-400ms |
+
+## References
+
+- [Zsh Startup Optimization](https://htr3n.github.io/2018/07/faster-zsh/)
+- [Zinit Turbo Mode](https://zdharma-continuum.github.io/zinit/wiki/INTRODUCTION/)

package/docs/adr/ADR-003-security-first.md

@@ -0,0 +1,140 @@
+# ADR-003: Security-First Approach
+
+**Status**: Accepted
+**Date**: 2026-02-09
+**Authors**: @sebastienrousseau
+
+## Context
+
+Dotfiles repositories present unique security challenges:
+- They configure system behavior and permissions
+- They may contain or reference secrets (API keys, tokens)
+- They execute scripts with user privileges
+- They're often cloned to multiple machines
+
+A security breach in dotfiles can compromise all systems using them.
+
+## Decision
+
+Implement a **defense-in-depth security model** with multiple layers:
+
+### Layer 1: Secrets Protection
+
+**Never commit secrets:**
+```bash
+# .gitleaks.toml - block common secret patterns
+[[rules]]
+id = "generic-api-key"
+regex = '''(?i)(api[_-]?key|apikey)\s*[:=]\s*['"]?([a-zA-Z0-9]{20,})'''
+```
+
+**Encrypted secrets with age:**
+```bash
+# Secrets stored encrypted, decrypted at apply time
+chezmoi.encryption = "age"
+chezmoi.age.identity = "~/.config/chezmoi/key.txt"
+```
+
+**CI enforcement:**
+- Gitleaks runs on every PR
+- TruffleHog for verified secrets detection
+- Block merge if secrets detected
+
+### Layer 2: Input Validation
+
+**Path traversal prevention:**
+```bash
+# Validate all user inputs
+if [[ ! "$template_lang" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+  die "Invalid template name: $template_lang"
+fi
+```
+
+**Safe file operations:**
+```bash
+# Use absolute paths, validate before operations
+local real_path
+real_path="$(realpath -m "$user_input")"
+if [[ "$real_path" != "$allowed_base"/* ]]; then
+  die "Path outside allowed directory"
+fi
+```
+
+### Layer 3: Opt-in System Modifications
+
+**Dangerous operations require explicit consent:**
+```bash
+# Security scripts are opt-in
+if [ "${DOTFILES_SECURITY:-0}" != "1" ]; then
+  echo "Security hardening is opt-in. Set DOTFILES_SECURITY=1 to enable."
+  exit 0
+fi
+```
+
+**Comprehensive logging:**
+```bash
+# All system modifications logged
+log_security_change() {
+  echo "[$(date -Iseconds)] $1" >> "$HOME/.local/share/dotfiles-security.log"
+}
+```
+
+### Layer 4: CI Security Scanning
+
+**Multi-tool approach:**
+- **Gitleaks**: Secrets in git history
+- **Shellcheck**: Shell script vulnerabilities
+- **Checkov**: Infrastructure misconfigurations
+- **Trivy**: Container vulnerabilities (when applicable)
+- **CodeQL**: Static analysis for Python/JavaScript
+
+**Weekly deep scans:**
+```yaml
+schedule:
+  - cron: '0 2 * * 0'  # Weekly security audit
+```
+
+### Layer 5: Minimal Privileges
+
+**Scripts request only needed permissions:**
+```bash
+# Don't run as root unless necessary
+if [ "$(id -u)" = "0" ]; then
+  die "This script should not run as root"
+fi
+
+# Use sudo only for specific commands
+sudo sysctl -w net.ipv4.tcp_keepalive_time=60
+```
+
+## Consequences
+
+### Positive
+- Secrets never enter git history
+- System modifications are auditable
+- Multiple layers catch different vulnerability types
+- Contributors have clear security patterns to follow
+
+### Negative
+- Additional complexity in scripts
+- Encrypted secrets require key management
+- Some features disabled by default (friction)
+
+### Neutral
+- Security vs convenience trade-offs explicit
+- Regular security audits via scheduled CI
+
+## Security Checklist for Contributors
+
+- [ ] No hardcoded secrets (use environment variables or age encryption)
+- [ ] Validate all user inputs
+- [ ] Use absolute paths for file operations
+- [ ] Document any system modifications
+- [ ] Test scripts with shellcheck
+- [ ] Add appropriate permission checks
+
+## References
+
+- [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/)
+- [Age Encryption](https://github.com/FiloSottile/age)
+- [Gitleaks](https://github.com/gitleaks/gitleaks)

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

@@ -0,0 +1,157 @@
+# 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
+
+```
+┌─────────────────────────────────────────────┐
+│                 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:**
+```
+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,89 @@
+# 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/)