install.bash

#!/usr/bin/env bash

# -----------------------------------------------------------------------------
# install.bash -- v1.1.0
# https://github.com/newbery/uv-python-shims
#
# Copies the project-root ./python shim to:
#   ~/.local/uv-python-shims/python
#
# Then creates shims for "major.minor" versions:
#   python3, python3.9, python3.10, ... python3.14
#
# Safety:
#   A manifest file is written on each successful run:
#     ${DEST_DIR}/.uv-python-shim-manifest
#
#   On the next run, if DEST_DIR contains any items NOT listed in the manifest,
#   the install will warn and exit (to avoid deleting user files).
#
# Control via environmment vars:
#   PAUSE=0.2       : slow down / speed up (seconds). Use PAUSE=0 to disable.
#   DEST_DIR=...    : change install directory
#   SHIM_MODE=copy  : set major.minor shim mode (copy|symlink|wrapper)
#   MINOR_VERSIONS="13 14"  : set major.minor versions to be created
#   UV_PYTHON_SHIMS_FORCE=1 : bypass safety checks and wipe DEST_DIR contents
#
# Default values:
#   PAUSE=0.08
#   DEST_DIR=$HOME/.local/uv-python-shims
#   SHIM_MODE=symlink
#   MINOR_VERSIONS="9 10 11 12 13 14"
# -----------------------------------------------------------------------------

set -euo pipefail

PAUSE="${PAUSE:-0.08}"
SHIM_MODE="${SHIM_MODE:-symlink}"
MINOR_VERSIONS="${MINOR_VERSIONS:-9 10 11 12 13 14}"
UV_PYTHON_SHIMS_FORCE="${UV_PYTHON_SHIMS_FORCE:-}"

SRC_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
DEST_DIR="${DEST_DIR:-$HOME/.local/uv-python-shims}"

SRC_SHIM="${SRC_DIR}/python"
DEST_SHIM="${DEST_DIR}/python"
MANIFEST="${DEST_DIR}/.uv-python-shim-manifest"

pause() {
  [[ "${PAUSE}" == "0" || "${PAUSE}" == "0.0" ]] && return 0
  sleep "${PAUSE}"
}

run_step() {
  local desc="$1"; shift
  pause
  "$@"
  ok "$desc"
  pause
}

create_copy() {
  local name="$1"
  local path="${DEST_DIR}/${name}"
  command cp -f -- "${SRC_SHIM}" "${path}"
  chmod 0755 "${path}"
}

create_symlink() {
  local name="$1"
  command ln -sfn "python" "${DEST_DIR}/${name}"
}

create_wrapper() {
  local name="$1"
  local path="${DEST_DIR}/${name}"
  command cat >"${path}" <<'EOF'
#!/usr/bin/env bash
# generated by uv-python-shim installer
UV_PYTHON_SHIM_INVOKED_AS="$(basename "$0")"
export UV_PYTHON_SHIM_INVOKED_AS
exec "$(dirname "$0")/python" "$@"
EOF
  chmod 0755 "${path}"
}

create_shim() {
  local name="$1"
  case "${SHIM_MODE}" in
    copy)     create_copy "${name}" ;;
    symlink)  create_symlink "${name}" ;;
    wrapper)  create_wrapper "${name}" ;;
  esac
}


# ----------------------------
# Some simple color setup
# ----------------------------

if [[ -t 1 ]]; then
  C_RESET=$'\033[0m'
  C_BOLD=$'\033[1m'
  C_GREEN=$'\033[32m'
  C_YELLOW=$'\033[33m'
  C_RED=$'\033[31m'
  C_CYAN=$'\033[36m'
else
  C_RESET=""; C_BOLD=""; C_GREEN=""; C_YELLOW=""; C_RED=""; C_CYAN=""
fi

info() { printf '%s==>%s %s\n'     "${C_CYAN}${C_BOLD}"  "${C_RESET}"  "$*" ; }
ok()   { printf '%s✔%s %s\n'       "${C_GREEN}"          "${C_RESET}"  "$*" ; }
warn() { printf '%s!%s %s\n'       "${C_YELLOW}"         "${C_RESET}"  "$*" ; }
err()  { printf '%sERROR:%s %s\n'  "${C_RED}${C_BOLD}"   "${C_RESET}"  "$*" >&2; }


# ----------------------------
# Manifest safety helpers
# ----------------------------

is_truthy() {
  case "${1:-}" in
    1|true|TRUE|yes|YES|y|Y|on|ON) return 0 ;;
    *) return 1 ;;
  esac
}

check_denylist() {
  # Refuse to wipe obviously dangerous paths (even with force).
  case "${DEST_DIR}" in
    ""|"/"|"$HOME"|"$HOME/"|"$HOME/.local"|"$HOME/.local/"|"$HOME/.local/bin"|"$HOME/bin")
      err "Refusing to wipe dangerous DEST_DIR: ${DEST_DIR}"
      err "Choose a dedicated directory (default is fine): \$HOME/.local/uv-python-shims"
      exit 1
      ;;
  esac
}

list_items() {
  local p
  shopt -s dotglob nullglob
  for p in "${DEST_DIR}"/*; do
    [[ -e "${p}" ]] || continue
    printf '%s\n' "${p#"${DEST_DIR}"/}"
  done
}

write_manifest() {
  local tmp
  tmp="$(mktemp "${DEST_DIR}/.uv-python-shim-manifest.tmp.XXXXXX")"
  installed=( "python" "python3" )
  for minor in ${MINOR_VERSIONS}; do
    installed+=( "python3.${minor}" )
  done
  installed+=( ".uv-python-shim-manifest" )
  printf '%s\n' "${installed[@]}" >"$tmp"
  command mv -f -- "${tmp}" "${MANIFEST}"
}

load_manifest() {
  if [[ ! -f "${MANIFEST}" ]]; then
    warn "Refusing to modify non-empty directory without manifest: ${DEST_DIR}"
    warn "To proceed (and wipe it), run with: UV_PYTHON_SHIMS_FORCE=1 bash ./install.bash"
    exit 1
  fi
  mapfile -t manifest_items <"${MANIFEST}"
}

validate_manifest() {
  declare -A allowed=()
  local item

  for item in "${manifest_items[@]}"; do
    [[ -n "${item}" ]] || continue
    allowed["${item}"]=1
  done

  while IFS= read -r item; do
    if [[ -z "${allowed[${item}]:-}" ]]; then
      warn "Refusing to modify ${DEST_DIR}: unexpected item not in manifest: ${item}"
      warn "If this directory is dedicated to uv-python-shims:"
      warn "  - remove the unexpected files, OR"
      warn "  - set UV_PYTHON_SHIMS_FORCE=1 to wipe the directory"
      exit 1
    fi
  done < <(list_items)
}

wipe_previous_install() {
  if [[ ! -d "${DEST_DIR}" ]]; then
    return 0
  fi

  # If user opts into force, just wipe DEST_DIR and skip the rest
  if is_truthy "${UV_PYTHON_SHIMS_FORCE}"; then
    check_denylist
    warn "UV_PYTHON_SHIMS_FORCE=1 set; wiping ${DEST_DIR}"
    command rm -rf -- "${DEST_DIR}"
    printf '\n'
    return 0
  fi

  # If DEST_DIR is already empty, just skip the rest
  local items=()
  shopt -s dotglob nullglob
  items=( "${DEST_DIR}"/* )
  if (( ${#items[@]} == 0 )); then
    return 0
  fi

  # Now load and validate manifest
  load_manifest
  validate_manifest

  # If we reach here, it's safe to remove all items listed in the manifest
  local rel
  for rel in "${manifest_items[@]}"; do
    [[ -n "${rel}" ]] || continue
    command rm -f -- "${DEST_DIR}/${rel}"
  done
}


# ----------------------------
# Do the work...
# ----------------------------

info "Install uv python shims"
printf '  Source:      %s\n' "${SRC_SHIM}"
printf '  Destination: %s\n\n' "${DEST_SHIM}"

if [[ ! -f "${SRC_SHIM}" ]]; then
  err "Source shim not found at: ${SRC_SHIM}"
  err "Expected a file named 'python' in the project root next to install.bash"
  exit 1
fi

case "${SHIM_MODE}" in symlink|wrapper|copy) ;;
  *)
    err "Invalid shim-mode: ${SHIM_MODE}"
    err "Allowed values: symlink|wrapper|copy"
    exit 1
    ;;
esac

wipe_previous_install

info "Create main shim"
run_step "Create directory ${DEST_DIR}" mkdir -p "${DEST_DIR}"
run_step "Copy shim to ${DEST_SHIM}" create_copy "python"
printf '\n'

info "Create major.minor shims (SHIM_MODE=${SHIM_MODE})"
run_step "Create ${DEST_DIR}/python3" create_shim "python3"
for minor in ${MINOR_VERSIONS}; do
  run_step "Create ${DEST_DIR}/python3.${minor}" create_shim "python3.${minor}"
done

write_manifest

printf '\n'
info "Done"

cat <<EOF

${C_BOLD}Activate shims${C_RESET}
Add this to your shell startup file:

  export PATH="${DEST_DIR}:\$PATH"

${C_BOLD}Common locations${C_RESET}
  bash: ~/.bashrc (and/or ~/.bash_profile)
  zsh : ~/.zshrc

Then restart your shell, or run:

  export PATH="${DEST_DIR}:\$PATH"

${C_BOLD}Verify result${C_RESET}
  which python
  which python3.11
  python --version
  python3.11 --version

${C_BOLD}Install can be customized${C_RESET}
  PAUSE=0            bash ./install.bash
  PAUSE=0.25         bash ./install.bash
  DEST_DIR=...       bash ./install.bash
  SHIM_MODE=copy     bash ./install.bash
  SHIM_MODE=wrapper  bash ./install.bash
  MINOR_VERSIONS="13 14"   bash ./install.bash
  UV_PYTHON_SHIMS_FORCE=1  bash ./install.bash
EOF