path: root/archsetup

#!/bin/bash
# ArchSetup - Craig Jennings <craigmartinjennings@gmail.com>
# https://cjennings.net/archsetup
# License: GNU GPLv3

# Commentary
#
# There are two levels of errors:
# * CRASH: Issues that will halt forward progress, aborting this script.
# * ERROR: Issues not serious enough to halt the script.
# Both are printed on screen and in the $logfile.
# Stderr is also printed to the $logfile for all relevant info.
#
# This script creates a tmpfs RAM disk for all compilation. This speeds up
# building and installing, and all source code no longer exists after reboot.
#
# # Code

# uncomment to stop on any error
# set -e

### Root Check

if [ "$EUID" -ne 0 ]; then
    echo "ERROR: This script must be run as root"
    echo "Usage: sudo $0"
    exit 1
fi

### Parse Arguments

skip_slow_packages=false
fresh_install=false
show_status_only=false
skip_gpu_drivers=false

while [ $# -gt 0 ]; do
    case "$1" in
        --skip-slow-packages)
            skip_slow_packages=true
            shift
            ;;
        --fresh)
            fresh_install=true
            shift
            ;;
        --status)
            show_status_only=true
            shift
            ;;
        --no-gpu-drivers)
            skip_gpu_drivers=true
            shift
            ;;
        --help|-h)
            echo "Usage: $0 [OPTIONS]"
            echo ""
            echo "Options:"
            echo "  --skip-slow-packages  Skip texlive-meta and topgrade"
            echo "  --fresh               Start fresh, ignore previous progress"
            echo "  --status              Show installation progress and exit"
            echo "  --no-gpu-drivers      Skip GPU driver detection/installation"
            echo "  --help, -h            Show this help message"
            exit 0
            ;;
        *)
            echo "Unknown option: $1"
            echo "Usage: $0 [--skip-slow-packages] [--fresh] [--status] [--no-gpu-drivers]"
            exit 1
            ;;
    esac
done

### Constants

username="cjennings"
password="welcome"  # will be changed on first login. :)

archsetup_dir="$(dirname "$(readlink -f "$0")")"
dotfiles_dir="$archsetup_dir/dotfiles"

dwm_repo="https://git.cjennings.net/dwm.git"
dmenu_repo="https://git.cjennings.net/dmenu.git"
st_repo="https://git.cjennings.net/st.git"
slock_repo="https://git.cjennings.net/slock.git"
dotemacs_repo="https://git.cjennings.net/dotemacs.git"

logfile="/var/log/archsetup-$(date +'%Y-%m-%d-%H-%M-%S').log"
source_dir="/home/$username/.local/src" # aur/git source goes here
packages_before="/var/log/archsetup-preexisting-package-list.txt"
packages_after="/var/log/archsetup-post-install-package-list.txt"
archsetup_packages="/var/log/archsetup-installed-packages.txt"

min_disk_space_gb=20
state_dir="/var/lib/archsetup/state"
error_messages=()

### Cleanup Trap
# Ensures tmpfs is unmounted if script exits unexpectedly
cleanup() {
    if mountpoint -q "$source_dir" 2>/dev/null; then
        umount "$source_dir" 2>/dev/null
    fi
}
trap cleanup EXIT

### State Tracking
# Enables resuming from where the script left off if interrupted.
# State is stored as marker files in $state_dir.
# Use --fresh to start over, --status to check progress.

step_completed() {
    [ -f "$state_dir/$1" ]
}

mark_complete() {
    mkdir -p "$state_dir"
    echo "$(date +'%Y-%m-%d %H:%M:%S')" > "$state_dir/$1"
}

run_step() {
    step_name="$1"
    step_func="$2"

    if step_completed "$step_name"; then
        printf "Skipping %s (already completed)\n" "$step_name"
        return 0
    fi

    if $step_func; then
        mark_complete "$step_name"
        return 0
    else
        printf "FAILED: %s\n" "$step_name"
        printf "To retry this step, remove: %s/%s\n" "$state_dir" "$step_name"
        return 1
    fi
}

show_status() {
    echo "Archsetup State Status"
    echo "======================"
    echo "State directory: $state_dir"
    echo ""
    if [ ! -d "$state_dir" ]; then
        echo "No state found. Script has not been run or was run with --fresh."
        exit 0
    fi
    echo "Completed steps:"
    for step in intro prerequisites create_user user_customizations \
                aur_installer essential_services xorg dwm \
                desktop_environment developer_workstation \
                supplemental_software boot_ux; do
        if step_completed "$step"; then
            timestamp=$(cat "$state_dir/$step")
            printf "  [x] %-25s (%s)\n" "$step" "$timestamp"
        else
            printf "  [ ] %-25s\n" "$step"
        fi
    done
    exit 0
}

# Handle --status flag (must be after state_dir is defined)
if $show_status_only; then
    show_status
fi

# Handle --fresh flag
if $fresh_install; then
    echo "Starting fresh installation (removing previous state)..."
    rm -rf "$state_dir"
fi

### Pre-flight Checks
preflight_checks() {
    echo "Running pre-flight checks..."

    # Check disk space (need at least 20GB free on root partition)
    available_kb=$(df / | awk 'NR==2 {print $4}')
    available_gb=$((available_kb / 1024 / 1024))
    if [ "$available_gb" -lt "$min_disk_space_gb" ]; then
        echo "ERROR: Insufficient disk space"
        echo "  Required: ${min_disk_space_gb}GB"
        echo "  Available: ${available_gb}GB"
        echo "  Free up disk space before running archsetup."
        exit 1
    fi
    echo "  [OK] Disk space: ${available_gb}GB available"

    # Check network connectivity
    if ! ping -c 1 -W 5 archlinux.org > /dev/null 2>&1; then
        echo "ERROR: No network connectivity"
        echo "  Cannot reach archlinux.org"
        echo "  Ensure network is configured before running archsetup."
        echo "  Try: ip link, dhcpcd, or nmtui"
        exit 1
    fi
    echo "  [OK] Network: archlinux.org reachable"

    # Check pacman is available
    if ! command -v pacman > /dev/null 2>&1; then
        echo "ERROR: pacman not found"
        echo "  This script requires Arch Linux with pacman installed."
        exit 1
    fi
    echo "  [OK] Package manager: pacman available"

    # Check we're on Arch Linux
    if [ ! -f /etc/arch-release ]; then
        echo "ERROR: Not running on Arch Linux"
        echo "  This script is designed for Arch Linux only."
        exit 1
    fi
    echo "  [OK] System: Arch Linux detected"

    echo "Pre-flight checks passed."
    echo ""
}

### Intro
intro() {
    printf "\n\nArchSetup launched @ %s\n" "$(date +'%D %T')"| tee -a "$logfile"
    if $skip_slow_packages; then
        printf "Running with --skip-slow-packages (skipping texlive-meta, topgrade)\n" | tee -a "$logfile"
    fi
    STARTTIME=$(date +%s)
    errors_encountered=0

    # begin with a clean logfile
    [ -f "$logfile" ] && rm -f "$logfile"
    touch "$logfile"

    # count the arch packages before install
    pacman -Q > "$packages_before" || \
        error "crash" "generating pre-install package list" "$?"
}

### General Functions
# Error
error () {
    # $1 = type ERROR, noted but the script will continue to run.
    #      anything else will produce CRASH, which halts the script
    # $2 = what was happening (e.g., "adding $username to group $groupname")
    # $3 = the error code (i.e., "$?")

    errors_encountered=$((errors_encountered+1))
    case "$1" in
        "error")
            msg="$2 (error code: $3)"
            error_messages+=("$msg")
            printf "ERROR: %s @ %s\n" "$msg" "$(date +'%T')" | tee -a "$logfile"
            return 1;
            ;;
        *)
            printf "CRASH: %s failed with error: %s @ %s. Script halted.\n" \
                   "$2" "$3"  "$(date +'%T')"  | tee -a "$logfile"
            exit 1;
            ;;
    esac
}

#  Display
display () {
    # $1 = type (TITLE, ACTION)
    # $2 = description (answers: "what are you trying to do?")

    case "$1" in
        "title")
            printf "\n##### %s\n" "$2" | tee -a "$logfile"
            return 0;
            ;;
        "subtitle")
            printf "\n%s\n" "$2"  | tee -a "$logfile"
            return 0;
            ;;
        "task")
            printf "...%s @ %s\n" "$2" "$(date +'%T')" | tee -a "$logfile"
            return 0;
            ;;
        *)
            printf "CRASH: display () called with incorrect arguments.\n"
            printf "...called %s type, %s action @ %s\n" \
                   "$1" "$2"  "$(date +'%T')"   | tee -a "$logfile"
            exit 1;
            ;;
    esac

}

# Pacman Install
pacman_install() {
    action="installing $1 via pacman" && display "task" "$action"
    if ! (pacman --noconfirm --needed -S "$1" >> "$logfile" 2>&1); then
        action="retrying $1" && display "task" "$action"
        if ! (pacman --noconfirm --needed -S "$1" >> "$logfile" 2>&1); then
            action="retrying $1 once more" && display "task" "$action"
            (pacman --noconfirm --needed -S "$1" >> "$logfile" 2>&1) ||
                error "error" "$action" "$?"
        fi
    fi
}

# Git Install
git_install() {
    prog_name="$(basename "$1" .git)"
    build_dir="$source_dir/$prog_name"
    action="building & installing $prog_name from source"
    display "task" "$action"

    if ! (sudo -u "$username" git clone --depth 1 "$1" "$build_dir" >> "$logfile" 2>&1); then
        error "error" "cloning source code for $prog_name - directory may exist, removing and retrying" "$?"
        (rm -rf "$build_dir" >> "$logfile" 2>&1) || \
            error "error" "removing existing directory for $prog_name" "$?"
        (sudo -u "$username" git clone --depth 1 "$1" "$build_dir" >> "$logfile" 2>&1) || \
            error "crash" "re-cloning source code for $prog_name after cleanup" "$?"
    fi

    (cd "$build_dir" && make install >> "$logfile" 2>&1) || \
        error "error" "building $prog_name from source code" "$?"
}

# AUR Install
aur_install() {
    action="installing $1 via the AUR" && display "task" "$action"
    if ! (sudo -u "$username" yay -S --noconfirm "$1" >> "$logfile" 2>&1); then
        action="retrying $1" && display "task" "$action"
        if ! (sudo -u "$username" yay -S --noconfirm "$1" >> "$logfile" 2>&1); then
            action="retrying $1 once more" && display "task" "$action"
            (sudo -u "$username" yay -S --noconfirm "$1" >> "$logfile" 2>&1) ||
                error "error" "$action" "$?"
        fi
    fi
}

# PIP Install (using pipx for isolated environments)
pip_install() {
    [ -x "$(command -v "pipx")" ] || pacman_install python-pipx
    action="installing $1 via pipx" && display "task" "$action"
    (sudo -u "$username" pipx install "$1" >> "$logfile" 2>&1)  || \
        error "error" "$action" "$?"
}

# Filesystem Detection
is_zfs_root() {
    # Returns 0 (true) if root filesystem is ZFS, 1 (false) otherwise
    [ "$(findmnt -n -o FSTYPE /)" = "zfs" ]
}

# GPU Driver Installation
install_gpu_drivers() {
    if $skip_gpu_drivers; then
        display "task" "Skipping GPU driver installation (--no-gpu-drivers)"
        return 0
    fi

    display "subtitle" "GPU Drivers"

    # Detect GPU vendors via lspci
    gpu_info=$(lspci 2>/dev/null | grep -E "VGA|3D")

    if echo "$gpu_info" | grep -qi "intel"; then
        display "task" "Intel GPU detected - installing drivers"
        pacman_install mesa
        pacman_install intel-media-driver     # hardware video acceleration
        pacman_install vulkan-intel           # Vulkan support
    fi

    if echo "$gpu_info" | grep -qi "amd\|radeon"; then
        display "task" "AMD GPU detected - installing drivers"
        pacman_install mesa
        pacman_install xf86-video-amdgpu
        pacman_install vulkan-radeon
        pacman_install libva-mesa-driver      # hardware video acceleration
    fi

    if echo "$gpu_info" | grep -qi "nvidia"; then
        display "task" "NVIDIA GPU detected - installing drivers"
        pacman_install nvidia-dkms            # DKMS version for kernel flexibility
        pacman_install nvidia-utils
        pacman_install nvidia-settings
        pacman_install libva-nvidia-driver    # hardware video acceleration
    fi

    # Fallback for VMs or unknown hardware
    if ! echo "$gpu_info" | grep -qiE "intel|amd|radeon|nvidia"; then
        display "task" "No discrete GPU detected - installing generic drivers"
        pacman_install mesa
        pacman_install xf86-video-vesa
    fi
}

### Prerequisites
prerequisites() {
    # why these software packages are 'required'
    # linux-firmware    - ensuring hardware can be detected properly
    # base_devel        - required tools to compile
    # ca_certificates   - for validation of keyrings, etc.
    # coreutils         - comparing package lists
    # curl              - to transfer source code
    # git               - tools required to work with git source respositories
    # go                - required to build yay, the aur installer
    # ntp               - must communicate with other servers in synchronized manner
    # python            - required for python pip installs
    # stow              - places the dotfiles (see: https://bit.ly/41GmysO)
    # tar               - extract unix archives
    # vi                - should things go wrong, we'll need an editor
    # zsh               - we need a shell interpreter for yay; this one's mine

    display "title" "Prerequisites"

    display "subtitle" "Bootstrapping"

    action="ensuring current Arch Linux keyring" && display "task" "$action"
    (pacman -Syy) >> "$logfile" 2>&1  || error "crash" "$action" "$?"
    (pacman -S --noconfirm archlinux-keyring) >> "$logfile" 2>&1  || \
        error "crash" "$action" "$?"

    display "task" "verifying Arch Linux keys"
    (pacman-key --populate archlinux >> "$logfile" 2>&1) || \
        error "crash" "verifying Arch Linux keys" "$?"

    action="refreshing the package cache" && display "task" "$action"
    (pacman -Syu --noconfirm >> "$logfile" 2>&1)  || error "crash" "$action" "$?"

    display "subtitle" "Required Software"

    for software in linux-firmware base-devel ca-certificates \
                                   coreutils curl git go ntp openssh python \
                                   stow tar vi zsh; do
        pacman_install "$software"
    done

    display "subtitle" "Environment Configuration"

    # sync the time on this machine
    action="synchronizing system time" && display "task" "$action"
    (ntpdate 0.us.pool.ntp.org >> "$logfile" 2>&1) || error "error" "$action" "$?"

    action="configuring compiler to use all processor cores" && display "task" "$action"
    sed -i "s/-j2/-j$(nproc)/;s/^#MAKEFLAGS/MAKEFLAGS/" /etc/makepkg.conf >> "$logfile" 2>&1

    action="disabling debug packages in makepkg" && display "task" "$action"
    sed -i 's/^OPTIONS=.*/OPTIONS=(strip docs !libtool !staticlibs emptydirs zipman purge !debug)/' /etc/makepkg.conf >> "$logfile" 2>&1

    # enable pacman concurrent downloads and color
    action="enabling concurrent downloads" && display "task" "$action"
    sed -i "s/^#ParallelDownloads.*$/ParallelDownloads = 10/;s/^#Color$/Color/" /etc/pacman.conf

    action="Package Mirrors" && display "subtitle" "$action"
    pacman_install reflector

    action="configuring reflector" && display "task" "$action"
    cat << 'EOF' > /etc/xdg/reflector/reflector.conf
--connection-timeout 3
--download-timeout 3
--protocol https
--age 12
--latest 20
--score 10
--fastest 5
--sort score
--save /etc/pacman.d/mirrorlist
EOF

    # Skip running reflector during installation - it can cause SSH disconnections during testing
    # The reflector.timer will update mirrors automatically later
    # action="updating repository mirrors" && display "task" "$action"
    # (reflector --connection-timeout 3 \
    #            --download-timeout 3 \
    #            --protocol https \
    #            --age 12 \
    #            --latest 20 \
    #            --score 10 \
    #            --fastest 5 \
    #            --sort score \
    #            --save /etc/pacman.d/mirrorlist > /dev/null 2>&1)

    action="enabling the reflector timer" && display "task" "$action"
    (systemctl enable reflector.timer >> "$logfile" 2>&1) || \
        error "error" "$action" "$?"

    action="replacing sudoers file if new package version exists" && display "task" "$action"
    [ -f /etc/sudoers.pacnew ] && cp /etc/sudoers.pacnew /etc/sudoers >> "$logfile" 2>&1

    action="creating a directory to build/install software from git/AUR."
    (mkdir -p "$source_dir") || error "crash" "creating the directory $source_dir"

}

### Create User
create_user () {
    display "title" "User Creation"

    display "task" "checking if user exists"
    # halt if $username exists
    ( id -u "$username" >/dev/null 2>&1; ) && \
        error "crash" "user '$username' already exists!"

    # create $username with home, group, shell, password
    action="creating user and home directory" && display "task" "$action"
    (useradd -m -G wheel -s /bin/zsh "$username" >> "$logfile" 2>&1) || \
        error "crash" "adding user '$username" "$?"

    display "task" "assigning the password"
    echo "$username:$password" | chpasswd  # any text is allowable! be careful!

    display "task" "adding to appropriate groups"
    (usermod -aG \
             sys,adm,network,scanner,power,uucp,audio,lp,rfkill,video,storage,optical,users \
             "$username" >> "$logfile" 2>&1) || error "crash" "adding $username to groups" "$?"

    display "task" "configuring shell"
    # zsh cache required: $username will install via yay; zsh will run those commands
    mkdir -p "/home/$username/.cache/zsh/"

    # give $username sudo nopasswd rights (required for aur installs)
    display "task" "granting permissions"
    (echo "%$username ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers) \
        || error "error" "$action" "$?"

    # mount as ramdisk to speed aur/git build/installs
    (mount -t tmpfs -o size=4G archsetup "$source_dir" >> "$logfile" 2>&1) || \
        error "crash" "mounting the RAM disk for archsetup" "$?"

    (chown -R "$username":wheel "$(dirname "$source_dir")" >> "$logfile" 2>&1) || \
        error "crash" "changing ownership of $source_dir" "$?"
}

### User Customizations
user_customizations() {
    action="User Customizations" && display "title" "$action"

    # Copy archsetup to user's home directory so dotfile symlinks are accessible.
    # Without this, stow creates symlinks pointing to wherever archsetup was run from
    # (e.g., /root/archsetup), which the user cannot read after login.
    user_archsetup_dir="/home/$username/code/archsetup"
    action="copying archsetup to user's home directory" && display "task" "$action"
    (mkdir -p "$user_archsetup_dir" && \
        cp -r "$archsetup_dir"/* "$user_archsetup_dir/" && \
        chown -R "$username": "/home/$username/code" \
        >> "$logfile" 2>&1) || error "error" "$action" "$?"

    # Update dotfiles_dir to point to user-accessible location
    dotfiles_dir="$user_archsetup_dir/dotfiles"

    action="linking dotfiles into place" && display "task" "$action"
    (cd "$dotfiles_dir"  &&  stow --target="/home/$username" --no-folding --adopt system \
                                >> "$logfile" 2>&1 )  || error "error" "$action" "$?"

    action="restoring dotfile versions" && display "task" "$action"
    (cd "$dotfiles_dir" &&  git restore . \
                                >> "$logfile" 2>&1 )  || error "error" "$action" "$?"

    action="creating common directories" && display "task" "$action"
    # Create default directories and grant permissions
    {
        mkdir -p -m 751 "/home/$username/code"
        mkdir -p -m 751 "/home/$username/documents"
        mkdir -p -m 751 "/home/$username/downloads/torrents/complete"
        mkdir -p -m 751 "/home/$username/downloads/torrents/incomplete"
        mkdir -p -m 751 "/home/$username/downloads/torrents/files"
        mkdir -p -m 751 "/home/$username/downloads/ebooks"
        mkdir -p -m 751 "/home/$username/music"
        mkdir -p -m 751 "/home/$username/projects"
        mkdir -p -m 751 "/home/$username/pictures/screenshots"
        mkdir -p -m 751 "/home/$username/videos"
        mkdir -p -m 751 "/home/$username/vms"
        chown -R "$username": "/home/$username"

        mkdir -p -m 751 /media/backup
        mkdir -p -m 751 /media/remote0
        mkdir -p -m 751 /media/remote1
        mkdir -p -m 751 /media/remote2
        chown -R "$username": /media
    }  >> "$logfile" 2>&1
}

### AUR Installer
aur_installer () {
    display "title" "AUR Installer"

    yay_repo="https://aur.archlinux.org/yay.git"
    build_dir="$source_dir/yay"

    display "task" "fetching source code for yay"
    if ! (sudo -u "$username" git clone --depth 1 "$yay_repo" "$build_dir" >> "$logfile" 2>&1); then
        error "error" "cloning source code for yay - directory may exist, removing and retrying" "$?"
        (rm -rf "$build_dir" >> "$logfile" 2>&1) || \
            error "crash" "removing existing directory for yay" "$?"
        (sudo -u "$username" git clone --depth 1 "$yay_repo" "$build_dir" >> "$logfile" 2>&1) || \
            error "crash" "re-cloning source code for yay after cleanup" "$?"
    fi

    action="packaging and installing yay"; display "task" "$action"
    (cd "$build_dir" && sudo -u "$username" makepkg --noconfirm -si >> "$logfile" 2>&1) || \
        error "crash" "$action" "$?"
}

### Essential Services
essential_services() {
    display "title" "Essential Services"

    # Randomness

    display "subtitle" "Randomness"
    pacman_install rng-tools
    action="enabling rngd service" && display "task" "$action"
    systemctl enable rngd >> "$logfile" 2>&1  || error "error" "$action" "$?"
    action="starting rngd service" && display "task" "$action"
    systemctl start rngd >> "$logfile" 2>&1  || error "error" "$action" "$?"

    # Networking

    display "subtitle" "Networking"
    pacman_install networkmanager
    action="enabling NetworkManager" && display "task" "$action"
    systemctl enable NetworkManager.service >> "$logfile" 2>&1 || error "error" "$action" "$?"

    action="configuring MAC address randomization" && display "task" "$action"
    mkdir -p /etc/NetworkManager/conf.d
    cat << 'EOF' > /etc/NetworkManager/conf.d/wifi-privacy.conf
[device-mac-randomization]
# Randomize MAC during WiFi scans
wifi.scan-rand-mac-address=yes

[connection-mac-randomization]
# Random MAC for each WiFi connection (prevents tracking)
wifi.cloned-mac-address=random
# Stable MAC for ethernet (avoids issues with MAC-based DHCP reservations)
ethernet.cloned-mac-address=stable
EOF

    # Encrypted DNS (DNS over TLS)

    action="configuring encrypted DNS (DNS over TLS)" && display "task" "$action"
    mkdir -p /etc/systemd/resolved.conf.d
    cat << 'EOF' > /etc/systemd/resolved.conf.d/dns-over-tls.conf
[Resolve]
# Use Cloudflare and Quad9 with DNS-over-TLS
DNS=1.1.1.1#cloudflare-dns.com 9.9.9.9#dns.quad9.net
FallbackDNS=1.0.0.1#cloudflare-dns.com 149.112.112.112#dns.quad9.net
DNSOverTLS=yes
DNSSEC=yes
EOF

    # Configure NetworkManager to use systemd-resolved
    cat << 'EOF' > /etc/NetworkManager/conf.d/dns.conf
[main]
dns=systemd-resolved
EOF

    # Note: If Docker containers have DNS issues, systemd-resolved's stub resolver
    # (127.0.0.53) may be the cause. Fix: configure Docker to use direct DNS, or
    # disable systemd-resolved and use /etc/resolv.conf directly. (2026-01-18)
    action="enabling systemd-resolved" && display "task" "$action"
    systemctl enable systemd-resolved >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Create resolv.conf symlink to systemd-resolved
    action="linking resolv.conf to systemd-resolved" && display "task" "$action"
    ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Power

    display "subtitle" "Power"
    pacman_install upower
    action="enabling upower service" && display "task" "$action"
    systemctl enable upower >> "$logfile" 2>&1  || error "error" "$action" "$?"

    # Secure Shell

    display "subtitle" "Secure Shell"
    pacman_install openssh
    action="enabling the openssh service to run at boot" && display "task" "$action"
    systemctl enable sshd >> "$logfile" 2>&1  || error "error" "$action" "$?"
    action="starting the openssh service" && display "task" "$action"
    systemctl start sshd >> "$logfile" 2>&1   || error "error" "$action" "$?"

    # SSH Brute Force Protection

    display "subtitle" "SSH Brute Force Protection"
    pacman_install fail2ban

    action="configuring fail2ban for SSH protection" && display "task" "$action"
    cat << 'EOF' > /etc/fail2ban/jail.local
[DEFAULT]
# Ban for 10 minutes by default
bantime = 10m
findtime = 10m
maxretry = 5
# Use ufw for ban actions
banaction = ufw

[sshd]
enabled = true
port = ssh
# Stricter settings for SSH: 3 attempts, 1 hour ban
maxretry = 3
bantime = 1h
EOF

    action="enabling fail2ban service" && display "task" "$action"
    systemctl enable fail2ban >> "$logfile" 2>&1 || error "error" "$action" "$?"
    action="starting fail2ban service" && display "task" "$action"
    systemctl start fail2ban >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Firewall

    # deny all connections by default, then allow the following:
    # http/s                    : 80/tcp, 443/tcp
    # tor                       : 9040,9050,9051,9053,9119/tcp
    # email                     : IMAP, IMAPS
    # mDNS printer discovery    : 5353/udp
    # ssh                       : ssh
    # syncthing                 : 22000/tcp, 22000/udp, 21027/udp
    # torrents                  : transmission
    # calibre content server    : 8080/tcp
    # warpinator transfers      : 42000/tcp, 42000/udp
    # warpinator registration   : 42000/tcp, 42000/udp
    # warpinator zeroconf       : 5353/tcp, 5353/udp

    display "subtitle" "Firewall"
    pacman_install ufw

    action="configuring ufw to deny by default" && display "task" "$action"
    ufw default deny incoming >> "$logfile" 2>&1 || error "error" "$action" "$?"

    for protocol in \
        "80,443,8080/tcp" \
            "9040,9050,9051,9053,9119/tcp" \
            "IMAP" "IMAPS" \
            "ssh" \
            "22000/tcp" "22000/udp" "21027/udp" \
            "42001/tcp" "42001/udp" \
            "42000/tcp" "42000/udp" \
            "5353/tcp" "5353/udp" \
            "transmission" \
        ; do
        action="adding ufw rule to allow $protocol" && display "task" "$action"
        (ufw allow "$protocol"  >> "$logfile" 2>&1) || error "error" "$action" "$?"
    done

    action="adding limits to protect from brute force attacks" && display "task" "$action"
    (ufw limit 22/tcp  >> "$logfile" 2>&1 && \
         ufw limit 443/tcp >> "$logfile" 2>&1) || \
        error "error" "$action" "$?"

    action="enabling firewall service to launch on boot" && display "task" "$action"
    systemctl enable ufw.service >> "$logfile" 2>&1  || error "error" "$action" "$?"

    action="starting firewall service" && display "task" "$action"
    systemctl start ufw.service >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Service Discovery

    display "subtitle" "Network Service Discovery"
    pacman_install nss-mdns # GNU Name Service Switch host name resolution
    pacman_install avahi # service discovery on a local network using mdns

    action="enabling avahi for mDNS discovery" && display "task" "$action"
    # Note: systemd-resolved handles DNS (with DoT), avahi handles mDNS (.local)
    systemctl enable avahi-daemon.service >> "$logfile" 2>&1 || error "error" "$action" "$?"

    pacman_install geoclue # geolocation service for location-aware apps
    action="enabling geoclue geolocation service" && display "task" "$action"
    systemctl enable geoclue.service >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Job Scheduling

    display "subtitle" "Job Scheduling"
    pacman_install cronie
    action="enabling cronie to launch at boot" && display "task" "$action"
    systemctl enable cronie  >> "$logfile" 2>&1  || error "error" "$action" "$?"
    pacman_install at
    action="enabling the batch delayed command scheduler" && display "task" "$action"
    systemctl enable atd  >> "$logfile" 2>&1  || error "error" "$action" "$?"

    # Package Repository Cache Maintenance

    display "subtitle" "Package Repository Cache Maintenance"
    pacman_install pacman-contrib
    action="enabling the package cache cleanup timer" && display "task" "$action"
    systemctl enable --now paccache.timer  >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Snapshot Service - filesystem-aware
    display "subtitle" "Snapshot Service"

    if is_zfs_root; then
        # ZFS: Install sanoid for snapshot management
        display "task" "ZFS detected - installing sanoid"
        aur_install sanoid

        action="creating sanoid configuration" && display "task" "$action"
        mkdir -p /etc/sanoid
        cat << 'EOF' > /etc/sanoid/sanoid.conf
# Sanoid configuration for ZFS snapshots
# Less aggressive - TrueNAS handles long-term backups

#############################
# Templates
#############################

[template_production]
    # Local rollback capability
    hourly = 6
    daily = 7
    weekly = 2
    monthly = 1
    autosnap = yes
    autoprune = yes

[template_backup]
    # Less frequent for large/static data
    hourly = 0
    daily = 3
    weekly = 2
    monthly = 1
    autosnap = yes
    autoprune = yes

[template_none]
    autosnap = no
    autoprune = yes

#############################
# Datasets
#############################

[zroot/ROOT/default]
    use_template = production

[zroot/home]
    use_template = production
    recursive = yes

[zroot/media]
    use_template = backup

[zroot/vms]
    use_template = backup

[zroot/var/log]
    use_template = production

[zroot/var/lib/pacman]
    use_template = production

[zroot/var/cache]
    use_template = none

[zroot/var/tmp]
    use_template = none

[zroot/tmp]
    use_template = none
EOF

        action="creating zfs-replicate script" && display "task" "$action"
        cat << 'EOF' > /usr/local/bin/zfs-replicate
#!/bin/bash
# zfs-replicate - Replicate ZFS datasets to TrueNAS
#
# Usage:
#   zfs-replicate              # Replicate all configured datasets
#   zfs-replicate [dataset]    # Replicate specific dataset

set -e

# TrueNAS Configuration
# Try local network first, fall back to tailscale
TRUENAS_LOCAL="truenas.local"
TRUENAS_TAILSCALE="truenas"
TRUENAS_USER="root"
TRUENAS_POOL="vault"
BACKUP_PATH="backups"  # TODO: Configure actual path

# Datasets to replicate
DATASETS="zroot/ROOT/default zroot/home zroot/media zroot/vms"

# Colors
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
RED='\033[0;31m'
NC='\033[0m'

info()  { echo -e "${GREEN}[INFO]${NC} $1"; }
warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }

command -v syncoid >/dev/null 2>&1 || error "syncoid not found. Install sanoid package."

# Determine which host to use
determine_host() {
    if ping -c 1 -W 2 "$TRUENAS_LOCAL" &>/dev/null; then
        echo "$TRUENAS_LOCAL"
    elif ping -c 1 -W 2 "$TRUENAS_TAILSCALE" &>/dev/null; then
        echo "$TRUENAS_TAILSCALE"
    else
        error "Cannot reach TrueNAS at $TRUENAS_LOCAL or $TRUENAS_TAILSCALE"
    fi
}

TRUENAS_HOST=$(determine_host)
info "Using TrueNAS host: $TRUENAS_HOST"

# Single dataset mode
if [[ -n "$1" ]]; then
    dataset="$1"
    dest="$TRUENAS_USER@$TRUENAS_HOST:$TRUENAS_POOL/$BACKUP_PATH/${dataset#zroot/}"
    info "Replicating $dataset -> $dest"
    syncoid --recursive "$dataset" "$dest"
    exit 0
fi

# Full replication
info "Starting ZFS replication to $TRUENAS_HOST"
echo ""

for dataset in $DATASETS; do
    dest="$TRUENAS_USER@$TRUENAS_HOST:$TRUENAS_POOL/$BACKUP_PATH/${dataset#zroot/}"
    info "Replicating $dataset -> $dest"

    if syncoid --recursive "$dataset" "$dest"; then
        info "  Success"
    else
        warn "  Failed (will retry next run)"
    fi
    echo ""
done

info "Replication complete."
EOF
        chmod +x /usr/local/bin/zfs-replicate

        action="creating zfs-replicate systemd service" && display "task" "$action"
        cat << 'EOF' > /etc/systemd/system/zfs-replicate.service
[Unit]
Description=ZFS Replication to TrueNAS
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/zfs-replicate
User=root

[Install]
WantedBy=multi-user.target
EOF

        action="creating zfs-replicate systemd timer" && display "task" "$action"
        cat << 'EOF' > /etc/systemd/system/zfs-replicate.timer
[Unit]
Description=Run ZFS replication nightly

[Timer]
OnCalendar=*-*-* 02:00:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target
EOF

        action="enabling sanoid timer" && display "task" "$action"
        systemctl enable sanoid.timer >> "$logfile" 2>&1 || error "error" "$action" "$?"

        action="enabling weekly ZFS scrub" && display "task" "$action"
        systemctl enable zfs-scrub-weekly.timer >> "$logfile" 2>&1 || error "error" "$action" "$?"

        # Note: zfs-replicate.timer is NOT enabled automatically
        # User must set up SSH key auth to TrueNAS first, then run:
        #   systemctl enable --now zfs-replicate.timer
        display "task" "zfs-replicate timer created (enable after SSH key setup to TrueNAS)"

    else
        # Non-ZFS (btrfs): Install timeshift-autosnap
        aur_install timeshift-autosnap
        pacman_install grub-btrfs
        action="enabling snapshot boot menu updates" && display "task" "$action"
        systemctl enable grub-btrfsd  >> "$logfile" 2>&1 || error "error" "$action" "$?"

        action="starting snapshot boot menu updates" && display "task" "$action"
        # starting and stopping service to generate the grub-btrfs config
        systemctl start grub-btrfsd  >> "$logfile" 2>&1 || error "error" "$action" "$?"
        systemctl stop grub-btrfsd  >> "$logfile" 2>&1 || error "error" "$action" "$?"
        # edit grub-btrfs config for timeshift auto snapshot support
        sed -i \
            's|ExecStart=/usr/bin/grub-btrfsd --syslog /.snapshots|ExecStart=/usr/bin/grub-btrfsd --syslog --timeshift-auto|' \
            /etc/systemd/system/grub-btrfsd.service

        action="regenerating boot menu" && display "task" "$action"
        grub-mkconfig -o /boot/grub/grub.cfg >> "$logfile" 2>&1 || error "error" "$action" "$?"
    fi
}

### Xorg Display Manager
xorg() {
    action="Xorg Display Server Dependencies" && display "subtitle" "$action"
    pacman_install libglvnd

    action="Xorg Display Server" && display "subtitle" "$action"
    for software in xorg-server xorg-xinit xorg-xsetroot \
                                xsel xorg-xbacklight xorg-xev \
                                xf86-input-libinput xorg-xeyes \
                                xorg-xdpyinfo xorg-xprop \
                                xorg-xwininfo xorg-xhost \
                                xorg-xinput xorg-xkill ; do
        pacman_install "$software"
    done

    # disallow vt switching or zapping the xorg server to bypass screen lock
    cat << EOF > /etc/X11/xorg.conf.d/00-no-vt-or-zap.conf
    Section "ServerFlags"
        Option "DontVTSwitch" "True"
        Option "DontZap"      "True"
EndSection
EOF
    action="configuring xorg server" && display "task" "$action"
    chmod 644 /etc/X11/xorg.conf.d/00-no-vt-or-zap.conf >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Install GPU-specific drivers
    install_gpu_drivers
}

### DWM Window Manager
dwm() {

    action="DWM Window Manager Dependencies" && display "subtitle" "$action"
    for software in coreutils fontconfig freetype2 glibc libx11 libxft libxinerama; do
        pacman_install "$software"
    done;

    action="DWM Window Manager" && display "subtitle" "$action"

    git_install "$dwm_repo"
    git_install "$dmenu_repo"
    git_install "$st_repo"
    git_install "$slock_repo"
    aur_install pinentry-dmenu  # password entry that leverages dmenu
}

### Desktop Environment
desktop_environment() {
    display "title" "Desktop Environment"

    # Fonts

    action="Fonts" && display "subtitle" "$action"
    pacman_install noto-fonts-emoji
    pacman_install terminus-font
    pacman_install ttf-firacode-nerd
    pacman_install ttf-hack-nerd
    pacman_install ttf-jetbrains-mono-nerd
    pacman_install ttf-meslo-nerd
    pacman_install ttf-nerd-fonts-symbols-mono
    aur_install ttf-all-the-icons
    aur_install ttf-lato
    aur_install ttf-ms-fonts
    aur_install ttf-ubraille


    # System Utilities

    action="System Utilities" && display "subtitle" "$action"
    pacman_install dmidecode
    pacman_install dosfstools
    pacman_install exfatprogs
    pacman_install lshw
    pacman_install ntfs-3g
    pacman_install sshfs
    pacman_install testdisk
    pacman_install tickrs
    pacman_install udisks2
    aur_install touchpad-indicator-git
    aur_install dotpac
    aur_install downgrade
    aur_install duf
    aur_install inxi
    aur_install mkinitcpio-firmware                  # suppresses missing firmware warnings during mkinitcpio

    # File Associations

    action="File/Application Associations" && display "subtitle" "$action"
    pacman_install perl-file-mimeinfo
    pacman_install xdg-utils

    # Authentication Tools

    action="Authentication Tools" && display "subtitle" "$action"
    pacman_install gnupg
    pacman_install polkit
    pacman_install gnome-keyring
    pacman_install seahorse
    pacman_install pass

    # ensure correct permissions on .gpg directory
    # the colon means the user's group will have perms
    [ -d /home/"$username"/.gnupg ] || mkdir /home/"$username"/.gnupg
    chown -R "$username": /home/"$username"/.gnupg
    find /home/"$username"/.gnupg -type f -exec chmod 600 {} \;
    find /home/"$username"/.gnupg -type d -exec chmod 700 {} \;

    #  Power Management

    action="Power Management" && display "subtitle" "$action"
    pacman_install acpi
    pacman_install powertop

    #  Audio System

    action="Audio System" && display "subtitle" "$action"
    for software in alsa-utils pipewire wireplumber pipewire-pulse \
                               pipewire-docs pamixer pulsemixer ffmpeg; do
        pacman_install "$software"
    done;
    # disable the pc speaker beep
    rmmod pcspkr >> "$logfile" 2>&1
    echo "blacklist pcspkr" > /etc/modprobe.d/nobeep.conf

    # Keyboard Shortcut Manager

    action="Keyboard Shortcut Manager" && display "subtitle" "$action"
    pacman_install sxhkd

    # Notifications

    action="Notification System" && display "subtitle" "$action"
    pacman_install libnotify
    pacman_install dunst

    # Screen Color Temperature

    action="Screen Color Temperature" && display "subtitle" "$action"
    pacman_install redshift

    # Bluetooth Devices

    action="Bluetooth System" && display "subtitle" "$action"
    for software in bluez bluez-utils blueman; do
        pacman_install "$software"
    done
    action="enabling bluetooth to launch at boot" && display "task" "$action"
    systemctl enable bluetooth.service  >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Command Line Utilities

    action="Command Line Utilities" && display "subtitle" "$action"
    for software in htop mc ncdu tmux fzf zip unzip atool wget detox \
                         lsof usbutils moreutils; do
        pacman_install "$software"
    done;

    for software in task-spooler-cpu speedtest-go-bin gotop-bin rar; do
        aur_install "$software"
    done;

    # Help And Documentation

    action="Help and Documentation" && display "subtitle" "$action"
    pacman_install man-db
    pacman_install arch-wiki-docs
    pacman_install tealdeer
    aur_install cht.sh-git

    # Sync Services

    action="Sync Services" && display "subtitle" "$action"

    pacman_install syncthing
    systemctl enable "syncthing@$username.service"  >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Desktop Environment Utilities

    action="Desktop Environment Utilities" && display "subtitle" "$action"

    for software in brightnessctl network-manager-applet xclip rofi \
                                  conky qalculate-gtk feh; do
        pacman_install "$software"
    done;

    aur_install caffeine-ng
    aur_install flameshot
    aur_install python-pulsectl
    aur_install xautolock
    aur_install xcolor

    # Theme and Cursor

    action="UI Theme" && display "subtitle" "$action"

    for software in picom lxappearance gnome-themes-extra; do
        pacman_install "$software"
    done;

    for software in vimix-cursors \
                        papirus-icon-theme qt6ct qt5ct; do
        aur_install "$software"
    done;

    pacman_install libappindicator-gtk3 # required by some applets

    # Browsers

    action="Browsers" && display "subtitle" "$action"
    pacman_install firefox
    ## TESTING IF NEEDED aur_install librewolf-bin
    aur_install tor-browser-bin
    aur_install google-chrome

    # Install Printing

    action="Print System" && display "subtitle" "$action"
    pacman_install cups                        # the printing service
    pacman_install cups-pdf                    # allows printing to pdf
    pacman_install foomatic-db-engine          # generates printer drivers, queues, and jobs
    pacman_install foomatic-db-ppds            # printer driver descriptions
    pacman_install foomatic-db-nonfree-ppds    # non-free printer driver descriptions
    pacman_install gutenprint                  # printer driver engine for older computers
    pacman_install foomatic-db-gutenprint-ppds # gutenprint prebuilt ppd files
    pacman_install system-config-printer       # graphical printer config tool

    action="enabling printing service to launch at boot" && display "task" "$action"
    (systemctl enable cups.service  >> "$logfile" 2>&1) || error "error" "$action" "$?"
}

### Developer Workstation
developer_workstation () {

    action="Developer Workstation" && display "title" "$action"

    action="Programming Languages and Utilities" && display "subtitle" "$action"
    # C
    pacman_install clang       # C/C++ compiler
    pacman_install cmake       # make system
    pacman_install gdb         # the GNU debugger
    pacman_install splint      # C programming static analysis
    pacman_install valgrind    # memory management utility

    # java
    pacman_install jdk-openjdk # Java Development Kit
    pacman_install openjdk-doc # ...and the documentation

    # Lisps
    pacman_install guile       # GNU Scheme
    pacman_install sbcl        # Steel Bank Common Lisp
    pacman_install racket      # Racket + SICP mit-scheme emulation

    # Python
    pacman_install pyright     # Python language server
    pacman_install pyenv       # Python environment manager

    # Shell
    pacman_install shellcheck  # Shell script linter
    pacman_install shfmt       # Shell script formatter

    # Go
    pacman_install delve       # Go programming language debugger
    pacman_install go-tools    # Go language utilities
    pacman_install gopls       # Go language server
    pacman_install staticcheck # Go programming language linter

    # Typescript
    pacman_install jq          # JSON processor
    pacman_install typescript  # Typescript programming language
    pacman_install nodejs      # Node-js JavaScript runtime environment
    pacman_install npm         # Node-js package manager
    aur_install nvm            # Node-js version manager

    # HTML
    pacman_install tidy        # HTML formatter
    pacman_install prettier    # Multi-language formatter

    # General Utilities
    pacman_install difftastic       # Structural diff tool
    pacman_install eza              # Modern ls replacement
    pacman_install meld             # Visual diff
    pacman_install ripgrep          # Fast grep utility
    aur_install the_silver_searcher # Another fast grep utility
    pacman_install zoxide           # Smart cd command that learns your habits

    action="Programming Editors" && display "subtitle" "$action"
    pacman_install mg                        # mini emacs
    pacman_install neovim                    # mega vi
    pacman_install pycharm-community-edition # python ide

    action="Emacs Dependencies" && display "subtitle" "$action"
    pacman_install emacs

    # supporting utilities used by my emacs configuration
    aur_install exercism-bin         # command line tool for exercism.io
    pacman_install libvips           # image previewer library
    pacman_install isync             # email sync
    aur_install epub-thumbnailer-git # epub previews in dirvish
    aur_install mu                   # email indexer and utilities
    aur_install multimarkdown        # markdown conversion
    aur_install proselint            # grammar checker
    aur_install gist                 # command-line gist poster
    pacman_install aspell            # spell check system
    pacman_install aspell-en         # spell check english files
    pacman_install fd                # a faster find for dired/dirvish
    pacman_install ffmpegthumbnailer # video previews in dired/dirvish
    pacman_install imagemagick       # image previews for dired/dirvish
    pacman_install libgccjit         # native compilation for Emacs
    pacman_install mediainfo         # generating media info in dired/dirvish
    pacman_install 7zip              # archive info for dirvish
    pacman_install mpv               # video viewer
    pacman_install mailutils         # Emacs' IMAP mail support backend
    pacman_install msmtp             # mail transport for Mu4e
    pacman_install msmtp-mta         # mail transport for Mu4e
    pacman_install python-lsp-server # python language support
    pacman_install rlwrap            # adds readline support to programs (SBCL-related)
    pacman_install sdcv              # stardict dictionary system
    pacman_install yt-dlp            # video download

    action="setting up emacs configuration files" && display "task" "$action"
    (sudo -u "$username" git clone --recurse-submodules "$dotemacs_repo" "/home/$username/.emacs.d"  >> \
          "$logfile" 2>&1) || error "error" "$action" "$?"

    action="Android Utilities" && display "subtitle" "$action"
    pacman_install android-file-transfer
    pacman_install android-tools

    action="DevOps Utilities" && display "subtitle" "$action"

    action="installing devops virtualization and automation tools" && display "task" "$action"
    aur_install vagrant                              # VM management (moved to AUR)
    pacman_install ansible

    # distrobox related
    pacman_install podman
    pacman_install distrobox
    aur_install boxbuddy
    aur_install ptyxis

    # boxes
    pacman_install gnome-boxes

    # docker
    pacman_install docker
    pacman_install docker-compose
    action="adding user to docker group" && display "task" "$action"
    (gpasswd -a "$username" docker >> "$logfile" 2>&1)  || error "error" "$action" "$?"
    action="enabling docker service to launch on boot" && display "task" "$action"
    systemctl enable docker.service >> "$logfile" 2>&1  || error "error" "$action" "$?"
}

### Supplemental Software
supplemental_software() {

    display "title" "Supplemental Software"

    # pacman installs
    pacman_install arandr                            # xrandr gui for monitor settings
    pacman_install arch-install-scripts              # for making arch installers
    pacman_install archinstall                       # the archinstall python program
    pacman_install aria2                             # fast downloader
    pacman_install audacity                          # audio editor
    pacman_install bc                                # arbitrary precision calculator
    pacman_install calibre                           # ebook manager/viewer
    pacman_install dash                              # posix compliant /bin/sh
    pacman_install devtools                          # tools for arch linux package maintenance
    pacman_install dfc                               # better display of available space on mounted filesystems
    pacman_install docx2txt                          # recovers text from docx files
    pacman_install entr                              # run arbitrary commands when files change
    pacman_install faac                              # open source mpeg 3 and aac encoder
    pacman_install faad2                             # processes an aac stream
    pacman_install fastfetch                         # cli system information tool
    pacman_install fdupes                            # identify binary duplicates
    pacman_install figlet                            # words into ascii art
    pacman_install filezilla                         # ftp gui
    pacman_install gimp                              # image editor
    pacman_install gparted                           # disk partition utility
    pacman_install gst-plugin-pipewire               # gstreamer audio plugin for pipewire
    pacman_install gst-plugins-base                  # gstreamer base audio plugins
    pacman_install gst-plugins-good                  # gstreamer extra audio plugins
    pacman_install gstreamer                         # pipeline based multimedia framework
    pacman_install gucharmap                         # gui display of character maps
    pacman_install gzip                              # compression tool
    pacman_install handbrake                         # video transcoder
    pacman_install ledger                            # CLI accounting software
    pacman_install libconfig                         # library for processing structured config files
    pacman_install libmad                            # mpeg audio decoder
    pacman_install libmpeg2                          # library for decoding mpeg video streams
    pacman_install maim                              # screenshot utility
    pacman_install mediainfo                         # technical and tag information about media files
    pacman_install mosh                              # alt SSH terminal with roaming and responsiveness support
    pacman_install odt2txt                           # converts from open document to text
    pacman_install p7zip                             # p7zip compression tool
    pacman_install pandoc-cli                        # universal document converter
    pacman_install protonmail-bridge                 # ProtonMail desktop bridge
    pacman_install perl-image-exiftool               # reads/writes exif info for raw photo files
    pacman_install poppler-glib                      # poppler-glib document viewer library
    pacman_install pv                                # monitor progress of data through pipeline
    pacman_install ranger                            # terminal file manager
    pacman_install rclone                            # syncs files from gdrive, s3, dropbox, etc.
    pacman_install signal-desktop                    # secure messenger
    pacman_install smartmontools                     # monitors hard drives
    pacman_install lynis                             # security auditing tool
    pacman_install telegram-desktop                  # messenger application
    if ! $skip_slow_packages; then
        pacman_install texlive-meta                  # latex (SLOW: ~6 min, 1GB download)
    fi
    pacman_install thunderbird                       # email, calendar, rss feeds
    pacman_install transmission-cli                  # bittorrent client
    pacman_install transmission-remote-gtk           # bittorrent client
    pacman_install unclutter                         # hides mouse cursor when not being used
    pacman_install vlc                               # media player
    pacman_install w3m                               # text based browser
    pacman_install wavpack                           # audio compression format
    pacman_install webkit2gtk                        # web content engine for GTK
    pacman_install xcb-util-cursor                   # calibre dependency (calibre installed manually)
    pacman_install xdotool                           # command line xorg automation tool
    pacman_install xz                                # general purpose data compression tool
    pacman_install zathura                           # document viewer
    pacman_install zathura-cb                        # zathura plugin for comics
    pacman_install zathura-djvu                      # zathura plugin for djvu books
    pacman_install zathura-pdf-mupdf                 # zathura plugin for pdf
    pacman_install zlib                              # compression library

    # aur installs
    aur_install dtrx                                 # extraction tool
    aur_install figlet-fonts                         # fonts for figlet
    aur_install foliate                              # pretty epub reader
    aur_install hfsprogs                             # file system tools for Mac OS
    aur_install insync                               # Google Drive sync client
    aur_install mcomix                               # image viewer for comic books
    aur_install nsxiv                                # image viewer
    aur_install snore-git                            # sleep with feedback
    # aur_install tageditor                            # metadata editor for mkv, webm and related video files (DISABLED: hangs indefinitely building qt5-webengine dependency)
    pacman_install thunar                            # file manager
    pacman_install gvfs-smb                          # SMB network share browsing in Thunar
    if ! $skip_slow_packages; then
        aur_install topgrade                         # upgrade everything utility (SLOW: ~12 min, Rust compilation)
    fi
    aur_install ueberzug                             # allows for displaying images in terminals
    aur_install valent                               # connect and interact with your phone
    aur_install warpinator                           # secure file transfers
    aur_install zsh-fast-syntax-highlighting-git     # Optimized and extended zsh-syntax-highlighting

    # working around an temp integ issue with python-lyricsgenius expiration date
    action="prep to workaround tidal-dl issue" && display "task" "$action"
    yay -S --noconfirm --mflags --skipinteg python-lyricsgenius >> "$logfile" 2>&1  || error "error" "$action" "$?"
    aur_install tidal-dl                             # tidal-dl:tidal as yt-dlp:youtube
}

### Boot-UX
boot_ux() {
    action="Boot UX" && display "title" "$action"

    action="removing distro and date/time from initial screen" && display "task" "$action"
    (cat /dev/null >/etc/issue)  || error "error" "$action" "$?"

    action="preventing kernel messages on the console" && display "task" "$action"
    (echo "kernel.printk = 3 3 3 3" >/etc/sysctl.d/20-quiet-printk.conf)  || \
        error "error" "$action" "$?"

    action="configuring console font" && display "task" "$action"
    if grep -q "^FONT=" /etc/vconsole.conf 2>/dev/null; then
        sed -i 's/^FONT=.*/FONT=ter-132n/' /etc/vconsole.conf
    else
        echo "FONT=ter-132n" >> /etc/vconsole.conf
    fi

    action="delegating fsck messages from udev to systemd" && display "task" "$action"
    sed -i '/^HOOKS=/ s/\budev\b/systemd/' /etc/mkinitcpio.conf  || error "error" "$action" "$?"
    mkinitcpio -P  >> "$logfile" 2>&1  || error "error" "running mkinitcpio -P to silence fsck messages" "$?"

    action="configuring quiet fsck output" && display "task" "$action"
    mkdir -p /etc/systemd/system/systemd-fsck-root.service.d
    cat << 'EOF' > /etc/systemd/system/systemd-fsck-root.service.d/quiet.conf
[Service]
StandardOutput=null
StandardError=journal+console
EOF

    mkdir -p /etc/systemd/system/systemd-fsck@.service.d
    cat << 'EOF' > /etc/systemd/system/systemd-fsck@.service.d/quiet.conf
[Service]
StandardOutput=null
StandardError=journal+console
EOF

    # action="removing hostname from login prompt" && display "task" "$action"
    # sed -i "s/--noclear/--nohostname --noclear/g" /usr/lib/systemd/system/getty@.service  \
        #     || error "error" "$action" "$?"
    # sed -i "s/--noclear/--nohostname --noclear/g" /usr/lib/systemd/system/container-getty@.service  \
        #     || error "error" "$action" "$?"
    # sed -i "s/--noclear/--nohostname --noclear/g" /usr/lib/systemd/system/console-getty.service  \
        #     || error "error" "$action" "$?"

    action="silencing the unneeded and chatty watchdog module" && display "task" "$action"
    echo "blacklist iTCO_wdt" >/etc/modprobe.d/nowatchdog.conf  || error "error" "$action" "$?"

    action="configuring journald retention" && display "task" "$action"
    mkdir -p /etc/systemd/journald.conf.d
    cat << 'EOF' > /etc/systemd/journald.conf.d/retention.conf
[Journal]
SystemMaxUse=500M
EOF

    # GRUB: reset timeouts, adjust log levels, larger menu for HiDPI screens, and show splashscreen
    # Note: nvme.noacpi=1 disables NVMe ACPI power management to prevent freezes on some drives.
    # Safe to keep on newer drives (minor power cost), remove if battery life is critical.
    action="configuring boot menu for silence and bootsplash" && display "task" "$action"
    if [ -f /etc/default/grub ]; then
        action="resetting timeouts and adjusting log levels on grub boot" && display "task" "$action"
        sed -i "s/.*GRUB_TIMEOUT=.*/GRUB_TIMEOUT=0/g" /etc/default/grub
        sed -i "s/.*GRUB_DEFAULT=.*/GRUB_DEFAULT=0/g" /etc/default/grub
        sed -i 's/.*GRUB_TERMINAL_OUTPUT=console/GRUB_TERMINAL_OUTPUT=gfxterm/' /etc/default/grub
        sed -i 's/.*GRUB_GFXMODE=auto/GRUB_GFXMODE=1024x768/' /etc/default/grub
        sed -i "s/.*GRUB_RECORDFAIL_TIMEOUT=.*/GRUB_RECORDFAIL_TIMEOUT=2/g" /etc/default/grub
        sed -i "s/.*GRUB_CMDLINE_LINUX_DEFAULT=.*/GRUB_CMDLINE_LINUX_DEFAULT=\"rw loglevel=2 rd.systemd.show_status=auto rd.udev.log_level=2 nvme.noacpi=1 mem_sleep_default=deep nowatchdog quiet splash\"/g" /etc/default/grub
        grub-mkconfig -o /boot/grub/grub.cfg  >> "$logfile" 2>&1  || error "error" "generating grub config" "$?"
    fi
}


### Outro
outro() {

    action="Cleanup" && display "title" "$action"
    action="forcing user password change on first login" && display "task" "$action"
    chage -d 0 "$username"  >> "$logfile" 2>&1 || error "error" "$action" "$?"

    # Lock root account last - if script fails earlier, root is still available for recovery
    action="locking root account (use sudo instead)" && display "task" "$action"
    passwd -l root >> "$logfile" 2>&1 || error "error" "$action" "$?"

    display "subtitle" "Statistics"
    action="identifying newly installed packages" && display "task" "$action"
    pacman -Q > "$packages_after"  || error "error" "$action" "$?"
    (comm -13 --nocheck-order "$packages_before" "$packages_after" > "$archsetup_packages")  || \
        error "error" "$action" "$?"

    action="comparing timestamps" && display "task" "$action"
    ENDTIME=$(date +%s)
    totalsecs=$(($ENDTIME - $STARTTIME))
    mins=$(($totalsecs / 60))
    secs=$(($totalsecs % 60))

    new_packages=$(wc -l < "$archsetup_packages")

    printf "\n"
    printf "Completion time    : %s\n" "$(date +'%D %T')"  | tee -a "$logfile"
    printf "Elapsed time       : %s minutes, %s seconds\n" "$mins" "$secs" | tee -a "$logfile"
    printf "Errors encountered : %s\n" "$errors_encountered" | tee -a "$logfile"
    printf "Log file location  : %s\n" "$logfile"
    printf "Packages installed : %s\n" "$new_packages"

    if [ ${#error_messages[@]} -gt 0 ]; then
        printf "\nError Summary:\n" | tee -a "$logfile"
        for msg in "${error_messages[@]}"; do
            printf "  - %s\n" "$msg" | tee -a "$logfile"
        done
    fi

    printf "\n"
    printf "Please reboot before working with your new workstation.\n\n"

    # Completion marker for automated testing
    printf "=== ARCHSETUP_EXECUTION_COMPLETE ===\n" | tee -a "$logfile"
}

### Installation Steps
preflight_checks      # verify system requirements (always runs)

run_step "intro" intro
run_step "prerequisites" prerequisites
run_step "create_user" create_user
run_step "user_customizations" user_customizations
run_step "aur_installer" aur_installer
run_step "essential_services" essential_services
run_step "xorg" xorg
run_step "dwm" dwm
run_step "desktop_environment" desktop_environment
run_step "developer_workstation" developer_workstation
run_step "supplemental_software" supplemental_software
run_step "boot_ux" boot_ux

outro                 # take end stats; show summary (always runs)

exit 0