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/driver/ioscompanion/device_test.go

@@ -0,0 +1,197 @@
+package ioscompanion
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net"
+	"os/exec"
+	"testing"
+
+	"github.com/priyanshujain/sanderling/internal/driver/ioscompanion/transport"
+)
+
+// startLoopbackListener accepts and immediately closes connections so
+// waitForListener succeeds against a real address without a real runner.
+func startLoopbackListener(t *testing.T) string {
+	t.Helper()
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { listener.Close() })
+	go func() {
+		for {
+			conn, acceptErr := listener.Accept()
+			if acceptErr != nil {
+				return
+			}
+			_ = conn.Close()
+		}
+	}()
+	return listener.Addr().String()
+}
+
+func testDeviceOptions(address string, companion transport.Companion) DeviceOptions {
+	return DeviceOptions{
+		HardwareUDID: "00008140-HW",
+		CoreDeviceID: "CORE-1",
+		BundleID:     "com.example.app",
+		Output:       &bytes.Buffer{},
+		spawnRunner:  func(context.Context, string) (*exec.Cmd, error) { return &exec.Cmd{}, nil },
+		startTunnel:  func(context.Context, string, string, string) (io.Closer, error) { return io.NopCloser(nil), nil },
+		dialRunner:   func(string) (transport.Companion, error) { return companion, nil },
+		pickAddress:  func() (string, error) { return address, nil },
+	}
+}
+
+func newDeviceCompanion() *fakeTextEditingCompanion {
+	companion := &fakeTextEditingCompanion{}
+	companion.accessibilityJSON = "[]"
+	companion.describe = transport.ScreenDescription{WidthPoints: 393, HeightPoints: 852}
+	return companion
+}
+
+func TestNewDeviceWiresRunnerOnlyMode(t *testing.T) {
+	address := startLoopbackListener(t)
+	companion := newDeviceCompanion()
+	d, err := NewDevice(context.Background(), testDeviceOptions(address, companion))
+	if err != nil {
+		t.Fatalf("NewDevice: %v", err)
+	}
+	defer d.Close()
+
+	if !d.deviceMode {
+		t.Fatal("deviceMode must be true")
+	}
+	if d.hybrid {
+		t.Fatal("device mode must not be hybrid")
+	}
+	if d.runnerClient != nil {
+		t.Fatal("device mode must leave runnerClient nil so InputText avoids the hybrid HID chord")
+	}
+	if d.companion != companion {
+		t.Fatal("d.companion must be the runner dialed over the tunnel")
+	}
+	if d.coreDeviceID != "CORE-1" {
+		t.Fatalf("coreDeviceID = %q, want CORE-1", d.coreDeviceID)
+	}
+	if d.screenWidth != 393 || d.screenHeight != 852 {
+		t.Fatalf("screen = %dx%d, want 393x852", d.screenWidth, d.screenHeight)
+	}
+}
+
+func TestNewDeviceRequiresIdentifiers(t *testing.T) {
+	if _, err := NewDevice(context.Background(), DeviceOptions{CoreDeviceID: "x"}); err == nil {
+		t.Fatal("missing HardwareUDID must error")
+	}
+	if _, err := NewDevice(context.Background(), DeviceOptions{HardwareUDID: "x"}); err == nil {
+		t.Fatal("missing CoreDeviceID must error")
+	}
+}
+
+func TestDeviceInputTextUsesNativeEditorNotKeyboardHID(t *testing.T) {
+	address := startLoopbackListener(t)
+	companion := newDeviceCompanion()
+	d, err := NewDevice(context.Background(), testDeviceOptions(address, companion))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer d.Close()
+
+	if err := d.InputText(context.Background(), "héllo 🌟"); err != nil {
+		t.Fatal(err)
+	}
+	if len(companion.inputTexts) != 1 || companion.inputTexts[0] != "héllo 🌟" {
+		t.Fatalf("inputTexts = %v, want native replace of the text", companion.inputTexts)
+	}
+	for _, call := range companion.recorded() {
+		if call == "hid" {
+			t.Fatal("device text must go through the native editor, never a keyboard HID chord")
+		}
+	}
+}
+
+func TestDeviceGesturesRouteTouchHIDToRunner(t *testing.T) {
+	address := startLoopbackListener(t)
+	companion := newDeviceCompanion()
+	d, err := NewDevice(context.Background(), testDeviceOptions(address, companion))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer d.Close()
+
+	if err := d.DoubleTap(context.Background(), 10, 20); err != nil {
+		t.Fatal(err)
+	}
+	if indexOf(companion.recorded(), "hid") < 0 {
+		t.Fatalf("gesture must send touch HID to the runner; got %v", companion.recorded())
+	}
+}
+
+func TestDeviceEraseAndPressKeyRouteThroughEditor(t *testing.T) {
+	address := startLoopbackListener(t)
+	companion := newDeviceCompanion()
+	d, err := NewDevice(context.Background(), testDeviceOptions(address, companion))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer d.Close()
+
+	if err := d.EraseText(context.Background(), 4); err != nil {
+		t.Fatal(err)
+	}
+	if err := d.PressKey(context.Background(), "enter"); err != nil {
+		t.Fatal(err)
+	}
+	if len(companion.eraseCounts) != 1 || companion.eraseCounts[0] != 4 {
+		t.Fatalf("eraseCounts = %v, want [4]", companion.eraseCounts)
+	}
+	if len(companion.pressedKeys) != 1 || companion.pressedKeys[0] != "enter" {
+		t.Fatalf("pressedKeys = %v, want [enter]", companion.pressedKeys)
+	}
+}
+
+func TestDeviceClearStateWithoutAppPathWarnsOnce(t *testing.T) {
+	output := &bytes.Buffer{}
+	d := &Driver{output: output, deviceMode: true}
+	d.resetContainer = d.deviceResetContainerUnsupported
+	for i := 0; i < 2; i++ {
+		if err := d.deviceResetContainerUnsupported(context.Background()); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if got := bytes.Count(output.Bytes(), []byte("requires --ios-app-path")); got != 1 {
+		t.Fatalf("warning emitted %d times, want once", got)
+	}
+}
+
+type recordingCloser struct{ closed bool }
+
+func (c *recordingCloser) Close() error {
+	c.closed = true
+	return nil
+}
+
+func TestDeviceCloseStopsRunnerAndTunnel(t *testing.T) {
+	d := &Driver{output: &bytes.Buffer{}}
+	runner := exec.Command("sleep", "30")
+	if err := runner.Start(); err != nil {
+		t.Fatal(err)
+	}
+	tunnel := &recordingCloser{}
+	d.runnerChild = runner
+	d.tunnel = tunnel
+
+	d.Close()
+
+	if d.runnerChild != nil || d.tunnel != nil {
+		t.Fatal("Close must clear the runner child and the tunnel")
+	}
+	if runner.ProcessState == nil {
+		t.Fatal("Close must reap the runner session child")
+	}
+	if !tunnel.closed {
+		t.Fatal("Close must close the usbmux tunnel")
+	}
+}