first_time_install.sh

#!/bin/bash

# LED Matrix First-Time Installation Script
# This script handles the complete setup for a new LED Matrix installation

set -Eeuo pipefail

# Global state for nicer error messages
CURRENT_STEP="initialization"

# Error handler for friendlier failures
on_error() {
    local exit_code=$?
    local line_no=${1:-unknown}
    echo "✗ An error occurred during: $CURRENT_STEP (line $line_no, exit $exit_code)" >&2
    if [ -n "${LOG_FILE:-}" ]; then
        echo "See the log for details: $LOG_FILE" >&2
        echo "-- Last 100 lines from log --" >&2
        tail -n 100 "$LOG_FILE" >&2 || true
    fi
    printf '\nCommon fixes:\n' >&2
    echo "- Ensure the Pi is online (try: ping -c1 8.8.8.8)." >&2
    echo "- If you saw an APT lock error: wait a minute, close other installers, then run: sudo dpkg --configure -a" >&2
    echo "- Re-run this script. It is safe to run multiple times." >&2
    exit "$exit_code"
}
trap 'on_error $LINENO' ERR

echo "=========================================="
echo "LED Matrix First-Time Installation Script"
echo "=========================================="
echo ""

# Show device model if available (helps users confirm they're on a Raspberry Pi)
if [ -r /proc/device-tree/model ]; then
    DEVICE_MODEL=$(tr -d '\0' </proc/device-tree/model)
    echo "Detected device: $DEVICE_MODEL"
else
    DEVICE_MODEL=""
    echo "⚠ Could not detect Raspberry Pi model (continuing anyway)"
fi

# Detect Pi 5 for hardware-specific install decisions (RP1 library verification)
IS_PI5=0
if echo "${DEVICE_MODEL:-}" | grep -qi "Raspberry Pi 5"; then
    IS_PI5=1
    echo "Raspberry Pi 5 detected — will verify RP1 library support."
fi

# Check OS version - must be Raspberry Pi OS Lite, Bookworm or Trixie.
# The rules live in scripts/install/lib_os.sh, shared with
# scripts/check_system_compatibility.sh.
echo ""
echo "Checking operating system requirements..."
echo "----------------------------------------"
OS_CHECK_FAILED=0
OS_RELEASE=""

OS_LIB="$(cd "$(dirname "$0")" && pwd)/scripts/install/lib_os.sh"
if [ ! -f "$OS_LIB" ]; then
    echo "✗ ERROR: $OS_LIB is missing, so the operating system cannot be checked."
    echo "  Your LEDMatrix download is incomplete. Download it again and re-run this script:"
    echo "    git clone https://github.com/ChuckBuilds/LEDMatrix.git"
    exit 1
fi
# shellcheck source=scripts/install/lib_os.sh
. "$OS_LIB"

if [ -r "$LM_OS_RELEASE_FILE" ]; then
    echo "Detected OS: $(lm_os_field PRETTY_NAME)"
    OS_VERSION_ID=$(lm_os_field VERSION_ID)
    echo "Version ID: ${OS_VERSION_ID:-unknown}"

    if OS_RELEASE=$(lm_os_release); then
        echo "✓ $(lm_release_label "$OS_RELEASE") detected"
    else
        OS_ID=$(lm_os_field ID)
        if [[ "$OS_ID" != "raspbian" ]] && [[ "$OS_ID" != "debian" ]]; then
            echo "✗ ERROR: This script requires Raspberry Pi OS (raspbian/debian)"
            echo "  Detected OS ID: ${OS_ID:-unknown}"
        else
            echo "✗ ERROR: This version of Raspberry Pi OS is not supported"
            echo "  Detected version: ${OS_VERSION_ID:-unknown}"
            echo "  Supported: Trixie (Debian 13) and Bookworm (Debian 12)"
        fi
        OS_CHECK_FAILED=1
    fi

    # Check if it's the Lite version (no desktop environment)
    # Check for desktop packages or desktop services
    DESKTOP_DETECTED=0
    # grep without -q: -q exits at the first match, dpkg then dies of SIGPIPE,
    # and pipefail turns a found desktop into "not found".
    if dpkg -l | grep -E "^ii.*raspberrypi-ui-mods|^ii.*lxde|^ii.*xfce|^ii.*gnome|^ii.*kde" >/dev/null; then
        DESKTOP_DETECTED=1
    fi
    if systemctl list-units --type=service --state=running 2>/dev/null | grep -qE "lightdm|gdm3|sddm|lxdm"; then
        DESKTOP_DETECTED=1
    fi
    if [ -d /usr/share/raspberrypi-ui-mods ] || [ -d /usr/share/xsessions ]; then
        DESKTOP_DETECTED=1
    fi
    
    if [ "$DESKTOP_DETECTED" -eq 1 ]; then
        echo "✗ ERROR: Desktop environment detected - this script requires Raspberry Pi OS Lite"
        echo "  Please use Raspberry Pi OS Lite (not the full desktop version)"
        OS_CHECK_FAILED=1
    else
        echo "✓ Lite version confirmed (no desktop environment)"
    fi
else
    echo "✗ ERROR: Could not detect OS version ($LM_OS_RELEASE_FILE not found)"
    OS_CHECK_FAILED=1
fi

# Python: whatever python3 the release ships (3.11 on Bookworm, 3.13 on
# Trixie). Checked only when python3 is already there -- Step 1 installs it
# otherwise, and on a supported release that brings the release's own version.
if [ "$OS_CHECK_FAILED" -eq 0 ]; then
    if PYTHON3_VERSION=$(lm_python_version); then
        case "$(lm_python_check "$PYTHON3_VERSION")" in
            ok)
                echo "✓ Python $PYTHON3_VERSION detected"
                ;;
            too-old)
                echo "✗ ERROR: python3 is Python $PYTHON3_VERSION; LEDMatrix needs Python 3.$LM_PYTHON_MIN_MINOR or newer"
                echo "  $(lm_release_label "$OS_RELEASE") ships Python $(lm_release_python "$OS_RELEASE"). Something on this"
                echo "  system has changed which Python 'python3' runs; point it back at the system Python."
                OS_CHECK_FAILED=1
                ;;
            *)
                echo "⚠ python3 is Python $PYTHON3_VERSION, which LEDMatrix has not been tested with"
                echo "  (tested: 3.$LM_PYTHON_MIN_MINOR to 3.$LM_PYTHON_MAX_MINOR). Continuing anyway."
                ;;
        esac
    else
        echo "python3 not found yet; Step 1 installs it."
    fi
fi

if [ "$OS_CHECK_FAILED" -eq 1 ]; then
    echo ""
    echo "Installation cannot continue."
    lm_print_supported_os_help
    exit 1
fi

echo "✓ OS requirements met"

# WiFi setup (the web page's WiFi tab and the LEDMatrix-Setup hotspot) needs
# NetworkManager. Both releases use it by default; say so plainly if this Pi
# does not, but carry on -- the display itself does not depend on it.
case "$(lm_network_stack)" in
    networkmanager) echo "✓ NetworkManager is managing the network" ;;
    dhcpcd) lm_print_dhcpcd_advice ;;
    *) echo "⚠ Could not tell which service manages the network; WiFi setup from the web page needs NetworkManager" ;;
esac
echo ""

# The user who ran the installer: SUDO_USER once we are running under sudo
# (the re-exec below guarantees that), otherwise whoever we are now.
if [ -n "${SUDO_USER:-}" ]; then
    ACTUAL_USER="$SUDO_USER"
else
    ACTUAL_USER=$(whoami)
fi

# Get the home directory of the actual user
USER_HOME=$(eval echo ~$ACTUAL_USER)

# --- rpi-rgb-led-matrix checkout helpers -------------------------------------
# Run git as whoever owns the project directory. Run as root against a
# user-owned repo, git refuses it ("dubious ownership"), and anything it does
# create — such as .git/modules/<submodule> — ends up root-owned, locking the
# user out of their own checkout. A root-owned install keeps running as root.
_rgb_repo_owner() {
    stat -c %U "$PROJECT_ROOT_DIR" 2>/dev/null || echo root
}

_git_as_repo_owner() {
    local owner
    owner=$(_rgb_repo_owner)
    if [ "$(id -u)" = "0" ] && [ "$owner" != "root" ] && command -v sudo >/dev/null 2>&1; then
        sudo -u "$owner" -H git "$@"
    else
        git "$@"
    fi
}

# Earlier installer versions ran the submodule git commands as root, leaving
# root-owned files the repo owner (and so _git_as_repo_owner) cannot write.
_reclaim_rgb_checkout() {
    local owner path
    owner=$(_rgb_repo_owner)
    if [ "$(id -u)" != "0" ] || [ "$owner" = "root" ]; then
        return 0
    fi
    for path in "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" "$PROJECT_ROOT_DIR/.git/modules/rpi-rgb-led-matrix-master"; do
        if [ -e "$path" ]; then
            chown -R "$owner:" "$path" 2>/dev/null || true
        fi
    done
}

# `git pull` on the main repo never moves an existing submodule checkout, so a
# submodule bump (e.g. the ARMv6 build fix for Pi Zero/1) would never reach a
# device installed before it. Move the checkout forward to the pinned commit —
# but never backward or sideways: a user who ran `git submodule update --remote`
# is newer than the pin and is left alone. Never fatal.
_sync_rgb_submodule() {
    local sub="$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" pinned current
    if [ ! -f "$PROJECT_ROOT_DIR/.gitmodules" ] || ! grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules" \
        || [ ! -e "$sub/.git" ]; then
        return 0
    fi
    if ! pinned=$(_git_as_repo_owner -C "$PROJECT_ROOT_DIR" rev-parse "HEAD:rpi-rgb-led-matrix-master" 2>/dev/null) \
        || [ -z "$pinned" ]; then
        return 0
    fi
    current=$(_git_as_repo_owner -C "$sub" rev-parse HEAD 2>/dev/null) || current=""
    if [ "$current" = "$pinned" ]; then
        return 0
    fi
    if [ -n "$current" ] && _git_as_repo_owner -C "$sub" cat-file -e "${pinned}^{commit}" 2>/dev/null \
        && ! _git_as_repo_owner -C "$sub" merge-base --is-ancestor "$current" "$pinned" 2>/dev/null; then
        echo "rpi-rgb-led-matrix-master is at ${current:0:7}, not behind the pinned ${pinned:0:7}; leaving it as is"
        return 0
    fi
    echo "Updating rpi-rgb-led-matrix-master to the pinned commit ${pinned:0:7}..."
    if ! _git_as_repo_owner -C "$PROJECT_ROOT_DIR" submodule update --init --recursive rpi-rgb-led-matrix-master; then
        echo "⚠ Could not update rpi-rgb-led-matrix-master to the pinned commit; building the existing checkout"
    fi
    return 0
}

# LEDMatrix's own changes to the library live in patches/rpi-rgb-led-matrix/ and
# are applied only for the build: _apply_rgb_patches before it, _revert_rgb_patches
# after it, success or not. The checkout is left exactly as it was, so `git pull`
# and _sync_rgb_submodule never meet local modifications in the submodule.
# A patch that no longer applies (a submodule bump, a hand-edited checkout) is
# reported and skipped -- the unpatched library still builds and works, so it is
# never fatal. One that is already applied is left alone and not reverted.
_RGB_APPLIED_PATCHES=()

_apply_rgb_patches() {
    local sub="$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master"
    local dir="$PROJECT_ROOT_DIR/patches/rpi-rgb-led-matrix" patch name
    _RGB_APPLIED_PATCHES=()
    [ -d "$dir" ] || return 0
    for patch in "$dir"/*.patch; do
        [ -f "$patch" ] || continue
        name=$(basename "$patch")
        if _git_as_repo_owner -C "$sub" apply --check "$patch" >/dev/null 2>&1; then
            if _git_as_repo_owner -C "$sub" apply "$patch"; then
                _RGB_APPLIED_PATCHES+=("$patch")
                echo "Applied library patch $name"
            else
                echo "⚠ Could not apply library patch $name; building without it"
            fi
        elif _git_as_repo_owner -C "$sub" apply --reverse --check "$patch" >/dev/null 2>&1; then
            echo "Library patch $name is already applied"
        else
            echo "⚠ Library patch $name does not apply to this checkout; building without it"
        fi
    done
    return 0
}

_revert_rgb_patches() {
    local sub="$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" i
    # Last applied first, in case two patches touch the same file.
    for ((i = ${#_RGB_APPLIED_PATCHES[@]} - 1; i >= 0; i--)); do
        if ! _git_as_repo_owner -C "$sub" apply --reverse "${_RGB_APPLIED_PATCHES[i]}"; then
            echo "⚠ Could not revert $(basename "${_RGB_APPLIED_PATCHES[i]}"); restore the checkout with: git -C $sub checkout -- ."
        fi
    done
    _RGB_APPLIED_PATCHES=()
    return 0
}
# --- end rpi-rgb-led-matrix checkout helpers ---------------------------------

# Determine the Project Root Directory (where this script is located)
PROJECT_ROOT_DIR=$(cd "$(dirname "$0")" && pwd)

echo "Detected user: $ACTUAL_USER"
echo "User home directory: $USER_HOME"
echo "Project directory: $PROJECT_ROOT_DIR"
echo ""

# Check if running as root; if not, try to elevate automatically for novices
if [ "$EUID" -ne 0 ]; then
    echo "This script needs administrator privileges. Attempting to re-run with sudo..."
    exec sudo -E bash "$0" "$@"
fi
echo "✓ Running as root (required for installation)"

# Initialize logging
LOG_DIR="$PROJECT_ROOT_DIR/logs"
mkdir -p "$LOG_DIR"
LOG_FILE="$LOG_DIR/first_time_install_$(date +%Y%m%d_%H%M%S).log"
exec > >(tee -a "$LOG_FILE") 2>&1
echo "Logging to: $LOG_FILE"

# Args and options (novice-friendly defaults)
ASSUME_YES=${LEDMATRIX_ASSUME_YES:-0}
SKIP_SOUND=${LEDMATRIX_SKIP_SOUND:-0}
SKIP_PERF=${LEDMATRIX_SKIP_PERF:-0}
SKIP_REBOOT_PROMPT=${LEDMATRIX_SKIP_REBOOT_PROMPT:-0}
SKIP_SWAP=${LEDMATRIX_SKIP_SWAP:-0}
BUILD_JOBS_OVERRIDE=${LEDMATRIX_BUILD_JOBS:-}
# Weekly automatic updates: 1 on, 0 off, empty = ask (interactive) or leave as is.
AUTO_UPDATE=${LEDMATRIX_AUTO_UPDATE:-}
# Update channel written to config.json: stable, beta, or empty = leave as is.
UPDATE_CHANNEL=$(printf '%s' "${LEDMATRIX_CHANNEL:-}" | tr '[:upper:]' '[:lower:]')

usage() {
    cat <<USAGE
Usage: sudo ./first_time_install.sh [options]

Options:
  -y, --yes                 Proceed without interactive confirmations
      --force-rebuild       Force rebuild of rpi-rgb-led-matrix even if present
      --skip-sound          Skip sound module configuration
      --skip-perf           Skip performance tweaks (isolcpus/audio)
      --no-reboot-prompt    Do not prompt for reboot at the end
      --skip-swap           Never add temporary swap for the C++ build
      --build-jobs N        Compile the C++ library with N parallel jobs
                            (default: scaled to available RAM)
      --enable-auto-update  Turn on weekly automatic updates (with health
                            check and automatic rollback)
      --no-auto-update      Leave weekly automatic updates off
      --beta                Follow main, the newest code (the beta update
                            channel). Without it, updates follow releases
                            (stable). It sets the channel; it does not move
                            this checkout -- the one-shot installer picks the
                            version, and so does the next update.
  -h, --help                Show this help message and exit

Environment variables (same effect as flags):
  LEDMATRIX_ASSUME_YES=1, RPI_RGB_FORCE_REBUILD=1, LEDMATRIX_SKIP_SOUND=1,
  LEDMATRIX_SKIP_PERF=1, LEDMATRIX_SKIP_REBOOT_PROMPT=1,
  LEDMATRIX_SKIP_SWAP=1, LEDMATRIX_BUILD_JOBS=N, LEDMATRIX_AUTO_UPDATE=1|0,
  LEDMATRIX_CHANNEL=stable|beta

Low-memory devices:
  On a Pi with under 2GB of RAM the C++ build is limited to fewer parallel
  jobs and a temporary swapfile is added for the duration of the build, then
  removed. Without this the compiler is killed by the kernel out-of-memory
  killer on 512MB and 1GB models.
USAGE
}

while [ $# -gt 0 ]; do
    case "$1" in
        -y|--yes) ASSUME_YES=1 ;;
        --force-rebuild) RPI_RGB_FORCE_REBUILD=1 ;;
        --skip-sound) SKIP_SOUND=1 ;;
        --skip-perf) SKIP_PERF=1 ;;
        --no-reboot-prompt) SKIP_REBOOT_PROMPT=1 ;;
        --skip-swap) SKIP_SWAP=1 ;;
        --enable-auto-update) AUTO_UPDATE=1 ;;
        --no-auto-update) AUTO_UPDATE=0 ;;
        --beta) UPDATE_CHANNEL=beta ;;
        --build-jobs)
            shift
            if [ $# -eq 0 ]; then echo "--build-jobs requires a number"; usage; exit 1; fi
            BUILD_JOBS_OVERRIDE="$1"
            ;;
        -h|--help) usage; exit 0 ;;
        *) echo "Unknown option: $1"; usage; exit 1 ;;
    esac
    shift
done

# Low-memory build helpers (job sizing, temporary swap, OOM detection).
# Sourced rather than inlined so the sizing logic can be unit-tested; if the
# file is missing we fall back to the historical behaviour rather than failing
# the install.
LOWMEM_LIB="$PROJECT_ROOT_DIR/scripts/install/lib_lowmem.sh"
LOWMEM_AVAILABLE=0
if [ -f "$LOWMEM_LIB" ]; then
    # shellcheck source=scripts/install/lib_lowmem.sh
    . "$LOWMEM_LIB"
    LOWMEM_AVAILABLE=1
else
    echo "⚠ $LOWMEM_LIB not found; skipping low-memory build protections."
    lm_remove_build_swap() { return 0; }
fi

# Remove the temporary build swapfile, and take any library patches back out
# of the submodule, no matter how the script ends. Step 6 does both itself;
# this is the backstop for the error path (on_error ends in `exit` and EXIT
# traps still run) and for an interrupted build. _revert_rgb_patches only
# touches patches it applied, so running it twice is harmless.
trap 'lm_remove_build_swap; _revert_rgb_patches' EXIT

# Helpers
retry() {
    local attempt=1
    local max_attempts=3
    local delay_seconds=5
    while true; do
        "$@" && return 0
        local status=$?
        if [ $attempt -ge $max_attempts ]; then
            echo "✗ Command failed after $attempt attempts: $*"
            return $status
        fi
        echo "⚠ Command failed (attempt $attempt/$max_attempts). Retrying in ${delay_seconds}s: $*"
        attempt=$((attempt+1))
        sleep "$delay_seconds"
    done
}

# Wait for another apt/dpkg process (commonly unattended-upgrades running
# shortly after first boot) to release its lock before we try apt ourselves.
# Without this, apt_update/apt_install can fail outright in the first couple
# minutes after a fresh Pi OS boot with a generic "Command failed after 3
# attempts" error.
wait_for_apt_lock() {
    command -v flock >/dev/null 2>&1 || return 0
    local lock_file="/var/lib/dpkg/lock-frontend"
    local max_wait=180
    local waited=0
    local printed=0
    while ! flock -n "$lock_file" -c true 2>/dev/null; do
        if [ "$printed" -eq 0 ]; then
            echo "⚠ Waiting for another apt/dpkg process to finish (e.g. unattended-upgrades on first boot)..."
            printed=1
        fi
        if [ "$waited" -ge "$max_wait" ]; then
            echo "⚠ Still waiting after ${max_wait}s; proceeding anyway."
            break
        fi
        sleep 5
        waited=$((waited+5))
    done
}

apt_update() { wait_for_apt_lock; retry apt-get -o DPkg::Lock::Timeout=180 update; }
apt_install() { wait_for_apt_lock; retry apt-get -o DPkg::Lock::Timeout=180 install -y "$@"; }
apt_remove() { apt-get remove -y "$@" || true; }

check_network() {
    if command -v ping >/dev/null 2>&1; then
        if ping -c 1 -W 3 8.8.8.8 >/dev/null 2>&1; then
            return 0
        fi
    fi
    if command -v curl >/dev/null 2>&1; then
        if curl -Is --max-time 5 http://deb.debian.org >/dev/null 2>&1; then
            return 0
        fi
    fi
    echo "✗ No internet connectivity detected."
    echo "Please connect your Raspberry Pi to the internet and re-run this script."
    exit 1
}

check_disk_space() {
    command -v df >/dev/null 2>&1 || return 0
    local available_mb
    available_mb=$(df -m "$PROJECT_ROOT_DIR" | awk 'NR==2{print $4}')
    available_mb=${available_mb:-0}
    if [ "$available_mb" -lt 500 ]; then
        echo "✗ ERROR: Insufficient disk space: ${available_mb}MB available (need at least 500MB)"
        echo "  Free up space first, e.g.: sudo apt clean && sudo apt autoremove"
        exit 1
    elif [ "$available_mb" -lt 1024 ]; then
        echo "⚠ Limited disk space: ${available_mb}MB available (recommend at least 1GB for the rpi-rgb-led-matrix build in Step 6)"
    else
        echo "✓ Disk space sufficient: ${available_mb}MB available"
    fi
}

# Decide how much memory Step 6's C++ build may use, and say so up front.
#
# Sets TOTAL_RAM_MB, TOTAL_SWAP_MB, BUILD_JOBS and LOW_RAM for later steps.
check_memory() {
    command -v nproc >/dev/null 2>&1 && CPU_CORES=$(nproc) || CPU_CORES=1

    # Validated up front rather than trusted: a non-numeric value would other-
    # wise survive as far as an arithmetic test in Step 6 and fail there with a
    # generic error. This must precede the fallback return below, which also
    # honours the override.
    if [ -n "$BUILD_JOBS_OVERRIDE" ]; then
        if ! echo "$BUILD_JOBS_OVERRIDE" | grep -qE '^[1-9][0-9]*$'; then
            echo "✗ Invalid build job count: '$BUILD_JOBS_OVERRIDE' (expected a positive integer)"
            exit 1
        fi
    fi

    if [ "$LOWMEM_AVAILABLE" != "1" ]; then
        TOTAL_RAM_MB=0
        TOTAL_SWAP_MB=0
        LOW_RAM=0
        BUILD_JOBS=${BUILD_JOBS_OVERRIDE:-$CPU_CORES}
        return 0
    fi

    TOTAL_RAM_MB=$(lm_total_ram_mb)
    TOTAL_SWAP_MB=$(lm_total_swap_mb)

    # Test hook: exercise the low-memory path on a machine that has plenty.
    if [ -n "${LEDMATRIX_FORCE_LOW_RAM:-}" ] && [ "${LEDMATRIX_FORCE_LOW_RAM}" != "0" ]; then
        TOTAL_RAM_MB="${LEDMATRIX_FORCE_LOW_RAM}"
        echo "⚠ LEDMATRIX_FORCE_LOW_RAM set: pretending this device has ${TOTAL_RAM_MB}MB of RAM"
    fi

    LOW_RAM=0
    if [ "$TOTAL_RAM_MB" -gt 0 ] && [ "$TOTAL_RAM_MB" -lt 2048 ]; then
        LOW_RAM=1
    fi

    if [ -n "$BUILD_JOBS_OVERRIDE" ]; then
        BUILD_JOBS="$BUILD_JOBS_OVERRIDE"
    else
        BUILD_JOBS=$(lm_build_jobs "$TOTAL_RAM_MB" "$CPU_CORES")
    fi

    echo "System memory: ${TOTAL_RAM_MB}MB RAM, ${TOTAL_SWAP_MB}MB swap, ${CPU_CORES} core(s)"
    if [ "$LOW_RAM" = "1" ]; then
        echo "⚠ Low-memory device detected."
        echo "  The rpi-rgb-led-matrix C++ build in Step 6 will use ${BUILD_JOBS} parallel job(s)"
        echo "  instead of all cores, and a temporary swapfile will be added for the build"
        echo "  and removed afterwards. Without this the compiler is killed by the kernel"
        echo "  out-of-memory killer. Expect Step 6 to take 15-25 minutes."
        if [ "$SKIP_SWAP" = "1" ]; then
            echo "  Temporary swap is disabled (--skip-swap); the build may still run out of memory."
        fi
    else
        echo "✓ Memory sufficient for the rpi-rgb-led-matrix build (${BUILD_JOBS} parallel job(s))"
    fi
}

# Compile and install the rgbmatrix Python package.
#
# CMAKE_BUILD_PARALLEL_LEVEL is the setting that actually caps the compile:
# upstream's pyproject.toml declares no [tool.scikit-build] options, so
# scikit-build-core drives Ninja through `cmake --build`, which reads this
# variable. Ninja's own default is nproc+2, i.e. six concurrent cc1plus
# processes on a 4-core Pi. MAKEFLAGS is ignored by Ninja and is set only to
# cover the Makefile-generator fallback if ninja-build is somehow absent.
#
# BUILD_TMPDIR redirects pip's build tree off tmpfs where applicable — see
# where it is computed in Step 6.
run_rgbmatrix_build() {
    local jobs="$1" out="$2"
    local pid elapsed=0

    TMPDIR="${BUILD_TMPDIR:-${TMPDIR:-/tmp}}" \
    CMAKE_BUILD_PARALLEL_LEVEL="$jobs" \
    MAKEFLAGS="-j${jobs}" \
        python3 -m pip install --break-system-packages . > "$out" 2>&1 &
    pid=$!

    # The build's output is captured to a file, so without a heartbeat a serial
    # compile on a 1GB Pi looks like a 20-minute hang and invites a Ctrl-C.
    #
    # Polled at a short interval but reported every 30s: polling at the report
    # interval instead would add most of that interval to the wall time of
    # every build, including fast ones on a Pi 4/5.
    while kill -0 "$pid" 2>/dev/null; do
        sleep 2
        elapsed=$((elapsed + 2))
        if [ "$((elapsed % 30))" -eq 0 ] && kill -0 "$pid" 2>/dev/null; then
            printf '  ... still compiling (%dm%02ds elapsed)\n' "$((elapsed / 60))" "$((elapsed % 60))"
        fi
    done

    wait "$pid"
}

# Explain a failed rgbmatrix build. The kernel OOM killer writes nothing to the
# build's own output, which is why this used to be reported as a missing
# build-tools problem and sent users chasing packages they already had.
print_rgbmatrix_build_failure() {
    local out="$1"

    if [ "$LOWMEM_AVAILABLE" = "1" ] && lm_build_failed_on_oom "$out"; then
        echo "✗ The rpi-rgb-led-matrix build was killed: the system ran out of memory."
        echo "  This is NOT a missing build-tools problem — the C++ compiler ran out of RAM."
        echo "  RAM: ${TOTAL_RAM_MB}MB   Swap: $(lm_total_swap_mb)MB   Parallel jobs used: ${BUILD_JOBS}"
        if [ -n "${LM_SWAP_SKIP_REASON:-}" ]; then
            echo "  No temporary swap was added: ${LM_SWAP_SKIP_REASON}"
        fi
        echo ""
        echo "  Try one of these, then re-run this script (it resumes at Step 6):"
        echo "    1. Force a single compile job:"
        echo "       sudo ./first_time_install.sh --build-jobs 1"
        echo "    2. Add permanent swap, if the temporary swapfile could not be created:"
        echo "       sudo apt install -y dphys-swapfile"
        echo "       sudo sed -i 's/^#\\?CONF_SWAPSIZE=.*/CONF_SWAPSIZE=2048/' /etc/dphys-swapfile"
        echo "       sudo sed -i 's/^#\\?CONF_MAXSWAP=.*/CONF_MAXSWAP=2048/' /etc/dphys-swapfile"
        echo "       sudo dphys-swapfile swapoff && sudo dphys-swapfile setup && sudo dphys-swapfile swapon"
        echo "    3. Free up disk space so a larger swapfile fits: sudo apt clean"
    else
        echo "✗ Failed to install rpi-rgb-led-matrix Python package"
        echo "  Ensure build tools are installed:"
        echo "  sudo apt install -y python-dev-is-python3 cmake build-essential"
    fi
}

# Set WEB_SERVICE_USER to the account ledmatrix-web.service runs as, or "root"
# when it cannot tell. Steps 3.1 and 11 choose plugin-directory ownership from
# it. The logic was pasted three times, identically, and is kept verbatim here.
# Note: install_web_service.sh and install_service.sh no longer contain the
# "User=root" / "User=${ACTUAL_USER}" strings grepped for below (the units come
# from systemd/*.service templates with User=__USER__). So once the unit is
# installed (Step 7.5, by install_service.sh) the first branch reads its real
# User=; before that the second branch is taken whenever
# install_web_service.sh exists, matches neither string, and yields "root" --
# the later branches are reached only if that script is missing.
detect_web_service_user() {
    WEB_SERVICE_USER="root"
    if [ -f "/etc/systemd/system/ledmatrix-web.service" ]; then
        # Check actual installed service file (most accurate)
        WEB_SERVICE_USER=$(grep "^User=" /etc/systemd/system/ledmatrix-web.service | cut -d'=' -f2 || echo "root")
    elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" ]; then
        # Check install_web_service.sh (used by first_time_install.sh)
        if grep -q "User=root" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
            WEB_SERVICE_USER="root"
        elif grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"; then
            WEB_SERVICE_USER="$ACTUAL_USER"
        fi
    elif [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" ]; then
        # Check template file (may have placeholder)
        WEB_SERVICE_USER=$(grep "^User=" "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service" | cut -d'=' -f2 || echo "root")
        # If template has placeholder, check install script
        if [ "$WEB_SERVICE_USER" = "__USER__" ] || [ -z "$WEB_SERVICE_USER" ]; then
            # Check install_service.sh to see what user it uses
            if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
                WEB_SERVICE_USER="$ACTUAL_USER"
            fi
        fi
    elif [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ] && grep -q "User=\${ACTUAL_USER}" "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"; then
        # Web service will be installed by install_service.sh as ACTUAL_USER
        WEB_SERVICE_USER="$ACTUAL_USER"
    fi
}

echo ""
echo "This script will perform the following steps:"
echo "1. Check prerequisites (network, disk, memory) and install system dependencies"
echo "2. Fix cache permissions"
echo "3. Fix assets directory permissions"
echo "3.1. Fix plugin directory permissions"
echo "4. Ensure configuration files exist"
echo "5. Install Python project dependencies (requirements.txt)"
echo "6. Build and install rpi-rgb-led-matrix and test import"
echo "   (compiles C++; low-memory Pis get temporary swap and a serial build)"
echo "7. Install web interface dependencies"
echo "7.5. Install main LED Matrix service"
echo "8. Install web interface service"
echo "8.1. Harden systemd unit file permissions"
echo "8.5. Install WiFi monitor service"
echo "9. Configure web interface permissions"
echo "10. Configure passwordless sudo access"
echo "10.1. Configure WiFi management permissions"
echo "11. Set up proper file ownership"
echo "12. Configure sound module to avoid conflicts"
echo "13. Apply performance optimizations"
echo "14. Test the installation"
echo ""

# Ask for confirmation
if [ "$ASSUME_YES" = "1" ]; then
    echo "Non-interactive mode: proceeding with installation."
else
    # Check if stdin is available (not running via pipe/curl)
    if [ -t 0 ]; then
        read -p "Do you want to proceed with the installation? (y/N): " -n 1 -r
        echo
        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
            echo "Installation cancelled."
            exit 0
        fi
    else
        # Non-interactive mode but ASSUME_YES not set - exit with error
        echo "✗ Non-interactive mode detected but ASSUME_YES not set." >&2
        echo "  Please run with -y flag or set LEDMATRIX_ASSUME_YES=1" >&2
        echo "  Example: sudo ./first_time_install.sh -y" >&2
        exit 1
    fi
fi

echo ""
CURRENT_STEP="Install system dependencies"
echo "Step 1: Installing system dependencies..."
echo "----------------------------------------"

# Pre-flight checks before APT operations
check_network
check_disk_space
check_memory

# Update package list. The one-shot installer refreshes the lists moments
# before invoking this script and exports LEDMATRIX_APT_UPDATED=1, so skip the
# duplicate refresh on that path.
if [ "${LEDMATRIX_APT_UPDATED:-0}" = "1" ]; then
    echo "Package lists already refreshed by the one-shot installer; skipping apt update."
else
    apt_update
fi

# Install required system packages
echo "Installing Python packages and dependencies..."
apt_install python3-pip python3-venv python-dev-is-python3 python3-pil python3-pil.imagetk build-essential python3-setuptools python3-wheel cmake ninja-build

# Install additional system dependencies that might be needed
echo "Installing additional system dependencies..."
apt_install git curl wget unzip

echo "✓ System dependencies installed"
echo ""

CURRENT_STEP="Fix cache permissions"
echo "Step 2: Fixing cache permissions..."
echo "----------------------------------"

# Run the cache setup script (uses proper group permissions)
if [ -f "$PROJECT_ROOT_DIR/scripts/install/setup_cache.sh" ]; then
    echo "Running cache setup script (proper group permissions)..."
    bash "$PROJECT_ROOT_DIR/scripts/install/setup_cache.sh"
    echo "✓ Cache permissions fixed with proper group setup"
elif [ -f "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_cache_permissions.sh" ]; then
    echo "Running cache permissions fix (legacy script)..."
    bash "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_cache_permissions.sh"
    echo "✓ Cache permissions fixed"
else
    echo "⚠ Cache setup scripts not found, setting up cache directory manually..."
    # Create ledmatrix group if it doesn't exist
    if ! getent group ledmatrix > /dev/null 2>&1; then
        groupadd ledmatrix
        echo "Created ledmatrix group"
    fi
    
    # Add users to ledmatrix group
    usermod -a -G ledmatrix "$ACTUAL_USER"
    if id daemon > /dev/null 2>&1; then
        usermod -a -G ledmatrix daemon
    fi
    
    # Create cache directory with proper permissions
    mkdir -p /var/cache/ledmatrix
    chown -R :ledmatrix /var/cache/ledmatrix
    # Set directory permissions: 775 with setgid for group inheritance
    find /var/cache/ledmatrix -type d -exec chmod 775 {} \;
    chmod g+s /var/cache/ledmatrix
    # Set file permissions: 660 for group-readable cache files
    find /var/cache/ledmatrix -type f -exec chmod 660 {} \;
    
    echo "✓ Cache directory created with proper group permissions"
    echo "  Note: You may need to log out and back in for group changes to take effect"
fi
echo ""

CURRENT_STEP="Fix assets directory permissions"
echo "Step 3: Fixing assets directory permissions..."
echo "--------------------------------------------"

# Run the assets permissions fix
if [ -f "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_assets_permissions.sh" ]; then
    echo "Running assets permissions fix..."
    bash "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_assets_permissions.sh"
    echo "✓ Assets permissions fixed"
else
    echo "⚠ Assets permissions script not found, fixing permissions manually..."
    
    # Set ownership of the entire assets directory to the real user
    echo "Setting ownership of assets directory..."
    chown -R "$ACTUAL_USER:$ACTUAL_USER" "$PROJECT_ROOT_DIR/assets"
    
    # 777: read/write for owner, group and every other account. Root (the
    # display service) does not need it -- root ignores mode bits -- so the
    # "other" bits only matter to accounts that are neither the owner nor root.
    echo "Setting permissions for assets directory..."
    chmod -R 777 "$PROJECT_ROOT_DIR/assets"
    
    # Specifically ensure the sports logos directories are writable
    SPORTS_DIRS=(
        "sports/ncaa_logos"
        "sports/nfl_logos"
        "sports/nba_logos"
        "sports/nhl_logos"
        "sports/mlb_logos"
        "sports/milb_logos"
        "sports/soccer_logos"
    )
    
    echo "Ensuring sports logo directories are writable..."
    for SPORTS_DIR in "${SPORTS_DIRS[@]}"; do
        FULL_PATH="$PROJECT_ROOT_DIR/assets/$SPORTS_DIR"
        if [ -d "$FULL_PATH" ]; then
            chmod 777 "$FULL_PATH"
            chown "$ACTUAL_USER:$ACTUAL_USER" "$FULL_PATH"
        else
            echo "Creating directory: $FULL_PATH"
            mkdir -p "$FULL_PATH"
            chown "$ACTUAL_USER:$ACTUAL_USER" "$FULL_PATH"
            chmod 777 "$FULL_PATH"
        fi
    done
    
    echo "✓ Assets permissions fixed manually"
fi
echo ""

CURRENT_STEP="Fix plugin directory permissions"
echo "Step 3.1: Fixing plugin directory permissions..."
echo "----------------------------------------------"

# Ensure home directory is traversable by root (needed for service access)
USER_HOME=$(eval echo ~$ACTUAL_USER)
if [ -d "$USER_HOME" ]; then
    HOME_PERMS=$(stat -c "%a" "$USER_HOME" 2>/dev/null || echo "unknown")
    if [ "$HOME_PERMS" = "700" ]; then
        echo "Fixing home directory permissions (700 -> 755) so root service can access subdirectories..."
        chmod 755 "$USER_HOME"
        echo "✓ Home directory permissions fixed"
    fi
fi
echo ""

# Run the plugin permissions fix
if [ -f "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_plugin_permissions.sh" ]; then
    echo "Running plugin permissions fix..."
    bash "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_plugin_permissions.sh"
    echo "✓ Plugin permissions fixed"
else
    echo "⚠ Plugin permissions script not found, fixing permissions manually..."
    
    # Ensure plugins directory exists
    if [ ! -d "$PROJECT_ROOT_DIR/plugins" ]; then
        echo "Creating plugins directory..."
        mkdir -p "$PROJECT_ROOT_DIR/plugins"
    fi
    
    # Determine ownership based on web service user
    detect_web_service_user
    
    # If web service runs as ACTUAL_USER (not root), set ownership to ACTUAL_USER
    # so the web service can change permissions. Root service can still access via group (775).
    # If web service runs as root, use root:ACTUAL_USER for mixed access.
    if [ "$WEB_SERVICE_USER" = "$ACTUAL_USER" ] || [ "$WEB_SERVICE_USER" != "root" ]; then
        echo "Web service runs as $WEB_SERVICE_USER, setting ownership to $ACTUAL_USER:$ACTUAL_USER..."
        echo "  (Root service can still access via group permissions)"
        chown -R "$ACTUAL_USER:$ACTUAL_USER" "$PROJECT_ROOT_DIR/plugins"
    else
        echo "Web service runs as root, setting ownership to root:$ACTUAL_USER..."
        chown -R root:"$ACTUAL_USER" "$PROJECT_ROOT_DIR/plugins"
    fi
    
    # Set directory permissions (775: rwxrwxr-x)
    echo "Setting directory permissions to 775..."
    find "$PROJECT_ROOT_DIR/plugins" -type d -exec chmod 775 {} \;
    
    # Set file permissions (664: rw-rw-r--)
    echo "Setting file permissions to 664..."
    find "$PROJECT_ROOT_DIR/plugins" -type f -exec chmod 664 {} \;
    
    echo "✓ Plugin permissions fixed manually"
fi

# Also ensure plugin-repos directory exists with proper permissions
# This is where plugins installed via the plugin store are stored
PLUGIN_REPOS_DIR="$PROJECT_ROOT_DIR/plugin-repos"
if [ ! -d "$PLUGIN_REPOS_DIR" ]; then
    echo "Creating plugin-repos directory..."
    mkdir -p "$PLUGIN_REPOS_DIR"
fi

# Determine ownership based on web service user
detect_web_service_user

# If web service runs as ACTUAL_USER (not root), set ownership to ACTUAL_USER
# so the web service can change permissions. Root service can still access via group (775).
# If web service runs as root, use root:ACTUAL_USER for mixed access.
if [ "$WEB_SERVICE_USER" = "$ACTUAL_USER" ] || [ "$WEB_SERVICE_USER" != "root" ]; then
    echo "Web service runs as $WEB_SERVICE_USER, setting ownership to $ACTUAL_USER:$ACTUAL_USER..."
    echo "  (Root service can still access via group permissions)"
    chown -R "$ACTUAL_USER:$ACTUAL_USER" "$PLUGIN_REPOS_DIR"
else
    echo "Web service runs as root, setting ownership to root:$ACTUAL_USER..."
    chown -R root:"$ACTUAL_USER" "$PLUGIN_REPOS_DIR"
fi

# Set directory permissions (2775: rwxrwsr-x, setgid so new entries inherit the group)
echo "Setting plugin-repos directory permissions to 2775 (setgid)..."
find "$PLUGIN_REPOS_DIR" -type d -exec chmod 2775 {} \;

# Set file permissions (664: rw-rw-r--)
echo "Setting plugin-repos file permissions to 664..."
find "$PLUGIN_REPOS_DIR" -type f -exec chmod 664 {} \;

echo "✓ Plugin-repos directory permissions fixed"
echo ""

CURRENT_STEP="Ensure configuration files exist"
echo "Step 4: Ensuring configuration files exist..."
echo "----------------------------------------------"

# Ensure config directory exists
mkdir -p "$PROJECT_ROOT_DIR/config"
chmod 2775 "$PROJECT_ROOT_DIR/config" || true

# Create ledmatrix group if it doesn't exist (needed for shared access)
LEDMATRIX_GROUP="ledmatrix"
if ! getent group "$LEDMATRIX_GROUP" > /dev/null 2>&1; then
    groupadd "$LEDMATRIX_GROUP" || true
    echo "Created group: $LEDMATRIX_GROUP"
fi

# Add root to ledmatrix group so service can read config files
if ! id -nG root | grep -qw "$LEDMATRIX_GROUP" 2>/dev/null; then
    usermod -a -G "$LEDMATRIX_GROUP" root || true
    echo "Added root to group: $LEDMATRIX_GROUP"
fi

# Set config directory ownership to user:ledmatrix group
chown "$ACTUAL_USER:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config" || true

# Create config.json from template if missing
if [ ! -f "$PROJECT_ROOT_DIR/config/config.json" ]; then
    if [ -f "$PROJECT_ROOT_DIR/config/config.template.json" ]; then
        echo "Creating config/config.json from template..."
        cp "$PROJECT_ROOT_DIR/config/config.template.json" "$PROJECT_ROOT_DIR/config/config.json"
        chown "$ACTUAL_USER:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config/config.json" || true
        chmod 644 "$PROJECT_ROOT_DIR/config/config.json"
        echo "✓ Main config file created from template"
    else
        echo "⚠ Template config/config.template.json not found; creating a minimal config file"
        cat > "$PROJECT_ROOT_DIR/config/config.json" <<'EOF'
{
    "web_display_autostart": true,
    "auto_update": {
        "enabled": false,
        "channel": "stable"
    },
    "timezone": "America/Chicago",
    "display": {
        "hardware": {
            "rows": 32,
            "cols": 64,
            "chain_length": 2,
            "parallel": 1,
            "brightness": 95,
            "hardware_mapping": "adafruit-hat-pwm"
        }
    },
    "clock": {
        "enabled": true,
        "format": "%I:%M %p"
    }
}
EOF
        chown "$ACTUAL_USER:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config/config.json" || true
        chmod 644 "$PROJECT_ROOT_DIR/config/config.json"
        echo "✓ Minimal config file created"
    fi
else
    echo "✓ Main config file already exists"
fi

# Weekly automatic updates (General tab -> Automatic Updates). Off unless asked
# for: --enable-auto-update / LEDMATRIX_AUTO_UPDATE=1, or "y" at the prompt when
# installing interactively. Only an explicit choice changes the setting, so
# re-running the installer with -y never switches it silently.
if [ -z "$AUTO_UPDATE" ] && [ "$ASSUME_YES" != "1" ] && [ -t 0 ]; then
    read -p "Automatically check for and install LEDMatrix updates once a week, with automatic rollback if an update breaks something? (y/N): " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then AUTO_UPDATE=1; else AUTO_UPDATE=0; fi
fi
case "$UPDATE_CHANNEL" in
    stable|beta|"") ;;
    *) echo "⚠ LEDMATRIX_CHANNEL=$UPDATE_CHANNEL is not stable or beta; leaving the update channel as it is"
       UPDATE_CHANNEL="" ;;
esac
# The update channel, likewise only when asked for (--beta / LEDMATRIX_CHANNEL).
if [ "$AUTO_UPDATE" = "1" ] || [ "$AUTO_UPDATE" = "0" ] || [ -n "$UPDATE_CHANNEL" ]; then
    if python3 - "$PROJECT_ROOT_DIR/config/config.json" "$AUTO_UPDATE" "$UPDATE_CHANNEL" <<'PY'
import json, os, sys, tempfile
path, enabled = sys.argv[1], sys.argv[2]
channel = sys.argv[3] if len(sys.argv) > 3 else ""
with open(path, encoding="utf-8") as f:
    config = json.load(f)
if not isinstance(config.get("auto_update"), dict):
    config["auto_update"] = {}
if enabled in ("0", "1"):
    config["auto_update"]["enabled"] = enabled == "1"
if channel:
    config["auto_update"]["channel"] = channel
# Written beside the original and swapped in whole: the display service's
# config watcher may be running and must never read a half-written file.
original = os.stat(path)
fd, tmp = tempfile.mkstemp(dir=os.path.dirname(os.path.abspath(path)), prefix=".config.")
try:
    with os.fdopen(fd, "w", encoding="utf-8") as f:
        json.dump(config, f, indent=4)
        f.write("\n")
        f.flush()
        os.fsync(f.fileno())
    os.chmod(tmp, original.st_mode & 0o777)
    if hasattr(os, "chown"):
        os.chown(tmp, original.st_uid, original.st_gid)
    os.replace(tmp, path)
except BaseException:
    if os.path.exists(tmp):
        os.unlink(tmp)
    raise
PY
    then
        if [ "$AUTO_UPDATE" = "1" ]; then echo "✓ Weekly automatic updates enabled"
        elif [ "$AUTO_UPDATE" = "0" ]; then echo "✓ Weekly automatic updates off"; fi
        if [ -n "$UPDATE_CHANNEL" ]; then echo "✓ Update channel: $UPDATE_CHANNEL"; fi
    else
        echo "⚠ Could not set auto_update in config/config.json; set it from the General tab instead"
    fi
fi

# Create config_secrets.json from template if missing
if [ ! -f "$PROJECT_ROOT_DIR/config/config_secrets.json" ]; then
    if [ -f "$PROJECT_ROOT_DIR/config/config_secrets.template.json" ]; then
        echo "Creating config/config_secrets.json from template..."
        cp "$PROJECT_ROOT_DIR/config/config_secrets.template.json" "$PROJECT_ROOT_DIR/config/config_secrets.json"
        # Check if service runs as root and set ownership accordingly
        SERVICE_USER="root"
        if [ -f "/etc/systemd/system/ledmatrix.service" ]; then
            SERVICE_USER=$(grep "^User=" /etc/systemd/system/ledmatrix.service | cut -d'=' -f2 || echo "root")
        elif [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix.service" ]; then
            SERVICE_USER=$(grep "^User=" "$PROJECT_ROOT_DIR/systemd/ledmatrix.service" | cut -d'=' -f2 || echo "root")
        fi
        
        if [ "$SERVICE_USER" = "root" ]; then
            chown "root:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config/config_secrets.json" || true
        else
            chown "$ACTUAL_USER:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config/config_secrets.json" || true
        fi
        chmod 640 "$PROJECT_ROOT_DIR/config/config_secrets.json"
        echo "✓ Secrets file created from template"
    else
        echo "⚠ Template config/config_secrets.template.json not found; creating a minimal secrets file"
        cat > "$PROJECT_ROOT_DIR/config/config_secrets.json" <<'EOF'
{
    "github": {
        "api_token": "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"
    }
}
EOF
        # Check if service runs as root and set ownership accordingly
        SERVICE_USER="root"
        if [ -f "/etc/systemd/system/ledmatrix.service" ]; then
            SERVICE_USER=$(grep "^User=" /etc/systemd/system/ledmatrix.service | cut -d'=' -f2 || echo "root")
        elif [ -f "$PROJECT_ROOT_DIR/systemd/ledmatrix.service" ]; then
            SERVICE_USER=$(grep "^User=" "$PROJECT_ROOT_DIR/systemd/ledmatrix.service" | cut -d'=' -f2 || echo "root")
        fi
        
        if [ "$SERVICE_USER" = "root" ]; then
            chown "root:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config/config_secrets.json" || true
        else
            chown "$ACTUAL_USER:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config/config_secrets.json" || true
        fi
        chmod 640 "$PROJECT_ROOT_DIR/config/config_secrets.json"
        echo "✓ Minimal secrets file created"
    fi
else
    echo "✓ Secrets file already exists"
fi
echo ""

CURRENT_STEP="Install project Python dependencies"
echo "Step 5: Installing Python project dependencies..."
echo "-----------------------------------------------"

# Install main project Python dependencies (numpy will be installed via pip from requirements.txt)
cd "$PROJECT_ROOT_DIR"
if [ -f "$PROJECT_ROOT_DIR/requirements.txt" ]; then
    echo "Reading requirements from: $PROJECT_ROOT_DIR/requirements.txt"
    
    # Check pip version (apt-installed pip is sufficient, no upgrade needed)
    echo "Checking pip version..."
    python3 -m pip --version

    # Count total packages for progress
    TOTAL_PACKAGES=$(grep -v '^#' "$PROJECT_ROOT_DIR/requirements.txt" | grep -v '^$' | wc -l)
    echo "Found $TOTAL_PACKAGES package(s) to install"
    echo ""
    
    # Install packages one at a time for better diagnostics
    INSTALLED=0
    FAILED=0
    PACKAGE_NUM=0
    
    while IFS= read -r line || [ -n "$line" ]; do
        # Remove inline comments (everything after #) but preserve comment-only lines
        # First check if line starts with # (comment-only line)
        if [[ "$line" =~ ^[[:space:]]*# ]]; then
            continue
        fi
        
        # Remove inline comments and trim whitespace
        line=$(echo "$line" | sed 's/[[:space:]]*#.*$//' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
        
        # Skip empty lines
        if [[ -z "$line" ]]; then
            continue
        fi
        
        PACKAGE_NUM=$((PACKAGE_NUM + 1))
        echo "[$PACKAGE_NUM/$TOTAL_PACKAGES] Installing: $line"
        
        # Install with a timeout where available. --verbose output goes to
        # $INSTALL_OUTPUT (filtered below, full copy in the log); --no-cache-dir
        # avoids pip cache issues.
        INSTALL_OUTPUT=$(mktemp)
        INSTALL_SUCCESS=false
        
        if command -v timeout >/dev/null 2>&1; then
            # Use timeout if available (10 minutes = 600 seconds)
            # --ignore-installed: apt-managed packages (e.g. python3-requests)
            # ship no pip RECORD file, so upgrading them would otherwise abort
            # with "uninstall-no-record-file"; this lays the new version down
            # alongside instead of trying to uninstall the apt copy first.
            if timeout 600 python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose "$line" > "$INSTALL_OUTPUT" 2>&1; then
                INSTALL_SUCCESS=true
            else
                EXIT_CODE=$?
                if [ "$EXIT_CODE" -eq 124 ]; then
                    echo "✗ Timeout (10 minutes) installing: $line"
                    echo "  This package may require building from source, which can be slow on Raspberry Pi."
                    echo "  You can try installing it manually later with:"
                    echo "    python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose '$line'"
                else
                    echo "✗ Failed to install: $line (exit code: $EXIT_CODE)"
                fi
            fi
        else
            # No timeout command available, install without timeout
            echo "  Note: timeout command not available, installation may take a while..."
            if python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose "$line" > "$INSTALL_OUTPUT" 2>&1; then
                INSTALL_SUCCESS=true
            else
                EXIT_CODE=$?
                echo "✗ Failed to install: $line (exit code: $EXIT_CODE)"
            fi
        fi
        
        # Show relevant output (filtered for readability)
        if [ -f "$INSTALL_OUTPUT" ]; then
            echo "  Output:"
            grep -E "(Collecting|Installing|Successfully|Preparing metadata|Building|ERROR|WARNING|Using cached|Downloading)" "$INSTALL_OUTPUT" | head -15 | sed 's/^/    /' || true
            # Log full output to log file
            cat "$INSTALL_OUTPUT" >> "$LOG_FILE"
            rm -f "$INSTALL_OUTPUT"
        fi
        
        if [ "$INSTALL_SUCCESS" = true ]; then
            INSTALLED=$((INSTALLED + 1))
            echo "✓ Successfully installed: $line"
        else
            FAILED=$((FAILED + 1))
            
            # Ask if user wants to continue (unless in non-interactive mode)
            if [ "$ASSUME_YES" != "1" ]; then
                read -p "  Continue with remaining packages? (Y/n): " -n 1 -r
                echo
                if [[ $REPLY =~ ^[Nn]$ ]]; then
                    echo "Installation cancelled by user"
                    exit 1
                fi
            fi
        fi
        echo ""
    done < "$PROJECT_ROOT_DIR/requirements.txt"
    
    echo "-----------------------------------------------"
    echo "Installation summary:"
    echo "  Installed: $INSTALLED"
    echo "  Failed: $FAILED"
    echo "  Total: $TOTAL_PACKAGES"
    echo ""
    
    if [ "$FAILED" -gt 0 ]; then
        echo "⚠ Some packages failed to install. The installation will continue, but"
        echo "  you may need to install them manually later. Check the log for details:"
        echo "  $LOG_FILE"
        echo ""
        echo "Common fixes for 'Preparing metadata' issues:"
        echo "  1. Ensure you have enough disk space: df -h"
        echo "  2. Check available memory: free -h"
        echo "  3. Try installing failed packages individually with verbose output:"
        echo "     python3 -m pip install --break-system-packages --no-cache-dir --prefer-binary --ignore-installed --verbose <package>"
        echo "  4. For packages that build from source (like numpy), consider:"
        echo "     - Installing pre-built wheels: python3 -m pip install --only-binary :all: <package>"
        echo "     - Or installing via apt if available: sudo apt install python3-<package>"
        echo ""
    fi
    
    if [ "$INSTALLED" -gt 0 ]; then
        echo "✓ Project Python dependencies installed ($INSTALLED/$TOTAL_PACKAGES successful)"
    else
        echo "✗ No packages were successfully installed"
        echo "  Check the log file for details: $LOG_FILE"
        exit 1
    fi
else
    echo "⚠ requirements.txt not found; skipping main dependency install"
fi
echo ""

# Install web interface dependencies
echo "Installing web interface dependencies..."
if [ -f "$PROJECT_ROOT_DIR/web_interface/requirements.txt" ]; then
    # --ignore-installed: apt-managed packages (e.g. python3-requests) ship no
    # pip RECORD file, so upgrading them to the version pinned here would
    # otherwise abort the whole install with "uninstall-no-record-file".
    if python3 -m pip install --break-system-packages --prefer-binary --ignore-installed -r "$PROJECT_ROOT_DIR/web_interface/requirements.txt"; then
        echo "✓ Web interface dependencies installed"
        # Create marker file to indicate dependencies are installed
        touch "$PROJECT_ROOT_DIR/.web_deps_installed"
    else
        echo "⚠ Warning: Some web interface dependencies failed to install"
        echo "  The web interface may not work correctly until dependencies are installed"
    fi
else
    echo "⚠ web_interface/requirements.txt not found; skipping"
fi
echo ""

CURRENT_STEP="Build and install rpi-rgb-led-matrix"
echo "Step 6: Building and installing rpi-rgb-led-matrix..."
echo "-----------------------------------------------------"

# On Pi 5, also check that the installed library has rp1_rio support.
# A library built before Pi 5 support was added imports fine but maps to the
# Pi 3 peripheral bus address (0x3f000000) instead of the RP1 chip at runtime.
_HAS_RP1=0
if python3 -c 'from rgbmatrix import RGBMatrixOptions; assert hasattr(RGBMatrixOptions(), "rp1_rio")' >/dev/null 2>&1; then
    _HAS_RP1=1
fi

_SKIP_BUILD=0
if python3 -c 'from rgbmatrix import RGBMatrix, RGBMatrixOptions' >/dev/null 2>&1 && [ "${RPI_RGB_FORCE_REBUILD:-0}" != "1" ]; then
    if [ "$IS_PI5" = "1" ] && [ "$_HAS_RP1" = "0" ]; then
        echo "⚠ Pi 5 detected: installed rgbmatrix lacks rp1_rio support (older build)."
        echo "  Forcing rebuild to get Pi 5 RP1 support..."
    else
        _SKIP_BUILD=1
    fi
fi

if [ "$_SKIP_BUILD" = "1" ]; then
    _skip_suffix=""
    if [ "$IS_PI5" = "1" ]; then _skip_suffix=" with Pi 5 RP1 support"; fi
    echo "rgbmatrix already installed${_skip_suffix}; skipping build (set RPI_RGB_FORCE_REBUILD=1 to force rebuild)."
else
    # Ensure rpi-rgb-led-matrix submodule is initialized
    # Wrapper used with retry(): removes any partial clone dir before each attempt
    # so git clone doesn't fail with "destination path already exists".
    _clone_rpi_rgb() {
        rm -rf "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master"
        _git_as_repo_owner clone https://github.com/hzeller/rpi-rgb-led-matrix.git rpi-rgb-led-matrix-master
    }
    _reclaim_rgb_checkout
    if [ ! -d "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" ]; then
        echo "rpi-rgb-led-matrix-master not found. Initializing git submodule..."
        cd "$PROJECT_ROOT_DIR"

        # Try to initialize submodule if .gitmodules exists
        if [ -f "$PROJECT_ROOT_DIR/.gitmodules" ] && grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules"; then
            echo "Initializing rpi-rgb-led-matrix submodule..."
            if ! retry _git_as_repo_owner submodule update --init --recursive rpi-rgb-led-matrix-master; then
                echo "⚠ Submodule init failed, cloning directly from GitHub..."
                retry _clone_rpi_rgb
            fi
        else
            # Fallback: clone directly if submodule not configured
            echo "Submodule not configured, cloning directly from GitHub..."
            retry _clone_rpi_rgb
        fi
    fi

    # Build and install rpi-rgb-led-matrix Python bindings
    if [ -d "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" ]; then
        # Check if submodule is properly initialized (not empty)
        if [ ! -f "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master/Makefile" ]; then
            echo "⚠ Submodule appears empty, re-initializing..."
            cd "$PROJECT_ROOT_DIR"
            rm -rf rpi-rgb-led-matrix-master
            if [ -f "$PROJECT_ROOT_DIR/.gitmodules" ] && grep -q "rpi-rgb-led-matrix" "$PROJECT_ROOT_DIR/.gitmodules"; then
                retry _git_as_repo_owner submodule update --init --recursive rpi-rgb-led-matrix-master
            else
                retry _clone_rpi_rgb
            fi
        fi

        _sync_rgb_submodule

        # Add temporary swap on low-memory devices so the compiler survives.
        CURRENT_STEP="Prepare the low-memory build environment"
        if [ "$LOWMEM_AVAILABLE" = "1" ] && [ "$SKIP_SWAP" != "1" ]; then
            lm_ensure_build_swap "$(lm_swap_needed_mb "$TOTAL_RAM_MB" "$TOTAL_SWAP_MB")"
        elif [ "$SKIP_SWAP" = "1" ]; then
            LM_SWAP_SKIP_REASON="disabled with --skip-swap"
        fi

        # pip builds in $TMPDIR. Debian 13 mounts /tmp as tmpfs, so the default
        # would hold the entire C++ build tree in RAM — competing with the very
        # compiler we are trying to keep under the memory limit.
        BUILD_TMPDIR=""
        if [ "$LOWMEM_AVAILABLE" = "1" ]; then
            _disk_tmp=$(lm_disk_backed_tmpdir)
            if [ -n "$_disk_tmp" ]; then
                BUILD_TMPDIR="$_disk_tmp/ledmatrix-build"
                # If this fails (a nearly-full disk being the likely cause on
                # exactly the devices this targets), fall back to the default
                # rather than pointing the build at a path that does not exist.
                if mkdir -p "$BUILD_TMPDIR" 2>/dev/null; then
                    echo "Building in $BUILD_TMPDIR (TMPDIR is memory-backed; keeping the build tree on disk)"
                else
                    echo "⚠ Could not create $BUILD_TMPDIR; falling back to the default TMPDIR"
                    BUILD_TMPDIR=""
                fi
            fi
        fi

        CURRENT_STEP="Build and install rpi-rgb-led-matrix"
        pushd "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" >/dev/null
        echo "Installing rpi-rgb-led-matrix Python package (scikit-build-core + cmake)..."
        echo "  Build deps required: python-dev-is-python3 cmake"
        echo "  Compiling C++ with ${BUILD_JOBS} parallel job(s)..."
        if [ "$BUILD_JOBS" -le 1 ]; then
            echo "  Deliberately serial to stay within this device's memory — expect 15-25 minutes."
        else
            echo "  This may take 2-5 minutes on a Pi 4/5..."
        fi
        BUILD_OUTPUT=$(mktemp)
        BUILD_SUCCESS=false
        _apply_rgb_patches
        if run_rgbmatrix_build "$BUILD_JOBS" "$BUILD_OUTPUT"; then
            BUILD_SUCCESS=true
        fi
        _revert_rgb_patches
        cat "$BUILD_OUTPUT" >> "$LOG_FILE"
        if [ "$BUILD_SUCCESS" != true ]; then
            print_rgbmatrix_build_failure "$BUILD_OUTPUT"
            echo ""
            echo "-- Last 50 lines of build output --"
            tail -n 50 "$BUILD_OUTPUT"
            rm -f "$BUILD_OUTPUT"
            if [ -n "$BUILD_TMPDIR" ]; then rm -rf "$BUILD_TMPDIR"; fi
            popd >/dev/null
            lm_remove_build_swap
            exit 1
        fi
        rm -f "$BUILD_OUTPUT"
        if [ -n "$BUILD_TMPDIR" ]; then rm -rf "$BUILD_TMPDIR"; fi
        popd >/dev/null
        # Hand the memory back well before Step 14's reboot.
        lm_remove_build_swap
    else
        echo "✗ rpi-rgb-led-matrix-master directory not found at $PROJECT_ROOT_DIR"
        echo "Failed to initialize submodule or clone repository"
        exit 1
    fi

    echo "Running rgbmatrix import test..."
    if python3 - <<'PY'
from importlib.metadata import version, PackageNotFoundError
try:
    from rgbmatrix import RGBMatrix, RGBMatrixOptions
    try:
        print("Success! rgbmatrix version:", version('rgbmatrix'))
    except PackageNotFoundError:
        print("Success! rgbmatrix installed (version unknown)")
except Exception as e:
    raise SystemExit(f"rgbmatrix import failed: {e}")
PY
    then
        echo "✓ rpi-rgb-led-matrix installed and verified"
        # Pi 5: confirm the freshly-built library has rp1_rio support
        if [ "$IS_PI5" = "1" ]; then
            if python3 -c 'from rgbmatrix import RGBMatrixOptions; assert hasattr(RGBMatrixOptions(), "rp1_rio")' >/dev/null 2>&1; then
                echo "✓ Pi 5 RP1 (rp1_rio) support confirmed"
            else
                echo "⚠ rp1_rio not found after rebuild — the submodule may be an older version."
                echo "  Try updating the submodule and rebuilding:"
                echo "    git submodule update --remote rpi-rgb-led-matrix-master"
                echo "    sudo RPI_RGB_FORCE_REBUILD=1 ./first_time_install.sh"
            fi
        fi
    else
        echo "✗ rpi-rgb-led-matrix import test failed"
        exit 1
    fi
fi
echo ""

CURRENT_STEP="Install web interface dependencies"
echo "Step 7: Installing web interface dependencies..."
echo "------------------------------------------------"

# Check if web dependencies were already installed (marker created in Step 5)
if [ -f "$PROJECT_ROOT_DIR/.web_deps_installed" ]; then
    echo "✓ Web interface dependencies already installed (marker file found)"
else
    # Install web interface dependencies
    echo "Installing Python dependencies for web interface..."
    cd "$PROJECT_ROOT_DIR"

    # Try to install dependencies using the smart installer if available
    WEB_DEPS_OK=true
    if [ -f "$PROJECT_ROOT_DIR/scripts/install_dependencies_apt.py" ]; then
        echo "Using smart dependency installer..."
        # -u: unbuffered stdout/stderr so output is captured in $LOG_FILE in
        # real time and in order relative to this script's own echo statements
        if ! python3 -u "$PROJECT_ROOT_DIR/scripts/install_dependencies_apt.py"; then
            WEB_DEPS_OK=false
        fi
    else
        # No marker means Step 5 did not install web_interface/requirements.txt,
        # and without the smart installer there is nothing else to try here.
        echo "⚠ scripts/install_dependencies_apt.py not found, and Step 5 did not install"
        echo "  web_interface/requirements.txt, so web interface dependencies may be missing."
        WEB_DEPS_OK=false
    fi

    # Create the marker only when installation actually succeeded, so a
    # re-run retries instead of silently skipping missing dependencies.
    if [ "$WEB_DEPS_OK" = true ]; then
        touch "$PROJECT_ROOT_DIR/.web_deps_installed"
        echo "✓ Web interface dependencies installed"
    else
        echo "⚠ Web interface dependency install reported errors; not creating .web_deps_installed (will retry on next run)"
    fi
fi
echo ""

CURRENT_STEP="Install main LED Matrix service"
echo "Step 7.5: Installing main LED Matrix service..."
echo "------------------------------------------------"

# Run the main service installation (idempotent)
# Note: install_service.sh always overwrites the service file, so it will update paths automatically
# This step runs AFTER all Python dependencies are installed (Steps 5-7)
if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" ]; then
    echo "Running main service installation/update..."
    bash "$PROJECT_ROOT_DIR/scripts/install/install_service.sh"
    echo "✓ Main LED Matrix service installed/updated"
else
    echo "✗ Main service installation script not found at $PROJECT_ROOT_DIR/scripts/install/install_service.sh"
    echo "Please ensure you are running this script from the project root: $PROJECT_ROOT_DIR"
    exit 1
fi

# Configure Python capabilities for hardware timing
echo "Configuring Python capabilities for hardware timing..."

# Check if setcap is available first
if ! command -v setcap >/dev/null 2>&1; then
    echo "⚠ setcap not found, skipping capability configuration"
    echo "  Install libcap2-bin if you need hardware timing capabilities"
else
    # The binary the services run (ExecStart=/usr/bin/python3), symlinks
    # resolved: python3.11 on Bookworm, python3.13 on Trixie. This used to
    # prefer /usr/bin/python3.13 whenever it existed, which would set the
    # capability on an interpreter the services never run if python3 pointed
    # elsewhere.
    PYTHON_BIN=""
    PYTHON_VER=""
    if [ -f "/usr/bin/python3" ]; then
        PYTHON_BIN=$(readlink -f /usr/bin/python3)
        PYTHON_VER=$(lm_python_version /usr/bin/python3) || PYTHON_VER="unknown"
    fi

    if [ -n "$PYTHON_BIN" ] && [ -f "$PYTHON_BIN" ]; then
        echo "Setting cap_sys_nice on $PYTHON_BIN (Python $PYTHON_VER)..."
        if sudo setcap 'cap_sys_nice=eip' "$PYTHON_BIN" 2>/dev/null; then
            echo "✓ Python $PYTHON_VER capabilities configured ($PYTHON_BIN)"
        else
            echo "⚠ Could not set cap_sys_nice on $PYTHON_BIN"
            echo "  This may require manual setup or running as root"
            echo "  The LED display may have timing issues without this capability"
        fi
    else
        echo "⚠ Python3 not found, skipping capability configuration"
    fi
fi
echo ""

CURRENT_STEP="Install web interface service"
echo "Step 8: Installing web interface service..."
echo "-------------------------------------------"

if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" ]; then
    # Check if service file exists and has old paths (needs update after reorganization)
    NEEDS_UPDATE=false
    if [ -f "/etc/systemd/system/ledmatrix-web.service" ]; then
        # Check if service file references old path (start_web_conditionally.py without scripts/utils/)
        if grep -q "start_web_conditionally.py" /etc/systemd/system/ledmatrix-web.service && ! grep -q "scripts/utils/start_web_conditionally.py" /etc/systemd/system/ledmatrix-web.service; then
            NEEDS_UPDATE=true
            echo "⚠ Service file has old paths, updating..."
        fi
    fi
    
    if [ ! -f "/etc/systemd/system/ledmatrix-web.service" ] || [ ! -f "/etc/systemd/system/ledmatrix-update-verify.path" ] || [ "$NEEDS_UPDATE" = true ]; then
        bash "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh"
        # Ensure systemd sees any new/changed unit files
        systemctl daemon-reload || true
        echo "✓ Web interface service installed/updated"
    else
        echo "✓ Web interface service already present with correct paths"
    fi
else
    echo "⚠ install_web_service.sh not found; skipping web service installation"
fi
echo ""

CURRENT_STEP="Harden systemd unit file permissions"
echo "Step 8.1: Setting systemd unit file permissions..."
echo "-----------------------------------------------"
for unit in "/etc/systemd/system/ledmatrix.service" "/etc/systemd/system/ledmatrix-web.service" "/etc/systemd/system/ledmatrix-wifi-monitor.service" "/etc/systemd/system/ledmatrix-update-verify.service" "/etc/systemd/system/ledmatrix-update-verify.path"; do
    if [ -f "$unit" ]; then
        chown root:root "$unit" || true
        chmod 644 "$unit" || true
    fi
done
systemctl daemon-reload || true
echo "✓ Systemd unit file permissions set"
echo ""

CURRENT_STEP="Install WiFi monitor service"
echo "Step 8.5: Installing WiFi monitor service..."
echo "---------------------------------------------"

# Install WiFi monitor service if script exists
if [ -f "$PROJECT_ROOT_DIR/scripts/install/install_wifi_monitor.sh" ]; then
    # Check if service file exists and has old paths (needs update after reorganization)
    NEEDS_UPDATE=false
    if [ -f "/etc/systemd/system/ledmatrix-wifi-monitor.service" ]; then
        # Check if service file references old path (wifi_monitor_daemon.py without scripts/utils/)
        if grep -q "wifi_monitor_daemon.py" /etc/systemd/system/ledmatrix-wifi-monitor.service && ! grep -q "scripts/utils/wifi_monitor_daemon.py" /etc/systemd/system/ledmatrix-wifi-monitor.service; then
            NEEDS_UPDATE=true
            echo "⚠ WiFi monitor service file has old paths, updating..."
        fi
    fi
    
    if [ ! -f "/etc/systemd/system/ledmatrix-wifi-monitor.service" ] || [ "$NEEDS_UPDATE" = true ]; then
        echo "Installing/updating WiFi monitor service..."
        # Run install script but don't fail installation if it errors (WiFi monitor is optional)
        if bash "$PROJECT_ROOT_DIR/scripts/install/install_wifi_monitor.sh"; then
            echo "✓ WiFi monitor service installation completed"
        else
            INSTALL_EXIT_CODE=$?
            echo "⚠ WiFi monitor service installation returned exit code $INSTALL_EXIT_CODE"
            echo "  Continuing installation - WiFi monitor is optional and can be installed later"
        fi
    fi
    
    # Harden service file permissions (if service was created)
    if [ -f "/etc/systemd/system/ledmatrix-wifi-monitor.service" ]; then
        chown root:root "/etc/systemd/system/ledmatrix-wifi-monitor.service" || true
        chmod 644 "/etc/systemd/system/ledmatrix-wifi-monitor.service" || true
        systemctl daemon-reload || true
        
        # Check if service was installed successfully
        if systemctl list-unit-files | grep -q "ledmatrix-wifi-monitor.service"; then
            echo "✓ WiFi monitor service installed"
            
            # Check if service is running
            if systemctl is-active --quiet ledmatrix-wifi-monitor.service 2>/dev/null; then
                echo "✓ WiFi monitor service is running"
            else
                echo "⚠ WiFi monitor service installed but not running (may need required packages)"
            fi
        else
            echo "⚠ WiFi monitor service file exists but not registered with systemd"
        fi
    else
        echo "⚠ WiFi monitor service file not created (installation may have failed)"
        echo "  You can install it later by running: sudo ./scripts/install/install_wifi_monitor.sh"
    fi
else
    echo "⚠ install_wifi_monitor.sh not found; skipping WiFi monitor installation"
    echo "  You can install it later by running: sudo ./scripts/install/install_wifi_monitor.sh"
fi
echo ""

CURRENT_STEP="Configure web interface permissions"
echo "Step 9: Configuring web interface permissions..."
echo "------------------------------------------------"

# Add user to required groups (idempotent)
echo "Adding user to systemd-journal group..."
if id -nG "$ACTUAL_USER" | grep -qw systemd-journal; then
    echo "User $ACTUAL_USER already in systemd-journal"
else
    usermod -a -G systemd-journal "$ACTUAL_USER"
fi

echo "Adding user to adm group..."
if id -nG "$ACTUAL_USER" | grep -qw adm; then
    echo "User $ACTUAL_USER already in adm"
else
    usermod -a -G adm "$ACTUAL_USER"
fi

echo "✓ User added to required groups"
echo ""

CURRENT_STEP="Configure passwordless sudo access"
echo "Step 10: Configuring passwordless sudo access..."
echo "------------------------------------------------"

# Create sudoers configuration for the web interface
echo "Creating sudoers configuration..."
SUDOERS_FILE="/etc/sudoers.d/ledmatrix_web"
# A predictable name in a world-writable directory is a symlink target;
# root writes the rules here, so let mktemp pick the name.
SUDOERS_TMP=$(mktemp "${TMPDIR:-/tmp}/ledmatrix_web_sudoers.XXXXXX")

# Get command paths
PYTHON_PATH=$(which python3)
SYSTEMCTL_PATH=$(which systemctl)
REBOOT_PATH=$(which reboot)
POWEROFF_PATH=$(which poweroff)
BASH_PATH=$(which bash)
JOURNALCTL_PATH=$(which journalctl 2>/dev/null || true)

# The rules themselves live in scripts/install/lib_sudoers.sh, shared with
# scripts/install/configure_web_sudo.sh so the two cannot drift apart again.
# If it is missing (a damaged checkout), keep whatever is already installed
# rather than failing the whole install; the gate below skips the install.
SUDOERS_VALID=1
SUDOERS_LIB="$PROJECT_ROOT_DIR/scripts/install/lib_sudoers.sh"
if [ -f "$SUDOERS_LIB" ]; then
    # shellcheck source=scripts/install/lib_sudoers.sh
    . "$SUDOERS_LIB"
    web_sudoers_rules "$ACTUAL_USER" "$PROJECT_ROOT_DIR" "$SYSTEMCTL_PATH" "$BASH_PATH" \
        "$REBOOT_PATH" "$POWEROFF_PATH" "$JOURNALCTL_PATH" > "$SUDOERS_TMP"
else
    SUDOERS_VALID=0
    echo "⚠ $SUDOERS_LIB not found; cannot generate the sudoers rules." >&2
    echo "⚠ Leaving $SUDOERS_FILE unchanged. The web interface cannot control" >&2
    echo "  the display service until this is fixed." >&2
fi

# Never install rules we have not parsed. A malformed drop-in in
# /etc/sudoers.d makes sudo refuse every command for every user, which on a
# headless Pi leaves no way in at all. If the rules do not parse, say so and
# keep whatever is already installed.
if [ "$SUDOERS_VALID" = "0" ]; then
    :  # nothing was generated; already reported above
elif command -v visudo >/dev/null 2>&1; then
    if ! visudo -c -f "$SUDOERS_TMP" >/dev/null 2>&1; then
        SUDOERS_VALID=0
        echo "⚠ The generated sudoers rules did not parse:" >&2
        visudo -c -f "$SUDOERS_TMP" >&2 || true
        echo "⚠ Leaving $SUDOERS_FILE unchanged. The web interface cannot control" >&2
        echo "  the display service until this is fixed." >&2
    fi
else
    echo "⚠ visudo not found; installing the sudoers rules unvalidated"
fi

if [ "$SUDOERS_VALID" = "0" ]; then
    rm -f "$SUDOERS_TMP"
elif [ -f "$SUDOERS_FILE" ] && cmp -s "$SUDOERS_TMP" "$SUDOERS_FILE"; then
    echo "Sudoers configuration already up to date"
    rm -f "$SUDOERS_TMP"
else
    echo "Installing/updating sudoers configuration..."
    cp "$SUDOERS_TMP" "$SUDOERS_FILE"
    chmod 440 "$SUDOERS_FILE"
    rm -f "$SUDOERS_TMP"
fi

if [ "$SUDOERS_VALID" = "1" ]; then
    echo "✓ Passwordless sudo access configured"
fi
echo ""

CURRENT_STEP="Configure WiFi management permissions"
echo "Step 10.1: Configuring WiFi management permissions..."
echo "-----------------------------------------------------"

# Configure WiFi permissions (sudo and PolicyKit) for WiFi management
if [ -f "$PROJECT_ROOT_DIR/scripts/install/configure_wifi_permissions.sh" ]; then
    echo "Configuring WiFi management permissions..."
    # Run as the actual user (not root) since the script checks for that
    if sudo -u "$ACTUAL_USER" bash "$PROJECT_ROOT_DIR/scripts/install/configure_wifi_permissions.sh"; then
        echo "✓ WiFi management permissions configured"
    else
        echo "⚠ WiFi permissions configuration failed, but continuing installation"
        echo "  You can run it manually later: ./scripts/install/configure_wifi_permissions.sh"
    fi
else
    echo "⚠ configure_wifi_permissions.sh not found; skipping WiFi permissions configuration"
    echo "  You can configure WiFi permissions later by running:"
    echo "    ./scripts/install/configure_wifi_permissions.sh"
fi
echo ""

CURRENT_STEP="Set proper file ownership"
echo "Step 11: Setting proper file ownership..."
echo "----------------------------------------"

# Set ownership of project files to the user
# Exclude plugin directories which need special permissions for root service access
# Use -h flag with chown to operate on symlinks themselves rather than following them
echo "Setting project file ownership (excluding plugin directories)..."
find "$PROJECT_ROOT_DIR" \
    -path "$PROJECT_ROOT_DIR/plugins" -prune -o \
    -path "$PROJECT_ROOT_DIR/plugin-repos" -prune -o \
    -path "$PROJECT_ROOT_DIR/scripts/dev/plugins" -prune -o \
    -path "*/.git*" -prune -o \
    -exec chown -h "$ACTUAL_USER:$ACTUAL_USER" {} \; 2>/dev/null || true

# Set proper permissions for config files
if [ -f "$PROJECT_ROOT_DIR/config/config.json" ]; then
    chmod 644 "$PROJECT_ROOT_DIR/config/config.json"
    echo "✓ Config file permissions set"
fi

# Set proper permissions for secrets file (restrictive: owner rw, group r)
# Owned by whoever WRITES the file, which is the web interface.
#
# This used to read the User= of ledmatrix.service — the display service —
# and, finding root, hand the file to root:ledmatrix 640. But the display
# service only ever reads secrets, and root can read any file regardless of
# mode. The account that *writes* them is the web interface: it saves config
# edits and performs backup restores, and it deliberately does not run as root
# (a web server should not). So a root-owned, group-read-only file left the web
# UI unable to write its own secrets, and restoring a backup failed with
# "Permission denied: config_secrets.json" while every other file in the same
# backup restored fine.
#
# Owning by the writer keeps the tighter 640 rather than loosening to
# group-writable, and root still reads it as superuser.
if [ -f "$PROJECT_ROOT_DIR/config/config_secrets.json" ]; then
    # The web service is the writer; fall back to the display service, then to
    # the installing user, so an unusual layout still lands somewhere sensible.
    SECRETS_OWNER=""
    for unit in "/etc/systemd/system/ledmatrix-web.service" \
                "$PROJECT_ROOT_DIR/systemd/ledmatrix-web.service"; do
        if [ -f "$unit" ]; then
            SECRETS_OWNER=$(grep -m1 "^User=" "$unit" | cut -d'=' -f2)
            [ -n "$SECRETS_OWNER" ] && break
        fi
    done
    if [ -z "$SECRETS_OWNER" ]; then
        SECRETS_OWNER="$ACTUAL_USER"
    fi
    SECRETS_FILE="$PROJECT_ROOT_DIR/config/config_secrets.json"
    # A root-owned file is only correct when the writer really is root.
    if ! chown "$SECRETS_OWNER:$LEDMATRIX_GROUP" "$SECRETS_FILE"; then
        echo "✗ ERROR: Failed to set ownership on $SECRETS_FILE to $SECRETS_OWNER:$LEDMATRIX_GROUP" >&2
        echo "  Try: sudo chown $SECRETS_OWNER:$LEDMATRIX_GROUP $SECRETS_FILE" >&2
        exit 1
    fi
    if ! chmod 640 "$SECRETS_FILE"; then
        echo "✗ ERROR: Failed to set permissions on $SECRETS_FILE to 640" >&2
        echo "  Try: sudo chmod 640 $SECRETS_FILE" >&2
        exit 1
    fi
    ACTUAL_OWNERSHIP=$(stat -c '%U:%G' "$SECRETS_FILE" 2>/dev/null || echo "unknown")
    ACTUAL_MODE=$(stat -c '%a' "$SECRETS_FILE" 2>/dev/null || echo "unknown")
    if [ "$ACTUAL_OWNERSHIP" != "$SECRETS_OWNER:$LEDMATRIX_GROUP" ] || [ "$ACTUAL_MODE" != "640" ]; then
        echo "✗ ERROR: $SECRETS_FILE ended up as $ACTUAL_OWNERSHIP mode $ACTUAL_MODE, expected $SECRETS_OWNER:$LEDMATRIX_GROUP mode 640" >&2
        echo "  The web interface may be unable to read or write config_secrets.json." >&2
        exit 1
    fi
    echo "✓ Secrets file owned by the web service user ($SECRETS_OWNER:$LEDMATRIX_GROUP, mode 640)"
fi

# Set proper permissions for YTM auth file (readable by all users including root service)
if [ -f "$PROJECT_ROOT_DIR/config/ytm_auth.json" ]; then
    chown "$ACTUAL_USER:$LEDMATRIX_GROUP" "$PROJECT_ROOT_DIR/config/ytm_auth.json" || true
    chmod 644 "$PROJECT_ROOT_DIR/config/ytm_auth.json"
    echo "✓ YTM auth file permissions set"
fi

# Re-apply plugin directory permissions based on web service user
echo "Re-applying plugin directory permissions..."
# Determine ownership based on web service user
detect_web_service_user

# Set ownership based on web service user
if [ "$WEB_SERVICE_USER" = "$ACTUAL_USER" ] || [ "$WEB_SERVICE_USER" != "root" ]; then
    PLUGIN_OWNER="$ACTUAL_USER:$ACTUAL_USER"
else
    PLUGIN_OWNER="root:$ACTUAL_USER"
fi

if [ -d "$PROJECT_ROOT_DIR/plugins" ]; then
    chown -R "$PLUGIN_OWNER" "$PROJECT_ROOT_DIR/plugins"
    find "$PROJECT_ROOT_DIR/plugins" -type d -exec chmod 2775 {} \;
    find "$PROJECT_ROOT_DIR/plugins" -type f -exec chmod 664 {} \;
fi
if [ -d "$PROJECT_ROOT_DIR/plugin-repos" ]; then
    chown -R "$PLUGIN_OWNER" "$PROJECT_ROOT_DIR/plugin-repos"
    find "$PROJECT_ROOT_DIR/plugin-repos" -type d -exec chmod 2775 {} \;
    find "$PROJECT_ROOT_DIR/plugin-repos" -type f -exec chmod 664 {} \;
fi

echo "✓ File ownership configured"
echo ""

CURRENT_STEP="Normalize project file permissions"
echo "Step 11.1: Normalizing project file and directory permissions..."
echo "--------------------------------------------------------------"

# Normalize directory permissions (exclude VCS metadata, plugin directories, and compiled libraries)
find "$PROJECT_ROOT_DIR" \
    -path "$PROJECT_ROOT_DIR/plugins" -prune -o \
    -path "$PROJECT_ROOT_DIR/plugin-repos" -prune -o \
    -path "$PROJECT_ROOT_DIR/scripts/dev/plugins" -prune -o \
    -path "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" -prune -o \
    -path "*/.git*" -prune -o \
    -type d -exec chmod 755 {} \; 2>/dev/null || true

# Set default file permissions (exclude plugin directories and compiled libraries)
find "$PROJECT_ROOT_DIR" \
    -path "$PROJECT_ROOT_DIR/plugins" -prune -o \
    -path "$PROJECT_ROOT_DIR/plugin-repos" -prune -o \
    -path "$PROJECT_ROOT_DIR/scripts/dev/plugins" -prune -o \
    -path "$PROJECT_ROOT_DIR/rpi-rgb-led-matrix-master" -prune -o \
    -path "*/.git*" -prune -o \
    -type f -exec chmod 644 {} \; 2>/dev/null || true

# Ensure shell scripts are executable
find "$PROJECT_ROOT_DIR" -path "*/.git*" -prune -o -type f -name "*.sh" -exec chmod 755 {} \; 2>/dev/null || true

# Explicitly ensure common helper scripts are executable (in case paths change)
chmod 755 "$PROJECT_ROOT_DIR/start_display.sh" "$PROJECT_ROOT_DIR/stop_display.sh" 2>/dev/null || true
chmod 755 "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_cache_permissions.sh" "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_web_permissions.sh" "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_assets_permissions.sh" "$PROJECT_ROOT_DIR/scripts/fix_perms/fix_plugin_permissions.sh" 2>/dev/null || true
chmod 755 "$PROJECT_ROOT_DIR/scripts/install/install_service.sh" "$PROJECT_ROOT_DIR/scripts/install/install_web_service.sh" 2>/dev/null || true

# Re-apply special permissions for config directory (lost during normalization)
chmod 2775 "$PROJECT_ROOT_DIR/config" || true

# Harden the sudo-granted helper scripts: root-owned, not writable by the web
# user (matches scripts/install/configure_web_sudo.sh). The sudoers rules in
# Step 10 run these as root, so a user-owned copy is a root shell for whoever
# can edit it. This must come after Step 11's project-wide chown to
# $ACTUAL_USER, which would otherwise hand them straight back.
for helper in safe_plugin_rm.sh safe_pip_install.sh; do
    HELPER_PATH="$PROJECT_ROOT_DIR/scripts/fix_perms/$helper"
    if [ -f "$HELPER_PATH" ]; then
        chown root:root "$HELPER_PATH" || echo "⚠ Could not set ownership on $HELPER_PATH"
        chmod 755 "$HELPER_PATH" || echo "⚠ Could not set permissions on $HELPER_PATH"
    fi
done

echo "✓ Project file permissions normalized"
echo ""

CURRENT_STEP="Sound module configuration"
echo "Step 12: Sound module configuration..."
echo "-------------------------------------"

# Remove services that may interfere with LED matrix timing
echo "Removing potential conflicting services (bluetooth and others)..."
if [ "$SKIP_SOUND" = "1" ]; then
    echo "Skipping sound module configuration as requested (--skip-sound)."
else
    # apt_remove never fails (it ends in `|| true`); apt itself reports any
    # package it could not remove.
    apt_remove bluez bluez-firmware pi-bluetooth triggerhappy pigpio
    echo "✓ Unnecessary services removed (or not present)"
fi

# Blacklist onboard sound module (idempotent)
BLACKLIST_FILE="/etc/modprobe.d/blacklist-rgb-matrix.conf"
if [ -f "$BLACKLIST_FILE" ] && grep -q '^blacklist snd_bcm2835\b' "$BLACKLIST_FILE"; then
    echo "snd_bcm2835 already blacklisted in $BLACKLIST_FILE"
else
    echo "Ensuring snd_bcm2835 is blacklisted in $BLACKLIST_FILE..."
    mkdir -p "/etc/modprobe.d"
    if [ -f "$BLACKLIST_FILE" ]; then
        cp "$BLACKLIST_FILE" "$BLACKLIST_FILE.bak" 2>/dev/null || true
    fi
    # Append once (don't clobber existing unrelated content)
    if [ -f "$BLACKLIST_FILE" ]; then
        echo "blacklist snd_bcm2835" >> "$BLACKLIST_FILE"
    else
        printf "blacklist snd_bcm2835\n" > "$BLACKLIST_FILE"
    fi
fi

# Update initramfs if available
if command -v update-initramfs >/dev/null 2>&1; then
    echo "Updating initramfs..."
    update-initramfs -u
else
    echo "update-initramfs not found; skipping"
fi

echo "✓ Sound module configuration applied"
echo ""

CURRENT_STEP="Apply performance optimizations"
echo "Step 13: Applying performance optimizations..."
echo "---------------------------------------------"

# Prefer /boot/firmware on newer Raspberry Pi OS, fall back to /boot on older
CMDLINE_FILE="/boot/firmware/cmdline.txt"
CONFIG_FILE="/boot/firmware/config.txt"
if [ ! -f "$CMDLINE_FILE" ]; then CMDLINE_FILE="/boot/cmdline.txt"; fi
if [ ! -f "$CONFIG_FILE" ]; then CONFIG_FILE="/boot/config.txt"; fi

# Append isolcpus=3 to cmdline if not present (idempotent)
if [ "$SKIP_PERF" = "1" ]; then
    echo "Skipping performance optimizations as requested (--skip-perf)."
elif [ -f "$CMDLINE_FILE" ]; then
    if grep -q '\bisolcpus=3\b' "$CMDLINE_FILE"; then
        echo "isolcpus=3 already present in $CMDLINE_FILE"
    else
        echo "Adding isolcpus=3 to $CMDLINE_FILE..."
        cp "$CMDLINE_FILE" "$CMDLINE_FILE.bak" 2>/dev/null || true
        # Ensure single-line cmdline gets the flag once, with a leading space
        sed -i '1 s/$/ isolcpus=3/' "$CMDLINE_FILE"
    fi
else
    echo "✗ $CMDLINE_FILE not found; skipping isolcpus optimization"
fi

# Enable the memory cgroup controller (idempotent).
# The Pi firmware boots with cgroup_disable=memory, so systemd's MemoryMax= is
# accepted and silently ignored — the display service then has no ceiling, and
# a runaway takes the whole board down (sshd can no longer fork, the panel goes
# dark) rather than just restarting the one service.
if [ "$SKIP_PERF" != "1" ] && [ -f "$CMDLINE_FILE" ]; then
    # Both parameters are required for the memory controller, and they can get
    # separated -- an image, another tool or a half-applied earlier run can
    # leave one without the other. Checking only cgroup_enable=memory would
    # report success while MemoryMax= silently does nothing, so each is checked
    # and appended independently.
    cgroup_missing=""
    for cgroup_param in cgroup_enable=memory cgroup_memory=1; do
        if ! grep -qw "$cgroup_param" "$CMDLINE_FILE"; then
            cgroup_missing="$cgroup_missing $cgroup_param"
        fi
    done
    if [ -z "$cgroup_missing" ]; then
        echo "cgroup memory parameters already present in $CMDLINE_FILE"
    else
        echo "Adding${cgroup_missing} to $CMDLINE_FILE..."
        cp "$CMDLINE_FILE" "$CMDLINE_FILE.bak" 2>/dev/null || true
        # The kernel command line must stay on one line.
        sed -i "1 s|\$|${cgroup_missing}|" "$CMDLINE_FILE"
        echo "  Takes effect after reboot. Verify with:"
        echo "    grep memory /sys/fs/cgroup/cgroup.controllers"
    fi
fi

# Persist the journal (idempotent).
# These images default to volatile storage: journald keeps everything in /run
# (tmpfs), so every reboot destroys the logs — including the ones that would
# explain why the board rebooted. Capped so an SD card is not worn out by logs.
# A non-empty /var/log/journal does not prove journald is configured the way
# this needs: the directory survives a switch back to volatile storage, and it
# says nothing about whether a size cap is set. Read the effective
# configuration instead, and only write the keys the user has not set
# themselves so an explicit local limit is preserved.
journald_effective() {
    # systemd-analyze merges journald.conf with every drop-in; grep is the
    # fallback for images that ship without it.
    if command -v systemd-analyze >/dev/null 2>&1 &&
       systemd-analyze cat-config systemd/journald.conf >/dev/null 2>&1; then
        systemd-analyze cat-config systemd/journald.conf 2>/dev/null
    else
        cat /etc/systemd/journald.conf /etc/systemd/journald.conf.d/*.conf 2>/dev/null || true
    fi
}
journald_conf="$(journald_effective)"
# Both settings are optional, and stock images ship them commented out. grep
# exits 1 on no match, which pipefail turns fatal under set -e — an absent
# setting must read as empty, not abort the install.
journald_storage="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]' || true)"
journald_cap="$(printf '%s\n' "$journald_conf" | grep -E '^[[:space:]]*SystemMaxUse=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]' || true)"

if [ "$journald_storage" = "persistent" ] && [ -n "$journald_cap" ]; then
    echo "Persistent journald storage already configured (SystemMaxUse=$journald_cap)"
else
    echo "Enabling persistent journald storage..."
    mkdir -p /etc/systemd/journald.conf.d
    {
        echo "# Installed by LEDMatrix first_time_install.sh"
        echo "[Journal]"
        echo "Storage=persistent"
        if [ -n "$journald_cap" ]; then
            echo "# SystemMaxUse left to your existing setting ($journald_cap)"
        else
            # Capped so logs cannot wear out or fill an SD card.
            echo "SystemMaxUse=64M"
        fi
    } > /etc/systemd/journald.conf.d/ledmatrix-persistent.conf
    mkdir -p /var/log/journal
    systemd-tmpfiles --create --prefix /var/log/journal >/dev/null 2>&1 || true
    systemctl restart systemd-journald >/dev/null 2>&1 || true

    # Drop-ins are applied in lexical order, so a locally added file that sorts
    # after ledmatrix-persistent.conf (zz-local.conf and friends) still wins.
    # Writing the file is not evidence it took effect -- re-read and say so
    # plainly rather than reporting success we cannot confirm.
    journald_now="$(journald_effective | grep -E '^[[:space:]]*Storage=' | tail -n1 | cut -d= -f2 | tr -d '[:space:]' || true)"
    if [ "$journald_now" = "persistent" ]; then
        echo "  Persistent journald storage active"
    else
        echo "  WARNING: journald storage is still '${journald_now:-unset}' after"
        echo "  writing /etc/systemd/journald.conf.d/ledmatrix-persistent.conf."
        echo "  Another drop-in that sorts later is overriding it. Check:"
        echo "    systemd-analyze cat-config systemd/journald.conf | grep -n Storage="
        echo "  Logs will not survive a reboot until that is resolved."
    fi
fi

# Ensure dtparam=audio=off in config.txt (idempotent)
if [ "$SKIP_PERF" = "1" ]; then
    : # skipped
elif [ -f "$CONFIG_FILE" ]; then
    if grep -q '^dtparam=audio=off\b' "$CONFIG_FILE"; then
        echo "Onboard audio already disabled in $CONFIG_FILE"
    elif grep -q '^dtparam=audio=on\b' "$CONFIG_FILE"; then
        echo "Disabling onboard audio in $CONFIG_FILE..."
        cp "$CONFIG_FILE" "$CONFIG_FILE.bak" 2>/dev/null || true
        sed -i 's/^dtparam=audio=on\b/dtparam=audio=off/' "$CONFIG_FILE"
    else
        echo "Adding dtparam=audio=off to $CONFIG_FILE..."
        cp "$CONFIG_FILE" "$CONFIG_FILE.bak" 2>/dev/null || true
        printf "\n# Disable onboard audio for LED matrix performance\n" >> "$CONFIG_FILE"
        echo "dtparam=audio=off" >> "$CONFIG_FILE"
    fi
else
    echo "✗ $CONFIG_FILE not found; skipping audio disable"
fi

echo "✓ Performance optimizations applied"
echo ""

CURRENT_STEP="Test the installation"
echo "Step 14: Testing the installation..."
echo "----------------------------------"

# Test sudo access
echo "Testing sudo access..."
if sudo -u "$ACTUAL_USER" sudo -n systemctl status ledmatrix.service > /dev/null 2>&1; then
    echo "✓ Sudo access test passed"
else
    echo "⚠ Sudo access test failed - may need to log out and back in"
fi

# Test journal access
echo "Testing journal access..."
if sudo -u "$ACTUAL_USER" journalctl --no-pager --lines=1 > /dev/null 2>&1; then
    echo "✓ Journal access test passed"
else
    echo "⚠ Journal access test failed - may need to log out and back in"
fi

# Check service status
echo "Checking service status..."
if systemctl is-active --quiet ledmatrix.service; then
    echo "✓ Main LED Matrix service is running"
else
    echo "⚠ Main LED Matrix service is not running"
fi

if systemctl is-active --quiet ledmatrix-web.service; then
    echo "✓ Web interface service is running"
else
    echo "⚠ Web interface service is not running"
fi

if systemctl list-unit-files | grep -q "ledmatrix-wifi-monitor.service"; then
    if systemctl is-active --quiet ledmatrix-wifi-monitor.service 2>/dev/null; then
        echo "✓ WiFi monitor service is running"
    else
        echo "⚠ WiFi monitor service is not running"
    fi
fi

echo ""
echo "=========================================="
echo "Installation Complete!"
echo "=========================================="
echo ""

# Network Diagnostics Section
echo "=========================================="
echo "Network Status & Access Information"
echo "=========================================="
echo ""

# Get current IP addresses
echo "Current IP Addresses:"
if command -v hostname >/dev/null 2>&1; then
    # Get IP addresses and filter out empty lines
    IPS=$(hostname -I 2>/dev/null || echo "")
    if [ -n "$IPS" ]; then
            # Use a more reliable method to process IPs
            FOUND_IPS=0
            for ip in $IPS; do
                # Filter out loopback, empty strings, and IPv6 link-local addresses (fe80:)
                if [ -n "$ip" ] && [ "$ip" != "127.0.0.1" ] && [ "$ip" != "::1" ] && ! [[ "$ip" =~ ^fe80: ]]; then
                    echo "  - $ip"
                    FOUND_IPS=1
                fi
            done
        if [ "$FOUND_IPS" -eq 0 ]; then
            echo "  ⚠ No non-loopback IP addresses found"
        fi
    else
        echo "  ⚠ No IP addresses found"
    fi
else
    echo "  ⚠ Could not determine IP addresses (hostname command not available)"
fi

echo ""

# Check WiFi status
echo "WiFi Connection Status:"
if command -v nmcli >/dev/null 2>&1; then
    WIFI_STATUS=$(nmcli -t -f DEVICE,TYPE,STATE device status 2>/dev/null | grep -i wifi || echo "")
    if [ -n "$WIFI_STATUS" ]; then
        echo "$WIFI_STATUS" | while IFS=':' read -r _ _ state; do
            if [ "$state" = "connected" ]; then
                SSID=$(nmcli -t -f active,ssid device wifi 2>/dev/null | grep "^yes:" | cut -d: -f2 | head -1 || true)
                if [ -n "$SSID" ]; then
                    echo "  ✓ Connected to: $SSID"
                else
                    echo "  ✓ Connected (SSID unknown)"
                fi
            else
                echo "  ✗ Not connected ($state)"
            fi
        done
    else
        echo "  ⚠ Could not determine WiFi status"
    fi
else
    echo "  ⚠ nmcli not available, cannot check WiFi status"
fi

echo ""

# Check AP mode status
echo "AP Mode Status:"
if systemctl is-active --quiet hostapd 2>/dev/null; then
    echo "  ✓ AP Mode is ACTIVE"
    echo "  → Connect to WiFi network: LEDMatrix-Setup"
    echo "  → Open network, no password"
    echo "  → Access web UI at: http://192.168.4.1:5000"
    AP_MODE_ACTIVE=true
else
    # Check if wlan0 has AP IP
    if ip addr show wlan0 2>/dev/null | grep -q "192.168.4.1"; then
        echo "  ✓ AP Mode is ACTIVE (IP detected)"
        echo "  → Connect to WiFi network: LEDMatrix-Setup"
        echo "  → Open network, no password"
        echo "  → Access web UI at: http://192.168.4.1:5000"
        AP_MODE_ACTIVE=true
    else
        echo "  ✗ AP Mode is inactive"
        AP_MODE_ACTIVE=false
    fi
fi

echo ""

# Web UI access information
echo "Web UI Access:"
if [ "$AP_MODE_ACTIVE" = true ]; then
    echo "  → Via AP Mode: http://192.168.4.1:5000"
    echo ""
    echo "  To connect to your WiFi network:"
    echo "  1. Connect to LEDMatrix-Setup network"
    echo "  2. Open http://192.168.4.1:5000 in your browser"
    echo "  3. Go to WiFi tab and connect to your network"
else
    # Get primary IP for web UI access
    PRIMARY_IP=""
    if command -v hostname >/dev/null 2>&1; then
        PRIMARY_IP=$(hostname -I 2>/dev/null | awk '{print $1}' | grep -v '^$' || echo "")
    fi
    
    if [ -n "$PRIMARY_IP" ] && [ "$PRIMARY_IP" != "127.0.0.1" ] && [ "$PRIMARY_IP" != "192.168.4.1" ]; then
        echo "  → Access at: http://$PRIMARY_IP:5000"
    else
        echo "  → Access at: http://<your-pi-ip>:5000"
        echo "    (Replace <your-pi-ip> with your Pi's IP address)"
    fi
    
    if systemctl is-active --quiet ledmatrix-web.service 2>/dev/null; then
        echo "  ✓ Web service is running"
    else
        echo "  ⚠ Web service is not running"
        echo "    Start with: sudo systemctl start ledmatrix-web"
    fi
fi

echo ""

# Service status summary
echo "Service Status:"
if systemctl is-active --quiet ledmatrix.service 2>/dev/null; then
    echo "  ✓ Main display service: running"
else
    echo "  ✗ Main display service: not running"
fi

if systemctl is-active --quiet ledmatrix-web.service 2>/dev/null; then
    echo "  ✓ Web interface service: running"
else
    echo "  ✗ Web interface service: not running"
fi

if systemctl list-unit-files | grep -q "ledmatrix-wifi-monitor.service"; then
    if systemctl is-active --quiet ledmatrix-wifi-monitor.service 2>/dev/null; then
        echo "  ✓ WiFi monitor service: running"
    else
        echo "  ⚠ WiFi monitor service: installed but not running"
    fi
else
    echo "  - WiFi monitor service: not installed"
fi

echo ""
echo "=========================================="
echo "Important Notes"
echo "=========================================="
echo ""
echo "1. PLEASE BE PATIENT after reboot!"
echo "   - The web interface may take up to 5 minutes to start on first boot"
echo "   - Services need time to initialize after installation"
echo "   - Wait at least 2-3 minutes before checking service status"
echo ""
echo "2. For group changes to take effect:"
echo "   - Log out and log back in to your SSH session, OR"
echo "   - Run: newgrp systemd-journal"
echo ""
echo "3. If you cannot access the web UI:"
echo "   - Check that the web service is running: sudo systemctl status ledmatrix-web"
echo "   - Verify firewall allows port 5000: sudo ufw status (if using UFW)"
echo "   - Check network connectivity: ping -c 3 8.8.8.8"
echo "   - If WiFi is not connected, connect to LEDMatrix-Setup AP network"
echo ""
echo "4. SSH Access:"
echo "   - SSH must be configured during initial Pi setup (via Raspberry Pi Imager or raspi-config)"
echo "   - This installation script does not configure SSH credentials"
echo ""
echo "5. Useful Commands:"
echo "   - Check service status: sudo systemctl status ledmatrix.service"
echo "   - View logs: journalctl -u ledmatrix-web.service -f"
echo "   - Start/stop display: sudo systemctl start/stop ledmatrix.service"
echo ""
echo "6. Configuration Files:"
echo "   - Main config: $PROJECT_ROOT_DIR/config/config.json"
echo "   - Secrets: $PROJECT_ROOT_DIR/config/config_secrets.json"
echo ""
echo "Enjoy your LED Matrix display!"

# Reboot last. It used to come before the summary above, so with -y (and
# the one-shot installer, which always passes -y) the reboot was already
# under way while the summary printed, and the SSH session usually dropped
# before any of it -- the web UI address included -- could be read.
echo ""
if [ "$SKIP_REBOOT_PROMPT" = "1" ]; then
    echo "Skipping reboot prompt as requested (--no-reboot-prompt)."
elif [ "$ASSUME_YES" = "1" ]; then
    echo "Non-interactive mode: rebooting now to apply changes..."
    reboot
else
    read -p "A reboot is recommended to apply kernel and audio changes. Reboot now? (y/N): " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        echo "Rebooting now..."
        reboot
    fi
fi