@houwert/conductor 0.19.1 → 0.21.0

package/skills/conductor-create-flow/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: conductor-create-flow
+description: Author and run Maestro-compatible YAML flows and command sequences with the conductor CLI, including recording flows from live interactions and sharding them across devices. Use when scripting a repeatable multi-step app journey, running an existing Maestro flow, recording a flow by interacting with the app, or running flows in parallel across booted devices.
+---
+
+# Conductor — flows
+
+A **flow** is a YAML file describing a sequence of conductor commands.
+Conductor's format is a subset of [Maestro](https://maestro.mobile.dev)'s — most
+existing Maestro flows run unchanged. Use flows for repeatable journeys; use
+`conductor-device-interact` for one-off ad-hoc steps.
+
+## Run flows
+
+| Command | Purpose |
+|---|---|
+| `conductor run-flow <file> [--env K=V] [--benchmark]` | Run a Maestro YAML flow file |
+| `conductor run-flow-inline '<yaml>' [--benchmark]` | Run inline YAML from the command line |
+| `conductor run-sequence [--file path.json]` | Run a JSON sequence of conductor commands serially; reads stdin if no `--file` |
+| `conductor run-parallel --flows-dir <path>` | Shard a directory of flows across all booted devices |
+
+`--benchmark` prints elapsed time per command and total flow time.
+
+## Flow YAML
+
+```yaml
+appId: com.example.myapp
+---
+- launchApp
+- tapOn: "Sign In"
+- inputText: "user@example.com"
+- assertVisible: "Dashboard"
+```
+
+`run-sequence` JSON shape (stops on first non-zero exit):
+
+```json
+{ "steps": [ { "cmd": "tap-on", "args": ["Login"] }, { "cmd": "input-text", "args": ["user@example.com"] } ] }
+```
+
+## Record a flow from your interactions
+
+| Command | Purpose |
+|---|---|
+| `conductor flow record start [--out path]` | Start recording this session's interactions to a YAML file |
+| `conductor flow record echo <text>` | Insert a `console.log` step |
+| `conductor flow record status` | Show the active recording path |
+| `conductor flow record finish` | Close the recording, print the file path |
+
+Record, then interact via `conductor-device-interact`; each action is appended
+to the flow. `finish` gives you a runnable `.yaml`.
+
+## Tips
+
+- Add `--json` for machine-readable output; a failed step exits non-zero.
+- `conductor run-flow --help` (and friends) for exact flags.

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

@@ -0,0 +1,96 @@
+---
+name: conductor-device-interact
+description: Drive a running iOS simulator, Android emulator, tvOS simulator, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements, typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard keys, opening URLs or deep links, navigating back, or verifying an app change in the real running app.
+---
+
+# Conductor — device interaction
+
+`conductor` drives a real running app the way a user would: launch it, tap,
+type, scroll, and assert. It bundles its own native drivers — no second CLI to
+install. Use it to verify a change in the actual app, not just in tests.
+
+To **observe** the screen (inspect the hierarchy, screenshot, read element
+state), use the `conductor-inspect` skill — it pairs with this one.
+
+## The core loop: act → observe → act
+
+Never tap blind, never assume the result. After every action, observe before
+the next one.
+
+1. **Observe** with `conductor capture-ui` (see `conductor-inspect`) to see the
+   screen and get short element refs (`@e1`, `@e2`, …).
+2. **Act** — `tap-on`, `input-text`, `scroll`, etc.
+3. **Confirm** with `assert-visible` / another `capture-ui`.
+
+```bash
+conductor launch-app com.example.myapp
+conductor capture-ui            # observe; get @eN refs
+conductor tap-on "Sign In"      # or: conductor tap-on @e3
+conductor input-text "user@example.com"
+conductor assert-visible "Dashboard"
+```
+
+## Interaction commands
+
+| Command | Purpose |
+|---|---|
+| `conductor launch-app <appId>` | Launch app (saved to session). `--no-stop-app` resumes; `--argument key=value` passes launch args |
+| `conductor stop-app [<appId>]` | Stop the app |
+| `conductor tap-on <element>` | Tap by text, id, or `@eN`. `--long-press`, `--double-tap`, `--optional`, `--index <n>` |
+| `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, …) |
+| `conductor hide-keyboard` | Dismiss the on-screen keyboard |
+| `conductor back` | Press back |
+| `conductor scroll [--direction down\|up\|left\|right]` | Scroll |
+| `conductor scroll-until-visible <element> [--direction] [--timeout ms]` | Scroll until element appears |
+| `conductor swipe --direction <dir>` / `--start <x,y> --end <x,y> [--duration ms]` | Swipe |
+| `conductor open-link <url>` | Open a URL / deep link |
+| `conductor pinch [--scale N] [--center x,y]` | Two-finger pinch (scale<1 out, >1 in) |
+| `conductor rotate-gesture [--degrees N] [--center x,y]` | Two-finger rotate |
+| `conductor gesture <json\|--file path>` | Play a multi-touch path |
+| `conductor clipboard read` / `clipboard write <text>` / `paste` | Clipboard (iOS) |
+| `conductor list-options [command]` | List valid values for enumerated params |
+
+## Discovering valid values
+
+Several commands only accept a fixed set of values (`press-key <key>`,
+`--direction`, `set-orientation`, `set-viewport --preset`/`--color-scheme`,
+`logs --level`/`--source`, `--platform`). Don't guess — list them:
+
+- `conductor <command> --options` — valid values for that command, e.g.
+  `conductor press-key --options`, `conductor swipe --options`.
+- `conductor list-options [command|param]` — same data; with no argument it
+  lists every enumerated parameter, or filter by name (`list-options direction`).
+- Add `--json` for machine-readable output.
+
+## Selecting elements
+
+Positional `<element>` matches **accessibility id first, then visible text**.
+Disambiguate when multiple match:
+
+- `--id <id>` / `--text <text>` — id-only / text-only matching
+- `--index <n>` — nth match (0-based)
+- `--below` / `--above` / `--left-of` / `--right-of <text>` — relative position
+- `--focused`, `--enabled`, `--checked`, `--selected` — state filters
+- `--timeout <ms>` — wait for the element to appear
+- `--optional` — missing element is a no-op, not an error
+- `@eN` — exact element from the **last `capture-ui`** (cached coords, ephemeral
+  ~60s; re-capture after navigating)
+
+If you can't find an element, run `conductor inspect` or `capture-ui` to see the
+real ids and texts rather than guessing.
+
+## ⚠️ Don't reset state to "fix" navigation
+
+Never use `launch-app --clear-state`, `clear-state`, or `--clear-keychain` to
+clear focus or navigation — they **wipe user data and sign the user out**, and
+can't be undone without their credentials. Navigate out with `back` / Menu, or
+relaunch without the flag. (See `conductor-device-setup`.)
+
+## Tips
+
+- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web>` scopes by platform.
+- 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

@@ -0,0 +1,73 @@
+---
+name: conductor-device-setup
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, installing or launching an app, setting up the web driver, keeping the driver warm, or coordinating multiple devices for parallel agents.
+---
+
+# Conductor — device & app setup
+
+Get a device running and an app installed before you drive it. Start here when
+nothing is booted yet.
+
+## Orient first
+
+```bash
+conductor workspace info     # detected project type, bundle IDs, devices, Metro port — best first call
+conductor list-devices       # booted + available devices
+conductor foreground-app     # bundle id of the app currently in front
+conductor list-apps          # installed app ids / package names
+```
+
+## Devices
+
+| Command | Purpose |
+|---|---|
+| `conductor start-device --platform <ios\|android\|tvos\|web>` | Boot a simulator/emulator or start the web driver |
+| `conductor start-device --os-version <n> --device-type <name>` | Pick OS version + device type (creates if needed) |
+| `conductor stop-device [<name-or-id>] [--all]` | Shut down device(s) |
+| `conductor delete-device <name-or-id> [--all]` | Delete simulator(s)/AVD(s)/web session(s) |
+| `conductor set-location --lat <n> --lng <n>` | Set GPS coordinates |
+| `conductor set-orientation <portrait\|landscape>` | Set orientation |
+| `conductor set-viewport [<w> <h>] [--preset mobile\|tablet\|desktop]` | Resize web viewport (web only) |
+| `conductor install-web [--check] [browser]` | Install a Playwright browser (chromium/firefox/webkit); `--check` = status |
+
+## App lifecycle
+
+| Command | Purpose |
+|---|---|
+| `conductor install-app <path>` | Install .app / .ipa / .apk |
+| `conductor launch-app <appId>` | Launch app (saved to session); `--no-stop-app`, `--argument key=value` |
+| `conductor stop-app [<appId>]` | Stop app |
+| `conductor uninstall-app <appId>` | Uninstall app |
+| `conductor copy-app <bundleId> --from <id> --to <id>` | Copy an installed app between iOS simulators |
+| `conductor download-app <appId> --output <path>` | Download installed app binary |
+
+### ⚠️ Destructive flags — ask the user first
+
+`conductor clear-state [<appId>]`, `launch-app --clear-state`, and
+`launch-app --clear-keychain` **wipe app data and sign the user out**, and can't
+be undone without their credentials. Never use them to "reset focus" or clear
+navigation — relaunch without the flag, or navigate out with `back` / Menu. If
+you genuinely need one, ask the human first.
+
+## Sessions, daemon & device pool
+
+A **session** remembers the last device + app so you don't re-specify them.
+Parallel agents each get their own `--session <name>` so they don't collide.
+
+| Command | Purpose |
+|---|---|
+| `conductor session [--clear] [--list]` | Show, clear, or list sessions |
+| `conductor daemon-start` | Start the per-session background daemon (keeps the driver warm — do this for any multi-step session) |
+| `conductor daemon-status` | Show daemon status |
+| `conductor daemon-stop [--all]` | Stop this session's daemon (`--all` = every session) |
+| `conductor device-pool --list` | List devices + pool status |
+| `conductor device-pool --acquire` | Claim a free device (prints id) |
+| `conductor device-pool --release <id>` | Release a device back to the pool |
+
+Don't leave a daemon running when you're done — `daemon-stop` it.
+
+## Tips
+
+- `--device <id>` / `--device-name <name>` targets a device; `--platform` scopes by platform.
+- Add `--json` for machine-readable output.
+- `conductor <command> --help` for exact flags.

package/skills/conductor-inspect/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: conductor-inspect
+description: Read the live UI state of a running app with the conductor CLI — view hierarchy, accessibility snapshot, screenshots, focused element, and element refs. Use when you need to see what's on screen, find an element's id/text/coordinates, take a screenshot, check focus, or assert that something is (or isn't) visible before or after acting.
+---
+
+# Conductor — inspection & assertions
+
+These commands let you **observe** a running app's screen so you know what to do
+next. Pair them with `conductor-device-interact`, which acts on what you find
+here. Always observe before you act, and confirm after.
+
+## Observe the screen
+
+| Command | Purpose |
+|---|---|
+| `conductor capture-ui [--output <path.json>]` | Screenshot + hierarchy + a11y snapshot in one JSON bundle; assigns short `@eN` refs. **Preferred way to observe.** |
+| `conductor inspect [--dump]` | Print the UI hierarchy (`--dump` = raw driver output) |
+| `conductor inspect --at <x,y> [--tappable]` | Topmost view at a screen point |
+| `conductor focused [--poll [ms]]` | Metadata of the focused element. `--poll` watches changes — only with a bounded use, then stop it |
+| `conductor take-screenshot [<element>] [--output <path>] [--full-page]` | Screenshot; crop to a matched element; `--full-page` (web) |
+
+`capture-ui` is the workhorse: it returns the screen as structured data **and**
+gives each element a ref like `@e3` that `conductor tap-on @e3` taps by cached
+coordinates. Refs are ephemeral (~60s) — re-capture after navigating or waiting.
+
+```bash
+conductor capture-ui --output /tmp/screen.json
+# read it: element texts, ids, frames, and @eN refs
+conductor tap-on @e5
+```
+
+## Assertions
+
+| Command | Purpose |
+|---|---|
+| `conductor assert-visible <element> [--timeout ms]` | Assert element is visible (non-zero exit on failure) |
+| `conductor assert-not-visible <element> [--timeout ms]` | Assert element is absent |
+
+Both take the same selectors as `tap-on`: `--id`, `--text`, `--index`,
+`--below` / `--above` / `--left-of` / `--right-of`, `--focused`, `--enabled`,
+`--checked`, `--selected`, `--optional`.
+
+## Tips
+
+- Add `--json` to parse output programmatically (pipe through `jq`).
+- When an interaction can't find an element, `inspect` / `capture-ui` shows the
+  real ids and texts on screen — don't guess selectors.
+- `conductor <command> --help` for exact flags.

package/skills/conductor-metro-debugger/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: conductor-metro-debugger
+description: Inspect a running app's JS runtime, logs, and network with the conductor CLI — evaluate JS in React Native (Hermes) or the web page, dump the React component tree, read console/Metro/device logs, and inspect or issue HTTP requests. Use when debugging app behavior, reading logs, evaluating expressions in the live runtime, inspecting React components, or examining network traffic.
+---
+
+# Conductor — runtime debugging, logs & network
+
+Inspect what a running app is doing under the UI — its JS runtime, console
+output, and HTTP traffic. Works against React Native (Hermes/Fusebox) and
+Playwright web.
+
+## Runtime (React Native / web)
+
+| Command | Purpose |
+|---|---|
+| `conductor debug status [--port N]` | RN debugger connection info |
+| `conductor debug evaluate <expr> [--port N]` | Run JS in the app runtime (Hermes or web page) |
+| `conductor debug component-tree [--port N]` | On-screen React component tree |
+| `conductor debug inspect-element <x,y>` | React component at a screen point |
+| `conductor debug log-registry [--source metro]` | Summarize recent Metro/Hermes console logs |
+
+## Logs
+
+| Command | Purpose |
+|---|---|
+| `conductor logs --recent <n>` | Last N buffered log lines — **agent-friendly, exits immediately** |
+| `conductor logs [--source metro\|device] [--level …] [--json] [--duration s]` | Stream logs (bound it with `--duration`) |
+| `conductor logs --list` | List Metro debugger targets for this device |
+
+Prefer `logs --recent N` over a bare `logs` stream — don't leave a stream
+running indefinitely.
+
+## Network
+
+| Command | Purpose |
+|---|---|
+| `conductor network logs [--limit N]` | Recent HTTP traffic (RN fetch/XHR shim; web via Playwright) |
+| `conductor network request <url> [--method M] [--body STR] [--header K=V]` | Issue an HTTP request from the app's context |
+
+## Metro bundler
+
+| Command | Purpose |
+|---|---|
+| `conductor metro reload [--port N] [--target N]` | Reload the JS bundle without restarting native |
+| `conductor metro stop [--port N]` | Stop the Metro bundler on a port (default 8081) |
+
+## Tips
+
+- `--port N` targets a specific Metro/debugger port when auto-detection isn't enough.
+- Add `--json` for machine-readable output.
+- For crashes and performance, see `conductor-profiler`.

package/skills/conductor-profiler/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: conductor-profiler
+description: Profile a running app's CPU, memory, and React render performance with the conductor CLI, and read crash reports. Use when investigating slowness, jank, memory growth or leaks, excessive React re-renders, or when an app has crashed and you need the crash report.
+---
+
+# Conductor — profiling & crashes
+
+Measure a running app's performance and inspect crashes.
+
+## Profiling
+
+| Command | Purpose |
+|---|---|
+| `conductor profile cpu --duration <s> [--out <path>]` | Record a CPU trace (iOS: xctrace, Android: simpleperf) |
+| `conductor profile memory --track <s> [--interval ms] [<appId>]` | Sample memory for N seconds, report deltas |
+| `conductor profile react start` / `profile react stop [--top N]` | Install a React commit-profiler hook, then summarize captured commits |
+
+## Memory
+
+| Command | Purpose |
+|---|---|
+| `conductor memory [<appId>]` | Device + app memory usage |
+| `conductor memory --objects` | Include per-class object counts (iOS heap; slower) |
+| `conductor memory --leaks` | Run leak detection (iOS only; slow, can pause the app) |
+| `conductor memory --save <name>` / `--diff <name>` / `--diff <name> --vs <other>` | Snapshot and diff memory reports |
+| `conductor memory --filter <regex>` / `--growth-only` / `--top <n>` | Narrow object/class tables (great for leak-hunting) |
+
+Typical leak hunt: `memory --save before`, exercise the screen, then
+`memory --diff before --growth-only`.
+
+## Crashes
+
+| Command | Purpose |
+|---|---|
+| `conductor crashes list [--app <bundleId>] [--since <duration>]` | List recent crash reports (iOS host + Android logcat) |
+| `conductor crashes show <id>` | Print a specific crash report |
+| `conductor crashes tail` | Stream new crash reports as they appear |
+
+## Tips
+
+- Add `--json` to parse reports programmatically.
+- These commands can be slow or pause the app — scope them with `--duration` / `--track` and avoid leaving `crashes tail` running.