run

#!/usr/bin/env bash
#
# usage: ./run.sh command [argument ...]
#
# Commands used during development / CI.
# Also, executable documentation for project dev practices.
#
# See https://death.andgravity.com/run-sh
# for an explanation of how it works and why it's useful.

################################################################################
# Core Development Commands

function install {
  #@ Install project dependencies and create virtual environment
  #@ Category: Core Development
  uv sync
  uv lock
}

function sync {
  #@ Install dependencies from lock file
  #@ Category: Core Development
  uv sync
}

function lint {
  #@ Run linting (ruff check/format + mypy type checking)
  #@ Category: Core Development
  uv run ruff check src
  uv run ruff format --check src
  mypy # Call mypy function
}

function format {
  #@ Auto-format code with ruff
  #@ Category: Core Development
  uv run ruff check --fix src
  uv run ruff format src
}

function mypy {
  #@ Run type checking only
  #@ Category: Core Development
  uv run mypy --config-file pyproject.toml src
}

function test {
  #@ Run all tests with pytest
  #@ Category: Core Development
  if [ $# -eq 0 ]; then
    # If no arguments provided, run tests only in tests/ directory to avoid config conflicts
    uv run pytest tests/
  else
    # If arguments provided, pass them through
    uv run pytest "$@"
  fi
}

function clean {
  #@ Remove temporary files and caches
  #@ Category: Core Development
  pycache-remove
  dsstore-remove
  mypycache-remove
  ipynbcheckpoints-remove
  pytestcache-remove
  build-remove
}

function version {
  #@ Show current project version
  #@ Category: Core Development
  cat VERSION
}

function bumpversion {
  #@ Bump version using bumpversion tool
  #@ Usage: bumpversion [patch|minor|major] or bumpversion --new-version X.Y.Z patch
  #@ Category: Core Development
  command bumpversion "$@"
}

################################################################################
# Package Management Commands

function build-deb {
  #@ Build Debian package (native)
  #@ Category: Package Management
  echo "🏗️ Building Debian package..."

  # Set up environment
  dev-env

  export DEBEMAIL="info@hatlabs.fi"
  export DEBFULLNAME="Hat Labs CI"
  export PACKAGE_VERSION=$(release-version)
  DEB_VERSION=$(echo "$PACKAGE_VERSION" | sed 's/-\([a-zA-Z]\)/~\1/g')

  # Create a new changelog entry
  dch --newversion "$DEB_VERSION" \
      --distribution stable \
      --force-distribution \
      "Automated release $PACKAGE_VERSION. See GitHub for details."

  dpkg-buildpackage -us -uc -b

  echo "✅ Debian package built successfully"
}

function docker-build-deb {
  #@ Build Debian package using Docker container
  #@ Category: Package Management
  echo "🐳 Building Debian package using Docker..."

  # Use Docker container for Debian packaging
  echo "🐳 Running Debian packaging in Docker container..."
  export DIR_NAME=$(basename "$PWD")
  debtools ./run build-deb

  echo "✅ Docker-based Debian package built successfully"
}

function build-docker-tools {
  #@ Build Docker tools image
  #@ Category: Package Management
  export DIR_NAME=$(basename "$PWD")
  docker compose -f docker/docker-compose.debtools.yml build debtools "$@"
}

################################################################################
# Testing/CI Commands

function ci-check {
  #@ Run CI verification checks (lint + test)
  #@ Category: Testing/CI
  echo "🔍 Running CI verification checks..."
  lint
  test
  echo "✅ CI checks passed"
}

function ci-build {
  #@ Full CI build pipeline (lint + test + package)
  #@ Category: Testing/CI
  echo "🚀 Running full CI build pipeline..."
  clean
  ci-check
  docker-build-deb
  echo "✅ CI build pipeline completed successfully"
}

################################################################################
# Development Utilities Commands

function update-dev-deps {
  #@ Update development dependencies to latest versions
  #@ Category: Development Utilities
  uv add --dev ruff mypy mypy-extensions
}

function update-bindings {
  #@ Update I2C bindings from firmware repo
  #@ Category: Development Utilities
  rm -rf src/halpi2_fw_i2c_postcard
  pushd ../HALPI2-firmware || { echo "Error: ../HALPI2-firmware not found"; exit 1; }
  ./run generate-bindings
  popd
  cp -a ../HALPI2-firmware/halpi2-fw-i2c-postcard/src/halpi2_fw_i2c_postcard src/
}

function push {
  #@ Push code to remote development server
  #@ Category: Development Utilities
  rsync -avP --delete --exclude-from='.gitignore' \
    --exclude='.venv' . halpi2:src/halpid/
}

function pull {
  #@ Pull code from remote development server
  #@ Category: Development Utilities
  rsync -avP --delete --exclude-from='.gitignore' \
    --exclude='.venv' halpi2:src/halpid/ .
}

function dev-env {
  #@ Show/check development environment
  #@ Category: Development Utilities
  _env
}

function debtools {
  #@ Run a command inside the debtools Docker container
  #@ Usage: debtools <command> [args]
  #@ Category: Development Utilities
  export DIR_NAME=$(basename "$PWD")
  docker compose -f docker/docker-compose.debtools.yml run --rm debtools "$@"
}

function bumpversion-dry-run {
  #@ Preview version change without applying
  #@ Usage: bumpversion-dry-run <version>
  #@ Category: Development Utilities
  local new_version="${1:-}"

  if [ -z "$new_version" ]; then
    echo "Error: Version required. Usage: bumpversion-dry-run <new_version>"
    echo "Current version: $(version)"
    echo "Example: ./run bumpversion-dry-run 3.2.0"
    exit 1
  fi

  echo "Current version: $(version)"
  echo "Preview of changes for version $new_version:"
  bump2version --new-version "$new_version" patch --dry-run --verbose
}

################################################################################
# Docker Commands

function build-docker {
  #@ Build the Docker image
  #@ Category: Docker
  echo Building docker ${DOCKER_IMAGE}:${DOCKER_IMAGE_VERSION} ...
  docker build -t ${DOCKER_IMAGE}:${DOCKER_IMAGE_VERSION} . \
    -f ./docker/Dockerfile --no-cache
}

function remove-docker {
  #@ Remove the Docker image
  #@ Category: Docker
  echo Removing docker ${DOCKER_IMAGE}:${DOCKER_IMAGE_VERSION} ...
  docker rmi -f ${DOCKER_IMAGE}:${DOCKER_IMAGE_VERSION}
}

################################################################################
# Setup/Installation Commands

function install-uv {
  #@ Download and install the latest version of uv
  #@ Category: Setup/Installation
  curl -LsSf https://astral.sh/uv/install.sh | sh
}

################################################################################
# Internal cleanup functions (not shown in main help)

function pycache-remove {
  find . -type d -name __pycache__ -exec rm -r {} + 2>/dev/null || true
}

function dsstore-remove {
  find . -type f -name .DS_Store -exec rm {} + 2>/dev/null || true
}

function mypycache-remove {
  find . -type d -name .mypy_cache -exec rm -r {} + 2>/dev/null || true
}

function ipynbcheckpoints-remove {
  find . -type d -name .ipynb_checkpoints -exec rm -r {} + 2>/dev/null || true
}

function pytestcache-remove {
  find . -type d -name .pytest_cache -exec rm -r {} + 2>/dev/null || true
}

function build-remove {
  rm -rf build/ 2>/dev/null || true
}


################################################################################
# Project-specific commands end.

# First, set up the environment.
# (Check the notes at the end when changing this.)

set -o nounset
set -o pipefail
set -o errexit

# Enable this to echo commands as they are executed.
#set -o xtrace

# Change the current directory to the project root.
PROJECT_ROOT=${0%/*}
if [[ $0 != $PROJECT_ROOT && $PROJECT_ROOT != "" ]]; then
  cd "$PROJECT_ROOT"
fi
readonly PROJECT_ROOT=$(pwd)

# Some useful variables.
DOCKER_IMAGE="halpid"
DOCKER_IMAGE_VERSION="latest"

# Store the absolute path to this script (useful for recursion).
readonly SCRIPT="$PROJECT_ROOT/$(basename "$0")"

################################################################################
# Meta-commands and utilities follow.

function help {
  #@ Show help for all available commands (auto-generated)
  #@ Category: Meta
  printf "%s <command> [args]\n\n" "${0}"

  # Extract help information from function comments
  # This automatically generates help from #@ comments in functions
  local -A categories
  local -A descriptions
  local -A usages

  # Parse all functions and their help comments
  while IFS= read -r line; do
    if [[ "$line" =~ ^function[[:space:]]+([^[:space:]{}]+) ]]; then
      current_func="${BASH_REMATCH[1]}"
    elif [[ "$line" =~ ^[[:space:]]*#@[[:space:]]*Category:[[:space:]]*(.+) ]]; then
      categories["$current_func"]="${BASH_REMATCH[1]}"
    elif [[ "$line" =~ ^[[:space:]]*#@[[:space:]]*Usage:[[:space:]]*(.+) ]]; then
      usages["$current_func"]="${BASH_REMATCH[1]}"
    elif [[ "$line" =~ ^[[:space:]]*#@[[:space:]]*(.+) ]] && [[ -z "${descriptions[$current_func]:-}" ]]; then
      descriptions["$current_func"]="${BASH_REMATCH[1]}"
    fi
  done < "$0"

  # Group functions by category and display
  local -A category_funcs
  for func in "${!categories[@]}"; do
    local cat="${categories[$func]}"
    category_funcs["$cat"]+="$func "
  done

  # Display in order of preference
  local ordered_categories=("Core Development" "Testing/CI" "Package Management" "Development Utilities" "Docker" "Setup/Installation" "Meta")

  for category in "${ordered_categories[@]}"; do
    if [[ -n "${category_funcs[$category]:-}" ]]; then
      echo "${category} Commands:"
      for func in ${category_funcs[$category]}; do
        local usage="${usages[$func]:-$func}"
        local desc="${descriptions[$func]:-No description}"
        printf "  %-30s %s\n" "$usage" "$desc"
      done
      echo ""
    fi
  done

  # Handle uncategorized functions
  for func in "${!descriptions[@]}"; do
    if [[ -z "${categories[$func]:-}" ]]; then
      local usage="${usages[$func]:-$func}"
      local desc="${descriptions[$func]}"
      printf "  %-30s %s\n" "$usage" "$desc"
    fi
  done
}

once_hash_array=()
function _once {
  # Run a command only once during the execution of this script, even if it's
  # called multiple times.
  #
  # Usage:
  #   _once <command> [argument ...]
  #
  # Example:
  #   _once echo "Hello"
  #   _once echo "Hello"  # won't be executed

  local command="$*"
  local hash=$(echo "$command" | shasum | cut -d' ' -f1)
  if [[ ! " ${once_hash_array[@]} " =~ " ${hash} " ]]; then
    once_hash_array+=("$hash")
    eval "$command"
  fi
}

compose_flags=""
function _dc {
  docker compose $compose_flags "$@"
}

function _env {
  echo "🗝️ Setting environment from .env and .env.defaults"
  # Go through the files and export all variables not already present in
  # the environment. First file has precedence!
  if [ -f .env ]; then
    _export_unset .env
  else
    # Make sure a .env file exists, otherwise docker-compose will complain
    cp .env.defaults .env
  fi
  if [ -f .env.defaults ]; then
    _export_unset .env.defaults
  fi
}

function _export_unset {
  local file="$1"

  # Need to use a temp file to avoid a subshell
  local tmpfile=$(mktemp)
  grep -v '^#' $file >$tmpfile

  while read -r line; do
    if [[ ! "$line" =~ ^[[:space:]]*$ ]]; then
      varname=$(echo "$line" | cut -d= -f1)
      if [[ -z "${!varname:-}" ]]; then
        eval $line
        export $varname
      fi
    fi
  done <$tmpfile
  rm $tmpfile
}

# Dispatch to command. A simpler version would be just "$@" (with the quotes!).

TIMEFORMAT=$'\nTask completed in %3lR'
time "${@:-help}"

# Some dev notes for this script.
#
# The commands *require*:
#
# * The current working directory is the project root.
# * The shell options and globals are set as they are.
#
# Inspired by the following:
#  - https://death.andgravity.com/run-sh
#  - http://www.oilshell.org/blog/2020/02/good-parts-sketch.html
#  - https://www.youtube.com/watch?v=SdmYd5hJISM&t=7s