@sun-asterisk/sungen 3.2.31 → 3.2.33

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)

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# setup.sh — macOS entry point of the sungen Appium environment bundle.
+#
+#   ./appium-environment/setup.sh [--check] [--skip-android] [--skip-ios] [--no-profile]
+#
+# 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)
+#   --skip-android   skip JDK / Android SDK / uiautomator2
+#   --skip-ios       skip Xcode CLT / applesimutils / xcuitest
+#   --no-profile     do not write the ANDROID_HOME / JAVA_HOME / PATH block to your shell profile
+# Exit: 0 ready (or only warnings) · 1 something failed · 2 unsupported OS / bad flag
+set -u
+
+BUNDLE_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+PROJECT_DIR=$(cd "$BUNDLE_DIR/.." && pwd)
+export PROJECT_DIR
+. "$BUNDLE_DIR/scripts/common/lib.sh"
+
+usage() { sed -n '4,13p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; }
+
+for arg in "$@"; do
+  case "$arg" in
+    --check)        SUNGEN_ENV_CHECK_ONLY=1 ;;
+    --skip-android) SUNGEN_ENV_SKIP_ANDROID=1 ;;
+    --skip-ios)     SUNGEN_ENV_SKIP_IOS=1 ;;
+    --no-profile)   SUNGEN_ENV_NO_PROFILE=1 ;;
+    -h|--help)      usage; exit 0 ;;
+    *) printf 'unknown flag: %s\n\n' "$arg" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+case "$(uname -s)" in
+  Darwin) ;;
+  Linux)
+    printf 'ℹ Linux detected — this bundle provisions macOS and Windows.\n'
+    printf '  Android on Linux: see README.md → "Manual fallback" (JDK + Android SDK via your package manager,\n'
+    printf '  then `sungen capability add mobile` for the project-local Appium + uiautomator2).\n'
+    exit 0 ;;
+  *) printf '✗ unsupported OS: %s (macOS: setup.sh · Windows: setup.ps1)\n' "$(uname -s)" >&2; exit 2 ;;
+esac
+
+cd "$PROJECT_DIR"
+if [ "$SUNGEN_ENV_CHECK_ONLY" = 1 ]; then section "sungen · Appium environment — check only (macOS)"
+else section "sungen · Appium environment setup (macOS)"; fi
+printf '%sproject: %s%s\n' "$C_DIM" "$PROJECT_DIR" "$C_RESET"
+
+# ── 1/5 prerequisites ──────────────────────────────────────────────────────────────────────────
+section "1/5  Prerequisites"
+. "$BUNDLE_DIR/scripts/common/verify-node.sh"
+
+brew_check()   { have brew && printf 'brew at %s' "$(command -v brew)"; }
+brew_install() {
+  NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" || return 1
+  # The installer does not touch the running shell — pick brew up for the rest of this run.
+  if [ -x /opt/homebrew/bin/brew ]; then eval "$(/opt/homebrew/bin/brew shellenv)"
+  elif [ -x /usr/local/bin/brew ]; then eval "$(/usr/local/bin/brew shellenv)"; fi
+}
+brew_verify()  { brew_check || { printf 'Homebrew not found after install — https://brew.sh, then re-run'; return 1; }; }
+run_step "Homebrew" brew_check brew_install brew_verify
+
+# ── 2/5 Android ────────────────────────────────────────────────────────────────────────────────
+if [ "$SUNGEN_ENV_SKIP_ANDROID" != 1 ]; then
+  section "2/5  Android (JDK, SDK, adb, emulator)"
+  . "$BUNDLE_DIR/scripts/macos/install-android.sh"
+else
+  section "2/5  Android"; log_skip "Android toolchain" "--skip-android"
+fi
+
+# ── 3/5 iOS ────────────────────────────────────────────────────────────────────────────────────
+if [ "$SUNGEN_ENV_SKIP_IOS" != 1 ]; then
+  section "3/5  iOS (Xcode, applesimutils)"
+  . "$BUNDLE_DIR/scripts/macos/install-ios.sh"
+else
+  section "3/5  iOS"; log_skip "iOS toolchain" "--skip-ios"
+fi
+
+# ── 4/5 Appium ─────────────────────────────────────────────────────────────────────────────────
+section "4/5  Appium (project-local) + platform drivers"
+. "$BUNDLE_DIR/scripts/common/install-appium.sh"
+
+# ── 5/5 health ─────────────────────────────────────────────────────────────────────────────────
+section "5/5  Health check"
+[ "$SUNGEN_ENV_SKIP_ANDROID" != 1 ] && . "$BUNDLE_DIR/scripts/macos/verify-android.sh"
+[ "$SUNGEN_ENV_SKIP_IOS" != 1 ]     && . "$BUNDLE_DIR/scripts/macos/verify-ios.sh"
+. "$BUNDLE_DIR/scripts/common/verify-appium.sh"
+
+print_summary

package/src/orchestrator/templates/specs-checked-state.ts

@@ -38,7 +38,7 @@ const POLL_INTERVAL_MS = 100;
 export interface DeclaredSignal { class?: string; attribute?: string }
 
 /** Where the control publishes its on/off state — decided in the page, from the real element. */
-export type StateSource = 'native' | 'aria-pressed' | 'aria-checked' | 'class' | 'attribute' | 'none';
+export type StateSource = 'native' | 'aria-pressed' | 'aria-checked' | 'aria-selected' | 'aria-current' | 'class' | 'attribute' | 'none';
 export interface ControlProbe {
   source: StateSource;
   /** Current state, already normalised. Meaningless when `source` is 'native' (Playwright reads it). */
@@ -110,6 +110,24 @@ export function probeControl(node: unknown, declared?: DeclaredSignal): ControlP
   }
   // Role claims checkable but nothing is published — let Playwright raise its own, precise error.
   if (ariaCheckableRole) return { source: 'native', on: false, buttonLike };
+  // `is selected` on a tab, an option, a chip or a nav item. These publish `aria-selected` or
+  // `aria-current`, which nothing above reads: the probe fell straight through to 'none' and the
+  // step failed saying the control has no on/off state to set, on a control that publishes one in
+  // the standard place. Read here rather than in the templates so a suite already generated in the
+  // field picks the fix up without regenerating — the same reasoning the URL predicate is a runtime
+  // helper for.
+  //
+  // `aria-current` is not a boolean: the spec allows 'page', 'step', 'location', 'date', 'time' and
+  // 'true', and only the literal 'false' (or the attribute's absence) means off. Read that way
+  // round, so `aria-current="page"` on the active nav item reads as ON rather than as a stray
+  // non-'true' string.
+  if (el.hasAttribute('aria-selected')) {
+    return { source: 'aria-selected', on: String(el.getAttribute('aria-selected') ?? '').trim().toLowerCase() === 'true', buttonLike };
+  }
+  if (el.hasAttribute('aria-current')) {
+    const raw = String(el.getAttribute('aria-current') ?? '').trim().toLowerCase();
+    return { source: 'aria-current', on: raw !== '' && raw !== 'false', buttonLike };
+  }
   return { source: 'none', on: false, buttonLike };
 }
 
@@ -132,11 +150,18 @@ const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms
  */
 const left = (deadline: number): number => Math.max(250, deadline - Date.now());
 
+/** The sources that name an ATTRIBUTE the live state can be re-read from. */
+type AttributeSource = 'aria-pressed' | 'aria-checked' | 'aria-selected' | 'aria-current';
+
 /** Read the live state. A REMOVED attribute means off: `aria-pressed={on || undefined}` is a common
  *  React/Vue idiom, so requiring a literal "false" would fail a control that is correctly off. */
-async function readOn(target: Locator, attr: 'aria-pressed' | 'aria-checked', deadline: number): Promise<boolean> {
-  const raw = await target.getAttribute(attr, { timeout: left(deadline) });
-  return String(raw ?? '').trim().toLowerCase() === 'true';
+async function readOn(target: Locator, attr: AttributeSource, deadline: number): Promise<boolean> {
+  const raw = String(await target.getAttribute(attr, { timeout: left(deadline) }) ?? '').trim().toLowerCase();
+  // `aria-current` is the one non-boolean of the four: the spec allows 'page', 'step', 'location',
+  // 'date', 'time' and 'true', so only the literal 'false' (or absence) means off. Read the other
+  // way round it would report the active nav item as OFF.
+  if (attr === 'aria-current') return raw !== '' && raw !== 'false';
+  return raw === 'true';
 }
 
 /**
@@ -238,12 +263,12 @@ export async function setCheckedState(
     // Not pressable and publishes nothing — there is no reading of this that makes the step meaningful.
     throw new Error(
       `Cannot ${want ? 'check' : 'uncheck'} [${label}] — it is not a checkbox/radio/switch, is not a `
-      + `button, and publishes no aria-pressed/aria-checked, so it has no on/off state to set. Point the `
+      + `button, and publishes no aria-pressed/aria-checked/aria-selected/aria-current, so it has no on/off state to set. Point the `
       + `selector at the control itself, or give it a real ARIA toggle role.`,
     );
   }
 
-  const attr = probe.source;
+  const attr: AttributeSource = probe.source as AttributeSource;
   // Already in the requested state → nothing to do. This is the idempotence `check` promises.
   if (probe.on === want) return;
   await target.click({ timeout });

package/src/orchestrator/templates/specs-locale-fixture.ts

@@ -42,18 +42,30 @@ interface LocaleInjection {
 
 let cached: LocaleInjection | null | undefined;
 
+/**
+ * Absent config → null, and locale injection is simply off (the documented no-op).
+ *
+ * A config that EXISTS but does not parse is a different thing and must not read the same way: the
+ * header above tells you to hand-edit this file, and a trailing comma would otherwise turn a
+ * `SUNGEN_ENV=ja` run into a base-locale run that asserts base-locale strings — green, and wrong.
+ * We warn rather than throw, because the injection is genuinely optional and failing every test on
+ * it would be a larger change than the fault warrants; the line names the file and the consequence.
+ */
 function loadLocaleConfig(): LocaleInjection | null {
   if (cached !== undefined) return cached;
+  const cfgPath = path.join(__dirname, 'locale-config.json');
+  if (!fs.existsSync(cfgPath)) {
+    cached = null;
+    return null;
+  }
   try {
-    const cfgPath = path.join(__dirname, 'locale-config.json');
-    if (!fs.existsSync(cfgPath)) {
-      cached = null;
-      return null;
-    }
-    const parsed = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')) as LocaleInjection;
-    cached = parsed;
-    return parsed;
-  } catch {
+    cached = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')) as LocaleInjection;
+    return cached;
+  } catch (e) {
+    console.error(
+      `⚠️  ${cfgPath}: unreadable (${e instanceof Error ? e.message.split('\n')[0] : String(e)}) — ` +
+      `locale state is NOT injected, so this SUNGEN_ENV run behaves as the base locale.`,
+    );
     cached = null;
     return null;
   }