uv

#!/usr/bin/env bash
#
# Lightweight project-local wrapper for uv, with automatic download and
# upgrade capability.
#
# Author: Florian Gamböck <uv-wrapper@mail.floga.de>
# Version: 0.2.0-SNAPSHOT
# Repository: https://github.com/FloGa/uv-wrapper
#
# SPDX-License-Identifier: 0BSD
#
# This file is intentionally license-light to allow frictionless reuse. Feel
# free to copy and paste this script into your own projects and adjust if
# necessary. No attribution or license text is required.

# -e: Fail immediately on error.
# -E: ERR trap is inherited by Shell functions, substitutions, etc.
set -eE

THISDIR=$(dirname "$0")

UV_ARCH=$(uname -m)
case "$UV_ARCH" in
  x86_64 | amd64) UV_ARCH="x86_64" ;;
  aarch64 | arm64) UV_ARCH="aarch64" ;;
  *)
    echo "Unsupported architecture: $UV_ARCH" >&2
    exit 1
    ;;
esac

UV_OS=$(uname -s)
case "$UV_OS" in
  Linux)
    UV_OS="unknown-linux-gnu"
    UV_EXT="tar.gz"
    UV_EXE="uv"
    ;;
  MINGW* | MSYS* | CYGWIN* | Windows_NT)
    UV_OS="pc-windows-msvc"
    UV_EXT="zip"
    UV_EXE="uv.exe"
    ;;
  *)
    echo "Unsupported operating system: $UV_OS" >&2
    exit 1
    ;;
esac

UV_PATH="$THISDIR/.uv"
UV_BIN_DIR="$UV_PATH/bin"
UV_TEMP_DIR="$UV_PATH/temp"

download() {
  echo "Checking required programs"

  local required=(curl sha256sum)

  case "$UV_EXT" in
    zip)
      required+=(unzip)
      unpack() {
        local archive=$1
        local out_dir=$2
        unzip -d "$out_dir" "$archive"
      }
      ;;
    tar.gz)
      required+=(tar gunzip)
      unpack() {
        local archive=$1
        local out_dir=$2
        tar -xzvp --strip-components=1 -C "$out_dir" -f "$archive"
      }
      ;;
  esac

  local cmd
  for cmd in "${required[@]}"; do
    echo "- $cmd"
    if ! command -v "$cmd" >/dev/null; then
      echo "! $cmd is not found, this indicates an incomplete environment"
      echo "! Please report this issue to your friendly neighborhood scripter"
      exit 1
    fi
  done

  echo "Removing previous temporary files"
  rm -rf "$UV_TEMP_DIR"

  mkdir -p "$UV_TEMP_DIR"

  if [ ! "$UV_VERSION" ]; then
    echo "Determine latest version"
    UV_VERSION=$(
      if ! curl -fLs -o /dev/null -w '%{url_effective}' \
        'https://github.com/astral-sh/uv/releases/latest'; then
        {
          echo "! Failed to retrieve latest release version."
          echo "! Maybe the redirect mechanism on GitHub is not working properly."
          echo "! As a quick fix, please specify an existing release manually."
          echo "! URL: https://github.com/astral-sh/uv/releases"
        } >&2
        exit 1
      fi
    )
    UV_VERSION=${UV_VERSION##*/}
    echo "$UV_VERSION" >"$THISDIR/.uv-version"
    echo "- $UV_VERSION"

    if is_uv_installed; then
      echo "Latest version already in place, no download necessary."
      return 0
    fi
  fi

  DOWNLOAD_URL="https://github.com/astral-sh/uv/releases/download/"
  DOWNLOAD_URL+="$UV_VERSION/uv-$UV_ARCH-$UV_OS.$UV_EXT"

  local file_name=${DOWNLOAD_URL##*/}
  local file_path="$UV_PATH/$file_name"

  echo "Downloading $UV_VERSION/$file_name"
  if ! curl -fLo "$file_path.temp" "$DOWNLOAD_URL"; then
    {
      echo "! Failed to download uv release: $UV_VERSION"
      echo "! The release may not exist, or GitHub may be unreachable."
      echo "! Download URL: $DOWNLOAD_URL"
    } >&2
    exit 1
  fi

  echo "Downloading SHA256"
  local uv_checksum
  uv_checksum=$(
    if ! curl -fL "$DOWNLOAD_URL.sha256"; then
      {
        echo "! Failed to download SHA256 checksum for $UV_VERSION."
        echo "! The download cannot be verified without the checksum."
        echo "! For your own safety, the uv-wrapper will not proceed."
        echo "! Download URL: $DOWNLOAD_URL.sha256"
      } >&2
      exit 1
    fi
  )
  uv_checksum=${uv_checksum%% *}

  echo "Check download"
  [ -r "$file_path.temp" ]
  [ "$uv_checksum" ]

  echo "Check hash"
  local checksum
  checksum=$(sha256sum "$file_path.temp")
  # Important workaround for Windows: Sometimes the whole line is prefixed
  # by a backslash to mark certain filenames. This disturbs the check for
  # the correct checksum, so remove it if present.
  checksum=${checksum#\\}
  checksum=${checksum%% *}
  if [ "$checksum" != "$uv_checksum" ]; then
    echo "'$checksum' =! '$uv_checksum'" >&2
    exit 1
  fi

  echo "Finalizing download"
  mv "$file_path.temp" "$file_path"

  echo "Unpacking archive"
  unpack "$file_path" "$UV_TEMP_DIR"

  echo "Check archive content"
  [ -r "$UV_TEMP_DIR/$UV_EXE" ]

  echo "Removing previous binary"
  rm -rf "$UV_BIN_DIR"
  mkdir -p "$UV_BIN_DIR"

  echo "Install uv to local bin"
  mv "$UV_TEMP_DIR/$UV_EXE" "$UV_BIN_DIR"
  chmod +x "$UV_BIN_DIR/$UV_EXE"

  # Note: uvx is ignored here on purpose, since it only makes sense in a
  # global context. uv shall only be called locally in this project.

  echo "Cleaning up temporary files"
  rm -rf "$file_path" "$UV_TEMP_DIR"
}

is_uv_installed() {
  if [ ! "$UV_VERSION" ]; then
    UV_VERSION=$(head -n 1 "$THISDIR/.uv-version" 2>/dev/null || true)

    # Remove leading and trailing whitespaces from the version string
    UV_VERSION=${UV_VERSION#"${UV_VERSION%%[![:space:]]*}"}
    UV_VERSION=${UV_VERSION%"${UV_VERSION##*[![:space:]]}"}

    # Validate UV_VERSION if set. We are only allowing stable versions here. If
    # this is too strict, we can easily remove the following block in the future.
    if [ "$UV_VERSION" ]; then
      if ! [[ "$UV_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
        {
          echo "! Invalid version format in .uv-version: $UV_VERSION"
          echo "! Expected format: X.Y.Z (e.g., 0.1.0)"
          echo "! Leave it empty or remove the file to automatically"
          echo "!   pick the latest release!"
        } >&2
        exit 1
      fi
    fi
  fi

  [ "$UV_VERSION" ] &&
    [ -x "$UV_BIN_DIR/$UV_EXE" ] &&
    [[ "$("$UV_BIN_DIR/$UV_EXE" --version)" = "uv $UV_VERSION "* ]]
}

LOCK_DIR="$UV_PATH/.install.lock"
LOCK_PID_FILE="$LOCK_DIR/pid"
LOCK_HELD=0

read_pid_file() {
  # Lock file might have been deleted by a concurrent process. Check it and
  # return the control back to the caller, but do not bail out completely yet.
  [ -r "$LOCK_PID_FILE" ] || return 1

  if ! cat "$LOCK_PID_FILE"; then
    {
      echo "Lock PID file could not be read: $LOCK_PID_FILE"
      echo "Please check if you have sufficient permissions and try again."
    } >&2
    exit 1
  fi
}

# Use mkdir as the atomic operation for acquiring the lock. The PID file is
# only auxiliary state used for stale-lock detection and diagnostics.
# Note that we cannot simply use flock here, because there are minimal
# environments like git-bash, which do not have flock available!
create_install_lock() {
  local lock_pid

  if [[ -e "$LOCK_DIR" && ! -d "$LOCK_DIR" ]]; then
    # Explicitly use recursive delete here, to handle the case when a parallel
    # instance has already removed the faulty file and created a proper
    # folder. This other instance will go into another waiting cycle by the
    # lock logic.
    if ! rm -rf "$LOCK_DIR"; then
      {
        echo "! Lock directory path cannot be cleared: $LOCK_DIR"
        echo "! Please remove it manually and try again."
      } >&2
      exit 1
    fi
  fi

  # Read back pid after writing it to counter possible race conditions.
  mkdir "$LOCK_DIR" 2>/dev/null &&
    echo "$$" >"$LOCK_PID_FILE" 2>/dev/null &&
    sleep 0.1 && {
    lock_pid=$(read_pid_file) || exit 1
  } &&
    [ "$lock_pid" = "$$" ]
}

release_install_lock() {
  [ "$LOCK_HELD" -eq 1 ] || return 0
  rm -rf "$LOCK_DIR" 2>/dev/null || true
  LOCK_HELD=0
}

acquire_install_lock() {
  mkdir -p "$UV_PATH"

  # Automatically ignore this directory.
  echo "*" >"$UV_PATH/.gitignore"

  local incomplete_lock_detected=
  while ! create_install_lock; do
    # If the other process has already finished, we don't need to wait any
    # longer.
    if is_uv_installed; then
      # Returning 1 here means "no lock acquired because installation is
      # already complete", not "installation failed".
      return 1
    fi

    # Detect stale locks on a best-effort basis. PID reuse can theoretically
    # make an old lock look alive, but this is sufficient for a short-lived
    # project-local installer.
    if [ -r "$LOCK_PID_FILE" ]; then
      local lock_pid
      IFS= read -r lock_pid <"$LOCK_PID_FILE" || true

      if [ "$lock_pid" ] && ! kill -0 "$lock_pid" 2>/dev/null; then
        echo "Removing stale install lock from PID $lock_pid" >&2
        rm -rf "$LOCK_DIR" 2>/dev/null || true
        continue
      fi
    fi

    # Detect an incomplete lock dir, probably due to an aborted previous
    # installation. It is checked for either a missing or an unreadable lock
    # file. We give it a grace period of one cycle, in case another process is
    # currently writing to it.
    if [[ -d "$LOCK_DIR" &&
      (! -e "$LOCK_PID_FILE" || ! -r "$LOCK_PID_FILE") ]]; then
      if [ ! "$incomplete_lock_detected" ]; then
        # Grace period, wait for one cycle before doing anything.
        incomplete_lock_detected=1
      else
        echo "Removing incomplete install lock" >&2
        if ! rm -rf "$LOCK_DIR"; then
          {
            echo "! Lock directory path cannot be cleared: $LOCK_DIR"
            echo "! Please remove it manually and try again."
          } >&2
          exit 1
        fi
        incomplete_lock_detected=
      fi
    else
      incomplete_lock_detected=
    fi

    sleep 1
  done

  LOCK_HELD=1
  return 0
}

ensure_installed() {
  is_uv_installed && return 0

  if acquire_install_lock; then
    # Check again after lock to prevent duplicate download.
    is_uv_installed || download
    release_install_lock
  fi

  is_uv_installed
}

cleanup() {
  local exit_code=$?
  release_install_lock

  if [ "$exit_code" -ne 0 ]; then
    echo "FAILED" >&2
  fi
}

trap cleanup EXIT

ensure_installed >&2

# This is a very opinionated decision. In the author's ideal world, all
# applications talk in UTF-8, but especially Windows does not always follow.
# To avoid conflicts between running this Python project on different
# operating systems, force UTF-8 mode for Python.
export PYTHONUTF8=1
exec "$UV_BIN_DIR/$UV_EXE" --project "$THISDIR" "$@"