menu.func

#!/usr/bin/env bash
# Copyright (c) 2021-2026 community-scripts ORG
# License: MIT | https://raw.githubusercontent.com/community-scripts/core/main/LICENSE

# ==============================================================================
# BUILD-UI/MENU.FUNC - MENUS, DIAGNOSTICS AND ENTRY POINTS
# ==============================================================================
# Part of the build UI. Load ui/build-ui.func -- it sources every part --
# rather than this file directly; the split is for maintenance only and no
# function name or behaviour changed with it.
# ==============================================================================

[[ -n "${_BUILD_UI_MENU_LOADED:-}" ]] && return 0
_BUILD_UI_MENU_LOADED=1

# ==============================================================================
# SECTION 7: USER INTERFACE & DIAGNOSTICS
# ==============================================================================

# ------------------------------------------------------------------------------
# diagnostics_check()
#
# - Ensures diagnostics config file exists at /usr/local/community-scripts/diagnostics
# - Asks user whether to send anonymous diagnostic data
# - Saves DIAGNOSTICS=yes/no in the config file
# - Creates file if missing with default DIAGNOSTICS=yes
# - Reads current diagnostics setting from file
# - Sets global DIAGNOSTICS variable for API telemetry opt-in/out
# ------------------------------------------------------------------------------
diagnostics_check() {
  local _cs_dir _diag_file
  _cs_dir="$(declare -f community_scripts_dir >/dev/null 2>&1 && community_scripts_dir || echo /usr/local/community-scripts)"
  _diag_file="${_cs_dir}/diagnostics"
  if ! [ -d "$_cs_dir" ]; then
    mkdir -p "$_cs_dir"
  fi

  if ! [ -f "$_diag_file" ]; then
    if (whiptail --backtitle "Proxmox VE Helper Scripts" --title "DIAGNOSTICS" --yesno "Send Diagnostics of LXC Installation?\n\n(This only transmits data without user data, just RAM, CPU, LXC name, ...)" 10 58); then
      cat <<EOF >"$_diag_file"
DIAGNOSTICS=yes

#This file is used to store the diagnostics settings for the Community-Scripts API.
#https://github.com/community-scripts/ProxmoxVE/discussions/1836
#Your diagnostics will be sent to the Community-Scripts API for troubleshooting/statistical purposes.
#You can review the data at https://community-scripts.org/analytics
#If you do not wish to send diagnostics, please set the variable 'DIAGNOSTICS' to "no" in ${_diag_file}, or use the menue.
#This will disable the diagnostics feature.
#To send diagnostics, set the variable 'DIAGNOSTICS' to "yes" in ${_diag_file}, or use the menue.
#This will enable the diagnostics feature.
#The following information will be sent:
#"disk_size"
#"core_count"
#"ram_size"
#"os_type"
#"os_version"
#"nsapp"
#"method"
#"pve_version"
#"status"
#If you have any concerns, please review the source code at core/core/build.func
EOF
      DIAGNOSTICS="yes"
    else
      cat <<EOF >"$_diag_file"
DIAGNOSTICS=no

#This file is used to store the diagnostics settings for the Community-Scripts API.
#https://github.com/community-scripts/ProxmoxVE/discussions/1836
#Your diagnostics will be sent to the Community-Scripts API for troubleshooting/statistical purposes.
#You can review the data at https://community-scripts.org/analytics
#If you do not wish to send diagnostics, please set the variable 'DIAGNOSTICS' to "no" in ${_diag_file}, or use the menue.
#This will disable the diagnostics feature.
#To send diagnostics, set the variable 'DIAGNOSTICS' to "yes" in ${_diag_file}, or use the menue.
#This will enable the diagnostics feature.
#The following information will be sent:
#"disk_size"
#"core_count"
#"ram_size"
#"os_type"
#"os_version"
#"nsapp"
#"method"
#"pve_version"
#"status"
#If you have any concerns, please review the source code at core/core/build.func
EOF
      DIAGNOSTICS="no"
    fi
  else
    DIAGNOSTICS=$(awk -F '=' '/^DIAGNOSTICS/ {print $2}' "$_diag_file")

  fi
}

diagnostics_menu() {
  local _diag_file
  _diag_file="$(declare -f community_scripts_dir >/dev/null 2>&1 && community_scripts_dir || echo /usr/local/community-scripts)/diagnostics"
  if [ "${DIAGNOSTICS:-no}" = "yes" ]; then
    if whiptail --backtitle "Proxmox VE Helper Scripts" \
      --title "DIAGNOSTIC SETTINGS" \
      --yesno "Send Diagnostics?\n\nCurrent: ${DIAGNOSTICS}" 10 58 \
      --yes-button "No" --no-button "Back"; then
      DIAGNOSTICS="no"
      sed -i 's/^DIAGNOSTICS=.*/DIAGNOSTICS=no/' "$_diag_file"
      whiptail --msgbox "Diagnostics set to ${DIAGNOSTICS}." 8 58
    fi
  else
    if whiptail --backtitle "Proxmox VE Helper Scripts" \
      --title "DIAGNOSTIC SETTINGS" \
      --yesno "Send Diagnostics?\n\nCurrent: ${DIAGNOSTICS}" 10 58 \
      --yes-button "Yes" --no-button "Back"; then
      DIAGNOSTICS="yes"
      sed -i 's/^DIAGNOSTICS=.*/DIAGNOSTICS=yes/' "$_diag_file"
      whiptail --msgbox "Diagnostics set to ${DIAGNOSTICS}." 8 58
    fi
  fi
}

# ------------------------------------------------------------------------------
# echo_default()
#
# - Prints summary of default values (ID, OS, type, disk, RAM, CPU, etc.)
# - Uses icons and formatting for readability
# - Convert CT_TYPE to description
# ------------------------------------------------------------------------------
echo_default() {
  CT_TYPE_DESC="Unprivileged"
  if [ "$CT_TYPE" -eq 0 ]; then
    CT_TYPE_DESC="Privileged"
  fi
  echo -e "${INFO}${BOLD}${DGN}$(_cs_host_version_line) (Kernel: ${KERNEL_VERSION})${CL}"
  local engine_ref scripts_ref
  engine_ref="$(_cs_engine_ref_line)"
  scripts_ref="$(_cs_scripts_ref_line)"
  [[ -n "$engine_ref" ]] && echo -e "${OVERRIDE}${BOLD}${YWB}${engine_ref}${CL}"
  [[ -n "$scripts_ref" ]] && echo -e "${OVERRIDE}${BOLD}${YWB}${scripts_ref}${CL}"
  echo -e "${CONTAINERID}${BOLD}${DGN}Container ID: ${BGN}${CT_ID}${CL}"
  echo -e "${OS}${BOLD}${DGN}Operating System: ${BGN}$var_os ($var_version)${CL}"
  echo -e "${CONTAINERTYPE}${BOLD}${DGN}Container Type: ${BGN}$CT_TYPE_DESC${CL}"
  echo -e "${DISKSIZE}${BOLD}${DGN}Disk Size: ${BGN}${DISK_SIZE} GB${CL}"
  echo -e "${CPUCORE}${BOLD}${DGN}CPU Cores: ${BGN}${CORE_COUNT}${CL}"
  echo -e "${RAMSIZE}${BOLD}${DGN}RAM Size: ${BGN}${RAM_SIZE} MiB${CL}"
  if [[ "$(_cs_host_arch)" == "arm64" ]]; then
    echo -e "${INFO}${BOLD}${DGN}Architecture: ${BGN}arm64${CL}"
  fi
  if [[ -n "${var_gpu:-}" && "${var_gpu}" == "yes" ]]; then
    # Say what will actually happen. A host with no DRM or NVIDIA nodes - an
    # arm64 board, say - has nothing to pass through, and announcing "Enabled"
    # only to report "no GPU devices found" later reads like a failure.
    if compgen -G '/dev/dri/*' >/dev/null 2>&1 || compgen -G '/dev/nvidia*' >/dev/null 2>&1; then
      echo -e "${GPU}${BOLD}${DGN}GPU Passthrough: ${BGN}Enabled${CL}"
    else
      echo -e "${GPU}${BOLD}${DGN}GPU Passthrough: ${BGN}Requested - no GPU devices on this host${CL}"
    fi
  fi
  if [ "$VERBOSE" == "yes" ]; then
    echo -e "${SEARCH}${BOLD}${DGN}Verbose Mode: ${BGN}Enabled${CL}"
  fi
  echo -e "${CREATING}${BOLD}${BL}Creating a ${APP} LXC using the above default settings${CL}"
  echo -e "  "

  # Log settings to file
  log_section "CONTAINER SETTINGS - ${APP}"
  log_msg "Application: ${APP}"
  log_msg "$(_cs_host_version_line) (Kernel: ${KERNEL_VERSION})"
  [[ -n "$engine_ref" ]] && log_msg "$engine_ref"
  [[ -n "$scripts_ref" ]] && log_msg "$scripts_ref"
  log_msg "Container ID: ${CT_ID}"
  log_msg "Operating System: $var_os ($var_version)"
  log_msg "Container Type: $CT_TYPE_DESC"
  log_msg "Disk Size: ${DISK_SIZE} GB"
  log_msg "CPU Cores: ${CORE_COUNT}"
  log_msg "RAM Size: ${RAM_SIZE} MiB"
  [[ -n "${var_gpu:-}" && "${var_gpu}" == "yes" ]] && log_msg "GPU Passthrough: Enabled"
  [[ "$VERBOSE" == "yes" ]] && log_msg "Verbose Mode: Enabled"
  log_msg "Session ID: ${SESSION_ID}"
}

# ------------------------------------------------------------------------------
# install_script()
#
# - Main entrypoint for installation mode
# - Runs safety checks (pve_check, root_check, diagnostics_check, run_preflight)
# - Builds interactive menu (Default, Verbose, Advanced, My Defaults, App Defaults, Diagnostics, Storage, Exit)
# - Applies chosen settings and triggers container build
# ------------------------------------------------------------------------------
install_script() {
  # pvesh spawns a Perl client and waits on pvedaemon — the slowest thing here
  # by far, and it needs nothing the checks below produce. Start it now and
  # collect it when it is actually needed, so it runs while they do.
  # core/build.func usually started it at load already (_cs_start_host_probes).
  local _nextid_file="" _nextid_pid=""
  if ! declare -f get_next_container_identifier &>/dev/null && [[ ! -f "${CS_PROBE_DIR:-/nonexistent}/nextid.out" ]] &&
    command -v pvesh &>/dev/null; then
    _nextid_file="$(mktemp 2>/dev/null)" || _nextid_file=""
    if [[ -n "$_nextid_file" ]]; then
      pvesh get /cluster/nextid >"$_nextid_file" 2>/dev/null &
      _nextid_pid=$!
    fi
  fi

  # Root first: for any other user /etc/pve/storage.cfg is unreadable, and the
  # cluster check in pve_check took that for a damaged cluster.
  shell_check
  root_check
  pve_check
  ensure_whiptail
  arch_check
  arm64_notice
  ssh_check
  maxkeys_check
  storage_content_check
  diagnostics_check

  if command -v systemctl >/dev/null 2>&1 && systemctl is-active -q ping-instances.service; then
    systemctl -q stop ping-instances.service
  fi

  if declare -f get_next_container_identifier &>/dev/null; then
    NEXTID="$(get_next_container_identifier)"
  elif NEXTID="$(_cs_probe_read nextid | tr -d '[:space:]')" && [[ -n "$NEXTID" ]]; then
    :
  elif [[ -n "$_nextid_pid" ]]; then
    wait "$_nextid_pid" 2>/dev/null || true
    NEXTID="$(tr -d '[:space:]' <"$_nextid_file" 2>/dev/null)"
    rm -f "$_nextid_file"
    # A backgrounded call that came back empty is not a reason to continue with
    # an empty CTID; ask again in the foreground so the error is the real one.
    [[ -z "$NEXTID" ]] && NEXTID=$(pvesh get /cluster/nextid)
  else
    NEXTID=$(pvesh get /cluster/nextid)
  fi

  # Get timezone using timedatectl (Debian 13+ compatible)
  # Fallback to /etc/timezone for older systems
  if command -v timedatectl >/dev/null 2>&1; then
    timezone=$(timedatectl show --value --property=Timezone 2>/dev/null || echo "UTC")
  elif [ -f /etc/timezone ]; then
    timezone=$(cat /etc/timezone)
  else
    timezone="UTC"
  fi
  [[ "${timezone:-}" == Etc/* ]] && timezone="host" # pct doesn't accept Etc/* zones

  # dev_mode set without naming flags means "ask": the picker comes before the
  # install menu rather than being buried in Settings, and the palette turns
  # red as soon as something is selected.
  if [[ "${_DEV_MODE_ASK:-0}" == "1" ]] && declare -f dev_mode_menu >/dev/null 2>&1; then
    dev_mode_menu
    color
  fi

  # Show APP Header + run preflight checks
  header_info
  run_preflight

  # --- Support CLI argument as direct preset (default, advanced, …) ---
  CHOICE="${mode:-${1:-}}"

  # If no CLI argument → show whiptail menu
  # Build menu dynamically based on available options
  local appdefaults_option=""
  local settings_option=""
  local menu_items=(
    "1" "Default Install"
    "2" "Advanced Install"
    "3" "User Defaults"
  )

  if [ -f "$(get_app_defaults_path)" ]; then
    appdefaults_option="4"
    menu_items+=("4" "App Defaults for ${APP}")
    settings_option="5"
    menu_items+=("5" "Settings")
  else
    settings_option="4"
    menu_items+=("4" "Settings")
  fi

  APPDEFAULTS_OPTION="$appdefaults_option"
  SETTINGS_OPTION="$settings_option"

  # Main menu loop - allows returning from Settings
  while true; do
    if [ -z "$CHOICE" ]; then
      TMP_CHOICE=$(whiptail \
        --backtitle "Proxmox VE Helper Scripts" \
        --title "Community-Scripts Options" \
        --ok-button "Select" --cancel-button "Exit Script" \
        --notags \
        --menu "\nChoose an option:\n Use TAB or Arrow keys to navigate, ENTER to select.\n" \
        20 60 9 \
        "${menu_items[@]}" \
        --default-item "1" \
        3>&1 1>&2 2>&3) || exit_script
      CHOICE="$TMP_CHOICE"
    fi

    # --- Main case ---
    local defaults_target=""
    local run_maybe_offer="no"
    case "$CHOICE" in
    1 | default | DEFAULT)
      header_info
      echo -e "${DEFAULT}${BOLD}${BL}Using Default Settings on node $PVEHOST_NAME${CL}"
      VERBOSE="no"
      METHOD="default"
      base_settings "$VERBOSE"
      echo_default
      defaults_target="$(ensure_global_default_vars_file)"
      break
      ;;
    2 | advanced | ADVANCED)
      header_info
      echo -e "${ADVANCED}${BOLD}${RD}Using Advanced Install on node $PVEHOST_NAME${CL}"
      METHOD="advanced"
      base_settings
      advanced_settings
      defaults_target="$(ensure_global_default_vars_file)"
      run_maybe_offer="yes"
      break
      ;;
    3 | mydefaults | MYDEFAULTS | userdefaults | USERDEFAULTS)
      default_var_settings || {
        msg_error "Failed to apply default.vars"
        exit 1
      }
      defaults_target="$(declare -f community_scripts_dir >/dev/null 2>&1 && community_scripts_dir || echo /usr/local/community-scripts)/default.vars"
      break
      ;;
    "$APPDEFAULTS_OPTION" | appdefaults | APPDEFAULTS)
      if [ -f "$(get_app_defaults_path)" ]; then
        header_info
        echo -e "${DEFAULT}${BOLD}${BL}Using App Defaults for ${APP} on node $PVEHOST_NAME${CL}"
        METHOD="appdefaults"
        load_vars_file "$(get_app_defaults_path)" "yes" # Force override script defaults
        base_settings
        echo_default
        defaults_target="$(get_app_defaults_path)"
        break
      else
        msg_error "No App Defaults available for ${APP}"
        exit 1
      fi
      ;;
    "$SETTINGS_OPTION" | settings | SETTINGS)
      settings_menu
      # After settings menu, show main menu again
      header_info
      CHOICE=""
      ;;
    generated | GENERATED)
      header_info
      echo -e "${DEFAULT}${BOLD}${BL}Using Generated Settings on node $PVEHOST_NAME${CL}"
      VERBOSE="no"
      METHOD="generated"
      base_settings "$VERBOSE"
      echo_default
      break
      ;;
    *)
      echo -e "${CROSS}${RD}Invalid option: $CHOICE${CL}"
      exit 1
      ;;
    esac
  done

  if [[ -n "$defaults_target" ]]; then
    ensure_storage_selection_for_vars_file "$defaults_target"
  fi

  if [[ "$run_maybe_offer" == "yes" ]]; then
    maybe_offer_save_app_defaults
  fi
}

edit_default_storage() {
  local vf
  vf="$(declare -f community_scripts_dir >/dev/null 2>&1 && community_scripts_dir || echo /usr/local/community-scripts)/default.vars"

  # Ensure file exists
  if [[ ! -f "$vf" ]]; then
    mkdir -p "$(dirname "$vf")" 2>/dev/null || true
    touch "$vf" 2>/dev/null || true
  fi

  # Let ensure_storage_selection_for_vars_file handle everything
  ensure_storage_selection_for_vars_file "$vf"
}

settings_menu() {
  while true; do
    local settings_items=(
      "1" "Manage API-Diagnostic Setting"
      "2" "Edit Default.vars"
      "3" "Configure dev mode"
    )
    if [ -f "$(get_app_defaults_path)" ]; then
      settings_items+=("4" "Edit App.vars for ${APP}")
      settings_items+=("5" "Back to Main Menu")
    else
      settings_items+=("4" "Back to Main Menu")
    fi

    local choice
    choice=$(whiptail --backtitle "Proxmox VE Helper Scripts" \
      --title "Community-Scripts SETTINGS Menu" \
      --ok-button "Select" --cancel-button "Exit Script" \
      --menu "\n\nChoose a settings option:\n\nUse Arrow keys to navigate, ENTER to select, TAB for buttons." 20 60 9 \
      "${settings_items[@]}" \
      3>&1 1>&2 2>&3) || exit_script

    case "$choice" in
    1) diagnostics_menu ;;
    2) nano "$(declare -f community_scripts_dir >/dev/null 2>&1 && community_scripts_dir || echo /usr/local/community-scripts)/default.vars" ;;
    3) dev_mode_menu ;;
    4)
      if [ -f "$(get_app_defaults_path)" ]; then
        nano "$(get_app_defaults_path)"
      else
        # Back was selected (no app.vars available)
        return
      fi
      ;;
    5)
      # Back to main menu
      return
      ;;
    esac
  done
}

# ------------------------------------------------------------------------------
# check_container_resources()
#
# - Compares host RAM/CPU with required values
# - Warns if under-provisioned and asks user to continue or abort
# ------------------------------------------------------------------------------
check_container_resources() {
  current_ram=$(awk '/^MemTotal:/ {printf "%d", $2 / 1024}' /proc/meminfo 2>/dev/null || true)
  current_cpu=$(nproc 2>/dev/null || grep -c ^processor /proc/cpuinfo 2>/dev/null || true)
  # A broken lxcfs mount on the host leaves /proc/meminfo unreadable; that is no reason to stop the update
  if [[ ! "$current_ram" =~ ^[0-9]+$ || ! "$current_cpu" =~ ^[0-9]+$ ]]; then
    msg_warn "Could not read this container's RAM or CPU count, skipping the resource check"
    return 0
  fi

  if [[ "$current_ram" -lt "$var_ram" ]] || [[ "$current_cpu" -lt "$var_cpu" ]]; then
    echo -e "\n${INFO}${HOLD} ${GN}Required: ${var_cpu} CPU, ${var_ram}MB RAM ${CL}| ${RD}Current: ${current_cpu} CPU, ${current_ram}MB RAM${CL}"
    echo -e "${YWB}Please ensure that the ${APP} LXC is configured with at least ${var_cpu} vCPU and ${var_ram} MB RAM for the build process.${CL}\n"
    # prompt_confirm, not a bare read from /dev/tty. update-apps.sh exports
    # PHS_SILENT=1 for unattended runs and cron has no /dev/tty at all, so the
    # read failed the whole update with a device error instead of answering the
    # question it was asked.
    echo -e "${INFO}${HOLD} ${RD}May cause data loss!${CL}"
    if ! prompt_confirm "Continue update with under-provisioned LXC?" "n"; then
      if is_unattended; then
        echo -e "${CROSS}${HOLD} ${YWB}Not continuing: LXC is under-provisioned and there is nobody to ask.${CL}"
      else
        echo -e "${CROSS}${HOLD} ${YWB}Exiting based on user input.${CL}"
      fi
      exit 113 # user aborted an under-provisioned update
    fi
  else
    echo -e ""
  fi
}

# ------------------------------------------------------------------------------
# check_container_storage()
#
# - Checks root (/) partition usage
# - Warns if usage >80% and asks user confirmation before proceeding
# ------------------------------------------------------------------------------
check_container_storage() {
  usage=$(df / -P | awk 'NR==2 {print $5}' | tr -d '%')

  if [ -z "$usage" ] || [ "$usage" -lt 0 ]; then
    echo -e "${CROSS}${HOLD}${RD}Error: Failed to check disk usage.${CL}"
    exit 1
  fi

  if [ "$usage" -gt 80 ]; then
    echo -e "${INFO}${HOLD}${YWB}Warning: Storage is dangerously low (${usage}%).${CL}"
    # See check_container_resources above for why this is not a bare read.
    if ! prompt_confirm "Continue anyway?" "n"; then
      if is_unattended; then
        echo -e "${CROSS}${HOLD}${YWB}Not continuing: only $((100 - usage))% of / is free and there is nobody to ask.${CL}"
        echo -e "${TAB}${YWB}An upgrade that runs out of disk mid-dpkg leaves the container broken.${CL}"
      else
        echo -e "${CROSS}${HOLD}${YWB}Exiting based on user input.${CL}"
      fi
      exit 114 # user aborted with storage too low
    fi
  fi
}

# ------------------------------------------------------------------------------
# ssh_extract_keys_from_file()
#
# - Extracts valid SSH public keys from given file
# - Supports RSA, Ed25519, ECDSA and filters out comments/invalid lines
# ------------------------------------------------------------------------------
ssh_extract_keys_from_file() {
  local f="$1"
  [[ -r "$f" ]] || return 0
  tr -d '\r' <"$f" | awk '
    /^[[:space:]]*#/ {next}
    /^[[:space:]]*$/ {next}
    # bare format: type base64 [comment]
    /^(ssh-(rsa|ed25519)|ecdsa-sha2-nistp256|sk-(ssh-ed25519|ecdsa-sha2-nistp256))[[:space:]]+/ {print; next}
    # with options: find from first key-type onward
    {
      match($0, /(ssh-(rsa|ed25519)|ecdsa-sha2-nistp256|sk-(ssh-ed25519|ecdsa-sha2-nistp256))[[:space:]]+/)
      if (RSTART>0) { print substr($0, RSTART) }
    }
  '
}

# ------------------------------------------------------------------------------
# ssh_build_choices_from_files()
#
# - Builds interactive whiptail checklist of available SSH keys
# - Generates fingerprint, type and comment for each key
# ------------------------------------------------------------------------------
ssh_build_choices_from_files() {
  local -a files=("$@")
  CHOICES=()
  COUNT=0
  MAPFILE="$(mktemp)"
  local id key typ fp cmt base ln=0

  for f in "${files[@]}"; do
    [[ -f "$f" && -r "$f" ]] || continue
    base="$(basename -- "$f")"
    case "$base" in
    known_hosts | known_hosts.* | config) continue ;;
    id_*) [[ "$f" != *.pub ]] && continue ;;
    esac

    # map every key in file
    while IFS= read -r key; do
      [[ -n "$key" ]] || continue

      typ=""
      fp=""
      cmt=""
      # Only the pure key part (without options) is already included in ‘key’.
      read -r _typ _b64 _cmt <<<"$key"
      typ="${_typ:-key}"
      cmt="${_cmt:-}"
      # Fingerprint via ssh-keygen (if available)
      if command -v ssh-keygen >/dev/null 2>&1; then
        fp="$(printf '%s\n' "$key" | ssh-keygen -lf - 2>/dev/null | awk '{print $2}')"
      fi
      # Label shorten
      [[ ${#cmt} -gt 40 ]] && cmt="${cmt:0:37}..."

      ln=$((ln + 1))
      COUNT=$((COUNT + 1))
      id="K${COUNT}"
      echo "${id}|${key}" >>"$MAPFILE"
      CHOICES+=("$id" "[$typ] ${fp:+$fp }${cmt:+$cmt }— ${base}" "OFF")
    done < <(ssh_extract_keys_from_file "$f")
  done
}

# ------------------------------------------------------------------------------
# ssh_discover_default_files()
#
# - Scans standard paths for SSH keys
# - Includes ~/.ssh/*.pub, /etc/ssh/authorized_keys, etc.
# ------------------------------------------------------------------------------
ssh_discover_default_files() {
  local -a cand=()
  shopt -s nullglob
  cand+=(/root/.ssh/authorized_keys /root/.ssh/authorized_keys2)
  cand+=(/root/.ssh/*.pub)
  cand+=(/etc/ssh/authorized_keys /etc/ssh/authorized_keys.d/*)
  shopt -u nullglob
  printf '%s\0' "${cand[@]}"
}

configure_ssh_settings() {
  local step_info="${1:-}"
  local backtitle="Proxmox VE Helper Scripts"
  [[ -n "$step_info" ]] && backtitle="Proxmox VE Helper Scripts [${step_info}]"

  SSH_KEYS_FILE="$(mktemp)"
  : >"$SSH_KEYS_FILE"

  IFS=$'\0' read -r -d '' -a _def_files < <(ssh_discover_default_files && printf '\0')
  ssh_build_choices_from_files "${_def_files[@]}"
  local default_key_count="$COUNT"

  local ssh_key_mode
  if [[ "$default_key_count" -gt 0 ]]; then
    ssh_key_mode=$(whiptail --backtitle "$backtitle" --title "SSH KEY SOURCE" --menu \
      "Provision SSH keys for root:" 14 72 4 \
      "found" "Select from detected keys (${default_key_count})" \
      "manual" "Paste a single public key" \
      "folder" "Scan another folder (path or glob)" \
      "none" "No keys" 3>&1 1>&2 2>&3) || exit_script
  else
    ssh_key_mode=$(whiptail --backtitle "$backtitle" --title "SSH KEY SOURCE" --menu \
      "No host keys detected; choose manual/none:" 12 72 2 \
      "manual" "Paste a single public key" \
      "none" "No keys" 3>&1 1>&2 2>&3) || exit_script
  fi

  case "$ssh_key_mode" in
  found)
    local selection
    selection=$(whiptail --backtitle "$backtitle" --title "SELECT HOST KEYS" \
      --checklist "Select one or more keys to import:" 20 140 10 "${CHOICES[@]}" 3>&1 1>&2 2>&3) || exit_script
    for tag in $selection; do
      tag="${tag%\"}"
      tag="${tag#\"}"
      local line
      line=$(grep -E "^${tag}\|" "$MAPFILE" | head -n1 | cut -d'|' -f2-)
      [[ -n "$line" ]] && printf '%s\n' "$line" >>"$SSH_KEYS_FILE"
    done
    ;;
  manual)
    SSH_AUTHORIZED_KEY="$(whiptail --backtitle "$backtitle" \
      --inputbox "Paste one SSH public key line (ssh-ed25519/ssh-rsa/...)" 10 72 --title "SSH Public Key" 3>&1 1>&2 2>&3)"
    [[ -n "$SSH_AUTHORIZED_KEY" ]] && printf '%s\n' "$SSH_AUTHORIZED_KEY" >>"$SSH_KEYS_FILE"
    ;;
  folder)
    local glob_path
    glob_path=$(whiptail --backtitle "$backtitle" \
      --inputbox "Enter a folder or glob to scan (e.g. /root/.ssh/*.pub)" 10 72 --title "Scan Folder/Glob" 3>&1 1>&2 2>&3)
    if [[ -n "$glob_path" ]]; then
      shopt -s nullglob
      read -r -a _scan_files <<<"$glob_path"
      shopt -u nullglob
      if [[ "${#_scan_files[@]}" -gt 0 ]]; then
        ssh_build_choices_from_files "${_scan_files[@]}"
        if [[ "$COUNT" -gt 0 ]]; then
          local folder_selection
          folder_selection=$(whiptail --backtitle "$backtitle" --title "SELECT FOLDER KEYS" \
            --checklist "Select key(s) to import:" 20 78 10 "${CHOICES[@]}" 3>&1 1>&2 2>&3) || exit_script
          for tag in $folder_selection; do
            tag="${tag%\"}"
            tag="${tag#\"}"
            local line
            line=$(grep -E "^${tag}\|" "$MAPFILE" | head -n1 | cut -d'|' -f2-)
            [[ -n "$line" ]] && printf '%s\n' "$line" >>"$SSH_KEYS_FILE"
          done
        else
          whiptail --backtitle "$backtitle" --msgbox "No keys found in: $glob_path" 8 60
        fi
      else
        whiptail --backtitle "$backtitle" --msgbox "Path/glob returned no files." 8 60
      fi
    fi
    ;;
  none)
    :
    ;;
  esac

  if [[ -s "$SSH_KEYS_FILE" ]]; then
    sort -u -o "$SSH_KEYS_FILE" "$SSH_KEYS_FILE"
    printf '\n' >>"$SSH_KEYS_FILE"
  fi

  # Always show SSH access dialog - user should be able to enable SSH even without keys
  if (whiptail --backtitle "$backtitle" --defaultno --title "SSH ACCESS" --yesno "Enable root SSH access?" 10 58); then
    SSH="yes"
  else
    SSH="no"
  fi
}

# ------------------------------------------------------------------------------
# msg_menu()
#
# - Displays a numbered menu for update_script() functions
# - In silent mode (PHS_SILENT=1): auto-selects the default option
# - In interactive mode: shows menu via read with 10s timeout + default fallback
# - Usage: CHOICE=$(msg_menu "Title" "tag1" "Description 1" "tag2" "Desc 2" ...)
# - The first item is always the default
# - Returns the selected tag to stdout
# - If no valid selection or timeout, returns the default (first) tag
# ------------------------------------------------------------------------------
msg_menu() {
  local title="$1"
  shift

  # Parse items into parallel arrays: tags[] and descriptions[]
  local -a tags=()
  local -a descs=()
  while [[ $# -ge 2 ]]; do
    tags+=("$1")
    descs+=("$2")
    shift 2
  done

  local default_tag="${tags[0]}"
  local count=${#tags[@]}

  # Silent mode: return default immediately
  if [[ -n "${PHS_SILENT+x}" ]] && [[ "${PHS_SILENT}" == "1" ]]; then
    echo "$default_tag"
    return 0
  fi

  # Display menu to /dev/tty so it doesn't get captured by command substitution
  {
    echo ""
    msg_custom "📋" "${BL}" "${title}"
    echo ""
    for i in "${!tags[@]}"; do
      local marker="  "
      [[ $i -eq 0 ]] && marker="* "
      printf "${TAB3}${marker}%s) %s\n" "${tags[$i]}" "${descs[$i]}"
    done
    echo ""
  } >/dev/tty

  local selection=""
  read -r -t 10 -p "${TAB3}Select [default=${default_tag}, timeout 10s]: " selection </dev/tty >/dev/tty || true

  # Validate selection
  if [[ -n "$selection" ]]; then
    for tag in "${tags[@]}"; do
      if [[ "$selection" == "$tag" ]]; then
        echo "$selection"
        return 0
      fi
    done
    msg_warn "Invalid selection '${selection}' - using default: ${default_tag}"
  fi

  echo "$default_tag"
  return 0
}

run_addon_updates() {
  shopt -s nullglob
  local addons=(/usr/local/bin/update_*)
  local a name ans
  shopt -u nullglob

  ((${#addons[@]} == 0)) && return 0

  if [[ "${PHS_SILENT:-0}" == "1" ]]; then
    msg_custom "ℹ️" "${YW}" "Detected ${#addons[@]} addon update script(s) - skipping (PHS_SILENT)"
    return 0
  fi

  echo
  echo -e "${INFO}${YW} Detected installed addon update script(s):${CL}"
  for a in "${addons[@]}"; do
    echo -e "${TAB}- ${a##*/update_}"
  done
  echo

  for a in "${addons[@]}"; do
    name="${a##*/update_}"
    printf 'Do you also want to update addon "%s"? (y/N) [60s]: ' "$name"
    ans=""
    if read -r -t 60 ans </dev/tty; then :; else echo; fi
    case "${ans,,}" in
    y | yes)
      bash "$a" || msg_warn "Addon update for $name failed (rc=$?)"
      ;;
    *)
      msg_custom "ℹ️" "${YW}" "Skipped addon: $name"
      ;;
    esac
  done
}

runtime_script_status_guard() {
  local mode="${1:-}"
  local script_slug="${SCRIPT_SLUG:-${NSAPP:-}}"
  script_slug="$(echo "$script_slug" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')"
  [[ -z "$script_slug" ]] && return 0

  local api_url="https://db.community-scripts.org/api/collections/script_scripts/records?filter=(slug='${script_slug}')&perPage=1&fields=slug,is_disabled,is_deleted,disable_message,deleted_message,pinned_version,pin_reason"
  local response
  if ! response=$(curl -fsSL --connect-timeout 2 --max-time 3 "$api_url" 2>/dev/null); then
    msg_warn "Script status check is unavailable. Continuing without status verification."
    return 0
  fi

  local is_deleted is_disabled deleted_message disable_message pinned_version pin_reason info_url
  if printf '%s' "$response" | grep -qE '"items":[[:space:]]*\[[[:space:]]*\]'; then
    return 0
  fi

  # PocketBase returns a flat, fixed-field JSON blob; sed is enough here (no jq needed).
  is_deleted=$(printf '%s' "$response" | sed -n 's/.*"is_deleted"[[:space:]]*:[[:space:]]*\(true\|false\).*/\1/p' | head -1)
  is_disabled=$(printf '%s' "$response" | sed -n 's/.*"is_disabled"[[:space:]]*:[[:space:]]*\(true\|false\).*/\1/p' | head -1)
  deleted_message=$(printf '%s' "$response" | sed -n 's/.*"deleted_message"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
  disable_message=$(printf '%s' "$response" | sed -n 's/.*"disable_message"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
  pinned_version=$(printf '%s' "$response" | sed -n 's/.*"pinned_version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
  pin_reason=$(printf '%s' "$response" | sed -n 's/.*"pin_reason"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
  is_deleted=${is_deleted:-false}
  is_disabled=${is_disabled:-false}
  info_url="https://community-scripts.org/scripts/${script_slug}"

  if [[ "$is_deleted" == "true" ]]; then
    msg_error "This script is no longer available in community-scripts."
    [[ -n "$deleted_message" ]] && msg_error "$deleted_message"
    [[ -z "$deleted_message" ]] && msg_error "This script was removed and cannot be installed or updated."
    msg_warn "More info: ${info_url}"
    return 1
  fi

  if [[ "$is_disabled" == "true" ]]; then
    case "${var_ignore_disable:-}" in
    1 | yes | true | on)
      msg_warn "This script is currently disabled in community-scripts."
      [[ -n "$disable_message" ]] && msg_warn "$disable_message"
      msg_warn "Bypassing disable status via var_ignore_disable — continuing at your own risk."
      msg_warn "More info: ${info_url}"
      return 0
      ;;
    esac

    msg_error "This script is currently disabled in community-scripts."
    [[ -n "$disable_message" ]] && msg_error "$disable_message"
    [[ -z "$disable_message" ]] && msg_error "Updates and installs are temporarily disabled for this script."
    msg_warn "More info: ${info_url}"
    return 1
  fi

  if [[ "$mode" == "update" && -n "$pinned_version" && -n "${NSAPP:-}" ]]; then
    local current_file="$HOME/.${NSAPP}"
    if [[ -f "$current_file" ]]; then
      local installed pinned_clean installed_clean
      installed="$(<"$current_file")"
      pinned_clean="$pinned_version"
      installed_clean="$installed"
      [[ "$pinned_clean" =~ ^v[0-9] ]] && pinned_clean="${pinned_clean:1}"
      [[ "$installed_clean" =~ ^v[0-9] ]] && installed_clean="${installed_clean:1}"
      if [[ "$installed_clean" == "$pinned_clean" ]]; then
        if [[ -n "$pin_reason" ]]; then
          msg_custom "ℹ️" "${YW}" "You are already on the pinned version (${pinned_version}). ${pin_reason}"
        else
          msg_custom "ℹ️" "${YW}" "You are already on the pinned version (${pinned_version}). No newer update is offered intentionally — please do not open an issue unless you see an actual error."
        fi
        msg_custom "ℹ️" "${YW}" "More info: ${info_url}"
      fi
    fi
  fi

  return 0
}
check_container_os_guard() {
  local rec_os="${var_os:-}" rec_ver="${var_version:-}"
  rec_os="${rec_os,,}"
  [[ -z "$rec_os" || -z "$rec_ver" ]] && return 0
  [[ -r /etc/os-release ]] || return 0

  local cur_os cur_ver
  cur_os="$(. /etc/os-release 2>/dev/null; echo "${ID:-}")"
  cur_ver="$(. /etc/os-release 2>/dev/null; echo "${VERSION_ID:-}")"
  cur_os="${cur_os,,}"
  [[ -z "$cur_os" || -z "$cur_ver" ]] && return 0

  # Exact version or prefix on a dot boundary (e.g. alpine 3.22 matches 3.22.1)
  if [[ "$cur_os" == "$rec_os" ]] && [[ "$cur_ver" == "$rec_ver" || "$cur_ver" == "$rec_ver".* ]]; then
    return 0
  fi

  local downgraded_target=0
  if [[ "$cur_os" == "$rec_os" ]] && [[ "$cur_ver" != "$rec_ver" ]]; then
    if [[ "$(printf '%s\n%s\n' "$cur_ver" "$rec_ver" | sort -V | tail -n1)" == "$cur_ver" ]]; then
      downgraded_target=1
    fi
  fi

  case "${var_ignore_os_mismatch:-}" in
  1 | yes | true | on)
    msg_warn "Container OS is ${cur_os} ${cur_ver} but the script recommends ${rec_os} ${rec_ver} — continuing via var_ignore_os_mismatch (may break, no support)."
    return 0
    ;;
  esac

  local ignore_file="/usr/local/community-scripts/ignore-os-mismatch"
  if [[ -f "$ignore_file" && "$(cat "$ignore_file" 2>/dev/null)" == "${rec_os} ${rec_ver}" ]]; then
    msg_warn "Container OS is ${cur_os} ${cur_ver} but the script recommends ${rec_os} ${rec_ver} — continuing (previously ignored via ${ignore_file}, may break, no support)."
    return 0
  fi

  local mismatch_detail remediation dialog_title="OS VERSION MISMATCH"
  if [[ "$cur_os" != "$rec_os" ]]; then
    # Two different distributions. Their version numbers are not comparable and
    # there is no upgrade path between them, so the version-mismatch wording
    # produced impossible advice like "upgrade the container OS to debian 26.04".
    dialog_title="WRONG OS"
    mismatch_detail="This container runs ${cur_os} ${cur_ver}, but this script targets ${rec_os} ${rec_ver}.\n\n${cur_os^} and ${rec_os^} are different distributions: there is no upgrade path between them, and their version numbers are unrelated.\n\nRecommended: create a new ${rec_os} ${rec_ver} container and install ${APP:-the application} there."
    remediation="Create a new ${rec_os} ${rec_ver} container instead - ${cur_os} cannot be upgraded to ${rec_os}"
  elif [[ "$downgraded_target" -eq 1 ]]; then
    mismatch_detail="Your container runs ${cur_os} ${cur_ver}, which is newer than what this script now targets (${rec_os} ${rec_ver}).\n\nThe target was likely lowered on purpose, e.g. because ${APP:-the app} had problems on newer OS versions - check the GitHub issues for ${APP:-this app} for details.\n\nContinuing on ${cur_ver} often still works, but isn't guaranteed. If you are unsure, ask in our Discord (https://discord.gg/3AnUqsXnmK) before continuing."
    remediation="This script now targets the older ${rec_os} ${rec_ver}. Check the GitHub issues for ${APP:-this app}, or ask in Discord (https://discord.gg/3AnUqsXnmK) if you are unsure"
  else
    mismatch_detail="This container runs ${cur_os} ${cur_ver}, but this script now targets ${rec_os} ${rec_ver}.\n\nUpdating on the older base OS may fail or leave ${APP:-the application} broken (e.g. required runtime versions are not available).\n\nRecommended: upgrade the container OS to ${rec_os} ${rec_ver} first, then run this update again."
    remediation="Upgrade the container OS to ${rec_os} ${rec_ver} first, then run this update again"
  fi

  if [[ "${PHS_SILENT:-0}" != "1" ]] && command -v whiptail &>/dev/null && [ -t 0 ] && [[ "$TERM" != "dumb" ]]; then
    local choice
    choice=$(whiptail --backtitle "Proxmox VE Helper Scripts" --title "$dialog_title" --menu \
      "${mismatch_detail}\n\nIf you continue anyway, it may break — no support is provided in that case.\n\nContinue anyway?" \
      20 70 3 \
      "1" "No  (cancel update)" \
      "2" "Yes (continue this time)" \
      "3" "Yes (continue and don't ask again)" \
      --nocancel --default-item "1" 3>&1 1>&2 2>&3)
    case "$choice" in
    2)
      msg_warn "Continuing update on ${cur_os} ${cur_ver} despite recommended ${rec_os} ${rec_ver} — may break, no support."
      return 0
      ;;
    3)
      mkdir -p "${ignore_file%/*}"
      echo "${rec_os} ${rec_ver}" >"$ignore_file"
      msg_warn "Continuing update on ${cur_os} ${cur_ver}; OS check for ${rec_os} ${rec_ver} disabled via ${ignore_file} — may break, no support."
      return 0
      ;;
    esac
    msg_error "Update cancelled: container OS ${cur_os} ${cur_ver} does not match the recommended ${rec_os} ${rec_ver}."
    return 1
  fi

  msg_error "Container OS ${cur_os} ${cur_ver} does not match the recommended ${rec_os} ${rec_ver} — skipping update."
  msg_error "${remediation} — or bypass this check (may break, no support) with: echo \"${rec_os} ${rec_ver}\" > ${ignore_file}"
  return 1
}
# Breaking-change advisory guard. Before an update touches anything, ask
# community-scripts whether an ACTIVE breaking change affects this script and, if
# so, surface it — most importantly the pull request to read — before any update
# work begins. This is the shell-side counterpart of the on-site banner: both
# read the same advisories from the same API (its TTL decides "active"), so a
# container update warns about exactly what the website shows.
#
# It mirrors runtime_script_status_guard on purpose: the same slug derivation and
# the same fail-open behaviour when the check is unreachable — an update must
# never be blocked by our own API being down. The difference is that a hit is
# usually not fatal. The point is to inform and let the operator decide,
# defaulting in interactive use to "cancel and review the PR first".
#
# Two refinements on top of a plain warning:
#   * Per-container memory. Each advisory the operator proceeds past is recorded
#     by PR number in a local ledger (/usr/local/community-scripts/
#     breaking-changes.seen). A still-active (within-TTL) advisory is shown once;
#     a later update in the same 30-day window is not nagged about it again. Only
#     an advisory this container has not yet handled is surfaced.
#   * Blocking advisories. An advisory the PR author marked action="block" is not
#     a warning but a stop: interactively it offers no one-keypress Continue, and
#     unattended it aborts the update. var_force_breaking_update=1 is the explicit
#     escape hatch (distinct from var_ignore_breaking_changes, which mutes the
#     check entirely). This is the one case where a reachable hit is fatal — never
#     an unreachable one, so a flaky API still can't wedge a fleet.
check_breaking_change_guard() {
  local script_slug="${SCRIPT_SLUG:-${NSAPP:-}}"
  script_slug="$(echo "$script_slug" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')"
  [[ -z "$script_slug" ]] && return 0

  # Opt-out for unattended fleets that have already accounted for advisories.
  case "${var_ignore_breaking_changes:-}" in
  1 | yes | true | on) return 0 ;;
  esac

  local api_url="https://community-scripts.org/api/breaking-changes?slug=${script_slug}"
  local response
  if ! response=$(curl -fsSL --connect-timeout 2 --max-time 4 "$api_url" 2>/dev/null); then
    # Fail open: never block an update because the advisory check was unreachable.
    return 0
  fi

  # Empty array -> no active breaking change for this script.
  if [[ -z "$response" ]] || printf '%s' "$response" | grep -qE '^[[:space:]]*\[[[:space:]]*\][[:space:]]*$'; then
    return 0
  fi

  # One JSON object per line so each advisory parses independently. Title and
  # summary are anchored on their neighbouring keys, so an embedded quote in a
  # PR title cannot truncate them. No jq: not present on a bare PVE host.
  local objects
  objects="$(printf '%s' "$response" | sed 's/},[[:space:]]*{/}\n{/g')"

  local seen_file="/usr/local/community-scripts/breaking-changes.seen"
  local details="" first_pr_url="" count=0 obj new_prs="" blocking=0
  while IFS= read -r obj; do
    [[ -z "$obj" ]] && continue
    local pr_url pr_number pr_title summary severity merged_at action steps_raw
    pr_url=$(printf '%s' "$obj" | sed -n 's/.*"pr_url":"\([^"]*\)".*/\1/p')
    pr_number=$(printf '%s' "$obj" | sed -n 's/.*"pr_number":\([0-9]*\).*/\1/p')
    pr_title=$(printf '%s' "$obj" | sed -n 's/.*"pr_title":"\(.*\)","summary".*/\1/p')
    summary=$(printf '%s' "$obj" | sed -n 's/.*"summary":"\(.*\)","severity".*/\1/p')
    severity=$(printf '%s' "$obj" | sed -n 's/.*"severity":"\([^"]*\)".*/\1/p')
    merged_at=$(printf '%s' "$obj" | sed -n 's/.*"merged_at":"\([^"]*\)".*/\1/p')
    action=$(printf '%s' "$obj" | sed -n 's/.*"action":"\([^"]*\)".*/\1/p')
    # pre_update_steps is a JSON string array; capture what's between the [ ].
    steps_raw=$(printf '%s' "$obj" | sed -n 's/.*"pre_update_steps":\[\([^]]*\)\].*/\1/p')
    # Un-escape the JSON string escapes that appear in human text.
    pr_title=${pr_title//\\\"/\"}
    pr_title=${pr_title//\\\//\/}
    summary=${summary//\\\"/\"}
    summary=${summary//\\\//\/}
    merged_at=${merged_at%%[T ]*} # date only

    # Skip advisories this container has already been shown and proceeded past
    # (recorded by PR number). This is what stops a within-TTL advisory from
    # re-warning on every update in its 30-day window once it has been handled.
    if [[ -n "$pr_number" ]] && [[ -f "$seen_file" ]] &&
      grep -qxF "$pr_number" "$seen_file" 2>/dev/null; then
      continue
    fi

    count=$((count + 1))
    [[ -z "$first_pr_url" ]] && first_pr_url="$pr_url"
    [[ -n "$pr_number" ]] && new_prs+=" $pr_number"
    [[ "$action" == "block" ]] && blocking=1

    local headline="${summary:-${pr_title:-Breaking change}}"
    [[ -n "$severity" ]] && headline+=" [${severity}]"
    [[ "$action" == "block" ]] && headline+=" [BLOCKS UPDATE]"
    details+="• ${headline}\n"
    if [[ -n "$pr_number" ]]; then
      details+="    PR #${pr_number}: ${pr_title}\n"
    elif [[ -n "$pr_title" ]]; then
      details+="    ${pr_title}\n"
    fi
    [[ -n "$pr_url" ]] && details+="    Review: ${pr_url}\n"
    [[ -n "$merged_at" ]] && details+="    Merged: ${merged_at}\n"
    if [[ -n "$steps_raw" ]]; then
      details+="    Before updating:\n"
      local step steps_lines
      steps_lines="$(printf '%s' "$steps_raw" | sed 's/","/\n/g')"
      while IFS= read -r step; do
        step=${step#\"}
        step=${step%\"}
        step=${step//\\\"/\"}
        step=${step//\\\//\/}
        [[ -n "$step" ]] && details+="      - ${step}\n"
      done <<<"$steps_lines"
    fi
    details+="\n"
  done <<<"$objects"

  [[ "$count" -eq 0 ]] && return 0

  local plural=""
  [[ "$count" -ne 1 ]] && plural="s"

  # Explicit, deliberate override: proceed even past a blocking advisory. Meant
  # for an operator who has read the PR, or an unattended fleet that has already
  # accounted for it. Distinct from var_ignore_breaking_changes (which mutes the
  # check entirely) — this still shows the advisory, it just doesn't stop.
  local force=0
  case "${var_force_breaking_update:-}" in
  1 | yes | true | on) force=1 ;;
  esac

  local proceed=0

  # Interactive: stop and require an explicit choice.
  if [[ "${PHS_SILENT:-0}" != "1" ]] && command -v whiptail &>/dev/null && [ -t 0 ] && [[ "$TERM" != "dumb" ]]; then
    local body
    body="${count} active breaking change${plural} may affect this update of ${APP:-$script_slug}.\n\n"
    body+="${details}"
    if [[ "$blocking" -eq 1 ]] && [[ "$force" -ne 1 ]]; then
      # A blocking advisory: no one-keypress "Continue". Inform and stop.
      body+="This update is BLOCKED until you address the change above.\n"
      body+="Read the pull request${plural}, then re-run once ready. To override on\n"
      body+="an unattended host, set var_force_breaking_update=1."
      whiptail --backtitle "Proxmox VE Helper Scripts" \
        --title "⛔ BREAKING CHANGE BLOCKS UPDATE — ${APP:-$script_slug}" \
        --msgbox "$(printf '%b' "$body")" 22 78
      msg_error "Update blocked by a breaking change — review ${first_pr_url:-the PR} and re-run. Override with var_force_breaking_update=1."
      proceed=0
    else
      body+="Read the pull request${plural} above before updating.\n\nContinue with the update anyway?"
      if whiptail --backtitle "Proxmox VE Helper Scripts" \
        --title "⚠ BREAKING CHANGE — ${APP:-$script_slug}" \
        --yesno "$(printf '%b' "$body")" 22 78 --defaultno \
        --yes-button "Continue" --no-button "Cancel & review" 3>&1 1>&2 2>&3; then
        msg_warn "Continuing update of ${APP:-$script_slug} despite an active breaking change — review ${first_pr_url:-the PR} if you have not."
        proceed=1
      else
        msg_error "Update cancelled — review the breaking change first: ${first_pr_url:-https://community-scripts.org/scripts/${script_slug}}"
        proceed=0
      fi
    fi
  else
    # Non-interactive / silent: can't prompt without hanging an unattended run, so
    # warn loudly. A blocking advisory still aborts (unless forced); a plain one
    # continues. var_ignore_breaking_changes already skips this entirely.
    msg_warn "Breaking change advisory for ${APP:-$script_slug} — ${count} active:"
    printf '%b' "$details" | while IFS= read -r l; do
      [[ -n "$l" ]] && msg_warn "  $l"
    done
    if [[ "$blocking" -eq 1 ]] && [[ "$force" -ne 1 ]]; then
      msg_error "Update blocked by a breaking change. Review the PR, then re-run. Override with var_force_breaking_update=1."
      proceed=0
    else
      msg_warn "Review the pull request before relying on this update."
      proceed=1
    fi
  fi

  if [[ "$proceed" -eq 1 ]]; then
    # Record the advisories we showed so a re-update inside the TTL window isn't
    # nagged about them again. Done on proceed rather than after a verified
    # update because most ct scripts exit inside update_script and never return
    # here — and by this point the operator has seen and accepted the change.
    if [[ -n "$new_prs" ]]; then
      mkdir -p /usr/local/community-scripts 2>/dev/null
      local n
      for n in $new_prs; do
        grep -qxF "$n" "$seen_file" 2>/dev/null || echo "$n" >>"$seen_file"
      done
    fi
    return 0
  fi
  return 1
}

# The update path, shared by the three branches of start() that reach it.
# exit, not return: returning continues into the ct script's host-only tail.
# Most ct scripts exit inside update_script, so the call after it is
# unreachable for them; cleanup and MOTD therefore run from on_exit.
_cs_run_update() {
  ensure_profile_loaded
  ensure_recorded_toolchains
  get_lxc_ip
  migrate_update_entrypoint
  runtime_script_status_guard update || exit 0
  check_container_os_guard || exit 0
  check_breaking_change_guard || exit 0
  apt_conffile_guard
  _CS_UPDATE_CLEANUP=1
  update_script
  run_addon_updates
  exit 0
}

# The whiptail update menu in plain text; sets VERBOSE or leaves on cancel.
_cs_ask_update_mode() {
  local choice=""
  echo -e "${YW}Update ${APP:-this container}?${CL}"
  echo -e "  ${GN}1)${CL} YES (silent mode)"
  echo -e "  ${GN}2)${CL} YES (verbose mode)"
  echo -e "  ${GN}3)${CL} NO (cancel update)"
  read -r -t 60 -p "Select option [1-3] (default: 1): " choice || choice=""
  case "$choice" in
  2) VERBOSE="yes" ;;
  3)
    _cs_clear
    exit_script
    exit
    ;;
  *) VERBOSE="no" ;;
  esac
  set_std_mode
}

start() {
  # Through the resolver, not a bare curl: this way a local checkout and the
  # prefetched copy are used. Hardcoding the URL here meant tools.func and its
  # five parts were six network requests between the header and the menu,
  # every run, whatever else had already been fetched.
  _cs_source_func "lib/tools.func"

  # Every branch after the first updates the system it is running on. Missing
  # pveversion used to be taken as proof of being inside a container, but an
  # Incus host has none either, so a create run fell through and ran apt-get
  # against the host. Only refuse on a positively identified host, so an
  # environment we cannot classify still updates as before.
  local _cs_platform=""
  declare -f detect_lxc_platform >/dev/null 2>&1 && _cs_platform="$(detect_lxc_platform)"

  if command -v pveversion >/dev/null 2>&1; then
    runtime_script_status_guard install || return 0
    install_script || return 0
    return 0
  elif [[ "$_cs_platform" == "pve" || "$_cs_platform" == "incus" ]]; then
    msg_error "This is a ${_cs_platform} host, not a container - refusing to update it"
    msg_custom "ℹ️" "${YW}" "The engine could not load the ${_cs_platform} backend, so ${APP:-this script} never got to the create path"
    msg_custom "ℹ️" "${YW}" "Retry with: LXC_PLATFORM=${_cs_platform} bash -c \"\$(curl -fsSL <script-url>)\""
    exit 1
  elif [ ! -z ${PHS_SILENT+x} ] && [[ "${PHS_SILENT}" == "1" ]]; then
    VERBOSE="no"
    set_std_mode
    _cs_run_update
  elif ! [ -t 0 ] || [[ "$TERM" == "dumb" ]]; then
    msg_custom "ℹ️" "${YW}" "No interactive terminal detected – defaulting to silent update mode"
    VERBOSE="no"
    set_std_mode
    _cs_run_update
  elif ! command -v whiptail &>/dev/null; then
    # Oracle, Amazon and other dnf images ship no whiptail; ask in plain text.
    _cs_ask_update_mode
    _cs_run_update
  else
    CHOICE=$(whiptail --backtitle "Proxmox VE Helper Scripts" --title "${APP} LXC Update/Setting" --menu \
      "Support/Update functions for ${APP} LXC. Choose an option:" \
      12 60 3 \
      "1" "YES (Silent Mode)" \
      "2" "YES (Verbose Mode)" \
      "3" "NO (Cancel Update)" --nocancel --default-item "1" 3>&1 1>&2 2>&3)

    case "$CHOICE" in
    1)
      VERBOSE="no"
      set_std_mode
      ;;
    2)
      VERBOSE="yes"
      set_std_mode
      ;;
    3)
      _cs_clear
      exit_script
      exit
      ;;
    esac
    _cs_run_update
  fi
}