@houwert/conductor 0.29.3 → 0.31.0

package/skills/conductor-device-interact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-interact
-description: Drive a running iOS simulator, Android emulator, tvOS simulator, Vega (Amazon Fire TV) virtual device, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements (by selector or raw coordinate), typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard/remote keys, opening URLs or deep links, navigating back, granting/denying app permissions, adding media to the gallery, setting GPS location or a travel route, toggling airplane mode, recording a screen video, or verifying an app change in the real running app.
+description: Drive a running iOS simulator, Android emulator, tvOS simulator, Vega (Amazon Fire TV) virtual device, Roku device, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements (by selector or raw coordinate), typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard/remote keys, opening URLs or deep links, navigating back, granting/denying app permissions, adding media to the gallery, setting GPS location or a travel route, toggling airplane mode, recording a screen video, or verifying an app change in the real running app.
 ---
 
 # Conductor — device interaction
@@ -41,7 +41,7 @@ conductor assert-visible "Dashboard"
 | `conductor copy-text-from <element>` | Print an element's text (and copy to the iOS clipboard) |
 | `conductor input-text <text>` | Type into the focused field |
 | `conductor erase-text [n]` | Erase n characters (default 50) |
-| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`) for tvOS / Android TV / vega. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) or a remote button (`Remote Dpad Up/Down/Left/Right/Center`, `Remote Menu`, `Remote Page Up/Down` on tvOS and Android TV, and `Remote Guide` on tvOS) for tvOS / Android TV / vega / roku. `--long-press` / `--duration <seconds>` holds it; `--measure` times the response (see `conductor-profiler`) |
 | `conductor hide-keyboard` | Dismiss the on-screen keyboard |
 | `conductor back` | Press back |
 | `conductor scroll [--direction down\|up\|left\|right]` | Scroll |
@@ -125,8 +125,19 @@ relaunch without the flag. (See `conductor-device-setup`.)
 
 ## Tips
 
-- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web|vega>` scopes by platform.
+- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web|vega|roku>` scopes by platform.
 - Vega (Amazon Fire TV) is D-pad driven: navigate with `press-key "Remote Dpad …"`; coordinate `tap-on` also works. `open-link`, `set-location`, gestures, and clipboard are unsupported. See `conductor-device-setup`.
+- Apple TV (tvOS) is focus-driven and has **no touch surface automation**: XCTest
+  refuses remote swipe gestures ("Swipe events are only implemented for iOS,
+  visionOS, and watchOS"), so `swipe`/`scroll` are unavailable. Navigate with
+  `press-key "Remote Dpad Up/Down/Left/Right"` and `"Remote Dpad Center"`; for
+  long lists use `press-key "Remote Page Up"` / `"Remote Page Down"` (tvOS 14.3+;
+  also mapped on Android TV), which move a screenful at a time when the app
+  honours them. `"Remote Guide"` (14.3+) and
+  `"Remote TV Provider"` / `"Remote One Two Three"` / `"Remote Four Colors"`
+  (18.1+) are also available. `--duration <seconds>` holds a button for
+  accelerated scrolling.
+- Roku is D-pad only — there is no touch. `tap-on <selector>` resolves the element but presses `Select`, which activates whatever currently holds **focus**, so navigate focus onto the target with `press-key "Remote Dpad …"` first and use `tap-on` to confirm. `scroll`/`swipe` become repeated D-pad presses in the direction the content moves. `open-link` needs an app id (it becomes a channel launch parameter). Only sideloaded dev-mode channels are inspectable. See `conductor-device-setup`.
 - Add `--json` for machine-readable output; failed assertions exit non-zero.
 - Run a per-session daemon for many commands (see `conductor-device-setup`).
 - `conductor <command> --help` for exact flags.

package/skills/conductor-device-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor-device-setup
-description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, Vega (Amazon Fire TV) virtual devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, physical iOS/tvOS devices, Vega (Amazon Fire TV) virtual devices, Roku devices, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, attaching to a Vega VVD or a Roku device, driving a physical iPhone/iPad/Apple TV, installing or launching an app, setting up the web driver, attaching to an already-running browser over CDP (e.g. an Electron app / its webviews), keeping the driver warm, or coordinating multiple devices for parallel agents.
 ---
 
 # Conductor — device & app setup
@@ -21,7 +21,7 @@ conductor list-apps          # installed app ids / package names (--json adds ap
 
 | Command                                                               | Purpose                                                                    |
 | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `conductor start-device --platform <ios\|android\|tvos\|web\|vega>`   | Boot a simulator/emulator, start the web driver, or attach to a Vega VVD    |
+| `conductor start-device --platform <ios\|android\|tvos\|web\|vega\|roku>` | Boot a simulator/emulator, start the web driver, attach to a Vega VVD, or check a Roku device |
 | `conductor start-device --os-version <n> --device-type <name>`        | Pick OS version + device type (creates if needed)                          |
 | `conductor start-device --platform android --avd <name> --device-type <profile> --memory <mb>` | Create an Android AVD with a RAM floor (default 4096MB; only raises, creation-time only) |
 | `conductor stop-device [<name-or-id>] [--all]`                        | Shut down device(s)                                                        |
@@ -69,6 +69,66 @@ app launch — so launch the app under test via conductor. Navigate with the D-p
 works. Unsupported on Vega: deep links (`open-link`), `set-location`, gestures,
 screen recording, clipboard, `clear-state`/`uninstall-app`.
 
+### Roku
+
+Roku is driven over the network with the **External Control Protocol** (ECP — an
+HTTP REST API on device port 8060). There is no emulator and no driver process:
+physical hardware only, and every command is a stateless ECP call.
+
+Device setup, once per device:
+
+1. Enable developer mode (Home ×3, Up ×2, Right, Left, Right, Left, Right) and
+   set a dev password.
+2. Set **Settings > System > Advanced system settings > Control by mobile apps >
+   Network access** to **Permissive** — recent Roku OS versions answer `403` to
+   every keypress otherwise, while still serving the view hierarchy.
+
+Environment:
+
+```bash
+export CONDUCTOR_ROKU_HOST=192.168.1.100   # pin a device by IP (primary)
+export CONDUCTOR_ROKU_PASSWORD=devpwd      # dev-mode password (screenshots only)
+export CONDUCTOR_ROKU_DISCOVERY=true       # optional: SSDP LAN scan (~1s per listing)
+```
+
+Devices show up in `list-devices` as `roku:<host>`;
+`conductor start-device --platform roku [--name <host>]` checks reachability
+rather than booting anything. The view hierarchy comes from `/query/app-ui`,
+which **only reports sideloaded dev-mode channels** — a store channel inspects as
+empty. A sideloaded channel's app id is `dev`. Screenshots need
+`CONDUCTOR_ROKU_PASSWORD`.
+
+Unsupported on Roku: `install-app`/`uninstall-app` (sideload via the device's dev
+web server at `http://<device-ip>`), `list-apps`, `clear-state`, gestures,
+screen recording, clipboard, `set-location`, memory/CPU profiling, and device logs.
+
+### Physical iOS / tvOS devices
+
+Real iPhones, iPads, and Apple TVs work alongside simulators. They're discovered
+through `devicectl`, show up in `list-devices` with status `connected`, and are
+addressed by their CoreDevice identifier (`--device <uuid>`).
+
+Requirements:
+
+- The device is **paired** with this Mac and on the **same network** — conductor
+  reaches the driver over the LAN, not the host's loopback.
+- **Developer Mode** is enabled on the device.
+- A signing team: conductor builds and signs the XCTest driver locally on first
+  use (a few minutes; cached per team in `~/.conductor/<platform>-driver-device/`).
+  Set `CONDUCTOR_TEAM_ID=<team>` when the Mac has more than one development team
+  — conductor refuses to guess rather than sign with the wrong one.
+
+Everything driven through the XCTest driver behaves the same as on a simulator:
+`inspect`, `capture-ui`, `tap-on`, `press-key`, `swipe`, `launch-app`,
+`terminate-app`, `install-app`, `uninstall-app`, flows.
+
+Simulator-only — these fail with an explicit message on a physical device:
+`set-location`, `open-link`, clipboard read/write, `clear-keychain`, `add-media`,
+screen recording and the live video stream, and OS log collection (`conductor
+logs` still gets **Metro** logs, which is the useful source for React Native).
+`clear-state` uninstalls on device without reinstalling — reinstall with
+`install-app` afterwards.
+
 ## App lifecycle
 
 | Command                                               | Purpose                                                                |

package/skills/conductor-profiler/SKILL.md

@@ -48,7 +48,7 @@ navigation, prefer asking a human to drive the physical remote during the
 window (the command announces the window on stderr for exactly this), and treat
 a divergence between human-driven and automated numbers as the harness.
 
-Not available on `vega` — but a **physical Fire TV Stick runs Fire OS
+Not available on `roku` (ECP exposes no counters) or `vega` — but a **physical Fire TV Stick runs Fire OS
 (Android)** over adb and works fine.
 
 Attribute jank by comparing each phase's p95 against its p50: `vsyncDelay` means