@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/scripts/diagnostics/workstation-attestation.sh

@@ -9,6 +9,9 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="${REPO_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+# Export so child processes (the mcp-doctor subprocess below) inherit it
+# without the env-prefix dance that confuses shellcheck (SC2097/SC2098).
+export REPO_ROOT
 
 # shellcheck source=../dot/lib/ui.sh
 source "$SCRIPT_DIR/../dot/lib/ui.sh"
@@ -91,7 +94,9 @@ if [[ -z "$current_profile" ]] && [[ -f "$agent_profile_file" ]]; then
   current_profile="$(jq -r '.defaultProfile // "ask"' "$agent_profile_file")"
 fi
 
-mcp_summary="$(REPO_ROOT="$REPO_ROOT" MCP_CONFIG="$REPO_ROOT/dot_config/claude/mcp_servers.json" bash "$REPO_ROOT/scripts/diagnostics/mcp-doctor.sh" --strict --json)"
+MCP_CONFIG="$REPO_ROOT/dot_config/claude/mcp_servers.json"
+export MCP_CONFIG
+mcp_summary="$(bash "$REPO_ROOT/scripts/diagnostics/mcp-doctor.sh" --strict --json)"
 
 attestation_json="$(
   jq -n \

package/scripts/dot/commands/agent.sh

@@ -76,11 +76,20 @@ _agent_checkpoint_file() {
 _agent_apply_profile_env() {
   local name="$1"
   export DOT_AGENT_PROFILE="$name"
-  export DOT_AGENT_APPROVAL="$(_agent_profile_field "$name" "approval")"
-  export DOT_AGENT_FILESYSTEM="$(_agent_profile_field "$name" "filesystem")"
-  export DOT_AGENT_NETWORK="$(_agent_profile_field "$name" "network")"
-  export DOT_AGENT_MCP_PROFILE="$(_agent_profile_field "$name" "mcpProfile")"
-  export DOT_AGENT_MAX_STEPS="$(_agent_profile_field "$name" "maxSteps")"
+  # Split declare-and-assign to avoid masking the field-getter's exit
+  # code (SC2155). If the profile JSON is malformed, the assignment
+  # now fails the function instead of silently exporting an empty value.
+  local approval filesystem network mcp_profile max_steps
+  approval="$(_agent_profile_field "$name" "approval")"
+  filesystem="$(_agent_profile_field "$name" "filesystem")"
+  network="$(_agent_profile_field "$name" "network")"
+  mcp_profile="$(_agent_profile_field "$name" "mcpProfile")"
+  max_steps="$(_agent_profile_field "$name" "maxSteps")"
+  export DOT_AGENT_APPROVAL="$approval"
+  export DOT_AGENT_FILESYSTEM="$filesystem"
+  export DOT_AGENT_NETWORK="$network"
+  export DOT_AGENT_MCP_PROFILE="$mcp_profile"
+  export DOT_AGENT_MAX_STEPS="$max_steps"
 }
 
 _agent_rbac_enforcement() {

package/scripts/dot/commands/ai.sh

@@ -28,9 +28,10 @@ if [[ ! -d "$PATTERN_DIR" ]]; then
 fi
 
 _show_ai_bridge_usage() {
-  echo "Usage: dot cl|copilot|gemini|kiro|autohand|vibe|qwen|zai --pattern [name] \"prompt\""
+  echo "Usage: dot cl|codex|copilot|gemini|goose|kiro|autohand|vibe|qwen|zai --pattern [name] \"prompt\""
   echo ""
   echo "Available Patterns:"
+  # shellcheck disable=SC2012
   ls -1 "$PATTERN_DIR" 2>/dev/null | sed 's/\.md$//' | sed 's/^/  - /' || echo "  (none)"
 }
 
@@ -57,18 +58,72 @@ _ai_refresh_status_cache() {
   tmp_file="$(mktemp)"
   mkdir -p "$AI_CACHE_DIR"
 
-  local entry category role name bin desc present version
+  local total=${#ai_entries[@]}
+
+  # Cold-cache refresh runs `$bin --version` for every tool — node-
+  # based ones are slow to start, so the total can hit 15-30s. Show a
+  # spinner so the user has feedback.
+  ui_spinner_start "Probing $total AI tools (cached for ${AI_STATUS_TTL}s)"
+
+  local jobs="${DOTFILES_AI_PROBE_JOBS:-$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 4)}"
+  local probe_dir
+  probe_dir="$(mktemp -d)"
+
+  # Probe via xargs -P. The probe logic lives INLINE in the bash -c
+  # string rather than as an exported function, because `export -f`
+  # doesn't always survive across bash invocations on every platform
+  # (notably macOS bash 3.2 needs the BASH_FUNC_*() env-var format,
+  # which subtly breaks for some shells in PATH). Inlining sidesteps
+  # the inheritance question entirely.
+  local i=0
+  local entry
+  local indexed=()
   for entry in "${ai_entries[@]}"; do
-    IFS='|' read -r category role name bin desc <<<"$entry"
-    if has_command "$bin"; then
-      present=1
-      version=$(_ai_extract_version "$bin")
+    indexed+=("$i|$entry")
+    i=$((i + 1))
+  done
+  # shellcheck disable=SC2016
+  local probe_script='
+    payload="$1"
+    out_dir="$2"
+    i="${payload%%|*}"
+    entry="${payload#*|}"
+    IFS="|" read -r category role name bin desc <<<"$entry"
+    if command -v "$bin" >/dev/null 2>&1; then
+      output=$("$bin" --version 2>/dev/null | head -1) || true
+      version=$(printf "%s" "$output" | sed "s/^[^0-9]*//" | sed "s/[[:space:]]*$//" | sed "s/\.$//")
+      printf "%s\t1\t%s\n" "$bin" "$version" >"$out_dir/$i"
     else
-      present=0
-      version=""
+      printf "%s\t0\t\n" "$bin" >"$out_dir/$i"
     fi
-    printf '%s\t%s\t%s\n' "$bin" "$present" "$version" >>"$tmp_file"
+  '
+  # NOTE: `-I{}` already implies one input line per invocation. Adding
+  # `-n1` on top triggers a BSD-xargs quirk where the input line is
+  # word-split on whitespace ("0|Agents (autonomous)|..." → multiple
+  # entries). Use only `-I{}`.
+  #
+  # ALSO: feed null-delimited records (`-0`) so apostrophes and
+  # other quote-like characters in the descriptions ("Block's coding
+  # agent") don't trigger xargs's "unterminated quote" parser.
+  printf '%s\0' "${indexed[@]}" |
+    xargs -0 -I{} -P"$jobs" \
+      bash -c "$probe_script" _ {} "$probe_dir" \
+      2>/dev/null || true
+
+  # Re-assemble in original entry order.
+  local n
+  for ((n = 0; n < i; n++)); do
+    [[ -f "$probe_dir/$n" ]] && cat "$probe_dir/$n" >>"$tmp_file"
   done
+  rm -rf "$probe_dir"
+
+  # Guard with `|| true` because ui_spinner_stop's last line evaluates
+  # to rc=1 when stdout is a TTY (the `[[ ! -t 1 ]] && printf` short-
+  # circuit). Under `set -euo pipefail` that rc would kill the script
+  # right before we get to write the cache, leaving the user with a
+  # silent broken cold-cache run. Defence in depth — the function
+  # now also has an explicit `return 0` upstream.
+  ui_spinner_stop || true
 
   mv "$tmp_file" "$AI_STATUS_CACHE_FILE"
 }
@@ -81,7 +136,9 @@ _ai_get_cached_status() {
 _ai_mise_pkg() {
   case "$1" in
     claude) echo "npm:@anthropic-ai/claude-code" ;;
+    codex) echo "npm:@openai/codex" ;;
     copilot) echo "npm:@github/copilot" ;;
+    goose) echo "pipx:goose-ai" ;;
     aider) echo "pipx:aider-chat" ;;
     opencode) echo "npm:opencode-ai" ;;
     sgpt) echo "pipx:shell-gpt" ;;
@@ -102,7 +159,9 @@ cmd_ai_status() {
   # category|role|name|binary|description
   local -a ai_clis=(
     "Agents (autonomous)|agent|Claude Code|claude|Anthropic CLI agent"
+    "Agents (autonomous)|agent|Codex CLI|codex|OpenAI Codex agent"
     "Agents (autonomous)|agent|Copilot CLI|copilot|GitHub Copilot CLI"
+    "Agents (autonomous)|agent|Goose|goose|Block's coding agent"
     "Coding (interactive)|coding|Aider|aider|AI pair programmer"
     "Coding (interactive)|coding|OpenCode|opencode|Terminal coding assistant"
     "Coding (interactive)|coding|Autohand Code|autohand|Autohand coding agent"
@@ -350,12 +409,18 @@ ${prompt}"
     cl | claude)
       printf "%s" "$full_prompt" | claude
       ;;
+    codex)
+      printf "%s" "$full_prompt" | codex
+      ;;
     copilot)
       copilot -sp "$full_prompt"
       ;;
     gemini)
       printf "%s" "$full_prompt" | gemini chat
       ;;
+    goose)
+      printf "%s" "$full_prompt" | goose session start
+      ;;
     kiro | kiro-cli)
       printf "%s" "$full_prompt" | kiro-cli chat
       ;;
@@ -404,7 +469,7 @@ case "${1:-}" in
     shift
     cmd_ai_query "$@"
     ;;
-  cl | claude | copilot | gemini | kiro | sgpt | ollama | opencode | aider | autohand | vibe | qwen | zai)
+  cl | claude | codex | copilot | gemini | goose | kiro | sgpt | ollama | opencode | aider | autohand | vibe | qwen | zai)
     tool="$1"
     shift
     run_ai_with_context "$tool" "$@"

package/scripts/dot/lib/bento.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Sourced by scripts/dot/commands/*.sh and dot_local/bin/executable_dot; inherits set -euo pipefail.
 # Dotfiles 2026: Atomic Intelligence Surface
 # High-fidelity, perfectly aligned, and professional.
 
@@ -30,7 +31,7 @@ _dotfiles_bento_render() {
 
   # Render a fixed-width card (42 cols) so output aligns in any terminal width
   printf "\n"
-  printf "  ${c_cyan}${c_bold}💎  D O T F I L E S${c_reset}  ${c_slate}[v0.2.500]${c_reset}\n"
+  printf "  ${c_cyan}${c_bold}💎  D O T F I L E S${c_reset}  ${c_slate}[v0.2.501]${c_reset}\n"
   printf "  ${c_slate}──────────────────────────────────────────${c_reset}\n"
 
   # Key system properties at a glance — answers "is my env healthy?" in 1 second

package/scripts/dot/lib/log.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Sourced by scripts/dot/commands/*.sh and scripts/diagnostics/*; inherits set -euo pipefail.
 # Structured JSON logging and metrics library.
 # Source this file to emit machine-readable logs and performance metrics.
 #
@@ -8,6 +9,11 @@
 #   dot_log info "apply_start" "source=chezmoi"
 #   dot_metric "shell_startup" 142 ms
 
+# Re-source guard: re-sourcing would mint a new DOT_TRACE_ID and break
+# correlation across modules that already captured the original.
+[[ "${_DOT_LIB_LOG_LOADED:-0}" == "1" ]] && return 0
+_DOT_LIB_LOG_LOADED=1
+
 # Correlation ID for tracing across commands in a single invocation
 DOT_TRACE_ID="${DOT_TRACE_ID:-$(date +%s%N 2>/dev/null | tail -c 12 || date +%s)}"
 export DOT_TRACE_ID

package/scripts/dot/lib/platform.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Sourced by scripts/dot/commands/*.sh; inherits set -euo pipefail.
 # Dotfiles CLI Platform Abstraction
 # Unified helpers for macOS, Linux, and WSL parity.
 

package/scripts/dot/lib/ui.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Sourced by scripts/dot/commands/*.sh, scripts/diagnostics/*, scripts/ops/*; inherits set -euo pipefail.
 ## Dotfiles CLI UI Component Library — Single Source of Truth.
 ##
 ## All CLI output MUST go through these primitives.  No raw printf with
@@ -30,6 +31,11 @@
 ##   ui_header "Section Title"
 ##   ui_ok "Operation succeeded"
 
+# Re-source guard: re-sourcing would zero out the BOLD/RED/etc colour
+# variables that ui_init() populated, breaking already-rendered output.
+[[ "${_DOT_LIB_UI_LOADED:-0}" == "1" ]] && return 0
+_DOT_LIB_UI_LOADED=1
+
 # ═══════════════════════════════════════════════════════════════════════
 # State — all zeroed before ui_init
 # ═══════════════════════════════════════════════════════════════════════
@@ -265,7 +271,12 @@ ui_spinner_stop() {
   fi
   ui_clear_line
   ui_show_cursor
+  # The newline is only needed when stdout is NOT a TTY. We must return
+  # 0 either way — without the explicit `return 0`, the function's exit
+  # status comes from the trailing `[[ ! -t 1 ]] && printf` chain, which
+  # is rc=1 on a TTY and breaks every caller running under `set -e`.
   [[ ! -t 1 ]] && printf "\n"
+  return 0
 }
 
 # ═══════════════════════════════════════════════════════════════════════

package/scripts/dot/lib/utils.sh

@@ -1,8 +1,13 @@
 #!/usr/bin/env bash
 # Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Sourced by scripts/dot/commands/*.sh and dot_local/bin/executable_dot; inherits set -euo pipefail.
 # Dotfiles CLI Utilities
 # Shared functions for dot command modules
 
+# Re-source guard: cheap short-circuit when sourced from multiple modules.
+[[ "${_DOT_LIB_UTILS_LOADED:-0}" == "1" ]] && return 0
+_DOT_LIB_UTILS_LOADED=1
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=ui.sh
 source "$SCRIPT_DIR/ui.sh"

package/scripts/git-hooks/pre-commit-audit.sh

@@ -140,6 +140,6 @@ if [[ $FAILED -eq 1 ]]; then
   printf '%b\\n' "   (Use --no-verify to bypass if absolutely necessary)"
   exit 1
 else
-  printf '%b\n' "${GREEN}${BOLD}✅ Audit passed.${NC} v0.2.500 standards maintained."
+  printf '%b\n' "${GREEN}${BOLD}✅ Audit passed.${NC} v0.2.501 standards maintained."
   exit 0
 fi

package/scripts/git-hooks/pre-push

@@ -1,8 +1,26 @@
 #!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# =============================================================================
+# pre-push hook
+#
+# 1. Refuses to push any commit that is not GPG/SSH-signed.
+# 2. Runs `scripts/qa/reliability-audit.sh --quick`. The audit is mandatory
+#    by default; explicit per-push bypass requires `DOTFILES_ALLOW_UNSKIPPED_PUSH=1`,
+#    and every bypass is logged to `~/.local/share/dotfiles/audit-bypass.log`.
+#
+# The legacy `DOTFILES_SKIP_PRE_PUSH_AUDIT=1` env var (opt-out) is rejected
+# with a migration message. The new variable is intentionally awkwardly
+# named so that setting it requires deliberate intent. See
+# `docs/security/AUDIT_BYPASS.md`.
+# =============================================================================
+
 set -euo pipefail
 
 repo_root="$(git rev-parse --show-toplevel)"
 
+# -----------------------------------------------------------------------------
+# Step 1 — signed-commit enforcement (unchanged)
+# -----------------------------------------------------------------------------
 while read -r local_ref local_sha remote_ref remote_sha; do
   [ "$local_sha" = "0000000000000000000000000000000000000000" ] && continue
 
@@ -18,12 +36,57 @@ while read -r local_ref local_sha remote_ref remote_sha; do
 
   for c in $(git rev-list "$range"); do
     if ! git verify-commit "$c" >/dev/null 2>&1; then
-      echo "Blocked: unsigned commit $c"
+      echo "Blocked: unsigned commit $c" >&2
       exit 1
     fi
   done
 done
 
-if [ "${DOTFILES_SKIP_PRE_PUSH_AUDIT:-0}" != "1" ]; then
-  bash "$repo_root/scripts/qa/reliability-audit.sh" --quick
+# -----------------------------------------------------------------------------
+# Step 2 — reject the legacy opt-out variable
+# -----------------------------------------------------------------------------
+if [ "${DOTFILES_SKIP_PRE_PUSH_AUDIT:-}" = "1" ]; then
+  cat >&2 <<'EOF'
+ERROR: DOTFILES_SKIP_PRE_PUSH_AUDIT is no longer honored.
+
+The pre-push audit was previously opt-out — setting one env var was enough
+to skip it. That made bypass invisible and routine. Effective with #871,
+the policy is fail-closed: the audit always runs unless you explicitly
+authorize a bypass for this single push.
+
+To bypass for one push:
+  DOTFILES_ALLOW_UNSKIPPED_PUSH=1 git push
+
+Every bypass is recorded to ~/.local/share/dotfiles/audit-bypass.log
+and surfaced by `dot doctor` if any are recent.
+
+See: docs/security/AUDIT_BYPASS.md
+EOF
+  exit 1
 fi
+
+# -----------------------------------------------------------------------------
+# Step 3 — run the audit (or log + skip if explicitly bypassed)
+# -----------------------------------------------------------------------------
+if [ "${DOTFILES_ALLOW_UNSKIPPED_PUSH:-}" = "1" ]; then
+  bypass_log_dir="${XDG_STATE_HOME:-$HOME/.local/state}/dotfiles"
+  # The audit-bypass log lives under XDG_STATE_HOME (user state — never
+  # checked in, never deployed by chezmoi to other locations).
+  mkdir -p "$bypass_log_dir"
+  bypass_log="$bypass_log_dir/audit-bypass.log"
+
+  ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+  remote="$(git remote get-url --push @{upstream} 2>/dev/null ||
+    git config --get remote.origin.url 2>/dev/null ||
+    echo unknown)"
+  reason="${DOTFILES_BYPASS_REASON:-no reason given}"
+
+  printf '%s\tbranch=%s\tremote=%s\treason=%s\n' \
+    "$ts" "$branch" "$remote" "$reason" >>"$bypass_log"
+
+  echo "WARN: pre-push audit bypassed (logged to $bypass_log)" >&2
+  exit 0
+fi
+
+bash "$repo_root/scripts/qa/reliability-audit.sh" --quick

package/scripts/ops/heal-chezmoi.sh

@@ -37,15 +37,50 @@ heal_chezmoi_drift() {
     return 0
   fi
 
+  # Partition the drift: column 2 is what `chezmoi apply` would fix
+  # (destination differs from source). Column 1 is source-only drift
+  # (unstaged edits in the chezmoi source tree). Apply can't help with
+  # the second case — that needs `git commit` in the source repo.
+  local applicable
+  local source_only
+  applicable=$(printf '%s\n' "$status_output" | awk 'substr($0,2,1)!=" "' | wc -l | tr -d ' ')
+  source_only=$(printf '%s\n' "$status_output" | awk 'substr($0,1,1)!=" " && substr($0,2,1)==" "' | wc -l | tr -d ' ')
+
   ISSUES_FOUND=$((ISSUES_FOUND + 1))
 
   if [[ "$DRY_RUN" == "1" ]]; then
-    log_dry "run 'chezmoi apply --force' to re-sync"
-  else
-    if _pkg_install "chezmoi re-apply" 0 1 chezmoi apply --force; then
-      FIXES_APPLIED=$((FIXES_APPLIED + 1))
-      CHEZMOI_APPLIED=1
-      persist_log "HEAL: chezmoi apply --force"
+    log_dry "run 'chezmoi apply --force' to re-sync ($applicable file(s))"
+    return 0
+  fi
+
+  # Skip the apply if every file is source-only drift; nothing to fix.
+  if [[ "$applicable" -eq 0 ]]; then
+    printf '  \033[38;5;220m⚠\033[0m chezmoi state                       %s file(s) modified in source only — commit or revert in the source repo\n' "$source_only"
+    return 0
+  fi
+
+  # Capture apply output so we can surface failure reasons.
+  local apply_log
+  apply_log=$(mktemp)
+  if chezmoi apply --force >"$apply_log" 2>&1; then
+    FIXES_APPLIED=$((FIXES_APPLIED + 1))
+    CHEZMOI_APPLIED=1
+    persist_log "HEAL: chezmoi apply --force"
+
+    # Verify: did apply actually clean the drift?
+    local remaining
+    remaining=$(chezmoi status 2>/dev/null | awk 'substr($0,2,1)!=" "' | wc -l | tr -d ' ')
+    if [[ "$remaining" -eq 0 ]]; then
+      printf '  \033[38;5;42m✓\033[0m chezmoi re-apply                     %s file(s) synced\n' "$applicable"
+    else
+      # shellcheck disable=SC2016
+      printf '  \033[38;5;220m⚠\033[0m chezmoi re-apply                     %s applied, %s still drifted — run `chezmoi diff` to inspect\n' \
+        "$((applicable - remaining))" "$remaining"
     fi
+  else
+    printf '  \033[38;5;196m✗\033[0m chezmoi re-apply                     failed; see %s\n' "$apply_log"
+    tail -5 "$apply_log" | sed 's/^/      /'
+    return 1
   fi
+  rm -f "$apply_log"
 }

package/scripts/qa/powershell-contract.ps1

@@ -0,0 +1,95 @@
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+#
+# PowerShell parity contract — smoke test for the dotfiles PowerShell
+# profile. Run by the windows-latest CI job (#860). Asserts that:
+#
+#   1. The profile parses + loads without throwing.
+#   2. Core function shims (`dot`, `ll`, `la`, `cat`) are defined.
+#   3. PSScriptAnalyzer reports no errors against the profile (warnings
+#      surface but don't fail the gate; tighten later).
+#
+# Exit codes:
+#   0  contract intact.
+#   1  any check failed; details printed to host.
+
+$ErrorActionPreference = 'Stop'
+$Failures = New-Object System.Collections.Generic.List[string]
+
+$RepoRoot = if ($env:GITHUB_WORKSPACE) { $env:GITHUB_WORKSPACE } else { (Get-Location).Path }
+$ProfileSrc = Join-Path $RepoRoot 'dot_config/powershell/Microsoft.PowerShell_profile.ps1.tmpl'
+
+if (-not (Test-Path $ProfileSrc)) {
+    Write-Output "FAIL: profile source not found at $ProfileSrc"
+    exit 1
+}
+
+# Step 1 — chezmoi-render the template into a real .ps1 we can dot-source.
+# In CI, chezmoi is on PATH (installed by setup-chezmoi composite).
+$Rendered = Join-Path $env:TEMP 'Microsoft.PowerShell_profile.ps1'
+if (Get-Command chezmoi -ErrorAction SilentlyContinue) {
+    & chezmoi execute-template --init --promptString version=0.2.501 `
+        --in $ProfileSrc | Set-Content -Path $Rendered -NoNewline
+} else {
+    # Fallback: strip chezmoi template syntax with a simple regex so the
+    # contract still runs locally without chezmoi installed.
+    (Get-Content $ProfileSrc -Raw) -replace '\{\{[^}]+\}\}', '0.0.0-fallback' |
+        Set-Content -Path $Rendered -NoNewline
+}
+
+if (-not (Test-Path $Rendered)) {
+    $Failures.Add("profile template did not render to $Rendered")
+}
+
+# Step 2 — dot-source the rendered profile and verify it didn't throw.
+$loadOk = $false
+try {
+    . $Rendered
+    $loadOk = $true
+    Write-Output "OK: profile dot-sourced"
+} catch {
+    Write-Output "FAIL: profile threw during load: $_"
+    $Failures.Add("profile load: $_")
+}
+
+# Step 3 — verify required function shims are defined.
+$RequiredFunctions = @('dot', 'd', 'll', 'la', 'cat')
+foreach ($fn in $RequiredFunctions) {
+    if (Get-Command $fn -CommandType Function -ErrorAction SilentlyContinue) {
+        Write-Output "OK: function $fn defined"
+    } else {
+        Write-Output "FAIL: function $fn not defined"
+        $Failures.Add("missing function: $fn")
+    }
+}
+
+# Step 4 — PSScriptAnalyzer (static analysis). Pre-installed on the
+# windows-latest GitHub-hosted runner; install on demand if missing.
+if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
+    Write-Output "Installing PSScriptAnalyzer..."
+    Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser -ErrorAction SilentlyContinue | Out-Null
+}
+
+if (Get-Module -ListAvailable -Name PSScriptAnalyzer) {
+    Import-Module PSScriptAnalyzer -Force
+    $Findings = Invoke-ScriptAnalyzer -Path $Rendered -Severity 'Error' -ErrorAction SilentlyContinue
+    if ($Findings) {
+        foreach ($f in $Findings) {
+            Write-Output "FAIL: PSScriptAnalyzer error: $($f.RuleName) at line $($f.Line): $($f.Message)"
+            $Failures.Add("PSScriptAnalyzer error: $($f.RuleName)")
+        }
+    } else {
+        Write-Output "OK: PSScriptAnalyzer clean (Error severity)"
+    }
+} else {
+    Write-Output "WARN: PSScriptAnalyzer not available — static analysis skipped"
+}
+
+Write-Output ""
+if ($Failures.Count -eq 0) {
+    Write-Output "PowerShell contract: PASS"
+    exit 0
+} else {
+    Write-Output "PowerShell contract: FAIL ($($Failures.Count) issue(s))"
+    foreach ($f in $Failures) { Write-Output "  - $f" }
+    exit 1
+}

package/scripts/theme/merge-wallpaper.sh

@@ -81,6 +81,10 @@ merge_pair() {
 
   local tmpdir
   tmpdir="$(mktemp -d)"
+  # Single-quotes prevent the variable expanding at trap-definition time;
+  # `$tmpdir` resolves when the trap fires (still scoped to this function
+  # because RETURN is per-function).
+  # shellcheck disable=SC2064  # intentionally expand $tmpdir at trap time within this function scope
   trap "rm -rf '$tmpdir'" RETURN
 
   # Convert both to JPEG for heif-enc input (it handles JPEG best)

package/scripts/theme/switch.sh

@@ -184,7 +184,7 @@ pick_theme() {
   fi
 
   local current
-  local current="$(current_theme)"
+  current="$(current_theme)"
 
   if [[ ! -f "$THEMES_FILE" ]]; then
     ui_err "Missing" "$THEMES_FILE"
@@ -234,7 +234,8 @@ pick_theme() {
 }
 
 list_themes() {
-  local current="$(current_theme)"
+  local current
+  current="$(current_theme)"
   local current_family="${current%-dark}"
   [[ "$current_family" != "$current" ]] || current_family="${current%-light}"
 
@@ -260,7 +261,8 @@ list_themes() {
 
 # Toggle between light and dark within the same family, or switch families
 toggle_theme() {
-  local current="$(current_theme)"
+  local current
+  current="$(current_theme)"
 
   if is_dark_theme "$current"; then
     if [[ "$current" == *-dark ]]; then
@@ -279,8 +281,9 @@ toggle_theme() {
 
 # Switch to the next wallpaper family while preserving mode.
 switch_family() {
-  local current="$(current_theme)"
-  local family="$(get_theme_family "$current")"
+  local current family
+  current="$(current_theme)"
+  family="$(get_theme_family "$current")"
   local mode="dark"
   local families=()
   local idx=0
@@ -316,8 +319,9 @@ switch_family() {
 
 # Show current theme info
 show_current() {
-  local current="$(current_theme)"
-  local family="$(get_theme_family "$current")"
+  local current family
+  current="$(current_theme)"
+  family="$(get_theme_family "$current")"
   local mode="dark"
   if ! is_dark_theme "$current" 2>/dev/null; then
     mode="light"
@@ -338,8 +342,13 @@ sync_theme() {
       ;;
     Linux)
       if command -v gsettings >/dev/null 2>&1; then
-        # Check GNOME color scheme
-        local scheme=scheme=$(gsettings get org.gnome.desktop.interface color-scheme 2>/dev/null | tr -d "'")
+        # Check GNOME color scheme. Fixes a long-standing bug where the
+        # variable was declared as `local scheme=scheme=$(...)` — the
+        # extra `scheme=` prefix made the value always start with that
+        # literal, so the `prefer-light` test below could never match
+        # and the system always fell through to the dark branch.
+        local scheme
+        scheme=$(gsettings get org.gnome.desktop.interface color-scheme 2>/dev/null | tr -d "'")
         if [[ "$scheme" == "prefer-light" ]]; then
           os_mode="light"
         else
@@ -349,7 +358,8 @@ sync_theme() {
       ;;
   esac
 
-  local current="$(current_theme)"
+  local current
+  current="$(current_theme)"
   if is_dark_theme "$current" && [[ "$os_mode" == "light" ]]; then
     ui_info "Sync" "System is light, switching dotfiles to light..."
     toggle_theme

package/dot_config/atuin/config.toml

@@ -1,40 +0,0 @@
-# Atuin Configuration (~/.config/atuin/config.toml)
-# https://atuin.sh/docs/config
-
-# 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
-history_filter = [
-  "^export (SECRET|TOKEN|PASSWORD|API_KEY|AWS_)",
-  "^PASSWORD=",
-  "^ssh-keygen",
-  "^(aws|gcloud|az|kubectl).*(configure|auth|login|-k |--kubeconfig)",
-  "curl.*-H.*[Aa]uthorization",
-  "git clone.*https://.*:.*@",
-  "^vault ",
-  "^op (read|inject|run)",
-]
-
-# Skip ephemeral directories
-secrets_filter = true
-network_timeout = 30