alpine.func

#!/bin/ash
# shellcheck shell=ash

# Erwartet vorhandene msg_* und optional $STD aus deinem Framework.

# Fallbacks, wenn core.func nicht geladen wurde (Alpine/ash-safe)
if ! command -v msg_info >/dev/null 2>&1; then
  msg_info() { echo "[INFO] $*"; }
fi
if ! command -v msg_ok >/dev/null 2>&1; then
  msg_ok() { echo "[OK] $*"; }
fi
if ! command -v msg_warn >/dev/null 2>&1; then
  msg_warn() { echo "[WARN] $*"; }
fi
if ! command -v msg_error >/dev/null 2>&1; then
  msg_error() { echo "[ERROR] $*" >&2; }
fi

# ------------------------------------------------------------------------------
# helpers
# ------------------------------------------------------------------------------
lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
has() { command -v "$1" >/dev/null 2>&1; }

# tools.func compatibility helpers (Alpine-safe)
cache_installed_version() {
  local app="$1" version="$2"
  mkdir -p /var/cache/app-versions
  echo "$version" >"/var/cache/app-versions/${app}_version.txt"
}

get_cached_version() {
  local app="$1"
  mkdir -p /var/cache/app-versions
  if [ -f "/var/cache/app-versions/${app}_version.txt" ]; then
    cat "/var/cache/app-versions/${app}_version.txt"
    return 0
  fi
  # 1, not 0. The tools tree returns 1 here, and `if get_cached_version app`
  # was therefore true on Alpine with nothing cached and empty output.
  return 1
}

version_gt() {
  # returns 0 if $1 > $2
  # BusyBox-safe version compare
  awk -v a="$1" -v b="$2" '
  function splitver(v, arr) { n=split(v, arr, /\./); return n }
  BEGIN {
    na=splitver(a, A); nb=splitver(b, B);
    n=(na>nb?na:nb);
    for (i=1;i<=n;i++) {
      va=(A[i]==""?0:A[i]); vb=(B[i]==""?0:B[i]);
      if (va+0 > vb+0) exit 0;
      if (va+0 < vb+0) exit 1;
    }
    exit 1;
  }'
}

# The tools tree takes dpkg|uname|both and defaults to dpkg. Alpine has no
# dpkg, so every mode resolves through uname -- but the argument is accepted
# rather than silently ignored, so a caller written against the other side
# behaves the same here.
get_system_arch() {
  local arch
  arch=$(uname -m 2>/dev/null || echo "")
  [ "$arch" = "x86_64" ] && arch="amd64"
  [ "$arch" = "aarch64" ] && arch="arm64"
  echo "$arch"
}

# The tools tree registers every temp dir for cleanup on exit. Doing nothing
# here leaked one per call, so keep a list and clear it the same way.
_alpine_temp_dirs=()
_alpine_cleanup_temp_dirs() {
  local d
  for d in "${_alpine_temp_dirs[@]}"; do
    [ -n "$d" ] && [ -d "$d" ] && rm -rf "$d"
  done
  _alpine_temp_dirs=()
}

create_temp_dir() {
  local tmp_dir
  tmp_dir=$(mktemp -d) || return 1
  if [ "${_alpine_temp_cleanup_registered:-0}" != "1" ]; then
    trap _alpine_cleanup_temp_dirs EXIT
    _alpine_temp_cleanup_registered=1
  fi
  _alpine_temp_dirs+=("$tmp_dir")
  echo "$tmp_dir"
}

get_os_info() {
  local field="${1:-all}"
  [ -z "${_OS_ID:-}" ] && _OS_ID=$(awk -F= '/^ID=/{gsub(/"/,"",$2); print $2}' /etc/os-release 2>/dev/null)
  [ -z "${_OS_CODENAME:-}" ] && _OS_CODENAME=$(awk -F= '/^VERSION_CODENAME=/{gsub(/"/,"",$2); print $2}' /etc/os-release 2>/dev/null)
  [ -z "${_OS_VERSION:-}" ] && _OS_VERSION=$(awk -F= '/^VERSION_ID=/{gsub(/"/,"",$2); print $2}' /etc/os-release 2>/dev/null)
  # version_full was missing, so asking for it fell through to *) and returned
  # the OS id instead of a version.
  [ -z "${_OS_VERSION_FULL:-}" ] && _OS_VERSION_FULL=$(awk -F= '/^VERSION=/{gsub(/"/,"",$2); print $2}' /etc/os-release 2>/dev/null)
  case "$field" in
  id) echo "$_OS_ID" ;;
  codename) echo "$_OS_CODENAME" ;;
  version | version_id) echo "$_OS_VERSION" ;;
  version_full) echo "$_OS_VERSION_FULL" ;;
  all) echo "ID=$_OS_ID CODENAME=$_OS_CODENAME VERSION=$_OS_VERSION" ;;
  *) echo "$_OS_ID" ;;
  esac
}

is_alpine() { [ "$(get_os_info id)" = "alpine" ]; }

get_os_version_major() {
  local v
  v=$(get_os_info version)
  echo "${v%%.*}"
}

ensure_dependencies() {
  need_tool "$@"
}

download_file() {
  local url="$1" output="$2" max_retries="${3:-3}" show_progress="${4:-false}"
  local i=1
  local curl_opts=(-fsSL)
  [ "$show_progress" = "true" ] && curl_opts=(-fL#)
  while [ $i -le "$max_retries" ]; do
    if curl "${curl_opts[@]}" -o "$output" "$url"; then
      return 0
    fi
    i=$((i + 1))
    [ $i -le "$max_retries" ] && {
      msg_warn "Download failed, retrying... (attempt $((i - 1))/$max_retries)"
      sleep 2
    }
  done
  msg_error "Failed to download: $url"
  # 250, matching lib/system.func. The exit code is what the error handler and
  # the telemetry read; returning 1 filed every Alpine download failure in the
  # same undifferentiated bucket as everything else that returns 1.
  return 250
}

github_api_call() {
  local url="$1" output_file="${2:-/dev/stdout}"
  local max_retries=3 retry_delay=2 attempt=1
  local http_code

  # An array, not a string. The old form built "-H Authorization:Bearer\ $TOKEN"
  # and expanded it unquoted, which split into three words: curl got a valueless
  # header (which it then drops) and the token as a second URL to fetch. Alpine
  # never authenticated, however valid the token was.
  local header_args=()
  [ -n "${GITHUB_TOKEN:-}" ] && header_args=(-H "Authorization: Bearer ${GITHUB_TOKEN}")

  while [ $attempt -le $max_retries ]; do
    # -sSL, not -fsSL. With -f curl exits non-zero on an HTTP error while -w
    # still prints the status, so the old `|| echo 000` appended to it and
    # http_code came out as "404000" -- making the 403 and 404 arms below
    # unreachable. Every failure fell through to the catch-all, and a 404 was
    # retried three times for a URL that was never going to exist.
    # Repeated, not shared: forge.func is not loaded on Alpine.
    local curl_rc
    http_code=$(curl -sSL --connect-timeout 10 --max-time 60 \
      -w "%{http_code}" -o "$output_file" \
      -H "Accept: application/vnd.github+json" \
      -H "X-GitHub-Api-Version: 2022-11-28" \
      "${header_args[@]}" "$url" 2>/dev/null)
    curl_rc=$?
    [ $curl_rc -ne 0 ] && http_code=000
    [ -z "$http_code" ] && http_code=000

    case "$http_code" in
    200) return 0 ;;
    401)
      msg_error "GitHub API authentication failed (HTTP 401)"
      [ -n "${GITHUB_TOKEN:-}" ] && msg_error "GITHUB_TOKEN appears to be invalid or expired"
      return 22
      ;;
    403) [ $attempt -lt $max_retries ] || {
      msg_error "GitHub API rate limit exceeded (HTTP 403)"
      return 22
    } ;;
    404)
      msg_error "GitHub API endpoint not found: $url"
      return 22
      ;;
    *) [ $attempt -lt $max_retries ] || {
      msg_error "GitHub API call failed with HTTP $http_code"
      return 22
    } ;;
    esac
    sleep "$retry_delay"
    retry_delay=$((retry_delay * 2))
    attempt=$((attempt + 1))
  done
  return 22
}

extract_version_from_json() {
  local json="$1" field="${2:-tag_name}" strip_v="${3:-true}" version
  need_tool jq || return 250
  version=$(printf '%s' "$json" | jq -r ".${field} // empty")
  if [ -z "$version" ]; then
    msg_warn "JSON field '${field}' is empty in API response"
    return 250
  fi
  [ "$strip_v" = "true" ] && printf '%s' "${version#v}" || printf '%s' "$version"
}

get_latest_github_release() {
  local repo="$1" strip_v="${2:-true}" tmp rc version
  tmp=$(mktemp) || return 250
  # 22 for "could not reach the API", 250 for "reached it but got no version",
  # the same split lib/forge.func uses. Both used to be 1 here, which the error
  # handler cannot tell apart from any other failure.
  github_api_call "https://api.github.com/repos/${repo}/releases/latest" "$tmp" || {
    msg_warn "GitHub API call failed for ${repo}"
    rm -f "$tmp"
    return 22
  }
  version=$(extract_version_from_json "$(cat "$tmp")" "tag_name" "$strip_v")
  rc=$?
  rm -f "$tmp"
  if [ $rc -ne 0 ] || [ -z "$version" ]; then
    msg_error "Could not determine latest version for ${repo}"
    return 250
  fi
  printf '%s' "$version"
}

need_tool() {
  # usage: need_tool curl jq unzip ...
  # setup missing tools via apk
  local missing=0 t
  for t in "$@"; do
    if ! has "$t"; then missing=1; fi
  done
  if [ "$missing" -eq 1 ]; then
    msg_info "Installing tools: $*"
    apk add --no-cache "$@" >/dev/null 2>&1 || {
      msg_error "apk add failed for: $*"
      return 1
    }
    msg_ok "Tools ready: $*"
  fi
}

net_resolves() {
  # better handling for missing getent on Alpine
  # usage: net_resolves api.github.com
  local host="$1"
  ping -c1 -W1 "$host" >/dev/null 2>&1 || nslookup "$host" >/dev/null 2>&1
}

ensure_usr_local_bin_persist() {
  local PROFILE_FILE="/etc/profile.d/10-localbin.sh"
  if [ ! -f "$PROFILE_FILE" ]; then
    echo 'case ":$PATH:" in *:/usr/local/bin:*) ;; *) export PATH="/usr/local/bin:$PATH";; esac' >"$PROFILE_FILE"
    chmod +x "$PROFILE_FILE"
  fi

  for rc_file in /root/.profile /root/.bashrc; do
    if [ -f "$rc_file" ] && ! grep -q '/usr/local/bin' "$rc_file"; then
      echo 'export PATH="/usr/local/bin:$PATH"' >>"$rc_file"
    fi
  done
}

download_with_progress() {
  # $1 url, $2 dest
  local url="$1" out="$2" content_length
  need_tool curl pv || return 1

  content_length=$(
    curl -fsSLI "$url" 2>/dev/null |
      awk '(tolower($1) ~ /^content-length:/) && ($2 + 0 > 0) {print $2+0}' |
      tail -1 | tr -cd '[:digit:]' || true
  )

  if [ -n "$content_length" ]; then
    curl -fsSL "$url" | pv -s "$content_length" >"$out" || {
      msg_error "Download failed: $url"
      return 1
    }
  else
    curl -fsSL -o "$out" "$url" || {
      msg_error "Download failed: $url"
      return 1
    }
  fi
}

# ------------------------------------------------------------------------------
# GitHub: check Release
# ------------------------------------------------------------------------------
check_for_gh_release() {
  # app, repo, [pinned]
  local app="$1" source="$2" pinned="${3:-}"
  local app_lc
  app_lc="$(lower "$app" | tr -d ' ')"
  local current_file="$HOME/.${app_lc}"
  local current="" release tag

  msg_info "Check for update: $app"

  net_resolves api.github.com || {
    msg_error "DNS/network error: api.github.com"
    return 1
  }
  need_tool curl jq || return 1

  github_api_call "https://api.github.com/repos/${source}/releases/latest" "/tmp/${app_lc}-release.json" || {
    msg_error "Unable to fetch latest tag for $app"
    return 1
  }
  tag=$(cat "/tmp/${app_lc}-release.json" | jq -r '.tag_name // empty')
  rm -f "/tmp/${app_lc}-release.json"
  [ -z "$tag" ] && {
    msg_error "Unable to fetch latest tag for $app"
    return 1
  }
  release="${tag#v}"

  [ -f "$current_file" ] && current="$(cat "$current_file")"

  if [ -n "$pinned" ]; then
    if [ "$pinned" = "$release" ]; then
      msg_ok "$app pinned to v$pinned (no update)"
      return 1
    fi
    if [ "$current" = "$pinned" ]; then
      msg_ok "$app pinned v$pinned installed (upstream v$release)"
      return 1
    fi
    msg_ok "$app pinned v$pinned (upstream v$release) → update/downgrade"
    CHECK_UPDATE_RELEASE="$pinned"
    return 0
  fi

  if [ "$release" != "$current" ] || [ ! -f "$current_file" ]; then
    CHECK_UPDATE_RELEASE="$release"
    msg_ok "New release available: v$release (current: v${current:-none})"
    return 0
  fi

  msg_ok "$app is up to date (v$release)"
  return 1
}

# Empty a target directory before a clean install, leaving mount points and
# CLEAN_INSTALL_KEEP paths alone, as in lib/forge.func.
_cs_mounts_under() {
  local dir="${1:?directory}" info="${3:-/proc/self/mountinfo}" mnt _
  local -n _cs_mounts="${2:?array name}"
  _cs_mounts=()
  [[ -r "$info" ]] || return 1
  while read -r _ _ _ _ mnt _; do
    printf -v mnt '%b' "$mnt"
    [[ "$mnt" == "$dir"/* ]] && _cs_mounts+=("$mnt")
  done <"$info"
  return 0
}

_cs_clean_target_dir() {
  local dir="${1:?directory}" list entry stash=""
  [[ -d "$dir" ]] || return 0
  dir="$(realpath "$dir")" # mountinfo lists resolved paths

  local -a keep=()
  [[ -n "${CLEAN_INSTALL_KEEP:-}" ]] && read -ra keep <<<"$CLEAN_INSTALL_KEEP"
  if ((${#keep[@]})); then
    stash="$(mktemp -d -p "$(dirname "$dir")" .clean-keep.XXXXXX)" || return 1
    for entry in "${keep[@]}"; do
      entry="${entry#/}"
      [[ -n "$entry" && -e "$dir/$entry" ]] || continue
      mkdir -p "$stash/$(dirname "$entry")"
      mv "$dir/$entry" "$stash/$entry" || msg_warn "Could not preserve ${entry}"
    done
  fi

  local -a mounts=() prune=()
  if ! _cs_mounts_under "$dir" mounts; then
    msg_error "Cannot read /proc/self/mountinfo, so ${dir} is not emptied"
    return 1
  fi
  if ((${#mounts[@]} == 0)); then
    find "${dir:?}" -mindepth 1 -maxdepth 1 -print0 | xargs -0 rm -rf --
  else
    # -path takes a pattern, so a literal \ * ? [ in a mount path is escaped.
    local bs='\'
    for entry in "${mounts[@]}"; do
      entry="${entry//"$bs"/"$bs$bs"}"
      entry="${entry//"*"/"$bs*"}"
      entry="${entry//"?"/"$bs?"}"
      entry="${entry//"["/"${bs}["}"
      prune+=(-path "$entry" -prune -o)
    done
    list="$(mktemp)" || return 1
    # Files first, then directories deepest first; rmdir fails on purpose on a parent that holds a mount.
    find "${dir:?}" -mindepth 1 "${prune[@]}" ! -type d -print0 >"$list"
    xargs -0 rm -f -- <"$list"
    find "${dir:?}" -mindepth 1 "${prune[@]}" -type d -print0 >"$list"
    sort -rz "$list" | xargs -0 rmdir -- 2>/dev/null || true
    rm -f "$list"
  fi

  if [[ -n "$stash" ]]; then
    for entry in "${keep[@]}"; do
      entry="${entry#/}"
      [[ -n "$entry" && -e "$stash/$entry" ]] || continue
      mkdir -p "$dir/$(dirname "$entry")"
      mv "$stash/$entry" "$dir/$entry" || msg_warn "Could not restore ${entry}"
    done
    rm -rf "$stash"
  fi
}

# ------------------------------------------------------------------------------
# GitHub: get Release  & deployen (Alpine)
# modes: tarball | prebuild | singlefile
# ------------------------------------------------------------------------------
fetch_and_deploy_gh_release() {
  # $1 app, $2 repo, [$3 mode], [$4 version], [$5 target], [$6 asset_pattern
  local app="$1" repo="$2" mode="${3:-tarball}" version="${4:-latest}" target="${5:-/opt/$1}" pattern="${6:-}"
  local app_lc
  app_lc=$(lower "$app" | tr -d ' ')
  local vfile="$HOME/.${app_lc}"
  local json url filename tmpd unpack

  net_resolves api.github.com || {
    msg_error "DNS/network error"
    return 1
  }
  need_tool curl jq tar || return 1
  [ "$mode" = "prebuild" ] || [ "$mode" = "singlefile" ] && need_tool unzip >/dev/null 2>&1 || true

  tmpd=$(mktemp -d) || return 1
  mkdir -p "$target"

  # Release JSON (with token/rate-limit handling)
  if [ "$version" = "latest" ]; then
    github_api_call "https://api.github.com/repos/$repo/releases/latest" "$tmpd/release.json" || {
      msg_error "GitHub API failed"
      rm -rf "$tmpd"
      return 1
    }
  else
    github_api_call "https://api.github.com/repos/$repo/releases/tags/$version" "$tmpd/release.json" || {
      msg_error "GitHub API failed"
      rm -rf "$tmpd"
      return 1
    }
  fi
  json=$(cat "$tmpd/release.json")

  # correct Version
  version=$(printf '%s' "$json" | jq -r '.tag_name // empty')
  version="${version#v}"

  [ -z "$version" ] && {
    msg_error "No tag in release json"
    rm -rf "$tmpd"
    return 1
  }

  get_url() {
    # Convert glob-style pattern to awk ERE:
    # protect existing .* → escape literal . → convert remaining * to .* → restore .*
    local _re
    _re=$(printf '%s' "$pattern" |
      sed 's/\.\*/__DS__/g; s/\./\\./g; s/\*/.*/g; s/__DS__/.*/g')
    printf '%s' "$json" | jq -r '.assets[].browser_download_url' |
      awk -v p="$_re" 'BEGIN{IGNORECASE=1} $0 ~ p {print; exit}' |
      tr -d '[:cntrl:]'
  }

  case "$mode" in
  tarball | source)
    url=$(printf '%s' "$json" | jq -r '.tarball_url // empty')
    [ -z "$url" ] && url="https://github.com/$repo/archive/refs/tags/v$version.tar.gz"
    filename="${app_lc}-${version}.tar.gz"
    download_with_progress "$url" "$tmpd/$filename" || {
      rm -rf "$tmpd"
      return 1
    }
    tar -xzf "$tmpd/$filename" -C "$tmpd" || {
      msg_error "tar extract failed"
      rm -rf "$tmpd"
      return 1
    }
    unpack=$(find "$tmpd" -mindepth 1 -maxdepth 1 -type d | head -n1)
    if [ -z "$unpack" ] || [ -z "$(find "$unpack" -mindepth 1 | head -n1)" ]; then
      msg_error "Archive has no payload: $filename"
      rm -rf "$tmpd"
      return 1
    fi
    [ "${CLEAN_INSTALL:-0}" = "1" ] && _cs_clean_target_dir "$target"
    # copy content of unpack to target
    (cd "$unpack" && tar -cf - .) | (cd "$target" && tar -xf -) || {
      msg_error "copy failed"
      rm -rf "$tmpd"
      return 1
    }
    ;;
  binary)
    [ -n "$pattern" ] || pattern="*.apk"
    url=$(get_url) || true
    [ -z "$url" ] && {
      msg_error "binary asset not found for pattern: $pattern"
      rm -rf "$tmpd"
      return 1
    }
    filename="${url##*/}"
    download_with_progress "$url" "$tmpd/$filename" || {
      rm -rf "$tmpd"
      return 1
    }
    case "$filename" in
    *.apk)
      apk add --no-cache --allow-untrusted "$tmpd/$filename" >/dev/null 2>&1 || {
        msg_error "apk install failed: $filename"
        rm -rf "$tmpd"
        return 1
      }
      ;;
    *)
      msg_error "Unsupported binary asset on Alpine: $filename"
      rm -rf "$tmpd"
      return 1
      ;;
    esac
    ;;
  prebuild)
    [ -n "$pattern" ] || {
      msg_error "prebuild requires asset pattern"
      rm -rf "$tmpd"
      return 1
    }
    url=$(get_url) || true
    [ -z "$url" ] && {
      msg_error "asset not found for pattern: $pattern"
      rm -rf "$tmpd"
      return 1
    }
    filename="${url##*/}"
    download_with_progress "$url" "$tmpd/$filename" || {
      rm -rf "$tmpd"
      return 1
    }
    # unpack archive (Zip or tarball)
    case "$filename" in
    *.zip)
      need_tool unzip || {
        rm -rf "$tmpd"
        return 1
      }
      mkdir -p "$tmpd/unp"
      unzip -q "$tmpd/$filename" -d "$tmpd/unp" || {
        msg_error "unzip failed: $filename"
        rm -rf "$tmpd"
        return 1
      }
      ;;
    *.tar.gz | *.tgz | *.tar.xz | *.tar.zst | *.tar.bz2)
      mkdir -p "$tmpd/unp"
      tar -xf "$tmpd/$filename" -C "$tmpd/unp" || {
        msg_error "tar extract failed"
        rm -rf "$tmpd"
        return 1
      }
      ;;
    *)
      msg_error "unsupported archive: $filename"
      rm -rf "$tmpd"
      return 1
      ;;
    esac
    # top-level folder strippen
    unpack="$tmpd/unp"
    if [ "$(find "$tmpd/unp" -mindepth 1 -maxdepth 1 -type d | wc -l)" -eq 1 ] && [ -z "$(find "$tmpd/unp" -mindepth 1 -maxdepth 1 -type f | head -n1)" ]; then
      unpack=$(find "$tmpd/unp" -mindepth 1 -maxdepth 1 -type d)
    fi
    if [ -z "$(find "$unpack" -mindepth 1 | head -n1)" ]; then
      msg_error "Archive has no payload: $filename"
      rm -rf "$tmpd"
      return 1
    fi
    [ "${CLEAN_INSTALL:-0}" = "1" ] && _cs_clean_target_dir "$target"
    (cd "$unpack" && tar -cf - .) | (cd "$target" && tar -xf -) || {
      msg_error "copy failed"
      rm -rf "$tmpd"
      return 1
    }
    ;;
  singlefile)
    [ -n "$pattern" ] || {
      msg_error "singlefile requires asset pattern"
      rm -rf "$tmpd"
      return 1
    }
    url=$(get_url) || true
    [ -z "$url" ] && {
      msg_error "asset not found for pattern: $pattern"
      rm -rf "$tmpd"
      return 1
    }
    filename="${url##*/}"
    local target_file="$app"
    [ "${USE_ORIGINAL_FILENAME:-false}" = "true" ] && target_file="$filename"
    download_with_progress "$url" "$target/$target_file" || {
      rm -rf "$tmpd"
      return 1
    }
    chmod +x "$target/$target_file"
    ;;
  *)
    msg_error "Unknown mode: $mode"
    rm -rf "$tmpd"
    return 1
    ;;
  esac

  echo "$version" >"$vfile"
  ensure_usr_local_bin_persist
  rm -rf "$tmpd"
  msg_ok "Deployed $app ($version) → $target"
}

# tools.func compatibility alias
fetch_and_deploy_gh() {
  fetch_and_deploy_gh_release "$@"
}

# ------------------------------------------------------------------------------
# yq (mikefarah) – Alpine
# ------------------------------------------------------------------------------
setup_yq() {
  # prefer apk, unless FORCE_GH=1
  if [ "${FORCE_GH:-0}" != "1" ] && apk info -e yq >/dev/null 2>&1; then
    msg_info "Updating yq via apk"
    apk add --no-cache --upgrade yq >/dev/null 2>&1 || true
    msg_ok "yq ready ($(yq --version 2>/dev/null))"
    return 0
  fi

  need_tool curl || return 1
  local arch bin url tmp
  case "$(uname -m)" in
  x86_64) arch="amd64" ;;
  aarch64) arch="arm64" ;;
  *)
    msg_error "Unsupported arch for yq: $(uname -m)"
    return 1
    ;;
  esac
  url="https://github.com/mikefarah/yq/releases/latest/download/yq_linux_${arch}"
  tmp="$(mktemp)"
  download_with_progress "$url" "$tmp" || return 1
  install -m 0755 "$tmp" /usr/local/bin/yq
  rm -f "$tmp"
  msg_ok "Setup yq ($(yq --version 2>/dev/null))"
}

# ------------------------------------------------------------------------------
# Adminer – Alpine
# ------------------------------------------------------------------------------
setup_adminer() {
  need_tool curl || return 1
  msg_info "Setup Adminer (Alpine)"
  mkdir -p /var/www/localhost/htdocs/adminer
  curl -fsSL https://github.com/vrana/adminer/releases/latest/download/adminer.php \
    -o /var/www/localhost/htdocs/adminer/index.php || {
    msg_error "Adminer download failed"
    return 1
  }
  msg_ok "Adminer at /adminer (served by your webserver)"
}

# ------------------------------------------------------------------------------
# uv – Alpine (musl tarball)
# optional: PYTHON_VERSION="3.12"
# ------------------------------------------------------------------------------
setup_uv() {
  need_tool curl tar || return 1
  local UV_BIN="/usr/local/bin/uv"
  local arch tarball url tmpd ver installed

  case "$(uname -m)" in
  x86_64) arch="x86_64-unknown-linux-musl" ;;
  aarch64) arch="aarch64-unknown-linux-musl" ;;
  *)
    msg_error "Unsupported arch for uv: $(uname -m)"
    return 1
    ;;
  esac

  # UV_VERSION pins the release, the same prefix the generic setup_uv in
  # lib/runtime.func honours; otherwise the latest one. Resolved through
  # get_latest_github_release so the call retries, uses GITHUB_TOKEN and pulls
  # in jq — the bare curl here printed nothing when jq was absent.
  ver="${UV_VERSION:-}"
  if [ -z "$ver" ]; then
    ver="$(get_latest_github_release "astral-sh/uv")" || {
      msg_error "uv: cannot determine latest version"
      return 1
    }
  fi
  ver="${ver#v}"

  if has "$UV_BIN"; then
    installed="$($UV_BIN -V 2>/dev/null | awk '{print $2}')"
    [ "$installed" = "$ver" ] && {
      msg_ok "uv $ver already installed"
      return 0
    }
    msg_info "Updating uv $installed → $ver"
  else
    msg_info "Setup uv $ver"
  fi

  tmpd="$(mktemp -d)" || return 1
  tarball="uv-${arch}.tar.gz"
  # astral-sh/uv publishes bare tags ("0.13.5"); the "v" was already stripped
  # above, so adding one back here asked GitHub for a tag that does not exist.
  url="https://github.com/astral-sh/uv/releases/download/${ver}/${tarball}"

  download_with_progress "$url" "$tmpd/uv.tar.gz" || {
    rm -rf "$tmpd"
    return 1
  }
  tar -xzf "$tmpd/uv.tar.gz" -C "$tmpd" || {
    msg_error "uv: extract failed"
    rm -rf "$tmpd"
    return 1
  }

  # tar contains ./uv
  if [ -x "$tmpd/uv" ]; then
    install -m 0755 "$tmpd/uv" "$UV_BIN"
  else
    # fallback: in subfolder
    install -m 0755 "$tmpd"/*/uv "$UV_BIN" 2>/dev/null || {
      msg_error "uv binary not found in tar"
      rm -rf "$tmpd"
      return 1
    }
  fi
  rm -rf "$tmpd"
  ensure_usr_local_bin_persist
  msg_ok "Setup uv $ver"

  if [ -n "${PYTHON_VERSION:-}" ]; then
    local match
    match="$(uv python list --only-downloads 2>/dev/null | awk -v maj="$PYTHON_VERSION" '
      $0 ~ "^cpython-"maj"\\." { print $0 }' | awk -F- '{print $2}' | sort -V | tail -n1)"
    [ -z "$match" ] && {
      msg_error "No matching Python for $PYTHON_VERSION"
      return 1
    }
    if ! uv python list | grep -q "cpython-${match}-linux"; then
      msg_info "Installing Python $match via uv"
      uv python install "$match" || {
        msg_error "uv python install failed"
        return 1
      }
      msg_ok "Python $match installed (uv)"
    fi
  fi
}

# ------------------------------------------------------------------------------
# Java – Alpine (OpenJDK)
# JAVA_VERSION: 17|21 (Default 21)
# ------------------------------------------------------------------------------
setup_java() {
  local JAVA_VERSION="${JAVA_VERSION:-21}" pkg
  case "$JAVA_VERSION" in
  17) pkg="openjdk17-jdk" ;;
  21 | *) pkg="openjdk21-jdk" ;;
  esac
  msg_info "Setup Java (OpenJDK $JAVA_VERSION)"
  apk add --no-cache "$pkg" >/dev/null 2>&1 || {
    msg_error "apk add $pkg failed"
    return 1
  }
  # set JAVA_HOME
  local prof="/etc/profile.d/20-java.sh"
  if [ ! -f "$prof" ]; then
    echo 'export JAVA_HOME=$(dirname $(dirname $(readlink -f $(command -v java))))' >"$prof"
    echo 'case ":$PATH:" in *:$JAVA_HOME/bin:*) ;; *) export PATH="$JAVA_HOME/bin:$PATH";; esac' >>"$prof"
    chmod +x "$prof"
  fi
  msg_ok "Java ready: $(java -version 2>&1 | head -n1)"
}

# ------------------------------------------------------------------------------
# Go – Alpine (apk prefers, else tarball)
# ------------------------------------------------------------------------------
setup_go() {
  if [ -z "${GO_VERSION:-}" ]; then
    msg_info "Setup Go (apk)"
    apk add --no-cache go >/dev/null 2>&1 || {
      msg_error "apk add go failed"
      return 1
    }
    msg_ok "Go ready: $(go version 2>/dev/null)"
    return 0
  fi

  need_tool curl tar || return 1
  local ARCH TARBALL URL TMP
  case "$(uname -m)" in
  x86_64) ARCH="amd64" ;;
  aarch64) ARCH="arm64" ;;
  *)
    msg_error "Unsupported arch for Go: $(uname -m)"
    return 1
    ;;
  esac

  # A bare major.minor version (e.g. "1.22", as commonly found in go.mod's `go`
  # directive) has no matching tarball -- go.dev only publishes patch releases
  # (go1.22.12, not go1.22) -- so resolve it to the latest matching patch first.
  if [[ "$GO_VERSION" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
    local go_major="${BASH_REMATCH[1]}" go_minor="${BASH_REMATCH[2]}"
    need_tool jq || return 1
    local go_releases go_patch
    go_releases=$(curl -fsSL "https://go.dev/dl/?mode=json&include=all" 2>/dev/null) || true
    go_patch=$(printf '%s' "$go_releases" | jq -r --arg maj "$go_major" --arg min "$go_minor" '
      [.[] | select(.stable == true) | .version
       | capture("^go(?<maj>[0-9]+)\\.(?<min>[0-9]+)\\.(?<patch>[0-9]+)$")
       | select(.maj == $maj and .min == $min)
       | (.patch | tonumber)]
      | max // empty' 2>/dev/null)
    if [[ -z "$go_patch" ]]; then
      msg_error "Could not resolve latest patch release for Go ${GO_VERSION}.x"
      return 1
    fi
    GO_VERSION="${go_major}.${go_minor}.${go_patch}"
  fi

  TARBALL="go${GO_VERSION}.linux-${ARCH}.tar.gz"
  URL="https://go.dev/dl/${TARBALL}"
  msg_info "Setup Go $GO_VERSION (tarball)"
  TMP="$(mktemp)"
  download_with_progress "$URL" "$TMP" || return 1
  rm -rf /usr/local/go
  tar -C /usr/local -xzf "$TMP" || {
    msg_error "extract go failed"
    rm -f "$TMP"
    return 1
  }
  rm -f "$TMP"
  ln -sf /usr/local/go/bin/go /usr/local/bin/go
  ln -sf /usr/local/go/bin/gofmt /usr/local/bin/gofmt
  ensure_usr_local_bin_persist
  msg_ok "Go ready: $(go version 2>/dev/null)"
}

# ------------------------------------------------------------------------------
# Composer – Alpine
# uses php83-cli + openssl + phar
# ------------------------------------------------------------------------------
setup_composer() {
  local COMPOSER_BIN="/usr/local/bin/composer"
  if ! has php; then
    # prefers php83
    msg_info "Installing PHP CLI for Composer"
    apk add --no-cache php83-cli php83-openssl php83-phar php83-iconv >/dev/null 2>&1 || {
      # Fallback to generic php if 83 not available
      apk add --no-cache php-cli php-openssl php-phar php-iconv >/dev/null 2>&1 || {
        msg_error "Failed to install php-cli for composer"
        return 1
      }
    }
    msg_ok "PHP CLI ready: $(php -v | head -n1)"
  fi

  if [ -x "$COMPOSER_BIN" ]; then
    msg_info "Updating Composer"
  else
    msg_info "Setup Composer"
  fi

  need_tool curl || return 1
  curl -fsSL https://getcomposer.org/installer -o /tmp/composer-setup.php || {
    msg_error "composer installer download failed"
    return 1
  }
  php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer >/dev/null 2>&1 || {
    msg_error "composer install failed"
    return 1
  }
  rm -f /tmp/composer-setup.php
  ensure_usr_local_bin_persist
  msg_ok "Composer ready: $(composer --version 2>/dev/null)"
}