@spec build_simctl_env(
  keyword(),
  String.t()
) :: [{String.t(), String.t()}]

Builds the SIMCTL_CHILD_* env-var list launch_app/3 passes to simctl. Extracted as a pure function so the override behaviour can be unit-tested without spawning subprocesses.

Always emits:

• SIMCTL_CHILD_MOB_DIST_PORT — :dist_port opt, default 9100
• SIMCTL_CHILD_MOB_SIM_RUNTIME_DIR — runtime_dir arg

Conditionally emits:

• SIMCTL_CHILD_MOB_NODE_SUFFIX — only when :node_suffix is a non-empty string. nil / "" → mob_beam.m auto-derives from SIMULATOR_UDID.

@spec devicectl_ipv4_addresses() :: [String.t()]

Returns the IPv4 addresses every connected physical device is known to reach Mac at, derived from xcrun devicectl list devices --json-output. Sources, in order:

1. connectionProperties.tunnelIPAddress if it's an IPv4 (CoreDevice USB tunnel; sometimes IPv6, which Erlang dist doesn't speak)
2. connectionProperties.localHostnames resolved via :inet.gethostbyname/1 (mDNS hostnames like Kevins-iPhone.coredevice.local, which usually resolve to the device's WiFi IPv4)

Returns [] if xcrun isn't installed, the JSON parse fails, or no device has any IPv4. Pure of side effects beyond the temp file used to capture devicectl's JSON output.

@spec enable_accessibility(String.t()) :: :ok

Enables the iOS accessibility system for the given simulator (or "booted").

SwiftUI lazily populates its accessibility tree only when an accessibility service is active. pegleg_nif:ui_tree/0 requires this to be called once per simulator session before it can return elements. Writes the VoiceOver preference into the simulator's preference store and posts the Darwin notification that UIKit listens to.

Safe to call repeatedly — idempotent.

@spec find_physical_at(String.t()) :: MobDev.Device.t() | nil

Queries EPMD at a specific IP for any *_ios node and returns a Device, or nil if no iOS BEAM node is reachable there. Used for direct connection when the IP is already known (e.g. from xcrun devicectl) and ARP may not be warm.

@spec launch_app(String.t(), String.t(), keyword()) :: {String.t(), non_neg_integer()}

Launches the app on a booted simulator.

Passes env vars through to the simulator app via simctl's SIMCTL_CHILD_* mechanism (the prefix is stripped before delivery to the child process):

• MOB_DIST_PORT — Erlang dist listen port
• MOB_NODE_SUFFIX — appended to the BEAM node name. When absent, mob_beam.m falls back to deriving a suffix from SIMULATOR_UDID so concurrent sims still get unique names.
• MOB_SIM_RUNTIME_DIR — directory the OTP runtime was written to; mob_beam.m reads from the same place ios/build.sh wrote.

Options:

• :dist_port — pin the dist listen port (default 9100).
• :node_suffix — override the BEAM node-name suffix. nil lets mob_beam.m auto-derive from SIMULATOR_UDID.

@spec list_devices() :: [MobDev.Device.t()]

Returns all iOS devices (simulators + physical).

@spec list_physical() :: [MobDev.Device.t()]

Returns connected physical iOS devices.

Always runs both USB discovery (ideviceinfo) and a LAN EPMD scan in parallel. The LAN scan finds the device's actual node IP (which is WiFi-first since mob_beam.m prefers a stable LAN address). The USB scan provides the UDID and device name. Results are merged: one device with the correct WiFi IP and full USB metadata.

If only one path finds the device, that result is used directly — so this works on USB-only setups and WiFi-only setups equally. When USB finds a device but LAN scan doesn't (cold ARP, rapid app launch, etc.), the result is enriched via xcrun devicectl — we ask for the device's known hostnames + tunnel IPs, resolve to IPv4, and probe each with EPMD. Single TCP probe per candidate, so it costs ~50 ms in the success case and doesn't slow down the no-iOS path.

@spec list_simulators() :: [MobDev.Device.t()]

Returns booted iOS simulators.

@spec parse_runtime_version(String.t()) :: String.t()

Parses a CoreSimulator runtime key into a human-readable version string. Exposed for testing.

@spec parse_simctl_json(String.t()) :: [MobDev.Device.t()]

Parses the JSON output of xcrun simctl list devices booted --json. Exposed for testing.

@spec parse_simctl_text(String.t()) :: [MobDev.Device.t()]

Parses the plain-text output of xcrun simctl list devices booted. Exposed for testing.

@spec restart_app_physical(String.t(), String.t()) :: {String.t(), non_neg_integer()}

Restarts the app on a physical iOS device via xcrun devicectl. Kills any other user-installed app first (they all share EPMD port 4369 and only one can run at a time), then launches the target app fresh.