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

cmd/sanderling/doctor.go

@@ -14,6 +14,8 @@ import (
 
 	"github.com/chromedp/chromedp"
 
+	"github.com/priyanshujain/sanderling/internal/driver/ioscompanion"
+	"github.com/priyanshujain/sanderling/internal/ios"
 	"github.com/priyanshujain/sanderling/internal/sidecarassets"
 )
 
@@ -59,8 +61,9 @@ func androidChecks() []doctorCheck {
 
 // iosChecks covers the simulator path, which the native companion drives with
 // no JVM. A simulator host with no Java still passes. Physical-device runs
-// additionally need java and the sidecar JAR, covered by iosDeviceChecks and
-// surfaced through the "all" union.
+// additionally need devicectl, the usbmuxd socket, a connected device, and
+// signing credentials, covered by iosDeviceChecks and surfaced through the
+// "all" union.
 func iosChecks() []doctorCheck {
 	return []doctorCheck{
 		{Name: "xcrun on PATH (ios simulator)", Run: checkExecutableOnPath("xcrun")},
@@ -68,12 +71,18 @@ func iosChecks() []doctorCheck {
 	}
 }
 
-// iosDeviceChecks covers the extra prerequisites a physical iOS device needs:
-// the JVM and a real sidecar JAR for the sidecar driver path.
+// iosDeviceChecks covers the prerequisites a physical iOS device needs: the
+// runner is built and driven over a native usbmux tunnel, so devicectl installs
+// the app, the macOS usbmuxd socket carries the tunnel, a device must be
+// connected and paired, and App Store Connect signing credentials must be
+// present for the no-UI build. Everything here is part of macOS + Xcode; nothing
+// is installed.
 func iosDeviceChecks() []doctorCheck {
 	return []doctorCheck{
-		{Name: "java 17+ on PATH (ios physical device)", Run: checkJavaVersion},
-		{Name: "sidecar JAR is real (ios physical device)", Run: checkSidecarJAR},
+		{Name: "devicectl available (ios physical device)", Run: checkDevicectl},
+		{Name: "usbmuxd socket present (ios physical device)", Run: checkUsbmuxd},
+		{Name: "an iOS device is connected and paired", Run: checkDeviceConnected},
+		{Name: "App Store Connect signing credentials present", Run: checkDeviceSigning},
 	}
 }
 
@@ -120,6 +129,48 @@ func checkSimctl(ctx context.Context) error {
 	return nil
 }
 
+// Device-check seams: package-level so the doctor's device checks run against
+// canned results instead of a real device.
+var (
+	doctorConnectedDevices = ios.ConnectedDevices
+	doctorVerifySigning    = ioscompanion.VerifyDeviceSigning
+	doctorVerifyUsbmuxd    = ioscompanion.VerifyUsbmuxdSocket
+)
+
+// checkDevicectl exercises `xcrun devicectl --version`: devicectl is an xcrun
+// subcommand, so a PATH lookup cannot find it.
+func checkDevicectl(ctx context.Context) error {
+	if err := exec.CommandContext(ctx, "xcrun", "devicectl", "--version").Run(); err != nil {
+		return fmt.Errorf("xcrun devicectl --version: %w", err)
+	}
+	return nil
+}
+
+// checkUsbmuxd confirms the macOS usbmuxd socket is present: the native device
+// tunnel speaks to it directly instead of shelling out to a third-party client.
+func checkUsbmuxd(_ context.Context) error {
+	return doctorVerifyUsbmuxd()
+}
+
+// checkDeviceConnected confirms at least one physical iOS device is connected
+// and paired, the prerequisite for the tunnel and the install.
+func checkDeviceConnected(ctx context.Context) error {
+	devices, err := doctorConnectedDevices(ctx)
+	if err != nil {
+		return err
+	}
+	if len(devices) == 0 {
+		return fmt.Errorf("no connected iOS device; connect and pair an iPhone")
+	}
+	return nil
+}
+
+// checkDeviceSigning confirms the App Store Connect signing environment is
+// complete and the key file exists, so the no-UI device build can sign.
+func checkDeviceSigning(_ context.Context) error {
+	return doctorVerifySigning()
+}
+
 func checkSidecarJAR(_ context.Context) error {
 	if sidecarassets.IsPlaceholder() {
 		return fmt.Errorf("placeholder JAR embedded; run `make sidecar && make sanderling` to embed the real fat JAR")

cmd/sanderling/doctor_test.go

@@ -8,6 +8,8 @@ import (
 	"io"
 	"strings"
 	"testing"
+
+	"github.com/priyanshujain/sanderling/internal/ios"
 )
 
 func TestRunDoctorChecks_AllPass(t *testing.T) {
@@ -142,15 +144,58 @@ func TestDoctorChecksFor_iOSSimulator_OmitsJava(t *testing.T) {
 	}
 }
 
-func TestDoctorChecksFor_iOSDevice_IncludesJava(t *testing.T) {
-	found := false
-	for _, c := range doctorChecksFor("ios-device") {
-		if strings.Contains(c.Name, "java") {
-			found = true
+func TestDoctorChecksFor_iOSDevice_CoversDevicePrereqs(t *testing.T) {
+	checks := doctorChecksFor("ios-device")
+	for _, c := range checks {
+		if strings.Contains(c.Name, "java") || strings.Contains(c.Name, "sidecar") {
+			t.Errorf("device checks must not include the retired %q", c.Name)
 		}
 	}
-	if !found {
-		t.Error("ios-device checks must include java for the sidecar path")
+	for _, want := range []string{"devicectl", "usbmuxd", "connected and paired", "signing credentials"} {
+		found := false
+		for _, c := range checks {
+			if strings.Contains(c.Name, want) {
+				found = true
+			}
+		}
+		if !found {
+			t.Errorf("ios-device checks missing %q: %+v", want, checks)
+		}
+	}
+}
+
+func TestCheckDeviceConnected(t *testing.T) {
+	original := doctorConnectedDevices
+	t.Cleanup(func() { doctorConnectedDevices = original })
+
+	doctorConnectedDevices = func(context.Context) ([]ios.Device, error) {
+		return []ios.Device{{Name: "iPhone"}}, nil
+	}
+	if err := checkDeviceConnected(context.Background()); err != nil {
+		t.Fatalf("a connected device must pass: %v", err)
+	}
+
+	doctorConnectedDevices = func(context.Context) ([]ios.Device, error) { return nil, nil }
+	if err := checkDeviceConnected(context.Background()); err == nil {
+		t.Fatal("no device must fail")
+	}
+}
+
+func TestCheckDeviceSigning_SurfacesSeamResult(t *testing.T) {
+	// checkDeviceSigning is a passthrough to the driver's credential check; the
+	// credential logic itself is covered by TestReadSigningCredentials* in the
+	// ioscompanion package. Here we only confirm the wiring through the seam.
+	original := doctorVerifySigning
+	t.Cleanup(func() { doctorVerifySigning = original })
+
+	doctorVerifySigning = func() error { return nil }
+	if err := checkDeviceSigning(context.Background()); err != nil {
+		t.Fatalf("a passing signing check must surface nil: %v", err)
+	}
+
+	doctorVerifySigning = func() error { return errors.New("missing credentials") }
+	if err := checkDeviceSigning(context.Background()); err == nil {
+		t.Fatal("a failing signing check must surface the error")
 	}
 }
 

cmd/sanderling/main.go

@@ -52,8 +52,8 @@ func parseTestArgs(args []string, stderr io.Writer) (testOptions, error) {
 	flagSet.StringVar(&options.bundleID, "bundle-id", "", "target app bundle ID (required)")
 	flagSet.StringVar(&options.platform, "platform", "android", "target platform: android, ios, web")
 	flagSet.StringVar(&options.avd, "avd", "", "Android AVD name to boot if no device is connected")
-	flagSet.StringVar(&options.iosDevice, "ios-device", "", "iOS simulator name or UDID to boot if none is running")
-	flagSet.StringVar(&options.iosAppPath, "ios-app-path", "", "path to the .app bundle for iOS simulator clear-state reinstall")
+	flagSet.StringVar(&options.iosDevice, "ios-device", "", "iOS target: a simulator name/UDID to boot, or a connected device's name, UDID, or CoreDevice id")
+	flagSet.StringVar(&options.iosAppPath, "ios-app-path", "", "path to the .app bundle for iOS clear-state reinstall (simulator: simctl; device: devicectl)")
 	flagSet.DurationVar(&options.duration, "duration", 5*time.Minute, "total test duration")
 	flagSet.Int64Var(&options.seed, "seed", 0, "RNG seed (0 = random)")
 	flagSet.StringVar(&options.output, "output", "./runs", "output directory for traces")