@sebastienrousseau/dotfiles 0.2.481 → 0.2.499

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

@@ -1,101 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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

@@ -1,140 +0,0 @@
-# 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

@@ -1,157 +0,0 @@
-# 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

@@ -1,89 +0,0 @@
-# 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/)