Physical-device iOS support (#64) (#66)

* feat(companion): add appState, eraseText, pressKey runner handlers

The Go runner transport already calls these methods; the in-device runner
implemented them only latently. They become load-bearing on the device
path, where the hybrid's legacy-companion fallback is absent. Backward
compatible: the simulator hybrid never calls them.

* feat(ios): resolve physical devices from devicectl

ResolveDevice parses xcrun devicectl list devices into Device{Name,
HardwareUDID, CoreDeviceID}: the hardware UDID feeds xcodebuild/iproxy
and the CoreDevice id feeds devicectl install. Matches by name or either
id; errors list candidates on none/ambiguous. Fixes the stale sidecar
comment on ResolveTarget.

* feat(ioscompanion): runner-only device driver mode

NewDevice reuses Driver with d.companion set to the runner dialed over an
iproxy usbmux tunnel, hybrid=false, runnerClient=nil. The existing accessor
seams then route launch/snapshot/text/gesture to the runner with no new
DeviceDriver methods. Device seams swap clear-state to a devicectl
reinstall, container reset to a warn-once no-op, and paste grant to a no-op.
realSpawnDeviceRunner builds and signs the runner at run time via the App
Store Connect API key (no Xcode UI), caching on a source hash.

* test(ioscompanion): cover device wiring, routing, and shell-out argv

Seam-driven NewDevice wiring + gesture/text routing (asserting no keyboard
HID), devicectl/build/test/iproxy argv builders, xctestrun test-target dict
name parsing, signing-credential env checks, and source-hash cache keying.

* feat(testrun): route physical-device iOS runs to the device driver

Execute resolves a non-simulator iOS target through ios.ResolveDevice into
its hardware UDID and CoreDevice id; buildDriver constructs NewDevice via a
seam instead of rejecting the device. Generalizes the --ios-device and
--ios-app-path help to cover the device path; signing stays env-read, never
a flag.

* feat(doctor): device prereqs replace java/sidecar for ios-device

iosDeviceChecks now verifies devicectl, iproxy on PATH, a connected+paired
device (via ios.ConnectedDevices), and App Store Connect signing creds (via
ioscompanion.VerifyDeviceSigning). The retired JVM sidecar checks stay only
under android.

* feat(conformance): device backend uses iphoneos app and tunnel orphan checks

The device backend now builds via just ios-device, points --ios-app-path at
the Debug-iphoneos bundle, and reinstalls each run for clear-state. The G5
orphan scan replaces the retired sidecar.jar check with lingering iproxy and
device test-without-building sessions (destination platform=iOS,id=).

* feat(folio): device build linking the iosArm64 framework

project.yml selects the Kotlin framework slice by SDK (iosArm64 for
iphoneos, iosSimulatorArm64 for simulator) and links via -framework Shared
on the SDK-conditional search path. New ios-device/test-ios-device recipes
mirror ios/test-ios, signing the Debug-iphoneos build with the .env API key.

* docs(cli): document ios-device doctor checks and the device flags

The --ios-device flag now also selects a connected device; --ios-app-path
covers the device install; the doctor gains an ios-device platform whose
checks are devicectl, iproxy, a paired device, and signing credentials.
Corrects the --clear-data default to true.

* fix(ioscompanion): resolve signing key path to absolute

xcodebuild's -authenticationKeyPath requires an absolute path, but .env
files commonly carry a repo-relative one. Resolve it against the working
directory before the stat so a relative ASC_API_KEY_PATH still signs.

* fix(ioscompanion): re-enable signing for the device runner build

companion/project.yml disables code signing for the simulator build, so
the device build inherited it and produced an unsigned runner that the
device rejected at install (0xe8008018). build-for-testing now forces
CODE_SIGNING_ALLOWED/REQUIRED=YES so automatic provisioning signs it.

* fix(ioscompanion): key the device build cache on signing identity

The cache marker hashed only sources, so switching signing team or key
reused a runner signed with the stale identity, which the device rejects at
install (0xe8008018). Fold team + key id into the cache key so a signing
change forces a rebuild.

* docs(getting-started): document physical iOS device setup

Lists the iproxy requirement and the App Store Connect signing env vars
(SANDERLING_IOS_TEAM, ASC_API_*) a device run needs, plus the
test-ios-device recipe and the doctor check.

* feat(ios): native usbmux client and in-process tunnel forwarder

Talk to macOS usbmuxd directly instead of shelling out to iproxy, so the
device path depends on nothing beyond macOS + Xcode.

* refactor(ios): drive device tunnel via io.Closer seam

Replace the tunnelChild *exec.Cmd and spawnTunnel seam with a tunnel
io.Closer and startTunnel seam backed by the in-process usbmux forwarder.

* refactor(ios): remove iproxy spawn from device runner

* test(ios): cover tunnel close via io.Closer not child process

* feat(doctor): check usbmuxd socket instead of iproxy on PATH

* chore(conformance): drop iproxy orphan check; tunnel is in-process

* docs(ios): device tunnel uses native usbmux, nothing to install

* chore: gitignore the signing keys directory

* feat(folio): add Android launcher icon (black bg, white dot)

* feat(folio): add iOS app icon (black bg, white dot)

* feat(folio): add web favicon (black bg, white dot)

* docs(ioscompanion): fix stale const comments

* refactor(ioscompanion): inline single-use devicectl argv builders

* refactor(ioscompanion): inline xcodegenArgs, drop tautological argv tests

* refactor(ioscompanion): inline firstNonEmpty

* refactor(doctor): dedup usbmuxd socket path via ioscompanion seam

* test(doctor): trim redundant signing-check test

* refactor(ioscompanion): deliver COMPANION_PORT via TEST_RUNNER_ env

* fix(testrun): seam preflight so iOS routing tests pass on CI without xcrun

internal/testrun/driver.go

@@ -16,16 +16,81 @@ import (
 	"github.com/priyanshujain/sanderling/internal/driver/chrome"
 	"github.com/priyanshujain/sanderling/internal/driver/ioscompanion"
 	driverSidecar "github.com/priyanshujain/sanderling/internal/driver/sidecar"
+	"github.com/priyanshujain/sanderling/internal/ios"
 	"github.com/priyanshujain/sanderling/internal/sidecarassets"
 )
 
+// iOS resolution seams: package-level so routing tests substitute canned
+// resolvers instead of shelling out to xcrun.
+var (
+	iosResolveTarget   = ios.ResolveTarget
+	iosResolveDevice   = ios.ResolveDevice
+	iosEnsureSimulator = ios.EnsureSimulator
+)
+
+// resolveIOSTarget decides whether a run drives a simulator or a physical
+// device and fills the iOS fields on Options. A simulator target is booted if
+// needed; a physical-device target is resolved to its hardware UDID and
+// CoreDevice id via devicectl.
+func resolveIOSTarget(ctx context.Context, options Options, stdout io.Writer) (Options, error) {
+	udid, isSimulator, err := iosResolveTarget(ctx, options.IosDevice)
+	if err != nil {
+		// No query and nothing booted: keep boot-first behavior, then resolve
+		// the simulator that EnsureSimulator just brought up.
+		if options.IosDevice == "" {
+			if bootErr := iosEnsureSimulator(ctx, "", stdout); bootErr != nil {
+				return options, bootErr
+			}
+			udid, isSimulator, err = iosResolveTarget(ctx, "")
+		}
+		if err != nil {
+			return options, err
+		}
+	} else if isSimulator {
+		if err := iosEnsureSimulator(ctx, options.IosDevice, stdout); err != nil {
+			return options, err
+		}
+		udid, isSimulator, err = iosResolveTarget(ctx, options.IosDevice)
+		if err != nil {
+			return options, err
+		}
+	}
+	options.iosUDID = udid
+	options.iosIsSimulator = isSimulator
+	if !isSimulator {
+		device, err := iosResolveDevice(ctx, options.IosDevice)
+		if err != nil {
+			return options, err
+		}
+		options.iosUDID = device.HardwareUDID
+		options.iosCoreDeviceID = device.CoreDeviceID
+		fmt.Fprintf(stdout, "using device: %s (udid %s, id %s)\n", device.Name, device.HardwareUDID, device.CoreDeviceID)
+	}
+	return options, nil
+}
+
+// preflight is a seam so routing tests exercise driver construction without the
+// host-readiness checks (xcrun, java) that are absent on a Linux CI runner.
+var preflight = Preflight
+
+// newDeviceDriver constructs the physical-device iOS driver and its cleanup. A
+// seam so routing tests assert the resolved identifiers reach DeviceOptions
+// without building or spawning a real runner.
+var newDeviceDriver = func(ctx context.Context, options ioscompanion.DeviceOptions) (driver.DeviceDriver, func(), error) {
+	d, err := ioscompanion.NewDevice(ctx, options)
+	if err != nil {
+		return nil, nil, err
+	}
+	return d, d.Close, nil
+}
+
 // buildDriver creates the appropriate DeviceDriver for the platform and returns
 // a cleanup function. For web, ChromeDriver is used directly. An iOS simulator
-// is driven by the native simulator companion (no JVM). Android uses the JVM
-// sidecar, which is extracted, spawned, and dialed. Physical iOS devices are
-// not yet supported.
+// is driven by the native simulator companion (no JVM). A physical iOS device
+// is driven runner-only over a usbmux tunnel. Android uses the JVM sidecar,
+// which is extracted, spawned, and dialed.
 func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver.DeviceDriver, func(), error) {
-	if err := Preflight(ctx, options.Platform); err != nil {
+	if err := preflight(ctx, options.Platform); err != nil {
 		return nil, nil, err
 	}
 	if options.Platform == "web" {
@@ -47,7 +112,17 @@ func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver
 	}
 
 	if options.Platform == "ios" {
-		return nil, nil, fmt.Errorf("physical-device iOS is not yet supported; run against a simulator instead")
+		d, cleanup, err := newDeviceDriver(ctx, ioscompanion.DeviceOptions{
+			HardwareUDID: options.iosUDID,
+			CoreDeviceID: options.iosCoreDeviceID,
+			BundleID:     options.BundleID,
+			AppPath:      options.IosAppPath,
+			Output:       stdout,
+		})
+		if err != nil {
+			return nil, nil, fmt.Errorf("ios device driver: %w", err)
+		}
+		return d, cleanup, nil
 	}
 
 	// Android uses the JVM sidecar, which requires java.

internal/testrun/driver_test.go

@@ -2,27 +2,150 @@ package testrun
 
 import (
 	"context"
+	"errors"
 	"io"
-	"os/exec"
-	"strings"
 	"testing"
+
+	"github.com/priyanshujain/sanderling/internal/driver"
+	"github.com/priyanshujain/sanderling/internal/driver/ioscompanion"
+	"github.com/priyanshujain/sanderling/internal/ios"
 )
 
-func TestBuildDriverRejectsPhysicalIOS(t *testing.T) {
-	if _, err := exec.LookPath("xcrun"); err != nil {
-		t.Skip("xcrun not on PATH; physical-iOS rejection is reached only after preflight")
+// stubDeviceDriver is a no-op DeviceDriver so routing tests never build or spawn
+// a real runner. Only construction wiring is under test.
+type stubDeviceDriver struct{ driver.DeviceDriver }
+
+func TestBuildDriverRoutesPhysicalIOSToDeviceDriver(t *testing.T) {
+	stubPreflight(t)
+	original := newDeviceDriver
+	t.Cleanup(func() { newDeviceDriver = original })
+
+	var got ioscompanion.DeviceOptions
+	closed := false
+	newDeviceDriver = func(_ context.Context, options ioscompanion.DeviceOptions) (driver.DeviceDriver, func(), error) {
+		got = options
+		return stubDeviceDriver{}, func() { closed = true }, nil
+	}
+
+	options := Options{Platform: "ios", BundleID: "app.folio", IosAppPath: "/tmp/iosApp.app"}
+	options.iosIsSimulator = false
+	options.iosUDID = "00008140-HW"
+	options.iosCoreDeviceID = "CORE-1"
+
+	d, cleanup, err := buildDriver(context.Background(), options, io.Discard)
+	if err != nil {
+		t.Fatalf("buildDriver: %v", err)
+	}
+	if d == nil {
+		t.Fatal("expected a device driver")
+	}
+	if got.HardwareUDID != "00008140-HW" || got.CoreDeviceID != "CORE-1" {
+		t.Fatalf("DeviceOptions ids = %+v, want the resolved hardware/core ids", got)
+	}
+	if got.BundleID != "app.folio" || got.AppPath != "/tmp/iosApp.app" {
+		t.Fatalf("DeviceOptions = %+v, want bundle and app path threaded through", got)
+	}
+	cleanup()
+	if !closed {
+		t.Fatal("cleanup must close the device driver")
+	}
+}
+
+func TestBuildDriverSurfacesDeviceConstructionError(t *testing.T) {
+	stubPreflight(t)
+	original := newDeviceDriver
+	t.Cleanup(func() { newDeviceDriver = original })
+	newDeviceDriver = func(context.Context, ioscompanion.DeviceOptions) (driver.DeviceDriver, func(), error) {
+		return nil, nil, errors.New("no signing creds")
 	}
 	options := Options{Platform: "ios"}
 	options.iosIsSimulator = false
+	if _, _, err := buildDriver(context.Background(), options, io.Discard); err == nil {
+		t.Fatal("expected the device construction error to surface")
+	}
+}
+
+// stubPreflight bypasses the host-readiness checks so routing tests exercise
+// driver construction on a Linux CI runner that lacks xcrun/java.
+func stubPreflight(t *testing.T) {
+	t.Helper()
+	original := preflight
+	t.Cleanup(func() { preflight = original })
+	preflight = func(context.Context, string) error { return nil }
+}
+
+func swapIOSResolveSeams(t *testing.T) {
+	t.Helper()
+	origTarget, origDevice, origEnsure := iosResolveTarget, iosResolveDevice, iosEnsureSimulator
+	t.Cleanup(func() {
+		iosResolveTarget, iosResolveDevice, iosEnsureSimulator = origTarget, origDevice, origEnsure
+	})
+}
+
+func TestResolveIOSTargetPhysicalDeviceFillsIDs(t *testing.T) {
+	swapIOSResolveSeams(t)
+	iosResolveTarget = func(_ context.Context, query string) (string, bool, error) {
+		return query, false, nil
+	}
+	resolveDeviceCalled := ""
+	iosResolveDevice = func(_ context.Context, query string) (ios.Device, error) {
+		resolveDeviceCalled = query
+		return ios.Device{Name: "iPhone", HardwareUDID: "00008140-HW", CoreDeviceID: "CORE-1"}, nil
+	}
+	iosEnsureSimulator = func(context.Context, string, io.Writer) error {
+		t.Fatal("must not boot a simulator on the device path")
+		return nil
+	}
+
+	options := Options{Platform: "ios", IosDevice: "iPhone"}
+	resolved, err := resolveIOSTarget(context.Background(), options, io.Discard)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolveDeviceCalled != "iPhone" {
+		t.Fatalf("ResolveDevice query = %q, want iPhone", resolveDeviceCalled)
+	}
+	if resolved.iosIsSimulator {
+		t.Fatal("device target must not be marked a simulator")
+	}
+	if resolved.iosUDID != "00008140-HW" || resolved.iosCoreDeviceID != "CORE-1" {
+		t.Fatalf("resolved ids = (%q, %q), want hardware/core ids", resolved.iosUDID, resolved.iosCoreDeviceID)
+	}
+}
 
-	_, cleanup, err := buildDriver(context.Background(), options, io.Discard)
-	if cleanup != nil {
-		cleanup()
+func TestResolveIOSTargetSimulatorSkipsDeviceResolution(t *testing.T) {
+	swapIOSResolveSeams(t)
+	iosResolveTarget = func(context.Context, string) (string, bool, error) {
+		return "sim-udid", true, nil
 	}
-	if err == nil {
-		t.Fatal("expected physical-device iOS to be rejected")
+	ensured := false
+	iosEnsureSimulator = func(context.Context, string, io.Writer) error { ensured = true; return nil }
+	iosResolveDevice = func(context.Context, string) (ios.Device, error) {
+		t.Fatal("simulator path must not resolve a physical device")
+		return ios.Device{}, nil
+	}
+
+	options := Options{Platform: "ios", IosDevice: "iPhone 17 Pro"}
+	resolved, err := resolveIOSTarget(context.Background(), options, io.Discard)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !ensured {
+		t.Fatal("simulator path must ensure the simulator is booted")
+	}
+	if !resolved.iosIsSimulator || resolved.iosUDID != "sim-udid" {
+		t.Fatalf("resolved = %+v, want the booted simulator", resolved)
+	}
+}
+
+func TestResolveIOSTargetDeviceResolutionErrorSurfaces(t *testing.T) {
+	swapIOSResolveSeams(t)
+	iosResolveTarget = func(_ context.Context, query string) (string, bool, error) { return query, false, nil }
+	iosResolveDevice = func(context.Context, string) (ios.Device, error) {
+		return ios.Device{}, errors.New("no device connected")
 	}
-	if !strings.Contains(err.Error(), "not yet supported") {
-		t.Fatalf("expected an unsupported-physical-iOS error, got %v", err)
+	options := Options{Platform: "ios", IosDevice: "iPhone"}
+	if _, err := resolveIOSTarget(context.Background(), options, io.Discard); err == nil {
+		t.Fatal("expected the device-resolution error to surface")
 	}
 }

internal/testrun/testrun.go

@@ -13,7 +13,6 @@ import (
 	"github.com/priyanshujain/sanderling/internal/android"
 	"github.com/priyanshujain/sanderling/internal/bundler"
 	"github.com/priyanshujain/sanderling/internal/driver"
-	"github.com/priyanshujain/sanderling/internal/ios"
 	"github.com/priyanshujain/sanderling/internal/runner"
 	"github.com/priyanshujain/sanderling/internal/trace"
 	"github.com/priyanshujain/sanderling/internal/verifier"
@@ -34,10 +33,13 @@ type Options struct {
 	Output     string
 	ClearData  bool
 
-	// iosUDID and iosIsSimulator are filled by Execute after resolving the iOS
-	// target, then read by buildDriver to choose the companion or sidecar path.
-	iosUDID        string
-	iosIsSimulator bool
+	// iosUDID, iosIsSimulator, and iosCoreDeviceID are filled by Execute after
+	// resolving the iOS target, then read by buildDriver to choose the simulator
+	// companion or the physical-device driver. On the device path iosUDID is the
+	// hardware UDID and iosCoreDeviceID is the CoreDevice id.
+	iosUDID         string
+	iosIsSimulator  bool
+	iosCoreDeviceID string
 }
 
 // Execute runs the full test pipeline: bundle, launch app, verify properties.
@@ -48,30 +50,11 @@ func Execute(ctx context.Context, options Options, stdout io.Writer) error {
 			return err
 		}
 	case "ios":
-		udid, isSimulator, err := ios.ResolveTarget(ctx, options.IosDevice)
+		resolved, err := resolveIOSTarget(ctx, options, stdout)
 		if err != nil {
-			// No query and nothing booted: keep boot-first behavior, then resolve
-			// the simulator that EnsureSimulator just brought up.
-			if options.IosDevice == "" {
-				if bootErr := ios.EnsureSimulator(ctx, "", stdout); bootErr != nil {
-					return bootErr
-				}
-				udid, isSimulator, err = ios.ResolveTarget(ctx, "")
-			}
-			if err != nil {
-				return err
-			}
-		} else if isSimulator {
-			if err := ios.EnsureSimulator(ctx, options.IosDevice, stdout); err != nil {
-				return err
-			}
-			udid, isSimulator, err = ios.ResolveTarget(ctx, options.IosDevice)
-			if err != nil {
-				return err
-			}
+			return err
 		}
-		options.iosUDID = udid
-		options.iosIsSimulator = isSimulator
+		options = resolved
 	}
 	prep, err := prepareBundleInputs(options)
 	if err != nil {