core.func

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

# ==============================================================================
# INCUS-CORE.FUNC - CORE UTILITIES FOR INCUS CONTAINER MANAGEMENT
# ==============================================================================
#
# This file provides core utility functions for Incus container management
# including colors, formatting, validation checks, message output, and
# execution helpers - adapted from Proxmox LXC patterns for Incus.
#
# Key differences from Proxmox LXC (core.func):
#   - Incus CLI instead of pct/pvesm
#   - incus profiles instead of CT templates
#   - incus storage pools instead of Proxmox storage
#   - incus networks instead of vmbr bridges
#   - No pveam (uses incus image copy/list)
#
# Usage:
#   source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/core/main/incus/core.func)
#   load_incus_functions
#
# ==============================================================================

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

INCUS_COMMUNITY_SCRIPTS_URL="${COMMUNITY_SCRIPTS_URL:-https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main}"

# Load upstream misc/core.func for full helper parity (prompt_*, dev-mode, etc.).
# Incus-specific behavior is provided through incus_* functions and aliases below.
if [[ -z "${_CORE_FUNC_LOADED:-}" ]]; then
  _cs_source_func "core/core.func"
fi

# ==============================================================================
# SECTION 1: INITIALIZATION & SETUP
# ==============================================================================

# ------------------------------------------------------------------------------
# load_incus_functions()
#
# - Initializes all core utility groups (colors, formatting, icons, defaults)
# - Ensures functions are loaded only once via __INCUS_FUNCTIONS_LOADED flag
# - Must be called at start of any Incus script
# ------------------------------------------------------------------------------
load_incus_functions() {
  [[ -n "${__INCUS_FUNCTIONS_LOADED:-}" ]] && return
  __INCUS_FUNCTIONS_LOADED=1
  incus_color
  incus_formatting
  incus_icons
  incus_default_vars
  incus_set_std_mode
}

# ------------------------------------------------------------------------------
# incus_color()
#
# - Sets ANSI color codes for styled terminal output
# - Variables: YW (yellow), YWB (yellow bright), BL (blue), RD (red)
#             GN (green), DGN (dark green), BGN (background green), CL (clear)
# ------------------------------------------------------------------------------
incus_color() {
  YW=$(echo "\033[33m")
  YWB=$'\e[93m'
  BL=$(echo "\033[36m")
  RD=$(echo "\033[01;31m")
  BGN=$(echo "\033[4;92m")
  GN=$(echo "\033[1;92m")
  DGN=$(echo "\033[32m")
  CL=$(echo "\033[m")

  # Same as core/core.func: a dev run is red, so it never reads as a normal one.
  if [[ -n "${dev_mode:-}" ]]; then
    BGN=$(echo "\033[4;91m")
    GN=$(echo "\033[1;91m")
    DGN=$(echo "\033[31m")
  fi
}

# ------------------------------------------------------------------------------
# incus_color_spinner()
#
# - Sets ANSI color codes specifically for spinner animation
# ------------------------------------------------------------------------------
incus_color_spinner() {
  CS_YW=$'\033[33m'
  CS_YWB=$'\033[93m'
  CS_CL=$'\033[m'
}

# ------------------------------------------------------------------------------
# incus_formatting()
#
# - Defines formatting helpers for terminal output
# ------------------------------------------------------------------------------
incus_formatting() {
  BFR="\\r\\033[K"
  BOLD=$(echo "\033[1m")
  HOLD=" "
  TAB="  "
  TAB3="      "
}

# ------------------------------------------------------------------------------
# incus_icons()
#
# - Sets symbolic emoji icons used throughout user feedback
# ------------------------------------------------------------------------------
incus_icons() {
  CM="${TAB}✔️${TAB}"
  CROSS="${TAB}✖️${TAB}"
  DNSOK="✔️ "
  DNSFAIL="${TAB}✖️${TAB}"
  INFO="${TAB}💡${TAB}${CL}"
  OVERRIDE="${TAB}🔀${TAB}${CL}"
  OS="${TAB}🖥️${TAB}${CL}"
  OSVERSION="${TAB}🌟${TAB}${CL}"
  CONTAINERTYPE="${TAB}📦${TAB}${CL}"
  DISKSIZE="${TAB}💾${TAB}${CL}"
  CPUCORE="${TAB}🧠${TAB}${CL}"
  RAMSIZE="${TAB}🛠️${TAB}${CL}"
  SEARCH="${TAB}🔍${TAB}${CL}"
  VERBOSE_CROPPED="🔍${TAB}"
  VERIFYPW="${TAB}🔐${TAB}${CL}"
  CONTAINERID="${TAB}🆔${TAB}${CL}"
  HOSTNAME="${TAB}🏠${TAB}${CL}"
  BRIDGE="${TAB}🌉${TAB}${CL}"
  NETWORK="${TAB}📡${TAB}${CL}"
  GATEWAY="${TAB}🌐${TAB}${CL}"
  ICON_DISABLEIPV6="${TAB}🚫${TAB}${CL}"
  DEFAULT="${TAB}⚙️${TAB}${CL}"
  MACADDRESS="${TAB}🔗${TAB}${CL}"
  VLANTAG="${TAB}🏷️${TAB}${CL}"
  ROOTSSH="${TAB}🔑${TAB}${CL}"
  CREATING="${TAB}🚀${TAB}${CL}"
  ADVANCED="${TAB}🧩${TAB}${CL}"
  FUSE="${TAB}🗂️${TAB}${CL}"
  GPU="${TAB}🎮${TAB}${CL}"
  CLOUD="${TAB}☁️${TAB}"
  VTPM="${TAB}🔐${TAB}"
  DISKBUS="${TAB}🔌${TAB}"
  SNAPSHOT="${TAB}📸${TAB}"
  HOURGLASS="${TAB}⏳${TAB}"
}

# ------------------------------------------------------------------------------
# incus_default_vars()
#
# - Sets default retry and wait variables used for system actions
# ------------------------------------------------------------------------------
incus_default_vars() {
  RETRY_NUM=10
  RETRY_EVERY=3
  i=$RETRY_NUM
}

# ------------------------------------------------------------------------------
# incus_set_std_mode()
#
# - Sets default verbose mode for script and OS execution
# - If VERBOSE=yes: STD="" (show all output)
# - If VERBOSE=no: STD="silent" (suppress output via silent() wrapper)
# ------------------------------------------------------------------------------
incus_set_std_mode() {
  if [ "${VERBOSE:-no}" = "yes" ]; then
    STD=""
  else
    STD="silent"
  fi

  # Enable bash tracing if trace mode active
  if [[ "${DEV_MODE_TRACE:-false}" == "true" ]]; then
    set -x
    # BASH_SOURCE is empty at the top level of `bash -c` and inside a
    # `source /dev/stdin`, which is exactly how the install script runs in the
    # container. Unguarded, set -u aborts the run the moment PS4 is expanded.
    export PS4='+(${BASH_SOURCE:-?}:${LINENO}): ${FUNCNAME[0]:+${FUNCNAME[0]}(): }'
  fi
}

# ==============================================================================
# SECTION 2: VALIDATION CHECKS (Incus-specific)
# ==============================================================================

# ------------------------------------------------------------------------------
# incus_shell_check()
#
# - Verifies that the script is running under Bash shell
# ------------------------------------------------------------------------------
incus_shell_check() {
  if [[ "$(ps -p $$ -o comm=)" != "bash" ]]; then
    _cs_clear
    incus_msg_error "Your default shell is currently not set to Bash. To use these scripts, please switch to the Bash shell."
    echo -e "\nExiting..."
    sleep 2
    exit 103 # shell is not Bash
  fi
}

# ------------------------------------------------------------------------------
# incus_root_check()
#
# - Verifies script is running with root privileges
# ------------------------------------------------------------------------------
incus_root_check() {
  # Incus can be used by non-root users in the 'incus-admin' group
  if incus info &>/dev/null; then
    return 0
  fi

  # Fallback: root always works
  if [[ "$(id -u)" -eq 0 ]]; then
    return 0
  fi

  _cs_clear
  incus_msg_error "Cannot access Incus. Either:"
  incus_msg_error "  - Run as root (sudo), or"
  incus_msg_error "  - Add your user to the incus-admin group: sudo usermod -aG incus-admin \$USER"
  echo -e "\nExiting..."
  sleep 2
  exit 152 # permission denied
}

# ------------------------------------------------------------------------------
# incus_check()
#
# - Validates that Incus is installed and accessible
# - Checks incus daemon is running
# - Exits with error message if Incus is not available
# ------------------------------------------------------------------------------
# The client's default remote is where every bare name in this backend goes;
# IncusOS has no shell, so a switched remote is the only way to drive it.
incus_target() {
  INCUS_REMOTE="$(LC_ALL=C incus remote get-default 2>/dev/null || echo local)"
  local info
  info="$(LC_ALL=C incus info 2>/dev/null)"
  # kernel_architecture is a scalar; the architectures list indents by version.
  INCUS_SERVER_ARCH="$(awk '$1 == "kernel_architecture:" {print $2; exit}' <<<"$info")"
  [[ -n "$INCUS_SERVER_ARCH" ]] || INCUS_SERVER_ARCH="$(awk '$1 == "architectures:" {a=1; next} a && $1 == "-" {print $2; exit}' <<<"$info")"
  case "$INCUS_SERVER_ARCH" in
  x86_64) INCUS_SERVER_ARCH="amd64" ;;
  aarch64) INCUS_SERVER_ARCH="arm64" ;;
  esac
  INCUS_SERVER_KERNEL="$(awk '$1 == "kernel_version:" {print $2; exit}' <<<"$info")"
  export INCUS_REMOTE INCUS_SERVER_ARCH INCUS_SERVER_KERNEL
}

incus_check() {
  if ! command -v incus &>/dev/null; then
    incus_msg_error "Incus is not installed on this system."
    incus_msg_error "Install Incus first: https://linuxcontainers.org/incus/docs/main/installing/"
    exit 1
  fi

  # Check if incus daemon is accessible. The probe's own error is what tells
  # a stopped daemon apart from a permission problem or an uninitialised
  # install, so keep it instead of always advising "systemctl start incus".
  local probe_err probe_rc=0
  probe_err="$(LC_ALL=C incus info 2>&1 >/dev/null)" || probe_rc=$?
  if ((probe_rc != 0)); then
    case "$probe_err" in
    *"onnection refused"* | *"o such file or directory"* | *"ailed to connect"*)
      incus_msg_error "Incus daemon is not running."
      incus_msg_error "Run: systemctl start incus"
      ;;
    *"ermission denied"* | *"needed permissions"* | *"not authorized"* | *"nauthorized"*)
      incus_msg_error "No permission to reach the Incus daemon as $(id -un)."
      # A fresh usermod does not reach an already-open login session, so the
      # same command can work in one terminal and fail in another.
      if id -nG 2>/dev/null | tr ' ' '\n' | grep -qx incus-admin; then
        incus_msg_error "You are in incus-admin, but this shell started before that - run: newgrp incus-admin (or log out and back in)"
      else
        incus_msg_error "Run: sudo usermod -aG incus-admin $(id -un) - then log out and back in, or start the shell with: newgrp incus-admin"
      fi
      ;;
    *"not been initialized"* | *"o storage pool"*)
      incus_msg_error "Incus is installed but not initialised."
      incus_msg_error "Run: incus admin init"
      ;;
    *)
      incus_msg_error "Cannot query the Incus daemon (incus info exited ${probe_rc})."
      incus_msg_error "${probe_err:-no error output - try running: incus info}"
      ;;
    esac
    exit 1
  fi

  # Check if we have any storage pools
  local pool_count
  pool_count=$(incus storage list -f csv,noheader 2>/dev/null | wc -l)
  if [[ "$pool_count" -eq 0 ]]; then
    incus_msg_error "No Incus storage pools found."
    incus_msg_error "Create one with: incus storage create default dir"
    exit 1
  fi

  incus_target
  if [[ "$INCUS_REMOTE" != "local" ]]; then
    incus_msg_custom "ℹ️" "${YW:-}" "Target: Incus remote '${INCUS_REMOTE}' (${INCUS_SERVER_ARCH:-unknown architecture})"
  fi
}

# ==============================================================================
# SECTION 3: EXECUTION HELPERS
# ==============================================================================

# ------------------------------------------------------------------------------
# get_active_incus_logfile()
#
# - Returns the appropriate log file based on execution context
# ------------------------------------------------------------------------------
get_active_incus_logfile() {
  if [[ -n "${_INCUS_HOST_LOGFILE:-}" ]]; then
    echo "$_INCUS_HOST_LOGFILE"
  elif [[ -n "${INCUS_INSTALL_LOG:-}" ]]; then
    echo "$INCUS_INSTALL_LOG"
  elif [[ -n "${INCUS_BUILD_LOG:-}" ]]; then
    echo "$INCUS_BUILD_LOG"
  else
    echo "/tmp/incus-build-$(date +%Y%m%d_%H%M%S).log"
  fi
}

INCUS_SILENT_LOGFILE="$(get_active_incus_logfile)"

# ------------------------------------------------------------------------------
# incus_strip_ansi()
#
# - Removes ANSI escape sequences from input text
# ------------------------------------------------------------------------------
incus_strip_ansi() {
  if [[ $# -gt 0 ]]; then
    echo -e "$*" | sed 's/\x1b\[[0-9;]*m//g; s/\x1b\[[0-9;]*[a-zA-Z]//g'
  else
    sed 's/\x1b\[[0-9;]*m//g; s/\x1b\[[0-9;]*[a-zA-Z]//g'
  fi
}

# ------------------------------------------------------------------------------
# incus_log_msg()
#
# - Writes message to active log file without ANSI codes
# - Adds timestamp prefix for log correlation
# ------------------------------------------------------------------------------
incus_log_msg() {
  local msg="$*"
  local logfile
  logfile="$(get_active_incus_logfile)"

  [[ -z "$msg" ]] && return
  [[ -z "$logfile" ]] && return

  mkdir -p "$(dirname "$logfile")" 2>/dev/null || true

  local clean_msg
  clean_msg=$(incus_strip_ansi "$msg")
  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $clean_msg" >>"$logfile"
}

# ------------------------------------------------------------------------------
# incus_log_section()
#
# - Writes a section header to the log file
# ------------------------------------------------------------------------------
incus_log_section() {
  local section="$1"
  local logfile
  logfile="$(get_active_incus_logfile)"

  [[ -z "$logfile" ]] && return
  mkdir -p "$(dirname "$logfile")" 2>/dev/null || true

  {
    echo ""
    echo "================================================================================"
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $section"
    echo "================================================================================"
  } >>"$logfile"
}

# ------------------------------------------------------------------------------
# incus_silent()
#
# - Executes command with output redirected to active log file
# - On error: displays last 20 lines of log and exits with original exit code
# ------------------------------------------------------------------------------
incus_silent() {
  local cmd="$*"
  local caller_line="${BASH_LINENO[0]:-unknown}"
  local logfile="$(get_active_incus_logfile)"

  set +Eeuo pipefail
  trap - ERR

  "$@" >>"$logfile" 2>&1
  local rc=$?

  set -Eeuo pipefail
  trap 'incus_error_handler' ERR

  if [[ $rc -ne 0 ]]; then
    printf "\e[?25h"
    incus_msg_error "in line ${caller_line}: exit code ${rc}"
    incus_msg_custom "→" "${YWB}" "${cmd}"

    if [[ -s "$logfile" ]]; then
      echo -e "\n${TAB}--- Last 20 lines of log ---"
      tail -n 20 "$logfile"
      echo -e "${TAB}-----------------------------------"
      echo -e "${TAB}📋 Full log: ${logfile}\n"
    fi

    exit "$rc"
  fi
}

# ------------------------------------------------------------------------------
# incus_spinner() / incus_stop_spinner()
#
# - Animated spinner for long-running operations
# ------------------------------------------------------------------------------
incus_spinner() {
  hash -r 2>/dev/null || true
  local chars=(⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏)
  local msg
  msg="$(_msg_fit "${SPINNER_MSG:-Processing...}" 4)"
  local i=0
  while true; do
    local index=$((i++ % ${#chars[@]}))
    printf "\r\033[2K%s %b" "${CS_YWB}${chars[$index]}${CS_CL}" "${CS_YWB}${msg}${CS_CL}"
    sleep 0.1 2>/dev/null || command sleep 0.1 2>/dev/null || break
  done
}

incus_clear_line() {
  tput cr 2>/dev/null || echo -en "\r"
  tput el 2>/dev/null || echo -en "\033[K"
}

incus_stop_spinner() {
  local pid="${SPINNER_PID:-}"
  [[ -z "$pid" && -f /tmp/.incus_spinner.pid ]] && pid=$(</tmp/.incus_spinner.pid)

  if [[ -n "$pid" && "$pid" =~ ^[0-9]+$ ]]; then
    if kill "$pid" 2>/dev/null; then
      sleep 0.05
      kill -9 "$pid" 2>/dev/null || true
      wait "$pid" 2>/dev/null || true
    fi
    rm -f /tmp/.incus_spinner.pid
  fi

  unset SPINNER_PID SPINNER_MSG
  stty sane 2>/dev/null || true
}

# ==============================================================================
# SECTION 4: MESSAGE OUTPUT (Incus-prefixed for namespace safety)
# ==============================================================================

# ------------------------------------------------------------------------------
# incus_msg_info()
#
# - Displays informational message with spinner animation
# ------------------------------------------------------------------------------
incus_msg_info() {
  local msg="$1"
  [[ -z "$msg" ]] && return

  if ! declare -p INCUS_MSG_INFO_SHOWN &>/dev/null || ! declare -A INCUS_MSG_INFO_SHOWN &>/dev/null; then
    declare -gA INCUS_MSG_INFO_SHOWN=()
  fi
  local sanitized_key
  sanitized_key=$(printf '%s' "$msg" | sed 's/\x1b\[[0-9;]*m//g; s/[^a-zA-Z0-9_]/_/g')
  [[ -n "${INCUS_MSG_INFO_SHOWN["$sanitized_key"]+x}" ]] && return
  INCUS_MSG_INFO_SHOWN["$sanitized_key"]=1

  incus_log_msg "[INFO] $msg"

  incus_stop_spinner
  SPINNER_MSG="$msg"

  if incus_is_verbose_mode; then
    local HOURGLASS="${TAB}⏳${TAB}"
    printf "\r\e[2K%s %b" "$HOURGLASS" "${YW}${msg}${CL}" >&2

    if [[ "${DEV_MODE_PAUSE:-false}" == "true" ]]; then
      echo -en "\n${YWB}[PAUSE]${CL} Press Enter to continue..." >&2
      read -r </dev/tty
    fi
    return
  fi

  incus_color_spinner
  incus_spinner &
  SPINNER_PID=$!
  echo "$SPINNER_PID" >/tmp/.incus_spinner.pid
  disown "$SPINNER_PID" 2>/dev/null || true
}

# ------------------------------------------------------------------------------
# incus_msg_ok()
# ------------------------------------------------------------------------------
incus_msg_ok() {
  local msg="$1"
  [[ -z "$msg" ]] && return
  incus_stop_spinner
  incus_clear_line
  # Match core.func: CM already includes TAB before/after the icon — no extra space.
  echo -e "$CM${GN}${msg}${CL}"
  incus_log_msg "[OK] $msg"
  local sanitized_key
  sanitized_key=$(printf '%s' "$msg" | sed 's/\x1b\[[0-9;]*m//g; s/[^a-zA-Z0-9_]/_/g')
  unset 'INCUS_MSG_INFO_SHOWN['"$sanitized_key"']' 2>/dev/null || true
}

# ------------------------------------------------------------------------------
# incus_msg_error()
# ------------------------------------------------------------------------------
incus_msg_error() {
  incus_stop_spinner
  local msg="$1"
  echo -e "${BFR:-}${CROSS:-✖️}${RD}${msg}${CL}" >&2
  incus_log_msg "[ERROR] $msg"
}

# ------------------------------------------------------------------------------
# incus_msg_warn()
# ------------------------------------------------------------------------------
incus_msg_warn() {
  incus_stop_spinner
  local msg="$1"
  # Same layout as core.func msg_warn (INFO already includes TAB padding).
  echo -e "${BFR:-}${INFO:-ℹ️} ${YWB}${msg}${CL}" >&2
  incus_log_msg "[WARN] $msg"
}

# ------------------------------------------------------------------------------
# incus_msg_custom()
# ------------------------------------------------------------------------------
incus_msg_custom() {
  local symbol="${1:-"[*]"}"
  local color="${2:-"\e[36m"}"
  local msg="${3:-}"
  [[ -z "$msg" ]] && return
  incus_stop_spinner
  # Same indentation as CM/CROSS: TAB + icon + TAB + message
  echo -e "${BFR:-}${TAB:-  }${symbol}${TAB:-  }${color}${msg}${CL:-\e[0m}"
  incus_log_msg "$msg"
}

# ------------------------------------------------------------------------------
# incus_msg_debug()
# ------------------------------------------------------------------------------
incus_msg_debug() {
  if [[ "${var_full_verbose:-0}" == "1" ]]; then
    [[ "${var_verbose:-0}" != "1" ]] && var_verbose=1
    echo -e "${YWB}[$(date '+%F %T')] [DEBUG]${CL} $*"
  fi
}

# ------------------------------------------------------------------------------
# incus_msg_dev()
# ------------------------------------------------------------------------------
incus_msg_dev() {
  if [[ -n "${dev_mode:-}" ]]; then
    echo -e "${SEARCH}${BOLD}${DGN}🔧 [DEV]${CL} $*"
  fi
}

# ------------------------------------------------------------------------------
# incus_is_verbose_mode()
# ------------------------------------------------------------------------------
incus_is_verbose_mode() {
  local verbose="${VERBOSE:-${var_verbose:-no}}"
  [[ "$verbose" != "no" || ! -t 2 ]]
}

# ------------------------------------------------------------------------------
# incus_is_unattended()
# ------------------------------------------------------------------------------
incus_is_unattended() {
  local mode="${MODE:-${mode:-}}"
  mode="${mode,,}"

  case "$mode" in
  default | 1 | mydefaults | userdefaults | 3 | appdefaults | 4)
    return 0
    ;;
  advanced | 2)
    # On Incus host: advanced remains interactive.
    # Inside container install phase (incus command unavailable): unattended.
    if command -v incus >/dev/null 2>&1; then
      return 1
    fi
    return 0
    ;;
  esac

  [[ "${PHS_SILENT:-0}" == "1" ]] && return 0
  [[ "${var_unattended:-}" =~ ^(yes|true|1)$ ]] && return 0
  [[ "${UNATTENDED:-}" =~ ^(yes|true|1)$ ]] && return 0
  [[ ! -t 0 ]] && return 0
  return 1
}

# ------------------------------------------------------------------------------
# incus_fatal()
# ------------------------------------------------------------------------------
incus_fatal() {
  incus_msg_error "$1"
  # kill -INT $$ alone does not stop a non-interactive bash script: the signal
  # arrives but execution continues, so callers assuming "fatal ends here" ran
  # on into a broken state. Signal first, to reach the main shell from a
  # subshell, then exit.
  kill -INT $$ 2>/dev/null || true
  exit 1
}

# ==============================================================================
# SECTION 5: INCUS-SPECIFIC UTILITIES
# ==============================================================================

# ------------------------------------------------------------------------------
# incus_get_storage_pools()
#
# - Returns list of available Incus storage pools
# ------------------------------------------------------------------------------
incus_get_storage_pools() {
  incus storage list -f csv,noheader 2>/dev/null | cut -d, -f1
}

# ------------------------------------------------------------------------------
# incus_get_networks()
#
# - Returns list of available Incus networks
# ------------------------------------------------------------------------------
incus_get_networks() {
  incus network list -f csv,noheader 2>/dev/null | grep -v '^lo$' | cut -d, -f1
}

# Prints the first member of a bridge that is not a guest interface, so a
# caller can tell a LAN bridge from a private one. A bridge carrying a physical
# NIC or a VLAN reaches the network; one holding only veth and tap devices does
# not. That is what separates a hand-built br0 or br20 from docker0, and it
# beats matching on names.
_incus_bridge_uplink() {
  local br="${1:?bridge}" m
  while IFS= read -r m; do
    [[ -z "$m" ]] && continue
    case "$m" in
    veth* | tap* | vnet* | vif* | macvtap*) continue ;;
    esac
    echo "$m"
    return 0
  done < <(ip -o link show master "$br" 2>/dev/null | awk -F'[:@ ]+' '{print $2}')
  return 1
}

# ------------------------------------------------------------------------------
# incus_default_profile_network()
#
# - Prints the network the `default` profile's nic device is attached to
# - Empty when the profile has no nic device, or Incus is unreachable
#
# `incus profile show default` is the honest answer to "what does this host
# actually put an instance on": it is the profile every create uses when none
# is named, so it is where the operator's own containers came from. A managed
# network is named by the nic's `network` key, a hand-built bridge by `parent`.
# ------------------------------------------------------------------------------
incus_default_profile_network() {
  incus profile show default 2>/dev/null | awk '
    function emit() { if (!done && dtype == "nic" && dnet != "") { print dnet; done = 1 } }
    function val(s) { sub(/^[^:]*:[[:space:]]*/, "", s); gsub(/^"|"$/, "", s); return s }
    /^devices:/ { indev = 1; next }
    indev && /^[^[:space:]]/ { emit(); indev = 0 }
    !indev { next }
    /^  [^[:space:]]/ { emit(); dtype = ""; dnet = ""; next }
    /^    network:/ { dnet = val($0); next }
    /^    parent:/ { if (dnet == "") dnet = val($0); next }
    /^    type:/ { dtype = val($0); next }
    END { emit() }
  '
}

# ------------------------------------------------------------------------------
# incus_network_candidates()
#
# - Prints the networks a new instance can sensibly be attached to, best first
# - Returns 1 when the host offers none
#
# `incus network list` also reports plain host interfaces as type physical, and
# attaching one moves the host's NIC into the instance - which an unprivileged
# container cannot start with, and which would cut the host off if it could.
# Picking the uplink is a decision for the operator, never a default.
#
# Unmanaged bridges do belong here though. A br0 or br20 built by hand in
# netplan is precisely the bridge people want, and requiring managed:true
# discarded it -- which is how an AdGuard container ended up behind NAT on a
# host that had a working LAN bridge sitting right next to it.
#
# Ranking, worst candidate last: a managed network with ipv4.nat is reachable
# from this host and from nowhere else, so it only wins when nothing else is
# offered. Within a class, the bridge that already carries instances wins.
# ------------------------------------------------------------------------------
incus_network_candidates() {
  local nets n cfg used pref
  nets=$(incus network list -f csv,noheader 2>/dev/null | cut -d, -f1 | sed '/^[[:space:]]*$/d' | grep -v '^lo$' || true)
  [[ -z "$nets" ]] && return 1

  local -a uplink=() lan=() nated=()
  while IFS= read -r n; do
    [[ -z "$n" ]] && continue
    cfg=$(LC_ALL=C incus network show "$n" 2>/dev/null || true)
    grep -qE '^type:[[:space:]]*bridge$' <<<"$cfg" || continue

    # used_by lists every instance and profile referencing the network. Only
    # the instances say anything about where this host's guests live.
    used=$(grep -cE '^-[[:space:]]+/1\.0/instances/' <<<"$cfg" || true)

    if grep -qE '^managed:[[:space:]]*true$' <<<"$cfg"; then
      if grep -qE '^[[:space:]]+ipv[46]\.nat:[[:space:]]*"?true"?' <<<"$cfg"; then
        nated+=("${used:-0} $n")
      else
        lan+=("${used:-0} $n")
      fi
    elif _incus_bridge_uplink "$n" >/dev/null; then
      uplink+=("${used:-0} $n")
    fi
    # An unmanaged bridge with no uplink is docker0 or a compose network.
    # Reachable from nothing that matters, so it is never offered.
  done <<<"$nets"

  local -a ranked=()
  while IFS= read -r n; do
    [[ -n "$n" ]] && ranked+=("$n")
  done < <(printf '%s\n' "${uplink[@]}" "${lan[@]}" "${nated[@]}" | sed '/^[[:space:]]*$/d' | sort -s -k1,1nr | cut -d' ' -f2-)
  ((${#ranked[@]})) || return 1

  # The default profile's network goes first when it is one of the candidates
  # and not the NATed one -- that last exception is the whole point of the
  # ordering above, and a default profile still pointing at incusbr0 is the
  # normal state of a host nobody has reconfigured.
  pref=$(incus_default_profile_network 2>/dev/null || true)
  if [[ -n "$pref" && "${ranked[0]}" != "$pref" ]]; then
    local -a promoted=()
    for n in "${uplink[@]}" "${lan[@]}"; do
      [[ "${n#* }" == "$pref" ]] && promoted=("$pref")
    done
    if ((${#promoted[@]})); then
      for n in "${ranked[@]}"; do
        [[ "$n" == "$pref" ]] || promoted+=("$n")
      done
      ranked=("${promoted[@]}")
    fi
  fi

  printf '%s\n' "${ranked[@]}"
  return 0
}

# ------------------------------------------------------------------------------
# incus_pick_default_network()
#
# - Prints the single best network for a new instance
# - Always prints something; incusbr0 is the last resort
# ------------------------------------------------------------------------------
incus_pick_default_network() {
  local n first="" cands
  cands=$(incus_network_candidates 2>/dev/null || true)
  [[ -z "$cands" ]] && {
    echo "incusbr0"
    return 0
  }
  while IFS= read -r n; do
    [[ -z "$n" ]] && continue
    [[ -z "$first" ]] && first="$n"
    [[ "$n" == "incusbr0" ]] && continue
    echo "$n"
    return 0
  done <<<"$cands"
  echo "${first:-incusbr0}"
  return 0
}

# ------------------------------------------------------------------------------
# incus_get_profiles()
#
# - Returns list of available Incus profiles
# ------------------------------------------------------------------------------
incus_get_profiles() {
  incus profile list -f csv,noheader 2>/dev/null | cut -d, -f1
}

# ------------------------------------------------------------------------------
# incus_get_images()
#
# - Returns list of locally cached Incus images
# ------------------------------------------------------------------------------
incus_get_images() {
  incus image list -f csv,noheader 2>/dev/null | cut -d, -f1,2
}

# ------------------------------------------------------------------------------
# incus_get_os_info()
#
# - Returns OS info from /etc/os-release
# - Usage: incus_get_os_info id|codename|version
# ------------------------------------------------------------------------------
incus_get_os_info() {
  local field="$1"
  case "$field" in
  id)
    . /etc/os-release 2>/dev/null && echo "${ID:-debian}"
    ;;
  codename)
    . /etc/os-release 2>/dev/null && echo "${VERSION_CODENAME:-bookworm}"
    ;;
  version)
    . /etc/os-release 2>/dev/null && echo "${VERSION_ID:-12}"
    ;;
  *)
    echo ""
    ;;
  esac
}

# ------------------------------------------------------------------------------
# incus_get_ip()
#
# - Returns current container IP
# ------------------------------------------------------------------------------
incus_get_ip() {
  local ip=""
  # Try IPv4 first
  ip=$(hostname -I 2>/dev/null | tr ' ' '\n' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$' | head -n1)
  # Fallback to IPv6
  if [[ -z "$ip" ]]; then
    ip=$(hostname -I 2>/dev/null | tr ' ' '\n' | grep -E ':' | head -n1)
  fi
  [[ -z "$ip" ]] && ip="Unknown"
  echo "$ip"
}

# ------------------------------------------------------------------------------
# incus_ensure_profile_loaded()
#
# - Sources /etc/profile.d/*.sh scripts if not already loaded
# - Fixes PATH issues when running via incus exec (non-login shells)
# ------------------------------------------------------------------------------
incus_ensure_profile_loaded() {
  [[ -n "${_INCUS_PROFILE_LOADED:-}" ]] && return
  command -v incusd &>/dev/null && return

  if [[ -d /etc/profile.d ]]; then
    for script in /etc/profile.d/*.sh; do
      [[ -r "$script" ]] && source "$script"
    done
  fi

  if [[ ":$PATH:" != *":/usr/local/bin:"* ]]; then
    export PATH="/usr/local/bin:$PATH"
  fi

  export _INCUS_PROFILE_LOADED=1
}

# ==============================================================================
# SECTION 6: ERROR HANDLER (minimal)
# ==============================================================================

# ------------------------------------------------------------------------------
# incus_error_handler()
#
# - Basic error trap for Incus scripts
# ------------------------------------------------------------------------------
incus_error_handler() {
  local exit_code=$?
  local line_no=${1:-${BASH_LINENO[0]:-unknown}}
  incus_msg_error "Unexpected error at line $line_no (exit code: $exit_code)"
  incus_msg_custom "→" "${YWB}" "Check log: $(get_active_incus_logfile)"
  exit "$exit_code"
}

# ------------------------------------------------------------------------------
# incus_catch_errors()
#
# - Set up error trapping for Incus scripts
# ------------------------------------------------------------------------------
incus_catch_errors() {
  set -Eeuo pipefail
  trap 'incus_error_handler ${LINENO}' ERR
}

# ==============================================================================
# SECTION 7: COMPATIBILITY ALIASES
# ==============================================================================
#
# These aliases allow existing install scripts to use msg_info/msg_ok/etc
# without modification, by mapping them to incus_* equivalents when running
# in Incus context.
#
# Usage in Incus install scripts:
#   source /dev/stdin <<< "$INCUS_FUNCTIONS"
#   # After this, msg_info/msg_ok/etc all work as normal
# ==============================================================================

incus_install_compat_aliases() {
  # Map standard function names to Incus variants
  # Using eval to create function aliases
  eval 'msg_info() { incus_msg_info "$@"; }'
  eval 'msg_ok() { incus_msg_ok "$@"; }'
  eval 'msg_error() { incus_msg_error "$@"; }'
  eval 'msg_warn() { incus_msg_warn "$@"; }'
  eval 'msg_custom() { incus_msg_custom "$@"; }'
  eval 'msg_debug() { incus_msg_debug "$@"; }'
  eval 'msg_dev() { incus_msg_dev "$@"; }'
  eval 'silent() { incus_silent "$@"; }'
  eval 'log_msg() { incus_log_msg "$@"; }'
  eval 'get_active_logfile() { get_active_incus_logfile; }'
  eval 'ensure_profile_loaded() { incus_ensure_profile_loaded; }'
  eval 'catch_errors() { incus_catch_errors; }'
  eval 'error_handler() { incus_error_handler "$@"; }'
  eval 'fatal() { incus_fatal "$@"; }'
  eval 'color() { incus_color; }'
  eval 'is_verbose_mode() { incus_is_verbose_mode; }'
  eval 'set_std_mode() { incus_set_std_mode; }'
  eval 'formatting() { incus_formatting; }'
  eval 'icons() { incus_icons; }'
  eval 'default_vars() { incus_default_vars; }'
  eval 'color_spinner() { incus_color_spinner; }'
  eval 'strip_ansi() { incus_strip_ansi "$@"; }'
  eval 'log_section() { incus_log_section "$@"; }'
  eval 'spinner() { incus_spinner; }'
  eval 'clear_line() { incus_clear_line; }'
  eval 'stop_spinner() { incus_stop_spinner; }'
  eval 'shell_check() { incus_shell_check; }'
  eval 'root_check() { incus_root_check; }'
  eval 'check() { incus_check; }'
  eval 'pve_check() { incus_check; }'
  eval 'load_functions() { load_incus_functions; }'
  eval 'is_unattended() { incus_is_unattended; }'
  eval 'get_storage_pools() { incus_get_storage_pools; }'
  eval 'get_networks() { incus_get_networks; }'
  eval 'get_profiles() { incus_get_profiles; }'
  eval 'get_images() { incus_get_images; }'
  eval 'get_os_info() { incus_get_os_info "$@"; }'
  eval 'get_ip() { incus_get_ip; }'
  eval 'on_hup_keepalive() { :; }'
}

# ==============================================================================
# SECTION 8: NETWORK & CONTAINER UTILITIES
# ==============================================================================

# ------------------------------------------------------------------------------
# incus_container_exists()
#
# - Checks if an Incus container exists
# - Returns 0 if exists, 1 otherwise
# ------------------------------------------------------------------------------
incus_container_exists() {
  local name="$1"
  incus info "$name" &>/dev/null && return 0 || return 1
}

# ------------------------------------------------------------------------------
# incus_instance_field()
#
# - Prints one `incus list` column for exactly the instance called <name>
# - Usage: incus_instance_field <name> <column-shorthand>   (4 = IPv4, s = state)
#
# `incus list <name>` is not an exact lookup. The manpage describes the
# positional filter as "a single keyword like web which will list any instance
# with a name starting by web", and the client turns it into the regex
# name=(^web$|^web.*) - so a lookup for "haos" also returns "haos-test" and a
# plain head -1 could answer with the wrong instance. Anchoring the regex the
# manpage documents narrows it to one instance server-side; the name column is
# compared here as well because that regex is matched case-insensitively.
# ------------------------------------------------------------------------------
incus_instance_field() {
  local name="${1:?name}" column="${2:?column}" pattern
  printf -v pattern '^%s$' "$name"
  LC_ALL=C incus list "$pattern" --format csv -c "n${column}" 2>/dev/null |
    awk -F, -v want="$name" '$1 == want { print substr($0, length(want) + 2); exit }'
}

# ------------------------------------------------------------------------------
# incus_container_running()
#
# - Checks if an Incus container is running
# - Returns 0 if running, 1 otherwise
# ------------------------------------------------------------------------------
incus_container_running() {
  local name="$1"
  local status
  status=$(incus info "$name" 2>/dev/null | awk '/^Status:/ {print $2}') || true
  # incus info upper-cases the status (cmd/incus/info.go prints
  # strings.ToUpper(inst.Status)) where incus list leaves it title-case, so
  # comparing against either spelling verbatim is wrong for one of them.
  [[ "${status^^}" == "RUNNING" ]]
}

# ------------------------------------------------------------------------------
# incus_get_next_name()
#
# - Generates next available container name from base name
# - Format: <appname>-<increment>
# ------------------------------------------------------------------------------
incus_get_next_name() {
  local base="${1:-incus-ct}"
  local counter=0
  local name="${base}"

  while incus_container_exists "$name"; do
    counter=$((counter + 1))
    name="${base}-${counter}"
  done

  echo "$name"
}

# ------------------------------------------------------------------------------
# incus_get_image_alias()
#
# - Maps var_os + var_version to incus image alias
# - Example: debian/13 -> "Debian 13 (trixie)"
# ------------------------------------------------------------------------------
incus_get_image_alias() {
  local os="${1:-debian}"
  local version="${2:-13}"

  # Convert to lowercase
  os="${os,,}"

  case "$os" in
  debian)
    case "$version" in
    12 | bookworm) echo "bookworm" ;;
    13 | trixie) echo "trixie" ;;
    *) echo "trixie" ;;
    esac
    ;;
  ubuntu)
    case "$version" in
    22.04 | 22 | jammy) echo "jammy" ;;
    24.04 | 24 | noble) echo "noble" ;;
    26.04 | 26 | plucky | resolute) echo "plucky" ;;
    *) echo "noble" ;;
    esac
    ;;
  alpine)
    case "$version" in
    3.19 | 3.20 | 3.21 | 3.22 | 3.23) echo "${version}" ;;
    *) echo "3.21" ;;
    esac
    ;;
  # The ct scripts carry Proxmox template versions; these are the image names.
  archlinux) echo "current" ;;
  centos)
    case "$version" in
    9 | 9-Stream) echo "9-Stream" ;;
    *) echo "10-Stream" ;;
    esac
    ;;
  devuan)
    case "$version" in
    5 | 5.0 | daedalus) echo "daedalus" ;;
    *) echo "excalibur" ;;
    esac
    ;;
  gentoo)
    case "$version" in
    systemd) echo "systemd" ;;
    *) echo "openrc" ;;
    esac
    ;;
  *)
    echo "${version}"
    ;;
  esac
}