@sebastienrousseau/dotfiles 0.2.520 → 0.2.522

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

@@ -1,130 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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,158 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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,171 +0,0 @@
----
-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

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

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