@astur-mobile/ios 0.1.0-beta.0

package/assets/ios-xctest-agent/HostApp/Info.plist

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>LSRequiresIPhoneOS</key>
+	<true/>
+	<key>UIApplicationSupportsIndirectInputEvents</key>
+	<true/>
+	<key>UILaunchScreen</key>
+	<dict/>
+	<key>UISupportedInterfaceOrientations</key>
+	<array>
+		<string>UIInterfaceOrientationPortrait</string>
+	</array>
+</dict>
+</plist>

package/assets/ios-xctest-agent/README.md

@@ -0,0 +1,74 @@
+# iOS XCUITest Agent
+
+iOS native UI automation must run through XCTest/XCUITest. The iOS agent is
+Astur's Swift device-side automation bridge. It is not an AI agent and it is not
+an Appium/WebDriver server.
+
+The public test API should match Android:
+
+```ts
+await device.getById('login-submit-button').tap();
+await expect(device.getByText('Welcome')).toBeVisible();
+```
+
+The runtime path is:
+
+```text
+Astur locator/action API
+  -> @astur-mobile/core session element methods
+  -> @astur-mobile/ios agent transport
+  -> Swift XCUITest agent
+  -> XCUIApplication / XCUIElement
+```
+
+This directory is the code that makes iOS inspection and native interaction possible. The host-side `@astur-mobile/ios` package can install, launch, and screenshot simulator apps through Xcode tools, but only this XCTest runner can read the iOS accessibility tree and perform native element actions inside Apple's supported automation boundary.
+
+Current command surface:
+
+- `agent.ping`
+- `device.setOrientation`
+- `tree.get`
+- `element.find`
+- `element.findAll`
+- `element.findMany`
+- `element.wait`
+- `element.tap`
+- `element.doubleTap`
+- `element.longPress`
+- `element.fill`
+- `element.drag`
+- `gesture.tap`
+- `gesture.doubleTap`
+- `gesture.longPress`
+- `gesture.swipe`
+- `gesture.drag`
+- `keyboard.state`
+- `keyboard.dismiss`
+
+Current implementation status:
+
+- Swift XCUITest command dispatcher is implemented in `AsturAgent.swift`
+- host-side iOS driver can connect to a provided endpoint or bootstrap the bundled simulator agent
+- reverse HTTP bridge mode is available for simulator execution
+- the bundled simulator agent is started once per Astur worker session, and Xcode DerivedData is reused per simulator id to avoid rebuilding into a fresh temp directory on every run
+- native lookup, wait, tap, double tap, long press, fill, drag, swipe, and keyboard commands run in XCUITest
+- fill replaces existing text inside the agent, using bounded delete input so React Native text fields do not leak state between specs
+- orientation changes run through `XCUIDevice.shared.orientation`
+- lifecycle, install, launch, screenshots, and video remain host-side through Xcode tools
+
+Implementation rules:
+
+- Use XCTest/XCUITest selectors and expectations for native UI control.
+- Do wait, lookup, actionability checks, and the final action inside the agent.
+- Return compact JSON snapshots for diagnostics and assertions.
+- Keep simulator lifecycle in the host driver; keep native element control here.
+- Preserve the public TypeScript API; complexity belongs in this layer.
+
+Astur avoids Appium and WebDriver, but it cannot bypass Apple's XCTest
+requirement for native iOS UI control.
+
+Current platform limits:
+
+- real-device execution still needs signing, provisioning, trusted-device handling, and real-device transport validation
+- system alerts are limited to what XCTest exposes through stable queries
+- direct per-app data/cache clearing is not available through `simctl`; use uninstall/reinstall reset for simulator clean state

package/dist/command.d.ts

@@ -0,0 +1,9 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+export interface CommandResult {
+    stdout: Buffer;
+    stderr: Buffer;
+}
+export declare function run(file: string, args: readonly string[], maxBuffer?: number): Promise<CommandResult>;
+export declare function runText(file: string, args: readonly string[]): Promise<string>;
+export declare function spawnCommand(file: string, args: readonly string[], options?: SpawnOptions): ChildProcess;
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAA0B,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGnH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,SAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAc/G;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpF;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,YAAiB,GAAG,YAAY,CAK5G"}

package/dist/command.js

@@ -0,0 +1,37 @@
+import { execFile, spawn } from 'node:child_process';
+import { AsturError } from '@astur-mobile/core';
+export function run(file, args, maxBuffer = 20 * 1024 * 1024) {
+    return new Promise((resolve, reject) => {
+        execFile(file, [...args], { encoding: 'buffer', maxBuffer }, (error, stdout, stderr) => {
+            if (error) {
+                reject(toCommandError(file, args, error, stdout, stderr));
+                return;
+            }
+            resolve({
+                stdout: Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout ?? ''),
+                stderr: Buffer.isBuffer(stderr) ? stderr : Buffer.from(stderr ?? '')
+            });
+        });
+    });
+}
+export async function runText(file, args) {
+    const result = await run(file, args);
+    return result.stdout.toString('utf8');
+}
+export function spawnCommand(file, args, options = {}) {
+    return spawn(file, [...args], {
+        ...options,
+        stdio: options.stdio ?? 'ignore'
+    });
+}
+function toCommandError(file, args, error, stdout, stderr) {
+    const stdoutText = Buffer.isBuffer(stdout) ? stdout.toString('utf8') : stdout;
+    const stderrText = Buffer.isBuffer(stderr) ? stderr.toString('utf8') : stderr;
+    const message = stderrText.trim() || stdoutText.trim() || error.message;
+    return new AsturError('COMMAND_FAILED', `${file} ${args.join(' ')} failed: ${message}`, {
+        code: error.code,
+        stdout: stdoutText,
+        stderr: stderrText
+    });
+}
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAgE,MAAM,oBAAoB,CAAC;AACnH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAOhD,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,IAAuB,EAAE,SAAS,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI;IACrF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACrF,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;gBAC1D,OAAO;YACT,CAAC;YAED,OAAO,CAAC;gBACN,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;gBACpE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;aACrE,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,IAAuB;IACjE,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,IAAuB,EAAE,UAAwB,EAAE;IAC5F,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;QAC5B,GAAG,OAAO;QACV,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,QAAQ;KACjC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,cAAc,CACrB,IAAY,EACZ,IAAuB,EACvB,KAAwB,EACxB,MAAuB,EACvB,MAAuB;IAEvB,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9E,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9E,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,UAAU,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,OAAO,CAAC;IAExE,OAAO,IAAI,UAAU,CAAC,gBAAgB,EAAE,GAAG,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,OAAO,EAAE,EAAE;QACtF,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,UAAU;QAClB,MAAM,EAAE,UAAU;KACnB,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import type { DeviceInfo, DoctorCheck, NormalizedCapabilities } from '@astur-mobile/protocol';
+import { type PlatformDriver, type PlatformSession } from '@astur-mobile/core';
+export interface IosDriverOptions {
+    xcrunPath?: string;
+    xcodebuildPath?: string;
+}
+interface DevicectlDevicesJson {
+    result?: {
+        devices?: DevicectlDeviceJson[];
+    };
+}
+interface DevicectlDeviceJson {
+    identifier?: string;
+    connectionProperties?: {
+        pairingState?: string;
+        tunnelState?: string;
+        transportType?: string;
+    };
+    deviceProperties?: {
+        bootState?: string;
+        developerModeStatus?: string;
+        name?: string;
+        osVersionNumber?: string;
+    };
+    hardwareProperties?: {
+        marketingName?: string;
+        platform?: string;
+        udid?: string;
+    };
+}
+export declare function createIosDriver(options?: IosDriverOptions): IosDriver;
+export declare class IosDriver implements PlatformDriver {
+    readonly platform: "ios";
+    private readonly xcrunPath;
+    private readonly xcodebuildPath;
+    constructor(options?: IosDriverOptions);
+    doctor(): Promise<DoctorCheck[]>;
+    listDevices(): Promise<DeviceInfo[]>;
+    private listDevicesForSelector;
+    private listSimulators;
+    private listConnectedDevices;
+    createSession(capabilities: NormalizedCapabilities): Promise<PlatformSession>;
+    private ensureDeviceReady;
+    private resolveNativeAgent;
+    private tryBootstrapBundledNativeAgent;
+}
+export declare function iosAgentDerivedDataRoot(): string;
+/**
+ * Removes the managed XCUITest agent DerivedData directories left behind by
+ * previous agent source versions for a device, keeping only the current build
+ * (`keepPath`). Without this, every change to the bundled Swift agent — and each
+ * source-stamp it produces — leaves a full Xcode build behind, and they
+ * accumulate until the disk fills. Other devices' builds are left untouched.
+ * Best-effort: never throws.
+ */
+export declare function pruneStaleIosAgentDerivedData(deviceId: string, keepPath: string, root?: string): Promise<void>;
+export declare function parseSimctlDevices(output: string): DeviceInfo[];
+export declare function parseXcdeviceDevices(output: string): DeviceInfo[];
+export declare function parseDevicectlDevices(output: string | DevicectlDevicesJson): DeviceInfo[];
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAKV,UAAU,EAGV,WAAW,EAmBX,sBAAsB,EAGvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAG5B,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAoJD,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;KACjC,CAAC;CACH;AAED,UAAU,mBAAmB;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,gBAAgB,CAAC,EAAE;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,kBAAkB,CAAC,EAAE;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AA8BD,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAEzE;AAED,qBAAa,SAAU,YAAW,cAAc;IAC9C,QAAQ,CAAC,QAAQ,EAAG,KAAK,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,OAAO,GAAE,gBAAqB;IAKpC,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAoGhC,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAS5B,sBAAsB;YAYtB,cAAc;YAKd,oBAAoB;IAS5B,aAAa,CAAC,YAAY,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;YA6BrE,iBAAiB;YAyCjB,kBAAkB;YAqDlB,8BAA8B;CAuO7C;AA29CD,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAsB,6BAA6B,CACjD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,MAAkC,GACvC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAoND,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAuB/D;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAkBjE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,GAAG,UAAU,EAAE,CAgBzF"}