@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/scripts/ops/heal-tools.sh

@@ -0,0 +1,340 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# shellcheck disable=SC2034
+# =============================================================================
+# heal-tools.sh — Tool installation helpers for heal.sh
+# Sourced by heal.sh; inherits set -euo pipefail, ui.sh, and shared variables.
+# =============================================================================
+
+# Helper to check command (mise-aware, mirrors doctor.sh)
+check_cmd() {
+  local cmd="$1"
+  if command -v "$cmd" &>/dev/null; then
+    return 0
+  fi
+  # Fallback: check if installed via mise
+  if command -v mise &>/dev/null; then
+    if mise ls --installed 2>/dev/null | grep -qE "($cmd|aqua:.*$cmd)"; then
+      return 0
+    fi
+  fi
+  return 1
+}
+
+detect_pkg_manager() {
+  if command -v brew >/dev/null 2>&1; then
+    echo "brew"
+  elif command -v apt-get >/dev/null 2>&1; then
+    echo "apt"
+  elif command -v dnf >/dev/null 2>&1; then
+    echo "dnf"
+  elif command -v pacman >/dev/null 2>&1; then
+    echo "pacman"
+  elif command -v nix-env >/dev/null 2>&1; then
+    echo "nix"
+  else
+    echo ""
+  fi
+}
+
+install_package() {
+  local pkg="$1"
+  local pkg_mgr
+  pkg_mgr=$(detect_pkg_manager)
+
+  case "$pkg_mgr" in
+    brew) brew install --quiet "$pkg" >/dev/null 2>&1 ;;
+    apt)
+      if ! command -v sudo >/dev/null 2>&1; then
+        log_error "sudo not found — cannot install '$pkg' via apt"
+        return 1
+      fi
+      sudo apt-get install -y -qq "$pkg" >/dev/null 2>&1
+      ;;
+    dnf)
+      if ! command -v sudo >/dev/null 2>&1; then
+        log_error "sudo not found — cannot install '$pkg' via dnf"
+        return 1
+      fi
+      sudo dnf install -y -q "$pkg" >/dev/null 2>&1
+      ;;
+    pacman)
+      if ! command -v sudo >/dev/null 2>&1; then
+        log_error "sudo not found — cannot install '$pkg' via pacman"
+        return 1
+      fi
+      sudo pacman -S --noconfirm --quiet "$pkg" >/dev/null 2>&1
+      ;;
+    nix) nix-env -iA "nixpkgs.$pkg" >/dev/null 2>&1 ;;
+    *)
+      log_error "No supported package manager found. Install '$pkg' manually."
+      return 1
+      ;;
+  esac
+}
+
+# Map command names to package names per package manager
+get_package_name() {
+  local cmd="$1"
+
+  case "$cmd" in
+    rg) echo "ripgrep" ;;
+    bat) echo "bat" ;;
+    fzf) echo "fzf" ;;
+    zsh) echo "zsh" ;;
+    age) echo "age" ;;
+    *) echo "$cmd" ;;
+  esac
+}
+
+# =============================================================================
+# Animated Package Installer — delegates to ui.sh ui_run_cmd
+# =============================================================================
+
+# Usage: _pkg_install "label" completed total command [args...]
+_pkg_install() { ui_run_cmd "$@"; }
+
+# Resolve latest GitHub release tag for a repo
+_gh_latest_tag() {
+  curl -fsSLI -o /dev/null -w '%{url_effective}' "https://github.com/$1/releases/latest" | sed 's|.*/||'
+}
+
+# Install a single package (dispatcher for _pkg_install to call in subshell)
+_do_install() {
+  local cmd="$1"
+  local pkg_mgr="$2"
+  local bin_dir="$HOME/.local/bin"
+  mkdir -p "$bin_dir"
+
+  # Binary/curl installers for tools not in standard apt repos
+  case "$cmd" in
+    starship)
+      local installer
+      installer=$(umask 077 && mktemp)
+      if ! curl -fsSL -o "$installer" https://starship.rs/install.sh; then
+        rm -f "$installer"
+        log_error "Failed to download starship installer"
+        return 1
+      fi
+      if ! head -1 "$installer" | grep -q '^#!/'; then
+        rm -f "$installer"
+        log_error "starship installer does not look like a shell script"
+        return 1
+      fi
+      sh "$installer" --yes
+      local rc=$?
+      rm -f "$installer"
+      return $rc
+      ;;
+    atuin)
+      local installer
+      installer=$(umask 077 && mktemp)
+      if ! curl -fsSL -o "$installer" https://setup.atuin.sh; then
+        rm -f "$installer"
+        log_error "Failed to download atuin installer"
+        return 1
+      fi
+      if ! head -1 "$installer" | grep -q '^#!/'; then
+        rm -f "$installer"
+        log_error "atuin installer does not look like a shell script"
+        return 1
+      fi
+      bash "$installer" --yes
+      local rc=$?
+      rm -f "$installer"
+      return $rc
+      ;;
+    nushell)
+      local arch tag ver
+      arch=$(uname -m)
+      tag=$(_gh_latest_tag "nushell/nushell")
+      ver="${tag#v}"
+      local tmp
+      tmp=$(mktemp -d)
+      curl -fsSL -o "$tmp/nu.tar.gz" \
+        "https://github.com/nushell/nushell/releases/download/${tag}/nu-${ver}-${arch}-unknown-linux-musl.tar.gz" &&
+        tar xzf "$tmp/nu.tar.gz" -C "$tmp" --strip-components=1 &&
+        install -m 755 "$tmp/nu" "$bin_dir/nu"
+      local rc=$?
+      rm -rf "$tmp"
+      return $rc
+      ;;
+    pueue)
+      local arch
+      arch=$(uname -m)
+      curl -fsSL -o "$bin_dir/pueue" \
+        "https://github.com/Nukesor/pueue/releases/latest/download/pueue-${arch}-unknown-linux-musl" &&
+        chmod +x "$bin_dir/pueue"
+      curl -fsSL -o "$bin_dir/pueued" \
+        "https://github.com/Nukesor/pueue/releases/latest/download/pueued-${arch}-unknown-linux-musl" &&
+        chmod +x "$bin_dir/pueued"
+      return $?
+      ;;
+    wasmtime)
+      local arch tag
+      arch=$(uname -m)
+      tag=$(_gh_latest_tag "bytecodealliance/wasmtime")
+      local tmp
+      tmp=$(mktemp -d)
+      # xz-utils required for .tar.xz extraction
+      command -v xz >/dev/null 2>&1 || sudo apt-get install -y -qq xz-utils >/dev/null 2>&1 || true
+      curl -fsSL -o "$tmp/wasmtime.tar.xz" \
+        "https://github.com/bytecodealliance/wasmtime/releases/download/${tag}/wasmtime-${tag}-${arch}-linux.tar.xz" &&
+        tar xJf "$tmp/wasmtime.tar.xz" -C "$tmp" --strip-components=1 &&
+        install -m 755 "$tmp/wasmtime" "$bin_dir/wasmtime"
+      local rc=$?
+      rm -rf "$tmp"
+      return $rc
+      ;;
+    sops)
+      local arch tag
+      arch=$(uname -m)
+      [[ "$arch" == "x86_64" ]] && arch="amd64"
+      [[ "$arch" == "aarch64" ]] && arch="arm64"
+      tag=$(_gh_latest_tag "getsops/sops")
+      curl -fsSL -o "$bin_dir/sops" \
+        "https://github.com/getsops/sops/releases/download/${tag}/sops-${tag}.linux.${arch}" &&
+        chmod +x "$bin_dir/sops"
+      return $?
+      ;;
+    hyperfine)
+      local arch tag
+      arch=$(uname -m)
+      tag=$(_gh_latest_tag "sharkdp/hyperfine")
+      local tmp
+      tmp=$(mktemp -d)
+      curl -fsSL -o "$tmp/hyperfine.tar.gz" \
+        "https://github.com/sharkdp/hyperfine/releases/download/${tag}/hyperfine-${tag}-${arch}-unknown-linux-musl.tar.gz" &&
+        tar xzf "$tmp/hyperfine.tar.gz" -C "$tmp" --strip-components=1 &&
+        install -m 755 "$tmp/hyperfine" "$bin_dir/hyperfine"
+      local rc=$?
+      rm -rf "$tmp"
+      return $rc
+      ;;
+    yazi)
+      local arch
+      arch=$(uname -m)
+      local url="https://github.com/sxyazi/yazi/releases/latest/download/yazi-${arch}-unknown-linux-musl.zip"
+      local tmp
+      tmp=$(mktemp -d)
+      command -v unzip >/dev/null 2>&1 || sudo apt-get install -y -qq unzip
+      curl -fsSL -o "$tmp/yazi.zip" "$url" &&
+        (cd "$tmp" && unzip -oq yazi.zip) &&
+        install -m 755 "$tmp"/yazi-*/yazi "$bin_dir/yazi"
+      local rc=$?
+      rm -rf "$tmp"
+      return $rc
+      ;;
+    zellij)
+      local arch
+      arch=$(uname -m)
+      local url="https://github.com/zellij-org/zellij/releases/latest/download/zellij-${arch}-unknown-linux-musl.tar.gz"
+      local tmp
+      tmp=$(mktemp -d)
+      curl -fsSL -o "$tmp/zellij.tar.gz" "$url" &&
+        tar xzf "$tmp/zellij.tar.gz" -C "$tmp" &&
+        install -m 755 "$tmp/zellij" "$bin_dir/zellij"
+      local rc=$?
+      rm -rf "$tmp"
+      return $rc
+      ;;
+  esac
+
+  # System package manager
+  local pkg
+  pkg=$(get_package_name "$cmd")
+  install_package "$pkg"
+}
+
+heal_missing_dependencies() {
+  log_step "Checking dependencies"
+  # All tools that dot doctor checks — unified list
+  local deps=(
+    zsh chezmoi starship rg bat fzf zoxide atuin yazi zellij
+    nushell pueue wasmtime sops age hyperfine
+  )
+  local all_missing=()
+
+  for cmd in "${deps[@]}"; do
+    local check_name="$cmd"
+    [[ "$cmd" == "nushell" ]] && check_name="nu"
+    if check_cmd "$check_name"; then continue; fi
+    if [[ "$cmd" == "bat" ]] && check_cmd "batcat"; then continue; fi
+    all_missing+=("$cmd")
+    ISSUES_FOUND=$((ISSUES_FOUND + 1))
+  done
+
+  MISSING_DEPS_FOUND=${#all_missing[@]}
+
+  if [[ ${#all_missing[@]} -eq 0 ]]; then
+    log_success "All dependencies present"
+    return 0
+  fi
+
+  local total=${#all_missing[@]}
+  local completed=0
+  local installed=0
+  local pkg_mgr
+  pkg_mgr=$(detect_pkg_manager)
+
+  echo ""
+  for cmd in "${all_missing[@]}"; do
+    if [[ "$DRY_RUN" == "1" ]]; then
+      log_dry "install '$cmd'"
+      completed=$((completed + 1))
+      continue
+    fi
+
+    if [[ -z "$pkg_mgr" ]]; then
+      printf '  \033[38;5;196m✗\033[0m %s (no package manager)\n' "$cmd"
+      completed=$((completed + 1))
+      continue
+    fi
+
+    if _pkg_install "$cmd" "$completed" "$total" _do_install "$cmd" "$pkg_mgr"; then
+      FIXES_APPLIED=$((FIXES_APPLIED + 1))
+      installed=$((installed + 1))
+      persist_log "HEAL: installed $cmd"
+
+      # Post-install hooks (run in parent scope)
+      case "$cmd" in
+        bat)
+          if [[ "$pkg_mgr" == "apt" ]] && command -v batcat >/dev/null 2>&1 && ! command -v bat >/dev/null 2>&1; then
+            mkdir -p "$HOME/.local/bin"
+            ln -sf "$(command -v batcat)" "$HOME/.local/bin/bat"
+          fi
+          ;;
+        atuin) export PATH="$HOME/.atuin/bin:$PATH" ;;
+      esac
+    fi
+    completed=$((completed + 1))
+  done
+
+  if [[ "$DRY_RUN" != "1" ]]; then
+    echo ""
+    printf '  \033[1;38;5;42mDone!\033[0m Installed %d/%d packages.\n' "$installed" "$total"
+  fi
+}
+
+heal_mise_tools() {
+  if ! command -v mise >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Avoid blocking every heal run. Only ensure mise tools when deps are missing
+  # or when explicitly requested.
+  if [[ "${DOTFILES_HEAL_MISE_INSTALL:-0}" != "1" ]] && [[ "${MISSING_DEPS_FOUND:-0}" -eq 0 ]]; then
+    return 0
+  fi
+
+  if [[ "$DRY_RUN" == "1" ]]; then
+    log_dry "run 'mise install' to ensure all tools are present"
+  else
+    if _pkg_install "mise tools" 0 1 mise install; then
+      # Start pueue daemon if it was just installed but not running
+      if command -v pueued >/dev/null && ! pueue status >/dev/null 2>&1; then
+        pueued -d 2>/dev/null || true
+      fi
+    fi
+  fi
+}

package/scripts/ops/heal.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# shellcheck disable=SC2034
+# =============================================================================
+# Dotfiles Heal Script - Auto-repair common dotfiles issues
+# Runs diagnostics and attempts automatic fixes
+# Usage: ./scripts/ops/heal.sh [OPTIONS]
+# =============================================================================
+
+set -euo pipefail
+
+_cleanup_files=()
+LOCK_DIR=""
+cleanup() {
+  rm -f "${_cleanup_files[@]:-}"
+  if [[ -n "$LOCK_DIR" ]]; then
+    rmdir "$LOCK_DIR" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../dot/lib/ui.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/../dot/lib/ui.sh"
+# shellcheck source=../dot/lib/log.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/../dot/lib/log.sh"
+DOT_COMMAND="heal"
+REPO_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
+DOTFILES_SOURCE="$REPO_ROOT"
+BACKUP_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/dotfiles/backups"
+STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/dotfiles"
+HEAL_LOG="$STATE_DIR/heal.log"
+
+# Logging — delegates to shared ui.sh primitives
+ui_init
+log() { printf '%b\n' "$*"; }
+log_info() { ui_info "$@"; }
+log_success() { ui_ok "$@"; }
+log_warn() { ui_warn "$@"; }
+log_error() { ui_err "$@"; }
+log_step() {
+  echo ""
+  ui_section "$*"
+}
+log_dry() { ui_warn "DRY-RUN" "Would: $*"; }
+
+# Persistent logging
+persist_log() {
+  mkdir -p "$STATE_DIR"
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $*" >>"$HEAL_LOG"
+}
+
+# Options
+DRY_RUN=0
+FORCE=0
+FIXES_APPLIED=0
+ISSUES_FOUND=0
+CHEZMOI_APPLIED=0
+MISSING_DEPS_FOUND=0
+
+usage() {
+  cat <<EOF
+Dotfiles Heal - Auto-repair common issues
+
+Usage: $(basename "$0") [OPTIONS]
+
+Options:
+  -n, --dry-run   Preview what would be fixed without making changes
+  -f, --force     Skip confirmation prompts
+  -h, --help      Show this help message
+
+Environment:
+  DOTFILES_NONINTERACTIVE=1   Skip all interactive prompts (same as --force)
+
+Repairs:
+  - Missing tools (zsh, starship, rg, bat, fzf, zoxide, atuin, yazi, zellij,
+    nushell, pueue, wasmtime, sops, age, hyperfine)
+  - Broken symlinks in \$HOME (depth 3)
+  - Chezmoi drift (re-applies dotfiles)
+  - Missing critical files (.zshrc, .bashrc, .profile)
+  - Missing XDG config directories
+
+EOF
+}
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -n | --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    -f | --force)
+      FORCE=1
+      shift
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      log_error "Unknown option: $1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+# Prevent concurrent execution
+# Prefer XDG runtime dir when it exists and is writable; fallback to /tmp.
+LOCK_BASE="/tmp"
+if [[ -n "${XDG_RUNTIME_DIR:-}" ]] && [[ -d "${XDG_RUNTIME_DIR}" ]] && [[ -w "${XDG_RUNTIME_DIR}" ]]; then
+  LOCK_BASE="${XDG_RUNTIME_DIR}"
+fi
+LOCK_FILE="${LOCK_BASE}/dotfiles-heal.lock"
+LOCK_DIR="${LOCK_FILE}.d"
+if command -v flock >/dev/null 2>&1; then
+  exec 9>"$LOCK_FILE"
+  if ! flock -n 9; then
+    # Fallback path for systems where flock exists but cannot lock reliably.
+    if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+      ui_warn "Already running" "Another instance is active"
+      exit 0
+    fi
+  fi
+else
+  # Portable fallback when flock is unavailable (e.g. default macOS envs).
+  if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+    ui_warn "Already running" "Another instance is active"
+    exit 0
+  fi
+fi
+
+# =============================================================================
+# Load modules (inherit scope: set -euo pipefail, ui.sh, and all variables)
+# =============================================================================
+
+# shellcheck source=heal-tools.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/heal-tools.sh"
+
+# shellcheck source=heal-system.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/heal-system.sh"
+
+# shellcheck source=heal-chezmoi.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/heal-chezmoi.sh"
+
+# =============================================================================
+# Main
+# =============================================================================
+
+main() {
+  echo ""
+  printf '  \033[1mDotfiles Heal\033[0m\n'
+  echo ""
+
+  if [[ "$DRY_RUN" == "1" ]]; then
+    log_info "Dry-run mode (no changes will be made)"
+  fi
+
+  # Confirm before making changes (unless --force, --dry-run, or non-interactive)
+  if [[ "$DRY_RUN" != "1" ]] && [[ "$FORCE" != "1" ]] && [[ "${DOTFILES_NONINTERACTIVE:-0}" != "1" ]]; then
+    log_warn "This will auto-repair your dotfiles environment."
+    read -rp "  Continue? [y/N] " response
+    if [[ ! "$response" =~ ^[Yy]$ ]]; then
+      log_info "Aborted."
+      exit 0
+    fi
+    echo ""
+  fi
+
+  # Create backup before making changes
+  if [[ "$DRY_RUN" != "1" ]]; then
+    _pkg_install "backup" 0 1 create_pre_heal_backup 2>/dev/null || true
+  fi
+
+  # Run all repairs
+  heal_missing_dependencies || true
+  heal_mise_tools || true
+
+  # Quick checks (no animation needed)
+  heal_chezmoi_drift || true
+  heal_broken_symlinks || true
+  heal_missing_critical_files || true
+  heal_missing_xdg_dirs || true
+
+  # Pre-warm shell caches for fast startup (< 50ms target)
+  local prewarm_script="$SCRIPT_DIR/prewarm.sh"
+  if [[ -f "$prewarm_script" ]] && [[ "$DRY_RUN" != "1" ]]; then
+    log_step "Performance"
+    _pkg_install "shell cache pre-warm" 0 1 bash "$prewarm_script" || true
+  fi
+
+  # Summary
+  echo ""
+  if [[ "$DRY_RUN" == "1" ]]; then
+    if [[ $ISSUES_FOUND -eq 0 ]]; then
+      printf '  \033[1;38;5;42mHealthy.\033[0m No issues found.\n'
+    else
+      printf '  Found %d issue(s). Run without --dry-run to apply fixes.\n' "$ISSUES_FOUND"
+    fi
+  else
+    if [[ $ISSUES_FOUND -eq 0 ]]; then
+      printf '  \033[1;38;5;42mHealthy.\033[0m No issues found.\n'
+    elif [[ $FIXES_APPLIED -gt 0 ]]; then
+      printf '  \033[1;38;5;42mDone!\033[0m Applied %d fix(es) for %d issue(s).\n' "$FIXES_APPLIED" "$ISSUES_FOUND"
+      persist_log "HEAL_COMPLETE: $FIXES_APPLIED fixes applied"
+      dot_log info "heal_complete" "fixes=$FIXES_APPLIED" "issues=$ISSUES_FOUND"
+    else
+      printf '  Found %d issue(s) but no fixes could be applied.\n' "$ISSUES_FOUND"
+      printf '  Run \033[38;5;211mdot doctor\033[0m for diagnostics.\n'
+    fi
+  fi
+  echo ""
+}
+
+main

package/scripts/ops/post-apply-repair.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../dot/lib/ui.sh
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/../dot/lib/ui.sh"
+
+ZWC_CACHE_DIRS_DEFAULT=("$HOME/.config/shell" "$HOME/.config/zsh")
+
+repair_zwc_cache() {
+  local repaired=0
+  local failed=0
+  local file
+  local dirs=()
+  local raw_dirs="${DOTFILES_ZWC_CACHE_DIRS:-}"
+
+  if [[ -n "$raw_dirs" ]]; then
+    # shellcheck disable=SC2206
+    dirs=($raw_dirs)
+  else
+    dirs=("${ZWC_CACHE_DIRS_DEFAULT[@]}")
+  fi
+
+  while IFS= read -r -d '' file; do
+    if [[ ! -w "$file" ]]; then
+      if rm -f "$file" >/dev/null 2>&1; then
+        ((repaired++)) || true
+      else
+        ((failed++)) || true
+      fi
+    fi
+  done < <(find "${dirs[@]}" -type f -name '*.zwc' -print0 2>/dev/null || true)
+
+  if ((failed > 0)); then
+    ui_err "Zsh cache repair" "failed to remove ${failed} stale .zwc file(s)"
+    return
+  fi
+
+  if ((repaired > 0)); then
+    ui_warn "Zsh cache repair" "removed ${repaired} stale read-only .zwc file(s)"
+  else
+    ui_ok "Zsh cache repair" "no stale .zwc permissions detected"
+  fi
+}
+
+resolve_zsh_bin() {
+  if [[ -n "${DOTFILES_ZSH_BIN:-}" ]]; then
+    printf "%s\n" "${DOTFILES_ZSH_BIN}"
+    return
+  fi
+  if command -v zsh >/dev/null 2>&1; then
+    command -v zsh
+    return
+  fi
+  printf "%s\n" ""
+}
+
+validate_dot_cli() {
+  local dot_bin="${HOME}/.local/bin/dot"
+  local zsh_out dot_alias dot_path
+  local zsh_bin
+
+  if [[ ! -x "$dot_bin" ]]; then
+    ui_err "dot CLI binary" "missing executable at ${dot_bin}"
+    return
+  fi
+  ui_ok "dot CLI binary" "$dot_bin"
+
+  zsh_bin="$(resolve_zsh_bin)"
+  if [[ -z "$zsh_bin" || ! -x "$zsh_bin" ]]; then
+    ui_warn "dot CLI resolution" "zsh not available; skipping shell validation"
+    return
+  fi
+
+  zsh_out="$("$zsh_bin" -lic '
+    alias dot 2>/dev/null || true
+    whence -p dot 2>/dev/null || true
+  ' 2>/dev/null || true)"
+  dot_alias="$(printf "%s\n" "$zsh_out" | head -n 1)"
+  dot_path="$(printf "%s\n" "$zsh_out" | tail -n 1)"
+
+  if [[ "$dot_alias" == *"cd_with_history"* ]]; then
+    ui_warn "dot alias collision" "legacy sessions may still map dot to navigation; run: unalias dot && exec zsh"
+  fi
+
+  if [[ "$dot_path" == "$dot_bin" ]]; then
+    ui_ok "dot CLI resolution" "$dot_path"
+  elif [[ -n "$dot_path" ]]; then
+    ui_warn "dot CLI resolution" "resolved to ${dot_path} (expected ${dot_bin})"
+  else
+    ui_err "dot CLI resolution" "dot not found in a fresh zsh login shell"
+  fi
+}
+
+main() {
+  ui_init
+  ui_header "Post-apply checks"
+  repair_zwc_cache
+  validate_dot_cli
+}
+
+if [[ "${DOTFILES_POST_APPLY_TESTING:-0}" != "1" ]]; then
+  main
+fi