@sun-asterisk/sungen 3.2.31 → 3.2.33

package/src/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -56,7 +56,7 @@ Scenario: VP-VAL-002 An email in an invalid format shows the format error
   2. **ENV-BOUND** (must exist in the test environment; harmless if leaked): seeded ids, registered emails, valid tokens → keep in yaml with a `# ENV-BOUND: <what to seed>` marker; per-environment values go in `<unit>.<env>.yaml`.
   3. **SECRET** (real login / harmful if leaked): NEVER write the real value — reference `${QA_<NAME>}` (uppercase, `QA_` prefix mandatory; only that shape resolves from `.env.qa` at runtime, any other `${...}` stays literal). Whenever you emit a new `${QA_*}` ref, ALSO append the name to `.env.qa.example`. Note: "password" is not automatically SECRET — a made-up password probing validation is INVENTED; only a real account's password is SECRET (and `@auth:role` via `sungen makeauth` usually removes the need entirely).
 
-- `@parallel` required when mixing `@auth:X` + `@no-auth` in the same feature
+- Mixing `@auth:X` + `@no-auth` in one feature is fine by default; just never tag that feature `@serial`
   → Playwright shares browser context per worker; auth state leaks across scenarios without isolation.
 
 - XSS ≠ SQL injection — generate as **2 separate scenarios**, never merge
@@ -568,7 +568,7 @@ and a real oracle, not a shrug: write the steps a human follows and the value th
 
 Add cleanup tags per the `sungen-gherkin-syntax` Cleanup table. Key rules:
 - **Always `@cleanup:overlay`** if ANY section opens a dialog; **always `@cleanup:forms`** if the screen has inline search, filter, or editable forms.
-- **`@parallel`** is required when mixing auth groups (`@auth:X` + `@no-auth`); recommended for validation-heavy features needing a clean form state per scenario.
+- **`@parallel`** names the default isolation, so mixing auth groups (`@auth:X` + `@no-auth`) needs no tag at all — only `@serial` breaks it, because one shared context cannot hold two sessions. Still worth stating explicitly on validation-heavy features that want a clean form state per scenario.
 - **`@afterEach`** hook only when `@cleanup:*` tags aren't enough (feature-specific reset logic).
 
 ---
@@ -838,9 +838,24 @@ is the common failure. Every navigation target the spec names needs a click-thro
 (`NAV-TARGET-ABSENT`), even when this flow does not consume the destination — a context param
 handed to another screen is that screen's input, and the handoff is where it goes wrong.
 
-**A deny case needs its allow case.** "permission denied → content hidden" passes just as happily
-when the content is hidden for everyone. Pair it with "permission granted → content shown", the
-way a boundary needs `min-1 / min / max / max+1` (`PERMISSION-PAIR-MISSING`).
+**A hidden case needs its shown case.** "permission denied → content hidden" passes just as
+happily when the content is hidden for everyone. Pair it with "permission granted → content
+shown", the way a boundary needs `min-1 / min / max / max+1` (`PERMISSION-PAIR-MISSING`).
+
+The same holds for ANY condition, not just permission: an element you assert `is hidden` in one
+state must be asserted PRESENT in some other state, or nothing distinguishes a working rule from a
+feature that is broken for everyone — and a mistyped selector matches nothing, so `is hidden`
+passes forever on its own (`VISIBILITY-PAIR-MISSING`). Conditional buttons, empty-vs-populated
+lists, the active tab, a radio state: "show A or B, never both" is a very common implementation
+defect, and only the pair catches it.
+
+**A requirement that states both directions is TWO requirements.** "`X` MUST be shown when no
+score is set; MUST NOT be shown once a score exists" is one line and two mutually-exclusive states,
+so one scenario cannot prove it — tagging `@spec:FR-013` on the positive case closes the ID, not
+the rule. Write one case per direction; `sungen audit` counts them as two coverage units and
+reports the unproved half as `SPEC-CLAUSE-UNCOVERED`. The gate only presses a requirement that
+NAMES its element and speaks about visibility or enabledness — but the habit is worth keeping for
+every opposing rule, gated or not.
 
 **State that ARRIVES with the data is a different case from state the test creates.** A
 discriminator field you can only observe at load (an item already favourited before the page

package/src/orchestrator/templates/ai-src/skills/sungen-tc-review/SKILL.md

@@ -105,7 +105,7 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 
 - [ ] Exactly **one** priority tag per scenario (`@high`/`@normal`/`@low`…)
 - [ ] `@manual`/`@auth:role`/`@no-auth`/`@cleanup:*`/`@parallel`/`@flow` used in the right context
-- [ ] `@parallel` is REQUIRED when a feature mixes auth groups (`@auth:user` + `@no-auth`)
+- [ ] A feature mixing auth groups (`@auth:user` + `@no-auth`) is NOT `@serial` — parallel is the default and one shared context cannot hold two sessions
 - [ ] `@flow`: `[Screen:Element]` namespace is consistent; YAML keys quoted with the colon (`"login:submit":`)
 
 ### A8. Mobile (`@platform:mobile/android/ios` units only)
@@ -321,7 +321,7 @@ Do NOT deduct points when a `.feature` lacks the following viewpoints (Playwrigh
 12. **Orphan key in test-data** (the advisory lint after `sungen generate` says `defined but never referenced`; a `@query`/`@api` param bound by name, a `@manual` comment ref or a `_*` metadata key is not one) → delete it or bind it into a scenario. **Unbound `{{x}}` in a step** (the same lint says `is not a test-data key and nothing binds it`) → add the key or fix the ref — left alone it runs as the literal text `${x}`.
 13. **Unnecessary CSS/locator selector** → switch to role+name/label/text; keys use spaces.
 14. **Scope crammed into `Background`** → split into `@steps`/`@extend`.
-15. **Mixed auth groups missing `@parallel`** → add `@parallel`.
+15. **Mixed auth groups on a `@serial` feature** → remove `@serial`, or split one feature per auth role.
 16. **Missing secondary behaviors** — spec defines tiebreaker, fallback rule, or secondary sort but no scenario tests it? Add 1 `@high` TC per rule.
 17. **Missing concurrency scenarios** — spec or test-viewpoint mentions multi-tab, multi-user, or simultaneous actions but no `@manual` scenario exists? Add 1 `@manual` TC per risk (`@normal` by default; `@high` if data integrity at risk).
 18. **Mobile: `see [X] page` oracle** → replace with a marker element on the destination screen + the origin's marker `is hidden` (SG-W022 — the original passes having proven nothing).
@@ -363,7 +363,7 @@ If `selectors/<name>.yaml` exists, count lines matching `@needs-live-verify` (pr
 - [ ] Assertions follow the 8 patterns, no redundant `is visible`
 - [ ] Every {{var}} exists in test-data.yaml and no orphan keys — both reported by the advisory data-driven lint at `sungen generate` (not `audit`); an unbound {{var}} compiles to a literal placeholder, never a compile error
 - [ ] Selector keys follow sungen-selector-keys; locator only as last resort
-- [ ] Tags valid; @parallel when mixing auth groups
+- [ ] Tags valid; no `@serial` on a feature that mixes auth groups
 - Syntax errors found: <n>
 
 ### Coverage Matrix (Layer B)

package/src/orchestrator/templates/appium-environment/README.md

@@ -0,0 +1,83 @@
+# appium-environment/ — one command to a working Appium machine
+
+Emitted by `sungen init --mobile` (or `sungen capability add mobile`), which also runs it once.
+It provisions everything **below** the Appium layer — the part QA used to do by hand — and ends with
+`appium driver doctor`. Every step is **check → install → verify**: a satisfied step is skipped, so the
+bundle is safe to re-run any time (a new machine, a teammate's clone, after an OS update).
+
+```bash
+sungen setup-mobile-env                       # any OS — emits this folder if missing, then runs it
+./appium-environment/setup.sh                 # macOS, directly
+powershell -NoProfile -ExecutionPolicy Bypass -File .\appium-environment\setup.ps1   # Windows, directly
+```
+
+| Flag (macOS) | Flag (Windows) | Effect |
+|---|---|---|
+| `--check` | `-Check` | report what is missing, install nothing (side-effect free) |
+| `--skip-android` | `-SkipAndroid` | skip JDK / Android SDK / uiautomator2 |
+| `--skip-ios` | — | skip Xcode CLT / applesimutils / xcuitest (iOS needs a Mac) |
+| `--no-profile` | `-NoProfile` | do not write env vars to your shell profile / User environment |
+
+Exit code: `0` ready (or only warnings) · `1` something failed · `2` unsupported OS / bad flag.
+`sungen init` treats a non-zero exit as a warning — the project scaffold is already complete.
+
+## What it installs (and what it only checks)
+
+| Step | macOS (`setup.sh`) | Windows (`setup.ps1`) |
+|---|---|---|
+| Node.js ≥ 18 | check only (sungen needs it already) | check only |
+| Package manager | Homebrew — installed if missing | winget — check only (App Installer, Microsoft Store) |
+| JDK ≥ 17 | `brew install openjdk@21` (an existing JDK ≥ 17 is kept) | `winget install Microsoft.OpenJDK.21` (existing JDK ≥ 17 kept) |
+| Android SDK root | existing `ANDROID_HOME` / Android Studio SDK / `brew install --cask android-commandlinetools` | existing / `%LOCALAPPDATA%\Android\Sdk` / Google's command-line tools zip |
+| `platform-tools` (adb) + `emulator` | `sdkmanager` | `sdkmanager` |
+| Env vars | marked block in `~/.zshrc` (or `~/.bash_profile`) | User environment (`ANDROID_HOME`, `ANDROID_SDK_ROOT`, `JAVA_HOME`, `Path`) |
+| Android Studio | **check + hint only** (optional — AVD manager / on-screen emulator) | same |
+| Xcode Command Line Tools | `xcode-select --install` (Apple's dialog — finish it, re-run) | — |
+| Xcode.app | **check + hint only** (App Store; required for iOS) | — |
+| Xcode license | `sudo xcodebuild -license accept` | — |
+| `applesimutils` | `brew tap wix/brew && brew install applesimutils` | — |
+| Appium | **project-local** (`node_modules/.bin/appium`, from `@sungen/driver-mobile`) — never global | same |
+| Appium drivers | `uiautomator2` + `xcuitest` into `~/.appium` | `uiautomator2` |
+| Health | `adb`, env vars, devices, Simulators, `appium driver doctor` | `adb`, env vars, devices, `appium driver doctor` |
+
+Nothing is installed globally with npm. GUI apps (Xcode.app, Android Studio) are never installed for you —
+the step tells you exactly where to get them and re-running the script picks up from there.
+
+## The env-var block
+
+macOS: the lines live between `# >>> sungen mobile env >>>` and `# <<< sungen mobile env <<<` in your
+shell profile; re-running rewrites only that block, and it is skipped entirely when your shell already
+exports matching values. To undo, delete the block. Windows: plain User-scope variables — undo in
+*System Properties → Environment Variables*.
+
+**Open a new terminal after the first run** so `PATH` / `JAVA_HOME` / `ANDROID_HOME` apply.
+
+## Known limitations
+
+- **Linux** is not provisioned (the entry point prints a notice and exits 0). Android on Linux: install a
+  JDK ≥ 17 and the Android command-line tools with your package manager, export the same variables, then
+  `sungen capability add mobile` for the project-local Appium + `uiautomator2`.
+- **`sungen update` does not refresh this folder.** To pick up a newer bundle, delete `appium-environment/`
+  and run `sungen capability add mobile` again (all other files are skipped because they already exist).
+- Windows downloads Google's command-line tools by a **pinned build number** (`$CmdlineToolsBuild` at the
+  top of `scripts/windows/install-android.ps1`). If the download 404s, bump it from
+  https://developer.android.com/studio#command-line-tools-only.
+- No AVD / Simulator is created and no phone is paired — plug in a device (USB debugging on) or start an
+  emulator before `/sungen:run-test`.
+
+## Manual fallback (the steps this bundle automates)
+
+- Android: https://sungen.sun-asterisk.vn/docs/mobile/appium-setup-android
+- iOS: https://sungen.sun-asterisk.vn/docs/mobile/appium-setup-ios
+- Overview + troubleshooting: https://sungen.sun-asterisk.vn/docs/mobile/appium-setup ·
+  https://sungen.sun-asterisk.vn/docs/mobile/mobile-troubleshooting
+
+## Layout
+
+```
+appium-environment/
+├── setup.sh · setup.ps1          entry points (OS check, flags, step order, summary)
+├── scripts/common/               lib.{sh,ps1} step runner · verify-node · install-appium · verify-appium
+├── scripts/macos/                install-android · verify-android · install-ios · verify-ios
+└── scripts/windows/              install-android · verify-android
+```

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

@@ -0,0 +1,44 @@
+# install-appium.ps1 - Appium stays PROJECT-LOCAL (a devDependency pulled in by @sungen/driver-mobile),
+# never `npm i -g appium`; the platform driver (uiautomator2) lives in ~\.appium and is installed
+# through that local CLI. Mirrors what `sungen init --mobile` does in TypeScript, so this script also
+# works on a fresh clone where a teammate ran init.
+if (-not $script:SungenEnvLibLoaded) { . (Join-Path $PSScriptRoot 'lib.ps1') }
+
+$AppiumCmd = $script:SungenEnvAppiumCmd
+
+function Get-AppiumVersion { if (Test-Path $AppiumCmd) { ((& $AppiumCmd -v) 2>$null | Select-Object -First 1) } }
+Invoke-Step -Title 'Appium (project-local)' -Check {
+  if (Test-Path $AppiumCmd) { "appium $(Get-AppiumVersion) (project-local: node_modules\.bin\appium)" }
+} -Install {
+  # Only re-install when the project already declares the mobile driver - otherwise the fix is
+  # `sungen capability add mobile`, a consent-gated sungen command, not this script's call.
+  $pkg = Join-Path $script:ProjectDir 'package.json'
+  if ((Test-Path $pkg) -and ((Get-Content $pkg -Raw) -match '"@sungen/driver-mobile"')) {
+    Push-Location $script:ProjectDir; try { Invoke-Native npm @('install') } finally { Pop-Location }
+  } else { return 'needs-user' }
+} -Verify {
+  if (Test-Path $AppiumCmd) { "appium $(Get-AppiumVersion)" }
+} -Hint "Appium is project-local (never global). Add the mobile driver + runtime with:`n  sungen capability add mobile"
+
+# --- platform driver -------------------------------------------------------------------------------
+function Get-InstalledDrivers {
+  $raw = (& $AppiumCmd driver list --installed --json) 2>$null | Out-String
+  if (-not $raw.Trim()) { return $null }
+  try { return ($raw | ConvertFrom-Json) } catch { return $null }
+}
+function Get-DriverDetail([string]$Name) {
+  $j = Get-InstalledDrivers
+  if ($j -and ($j.PSObject.Properties.Name -contains $Name)) { "$Name $($j.$Name.version) in ~\.appium" }
+}
+
+if (Test-Path $AppiumCmd) {
+  if (-not $script:SungenEnvSkipAndroid) {
+    $script:CurrentDriver = 'uiautomator2'
+    Invoke-Step -Title "Appium driver: $($script:CurrentDriver)" -Check { Get-DriverDetail $script:CurrentDriver } `
+      -Install { Invoke-Native $AppiumCmd @('driver', 'install', $script:CurrentDriver) } `
+      -Verify { Get-DriverDetail $script:CurrentDriver } `
+      -Hint "retry: npx appium driver install $($script:CurrentDriver)"
+  }
+} else {
+  Write-Warn 'Appium platform driver (uiautomator2)' 'skipped - Appium is not installed in this project yet (see the step above)'
+}

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# install-appium.sh — Appium stays PROJECT-LOCAL (a devDependency pulled in by @sungen/driver-mobile),
+# never `npm i -g appium`; the platform drivers (uiautomator2 / xcuitest) live in ~/.appium and are
+# installed through that local CLI. Mirrors what `sungen init --mobile` does in TypeScript, so this
+# script also works on a fresh clone where a teammate ran init.
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] || . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib.sh"
+
+APPIUM_BIN=$SUNGEN_ENV_APPIUM_BIN
+
+appium_check() {
+  [ -x "$APPIUM_BIN" ] || return 1
+  printf 'appium %s (project-local: node_modules/.bin/appium)' "$("$APPIUM_BIN" -v 2>/dev/null)"
+}
+appium_install() {
+  # Only re-install when the project already declares the mobile driver — otherwise the fix is
+  # `sungen capability add mobile`, which is a consent-gated sungen command, not this script's call.
+  if grep -q '"@sungen/driver-mobile"' "$PROJECT_DIR/package.json" 2>/dev/null; then
+    (cd "$PROJECT_DIR" && npm install)
+  else
+    return 2
+  fi
+}
+appium_verify() {
+  appium_check || { printf 'Appium is project-local (never global). Add the mobile driver + runtime with:\n  sungen capability add mobile'; return 1; }
+}
+run_step "Appium (project-local)" appium_check appium_install appium_verify
+
+# ── platform drivers — one run_step per driver, CURRENT_DRIVER carries the name (bash 3.2: no closures)
+installed_drivers_json() { "$APPIUM_BIN" driver list --installed --json 2>/dev/null; }
+drv_check() {
+  local json ver
+  json=$(installed_drivers_json) || return 1
+  printf '%s' "$json" | grep -q "\"$CURRENT_DRIVER\"" || return 1
+  ver=$(printf '%s' "$json" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const j=JSON.parse(s);process.stdout.write((j['$CURRENT_DRIVER']||{}).version||'')}catch{}})" 2>/dev/null)
+  printf '%s %s in ~/.appium' "$CURRENT_DRIVER" "${ver:-}"
+}
+drv_install() { "$APPIUM_BIN" driver install "$CURRENT_DRIVER"; }
+drv_verify()  { drv_check || { printf 'retry: npx appium driver install %s' "$CURRENT_DRIVER"; return 1; }; }
+
+if [ -x "$APPIUM_BIN" ]; then
+  APPIUM_DRIVERS="uiautomator2"
+  [ "$SUNGEN_ENV_SKIP_ANDROID" = 1 ] && APPIUM_DRIVERS=""
+  # xcuitest builds WebDriverAgent with Xcode at run time → only meaningful on a Mac.
+  if [ "$(uname -s)" = Darwin ] && [ "$SUNGEN_ENV_SKIP_IOS" != 1 ]; then APPIUM_DRIVERS="$APPIUM_DRIVERS xcuitest"; fi
+  for CURRENT_DRIVER in $APPIUM_DRIVERS; do
+    run_step "Appium driver: $CURRENT_DRIVER" drv_check drv_install drv_verify
+  done
+else
+  log_warn "Appium platform drivers (uiautomator2 / xcuitest)" "skipped — Appium is not installed in this project yet (see the step above)"
+fi

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

@@ -0,0 +1,108 @@
+# lib.ps1 - shared step runner for the sungen appium-environment bundle (Windows side).
+# Dot-sourced by setup.ps1 and by every scripts\**\*.ps1; never run directly.
+# Windows PowerShell 5.1 compatible: no ternary, no ??, ASCII only (5.1 reads BOM-less files as ANSI).
+#
+# Step model (see docs: Mobile -> Appium setup -> "One command"):
+#   Check   -> returns a detail string when already satisfied, $null otherwise (side-effect free)
+#   Install -> idempotent; output streams to the console; returns 'needs-user' when the user must finish it
+#   Verify  -> returns a detail string when satisfied, $null otherwise; -Hint is shown on failure
+
+if ($script:SungenEnvLibLoaded) { return }
+$script:SungenEnvLibLoaded = $true
+$ErrorActionPreference = 'Continue'
+
+# Flags - set by setup.ps1's parameters, read by every step.
+if ($null -eq $script:SungenEnvCheckOnly)   { $script:SungenEnvCheckOnly = $false }
+if ($null -eq $script:SungenEnvSkipAndroid) { $script:SungenEnvSkipAndroid = $false }
+if ($null -eq $script:SungenEnvNoProfile)   { $script:SungenEnvNoProfile = $false }
+# Flipped to $true when the User environment actually changed.
+$script:SungenEnvProfileChanged = $false
+
+# Paths: <project>\appium-environment\scripts\common\lib.ps1 -> bundle = ..\.., project = bundle\..
+$script:SungenEnvBundleDir = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+if (-not $script:ProjectDir) { $script:ProjectDir = (Resolve-Path (Join-Path $script:SungenEnvBundleDir '..')).Path }
+# Appium is project-local by design (never `npm i -g appium`) - see install-appium.ps1.
+$script:SungenEnvAppiumCmd = Join-Path $script:ProjectDir 'node_modules\.bin\appium.cmd'
+
+$script:CountOk = 0; $script:CountSkip = 0; $script:CountWarn = 0; $script:CountFail = 0
+
+function Write-Section([string]$Title) { Write-Host ''; Write-Host $Title -ForegroundColor White }
+function Write-Detail([string]$Text) {
+  if (-not $Text) { return }
+  foreach ($line in ($Text -split "`r?`n")) { if ($line) { Write-Host "            $line" -ForegroundColor DarkGray } }
+}
+function Write-Ok([string]$Title, [string]$Detail)   { $script:CountOk++;   Write-Host "[ok]      $Title" -ForegroundColor Green;    Write-Detail $Detail }
+function Write-Skip([string]$Title, [string]$Detail) { $script:CountSkip++; Write-Host "[skip]    $Title" -ForegroundColor DarkGray; Write-Detail $Detail }
+function Write-Warn([string]$Title, [string]$Detail) { $script:CountWarn++; Write-Host "[warn]    $Title" -ForegroundColor Yellow;   Write-Detail $Detail }
+function Write-Fail([string]$Title, [string]$Detail) { $script:CountFail++; Write-Host "[fail]    $Title" -ForegroundColor Red;      Write-Detail $Detail }
+function Write-Install([string]$Title) { Write-Host "[install] $Title" -ForegroundColor Cyan }
+
+# Invoke-Native <exe> <args...> - run a native command, throw on a non-zero exit code.
+function Invoke-Native([string]$File, [string[]]$Arguments) {
+  & $File @Arguments
+  if ($LASTEXITCODE -ne 0) { throw "$File exited with code $LASTEXITCODE" }
+}
+
+# Invoke-Step - an install-type step.
+function Invoke-Step {
+  param([string]$Title, [scriptblock]$Check, [scriptblock]$Install, [scriptblock]$Verify, [string]$Hint)
+  $found = $null; try { $found = & $Check } catch { $found = $null }
+  if ($found) { Write-Skip $Title "$found"; return }
+  if ($script:SungenEnvCheckOnly) { Write-Fail $Title 'not installed - run without -Check to install'; return }
+  Write-Install $Title
+  $needsUser = $false; $err = $null
+  try { $r = & $Install; if ("$r" -eq 'needs-user') { $needsUser = $true } } catch { $err = $_.Exception.Message }
+  $ok = $null; try { $ok = & $Verify } catch { $ok = $null }
+  if ($ok) { Write-Ok $Title "$ok"; return }
+  $msg = $Hint; if ($err) { $msg = "$err`n$Hint" }
+  if ($needsUser) { Write-Warn $Title $msg } else { Write-Fail $Title $msg }
+}
+
+# Invoke-Check - a verification-only step (ok / fail, or -Warn for informational checks).
+function Invoke-Check {
+  param([string]$Title, [scriptblock]$Check, [string]$Hint, [switch]$Warn)
+  $out = $null; try { $out = & $Check } catch { $out = $null }
+  if ($out) { Write-Ok $Title "$out"; return }
+  if ($Warn) { Write-Warn $Title $Hint } else { Write-Fail $Title $Hint }
+}
+
+# Invoke-Guided - GUI installs this bundle never performs itself: skip when present, else warn with the next action.
+function Invoke-Guided {
+  param([string]$Title, [scriptblock]$Check, [string]$Guidance)
+  $found = $null; try { $found = & $Check } catch { $found = $null }
+  if ($found) { Write-Skip $Title "$found" } else { Write-Warn $Title $Guidance }
+}
+
+# --- user environment (the Windows counterpart of the shell-profile block) ------------------------
+# Update-SessionPath - pick up PATH changes made by installers (winget) without a new console.
+function Update-SessionPath {
+  $env:Path = [Environment]::GetEnvironmentVariable('Path', 'Machine') + ';' + [Environment]::GetEnvironmentVariable('Path', 'User')
+}
+# Set-UserEnv <name> <value> - user-scope variable (what `setx` does, without its 1024-char truncation). $true when changed.
+function Set-UserEnv([string]$Name, [string]$Value) {
+  if ([Environment]::GetEnvironmentVariable($Name, 'User') -eq $Value) { Set-Item -Path "env:$Name" -Value $Value; return $false }
+  [Environment]::SetEnvironmentVariable($Name, $Value, 'User')
+  Set-Item -Path "env:$Name" -Value $Value
+  $script:SungenEnvProfileChanged = $true
+  return $true
+}
+# Add-UserPath <dir> - append to the user-scope Path once; also to this session. $true when changed.
+function Add-UserPath([string]$Dir) {
+  $current = [Environment]::GetEnvironmentVariable('Path', 'User')
+  $parts = @(); if ($current) { $parts = @($current -split ';' | Where-Object { $_ }) }
+  if (-not (($env:Path -split ';') -contains $Dir)) { $env:Path = "$env:Path;$Dir" }
+  if ($parts -contains $Dir) { return $false }
+  [Environment]::SetEnvironmentVariable('Path', (($parts + $Dir) -join ';'), 'User')
+  $script:SungenEnvProfileChanged = $true
+  return $true
+}
+
+# Write-Summary - tallies + the "new terminal" notice. Returns 1 when anything failed, else 0.
+function Write-Summary {
+  Write-Host ''
+  Write-Host "$($script:CountOk) ok, $($script:CountSkip) skipped, $($script:CountWarn) warned, $($script:CountFail) failed" -ForegroundColor White
+  if ($script:SungenEnvProfileChanged) { Write-Host '-> Open a NEW terminal so Path / JAVA_HOME / ANDROID_HOME apply.' -ForegroundColor Yellow }
+  if ($script:CountWarn -gt 0) { Write-Host '   warnings need a manual step - do it, then re-run this script.' }
+  if ($script:CountFail -gt 0) { return 1 }
+  return 0
+}

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

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# lib.sh — shared step runner for the sungen appium-environment bundle (macOS / Linux side).
+# Sourced by setup.sh and by every scripts/**/*.sh; never run directly.
+# Bash 3.2 compatible (the /bin/bash that ships with macOS): no associative arrays, no ${var,,}.
+#
+# Step model (see docs: Mobile → Appium setup → "One command"):
+#   check   → exit 0 when already satisfied (side-effect free — this is all `--check` runs)
+#   install → idempotent; output streams to the terminal; exit 2 = started but needs a user action
+#   verify  → exit 0 when satisfied; stdout is the detail (ok) or the hint (fail)
+
+[ -n "${SUNGEN_ENV_LIB_LOADED:-}" ] && return 0
+SUNGEN_ENV_LIB_LOADED=1
+
+# Flags — set by setup.sh's argument parser, read by every step.
+SUNGEN_ENV_CHECK_ONLY=${SUNGEN_ENV_CHECK_ONLY:-0}
+SUNGEN_ENV_SKIP_ANDROID=${SUNGEN_ENV_SKIP_ANDROID:-0}
+SUNGEN_ENV_SKIP_IOS=${SUNGEN_ENV_SKIP_IOS:-0}
+SUNGEN_ENV_NO_PROFILE=${SUNGEN_ENV_NO_PROFILE:-0}
+# Flipped to 1 by write_profile_block when the shell profile actually changed.
+SUNGEN_ENV_PROFILE_CHANGED=0
+
+# Paths: <project>/appium-environment/scripts/common/lib.sh → bundle = ../.., project = bundle/..
+SUNGEN_ENV_BUNDLE_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+PROJECT_DIR=${PROJECT_DIR:-$(cd "$SUNGEN_ENV_BUNDLE_DIR/.." && pwd)}
+# Appium is project-local by design (never `npm i -g appium`) — see install-appium.sh.
+SUNGEN_ENV_APPIUM_BIN="$PROJECT_DIR/node_modules/.bin/appium"
+
+# Environment as it was BEFORE this run — lets the profile step recognise a machine whose own
+# shell profile already exports everything (then no block is written).
+SUNGEN_ENV_INITIAL_ANDROID_HOME=${ANDROID_HOME:-}
+SUNGEN_ENV_INITIAL_JAVA_HOME=${JAVA_HOME:-}
+SUNGEN_ENV_INITIAL_ADB=$(command -v adb 2>/dev/null || true)
+
+COUNT_OK=0; COUNT_SKIP=0; COUNT_WARN=0; COUNT_FAIL=0
+
+if [ -t 1 ]; then
+  C_OK=$'\033[32m'; C_WARN=$'\033[33m'; C_FAIL=$'\033[31m'; C_DIM=$'\033[2m'; C_BOLD=$'\033[1m'; C_RESET=$'\033[0m'
+else
+  C_OK=''; C_WARN=''; C_FAIL=''; C_DIM=''; C_BOLD=''; C_RESET=''
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+# version_major "v22.17.1" → 22
+version_major() { printf '%s' "$1" | sed -E 's/^[^0-9]*([0-9]+).*/\1/'; }
+# java_major_of <java binary> → 21 (empty when not runnable). "1.8.0_x" → 1, so JDK 8 fails a ≥17 gate.
+java_major_of() { "$1" -version 2>&1 | head -n1 | sed -E 's/^[^"]*"([0-9]+)(\.[0-9]+)*.*$/\1/' | grep -E '^[0-9]+$'; }
+# first_line <multi-line string>
+first_line() { printf '%s' "${1%%$'\n'*}"; }
+
+section() { printf '\n%s%s%s\n' "$C_BOLD" "$1" "$C_RESET"; }
+_detail() { [ -n "$1" ] && printf '            %s%s%s\n' "$C_DIM" "$1" "$C_RESET"; return 0; }
+_detail_lines() { printf '%s\n' "$1" | while IFS= read -r line; do [ -n "$line" ] && _detail "$line"; done; return 0; }
+
+log_ok()      { COUNT_OK=$((COUNT_OK+1));     printf '%s✓ ok%s       %s\n' "$C_OK" "$C_RESET" "$1"; _detail_lines "${2:-}"; }
+log_skip()    { COUNT_SKIP=$((COUNT_SKIP+1)); printf '%s– skip%s     %s\n' "$C_DIM" "$C_RESET" "$1"; _detail_lines "${2:-}"; }
+log_warn()    { COUNT_WARN=$((COUNT_WARN+1)); printf '%s⚠ warn%s     %s\n' "$C_WARN" "$C_RESET" "$1"; _detail_lines "${2:-}"; }
+log_fail()    { COUNT_FAIL=$((COUNT_FAIL+1)); printf '%s✗ fail%s     %s\n' "$C_FAIL" "$C_RESET" "$1"; _detail_lines "${2:-}"; }
+log_install() { printf '📦 install  %s\n' "$1"; }
+
+# run_step <title> <check_fn> <install_fn> <verify_fn> — an install-type step.
+run_step() {
+  local title=$1 check_fn=$2 install_fn=$3 verify_fn=$4 found out rc
+  if found=$("$check_fn" 2>/dev/null); then log_skip "$title" "${found:-already installed}"; return 0; fi
+  if [ "$SUNGEN_ENV_CHECK_ONLY" = 1 ]; then log_fail "$title" "not installed — run without --check to install"; return 0; fi
+  log_install "$title"
+  "$install_fn"; rc=$?
+  if out=$("$verify_fn" 2>&1); then log_ok "$title" "$out"; return 0; fi
+  if [ "$rc" -eq 2 ]; then log_warn "$title" "${out:-needs a manual step — re-run setup.sh afterwards}"
+  else log_fail "$title" "${out:-install did not complete}"; fi
+  return 0
+}
+
+# run_check <title> <check_fn> <hint> [warn] — a verification-only step (ok / fail, or warn for informational checks).
+run_check() {
+  local title=$1 check_fn=$2 hint=$3 level=${4:-fail} out msg
+  if out=$("$check_fn" 2>&1); then log_ok "$title" "$out"; return 0; fi
+  msg=$hint; [ -n "$out" ] && msg="$out"$'\n'"$hint"
+  if [ "$level" = warn ]; then log_warn "$title" "$msg"; else log_fail "$title" "$msg"; fi
+  return 0
+}
+
+# run_guided <title> <check_fn> <guidance> — GUI / App Store installs this bundle never performs itself.
+run_guided() {
+  local title=$1 check_fn=$2 guidance=$3 found
+  if found=$("$check_fn" 2>/dev/null); then log_skip "$title" "${found:-already installed}"; return 0; fi
+  log_warn "$title" "$guidance"
+  return 0
+}
+
+# ── shell profile block ────────────────────────────────────────────────────────────────────────
+PROFILE_BEGIN='# >>> sungen mobile env >>>'
+PROFILE_END='# <<< sungen mobile env <<<'
+# zsh → ~/.zshrc, bash → ~/.bash_profile, anything else → ~/.profile
+profile_file() {
+  case "${SHELL:-}" in
+    *zsh)  printf '%s' "$HOME/.zshrc" ;;
+    *bash) printf '%s' "$HOME/.bash_profile" ;;
+    *)     printf '%s' "$HOME/.profile" ;;
+  esac
+}
+profile_block_content() {
+  local file; file=$(profile_file); [ -f "$file" ] || return 0
+  awk -v b="$PROFILE_BEGIN" -v e="$PROFILE_END" '$0==b{f=1;next} $0==e{f=0} f' "$file"
+}
+# write_profile_block <content> — append the marked block, replace it when different, keep it when identical.
+# Returns 0 = unchanged, 3 = written. Sets PROFILE_MSG. Must NOT be called in a subshell (it sets globals).
+write_profile_block() {
+  local content=$1 file tmp
+  file=$(profile_file); [ -f "$file" ] || : > "$file"
+  if [ "$(profile_block_content)" = "$content" ]; then PROFILE_MSG="block already up to date in $file"; return 0; fi
+  tmp=$(mktemp)
+  awk -v b="$PROFILE_BEGIN" -v e="$PROFILE_END" '$0==b{f=1;next} $0==e{f=0;next} !f' "$file" > "$tmp"
+  [ -s "$tmp" ] && [ -n "$(tail -c1 "$tmp")" ] && printf '\n' >> "$tmp"
+  { cat "$tmp"; printf '%s\n%s\n%s\n' "$PROFILE_BEGIN" "$content" "$PROFILE_END"; } > "$file"
+  rm -f "$tmp"
+  SUNGEN_ENV_PROFILE_CHANGED=1
+  PROFILE_MSG="written to $file — open a new terminal to apply"
+  return 3
+}
+# profile_step <title> <content> — the profile block as a step (honours --no-profile and --check).
+profile_step() {
+  local title=$1 content=$2
+  if [ "$SUNGEN_ENV_NO_PROFILE" = 1 ]; then log_skip "$title" "--no-profile"; return 0; fi
+  if [ "$SUNGEN_ENV_CHECK_ONLY" = 1 ]; then
+    if [ "$(profile_block_content)" = "$content" ]; then log_skip "$title" "block already up to date in $(profile_file)"
+    else log_fail "$title" "block missing or outdated in $(profile_file) — run without --check to write it"; fi
+    return 0
+  fi
+  write_profile_block "$content"
+  case $? in 3) log_ok "$title" "$PROFILE_MSG" ;; *) log_skip "$title" "$PROFILE_MSG" ;; esac
+  return 0
+}
+
+# print_summary — tallies + the "new terminal" notice. Exit 1 when anything failed.
+print_summary() {
+  printf '\n%s%d ok · %d skipped · %d warned · %d failed%s\n' "$C_BOLD" "$COUNT_OK" "$COUNT_SKIP" "$COUNT_WARN" "$COUNT_FAIL" "$C_RESET"
+  [ "$SUNGEN_ENV_PROFILE_CHANGED" = 1 ] && printf '%s→ Open a NEW terminal so PATH / JAVA_HOME / ANDROID_HOME apply.%s\n' "$C_WARN" "$C_RESET"
+  [ "$COUNT_WARN" -gt 0 ] && printf '  warnings need a manual step — do it, then re-run this script.\n'
+  [ "$COUNT_FAIL" -gt 0 ] && return 1
+  return 0
+}

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)"