sanderling/examples/folio/justfile

set shell := ["bash", "-cu"]
set dotenv-load := true

sanderling := env_var_or_default("SANDERLING", "sanderling")
avd        := env_var_or_default("AVD", "")
android_device := env_var_or_default("ANDROID_DEVICE", "")
duration   := env_var_or_default("DURATION", "1m")
seed       := env_var_or_default("SEED", "0")
output     := env_var_or_default("OUTPUT", justfile_directory() / "sanderling" / "runs")
ios_device := env_var_or_default("IOS_DEVICE", "iPhone 17 Pro")
ios_app    := justfile_directory() / "app" / "iosApp" / "build" / "Build" / "Products" / "Debug-iphonesimulator" / "iosApp.app"
ios_app_device := justfile_directory() / "app" / "iosApp" / "build" / "Build" / "Products" / "Debug-iphoneos" / "iosApp.app"
apk        := justfile_directory() / "app" / "androidApp" / "build" / "outputs" / "apk" / "debug" / "androidApp-debug.apk"

default:
    @just --list

# Resolve ANDROID_HOME from the env or a short list of canonical install
# locations, so Gradle can find the Android SDK without the user having to
# export anything.
_android-home:
    #!/usr/bin/env bash
    set -euo pipefail
    if [[ -n "${ANDROID_HOME:-}" && -d "$ANDROID_HOME" ]]; then
      echo "$ANDROID_HOME"; exit 0
    fi
    if [[ -n "${ANDROID_SDK_ROOT:-}" && -d "$ANDROID_SDK_ROOT" ]]; then
      echo "$ANDROID_SDK_ROOT"; exit 0
    fi
    for candidate in \
      "$HOME/Library/Android/sdk" \
      "$HOME/Android/Sdk" \
      "/opt/homebrew/share/android-commandlinetools" \
      "/usr/local/share/android-commandlinetools"; do
      if [[ -d "$candidate" ]]; then
        echo "$candidate"; exit 0
      fi
    done
    echo "could not locate Android SDK (set ANDROID_HOME)" >&2
    exit 1

# Ensure an Android device is online. If none is connected and no AVD is
# provided, boot the first AVD whose system image is actually installed
# (headless) and wait for it to finish booting.
_ensure-device:
    #!/usr/bin/env bash
    set -euo pipefail
    sdk="$(just _android-home)"
    adb="$sdk/platform-tools/adb"
    if "$adb" devices | awk 'NR>1 && $2=="device"{f=1} END{exit !f}'; then
      exit 0
    fi
    if [[ -n "{{avd}}" ]]; then
      exit 0  # sanderling boots the named AVD itself
    fi
    emulator="$sdk/emulator/emulator"
    avd=""
    for candidate in $("$emulator" -list-avds); do
      # The AVD directory is named in <name>.ini's path= field, which is not
      # always "<name>.avd" (e.g. Medium_Phone_API_36.0 -> Medium_Phone.avd).
      avddir="$(sed -n 's/^path=//p' "$HOME/.android/avd/$candidate.ini" 2>/dev/null || true)"
      [[ -n "$avddir" ]] || avddir="$HOME/.android/avd/$candidate.avd"
      sysdir="$(sed -n 's/^image\.sysdir\.1=//p' "$avddir/config.ini" 2>/dev/null || true)"
      if [[ -n "$sysdir" && -d "$sdk/$sysdir" ]]; then avd="$candidate"; break; fi
    done
    if [[ -z "$avd" ]]; then
      echo "no bootable AVD found (no installed system image); create one or set AVD=" >&2
      exit 1
    fi
    echo "booting emulator: $avd"
    ANDROID_SDK_ROOT="$sdk" ANDROID_HOME="$sdk" nohup "$emulator" -avd "$avd" \
      -no-window -no-snapshot -gpu swiftshader_indirect -no-audio >/tmp/folio-emulator.log 2>&1 &
    for _ in $(seq 1 150); do
      if [[ "$("$adb" shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')" == "1" ]]; then
        echo "emulator ready"; exit 0
      fi
      sleep 2
    done
    echo "emulator did not finish booting in time (see /tmp/folio-emulator.log)" >&2
    exit 1

# Print the serial every device-affecting recipe must act on, or refuse. A run
# installs the app, clears its state and fuzzes it, so the target is never
# inferred from "whatever adb resolved to": the one case it picks on its own is
# a single emulator on the local adb server, which is cheap to rebuild.
_require-device:
    #!/usr/bin/env bash
    set -euo pipefail
    adb="$(just _android-home)/platform-tools/adb"
    listing="$("$adb" devices)"
    online="$(echo "$listing" | awk 'NR>1 && $2=="device"{print $1}')"
    count="$(printf '%s' "$online" | grep -c . || true)"

    refuse() {
      cat >&2 <<EOF
    folio: $1

    $listing

    Set ANDROID_DEVICE to the serial to use, and ADB_SERVER_SOCKET when that adb
    server runs on another host. Either can live in examples/folio/.env:

      ANDROID_DEVICE=emulator-5554 just test
      ADB_SERVER_SOCKET=tcp:10.0.0.5:5037 ANDROID_DEVICE=emulator-5554 just test
    EOF
      exit 1
    }

    if [[ -n "{{android_device}}" ]]; then
      if printf '%s\n' "$online" | grep -qxF "{{android_device}}"; then
        echo "{{android_device}}"
        exit 0
      fi
      refuse "ANDROID_DEVICE={{android_device}} is not an online device."
    fi
    if [[ "$count" -eq 0 ]]; then
      refuse "no device is online."
    fi
    if [[ -z "${ADB_SERVER_SOCKET:-}" && "$count" -eq 1 && "$online" =~ ^emulator-[0-9]+$ ]]; then
      echo "$online"
      exit 0
    fi
    refuse "refusing to install on and fuzz a device nobody named. A run installs
    the app, clears its state and drives it, so the only target it picks on its
    own is a single emulator on the local adb server."

# Run folio's own unit tests. Named test-unit because `test` is the fuzz run.
test-unit:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    ./gradlew :core:testDebugUnitTest :app:shared:testDebugUnitTest

# Build the folio debug APK without installing it.
build:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    ./gradlew :app:androidApp:assembleDebug

# Build and install the folio APK on a running emulator/device. Gradle only
# assembles: adb does the install because it reads ADB_SERVER_SOCKET, so the
# device may live on a remote adb server, which AGP's loopback-only client
# cannot reach.
install: _ensure-device
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    serial="$(just _require-device)"
    export ANDROID_SERIAL="$serial"
    ./gradlew :app:androidApp:assembleDebug
    "$ANDROID_HOME/platform-tools/adb" install -r "{{apk}}"

# Remove the folio APK from the connected device.
uninstall:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    serial="$(just _require-device)"
    export ANDROID_SERIAL="$serial"
    "$ANDROID_HOME/platform-tools/adb" uninstall app.folio

# Remove gradle + iOS build directories.
clean:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    ./gradlew clean
    rm -rf app/iosApp/build

# Regenerate iosApp.xcodeproj from project.yml.
ios-gen:
    #!/usr/bin/env bash
    set -euo pipefail
    cd app/iosApp && xcodegen generate

# Build + install + launch on a booted iOS simulator (boots IOS_DEVICE if none).
ios:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    if ! xcrun simctl list devices booted | grep -q Booted; then
      xcrun simctl boot "{{ios_device}}"
      open -a Simulator
      sleep 3
    fi
    just ios-gen
    xcodebuild -project app/iosApp/iosApp.xcodeproj -scheme iosApp \
      -destination 'platform=iOS Simulator,name={{ios_device}}' \
      -derivedDataPath app/iosApp/build \
      build | tail -5
    # Installing over the top keeps the data container, and folio's signed-in
    # session with it, so a run started straight after would open on the last
    # run's Home screen instead of Login and diverge at step 1.
    xcrun simctl uninstall booted app.folio || true
    xcrun simctl install booted "{{ios_app}}"
    xcrun simctl launch booted app.folio

# Build the folio app for a connected physical iOS device (signed via .env creds).
# Signing reads ASC_API_* and DEVELOPMENT_TEAM/SANDERLING_IOS_TEAM from .env;
# sanderling installs the build on the device per run via devicectl.
ios-device:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    just ios-gen
    xcodebuild -project app/iosApp/iosApp.xcodeproj -scheme iosApp \
      -destination 'generic/platform=iOS' \
      -derivedDataPath app/iosApp/build \
      -allowProvisioningUpdates \
      -authenticationKeyPath "$ASC_API_KEY_PATH" \
      -authenticationKeyID "$ASC_API_KEY_ID" \
      -authenticationKeyIssuerID "$ASC_API_ISSUER_ID" \
      CODE_SIGN_STYLE=Automatic \
      DEVELOPMENT_TEAM="${SANDERLING_IOS_TEAM:-${DEVELOPMENT_TEAM:-}}" \
      build | tail -5

# Run 'sanderling test' against the folio app. Uses a connected device if one is
# online; otherwise boots AVD=<name> when provided, or auto-boots a bootable AVD.
# Depends on install so the run always fuzzes the current build, matching
# test-ios which rebuilds and reinstalls the app first.
test: install
    #!/usr/bin/env bash
    set -euo pipefail
    serial="$(just _require-device)"
    device_flag=(--device "$serial")
    if [[ -n "{{avd}}" ]]; then
      device_flag+=(--avd "{{avd}}")
    fi
    "{{sanderling}}" test \
      --spec "{{justfile_directory()}}/sanderling/spec.ts" \
      --bundle-id app.folio \
      "${device_flag[@]}" \
      --android-app-path "{{apk}}" \
      --duration "{{duration}}" \
      --seed "{{seed}}" \
      --output "{{output}}"

# Run 'sanderling test' with the LLM action generator instead of the seeded
# fuzzer. Needs OPENROUTER_API_KEY (or OPENAI_API_KEY) in the environment; the
# model is configured by generator = llm({...}) in spec.ts.
test-llm: install
    #!/usr/bin/env bash
    set -euo pipefail
    serial="$(just _require-device)"
    device_flag=(--device "$serial")
    if [[ -n "{{avd}}" ]]; then
      device_flag+=(--avd "{{avd}}")
    fi
    "{{sanderling}}" test \
      --spec "{{justfile_directory()}}/sanderling/spec.ts" \
      --bundle-id app.folio \
      --generator llm \
      "${device_flag[@]}" \
      --android-app-path "{{apk}}" \
      --duration "{{duration}}" \
      --seed "{{seed}}" \
      --output "{{output}}"

# Serve the wasmJs web app from a webpack dev server with COOP/COEP headers.
web:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    ./gradlew :app:webApp:wasmJsBrowserDevelopmentRun --continuous

# Produce a webpack distributable bundle for the web app.
web-build:
    #!/usr/bin/env bash
    set -euo pipefail
    export ANDROID_HOME="$(just _android-home)"
    ./gradlew :app:webApp:wasmJsBrowserDevelopmentExecutableDistribution

# Build + install + run sanderling spec on iOS simulator.
test-ios:
    #!/usr/bin/env bash
    set -euo pipefail
    just ios
    ios_device_flag=()
    if [[ -n "{{ios_device}}" ]]; then
      ios_device_flag=(--ios-device "{{ios_device}}")
    fi
    "{{sanderling}}" test \
      --platform ios \
      --spec "{{justfile_directory()}}/sanderling/spec.ts" \
      --bundle-id app.folio \
      --ios-app-path "{{ios_app}}" \
      "${ios_device_flag[@]}" \
      --duration "{{duration}}" \
      --seed "{{seed}}" \
      --output "{{output}}"

# Requires App Store Connect signing creds in .env and IOS_DEVICE set to the
# connected device's name (or UDID / CoreDevice id).
# Build + install + run sanderling spec on a connected physical iOS device.
test-ios-device:
    #!/usr/bin/env bash
    set -euo pipefail
    just ios-device
    "{{sanderling}}" test \
      --platform ios \
      --spec "{{justfile_directory()}}/sanderling/spec.ts" \
      --bundle-id app.folio \
      --ios-app-path "{{ios_app_device}}" \
      --ios-device "{{ios_device}}" \
      --duration "{{duration}}" \
      --seed "{{seed}}" \
      --output "{{output}}"