@sun-asterisk/sungen 3.2.31 → 3.2.32

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -154,6 +154,7 @@ two content-filtered queries can hit different rows if the table re-renders in b
 #    dropdown | select | combobox → tag probed at runtime (toHaveValue native, toHaveText custom trigger)
 # 5. State: User see [T] button is disabled | checkbox is checked | dialog with {{v}} is hidden
 # 6. Attribute (toHaveAttribute): User see [T] image | link with {{v}}
+#    WHICH attribute comes from the entry's `attribute:` — any name, not just href/src
 # 7. Count: User see [T] row with {{count}}
 # 8. Page: User see [T] page | page with {{url}}   ← `with` also asserts the query string
 #    NEVER a state: `page is hidden` / `page is empty` … are NOT step forms (see Pattern 8 below)
@@ -291,7 +292,22 @@ job table:
   value: 'div.job-list'
   rows: 'div.job-row'        # what EVERY row matches — NOT a row label's entry
 ```
-Two different keys, two meanings: `rows:` on the table = every row (the shape); a `type: locator` entry on a **row label** = ONE positioned row (`tbody tr:first-child`). A shape put on a row label fails at run time with a `toHaveCount(1)` message that points back here. A CSS-located table with no `rows:` gets `SG-W016`. On a shaped table `table row {{n}}` counts from the first data row (no header offset).
+Two different keys, two meanings: `rows:` on the table = every row (the shape); a `type: locator` entry on a **row label** = ONE positioned row (`tbody tr:first-child`). A shape put on a row label fails at run time with a `toHaveCount(1)` message that points back here. A table located by CSS — or by a role that holds no rows, such as `role: list` or `role: region` — with no `rows:` gets `SG-W016`. On a shaped table `table row {{n}}` counts from the first data row (no header offset).
+
+**A shaped row has no CELLS either, so the two cell-reading steps need one more declaration.** `see [Col] column with {{v}}` reaches the cell through `getByRole('cell')`, and `table match data:` reads its header row from `thead tr` and addresses cells as `td, th` — a `<div>` row has none of those. Name the cell on the column:
+```yaml
+job table:
+  type: locator
+  value: 'div.job-list'
+  rows: 'div.job-row'
+  columns:
+    title:
+      index: 0
+      header: 'Title'
+      elements:
+        cell: { type: locator, value: '.job-title' }   # relative to ONE row
+```
+With it, `see [Title] column with {{v}}` compiles to `tableRow.locator('.job-title')` and `table match data:` stops reading `thead` altogether — the header-to-column mapping is then known at compile time, so there is nothing left to race with. Without it on a shaped table, `see [Col] column` warns (`SG-W034`) and `table match data:` is refused outright (`SG-E035`) rather than waiting out every timeout against a header row that will never exist.
 
 ### Browser storage `[web]`
 
@@ -556,6 +572,7 @@ award:
 | `page` | relative URL | — | navigation |
 | `upload` | — | — | file inputs |
 | `frame` | iframe selector | — | iframes |
+| `id` | `#the-id` (a bare `the-id` also works) | — | an element whose only stable handle is its DOM id |
 
 Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns` `checked` `selected`
 
@@ -569,6 +586,39 @@ when the state differs, then assert it; `is checked` / `is unchecked` / `is sele
 the same entry (`is focused`, …) keep their native matchers. The value must be ONE plain class token or
 attribute name — whitespace, a quote or a backslash is refused at compile time, naming the entry.
 
+`attribute:` names the attribute an `image`/`link` assertion reads, and it takes ANY attribute name
+straight from the YAML — nothing is hardcoded to `href`/`src`. To assert several attributes of ONE
+element, declare several keys with the SAME locator and different `attribute:`; each key is then a
+separate reference in the Gherkin:
+```yaml
+job link:            # the link's TEXT
+  type: locator
+  value: 'a.job-link'
+job link href:       # the same element, its href
+  type: locator
+  value: 'a.job-link'
+  attribute: href
+job link target:
+  type: locator
+  value: 'a.job-link'
+  attribute: target
+```
+
+**A `page` value that is an ABSOLUTE URL now anchors the HOST as well as the path.** `value:
+'https://admin.example.com/jobs'` means "that path on that host": `see [X] page`, `is on [X] page`
+and `should remain on` all fail on `https://admin-stg.example.com/jobs`. Before, only `wait for [X]
+page` checked the host and the assertions matched the path on any host at all — so an assertion
+naming one environment silently passed in another. If the page is the same in every environment,
+declare it **relative** (`value: '/jobs'`) and let `baseURL` supply the host; keep the absolute form
+for a destination that really is on another host.
+
+`anchor:` is a `page` entry's rendered-content proof: `Then User see [X] page` asserts the URL AND
+that the anchor element is present, so a route guard that leaves the URL alone cannot pass it. Three
+things it does NOT do, each verified rather than assumed: it is read only by the `Then`-side page
+assertion, so `Given User is on [X] page` ignores it; the `should see route` / `should remain on`
+forms ignore it too — they compile through the route assertion, which is never handed an anchor; and
+nothing warns when a page entry declares one and no step asserts that page.
+
 `scope` (e.g. `scope: dialog`) is `[web]`-effective only — no Appium template reads `inDialog`, so
 on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`).
 
@@ -724,7 +774,9 @@ npx playwright test --grep "@smoke|@high"    # smoke OR high
 | Serial (default) | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
 | `@parallel` | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
 
-**`@parallel` is required** when a feature has multiple auth groups (e.g., `@auth:user` + `@no-auth` scenarios). Serial mode uses one shared browser context and cannot mix auth roles. The compiler will error if `@parallel` is missing in this case.
+**Multiple auth groups need the default isolation.** A feature mixing `@auth:user` with `@no-auth` compiles as-is — features are parallel by default, and `@parallel` only names that default. What breaks it is `@serial`: one shared browser context cannot carry two different sessions, so the compiler errors and asks you to drop `@serial` or split the feature.
+
+`@no-auth` is a demand for an **empty** session, not merely the absence of `@auth:`. Its scenarios compile into their own `test.describe('no-auth')` with an inline empty `storageState`, so they stay signed out even when `playwright.config.ts` sets a global one. An untagged scenario is different again: it inherits whatever that config says.
 
 ### `@flow` tag (E2E cross-screen testing)
 
@@ -806,6 +858,7 @@ dashboard:
 | Assertion clause the pattern drops | `Then User see [Code] text matches "<format>"` compiling to a bare `toBeVisible()` | Use the exact supported phrasing for the clause (see the `matches` / `contains` / `has text` forms above). A clause that gets swallowed leaves an assertion that passes whatever the element says, so the step is rejected with `SG-E023` instead. If the step still compiles bare, you are on an older global sungen — run `npx sungen` |
 | Mobile lifecycle step with no app id | `When User restart the app` in a feature whose `Path:` carries only a route | Declare the app id on the Feature: `Path: com.example.app/.MainActivity \| com.example.app`. The lifecycle steps resolve the app from `Path`; without it the whole spec would die at runtime, so the step is rejected with `SG-E024`. For a mobile unit `--path` carries the APP ID, `--reach` carries the navigation recipe |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
+| Asserting a cell with the row filter | `Then User see [Status] text in [Job Table] table with {{v}}` | The single `with` is read as the EXPECTED VALUE, not as a row filter, so the assertion runs against the WHOLE table and can pass on a row the sentence never named. Use the two-`with` form — `Then User see [Status] text with <expected> in [Job Row] row with {{v}}` — pointing the second `[…]` at a ROW entry, not at the table entry (a filter applied to the table narrows nothing). Warned with `SG-W032`. A `fill` is NOT flagged: a write needs a value, so its `with {{v}}` is that value and the step is an ordinary container-scoped write |
 | Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
 | Literal URL navigate | `User navigate to "/dashboard"` | `User is on [Dashboard] page` (add page selector in `selectors.yaml`) |

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
+}