install.sh

#!/usr/bin/env bash
# shellcheck disable=SC2016

set -euo pipefail
IFS=$'\n\t'
FORCE_MODE=false
MINIMAL_MODE=false
DRY_RUN=false
COPY_MODE=false
CLEAN_BACKUPS=false
SHOW_HELP=false
INSTALL_ALL=false
SKIP_GIT_CONFIG=false
UNINSTALL_MODE=false
SKIP_TOOLS=false
BREW_UPGRADE=false
SYNC_MODE=false
TRUST_BREW_TAPS=false
OPTIONAL_INSTALL_APPROVED=false
TEST_FUNCTION="${DOTFILES_TEST_FUNCTION:-}"
for arg in "$@"; do
    case "$arg" in
        -dr | --dry-run)
            DRY_RUN=true
            echo "🧪 Running in dry-run mode. No files will be changed."
            ;;
        -c | --copy)
            COPY_MODE=true
            echo "📄 Running in copy mode with backup."
            ;;
        -cb | --clean-backups)
            CLEAN_BACKUPS=true
            ;;
        -f | --force)
            FORCE_MODE=true
            ;;
        -m | --minimal)
            MINIMAL_MODE=true
            ;;
        --skip-tools)
            SKIP_TOOLS=true
            ;;
        --brew-upgrade)
            BREW_UPGRADE=true
            ;;
        --sync)
            SYNC_MODE=true
            ;;
        --trust-brew-taps)
            TRUST_BREW_TAPS=true
            ;;
        -h | --help)
            SHOW_HELP=true
            ;;
        -a | --all)
            INSTALL_ALL=true
            ;;
        --uninstall)
            UNINSTALL_MODE=true
            ;;
        *)
            echo "❌ Unknown argument: $arg" >&2
            exit 2
            ;;
    esac
done

if $SHOW_HELP; then
    echo "Usage: ./install.sh [options]"
    echo ""
    echo "Options:"
    echo "  -dr, --dry-run         Run in dry mode (no files modified)"
    echo "  -c,  --copy            Copy files instead of symlinking"
    echo "  -f,  --force           Skip prompts and force optional installs (does not clean backups)"
    echo "  -m,  --minimal         Install only core dotfiles (no extras or tools)"
    echo "      --skip-tools        Skip optional package managers and tool installation"
    echo "      --brew-upgrade      Upgrade Brewfile dependencies during macOS installation"
    echo "      --sync              Reconcile dotfiles, shell setup, and Git defaults without tool installs or prompts"
    echo "      --trust-brew-taps   Explicitly trust every third-party tap declared in the Brewfile"
    echo "  -cb, --clean-backups   Offer to remove backups created by this installer"
    echo "  -a,  --all             Automatically install all optional tools"
    echo "      --uninstall        Remove links and revert shell rc additions"
    echo "  -h,  --help            Show this help message"
    exit 0
fi

if $SYNC_MODE && { $MINIMAL_MODE || $INSTALL_ALL || $FORCE_MODE || $BREW_UPGRADE || $CLEAN_BACKUPS || $TRUST_BREW_TAPS; }; then
    echo "❌ --sync cannot be combined with --minimal, --all, --force, --brew-upgrade, --clean-backups, or --trust-brew-taps." >&2
    exit 2
fi

if $UNINSTALL_MODE && { $COPY_MODE || $MINIMAL_MODE || $SKIP_TOOLS || $BREW_UPGRADE || $INSTALL_ALL || $SYNC_MODE || $TRUST_BREW_TAPS; }; then
    echo "❌ --uninstall cannot be combined with installation-only options." >&2
    exit 2
fi

if $FORCE_MODE; then
    INSTALL_ALL=true
fi

if $MINIMAL_MODE; then
    INSTALL_ALL=false
    SKIP_GIT_CONFIG=true
    SKIP_FETCH=true
    SKIP_TOOLS=true
fi

if $SYNC_MODE; then
    SKIP_TOOLS=true
    SKIP_FETCH=true
fi

### === Defaults & Constants ===
UV_PYTHON_VERSION='3.13'
NVM_VERSION="${DOTFILES_NVM_VERSION:-v0.40.4}"

if [[ ! "$NVM_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
    echo "❌ DOTFILES_NVM_VERSION must be a semantic version tag such as v0.40.4." >&2
    exit 2
fi

COMMON_RC_LINES=(
    "[[ -f ~/.shell_aliases ]] && source ~/.shell_aliases"
    "[[ -f ~/.shell_functions ]] && source ~/.shell_functions"
    "[[ -f ~/.git_aliases ]] && source ~/.git_aliases"
    "[[ -f ~/.git_functions ]] && source ~/.git_functions"
    "[[ -f ~/.history_settings ]] && source ~/.history_settings"
    "[[ -f ~/.omp_init ]] && source ~/.omp_init"
    '[[ -d "$HOME/.local/bin" ]] && export PATH="$HOME/.local/bin:$PATH"'
    '[[ -f "$HOME/.local/share/swiftly/env.sh" ]] && . "$HOME/.local/share/swiftly/env.sh"'
)

NVM_RC_LINES=(
    'export NVM_DIR="$HOME/.nvm"'
    '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"'
    '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"'
)

HOMEBREW_RC_LINES=(
    'eval "$(/opt/homebrew/bin/brew shellenv)"'
    'eval "$(/usr/local/bin/brew shellenv)"'
)

PATH_DEDUP_MARKER='# PATH de-dup (dotfiles installer)'
BASH_PATH_DEDUP_LINE='[ -x /usr/bin/awk ] && [ -x /usr/bin/paste ] && [ -x /usr/bin/tr ] && PATH="$([ -x /usr/bin/printf ] && /usr/bin/printf %s "$PATH" | /usr/bin/tr ":" "\n" | /usr/bin/awk '\''!seen[$0]++'\'' | /usr/bin/paste -sd:)" && export PATH'
LEGACY_PATH_DEDUP_MARKER='# Remove duplicates from PATH'
LEGACY_PATH_DEDUP_LINE='export PATH=$(echo "$PATH" | tr ":" "\n" | awk "!seen[\$0]++" | paste -sd:)'

DELTA_GIT_DEFAULTS=(
    "core.pager=delta"
    "interactive.diffFilter=delta --color-only"
    "delta.navigate=true"
    "delta.dark=true"
    "delta.side-by-side=true"
    "delta.line-numbers=true"
)

### === Define dotfiles ===
BASEDIR=$(cd "$(dirname "$0")" && pwd)
DOTFILES_HOME="$BASEDIR"
MACOS_BREWFILE="$DOTFILES_HOME/macos/Brewfile"
MACOS_DOCK_SCRIPT="$DOTFILES_HOME/macos/dock.sh"
MACOS_DEFAULTS_SCRIPT="$DOTFILES_HOME/macos/defaults.sh"
GIT_DEFAULTS_FILE="$DOTFILES_HOME/git/defaults.conf"
GIT_CONFIG_STATE_DIR="$HOME/.config/dotfiles/installer-state"
GIT_CONFIG_STATE_FILE="$GIT_CONFIG_STATE_DIR/git-config.before"
BACKUP_MANIFEST="$GIT_CONFIG_STATE_DIR/backups.list"

SYMLINK_KEYS=(
    "$HOME/.shell_aliases"
    "$HOME/.shell_functions"
    "$HOME/.history_settings"
    "$HOME/.omp_init"
    "$HOME/.nanorc"
    "$HOME/.git_aliases"
    "$HOME/.git_functions"
    "$HOME/.global.gitignore"
)
SYMLINK_VALUES=(
    "$DOTFILES_HOME/general/.aliases"
    "$DOTFILES_HOME/general/.functions"
    "$DOTFILES_HOME/general/.history_settings"
    "$DOTFILES_HOME/general/.omp_init"
    "$DOTFILES_HOME/nano/.nanorc"
    "$DOTFILES_HOME/git/.git_aliases"
    "$DOTFILES_HOME/git/.git_functions"
    "$DOTFILES_HOME/git/global.gitignore"
)

REQUIRED_TOOLS=(nano docker swift git)

### === Detect Environment ===
OS="$(uname -s)"
SHELL_NAME=$(basename "$SHELL")

if $TRUST_BREW_TAPS && [ "$OS" != "Darwin" ]; then
    echo "❌ --trust-brew-taps is only available on macOS." >&2
    exit 2
fi

printf "\n🔍 Detected OS: %s\n" "$OS"
printf "🔍 Detected Shell: %s\n" "$SHELL_NAME"

add_to_rc_if_not_present() {
    local rc_file="${1/#\~/$HOME}" # expand ~ to $HOME
    local line_to_add="$2"
    if [ -f "$rc_file" ] && grep -Fq "$line_to_add" "$rc_file"; then
        echo "📄 $line_to_add found in $rc_file, no need to add"
    else
        if $DRY_RUN; then
            echo "🧪 Would add to $rc_file: $line_to_add"
        else
            echo "📝 adding $line_to_add to $rc_file"
            echo "$line_to_add" >>"$rc_file"
        fi
    fi
}

record_backup() {
    local backup_path="$1"

    mkdir -p "$GIT_CONFIG_STATE_DIR"
    touch "$BACKUP_MANIFEST"
    if ! grep -Fqx -- "$backup_path" "$BACKUP_MANIFEST"; then
        printf '%s\n' "$backup_path" >>"$BACKUP_MANIFEST"
    fi
}

backup_existing_path() {
    local path="$1"
    local backup_path
    local counter=0

    backup_path="${path}.bak.$(date +%s)"

    while [ -e "$backup_path" ] || [ -L "$backup_path" ]; do
        counter=$((counter + 1))
        backup_path="${path}.bak.$(date +%s).$counter"
    done

    mv -- "$path" "$backup_path"
    record_backup "$backup_path"
    printf '%s\n' "$backup_path"
}

calculate_sha256() {
    local path="$1"

    if command -v sha256sum >/dev/null 2>&1; then
        sha256sum "$path" | awk '{print $1}'
    elif command -v shasum >/dev/null 2>&1; then
        shasum -a 256 "$path" | awk '{print $1}'
    else
        return 1
    fi
}

verify_sha256_file() {
    local expected_sha256="$1"
    local path="$2"
    local actual_sha256

    if [[ ! "$expected_sha256" =~ ^[[:xdigit:]]{64}$ ]]; then
        echo "❌ Invalid SHA-256 digest for $path" >&2
        return 2
    fi
    if ! actual_sha256=$(calculate_sha256 "$path"); then
        echo "❌ No SHA-256 utility available; refusing to use $path" >&2
        return 1
    fi
    if [ "$actual_sha256" != "$expected_sha256" ]; then
        echo "❌ SHA-256 mismatch for $path" >&2
        return 1
    fi
}

run_remote_script() {
    local url="$1"
    shift
    local expected_sha256=""
    local script status

    if [ "${1:-}" = "--sha256" ]; then
        if [ "$#" -lt 2 ]; then
            echo "❌ --sha256 requires a SHA-256 digest for $url" >&2
            return 2
        fi
        expected_sha256="$2"
        shift 2
        if [[ ! "$expected_sha256" =~ ^[[:xdigit:]]{64}$ ]]; then
            echo "❌ Invalid SHA-256 digest for $url" >&2
            return 2
        fi
    fi

    script=$(mktemp "${TMPDIR:-/tmp}/dotfiles-download.XXXXXX")
    if ! curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 -o "$script" "$url"; then
        rm -f "$script"
        return 1
    fi

    if [ -n "$expected_sha256" ]; then
        if ! verify_sha256_file "$expected_sha256" "$script"; then
            rm -f "$script"
            return 1
        fi
        echo "🔐 Verified SHA-256 for $url"
    fi

    if bash "$script" "$@"; then
        status=0
    else
        status=$?
    fi
    rm -f "$script"
    return "$status"
}

remove_from_rc_if_present() {
    local rc_file="${1/#\~/$HOME}"
    local line_to_remove="$2"
    if [ -f "$rc_file" ] && grep -Fq "$line_to_remove" "$rc_file"; then
        if $DRY_RUN; then
            echo "🧪 Would remove line from $rc_file: $line_to_remove"
        else
            echo "🧽 removing line from $rc_file: $line_to_remove"
            # Create a temp file safely
            tmp_file="${rc_file}.tmp.$$"
            grep -Fv "$line_to_remove" "$rc_file" >"$tmp_file" || true
            mv "$tmp_file" "$rc_file"
        fi
    fi
}

cleanup_legacy_path_dedup() {
    local rc_file="$1"

    remove_from_rc_if_present "$rc_file" "$LEGACY_PATH_DEDUP_MARKER"
    remove_from_rc_if_present "$rc_file" "$LEGACY_PATH_DEDUP_LINE"
}

apt_package_installed() {
    dpkg -s "$1" >/dev/null 2>&1
}

install_required_apt_package() {
    local pkg="$1"

    if apt_package_installed "$pkg"; then
        echo "✅ $pkg already installed"
    else
        echo "📦 Installing $pkg..."
        sudo apt install -y "$pkg"
    fi
}

install_optional_apt_package() {
    local pkg="$1"

    if apt_package_installed "$pkg"; then
        echo "✅ $pkg already installed"
    else
        echo "📦 Installing $pkg..."
        if sudo apt install -y "$pkg"; then
            echo "✅ Installed $pkg"
        else
            echo "⚠️  $pkg is unavailable from apt on this system; continuing without it"
        fi
    fi
}

install_eza_from_apt_repository() {
    local key_url="https://raw.githubusercontent.com/eza-community/eza/main/deb.asc"
    local keyring="/etc/apt/keyrings/gierens.gpg"
    local source_file="/etc/apt/sources.list.d/gierens.list"
    local architecture key_tmp

    if apt_package_installed eza; then
        echo "✅ eza already installed"
        return 0
    fi

    architecture=$(dpkg --print-architecture 2>/dev/null || true)
    if [ -z "$architecture" ]; then
        echo "⚠️  Cannot determine the Debian architecture; skipping eza."
        return 0
    fi

    echo "📥 Configuring the official eza apt repository..."
    key_tmp=$(mktemp "${TMPDIR:-/tmp}/eza-key.XXXXXX")
    if ! curl --fail --silent --show-error --location --proto '=https' --tlsv1.2 -o "$key_tmp" "$key_url"; then
        rm -f "$key_tmp"
        echo "⚠️  Could not download the eza repository key; skipping eza."
        return 0
    fi

    if [ -n "${DOTFILES_EZA_KEY_SHA256:-}" ]; then
        if ! verify_sha256_file "$DOTFILES_EZA_KEY_SHA256" "$key_tmp"; then
            rm -f "$key_tmp"
            echo "⚠️  eza repository key verification failed; skipping eza."
            return 0
        fi
        echo "🔐 Verified SHA-256 for the eza repository key"
    fi

    if ! sudo mkdir -p "$(dirname "$keyring")" || ! sudo gpg --dearmor --yes --output "$keyring" "$key_tmp"; then
        rm -f "$key_tmp"
        echo "⚠️  Could not install the eza repository key; skipping eza."
        return 0
    fi
    rm -f "$key_tmp"
    sudo chmod 0644 "$keyring"

    printf 'deb [arch=%s signed-by=%s] http://deb.gierens.de stable main\n' \
        "$architecture" "$keyring" | sudo tee "$source_file" >/dev/null
    sudo chmod 0644 "$source_file"
    sudo apt update
    if ! sudo apt install -y eza; then
        echo "⚠️  eza is unavailable from the official repository; skipping it."
    fi
}

ensure_local_bin_on_path() {
    if [ -d "$HOME/.local/bin" ] && [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
        export PATH="$HOME/.local/bin:$PATH"
    fi
}

report_macos_sudo_touch_id_status() {
    local sudo_pam="/etc/pam.d/sudo"
    local sudo_tid_line='auth       sufficient     pam_tid.so'

    if grep -Fqx "$sudo_tid_line" "$sudo_pam" 2>/dev/null; then
        echo "✅ Touch ID is already enabled for sudo via $sudo_pam"
        return 0
    fi

    echo "⚠️  Touch ID for sudo does not appear to be enabled."
    echo "ℹ️  Manual recovery path:"
    echo "   1. Edit /etc/pam.d/sudo with sudo"
    echo "   2. Ensure this exact line is present: $sudo_tid_line"
    echo "   3. Test with: sudo -k && sudo -v"
}

offer_github_authentication() {
    if ! command -v gh >/dev/null 2>&1; then
        return 0
    fi

    if gh auth status --hostname github.com >/dev/null 2>&1; then
        echo "✅ GitHub CLI is already authenticated on github.com"
        return 0
    fi

    if [ "${DOTFILES_TEST_INTERACTIVE:-false}" != true ] && { [ ! -t 0 ] || [ ! -t 1 ]; }; then
        echo "ℹ️  gh is not authenticated. Run 'gh auth login' from an interactive shell when ready."
        return 0
    fi

    local configure_gh_auth
    read -r -p $'\n🐙 Authenticate GitHub CLI with gh auth login? [y/N]: ' configure_gh_auth || return 0
    if [[ ! "$configure_gh_auth" =~ ^[Yy]$ ]]; then
        echo "ℹ️  Skipping GitHub CLI authentication. Run 'gh auth login' later when ready."
        return 0
    fi

    if gh auth login; then
        echo "✅ GitHub CLI authentication completed."
        echo "ℹ️  Configure Git to use gh credentials with: gh auth setup-git"
        echo "ℹ️  Add an SSH authentication key with: gh ssh-key add ~/.ssh/<key>.pub --type authentication"
        echo "ℹ️  Add an SSH signing key with: gh ssh-key add ~/.ssh/<key>.pub --type signing"
        echo "ℹ️  Add a GPG signing key with: gh gpg-key add <public-key-file>"
    else
        echo "⚠️  GitHub CLI authentication was not completed; you can retry with: gh auth login"
    fi
}

offer_nvm_global_package_migration() {
    local previous_node="$1"
    local target_node migrate_packages

    target_node="$(nvm version current 2>/dev/null || echo none)"
    if [ "$target_node" = "$previous_node" ] || [ "$target_node" = "none" ] || [ "$target_node" = "system" ]; then
        return 0
    fi

    echo "ℹ️  Global npm packages are scoped to each nvm Node version."
    echo "   Current target: $target_node"
    echo "   Source version: $previous_node"

    if $FORCE_MODE || $INSTALL_ALL || { [ "${DOTFILES_TEST_INTERACTIVE:-false}" != true ] && { [ ! -t 0 ] || [ ! -t 1 ]; }; }; then
        echo "ℹ️  Skipping package migration in non-interactive/automatic mode."
        echo "   Run when ready: nvm use $target_node && nvm reinstall-packages $previous_node"
        return 0
    fi

    read -r -p $'📦 Migrate global npm packages to the new Node version with nvm reinstall-packages? [y/N]: ' migrate_packages || return 0
    if [[ "$migrate_packages" =~ ^[Yy]$ ]]; then
        if nvm reinstall-packages "$previous_node"; then
            echo "✅ Global npm packages migrated from $previous_node to $target_node"
        else
            echo "⚠️  Global npm package migration failed; retry with: nvm use $target_node && nvm reinstall-packages $previous_node"
        fi
    else
        echo "ℹ️  Skipping package migration. Run when ready: nvm use $target_node && nvm reinstall-packages $previous_node"
    fi
}

ensure_macos_xcode_tools() {
    local developer_dir xcode_version xcode_line

    if ! developer_dir=$(xcode-select -p 2>/dev/null); then
        echo "⚠️  Xcode developer tools are missing."
        echo "ℹ️  Install Xcode from the App Store or run: xcode-select --install"
        return 1
    fi

    if ! xcode_version=$(xcodebuild -version 2>/dev/null); then
        echo "⚠️  xcodebuild is unavailable even though xcode-select points to $developer_dir"
        echo "ℹ️  Install Xcode, then run: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer"
        return 1
    fi

    echo "✅ Xcode developer directory: $developer_dir"
    while IFS= read -r xcode_line; do
        [[ -n "$xcode_line" ]] && echo "✅ $xcode_line"
    done <<<"$xcode_version"
}

report_macos_stats_quarantine_hint() {
    local stats_app="/Applications/Stats.app"

    if [ ! -d "$stats_app" ] || ! command -v xattr >/dev/null 2>&1; then
        return 0
    fi

    if xattr -p com.apple.quarantine "$stats_app" >/dev/null 2>&1; then
        echo "ℹ️  Stats.app still has the quarantine bit set."
        echo "   If it refuses to open, run:"
        echo "   sudo xattr -r -d com.apple.quarantine /Applications/Stats.app/"
    fi
}

report_git_identity_hint() {
    local git_name git_email

    if ! command -v git >/dev/null 2>&1; then
        return 0
    fi

    git_name=$(git config --global --get user.name 2>/dev/null || true)
    git_email=$(git config --global --get user.email 2>/dev/null || true)

    if [[ -n "$git_name" && -n "$git_email" ]]; then
        return 0
    fi

    echo "ℹ️  Git identity is not fully configured yet."
    echo "   Set it with:"
    echo "   git config --global user.name \"Your Name\""
    echo "   git config --global user.email \"you@example.com\""
}

phase_banner() {
    printf '\n%s\n' "────────────────────────────────────────────────"
    printf '▶ %s\n' "$1"
    printf '%s\n' "────────────────────────────────────────────────"
}

install_uv_python_version() {
    if uv python install --preview --default "$UV_PYTHON_VERSION"; then
        ensure_local_bin_on_path
        return 0
    fi

    echo "⚠️  uv default executables require preview mode; falling back to Python $UV_PYTHON_VERSION without default executables."
    uv python install "$UV_PYTHON_VERSION" || true
    ensure_local_bin_on_path
}

trust_brewfile_taps() {
    local tap

    while IFS= read -r tap; do
        echo "🔐 Trusting Homebrew tap: $tap"
        brew trust --tap "$tap"
    done < <(sed -nE 's/^[[:space:]]*tap[[:space:]]+"([^"]+)".*/\1/p' "$MACOS_BREWFILE")
}

apply_rc_lines() {
    local action="$1"
    local rc_file="$2"
    shift 2

    local line
    for line in "$@"; do
        if [[ "$action" == "add" ]]; then
            add_to_rc_if_not_present "$rc_file" "$line"
        else
            remove_from_rc_if_present "$rc_file" "$line"
        fi
    done
}

snapshot_git_config_value() {
    local state_file="$1"
    local setting_id="$2"
    local setting_key="$3"
    local value

    while IFS= read -r value; do
        git config --file "$state_file" --add "snapshot.$setting_id" "$value"
    done < <(git config --global --get-all "$setting_key" 2>/dev/null || true)
}

snapshot_git_config_key_if_missing() {
    local state_file="$1"
    local setting_key="$2"
    local setting_id

    setting_id=$(git_config_setting_id "$setting_key")
    if git config --file "$state_file" --get-all "snapshot.$setting_id" >/dev/null 2>&1; then
        return
    fi

    snapshot_git_config_value "$state_file" "$setting_id" "$setting_key"
}

snapshot_git_default_from_baseline() {
    local state_file="$1"
    local setting_key="$2"
    local setting_id

    setting_id=$(git_config_setting_id "$setting_key")
    snapshot_git_config_value "$state_file" "$setting_id" "$setting_key"
}

git_config_setting_id() {
    printf '%s' "$1" | tr '[:upper:].' '[:lower:]-'
}

for_each_git_default() {
    local callback="$1"
    shift
    local setting_key
    local setting_value
    local callback_failed=false

    while IFS='=' read -r setting_key setting_value; do
        if [ -z "$setting_key" ] || [[ "$setting_key" == \#* ]]; then
            continue
        fi
        if [ -z "$setting_value" ]; then
            echo "❌ Invalid Git defaults entry: $setting_key" >&2
            return 2
        fi
        if ! "$callback" "$@" "$setting_key" "$setting_value"; then
            callback_failed=true
        fi
    done <"$GIT_DEFAULTS_FILE"

    if $callback_failed; then
        return 1
    fi
}

snapshot_git_config_before_install() {
    if [ -f "$GIT_CONFIG_STATE_FILE" ]; then
        return
    fi

    mkdir -p "$GIT_CONFIG_STATE_DIR"
    local state_tmp
    state_tmp=$(mktemp "$GIT_CONFIG_STATE_DIR/git-config.before.XXXXXX")
    chmod 600 "$state_tmp"

    git config --file "$state_tmp" installer.version 1
    snapshot_git_config_value "$state_tmp" "core-excludesfile" "core.excludesfile"
    for_each_git_default snapshot_git_default_from_baseline "$state_tmp"

    mv "$state_tmp" "$GIT_CONFIG_STATE_FILE"
}

configure_git_default() {
    local setting_key="$1"
    local setting_value="$2"
    local setting_id
    setting_id=$(git_config_setting_id "$setting_key")

    git config --global "$setting_key" "$setting_value"
    git config --file "$GIT_CONFIG_STATE_FILE" --replace-all "managed.$setting_id" "$setting_value"
}

configure_git_default_from_baseline() {
    configure_git_default "$1" "$2"
}

configure_delta_git() {
    local setting_entry setting_key setting_value

    if ! command -v delta >/dev/null 2>&1; then
        return 0
    fi

    snapshot_git_config_before_install
    for setting_entry in "${DELTA_GIT_DEFAULTS[@]}"; do
        IFS='=' read -r setting_key setting_value <<<"$setting_entry"
        snapshot_git_config_key_if_missing "$GIT_CONFIG_STATE_FILE" "$setting_key"
        configure_git_default "$setting_key" "$setting_value"
    done

    echo "✅ Configured Git to use delta with navigation, side-by-side output, and line numbers."
}

restore_git_default() {
    local setting_key="$1"
    local setting_id
    local installed_value
    local current_value
    local snapshot_value

    setting_id=$(git_config_setting_id "$setting_key")
    installed_value=$(git config --file "$GIT_CONFIG_STATE_FILE" --get "managed.$setting_id" 2>/dev/null || true)
    if [ -z "$installed_value" ]; then
        return
    fi

    current_value=$(git config --global --get-all "$setting_key" 2>/dev/null || true)
    if [ "$current_value" != "$installed_value" ]; then
        echo "⚠️  Keeping Git setting $setting_key because it changed after installation."
        return 1
    fi

    git config --global --unset-all "$setting_key" || true
    while IFS= read -r snapshot_value; do
        git config --global --add "$setting_key" "$snapshot_value"
    done < <(git config --file "$GIT_CONFIG_STATE_FILE" --get-all "snapshot.$setting_id" 2>/dev/null || true)
}

restore_git_default_from_baseline() {
    restore_git_default "$1"
}

restore_git_config_before_install() {
    if [ ! -f "$GIT_CONFIG_STATE_FILE" ]; then
        return
    fi

    if $DRY_RUN; then
        echo "🧪 Would restore Git settings managed by the installer."
        return
    fi

    if ! command -v git >/dev/null 2>&1; then
        echo "⚠️  git not found; leaving installer-managed Git settings in place."
        return
    fi

    local restore_failed=false
    echo "🔧 Restoring Git settings managed by the installer..."
    restore_git_default "core.excludesfile" || restore_failed=true
    for_each_git_default restore_git_default_from_baseline || restore_failed=true
    local delta_entry delta_key
    for delta_entry in "${DELTA_GIT_DEFAULTS[@]}"; do
        delta_key="${delta_entry%%=*}"
        restore_git_default "$delta_key" || restore_failed=true
    done

    if ! $restore_failed; then
        rm -f "$GIT_CONFIG_STATE_FILE"
        rmdir "$GIT_CONFIG_STATE_DIR" 2>/dev/null || true
    fi
}

run_uninstall() {
    echo -e "\n🧹 Uninstalling dotfiles symlinks and shell rc additions..."
    restore_git_config_before_install
    # Remove symlinks we manage if they point to our repo
    for i in "${!SYMLINK_KEYS[@]}"; do
        local dest src
        dest="${SYMLINK_KEYS[$i]}"
        src="${SYMLINK_VALUES[$i]}"
        if [ -L "$dest" ] && [ "$(readlink "$dest")" = "$src" ]; then
            if $DRY_RUN; then
                echo "🧪 Would remove symlink $dest"
            else
                echo "🗑️  Removing symlink $dest"
                rm -f "$dest"
            fi
        fi
    done

    # Remove startup additions (guarded lines)
    for rc in ~/.zshrc ~/.bashrc; do
        apply_rc_lines remove "$rc" "${COMMON_RC_LINES[@]}"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && nice_print_aliases"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && { fastfetch 2>/dev/null; } &>/dev/null"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && { screenfetch 2>/dev/null; } &>/dev/null"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && { fastfetch 2>/dev/null; } 2>/dev/null"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && { screenfetch 2>/dev/null; } 2>/dev/null"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && fastfetch 2>/dev/null"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && screenfetch 2>/dev/null"
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && eval \"\$(zoxide init zsh)\""
        remove_from_rc_if_present "$rc" "[[ \$- == *i* ]] && eval \"\$(zoxide init bash)\""
        remove_from_rc_if_present "$rc" "source /usr/share/fzf/key-bindings.bash"
        remove_from_rc_if_present "$rc" "source /usr/share/fzf/completion.bash"
        remove_from_rc_if_present "$rc" "source /usr/share/fzf/key-bindings.zsh"
        remove_from_rc_if_present "$rc" "source /usr/share/fzf/completion.zsh"
        remove_from_rc_if_present "$rc" "$PATH_DEDUP_MARKER"
        remove_from_rc_if_present "$rc" 'typeset -U path'
        remove_from_rc_if_present "$rc" '[ -x /usr/bin/awk ] && [ -x /usr/bin/paste ] && [ -x /usr/bin/tr ] && PATH="$([ -x /usr/bin/printf ] && /usr/bin/printf %s "$PATH" | /usr/bin/tr ":" "\n" | /usr/bin/awk '\''!seen[$0]++'\'' | /usr/bin/paste -sd:)" && export PATH'
        apply_rc_lines remove "$rc" "${NVM_RC_LINES[@]}"
    done

    for rc in ~/.zprofile ~/.bash_profile; do
        apply_rc_lines remove "$rc" "${HOMEBREW_RC_LINES[@]}"
    done
}

if [ -n "$TEST_FUNCTION" ]; then
    case "$TEST_FUNCTION" in
        gh-auth)
            offer_github_authentication
            ;;
        nvm-migrate)
            offer_nvm_global_package_migration "${DOTFILES_TEST_NVM_PREVIOUS:-v0.0.0}"
            ;;
        remote-script)
            run_remote_script "${DOTFILES_TEST_REMOTE_URL:-https://example.invalid/script.sh}" --sha256 "${DOTFILES_TEST_REMOTE_SHA256:-}"
            ;;
        *)
            echo "❌ Unknown DOTFILES_TEST_FUNCTION: $TEST_FUNCTION" >&2
            exit 2
            ;;
    esac
    exit 0
fi

if $UNINSTALL_MODE; then
    run_uninstall
    echo -e "\n🚀 Uninstall complete."
    exit 0
fi

### === Symlink Files ===
echo -e "\n🔗 Linking or copying files..."
for i in "${!SYMLINK_KEYS[@]}"; do
    dest="${SYMLINK_KEYS[$i]}"
    src="${SYMLINK_VALUES[$i]}"
    if $DRY_RUN; then
        action=$([[ $COPY_MODE == true ]] && echo "copy" || echo "link")
        echo "🧪 Would $action $dest → $src"
    elif $COPY_MODE; then
        if [ -e "$dest" ] || [ -L "$dest" ]; then
            backup_path=$(backup_existing_path "$dest")
            echo "📦 Backed up $dest -> $backup_path"
        fi
        cp -a "$src" "$dest"
        echo "📄 Copied $src → $dest"
    else
        if [ -e "$dest" ] || [ -L "$dest" ]; then
            if [ ! -L "$dest" ] || [ "$(readlink "$dest")" != "$src" ]; then
                backup_path=$(backup_existing_path "$dest")
                echo "📦 Backed up existing $dest -> $backup_path"
            fi
        fi
        ln -sf "$src" "$dest"
        echo "✅ Linked $dest → $src"
    fi
done

### === Optional Tools Install ===
if ! $MINIMAL_MODE && ! $SKIP_TOOLS && ! $DRY_RUN; then
    if $INSTALL_ALL; then
        do_install="y"
    else
        if [[ "$OS" == "Darwin" ]]; then
            read -r -p $'\n✨ Install macOS packages and defaults? (Brewfile + recommended system settings + Dock layout)? [y/N]: ' do_install
        else
            read -r -p $'\n✨ Install optional tools? (fzf, eza, bat, zoxide, oh-my-posh, nano, fd, ripgrep, shellcheck, shfmt, uv, swiftly, gh)? [y/N]: ' do_install
        fi
    fi

    if [[ "$do_install" =~ ^[Yy]$ ]]; then
        OPTIONAL_INSTALL_APPROVED=true
        echo -e "\n📦 Installing tools..."

        case "$OS" in
            Darwin)
                if ! ensure_macos_xcode_tools; then
                    exit 1
                fi

                if ! command -v brew >/dev/null; then
                    echo "🍺 Homebrew not found. Installing..."
                    if [ -n "${DOTFILES_HOMEBREW_INSTALL_SHA256:-}" ]; then
                        brew_install_args=(--sha256 "$DOTFILES_HOMEBREW_INSTALL_SHA256")
                    else
                        brew_install_args=()
                    fi
                    if ! run_remote_script "https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh" "${brew_install_args[@]}"; then
                        echo "❌ Homebrew installation failed." >&2
                        exit 1
                    fi
                    # Initialize Homebrew in current session and future shells
                    if [ -x /opt/homebrew/bin/brew ]; then
                        eval "$(/opt/homebrew/bin/brew shellenv)"
                        apply_rc_lines add "$HOME/.zprofile" "${HOMEBREW_RC_LINES[0]}"
                        apply_rc_lines add "$HOME/.bash_profile" "${HOMEBREW_RC_LINES[0]}"
                    elif [ -x /usr/local/bin/brew ]; then
                        eval "$(/usr/local/bin/brew shellenv)"
                        apply_rc_lines add "$HOME/.zprofile" "${HOMEBREW_RC_LINES[1]}"
                        apply_rc_lines add "$HOME/.bash_profile" "${HOMEBREW_RC_LINES[1]}"
                    fi
                fi

                if $TRUST_BREW_TAPS; then
                    phase_banner "Homebrew tap trust"
                    trust_brewfile_taps
                fi

                phase_banner "Homebrew Bundle"
                if [ -f "$MACOS_BREWFILE" ]; then
                    echo "📦 Installing macOS packages from Brewfile..."
                    if $BREW_UPGRADE; then
                        brew bundle install --verbose --file "$MACOS_BREWFILE"
                    else
                        # Bootstrap missing packages without taking ownership of every installed update.
                        brew bundle install --no-upgrade --verbose --file "$MACOS_BREWFILE"
                    fi
                else
                    echo "⚠️  Missing macOS Brewfile at $MACOS_BREWFILE; skipping package install."
                fi

                ensure_local_bin_on_path

                phase_banner "Shell integration"
                # fzf keybindings/completions (Homebrew layout)
                if $INSTALL_ALL || $FORCE_MODE; then configure_fzf="y"; else read -r -p $'\n🎹 Enable fzf keybindings and completions? [y/N]: ' configure_fzf; fi
                if [[ "$configure_fzf" =~ ^[Yy]$ ]]; then
                    echo "⚙️  Configuring fzf keybindings/completions..."
                    "$(brew --prefix)/opt/fzf/install" --key-bindings --completion --no-update-rc || true
                    zsh_bind="$(brew --prefix)/opt/fzf/shell/key-bindings.zsh"
                    zsh_comp="$(brew --prefix)/opt/fzf/shell/completion.zsh"
                    bash_bind="$(brew --prefix)/opt/fzf/shell/key-bindings.bash"
                    bash_comp="$(brew --prefix)/opt/fzf/shell/completion.bash"
                    if [[ "$SHELL_NAME" == "zsh" ]]; then
                        if [ -f "$zsh_bind" ]; then apply_rc_lines add "$HOME/.zshrc" "source $zsh_bind"; fi
                        if [ -f "$zsh_comp" ]; then apply_rc_lines add "$HOME/.zshrc" "source $zsh_comp"; fi
                    else
                        if [ -f "$bash_bind" ]; then apply_rc_lines add "$HOME/.bashrc" "source $bash_bind"; fi
                        if [ -f "$bash_comp" ]; then apply_rc_lines add "$HOME/.bashrc" "source $bash_comp"; fi
                    fi
                fi

                phase_banner "macOS system preferences"
                if [ -f "$MACOS_DEFAULTS_SCRIPT" ]; then
                    if $INSTALL_ALL || $FORCE_MODE; then apply_macos_defaults="y"; else read -r -p $'\n🍎 Apply recommended macOS defaults? [y/N]: ' apply_macos_defaults; fi
                    if [[ "$apply_macos_defaults" =~ ^[Yy]$ ]]; then
                        bash "$MACOS_DEFAULTS_SCRIPT" --restart
                    fi
                else
                    echo "⚠️  Missing macOS defaults script at $MACOS_DEFAULTS_SCRIPT; skipping defaults."
                fi

                if [ -f "$MACOS_DOCK_SCRIPT" ]; then
                    if $INSTALL_ALL || $FORCE_MODE; then apply_macos_dock="y"; else read -r -p $'\n🧷 Apply saved Dock layout? [y/N]: ' apply_macos_dock; fi
                    if [[ "$apply_macos_dock" =~ ^[Yy]$ ]]; then
                        bash "$MACOS_DOCK_SCRIPT" --restart
                    fi
                else
                    echo "⚠️  Missing macOS Dock script at $MACOS_DOCK_SCRIPT; skipping Dock layout."
                fi

                if $INSTALL_ALL || $FORCE_MODE; then check_macos_sudo_touch_id="y"; else read -r -p $'\n🔐 Check Touch ID for sudo configuration? [Y/n]: ' check_macos_sudo_touch_id; fi
                if [[ ! "$check_macos_sudo_touch_id" =~ ^[Nn]$ ]]; then
                    report_macos_sudo_touch_id_status
                fi

                # Optional: install pinned Python via uv
                phase_banner "Toolchain checks"
                if command -v uv >/dev/null 2>&1; then
                    if $INSTALL_ALL || $FORCE_MODE; then uv_install_py="y"; else read -r -p $'🐍 Install Python 3.13 via uv? [y/N]: ' uv_install_py; fi
                    if [[ "$uv_install_py" =~ ^[Yy]$ ]]; then
                        install_uv_python_version
                    fi
                fi

                # Optional: install latest stable Swift toolchain via swiftly
                if command -v swiftly >/dev/null 2>&1; then
                    if $INSTALL_ALL || $FORCE_MODE; then sw_install_tc="y"; else read -r -p $'🦅 Install latest stable Swift toolchain via swiftly? [y/N]: ' sw_install_tc; fi
                    if [[ "$sw_install_tc" =~ ^[Yy]$ ]]; then
                        swiftly install stable || true
                    fi
                fi

                phase_banner "Post-install hints"
                report_macos_stats_quarantine_hint
                ;;
            Linux)
                echo "🐧 Detected Linux; targeting Debian/Ubuntu via apt"
                sudo apt update

                # Required packages (alphabetical)
                for pkg in curl exiv2 fzf gnupg jq nano ripgrep unzip; do
                    install_required_apt_package "$pkg"
                done

                # Best-effort packages: useful enhancements, but not hard blockers
                for pkg in bat delta fd-find fastfetch zoxide; do
                    install_optional_apt_package "$pkg"
                done

                # gh (GitHub CLI) via official apt repository
                if ! command -v gh >/dev/null 2>&1; then
                    echo "📥 Installing GitHub CLI (gh)..."
                    if [ ! -f /usr/share/keyrings/githubcli-archive-keyring.gpg ]; then
                        if curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
                            | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg; then
                            sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg || true
                        fi
                    fi
                    if ! grep -qs "cli.github.com/packages" /etc/apt/sources.list /etc/apt/sources.list.d/* 2>/dev/null; then
                        echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
                            | sudo tee /etc/apt/sources.list.d/github-cli.list >/dev/null || true
                    fi
                    sudo apt update || true
                    sudo apt install -y gh || echo "⚠️  Failed to install gh via apt; you can install it manually: https://github.com/cli/cli#installation"
                else
                    echo "✅ gh already installed"
                fi

                # eza
                if ! command -v eza >/dev/null; then
                    install_eza_from_apt_repository
                fi

                # oh-my-posh
                if ! command -v oh-my-posh >/dev/null; then
                    echo "📥 Installing oh-my-posh..."
                    echo "   Downloading the official installer over HTTPS before execution."
                    if [ -n "${DOTFILES_OHMYPOSH_INSTALL_SHA256:-}" ]; then
                        oh_my_posh_install_args=(--sha256 "$DOTFILES_OHMYPOSH_INSTALL_SHA256")
                    else
                        oh_my_posh_install_args=()
                    fi
                    run_remote_script "https://ohmyposh.dev/install.sh" "${oh_my_posh_install_args[@]}" -d "$HOME/.local/bin" -t "$HOME/.cache/oh-my-posh/themes"
                fi

                # fastfetch
                if ! command -v fastfetch >/dev/null; then
                    echo "📥 Installing fastfetch..."
                    install_optional_apt_package fastfetch
                    if ! command -v fastfetch >/dev/null; then
                        echo "⚠️ fastfetch not available via apt. You can build it manually:"
                        echo "   https://github.com/fastfetch-cli/fastfetch"
                    fi
                fi

                # handle batcat/bat and fdfind/fd shims
                if command -v batcat >/dev/null && ! command -v bat >/dev/null; then
                    sudo ln -sf "$(command -v batcat)" /usr/local/bin/bat
                    echo "🔗 Created shim: bat -> batcat"
                fi
                if command -v fdfind >/dev/null && ! command -v fd >/dev/null; then
                    sudo ln -sf "$(command -v fdfind)" /usr/local/bin/fd
                    echo "🔗 Created shim: fd -> fdfind"
                fi

                # uv (Python tool)
                if ! command -v uv >/dev/null 2>&1; then
                    echo "📥 Installing uv (Python tooling)..."
                    echo "   Downloading the official installer over HTTPS before execution."
                    if [ -n "${DOTFILES_UV_INSTALL_SHA256:-}" ]; then
                        uv_install_args=(--sha256 "$DOTFILES_UV_INSTALL_SHA256")
                    else
                        uv_install_args=()
                    fi
                    run_remote_script "https://astral.sh/uv/install.sh" "${uv_install_args[@]}"
                else
                    echo "✅ uv already installed"
                fi

                # swiftly (Swift toolchain manager)
                # Try to source existing env so detection works even if not on PATH yet
                swiftly_home="${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}"
                swiftly_env="$swiftly_home/env.sh"
                swiftly_bin="$swiftly_home/bin/swiftly"
                # shellcheck disable=SC1090
                if [ -f "$swiftly_env" ]; then . "$swiftly_env"; fi
                if ! command -v swiftly >/dev/null 2>&1 && [ ! -x "$swiftly_bin" ]; then
                    echo "📥 Installing swiftly (Swift toolchain manager)..."
                    # Ensure GnuPG is available for signature verification required by swiftly
                    if ! command -v gpg >/dev/null 2>&1; then
                        echo "   ↪ Installing gnupg (required by swiftly)..."
                        sudo apt install -y gnupg || true
                    fi
                    arch="$(uname -m)"
                    url="https://download.swift.org/swiftly/linux/swiftly-${arch}.tar.gz"
                    swiftly_archive="swiftly-${arch}.tar.gz"
                    tmpdir="$(mktemp -d)"
                    if (
                        set -e
                        cd "$tmpdir"
                        echo "   ↪ Downloading $url"
                        curl -fLO "$url"
                        if [ -n "${DOTFILES_SWIFTLY_INSTALL_SHA256:-}" ]; then
                            verify_sha256_file "$DOTFILES_SWIFTLY_INSTALL_SHA256" "$swiftly_archive"
                            echo "   ↪ Verified SHA-256 for $swiftly_archive"
                        fi
                        tar zxf "$swiftly_archive"
                        ./swiftly init --quiet-shell-followup --skip-install
                    ); then
                        env_file="$swiftly_env"
                        # shellcheck disable=SC1090
                        if [ -f "$env_file" ]; then . "$env_file"; fi
                        hash -r || true
                        echo "✅ swiftly installed"
                    else
                        if ! command -v gpg >/dev/null 2>&1; then
                            echo "⚠️  swiftly failed and 'gpg' is missing. Install it with: sudo apt install -y gnupg"
                        fi
                        echo "⚠️  swiftly installation failed. See https://www.swift.org/install/linux/ for manual steps."
                    fi
                    rm -rf "$tmpdir"
                else
                    echo "✅ swiftly already installed"
                fi

                # Ensure current session can find freshly installed user binaries
                ensure_local_bin_on_path
                # shellcheck disable=SC1090
                if [ -f "$swiftly_env" ]; then . "$swiftly_env"; fi

                # Optional: install pinned Python via uv
                if command -v uv >/dev/null 2>&1; then
                    if $INSTALL_ALL || $FORCE_MODE; then uv_install_py="y"; else read -r -p $'🐍 Install Python 3.13 via uv? [y/N]: ' uv_install_py; fi
                    if [[ "$uv_install_py" =~ ^[Yy]$ ]]; then
                        install_uv_python_version
                    fi
                fi

                # Optional: install latest stable Swift toolchain via swiftly
                if command -v swiftly >/dev/null 2>&1; then
                    if $INSTALL_ALL || $FORCE_MODE; then sw_install_tc="y"; else read -r -p $'🦅 Install latest stable Swift toolchain via swiftly? [y/N]: ' sw_install_tc; fi
                    if [[ "$sw_install_tc" =~ ^[Yy]$ ]]; then
                        swiftly install stable || true
                    fi
                fi
                ;;
            *)
                echo "❌ Unsupported OS. Install dependencies manually."
                ;;
        esac
    fi
fi

# Set up Git global ignore config and merge recommended defaults into the existing global config.
if ! $SKIP_GIT_CONFIG && ! $DRY_RUN; then
    if command -v git >/dev/null 2>&1; then
        snapshot_git_config_before_install
        GIT_IGNORE_GLOBAL="$HOME/.global.gitignore"
        if [ -f "$GIT_IGNORE_GLOBAL" ]; then
            echo "🔧 Configuring Git global ignore path..."
            configure_git_default "core.excludesfile" "$GIT_IGNORE_GLOBAL"
        fi

        echo "🔧 Configuring global Git behavior..."
        for_each_git_default configure_git_default_from_baseline
    else
        echo "⚠️  git not found; skipping global Git configuration for now."
    fi
fi

if $OPTIONAL_INSTALL_APPROVED && ! $MINIMAL_MODE && ! $SKIP_TOOLS && ! $DRY_RUN && ! $FORCE_MODE && ! $INSTALL_ALL && command -v delta >/dev/null 2>&1; then
    read -r -p $'\n🎨 Configure delta as the Git pager with side-by-side diffs? [y/N]: ' configure_delta
    if [[ "$configure_delta" =~ ^[Yy]$ ]]; then
        configure_delta_git
    fi
fi

if $OPTIONAL_INSTALL_APPROVED && ! $MINIMAL_MODE && ! $SKIP_TOOLS && ! $DRY_RUN && ! $FORCE_MODE && ! $INSTALL_ALL; then
    offer_github_authentication
fi

### === Optional NVM Install ===
if ! $MINIMAL_MODE && ! $SKIP_TOOLS && ! $DRY_RUN; then
    if $FORCE_MODE; then want_nvm="y"; else read -r -p $'\n🟢 Install/Update nvm (Node Version Manager)? [y/N]: ' want_nvm; fi
    if [[ "$want_nvm" =~ ^[Yy]$ ]]; then
        NVM_TAG="$NVM_VERSION"

        if [ -d "$HOME/.nvm/.git" ]; then
            echo "🔄 Updating existing nvm to $NVM_TAG..."
            git -C "$HOME/.nvm" fetch --tags origin || true
            git -C "$HOME/.nvm" checkout "$NVM_TAG" || true
        else
            echo "📦 Installing nvm ($NVM_TAG)..."
            # Use the official installer pinned to the selected release tag.
            if [ -n "${DOTFILES_NVM_INSTALL_SHA256:-}" ]; then
                nvm_install_args=(--sha256 "$DOTFILES_NVM_INSTALL_SHA256")
            else
                nvm_install_args=()
            fi
            run_remote_script "https://raw.githubusercontent.com/nvm-sh/nvm/$NVM_TAG/install.sh" "${nvm_install_args[@]}"
        fi

        # Ensure nvm is initialized for the current shell; avoid touching rc of other shells
        if [[ "$SHELL_NAME" == "zsh" ]]; then
            apply_rc_lines add "$HOME/.zshrc" "${NVM_RC_LINES[@]}"
        else
            apply_rc_lines add "$HOME/.bashrc" "${NVM_RC_LINES[@]}"
        fi

        # Initialize nvm in current session if possible
        export NVM_DIR="$HOME/.nvm"
        # shellcheck disable=SC1091
        if [ -s "$NVM_DIR/nvm.sh" ]; then . "$NVM_DIR/nvm.sh"; fi
        # shellcheck disable=SC1091
        if [ -s "$NVM_DIR/bash_completion" ]; then . "$NVM_DIR/bash_completion"; fi

        # Determine current and latest LTS versions (best-effort)
        current_node="$(nvm version current 2>/dev/null || echo none)"
        remote_lts="$(nvm version-remote --lts 2>/dev/null || echo '')"

        if [[ "$current_node" != "none" && "$current_node" != "system" ]]; then
            # User already has a Node version active via nvm → offer to switch
            if $FORCE_MODE || $INSTALL_ALL; then
                switch_to_lts="y"
            else
                read -r -p $'\n🌳 Detected Node '"$current_node"$' active via nvm.'$'\n'$'   Switch to latest LTS'"${remote_lts:+ ($remote_lts)}"$' and set as default?\n'$'   Global npm packages are per-Node-version; a migration prompt follows after a successful switch.\n'$'   Proceed? [y/N]: ' switch_to_lts
            fi
            if [[ "$switch_to_lts" =~ ^[Yy]$ ]]; then
                prev_node="$current_node"
                nvm install --lts || true
                nvm alias default 'lts/*' || true
                nvm use --lts || true
                # Optionally enable Corepack for yarn/pnpm shims (non-fatal if missing)
                if command -v corepack >/dev/null 2>&1; then corepack enable || true; fi
                offer_nvm_global_package_migration "$prev_node"
            fi
        else
            # No active Node via nvm → offer to install latest LTS and set default
            if $FORCE_MODE || $INSTALL_ALL; then install_node="y"; else read -r -p $'🌱 Install latest LTS Node via nvm and set default? [y/N]: ' install_node; fi
            if [[ "$install_node" =~ ^[Yy]$ ]]; then
                nvm install --lts && nvm alias default 'lts/*'
                # Optionally enable Corepack for yarn/pnpm shims (non-fatal if missing)
                if command -v corepack >/dev/null 2>&1; then corepack enable || true; fi
            fi
        fi
    fi
fi

### === Check for other tools used in aliases/functions ===
echo -e "\n🔍 Checking for other recommended tools..."

for tool in "${REQUIRED_TOOLS[@]}"; do
    if ! command -v "$tool" >/dev/null 2>&1; then
        echo "⚠️  $tool not found. Some aliases or functions may not work correctly."
    else
        echo "✅ $tool is available."
    fi
done

FETCH_CMD=""
if command -v fastfetch >/dev/null 2>&1; then
    FETCH_CMD="{ fastfetch 2>/dev/null; } 2>/dev/null"
else
    FETCH_CMD="{ screenfetch 2>/dev/null; } 2>/dev/null"
fi

configure_shell_rc() {
    local shell_kind="$1"
    local rc_file="$2"
    local fzf_bind="$3"
    local fzf_comp="$4"
    local path_dedup_line="$5"
    local rc_path="${rc_file/#\~/$HOME}"
    local reply

    if [ -f "$rc_path" ]; then
        echo "🧠 $rc_path present, checking lines..."
    else
        if $DRY_RUN; then
            echo "🧪 Would create $rc_path"
        else
            echo "📝 $rc_path not found, creating a new one..."
            touch "$rc_path"
        fi
    fi

    apply_rc_lines add "$rc_file" "${COMMON_RC_LINES[@]}"
    cleanup_legacy_path_dedup "$rc_file"
    add_to_rc_if_not_present "$rc_file" "$PATH_DEDUP_MARKER"
    add_to_rc_if_not_present "$rc_file" "$path_dedup_line"

    if $DRY_RUN; then
        echo "🧪 Dry-run: skipping interactive startup prompts for $rc_path"
    elif ! ${SKIP_FETCH:-false}; then
        if $FORCE_MODE; then
            reply="y"
        else
            read -r -p "🧠 Run nice_print_aliases at shell startup? [y/N]: " reply
        fi
        if [[ "$reply" =~ ^[Yy]$ ]]; then
            add_to_rc_if_not_present "$rc_file" "[[ \$- == *i* ]] && nice_print_aliases"
        fi

        if $FORCE_MODE; then
            reply="y"
        else
            read -r -p "🖼️  Run $FETCH_CMD at shell startup? [y/N]: " reply
        fi
        if [[ "$reply" =~ ^[Yy]$ ]]; then
            add_to_rc_if_not_present "$rc_file" "[[ \$- == *i* ]] && $FETCH_CMD"
        fi
    fi

    if command -v zoxide >/dev/null 2>&1; then
        add_to_rc_if_not_present "$rc_file" "[[ \$- == *i* ]] && eval \"\$(zoxide init $shell_kind)\""
    fi
    if [ -f "$fzf_bind" ]; then
        add_to_rc_if_not_present "$rc_file" "source $fzf_bind"
    fi
    if [ -f "$fzf_comp" ]; then
        add_to_rc_if_not_present "$rc_file" "source $fzf_comp"
    fi
}

if [[ "$SHELL_NAME" == "zsh" ]]; then
    configure_shell_rc "zsh" "$HOME/.zshrc" "/usr/share/fzf/key-bindings.zsh" "/usr/share/fzf/completion.zsh" 'typeset -U path'
fi

if [[ "$SHELL_NAME" == "bash" ]]; then
    configure_shell_rc "bash" "$HOME/.bashrc" "/usr/share/fzf/key-bindings.bash" "/usr/share/fzf/completion.bash" "$BASH_PATH_DEDUP_LINE"
fi

if $CLEAN_BACKUPS; then
    echo -e "\n🧹 Looking for installer-created backup files to remove..."
    BACKUPS=()
    if [ -f "$BACKUP_MANIFEST" ]; then
        while IFS= read -r file; do
            [ -n "$file" ] || continue
            # Ignore tampered/out-of-scope manifest entries and stale paths.
            case "$file" in
                "$HOME"/*.bak.*)
                    if [ -e "$file" ] || [ -L "$file" ]; then
                        BACKUPS+=("$file")
                    fi
                    ;;
            esac
        done <"$BACKUP_MANIFEST"
    fi

    if [ ${#BACKUPS[@]} -eq 0 ]; then
        echo "✅ No backup files found."
    else
        echo "🗒️  Found the following backup files:"
        for file in "${BACKUPS[@]}"; do
            echo " - $file"
        done
        echo
        if $DRY_RUN; then
            for file in "${BACKUPS[@]}"; do
                echo "🧪 Would remove $file"
            done
            echo "✅ Dry-run complete. No backup files were removed."
        else
            if $FORCE_MODE; then
                confirm="y"
            else
                read -r -p "🛑 Do you want to delete all these files? [y/N]: " confirm
            fi
            if [[ "$confirm" =~ ^[Yy]$ ]]; then
                for file in "${BACKUPS[@]}"; do
                    echo "🗑️  Removing $file"
                    rm -f "$file"
                done
                : >"$BACKUP_MANIFEST"
                echo "✅ Done cleaning up backups."
            else
                echo "❌ Skipped backup cleanup."
            fi
        fi
    fi
fi

report_git_identity_hint

echo -e "\n🚀 Setup complete. You may need to restart your shell or source the new config."