devtools

#!/usr/bin/env bash

set -euo pipefail

print_usage() {
  cat <<EOF
devtools — manage the BTC Map Android dev environment.

Usage:
  ./devtools app run               Run the app (desktop by default, under Compose Hot Reload;
                                   --android for Waydroid, which boots it first if needed;
                                   --cold for a plain desktop run)
  ./devtools app deploy-beta       Build and deploy beta packages for the named platforms
  ./devtools app prepare-release   Build the release binaries for every supported platform
  ./devtools app bundle-data       Download latest places, areas, comments and events snapshots
  ./devtools app bundle-map-styles Bundle MapLibre styles, sprites and glyphs (--force re-downloads)
  ./devtools app bundle-icons      Extract the icon-name list from the bundled font
  ./devtools website deploy        Build the Hugo site and rsync it to android.btcmap.org
EOF
}

err() {
  echo "Error: $*" >&2
}

print_usage_app() {
  cat <<EOF
Usage: ./devtools app <command>

Commands:
  run                Run the app. Runs the desktop app by default, or the
                     Android build in Waydroid with --android, which boots
                     Waydroid first if it is not already running. The desktop
                     app runs under Compose Hot Reload, so code changes reach
                     the running window without a restart; --cold starts a
                     plain run instead. Remaining arguments go to Gradle, e.g.
                     --no-auto to reload on demand instead of on every save.
  deploy-beta        Build and deploy beta packages for the named platforms:
                     --android (the APKs and update manifest), --linux (the
                     AppImage) and --windows / --macos (the Conveyor packages).
                     At least one platform is required.
  prepare-release    Build the release binaries for every supported platform
                     and stage them in the repository's release/ directory
  bundle-data        Download latest places, areas, comments and events
                     snapshots (always refreshes)
  bundle-map-styles  Bundle MapLibre styles, sprites and glyphs (--force
                     re-downloads)
  bundle-icons       Extract the icon-name list from the bundled Material
                     Symbols font
EOF
}

print_usage_website() {
  cat <<EOF
Usage: ./devtools website <command>

Commands:
  deploy    Build the Hugo site and rsync it to btcmap-api:/srv/http/android.btcmap.org
EOF
}

# START emulator section

# The Android target runs inside Waydroid — a container that boots a full
# Android system on the host kernel — instead of Google's emulator: no AVD to
# keep around, no emulator binary, no SDK system images. Waydroid is in Arch's
# official repositories (`sudo pacman -S waydroid`) and fetches its image once
# (`sudo waydroid init`). The session is driven through Waydroid's own CLI;
# the app commands talk to the guest over adb (see the app section).
emulator_log="waydroid.log"

require_waydroid() {
  if ! command -v waydroid >/dev/null 2>&1; then
    err "waydroid is not installed. Install it with: sudo pacman -S waydroid"
    return 1
  fi
  if waydroid status 2>&1 | grep -q "not initialized"; then
    err "Waydroid is not initialized. Initialize it once with: sudo waydroid init"
    return 1
  fi
}

waydroid_session_running() {
  # `waydroid status` separates the label from the value with a tab.
  waydroid status 2>/dev/null | grep -qE '^Session:[[:space:]]*RUNNING'
}

waydroid_container_frozen() {
  waydroid status 2>/dev/null | grep -qE '^Container:[[:space:]]*FROZEN'
}

# Waydroid suspends the guest when no app is on screen (suspend_action=freeze),
# and a frozen guest stops answering adb — device commands would just hang.
# Showing the full UI unfreezes it (the launcher counts as the active app).
wake_waydroid() {
  if waydroid_container_frozen; then
    waydroid show-full-ui >/dev/null 2>&1 || true
  fi
}

# Multi-window (one window per app, managed by the desktop instead of one
# full-screen Android surface) is a persistent guest property. The guest only
# reads it when the session starts, so changing it means restarting the session.
waydroid_multi_window() {
  waydroid prop get persist.waydroid.multi_windows 2>/dev/null \
    | tr -d '[:space:]' | grep -qx true
}

start_waydroid_session() {
  # Detached: the session manager blocks for as long as the guest runs, so this
  # returns once Android is up, not when the session ends. Its details go to the
  # log rather than to Waydroid's own log file, so a failed boot can be read with
  # the tail below.
  nohup setsid waydroid --details-to-stdout session start > "$emulator_log" 2>&1 \
    < /dev/null & disown

  echo "Booting Waydroid (logs: $emulator_log)..."
  local waited=0
  while [ "$waited" -lt 240 ]; do
    if waydroid_session_running; then
      return 0
    fi
    # A session manager that has died — no binder device, the container service
    # not running — never reaches RUNNING, so stop waiting for it.
    if ! pgrep -f '[w]aydroid .*session start' >/dev/null 2>&1; then
      break
    fi
    sleep 0.5
    waited=$((waited + 1))
  done

  echo "Error: Waydroid did not come up (see $emulator_log):" >&2
  tail -n 20 "$emulator_log" >&2
  return 1
}

stop_waydroid_session() {
  waydroid session stop >/dev/null 2>&1 || true
  local waited=0
  while [ "$waited" -lt 40 ]; do
    if ! waydroid_session_running; then
      return 0
    fi
    sleep 0.5
    waited=$((waited + 1))
  done

  err "Waydroid did not shut down"
  return 1
}

# The session is what the guest's Android system runs under; without it every
# `waydroid app` command logs "WayDroid session is stopped" and exits 0, so
# check for it up front instead of after a silent failure.
require_waydroid_session() {
  require_waydroid || return 1
  if ! waydroid_session_running; then
    err "the Waydroid session is not running. Boot it with: ./devtools app run --android"
    return 1
  fi
}

# `app run --android` calls this, so there is no separate command to start
# Waydroid: the session is a prerequisite of running the app, not a step of its
# own. Boots it when it is not up, then applies the dev settings.
ensure_waydroid_session() {
  require_waydroid || return 1

  local booted=0

  if ! waydroid_session_running; then
    # Waydroid's guest reaches the host through the Android binder driver. A
    # kernel without it (or with binderfs left unmounted) can never start the
    # container, and the failure only shows up as a session that never comes up.
    if [ ! -e /dev/binder ] && [ ! -d /dev/binderfs ]; then
      cat >&2 <<'EOF'
Error: no Android binder device: /dev/binder is missing and /dev/binderfs is
not mounted.

Waydroid needs the Android binder driver. Either run a kernel that ships it
(linux-zen), install binder_linux-dkms, or mount binderfs and link its devices
into /dev. See https://wiki.archlinux.org/title/Waydroid.
EOF
      return 1
    fi

    start_waydroid_session || return 1
    booted=1
  fi

  # The image's windowed mode (one window per app) turned out to be fragile —
  # it regressed to fullscreen tasks and crashed SurfaceFlinger — so the dev
  # session runs with the whole Android UI in one window instead.
  if waydroid_multi_window; then
    echo "Switching Waydroid back to fullscreen mode..."
    if ! waydroid prop set persist.waydroid.multi_windows false; then
      err "could not turn off Waydroid multi-window mode"
      return 1
    fi
    # The guest reads the property when it starts, so the session has to be
    # restarted for the display to leave freeform mode.
    stop_waydroid_session || return 1
    start_waydroid_session || return 1
    booted=1
  fi

  # A frozen guest does not answer adb, so wake it, then apply the guest-side
  # settings (screen stays on, no on-screen keyboard).
  wake_waydroid
  if ! configure_guest; then
    echo "Note: could not apply the Waydroid guest settings (adb unavailable)." >&2
  fi

  if [ "$booted" -eq 1 ]; then
    # Puts the guest on screen: the session alone has no visible window. When
    # the session was already up, leave it where the user left it.
    waydroid show-full-ui >/dev/null 2>&1 || true
  fi
}

# END emulator section

# START signing section

android_sdk_dir() {
  if [ -n "${ANDROID_HOME:-}" ]; then
    echo "$ANDROID_HOME"
    return 0
  fi
  if [ -n "${ANDROID_SDK_ROOT:-}" ]; then
    echo "$ANDROID_SDK_ROOT"
    return 0
  fi
  local sdk_dir
  sdk_dir="$(sed -n 's/^sdk\.dir=//p' local.properties 2>/dev/null | head -n1)"
  if [ -n "$sdk_dir" ]; then
    echo "$sdk_dir"
    return 0
  fi
  return 1
}

find_apksigner() {
  local sdk_dir
  sdk_dir="$(android_sdk_dir)" || return 1
  local build_tools
  build_tools="$(ls -d "$sdk_dir"/build-tools/*/ 2>/dev/null | sort -V | tail -n1)"
  [ -n "$build_tools" ] && [ -x "${build_tools}apksigner" ] && echo "${build_tools}apksigner"
}

assert_apk_signed() {
  local apk="$1"
  if [ ! -f "$apk" ]; then
    echo "Error: APK not found at $apk" >&2
    return 1
  fi
  local apksigner
  if ! apksigner="$(find_apksigner)"; then
    echo "Error: could not locate apksigner; refusing to deploy an unsigned APK." >&2
    return 1
  fi
  if ! "$apksigner" verify --print-certs "$apk" >/dev/null 2>&1; then
    echo "Error: $apk is not signed. Add the release keystore properties to local.properties." >&2
    return 1
  fi
  echo "$apk is signed."
}

# END signing section

# START website section

cmd_website_deploy() {
  if ! command -v hugo >/dev/null 2>&1; then
    err "hugo is not installed; install Hugo to build the site."
    return 1
  fi

  local dest="btcmap-api:/srv/http/android.btcmap.org/"

  # Hugo does not prune its output, so clear it to avoid shipping stale pages
  # from earlier builds.
  echo "Building the Hugo site..."
  rm -rf website/public
  (cd website && hugo)

  echo "Deploying to $dest..."
  rsync -avz --delete --chmod=D755,F644 website/public/ "$dest"
}

cmd_website() {
  local target="${1:-help}"
  shift || true
  case "$target" in
    deploy) cmd_website_deploy "$@" ;;
    help|-h|--help) print_usage_website ;;
    *) err "Unknown website command: $target"; print_usage_website; return 1 ;;
  esac
}

# END website section

# START cdn section

# BunnyCDN API key for the static.btcmap.org pull zone. Set BUNNY_API_KEY in
# the environment or add `bunny.api.key=...` to local.properties.
bunny_api_key() {
  if [ -n "${BUNNY_API_KEY:-}" ]; then
    printf '%s' "$BUNNY_API_KEY"
    return 0
  fi
  local key
  key="$(sed -n 's/^bunny\.api\.key=//p' local.properties 2>/dev/null | head -n1)"
  if [ -n "$key" ]; then
    printf '%s' "$key"
    return 0
  fi
  return 1
}

assert_bunny_api_key() {
  if ! bunny_api_key >/dev/null; then
    err "no BunnyCDN API key; refusing to deploy without purging the CDN cache."
    err "Set BUNNY_API_KEY in the environment or add 'bunny.api.key=...' to local.properties."
    return 1
  fi
}

# Purge absolute CDN URLs from the Bunny edge cache, waiting for the purge to
# complete so a request right after the deploy cannot hit a stale object.
purge_cdn() {
  local key
  key="$(bunny_api_key)" || return 1
  local url
  for url in "$@"; do
    echo "Purging $url from the CDN..."
    curl -fsS -X POST -G \
      --data-urlencode "url=$url" \
      --data-urlencode "async=false" \
      -H "AccessKey: $key" \
      "https://api.bunny.net/purge" >/dev/null
  done
}

# END cdn section

# START appimage section

# appimagetool only publishes a moving "continuous" build, so the URL can be
# overridden to pin one. A ready-made binary can also be pointed at directly
# with APPIMAGETOOL=/path/to/appimagetool.
appimagetool_url_default="https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage"

# Downloads and extracts appimagetool into a cache on first use, then prints the
# path to a runnable appimagetool. The extracted form is used so packing does
# not need a FUSE mount of the tool itself.
prepare_appimagetool() {
  if [ -n "${APPIMAGETOOL:-}" ]; then
    printf '%s' "$APPIMAGETOOL"
    return 0
  fi

  local dir="${XDG_CACHE_HOME:-$HOME/.cache}/btcmap/appimagetool"
  local apprun="$dir/squashfs-root/AppRun"
  if [ -x "$apprun" ]; then
    printf '%s' "$apprun"
    return 0
  fi

  local url="${APPIMAGETOOL_URL:-$appimagetool_url_default}"
  echo "Downloading appimagetool from $url..." >&2
  mkdir -p "$dir"
  local image="$dir/appimagetool-x86_64.AppImage"
  curl -fsSL -o "$image" "$url"
  chmod +x "$image"
  rm -rf "$dir/squashfs-root"
  (cd "$dir" && "$image" --appimage-extract >/dev/null)
  if [ ! -x "$apprun" ]; then
    err "could not extract appimagetool"
    return 1
  fi
  printf '%s' "$apprun"
}

# Wraps the jpackage app image the Compose plugin produces (built by the
# createDistributable task) in an AppDir and packs it into a single-file
# AppImage at $1. The app image already carries its own runtime, so the result
# needs no Java on the target machine.
build_desktop_appimage() {
  local out="$1"
  local app_dir="desktopApp/build/compose/binaries/main/app/BTC Map"
  if [ ! -x "$app_dir/bin/BTC Map" ]; then
    err "desktop app image not found at $app_dir; run :desktopApp:createDistributable first."
    return 1
  fi

  local out_dir appdir
  out_dir="$(dirname "$out")"
  appdir="$out_dir/BTC-Map.AppDir"
  rm -rf "$out_dir"
  mkdir -p "$appdir/usr"
  cp -a "$app_dir/." "$appdir/usr/"

  # The jpackage launcher has a space in its name; an alias without one is
  # friendlier for the desktop entry (Exec=/Icon=) and for a PATH install.
  cat > "$appdir/usr/bin/btc-map" <<'RUN'
#!/bin/sh
HERE="$(dirname "$(readlink -f "$0")")"
exec "$HERE/BTC Map" "$@"
RUN
  chmod +x "$appdir/usr/bin/btc-map"

  cat > "$appdir/AppRun" <<'RUN'
#!/bin/sh
HERE="$(dirname "$(readlink -f "$0")")"
exec "$HERE/usr/bin/btc-map" "$@"
RUN
  chmod +x "$appdir/AppRun"

  cat > "$appdir/btc-map.desktop" <<'DESKTOP'
[Desktop Entry]
Type=Application
Name=BTC Map
Comment=Map of Bitcoin merchants
Exec=btc-map
Icon=btc-map
Categories=Finance;Network;
Terminal=false
DESKTOP

  cp fastlane/metadata/android/en-US/images/icon.png "$appdir/btc-map.png"

  local appimagetool
  appimagetool="$(prepare_appimagetool)"

  echo "Packing $out..."
  ARCH=x86_64 "$appimagetool" "$appdir" "$out"
}

# END appimage section

# START conveyor section

# Every desktop artifact lives under one directory on the CDN, one per channel:
# the Windows and macOS packages Conveyor builds and the Linux AppImage.
desktop_cdn_base="https://cdn.static.btcmap.org/desktop"
desktop_dest="btcmap-api:/srv/http/static.btcmap.org/desktop"

# Conveyor builds the Windows (MSIX, plus an installer .exe and a portable .zip)
# and macOS (a signed, Sparkle-updating .app archive) packages from this Linux
# machine. That is the whole reason it is here: jpackage, which the Compose
# plugin wraps, cannot cross-compile and silently skips the foreign-OS formats,
# so without Conveyor the desktop app could only ever ship as a Linux AppImage.
#
# It is a ~111 MB tool, cached under ${XDG_CACHE_HOME}/btcmap/conveyor on first
# use. Point CONVEYOR at a binary to use an install of your own instead, or
# CONVEYOR_URL at a different download.
conveyor_version_default="22.3"
conveyor_url_default="https://downloads.hydraulic.dev/conveyor/conveyor-${conveyor_version_default}-linux-amd64.tar.gz"

# Downloads and unpacks Conveyor into a cache on first use, then prints the path
# to its launcher.
prepare_conveyor() {
  if [ -n "${CONVEYOR:-}" ]; then
    printf '%s' "$CONVEYOR"
    return 0
  fi

  local dir="${XDG_CACHE_HOME:-$HOME/.cache}/btcmap/conveyor"
  local bin="$dir/conveyor-${conveyor_version_default}/bin/conveyor"
  if [ -x "$bin" ]; then
    printf '%s' "$bin"
    return 0
  fi

  local url="${CONVEYOR_URL:-$conveyor_url_default}"
  echo "Downloading Conveyor from $url..." >&2
  mkdir -p "$dir"
  local tarball="$dir/conveyor.tar.gz"
  curl -fsSL -o "$tarball" "$url"
  tar xzf "$tarball" -C "$dir"
  rm -f "$tarball"
  if [ ! -x "$bin" ]; then
    err "could not unpack Conveyor"
    return 1
  fi
  printf '%s' "$bin"
}

# The Conveyor signing root key: the one key every Windows and macOS package
# key, update feed and package identity is derived from. It is signing material,
# so it is kept beside the Android keystore and outside the repository, and
# local.properties points at it, exactly as it points at the keystore itself.
# Losing or rotating it breaks updates for every copy already installed and
# looks like a different app to Windows, so it is never created anywhere else.
conveyor_signing_key() {
  sed -n 's/^conveyor\.signing\.key=//p' local.properties 2>/dev/null | head -n1
}

# Uses the root key at the configured path, generating it there on first use. If
# it has a passphrase (conveyor keys passphrase), export it as
# CONVEYOR_PASSPHRASE so the builds can unlock it.
ensure_conveyor_key() {
  local conveyor="$1"
  local key
  key="$(conveyor_signing_key)"
  if [ -z "$key" ]; then
    err "no 'conveyor.signing.key' in local.properties; refusing to deploy."
    err "It must point at the Conveyor signing root key file, which belongs beside the Android keystore, outside the repository."
    return 1
  fi
  if [ "$(basename "$key")" != "defaults.conf" ]; then
    err "conveyor.signing.key must name the file defaults.conf, the name Conveyor writes the root key to (got $(basename "$key"))."
    return 1
  fi
  if [ -f "$key" ]; then
    return 0
  fi

  echo "Generating the Conveyor signing root key (once) at $key..." >&2
  mkdir -p "$(dirname "$key")"
  "$conveyor" --agree-to-license=1 keys generate --no-passphrase -o "$(dirname "$key")"
  cat >&2 <<EOF

Back this file up now: $key
Every Windows and macOS package key, update feed and package identity comes from
it. Without it, every copy already installed can never be updated again.
EOF
}

# Builds the Windows and macOS packages and their update site into $3 for the
# channel in $2 (beta or release), using the Conveyor in $1. $4 optionally
# narrows the build to a subset of the machines, as a HOCON list (e.g.
# [windows.amd64]); empty builds every machine the config names. The channel is
# the last path segment of the update URL baked into the packages, so installed
# copies check only their own channel; changing it later strands the copies
# already out there.
build_desktop_packages() {
  local conveyor="$1"
  local channel="$2"
  local out="$3"
  local machines="${4:-}"

  rm -rf "$out"

  # A debuggable build when asked for: the same packages, but with the JVM
  # attach mechanism re-enabled (a signed launcher disables it, which is why a
  # running Windows build cannot be inspected), a console, and a JDWP port. See
  # conveyor-debug.conf. Traffic and the published channel are unchanged.
  local conf="desktopApp/conveyor.conf"
  if [ -n "${CONVEYOR_DEBUG:-}" ]; then
    conf="desktopApp/conveyor-debug.conf"
    echo "Building a DEBUG build of the desktop packages (attach enabled, console, JDWP on 127.0.0.1:5005)." >&2
  fi

  local args=("--agree-to-license=1")
  # Conveyor will not prompt for a passphrase without a terminal, so an
  # encrypted root key has to be unlocked through the environment.
  if [ -n "${CONVEYOR_PASSPHRASE:-}" ]; then
    args+=("--passphrase=env:CONVEYOR_PASSPHRASE")
  fi
  args+=("-f" "$conf" "-Kapp.site.base-url=$desktop_cdn_base/$channel")
  if [ -n "$machines" ]; then
    args+=("-Kapp.machines=$machines")
  fi

  echo "Building the desktop packages for the $channel channel..."
  "$conveyor" "${args[@]}" make site --output-dir "$out"
}

# Purges every file the packaged site contains from the CDN. The names embed the
# version and are stable only across a rebuild of the same version, so they are
# read from the output directory rather than listed by hand.
purge_conveyor_site() {
  local channel="$1"
  local dir="$2"
  local urls=()
  local file
  while IFS= read -r file; do
    urls+=("$desktop_cdn_base/$channel/${file#"$dir"/}")
  done < <(find "$dir" -type f | sort)
  purge_cdn "${urls[@]}"
}

# END conveyor section

# START app section

# Downloads the latest places, areas, comments and events snapshots. The
# snapshots are committed as assets and refreshed manually; see AGENTS.md,
# "Bundled Assets".
cmd_app_bundle_data() {
  python3 bundle_places.py "$@"
  python3 bundle_areas.py "$@"
  python3 bundle_comments.py "$@"
  python3 bundle_events.py "$@"
}

# Bundles the MapLibre styles, sprites and glyphs.
cmd_app_bundle_map_styles() {
  python3 bundle_map_styles.py "$@"
}

# Extracts the icon-name list from the bundled Material Symbols font into the
# generated `MaterialSymbolNames.kt`.
cmd_app_bundle_icons() {
  python3 bundle_icons.py "$@"
}

# The application id of the debug build, which is the package it installs into
# the guest.
app_package="org.btcmap.debug"

# The SDK is where both the build and adb come from. Gradle finds it only
# through ANDROID_HOME/ANDROID_SDK_ROOT or `sdk.dir` in local.properties, which
# is per checkout and gitignored; fall back to the usual per-user install so the
# Android target works from a plain shell.
require_android_sdk() {
  local sdk
  if ! sdk="$(android_sdk_dir)" || [ -z "$sdk" ] || [ ! -d "$sdk" ]; then
    sdk="${HOME}/Android/Sdk"
  fi
  if [ -z "$sdk" ] || [ ! -d "$sdk" ]; then
    err "the Android SDK was not found: set ANDROID_HOME or sdk.dir in local.properties"
    return 1
  fi

  export ANDROID_HOME="$sdk"
  case ":$PATH:" in
    *":$sdk/platform-tools:"*) ;;
    *) export PATH="$sdk/platform-tools:$PATH" ;;
  esac
  if ! command -v adb >/dev/null 2>&1; then
    err "adb was not found in $sdk/platform-tools"
    return 1
  fi
}

# The guest is reached over adb on Waydroid's container network. Waydroid's own
# `waydroid app install` logs its failures instead of failing (recent images
# break it outright), so the app commands use adb, whose failures are visible.
waydroid_device() {
  require_waydroid_session || return 1
  require_android_sdk || return 1
  wake_waydroid

  local ip serial waited=0
  ip="$(waydroid status 2>/dev/null | sed -n 's/^IP address:[[:space:]]*//p' | head -n1)" || true
  if [ -z "$ip" ]; then
    err "could not read the Waydroid guest address from: waydroid status"
    return 1
  fi
  serial="$ip:5555"

  # The session reports RUNNING before Android has finished booting, and adb
  # shows the guest as offline for a moment after a (re)start, so wait for the
  # guest itself to say it is ready rather than race it.
  while [ "$waited" -lt 120 ]; do
    adb connect "$serial" >/dev/null 2>&1 || true
    if [ "$(timeout 5 adb -s "$serial" shell getprop sys.boot_completed 2>/dev/null \
        | tr -d '\r[:space:]')" = "1" ]; then
      echo "$serial"
      return 0
    fi
    sleep 1
    waited=$((waited + 1))
  done

  err "adb cannot reach the Waydroid guest at $serial; accept its debugging prompt in Waydroid"
  return 1
}

# Guest-side settings applied on every start:
# - keep the Android screen on: a sleeping guest hides the app window and lets
#   Waydroid freeze the container, which adb then cannot talk to;
# - keep the IME away from focused fields: Waydroid presents the host keyboard as
#   a hardware keyboard, but the image asks for the virtual keyboard anyway.
configure_guest() {
  local serial

  # Called in this shell, not the substitution below: require_android_sdk puts
  # platform-tools on PATH, which a subshell would not pass back.
  require_android_sdk || return 1
  serial="$(waydroid_device)" || return 1

  timeout 15 adb -s "$serial" shell settings put system screen_off_timeout 2147483647 >/dev/null
  timeout 15 adb -s "$serial" shell settings put secure show_ime_with_hard_keyboard 0 >/dev/null
}

install_apk() {
  local apk_path="$1" serial

  serial="$(waydroid_device)" || return 1

  echo "Installing $apk_path in Waydroid..."
  if ! timeout 180 adb -s "$serial" install -r -t "$apk_path"; then
    err "the APK did not install (see the failure above)"
    return 1
  fi
}

# `waydroid app launch` is Waydroid's own launch — it also records the active
# app for the host — whereas `am start` only updates the activity. The CLI logs
# a failed launch and still exits 0, so wait for the process instead.
launch_app() {
  local serial="$1" pid waited attempt=0

  while [ "$attempt" -lt 3 ]; do
    echo "Launching $app_package..."
    waydroid app launch "$app_package"

    waited=0
    while [ "$waited" -lt 10 ]; do
      pid="$(timeout 5 adb -s "$serial" shell pidof "$app_package" 2>/dev/null | tr -d '\r[:space:]')" || true
      if [ -n "$pid" ]; then
        return 0
      fi
      sleep 0.5
      waited=$((waited + 1))
    done
    attempt=$((attempt + 1))
  done

  err "$app_package did not start; see: waydroid log"
  return 1
}

cmd_app_run_android() {
  local apk_path="./app/build/outputs/apk/debug/app-x86_64-debug.apk" serial

  require_android_sdk || return 1
  ensure_waydroid_session || return 1

  echo "Assembling debug APK..."
  ./gradlew assembleDebug "$@"

  if [ ! -f "$apk_path" ]; then
    err "APK not found at $apk_path"
    return 1
  fi

  install_apk "$apk_path" || return 1

  serial="$(waydroid_device)" || return 1
  launch_app "$serial"
}

cmd_app_run_desktop() {
  local log="${TMPDIR:-/tmp}/btcmap-desktop.log"

  # Two instances would open the same database under $BTCMAP_HOME, so refuse to
  # start a second one.
  if pgrep -f "org.btcmap.desktop.MainK[t]" >/dev/null 2>&1; then
    echo "The desktop app is already running; not starting a second instance."
    echo "Stop it with: pkill -f 'org.btcmap.desktop.MainK[t]'"
    return 0
  fi

  local task=":desktopApp:hotRun"
  # --auto watches the sources and reloads the running window whenever one
  # changes, which is the point of running under hot reload here. It keeps the
  # Gradle build alive between reloads; --no-auto (forwarded to Gradle) turns
  # that off and leaves the reload to `./gradlew :desktopApp:reload`.
  local args=(--auto)

  if [ -z "$desktop_hot" ]; then
    task=":desktopApp:run"
    args=()
    echo "Launching the desktop app (logs: $log)..."
  else
    # Hot reload runs the app on the JetBrains Runtime, not on the toolchain the
    # plain run uses: only the JBR can redefine the classes it has already
    # loaded. The toolchain resolver provisions it into ~/.gradle/jdks (a 560 MB
    # download, once) on the first hot run.
    echo "Launching the desktop app with Compose Hot Reload (logs: $log)..."
    echo "Saving a source file reloads the window; the dev-tools window has a Reload UI button."
  fi

  echo "Waiting for the window to appear (build output: $log)..."

  # Truncated here rather than by the subshell's redirection: the wait loop
  # below must never read a marker left from the previous run before this one
  # starts.
  : > "$log"

  # Detached, but this shell waits for the window before returning: the task
  # blocks for the life of the window, so it keeps the app's output (and, under
  # hot reload, each reload's) in $log, because `hotRun` runs the app attached.
  (
    echo "btcmap: devtools run started at $(date +%H:%M:%S.%3N)"
    exec ./gradlew "$task" "${args[@]}" "$@"
  ) >> "$log" 2>&1 &
  local pid=$!

  # Ctrl+C during the wait cancels the launch instead of leaving the build
  # running invisibly after the prompt has come back.
  trap 'kill -TERM "$pid" 2>/dev/null; echo "Launch cancelled." >&2; exit 130' INT TERM

  # Block until the app has committed its first composition: a launch that fails
  # should fail the command, not return a prompt that looks like success while
  # the window never appears. The mark is the app's own (see Main.kt) and is the
  # closest thing to "a window is on screen" here — it means the UI is up, not
  # merely that Gradle finished compiling. The build (and the hot reload loop)
  # keeps running once we return.
  while kill -0 "$pid" 2>/dev/null; do
    if grep -qF 'btcmap: first composition committed' "$log" 2>/dev/null; then
      trap - INT TERM
      echo "The app is running (logs: $log)."
      return 0
    fi
    sleep 0.5
  done
  trap - INT TERM

  echo "Error: the desktop app exited before its window appeared." >&2
  tail -n 20 "$log" >&2
  return 1
}

# Chooses the app target from optional --android/--desktop flags (desktop by
# default), leaving the remaining arguments (forwarded to Gradle) in
# app_target_args. The desktop app runs under Compose Hot Reload unless --cold
# is given, because reloading the running window is how the desktop app is
# iterated on; the Android target has no equivalent and always runs plainly.
# Prints the app usage and returns 1 when asked for help.
app_target="desktop"
app_target_args=()
desktop_hot=1

parse_app_target() {
  app_target="desktop"
  app_target_args=()
  desktop_hot=1
  local arg
  for arg in "$@"; do
    case "$arg" in
      --android) app_target="android" ;;
      --desktop) app_target="desktop" ;;
      --cold|--no-hot) desktop_hot="" ;;
      help|-h|--help) print_usage_app; return 1 ;;
      *) app_target_args+=("$arg") ;;
    esac
  done
}

cmd_app_run() {
  parse_app_target "$@" || return 0
  case "$app_target" in
    android) cmd_app_run_android "${app_target_args[@]}" ;;
    desktop) cmd_app_run_desktop "${app_target_args[@]}" ;;
  esac
}

# The platforms `deploy-beta` can publish, each selectable on its own: the
# Android APKs and update manifest (--android), the Linux AppImage (--linux) and
# the packages Conveyor builds for Windows (--windows) and Apple Silicon macOS
# (--macos). At least one has to be named; naming several narrows neither the
# build nor the upload, it just does each.
deploy_android=""
deploy_linux=""
deploy_windows=""
deploy_macos=""

parse_deploy_platforms() {
  deploy_android=""
  deploy_linux=""
  deploy_windows=""
  deploy_macos=""
  local arg
  for arg in "$@"; do
    case "$arg" in
      --android) deploy_android=1 ;;
      --linux) deploy_linux=1 ;;
      --windows) deploy_windows=1 ;;
      --macos) deploy_macos=1 ;;
      help|-h|--help) print_usage_app; return 1 ;;
      *) err "Unknown deploy-beta parameter: $arg"; print_usage_app; return 1 ;;
    esac
  done
  if [ -z "$deploy_android$deploy_linux$deploy_windows$deploy_macos" ]; then
    err "deploy-beta needs at least one platform: --android, --linux, --windows or --macos."
    print_usage_app
    return 1
  fi
}

cmd_app_deploy_beta() {
  parse_deploy_platforms "$@" || return 1
  assert_bunny_api_key

  # Windows and macOS are one Conveyor build, so either flag means that build.
  local desktop=""
  if [ -n "$deploy_windows$deploy_macos" ]; then
    desktop=1
  fi

  # The Conveyor signing root key has to exist before Gradle runs: the generated
  # config includes it, so writeConveyorConfig embeds it.
  local conveyor=""
  if [ -n "$desktop" ]; then
    conveyor="$(prepare_conveyor)"
    ensure_conveyor_key "$conveyor"
  fi

  # Assemble only what the selected platforms need. The APKs need the beta build
  # type; the Linux AppImage comes from the jpackage app image; the Windows and
  # macOS packages share the ordinary jars and the generated Conveyor config.
  local gradle_tasks=()
  if [ -n "$deploy_android" ]; then
    gradle_tasks+=(assembleBeta)
  fi
  if [ -n "$deploy_linux" ]; then
    gradle_tasks+=(:desktopApp:createDistributable)
  fi
  if [ -n "$desktop" ]; then
    gradle_tasks+=(:shared:jvmJar :ui:jvmJar :desktopApp:jar :desktopApp:writeConveyorConfig)
  fi

  echo "Assembling: ${gradle_tasks[*]}"
  # The beta build is stamped with its build time, so a rebuild at the same
  # version code is still newer than the build an installed copy is running. The
  # manifest written below carries the same stamp, read back from the APK's
  # BuildConfig, so the two agree.
  if [ -n "$deploy_android" ]; then
    local build_time
    build_time="$(date +%s%3N)"
    ./gradlew "${gradle_tasks[@]}" -PbtcmapBuildTime="$build_time"
  else
    ./gradlew "${gradle_tasks[@]}"
  fi

  local appimage_out="desktopApp/build/compose/appimage/BTC-Map-x86_64.AppImage"
  local packages_out="desktopApp/build/conveyor/beta"
  local beta_dest="$desktop_dest/beta/"

  if [ -n "$deploy_android" ]; then
    local apk_dir="app/build/outputs/apk/beta"
    local dest="btcmap-api:/srv/http/static.btcmap.org/android/apk/"
    local manifest_dest="btcmap-api:/srv/http/static.btcmap.org/android/latest-app-beta-ver.json"
    local build_config="app/build/generated/source/buildConfig/beta/org/btcmap/BuildConfig.java"

    assert_apk_signed "$apk_dir/app-arm64-v8a-beta.apk"
    assert_apk_signed "$apk_dir/app-universal-beta.apk"

    local version_code version_name build_time_value
    version_code="$(sed -n 's/.*VERSION_CODE = \([0-9]*\);.*/\1/p' "$build_config" | head -n1)"
    version_name="$(sed -n 's/.*VERSION_NAME = "\(.*\)";.*/\1/p' "$build_config" | head -n1)"
    build_time_value="$(sed -n 's/.*BUILD_TIME = \([0-9]*\)L;.*/\1/p' "$build_config" | head -n1)"
    if [ -z "$version_code" ] || [ -z "$version_name" ] || [ -z "$build_time_value" ]; then
      echo "Error: could not read version info from $build_config" >&2
      return 1
    fi

    local manifest
    manifest="$(mktemp)"
    cat > "$manifest" <<JSON
{
  "code": $version_code,
  "name": "$version_name",
  "buildTime": $build_time_value,
  "url": "https://cdn.static.btcmap.org/android/apk/beta.apk"
}
JSON
    chmod 644 "$manifest"

    rsync -avz --progress "$apk_dir"/app-arm64-v8a-beta.apk "$dest/beta.apk"
    rsync -avz --progress "$apk_dir"/app-universal-beta.apk "$dest/beta-universal.apk"
    rsync -avz --progress --chmod=F644 "$manifest" "$manifest_dest"
    rm -f "$manifest"

    # The APKs and the manifest are overwritten in place, so the pull zone would
    # keep serving its cached copy for the full max-age window unless we purge
    # it.
    purge_cdn \
      "https://cdn.static.btcmap.org/android/apk/beta.apk" \
      "https://cdn.static.btcmap.org/android/apk/beta-universal.apk" \
      "https://cdn.static.btcmap.org/android/latest-app-beta-ver.json"
  fi

  if [ -n "$deploy_linux" ]; then
    build_desktop_appimage "$appimage_out"
    # Overwritten in place, so purge the cached copy as above.
    rsync -avz --progress --mkpath --chmod=F755 "$appimage_out" "$beta_dest/BTC-Map-x86_64.AppImage"
    purge_cdn "$desktop_cdn_base/beta/BTC-Map-x86_64.AppImage"
  fi

  if [ -n "$desktop" ]; then
    # Conveyor builds both machines by default; narrow it to the ones asked for
    # so a Windows- or macOS-only deploy does not build and upload the other.
    local machines=""
    if [ -n "$deploy_windows" ] && [ -n "$deploy_macos" ]; then
      machines="[windows.amd64,mac.aarch64]"
    elif [ -n "$deploy_windows" ]; then
      machines="[windows.amd64]"
    else
      machines="[mac.aarch64]"
    fi

    build_desktop_packages "$conveyor" beta "$packages_out" "$machines"

    # No --delete on the site: Conveyor keeps each version's package online so it
    # can generate deltas from it for the next one, so the older files are meant
    # to stay. Its own versioned file names never collide.
    rsync -avz --progress --mkpath --chmod=D755,F644 "$packages_out"/ "$beta_dest"

    # The part of the site whose names do not carry a version (the update
    # metadata, the download page, the installer and the update checker) is
    # overwritten in place, so the pull zone would keep serving its cached copy
    # for the full max-age window unless we purge it.
    purge_conveyor_site beta "$packages_out"
  fi
}

# Builds the release binaries for every supported platform — the Android APKs,
# the Linux AppImage and the Windows and macOS packages — and stages them in a
# `release/` directory in the repository root. Nothing is uploaded; this only
# prepares the files.
cmd_app_prepare_release() {
  # Resolve the signing key before Gradle runs: the generated Conveyor config
  # includes it, so it has to exist by the time writeConveyorConfig writes that.
  local conveyor
  conveyor="$(prepare_conveyor)"
  ensure_conveyor_key "$conveyor"

  # The desktop app is a single build every channel shares, so its packages come
  # from the ordinary jar. The generated Conveyor config has to be written before
  # Conveyor reads it.
  ./gradlew assembleRelease :desktopApp:createDistributable \
    :shared:jvmJar :ui:jvmJar :desktopApp:jar :desktopApp:writeConveyorConfig "$@"

  local apk_dir="app/build/outputs/apk/release"
  local packages_out="desktopApp/build/conveyor/release"
  local build_config="app/build/generated/source/buildConfig/release/org/btcmap/BuildConfig.java"

  assert_apk_signed "$apk_dir/app-arm64-v8a-release.apk"
  assert_apk_signed "$apk_dir/app-universal-release.apk"

  local version_name
  version_name="$(sed -n 's/.*VERSION_NAME = "\(.*\)";.*/\1/p' "$build_config" | head -n1)"
  if [ -z "$version_name" ]; then
    echo "Error: could not read version info from $build_config" >&2
    return 1
  fi

  local apk_base="btcmap-android-${version_name}"
  # The release AppImage is named after the version, like the APKs, so each
  # release can be told apart; the beta one keeps a stable name instead.
  local appimage_out="desktopApp/build/compose/appimage/BTC-Map-${version_name}-x86_64.AppImage"

  build_desktop_appimage "$appimage_out"
  build_desktop_packages "$conveyor" release "$packages_out"

  local out="release"
  echo "Staging the release binaries in $out/..."
  rm -rf "$out"
  mkdir -p "$out"
  cp "$apk_dir/app-arm64-v8a-release.apk" "$out/${apk_base}.apk"
  cp "$apk_dir/app-universal-release.apk" "$out/${apk_base}-universal.apk"
  cp "$appimage_out" "$out/"
  cp -a "$packages_out"/. "$out/"

  echo "Release binaries are in $out/."
}

cmd_app() {
  local target="${1:-help}"
  shift || true
  case "$target" in
    run) cmd_app_run "$@" ;;
    deploy-beta) cmd_app_deploy_beta "$@" ;;
    prepare-release) cmd_app_prepare_release "$@" ;;
    bundle-data) cmd_app_bundle_data "$@" ;;
    bundle-map-styles) cmd_app_bundle_map_styles "$@" ;;
    bundle-icons) cmd_app_bundle_icons "$@" ;;
    help|-h|--help) print_usage_app ;;
    *) err "Unknown app command: $target"; print_usage_app; return 1 ;;
  esac
}

# END app section

main() {
  local cmd="${1:-help}"
  shift || true
  case "$cmd" in
    app) cmd_app "$@" ;;
    website) cmd_website "$@" ;;
    help|-h|--help) print_usage ;;
    *) err "Unknown command: $cmd"; print_usage; return 1 ;;
  esac
}

main "$@"