update.sh

#!/usr/bin/env bash
# Update all managed tools and plugins
# Safe to run periodically - updates in-place, no reinstall needed
#
# Usage: update.sh [--check] [tool ...]
#
#   --check, -c    Show current vs latest versions without making any changes
#   --help,  -h    Show this message
#
# Available tools (pass one or more to update only those):
#   apt  omz  tmux-plugins  zsh-plugins  fzf  rg  fd  shellcheck
#   zoxide  delta  eza  yazi  uv  ruff  neovim  cheat  pre-commit  xcape
#
# A PATH shadow check always runs at the end (read-only). It detects older
# binaries at higher-priority PATH locations that would hide managed versions
# installed to /usr/local/bin (e.g. nvim, xcape).
#
# Examples:
#   ./update.sh --check              # check all versions + shadow report
#   ./update.sh --check neovim fzf  # check only neovim and fzf (+ shadow report)
#   ./update.sh neovim              # update only neovim (+ shadow report)
#   NOSUDO=1 ./update.sh            # skip apt upgrade, skip all sudo operations

set -euo pipefail

DOTFILES_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${DOTFILES_DIR}/lib/utils.sh"

ZSH_CUSTOM="${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}"
ARCH=$(uname -m)   # x86_64, aarch64, armv7l, ...

# ── Argument parsing ───────────────────────────────────────────────────────────

CHECK_ONLY=false
SELECTED=()

while [[ $# -gt 0 ]]; do
    case "$1" in
        --check|-c) CHECK_ONLY=true ;;
        --help|-h)
            sed -n '5,17p' "${BASH_SOURCE[0]}" | sed 's/^# \?//'
            exit 0
            ;;
        -*) echo "Unknown option: $1" >&2; exit 1 ;;
        *)  SELECTED+=("$1") ;;
    esac
    shift
done

_KNOWN_TOOLS=(apt omz tmux-plugins zsh-plugins fzf rg fd shellcheck
              zoxide delta eza yazi uv ruff neovim cheat pre-commit xcape)

# Validate SELECTED against known tool names.
for _sel in "${SELECTED[@]+"${SELECTED[@]}"}"; do
    _found=false
    for _known in "${_KNOWN_TOOLS[@]}"; do
        [[ "$_sel" == "$_known" ]] && _found=true && break
    done
    if ! $_found; then
        echo "Unknown tool: '$_sel'" >&2
        echo "Run '${BASH_SOURCE[0]} --help' for available tools." >&2
        exit 1
    fi
done
unset _sel _found _known

# Returns 0 (run this step) or 1 (skip it).
_should_run() {
    [[ ${#SELECTED[@]} -eq 0 ]] && return 0
    local name
    for name in "${SELECTED[@]}"; do
        [[ "$name" == "$1" ]] && return 0
    done
    return 1
}

# Update a standard GitHub binary release using Rust triple naming (tar.gz).
# Usage: _update_std_tool CMD LABEL REPO GNU_ARM [BINARY] [ASSET_PREFIX]
#   GNU_ARM: "gnu" -> aarch64 uses GNU triple; otherwise musl for both arches
_update_std_tool() {
    local cmd="$1" label="$2" repo="$3" gnu_arm="$4"
    local binary="${5:-$1}" prefix="${6:-}"
    _should_run "$cmd" || return 0
    log_step "$label"
    if ! has "$cmd"; then
        log_warn "$label not installed - skipping"
        return
    fi
    local arch
    case "$ARCH" in
        x86_64)  arch="x86_64-unknown-linux-musl" ;;
        aarch64) [ "$gnu_arm" = "gnu" ] && arch="aarch64-unknown-linux-gnu" || arch="aarch64-unknown-linux-musl" ;;
        *)       log_warn "$label: unsupported arch $ARCH - skipping"; return ;;
    esac
    local dest; dest=$(_resolve_dest "$binary" ~/.local/bin/"$binary")
    _gh_update_binary "$cmd" "$repo" "${prefix}${arch}.tar.gz" "$binary" "$dest" || true
}

# uv installs two binaries (uv + uvx) from one tarball - needs a custom handler.
_do_update_uv() {
    local uv_arch
    case "$ARCH" in
        x86_64)  uv_arch="x86_64-unknown-linux-musl"  ;;
        aarch64) uv_arch="aarch64-unknown-linux-musl" ;;
        *)       log_warn "uv: unsupported arch $ARCH - skipping"; return ;;
    esac
    if $CHECK_ONLY; then
        local current; current=$(_cmd_version uv --version) || current=""
        local latest; latest=$(_gh_latest_tag "astral-sh/uv") || latest=""
        _report_version uv "$current" "${latest:-unknown}"
        return
    fi
    local url; url=$(_gh_latest_release "astral-sh/uv" "uv-${uv_arch}.tar.gz") || url=""
    if [ -z "$url" ]; then log_warn "uv: could not fetch release URL - skipping"; return; fi
    local tmp; tmp=$(mktemp -d)
    # shellcheck disable=SC2064
    trap "rm -rf '$tmp'" RETURN
    if has curl; then curl -sfL "$url" | tar -xz -C "$tmp" \
        || { log_warn "uv: download/extraction failed - skipping"; return; }
    else wget -qO- "$url" | tar -xz -C "$tmp" \
        || { log_warn "uv: download/extraction failed - skipping"; return; }; fi
    for bin in uv uvx; do
        local found; found=$(find "$tmp" -name "$bin" -type f | head -1)
        [ -n "$found" ] && mv "$found" ~/.local/bin/"$bin" && chmod +x ~/.local/bin/"$bin"
    done
    if has uv; then
        log_ok "uv updated → ~/.local/bin ($(uv --version 2>/dev/null))"
        _verify_dest uv ~/.local/bin/uv
        _verify_dest uvx ~/.local/bin/uvx
    else
        log_warn "uv: binary not found in archive - update may have failed"
    fi
}

# neovim uses a directory tree (not a single binary) and skips when already current.
_do_update_neovim() {
    local nvim_arch
    case "$ARCH" in
        x86_64)  nvim_arch="linux-x86_64" ;;
        aarch64) nvim_arch="linux-arm64"  ;;
        *)       log_warn "neovim: unsupported arch $ARCH - skipping"; return ;;
    esac
    # Prebuilt binaries since v0.10.0 require glibc ≥ 2.32 (Ubuntu 22.04+).
    # On older systems keep/restore the legacy v0.9.5 binary instead.
    local glibc_ver
    glibc_ver=$(ldd --version 2>/dev/null | head -1 | grep -oE '[0-9]+\.[0-9]+$' || echo "0.0")
    if _ver_older_than "$glibc_ver" "2.32"; then
        log_warn "neovim: system glibc $glibc_ver < 2.32 - pinned to legacy v0.9.5"
        local nvim_dest
        if $CAN_APT; then nvim_dest=/usr/local/bin/nvim; else nvim_dest=$HOME/.local/bin/nvim; fi
        if $CHECK_ONLY; then
            local cur_leg; cur_leg=$(_cmd_version nvim --version) || cur_leg="none"
            log_info "  neovim: $cur_leg (legacy; cannot upgrade on glibc $glibc_ver)"
            return
        fi
        # Remove any shadow binary in ~/.local/bin that is broken (GLIBC mismatch)
        # and would mask a working /usr/local/bin/nvim.
        local shadow="$HOME/.local/bin/nvim"
        if [ -f "$shadow" ] && ! "$shadow" --version >/dev/null 2>&1; then
            rm -f "$shadow"
            log_info "neovim: removed incompatible shadow binary at $shadow"
        fi
        if "$nvim_dest" --version >/dev/null 2>&1; then
            local leg_v; leg_v=$("$nvim_dest" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
            log_ok "neovim $leg_v already installed (glibc-compatible) - skipping"
            return
        fi
        # Skip if never installed - update.sh updates existing tools, not installs new ones.
        if [ ! -e "$nvim_dest" ]; then
            log_info "neovim: not installed on this host - skipping (run install.sh workstation to install)"
            return
        fi
        # Binary exists but is broken (overwritten by a prior update run). Restore v0.9.5.
        if [ "$ARCH" != "x86_64" ]; then
            log_warn "neovim: legacy binary only available for x86_64 - skipping"
            return
        fi
        local leg_url="https://github.com/neovim/neovim/releases/download/v0.9.5/nvim-linux64.tar.gz"
        log_info "neovim: restoring v0.9.5 (glibc 2.17+ compatible)"
        local tmp; tmp=$(mktemp -d)
        # shellcheck disable=SC2064
        trap "rm -rf '$tmp'" RETURN
        if has curl; then curl -sfL "$leg_url" | tar -xz -C "$tmp" \
            || { log_warn "neovim: legacy download failed - skipping"; return; }
        else wget -qO- "$leg_url" | tar -xz -C "$tmp" \
            || { log_warn "neovim: legacy download failed - skipping"; return; }; fi
        local leg_extracted; leg_extracted=$(find "$tmp" -maxdepth 1 -type d -name 'nvim-*' | head -1)
        [ -z "$leg_extracted" ] && { log_warn "neovim: unexpected archive layout - skipping"; return; }
        if $CAN_APT; then $SUDO cp -r "$leg_extracted"/. /usr/local/; else cp -r "$leg_extracted"/. "$HOME/.local/"; fi
        log_ok "neovim restored → $("$nvim_dest" --version 2>/dev/null | head -1)"
        return
    fi

    local latest_tag="" nvim_url=""
    read -r latest_tag nvim_url < <(_gh_release_info "neovim/neovim" "nvim-${nvim_arch}.tar.gz") || true
    local latest="${latest_tag#v}"
    local current; current=$(_cmd_version nvim --version) || current=""
    if [ -z "$latest" ]; then
        log_warn "neovim: could not fetch release info - skipping"
        return
    fi
    if $CHECK_ONLY; then
        _report_version neovim "${current:-none}" "$latest_tag"
        if $CAN_APT; then
            log_info "  → update would install to /usr/local/"
        else
            log_info "  → update would install to ~/.local/"
        fi
        return
    fi
    if [ "$current" = "$latest" ]; then
        log_ok "neovim $latest_tag already up to date"
        return
    fi
    log_info "neovim: upgrading ${current:-none} → $latest"
    if [ -z "$nvim_url" ]; then
        log_warn "neovim: could not fetch download URL - skipping"
        return
    fi
    local tmp; tmp=$(mktemp -d)
    # shellcheck disable=SC2064
    trap "rm -rf '$tmp'" RETURN
    if has curl; then curl -sfL "$nvim_url" | tar -xz -C "$tmp" \
        || { log_warn "neovim: download/extraction failed - skipping"; return; }
    else wget -qO- "$nvim_url" | tar -xz -C "$tmp" \
        || { log_warn "neovim: download/extraction failed - skipping"; return; }; fi
    local extracted; extracted=$(find "$tmp" -maxdepth 1 -type d -name 'nvim-*' | head -1)
    if [ -z "$extracted" ]; then log_warn "neovim: unexpected archive layout - skipping"; return; fi
    local nvim_dest
    if $CAN_APT; then
        $SUDO cp -r "$extracted"/. /usr/local/
        nvim_dest=/usr/local/bin/nvim
    else
        cp -r "$extracted"/. "$HOME/.local/"
        nvim_dest=$HOME/.local/bin/nvim
    fi
    log_ok "neovim updated → $(nvim --version 2>/dev/null | head -1)"
    _verify_dest nvim "$nvim_dest"
}

# xcape is source-built (no versioned releases) - tmpdir must live in a
# function so `trap ... RETURN` fires correctly on function exit.
_do_update_xcape() {
    if has xcape; then
        if $CHECK_ONLY; then
            _check_git_updates "xcape" "" 2>/dev/null || true
            log_info "xcape: installed at $(command -v xcape) - source-built from alols/xcape (no version tags)"
            if $CAN_APT; then
                log_info "  → run './update.sh xcape' to rebuild from latest source"
            else
                log_warn "  → sudo + apt required to rebuild xcape"
            fi
        else
            if ! $CAN_APT; then
                log_warn "xcape: sudo + apt required to install build deps and binary - skipping"
            else
                log_info "xcape: rebuilding from source (alols/xcape)"
                apt_install libxtst-dev libx11-dev pkg-config make gcc
                local _xc_tmp; _xc_tmp=$(mktemp -d)
                # shellcheck disable=SC2064
                trap "rm -rf '$_xc_tmp'" RETURN
                if git clone --depth=1 https://github.com/alols/xcape.git "$_xc_tmp/xcape" 2>/dev/null \
                        && make -C "$_xc_tmp/xcape" 2>/dev/null; then
                    $SUDO install -m 755 "$_xc_tmp/xcape/xcape" /usr/local/bin/xcape
                    log_ok "xcape rebuilt → /usr/local/bin/xcape"
                else
                    log_warn "xcape: build failed - skipping"
                fi
            fi
        fi
    else
        log_warn "xcape not installed - run install.sh workstation first"
        log_warn "  Requires: sudo apt-get install -y libxtst-dev libx11-dev pkg-config make gcc"
    fi
}

# ── PATH shadow check ─────────────────────────────────────────────────────────
# Detect binaries at higher-priority PATH locations that shadow dotfiles-managed
# versions at /usr/local/bin. Runs always (read-only, no side effects).
#
# Only /usr/local/bin tools need this check - tools at ~/.local/bin are already
# at the highest dotfiles-managed PATH priority and cannot be shadowed by the
# installer itself.
_check_path_shadows() {
    log_step "PATH shadow check"

    # Collect PATH dirs that appear before /usr/local/bin.
    # These are the only locations that can shadow /usr/local/bin binaries.
    local -a _before=() _all_dirs=()
    local _dir _found_usr_local=false
    IFS=: read -ra _all_dirs <<< "${PATH:-}"
    for _dir in "${_all_dirs[@]}"; do
        if [ "$_dir" = "/usr/local/bin" ]; then
            _found_usr_local=true
            break
        fi
        _before+=("$_dir")
    done

    # If /usr/local/bin is not in PATH at all, the check is meaningless -
    # managed binaries there are unreachable regardless of shadows.
    if ! $_found_usr_local; then
        log_info "PATH shadow check: /usr/local/bin not in PATH - skipping (run from zsh after exec zsh)"
        return 0
    fi

    if [ ${#_before[@]} -eq 0 ]; then
        log_ok "/usr/local/bin is first in PATH - no shadow risk"
        return 0
    fi

    local _any_issue=false _any_checked=false _tool _canonical _shadow _cv _sv
    for _tool in nvim xcape; do
        _canonical="/usr/local/bin/$_tool"
        [ -x "$_canonical" ] || continue  # not installed at /usr/local/bin
        _any_checked=true

        _shadow=""
        for _dir in "${_before[@]}"; do
            [ -x "$_dir/$_tool" ] && _shadow="$_dir/$_tool" && break
        done

        [ -z "$_shadow" ] && continue  # no shadow for this tool - silent in clean case

        _cv=$(_cmd_version "$_canonical" --version) || _cv=""
        _sv=$(_cmd_version "$_shadow" --version) || _sv=""

        if [ -z "$_cv" ] || [ -z "$_sv" ]; then
            log_warn "$_tool: $_shadow shadows /usr/local/bin/$_tool (cannot read versions - inspect manually)"
            _any_issue=true
        elif _ver_older_than "$_sv" "$_cv"; then
            log_warn "$_tool: $_shadow ($_sv) shadows /usr/local/bin/$_tool ($_cv)"
            log_warn "  Fix: rm $_shadow"
            _any_issue=true
        elif [ "$_sv" = "$_cv" ]; then
            log_warn "$_tool: duplicate at $_shadow - same version as /usr/local/bin/$_tool"
            log_warn "  Consider: rm $_shadow"
            _any_issue=true
        else
            log_info "$_tool: $_shadow ($_sv) supersedes /usr/local/bin/$_tool ($_cv) - custom newer version"
        fi
    done

    if ! $_any_checked; then
        log_info "No tools installed at /usr/local/bin - shadow check not applicable"
    elif ! $_any_issue; then
        log_ok "No PATH shadows detected for /usr/local/bin tools"
    fi
}

# ── System packages ────────────────────────────────────────────────────────────
log_info "Checking sudo access..."
detect_sudo
case "$SUDO_STATUS" in
    root)              log_ok   "Running as root - system upgrades will run directly" ;;
    sudo_passwordless) log_ok   "sudo available - system upgrades will run via sudo" ;;
    sudo_password)
        log_ok   "sudo available - system upgrades will run via sudo"
        log_warn "sudo requires a password - you will be prompted when it is used" ;;
    nosudo)            log_warn "No sudo - system package upgrade skipped" ;;
esac
if _should_run apt; then
    log_step "System packages (apt)"
    if $CAN_APT; then
        if $CHECK_ONLY; then
            apt list --upgradable 2>/dev/null | grep -v '^Listing' || true
            log_info "  → sudo required to apply these updates"
        else
            $SUDO apt-get -yq update
            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get -yq upgrade
            log_ok "System packages updated"
        fi
    elif $CAN_SUDO; then
        log_warn "No apt on this system - skipping (upgrade via your native package manager)"
    else
        log_warn "No sudo - skipping apt upgrade"
    fi
fi

# ── oh-my-zsh ──────────────────────────────────────────────────────────────────
if _should_run omz; then
    log_step "oh-my-zsh"
    if [ -d ~/.oh-my-zsh ]; then
        if $CHECK_ONLY; then
            _check_git_updates "oh-my-zsh" ~/.oh-my-zsh
        else
            if zsh -c 'source ~/.oh-my-zsh/oh-my-zsh.sh; omz update --unattended' 2>/dev/null; then
                log_ok "oh-my-zsh updated"
            elif git -C ~/.oh-my-zsh pull --quiet; then
                log_ok "oh-my-zsh updated (via git pull)"
            else
                log_warn "oh-my-zsh: update failed (both omz and git pull) - skipping"
            fi
        fi
    else
        log_warn "oh-my-zsh not installed - skipping"
    fi
fi

# ── tmux plugins ───────────────────────────────────────────────────────────────
if _should_run tmux-plugins; then
    log_step "tmux plugins"
    for _tmux_plugin in tmux-resurrect tmux-continuum tmux-fzf tmux-cpu; do
        if $CHECK_ONLY; then
            _check_git_updates "$_tmux_plugin" "$HOME/.tmux/plugins/$_tmux_plugin"
        else
            _update_plugin "$_tmux_plugin" "$HOME/.tmux/plugins/$_tmux_plugin"
        fi
    done
fi

# ── zsh plugins ────────────────────────────────────────────────────────────────
if _should_run zsh-plugins; then
    log_step "zsh plugins"
    if $CHECK_ONLY; then
        _check_git_updates "powerlevel10k"            "$ZSH_CUSTOM/themes/powerlevel10k"
        _check_git_updates "zsh-autosuggestions"      "$ZSH_CUSTOM/plugins/zsh-autosuggestions"
        _check_git_updates "fast-syntax-highlighting" "$ZSH_CUSTOM/plugins/fast-syntax-highlighting"
        _check_git_updates "fzf-tab"                  "$ZSH_CUSTOM/plugins/fzf-tab"
    else
        _update_plugin "powerlevel10k"            "$ZSH_CUSTOM/themes/powerlevel10k"            "https://github.com/romkatv/powerlevel10k"
        _update_plugin "zsh-autosuggestions"      "$ZSH_CUSTOM/plugins/zsh-autosuggestions"     "https://github.com/zsh-users/zsh-autosuggestions"
        _update_plugin "fast-syntax-highlighting" "$ZSH_CUSTOM/plugins/fast-syntax-highlighting" "https://github.com/zdharma-continuum/fast-syntax-highlighting"
        _update_plugin "fzf-tab"                  "$ZSH_CUSTOM/plugins/fzf-tab"                 "https://github.com/Aloxaf/fzf-tab"
    fi
fi

# ── fzf ────────────────────────────────────────────────────────────────────────
# Installed via git clone (~/.fzf) - update by pulling the repo.
# Shell integration lives in ~/.fzf.zsh (generated by ~/.fzf/install at
# install time) and is sourced by .zshrc.
if _should_run fzf; then
    log_step "fzf"
    if [ -d ~/.fzf/.git ]; then
        if $CHECK_ONLY; then
            _check_git_updates "fzf" ~/.fzf
        else
            if git -C ~/.fzf pull --quiet --rebase; then
                ver=$(_cmd_version ~/.fzf/bin/fzf --version) || ver="?"
                log_ok "fzf updated → ~/.fzf ($ver)"
            else
                log_warn "fzf: git pull failed - skipping"
            fi
            # Self-heal the symlink in case an older dotfiles version (where
            # _install_fzf returned early when ~/.fzf existed) left it missing.
            mkdir -p ~/.local/bin
            ln -sf ~/.fzf/bin/fzf ~/.local/bin/fzf
            # Self-heal ~/.fzf.zsh too. Without it, .zshrc's
            # `[[ -f ~/.fzf.zsh ]] && source ~/.fzf.zsh` silently no-ops and
            # Ctrl+R is not bound to fzf history search.
            if [ ! -f ~/.fzf.zsh ]; then
                log_info "fzf: ~/.fzf.zsh missing - regenerating"
                ~/.fzf/install --no-update-rc --key-bindings --completion >/dev/null
            fi
        fi
    elif has fzf; then
        log_warn "fzf: not managed as a git clone at ~/.fzf - skipping (update manually)"
    else
        log_warn "fzf not installed - skipping"
    fi
fi

# ── ripgrep ────────────────────────────────────────────────────────────────────
_update_std_tool rg "ripgrep" "BurntSushi/ripgrep" gnu

# ── fd ─────────────────────────────────────────────────────────────────────────
# Special case: fd may be installed as fdfind (Debian/Ubuntu); always put the
# updated binary at ~/.local/bin/fd regardless of where the current one lives.
if _should_run fd; then
    log_step "fd"
    if has fd || has fdfind; then
        case "$ARCH" in
            x86_64)  _gh_update_binary fd "sharkdp/fd" "x86_64-unknown-linux-musl.tar.gz" fd ~/.local/bin/fd || true ;;
            aarch64) _gh_update_binary fd "sharkdp/fd" "aarch64-unknown-linux-gnu.tar.gz"  fd ~/.local/bin/fd || true ;;
            *)       log_warn "fd: unsupported arch $ARCH - skipping" ;;
        esac
    else
        log_warn "fd not installed - skipping"
    fi
fi

# ── shellcheck ─────────────────────────────────────────────────────────────────
# Uses bare arch names (x86_64/aarch64), not Rust triples - keep its own section.
if _should_run shellcheck; then
    log_step "shellcheck"
    if has shellcheck; then
        sc_arch=""
        case "$ARCH" in
            x86_64)  sc_arch="x86_64"  ;;
            aarch64) sc_arch="aarch64" ;;
            *)       log_warn "shellcheck: unsupported arch $ARCH - skipping" ;;
        esac
        if [ -n "$sc_arch" ]; then
            dest=$(_resolve_dest shellcheck ~/.local/bin/shellcheck)
            _gh_update_binary shellcheck "koalaman/shellcheck" \
                "linux.${sc_arch}.tar.xz" shellcheck "$dest" || true
        fi
    else
        log_warn "shellcheck not installed - skipping"
    fi
fi

# ── zoxide ──────────────────────────────────────────────────────────────────────────────
_update_std_tool zoxide "zoxide" "ajeetdsouza/zoxide" musl

# ── delta ───────────────────────────────────────────────────────────────────────────────
_update_std_tool delta "delta" "dandavison/delta" gnu

# ── eza ────────────────────────────────────────────────────────────────────────────────
# Asset pattern has an eza_ prefix before the arch triple.
_update_std_tool eza "eza" "eza-community/eza" musl eza "eza_"

# ── yazi ───────────────────────────────────────────────────────────────────────
# Custom: ships a .zip (not a tarball) containing two binaries - yazi + ya.
if _should_run yazi; then
    log_step "yazi"
    # Recognize a managed ~/.local/bin install even when that dir is not on PATH
    # (update.sh does not prepend it), mirroring how the cheat block gates on a
    # file test. `has yazi` still covers a yazi found elsewhere on PATH (e.g. cargo).
    if has yazi || [ -x "$HOME/.local/bin/yazi" ]; then
        case "$ARCH" in
            x86_64)  yazi_arch="x86_64-unknown-linux-musl"  ;;
            aarch64) yazi_arch="aarch64-unknown-linux-musl" ;;
            *)       yazi_arch="" ;;
        esac
        if [ -z "$yazi_arch" ]; then
            log_warn "yazi: unsupported arch $ARCH - skipping"
        elif $CHECK_ONLY; then
            current=$(_cmd_version yazi --version) || current=""
            latest=$(_gh_latest_tag_noapi "sxyazi/yazi") || latest=""
            _report_version yazi "$current" "${latest:-unknown}"
        else
            # Stable asset name -> use latest/download direct URL (no API call).
            yazi_url="https://github.com/sxyazi/yazi/releases/latest/download/yazi-${yazi_arch}.zip"
            yazi_dest=$(_resolve_dest yazi ~/.local/bin/yazi)
            ya_dest=$(_resolve_dest ya ~/.local/bin/ya)
            yazi_tmp=$(mktemp -d)
            _yazi_ok=true
            if has curl; then curl -sfL "$yazi_url" -o "$yazi_tmp/yazi.zip" || _yazi_ok=false
            else wget -qO "$yazi_tmp/yazi.zip" "$yazi_url" || _yazi_ok=false; fi
            if $_yazi_ok; then
                if has unzip; then unzip -qo "$yazi_tmp/yazi.zip" -d "$yazi_tmp" || _yazi_ok=false
                elif has python3; then python3 -m zipfile -e "$yazi_tmp/yazi.zip" "$yazi_tmp" || _yazi_ok=false
                else log_warn "yazi: no unzip or python3 to extract - skipping"; _yazi_ok=false; fi
            fi
            if $_yazi_ok; then
                yazi_found=$(find "$yazi_tmp" -name yazi -type f | head -1)
                [ -n "$yazi_found" ] && mv "$yazi_found" "$yazi_dest" && chmod +x "$yazi_dest"
                ya_found=$(find "$yazi_tmp" -name ya -type f | head -1)
                [ -n "$ya_found" ] && mv "$ya_found" "$ya_dest" && chmod +x "$ya_dest"
                log_ok "yazi updated → $yazi_dest ($(_cmd_version "$yazi_dest" --version || echo '?'))"
                _verify_dest yazi "$yazi_dest"
            else
                log_warn "yazi: download/extraction failed - skipping"
            fi
            rm -rf "$yazi_tmp"
        fi
    else
        log_warn "yazi not installed - run install.sh first"
    fi
fi

# ── uv ───────────────────────────────────────────────────────────────────────────
# Custom: installs two binaries (uv + uvx) from a single tarball.
if _should_run uv; then
    log_step "uv"
    if has uv; then
        _do_update_uv
    else
        log_warn "uv not installed - skipping (run install.sh workstation first)"
    fi
fi

# ── ruff ───────────────────────────────────────────────────────────────────────
if _should_run ruff; then
    log_step "ruff"
    if has uv && uv tool list 2>/dev/null | grep -q '^ruff '; then
        if $CHECK_ONLY; then
            log_info "ruff: installed=$(ruff --version 2>/dev/null)  (latest: pypi.org/project/ruff)"
        else
            uv tool upgrade ruff --quiet
            log_ok "ruff updated ($(ruff --version 2>/dev/null))"
        fi
    elif has ruff; then
        log_warn "ruff: not managed by uv tool - skipping (update manually)"
    else
        log_warn "ruff not installed - skipping"
    fi
fi

# ── neovim ────────────────────────────────────────────────────────────────────────────
# Custom: extracts a directory tree, single API call, skips when already current.
if _should_run neovim; then
    log_step "neovim"
    _do_update_neovim
fi

# ── cheat ──────────────────────────────────────────────────────────────────────
# Custom: single compressed binary (gunzip, not tarball).
if _should_run cheat; then
    log_step "cheat"
    if [ -f ~/.local/bin/cheat ]; then
        if $CHECK_ONLY; then
            current=$(_cmd_version ~/.local/bin/cheat --version) || current=""
            latest=$(_gh_latest_tag "cheat/cheat") || latest=""
            _report_version cheat "$current" "${latest:-unknown}"
        else
            case "$ARCH" in
                x86_64)  cheat_arch="amd64" ;;
                aarch64) cheat_arch="arm64" ;;
                *)       cheat_arch=""      ;;
            esac
            if [ -z "$cheat_arch" ]; then
                log_warn "cheat: unsupported arch $ARCH - skipping"
            else
                url=$(_gh_latest_release "cheat/cheat" "linux-${cheat_arch}.gz") || url=""
                if [ -n "$url" ]; then
                    _cheat_ok=true
                    if has curl; then curl -sfL "$url" | gunzip > ~/.local/bin/cheat || _cheat_ok=false
                    else wget -qO- "$url" | gunzip > ~/.local/bin/cheat || _cheat_ok=false; fi
                    if $_cheat_ok; then
                        chmod +x ~/.local/bin/cheat
                        log_ok "cheat updated"
                        _verify_dest cheat ~/.local/bin/cheat
                    else
                        log_warn "cheat: download/decompression failed - skipping"
                        rm -f ~/.local/bin/cheat
                    fi
                else
                    log_warn "cheat: could not fetch release URL - skipping"
                fi
            fi
        fi
    else
        log_warn "cheat not installed - run install.sh workstation first"
    fi
fi

# ── xcape ──────────────────────────────────────────────────────────────────────
# Source-built from https://github.com/alols/xcape (no versioned releases).
# Deps: libxtst-dev libx11-dev pkg-config make gcc
if _should_run xcape; then
    log_step "xcape"
    _do_update_xcape
fi

# ── pre-commit common repo ─────────────────────────────────────────────────────
if _should_run pre-commit; then
    log_step "pre-commit (common repo)"
    PRECOMMIT_REPO="${PRECOMMIT_REPO:-$HOME/projects/common/pre-commit}"
    if [ -d "$PRECOMMIT_REPO/.git" ]; then
        if $CHECK_ONLY; then
            _check_git_updates "pre-commit" "$PRECOMMIT_REPO"
        else
            if git -C "$PRECOMMIT_REPO" pull --quiet --rebase; then
                log_ok "pre-commit repo updated ($PRECOMMIT_REPO)"
                log_info "  Note: re-run pre-commit/install.sh in each project to upgrade the tool version"
            else
                log_warn "pre-commit repo pull failed - skipping (local changes or network issue?)"
            fi
        fi
    else
        log_warn "pre-commit repo not found at $PRECOMMIT_REPO - skipping"
        log_warn "  To override: PRECOMMIT_REPO=/your/path ./update.sh"
    fi
fi

# ── PATH shadow check (always runs - read-only) ───────────────────────────────
_check_path_shadows

echo ""
if $CHECK_ONLY; then
    log_ok "Check complete"
else
    log_ok "Update complete - restart your shell to apply changes"
fi
echo ""