@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/docs/security/SECRETS.md

@@ -1,3 +1,8 @@
+---
+render_with_liquid: false
+---
+{% raw %}
+
 # Secrets Management
 
 Provider-agnostic secrets via `dot secrets`. Supports macOS Keychain, `pass`, and age-encrypted local storage.
@@ -17,6 +22,7 @@ infra = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "GITHUB_TOKEN"]
 ```
 
 `auto` resolves in this order:
+
 1. `macos-keychain` on macOS
 2. `pass` when available
 3. `plain-enc` fallback (age-encrypted local store)
@@ -49,6 +55,7 @@ eval "$(dot env load ai)"
 When `auto_load = true`, shell startup can load configured buckets automatically via `dot env load <bucket>`.
 
 Environment toggles:
+
 - `DOTFILES_SECRETS_PROVIDER`
 - `DOTFILES_SECRETS_AUTO_LOAD`
 - `DOTFILES_SECRETS_BUCKET_NAMES`
@@ -89,6 +96,7 @@ secrets_backend = "1password"
 ```
 
 Use in templates:
+
 ```text
 {{ onepassword "my-secret" "vault-name" }}
 {{ onepasswordRead "op://vault/item/field" }}
@@ -104,6 +112,7 @@ secrets_backend = "bitwarden"
 ```
 
 Use in templates:
+
 ```text
 {{ bitwarden "item" "my-login" }}
 {{ bitwardenFields "item" "my-login" }}
@@ -119,6 +128,7 @@ secrets_backend = "vault"
 ```
 
 Use in templates:
+
 ```text
 {{ vault "secret/data/my-secret" }}
 ```
@@ -133,6 +143,7 @@ secrets_backend = "pass"
 ```
 
 Use in templates:
+
 ```text
 {{ pass "my-secret" }}
 ```
@@ -144,3 +155,4 @@ See the [chezmoi documentation](https://www.chezmoi.io/user-guide/password-manag
 - **Never commit** `~/.config/chezmoi/key.txt` to version control.
 - **Avoid shell history exposure** — use `dot secrets set` which prompts securely.
 - **Rotate credentials** on a regular schedule.
+{% endraw %}

package/docs/security/SECURITY.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Security
 
 How dotfiles handles security and system modifications.

package/docs/security/SECURITY_CHECKLIST.md

@@ -1,27 +1,36 @@
+---
+render_with_liquid: false
+---
+
 # Security Release Checklist
 
 Use this checklist before cutting any new release (e.g., `v0.x.x`) to ensure supply-chain integrity.
 
 ## 1. Supply Chain & Installer
+
 - [ ] **Pinned Version**: Update `install.sh` `VERSION` variable to match the release tag.
 - [ ] **Docs Sync**: Ensure `README.md` and `.github/PULL_REQUEST_TEMPLATE.md` installer URLs point to the new tag (not `main`).
 - [ ] **Clean Build**: Verify `install.sh` does not curl random scripts from third parties without pinning.
 - [ ] **SOUP Register**: Review [SOUP_REGISTER.md](/home/seb/.dotfiles/docs/security/SOUP_REGISTER.md) and confirm all active external components have an owner and validation path.
 
 ## 2. Secrets & Leak Prevention
+
 - [ ] **SSH Keys**: Scan `dot_ssh/` to ensure no private keys (`id_rsa`, `id_ed25519`) are committed.
 - [ ] **Env Vars**: Check for hardcoded API tokens in `dot_config/` (use `age` encryption or environment variables instead).
 - [ ] **Git History**: Run `git secrets` or similar to scan for accidental commits of credentials.
 
 ## 3. Platform Safety
+
 - [ ] **WSL Check**: Verify `install.sh` detects WSL and does not try to install systemd services or macOS defaults.
 - [ ] **Root usage**: Ensure no script requires `sudo` unnecessarily (Principle of Least Privilege).
 
 ## 4. Toolchain
+
 - [ ] **Binary Integrity**: Check that `dot_local/bin/` scripts are pure shell/executable and match expected checksums (no binary blobs).
 - [ ] **Dependency Scan**: Run `npm audit` / `cargo audit` if applicable (currently Node.js legacy is removed).
 
 ## 5. MCP (Model Context Protocol) Hardening
+
 - [ ] **Launcher Policy**: Verify `dot mcp` shows only allowlisted launchers (`npx`, `node`, `uvx`).
 - [ ] **Filesystem Scope**: Ensure no MCP server has broad access (`/`, `/home`, `/Users`).
 - [ ] **Default Profile**: Confirm only the `strict-local` server set is enabled by default.
@@ -32,6 +41,7 @@ Use this checklist before cutting any new release (e.g., `v0.x.x`) to ensure sup
 Run `dot mcp --strict --json` to validate all MCP server configurations and capture an audit artifact.
 
 ## 6. Release Attestation
+
 - [ ] **SBOM Generation**: Verify `dotfiles-sbom.spdx.json` is generated in release workflow.
 - [ ] **Attestation Signing**: Confirm `actions/attest-build-provenance` signs the release artifacts.
 - [ ] **Attestation Verification**: Verify with `gh attestation verify <artifact> --repo sebastienrousseau/dotfiles`.
@@ -39,6 +49,7 @@ Run `dot mcp --strict --json` to validate all MCP server configurations and capt
 - [ ] **Automation Keying**: Confirm `ACTIONS_BOT_SIGNING_KEY` exists and matches the signer in `dot_config/git/allowed_signers`.
 
 ## 7. Final Verification
+
 - [ ] **Docker Test**: Run `docker build -f Dockerfile.test .` to verify clean install.
 - [ ] **Doctor**: Run `dot doctor` locally.
 - [ ] **MCP Check**: Run `dot mcp` to verify MCP configuration.

package/docs/security/SHELL_EXEMPTIONS.md

@@ -0,0 +1,145 @@
+---
+render_with_liquid: false
+---
+
+# Shell Preamble Exemptions
+
+Every bash script in this repo must include `set -euo pipefail` (or
+`set -eu` for POSIX `sh`) within its first 50 lines. The rule is
+enforced by
+[`scripts/ci/check-shell-preamble.sh`](../../scripts/ci/check-shell-preamble.sh),
+wired into `pre-commit` and the `reusable-shell-lint.yml` CI job.
+Tests pin the contract under
+[`tests/unit/security/test_shell_preamble_lint.sh`](../../tests/unit/security/test_shell_preamble_lint.sh).
+
+## Why the preamble is mandatory
+
+`set -e` fails the script on the first error. `set -u` rejects
+reads of unset variables. `set -o pipefail` propagates the exit
+code of the last failing command in a pipeline rather than only the
+final command's. Together they convert silent failures into loud
+ones — which is the only way to catch them.
+
+Real example from this repo's history: `executable_dot-load-benchmark`
+shipped with only `set -e`. A failing pipeline (e.g. `cmd | grep`)
+where `grep` succeeded would still report success even when `cmd`
+crashed. The full triple catches this. The benchmark was upgraded
+in commit 970b631d under #854.
+
+## Exemption categories
+
+Two kinds of files legitimately can't enforce the preamble locally:
+
+### 1. Sourced libraries
+
+Files loaded via `source` / `.` into a caller's shell context. The
+caller already has `set -euo pipefail`; the library inherits it.
+Adding `set -e` locally would persist after the library returns and
+break the caller's own error-handling logic.
+
+These files must carry a comment header in their first 15 lines:
+
+```bash
+# Sourced by <parent>.sh; inherits set -euo pipefail.
+```
+
+The lint accepts files with this marker regardless of preamble
+state. Current adopters:
+
+| Path | Sourced by |
+|---|---|
+| `dot_config/shell/00-core-paths.sh.tmpl` | shell init (zsh/bash/fish) |
+| `dot_config/shell/05-core-safety.sh` | shell init |
+| `dot_config/shell/10-secrets.sh` | shell init |
+| `dot_config/shell/40-fzf-defaults.sh.tmpl` | shell init |
+| `dot_config/shell/40-ls-colors.sh` | shell init |
+| `dot_config/shell/50-logic-functions-core.sh.tmpl` | shell init + fish bridge |
+| `dot_config/shell/50-logic-functions.sh.tmpl` | shell init + fish bridge |
+| `dot_config/shell/51-logic-functions-extra.sh.tmpl` | shell init (lazy) |
+| `dot_config/shell/90-ux-aliases.sh.tmpl` | shell init + fish bridge |
+| `dot_config/shell/91-ux-aliases-lazy.sh.tmpl` | shell init (lazy) |
+| `scripts/dot/lib/bento.sh` | dot CLI commands |
+| `scripts/dot/lib/log.sh` | dot CLI + diagnostics |
+| `scripts/dot/lib/platform.sh` | dot CLI commands |
+| `scripts/dot/lib/ui.sh` | dot CLI + diagnostics + ops |
+| `scripts/dot/lib/utils.sh` | dot CLI |
+| `scripts/ops/heal-chezmoi.sh` | `scripts/ops/heal.sh` |
+| `scripts/ops/heal-system.sh` | `scripts/ops/heal.sh` |
+| `scripts/ops/heal-tools.sh` | `scripts/ops/heal.sh` |
+
+### 2. Bulk-sourced fragments (path-skipped)
+
+Three directories contain hundreds of alias / function / PATH
+snippets that are sourced into the shell. Annotating each one
+individually would be 300+ marker comments with no extra signal.
+The lint skips them by path:
+
+| Path | Contents |
+|---|---|
+| `.chezmoitemplates/aliases/**/*.aliases.sh` | alias definitions sourced into the user's shell. |
+| `.chezmoitemplates/functions/**` | shell-function definitions sourced into the user's shell. |
+| `.chezmoitemplates/paths/**` | `PATH=…:$PATH` snippets concatenated by the shell init. |
+
+### 3. Test scripts (path-skipped)
+
+`tests/**` — every file under the test tree is invoked through
+`tests/framework/test_runner.sh` which manages shell options for its
+children. The runner itself has the full preamble; children that
+source the framework inherit it.
+
+### 4. Explicit opt-outs
+
+Init fragments and completion scripts that must NOT carry their own
+preamble (e.g., `dot_local/bin/executable_dot_completion`, a zsh
+completion sourced into the interactive shell) can carry an
+explicit marker:
+
+```bash
+# preamble:skip — opt-out for completion / init fragments.
+```
+
+The lint accepts these. Use sparingly.
+
+## Adding a new exemption
+
+When you need to mark a new file:
+
+1. **Decide whether it's actually sourced or executed.** If a user
+   ever invokes it directly (chmod +x + `./file.sh`), add the
+   preamble. If it's only ever `source`d, mark it.
+
+2. **Pick the right marker.**
+   - Sourced library: `# Sourced by <caller>; inherits set -euo pipefail.`
+   - Completion / init fragment: `# preamble:skip — <why>.`
+
+3. **Run the checker:**
+
+   ```bash
+   ./scripts/ci/check-shell-preamble.sh path/to/file.sh
+   ```
+
+   Exit 0 = lint passes.
+
+4. **If you're adding a new entire directory of fragments**
+   (rare — alias buckets, plugin trees), edit the path-skip rule
+   in `scripts/ci/check-shell-preamble.sh` and document it in this
+   page's "Bulk-sourced fragments" table above.
+
+## CI integration
+
+- **Pre-commit hook** (`config/pre-commit-config.yaml` →
+  `shell-preamble-check`): blocks `git commit` if a staged shell
+  file fails the lint.
+- **CI** (`.github/workflows/reusable-shell-lint.yml`): runs the
+  full-repo scan on every PR.
+
+A change to either the checker or the marker convention must update
+this page in the same PR.
+
+## References
+
+- `scripts/ci/check-shell-preamble.sh` — the lint.
+- `tests/unit/security/test_shell_preamble_lint.sh` — contract test.
+- `config/pre-commit-config.yaml` (`shell-preamble-check` hook).
+- `.github/workflows/reusable-shell-lint.yml` — CI invocation.
+- Issue [#854](https://github.com/sebastienrousseau/dotfiles/issues/854).

package/docs/security/SOUP_REGISTER.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # SOUP Register
 
 ## Purpose

package/docs/security/THREAT_MODEL.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Threat Model
 
 Security analysis of the dotfiles distribution. Covers trust boundaries, threat actors, attack surfaces, and mitigations.
@@ -45,6 +49,7 @@ The primary trust boundary is the **local machine**. Dotfiles are deployed to an
 **Risk:** Malicious code in sourced files executes with user privileges on every shell start.
 
 **Mitigations:**
+
 - All shell scripts pass `shellcheck --severity=error`
 - `set -euo pipefail` enforced in all operational scripts
 - `eval` usage hardened with process substitution (`. /dev/stdin`)
@@ -56,6 +61,7 @@ The primary trust boundary is the **local machine**. Dotfiles are deployed to an
 **Risk:** API keys, tokens, and SSH keys leaked via git history, shell history, or environment.
 
 **Mitigations:**
+
 - [Gitleaks](https://github.com/gitleaks/gitleaks) pre-commit hook blocks secrets in commits
 - Atuin `history_filter` excludes sensitive patterns
 - Age encryption for local secret storage
@@ -67,6 +73,7 @@ The primary trust boundary is the **local machine**. Dotfiles are deployed to an
 **Risk:** Compromised upstream packages injected into the toolchain.
 
 **Mitigations:**
+
 - Nix Flakes provide reproducible, pinned dependencies
 - Zinit plugin versions pinned (`ver"0.8.0"`)
 - Neovim plugin versions locked via `lazy-lock.json`
@@ -78,6 +85,7 @@ The primary trust boundary is the **local machine**. Dotfiles are deployed to an
 **Risk:** Attacker places malicious binary in a PATH directory that shadows legitimate tools.
 
 **Mitigations:**
+
 - PATH construction is deterministic (template-generated)
 - `~/.local/bin` is user-controlled and checked for writability
 - No world-writable directories in PATH
@@ -88,6 +96,7 @@ The primary trust boundary is the **local machine**. Dotfiles are deployed to an
 **Risk:** Chezmoi template variables could inject shell code if not properly quoted.
 
 **Mitigations:**
+
 - Template variables come from `.chezmoidata.toml` (user-controlled)
 - No external/network data used in templates
 - Template validation via `chezmoi apply --dry-run` in CI
@@ -97,6 +106,7 @@ The primary trust boundary is the **local machine**. Dotfiles are deployed to an
 **Risk:** Stale or tampered cache files in `~/.cache/shell/` sourced at startup.
 
 **Mitigations:**
+
 - `_cached_eval` validates cache against binary mtime
 - Cache files are user-owned (0644)
 - Cache directory is under `$XDG_CACHE_HOME` (user-controlled)

package/docs/security/VERIFICATION_VALIDATION.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Verification and Validation Report
 
 ## Document Control
@@ -5,7 +9,7 @@
 | Field | Value |
 |-------|-------|
 | Document ID | VV-DOT-001 |
-| Version | 0.2.500 |
+| Version | 0.2.501 |
 | Date | 2026-03-20 |
 | Author | Repository Maintainer |
 | Status | Active |

package/docs/themes/README.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Theme Gallery
 
 Themes are auto-generated from your wallpapers — the available set depends on what's present on your system. Run `dot theme list` to see what's discovered.

package/docs/themes/VISUAL_INTEGRITY_REPORT.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Visual Integrity Report
 
 Generated: 2026-04-08

package/dot_config/ai/identity.md

@@ -1,11 +1,13 @@
 # AI Identity & Preferences
 
 ## Profile
+
 - **User**:
 - **Role**: Senior Software Engineer / Architect
 - **Expertise**: Rust, TypeScript, Go, DevOps (Nix, Kubernetes), Shell Scripting.
 
 ## Coding Style
+
 - **Principles**: Clean code, SOLID, DRY, KISS.
 - **Preferences**:
   - Prefer TypeScript over JavaScript.
@@ -15,6 +17,7 @@
 - **Documentation**: Use JSDoc/TSDoc for code and GitHub-flavored Markdown for docs.
 
 ## Workspace Context
+
 - **Environment**: Linux (CachyOS/Arch), macOS.
 - **Shells**: Zsh (primary), Fish, Nushell, Bash.
 - **Dotfiles**: Managed by Chezmoi, optimized for performance and security.

package/dot_config/ai/patterns/architect.md

@@ -3,12 +3,14 @@
 You are an expert Shell Infrastructure Architect specializing in the 2026 developer stack.
 
 ## Core Directives
+
 - **Subtlety**: Propose changes that integrate seamlessly without adding unnecessary complexity.
 - **Performance**: Prioritize shell startup speed and binary efficiency (e.g., _cached_eval).
 - **Architecture**: Adhere to the modular "rc.d" structure and XDG Base Directory standards.
 - **Tools**: Leverage Mise for runtimes, Nix for declarative environments, and Chezmoi for state management.
 
 ## Environment Context
+
 - OS: Arch/CachyOS (optimized for x86-64-v4) or macOS.
 - Shells: Zsh (primary), Fish, Nushell, Bash.
 - Security: Age/SOPS for secrets, GPG signing enforced.

package/dot_config/ai/patterns/hardener.md

@@ -3,11 +3,13 @@
 You are a security engineer specializing in high-compliance Fintech environments and Post-Quantum Cryptography (PQC).
 
 ## Core Directives
+
 - **Zero Trust**: Assume all external scripts are compromised until verified.
 - **Encryption**: Enforce Age/SOPS for all sensitive data.
 - **Compliance**: Adhere to 2026 security baselines (GPG signing, SSH certificate authorities).
 - **Privacy**: Disable all non-essential telemetry at the OS and application level.
 
 ## Verification Logic
+
 - Every proposal must include a "Verification" step (e.g., dot verify --security).
 - Prioritize hardware enclave (TPM/Secure Enclave) integrations.

package/dot_config/ai/patterns/refactor.md

@@ -3,11 +3,13 @@
 You are an expert in shell script optimization and POSIX compliance.
 
 ## Core Directives
+
 - **Portability**: Ensure scripts work across Zsh, Bash, and Dash unless specifically optimized for a feature shell (like Fish/Nushell).
 - **Indempotency**: Scripts must be safe to run multiple times without side effects.
 - **Linting**: Adhere to ShellCheck best practices and strict error handling (set -euo pipefail).
 - **Latency**: Minimize subshell calls and external binary forks.
 
 ## Optimization Strategy
+
 - Use built-in shell features over external commands where possible.
 - Implement caching mechanisms for heavy computations.

package/dot_config/alacritty/alacritty.toml.tmpl

@@ -1,9 +1,9 @@
 {{- $fontFamily := default "JetBrainsMono Nerd Font" .terminal_font_family -}}
 {{- $fontSize := default 12 .terminal_font_size -}}
-{{- $t := index .themes (default "macos-monterey-dark" .theme) -}}
-{{- if not $t -}}{{- $t = index .themes "macos-monterey-dark" -}}{{- end }}
+{{- $t := index .themes (default "big-sur-dark" .theme) -}}
+{{- if not $t -}}{{- $t = index .themes "big-sur-dark" -}}{{- end }}
 {{- $tt := $t -}}
-{{- $themeName := default "macos-monterey-dark" .theme -}}
+{{- $themeName := default "big-sur-dark" .theme -}}
 {{- if hasSuffix "-light" $themeName -}}
   {{- $darkTheme := index .themes (printf "%s-dark" (trimSuffix "-light" $themeName)) -}}
   {{- if $darkTheme -}}{{- $tt = $darkTheme -}}{{- end -}}

package/dot_config/atuin/config.toml.tmpl

@@ -0,0 +1,47 @@
+# Atuin Configuration (~/.config/atuin/config.toml)
+# https://atuin.sh/docs/config
+#
+# This file is templated by chezmoi. The `history_filter` block is sourced
+# from `.chezmoidata/secrets-patterns.toml` (see #872) so the same audited
+# defaults ship to every machine, with per-host extension via
+# `~/.config/chezmoi/chezmoi.toml` → `[data.atuin.history_filter] extra = [...]`.
+
+# Core
+update_check = false
+db_path = "~/.local/share/atuin/history.db"
+key_path = "~/.local/share/atuin/key"
+session_path = "~/.local/share/atuin/session"
+
+# Sync
+auto_sync = true
+sync_frequency = "10m"
+sync_address = "https://api.atuin.sh"
+
+# UI
+style = "compact"
+inline_height = 20
+show_preview = true
+enter_accept = true
+
+# Search
+search_mode = "fuzzy"
+filter_mode = "global"
+workspaces = true
+
+# Privacy: skip commands that may contain secrets.
+# Defaults come from .chezmoidata/secrets-patterns.toml; the `extra` slot
+# in chezmoi.toml allows per-host extension without editing this template.
+history_filter = [
+{{- range .atuin.history_filter.defaults }}
+  {{ . | quote }},
+{{- end }}
+{{- with .atuin.history_filter.extra }}
+{{- range . }}
+  {{ . | quote }},
+{{- end }}
+{{- end }}
+]
+
+# Skip ephemeral directories
+secrets_filter = true
+network_timeout = 30

package/dot_config/dotfiles/agent-card.json

@@ -1,7 +1,7 @@
 {
   "specVersion": "0.3",
   "name": "dotfiles-agent",
-  "version": "0.2.500",
+  "version": "0.2.501",
   "description": "Trusted workstation agent surface for local shell automation.",
   "defaultProfile": "ask",
   "protocols": ["mcp", "a2a"],

package/dot_config/dotfiles/boot/README.md

@@ -1,9 +1,11 @@
 Place your Linux boot logo image here.
 
 Default path used by the script:
+
 - ~/.config/dotfiles/boot/logo.png
 
 Run:
+
 - sudo ~/.dotfiles/scripts/theme/install-boot-logo.sh --apply
 
 ---

package/dot_config/dotfiles/grub/README.md

@@ -1,9 +1,11 @@
 Place your GRUB theme files here.
 
 Default path used by the script:
+
 - ~/.config/dotfiles/grub/theme
 
 Run:
+
 - sudo ~/.dotfiles/scripts/theme/install-grub-theme.sh --apply
 
 ---

package/dot_config/dotfiles/lock/README.md

@@ -1,9 +1,11 @@
 Place your lock screen icon here.
 
 Default path used by the script:
+
 - ~/.config/dotfiles/lock/icon.png
 
 Example:
+
 - swaylock --image ~/.config/dotfiles/lock/icon.png
 
 ---

package/dot_config/fish/conf.d/init.fish.tmpl

@@ -55,6 +55,11 @@ if test "$DOTFILES_ARTIFACT_MODE" = "0"; and command -v starship >/dev/null
     if not _dotfiles_source_cached_init starship starship-init.fish
         starship init fish | source
     end
+    # Transient Prompt: collapse past prompts to the [character] glyph
+    # after Enter, reducing scrollback noise.
+    if functions -q enable_transience
+        enable_transience
+    end
 end
 
 # ── Lazy Hydration (deferred to first prompt) ────────────────────
@@ -124,6 +129,7 @@ end
 
 function _dotfiles_trigger_hydration --on-event fish_prompt
     functions -e _dotfiles_trigger_hydration
+    functions -e _dotfiles_trigger_hydration_on_missing
     _dotfiles_async_init
     if test "$DOTFILES_ARTIFACT_MODE" = "1"
         begin
@@ -133,6 +139,21 @@ function _dotfiles_trigger_hydration --on-event fish_prompt
     end
 end
 
+# Belt-and-braces: if the user types an unknown command BEFORE the
+# first prompt fires (e.g. `fish -ic 'foo'` from a script that
+# doesn't render a prompt), trigger the same lazy-layer load via
+# fish_command_not_found. The hydration function may already have
+# fired and removed itself — guard against double-load. (Closes
+# AC#2 of #880; fish's analogue to zsh's function_not_found.)
+function _dotfiles_trigger_hydration_on_missing --on-event fish_command_not_found
+    functions -e _dotfiles_trigger_hydration_on_missing
+    functions -e _dotfiles_trigger_hydration
+    _dotfiles_async_init
+    # After hydration, the command may now resolve; let fish's default
+    # not-found handler print the standard message for whatever the
+    # user typed.
+end
+
 # ── Keybindings (Fish 4.x enhanced) ─────────────────────────────
 bind ctrl-backspace backward-kill-word
 bind alt-enter 'commandline -f accept-autosuggestion; commandline -f execute'