@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

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

@@ -0,0 +1,115 @@
+# 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,53 @@
+# 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.500 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,85 @@
+# 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/README.md

@@ -0,0 +1,32 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) that document
+significant architectural decisions made in this project.
+
+## Index
+
+| ADR | Title | Status |
+|-----|-------|--------|
+| [ADR-001](ADR-001-ci-cd-pipeline.md) | Multi-stage CI/CD Pipeline Design | Accepted |
+| [ADR-002](ADR-002-shell-performance.md) | Shell Performance Optimization Strategy | Accepted |
+| [ADR-003](ADR-003-security-first.md) | Security-First Approach | Accepted |
+| [ADR-004](ADR-004-cli-architecture.md) | Chezmoi + Custom CLI Wrapper Architecture | Accepted |
+| [ADR-005](ADR-005-chezmoi-choice.md) | Chezmoi as Dotfiles Manager | Accepted |
+| [ADR-006](ADR-006-shell-selection.md) | Zsh as Default Shell | Accepted |
+| [ADR-007](ADR-007-multi-shell-parity.md) | Multi-Shell Parity Strategy | Accepted |
+| [ADR-008](ADR-008-alias-system-architecture.md) | Alias System Architecture | Accepted |
+
+## ADR Format
+
+Each ADR follows this structure:
+
+- **Status**: Proposed, Accepted, Deprecated, Superseded
+- **Context**: The situation and forces at play
+- **Decision**: The change being made
+- **Consequences**: The resulting context after applying the decision
+
+## References
+
+- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+- [ADR Tools](https://github.com/npryce/adr-tools)
+

package/docs/architecture/ARCHITECTURE.md

@@ -0,0 +1,113 @@
+# Architecture
+
+Core architectural decisions and system design of the dotfiles shell distribution.
+
+---
+
+## Philosophy
+
+- **XDG-First**: Configuration lives under `~/.config/` to keep the home directory clean.
+- **Multi-Shell**: First-class support for Zsh, Fish, and Nushell with a shared logic core.
+- **Fast Startup**: Heavy features are deferred or autoloaded to keep the first prompt under 50ms.
+- **Deterministic**: Nix Flakes provide bit-for-bit identical environments across machines.
+- **Non-Blocking**: Background daemons (Pueue) handle upgrades and builds without stalling the shell.
+
+## System Layout
+
+```text
+~/.dotfiles/
+├── dot_config/          # Managed application configurations (~/.config/)
+│   ├── zsh/             # Modular Zsh rc.d architecture
+│   ├── fish/            # Autoloading Fish configuration
+│   ├── nushell/         # Structured data shell config
+│   ├── shell/           # Shared logic (aliases, paths, functions)
+│   └── ...              # 50+ tool configurations (nvim, tmux, ghostty, etc.)
+├── dot_local/           # Local binaries and scripts (~/.local/bin/)
+├── .chezmoitemplates/   # Unified source for aliases, functions, and paths
+├── scripts/             # Internal libraries and diagnostics
+├── nix/                 # Nix Flake for deterministic toolchains
+├── lib/wasm-tools/      # Rust source for Wasm utilities
+└── install.sh           # Universal bootstrap script (zero dependencies)
+```
+
+---
+
+## Shell Startup Strategies
+
+### Shared: `_cached_eval`
+
+Across Zsh, Fish, and Bash, an idempotent caching wrapper avoids redundant tool initialization (Starship, Zoxide, Atuin).
+
+1. **Intercept** — check if a cached version of the tool's `eval` output exists in `~/.cache/shell/`.
+2. **Validate** — compare the cache timestamp against the tool binary's mtime.
+3. **Bypass** — if valid, `source` the cached text directly, saving 20-50ms per tool.
+
+### Lazy-Hydration Model
+
+To reach a fluid first-prompt target (< 50ms), the shell uses a three-phase startup:
+
+1. **Phase 1 (Visual Paint)** — render the prompt immediately using static escape codes.
+2. **Phase 2 (Async Hydration)** — dispatch tool initializations (mise, atuin, etc.) to background workers.
+3. **Phase 3 (On-Demand Activation)** — environment hydration occurs on first user interaction or after 500ms of idle time.
+
+---
+
+## Artifact Mode
+
+A minimal environment triggered by `DOTFILES_ARTIFACT_MODE=1`.
+
+- **Minimalist UI** — strips prompt complexity, leaving only a green `->`.
+- **Intelligence Surface** — an async Bento-style dashboard rendered via `bento.sh` that provides environment context (Node version, cloud status, Git health) without blocking the main thread.
+- **Redraw Signaling** — uses `SIGWINCH` to return control after background hydration completes.
+
+---
+
+## Ultra-Fast Mode
+
+Set `DOTFILES_ULTRA_FAST=1` to skip all non-essential initialization. Only core paths, aliases, and the prompt are loaded. Useful for:
+
+- CI/CD pipelines where full shell setup is unnecessary
+- Rapid scripting sessions where startup latency matters
+- Benchmarking baseline shell performance
+
+---
+
+## Debug and Trace Modes
+
+### DOTFILES_DEBUG=1
+
+Enables verbose diagnostic output during shell startup. Prints which files are sourced and their load times.
+
+### DOTFILES_TRACE=1
+
+Enables `set -x` tracing for the entire shell startup sequence. Output is written to `~/.local/state/dotfiles/debug.log` for post-mortem analysis.
+
+---
+
+## Function Groups (groups.json)
+
+Functions are organized into groups defined in `.chezmoitemplates/functions/groups.json`:
+
+| Group | Functions | Description |
+|-------|-----------|-------------|
+| `api` | apihealth, apilatency, apiload | API testing utilities |
+| `curl` | curlheader, curlstatus, curltime, httpdebug | HTTP debugging |
+| `text` | encode64, kebabcase, lowercase, titlecase, ... | Text transformation |
+| `system` | environment, freespace, hostinfo, myproc, sysinfo | System introspection |
+| `files` | backup, extract, hexdump, hiddenfiles, size, zipf | File operations |
+| `interactive` | banner, emoji, matrix, rainbow, stopwatch | Terminal fun |
+| `nav` | cdls, goto, ql | Navigation shortcuts |
+| `security` | genpass, keygen, mount_read_only | Security utilities |
+| `misc` | dothelp, view-source, prependpath, caffeine | Miscellaneous |
+
+Groups are lazy-loaded: stub functions are defined at startup, and the real implementation is loaded on first invocation. This keeps startup fast while providing 52+ functions on demand.
+
+The `groups.json` schema maps group names to arrays of relative paths (including subdirectory):
+
+```json
+{
+  "group_name": ["group_name/function1.sh", "group_name/function2.sh"]
+}
+```
+
+Each `.sh` file lives in a subdirectory matching its group and defines a single function with the same name as the file (minus `.sh` extension).

package/docs/architecture/INTEROP.md

@@ -0,0 +1,36 @@
+# Cross-Platform Interoperability
+
+How dotfiles commands and shims map across macOS, Linux, and WSL2.
+
+## Command Mapping
+
+| Alias / Command | macOS | Linux (Debian/Arch) | WSL2 (Windows Host) |
+| :--- | :--- | :--- | :--- |
+| `cb` (Clipboard) | `pbcopy` / `pbpaste` | `xclip` / `wl-copy` | `clip.exe` / `powershell.exe` |
+| `open` | `open` | `xdg-open` | `wslview` / `explorer.exe` |
+| `notify` | `osascript` (AppleScript) | `notify-send` / `gum log` | `powershell.exe` (Toast) / `gum` |
+| `win` (Paths) | N/A | N/A | `wslpath` |
+| `browser` | `open` | `xdg-open` | `powershell.exe Start-Process` |
+
+## Infrastructure Parity
+
+| Feature | macOS | Linux | WSL2 |
+| :--- | :--- | :--- | :--- |
+| **Package Manager** | Homebrew (`brew`) | `apt` / `pacman` / `nix` | `apt` + Windows binaries |
+| **Shell Startup** | Async lazy-hydration | Async lazy-hydration | Async (optimized for IO) |
+| **Environment** | native plist / launchctl | systemd / dbus | systemd (if enabled) / init |
+| **Hardware** | Secure Enclave | TPM 2.0 / LUKS | Windows Hello bridge |
+
+## Troubleshooting
+
+### WSL2 IO Latency
+Keep projects in the Linux filesystem (`~/...`), not under `/mnt/c/`.
+
+### WSL2 Windows Binary Path
+If you've disabled WSL path sharing, make sure Windows-side binaries like `clip.exe` and `explorer.exe` are still reachable in `$PATH`.
+
+### macOS Permissions
+Grant your terminal "Full Disk Access" in System Settings so dotfiles can manage all configurations.
+
+### Linux GUI Fallbacks
+In headless environments, GUI commands like `cb` and `open` fall back to `gum log` or terminal bell instead of hanging.