jc

#!/usr/bin/env bash
# shellcheck disable=SC2155 disable=SC2120 disable=SC2024 disable=SC2034
# set -x

# Constants
SCRIPT_NAME=$(basename $0)
# Tracking directories
fMainDir=$(cd "$(dirname "$(readlink -f "$0")")" || exit; pwd)
fTKFilesDir=$fMainDir/track-files
fTKCompDir=$fMainDir/completion
fTKVimColorsDir=$fMainDir/assets/vim-colors
fTKBatThemeDir=$fMainDir/assets/bat-themes
fTKFontDir=$fMainDir/assets/fonts
fTKFontConfigDir=$fMainDir/assets/fontconfig
fTKClangdConfig=$fMainDir/assets/clangd/config.yaml
fTKtemplateDir=$fMainDir/template
fTKToolsDir=$fMainDir/nv-tools
fDownloads=$HOME/Downloads
fJCPath=$fMainDir/$SCRIPT_NAME
fFirstTimeFile=$fMainDir/".has_been_invoked"
# Cursor
fTKCursorDir=$fMainDir/assets/cursor
fTKCursorLocalSettings=$fTKCursorDir/local.settings.json
fTKCursorKeybindings=$fTKCursorDir/keybindings.json
fTKCursorRemoteSettings=$fTKCursorDir/remote.settings.json
# Claude
fTKClaudeDir=$fMainDir/assets/claude
fTKClaudeCodeSettings=$fTKClaudeDir/settings.json
fTKClaudeCodeLocalSettings=$fTKClaudeDir/settings.local.json
fTKClaudeCodeMd=$fTKClaudeDir/CLAUDE.md
fTKClaudeDesktopConfig=$fTKClaudeDir/claude_desktop_config.json
fTKClaudeMcpJson=$fTKClaudeDir/.mcp.json
# Codex
fTKCodexDir=$fMainDir/assets/codex
fTKCodexConfig=$fTKCodexDir/config.toml
# Misc
fVimPlugsManagerPath=$HOME/.vim/autoload/plug.vim
fzfBinPath=$HOME/.vim/bundle/fzf/bin/fzf
fzfTabCompPath=$HOME/.vim/bundle/fzf-tab-completion/bash/fzf-bash-completion.sh # A fzf plugin: fzf-tab-completion
fBackupDir="$HOME/Public/env.bak"
fOSCategory=debian # ubuntu/debian is the default OS type
fArch=
fNoInstallTools=
fCheckTlsConn=
fCursorAction=
fClaudeAction=
fClaudeDesktopAction=
fClaudeLinkMcpJson=
fCodexAction=
# VNC server
fVncAbbrePort=9
fVncFullPort="590${fVncAbbrePort}"
fVncResolution=2060x1080
fVncServer= # 1: start VNC server; 2: kill VNC server 3: restart VNC server
fVncLockAction=
# Display Mode | gdm: start gdm3 (graphical), text: stop gdm3 (text mode)
fDisplayMode=
fLinkClangFormatPath= # Link clang-format to this path
# Update Options
appInstallUpdate= # 1: install apps and continue; 2: install apps and exit
fNVMUpdate=
fGitLfsUpdate=
fClangdUpdate=
fDockerUpdate=
fWiresharkUpdate=
fFirefoxUpdate=
fChinesePinyinUpdate=
fXrayUpdate=
fXrayRemove=
fXrayPort=
fXrayServer=
fWireguardUpdate=
fWireguardRemove=
fWireguardPort=
fWireguardServer=
fWireguardClientName=
fSwapReq=
# RTSP Stream Playback
fRtspFlag=
fRtspMulti=
fRtspKill=
fRtspList=
fRtspFilter=
fRtspSrvIp=192.168.10.240
fRtspStream=
MAX_RTSP_STREAMS=10
fRtspScreenRes=   # Exp: 4k Mi Monitor resolution 3360 x 1890
fSambaServerFlag= # 1: Start samba server 2: Start samba server and reset password
# Camera ACL (OpenWrt firewall rules Block_C700_NN)
fGwHost="root@192.168.10.1"
fGwPort=8822
fGwAclAction=""    # block | unblock | status
fGwAclTarget=""    # c700_01 | c700_02 | all
# SSH Tunnel (autossh port forward over VPN)
# Remote host: the real server autossh connects to. Not derivable from the
# sing-box config because sing-box only sees 127.0.0.1 in xray-tunnel mode.
fSshTunnelRemoteIp=10.6.10.221
# Ports are populated from .outbounds[proxy].server_port when xray-tunnel
# mode is detected in launchSingbox; unused in other modes.
fSshTunnelRemotePort=""
fSshTunnelLocalPort=""
fSshTunnelAutosshPid=""
# Singbox (sing-box proxy)
fSingbox=
fSingboxConfig="$HOME/Documents/sing-box-config.jsonc"
fSingboxLink=""           # xray | wireguard — which config to symlink
fSingboxProxyMode=""      # wireguard | xray-direct | xray-tunnel
fSingboxRetryTimeout=180  # seconds to retry after VPN/tunnel drop
fSingboxMonitorPid=""
fSingboxCleaning=0
fSingboxRecoveryMarker=""
# Colors
RED='\033[31m'
GREEN='\033[32m'
MAGENTA='\033[35m'
LIGHTYELLOW='\033[93m'
BOLD='\033[1m'
NORMAL='\033[0m'
BLUE='\033[34m'
GREY='\033[90m'
CYAN='\033[36m'
RESET='\033[0m'
COLOR=$MAGENTA

# On macOS, always initialize Homebrew environment
if [[ $(uname -s) == 'Darwin' ]]; then
    [ -x /opt/homebrew/bin/brew ] && eval "$(/opt/homebrew/bin/brew shellenv)"
    [ -x /usr/local/bin/brew ] && eval "$(/usr/local/bin/brew shellenv)"
fi

usage() {
    cat << _EOF
Usage: $SCRIPT_NAME [OPTIONS]

Set up coding environment, manage VNC/Samba servers, and play RTSP camera streams.

Common Options:
    -h, --help                      Print this help message
    -n, --no-tools                  Don't install tools
    -d, --debug                     Enable debug mode
    --check-tls                     Check TLS connection
    --link-clang-format             Link clang-format to current path
    --auto-remove                   Remove unused packages
    --update                        Update all packages
    --upgrade                       Upgrade all packages

Update Options (installed by default on first run):
    --nvm                           Update NVM
    --git-lfs                       Update Git LFS from PackageCloud
    --apps                          Update Apps
    --chinese-pinyin                Update Rime Pinyin
    --docker                        Update Docker from Docker PPA
    --wireshark                     Update Wireshark from Wireshark PPA
    --firefox                       Update Firefox from Mozilla PPA
    --clangd                        Update Clangd from Github

Cursor Options:
    --cursor-backup                 Back up Cursor local, remote, and keybinding JSON files
    --cursor-restore                Restore Cursor local, remote, and keybinding JSON files

Samba Options:
    --samba                         Install and configure Samba Server
    --samba-reset-password          Reset Samba Server password

Swap Options:
    --swap                          Add swap file (default 8G)

Vnc Server Options:
    --vnc,--vnc-start               Start VNC server
    --vnc-stop                      Stop VNC server
    --vnc-restart                   Restart VNC server

Display Mode Options:
    --gdm                           Switch to graphical mode (start gdm3)
    --text                          Switch to text mode (stop gdm3)

Vnc Lock Options:
    --vnclock                       Effect options: [unlock|lock|status]
    --unlock-vnc                    Unlock VNC, equivalent to --vnclock unlock
    --lock-vnc                      Lock VNC, equivalent to --vnclock lock

RTSP Options:
    --rtsp                          Play RTSP stream with mpv (low-latency)
    --rtsp-all                      Play multiple RTSP streams in tiled layout
    --rtsp-kill                     Kill all running mpv instances
    --rtsp-list                     List all available streams from go2rtc
    --rtsp-raw                      Play all *_raw streams in tiled layout
    --rtsp-h264                     Play all *_h264 streams in tiled layout
    --rtsp-stream <stream>          Specify stream name (default: first from go2rtc)
    --rtsp-ip <ip>                  Specify RTSP server IP (default: ${fRtspSrvIp})
    --rtsp-resolution <WxH>         Set screen resolution for tiling (e.g. 3360x1890)

Camera ACL Options (controls Block_C700_NN rules on OpenWrt router):
    --acl-block   <c700_01|c700_02|all>  Enable block rule(s) — camera(s) offline
    --acl-unblock <c700_01|c700_02|all>  Disable block rule(s) — camera(s) online
    --acl-status  <c700_01|c700_02|all>  Show current rule state

Singbox Options:
    --singbox                       Launch sing-box proxy (auto-detects xray or WireGuard)
    --singbox-xray                  Link xray sing-box config to ~/Documents
    --singbox-wg                    Link WireGuard sing-box config to ~/Documents

Xray Options (server-side only — run on the Xray server host):
    --xray                          Install or update Xray from Github
    --xray-port <port>              Set Xray listen port (default: 443)
    --xray-server <ip>              Set server IP in share URL (auto-detected if omitted)
    --xray-remove                   Remove Xray from system

WireGuard Options (server-side only — run on the WireGuard server host):
    --wg                            Install/configure WireGuard VPN server
    --wg-port <port>                Set WireGuard listen port (default: 51820)
    --wg-server <ip>                Set server IP in client config (auto-detected if omitted)
    --wg-client <name>              Set client config name (default: client1)
    --wg-remove                     Remove WireGuard from system

Claude Options:
    --claude                        Install or upgrade Claude Code (CLI)
    --claude-remove                 Remove Claude Code
    --claude-backup                 Back up Claude Code CLI settings
                                    (settings.json, settings.local.json, CLAUDE.md)
    --claude-restore                Restore Claude Code CLI settings
    --claude-link-mcp               Symlink tracked .mcp.json into current directory
    --claude-desktop-backup         Back up macOS Claude Desktop config
                                    (claude_desktop_config.json)
    --claude-desktop-restore        Restore macOS Claude Desktop config

Codex Options:
    --codex                         Install or upgrade Codex (CLI)
    --codex-remove                  Remove Codex
    --codex-backup                  Back up Codex CLI settings
                                    (config.toml)
    --codex-restore                 Restore Codex CLI settings

Gemini Options:
    --gemini                        Install or upgrade Gemini (CLI)
    --gemini-remove                 Remove Gemini CLI

Examples:
    $SCRIPT_NAME -h
    $SCRIPT_NAME --link-clang-format \$HOME/crosslv

_EOF
exit 0
}

# Detect and use GNU getopt if available (required for long options on macOS)
GETOPT_BIN="getopt"
if command -v /opt/homebrew/opt/gnu-getopt/bin/getopt &> /dev/null; then
    GETOPT_BIN="/opt/homebrew/opt/gnu-getopt/bin/getopt"
elif command -v /usr/local/opt/gnu-getopt/bin/getopt &> /dev/null; then
    GETOPT_BIN="/usr/local/opt/gnu-getopt/bin/getopt"
fi

SHORTOPTS="hdnf"
# Two colons: The option takes an optional argument
LONGOPTS="help,debug,no-tools,clangd,docker,link-clang-format::,auto-remove,nvm\
          upgrade,chinese-pinyin,apps,apps-only,vnc-restart,vnc-stop,unlock-vnc,vnclock:,\
          lock-vnc,vnc-start,vnc,firefox,update,samba,samba-reset-password,wireshark,\
          git-lfs,rtsp,rtsp-all,rtsp-kill,rtsp-list,rtsp-raw,rtsp-h264,rtsp-stream:,\
          rtsp-ip:,rtsp-resolution:,check-tls::,swap::,gdm,text,claude,claude-remove,\
          claude-backup,claude-restore,claude-desktop-backup,claude-desktop-restore,claude-link-mcp,\
          codex,codex-remove,codex-backup,codex-restore,\
          gemini,gemini-remove,cursor-backup,cursor-restore,\
          singbox,singbox-xray,singbox-wg,\
          xray,xray-port:,xray-server:,xray-remove,wg,wg-port:,wg-server:,wg-client:,wg-remove,\
          acl-block:,acl-unblock:,acl-status:"

# Use getopt to parse command-line options
if ! PARSED=$("$GETOPT_BIN" --options $SHORTOPTS --longoptions "$LONGOPTS" --name "$0" -- "$@"); then
    echo -e "${COLOR}Error: Failed to parse command-line options.${RESET}" >&2
    echo -e "${CYAN}Tip: On macOS, install GNU getopt: ${GREY}brew install gnu-getopt${RESET}" >&2
    exit 1
fi

# Reset positional parameters to the parsed values
eval set -- "$PARSED"

checkNodeEnv() {
    local nvmSh="$HOME/.nvm/nvm.sh"
    if [ ! -s "$nvmSh" ]; then
        echo -e "${LIGHTYELLOW}NVM not found. Installing NVM and Node.js first...${RESET}"
        local nvmVersion="v0.40.3"
        if ! curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/"$nvmVersion"/install.sh | bash; then
            echo -e "${RED}Error: Failed to install NVM.${RESET}"
            return 1
        fi
    fi

    if [ -s "$nvmSh" ]; then
        export NVM_DIR="$HOME/.nvm"
        # shellcheck source=/dev/null
        source "$nvmSh"
    else
        echo -e "${RED}Error: nvm.sh not found.${RESET}"
        return 1
    fi

    if ! command -v node &>/dev/null; then
        echo -e "${LIGHTYELLOW}Node.js not found. Installing latest LTS via NVM...${RESET}"
        nvm install --lts
        nvm alias default lts/*
    fi
}

installClaude() {
    local bin ver

    echo -e "${BOLD}${COLOR}Installing Claude Code${RESET}"

    # Use npm on every OS. Homebrew's claude-code cask is auto-bumped from
    # the GCS bucket and routinely lags npm by 10+ patch releases, so even
    # macOS users get fresher binaries from the npm package (which ships
    # native binaries per platform via optionalDependencies).
    checkNodeEnv || return 1
    echo -e "  ${LIGHTYELLOW}Installing ${BLUE}@anthropic-ai/claude-code${RESET}${GREY}...${RESET}"
    npm install -g @anthropic-ai/claude-code @anthropic-ai/sandbox-runtime || {
        echo -e "  ${RED}Error: npm install failed.${RESET}" >&2
        return 1
    }
    hash -r

    ver=$(claude -v 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
    bin=$(command -v claude 2>/dev/null || echo 'not found')
    bin=${bin/#$HOME/\~}

    echo -e "${GREEN}✔ Installed${RESET} ${GREY}v${ver:-unknown}${RESET}"
    echo -e "${GREEN}✔${RESET} ${GREY}Binary${RESET}: ${CYAN}${bin}${RESET}"
    echo -e "${GREEN}✔${RESET} ${GREY}Config${RESET}: ${CYAN}~/.claude${RESET}"
}

installCodex() {
    local bin ver

    echo -e "${BOLD}${COLOR}Installing Codex${RESET}"

    # See installClaude — npm is the canonical, most up-to-date channel
    # on every OS.
    checkNodeEnv || return 1
    echo -e "  ${LIGHTYELLOW}Installing ${BLUE}@openai/codex${RESET}${GREY}...${RESET}"
    npm install -g @openai/codex || {
        echo -e "  ${RED}Error: npm install failed.${RESET}" >&2
        return 1
    }
    hash -r

    ver=$(codex --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
    bin=$(command -v codex 2>/dev/null || echo 'not found')
    bin=${bin/#$HOME/\~}

    echo -e "${GREEN}✔ Installed${RESET} ${GREY}v${ver:-unknown}${RESET}"
    echo -e "${GREEN}✔${RESET} ${GREY}Binary${RESET}: ${CYAN}${bin}${RESET}"
    echo -e "${GREEN}✔${RESET} ${GREY}Config${RESET}: ${CYAN}~/.codex${RESET}"
}

removeClaude() {
    echo -e "${BOLD}${COLOR}Removing Claude Code${RESET}"

    if [ -s "$HOME/.nvm/nvm.sh" ]; then
        export NVM_DIR="$HOME/.nvm"
        # shellcheck source=/dev/null
        source "$NVM_DIR/nvm.sh"
    fi
    local removed=false
    local pkg
    for pkg in @anthropic-ai/claude-code @anthropic-ai/sandbox-runtime; do
        if command -v npm &>/dev/null && npm list -g "$pkg" &>/dev/null; then
            echo -e "  ${LIGHTYELLOW}Removing ${BLUE}${pkg}${RESET}${GREY}...${RESET}"
            npm uninstall -g "$pkg"
            removed=true
        fi
    done

    # Clean up legacy macOS Homebrew installs from earlier versions of jc.
    if [[ $(uname -s) == 'Darwin' ]] && command -v brew &>/dev/null \
        && brew list --cask claude-code &>/dev/null; then
        echo -e "  ${LIGHTYELLOW}Removing legacy ${BLUE}claude-code${RESET} ${GREY}cask...${RESET}"
        brew uninstall --cask claude-code
        removed=true
    fi

    if ! $removed; then
        echo -e "  ${GREY}Claude Code is not installed.${RESET}"
        return 0
    fi

    echo -e "${GREEN}✔${GREY} Claude Code removed.${RESET}"
}

removeCodex() {
    echo -e "${BOLD}${COLOR}Removing Codex${RESET}"

    if [ -s "$HOME/.nvm/nvm.sh" ]; then
        export NVM_DIR="$HOME/.nvm"
        # shellcheck source=/dev/null
        source "$NVM_DIR/nvm.sh"
    fi
    local removed=false
    if command -v npm &>/dev/null && npm list -g @openai/codex &>/dev/null; then
        echo -e "  ${LIGHTYELLOW}Removing ${BLUE}@openai/codex${RESET}${GREY}...${RESET}"
        npm uninstall -g @openai/codex
        removed=true
    fi

    # Clean up legacy macOS Homebrew installs from earlier versions of jc.
    if [[ $(uname -s) == 'Darwin' ]] && command -v brew &>/dev/null \
        && brew list --cask codex &>/dev/null; then
        echo -e "  ${LIGHTYELLOW}Removing legacy ${BLUE}codex${RESET} ${GREY}cask...${RESET}"
        brew uninstall --cask codex
        removed=true
    fi

    if ! $removed; then
        echo -e "  ${GREY}Codex is not installed.${RESET}"
        return 0
    fi

    echo -e "${GREEN}✔${GREY} Codex removed.${RESET}"
}

installGemini() {
    local bin ver

    echo -e "${BOLD}${COLOR}Installing Gemini CLI${RESET}"

    # Same npm channel as claude/codex — Google ships gemini-cli only via
    # @google/gemini-cli on npm; no Homebrew or system package today.
    checkNodeEnv || return 1
    echo -e "  ${LIGHTYELLOW}Installing ${BLUE}@google/gemini-cli${RESET}${GREY}...${RESET}"
    npm install -g @google/gemini-cli || {
        echo -e "  ${RED}Error: npm install failed.${RESET}" >&2
        return 1
    }
    hash -r

    ver=$(gemini --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
    bin=$(command -v gemini 2>/dev/null || echo 'not found')
    bin=${bin/#$HOME/\~}

    echo -e "${GREEN}✔ Installed${RESET} ${GREY}v${ver:-unknown}${RESET}"
    echo -e "${GREEN}✔${RESET} ${GREY}Binary${RESET}: ${CYAN}${bin}${RESET}"
    echo -e "${GREEN}✔${RESET} ${GREY}Config${RESET}: ${CYAN}~/.gemini${RESET}"
}

removeGemini() {
    echo -e "${BOLD}${COLOR}Removing Gemini CLI${RESET}"

    if [ -s "$HOME/.nvm/nvm.sh" ]; then
        export NVM_DIR="$HOME/.nvm"
        # shellcheck source=/dev/null
        source "$NVM_DIR/nvm.sh"
    fi
    local removed=false
    if command -v npm &>/dev/null && npm list -g @google/gemini-cli &>/dev/null; then
        echo -e "  ${LIGHTYELLOW}Removing ${BLUE}@google/gemini-cli${RESET}${GREY}...${RESET}"
        npm uninstall -g @google/gemini-cli
        removed=true
    fi

    if ! $removed; then
        echo -e "  ${GREY}Gemini CLI is not installed.${RESET}"
        return 0
    fi

    echo -e "${GREEN}✔${GREY} Gemini CLI removed.${RESET}"
}

gwAclControl() {
    local action="$1" target="$2"
    local rules="" desired=""

    case "$target" in
        c700_01) rules="Block_C700_01" ;;
        c700_02) rules="Block_C700_02" ;;
        all)     rules="Block_C700_01 Block_C700_02" ;;
        *)
            echo -e "${RED}Error: Invalid target '$target'. Valid: c700_01, c700_02, all${RESET}" >&2
            return 2
            ;;
    esac

    case "$action" in
        block)   desired="1" ;;
        unblock) desired="0" ;;
        status)  desired="" ;;
    esac

    local rc=0 remote_env
    printf -v remote_env "DESIRED='%s' RULES='%s' sh -s" "$desired" "$rules"
    ssh -p "$fGwPort" -o ConnectTimeout=5 -o BatchMode=yes \
        "$fGwHost" "$remote_env" <<'REMOTE' || rc=$?
set -e
missing=0
changed=0
for n in $RULES; do
    sec=$(uci show firewall | awk -F'[.=]' -v n="$n" '
        tolower($0) ~ "\\.name=\x27" tolower(n) "\x27" { print $2; exit }
    ')
    if [ -z "$sec" ]; then
        echo "ERROR: firewall rule $n not found" >&2
        missing=1
        continue
    fi
    cur=$(uci -q get firewall.$sec.enabled); [ -z "$cur" ] && cur=1
    if [ -z "$DESIRED" ]; then
        echo "$n: enabled=$cur (section=$sec)"
        continue
    fi
    if [ "$cur" != "$DESIRED" ]; then
        uci set firewall.$sec.enabled="$DESIRED"; changed=1
        echo "$n: $cur -> $DESIRED"
    else
        echo "$n: already $DESIRED"
    fi
done
if [ "$missing" = 1 ]; then
    echo "ERROR: one or more rules not found; aborting without commit" >&2
    exit 3
fi
if [ "$changed" = 1 ]; then
    uci commit firewall
    /etc/init.d/firewall reload >/dev/null 2>&1
    echo "firewall reloaded"
fi
REMOTE

    if [ "$rc" -eq 3 ]; then
        echo -e "${LIGHTYELLOW}Hint: verify rule names with:${RESET}"
        echo -e "  ssh -p $fGwPort $fGwHost \"uci show firewall | grep -i '\\.name='\"" >&2
    fi
    return "$rc"
}

while true; do
    case "$1" in
        -n|--no-tools)
            fNoInstallTools=true
            shift
            ;;
        --apps)
            appInstallUpdate=1
            shift
            ;;
        --apps-only)
            appInstallUpdate=2
            shift
            ;;
        --nvm)
            fNVMUpdate=true
            shift
            ;;
        --git-lfs)
            fGitLfsUpdate=true
            shift
            ;;
        --docker)
            fDockerUpdate=true
            shift
            ;;
        --wireshark)
            fWiresharkUpdate=true
            shift
            ;;
        --firefox)
            fFirefoxUpdate=true
            shift
            ;;
        --clangd)
            fClangdUpdate=true
            shift
            ;;
        --rtsp)
            fRtspFlag=1
            shift
            ;;
        --rtsp-all)
            fRtspFlag=1
            fRtspMulti=1
            shift
            ;;
        --rtsp-kill)
            fRtspKill=1
            shift
            ;;
        --rtsp-list)
            fRtspList=1
            shift
            ;;
        --rtsp-raw)
            fRtspFlag=1
            fRtspMulti=1
            fRtspFilter="_raw"
            shift
            ;;
        --rtsp-h264)
            fRtspFlag=1
            fRtspMulti=1
            fRtspFilter="_h264"
            shift
            ;;
        --rtsp-stream)
            fRtspFlag=1
            fRtspStream="$2"
            shift 2
            ;;
        --rtsp-ip)
            fRtspSrvIp="$2"
            shift 2
            ;;
        --rtsp-resolution)
            fRtspScreenRes="${2//x/ }"
            shift 2
            ;;
        --samba)
            fSambaServerFlag=1
            shift
            ;;
        --samba-reset-password)
            fSambaServerFlag=2
            shift
            ;;
        --vnc|--vnc-start)
            fVncServer=1
            shift
            ;;
        --vnc-stop)
            fVncServer=2
            shift
            ;;
        --vnc-restart)
            fVncServer=3
            shift
            ;;
        --vnclock)
            fVncLockAction="$2"
            shift 2
            ;;
        --unlock-vnc)
            fVncLockAction="unlock"
            shift
            ;;
        --lock-vnc)
            fVncLockAction="lock"
            shift
            ;;
        --gdm)
            fDisplayMode="gdm"
            shift
            ;;
        --text)
            fDisplayMode="text"
            shift
            ;;
        --chinese-pinyin)
            fChinesePinyinUpdate=true
            shift
            ;;
        --swap)
            fSwapReq=true
            shift 2
            ;;
        --link-clang-format)
            # $1 is '--link-clang-format'.
            # $2 is always an empty string '', even if an argument is provided.
            # Any provided argument appears sequentially in the positional parameters.
            # Example: $ jc huhu --link-clang-format /home/user1/ leetcode
            #       => jc --link-clang-format '' -- 'huhu' '/home/user1/' 'leetcode'
            # CRITICAL: Always 'shift 2' to consume the option ($1) and the
            # empty placeholder token ($2).
            fLinkClangFormatPath="$PWD"
            shift 2
            ;;
        --check-tls)
            fCheckTlsConn=true
            shift 2
            ;;
        --auto-remove)
            echo -e "${COLOR}Removing unused packages${RESET}"
            sudo apt autoremove -y
            shift
            exit 0
            ;;
        --update)
            echo -e "${COLOR}Updating all packages${RESET}"
            if [[ $(uname -s) == 'Darwin' ]]; then
                brew update
            else
                sudo apt update -y
            fi
            shift
            exit 0
            ;;
        --upgrade)
            echo -e "${COLOR}Updating all packages${RESET}"
            if [[ $(uname -s) == 'Darwin' ]]; then
                brew update
                echo -e "${COLOR}Upgrading all packages${RESET}"
                brew upgrade
            else
                sudo apt update -y
                echo -e "${COLOR}Upgrading all packages${RESET}"
                sudo apt upgrade -y --allow-downgrades
            fi
            # Upgrade globally installed npm packages
            nvmSh="$HOME/.nvm/nvm.sh"
            if [ -s "$nvmSh" ]; then
                # shellcheck source=/dev/null
                source "$nvmSh"
                # Parse `npm list -g --depth=0` lines like `├── @scope/pkg@1.2.3`
                # or `└── pkg@1.2.3` and emit just the package name. Avoid grep
                # -oP / \K / lookahead — BSD grep on macOS lacks PCRE.
                globalPkgs=$(npm list -g --depth=0 2>/dev/null | awk '/── / {
                    pkg = $NF
                    n = split(pkg, parts, "@")
                    if (n == 2) print parts[1]
                    else if (n == 3 && parts[1] == "") print "@" parts[2]
                }')
                if [ -n "$globalPkgs" ]; then
                    echo -e "${COLOR}Upgrading globally installed npm packages${RESET}"
                    for pkg in $globalPkgs; do
                        echo -e "  ${LIGHTYELLOW}Upgrading ${BLUE}$pkg${RESET}"
                        npm install -g "${pkg}@latest"
                    done
                fi
            fi
            shift
            exit 0
            ;;
        --claude)
            installClaude
            shift
            exit 0
            ;;
        --claude-remove)
            removeClaude
            shift
            exit 0
            ;;
        --claude-backup)
            fClaudeAction="backup"
            shift
            ;;
        --claude-restore)
            fClaudeAction="restore"
            shift
            ;;
        --claude-desktop-backup)
            fClaudeDesktopAction="backup"
            shift
            ;;
        --claude-desktop-restore)
            fClaudeDesktopAction="restore"
            shift
            ;;
        --claude-link-mcp)
            fClaudeLinkMcpJson=1
            shift
            ;;
        --codex)
            installCodex
            shift
            exit 0
            ;;
        --codex-remove)
            removeCodex
            shift
            exit 0
            ;;
        --codex-backup)
            fCodexAction="backup"
            shift
            ;;
        --codex-restore)
            fCodexAction="restore"
            shift
            ;;
        --gemini)
            installGemini
            shift
            exit 0
            ;;
        --gemini-remove)
            removeGemini
            shift
            exit 0
            ;;
        --xray)
            fXrayUpdate=true
            shift
            ;;
        --xray-port)
            fXrayPort="$2"
            if ! [[ "$fXrayPort" =~ ^[0-9]+$ ]] || (( fXrayPort < 1 || fXrayPort > 65535 )); then
                echo -e "${RED}Error: Invalid Xray port: $fXrayPort${RESET}"
                exit 1
            fi
            shift 2
            ;;
        --xray-server)
            fXrayServer="$2"
            shift 2
            ;;
        --xray-remove)
            fXrayRemove=true
            shift
            ;;

        --wg)
            fWireguardUpdate=true
            shift
            ;;
        --wg-port)
            fWireguardPort="$2"
            if ! [[ "$fWireguardPort" =~ ^[0-9]+$ ]] || (( fWireguardPort < 1 || fWireguardPort > 65535 )); then
                echo -e "${RED}Error: Invalid WireGuard port: $fWireguardPort${RESET}"
                exit 1
            fi
            shift 2
            ;;
        --wg-server)
            fWireguardServer="$2"
            shift 2
            ;;
        --wg-client)
            fWireguardClientName="$2"
            shift 2
            ;;
        --wg-remove)
            fWireguardRemove=true
            shift
            ;;

        --cursor-backup)
            fCursorAction="backup"
            shift
            ;;
        --cursor-restore)
            fCursorAction="restore"
            shift
            ;;
        --singbox)
            fSingbox=1
            shift
            ;;
        --singbox-xray)
            fSingboxLink="xray"
            shift
            ;;
        --singbox-wg)
            fSingboxLink="wireguard"
            shift
            ;;

        --acl-block)
            fGwAclAction="block"
            fGwAclTarget="$2"
            shift 2
            ;;
        --acl-unblock)
            fGwAclAction="unblock"
            fGwAclTarget="$2"
            shift 2
            ;;
        --acl-status)
            fGwAclAction="status"
            fGwAclTarget="$2"
            shift 2
            ;;

        -d|--debug)
            set -x
            echo -e "${COLOR}Debug mode enabled${RESET}"
            shift
            ;;
        -h|--help)
            usage
            ;;
        --)
            shift
            break
            ;;
        *)
            echo -e "${RED}Error: Invalid option: $1${RESET}" >&2
            exit 1
            ;;
    esac
done

if [ -n "$fGwAclAction" ]; then
    gwAclControl "$fGwAclAction" "$fGwAclTarget" || exit $?
    exit 0
fi


checkSudoPrivilege() {
    echo -e "${COLOR}Checking Sudo Privilege${RESET}"
    if sudo -n true 2>/dev/null; then
        echo -e "${GREEN}✔${GREY} User has passwordless sudo access.${RESET}"
        return
    fi

    if [[ $(uname -s) == 'Linux' ]]; then
        local sudoersFile="/etc/sudoers.d/$USER"
        # if id -nG "$USER" | grep -qw "sudo"; then
        if sudo -v; then
            echo -e "${LIGHTYELLOW}User $USER has sudo but requires a password. Configuring passwordless sudo${RESET}"
            echo "$USER ALL=(ALL) NOPASSWD:ALL" | sudo tee "$sudoersFile" > /dev/null
            sudo chmod 0440 "$sudoersFile"
        else
            echo -e "${RED}✗${GREY} User $USER has no sudo privilege.${RESET}"
            echo -e "${LIGHTYELLOW}Granting sudo access via root account (root password required)${RESET}"
            su -c "usermod -aG sudo $USER && echo '$USER ALL=(ALL) NOPASSWD:ALL' > $sudoersFile && chmod 0440 $sudoersFile" root
        fi

        if sudo -n true 2>/dev/null; then
            echo -e "${GREEN}✔${GREY} Passwordless sudo access configured for $USER.${RESET}"
            return
        fi
    fi

    echo -e "${RED}✗${GREY} Failed to obtain passwordless sudo access. Please configure manually.${RESET}"
    exit 1
}

checkTlsConnection() {
    local targetHost=${1:-"github.com"}
    if command -v openssl &> /dev/null; then
        checkTlsConnWithOpenssl "$targetHost"
    elif command -v curl &> /dev/null; then
        checkTlsConnWithCurl "$targetHost"
    else
        echo -e "${LIGHTYELLOW}curl and openssl are not installed. Aborting.${RESET}"
        exit 1
    fi
}

checkTlsConnWithOpenssl() {
    local targetHost=${1:-"github.com"}
    echo -e "${COLOR}Verifying server certificate against CA list for: ${NORMAL}${targetHost}${RESET}"

    # Use openssl s_client to connect and verify the certificate.
    # -connect <host>:<port>
    # -servername <host> for SNI
    # -showcerts (optional, but useful if debugging; we'll focus on the verify return code)
    # -verify_return_error: Crucial for getting a meaningful exit code on verification failure.
    # </dev/null: Prevents blocking on stdin.
    # 2>&1: Captures both stdout and stderr.
    local opensslOutput
    opensslOutput=$(openssl s_client -connect "${targetHost}:443" -servername "${targetHost}" -verify_return_error </dev/null 2>&1)
    local opensslExitCode=$?

    # openssl s_client returns non-zero for many errors, including verification failures.
    # A successful verification usually results in 'verify return:1'.
    # We need to check the exit code *and* the output for 'verify return:1'.

    # Grep for the specific success indicator and check the exit code.
    # The 'verify return:1' is the most direct confirmation of CA trust.
    # Note: openssl s_client may return non-zero even on successful verification due to connection closure
    if echo "$opensslOutput" | grep -q 'verify return:1' && ! echo "$opensslOutput" | grep -q 'verify return:0'; then
        echo -e "${GREEN}✔${GREY} Server certificate is trusted (legally issued and verifiable against CA list).${RESET}"
        # Optionally display specific certificate details if needed for context:
        local certDetails=$(echo "$opensslOutput" | openssl x509 -noout -subject -issuer -dates)
        if [ -n "$certDetails" ]; then
            echo -e "${CYAN}--- Certificate Details ---${RESET}"
            echo "$certDetails"
            echo -e "${CYAN}---------------------------${RESET}"
        fi
    else
        # Handle failures
        echo -e "${RED}✗${GREY} Server certificate is NOT trusted or an error occurred.${RESET}"
        if echo "$opensslOutput" | grep -q 'verify return:.*error'; then
            echo -e "${RED}  Reason: Certificate validation failed.${RESET}"
        elif echo "$opensslOutput" | grep -q 'connect:errno='; then
            echo -e "${RED}  Reason: Could not connect to the server.${RESET}"
        elif echo "$opensslOutput" | grep -q 'certificate verify failed'; then
            echo -e "${RED}  Reason: OpenSSL reported a certificate verification failure.${RESET}"
        else
            echo -e "${RED}  Reason: Unknown error or non-verified certificate.${RESET}"
        fi
        # Show a snippet of the output for debugging
        echo -e "${CYAN}☞ ${GREY}openssl output snippet:${RESET}"
        echo "$opensslOutput" | head -n 10
        exit 1 # Exit on any failure
    fi
}

checkTlsConnWithCurl() {
    local targetHost=${1:-"github.com"}
    echo -e "${COLOR}Checking TLS Certificate Trust for: ${NORMAL}${targetHost}${RESET}"

    local curlOutput
    # -fsS = --fail --silent --show-error
    curlOutput=$(curl --head -fsS --connect-timeout 5 "https://${targetHost}" 2>&1)
    local curlExitCode=$?

    # Exit code 60 is specifically for peer certificate verification failure.
    if [ $curlExitCode -eq 0 ]; then
        echo -e "${GREEN}✔${GREY} TLS connection successful. Certificate is trusted.${RESET}"
    elif [ $curlExitCode -eq 60 ]; then
        echo -e "${RED}✗${GREY} TLS connection failed: Certificate validation error.${RESET}"
        echo -e "${RED}  This is often due to a corporate proxy (Man-in-the-Middle).${RESET}"
        echo -e "${GREY}☞ Details: \n$(echo "$curlOutput" | sed 's/curl: (60) //')${RESET}"
        exit 1
    else
        echo -e "${RED}✗${GREY} TLS connection failed for another reason (Exit Code: $curlExitCode).${RESET}"
        echo -e "${GREY}☞ Details: \n$(echo "$curlOutput" | sed 's/curl: ([0-9]\+) //')${RESET}"
    fi
}

detectDistroFamily() {
    if [[ -f /etc/os-release ]]; then
        # shellcheck source=/dev/null
        . /etc/os-release
        case "$ID" in
            fedora|centos|rhel|rocky|alma) echo "fedora" ; return ;;
        esac
        case "$ID_LIKE" in
            *fedora*|*rhel*) echo "fedora" ; return ;;
            *debian*)        echo "debian" ; return ;;
        esac
    fi
    echo "debian"
}

checkOSAndArch() {
    echo -e "${COLOR}Checking OS and Architecture${RESET}"
    fArch=$(uname -m)
    if [[ -f /etc/os-release ]]; then
        local prettyName=$(awk -F= '/^PRETTY_NAME=/{print $2}' /etc/os-release)
        local idLike=$(awk -F= '/^ID_LIKE=/{print $2}' /etc/os-release)
        case "$idLike" in
            "debian")
                fOSCategory=$idLike
                echo -e "${GREEN}✔${GREY} The current OS type is ${LIGHTYELLOW}$prettyName${RESET}. ${GREY}The Arch is ${LIGHTYELLOW}$fArch${RESET}"
                ;;
            *)
                fOSCategory=$idLike
                echo -e "${GREEN}❌${GREY} The current OS type is ${LIGHTYELLOW}$prettyName${RESET}. ${GREY}The Arch is ${LIGHTYELLOW}$fArch${RESET}"
                echo "  We currently do not support this OS type."
                exit
                ;;
        esac
    elif [[ $(uname) == "Darwin" ]]; then
        fOSCategory=mac
        echo -e "${GREEN}✔${GREY} The current OS type is ${LIGHTYELLOW}macOS${RESET}. ${GREY}The Arch is ${LIGHTYELLOW}$fArch${RESET}"
    else
        echo -e "${GREEN}❌${GREY} The OS type is not supported or could not be determined."
        exit 1
    fi
}

removeInstalledPackages() {
        local packagesToCheck=("$@")
        local packagesToRemove=()

        for pkg in "${packagesToCheck[@]}"; do
            if dpkg-query -W -f='${Status}' "$pkg" 2>/dev/null | grep -q "ok installed"; then
                packagesToRemove+=("$pkg")
            fi
        done

        if [ ${#packagesToRemove[@]} -gt 0 ]; then
            echo -e "${LIGHTYELLOW}Removing conflicting/unwanted packages: ${packagesToRemove[*]}${RESET}"
            sudo apt remove --purge -y "${packagesToRemove[@]}"
        fi
}

ubuntuInstallApps() {
    [ ! -f "$fFirstTimeFile" ] && appInstallUpdate=1
    [ -z "$appInstallUpdate" ] && return
    checkSudoPrivilege
    local appsForUbuntu=(
        # --- Core Command-Line Tools ---
        tmux                    # Terminal multiplexer
        vim                     # Vi IMproved
        rsync                   # Remote file sync
        curl                    # Command-line HTTP client
        gnupg                   # GNU privacy guard
        lsb-release             # Linux Standard Base
        openssl                 # OpenSSL command-line tools
        dos2unix                # Convert DOS line endings to Unix
        expect                  # Expect script interpreter
        shellcheck              # Shell script static analyzer
        bash-completion         # Bash completion
        qrencode                # QR code generator

        # --- File Finding & Processing ---
        mlocate                 # locate/updatedb for fast file searching
        fd-find                 # fd, a faster find
        ripgrep                 # rg, a faster grep
        jq                      # JSON processor
        bat                     # A cat clone with syntax highlighting

        # --- Build System & Toolchains ---
        build-essential         # Compiler toolchain (gcc, make, etc.)
        pkg-config              # Manage compile/link flags for libraries
        gdb                     # The GNU Debugger
        universal-ctags         # Ctags for code navigation
        ragel                   # State machine compiler
        bear                    # Generate compilation database
        clang-tools             # Clang compiler tools
        cmake                   # Cross-platform build system generator
        libtool                 # Generic library support script
        autoconf                # Generates configuration scripts
        gettext                 # GNU internationalization utilities
        texinfo                 # Documentation system

        # --- Development Libraries ---
        python3-dev             # Python 3 development headers
        python3-venv            # Python 3 virtual environment
        libssl-dev              # OpenSSL development libraries
        libboost-all-dev        # Boost C++ libraries
        libsqlite3-dev          # SQLite 3 development library
        libpcap-dev             # Packet capture library headers
        libbpf-dev              # libbpf eBPF library
        libcurl4-openssl-dev    # cURL development library
        libisl-dev              # Integer Set Library for polyhedral compilation
        libgmp-dev              # GNU Multiple Precision Arithmetic Library
        libncurses-dev          # Ncurses terminal library
        libsource-highlight-dev # Source code highlighting library
        libmpfr-dev             # Multiple-precision floating-point library

        # --- System & Performance Analysis ---
        htop                      # Interactive process viewer
        linux-tools-common        # Common Linux tools
        bpfcc-tools               # BCC eBPF toolkit

        # --- Networking Tools ---
        netcat-openbsd          # nc
        socat                   # netcat replacement
        net-tools               # (Optional, legacy: ifconfig, netstat)
        iproute2                # (Recommended, modern: ip, ss)
        conntrack               # Connection tracking tools
        nftables                # Netfilter tables
        inetutils-traceroute    # Traceroute
        nmap                    # Network scanner and security auditing tool
        openssh-server          # SSH server
        sshfs                   # SSH filesystem
        sshpass                 # SSH password authentication

        # --- Desktop Environment (Choose ONE) ---
        ubuntu-desktop          # The full GNOME desktop environment
        xfce4                   # A lightweight XFCE desktop
        xfce4-goodies           # Goodies for XFCE (recommended)
        xfce4-screensaver       # XFCE screensaver

        # --- GUI Tools & Dependencies ---
        gdm3                    # GNOME Display Manager
        yaru-theme-icon         # Yaru icon theme
        network-manager-gnome   # Network manager
        gnome-keyring           # Keyring manager
        xsel                    # Command-line clipboard tool
        xclip                   # Command-line clipboard tool
        fonts-noto-cjk          # CJK fonts
        fonts-wqy-microhei      # Chinese fonts
        fonts-wqy-zenhei        # Chinese fonts
        remmina                 # Remote desktop client (VNC, RDP, etc.)
        remmina-plugin-rdp      # RDP plugin for Remmina
        tigervnc-standalone-server # VNC server
        tigervnc-xorg-extension    # VNC X11 extension

        # --- Virtualization ---
        qemu-kvm                # KVM virtualization
        qemu-utils              # QEMU utilities
        libvirt-daemon-system   # libvirt daemon
        virt-manager            # GUI for managing virtual machines
        virt-top

        # --- Miscellaneous ---
        ffmpeg                  # FFmpeg command-line tools
        sqlite3                 # Command-line interface for SQLite
        ifupdown                # Legacy network configuration tool
        bridge-utils            # Bridge configuration utility
    )
    echo -e "${COLOR}Updating Apps for Ubuntu${RESET}"
    sudo apt update
    if ! removeInstalledPackages thunderbird lightdm xrdp xorgxrdp; then
        echo -e "${RED}Error: Failed to remove one or more conflicting packages. Aborting Apps installation.${RESET}"
        return 1
    fi
    echo "gdm3 shared/default-x-display-manager select gdm3" | sudo debconf-set-selections
    # echo "wireshark-common wireshark-common/install-setuid boolean true" | sudo debconf-set-selections
    sudo DEBIAN_FRONTEND=noninteractive apt install -y --no-install-recommends "${appsForUbuntu[@]}"

    # Install kernel-specific linux-tools if available (may not exist for custom kernels)
    # Try kernel-specific version first, fall back to generic
    local kernelToolsPkg="linux-tools-$(uname -r)"
    local genericToolsPkg="linux-tools-generic"
    if apt-cache show "$kernelToolsPkg" &>/dev/null; then
        echo -e "${GREY}Installing kernel-specific tools: ${kernelToolsPkg}${RESET}"
        sudo DEBIAN_FRONTEND=noninteractive apt install -y "$kernelToolsPkg" || \
            echo -e "${LIGHTYELLOW}Warning: Failed to install ${kernelToolsPkg}, skipping.${RESET}"
    elif apt-cache show "$genericToolsPkg" &>/dev/null; then
        echo -e "${LIGHTYELLOW}Note: ${kernelToolsPkg} not available, trying ${genericToolsPkg}...${RESET}"
        sudo DEBIAN_FRONTEND=noninteractive apt install -y "$genericToolsPkg" || \
            echo -e "${LIGHTYELLOW}Warning: Failed to install ${genericToolsPkg}, skipping.${RESET}"
    else
        echo -e "${LIGHTYELLOW}Note: Neither ${kernelToolsPkg} nor ${genericToolsPkg} available, skipping.${RESET}"
    fi

    # sudo DEBIAN_FRONTEND=noninteractive dpkg-reconfigure gdm3
    sudo apt autoremove -y
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}Success!${RESET}"
        if [ "$appInstallUpdate" -eq 2 ]; then
            exit 0
        fi
    else
        echo -e "${RED}Failed!${RESET}"
        exit 1
    fi
}

macInstallApps() {
    [ ! -f "$fFirstTimeFile" ] && appInstallUpdate=1
    [ -z "$appInstallUpdate" ] && return
    checkSudoPrivilege
    appsForMac=(
        # --- Core Command-Line Tools ---
        bash                    # GNU Bash (newer than macOS built-in)
        gnu-getopt              # GNU getopt (long options support)
        gnu-sed                 # GNU sed (macOS ships BSD sed)
        gawk                    # GNU awk (macOS ships BSD awk)
        grep                    # GNU grep (macOS ships BSD grep)
        coreutils               # GNU core utilities (gdate, gstat, etc.)
        bash-completion@2       # Bash completion (v2, for Bash 4+)
        shellcheck              # Shell script static analyzer
        vim                     # Vi IMproved
        tmux                    # Terminal multiplexer
        htop                    # Interactive process viewer
        dos2unix                # Convert DOS line endings to Unix

        # --- File Finding & Processing ---
        fd                      # A faster find
        ripgrep                 # rg, a faster grep
        bat                     # A cat clone with syntax highlighting
        fzf                     # Fuzzy finder
        jq                      # JSON processor

        # --- Version Control & Networking ---
        git                     # Distributed version control
        git-lfs                 # Git Large File Storage
        autossh                 # Auto-reconnecting SSH sessions
        curl                    # Command-line HTTP client (newer than macOS built-in)
        rsync                   # Fast incremental file transfer (newer than macOS built-in)

        # --- GUI & Desktop ---
        fontconfig              # Font configuration library
        freerdp                 # Remote desktop client (RDP)

        # --- Networking ---
        nmap                    # Network scanner and security auditing tool

        # --- Miscellaneous ---
        ffmpeg                  # Media processing toolkit
        yt-dlp                  # Video downloader
        qrencode                # QR code generator
    )
    casksForMac=(
        xquartz                 # X11 server for macOS
    )

    echo -e "${COLOR}Updating Apps for MacOS${RESET}"
    brew update

    # Unlink old bash-completion if installed (conflicts with bash-completion@2)
    # if brew list bash-completion &>/dev/null; then
    #     echo -e "${GREY}Unlinking old bash-completion...${RESET}"
    #     brew unlink bash-completion
    # fi

    brew install "${appsForMac[@]}"
    brew install --cask "${casksForMac[@]}"
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}Success!${RESET}"
        if [ "$appInstallUpdate" -eq 2 ]; then
            exit 0
        fi
    else
        echo -e "${RED}Failed!${RESET}"
        exit 1
    fi
}

setTimeZone() {
    echo -e "${COLOR}Setting Timezone${RESET}"
    if [[ $(uname -s) == 'Darwin' ]]; then
        echo -e "${COLOR}Checking Timezone on macOS${RESET}"
        local currentTZ=$(readlink /etc/localtime 2>/dev/null | sed 's|/var/db/timezone/zoneinfo/||' || echo "Unknown")
        if [[ "$currentTZ" == "Asia/Shanghai" ]]; then
            echo -e "${GREEN}✔${GREY} Timezone is already set to Asia/Shanghai${RESET}"
        else
            echo -e "${LIGHTYELLOW}Current timezone: $currentTZ${RESET}"
            echo -e "${LIGHTYELLOW}To change timezone on macOS:${RESET}"
            echo -e "${GREY}  System Settings → General → Date & Time → Time Zone${RESET}"
            echo -e "${GREY}  Or use: sudo systemsetup -settimezone Asia/Shanghai${RESET}"
        fi
        return
    fi

    # Linux (Ubuntu/Debian)
    if [ "$(timedatectl | grep "Time zone" | awk '{print $3}')" == "Asia/Shanghai" ]; then
        echo -e "${GREEN}✔${GREY} Time zone is already shanghai${RESET}"
        return
    fi
    echo -e "${COLOR}Setting Timezone to Shanghai${RESET}"
    sudo timedatectl set-timezone Asia/Shanghai
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}Success!${RESET}"
    else
        echo -e "${RED}Failed!${RESET}"
        exit 1
    fi
}

stopAndDisableDaemonService() {
    local targetServiceName="${1:-networking.service}"
    if ! systemctl cat "$targetServiceName" >/dev/null 2>&1; then
        return 1
    fi
    # Stop the service
    local targetServiceStatus=$(systemctl is-active "$targetServiceName" 2>&1)
    if [ "$targetServiceStatus" == "active" ]; then
        echo -e "${LIGHTYELLOW}Service '${targetServiceName}' is active. Attempting to stop it...${RESET}"
        if sudo systemctl stop "$targetServiceName"; then
            echo -e "${GREEN}✔${GREY} Successfully stopped service '${targetServiceName}'.${RESET}"
        else
            echo -e "${RED}Failed to stop service '${targetServiceName}'.${RESET}"
        fi
    elif [ "$targetServiceStatus" == "inactive" ] || [ "$targetServiceStatus" == "failed" ]; then
        echo -e "${GREEN}✔${GREY} Service '${targetServiceName}' is inactive (status: $targetServiceStatus).${RESET}"
    else
        echo -e "${RED}Failed to check status for service '${targetServiceName}'.${RESET}"
        return 1
    fi

    # Disable the service
    local targetServiceEnabledStatus=$(systemctl is-enabled "$targetServiceName" 2>&1)
    case "$targetServiceEnabledStatus" in
        "disabled")
            echo -e "${GREEN}✔${GREY} Service '${targetServiceName}' is already disabled.${RESET}"
            return 0
            ;;
        "static")
            echo -e "${GREEN}✔${GREY} Service '${targetServiceName}' is static (cannot be enabled/disabled conventionally). No action needed.${RESET}"
            return 0
            ;;
        "masked")
            echo -e "${GREEN}✔${GREY} networking.service is masked. No disable action needed.${RESET}"
            return 0
            ;;
        *)
            echo -e "${LIGHTYELLOW}Attempting to disable service '${targetServiceName}' (current status: '$targetServiceEnabledStatus')...${RESET}"
            if sudo systemctl disable "$targetServiceName"; then
                echo -e "${GREEN}✔${GREY} Successfully disabled service '${targetServiceName}'.${RESET}"
            else
                echo -e "${RED}Failed to disable service '${targetServiceName}'. It might be already disabled or an error occurred.${RESET}"
                return 1
            fi
            ;;
    esac
}

# There are two primary services associated with networking in Debian/Ubuntu-based systems:
# 1. networking.service:
#    - This is the traditional System V init-style networking service.
#    - It primarily manages network interfaces configured in `/etc/network/interfaces`.
#    - It's often used for statically configured interfaces or simpler network setups.
#    - On modern systems, especially desktops and laptops, NetworkManager often takes precedence.
#
# 2. NetworkManager.service:
#    - This is a more dynamic and feature-rich network management daemon.
#    - It's the default on most modern desktop Linux distributions, including Ubuntu Desktop.
#    - It provides automatic detection and configuration for various network types (Ethernet, Wi-Fi, VPNs, etc.).
#    - It manages connections through profiles and can handle roaming, multiple connections, and user-specific settings.
#    - It usually takes control of interfaces *not* explicitly managed by `/etc/network/interfaces` (unless configured otherwise).
#
# Coexistence and Conflicts:
# - Generally, it's recommended to use *either* `networking.service` (via `/etc/network/interfaces`) *or* `NetworkManager.service` to manage a particular network interface, but not both.
# - Having both active and attempting to manage the same interfaces can lead to conflicts, unpredictable behavior, or connection issues.
# - For desktop environments, NetworkManager is usually preferred for its ease of use and dynamic capabilities.
# - For servers, especially with static IPs, `networking.service` with `/etc/network/interfaces` is often sufficient and more straightforward.
# - The script below checks if NetworkManager is active. If it is, and `networking.service` is also active,
#   it attempts to stop and disable `networking.service` to prevent potential conflicts, assuming NetworkManager
#   is the intended primary network manager.
checkNetworkManagerStatus() {
    # echo -e "${COLOR}Checking NetworkManager.service status...${RESET}"
    local nmServiceStatus=$(systemctl is-active NetworkManager.service 2>&1)
    if [ "$nmServiceStatus" == "active" ]; then
        echo -e "${GREEN}✔${GREY} NetworkManager is active.${RESET}"
        stopAndDisableDaemonService "networking.service"
    elif [ "$nmServiceStatus" == "inactive" ] || [ "$nmServiceStatus" == "failed" ]; then
        echo -e "${LIGHTYELLOW}NetworkManager is not active (status: ${nmServiceStatus}).${RESET}"
        echo -e "${LIGHTYELLOW}Consider enabling and starting NetworkManager if it's intended to manage network connections.${RESET}"
        if [ "$(systemctl is-active networking.service 2>/dev/null)" == "active" ]; then
            echo -e "${GREY}networking.service is active. This might be intentional if NetworkManager is not used.${RESET}"
        fi
    else
        echo -e "${RED}Could not determine status of NetworkManager (status: '$nmServiceStatus').${RESET}"
    fi
}

stopUnnecessaryServices() {
    echo -e "${COLOR}Stopping Unnecessary Services${RESET}"
    checkNetworkManagerStatus
    local services_to_manage=(
        "cups.service"          # CUPS (Common UNIX Printing System)
        "cups-browsed.service"  # CUPS Browser Support
        "nmbd.service"          # NetBIOS Name Service
        "xrdp.service"          # Remote Desktop Protocol
        # "ufw.service"           # Uncomplicated Firewall
    )
    for service in "${services_to_manage[@]}"; do
        stopAndDisableDaemonService "$service"
    done
}

disableLidCloseSuspend() {
    echo -e "${COLOR}Configuring Laptop for Lid-Closed Server Mode${RESET}"

    local logindConf="/etc/systemd/logind.conf"
    local needRestart=0

    # 1. Set HandleLidSwitch options to ignore in logind.conf
    local lidSettings=("HandleLidSwitch" "HandleLidSwitchExternalPower" "HandleLidSwitchDocked")
    for setting in "${lidSettings[@]}"; do
        local current=$(grep -E "^${setting}=" "$logindConf" 2>/dev/null | cut -d= -f2)
        if [ "$current" == "ignore" ]; then
            echo -e "${GREEN}✔${GREY} ${setting}=ignore already set${RESET}"
        else
            sudo sed -i "s/^#\?${setting}=.*/${setting}=ignore/" "$logindConf"
            echo -e "${GREEN}✔${GREY} ${setting}=ignore${RESET}"
            needRestart=1
        fi
    done

    if [ "$needRestart" -eq 1 ]; then
        sudo systemctl restart systemd-logind
        echo -e "${GREEN}✔${GREY} systemd-logind restarted${RESET}"
    fi

    # 2. Mask sleep/suspend/hibernate targets
    local targets=("sleep.target" "suspend.target" "hibernate.target" "hybrid-sleep.target")
    for target in "${targets[@]}"; do
        if systemctl is-enabled "$target" 2>/dev/null | grep -q "masked"; then
            echo -e "${GREEN}✔${GREY} ${target} already masked${RESET}"
        else
            sudo systemctl mask "$target" >/dev/null 2>&1
            echo -e "${GREEN}✔${GREY} ${target} masked${RESET}"
        fi
    done

    # 3. Disable GNOME power manager auto-suspend (if gnome-settings-daemon is installed)
    if dpkg -l gnome-settings-daemon 2>/dev/null | grep -q '^ii'; then
        local dbusAddr="unix:path=/run/user/$(id -u)/bus"
        DBUS_SESSION_BUS_ADDRESS="$dbusAddr" gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type 'nothing' 2>/dev/null
        DBUS_SESSION_BUS_ADDRESS="$dbusAddr" gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-timeout 0 2>/dev/null
        DBUS_SESSION_BUS_ADDRESS="$dbusAddr" gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-type 'nothing' 2>/dev/null
        DBUS_SESSION_BUS_ADDRESS="$dbusAddr" gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-timeout 0 2>/dev/null
        DBUS_SESSION_BUS_ADDRESS="$dbusAddr" gsettings set org.gnome.settings-daemon.plugins.power idle-dim false 2>/dev/null
        echo -e "${GREEN}✔${GREY} GNOME power manager auto-suspend disabled${RESET}"
    fi
}

installTmuxPluginsManager() {
    echo -e "${COLOR}Installing Tmux Plugins Manager${RESET}"
    if [ -d ~/.tmux/plugins/tpm ]; then
        echo -e "${GREEN}✔${GREY} Tmux Plug Manager is already installed${RESET}"
    else
        git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}Success!${RESET}"
        else
            echo -e "${RED}Failed!${RESET}"
            exit 1
        fi
    fi
    echo -e "${COLOR}Installing Tmux plugins${RESET}"
    ~/.tmux/plugins/tpm/bin/install_plugins
}

installVimPluginsManager (){
    echo -e "${COLOR}Installing Vim Plugins Manager${RESET}"

    if [ ! -f ~/.vimrc ]; then
        echo "No .vimrc found, Abort!"
        exit 1
    fi

    if [ ! -f "$fVimPlugsManagerPath" ]; then
        # use the --insecure option to avoid certificate check
        curl -fLo "$fVimPlugsManagerPath" --create-dirs \
        https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
    else
        echo -e "${GREEN}✔${GREY} Vim Plug Manager is already installed${RESET}"
    fi

    echo -e "${COLOR}Updating Vim Plugins${RESET}"
    vim +PlugInstall +PlugUpdate +qall
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}✔ Success!${RESET}"
    else
        echo -e "${RED}✗ Failed!${RESET}"
        exit 1
    fi
}

# linkFile: Creates a symbolic link for a file or command to a destination directory.
#
# It can link a source file by its path or a command from the system's PATH.
# The function will back up any existing non-link file at the destination.
#
# Usage:
#   linkFile <target_path_or_cmd> <destination_dir> [new_link_name] [type]
#
# Example (file):
#   linkFile ~/myfile.txt /data/backup
# Example (file with new name):
#   linkFile ~/myfile.txt /data/backup my-renamed-file.txt
# Example (command):
#   linkFile batcat ~/.usr/bin bat command
#
# Arguments:
#   $1 - The source file path or command name.
#   $2 - The destination directory where the link will be created.
#   $3 - New link name (optional, defaults to the basename of the source).
#   $4 - Type of source: 'file' (default) or 'command' (optional).
#
# Returns:
#   0 on successful link creation.
#   1 if the link is already up to date.
#   2 if the source command is not found.
#   Exits the script if a source file does not exist.
#
linkFile() {
    local src="$1"         # Source file or command
    local linkPath="$2"    # Destination directory to link to
    local newLinkName="$3" # New link name (optional, default: as is)
    local type=${4:-file}  # Type of source

    if [[ "$type" == "command" ]]; then
        local originalCmd="$src"
        src=$(command -v "$src")
        if [ -z "$src" ]; then
            echo -e "${RED}✗${GREY} ${originalCmd} is not installed${RESET}"
            return 2
        fi
    fi
    if [ ! -d "$linkPath" ]; then
        mkdir -p "$linkPath"
    fi

    local filename=$(basename "$src")
    local linkName=${newLinkName:-$filename}
    local dst="$linkPath/${linkName}"
    [ ! -e "$src" ] && echo -e "${RED}Error: $src does not exist${RESET}" && return 1
    if [ -f "$dst" ] && [ ! -L "$dst" ]; then
        [ ! -d "$fBackupDir" ] && mkdir -p "$fBackupDir"
        echo -e "${CYAN}Warning: $dst is not a link, backing it up into $fBackupDir${RESET}"
        local mvSuccess=false
        local mvPrefix=
        for _ in {1..2}; do
            if $mvPrefix mv "$dst" "$fBackupDir/${linkName}.bak" &> /dev/null; then
                mvSuccess=true
                break
            fi
            if [ -z "$mvPrefix" ]; then
                echo -e "   ├─ ${GREY}Info:${RESET}   ${RED}Backup failed! Retrying with sudo...${RESET}"
                mvPrefix="sudo "
            else
                break
            fi
        done
        if [ "$mvSuccess" = true ]; then
            echo -e "   └─ ${GREY}Backup:${RESET} ✔ ${GREEN}Moved to $fBackupDir/${linkName}.bak${RESET}"
        else
            echo -e "   └─ ${GREY}Backup:${RESET} ❌ ${RED}Failed to back up $dst${RESET}"
            return 1
        fi
    fi

    if [ -L "$dst" ] && [ "$(readlink "$dst")" == "$src" ]; then
        echo -e "${GREEN}✔${GREY} Link ${BLUE}${linkName}${GREY} is already up to date.${RESET}"
        return 1
    fi

    echo -e "🔗 ${LIGHTYELLOW}Creating Symlink${RESET}"
    echo -e "   ├─ ${GREY}Source:${RESET} ${CYAN}$src${RESET}"
    echo -e "   └─ ${GREY}Target:${RESET} ${CYAN}$dst${RESET}"

    local success=false
    local execPrefix=
    for _ in {1..2}; do
        if $execPrefix ln -sf "$src" "$dst" &> /dev/null; then
            success=true
            break
        fi
        if [ -z "$execPrefix" ]; then
            echo -e "   ├─ ${GREY}Info:${RESET}   ${RED}Failed! Retrying with sudo...${RESET}"
            execPrefix="sudo "
        else
            break
        fi
    done
    if [ "$success" = true ]; then
        echo -e "   └─ ${GREY}Status:${RESET} ✔ ${GREEN}Success!${RESET}"
    else
        echo -e "   └─ ${GREY}Status:${RESET} ❌ ${RED}Failed!${RESET}"
    fi
}

# syncFile: Syncs a file into a destination directory using rsync.
#
# Creates the destination directory if needed. Skips files that are already
# identical at the destination.
#
# Usage:
#   syncFile <source_file> <destination_dir> [new_file_name]
#
# Returns:
#   0 on successful copy.
#   1 if the destination is already up to date.
#   2 if the source file does not exist.
#   3 if the copy fails.
syncFile() {
    local src="$1"
    local syncPath="$2"
    local newName="$3"
    local rsyncOutput=
    local rsyncStatus=0

    local filename=$(basename "$src")
    local syncName=${newName:-$filename}
    local dst="$syncPath/${syncName}"

    if [ ! -f "$src" ]; then
        echo -e "${LIGHTYELLOW}Warning: ${BLUE}$src${LIGHTYELLOW} does not exist, skipping.${RESET}"
        return 2
    fi

    if [ ! -d "$syncPath" ] && ! mkdir -p "$syncPath"; then
        echo -e "${RED}Error: Failed to create directory ${BLUE}$syncPath${RESET}"
        return 3
    fi

    echo -e "📄 ${LIGHTYELLOW}Syncing File${RESET}"
    echo -e "   ├─ ${GREY}Source:${RESET} ${CYAN}$src${RESET}"
    echo -e "   └─ ${GREY}Target:${RESET} ${CYAN}$dst${RESET}"

    if ! command -v rsync &> /dev/null; then
        echo -e "   └─ ${GREY}Status:${RESET} ❌ ${RED}rsync is not installed.${RESET}"
        return 3
    fi

    rsyncOutput=$(rsync -ci "$src" "$dst" 2>&1)
    rsyncStatus=$?
    if [ $rsyncStatus -eq 0 ]; then
        if [ -z "$rsyncOutput" ]; then
            echo -e "   └─ ${GREY}Status:${RESET} ✔ ${GREEN}Already up to date.${RESET}"
            return 1
        fi

        echo -e "   └─ ${GREY}Status:${RESET} ✔ ${GREEN}Success!${RESET}"
        return 0
    fi

    echo -e "   └─ ${GREY}Status:${RESET} ❌ ${RED}Failed!${RESET}"
    [ -n "$rsyncOutput" ] && echo -e "      ${GREY}${rsyncOutput}${RESET}"
    return 3
}

# linkFiles: Creates symbolic links for all files from a source directory to a destination directory.
#
# This function iterates through all files in a source directory and creates a
# symbolic link for each in the destination directory. After linking, it also
# removes any broken symbolic links found in the destination directory (this
# cleanup is skipped if the destination is the user's home directory).
#
# Usage:
#   linkFiles <source_dir> <destination_dir> [link_name_prefix]
#
# Example:
#   # Link files from a config folder to the home directory, creating dotfiles.
#   linkFiles ~/dotfiles/config ~/. "."
#
# Arguments:
#   $1 - The source directory containing the files to be linked.
#   $2 - The destination directory where the symbolic links will be created.
#   $3 - An optional prefix to add to the created link names (e.g., ".").
#
# Exits:
#   The script will exit if the source directory does not exist.
linkFiles() {
    local srcDir="$1"           # Source directory
    local linkPath="$2"         # Destination directory
    local linknamePrefix="$3"   # Prefix for destination filename. Exp: . for hidden files

    [ ! -d "$srcDir" ] && echo "Source directory $srcDir does not exist, abort!" && exit 1
    [ ! -d "$linkPath" ] && mkdir -p "$linkPath"

    for file in "$srcDir"/*; do
        linkFile "$file" "$linkPath" "${linknamePrefix}$(basename "$file")"
    done

    if [ "$linkPath" == "$HOME" ]; then
        return
    fi
    # Remove broken symlinks
    find "$linkPath" -type l ! \
            -exec test -e {} \; \
            -exec rm -f {} \; \
            -exec echo -e "${CYAN}Deleting broken link: {}${RESET}" \;
}

buildBatTheme() {
    # https://github.com/sharkdp/bat/tree/master/assets/themes
    echo -e "${COLOR}Building Bat Themes${RESET}"
    local batThemeDir=$HOME/.config/bat/themes
    local needBuild=
    [ ! -d "$batThemeDir" ] && mkdir -p "$batThemeDir"

    for theme in "$fTKBatThemeDir"/*; do
        linkFile "$theme" "$batThemeDir"
        if [ $? -eq 1 ]; then
            continue
        fi
        needBuild=true
    done

    [ -z "$needBuild" ] && return
    batcat cache --build
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}Success!${RESET}"
    else
        echo -e "${RED}Failed!${RESET}"
        exit 1
    fi
}

buildExtraFonts() {
    echo -e "${COLOR}Building Extra Fonts${RESET}"
    local needBuild=
    local fontConfigDir="$HOME/.config/fontconfig/conf.d"
    local fontDir=$HOME/.local/share/fonts
    [ ! -d "$fontDir" ] && mkdir -p "$fontDir"
    [ ! -d "$fontConfigDir" ] && mkdir -p "$fontConfigDir"

    # Detect fc-list command
    local FC_LIST_CMD="fc-list"
    local FC_CACHE_CMD="fc-cache"
    if [[ $(uname -s) == 'Darwin' ]]; then
        if command -v /opt/homebrew/bin/fc-list &> /dev/null; then
            FC_LIST_CMD="/opt/homebrew/bin/fc-list"
            FC_CACHE_CMD="/opt/homebrew/bin/fc-cache"
        elif command -v /usr/local/bin/fc-list &> /dev/null; then
            FC_LIST_CMD="/usr/local/bin/fc-list"
            FC_CACHE_CMD="/usr/local/bin/fc-cache"
        fi
    fi

    for fontConfig in "$fTKFontConfigDir"/*; do
        linkFile "$fontConfig" "$fontConfigDir"
        if [ $? -eq 1 ]; then
            continue
        fi
    done

    for font in "$fTKFontDir"/*; do
        local fontFile=$(basename "$font")

        # Check if font exists
        if command -v "$FC_LIST_CMD" &> /dev/null; then
            local fontExists=$("$FC_LIST_CMD" | grep -i "$fontFile")
            if [ -n "$fontExists" ]; then
                echo -e "${GREEN}✔${GREY} Font ${BLUE}${fontFile}${GREY} is already up to date.${RESET}"
                continue
            fi
        else
            # Fallback: check if font file exists in font directory
            if [ -f "$fontDir/$fontFile" ] || [ -L "$fontDir/$fontFile" ]; then
                echo -e "${GREEN}✔${GREY} Link ${BLUE}${fontFile}${GREY} is already up to date.${RESET}"
                continue
            fi
        fi

        linkFile "$font" "$fontDir"
        if [ $? -eq 1 ]; then
            continue
        fi
        needBuild=true
    done

    [ -z "$needBuild" ] && return

    # Build font cache if fc-cache is available
    if command -v "$FC_CACHE_CMD" &> /dev/null; then
        echo -e "${COLOR}Building font cache...${RESET}"
        if [[ $(uname -s) == 'Darwin' ]]; then
            "$FC_CACHE_CMD" -fv
        else
            sudo "$FC_CACHE_CMD" -fv
        fi
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}Success!${RESET}"
        else
            echo -e "${LIGHTYELLOW}Warning: Font cache build had issues, but fonts are installed.${RESET}"
        fi
    else
        echo -e "${LIGHTYELLOW}Note: fc-cache not available, fonts installed but cache not rebuilt.${RESET}"
        echo -e "${GREY}On macOS, fonts may require logging out and back in to take effect.${RESET}"
    fi
}

changeTMOUTToWritable() {
    # TMOUT is readonly in /etc/profile, change it to writable so that we can unset it in .bashrc
    if ! grep -q "TMOUT" /etc/profile; then
        return
    fi
    echo -e "${COLOR}Changing TMOUT to Writable${RESET}"
    if grep -q "^readonly TMOUT" /etc/profile; then
        echo -e "${GREY}TMOUT is readonly in /etc/profile, change it to writable${RESET}"
    else
        echo -e "${GREEN}✔${GREY} TMOUT is already writable$ in /etc/profile${RESET}"
        return
    fi

    sudo sed -i 's/^readonly TMOUT/# readonly TMOUT/g' /etc/profile
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}Success!${RESET}"
    else
        echo -e "${RED}Failed!${RESET}"
        exit 1
    fi
}

createTKSymlinks() {
    # The directories are guaranteed to exist when this function is called.
    echo -e "${COLOR}Creating Home Directory Symlinks${RESET}"
    linkFiles "$fTKFilesDir" "$HOME" "."
    echo -e "${COLOR}Creating Completion Symlinks${RESET}"
    linkFiles "$fTKCompDir" "$HOME/.bash_completion.d"
    echo -e "${COLOR}Creating Vim Colorscheme Symlinks${RESET}"
    linkFiles "$fTKVimColorsDir" "$HOME/.vim/colors"
}

createToolsSymlinks() {
    [ -n "$fNoInstallTools" ] && return
    echo -e "${COLOR}Creating Tool Symlinks${RESET}"
    linkFiles "$fTKToolsDir" "$HOME/.usr/bin"
    echo -e "${COLOR}Creating template symlinks${RESET}"
    linkFiles "$fTKtemplateDir" "$HOME/Templates"
}

relinkSysCmds() {
    echo -e "${COLOR}Relinking System Commands${RESET}"
    linkFile "batcat" "$HOME/.usr/bin" "bat" "command"
    linkFile "fdfind" "$HOME/.usr/bin" "fd" "command"
    linkFile "bash" "/bin" "sh" "command"
}

createMacOSBashProfile() {
    echo -e "${COLOR}Creating macOS bash_profile${RESET}"
    linkFile "$fTKFilesDir/bash_profile" "$HOME" ".bash_profile"
}

setMacOSDefaultShell() {
    echo -e "${COLOR}Setting up Homebrew Bash as default shell${RESET}"
    [[ $(uname -s) != 'Darwin' ]] && return

    local HOMEBREW_BASH="/opt/homebrew/bin/bash"
    # Fallback for Intel Mac
    [ ! -x "$HOMEBREW_BASH" ] && HOMEBREW_BASH="/usr/local/bin/bash"

    if [ ! -x "$HOMEBREW_BASH" ]; then
        echo -e "${LIGHTYELLOW}Homebrew bash not found, skipping default shell setup${RESET}"
        return
    fi

    # Add to /etc/shells if not already there
    if ! grep -q "^${HOMEBREW_BASH}$" /etc/shells; then
        echo -e "${GREY}Adding ${HOMEBREW_BASH} to /etc/shells${RESET}"
        sudo sh -c "echo '$HOMEBREW_BASH' >> /etc/shells"
    else
        echo -e "${GREEN}✔${GREY} ${HOMEBREW_BASH} already in /etc/shells${RESET}"
    fi

    # Change default shell if not already set
    if [ "$SHELL" != "$HOMEBREW_BASH" ]; then
        echo -e "${GREY}Changing default shell to ${HOMEBREW_BASH}${RESET}"
        # Use sudo to avoid password prompt (requires passwordless sudo)
        sudo chsh -s "$HOMEBREW_BASH" "$USER"
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}✔${GREY} Default shell changed to Bash 5.x${RESET}"
            echo -e "${LIGHTYELLOW}Note: Please restart your terminal for the change to take effect.${RESET}"
        else
            echo -e "${RED}Failed to change default shell${RESET}"
        fi
    else
        echo -e "${GREEN}✔${GREY} Default shell is already ${HOMEBREW_BASH}${RESET}"
    fi
}

setLinuxDefaultShell() {
    echo -e "${COLOR}Setting up Linux default shell${RESET}"
    [[ $(uname -s) != 'Linux' ]] && return

    local BASH_PATH="/bin/bash"

    if [ ! -x "$BASH_PATH" ]; then
        echo -e "${LIGHTYELLOW}Bash not found, skipping default shell setup${RESET}"
        return
    fi

    # Change default shell if not already set
    if [ "$SHELL" != "$BASH_PATH" ]; then
        echo -e "${GREY}Setting up Bash as default shell${RESET}"
        echo -e "${GREY}Changing default shell to ${BASH_PATH}${RESET}"
        sudo chsh -s "$BASH_PATH"
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}✔${GREY} Default shell changed to Bash${RESET}"
            echo -e "${LIGHTYELLOW}Note: Please restart your terminal for the change to take effect.${RESET}"
        else
            echo -e "${RED}Failed to change default shell${RESET}"
        fi
    else
        echo -e "${GREEN}✔${GREY} Default shell is already ${BASH_PATH}${RESET}"
    fi
}

getCursorUserConfigDir() {
    case "$(uname -s)" in
        Darwin)
            echo "$HOME/Library/Application Support/Cursor/User"
            ;;
        Linux)
            echo "$HOME/.config/Cursor/User"
            ;;
        *)
            return 1
            ;;
    esac
}

getCursorRemoteSettingsPath() {
    echo "$HOME/.cursor-server/data/Machine/settings.json"
}

backupCursorSettings() {
    if [[ $(uname -s) != 'Darwin' ]]; then
        echo -e "${RED}Error: --cursor-backup is only supported on macOS.${RESET}"
        return 1
    fi
    echo -e "${COLOR}Backing up Cursor settings${RESET}"

    local cursorUserDir=
    local remoteSettingsPath=
    local processedCount=0
    local failedCount=0
    local status=0

    if ! cursorUserDir=$(getCursorUserConfigDir); then
        echo -e "${RED}Error: Unsupported OS for Cursor settings backup: $(uname -s)${RESET}"
        return 1
    fi

    syncFile "$cursorUserDir/settings.json" "$fTKCursorDir" "local.settings.json"
    _trackSyncResult $? processedCount failedCount

    syncFile "$cursorUserDir/keybindings.json" "$fTKCursorDir"
    _trackSyncResult $? processedCount failedCount

    remoteSettingsPath=$(getCursorRemoteSettingsPath)
    if [ -d "$HOME/.cursor-server" ]; then
        syncFile "$remoteSettingsPath" "$fTKCursorDir" "remote.settings.json"
        _trackSyncResult $? processedCount failedCount
    else
        echo -e "${LIGHTYELLOW}Warning: Cursor Server not found, skipping remote settings backup${RESET}"
    fi

    if [ $failedCount -gt 0 ]; then
        return 1
    fi

    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Cursor settings files were backed up${RESET}"
        return 1
    fi
}

restoreCursorSettings() {
    if [[ $(uname -s) != 'Darwin' ]]; then
        echo -e "${RED}Error: --cursor-restore is only supported on macOS.${RESET}"
        return 1
    fi
    echo -e "${COLOR}Restoring Cursor settings${RESET}"

    local cursorUserDir=
    local remoteSettingsPath=
    local processedCount=0
    local failedCount=0

    if ! cursorUserDir=$(getCursorUserConfigDir); then
        echo -e "${RED}Error: Unsupported OS for Cursor settings restore: $(uname -s)${RESET}"
        return 1
    fi

    syncFile "$fTKCursorLocalSettings" "$cursorUserDir" "settings.json"
    _trackSyncResult $? processedCount failedCount

    syncFile "$fTKCursorKeybindings" "$cursorUserDir"
    _trackSyncResult $? processedCount failedCount

    remoteSettingsPath=$(getCursorRemoteSettingsPath)
    if [ -d "$HOME/.cursor-server" ]; then
        syncFile "$fTKCursorRemoteSettings" "$(dirname "$remoteSettingsPath")" "settings.json"
        _trackSyncResult $? processedCount failedCount
    else
        echo -e "${LIGHTYELLOW}Warning: Cursor Server not found, skipping remote settings restore${RESET}"
    fi

    if [ $failedCount -gt 0 ]; then
        return 1
    fi

    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Cursor settings files were restored${RESET}"
        return 1
    fi
}

# _trackSyncResult <syncFile_status> <processed_nameref> <failed_nameref>
# Bumps the processed/failed counters based on syncFile's return code:
#   0|1 = processed (copied or already up to date), 3 = failed.
_trackSyncResult() {
    local -n _proc=$2
    local -n _failed=$3
    case "$1" in
        0|1) _proc=$((_proc + 1)) ;;
        3)   _failed=$((_failed + 1)) ;;
    esac
}

getClaudeCodeDir() { echo "$HOME/.claude"; }
getCodexDir()      { echo "$HOME/.codex"; }

linkClaudeMcpJson() {
    echo -e "${COLOR}Linking Claude .mcp.json${RESET}"
    linkFile "$fTKClaudeMcpJson" "$PWD" ".mcp.json"
}

getClaudeDesktopConfigDir() {
    case "$(uname -s)" in
        Darwin) echo "$HOME/Library/Application Support/Claude" ;;
        *) return 1 ;;
    esac
}

backupClaudeCodeSettings() {
    echo -e "${COLOR}Backing up Claude Code settings${RESET}"
    local srcDir=$(getClaudeCodeDir)
    local processedCount=0 failedCount=0

    if [ ! -d "$srcDir" ]; then
        echo -e "${LIGHTYELLOW}Warning: $srcDir not found, nothing to back up.${RESET}"
        return 0
    fi

    syncFile "$srcDir/settings.json"       "$fTKClaudeDir"
    _trackSyncResult $? processedCount failedCount
    syncFile "$srcDir/settings.local.json" "$fTKClaudeDir"
    _trackSyncResult $? processedCount failedCount
    syncFile "$srcDir/CLAUDE.md"           "$fTKClaudeDir"
    _trackSyncResult $? processedCount failedCount

    if [ $failedCount -gt 0 ]; then
        return 1
    fi
    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Claude Code settings files were backed up${RESET}"
        return 1
    fi
}

restoreClaudeCodeSettings() {
    echo -e "${COLOR}Restoring Claude Code settings${RESET}"
    local dstDir=$(getClaudeCodeDir)
    local processedCount=0 failedCount=0

    [ ! -d "$dstDir" ] && mkdir -p "$dstDir"

    syncFile "$fTKClaudeCodeSettings"      "$dstDir"
    _trackSyncResult $? processedCount failedCount
    syncFile "$fTKClaudeCodeLocalSettings" "$dstDir"
    _trackSyncResult $? processedCount failedCount
    syncFile "$fTKClaudeCodeMd"            "$dstDir"
    _trackSyncResult $? processedCount failedCount

    if [ $failedCount -gt 0 ]; then
        return 1
    fi
    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Claude Code settings files were restored${RESET}"
        return 1
    fi
}

backupClaudeDesktopSettings() {
    if [[ $(uname -s) != 'Darwin' ]]; then
        echo -e "${RED}Error: --claude-desktop-backup is only supported on macOS.${RESET}"
        return 1
    fi
    echo -e "${COLOR}Backing up Claude Desktop settings${RESET}"

    local srcDir=
    if ! srcDir=$(getClaudeDesktopConfigDir); then
        echo -e "${RED}Error: Unsupported OS for Claude Desktop backup: $(uname -s)${RESET}"
        return 1
    fi

    if [ ! -d "$srcDir" ]; then
        echo -e "${LIGHTYELLOW}Warning: Claude Desktop config directory $srcDir not found, nothing to back up.${RESET}"
        return 0
    fi

    local processedCount=0 failedCount=0
    syncFile "$srcDir/claude_desktop_config.json" "$fTKClaudeDir"
    _trackSyncResult $? processedCount failedCount

    if [ $failedCount -gt 0 ]; then
        return 1
    fi
    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Claude Desktop settings files were backed up${RESET}"
        return 1
    fi
}

restoreClaudeDesktopSettings() {
    if [[ $(uname -s) != 'Darwin' ]]; then
        echo -e "${RED}Error: --claude-desktop-restore is only supported on macOS.${RESET}"
        return 1
    fi
    echo -e "${COLOR}Restoring Claude Desktop settings${RESET}"

    local dstDir=
    if ! dstDir=$(getClaudeDesktopConfigDir); then
        echo -e "${RED}Error: Unsupported OS for Claude Desktop restore: $(uname -s)${RESET}"
        return 1
    fi

    [ ! -d "$dstDir" ] && mkdir -p "$dstDir"

    local processedCount=0 failedCount=0
    syncFile "$fTKClaudeDesktopConfig" "$dstDir"
    _trackSyncResult $? processedCount failedCount

    if [ $failedCount -gt 0 ]; then
        return 1
    fi
    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Claude Desktop settings files were restored${RESET}"
        return 1
    fi
}

backupCodexSettings() {
    echo -e "${COLOR}Backing up Codex settings${RESET}"
    local srcDir=$(getCodexDir)
    local processedCount=0 failedCount=0

    if [ ! -d "$srcDir" ]; then
        echo -e "${LIGHTYELLOW}Warning: $srcDir not found, nothing to back up.${RESET}"
        return 0
    fi

    syncFile "$srcDir/config.toml" "$fTKCodexDir"
    _trackSyncResult $? processedCount failedCount

    if [ $failedCount -gt 0 ]; then
        return 1
    fi
    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Codex settings files were backed up${RESET}"
        return 1
    fi
}

restoreCodexSettings() {
    echo -e "${COLOR}Restoring Codex settings${RESET}"
    local dstDir=$(getCodexDir)
    local processedCount=0 failedCount=0

    [ ! -d "$dstDir" ] && mkdir -p "$dstDir"

    syncFile "$fTKCodexConfig" "$dstDir"
    _trackSyncResult $? processedCount failedCount

    if [ $failedCount -gt 0 ]; then
        return 1
    fi
    if [ $processedCount -eq 0 ]; then
        echo -e "${RED}Error: No Codex settings files were restored${RESET}"
        return 1
    fi
}

createCursorCLISymlinks() {
    [ ! -d "$HOME/.cursor-server" ] && return
    echo -e "${COLOR}Creating Cursor CLI Symlinks${RESET}"
    linkFile "$fTKCursorDir/code" "$HOME/.local/bin"
    linkFile "$HOME/.local/bin/code" "$HOME/.local/bin" "cursor"
}

createDevToolSymlinks() {
    echo -e "${COLOR}Creating Dev Tool Symlinks${RESET}"
    # The directories are guaranteed to exist when this function is called.
    linkFile "$fTKClangdConfig" "$HOME/.config/clangd"
    linkFile "$fzfTabCompPath" "$HOME/.bash_completion.d" "fzf_tab_completion.bash"
    linkFile "$fzfBinPath" "$HOME/.usr/bin"
    linkFile "$fJCPath" "$HOME/.usr/bin"
    if [ -d "$HOME"/.vscode-server/data/Machine ]; then
        linkFile "$fMainDir"/assets/vscode/remote.settings.json "$HOME"/.vscode-server/data/Machine "settings.json"
    fi
}

createEssentialPaths() {
    local dirsToCheck=(
        "$fBackupDir"
        "$HOME/Downloads"
        "$HOME/Templates"
        "$HOME/Media"
        "$HOME/.vnc"
        "$HOME/.bash_completion.d"
        "$HOME/.usr/bin"
        "$HOME/.local/share/fonts"
        "$HOME/.config/bat/themes"
        "$HOME/.config/fontconfig/conf.d"
        "$HOME/.config/clangd"
    )

    for dir in "${dirsToCheck[@]}"; do
        if [ ! -d "$dir" ]; then
            echo -e "${LIGHTYELLOW}  Creating directory: ${BLUE}$dir${RESET}"
            mkdir -p "$dir"
            if [ $? -ne 0 ]; then
                echo -e "${RED}  Error: Failed to create directory $dir${RESET}"
                exit 1
            fi
        fi
    done

    cd "$fMainDir" || exit
}

# Download and extract a zip from a GitHub release URL.
# Sets GITHUB_RELEASE_EXTRACT_DIR to the path of the extracted directory.
# $1: display name (e.g. "Clangd", "Xray")
# $2: download URL
downloadGithubRelease() {
    local name="$1" downloadUrl="$2"
    GITHUB_RELEASE_EXTRACT_DIR=""

    if ! command -v jq &> /dev/null; then
        echo -e "${RED}Error: jq is required but not installed. Please install jq first.${RESET}"
        return 1
    fi

    echo -e "${LIGHTYELLOW}Downloading $name${RESET}"
    local fileName=$(basename "$downloadUrl")
    local downloadDst="$fDownloads/$fileName"
    if [ -f "$downloadDst" ]; then
        echo -e "${GREY}File $fileName already exists in $fDownloads, skipping download.${RESET}"
    else
        curl -Lo "$downloadDst" "$downloadUrl"
        if [ $? -ne 0 ]; then
            echo -e "${RED}Error: Failed to download $name${RESET}"
            return 1
        fi
    fi

    cd "$fDownloads" || exit 1
    local peekInfo=$(zipinfo -1 "$downloadDst" | head -n 1)
    local extractDir="$fDownloads/$(dirname "$peekInfo")"
    # If top-level entry is a file (no subdir), extract into a named directory
    if [[ "$extractDir" == "$fDownloads/." ]]; then
        extractDir="$fDownloads/${fileName%.zip}"
        if [ -d "$extractDir" ]; then
            echo -e "${GREY}Directory $extractDir already exists, skipping extraction.${RESET}"
        else
            mkdir -p "$extractDir"
            echo -e "${LIGHTYELLOW}Extracting $name${RESET}"
            unzip -o "$downloadDst" -d "$extractDir"
        fi
    else
        if [ -d "$extractDir" ]; then
            echo -e "${GREY}Directory $extractDir already exists, skipping extraction.${RESET}"
        else
            echo -e "${LIGHTYELLOW}Extracting $name${RESET}"
            unzip "$downloadDst"
            if [ ! -d "$extractDir" ]; then
                echo -e "${RED}Error: Failed to extract $name${RESET}"
                return 1
            fi
        fi
    fi

    echo -e "${GREEN}Successfully extracted to $extractDir${RESET}"
    GITHUB_RELEASE_EXTRACT_DIR="$extractDir"
}

installLatestGithubClangd() {
    echo -e "${COLOR}Checking for Github Clangd (Github Release)${RESET}"
    if [ -z "$fClangdUpdate" ] && command -v clangd &> /dev/null; then
        echo -e "${GREEN}✔${GREY} Clangd is already installed.${RESET}"
        printf "  "
        clangd --version | head -n 1 | sed 's/ (.*//'
        return 0
    fi

    # Github clangd is only available for x86_64
    if [ "$fArch" == "aarch64" ]; then
        echo -e "${LIGHTYELLOW}Github clangd is not available for $fArch architecture.${RESET}"
        echo -e "${LIGHTYELLOW}Installing clangd from apt package manager.${RESET}"
        sudo apt install clangd -y
        return
    fi

    if ! command -v jq &> /dev/null; then
        echo -e "${RED}Error: jq is required but not installed. Please install jq first.${RESET}"
        return 1
    fi

    local currentVersion="0.0.0"
    local clangdPath=$(command -v clangd 2>/dev/null)
    if [ -n "$clangdPath" ]; then
        currentVersion=$($clangdPath --version | head -n1 | grep -oP 'version \K[0-9]+\.[0-9]+\.[0-9]+' || echo "")
        echo -e "Current clangd version: ${BLUE}$currentVersion${RESET}"
    fi

    # Get the latest stable release version and download URL
    # 20.1.0
    # https://github.com/clangd/clangd/releases/download/20.1.0/clangd-linux-20.1.0.zip
    echo -e "${LIGHTYELLOW}Fetching latest Clangd binary information${RESET}"
    local output=$(curl -s https://api.github.com/repos/clangd/clangd/releases |
        jq -r '[.[] | select(.prerelease == false)] | .[0] |
               .name, (.assets[] | select(.name | contains("clangd-linux")) | .browser_download_url)')
    mapfile -t lines <<< "$output"
    local latestVersion="${lines[0]}"
    local downloadUrl="${lines[1]}"
    if [ -z "$latestVersion" ] || [ "$latestVersion" == "null" ]; then
        echo -e "${RED}Error: Failed to get latest version information${RESET}"
        return 1
    fi

    echo -e "Latest available clangd version: ${COLOR}$latestVersion${RESET}"
    if [ -n "$currentVersion" ]; then
        if [ "$(printf '%s\n' "$latestVersion" "$currentVersion" | sort -V -r | head -n1)" == "$currentVersion" ]; then
            echo -e "${GREY}No update needed. Current version is up to date.${RESET}"
            return 0
        fi
    fi

    downloadGithubRelease "Clangd" "$downloadUrl" || return 1

    local clangdBinary=$(find "$GITHUB_RELEASE_EXTRACT_DIR" -type f -name "clangd" -executable | head -n 1)
    if [ -z "$clangdBinary" ]; then
        echo -e "${RED}Error: Failed to find the clangd binary in the extracted directory${RESET}"
        return 1
    fi

    linkFile "$clangdBinary" "$HOME/.usr/bin"
}

# Install/update Xray and auto-configure a VLESS-REALITY server.
#
#   jc --xray [--xray-port PORT]
#
#   +----------------------------------+
#   | Download + install Xray binary   |
#   | Install geodata (geoip/geosite)  |
#   +----------------+-----------------+
#                    |
#                    v
#          +-------------------+
#          | System-level      |
#          | setup (/etc/xray) |
#          | + systemd service |
#          +---------+---------+
#                    |
#                    v
#          +---------+---------+
#          | Existing configs? |
#          +---------+---------+
#           /                 \
#         Yes                  No
#          |                    |
#          v                    |
#   +----------------+         |
#   | Prompt:        |         |
#   | 1) Keep        |         |
#   | 2) Regenerate  |         |
#   +-------+--------+         |
#    /             \            |
#   v               v          |
#  Keep         Regenerate     |
#   |           (rm old)       |
#   |               \          |
#   v                v         v
#  +----------+    +-------------------+
#  | Restart  |    | Generate UUID,    |
#  | service  |    |  x25519, shortId  |
#  | (binary  |    +---------+---------+
#  |  update) |              |
#  +----------+              v
#                  +-------------------+
#                  | Write config JSON |
#                  | VLESS-REALITY-    |
#                  |  <port>.json      |
#                  +---------+---------+
#                            |
#                            v
#                  +-------------------+
#                  | Restart service   |
#                  +---------+---------+
#                            |
#                            v
#                  +-------------------+
#                  | Detect public IP  |
#                  +---------+---------+
#                            |
#                            v
#                  +-------------------+
#                  | Print config info |
#                  | + share URL       |
#                  | + QR code         |
#                  +-------------------+
installXray() {
    echo -e "${COLOR}Checking for Xray (Github Release)${RESET}"
    if [ -z "$fXrayUpdate" ] && command -v xray &> /dev/null; then
        echo -e "${GREEN}✔${GREY} Xray is already installed.${RESET}"
        printf "  "
        xray version 2>/dev/null | head -n 1
        return 0
    fi

    local arch=${fArch:-$(uname -m)}
    local xrayArch
    case "$arch" in
        x86_64)  xrayArch="64" ;;
        aarch64) xrayArch="arm64-v8a" ;;
        *)
            echo -e "${RED}Error: Unsupported architecture for Xray: $arch${RESET}"
            return 1
            ;;
    esac

    local xrayOS
    case "$(uname -s)" in
        Darwin) xrayOS="macos" ;;
        *)      xrayOS="linux" ;;
    esac

    echo -e "${LIGHTYELLOW}Fetching latest Xray release information${RESET}"
    local output=$(curl -s https://api.github.com/repos/XTLS/Xray-core/releases/latest |
        jq -r '.tag_name')
    if [ -z "$output" ] || [ "$output" == "null" ]; then
        echo -e "${RED}Error: Failed to get latest Xray version${RESET}"
        return 1
    fi

    local latestVersion="$output"
    echo -e "Latest Xray version: ${COLOR}$latestVersion${RESET}"

    local downloadUrl="https://github.com/XTLS/Xray-core/releases/download/${latestVersion}/Xray-${xrayOS}-${xrayArch}.zip"
    downloadGithubRelease "Xray" "$downloadUrl" || return 1

    local xrayBinary="$GITHUB_RELEASE_EXTRACT_DIR/xray"
    if [ ! -f "$xrayBinary" ]; then
        echo -e "${RED}Error: xray binary not found in extracted directory${RESET}"
        return 1
    fi
    chmod +x "$xrayBinary"

    linkFile "$xrayBinary" "$HOME/.usr/bin"
    linkFile "$fTKToolsDir/xray-manager" "$HOME/.usr/bin"
    linkFile "$fTKCompDir/jx_completion.bash" "$HOME/.bash_completion.d"

    # Install geodata files
    local xrayShareDir="$HOME/.usr/share/xray"
    mkdir -p "$xrayShareDir"
    for dat in geoip.dat geosite.dat; do
        if [ -f "$GITHUB_RELEASE_EXTRACT_DIR/$dat" ]; then
            cp -f "$GITHUB_RELEASE_EXTRACT_DIR/$dat" "$xrayShareDir/"
            echo -e "${GREEN}✔${GREY} Installed $dat to $xrayShareDir${RESET}"
        fi
    done

    # Set up server environment and systemd service (Linux only)
    if [[ "$(uname -s)" != "Darwin" ]]; then
        if ! sudo -n true 2>/dev/null; then
            echo -e "${LIGHTYELLOW}System-level install requires sudo privileges.${RESET}"
            echo -e "  ${GREEN}1)${RESET} Enter sudo password and continue"
            echo -e "  ${GREEN}2)${RESET} Cancel"
            local choice
            read -rp "$(echo -e "${CYAN}▸${RESET} Enter choice [1-2]: ")" choice
            case "$choice" in
                1) ;;
                *) echo -e "${GREY}Cancelled.${RESET}"; return 0 ;;
            esac
        fi

        echo -e "${LIGHTYELLOW}Setting up system-level Xray environment...${RESET}"
        sudo mkdir -p /etc/xray/bin /etc/xray/conf /var/log/xray
        sudo cp -f "$xrayBinary" /etc/xray/bin/xray
        sudo chmod +x /etc/xray/bin/xray
        for dat in geoip.dat geosite.dat; do
            [[ -f "$GITHUB_RELEASE_EXTRACT_DIR/$dat" ]] && sudo cp -f "$GITHUB_RELEASE_EXTRACT_DIR/$dat" /etc/xray/bin/
        done
        local serviceFile="$fMainDir/assets/xray/xray.service"
        if [[ -f "$serviceFile" ]]; then
            sudo cp -f "$serviceFile" /etc/systemd/system/xray.service
            sudo systemctl daemon-reload
            sudo systemctl enable xray 2>/dev/null
            echo -e "${GREEN}✔${GREY} Systemd service installed and enabled${RESET}"
        fi

        # --- Auto-configure VLESS-REALITY and start service ---
        local xrayBin=/etc/xray/bin/xray
        local confDir=/etc/xray/conf
        local systemctlCmd="sudo systemctl"

        local generateConfig=true
        if ls "$confDir"/*.json &>/dev/null; then
            echo -e "\n${LIGHTYELLOW}Existing Xray config(s) found in $confDir:${RESET}"
            find "$confDir" -maxdepth 1 -name '*.json' -print0 2>/dev/null | while IFS= read -r -d '' f; do
                echo -e "  ${GREY}- $(basename "$f" .json)${RESET}"
            done
            echo -e "  ${GREEN}1)${RESET} Keep existing configs (restart service with updated binary)"
            echo -e "  ${GREEN}2)${RESET} Regenerate fresh config (removes existing configs)"
            local rerunChoice
            read -rp "$(echo -e "${CYAN}▸${RESET} Enter choice [1-2]: ")" rerunChoice
            case "$rerunChoice" in
                2)
                    sudo rm -f "$confDir"/*.json
                    ;;
                *)
                    generateConfig=false
                    ;;
            esac
        fi

        if [[ "$generateConfig" == true ]]; then
            local port="${fXrayPort:-443}"
            local sni="www.nvidia.com"
            local uuid=$("$xrayBin" uuid)
            local keypair=$("$xrayBin" x25519)
            local privateKey=$(echo "$keypair" | grep -i "private" | awk '{print $NF}')
            local publicKey=$(echo "$keypair" | grep -i "public" | awk '{print $NF}')
            if [[ -z "$uuid" || -z "$privateKey" || -z "$publicKey" ]]; then
                echo -e "${RED}Error: Failed to generate keys (uuid=$uuid, privateKey=${privateKey:+set}, publicKey=${publicKey:+set})${RESET}"
                echo -e "${GREY}xray x25519 output:${RESET}"
                echo "$keypair"
                return 1
            fi
            local shortId=$(openssl rand -hex 4)
            local configName="VLESS-REALITY-${port}"
            local configPath="$confDir/${configName}.json"

            local configJson
            configJson=$(cat << XEOF
{
  "inbounds": [
    {
      "port": $port,
      "protocol": "vless",
      "settings": {
        "clients": [
          {
            "id": "$uuid",
            "flow": "xtls-rprx-vision"
          }
        ],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "tcp",
        "security": "reality",
        "realitySettings": {
          "dest": "$sni:443",
          "serverNames": ["$sni"],
          "privateKey": "$privateKey",
          "shortIds": ["$shortId"]
        }
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls", "quic"],
        "routeOnly": true
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}
XEOF
)
            echo "$configJson" | sudo tee "$configPath" > /dev/null
            echo -e "${GREEN}✔${GREY} Config created: ${CYAN}$configName${RESET}"

            local testCmd="sudo $xrayBin run -test -confdir $confDir"
            if ! $testCmd 2>&1; then
                echo -e "${RED}✗ Xray config test failed${RESET}"
                return 1
            fi
            echo -e "${GREEN}✔${GREY} Config test passed${RESET}"

            $systemctlCmd restart xray
            sleep 1
            if $systemctlCmd is-active --quiet xray; then
                echo -e "${GREEN}✔${GREY} Xray service started${RESET}"
            else
                echo -e "${RED}✗ Xray service failed to start${RESET}"
                $systemctlCmd status xray --no-pager 2>&1 | tail -5
                echo -e "${GREY}Check full logs with: ${BLUE}sudo journalctl -u xray -n 20 --no-pager${RESET}"
            fi

            local ip="${fXrayServer}"
            if [[ -z "$ip" ]]; then
                ip=$(curl -4 -s --connect-timeout 5 https://one.one.one.one/cdn-cgi/trace 2>/dev/null | grep "ip=" | cut -d= -f2)
                [[ -z "$ip" ]] && ip=$(curl -4 -s --connect-timeout 5 https://ifconfig.me 2>/dev/null)
                [[ -z "$ip" ]] && ip=$(hostname -I | awk '{print $1}')
            fi

            # Persist server IP so jx info/url/qr uses the same address
            local ipFile="/etc/xray/.server_ip"
            echo "$ip" | sudo tee "$ipFile" > /dev/null

            local url="vless://${uuid}@${ip}:${port}?encryption=none&flow=xtls-rprx-vision&type=tcp&security=reality&sni=${sni}&fp=chrome&pbk=${publicKey}&sid=${shortId}#${configName}"

            echo
            echo -e "====================================================="
            echo -e "${CYAN}▸${RESET} ${BOLD}Config: ${CYAN}$configName${RESET}"
            echo -e "====================================================="
            echo -e "  ${GREY}Protocol:${RESET}    VLESS"
            echo -e "  ${GREY}Address:${RESET}     $ip"
            echo -e "  ${GREY}Port:${RESET}        $port"
            echo -e "  ${GREY}UUID:${RESET}        $uuid"
            echo -e "  ${GREY}Flow:${RESET}        xtls-rprx-vision"
            echo -e "  ${GREY}Security:${RESET}    reality"
            echo -e "  ${GREY}SNI:${RESET}         $sni"
            echo -e "  ${GREY}Fingerprint:${RESET} chrome"
            echo -e "  ${GREY}Public Key:${RESET}  $publicKey"
            echo -e "  ${GREY}Short ID:${RESET}    $shortId"
            echo -e "====================================================="
            echo -e "  ${GREY}URL:${RESET}"
            echo -e "  ${BLUE}$url${RESET}"
            echo -e "====================================================="

            echo
            if command -v qrencode &>/dev/null; then
                echo -e "${CYAN}▸${RESET} ${BOLD}QR Code:${RESET}"
                echo
                qrencode -t ANSIUTF8 -m 1 "$url"
            else
                local _pkgCmd="apt"; command -v dnf &>/dev/null && _pkgCmd="dnf"
                echo -e "${LIGHTYELLOW}Tip: Install qrencode for QR code display: ${BLUE}sudo $_pkgCmd install qrencode${RESET}"
                echo -e "${CYAN}▸${RESET} Online QR code:"
                echo -e "  ${BLUE}https://233boy.github.io/tools/qr.html#${url}${RESET}"
            fi
            echo
        else
            $systemctlCmd restart xray
            sleep 1
            if $systemctlCmd is-active --quiet xray; then
                echo -e "${GREEN}✔${GREY} Xray service restarted with updated binary${RESET}"
            else
                echo -e "${RED}✗ Xray service failed to restart${RESET}"
                $systemctlCmd status xray --no-pager 2>&1 | tail -5
                echo -e "${GREY}Check logs with: ${BLUE}$systemctlCmd status xray${RESET}"
            fi
        fi
    fi
}

removeXray() {
    echo -e "${COLOR}Removing Xray${RESET}"
    local removed=0
    local xrayBin="$HOME/.usr/bin/xray"
    local xrayShareDir="$HOME/.usr/share/xray"

    # Remove local binary symlink and geodata
    if [ -L "$xrayBin" ] || [ -f "$xrayBin" ]; then
        rm -f "$xrayBin"
        echo -e "${GREEN}✔${GREY} Removed $xrayBin${RESET}"
        ((removed++))
    fi
    if [ -d "$xrayShareDir" ]; then
        rm -rf "$xrayShareDir"
        echo -e "${GREEN}✔${GREY} Removed $xrayShareDir${RESET}"
        ((removed++))
    fi

    if [[ "$(uname -s)" == "Darwin" ]]; then
        :
    elif [[ -d /etc/xray ]]; then
        # System-level cleanup
        echo -e "${LIGHTYELLOW}Detected system-level install${RESET}"
        if systemctl is-active xray &>/dev/null; then
            sudo systemctl stop xray
            echo -e "${GREEN}✔${GREY} Stopped xray system service${RESET}"
            ((removed++))
        fi
        if [[ -f /etc/systemd/system/xray.service ]]; then
            sudo systemctl disable xray 2>/dev/null
            sudo rm -f /etc/systemd/system/xray.service
            sudo systemctl daemon-reload
            echo -e "${GREEN}✔${GREY} Removed system systemd service${RESET}"
            ((removed++))
        fi
        sudo rm -rf /etc/xray
        echo -e "${GREEN}✔${GREY} Removed /etc/xray${RESET}"
        ((removed++))
        if [[ -d /var/log/xray ]]; then
            sudo rm -rf /var/log/xray
            echo -e "${GREEN}✔${GREY} Removed /var/log/xray${RESET}"
            ((removed++))
        fi
    fi

    if [ $removed -eq 0 ]; then
        echo -e "${GREY}Xray is not installed.${RESET}"
    else
        echo -e "${GREEN}✔${GREY} Xray removed successfully.${RESET}"
    fi
}

# Install/configure a WireGuard VPN server with one client peer.
#
#   jc --wg [--wg-port PORT] [--wg-server IP] [--wg-client NAME]
#
#   +----------------------------------+
#   | Install wireguard + qrencode     |
#   +----------------+-----------------+
#                    |
#                    v
#          +-------------------+
#          | Enable IP forward |
#          | (sysctl)          |
#          +---------+---------+
#                    |
#                    v
#          +---------+---------+
#          | Existing wg0.conf?|
#          +---------+---------+
#           /                 \
#         Yes                  No
#          |                    |
#          v                    |
#   +----------------+         |
#   | Prompt:        |         |
#   | 1) Keep        |         |
#   | 2) Regenerate  |         |
#   +-------+--------+         |
#    /             \            |
#   v               v          |
#  Keep         Regenerate     |
#   |           (rm old)       |
#   |               \          |
#   v                v         v
#  +----------+    +-------------------+
#  | Restart  |    | Generate server & |
#  | service  |    |  client key pairs |
#  +----------+    +---------+---------+
#                            |
#                            v
#                  +-------------------+
#                  | Write wg0.conf    |
#                  | + client conf     |
#                  +---------+---------+
#                            |
#                            v
#                  +-------------------+
#                  | Enable & start    |
#                  | wg-quick@wg0      |
#                  +---------+---------+
#                            |
#                            v
#                  +-------------------+
#                  | Print client conf |
#                  | + QR code         |
#                  +-------------------+
installWireguard() {
    echo -e "${COLOR}Checking for WireGuard${RESET}"

    if [[ "$(uname -s)" == "Darwin" ]]; then
        echo -e "${RED}Error: WireGuard server setup is only supported on Linux${RESET}"
        return 1
    fi

    if [ -z "$fWireguardUpdate" ] && command -v wg &> /dev/null && [[ -f /etc/wireguard/wg0.conf ]]; then
        echo -e "${GREEN}✔${GREY} WireGuard is already installed and configured.${RESET}"
        sudo wg show wg0 2>/dev/null | head -5
        return 0
    fi

    if ! sudo -n true 2>/dev/null; then
        echo -e "${LIGHTYELLOW}WireGuard installation requires sudo privileges.${RESET}"
        echo -e "  ${GREEN}1)${RESET} Enter sudo password and continue"
        echo -e "  ${GREEN}2)${RESET} Cancel"
        local choice
        read -rp "$(echo -e "${CYAN}▸${RESET} Enter choice [1-2]: ")" choice
        case "$choice" in
            1) ;;
            *) echo -e "${GREY}Cancelled.${RESET}"; return 0 ;;
        esac
    fi

    echo -e "${LIGHTYELLOW}Installing WireGuard packages...${RESET}"
    local distro=$(detectDistroFamily)
    if [[ "$distro" == "fedora" ]]; then
        sudo dnf install -y wireguard-tools qrencode >/dev/null 2>&1
    else
        sudo apt-get update -qq
        sudo apt-get install -y wireguard wireguard-tools qrencode >/dev/null 2>&1
    fi
    if ! command -v wg &> /dev/null; then
        echo -e "${RED}Error: WireGuard installation failed${RESET}"
        return 1
    fi
    echo -e "${GREEN}✔${GREY} WireGuard packages installed${RESET}"

    # Enable IP forwarding
    if ! grep -q '^net.ipv4.ip_forward=1' /etc/sysctl.conf 2>/dev/null; then
        echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf > /dev/null
    fi
    sudo sysctl -w net.ipv4.ip_forward=1 > /dev/null 2>&1
    echo -e "${GREEN}✔${GREY} IP forwarding enabled${RESET}"

    local port="${fWireguardPort:-51820}"
    local clientName="${fWireguardClientName:-client1}"
    local subnet="10.66.66"
    local serverAddr="${subnet}.1/24"
    local clientAddr="${subnet}.2/32"
    local dnsServer="1.1.1.1, 8.8.8.8"

    sudo mkdir -p /etc/wireguard/clients
    sudo chmod 700 /etc/wireguard

    local generateConfig=true
    if [[ -f /etc/wireguard/wg0.conf ]]; then
        echo -e "\n${LIGHTYELLOW}Existing WireGuard config found: /etc/wireguard/wg0.conf${RESET}"
        echo -e "  ${GREEN}1)${RESET} Keep existing config (restart service)"
        echo -e "  ${GREEN}2)${RESET} Regenerate fresh config (removes existing keys & config)"
        local rerunChoice
        read -rp "$(echo -e "${CYAN}▸${RESET} Enter choice [1-2]: ")" rerunChoice
        case "$rerunChoice" in
            2)
                sudo systemctl stop wg-quick@wg0 2>/dev/null
                sudo rm -f /etc/wireguard/wg0.conf
                sudo rm -f /etc/wireguard/server_private.key /etc/wireguard/server_public.key
                sudo rm -rf /etc/wireguard/clients
                sudo mkdir -p /etc/wireguard/clients
                ;;
            *)
                generateConfig=false
                ;;
        esac
    fi

    if [[ "$generateConfig" == true ]]; then
        # Generate server key pair
        local serverPrivKey=$(wg genkey)
        local serverPubKey=$(echo "$serverPrivKey" | wg pubkey)
        echo "$serverPrivKey" | sudo tee /etc/wireguard/server_private.key > /dev/null
        echo "$serverPubKey"  | sudo tee /etc/wireguard/server_public.key > /dev/null
        sudo chmod 600 /etc/wireguard/server_private.key

        # Generate client key pair
        local clientPrivKey=$(wg genkey)
        local clientPubKey=$(echo "$clientPrivKey" | wg pubkey)
        local clientPsk=$(wg genpsk)

        # Detect default network interface
        local netIf=$(ip route show default 2>/dev/null | awk '{print $5}' | head -1)
        if [[ -z "$netIf" ]]; then
            netIf="eth0"
            echo -e "${LIGHTYELLOW}Warning: Could not detect default interface, using ${netIf}${RESET}"
        fi

        # Write server config
        sudo tee /etc/wireguard/wg0.conf > /dev/null << WGEOF
[Interface]
Address = $serverAddr
ListenPort = $port
PrivateKey = $serverPrivKey
PostUp = iptables -t nat -A POSTROUTING -o $netIf -j MASQUERADE; iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A FORWARD -o wg0 -j ACCEPT
PostDown = iptables -t nat -D POSTROUTING -o $netIf -j MASQUERADE; iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -o wg0 -j ACCEPT

[Peer]
# $clientName
PublicKey = $clientPubKey
PresharedKey = $clientPsk
AllowedIPs = ${subnet}.2/32
WGEOF
        sudo chmod 600 /etc/wireguard/wg0.conf
        echo -e "${GREEN}✔${GREY} Server config created: /etc/wireguard/wg0.conf${RESET}"

        local ip="${fWireguardServer}"
        if [[ -z "$ip" ]]; then
            ip=$(curl -4 -s --connect-timeout 5 https://one.one.one.one/cdn-cgi/trace 2>/dev/null | grep "ip=" | cut -d= -f2)
            [[ -z "$ip" ]] && ip=$(curl -4 -s --connect-timeout 5 https://ifconfig.me 2>/dev/null)
            [[ -z "$ip" ]] && ip=$(hostname -I | awk '{print $1}')
        fi

        # Build client config
        local clientConf="[Interface]
Address = $clientAddr
DNS = $dnsServer
PrivateKey = $clientPrivKey

[Peer]
PublicKey = $serverPubKey
PresharedKey = $clientPsk
Endpoint = ${ip}:${port}
AllowedIPs = 0.0.0.0/0, ::/0
PersistentKeepalive = 25"

        # Save client config
        local clientConfPath="/etc/wireguard/clients/${clientName}.conf"
        echo "$clientConf" | sudo tee "$clientConfPath" > /dev/null
        sudo chmod 600 "$clientConfPath"
        echo -e "${GREEN}✔${GREY} Client config saved: ${CYAN}$clientConfPath${RESET}"

        # Enable and start the service
        sudo systemctl enable wg-quick@wg0 2>/dev/null
        sudo systemctl restart wg-quick@wg0
        sleep 1
        if sudo systemctl is-active --quiet wg-quick@wg0; then
            echo -e "${GREEN}✔${GREY} wg-quick@wg0 service started${RESET}"
        else
            echo -e "${RED}✗ wg-quick@wg0 service failed to start${RESET}"
            sudo systemctl status wg-quick@wg0 --no-pager 2>&1 | tail -5
            echo -e "${GREY}Check full logs with: ${BLUE}sudo journalctl -u wg-quick@wg0 -n 20 --no-pager${RESET}"
        fi

        # Allow port through firewall if active
        if command -v ufw &>/dev/null && sudo ufw status | grep -qw "active"; then
            sudo ufw allow "${port}/udp" > /dev/null 2>&1
            echo -e "${GREEN}✔${GREY} UFW rule added: allow ${port}/udp${RESET}"
        elif command -v firewall-cmd &>/dev/null && sudo firewall-cmd --state 2>/dev/null | grep -q running; then
            sudo firewall-cmd --permanent --add-port="${port}/udp" > /dev/null 2>&1
            sudo firewall-cmd --reload > /dev/null 2>&1
            echo -e "${GREEN}✔${GREY} firewalld rule added: allow ${port}/udp${RESET}"
        fi

        # Print summary
        echo
        echo -e "====================================================="
        echo -e "${CYAN}▸${RESET} ${BOLD}WireGuard Server${RESET}"
        echo -e "====================================================="
        echo -e "  ${GREY}Endpoint:${RESET}        ${ip}:${port}"
        echo -e "  ${GREY}Server Address:${RESET}  $serverAddr"
        echo -e "  ${GREY}Server PubKey:${RESET}   $serverPubKey"
        echo -e "  ${GREY}Interface:${RESET}       $netIf"
        echo -e "====================================================="
        echo -e "${CYAN}▸${RESET} ${BOLD}Client: ${CYAN}$clientName${RESET}"
        echo -e "====================================================="
        echo -e "  ${GREY}Address:${RESET}         $clientAddr"
        echo -e "  ${GREY}DNS:${RESET}             $dnsServer"
        echo -e "  ${GREY}AllowedIPs:${RESET}      0.0.0.0/0, ::/0"
        echo -e "  ${GREY}Config file:${RESET}     $clientConfPath"
        echo -e "====================================================="
        echo -e "  ${GREY}Client config:${RESET}"
        echo
        echo -e "${BLUE}$clientConf${RESET}"
        echo
        echo -e "====================================================="

        echo
    else
        sudo systemctl restart wg-quick@wg0
        sleep 1
        if sudo systemctl is-active --quiet wg-quick@wg0; then
            echo -e "${GREEN}✔${GREY} wg-quick@wg0 service restarted${RESET}"
        else
            echo -e "${RED}✗ wg-quick@wg0 service failed to restart${RESET}"
            sudo systemctl status wg-quick@wg0 --no-pager 2>&1 | tail -5
            echo -e "${GREY}Check logs with: ${BLUE}sudo journalctl -u wg-quick@wg0 -n 20 --no-pager${RESET}"
        fi
    fi
}

removeWireguard() {
    echo -e "${COLOR}Removing WireGuard${RESET}"
    local removed=0

    if sudo systemctl is-active --quiet wg-quick@wg0 2>/dev/null; then
        sudo systemctl stop wg-quick@wg0
        echo -e "${GREEN}✔${GREY} Stopped wg-quick@wg0 service${RESET}"
        ((removed++))
    fi
    if sudo systemctl is-enabled --quiet wg-quick@wg0 2>/dev/null; then
        sudo systemctl disable wg-quick@wg0 2>/dev/null
        echo -e "${GREEN}✔${GREY} Disabled wg-quick@wg0 service${RESET}"
        ((removed++))
    fi

    if [[ -d /etc/wireguard ]]; then
        sudo rm -rf /etc/wireguard
        echo -e "${GREEN}✔${GREY} Removed /etc/wireguard${RESET}"
        ((removed++))
    fi

    # Remove firewall rules if present
    if command -v ufw &>/dev/null && sudo ufw status | grep -qw "active"; then
        sudo ufw delete allow 51820/udp > /dev/null 2>&1
    elif command -v firewall-cmd &>/dev/null && sudo firewall-cmd --state 2>/dev/null | grep -q running; then
        sudo firewall-cmd --permanent --remove-port=51820/udp > /dev/null 2>&1
        sudo firewall-cmd --reload > /dev/null 2>&1
    fi

    # Revert IP forwarding only if no other tunnel software needs it
    if grep -q '^net.ipv4.ip_forward=1' /etc/sysctl.conf 2>/dev/null; then
        if ! command -v xray &>/dev/null && ! ip link show wg0 &>/dev/null; then
            sudo sed -i '/^net.ipv4.ip_forward=1/d' /etc/sysctl.conf
            sudo sysctl -w net.ipv4.ip_forward=0 > /dev/null 2>&1
            echo -e "${GREEN}✔${GREY} Reverted IP forwarding${RESET}"
            ((removed++))
        fi
    fi

    if [ $removed -eq 0 ]; then
        echo -e "${GREY}WireGuard is not installed.${RESET}"
    else
        echo -e "${GREEN}✔${GREY} WireGuard removed successfully.${RESET}"
    fi
}

createFirstTimeFile() {
    [ -f "$fFirstTimeFile" ] && return
    touch "$fFirstTimeFile"
}

installLatestGitLfs() {
    echo -e "${COLOR}Checking for Git LFS (PackageCloud)${RESET}"

    if [ -z "$fGitLfsUpdate" ] && command -v git-lfs &>/dev/null; then
        local lfsPolicy
        lfsPolicy=$(apt-cache policy git-lfs)
        local installedVersion candidateVersion
        installedVersion=$(echo "$lfsPolicy" | grep "Installed:" | awk '{print $2}')
        candidateVersion=$(echo "$lfsPolicy" | grep "Candidate:" | awk '{print $2}')

        if [ "$installedVersion" != "(none)" ] && [ "$installedVersion" == "$candidateVersion" ]; then
            if echo "$lfsPolicy" | grep -q "packagecloud.io"; then
                echo -e "${GREEN}✔${GREY} Git LFS (from PackageCloud) is already installed and up-to-date.${RESET}"
                printf "  "
                git-lfs --version | head -n 1
                return 0
            fi
        fi
    fi

    echo -e "${LIGHTYELLOW}Proceeding with Git LFS installation/update from PackageCloud...${RESET}"

    # 1. Add the Git LFS repository
    echo -e "${LIGHTYELLOW}Checking for Git LFS repository (packagecloud.io)...${RESET}"
    if grep -qr "packagecloud.io/github/git-lfs" /etc/apt/sources.list /etc/apt/sources.list.d/ 2>/dev/null; then
        echo -e "${GREEN}✔${GREY} Git LFS repository already configured.${RESET}"
    else
        echo -e "${LIGHTYELLOW}Adding the Git LFS repository script from packagecloud.io...${RESET}"
        if ! curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash; then
            echo -e "${RED}Error: Failed to add Git LFS repository. Aborting.${RESET}"
            return 1
        fi
        echo -e "${GREEN}Git LFS repository added successfully.${RESET}"
    fi

    # 2. Create the preference file to prioritize PackageCloud Git LFS
    local preferenceFilePath="/etc/apt/preferences.d/git-lfs-ppa-priority"
    local preferenceContent
    preferenceContent=$(cat <<'EOF'
Package: git-lfs
Pin: origin packagecloud.io
Pin-Priority: 1001

Package: git-lfs
Pin: release o=Ubuntu*
Pin-Priority: -1
EOF
)
    echo -e "${LIGHTYELLOW}Setting up APT preferences to prioritize Git LFS from PackageCloud...${RESET}"
    if [ -f "$preferenceFilePath" ] && cmp -s <(echo "$preferenceContent") "$preferenceFilePath"; then
        echo -e "${GREY}APT preference file '$preferenceFilePath' already exists and is correctly configured.${RESET}"
    else
        echo "$preferenceContent" | sudo tee "$preferenceFilePath" > /dev/null
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}APT preference file '$preferenceFilePath' created/updated successfully.${RESET}"
        else
            echo -e "${RED}Failed to create/update APT preference file '$preferenceFilePath'. Aborting.${RESET}"
            return 1
        fi
    fi

    # 3. Update package list and install
    echo -e "${LIGHTYELLOW}Updating package lists...${RESET}"
    if ! sudo apt update; then
        echo -e "${RED}Error: Failed to update apt package list. Aborting.${RESET}"
        return 1
    fi

    echo -e "${LIGHTYELLOW}Installing Git LFS...${RESET}"
    if ! sudo DEBIAN_FRONTEND=noninteractive apt install -y git-lfs; then
        echo -e "${RED}Error: Failed to install git-lfs. Aborting.${RESET}"
        return 1
    fi
    echo -e "${GREEN}Git LFS installed successfully.${RESET}"

    # 4. Initialize Git LFS for the user
    echo -e "${LIGHTYELLOW}Running 'git lfs install' to initialize Git LFS...${RESET}"
    if git lfs install; then
        echo -e "${GREEN}Git LFS initialized successfully for the current user.${RESET}"
    else
        echo -e "${RED}Warning: 'git lfs install' command failed. You may need to run it manually.${RESET}"
    fi
    echo -e "${GREEN}--- Git LFS Installation Process Completed ---${RESET}"
    git-lfs --version
    return 0
}

installLatestPPaDocker() {
    echo -e "${COLOR}Checking for Docker${RESET}"
    if command -v docker &> /dev/null && [ -z "$fDockerUpdate" ]; then
        echo -e "${GREEN}✔${GREY} Docker is already installed.${RESET}"
        printf "  "
        docker --version
        return 0
    fi

    # 1. Uninstall old versions
    echo -e "${LIGHTYELLOW}Uninstalling old Docker versions (if any)...${RESET}"
    sudo apt-get remove -y docker docker-engine docker.io containerd runc > /dev/null 2>&1
    sudo apt-get autoremove -y > /dev/null 2>&1
    echo -e "${GREY}Old versions uninstalled/autoremoved (if any existed).${RESET}"

    # 2. Set up the repository
    echo -e "${LIGHTYELLOW}Setting up Docker repository...${RESET}"
    if ! sudo apt-get update; then
        echo -e "${RED}Failed to update apt package list.${RESET}"
        exit 1
    fi

    if [ ! -d /etc/apt/keyrings ] && ! sudo install -m 0755 -d /etc/apt/keyrings; then
        echo -e "${RED}Failed to create /etc/apt/keyrings directory.${RESET}"
        exit 1
    fi

    # Step 2a: Add Docker's official GPG key
    local dockerGpgKey="/etc/apt/keyrings/docker.gpg"
    if [ -f "$dockerGpgKey" ]; then
        echo -e "${GREEN}✔${GREY} Docker GPG key already exists.${RESET}"
    else
        echo -e "${LIGHTYELLOW}Downloading Docker's official GPG key...${RESET}"
        # Download Docker's official GPG key
        if ! curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o "$dockerGpgKey"; then
            echo -e "${RED}Failed to download or dearmor Docker GPG key.${RESET}"
            exit 1
        fi
        if ! sudo chmod a+r "$dockerGpgKey"; then
        echo -e "${RED}Failed to set permissions for Docker GPG key.${RESET}"
        exit 1
    fi
        echo -e "${GREEN}Docker GPG key downloaded and configured successfully.${RESET}"
    fi

    # Step 2b: Add the Docker repository to Apt sources.
    # This command creates the repository source file and points to Docker's official repository.
    # The `signed-by` option tells apt to verify packages from this repo using the key we just downloaded.
    # This now uses the official recommended method from Docker's documentation.
    if ! echo \
      "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
      $(lsb_release -cs) stable" | \
      sudo tee /etc/apt/sources.list.d/docker.list > /dev/null; then
        echo -e "${RED}Failed to add Docker repository to apt sources.${RESET}"
        exit 1
    fi
    echo -e "${GREEN}Docker repository set up successfully.${RESET}"

    # Step 3: Install Docker Engine.
    echo -e "${LIGHTYELLOW}Updating package list and installing Docker Engine...${RESET}"
    if ! sudo apt-get update; then
        echo -e "${RED}Failed to update apt package list after adding Docker repo.${RESET}"
        exit 1
    fi
    if ! sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin; then
        echo -e "${RED}Failed to install Docker Engine packages.${RESET}"
        exit 1
    fi
    echo -e "${GREEN}Docker Engine installed successfully.${RESET}"

    # Step 4: Verify installation by running the hello-world container.
    echo -e "${LIGHTYELLOW}Verifying Docker installation by running hello-world...${RESET}"
    if sudo docker run hello-world; then
        echo -e "${GREEN}Docker hello-world container ran successfully.${RESET}"
    else
        echo -e "${RED}Docker hello-world container failed to run. Docker might be installed but requires attention.${RESET}"
    fi

    # Step 5: Post-installation steps (run Docker as a non-root user).
    echo -e "${LIGHTYELLOW}Configuring Docker to run without sudo for current user ($USER)...${RESET}"
    # Create the 'docker' group if it doesn't exist.
    if ! getent group docker > /dev/null; then
        echo -e "${GREY}Docker group does not exist, creating it...${RESET}"
        if ! sudo groupadd docker; then
            echo -e "${RED}Failed to create 'docker' group. You may need to do this manually.${RESET}"
        else
            echo -e "${GREEN}'docker' group created.${RESET}"
        fi
    else
        echo -e "${GREY}'docker' group already exists.${RESET}"
    fi

    # Add the current user to the 'docker' group.
    if getent group docker > /dev/null; then
        if sudo usermod -aG docker "$USER"; then
            echo -e "${GREEN}User '$USER' added to the 'docker' group.${RESET}"
            echo -e "${BOLD}${MAGENTA}→ Run 'newgrp docker' to apply the change immediately.${RESET}"
            echo -e "${BOLD}${MAGENTA}→ For Cursor/VSCode users: Kill the remote server and reload the window so the container tools extension can access /run/docker.sock${RESET}"
        else
            echo -e "${RED}Failed to add user $USER to the 'docker' group. You may need to do this manually (e.g., sudo usermod -aG docker \"\$USER\").${RESET}"
        fi
    else
        echo -e "${RED}Cannot add user to 'docker' group as the group does not exist or could not be created.${RESET}"
    fi

    echo -e "${GREEN}Docker installation and basic configuration process completed.${RESET}"
}

installLatestRimePinyin() {
    # Skip if not first time and not explicitly requested
    [ -f "$fFirstTimeFile" ] && [ -z "$fChinesePinyinUpdate" ] && return

    echo -e "${COLOR}Checking Rime Pinyin Input Method${RESET}"

    # Dispatch to macOS-specific function if on Darwin (only when --chinese-pinyin)
    if [[ $(uname -s) == 'Darwin' ]]; then
        if [ -n "$fChinesePinyinUpdate" ]; then
            installRimeMacOS
            return $?
        fi
        return 0
    fi

    if [ -z "$fChinesePinyinUpdate" ]; then
        for cmd in fcitx5 fcitx; do
            if command -v "${cmd}-configtool" &>/dev/null; then
                echo -e "${GREEN}✔${GREY} Rime Pinyin input method is already installed.${RESET}"
                printf "  "
                "$cmd" --version
                return 0
            fi
        done
    fi

    echo -e "${LIGHTYELLOW}Updating package lists...${RESET}"
    if ! sudo apt update; then
        echo -e "${RED}Failed to update apt package list. Aborting Rime installation.${RESET}"
        return 1
    fi

    local fcitxXProfilePath=$fMainDir/assets/rime/fcitx5.xprofile
    local rimeDefaultCustomYaml=$fMainDir/assets/rime/default.custom.yaml
    local localRimePath="$HOME/.local/share/fcitx5/rime"
    # --- Attempt Fcitx5-Rime first ---
    echo -e "${COLOR}Checking for Fcitx5-Rime availability...${RESET}"
    if apt-cache show fcitx5-rime > /dev/null 2>&1; then
        echo -e "${GREEN}Fcitx5-Rime (fcitx5-rime) appears to be available. Attempting installation.${RESET}"
        local packagesToInstallFcitx5=(
            fcitx5
            fcitx5-rime
            fcitx5-chinese-addons # Provides general Chinese support, dictionaries, etc.
            # fcitx5-configtool     # GUI configuration tool (e.g., fcitx5-config-qt)
            fcitx5-config-qt      # GUI configuration tool
            im-config             # Input method configuration tool (sets fcitx5 as default)
        )

        # Link the xprofile file
        linkFile "$fcitxXProfilePath" "$HOME" .xprofile
        linkFile "$rimeDefaultCustomYaml" "$localRimePath" default.custom.yaml
        echo -e "${LIGHTYELLOW}Installing Fcitx5 packages: ${packagesToInstallFcitx5[*]}${RESET}"
        if sudo DEBIAN_FRONTEND=noninteractive apt install -y "${packagesToInstallFcitx5[@]}"; then
            echo -e "${GREEN}Successfully installed Fcitx5 and Rime packages.${RESET}"
            echo -e "${LIGHTYELLOW}Setting fcitx5 as the default input method system-wide using im-config...${RESET}"
            if sudo im-config -n fcitx5; then
                echo -e "${GREEN}Successfully configured fcitx5 as the default input method via im-config.${RESET}"
                echo -e "${GREY}(im-config handles setting environment variables like XMODIFIERS, GTK_IM_MODULE, QT_IM_MODULE for graphical sessions)${RESET}"
            else
                echo -e "${RED}Failed to set fcitx5 as the default input method using im-config.${RESET}"
                echo -e "${LIGHTYELLOW}You might need to run 'im-config' (as a regular user, not sudo) to select fcitx5, or configure it via your desktop environment's settings.${RESET}"
                echo -e "${LIGHTYELLOW}Alternatively, for X11 sessions, ensure these lines are in your ~/.xprofile or similar (e.g., ~/.profile, ~/.xinitrc):${RESET}"
                echo -e "${LIGHTYELLOW}  export GTK_IM_MODULE=fcitx5${RESET}"
                echo -e "${LIGHTYELLOW}  export QT_IM_MODULE=fcitx5${RESET}"
                echo -e "${LIGHTYELLOW}  export XMODIFIERS=@im=fcitx5${RESET}"
            fi

            echo -e "${GREEN}Fcitx5-Rime installation and basic configuration process completed.${RESET}"
            echo -e "${BOLD}${MAGENTA}IMPORTANT: A system REBOOT or RE-LOGIN is REQUIRED for all changes to take full effect.${RESET}"
            echo -e "${LIGHTYELLOW}After rebooting/re-logging in:${RESET}"
            echo -e "${LIGHTYELLOW}1. Fcitx5 should start automatically. If not, add 'fcitx5' to your session's startup applications.${RESET}"
            echo -e "${LIGHTYELLOW}2. Open 'Fcitx 5 Configuration' (command: ${BLUE}fcitx5-configtool${RESET}).${RESET}"
            echo -e "${LIGHTYELLOW}3. In the 'Input Method' tab, ensure 'Rime' is in the list of active input methods. ${RESET}"
            echo -e "${LIGHTYELLOW}   If not, click the '+' button, uncheck 'Only Show Current Language' if needed, find 'Rime', and add it.${RESET}"
            echo -e "${LIGHTYELLOW}4. You can switch input methods using the configured hotkey (often Ctrl+Space or Super+Space). Check 'Global Options' tab in fcitx5-configtool for 'Trigger Input Method'.${RESET}"
            echo -e "${LIGHTYELLOW}5. For Rime specific settings (e.g., traditional Chinese, fuzzy pinyin), create/edit files in ${BLUE}~/.local/share/fcitx5/rime/${RESET} (e.g., default.custom.yaml). Refer to Rime documentation.${RESET}"
            return 0
        else
            echo -e "${RED}Failed to install Fcitx5-Rime packages. Will try Fcitx4-Rime as a fallback.${RESET}"
        fi
    else
        echo -e "${LIGHTYELLOW}Fcitx5-Rime (fcitx5-rime) not found in official repositories. Checking for Fcitx4-Rime.${RESET}"
    fi

    # --- Attempt Fcitx4-Rime (fcitx) if Fcitx5-Rime was not available or failed ---
    echo -e "${COLOR}Checking for Fcitx4-Rime (fcitx-rime) availability...${RESET}"
    if apt-cache show fcitx-rime > /dev/null 2>&1; then
        echo -e "${GREEN}Fcitx4-Rime (fcitx-rime) appears to be available. Attempting installation.${RESET}"
        local packagesToInstallFcitx4=(
            fcitx
            fcitx-rime
            fcitx-table-all       # Common tables for fcitx4, includes pinyin etc.
            fcitx-frontend-gtk3
            fcitx-frontend-qt5    # Or fcitx-libs-qt5 on older systems
            fcitx-config-gtk      # GUI config tool for fcitx4 (or fcitx-configtool)
            im-config
        )

        # Link .xprofile to ~/.xprofile
        fcitxXProfilePath=$fMainDir/assets/rime/fcitx.xprofile
        linkFile "$fcitxXProfilePath" "$HOME" .xprofile
        localRimePath="$HOME/.config/fcitx/rime"
        linkFile "$rimeDefaultCustomYaml" "$localRimePath" default.custom.yaml
        echo -e "${LIGHTYELLOW}Installing Fcitx4 packages: ${packagesToInstallFcitx4[*]}${RESET}"
        if sudo DEBIAN_FRONTEND=noninteractive apt install -y "${packagesToInstallFcitx4[@]}"; then
            echo -e "${GREEN}Successfully installed Fcitx4 and Rime packages.${RESET}"

            echo -e "${LIGHTYELLOW}Setting fcitx as the default input method system-wide using im-config...${RESET}"
            if sudo im-config -n fcitx; then # Note: 'fcitx' for fcitx4
                echo -e "${GREEN}Successfully configured fcitx as the default input method via im-config.${RESET}"
            else
                echo -e "${RED}Failed to set fcitx as the default input method using im-config.${RESET}"
                echo -e "${LIGHTYELLOW}You might need to run 'im-config' (as a regular user) to select fcitx, or configure it via your desktop environment's settings.${RESET}"
                echo -e "${LIGHTYELLOW}Alternatively, for X11 sessions, ensure these lines are in your ~/.xprofile or similar:${RESET}"
                echo -e "${LIGHTYELLOW}  export GTK_IM_MODULE=fcitx${RESET}"
                echo -e "${LIGHTYELLOW}  export QT_IM_MODULE=fcitx${RESET}"
                echo -e "${LIGHTYELLOW}  export XMODIFIERS=@im=fcitx${RESET}"
            fi

            echo -e "${GREEN}Fcitx4-Rime installation and basic configuration process completed.${RESET}"
            echo -e "${BOLD}${MAGENTA}IMPORTANT: A system REBOOT or RE-LOGIN is REQUIRED for all changes to take full effect.${RESET}"
            echo -e "${LIGHTYELLOW}After rebooting/re-logging in:${RESET}"
            echo -e "${LIGHTYELLOW}1. Fcitx should start automatically. If not, add 'fcitx' to your session's startup applications.${RESET}"
            echo -e "${LIGHTYELLOW}2. Open 'Fcitx Configuration' (command: ${BLUE}fcitx-config-gtk${RESET} or ${BLUE}fcitx-configtool${RESET}).${RESET}"
            echo -e "${LIGHTYELLOW}3. Ensure 'Rime' is in the list of active input methods. If not, add it.${RESET}"
            echo -e "${LIGHTYELLOW}4. Switch input methods using the configured hotkey (e.g., Ctrl+Space).${RESET}"
            echo -e "${LIGHTYELLOW}5. Rime user data for fcitx4 is typically in ${BLUE}~/.config/fcitx/rime/${RESET}. Check Rime documentation.${RESET}"
            return 0
        else
            echo -e "${RED}Failed to install Fcitx4-Rime packages.${RESET}"
        fi
    else
        echo -e "${LIGHTYELLOW}Fcitx4-Rime (fcitx-rime) not found in official repositories.${RESET}"
    fi

    echo -e "${RED}Could not install Rime (neither Fcitx5-Rime nor Fcitx4-Rime) from official repositories.${RESET}"
    echo -e "${LIGHTYELLOW}Please ensure your system is Ubuntu/Debian based and your package sources are correctly configured.${RESET}"
    echo -e "${LIGHTYELLOW}No Rime input method was installed.${RESET}"
    return 1
}

# Install Rime (Squirrel) input method on macOS
# Squirrel is the macOS frontend for Rime input method engine
# Requires macOS 13 (Ventura) or later for the latest version
installRimeMacOS() {
    echo -e "${COLOR}Checking Rime (Squirrel) Input Method for macOS${RESET}"

    # Check if we're on macOS
    if [[ $(uname -s) != 'Darwin' ]]; then
        echo -e "${LIGHTYELLOW}This function is for macOS only. Use installLatestRimePinyin() for Linux.${RESET}"
        return 1
    fi

    # Check if Homebrew is available
    if ! command -v brew &>/dev/null; then
        echo -e "${RED}Homebrew is not installed. Please install Homebrew first:${RESET}"
        echo -e "${GREY}  /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"${RESET}"
        return 1
    fi

    # Check if Squirrel is already installed (skip check if update flag is set)
    if [ -z "$fChinesePinyinUpdate" ]; then
        local squirrelPath=""
        if [ -d "/Library/Input Methods/Squirrel.app" ]; then
            squirrelPath="/Library/Input Methods/Squirrel.app"
        elif [ -d "$HOME/Library/Input Methods/Squirrel.app" ]; then
            squirrelPath="$HOME/Library/Input Methods/Squirrel.app"
        fi
        if [ -n "$squirrelPath" ]; then
            local squirrelVersion=$("$squirrelPath/Contents/MacOS/Squirrel" --version 2>/dev/null || echo "unknown")
            echo -e "${GREEN}✔${GREY} Squirrel (Rime) is already installed.${RESET}"
            echo -e "  ${GREY}Version: ${squirrelVersion}${RESET}"
            return 0
        fi
    fi

    # Install Squirrel via Homebrew
    echo -e "${LIGHTYELLOW}Installing Squirrel (Rime) via Homebrew...${RESET}"
    if ! brew install --cask squirrel; then
        echo -e "${RED}Failed to install Squirrel via Homebrew.${RESET}"
        echo -e "${LIGHTYELLOW}You can try manual installation from: https://github.com/rime/squirrel/releases${RESET}"
        return 1
    fi

    echo -e "${GREEN}Successfully installed Squirrel (Rime).${RESET}"

    # Set up configuration files
    local rimeConfigPath="$HOME/Library/Rime"
    local squirrelCustomYaml="$fMainDir/assets/rime/squirrel.custom.yaml"
    local defaultCustomYaml="$fMainDir/assets/rime/default.custom.yaml"
    local lunaPinyinCustomYaml="$fMainDir/assets/rime/luna_pinyin_simp.custom.yaml"

    echo -e "${COLOR}Setting up Rime configuration files...${RESET}"

    # Create Rime config directory if it doesn't exist
    mkdir -p "$rimeConfigPath"

    # Link configuration files
    [ -f "$squirrelCustomYaml" ] && linkFile "$squirrelCustomYaml" "$rimeConfigPath" squirrel.custom.yaml
    [ -f "$defaultCustomYaml" ] && linkFile "$defaultCustomYaml" "$rimeConfigPath" default.custom.yaml
    [ -f "$lunaPinyinCustomYaml" ] && linkFile "$lunaPinyinCustomYaml" "$rimeConfigPath" luna_pinyin_simp.custom.yaml

    echo -e "${GREEN}Squirrel (Rime) installation completed.${RESET}"
    echo ""
    echo -e "${BOLD}${MAGENTA}IMPORTANT: Post-installation steps required:${RESET}"
    echo -e "${LIGHTYELLOW}1. Log out and log back in (or restart your Mac)${RESET}"
    echo -e "${LIGHTYELLOW}2. Go to: ${BLUE}System Settings → Keyboard → Input Sources${RESET}"
    echo -e "${LIGHTYELLOW}3. Click '+' and add 'Squirrel' (under Chinese, Simplified)${RESET}"
    echo -e "${LIGHTYELLOW}4. Use ${BLUE}Ctrl+\`${RESET} or ${BLUE}F4${RESET} to switch Rime schemas${RESET}"
    echo -e "${LIGHTYELLOW}5. Use your configured hotkey to switch between input methods${RESET}"
    echo ""
    echo -e "${COLOR}Per-Application Input Mode (configured in squirrel.custom.yaml):${RESET}"
    echo -e "${GREY}  - Terminal, iTerm2, VS Code, Xcode → English (ascii_mode)${RESET}"
    echo -e "${GREY}  - Safari, Chrome, Firefox → Chinese${RESET}"
    echo -e "${GREY}  - WeChat, QQ, Messages → Chinese${RESET}"
    echo -e "${GREY}  - Edit ${BLUE}~/Library/Rime/squirrel.custom.yaml${RESET} to customize${RESET}"
    echo ""
    echo -e "${LIGHTYELLOW}After editing config files, click 'Deploy' in Squirrel menu (鼠鬚管 → 重新部署)${RESET}"
    echo ""
    echo -e "${COLOR}Troubleshooting: If Squirrel doesn't appear after restart:${RESET}"
    echo -e "${GREY}  Squirrel is installed but NOT automatically added to input sources.${RESET}"
    echo -e "${GREY}  You MUST manually add it via: System Settings → Keyboard → Input Sources → '+' → Chinese, Simplified → Squirrel${RESET}"
    echo -e "${GREY}  If Squirrel is not in the list, run: ${BLUE}/Library/Input\\ Methods/Squirrel.app/Contents/MacOS/Squirrel --install${RESET}"

    return 0
}

installLatestPPaFirefox() {
    echo -e "${COLOR}Checking for Firefox (Mozilla PPA)${RESET}"
    if [ -z "$fFirefoxUpdate" ] && firefox --version &>/dev/null && ! apt-cache show fcitx5-rime > /dev/null 2>&1; then
        echo -e "${GREEN}✔${GREY} The current version of Firefox is acceptable.${RESET}"
        return 0
    fi

    # Check if Firefox is installed and if it's the DEB version from Mozilla PPA
    if [ -z "$fFirefoxUpdate" ] && command -v firefox &>/dev/null; then
        firefoxPolicy=$(apt-cache policy firefox)
        if echo "$firefoxPolicy" | grep -q "mozillateam/ppa"; then
            installedVersion=$(echo "$firefoxPolicy" | grep "Installed:" | awk '{print $2}')
            candidateVersion=$(echo "$firefoxPolicy" | grep "Candidate:" | awk '{print $2}')
            if [ "$installedVersion" != "(none)" ] && [ "$installedVersion" == "$candidateVersion" ]; then
                echo -e "${GREEN}✔${GREY} Firefox (Mozilla PPA) is already installed and up-to-date.${RESET}"
                echo "  $installedVersion"
                return 0
            fi
        elif echo "$firefoxPolicy" | grep -q "snap"; then
            echo -e "${LIGHTYELLOW}Snap version of Firefox found. Will attempt to replace with DEB version.${RESET}"
        fi
    fi

    # 1. Add the Mozilla PPA
    echo -e "${LIGHTYELLOW}Checking for Mozilla PPA (ppa:mozillateam/ppa)${RESET}"
    if grep -qr "mozillateam/ppa" /etc/apt/sources.list /etc/apt/sources.list.d/ 2>/dev/null; then
        echo -e "${GREEN}✔${GREY} Mozilla PPA already configured.${RESET}"
    else
        echo -e "${LIGHTYELLOW}Adding the Mozilla PPA${RESET}"
        if ! sudo add-apt-repository -y ppa:mozillateam/ppa; then
            echo -e "${RED}Failed to add Mozilla PPA. Aborting Firefox DEB installation.${RESET}"
            return 1
        fi
        echo -e "${GREEN}Mozilla PPA added successfully.${RESET}"
    fi

    # 2. Create the preference file to prioritize PPA Firefox
    local preferenceFilePath="/etc/apt/preferences.d/mozilla-firefox-nosnap"
    local preferenceContent=$(cat <<EOF
Package: *
Pin: release o=LP-PPA-mozillateam
Pin-Priority: 1001

Package: firefox
Pin: release o=Ubuntu*
Pin-Priority: -1
EOF
)
    echo -e "${LIGHTYELLOW}Setting up APT preferences to prioritize Mozilla PPA Firefox${RESET}"
    if [ -f "$preferenceFilePath" ] && cmp -s <(echo "$preferenceContent") "$preferenceFilePath"; then
        echo -e "${GREY}APT preference file '$preferenceFilePath' already exists and is correctly configured.${RESET}"
    else
        echo "$preferenceContent" | sudo tee "$preferenceFilePath" > /dev/null
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}APT preference file '$preferenceFilePath' created/updated successfully.${RESET}"
        else
            echo -e "${RED}Failed to create/update APT preference file '$preferenceFilePath'. Aborting.${RESET}"
            return 1
        fi
    fi

    # 3. Uninstall Snap Firefox (if present) and clean up AppArmor profiles
    if snap list firefox &>/dev/null; then
        echo -e "${LIGHTYELLOW}Uninstalling Snap version of Firefox${RESET}"
        if ! sudo snap remove firefox; then
            echo -e "${RED}Failed to remove Snap Firefox. This might interfere. Continuing, but manual removal might be needed.${RESET}"
        else
            echo -e "${GREEN}Snap Firefox removed successfully.${RESET}"
        fi
    else
        echo -e "${GREY}Snap version of Firefox not found. Skipping removal.${RESET}"
    fi

    # 4. Install DEB Firefox
    echo -e "${LIGHTYELLOW}Updating package lists${RESET}"
    if ! sudo apt update; then
        echo -e "${RED}Failed to update apt package list after PPA and preference changes. Aborting Firefox installation.${RESET}"
        return 1
    fi

    echo -e "${LIGHTYELLOW}Installing Firefox from Mozilla PPA${RESET}"
    if ! sudo apt install -y --allow-downgrades firefox; then
        echo -e "${RED}Failed to install Firefox from Mozilla PPA.${RESET}"
        echo -e "${LIGHTYELLOW}Attempting to install specific components that might be missing (e.g., language packs)${RESET}"
        sudo apt install -y --allow-downgrades firefox-locale-en
        if ! sudo apt install -y --allow-downgrades firefox; then
             echo -e "${RED}Still failed to install Firefox after attempting component install.${RESET}"
             return 1
        fi
    fi

    # 5. Verify installation
    if command -v firefox &>/dev/null; then
        firefoxVersion=$(firefox --version)
        firefoxPolicyAfter=$(apt-cache policy firefox)
        if echo "$firefoxPolicyAfter" | grep -q "mozillateam/ppa"; then
            echo -e "${GREEN}Firefox installed successfully! Version: $firefoxVersion${RESET}"
            echo -e "${GREY}Policy check confirms it's from Mozilla PPA.${RESET}"
        else
            echo -e "${RED}Firefox installed, but it might not be the DEB version from Mozilla PPA. Please check 'apt-cache policy firefox'.${RESET}"
        fi
    else
        echo -e "${RED}Firefox installation failed or binary not found in PATH.${RESET}"
        return 1
    fi
    return 0
}

linkClangFormat() {
    local argVal="$1"
    if [ -n "$argVal" ]; then
        if [ ! -d "$argVal" ]; then
            echo -e "${RED}Error: Link path '$argVal' is not a valid directory.${RESET}" >&2
            exit 1
        fi
        fLinkClangFormatPath="$argVal"
    fi

    local realClangFormatPath=$fMainDir/assets/clangd/clang-format
    echo -e "${LIGHTYELLOW}Linking clang-format to $fLinkClangFormatPath/.clang-format${RESET}"
    linkFile "$realClangFormatPath" "$fLinkClangFormatPath" .clang-format
}

vncLock() {
    if ! command -v xfce4-screensaver-command &> /dev/null; then
        echo -e "${RED}Error: xfce4-screensaver-command is not installed.${RESET}" >&2
        exit 1
    fi
    if [ $# -lt 1 ]; then
        echo -e "${RED}Error: Missing action argument.${RESET}" >&2
        exit 1
    fi

    local DISPLAY_NUM=":$fVncAbbrePort"
    local ACTION="$1"
    set -x
    case "$ACTION" in
        lock)
            DISPLAY="$DISPLAY_NUM" xfce4-screensaver-command --lock
            ;;
        unlock)
            DISPLAY="$DISPLAY_NUM" xfce4-screensaver-command --deactivate || {
                echo "Unlock failed. Please check:"
                echo "1. Correct DISPLAY setting (currently using $DISPLAY_NUM)"
                echo "2. Screen may require manual password entry"
                echo "3. Try restarting screensaver: pkill -f xfce4-screensaver"
                return 1
            }
            ;;
        status)
            DISPLAY="$DISPLAY_NUM" xfce4-screensaver-command --query
            ;;
        *)
            echo "Usage: $SCRIPT_NAME --vnclock [lock|unlock|status]"
            return 1
            ;;
    esac
}

isVncServerRunning() {
    if ! command -v tigervncserver &> /dev/null; then
        echo -e "${RED}Error: vncserver is not installed.${RESET}" >&2
        exit 1
    fi
    if lsof -i :$fVncFullPort | grep --quiet LISTEN; then
        return 0
    else
        return 1
    fi
}

stopVncServer() {
    if isVncServerRunning; then
        echo -e "${LIGHTYELLOW}Stopping VNC server on port $fVncFullPort...${RESET}"
        tigervncserver -kill :$fVncAbbrePort
    else
        echo -e "${LIGHTYELLOW}VNC server on port $fVncFullPort is not running.${RESET}"
    fi
}

# genChineseLocale() {
#     if ! command -v locale-gen &> /dev/null; then
#         echo -e "${RED}Error: locale-gen is not installed.${RESET}" >&2
#         exit 1
#     fi

#     if locale -a | grep -iq '^zh_CN\.utf8$'; then
#         return 0
#     fi

#     echo -e "${GREEN}Generating Chinese locale (zh_CN.UTF-8)...${RESET}"
#     sudo locale-gen zh_CN.UTF-8
#     sudo update-locale LANG=en_US.UTF-8 LC_CTYPE=zh_CN.UTF-8 # Update /etc/default/locale
#     if [ $? -eq 0 ]; then
#         echo -e "${GREEN}✔${GREY} Chinese locale generated successfully.${RESET}"
#     else
#         echo -e "${RED}Error: Failed to generate Chinese locale.${RESET}"
#         return 1
#     fi
# }

startVncServer() {
    if isVncServerRunning; then
        echo -e "${LIGHTYELLOW}VNC server on port $fVncFullPort is already running.${RESET}"
        return 0
    fi
    local hostIpAddress=$(hostname -I | awk '{print $1}')
    local hostUsername=$(whoami)
    local xstartupPath=$fMainDir/assets/vnc/xstartup
    local xstartupDest=$HOME/.vnc/xstartup
    [ -d "$HOME"/.vnc ] || mkdir -p "$HOME"/.vnc
    cd "$HOME"/.vnc || exit
    linkFile "$xstartupPath" "$HOME/.vnc" xstartup
    [ -d /etc/gdm3 ] && linkFile "$fMainDir/assets/gdm3/custom.conf" "/etc/gdm3" custom.conf
    echo -e "${GREEN}Starting VNC server...${RESET}"
    local startCmd="tigervncserver :$fVncAbbrePort -geometry $fVncResolution -SecurityTypes None -localhost yes -depth 24 -xstartup $xstartupDest"
    echo -e "${MAGENTA}$startCmd${RESET}"
    $startCmd
    if [ $? -ne 0 ]; then
        echo -e "${RED}Failed to start VNC server.${RESET}"
        return 1
    fi
    echo -e "${MAGENTA}VNC server started successfully:${RESET}"
    sudo lsof -i :5909
    echo -e "${CYAN}===================================================${RESET}"
    echo -e "${BOLD}${LIGHTYELLOW}- On your local machine, setup the SSH tunnel as follows:${RESET}"
    echo -e "  ${GREEN}Option 1.${RESET} Use Vs Code Port Forward feature to forward the port ${MAGENTA}$fVncFullPort${RESET}"
    echo -e "  ${GREEN}Option 2.${RESET} Open a terminal and run the following command:"
    echo -e "    ${BLUE}ssh -NL ${MAGENTA}$fVncFullPort${BLUE}:localhost:${MAGENTA}$fVncFullPort ${MAGENTA}$hostUsername@$hostIpAddress${RESET}"
    echo -e "    ${GREY}or simply:${RESET} ${BLUE}ssh -NL ${MAGENTA}$fVncFullPort${BLUE}:localhost:${MAGENTA}$fVncFullPort ${MAGENTA}droplet1${RESET}"
    echo -e "${BOLD}${LIGHTYELLOW}- Connect to the VNC server using a VNC viewer:${RESET}"
    echo -e "  ${BLUE}vncviewer localhost:${MAGENTA}$fVncFullPort${RESET}"
    echo -e "${CYAN}===================================================${RESET}"
}

restartVncServer() {
    stopVncServer
    sleep 1
    startVncServer
}

addUserIntoLibvirtGrp() {
    echo -e "${COLOR}Configuring Libvirt Group Membership for Current User${RESET}"

    if ! getent group libvirt > /dev/null; then
        echo -e "${RED}Error: The 'libvirt' group does not exist.${RESET}"
        echo -e "${LIGHTYELLOW}This might indicate that 'libvirt-daemon-system' or similar packages are not installed or not installed correctly.${RESET}"
        echo -e "${LIGHTYELLOW}Please verify libvirt installation. Skipping group membership addition.${RESET}"
        return 1
    fi

    if id -nG "$USER" | grep -qw libvirt; then
        echo -e "${GREEN}✔${GREY} User '$USER' is already a member of the 'libvirt' group.${RESET}"
        printf "  "
        libvirtd --version
        return 0
    fi

    echo -e "${LIGHTYELLOW}Attempting to add user '$USER' to the 'libvirt' group...${RESET}"
    if sudo usermod -aG libvirt "$USER"; then
        echo -e "${GREEN}Successfully added user '$USER' to the 'libvirt' group.${RESET}"
        echo -e "${BOLD}${MAGENTA}IMPORTANT: You must log out and log back in, or open a new shell session (or run 'newgrp libvirt'), for this group membership change to take effect.${RESET}"
    else
        echo -e "${RED}Failed to add user '$USER' to the 'libvirt' group.${RESET}"
        echo -e "${LIGHTYELLOW}Please try adding the user manually: ${BLUE}sudo usermod -aG libvirt $USER${RESET}"
        return 1
    fi

    return 0
}

installSambaServer() {
    echo -e "${COLOR}Starting Samba Server Installation/Configuration${RESET}"
    # Step 1: Check if Samba is already installed
    if command -v smbd &> /dev/null; then
        echo -e "${GREEN}✔${GREY} Samba (smbd) is already installed.${RESET}"
    else
        echo -e "${LIGHTYELLOW}Samba (smbd) not found. Attempting installation...${RESET}"
        if ! sudo apt update; then
            echo -e "${RED}Error: Failed to update apt package list. Aborting Samba installation.${RESET}"
            return 1
        fi
        if ! sudo DEBIAN_FRONTEND=noninteractive apt install -y samba smbclient; then
            echo -e "${RED}Error: Failed to install Samba packages. Aborting.${RESET}"
            return 1
        fi
        echo -e "${GREEN}Samba installed successfully.${RESET}"
    fi

    # Step 2: Configure Samba
    local sambaSysConfFile="/etc/samba/smb.conf"
    local mySambaConfSource="$fMainDir/assets/samba/ubuntu.smb.conf"
    if [ ! -f "$mySambaConfSource" ]; then
        echo -e "${RED}Error: Source Samba configuration file ('smb.conf') not found at ${BLUE}$mySambaConfSource${RESET}"
        echo -e "${LIGHTYELLOW}This script expects a custom 'smb.conf' to be present in the assets.${RESET}"
        exit 1
    fi
    echo -e "${LIGHTYELLOW}Validating Samba configuration with 'testparm'...${RESET}"
    if testparm -s "$mySambaConfSource"; then
        echo -e "${GREEN}✔${GREY} Samba configuration appears valid.${RESET}"
    else
        echo -e "${RED}Error: Samba configuration validation failed (testparm reported errors).${RESET}"
        echo -e "${LIGHTYELLOW}Please review '${BLUE}$mySambaConfSource${LIGHTYELLOW}' and the output above.${RESET}"
        exit 1
    fi
    linkFile "$mySambaConfSource" /etc/samba smb.conf

    # Step 3: Configure Samba to use the current user
    local smbUser="$USER"
    local smbShareGroup=$(id -gn "$USER")

    if [ -z "$smbUser" ]  || [ -z "$smbShareGroup" ]; then
        echo -e "${RED}Error: Could not determine current user or their primary group. Aborting Samba setup.${RESET}"
        return 1
    fi

    echo -e "${LIGHTYELLOW}Samba will be configured for the current user: ${BOLD}$smbUser${RESET}"
    echo -e "${LIGHTYELLOW}The user's primary group will be used for file sharing: ${BOLD}$smbShareGroup${RESET}"

    # Set Samba password for the Samba user, who will be authenticating
    echo -e "${LIGHTYELLOW}Setting Samba password for user '${BOLD}$smbUser${LIGHTYELLOW}'...${RESET}"
    local sambaPassword=""
    local sambaPasswordConfirm=""
    local sambaPasswordFile="/etc/samba/smbpasswd"
    if [ ! -f "$sambaPasswordFile" ] || [ ! -s "$sambaPasswordFile" ] || [ "$fSambaServerFlag" == "2" ]; then # Reset password
        while true; do
            echo -en "${GREY}Enter new Samba password for user ${BOLD}$smbUser${LIGHTYELLOW} (must not be empty): ${RESET}"
            read -r -s sambaPassword
            echo
            if [ -z "$sambaPassword" ]; then
                echo -e "${RED}Password cannot be empty. Please try again.${RESET}"
                continue
            fi
            echo -en "${GREY}Confirm Samba password: ${RESET}"
            read -r -s sambaPasswordConfirm
            echo
            if [ "$sambaPassword" = "$sambaPasswordConfirm" ]; then
                break
            else
                echo -e "${RED}Passwords do not match. Please try again.${RESET}"
            fi
        done
        # Add/update the Samba user in Samba's database and set the password
        if (echo "$sambaPassword"; echo "$sambaPassword") | sudo smbpasswd -a "$smbUser" -s; then
            echo -e "${GREEN}✔${GREY} Samba password for user '$smbUser' set successfully.${RESET}"
        else
            echo -e "${RED}Error: Failed to set Samba password for user '$smbUser'.${RESET}"
            echo -e "${LIGHTYELLOW}Ensure '$smbUser' is a valid system user and you have sudo privileges.${RESET}"
            return 1
        fi
    fi

    # Step 4: Enable and start Samba services
    # local servicesToManage=("smbd" "nmbd")
    local servicesToManage=("smbd")
    local overallSuccess=true
    for service in "${servicesToManage[@]}"; do
        echo -e "${LIGHTYELLOW}Managing service: $service...${RESET}"
        if sudo systemctl restart "$service"; then
            echo -e "  ${GREEN}✔${GREY} $service restarted successfully.${RESET}"
        else
            echo -e "  ${RED}Error: Failed to restart $service.${RESET}"
            echo -e "  ${LIGHTYELLOW}Check with: sudo systemctl status $service && journalctl -xeu $service${RESET}"
            if [ "$service" == "smbd" ]; then
                overallSuccess=false;
            fi # Critical
        fi
        if sudo systemctl is-enabled "$service" | grep -q "enabled"; then
            echo -e "  ${GREEN}✔${GREY} $service is already enabled to start on boot.${RESET}"
        else
            if sudo systemctl enable "$service"; then
                echo -e "  ${GREEN}✔${GREY} $service enabled successfully for boot start.${RESET}"
            else
                echo -e "  ${RED}Error: Failed to enable $service for boot start.${RESET}"
                if [ "$service" == "smbd" ]; then
                    overallSuccess=false;
                fi # Critical
            fi
        fi
    done
    if [ "$overallSuccess" = false ]; then
        echo -e "${RED}Critical error managing Samba services. Aborting further Samba setup.${RESET}"
        exit 1
    fi

    # Step 5: Configuring Firewall (UFW)
    if command -v ufw &> /dev/null; then
        if sudo ufw status | grep -qw "Status: active"; then
            echo -e "${LIGHTYELLOW}UFW firewall is active. Checking/Adding rules for Samba...${RESET}"
            if sudo ufw status | grep -Ewq "Samba|ALLOW IN.*137,138/(udp|UDP)|ALLOW IN.*139,445/(tcp|TCP)"; then
                 echo -e "${GREEN}✔${GREY} UFW rule for 'Samba' or its specific ports already seems to exist or is allowed.${RESET}"
            else
                echo -e "${LIGHTYELLOW}Attempting to allow Samba through UFW (using 'samba' application profile)...${RESET}"
                if sudo ufw allow 445/tcp; then
                    echo -e "${GREEN}✔${GREY} UFW rule for Samba added successfully.${RESET}"
                    echo -e "${GREY}Current UFW status: ${RESET}"
                    sudo ufw status
                else
                    echo -e "${RED}Warning: Failed to add UFW rule for Samba using 'ufw allow samba'.${RESET}"
                    echo -e "${LIGHTYELLOW}You may need to manually allow TCP ports 445: sudo ufw allow 445/tcp${RESET}"
                fi
            fi
        else
            echo -e "${GREY}UFW firewall is installed but not active. Skipping UFW rule configuration.${RESET}"
        fi
    else
        echo -e "${GREY}UFW firewall manager not found. Skipping UFW configuration.${RESET}"
    fi

    # 6. Final message
    echo -e "\n${GREEN}--- Samba Server Installation/Configuration Process Completed ---${RESET}"
    echo -e "${LIGHTYELLOW}Summary:${RESET}"
    echo -e "  - Samba packages checked/installed."
    echo -e "  - Configuration '${BLUE}$sambaSysConfFile${RESET}' applied/validated."
    echo -e "  - Samba password set for user '${BOLD}$smbUser${RESET}'."
    echo -e "  - Services ${servicesToManage[*]} restarted and enabled."
    echo -e "  - Firewall rules for Samba (if UFW active) checked/added."
    echo -e "\n${BOLD}${LIGHTYELLOW}Next Steps & Testing:${RESET}"
    echo -e "  1. Ensure your share definitions in '$sambaSysConfFile' are correct for your needs."
    echo -e "  2. ${LIGHTYELLOW}Test connection from this machine: ${BLUE}smbclient -L localhost -U $smbUser${RESET}"
    echo -e "     (You will be prompted for the Samba password you just set)."
    echo -e "  3. Test from another client machine on the network using this server's IP address."
    echo -e "     - ${BOLD}On Linux/macOS:${RESET}"
    echo -e "       - Example (list shares): ${BLUE}smbclient --list //SERVER_IP_ADDRESS -U $smbUser${RESET}"
    echo -e "       - Example (connect to a share): ${BLUE}smbclient //SERVER_IP_ADDRESS/sharename -U $smbUser${RESET}"
    echo -e "     - ${BOLD}On Windows:${RESET}"
    echo -e "       - In File Explorer, type ${BLUE}\\\\\\SERVER_IP_ADDRESS${RESET} in the address bar."
    echo -e "       - When prompted, use username '${BOLD}$smbUser${RESET}' and the password you set."
    echo -e "     Or map a network drive via your client OS's file explorer."
    echo -e "  4. Remember to change the ownership of the share directory to '${BOLD}$smbUser${RESET}'."
    echo -e "     You can do this using the '${BLUE}chown -R $smbUser:$smbShareGroup /path/to/share/directory${RESET}' command."
    echo -e "${GREY}If issues arise, check Samba logs (e.g., 'journalctl -u smbd -u nmbd', '/var/log/samba/log.<client_hostname_or_ip>') and 'sudo smbstatus'.${RESET}"

    return 0
}

addSwap() {
    # Default swap size is 8G
    local swapSize=${1:-8G}

    # Use regex to parse size and unit, only matching integers
    # ([0-9]+) matches one or more digits (integer part)
    # ([KMGTP]B?|[kMGTp]b?)? matches K, M, G, T, P or kB, MB, GB, TB, PB (case-insensitive and optional)
    local regex="^([0-9]+)([KkMmGgTtPp]B?)?$"

    # Try to match the input
    if [[ "$swapSize" =~ $regex ]]; then
        local num=${BASH_REMATCH[1]}    # Integer number part
        local unit=${BASH_REMATCH[2]}    # Unit part (can be empty)
        # Convert unit to uppercase and remove optional 'B' for unified handling
        local unit_upper=$(echo "$unit" | tr '[:lower:]' '[:upper:]' | sed 's/B$//')

        # echo -e "${LIGHTYELLOW}Swap size parsed: ${num}${unit_upper}${RESET}"
    else
        # Exit if the format is invalid or contains decimals
        echo -e "${RED}Invalid swap size format: ${swapSize}. Please use an integer followed by an optional unit (e.g., '8G', '4096M', or '8192').${RESET}"
        return 1
    fi

    echo -e "${COLOR}Adding Swap File of size ${num}${unit_upper}${RESET}"

    # ----------------------------------------------------
    # Check if ANY swap is already active
    # swapon --show outputs a header line, so we check if there is more than one line of output.
    # The 'tail -n +2' command skips the header line, and we check if any content remains.
    # ----------------------------------------------------
    if swapon --show | tail -n +2 | grep -q '.*'; then
        echo -e "${GREEN}✔${GREY} At least one swap area is already active.${RESET}"
        swapon --show
        return 0
    fi

    # Create or enable the Swap
    if [ -f /swapfile ]; then
        echo -e "${LIGHTYELLOW}/swapfile exists but not active. Enabling it...${RESET}"
    else
        echo -e "${LIGHTYELLOW}Creating swap file of size $swapSize...${RESET}"

        # Prefer fallocate, as it directly supports size strings with units
        # Suppress standard error output of fallocate in case of failure
        if ! sudo fallocate -l "$swapSize" /swapfile 2>/dev/null; then
            echo -e "${RED}fallocate failed. Trying dd fallback...${RESET}"

            # Fallback to dd command
            # dd requires an integer count and a bs (block size)

            local bs_val
            case "$unit_upper" in
                "K") bs_val="1K" ;;
                "M") bs_val="1M" ;;
                "G") bs_val="1G" ;;
                "T") bs_val="1T" ;;
                "")
                     # If no unit is provided (e.g., 8192), assume 'M' unit and set bs to 1M
                     echo -e "${LIGHTYELLOW}No unit provided. Assuming 'M' unit for dd fallback.${RESET}"
                     bs_val="1M"
                     ;;
                *)
                     # Should not happen if regex is correct, but safe check for dd
                     echo -e "${RED}Unsupported unit '$unit_upper' for dd fallback (Use K, M, G, or T).${RESET}"
                     return 1
                     ;;
            esac

            echo -e "${LIGHTYELLOW}dd command: sudo dd if=/dev/zero of=/swapfile bs=${bs_val} count=${num} status=progress${RESET}"
            if ! sudo dd if=/dev/zero of=/swapfile bs="$bs_val" count="$num" status=progress; then
                echo -e "${RED}dd failed.${RESET}"
                return 1
            fi
        fi

        # Set correct permissions and format the swap file
        sudo chmod 600 /swapfile
        sudo mkswap /swapfile
    fi

    # Activate the swap file
    sudo swapon /swapfile
    if [ $? -eq 0 ]; then
        echo -e "${GREEN}Swap enabled successfully.${RESET}"
        # Add to fstab for persistence across reboots
        if ! grep -q "^/swapfile" /etc/fstab; then
            echo -e "${GREY}Adding /swapfile to /etc/fstab${RESET}"
            echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
        fi
    else
        echo -e "${RED}Failed to enable swap.${RESET}"
        exit 1
    fi
    free -h
}

installLatestPPaWireshark() {
    echo -e "${COLOR}Checking for Wireshark (Wireshark PPA)${RESET}"

    if [ -z "$fWiresharkUpdate" ] && command -v wireshark &>/dev/null; then
        local wiresharkPolicy
        wiresharkPolicy=$(apt-cache policy wireshark)
        if echo "$wiresharkPolicy" | grep -q "wireshark-dev/stable"; then
            local installedVersion candidateVersion
            installedVersion=$(echo "$wiresharkPolicy" | grep "Installed:" | awk '{print $2}')
            candidateVersion=$(echo "$wiresharkPolicy" | grep "Candidate:" | awk '{print $2}')
            if [ "$installedVersion" != "(none)" ] && [ "$installedVersion" == "$candidateVersion" ]; then
                echo -e "${GREEN}✔${GREY} Wireshark (from PPA) is already installed and up-to-date.${RESET}"
                printf "  "
                wireshark --version | head -n 1
                return 0
            fi
        fi
    fi

    # 1. Add the Wireshark PPA repository
    if grep -qr "wireshark-dev/stable" /etc/apt/sources.list /etc/apt/sources.list.d/ 2>/dev/null; then
        echo -e "${GREEN}✔${GREY} Wireshark PPA already configured.${RESET}"
    else
        echo -e "${LIGHTYELLOW}Adding the Wireshark PPA...${RESET}"
        if ! sudo add-apt-repository -y ppa:wireshark-dev/stable; then
            echo -e "${RED}Error: Failed to add Wireshark PPA. Aborting.${RESET}"
            return 1
        fi
        echo -e "${GREEN}Wireshark PPA added successfully.${RESET}"
    fi

    # 2. Create the preference file to prioritize PPA Wireshark
    local preferenceFilePath="/etc/apt/preferences.d/wireshark-ppa-priority"
    # The 'o' value can be found with 'apt-cache policy wireshark' -> 'LP-PPA-wireshark-dev-stable'
    local preferenceContent
    preferenceContent=$(cat <<'EOF'
Package: *
Pin: release o=LP-PPA-wireshark-dev-stable
Pin-Priority: 1001

Package: wireshark*
Pin: release o=Ubuntu*
Pin-Priority: -1
EOF
)
    echo -e "${LIGHTYELLOW}Setting up APT preferences to prioritize Wireshark PPA...${RESET}"
    if [ -f "$preferenceFilePath" ] && cmp -s <(echo "$preferenceContent") "$preferenceFilePath"; then
        echo -e "${GREY}APT preference file '$preferenceFilePath' already exists and is correctly configured.${RESET}"
    else
        echo "$preferenceContent" | sudo tee "$preferenceFilePath" > /dev/null
        if [ $? -eq 0 ]; then
            echo -e "${GREEN}APT preference file '$preferenceFilePath' created/updated successfully.${RESET}"
        else
            echo -e "${RED}Failed to create/update APT preference file '$preferenceFilePath'. Aborting.${RESET}"
            return 1
        fi
    fi

    # 3. Update package list
    echo -e "${LIGHTYELLOW}Updating package lists...${RESET}"
    if ! sudo apt update; then
        echo -e "${RED}Error: Failed to update apt package list. Aborting.${RESET}"
        return 1
    fi

    # 4. Pre-configure wireshark-common to allow non-root users to capture packets.
    # This avoids the interactive prompt during installation.
    echo -e "${LIGHTYELLOW}Pre-configuring wireshark-common to allow non-root packet capture...${RESET}"
    if ! echo "wireshark-common wireshark-common/install-setuid boolean true" | sudo debconf-set-selections; then
        echo -e "${RED}Warning: Failed to pre-configure wireshark-common via debconf. The installation might prompt for input.${RESET}"
    fi

    # 5. Install Wireshark
    echo -e "${LIGHTYELLOW}Installing Wireshark...${RESET}"
    if ! sudo DEBIAN_FRONTEND=noninteractive apt install -y wireshark; then
        echo -e "${RED}Error: Failed to install Wireshark. Aborting.${RESET}"
        return 1
    fi
    echo -e "${GREEN}Wireshark installed successfully.${RESET}"

    # 6. Add user to the 'wireshark' group
    if ! getent group wireshark > /dev/null; then
        echo -e "${RED}Error: The 'wireshark' group was not created by the installation. Manual configuration may be needed.${RESET}"
    elif id -nG "$USER" | grep -qw wireshark; then
        echo -e "${GREEN}✔${GREY} User '$USER' is already a member of the 'wireshark' group.${RESET}"
    else
        echo -e "${LIGHTYELLOW}Adding current user '$USER' to the 'wireshark' group...${RESET}"
        if sudo usermod -aG wireshark "$USER"; then
            echo -e "${GREEN}Successfully added user '$USER' to the 'wireshark' group.${RESET}"
        else
            echo -e "${RED}Error: Failed to add user '$USER' to the 'wireshark' group.${RESET}"
            return 1
        fi
    fi

    # 7. Final message
    echo -e "\n${BOLD}${MAGENTA}IMPORTANT: You must run 'newgrp wireshark' or you have to log out and log back in, for group changes to take effect.${RESET}"
    echo -e "${LIGHTYELLOW}This will allow you to capture network traffic as a non-root user.${RESET}"
    wireshark --version
    return 0
}

configureTcpdumpCaps() {
    echo -e "${COLOR}Configuring tcpdump for Non-root User Packet Capture${RESET}"

    # Check for required tools first
    if ! command -v tcpdump &> /dev/null; then
        echo -e "${LIGHTYELLOW}Warning: tcpdump command not found. Skipping configuration.${RESET}"
        echo -e "${GREY}Please install it via 'sudo apt install tcpdump' and re-run.${RESET}"
        return 1
    fi
    # `setcap` is a utility for setting file capabilities. By granting the 'cap_net_raw'
    # and 'cap_net_admin' capabilities to the tcpdump binary, we allow non-root users
    # to capture packets without needing full sudo privileges. This is more secure
    # than making tcpdump setuid root. The `libcap2-bin` package provides `setcap`.
    if ! command -v setcap &> /dev/null || ! command -v getcap &> /dev/null; then
        echo -e "${RED}Error: 'setcap' or 'getcap' command not found.${RESET}"
        echo -e "${LIGHTYELLOW}Please install the required package (e.g., 'sudo apt install libcap2-bin') and re-run.${RESET}"
        return 1
    fi

    local tcpdumpPath
    tcpdumpPath=$(command -v tcpdump)
    local requiredCaps="cap_net_admin,cap_net_raw+eip"
    local currentCaps
    currentCaps=$(getcap "$tcpdumpPath" 2>/dev/null)

    # Check if the capabilities are already set
    if [[ "$currentCaps" == *"cap_net_admin,cap_net_raw"* ]]; then
        echo -e "${GREEN}✔${GREY} tcpdump already has the required capabilities for non-root capture.${RESET}"
        printf "  "
        tcpdump --version 2>&1 | head -n 1
        return 0
    fi

    # Check if the filesystem supports extended attributes (required for setcap)
    local tcpdumpDir
    tcpdumpDir=$(dirname "$tcpdumpPath")
    local fsType
    fsType=$(df -T "$tcpdumpDir" 2>/dev/null | awk 'NR==2 {print $2}')
    if [[ "$fsType" == "nfs"* ]] || [[ "$fsType" == "cifs" ]] || [[ "$fsType" == "smbfs" ]]; then
        echo -e "${LIGHTYELLOW}⚠ Skipping: tcpdump is on a ${fsType} filesystem which doesn't support capabilities.${RESET}"
        echo -e "${GREY}  Use 'sudo tcpdump' for packet capture on this system.${RESET}"
        return 0
    fi

    echo -e "${LIGHTYELLOW}Attempting to set network capture capabilities on the tcpdump binary...${RESET}"
    echo -e "${GREY}Executing: sudo setcap '$requiredCaps' '$tcpdumpPath'${RESET}"
    if sudo setcap "$requiredCaps" "$tcpdumpPath"; then
        echo -e "${GREEN}Successfully set capabilities on '$tcpdumpPath'.${RESET}"
        echo -e "${LIGHTYELLOW}Normal users should now be able to run tcpdump for packet capture.${RESET}"
    else
        echo -e "${LIGHTYELLOW}🔸 Could not set capabilities on tcpdump binary.${RESET}"
        echo -e "${GREY}   This may be due to filesystem limitations, AppArmor, or SELinux.${RESET}"
        echo -e "${GREY}   Use 'sudo tcpdump' for packet capture on this system.${RESET}"
        return 0
    fi

    return 0
}

installNvmNodeJs() {
    echo -e "${COLOR}Installing NVM (Node Version Manager) and Node.js via official script${RESET}"
    local nvmDir="$HOME/.nvm"
    local nvmSh="$nvmDir/nvm.sh"
    if [ -z "$fNVMUpdate" ] && [ -s "$nvmSh" ]; then
        echo -e "${GREEN}✔${GREY} NVM is already installed in ${BLUE}$nvmDir${RESET}"
        # shellcheck disable=SC1090
        source "$nvmSh"
        printf "  " && nvm --version
        # Link current Node.js version
        [ -n "$(nvm which current 2>/dev/null)" ] && linkFile "$(nvm which current)" "$HOME/.usr/bin" "node"
        return 0
    else
        local nvmVersion="v0.40.3"
        # Remove conflicting system packages if they exist to avoid conflicts.
        echo -e "${LIGHTYELLOW}Checking and removing system-installed Node.js/npm...${RESET}"
        removeInstalledPackages nodejs npm
        # Download and run the NVM installation script
        # The script will also update .bashrc if necessary
        if ! curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/"$nvmVersion"/install.sh | bash; then
            echo -e "${RED}Error: Failed to install NVM. Aborting Node.js setup.${RESET}"
            return 1
        fi
        echo -e "${GREEN}NVM installed successfully.${RESET}"
    fi

    # Source the NVM script to make the 'nvm' command available in this shell session
    if [ -s "$nvmSh" ]; then
        export NVM_DIR="$nvmDir"
        # shellcheck disable=SC1090
        source "$nvmSh"
    else
        echo -e "${RED}Error: nvm.sh script not found after installation. Cannot proceed.${RESET}"
        return 1
    fi

    # Install the latest LTS (Long-Term Support) version of Node.js.
    # `nvm install --lts` is idempotent; it will install if not present or
    # do nothing if the latest LTS version is already installed.
    echo -e "${LIGHTYELLOW}Installing/Updating to the latest LTS version of Node.js via NVM...${RESET}"
    if ! nvm install --lts; then
        echo -e "${RED}Error: Failed to install Node.js LTS version using NVM.${RESET}"
        return 1
    fi
    echo -e "${GREEN}Successfully installed/verified Node.js LTS version.${RESET}"
    # Set this version as the default for new shell sessions
    echo -e "${LIGHTYELLOW}Setting/updating default Node.js alias to the latest LTS...${RESET}"
    nvm alias default lts/*
    echo -e "${GREEN}✔${GREY} Default Node.js version set to the latest LTS.${RESET}"
    echo -e "${GREEN}✔${GREY} Current version in use: $(nvm current)${RESET}"
    echo -e "\n${CYAN}IMPORTANT: NVM has been configured. To use it in a new terminal, you may need to RE-LOGIN or RESTART your terminal.${RESET}"
    echo -e "${LIGHTYELLOW}To use it in this current shell session immediately, run: ${BLUE}source ~/.nvm/nvm.sh${RESET}"

    [ -n "$(nvm which current 2>/dev/null)" ] && linkFile "$(nvm which current)" "$HOME/.usr/bin" "node"
    return 0
}

allowUnprivilegedUserns() {
    echo -e "${COLOR}Allowing unprivileged user namespaces (required by Firefox, Cursor, etc.)${RESET}"
    local sysctlKey="kernel.apparmor_restrict_unprivileged_userns"
    local sysctlFile="/etc/sysctl.d/99-userns.conf"
    if [ ! -e "/proc/sys/kernel/apparmor_restrict_unprivileged_userns" ]; then
        echo -e "${GREEN}✔${GREY} Kernel does not restrict unprivileged user namespaces (no AppArmor userns restriction).${RESET}"
        return
    fi
    if [ "$(sysctl -n "$sysctlKey" 2>/dev/null)" == "0" ]; then
        echo -e "${GREEN}✔${GREY} Unprivileged user namespaces already allowed.${RESET}"
        return
    fi
    sudo sysctl -w "$sysctlKey=0" > /dev/null 2>&1
    echo "$sysctlKey=0" | sudo tee "$sysctlFile" > /dev/null
    echo -e "${GREEN}✔${GREY} Unprivileged user namespaces enabled (persisted in $sysctlFile).${RESET}"
}

switchDisplayMode() {
    echo -e "${COLOR}Switching Display Mode to ${1:-text}${RESET}"
    local currentTarget
    currentTarget=$(systemctl get-default 2>/dev/null)
    case "$1" in
        gdm)
            if [ "$currentTarget" == "graphical.target" ] && systemctl is-active gdm3 &>/dev/null; then
                echo -e "${GREEN}✔${GREY} Already in graphical mode (gdm3 running).${RESET}"
                return
            fi
            echo -e "${COLOR}Switching to graphical mode${RESET}"
            sudo systemctl set-default graphical.target
            if sudo systemctl start gdm3; then
                echo -e "${GREEN}✔${GREY} gdm3 started. Default boot target set to graphical.${RESET}"
            else
                echo -e "${RED}Failed to start gdm3.${RESET}"
                return 1
            fi
            ;;
        text)
            if [ "$currentTarget" == "multi-user.target" ] && ! systemctl is-active gdm3 &>/dev/null; then
                echo -e "${GREEN}✔${GREY} Already in text mode (multi-user.target).${RESET}"
                return
            fi
            echo -e "${COLOR}Switching to text mode${RESET}"
            sudo systemctl set-default multi-user.target
            sudo systemctl stop gdm3 2>/dev/null
            echo -e "${GREEN}✔${GREY} Default boot target set to text mode. Use 'jc --gdm' to start desktop on demand.${RESET}"
            ;;
    esac
}

doCommonJobs() {
    createTKSymlinks           # Create Tracked Files symlinks
    installVimPluginsManager   # Install Vim Plugins Manager
    installTmuxPluginsManager  # Install Tmux Plugins Manager
    createToolsSymlinks        # Create tool symlinks
    createCursorCLISymlinks    # Create Cursor CLI symlinks (code/cursor)
    createDevToolSymlinks      # Create dev tool symlinks (clangd, fzf, jc, vscode)
    buildBatTheme              # Build bat theme
    buildExtraFonts            # Build extra fonts
}

doDebianJobs() {
    ubuntuInstallApps          # Install apps for Ubuntu
    doCommonJobs               # Common setup tasks
    relinkSysCmds              # Relink system commands
    addUserIntoLibvirtGrp      # Add user into libvirt group
    installNvmNodeJs           # Install NVM and Node.js
    installLatestGitLfs        # Install Git LFS (PackageCloud)
    installLatestRimePinyin    # Install Rime Pinyin input method
    installLatestPPaFirefox    # Install Firefox (Mozilla PPA)
    installLatestPPaDocker     # Install Docker
    installLatestPPaWireshark  # Install Wireshark (Mozilla PPA)
    configureTcpdumpCaps       # Configure tcpdump for non-root user packet capture
    installLatestGithubClangd  # Install Github Clangd
    stopUnnecessaryServices    # Stop unnecessary services
    disableLidCloseSuspend     # Disable lid-close suspend for server use
    allowUnprivilegedUserns    # Allow user namespaces for Chromium-based apps (Firefox, Cursor, etc.)
    switchDisplayMode text     # Boot to text mode, use --gdm to start desktop on demand
    changeTMOUTToWritable      # Change TMOUT to writable
    setLinuxDefaultShell       # Set default shell
    setTimeZone                # Set timezone
    createFirstTimeFile        # Create first-time file marker
}

doMacJobs() {
    macInstallApps             # Install apps for macOS
    doCommonJobs               # Common setup tasks
    createMacOSBashProfile     # Create macOS bash_profile
    setMacOSDefaultShell       # Set default shell
    installNvmNodeJs           # Install NVM and Node.js
    installLatestRimePinyin    # Install Rime Pinyin input method
    createFirstTimeFile        # Create first-time file marker
}

listRtspStreams() {
    local stream_list
    stream_list=$(getSupportedRtspStreams) || return 1
    local streams
    read -ra streams <<< "$stream_list"
    if (( ${#streams[@]} == 0 )); then
        echo -e "${LIGHTYELLOW}No streams available from go2rtc.${RESET}"
        return 0
    fi
    echo -e "${COLOR}Streams from go2rtc at ${BLUE}${fRtspSrvIp}:1984${COLOR}:${RESET}"
    local prev_group=""
    for s in $(printf '%s\n' "${streams[@]}" | sort); do
        local group="${s%_*}"
        local variant="${s##*_}"
        if [[ "$group" != "$prev_group" ]]; then
            echo -e "  ${GREEN}${group}${RESET}"
            prev_group="$group"
        fi
        echo -e "    ${GREY}${variant}${RESET}  ${BLUE}${s}${RESET}"
    done
}

getSupportedRtspStreams() {
    local api_url="http://${fRtspSrvIp}:1984/api/streams"
    local response
    response=$(curl -sf --connect-timeout 3 "$api_url") || {
        echo -e "${RED}Error: failed to reach go2rtc API at ${api_url}${RESET}" >&2
        return 1
    }
    echo "$response" | jq -r 'keys | join(" ")'
}

killRtspStreams() {
    if ! pgrep -x mpv &> /dev/null; then
        echo -e "${LIGHTYELLOW}No mpv instances running.${RESET}"
        return 0
    fi
    echo -e "${COLOR}Killing all mpv instances.${RESET}"
    pkill mpv
    if [ $? -ne 0 ]; then
        echo -e "${RED}Error: Failed to kill mpv instances.${RESET}"
        return 1
    fi
    echo -e "${GREEN}✔${GREY} All mpv instances killed.${RESET}"
    return 0
}

# Auto-detect screen resolution. On multi-monitor macOS, prefers the largest
# external display (has "UI Looks like" in system_profiler output).
# Falls back to the largest of any display.
# Outputs: "width height total_monitors external_monitors" or empty on failure.
getScreenResolution() {
    local best_w=0 best_h=0 best_area=0 total=0 external=0
    if [[ "$(uname)" == "Darwin" ]]; then
        local profiler
        profiler=$(system_profiler SPDisplaysDataType 2>/dev/null)
        total=$(echo "$profiler" | grep -c 'Resolution:')
        external=$(echo "$profiler" | grep -c 'UI Looks like')
        # External monitors: grab native Resolution preceding "UI Looks like"
        while IFS=' ' read -r w h; do
            local area=$(( w * h ))
            if (( area > best_area )); then
                best_w=$w best_h=$h best_area=$area
            fi
        done < <(echo "$profiler" \
            | awk '/Resolution:/{w=$2; h=$4} /UI Looks like/{print w, h}')
        # Fallback: any Resolution line if no external found
        if (( best_area == 0 )); then
            while IFS=' ' read -r w h; do
                local area=$(( w * h ))
                if (( area > best_area )); then
                    best_w=$w best_h=$h best_area=$area
                fi
            done < <(echo "$profiler" | awk '/Resolution:/{print $2, $4}')
        fi
    else
        while IFS=' ' read -r w h; do
            local area=$(( w * h ))
            if (( area > best_area )); then
                best_w=$w best_h=$h best_area=$area
            fi
            (( total++ ))
        done < <(xdpyinfo 2>/dev/null \
            | awk '/dimensions:/{split($2,a,"x"); print a[1], a[2]}')
    fi
    (( best_area > 0 )) && echo "$best_w $best_h $total $external"
}

# Pixel-perfect tiling geometry for mpv windows.
# Args: $1=tile index, $2=total tiles, $3=screen width, $4=screen height
# Distributes pixels evenly so tiles differ by at most 1px — zero gaps, zero overlaps.
computeTileGeometryPixel() {
    local idx=$1 total=$2 sw=$3 sh=$4
    local cols
    cols=$(echo "sqrt($total)" | bc -l)
    cols=$(printf '%.0f' "$cols")
    (( cols * cols < total )) && (( cols++ ))
    local rows=$(( (total + cols - 1) / cols ))
    local col=$(( idx % cols ))
    local row=$(( idx / cols ))
    local x=$(( col * sw / cols ))
    local y=$(( row * sh / rows ))
    local w=$(( (col + 1) * sw / cols - x ))
    local h=$(( (row + 1) * sh / rows - y ))
    echo "${w}x${h}+${x}+${y}"
}

# Percentage-based tiling fallback when screen resolution is unknown.
# Args: $1=tile index, $2=total tiles
# mpv percentage offsets are relative to (screen - window), not screen.
computeTileGeometryPercent() {
    local idx=$1 total=$2
    local cols
    cols=$(echo "sqrt($total)" | bc -l)
    cols=$(printf '%.0f' "$cols")
    (( cols * cols < total )) && (( cols++ ))
    local rows=$(( (total + cols - 1) / cols ))
    local w=$(( 100 / cols ))
    local h=$(( 100 / rows ))
    local col=$(( idx % cols ))
    local row=$(( idx / cols ))
    local x=0 y=0
    (( cols > 1 )) && x=$(( col * 100 / (cols - 1) ))
    (( rows > 1 )) && y=$(( row * 100 / (rows - 1) ))
    echo "${w}%x${h}%+${x}%+${y}%"
}

playRtspStream() {
    if ! command -v mpv &> /dev/null; then
        echo -e "${RED}Error: mpv is not installed.${RESET}"
        echo -e "${LIGHTYELLOW}Install it with: ${BLUE}brew install mpv${RESET}"
        return 1
    fi

    local server="$fRtspSrvIp"
    # mpv process architecture:
    #   ├── Network layer (fetches RTSP data)
    #   ├── Stream cache (--cache, mpv's own)
    #   ├── Demuxer (uses FFmpeg's libavformat to parse containers)
    #   │   └── Demuxer buffer (--demuxer-max-bytes, mpv's own queue)
    #   ├── Decoder (uses FFmpeg's libavcodec, or HW decoder like videotoolbox)
    #   └── Video output (renders to screen)
    #
    # Data pipeline (all tuned for zero-latency live RTSP):
    #   Network → [Stream Cache] → Demuxer → [Demuxer Buffer] → Decoder → Display
    #                --cache=no       ↑         --demuxer-max-bytes=200KiB
    #               (disabled)        |        (small queue)
    #                                 |
    #                        --demuxer-readahead-secs=0
    #                        (don't read ahead in time)
    local args=(
        "--profile=low-latency"
        "--hwdec=videotoolbox"
        "--cache=no"
        "--demuxer-max-bytes=500Kib"
        "--demuxer-readahead-secs=0"
        "--demuxer-max-back-bytes=0"
        "--framedrop=decoder+vo"
        "--vd-lavc-threads=1"
        "--vd-lavc-fast"
        "--rtsp-transport=tcp"
        "--video-sync=desync"
        "--audio-buffer=0"
        "--really-quiet"
    )

    local screen_res
    if [[ -n "$fRtspScreenRes" ]]; then
        screen_res="$fRtspScreenRes"
        echo -e "${GREY}Screen resolution: ${screen_res// /x} (manual)${RESET}"
    else
        screen_res=$(getScreenResolution)
        if [[ -n "$screen_res" ]]; then
            local _sw _sh _total _ext
            read -r _sw _sh _total _ext <<< "$screen_res"
            screen_res="$_sw $_sh"
            local monitor_info="${_total} monitor(s)"
            (( _ext > 0 )) && monitor_info+=", ${_ext} external"
            echo -e "${GREY}Detected ${monitor_info}: ${_sw}x${_sh} (pixel mode)${RESET}"
        else
            echo -e "${LIGHTYELLOW}Screen resolution not detected, falling back to percentage mode.${RESET}"
            echo -e "${GREY}Tip: use ${BLUE}--rtsp-resolution <WxH>${GREY} to set manually.${RESET}"
        fi
    fi

    # Auto-fit tiling: cols=ceil(sqrt(N)), rows=ceil(N/cols), row-major order.
    # Uses pixel geometry when screen resolution is known, otherwise falls back to percentage.
    if [ -n "$fRtspMulti" ]; then
        local stream_list
        stream_list=$(getSupportedRtspStreams) || return 1
        if [[ -n "$fRtspFilter" ]]; then
            stream_list=$(echo "$stream_list" | tr ' ' '\n' | grep "$fRtspFilter" | tr '\n' ' ')
        fi
        local streams
        read -ra streams <<< "$stream_list"
        local count=${#streams[@]}
        if (( count == 0 )); then
            echo -e "${RED}Error: no streams available from go2rtc.${RESET}"
            return 1
        fi
        if (( count > MAX_RTSP_STREAMS )); then
            echo -e "${RED}Error: too many streams (${count}). Max supported: ${MAX_RTSP_STREAMS}.${RESET}"
            return 1
        fi
        local use_pixel='' sw sh
        if [[ -n "$screen_res" ]]; then
            read -r sw sh <<< "$screen_res"
            [[ -n "$sw" && -n "$sh" ]] && use_pixel=1
        fi
        args+=(--no-border --ontop)
        # Compare desired stream set against the last-launched set (stored in marker file).
        # Same set → selective relaunch of dead streams only (recovery).
        # Different set → kill all and relaunch with correct geometry.
        local marker="/tmp/jc_rtsp_streams"
        local desired_set
        desired_set=$(printf '%s\n' "${streams[@]}" | sort | tr '\n' ' ')
        if pgrep -x mpv &> /dev/null && [[ -f "$marker" ]]; then
            local previous_set
            previous_set=$(<"$marker")
            if [[ "$desired_set" != "$previous_set" ]]; then
                echo -e "${LIGHTYELLOW}Stream set changed — restarting all streams.${RESET}"
                pkill mpv
                sleep 0.5
            fi
        fi
        echo "$desired_set" > "$marker"
        if [[ -n "$use_pixel" ]]; then
            echo -e "${COLOR}Playing ${count} RTSP streams in auto-fit tiled layout (${sw}x${sh} pixel)${RESET}"
        else
            echo -e "${COLOR}Playing ${count} RTSP streams in auto-fit tiled layout (percentage)${RESET}"
        fi
        local launched=0
        for i in "${!streams[@]}"; do
            if pgrep -f "mpv.*${streams[$i]}" &> /dev/null; then
                echo -e "  ${GREEN}${streams[$i]}${GREY} — already running${RESET}"
                continue
            fi
            local geom mute_flag=()
            if [[ -n "$use_pixel" ]]; then
                geom=$(computeTileGeometryPixel "$i" "$count" "$sw" "$sh")
            else
                geom=$(computeTileGeometryPercent "$i" "$count")
            fi
            (( i > 0 )) && mute_flag=(--mute=yes)
            mpv "rtsp://${server}:8554/${streams[$i]}" "${args[@]}" "${mute_flag[@]}" --geometry="$geom" \
                --force-media-title="${streams[$i]}" 2>/dev/null &
            echo -e "  ${BLUE}${streams[$i]}${GREY} — launched${RESET}"
            (( launched++ ))
        done
        if (( launched == 0 )); then
            echo -e "${CYAN}All ${count} streams already running.${RESET}"
        else
            echo -e "${CYAN}${launched}/${count} stream(s) launched.${RESET} ${BLUE}To stop all: ${LIGHTYELLOW}pkill mpv${RESET}"
        fi
    else
        if [[ -z "$fRtspStream" ]]; then
            local available
            available=$(getSupportedRtspStreams) || return 1
            read -ra available <<< "$available"
            if (( ${#available[@]} == 0 )); then
                echo -e "${RED}Error: no streams available from go2rtc.${RESET}"
                return 1
            fi
            fRtspStream="${available[0]}"
        fi
        local url="rtsp://${server}:8554/${fRtspStream}"
        echo -e "${COLOR}Playing RTSP stream: ${BLUE}${url}${RESET}"
        echo -e "${COLOR}Executing:${RESET} mpv \"${url}\" ${args[*]}${RESET}"
        mpv "$url" "${args[@]}" --force-media-title="${fRtspStream}" 2>/dev/null
        local rc=$?
        if (( rc != 0 )); then
            echo -e "${RED}Error: mpv exited with code ${rc}.${RESET}"
            echo -e "${GREY}Possible causes:${RESET}"
            echo -e "${GREY}  - RTSP server not reachable at ${BLUE}${server}:8554${RESET}"
            echo -e "${GREY}  - Stream ${BLUE}${fRtspStream}${GREY} not available on server${RESET}"
            echo -e "${GREY}  - go2rtc not running (check: ${BLUE}curl -s http://${server}:1984/api/streams${GREY})${RESET}"
            echo -e "${GREY}  - Run without ${BLUE}--really-quiet${GREY} for full mpv output:${RESET}"
            echo -e "${GREY}    mpv \"${url}\" ${args[*]//--really-quiet/}${RESET}\n"
        fi
    fi
}

isVpnInterfaceUp() {
    # A VPN is usable only if the interface has the UP flag AND an IPv4 address.
    # GlobalProtect clears the UP flag on disconnect but leaves the inet line
    # intact, so `inet ` alone is not a reliable liveness signal.
    local out
    out=$(ifconfig "$1" 2>/dev/null) || return 1
    [[ "$out" == *"inet "* ]] || return 1
    grep -qE '<UP[,>]' <<<"$out"
}

detectVpnInterface() {
    local iface
    for iface in $(ifconfig -l); do
        case "$iface" in
            utun*)
                if isVpnInterfaceUp "$iface"; then
                    echo "$iface"
                    return 0
                fi
                ;;
        esac
    done
    return 1
}

isSshTunnelAlive() {
    nc -z 127.0.0.1 "$fSshTunnelLocalPort" >/dev/null 2>&1
}

stopSshTunnel() {
    if [ -n "$fSshTunnelAutosshPid" ]; then
        pkill -P "$fSshTunnelAutosshPid" 2>/dev/null || true
        kill "$fSshTunnelAutosshPid" 2>/dev/null || true
        fSshTunnelAutosshPid=""
    fi
    pkill -f "autossh.*${fSshTunnelLocalPort}:127.0.0.1:${fSshTunnelRemotePort}" 2>/dev/null || true
    pkill -f "ssh.*${fSshTunnelLocalPort}:127.0.0.1:${fSshTunnelRemotePort}" 2>/dev/null || true
}

startSshTunnel() {
    # Caller (waitForTransportReady) already verified the VPN interface is up
    # and the remote SSH port is reachable, so this function focuses solely on
    # launching autossh and confirming the local listener.
    local sshTarget="${USER}@${fSshTunnelRemoteIp}"

    if isSshTunnelAlive; then
        echo -e "${GREEN}✔${GREY} Forward already active on 127.0.0.1:${fSshTunnelLocalPort}.${RESET}"
        return 0
    fi

    echo -e "${LIGHTYELLOW}☞ Setting up SSH port forward (${fSshTunnelLocalPort} → ${fSshTunnelRemoteIp}:${fSshTunnelRemotePort})${RESET}"
    if lsof -i ":${fSshTunnelLocalPort}" -sTCP:LISTEN >/dev/null 2>&1; then
        echo -e "${RED}Error: Local port ${fSshTunnelLocalPort} is already in use:${RESET}"
        lsof -i ":${fSshTunnelLocalPort}" -sTCP:LISTEN 2>/dev/null | head -5
        return 1
    fi

    local sshLog=$(mktemp /tmp/ssh-tunnel-XXXXXXXX)
    autossh -M 0 -f -N \
        -L "${fSshTunnelLocalPort}:127.0.0.1:${fSshTunnelRemotePort}" \
        "$sshTarget" \
        -o "ServerAliveInterval 5" \
        -o "ServerAliveCountMax 3" \
        -o "ExitOnForwardFailure yes" \
        -o "StrictHostKeyChecking accept-new" \
        -o "ConnectTimeout 15" \
        -v -E "$sshLog"
    local maxWait=20
    local waited=0
    while [ "$waited" -lt "$maxWait" ]; do
        if isSshTunnelAlive; then
            break
        fi
        sleep 1
        ((waited++))
    done
    if ! isSshTunnelAlive; then
        echo -e "${RED}Error: Forward failed, port ${fSshTunnelLocalPort} not listening after ${maxWait}s.${RESET}"
        if [ -s "$sshLog" ]; then
            echo -e "${GREY}SSH log (last 20 lines):${RESET}"
            tail -20 "$sshLog"
        fi
        rm -f "$sshLog"
        return 1
    fi
    rm -f "$sshLog"
    fSshTunnelAutosshPid="$(pgrep -n -f "autossh.*${fSshTunnelLocalPort}:127.0.0.1:${fSshTunnelRemotePort}" || true)"
    echo -e "${GREEN}✔${GREY} Forward established.${RESET}"
}

linkSingboxConfig() {
    local target="$fMainDir/assets/$1/sing-box-config.jsonc"
    linkFile "$target" "$(dirname "$fSingboxConfig")"
    # linkFile returns 1 for "already up to date", which is not an error
    local rc=$?
    [[ $rc -le 1 ]] && return 0
    return $rc
}

killSingboxMonitor() {
    [ -n "$fSingboxMonitorPid" ] || return 0
    pkill -P "$fSingboxMonitorPid" 2>/dev/null || true
    kill "$fSingboxMonitorPid" 2>/dev/null || true
    fSingboxMonitorPid=""
}

cleanupSingbox() {
    [ "$fSingboxCleaning" -eq 1 ] && return
    fSingboxCleaning=1
    echo -e "\n${LIGHTYELLOW}⏻ Cleaning up sing-box${RESET}"
    killSingboxMonitor
    sudo pkill -x sing-box 2>/dev/null || true
    [[ "$fSingboxProxyMode" == "xray-tunnel" ]] && stopSshTunnel
    [ -n "$fSingboxRecoveryMarker" ] && rm -f "$fSingboxRecoveryMarker"
    echo -e "${GREEN}✔${GREY} sing-box exited cleanly.${RESET}\n"
}

# Watches the VPN interface (and the SSH tunnel for xray-tunnel mode).
# On loss, writes a reason code to $fSingboxRecoveryMarker and kills sing-box
# so the main loop enters recovery. Intentionally silent — the main shell
# prints the alert banner after sing-box exits so it isn't buried under
# sing-box's post-SIGTERM log flush.
startSingboxMonitor() {
    local vpnInterface="$1"
    (
        while true; do
            if ! isVpnInterfaceUp "$vpnInterface"; then
                echo "vpn_down" > "$fSingboxRecoveryMarker"
                sudo pkill -x sing-box 2>/dev/null || true
                break
            fi
            if [[ "$fSingboxProxyMode" == "xray-tunnel" ]] && ! isSshTunnelAlive; then
                echo "tunnel_down" > "$fSingboxRecoveryMarker"
                sudo pkill -x sing-box 2>/dev/null || true
                break
            fi
            sleep 5
        done
    ) &
    fSingboxMonitorPid=$!
}

# Block until the transport upstream is ready, shared by all three proxy modes.
# Fast path when everything is already healthy; otherwise waits for VPN and
# (for xray-tunnel) (re-)establishes the SSH port forward, all under a single
# end-to-end deadline of fSingboxRetryTimeout.
waitForTransportReady() {
    # Fast path: silent success if already ready.
    if detectVpnInterface >/dev/null 2>&1; then
        case "$fSingboxProxyMode" in
            xray-tunnel) isSshTunnelAlive && return 0 ;;
            *)           return 0 ;;
        esac
    fi

    local deadline=$((SECONDS + fSingboxRetryTimeout))
    local waitingAnnounced=0 vpnAnnounced=0

    while [ "$SECONDS" -lt "$deadline" ]; do
        local remaining=$((deadline - SECONDS))

        # Step 1: wait for VPN interface up
        if ! detectVpnInterface >/dev/null 2>&1; then
            if [ "$waitingAnnounced" -eq 0 ]; then
                echo -e "${CYAN}⏳ Waiting for VPN UP (≤${fSingboxRetryTimeout}s)${RESET}"
                waitingAnnounced=1
            fi
            echo -e "${CYAN}   ↻ ${remaining}s${RESET}"
            sleep 5
            continue
        fi
        if [ "$vpnAnnounced" -eq 0 ] && [ "$waitingAnnounced" -eq 1 ]; then
            echo -e "${GREEN}🟢 VPN recovered.${RESET}"
            vpnAnnounced=1
        fi

        # Step 2: mode-specific transport setup
        case "$fSingboxProxyMode" in
            xray-tunnel)
                # For xray-tunnel we additionally require the remote SSH port
                # to be reachable via the VPN before trying autossh.
                if ! nc -z -G 2 "$fSshTunnelRemoteIp" 22 >/dev/null 2>&1; then
                    echo -e "${CYAN}   ↻ remote SSH not reachable (${remaining}s)${RESET}"
                    sleep 5
                    continue
                fi
                stopSshTunnel
                sleep 2
                startSshTunnel && return 0
                echo -e "${CYAN}   ↻ SSH tunnel setup failed (${remaining}s)${RESET}"
                sleep 5
                ;;
            *)
                return 0
                ;;
        esac
    done

    echo -e "${RED}Error: Failed to bring up transport within ${fSingboxRetryTimeout}s.${RESET}"
    return 1
}

launchSingbox() {
    echo -e "${COLOR}▶ Launching sing-box${RESET}"

    if ! command -v sing-box &>/dev/null; then
        echo -e "${RED}Error: sing-box is not installed.${RESET}"
        return 1
    fi

    if pgrep -x sing-box >/dev/null 2>&1; then
        echo -e "${LIGHTYELLOW}sing-box is already running.${RESET}"
        return 0
    fi

    trap 'cleanupSingbox; exit 0' SIGINT SIGTERM

    fSingboxRecoveryMarker=$(mktemp /tmp/singbox-recovery.XXXXXX)

    # Auto-detect proxy mode from config
    local proxyMode=""
    if command -v jq &>/dev/null && [ -f "$fSingboxConfig" ]; then
        local configJson
        configJson=$(sed '/^[[:space:]]*\/\//d' "$fSingboxConfig")

        local wgEndpoint
        wgEndpoint=$(echo "$configJson" | jq -r '.endpoints[]? | select(.type == "wireguard") | .tag' 2>/dev/null)
        if [[ -n "$wgEndpoint" ]]; then
            proxyMode="wireguard"
            echo -e "${GREEN}✔${GREY} WireGuard mode detected, no SSH tunnel needed.${RESET}"
        else
            local proxyServer
            proxyServer=$(echo "$configJson" | jq -r '.outbounds[] | select(.tag == "proxy") | .server' 2>/dev/null)
            if [[ -n "$proxyServer" ]]; then
                if [[ "$proxyServer" == "127.0.0.1" || "$proxyServer" == "localhost" ]]; then
                    proxyMode="xray-tunnel"
                    # Derive SSH tunnel ports from the config's proxy outbound
                    # so changing the port in one place keeps autossh in sync.
                    local proxyPort
                    proxyPort=$(echo "$configJson" | jq -r '.outbounds[] | select(.tag == "proxy") | .server_port' 2>/dev/null)
                    if ! [[ "$proxyPort" =~ ^[0-9]+$ ]] || (( proxyPort < 1 || proxyPort > 65535 )); then
                        echo -e "${RED}Error: Invalid proxy.server_port in config: '${proxyPort}'.${RESET}"
                        cleanupSingbox
                        return 1
                    fi
                    fSshTunnelLocalPort="$proxyPort"
                    fSshTunnelRemotePort="$proxyPort"
                    echo -e "${GREEN}✔${GREY} xray-tunnel mode (127.0.0.1:${proxyPort} → ${fSshTunnelRemoteIp}:${proxyPort}).${RESET}"
                else
                    proxyMode="xray-direct"
                    echo -e "${GREEN}✔${GREY} Direct xray mode (${proxyServer}), no SSH tunnel needed.${RESET}"
                fi
            fi
        fi
    fi

    if [[ -z "$proxyMode" ]]; then
        echo -e "${RED}Error: Could not detect proxy mode from config. Only xray and wireguard are supported.${RESET}"
        cleanupSingbox
        return 1
    fi
    fSingboxProxyMode="$proxyMode"

    if ! waitForTransportReady; then
        cleanupSingbox
        return 1
    fi

    while true; do
        # Reset marker and cleaning flag for this iteration
        true > "$fSingboxRecoveryMarker"
        fSingboxCleaning=0

        # All three modes depend on the corp VPN utun interface being up; the
        # monitor watches it and kills sing-box to trigger the recovery loop.
        local vpnInterface
        vpnInterface="$(detectVpnInterface)" || {
            echo -e "${RED}Error: No utun* interface with an IPv4 address found.${RESET}"
            cleanupSingbox
            return 1
        }
        startSingboxMonitor "$vpnInterface"

        echo -e "${BOLD}${GREEN}━━━ ▶ sing-box running (Ctrl+C to quit) ━━━${RESET}"
        sudo sing-box run -c "$fSingboxConfig"

        # sing-box exited — stop the watchdog before deciding why.
        killSingboxMonitor

        if [ ! -s "$fSingboxRecoveryMarker" ]; then
            # Marker empty: user Ctrl+C or sing-box crashed on its own
            cleanupSingbox
            return 0
        fi

        # Marker non-empty → monitor tripped (vpn_down / tunnel_down).
        # We print the alert banner HERE (not from the monitor subshell)
        # so it lands after sing-box has flushed its exit-time log spam,
        # keeping the whole recovery block visually contiguous.
        local reasonMsg
        case "$(cat "$fSingboxRecoveryMarker")" in
            vpn_down)    reasonMsg="VPN interface lost" ;;
            tunnel_down) reasonMsg="SSH tunnel dropped" ;;
            *)           reasonMsg="unknown failure" ;;
        esac
        echo -e "\n${BOLD}${RED}━━━ 🔴 ${reasonMsg} ━━━${RESET}"
        echo -e "${GREY}   → stopping sing-box, entering recovery${RESET}"

        stopSshTunnel
        if ! waitForTransportReady; then
            cleanupSingbox
            return 1
        fi
    done
}

doEarlyExitJobs() {
    [ -n "$fLinkClangFormatPath" ] && { linkClangFormat "$1"; exit 0; }
    [ -n "$fClaudeLinkMcpJson" ]   && { linkClaudeMcpJson; exit 0; }
    [ -n "$fCheckTlsConn" ]        && { checkTlsConnection "$1"; exit 0; }
    case "$fCursorAction" in
        backup)  backupCursorSettings;  exit $? ;;
        restore) restoreCursorSettings; exit $? ;;
    esac
    case "$fClaudeAction" in
        backup)  backupClaudeCodeSettings;  exit $? ;;
        restore) restoreClaudeCodeSettings; exit $? ;;
    esac
    case "$fClaudeDesktopAction" in
        backup)  backupClaudeDesktopSettings;  exit $? ;;
        restore) restoreClaudeDesktopSettings; exit $? ;;
    esac
    case "$fCodexAction" in
        backup)  backupCodexSettings;  exit $? ;;
        restore) restoreCodexSettings; exit $? ;;
    esac
    [ -n "$fDisplayMode" ]         && { switchDisplayMode "$fDisplayMode"; exit 0; }
    [ -n "$fRtspKill" ]            && { killRtspStreams; exit 0; }
    [ -n "$fRtspList" ]            && { listRtspStreams; exit 0; }
    [ -n "$fRtspFlag" ]            && { playRtspStream; exit 0; }
    [ -n "$fSambaServerFlag" ]     && { installSambaServer; exit 0; }
    if [ -n "$fSingboxLink" ]; then
        linkSingboxConfig "$fSingboxLink" || exit $?
        [ -z "$fSingbox" ] && exit 0
    fi
    [ -n "$fSingbox" ]             && { launchSingbox; exit $?; }
    [ -n "$fXrayUpdate" ]          && { installXray; exit 0; }
    [ -n "$fXrayRemove" ]          && { removeXray; exit 0; }
    [ -n "$fWireguardUpdate" ]     && { installWireguard; exit 0; }
    [ -n "$fWireguardRemove" ]     && { removeWireguard; exit 0; }
    [ -n "$fSwapReq" ]             && { addSwap "$1"; exit 0; }
    [ -n  "$fVncLockAction" ]      && { vncLock "$fVncLockAction"; exit 0; }
    case "$fVncServer" in
        1) startVncServer;       exit 0 ;;
        2) stopVncServer;        exit 0 ;;
        3) restartVncServer;     exit 0 ;;
    esac
}

showUfwStatus() {
    # UFW is Linux-specific, skip on macOS
    if [[ $(uname -s) == 'Darwin' ]]; then
        return
    fi

    if ! command -v ufw &> /dev/null || sudo ufw status | grep -qw "Status: inactive"; then
        return
    fi
    echo -e "${COLOR}Checking UFW Firewall Status${RESET}"
    sudo ufw status verbose
    echo -e "${LIGHTYELLOW}Tip: Common UFW commands:${RESET}"
    echo -e "  ${GREY}- sudo ufw status        : Check if the firewall is active.${RESET}"
    echo -e "  ${GREY}- sudo ufw enable        : Enable the firewall.${RESET}"
    echo -e "  ${GREY}- sudo ufw disable       : Disable the firewall.${RESET}"
    echo -e "  ${GREY}- sudo ufw allow <port>  : Allow traffic on a specific port (e.g., sudo ufw allow 445/tcp).${RESET}"
    echo -e "  ${GREY}- sudo ufw deny <port>   : Deny traffic on a specific port.${RESET}"
    echo -e "  ${GREY}- sudo ufw delete allow <port>: Delete an allow rule (e.g., sudo ufw delete allow 445/tcp).\n${RESET}"
}

main() {
    doEarlyExitJobs "$1"
    checkOSAndArch
    checkTlsConnection
    createEssentialPaths
    case "$fOSCategory" in
        debian) doDebianJobs ;;
        mac)    doMacJobs    ;;
    esac
    showUfwStatus
    echo -e "${GREEN}${SCRIPT_NAME} completed successfully in ${SECONDS}s.${RESET}"
}

main "$@"