@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/adr/ADR-010-starship-transient-prompt.md

@@ -0,0 +1,144 @@
+---
+render_with_liquid: false
+---
+
+# ADR-010: Enable Starship Transient Prompt in Zsh and Fish
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-12
+
+## Context
+
+Starship is the prompt renderer for both zsh and fish in this
+distribution (pinned via `mise.toml`: `starship = "1.24.2"`).
+A typical Starship prompt for this project renders 4–6 lines including
+the directory, git branch + dirty markers, language toolchain version,
+duration of the previous command, and a final `❯` line.
+
+By default Starship emits this multi-line prompt on **every** previous
+command as well as the current one. After 50 commands in a session, the
+terminal scrollback contains 200–300 lines of historical prompts — most
+of which only convey context that was relevant at the time the command
+ran. Search through scrollback (Ctrl-r history, copy-paste, screenshots,
+asciinema replay) is noisy.
+
+Starship 1.24+ supports a **transient prompt** feature: when a command
+finishes, the prompt that produced it is rewritten to a compact form
+(e.g., `❯`) and the full prompt is re-emitted only at the live editing
+line. The current command always shows the full prompt; history shows
+only the compact form.
+
+**Problem:** Reduce scrollback noise without sacrificing the live prompt's
+rich context, and apply it consistently across the two interactive
+shells we support as first-class.
+
+**Constraints:**
+
+- Must work in zsh and fish (the two Tier-1 shells per ADR-007).
+- Must not interfere with `_cached_eval`'s startup-cost optimization
+  (the transient hook fires per-prompt, not per-shell-start).
+- Must not break copy-paste of previous commands: the compact line
+  must still be `❯` (or similar) so `<Ctrl-shift-c>` over scrollback
+  yields runnable shell content if the user includes the prompt.
+
+## Decision
+
+Call Starship's `enable_transience` shell function after the cached
+`starship init` runs in each shell. We share one `starship.toml.tmpl`
+across both shells; the transient prompt content is the existing
+`[character]` block (no separate `[transient_*]` section needed).
+
+- **Fish**: `dot_config/fish/conf.d/init.fish.tmpl` calls
+  `enable_transience` once the function is defined. `starship init
+  fish` defines it via `--print-full-init`. Result: `$fish_transient_prompt`
+  flips to `1` and the Enter handler is bound to
+  `__starship_transient_execute`. The compact prompt collapses past
+  scrollback as soon as the next command runs.
+
+- **Zsh**: `dot_config/zsh/dot_zshrc.tmpl` carries the same
+  `enable_transience` call, guarded by
+  `(( ${+functions[enable_transience]} ))`. **Upstream Starship does
+  not ship a zsh-side `enable_transience` function yet** (tracked by
+  [starship/starship#3522](https://github.com/starship/starship/issues/3522)).
+  The guard returns 0, the block no-ops, and zsh keeps its full multi-
+  line prompt in scrollback for now. The code is a forward-compatibility
+  hook: when upstream ships the zsh function, the feature activates
+  automatically on the next `mise upgrade starship` with no zshrc edit.
+
+  Alternatives we rejected for zsh:
+
+  - **Roll our own `zle` widget that rewrites `$PROMPT` on Enter.**
+    Possible (the standard recipe overrides `accept-line` with a
+    transient widget). Rejected because:
+    (a) any hand-rolled implementation will conflict with upstream
+        once they ship the official function, forcing a removal,
+    (b) Starship's prompt is multi-line and ANSI-coloured; correctly
+        rewriting it from a custom widget requires duplicating
+        Starship's escape-code generation, which drifts with every
+        Starship release,
+    (c) it'd run inside `_cached_eval`'s eager-init path, complicating
+        the cache-invalidation semantics we documented in ADR-002.
+  - **Third-party zsh plugin (e.g. zsh-autocomplete's transient mode).**
+    Rejected because the upstream Starship fix is in active discussion
+    and a plugin adds a permanent dependency we'd then have to remove.
+  - **Disable zsh transient until upstream lands.** The current state.
+    Zsh users see the same scrollback density they had before this PR;
+    the visible improvement is fish-only. Honest trade-off.
+
+- **Transient prompt content**: `❯` plus optional exit-code dot
+  (red dot if `$status != 0`). Keep it 1–3 characters so scrollback
+  density actually improves.
+
+The toggle is exposed in `.chezmoidata.toml` as
+`features.starship_transient = true`. Users on bandwidth-constrained
+terminals (slow SSH, serial console) can flip it off without editing
+the canonical config.
+
+## Consequences
+
+### Positive (fish only, until upstream lands zsh support)
+
+- Scrollback is 4–5× denser **in fish**. A 100-command session that previously
+  filled the screen 20× over now fills it ~4×.
+- Asciinema recordings (relevant for the showcase commits in #874)
+  read much more naturally — fewer screens of historical prompts
+  between actions.
+- The live prompt still surfaces all the rich context Starship was
+  configured for; only history is compacted.
+
+### Negative
+
+- Slightly more complex Starship config; the maintainer must remember
+  that `[character]` and `[transient_*]` are distinct modules.
+- Users who rely on visual scanning of historical prompts (e.g., "what
+  branch was I on when I ran that?") lose that signal. Mitigation: the
+  feature flag.
+
+### Risks
+
+- Starship's transient API is stable since 1.16 (2023) but the exact
+  config surface evolves. If Starship breaks the schema in a future
+  major, the pinned version in `mise.toml` insulates us; we vet new
+  releases through `dot upgrade --dry-run` before bumping.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| Single-line Starship prompt | Sacrifices live-prompt richness for the same scrollback-density goal. The transient feature gives both. |
+| Custom zsh `precmd` rewriter | Would have to be reimplemented in fish. Starship already solved it. |
+| Disable Starship entirely on history | Loses the whole reason we use Starship. |
+
+## References
+
+- Starship transient prompt docs:
+  <https://starship.rs/advanced-config/#transientprompt-and-transientrightprompt-in-zsh>
+- ADR-002 (Shell Performance Optimization) — establishes the
+  `_cached_eval` constraint this ADR respects.
+- ADR-007 (Multi-Shell Parity) — establishes zsh + fish as Tier-1.
+- Issue #873 — captures this ADR alongside `llms.txt`.

package/docs/adr/ADR-011-nushell-tier3-keep.md

@@ -0,0 +1,144 @@
+---
+render_with_liquid: false
+---
+
+# ADR-011: Keep Nushell as Tier-3 Reference with Minimum-Viable Caching
+
+## Status
+
+Accepted
+
+## Date
+
+2026-05-13
+
+## Context
+
+ADR-007 (Multi-Shell Parity Strategy) classified the three supported
+shells:
+
+| Tier | Shells | Definition |
+|---|---|---|
+| Tier 1 (Full) | zsh, bash | Native aliases, functions, lazy loading, `_cached_eval` |
+| Tier 2 (Bridged) | fish | Aliases + functions via bridge, `_cached_eval` |
+| Tier 3 (Compatible) | nushell | Simple aliases only, functions via bash delegation |
+
+The 2026 audit (slice 3 of #880's deep-dive) flagged Nushell as a
+maintenance candidate:
+
+- < 5% feature parity with zsh.
+- No async / deferred-load support.
+- No equivalent of `_cached_eval` — meaning every Nushell start spawns
+  `starship init nu`, `mise activate nu`, `zoxide init nushell`,
+  `atuin init nu` as fresh subprocesses, costing 100–200 ms aggregated.
+- 5 config files (`config.nu.tmpl`, `env.nu.tmpl`, `aliases.nu`,
+  `completions.nu.tmpl`, `functions.nu.tmpl`) totalling ~270 lines —
+  enough to be meaningful, not enough to be self-sustaining.
+
+Three paths were proposed:
+
+1. **Keep as-is** — accept the gap, defer maintenance.
+2. **Reduce to a stub** — leave the config but stop investing.
+3. **Remove entirely** — delete all references.
+
+## Decision
+
+**Keep Nushell as Tier-3 with explicit limitations + a minimum-viable
+`_cached_eval` equivalent.**
+
+Specifically:
+
+- Ship `dot_config/nushell/cached_eval.nu` — a Nushell module that
+  ports the binary-mtime-based init caching pattern from zsh/fish.
+  It handles the four tools that matter most for shell start:
+  starship, mise, zoxide, atuin. See the Nushell-specific tradeoffs
+  in the "Consequences" section below.
+- Wire `env.nu.tmpl` to use the new module so subsequent shells skip
+  the subprocess spawns when binaries haven't moved.
+- Continue maintaining the existing `aliases.nu` (hand-curated simple
+  aliases — `l`, `ll`, `la`, etc.) but accept that the bash-bridge
+  approach for full alias parity isn't worth the complexity.
+- Update `README.md`'s shell list to call Nushell out as "best-effort
+  / Tier-3" so users have correct expectations.
+- Reject the "remove entirely" option for now (see Rationale below).
+
+## Rationale
+
+**Why not remove**: Nushell is shipped with the canonical `mise`
+toolchain in this repo (it's installable via `mise install nushell`)
+and is gaining adoption in the Rust + data-engineering communities
+that overlap with this distribution's audience. Removing it would
+break promises to a small-but-vocal segment of users. The maintenance
+cost of the current 270-line surface is low.
+
+**Why not reduce to a stub**: A stub config is worse than the current
+moderate config — users who type `nu` and get a featureless shell
+without any of the integrations the README promised would feel
+betrayed. Either we keep the shell working well enough to use, or we
+delete it.
+
+**Why the minimum-viable cache layer**: The biggest waste on every
+Nushell start was the four uncached subprocess spawns
+(`starship init nu` etc.). Adding mtime-based caching for those costs
+~50 lines of Nushell code and saves 100–200 ms per shell. That's the
+cheapest meaningful improvement; deeper investments (async hydration,
+plugin system, bash bridge for aliases) await an actual user request.
+
+## Consequences
+
+### Positive
+
+- Nushell starts substantially faster than before (TBD — needs
+  measurement on a host with all four tools installed). The
+  subprocess elimination saves ~50–80 ms per cached tool, per cold
+  shell after the cache is populated.
+- The mtime-invalidation pattern matches what zsh / fish do, so a
+  contributor familiar with one of the other shells can read the
+  Nushell code without learning a new mental model.
+- Explicit Tier-3 documentation avoids the "wait, this is supposed to
+  be at parity" surprise.
+
+### Negative
+
+- Nushell's parse-time evaluator means we can't wrap source calls in
+  the cache function — the caller has to `source <path>` directly.
+  Slightly more boilerplate than the zsh/fish APIs.
+- No malware-pattern screening in the cached output. The zsh / fish
+  implementations grep for `curl ... | sh`, `nc -e`, etc. before
+  sourcing; the Nushell version trusts its inputs. For the four tools
+  we ship (`starship`, `mise`, `zoxide`, `atuin`) this is acceptable
+  — they're official binaries pinned via `mise.toml`. Future tools
+  added to the cache must be similarly trusted.
+- No per-tool timing telemetry. The `EVALCACHE_TIMING` infrastructure
+  zsh has (#863) isn't ported. If Nushell perf becomes a sustained
+  user concern, this is the next layer to add.
+
+### Risks
+
+- Nushell's syntax evolves quickly between 0.x releases. The
+  `cached_eval.nu` module uses `path exists`, `ls | get -i modified`,
+  and `run-external` which have been stable since 0.86 (Q3 2024).
+  If a future Nushell release breaks the API, the module fails fast
+  (saving an empty cache file) rather than corrupting state.
+- Cache invalidation by mtime is fragile when the user installs a
+  tool via a non-mtime-respecting method (e.g. unpacking a tarball
+  with `--no-touch-mtimes`). The fallback is the user running
+  `dot prewarm` or deleting `~/.cache/nushell/*.nu`. Documented in
+  `docs/operations/PERFORMANCE.md`.
+
+## Alternatives Considered
+
+| Alternative | Why rejected |
+|---|---|
+| **Bash bridge for full alias parity** | Adds a `bash --norc --noprofile -c '...'` subprocess on every Nushell start (~30 ms). Defeats the perf gain from the cache layer. |
+| **Port `_cached_eval` 1:1 (malware screen + JSONL telemetry)** | The full zsh implementation is 100+ lines. The Nushell version covers the 80% case at 50 lines; the remaining 20% (advanced features) aren't load-bearing for Tier-3 status. |
+| **Delete Nushell entirely** | See "Why not remove" above. |
+| **Reduce to a stub** | See "Why not reduce to a stub" above. |
+
+## References
+
+- [`dot_config/nushell/cached_eval.nu`](../../dot_config/nushell/cached_eval.nu) — the new module.
+- [`dot_config/nushell/env.nu.tmpl`](../../dot_config/nushell/env.nu.tmpl) — adopter.
+- ADR-007 (Multi-Shell Parity Strategy) — establishes the tier definitions.
+- ADR-002 (Shell Performance Optimization Strategy) — establishes `_cached_eval` semantics this module ports.
+- Issue [#880](https://github.com/sebastienrousseau/dotfiles/issues/880).

package/docs/adr/README.md

@@ -0,0 +1,39 @@
+---
+render_with_liquid: false
+---
+
+# 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-009](ADR-009-wallpaper-driven-theming.md) | Wallpaper-Driven Theming Engine | Accepted |
+| [ADR-010](ADR-010-starship-transient-prompt.md) | Enable Starship Transient Prompt in Zsh and Fish | Accepted |
+| [ADR-011](ADR-011-nushell-tier3-keep.md) | Keep Nushell as Tier-3 Reference with Minimum-Viable Caching | 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,117 @@
+---
+render_with_liquid: false
+---
+
+# 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,44 @@
+---
+render_with_liquid: false
+---
+
+# 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.