agent-device-proxy 0.1.5 → 0.2.0

package/scripts/macos-remote-setup.sh

@@ -0,0 +1,1117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# SSH-friendly host setup for self-hosted macOS mobile execution nodes.
+# Installs Xcode toolchain + simulator defaults, Android SDK/emulator defaults,
+# Node.js toolchain, and CLI dependencies used by runtime scripts.
+
+MACOS_SETUP_BREW_UPDATE="${MACOS_SETUP_BREW_UPDATE:-true}"
+MACOS_SETUP_INSTALL_XCODE="${MACOS_SETUP_INSTALL_XCODE:-true}"
+MACOS_SETUP_XCODE_VERSION="${MACOS_SETUP_XCODE_VERSION:-latest}"
+MACOS_SETUP_STRICT_XCODE="${MACOS_SETUP_STRICT_XCODE:-true}"
+MACOS_SETUP_INSTALL_IOS_RUNTIME="${MACOS_SETUP_INSTALL_IOS_RUNTIME:-true}"
+MACOS_SETUP_IOS_SIMULATOR_NAME="${MACOS_SETUP_IOS_SIMULATOR_NAME:-iPhone 17 Pro}"
+MACOS_SETUP_INSTALL_ANDROID="${MACOS_SETUP_INSTALL_ANDROID:-true}"
+MACOS_SETUP_ANDROID_API="${MACOS_SETUP_ANDROID_API:-latest}"
+MACOS_SETUP_ANDROID_DEVICE_PROFILE="${MACOS_SETUP_ANDROID_DEVICE_PROFILE:-pixel_9_pro_xl}"
+MACOS_SETUP_ANDROID_AVD_NAME="${MACOS_SETUP_ANDROID_AVD_NAME:-Pixel_9_Pro_XL}"
+MACOS_SETUP_INSTALL_AGENT_DEVICE="${MACOS_SETUP_INSTALL_AGENT_DEVICE:-true}"
+MACOS_SETUP_INSTALL_COCOAPODS="${MACOS_SETUP_INSTALL_COCOAPODS:-true}"
+MACOS_SETUP_INSTALL_ZULU_JDK="${MACOS_SETUP_INSTALL_ZULU_JDK:-${MACOS_SETUP_INSTALL_OPENJDK:-true}}"
+MACOS_SETUP_SHELL_PROFILE="${MACOS_SETUP_SHELL_PROFILE:-$HOME/.zprofile}"
+ANDROID_SDK_ROOT="${ANDROID_SDK_ROOT:-$HOME/Library/Android/sdk}"
+BREW_READY="false"
+BREW_UPDATED="false"
+DRY_RUN="false"
+DRY_RUN_INSTALLS=()
+DRY_RUN_SKIPS=()
+
+prime_default_macos_paths() {
+  local candidate
+  for candidate in /opt/homebrew/bin /opt/homebrew/sbin /usr/local/bin /usr/local/sbin; do
+    if [[ -d "$candidate" && ":$PATH:" != *":$candidate:"* ]]; then
+      PATH="$candidate:$PATH"
+    fi
+  done
+  export PATH
+}
+
+resolve_login_shell() {
+  if [[ -n "${SHELL:-}" && -x "${SHELL:-}" ]]; then
+    printf "%s\n" "$SHELL"
+    return
+  fi
+  if command -v dscl >/dev/null 2>&1; then
+    dscl . -read "/Users/$USER" UserShell 2>/dev/null | awk '/UserShell:/ {print $2; exit}'
+    return
+  fi
+  printf "\n"
+}
+
+prime_login_shell_environment() {
+  local login_shell
+  login_shell="$(resolve_login_shell)"
+  if [[ -z "$login_shell" || ! -x "$login_shell" ]]; then
+    return
+  fi
+
+  local shell_output
+  shell_output="$(
+    "$login_shell" -lc '
+      printf "__MACOS_REMOTE_SETUP_ENV_START__\n"
+      printf "PATH=%s\n" "$PATH"
+      printf "ANDROID_SDK_ROOT=%s\n" "${ANDROID_SDK_ROOT:-}"
+      printf "ANDROID_HOME=%s\n" "${ANDROID_HOME:-}"
+      printf "JAVA_HOME=%s\n" "${JAVA_HOME:-}"
+      printf "__MACOS_REMOTE_SETUP_ENV_END__\n"
+    ' 2>/dev/null || true
+  )"
+
+  if [[ "$shell_output" != *"__MACOS_REMOTE_SETUP_ENV_START__"* ]]; then
+    return
+  fi
+
+  local env_lines
+  env_lines="$(
+    printf "%s\n" "$shell_output" | awk '
+      $0 == "__MACOS_REMOTE_SETUP_ENV_START__" { capture=1; next }
+      $0 == "__MACOS_REMOTE_SETUP_ENV_END__" { capture=0; exit }
+      capture { print }
+    '
+  )"
+
+  local key value
+  while IFS='=' read -r key value; do
+    case "$key" in
+      PATH)
+        if [[ -n "$value" ]]; then
+          PATH="$value"
+        fi
+        ;;
+      ANDROID_SDK_ROOT)
+        if [[ -n "$value" ]]; then
+          ANDROID_SDK_ROOT="$value"
+        fi
+        ;;
+      ANDROID_HOME)
+        if [[ -n "$value" ]]; then
+          ANDROID_HOME="$value"
+        fi
+        ;;
+      JAVA_HOME)
+        if [[ -n "$value" ]]; then
+          JAVA_HOME="$value"
+        fi
+        ;;
+    esac
+  done <<<"$env_lines"
+
+  export PATH ANDROID_SDK_ROOT ANDROID_HOME JAVA_HOME
+}
+
+normalize_bool() {
+  local raw
+  raw="$(printf "%s" "$1" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')"
+  case "$raw" in
+    1|true|yes|on) printf "true\n" ;;
+    0|false|no|off) printf "false\n" ;;
+    *) echo "Error: expected boolean-like value, got '$1'." >&2; exit 64 ;;
+  esac
+}
+
+log() {
+  printf "[macos-remote-setup] %s\n" "$1"
+}
+
+warn() {
+  printf "[macos-remote-setup] Warning: %s\n" "$1" >&2
+}
+
+fail() {
+  printf "[macos-remote-setup] Error: %s\n" "$1" >&2
+  exit 64
+}
+
+usage() {
+  cat <<'EOF_USAGE'
+Usage: macos-remote-setup.sh [--dry-run|-n] [--help|-h]
+
+Options:
+  -n, --dry-run  Detect and print what would be installed/skipped without applying changes.
+  -h, --help     Show this help.
+EOF_USAGE
+}
+
+parse_args() {
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      -n|--dry-run)
+        DRY_RUN="true"
+        ;;
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      *)
+        fail "unknown argument: $1"
+        ;;
+    esac
+    shift
+  done
+}
+
+record_dry_run_install() {
+  local label="$1"
+  DRY_RUN_INSTALLS+=("$label")
+}
+
+record_dry_run_skip() {
+  local label="$1"
+  DRY_RUN_SKIPS+=("$label")
+}
+
+log_dry_run_command() {
+  local rendered=""
+  local arg
+  for arg in "$@"; do
+    rendered+=$(printf "%q " "$arg")
+  done
+  log "[dry-run] would run: ${rendered% }"
+}
+
+run_as_admin() {
+  if [[ "$DRY_RUN" == "true" ]]; then
+    if [[ "$(id -u)" == "0" ]]; then
+      log_dry_run_command "$@"
+    else
+      log_dry_run_command sudo "$@"
+    fi
+    return
+  fi
+  if [[ "$(id -u)" == "0" ]]; then
+    "$@"
+    return
+  fi
+  sudo "$@"
+}
+
+ensure_macos_host() {
+  if [[ "$(uname -s)" != "Darwin" ]]; then
+    fail "this script requires macOS (Darwin)."
+  fi
+}
+
+ensure_homebrew() {
+  if command -v brew >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "homebrew"
+    fi
+    return
+  fi
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "homebrew"
+    log "Homebrew not found."
+    log "[dry-run] would run: NONINTERACTIVE=1 /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""
+    return
+  fi
+  log "Homebrew not found. Installing Homebrew."
+  NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+}
+
+load_brew_shellenv() {
+  local brew_bin
+  for brew_bin in /opt/homebrew/bin/brew /usr/local/bin/brew; do
+    if [[ -x "$brew_bin" ]]; then
+      eval "$("$brew_bin" shellenv)"
+      return
+    fi
+  done
+  fail "brew executable was not found after installation."
+}
+
+ensure_brew_ready() {
+  if [[ "$BREW_READY" == "true" ]]; then
+    return
+  fi
+  if ! command -v brew >/dev/null 2>&1; then
+    ensure_homebrew
+    if [[ "$DRY_RUN" == "true" ]]; then
+      BREW_READY="true"
+      return
+    fi
+  fi
+  load_brew_shellenv
+  BREW_READY="true"
+  if [[ "$MACOS_SETUP_BREW_UPDATE" == "true" && "$BREW_UPDATED" != "true" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      log_dry_run_command brew update
+    else
+      log "Running brew update."
+      brew update
+    fi
+    BREW_UPDATED="true"
+  fi
+}
+
+brew_install_formula_if_missing() {
+  local name="$1"
+  ensure_brew_ready
+  if ! command -v brew >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_install "brew formula: $name"
+      log_dry_run_command brew install "$name"
+      return
+    fi
+    fail "brew is required to install formula: $name"
+  fi
+  if brew list --formula "$name" >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "brew formula: $name"
+    fi
+    return
+  fi
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "brew formula: $name"
+    log_dry_run_command brew install "$name"
+    return
+  fi
+  log "Installing Homebrew formula: $name"
+  brew install "$name"
+}
+
+brew_install_cask_if_missing() {
+  local name="$1"
+  ensure_brew_ready
+  if ! command -v brew >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_install "brew cask: $name"
+      log_dry_run_command brew install --cask "$name"
+      return
+    fi
+    fail "brew is required to install cask: $name"
+  fi
+  if brew list --cask "$name" >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "brew cask: $name"
+    fi
+    return
+  fi
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "brew cask: $name"
+    log_dry_run_command brew install --cask "$name"
+    return
+  fi
+  log "Installing Homebrew cask: $name"
+  brew install --cask "$name"
+}
+
+ensure_profile_export_block() {
+  local profile_path="$1"
+  local marker_begin="# >>> macos-remote-setup >>>"
+  local marker_end="# <<< macos-remote-setup <<<"
+  local block
+  block="$(cat <<EOF_BLOCK
+$marker_begin
+export ANDROID_SDK_ROOT="$ANDROID_SDK_ROOT"
+export ANDROID_HOME="$ANDROID_SDK_ROOT"
+if [[ -d "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home" ]]; then
+  export JAVA_HOME="/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home"
+elif [[ -x "/usr/libexec/java_home" ]]; then
+  export JAVA_HOME="$(/usr/libexec/java_home -v 17 2>/dev/null || true)"
+fi
+if [[ -n "\${JAVA_HOME:-}" ]]; then
+  export PATH="\$JAVA_HOME/bin:\$PATH"
+fi
+export PATH="\$PATH:\$ANDROID_SDK_ROOT/platform-tools:\$ANDROID_SDK_ROOT/emulator:\$ANDROID_SDK_ROOT/cmdline-tools/latest/bin"
+if [[ -d "\$HOME/.bun/bin" ]]; then
+  export PATH="\$HOME/.bun/bin:\$PATH"
+fi
+if command -v brew >/dev/null 2>&1; then
+  eval "\$(brew shellenv)"
+fi
+$marker_end
+EOF_BLOCK
+)"
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    if [[ -f "$profile_path" ]]; then
+      if grep -Fq "$marker_begin" "$profile_path"; then
+        record_dry_run_skip "shell profile block: $profile_path"
+      else
+        record_dry_run_install "shell profile block: $profile_path"
+      fi
+    else
+      record_dry_run_install "shell profile block: $profile_path"
+    fi
+    log_dry_run_command update-shell-profile "$profile_path"
+    return
+  fi
+
+  mkdir -p "$(dirname "$profile_path")"
+  touch "$profile_path"
+  if grep -Fq "$marker_begin" "$profile_path"; then
+    awk -v begin="$marker_begin" -v end="$marker_end" -v replace="$block" '
+      $0 == begin { print replace; in_block=1; next }
+      $0 == end { in_block=0; next }
+      !in_block { print }
+    ' "$profile_path" >"${profile_path}.tmp"
+    mv "${profile_path}.tmp" "$profile_path"
+    return
+  fi
+
+  {
+    printf "\n%s\n" "$block"
+  } >>"$profile_path"
+}
+
+ensure_path_for_current_session() {
+  export ANDROID_HOME="$ANDROID_SDK_ROOT"
+  if [[ -d "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home" ]]; then
+    export JAVA_HOME="/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home"
+  elif [[ -x "/usr/libexec/java_home" ]]; then
+    export JAVA_HOME="$(/usr/libexec/java_home -v 17 2>/dev/null || true)"
+  fi
+  if [[ -n "${JAVA_HOME:-}" ]]; then
+    export PATH="$JAVA_HOME/bin:$PATH"
+  fi
+  export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/emulator:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin"
+  if [[ -d "$HOME/.bun/bin" ]]; then
+    export PATH="$HOME/.bun/bin:$PATH"
+  fi
+}
+
+find_sdkmanager_bin() {
+  find_android_cmdline_tool "sdkmanager"
+}
+
+find_avdmanager_bin() {
+  find_android_cmdline_tool "avdmanager"
+}
+
+find_android_cmdline_tool() {
+  local tool_name="$1"
+  local candidate
+  local brew_prefix=""
+  if command -v "$tool_name" >/dev/null 2>&1; then
+    command -v "$tool_name"
+    return
+  fi
+  if command -v brew >/dev/null 2>&1; then
+    brew_prefix="$(brew --prefix 2>/dev/null || true)"
+  fi
+
+  for candidate in \
+    "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/$tool_name" \
+    "$brew_prefix/share/android-commandlinetools/cmdline-tools/latest/bin/$tool_name" \
+    "/opt/homebrew/share/android-commandlinetools/cmdline-tools/latest/bin/$tool_name" \
+    "/usr/local/share/android-commandlinetools/cmdline-tools/latest/bin/$tool_name"; do
+    if [[ -x "$candidate" ]]; then
+      printf "%s\n" "$candidate"
+      return
+    fi
+  done
+  printf "\n"
+}
+
+find_emulator_bin() {
+  if command -v emulator >/dev/null 2>&1; then
+    command -v emulator
+    return
+  fi
+  if [[ -x "$ANDROID_SDK_ROOT/emulator/emulator" ]]; then
+    printf "%s\n" "$ANDROID_SDK_ROOT/emulator/emulator"
+    return
+  fi
+  printf "\n"
+}
+
+current_xcode_version() {
+  xcodebuild -version 2>/dev/null | awk '/^Xcode / {print $2; exit}' || true
+}
+
+resolve_latest_ios_runtime_identifier() {
+  xcrun simctl list runtimes --json 2>/dev/null | node -e '
+    const fs = require("node:fs");
+    const parsed = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+    const runtimes = Array.isArray(parsed.runtimes) ? parsed.runtimes : [];
+    const ios = runtimes.filter((r) =>
+      r && typeof r.identifier === "string" &&
+      r.identifier.includes(".iOS-") &&
+      r.isAvailable !== false &&
+      !(typeof r.availability === "string" && r.availability.includes("unavailable"))
+    );
+    ios.sort((a, b) => String(a.identifier).localeCompare(String(b.identifier), undefined, { numeric: true }));
+    process.stdout.write(ios.length > 0 ? ios[ios.length - 1].identifier : "");
+  ' || true
+}
+
+android_package_installed() {
+  local pkg="$1"
+  case "$pkg" in
+    platform-tools)
+      [[ -x "$ANDROID_SDK_ROOT/platform-tools/adb" ]]
+      ;;
+    emulator)
+      [[ -x "$ANDROID_SDK_ROOT/emulator/emulator" ]]
+      ;;
+    "cmdline-tools;latest")
+      [[ -x "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager" ]]
+      ;;
+    *)
+      [[ -d "$ANDROID_SDK_ROOT/${pkg//;/\/}" ]]
+      ;;
+  esac
+}
+
+resolve_java17_home() {
+  if [[ -d "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home" ]]; then
+    printf "%s\n" "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home"
+    return
+  fi
+  if [[ -x "/usr/libexec/java_home" ]]; then
+    /usr/libexec/java_home -v 17 2>/dev/null || true
+    return
+  fi
+  printf "\n"
+}
+
+find_zulu17_pkg() {
+  if ! command -v brew >/dev/null 2>&1; then
+    printf "\n"
+    return
+  fi
+  local cask_dir
+  cask_dir="$(brew --prefix)/Caskroom/zulu@17"
+  if [[ ! -d "$cask_dir" ]]; then
+    printf "\n"
+    return
+  fi
+  find "$cask_dir" -maxdepth 3 -type f -name "*.pkg" -print 2>/dev/null | head -n 1 || true
+}
+
+ensure_zulu17_jdk() {
+  if [[ "$(normalize_bool "$MACOS_SETUP_INSTALL_ZULU_JDK")" != "true" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "zulu@17 jdk"
+    fi
+    return
+  fi
+
+  local java_home
+  java_home="$(resolve_java17_home)"
+  if [[ -n "$java_home" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "zulu@17 jdk"
+    fi
+    export JAVA_HOME="$java_home"
+    export PATH="$JAVA_HOME/bin:$PATH"
+    return
+  fi
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "zulu@17 jdk"
+  fi
+  brew_install_cask_if_missing "zulu@17"
+  local zulu_pkg
+  zulu_pkg="$(find_zulu17_pkg)"
+  if [[ -n "$zulu_pkg" ]]; then
+    log "Installing Azul Zulu JDK 17 package."
+    run_as_admin installer -pkg "$zulu_pkg" -target /
+  else
+    warn "Zulu JDK installer package not found in Caskroom; manual install may be required."
+    brew info --cask zulu@17 || true
+    if [[ "$DRY_RUN" == "true" ]]; then
+      return
+    fi
+  fi
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log "[dry-run] would export JAVA_HOME from installed JDK 17 path."
+    return
+  fi
+
+  java_home="$(resolve_java17_home)"
+  if [[ -z "$java_home" ]]; then
+    fail "JDK 17 not detected after zulu@17 install. Install 'Double-Click to Install Azul Zulu JDK 17.pkg' from the zulu@17 Caskroom and rerun."
+  fi
+
+  export JAVA_HOME="$java_home"
+  export PATH="$JAVA_HOME/bin:$PATH"
+}
+
+ensure_xcodes_cli() {
+  if command -v xcodes >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "xcodes cli"
+    fi
+    return
+  fi
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "xcodes cli"
+  fi
+  ensure_brew_ready
+  log "Installing xcodes CLI."
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log_dry_run_command brew tap xcodesorg/made
+    log_dry_run_command brew install xcodes
+    return
+  fi
+  brew tap xcodesorg/made >/dev/null 2>&1 || true
+  if ! brew install xcodes >/dev/null 2>&1; then
+    brew install xcodesorg/made/xcodes
+  fi
+}
+
+ensure_latest_xcode_install() {
+  local strict="$1"
+  local install_help
+  local -a install_args=("install")
+
+  if [[ "$(normalize_bool "$MACOS_SETUP_INSTALL_XCODE")" != "true" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "xcode"
+    fi
+    return
+  fi
+  if [[ "$MACOS_SETUP_XCODE_VERSION" == "latest" && -n "$(resolve_latest_xcode_developer_dir)" ]]; then
+    log "Xcode app already present; skipping xcodes install."
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "xcode"
+    fi
+    return
+  fi
+  if [[ "$MACOS_SETUP_XCODE_VERSION" != "latest" ]]; then
+    local installed_version
+    installed_version="$(current_xcode_version)"
+    if [[ -n "$installed_version" && "$installed_version" == "$MACOS_SETUP_XCODE_VERSION" ]]; then
+      log "Requested Xcode version already active ($installed_version); skipping xcodes install."
+      if [[ "$DRY_RUN" == "true" ]]; then
+        record_dry_run_skip "xcode $MACOS_SETUP_XCODE_VERSION"
+      fi
+      return
+    fi
+  fi
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    if [[ "$MACOS_SETUP_XCODE_VERSION" == "latest" ]]; then
+      record_dry_run_install "xcode latest"
+    else
+      record_dry_run_install "xcode $MACOS_SETUP_XCODE_VERSION"
+    fi
+  fi
+  ensure_xcodes_cli
+  if command -v xcodes >/dev/null 2>&1; then
+    install_help="$(xcodes help install 2>/dev/null || xcodes install --help 2>/dev/null || true)"
+  else
+    install_help=""
+  fi
+
+  if [[ "$MACOS_SETUP_XCODE_VERSION" == "latest" ]]; then
+    if grep -Fq -- "--latest" <<<"$install_help"; then
+      install_args+=("--latest")
+    else
+      install_args+=("latest")
+    fi
+  else
+    install_args+=("$MACOS_SETUP_XCODE_VERSION")
+  fi
+
+  if grep -Fq -- "--select" <<<"$install_help"; then
+    install_args+=("--select")
+  fi
+
+  log "Installing/selecting Xcode via xcodes (${install_args[*]})."
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log_dry_run_command xcodes "${install_args[@]}"
+    return
+  fi
+  if ! xcodes "${install_args[@]}"; then
+    if [[ "$strict" == "true" ]]; then
+      fail "xcodes install failed. Authenticate with xcodes and rerun."
+    fi
+    warn "xcodes install failed. Continuing because strict mode is disabled."
+  fi
+}
+
+resolve_latest_xcode_developer_dir() {
+  local app_path
+  app_path="$(ls -dt /Applications/Xcode*.app 2>/dev/null | head -n 1 || true)"
+  if [[ -n "$app_path" && -d "$app_path/Contents/Developer" ]]; then
+    printf "%s\n" "$app_path/Contents/Developer"
+    return
+  fi
+  printf "\n"
+}
+
+ensure_xcode_cli_setup() {
+  local developer_dir
+  developer_dir="$(resolve_latest_xcode_developer_dir)"
+  if [[ -z "$developer_dir" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "no local Xcode app currently detected; dry-run cannot validate xcode-select setup."
+      return
+    fi
+    fail "could not resolve /Applications/Xcode*.app. Install Xcode first."
+  fi
+
+  log "Setting active developer directory: $developer_dir"
+  run_as_admin xcode-select -s "$developer_dir"
+  run_as_admin xcodebuild -license accept >/dev/null 2>&1 || true
+  run_as_admin xcodebuild -runFirstLaunch >/dev/null 2>&1 || true
+  if [[ "$DRY_RUN" == "true" ]]; then
+    return
+  fi
+
+  if ! xcode-select -p >/dev/null 2>&1; then
+    fail "xcode-select is not configured after setup."
+  fi
+}
+
+ensure_ios_runtime_and_simulator() {
+  local runtime_identifier
+  runtime_identifier="$(resolve_latest_ios_runtime_identifier)"
+  if [[ -n "$runtime_identifier" ]]; then
+    log "iOS simulator runtime already available; skipping runtime download."
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "ios simulator runtime"
+    fi
+  elif [[ "$(normalize_bool "$MACOS_SETUP_INSTALL_IOS_RUNTIME")" == "true" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_install "ios simulator runtime"
+    fi
+    log "Attempting to ensure iOS simulator platform runtime."
+    if [[ "$DRY_RUN" == "true" ]]; then
+      log_dry_run_command xcodebuild -downloadPlatform iOS
+    else
+      xcodebuild -downloadPlatform iOS >/dev/null 2>&1 || warn "xcodebuild -downloadPlatform iOS failed; continuing."
+      runtime_identifier="$(resolve_latest_ios_runtime_identifier)"
+    fi
+  elif [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_skip "ios simulator runtime (disabled)"
+  fi
+
+  if [[ -z "$runtime_identifier" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "no available iOS runtime currently; simulator creation plan may be incomplete in dry-run mode."
+      return
+    fi
+    fail "no available iOS simulator runtime found after setup."
+  fi
+
+  local existing_udid
+  existing_udid="$(xcrun simctl list devices --json 2>/dev/null | node -e '
+    const fs = require("node:fs");
+    const target = process.argv[1];
+    const parsed = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+    for (const list of Object.values(parsed.devices || {})) {
+      if (!Array.isArray(list)) continue;
+      for (const device of list) {
+        if (!device || typeof device !== "object") continue;
+        if (device.name !== target) continue;
+        if (device.isAvailable === false) continue;
+        if (typeof device.udid === "string") {
+          process.stdout.write(device.udid);
+          process.exit(0);
+        }
+      }
+    }
+  ' "$MACOS_SETUP_IOS_SIMULATOR_NAME" || true)"
+  if [[ -n "$existing_udid" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "ios simulator: $MACOS_SETUP_IOS_SIMULATOR_NAME"
+    fi
+    return
+  fi
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "ios simulator: $MACOS_SETUP_IOS_SIMULATOR_NAME"
+  fi
+
+  local device_type_identifier
+  device_type_identifier="$(xcrun simctl list devicetypes --json 2>/dev/null | node -e '
+    const fs = require("node:fs");
+    const target = process.argv[1].trim().toLowerCase();
+    const parsed = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+    const list = Array.isArray(parsed.devicetypes) ? parsed.devicetypes : [];
+    const exact = list.find((e) =>
+      e && typeof e.name === "string" && typeof e.identifier === "string" &&
+      e.name.trim().toLowerCase() === target
+    );
+    if (exact) {
+      process.stdout.write(exact.identifier);
+      process.exit(0);
+    }
+    const fallback = list.find((e) =>
+      e && typeof e.name === "string" && typeof e.identifier === "string" && /^iphone/i.test(e.name)
+    );
+    if (fallback) process.stdout.write(fallback.identifier);
+  ' "$MACOS_SETUP_IOS_SIMULATOR_NAME" || true)"
+
+  if [[ -z "$device_type_identifier" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "unable to resolve iOS simulator device type in dry-run mode."
+      return
+    fi
+    fail "failed to resolve iOS simulator device type."
+  fi
+
+  log "Creating default iOS simulator: $MACOS_SETUP_IOS_SIMULATOR_NAME"
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log_dry_run_command xcrun simctl create "$MACOS_SETUP_IOS_SIMULATOR_NAME" "$device_type_identifier" "$runtime_identifier"
+    return
+  fi
+  xcrun simctl create "$MACOS_SETUP_IOS_SIMULATOR_NAME" "$device_type_identifier" "$runtime_identifier" >/dev/null
+}
+
+ensure_node_and_package_managers() {
+  if ! command -v node >/dev/null 2>&1; then
+    brew_install_formula_if_missing "node"
+  elif [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_skip "node"
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    brew_install_formula_if_missing "jq"
+  elif [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_skip "jq"
+  fi
+
+  if [[ "$(normalize_bool "$MACOS_SETUP_INSTALL_COCOAPODS")" == "true" ]] && ! command -v pod >/dev/null 2>&1; then
+    brew_install_formula_if_missing "cocoapods"
+  elif [[ "$DRY_RUN" == "true" ]]; then
+    if [[ "$(normalize_bool "$MACOS_SETUP_INSTALL_COCOAPODS")" == "true" ]]; then
+      record_dry_run_skip "cocoapods"
+    else
+      record_dry_run_skip "cocoapods (disabled)"
+    fi
+  fi
+  ensure_zulu17_jdk
+  ensure_path_for_current_session
+
+  if command -v corepack >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      log_dry_run_command corepack enable
+    else
+      corepack enable >/dev/null 2>&1 || true
+    fi
+    if ! command -v pnpm >/dev/null 2>&1; then
+      if [[ "$DRY_RUN" == "true" ]]; then
+        record_dry_run_install "pnpm"
+        log_dry_run_command corepack prepare pnpm@latest --activate
+      else
+        corepack prepare pnpm@latest --activate
+      fi
+    elif [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "pnpm"
+    fi
+    if ! command -v yarn >/dev/null 2>&1; then
+      if [[ "$DRY_RUN" == "true" ]]; then
+        record_dry_run_install "yarn"
+        log_dry_run_command corepack prepare yarn@stable --activate
+      else
+        corepack prepare yarn@stable --activate
+      fi
+    elif [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "yarn"
+    fi
+  else
+    local -a missing_pkg_managers=()
+    if ! command -v pnpm >/dev/null 2>&1; then
+      missing_pkg_managers+=("pnpm")
+    fi
+    if ! command -v yarn >/dev/null 2>&1; then
+      missing_pkg_managers+=("yarn")
+    fi
+    if [[ "${#missing_pkg_managers[@]}" -gt 0 ]]; then
+      if [[ "$DRY_RUN" == "true" ]]; then
+        local manager
+        for manager in "${missing_pkg_managers[@]}"; do
+          record_dry_run_install "$manager"
+        done
+        log_dry_run_command npm install -g "${missing_pkg_managers[@]}"
+      else
+        npm install -g "${missing_pkg_managers[@]}"
+      fi
+    elif [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "pnpm"
+      record_dry_run_skip "yarn"
+    fi
+  fi
+
+  ensure_bun
+}
+
+ensure_bun() {
+  if command -v bun >/dev/null 2>&1; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "bun"
+    fi
+    return
+  fi
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "bun"
+    log_dry_run_command /bin/bash -c "curl -fsSL https://bun.sh/install | bash"
+    return
+  fi
+
+  log "Installing Bun with the official install script."
+  /bin/bash -c "$(curl -fsSL https://bun.sh/install)"
+  if [[ -d "$HOME/.bun/bin" ]]; then
+    export PATH="$HOME/.bun/bin:$PATH"
+  fi
+}
+
+ensure_android_sdk_and_emulator() {
+  if [[ "$(normalize_bool "$MACOS_SETUP_INSTALL_ANDROID")" != "true" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "android sdk/emulator"
+    fi
+    return
+  fi
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log_dry_run_command mkdir -p "$ANDROID_SDK_ROOT"
+  else
+    mkdir -p "$ANDROID_SDK_ROOT"
+  fi
+  if ! command -v sdkmanager >/dev/null 2>&1 || ! command -v avdmanager >/dev/null 2>&1; then
+    brew_install_cask_if_missing "android-commandlinetools"
+  elif [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_skip "brew cask: android-commandlinetools"
+  fi
+  if ! command -v adb >/dev/null 2>&1; then
+    brew_install_formula_if_missing "android-platform-tools"
+  elif [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_skip "brew formula: android-platform-tools"
+  fi
+  ensure_path_for_current_session
+  if [[ -z "$(resolve_java17_home)" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "java runtime 17 not found currently; dry-run cannot validate android sdk steps."
+      return
+    fi
+    fail "java runtime 17 not found. Enable MACOS_SETUP_INSTALL_ZULU_JDK=true and rerun."
+  fi
+
+  local sdkmanager_bin
+  sdkmanager_bin="$(find_sdkmanager_bin)"
+  if [[ -z "$sdkmanager_bin" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "sdkmanager not found currently; dry-run cannot resolve exact Android package plan."
+      return
+    fi
+    fail "sdkmanager not found after android-commandlinetools install."
+  fi
+  local avdmanager_bin
+  avdmanager_bin="$(find_avdmanager_bin)"
+  if [[ -z "$avdmanager_bin" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "avdmanager not found currently; dry-run cannot resolve exact Android AVD plan."
+      return
+    fi
+    fail "avdmanager not found after android-commandlinetools install."
+  fi
+
+  log "Accepting Android SDK licenses."
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log_dry_run_command "$sdkmanager_bin" --sdk_root="$ANDROID_SDK_ROOT" --licenses
+  else
+    yes | "$sdkmanager_bin" --sdk_root="$ANDROID_SDK_ROOT" --licenses >/dev/null || true
+  fi
+
+  local sdk_list
+  sdk_list="$("$sdkmanager_bin" --sdk_root="$ANDROID_SDK_ROOT" --list | tr -d '\r')"
+  local api_level
+  if [[ "$MACOS_SETUP_ANDROID_API" == "latest" ]]; then
+    api_level="$(printf "%s\n" "$sdk_list" | grep -Eo 'system-images;android-[0-9]+;google_apis(_playstore)?;(arm64-v8a|x86_64)' | sed -E 's/^system-images;android-([0-9]+);.*$/\1/' | sort -uV | tail -n 1 || true)"
+  else
+    api_level="$MACOS_SETUP_ANDROID_API"
+  fi
+
+  if [[ -z "$api_level" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "unable to resolve Android API level from current sdkmanager list in dry-run."
+      return
+    fi
+    fail "unable to resolve Android API level from sdkmanager system image list."
+  fi
+
+  local arch_suffix="x86_64"
+  if [[ "$(uname -m)" == "arm64" ]]; then
+    arch_suffix="arm64-v8a"
+  fi
+
+  local system_image_pkg=""
+  local candidate
+  for candidate in \
+    "system-images;android-$api_level;google_apis;$arch_suffix" \
+    "system-images;android-$api_level;google_apis_playstore;$arch_suffix"; do
+    if printf "%s\n" "$sdk_list" | grep -Fq "$candidate"; then
+      system_image_pkg="$candidate"
+      break
+    fi
+  done
+  if [[ -z "$system_image_pkg" ]]; then
+    fail "unable to resolve Android system image package for api=$api_level arch=$arch_suffix."
+  fi
+
+  local -a packages=("cmdline-tools;latest" "platform-tools" "emulator" "$system_image_pkg")
+  local -a missing_packages=()
+  local pkg
+  for pkg in "${packages[@]}"; do
+    if ! android_package_installed "$pkg"; then
+      if [[ "$DRY_RUN" == "true" ]]; then
+        record_dry_run_install "android sdk package: $pkg"
+      fi
+      missing_packages+=("$pkg")
+    elif [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "android sdk package: $pkg"
+    fi
+  done
+
+  if [[ "${#missing_packages[@]}" -gt 0 ]]; then
+    log "Installing missing Android SDK packages: ${missing_packages[*]}"
+    if [[ "$DRY_RUN" == "true" ]]; then
+      log_dry_run_command "$sdkmanager_bin" --sdk_root="$ANDROID_SDK_ROOT" --install "${missing_packages[@]}"
+    else
+      "$sdkmanager_bin" --sdk_root="$ANDROID_SDK_ROOT" --install "${missing_packages[@]}"
+    fi
+  else
+    log "Android SDK packages already present; skipping sdkmanager install."
+  fi
+
+  local emulator_bin
+  emulator_bin="$(find_emulator_bin)"
+  if [[ -z "$emulator_bin" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      warn "emulator binary not found currently; dry-run cannot validate AVD creation step."
+      return
+    fi
+    fail "emulator binary not found after SDK package install."
+  fi
+
+  if ! "$emulator_bin" -list-avds | grep -Fxq "$MACOS_SETUP_ANDROID_AVD_NAME"; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_install "android avd: $MACOS_SETUP_ANDROID_AVD_NAME"
+    fi
+    log "Creating default Android AVD: $MACOS_SETUP_ANDROID_AVD_NAME"
+    if [[ "$DRY_RUN" == "true" ]]; then
+      log_dry_run_command "$avdmanager_bin" create avd -n "$MACOS_SETUP_ANDROID_AVD_NAME" -k "$system_image_pkg" -d "$MACOS_SETUP_ANDROID_DEVICE_PROFILE" --force
+      return
+    fi
+    if ! (set +o pipefail; echo "no" | "$avdmanager_bin" create avd \
+      -n "$MACOS_SETUP_ANDROID_AVD_NAME" \
+      -k "$system_image_pkg" \
+      -d "$MACOS_SETUP_ANDROID_DEVICE_PROFILE" \
+      --force >/dev/null 2>&1); then
+      (set +o pipefail; echo "no" | "$avdmanager_bin" create avd \
+        -n "$MACOS_SETUP_ANDROID_AVD_NAME" \
+        -k "$system_image_pkg" \
+        --force >/dev/null)
+    fi
+  elif [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_skip "android avd: $MACOS_SETUP_ANDROID_AVD_NAME"
+  fi
+}
+
+ensure_agent_device_cli() {
+  if [[ "$(normalize_bool "$MACOS_SETUP_INSTALL_AGENT_DEVICE")" != "true" ]]; then
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "agent-device"
+      record_dry_run_skip "agent-device-proxy"
+    fi
+    return
+  fi
+  if command -v agent-device >/dev/null 2>&1 && command -v agent-device-proxy >/dev/null 2>&1; then
+    log "agent-device and agent-device-proxy already installed; skipping npm global install."
+    if [[ "$DRY_RUN" == "true" ]]; then
+      record_dry_run_skip "agent-device"
+      record_dry_run_skip "agent-device-proxy"
+    fi
+    return
+  fi
+  if [[ "$DRY_RUN" == "true" ]]; then
+    record_dry_run_install "agent-device"
+    record_dry_run_install "agent-device-proxy"
+    log_dry_run_command npm install -g agent-device@latest agent-device-proxy@latest
+    return
+  fi
+  log "Installing/updating global agent-device and agent-device-proxy CLIs."
+  npm install -g agent-device@latest agent-device-proxy@latest
+
+  local missing_bins=()
+  local candidate
+  for candidate in agent-device agent-device-proxy; do
+    if ! command -v "$candidate" >/dev/null 2>&1; then
+      missing_bins+=("$candidate")
+    fi
+  done
+
+  if [[ "${#missing_bins[@]}" -gt 0 ]]; then
+    fail "npm global install completed, but these commands are still unavailable on PATH: ${missing_bins[*]}"
+  fi
+
+  log "Installed agent-device: $(command -v agent-device)"
+  log "Installed agent-device-proxy: $(command -v agent-device-proxy)"
+}
+
+print_dry_run_summary() {
+  local item
+  if [[ "$DRY_RUN" != "true" ]]; then
+    return
+  fi
+
+  log "Dry-run summary:"
+  if [[ "${#DRY_RUN_INSTALLS[@]}" -gt 0 ]]; then
+    log "  would install:"
+    for item in "${DRY_RUN_INSTALLS[@]}"; do
+      log "    - $item"
+    done
+  else
+    log "  would install: none"
+  fi
+
+  if [[ "${#DRY_RUN_SKIPS[@]}" -gt 0 ]]; then
+    log "  would skip:"
+    for item in "${DRY_RUN_SKIPS[@]}"; do
+      log "    - $item"
+    done
+  else
+    log "  would skip: none"
+  fi
+  log "No changes were applied."
+}
+
+main() {
+  parse_args "$@"
+  ensure_macos_host
+  prime_login_shell_environment
+  prime_default_macos_paths
+  MACOS_SETUP_BREW_UPDATE="$(normalize_bool "$MACOS_SETUP_BREW_UPDATE")"
+  MACOS_SETUP_STRICT_XCODE="$(normalize_bool "$MACOS_SETUP_STRICT_XCODE")"
+
+  ensure_node_and_package_managers
+  ensure_latest_xcode_install "$MACOS_SETUP_STRICT_XCODE"
+  ensure_xcode_cli_setup
+  ensure_ios_runtime_and_simulator
+  ensure_android_sdk_and_emulator
+  ensure_agent_device_cli
+  ensure_profile_export_block "$MACOS_SETUP_SHELL_PROFILE"
+  print_dry_run_summary
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log "Dry-run complete."
+    return
+  fi
+
+  log "Setup complete."
+  log "Run these verification commands:"
+  log "  xcode-select -p"
+  log "  xcrun simctl list runtimes | grep iOS"
+  log "  pnpm --version && yarn --version && bun --version && node -v"
+  log "  sdkmanager --sdk_root=\"$ANDROID_SDK_ROOT\" --list | head -n 20"
+  log "  pnpm --filter @platform/runtime podman:ios:preflight"
+}
+
+main "$@"