@sun-asterisk/sungen 3.2.31 → 3.2.32

package/src/orchestrator/templates/appium-environment/scripts/common/verify-appium.ps1

@@ -0,0 +1,39 @@
+# verify-appium.ps1 - the final gate: `appium driver doctor uiautomator2` checks the whole chain the
+# driver needs at run time (JAVA_HOME, ANDROID_HOME, adb). Doctor problems are reported as warnings
+# with the doctor's own output - it names the missing piece.
+if (-not $script:SungenEnvLibLoaded) { . (Join-Path $PSScriptRoot 'lib.ps1') }
+
+$AppiumCmd = $script:SungenEnvAppiumCmd
+# Doctor prints a required failure as a heavy-ballot-x line; the character is referenced by code point
+# so this file stays ASCII (Windows PowerShell 5.1 reads BOM-less scripts as ANSI).
+$RequiredFailMark = [string][char]0x2716
+
+Invoke-Check -Title 'Appium CLI' -Check {
+  if (Test-Path $AppiumCmd) { "appium $((& $AppiumCmd -v) 2>$null | Select-Object -First 1)" }
+} -Hint 'not installed in this project - sungen capability add mobile'
+
+if ((Test-Path $AppiumCmd) -and -not $script:SungenEnvSkipAndroid) {
+  $installed = (& $AppiumCmd driver list --installed --json) 2>$null | Out-String
+  if ($installed -match '"uiautomator2"') {
+    # Inline (not Invoke-Check) so the failure detail prints AFTER the step title, like every other step.
+    $title = 'appium driver doctor uiautomator2'
+    $hint = 'fix the required items above (open a NEW terminal first if the environment was just written), then re-run'
+    $out = (& $AppiumCmd driver doctor uiautomator2 2>&1) | Out-String
+    $rc = $LASTEXITCODE
+    # Doctor marks BOTH required and optional problems with the same mark, so read its summary line:
+    #   "### Diagnostic completed, N required fixes needed, M optional fixes possible. ###"
+    $req = $null; if ($out -match 'Diagnostic completed, (\d+) required fix') { $req = [int]$Matches[1] }
+    $opt = 0;     if ($out -match ', (\d+) optional fix') { $opt = [int]$Matches[1] }
+    if ($null -eq $req) {
+      # No summary line (older driver) - fall back to the exit code.
+      if ($rc -eq 0) { Write-Ok $title 'doctor exited 0' } else { Write-Warn $title "$out`n$hint" }
+    } elseif ($req -gt 0) {
+      $marks = @(($out -split "`r?`n") | Where-Object { $_.Contains($RequiredFailMark) } | ForEach-Object { $_ -replace '^.*Doctor\s+', '' })
+      Write-Warn $title ("$req required fix(es) needed:`n" + ($marks -join "`n") + "`nfull report: npx appium driver doctor uiautomator2`n$hint")
+    } else {
+      Write-Ok $title "0 required fixes, $opt optional (extras like bundletool / gstreamer - see: npx appium driver doctor uiautomator2)"
+    }
+  } else {
+    Write-Warn 'appium driver doctor uiautomator2' 'driver not installed - see the Appium step above'
+  }
+}

package/src/orchestrator/templates/appium-environment/scripts/common/verify-appium.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# verify-appium.sh — the final gate: `appium driver doctor <driver>` checks the whole chain the
+# driver needs at run time (JAVA_HOME, ANDROID_HOME, adb; Xcode + simctl for xcuitest).
+# Doctor problems are reported as warnings with the doctor's own output — it names the missing piece.
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] || . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib.sh"
+
+APPIUM_BIN=$SUNGEN_ENV_APPIUM_BIN
+
+appium_cli_check() { [ -x "$APPIUM_BIN" ] || return 1; printf 'appium %s' "$("$APPIUM_BIN" -v 2>/dev/null)"; }
+run_check "Appium CLI" appium_cli_check "not installed in this project — sungen capability add mobile"
+
+doctor_check() {
+  local out rc req opt
+  out=$("$APPIUM_BIN" driver doctor "$CURRENT_DRIVER" 2>&1); rc=$?
+  # Doctor marks BOTH required and optional problems with "✖", so read its own summary line instead:
+  #   "### Diagnostic completed, N required fixes needed, M optional fixes possible. ###"
+  req=$(printf '%s\n' "$out" | sed -n -E 's/.*Diagnostic completed, ([0-9]+) required fix.*/\1/p' | tail -n1)
+  opt=$(printf '%s\n' "$out" | sed -n -E 's/.*, ([0-9]+) optional fix.*/\1/p' | tail -n1)
+  if [ -z "$req" ]; then
+    # No summary line (older driver) — fall back to the exit code.
+    [ "$rc" -eq 0 ] && { printf 'doctor exited 0'; return 0; }
+    printf '%s' "$out"; return 1
+  fi
+  if [ "$req" -gt 0 ]; then
+    printf '%s required fix(es) needed:\n%s\nfull report: npx appium driver doctor %s' "$req" \
+      "$(printf '%s\n' "$out" | grep '✖' | sed -E 's/^.*Doctor +//')" "$CURRENT_DRIVER"
+    return 1
+  fi
+  printf '0 required fixes · %s optional (extras like bundletool / gstreamer — see: npx appium driver doctor %s)' "${opt:-0}" "$CURRENT_DRIVER"
+}
+
+if [ -x "$APPIUM_BIN" ]; then
+  DOCTOR_DRIVERS=""
+  [ "$SUNGEN_ENV_SKIP_ANDROID" != 1 ] && DOCTOR_DRIVERS="uiautomator2"
+  if [ "$(uname -s)" = Darwin ] && [ "$SUNGEN_ENV_SKIP_IOS" != 1 ]; then DOCTOR_DRIVERS="$DOCTOR_DRIVERS xcuitest"; fi
+  for CURRENT_DRIVER in $DOCTOR_DRIVERS; do
+    if printf '%s' "$("$APPIUM_BIN" driver list --installed --json 2>/dev/null)" | grep -q "\"$CURRENT_DRIVER\""; then
+      run_check "appium driver doctor $CURRENT_DRIVER" doctor_check "fix the required items above (open a NEW terminal first if the profile block was just written), then re-run" warn
+    else
+      log_warn "appium driver doctor $CURRENT_DRIVER" "driver not installed — see the Appium step above"
+    fi
+  done
+fi

package/src/orchestrator/templates/appium-environment/scripts/common/verify-node.ps1

@@ -0,0 +1,13 @@
+# verify-node.ps1 - Node.js >= 18 (sungen's own engine floor). Never installs Node: sungen is already
+# running on it when this bundle is invoked from `sungen init`; a standalone run gets the guide.
+if (-not $script:SungenEnvLibLoaded) { . (Join-Path $PSScriptRoot 'lib.ps1') }
+
+$NodeMin = 18
+Invoke-Check -Title "Node.js >= $NodeMin" -Check {
+  if (-not (Get-Command node -ErrorAction SilentlyContinue)) { return $null }
+  $v = (& node -v) 2>$null
+  $major = 0; if ("$v" -match '(\d+)') { $major = [int]$Matches[1] }
+  if ($major -lt $NodeMin) { return $null }
+  $npm = (& npm -v) 2>$null
+  "node $v, npm $npm"
+} -Hint 'install Node LTS: https://nodejs.org  (or: winget install OpenJS.NodeJS.LTS), then open a new terminal'

package/src/orchestrator/templates/appium-environment/scripts/common/verify-node.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# verify-node.sh — Node.js ≥ 18 (sungen's own engine floor). Never installs Node: sungen is already
+# running on it when this bundle is invoked from `sungen init`; a standalone run gets the guide.
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] || . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib.sh"
+
+NODE_MIN=18
+
+node_check() {
+  local v major
+  have node || return 1
+  v=$(node -v 2>/dev/null) || return 1
+  major=$(version_major "$v")
+  [ "$major" -ge "$NODE_MIN" ] || { printf 'node %s is below %s' "$v" "$NODE_MIN"; return 1; }
+  printf 'node %s · npm %s' "$v" "$(npm -v 2>/dev/null || printf '?')"
+}
+run_check "Node.js ≥ $NODE_MIN" node_check "install Node LTS: https://nodejs.org  (or: brew install node · nvm install --lts)"

package/src/orchestrator/templates/appium-environment/scripts/macos/install-android.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# install-android.sh — macOS: JDK ≥ 17, Android SDK root, platform-tools + emulator, shell profile block.
+# Headless via Homebrew (decision D2): `openjdk@21` + the `android-commandlinetools` cask + sdkmanager.
+# Android Studio is optional (only for an on-screen emulator) and is never installed here.
+# Sourced by setup.sh (shares the runner + counters); runnable standalone for debugging.
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] || . "$(cd "$(dirname "${BASH_SOURCE[0]}")/../common" && pwd)/lib.sh"
+
+JDK_MIN=17
+BREW_SDK_ROOT=$( { have brew && printf '%s/share/android-commandlinetools' "$(brew --prefix)"; } 2>/dev/null || true)
+
+# ── JDK ────────────────────────────────────────────────────────────────────────────────────────
+# Any working JDK ≥ 17 is accepted (Temurin, Corretto, Oracle, asdf…) — we never replace a good one.
+# resolve_* run in THIS shell (not a subshell) so their exports survive; *_check run captured.
+resolve_java_home() {
+  local major home
+  if [ -n "${JAVA_HOME:-}" ] && [ -x "$JAVA_HOME/bin/java" ]; then
+    major=$(java_major_of "$JAVA_HOME/bin/java"); [ -n "$major" ] && [ "$major" -ge "$JDK_MIN" ] && return 0
+  fi
+  if have java; then
+    major=$(java_major_of java)
+    if [ -n "$major" ] && [ "$major" -ge "$JDK_MIN" ]; then
+      home=$(java -XshowSettings:properties -version 2>&1 | awk -F' = ' '/java\.home/{print $2}')
+      [ -d "$home" ] && { export JAVA_HOME=$home; return 0; }
+    fi
+  fi
+  # Homebrew openjdk@21 present but not on PATH (brew keeps it keg-only).
+  if have brew && [ -x "$(brew --prefix openjdk@21 2>/dev/null)/bin/java" ]; then export JAVA_HOME; JAVA_HOME=$(brew --prefix openjdk@21); return 0; fi
+  return 1
+}
+jdk_check() {
+  local major
+  [ -n "${JAVA_HOME:-}" ] && [ -x "$JAVA_HOME/bin/java" ] || return 1
+  major=$(java_major_of "$JAVA_HOME/bin/java"); [ -n "$major" ] && [ "$major" -ge "$JDK_MIN" ] || return 1
+  printf 'java %s · JAVA_HOME=%s' "$major" "$JAVA_HOME"
+}
+jdk_install() { brew install openjdk@21 && { export JAVA_HOME; JAVA_HOME=$(brew --prefix openjdk@21); }; }
+jdk_verify()  { jdk_check || { printf 'no JDK ≥ %s — brew install openjdk@21 && export JAVA_HOME=$(brew --prefix openjdk@21)' "$JDK_MIN"; return 1; }; }
+resolve_java_home || true
+run_step "JDK ≥ $JDK_MIN" jdk_check jdk_install jdk_verify
+
+# ── Android SDK root ───────────────────────────────────────────────────────────────────────────
+# find_sdkmanager <sdk root> → path of sdkmanager (cmdline-tools/latest, any cmdline-tools/*, legacy tools/bin)
+find_sdkmanager() {
+  local root=$1 c
+  [ -n "$root" ] || return 1
+  for c in "$root/cmdline-tools/latest/bin/sdkmanager" "$root"/cmdline-tools/*/bin/sdkmanager "$root/tools/bin/sdkmanager"; do
+    [ -x "$c" ] && { printf '%s' "$c"; return 0; }
+  done
+  return 1
+}
+sdk_root_usable() { [ -n "$1" ] && [ -d "$1" ] && { [ -x "$1/platform-tools/adb" ] || find_sdkmanager "$1" >/dev/null; }; }
+# Precedence: what the user already exports → Android Studio's default → the Homebrew cask root.
+resolve_android_home() {
+  local c
+  for c in "${ANDROID_HOME:-}" "${ANDROID_SDK_ROOT:-}" "$HOME/Library/Android/sdk" "$BREW_SDK_ROOT"; do
+    if sdk_root_usable "$c"; then export ANDROID_HOME=$c ANDROID_SDK_ROOT=$c; return 0; fi
+  done
+  return 1
+}
+sdk_root_check()   { sdk_root_usable "${ANDROID_HOME:-}" || return 1; printf 'ANDROID_HOME=%s' "$ANDROID_HOME"; }
+sdk_root_install() { brew install --cask android-commandlinetools && export ANDROID_HOME=$BREW_SDK_ROOT ANDROID_SDK_ROOT=$BREW_SDK_ROOT; }
+sdk_root_verify()  {
+  find_sdkmanager "${ANDROID_HOME:-}" >/dev/null || { printf 'sdkmanager not found under %s — brew install --cask android-commandlinetools' "${ANDROID_HOME:-<unset>}"; return 1; }
+  printf 'ANDROID_HOME=%s' "$ANDROID_HOME"
+}
+resolve_android_home || true
+run_step "Android SDK root (cmdline-tools)" sdk_root_check sdk_root_install sdk_root_verify
+
+# ── platform-tools (adb) + emulator ────────────────────────────────────────────────────────────
+sdk_pkgs_check() {
+  local v
+  [ -x "${ANDROID_HOME:-}/platform-tools/adb" ] && [ -x "$ANDROID_HOME/emulator/emulator" ] || return 1
+  v=$("$ANDROID_HOME/platform-tools/adb" version 2>/dev/null) || v='adb'
+  printf 'platform-tools + emulator · %s' "$(first_line "$v")"
+}
+sdk_pkgs_install() {
+  local sm
+  sm=$(find_sdkmanager "${ANDROID_HOME:-}") || { printf 'no sdkmanager — the "Android SDK root" step must succeed first\n' >&2; return 1; }
+  # sdkmanager needs a JDK; --sdk_root is mandatory for the cask layout. Licenses are accepted
+  # non-interactively (they are Google's SDK terms — the same prompt Android Studio shows).
+  yes 2>/dev/null | JAVA_HOME=${JAVA_HOME:-} "$sm" --sdk_root="$ANDROID_HOME" --licenses >/dev/null 2>&1 || true
+  JAVA_HOME=${JAVA_HOME:-} "$sm" --sdk_root="$ANDROID_HOME" "platform-tools" "emulator"
+}
+sdk_pkgs_verify() { sdk_pkgs_check || { printf 'adb / emulator still missing — sdkmanager --sdk_root="%s" platform-tools emulator' "${ANDROID_HOME:-}"; return 1; }; }
+run_step "Android platform-tools (adb) + emulator" sdk_pkgs_check sdk_pkgs_install sdk_pkgs_verify
+
+# Make the tools reachable for the rest of THIS run (the profile block covers new terminals).
+if [ -n "${ANDROID_HOME:-}" ]; then
+  export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"
+fi
+
+# ── shell profile block (decision D3) ─────────────────────────────────────────────────────────
+PROFILE_TITLE="Shell profile (ANDROID_HOME, JAVA_HOME, PATH)"
+if [ -z "${ANDROID_HOME:-}" ] || [ -z "${JAVA_HOME:-}" ]; then
+  log_warn "$PROFILE_TITLE" "skipped — fix the JDK / SDK steps above first, then re-run"
+elif [ "$SUNGEN_ENV_INITIAL_ANDROID_HOME" = "$ANDROID_HOME" ] && [ "$SUNGEN_ENV_INITIAL_JAVA_HOME" = "$JAVA_HOME" ] \
+  && [ -n "$SUNGEN_ENV_INITIAL_ADB" ] && grep -qs 'ANDROID_HOME' "$(profile_file)"; then
+  # The user's own profile already exports the right values (and adb was on PATH before we touched it) —
+  # nothing to add. A value exported only in this terminal session does not count: the profile must name it.
+  log_skip "$PROFILE_TITLE" "already exported by your shell profile (ANDROID_HOME, JAVA_HOME, adb on PATH) — no block written"
+else
+  profile_step "$PROFILE_TITLE" "$(printf 'export ANDROID_HOME="%s"\nexport ANDROID_SDK_ROOT="$ANDROID_HOME"\nexport JAVA_HOME="%s"\nexport PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"' "$ANDROID_HOME" "$JAVA_HOME")"
+fi
+
+# ── Android Studio — optional, GUI, never installed here ───────────────────────────────────────
+if [ -d "/Applications/Android Studio.app" ]; then
+  log_skip "Android Studio (optional)" "/Applications/Android Studio.app"
+else
+  log_skip "Android Studio (optional)" "not installed — only needed for the AVD manager / an on-screen emulator: https://developer.android.com/studio"
+fi

package/src/orchestrator/templates/appium-environment/scripts/macos/install-ios.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# install-ios.sh — macOS: Xcode Command Line Tools, Xcode.app (checked + guided), license, applesimutils.
+# Xcode.app comes from the App Store and is never installed here (decision D2); xcuitest needs it
+# because WebDriverAgent is built by Xcode at run time.
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] || . "$(cd "$(dirname "${BASH_SOURCE[0]}")/../common" && pwd)/lib.sh"
+
+# ── Command Line Tools ─────────────────────────────────────────────────────────────────────────
+clt_check()   { xcode-select -p 2>/dev/null; }
+# `xcode-select --install` opens Apple's dialog and returns immediately — the install finishes
+# outside this script, so report "needs a manual step" (exit 2) rather than success or failure.
+clt_install() { xcode-select --install >/dev/null 2>&1; return 2; }
+clt_verify()  { clt_check || { printf 'finish the "Install Command Line Developer Tools" dialog, then re-run setup.sh'; return 1; }; }
+run_step "Xcode Command Line Tools" clt_check clt_install clt_verify
+
+# ── Xcode.app (guided) ─────────────────────────────────────────────────────────────────────────
+# Only a full Xcode answers `xcodebuild -version`; a CLT-only machine errors out here.
+xcode_check() { local v; v=$(xcodebuild -version 2>/dev/null) || return 1; first_line "$v"; }
+run_guided "Xcode.app" xcode_check "not installed — required for iOS (Xcode builds WebDriverAgent). Install Xcode from the App Store, open it once, then re-run setup.sh"
+
+# ── license — only meaningful once Xcode.app is there ──────────────────────────────────────────
+if xcode_check >/dev/null 2>&1; then
+  license_check()   { xcodebuild -license check >/dev/null 2>&1 && printf 'accepted'; }
+  license_install() { sudo xcodebuild -license accept; }
+  license_verify()  { license_check || { printf 'run: sudo xcodebuild -license accept'; return 1; }; }
+  run_step "Xcode license" license_check license_install license_verify
+fi
+
+# ── applesimutils — Simulator permission steps (`grant permission …`) ──────────────────────────
+asu_check()   { have applesimutils && printf 'applesimutils at %s' "$(command -v applesimutils)"; }
+asu_install() { brew tap wix/brew && brew install applesimutils; }
+asu_verify()  { asu_check || { printf 'brew tap wix/brew && brew install applesimutils'; return 1; }; }
+run_step "applesimutils (Simulator permission steps)" asu_check asu_install asu_verify

package/src/orchestrator/templates/appium-environment/scripts/macos/verify-android.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# verify-android.sh — macOS: is the Android side usable right now? (adb, env vars, connected devices)
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] || . "$(cd "$(dirname "${BASH_SOURCE[0]}")/../common" && pwd)/lib.sh"
+
+# Prefer the adb under ANDROID_HOME (this run may have just installed it) over a stale one on PATH.
+android_adb() {
+  if [ -x "${ANDROID_HOME:-}/platform-tools/adb" ]; then printf '%s/platform-tools/adb' "$ANDROID_HOME"
+  else command -v adb 2>/dev/null; fi
+}
+
+adb_check() {
+  local adb v
+  adb=$(android_adb) && [ -x "$adb" ] || return 1
+  v=$("$adb" version 2>/dev/null) || return 1
+  printf '%s' "$(first_line "$v")"
+}
+run_check "adb" adb_check "adb not found — re-run without --skip-android, or open a NEW terminal if the profile block was just written"
+
+env_check() {
+  [ -n "${ANDROID_HOME:-}" ] && [ -n "${JAVA_HOME:-}" ] || return 1
+  printf 'ANDROID_HOME=%s · JAVA_HOME=%s' "$ANDROID_HOME" "$JAVA_HOME"
+}
+run_check "ANDROID_HOME / JAVA_HOME" env_check "not set in this shell — open a NEW terminal (profile block) or export them"
+
+devices_check() {
+  local adb n
+  adb=$(android_adb) && [ -x "$adb" ] || return 1
+  n=$("$adb" devices 2>/dev/null | awk 'NR>1 && $2=="device"{n++} END{print n+0}')
+  if [ "$n" -gt 0 ]; then printf '%s device(s) connected' "$n"
+  else printf 'no device connected — plug in a phone (USB debugging on) or start an emulator before /sungen:run-test'; fi
+}
+run_check "Android devices" devices_check "adb is not usable yet" warn

package/src/orchestrator/templates/appium-environment/scripts/macos/verify-ios.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# verify-ios.sh — macOS: is the iOS side usable right now? (Xcode selected, Simulator runtimes visible)
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] || . "$(cd "$(dirname "${BASH_SOURCE[0]}")/../common" && pwd)/lib.sh"
+
+xcode_version_check() { local v; v=$(xcodebuild -version 2>/dev/null) || return 1; printf '%s · %s' "$(first_line "$v")" "$(xcode-select -p 2>/dev/null)"; }
+run_check "Xcode" xcode_version_check "Xcode.app not installed or not selected — App Store, then: sudo xcode-select -s /Applications/Xcode.app" warn
+
+simulators_check() {
+  local json n
+  json=$(xcrun simctl list devices available -j 2>/dev/null) || return 1
+  n=$(printf '%s' "$json" | grep -c '"udid"' || true)
+  if [ "${n:-0}" -gt 0 ]; then printf '%s simulator(s) available (xcrun simctl list devices available)' "$n"
+  else printf 'no Simulator runtime — Xcode → Settings → Components, add an iOS Simulator runtime'; return 1; fi
+}
+run_check "iOS Simulators" simulators_check "xcrun simctl is not usable — needs Xcode.app (real-iPhone runs need it too: WebDriverAgent signing)" warn

package/src/orchestrator/templates/appium-environment/scripts/windows/install-android.ps1

@@ -0,0 +1,153 @@
+# install-android.ps1 - Windows: JDK >= 17, Android SDK root, platform-tools + emulator, User environment.
+# Headless via winget (decision D2): Microsoft OpenJDK 21 + Google's command-line tools zip + sdkmanager.
+# Android Studio is optional (only for an on-screen emulator) and is never installed here.
+# Dot-sourced by setup.ps1 (shares the runner + counters); runnable standalone for debugging.
+if (-not $script:SungenEnvLibLoaded) { . (Join-Path $PSScriptRoot '..\common\lib.ps1') }
+
+$JdkMin = 17
+# Google rotates the command-line tools zip name; bump this ONE value when the download 404s.
+# Current builds: https://developer.android.com/studio#command-line-tools-only
+$CmdlineToolsBuild = '13114758'
+$DefaultSdkRoot = Join-Path $env:LOCALAPPDATA 'Android\Sdk'
+
+# --- JDK ------------------------------------------------------------------------------------------
+# Any working JDK >= 17 is accepted (Microsoft, Temurin, Oracle, Corretto...) - we never replace a good one.
+function Get-JavaMajor([string]$JavaExe) {
+  try { $out = (& $JavaExe -version 2>&1) | Out-String; if ($out -match '"(\d+)(\.\d+)*') { return [int]$Matches[1] } } catch {}
+  return 0
+}
+function Get-JavaHomeFromExe([string]$JavaExe) {
+  $out = (& $JavaExe -XshowSettings:properties -version 2>&1) | Out-String
+  if ($out -match 'java\.home = (.+)') { return $Matches[1].Trim() }
+  return $null
+}
+function Test-JdkHome([string]$JdkHome) {
+  if (-not $JdkHome) { return $false }
+  $exe = Join-Path $JdkHome 'bin\java.exe'
+  return ((Test-Path $exe) -and ((Get-JavaMajor $exe) -ge $JdkMin))
+}
+# Resolve-JavaHome - sets $env:JAVA_HOME when a usable JDK is found (env -> PATH -> vendor default folders).
+function Resolve-JavaHome {
+  if (Test-JdkHome $env:JAVA_HOME) { return $true }
+  $java = Get-Command java -ErrorAction SilentlyContinue
+  if ($java -and ((Get-JavaMajor $java.Source) -ge $JdkMin)) {
+    $home = Get-JavaHomeFromExe $java.Source
+    if ($home -and (Test-Path $home)) { $env:JAVA_HOME = $home; return $true }
+  }
+  foreach ($root in @((Join-Path $env:ProgramFiles 'Microsoft'), (Join-Path $env:ProgramFiles 'Eclipse Adoptium'), (Join-Path $env:ProgramFiles 'Java'))) {
+    if (-not (Test-Path $root)) { continue }
+    $cand = Get-ChildItem $root -Directory -Filter 'jdk-*' -ErrorAction SilentlyContinue | Sort-Object Name -Descending |
+      Where-Object { Test-JdkHome $_.FullName } | Select-Object -First 1
+    if ($cand) { $env:JAVA_HOME = $cand.FullName; return $true }
+  }
+  return $false
+}
+function Get-JdkDetail { if (Resolve-JavaHome) { "java $(Get-JavaMajor (Join-Path $env:JAVA_HOME 'bin\java.exe')), JAVA_HOME=$env:JAVA_HOME" } }
+
+Invoke-Step -Title "JDK >= $JdkMin" -Check { Get-JdkDetail } -Install {
+  Invoke-Native winget @('install', '--id', 'Microsoft.OpenJDK.21', '-e', '--silent', '--accept-source-agreements', '--accept-package-agreements')
+  Update-SessionPath
+} -Verify { Get-JdkDetail } -Hint 'winget install --id Microsoft.OpenJDK.21 -e   (then open a NEW terminal and re-run)'
+
+# --- Android SDK root -----------------------------------------------------------------------------
+function Find-SdkManager([string]$Root) {
+  if (-not $Root) { return $null }
+  foreach ($c in @((Join-Path $Root 'cmdline-tools\latest\bin\sdkmanager.bat'), (Join-Path $Root 'tools\bin\sdkmanager.bat'))) { if (Test-Path $c) { return $c } }
+  $any = Get-ChildItem (Join-Path $Root 'cmdline-tools') -Directory -ErrorAction SilentlyContinue |
+    ForEach-Object { Join-Path $_.FullName 'bin\sdkmanager.bat' } | Where-Object { Test-Path $_ } | Select-Object -First 1
+  return $any
+}
+function Test-SdkRoot([string]$Root) {
+  if (-not $Root -or -not (Test-Path $Root)) { return $false }
+  return ((Test-Path (Join-Path $Root 'platform-tools\adb.exe')) -or [bool](Find-SdkManager $Root))
+}
+# Precedence: what the user already set -> Android Studio's default (%LOCALAPPDATA%\Android\Sdk).
+function Resolve-AndroidHome {
+  foreach ($c in @($env:ANDROID_HOME, $env:ANDROID_SDK_ROOT, $DefaultSdkRoot)) {
+    if (Test-SdkRoot $c) { $env:ANDROID_HOME = $c; $env:ANDROID_SDK_ROOT = $c; return $true }
+  }
+  return $false
+}
+function Install-CmdlineTools {
+  # Cmdlet errors (download 404 when Google rotates the zip, unpack failures) must become terminating so
+  # Invoke-Step's try/catch reports the real cause instead of only the generic hint.
+  $ErrorActionPreference = 'Stop'
+  $root = $DefaultSdkRoot
+  $url = "https://dl.google.com/android/repository/commandlinetools-win-${CmdlineToolsBuild}_latest.zip"
+  $zip = Join-Path $env:TEMP "commandlinetools-win-$CmdlineToolsBuild.zip"
+  $staging = Join-Path $env:TEMP "sungen-cmdline-tools-$CmdlineToolsBuild"
+  New-Item -ItemType Directory -Force -Path (Join-Path $root 'cmdline-tools') | Out-Null
+  Write-Host "            downloading $url" -ForegroundColor DarkGray
+  [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+  Invoke-WebRequest -Uri $url -OutFile $zip -UseBasicParsing
+  if (Test-Path $staging) { Remove-Item $staging -Recurse -Force }
+  Expand-Archive -Path $zip -DestinationPath $staging -Force
+  # The zip unpacks as cmdline-tools\ but sdkmanager only works from cmdline-tools\latest\.
+  $latest = Join-Path $root 'cmdline-tools\latest'
+  if (Test-Path $latest) { Remove-Item $latest -Recurse -Force }
+  Move-Item (Join-Path $staging 'cmdline-tools') $latest
+  Remove-Item $zip -Force -ErrorAction SilentlyContinue
+  Remove-Item $staging -Recurse -Force -ErrorAction SilentlyContinue
+  $env:ANDROID_HOME = $root; $env:ANDROID_SDK_ROOT = $root
+}
+[void](Resolve-AndroidHome)
+Invoke-Step -Title 'Android SDK root (cmdline-tools)' -Check {
+  if (Test-SdkRoot $env:ANDROID_HOME) { "ANDROID_HOME=$env:ANDROID_HOME" }
+} -Install { Install-CmdlineTools } -Verify {
+  if (Find-SdkManager $env:ANDROID_HOME) { "ANDROID_HOME=$env:ANDROID_HOME" }
+} -Hint "download the command-line tools zip from https://developer.android.com/studio#command-line-tools-only and unpack it to $DefaultSdkRoot\cmdline-tools\latest"
+
+# --- platform-tools (adb) + emulator --------------------------------------------------------------
+function Get-SdkPackagesDetail {
+  if (-not $env:ANDROID_HOME) { return $null }
+  $adb = Join-Path $env:ANDROID_HOME 'platform-tools\adb.exe'; $emu = Join-Path $env:ANDROID_HOME 'emulator\emulator.exe'
+  if ((Test-Path $adb) -and (Test-Path $emu)) { $v = (& $adb version) 2>$null | Select-Object -First 1; "platform-tools + emulator, $v" }
+}
+Invoke-Step -Title 'Android platform-tools (adb) + emulator' -Check { Get-SdkPackagesDetail } -Install {
+  $sm = Find-SdkManager $env:ANDROID_HOME
+  if (-not $sm) { throw 'no sdkmanager - the "Android SDK root" step must succeed first' }
+  # sdkmanager needs JAVA_HOME (set above). Licenses are Google's SDK terms - the same prompt Android
+  # Studio shows - accepted non-interactively here.
+  $yes = ('y' + "`n") * 40
+  $yes | & $sm "--sdk_root=$env:ANDROID_HOME" --licenses 2>&1 | Out-Null
+  Invoke-Native $sm @("--sdk_root=$env:ANDROID_HOME", 'platform-tools', 'emulator')
+} -Verify { Get-SdkPackagesDetail } -Hint "sdkmanager --sdk_root=$env:ANDROID_HOME platform-tools emulator"
+
+# Make the tools reachable for the rest of THIS run (the User environment covers new consoles).
+if ($env:ANDROID_HOME) {
+  foreach ($d in @('platform-tools', 'emulator', 'cmdline-tools\latest\bin')) {
+    $p = Join-Path $env:ANDROID_HOME $d
+    if (-not (($env:Path -split ';') -contains $p)) { $env:Path = "$env:Path;$p" }
+  }
+}
+
+# --- User environment (decision D3) ---------------------------------------------------------------
+$EnvTitle = 'User environment (ANDROID_HOME, ANDROID_SDK_ROOT, JAVA_HOME, Path)'
+$PathDirs = @('platform-tools', 'emulator', 'cmdline-tools\latest\bin')
+if (-not $env:ANDROID_HOME -or -not $env:JAVA_HOME) {
+  Write-Warn $EnvTitle 'skipped - fix the JDK / SDK steps above first, then re-run'
+} elseif ($script:SungenEnvNoProfile) {
+  Write-Skip $EnvTitle '-NoProfile'
+} elseif ($script:SungenEnvCheckOnly) {
+  $missing = @()
+  foreach ($pair in @(@('ANDROID_HOME', $env:ANDROID_HOME), @('ANDROID_SDK_ROOT', $env:ANDROID_HOME), @('JAVA_HOME', $env:JAVA_HOME))) {
+    if ([Environment]::GetEnvironmentVariable($pair[0], 'User') -ne $pair[1]) { $missing += $pair[0] }
+  }
+  $userPath = @(([Environment]::GetEnvironmentVariable('Path', 'User')) -split ';')
+  foreach ($d in $PathDirs) { if (-not ($userPath -contains (Join-Path $env:ANDROID_HOME $d))) { $missing += "Path+=$d" } }
+  if ($missing.Count -gt 0) { Write-Fail $EnvTitle "not set for your user: $($missing -join ', ') - run without -Check to write them" }
+  else { Write-Skip $EnvTitle 'already set for your user' }
+} else {
+  $changed = @()
+  if (Set-UserEnv 'ANDROID_HOME' $env:ANDROID_HOME)     { $changed += 'ANDROID_HOME' }
+  if (Set-UserEnv 'ANDROID_SDK_ROOT' $env:ANDROID_HOME) { $changed += 'ANDROID_SDK_ROOT' }
+  if (Set-UserEnv 'JAVA_HOME' $env:JAVA_HOME)           { $changed += 'JAVA_HOME' }
+  foreach ($d in $PathDirs) { if (Add-UserPath (Join-Path $env:ANDROID_HOME $d)) { $changed += "Path+=$d" } }
+  if ($changed.Count -gt 0) { Write-Ok $EnvTitle "set for your user: $($changed -join ', ') - open a NEW terminal to apply" }
+  else { Write-Skip $EnvTitle 'already set for your user' }
+}
+
+# --- Android Studio - optional, GUI, never installed here ------------------------------------------
+$studio = @((Join-Path $env:LOCALAPPDATA 'Programs\Android Studio'), (Join-Path $env:ProgramFiles 'Android\Android Studio')) | Where-Object { Test-Path $_ } | Select-Object -First 1
+if ($studio) { Write-Skip 'Android Studio (optional)' $studio }
+else { Write-Skip 'Android Studio (optional)' 'not installed - only needed for the AVD manager / an on-screen emulator: https://developer.android.com/studio' }

package/src/orchestrator/templates/appium-environment/scripts/windows/verify-android.ps1

@@ -0,0 +1,26 @@
+# verify-android.ps1 - Windows: is the Android side usable right now? (adb, env vars, connected devices)
+if (-not $script:SungenEnvLibLoaded) { . (Join-Path $PSScriptRoot '..\common\lib.ps1') }
+
+# Prefer the adb under ANDROID_HOME (this run may have just installed it) over a stale one on PATH.
+function Get-AndroidAdb {
+  if ($env:ANDROID_HOME) { $p = Join-Path $env:ANDROID_HOME 'platform-tools\adb.exe'; if (Test-Path $p) { return $p } }
+  $cmd = Get-Command adb -ErrorAction SilentlyContinue
+  if ($cmd) { return $cmd.Source }
+  return $null
+}
+
+Invoke-Check -Title 'adb' -Check {
+  $adb = Get-AndroidAdb; if (-not $adb) { return $null }
+  (& $adb version) 2>$null | Select-Object -First 1
+} -Hint 'adb not found - re-run without -SkipAndroid, or open a NEW terminal if the environment was just written'
+
+Invoke-Check -Title 'ANDROID_HOME / JAVA_HOME' -Check {
+  if ($env:ANDROID_HOME -and $env:JAVA_HOME) { "ANDROID_HOME=$env:ANDROID_HOME, JAVA_HOME=$env:JAVA_HOME" }
+} -Hint 'not set in this console - open a NEW terminal (User environment) or set them'
+
+Invoke-Check -Title 'Android devices' -Check {
+  $adb = Get-AndroidAdb; if (-not $adb) { return $null }
+  $lines = @((& $adb devices) 2>$null | Select-Object -Skip 1 | Where-Object { $_ -match '\sdevice$' })
+  if ($lines.Count -gt 0) { "$($lines.Count) device(s) connected" }
+  else { 'no device connected - plug in a phone (USB debugging on) or start an emulator before /sungen:run-test' }
+} -Hint 'adb is not usable yet' -Warn

package/src/orchestrator/templates/appium-environment/setup.ps1

@@ -0,0 +1,58 @@
+<#
+.SYNOPSIS
+  setup.ps1 - Windows entry point of the sungen Appium environment bundle.
+.DESCRIPTION
+  .\appium-environment\setup.ps1 [-Check] [-SkipAndroid] [-NoProfile]
+
+  Emitted by `sungen init --mobile` / `sungen capability add mobile`, which also run it once.
+  Re-run it any time: every step is check -> install -> verify and a satisfied step is skipped.
+    -Check        report what is missing, install nothing (side-effect free)
+    -SkipAndroid  skip JDK / Android SDK / uiautomator2
+    -NoProfile    do not write ANDROID_HOME / JAVA_HOME / Path to your User environment
+  iOS (xcuitest) needs Xcode and therefore a Mac - there is no iOS step on Windows.
+  Exit: 0 ready (or only warnings) - 1 something failed - 2 unsupported host
+  Run as:  powershell -NoProfile -ExecutionPolicy Bypass -File .\appium-environment\setup.ps1
+#>
+[CmdletBinding()]
+param([switch]$Check, [switch]$SkipAndroid, [switch]$NoProfile)
+
+$ErrorActionPreference = 'Continue'
+if ($PSVersionTable.PSVersion.Major -lt 5) { Write-Host 'Windows PowerShell 5.1 or newer is required.' -ForegroundColor Red; exit 2 }
+if ($env:OS -ne 'Windows_NT') { Write-Host 'setup.ps1 is for Windows - on macOS run ./appium-environment/setup.sh' -ForegroundColor Red; exit 2 }
+
+$script:SungenEnvCheckOnly   = [bool]$Check
+$script:SungenEnvSkipAndroid = [bool]$SkipAndroid
+$script:SungenEnvNoProfile   = [bool]$NoProfile
+$script:ProjectDir = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+. (Join-Path $PSScriptRoot 'scripts\common\lib.ps1')
+
+Set-Location $script:ProjectDir
+if ($script:SungenEnvCheckOnly) { Write-Section 'sungen - Appium environment - check only (Windows)' }
+else { Write-Section 'sungen - Appium environment setup (Windows)' }
+Write-Host "project: $($script:ProjectDir)" -ForegroundColor DarkGray
+
+# --- 1/4 prerequisites -----------------------------------------------------------------------------
+Write-Section '1/4  Prerequisites'
+. (Join-Path $PSScriptRoot 'scripts\common\verify-node.ps1')
+Invoke-Check -Title 'winget (Windows Package Manager)' -Check {
+  if (Get-Command winget -ErrorAction SilentlyContinue) { $v = (& winget --version) 2>$null | Select-Object -First 1; "winget $v" }
+} -Hint 'winget missing - install "App Installer" from the Microsoft Store (Windows 10 1809+ / 11), then re-run'
+
+# --- 2/4 Android -----------------------------------------------------------------------------------
+if (-not $script:SungenEnvSkipAndroid) {
+  Write-Section '2/4  Android (JDK, SDK, adb, emulator)'
+  . (Join-Path $PSScriptRoot 'scripts\windows\install-android.ps1')
+} else {
+  Write-Section '2/4  Android'; Write-Skip 'Android toolchain' '-SkipAndroid'
+}
+
+# --- 3/4 Appium ------------------------------------------------------------------------------------
+Write-Section '3/4  Appium (project-local) + platform driver'
+. (Join-Path $PSScriptRoot 'scripts\common\install-appium.ps1')
+
+# --- 4/4 health ------------------------------------------------------------------------------------
+Write-Section '4/4  Health check'
+if (-not $script:SungenEnvSkipAndroid) { . (Join-Path $PSScriptRoot 'scripts\windows\verify-android.ps1') }
+. (Join-Path $PSScriptRoot 'scripts\common\verify-appium.ps1')
+
+exit (Write-Summary)