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.

# 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)

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

################################################################################
# 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 (run inside devtools container)
  #@ Category: Package Management
  echo "🏗️ Building Debian package..."

  # Create a build area with the project as a subdirectory
  # This allows dpkg-buildpackage to write to the parent directory
  BUILD_AREA=$(mktemp -d)
  PROJECT_NAME=$(basename "$PWD")

  # Copy source to build area
  cp -a . "$BUILD_AREA/$PROJECT_NAME"
  cd "$BUILD_AREA/$PROJECT_NAME"

  # Build the package
  uv sync
  dpkg-buildpackage -us -uc -b

  # Move artifacts back to original directory
  mv "$BUILD_AREA"/*.deb "$BUILD_AREA"/*.buildinfo "$BUILD_AREA"/*.changes "$OLDPWD/" 2>/dev/null || true

  # Cleanup
  rm -rf "$BUILD_AREA"

  echo "✅ Debian package built successfully"
}

function build {
  #@ Build Debian package in Docker container
  #@ Category: Package Management
  echo "🐳 Building Debian package using Docker..."
  devtools ./run build-deb
  echo "✅ Build complete - packages in current directory"
}

function build-docker {
  #@ Build development Docker image
  #@ Category: Package Management
  echo "🐳 Building development Docker image..."
  docker compose -f docker/docker-compose.devtools.yml build devtools
  echo "✅ Docker image built successfully"
}

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

function devtools {
  #@ Run command in devtools container
  #@ Usage: devtools <command> [args]
  #@ Category: Docker
  docker compose -f docker/docker-compose.devtools.yml run --rm devtools "$@"
}

function docker-shell {
  #@ Open interactive shell in development container
  #@ Category: Docker
  echo "🐚 Opening shell in development container..."
  echo "   Working directory: /workspace"
  echo "   Exit with: exit or Ctrl+D"
  echo ""
  devtools bash
}

function docker-clean {
  #@ Remove development Docker containers and images
  #@ Category: Docker
  echo "🧹 Cleaning Docker containers and images..."
  docker compose -f docker/docker-compose.devtools.yml down --rmi all --volumes
  echo "✅ Docker cleanup complete"
}

################################################################################
# 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
  build
  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 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
}

################################################################################
# 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
}

################################################################################
# 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" "Docker" "Development Utilities" "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
}

################################################################################
# Commands end.

# 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