zig-mobile-runner 0.1.0

package/src/doctor.zig

@@ -0,0 +1,412 @@
+const std = @import("std");
+const android = @import("android.zig");
+const command = @import("command.zig");
+const config = @import("config.zig");
+const doctor_hints = @import("doctor_hints.zig");
+const ios = @import("ios.zig");
+const types = @import("types.zig");
+const validation = @import("validation.zig");
+
+pub const Status = doctor_hints.Status;
+
+pub const Check = struct {
+    name: []const u8,
+    status: Status,
+    detail: []const u8,
+    error_code: ?[]const u8 = null,
+    field_path: ?[]const u8 = null,
+    hint: ?[]const u8 = null,
+    count: ?usize = null,
+    ready_count: ?usize = null,
+    script_count: ?usize = null,
+    script_names: ?[]const []const u8 = null,
+
+    pub fn deinit(self: Check, allocator: std.mem.Allocator) void {
+        allocator.free(self.name);
+        allocator.free(self.detail);
+        if (self.error_code) |error_code| allocator.free(error_code);
+        if (self.field_path) |field_path| allocator.free(field_path);
+        if (self.hint) |hint| allocator.free(hint);
+        if (self.script_names) |script_names| freeStringList(allocator, script_names);
+    }
+};
+
+pub const Options = struct {
+    zig_path: []const u8 = "zig",
+    adb_path: []const u8 = "adb",
+    android_shim_path: ?[]const u8 = null,
+    android_smoke_scenario: ?[]const u8 = null,
+    xcrun_path: []const u8 = "xcrun",
+    ios_shim_path: ?[]const u8 = null,
+    ios_smoke_scenario: ?[]const u8 = null,
+};
+
+pub fn checkConfigLoaded(allocator: std.mem.Allocator, path: []const u8, scripts: []const config.ScriptCommand) !Check {
+    const name = try allocator.dupe(u8, "config");
+    errdefer allocator.free(name);
+    const detail = try allocator.dupe(u8, path);
+    errdefer allocator.free(detail);
+    const script_names = try duplicateScriptNames(allocator, scripts);
+    errdefer freeStringList(allocator, script_names);
+
+    return .{
+        .name = name,
+        .status = .ok,
+        .detail = detail,
+        .script_count = scripts.len,
+        .script_names = script_names,
+    };
+}
+
+fn duplicateScriptNames(allocator: std.mem.Allocator, scripts: []const config.ScriptCommand) ![]const []const u8 {
+    if (scripts.len == 0) return &.{};
+
+    var names = try allocator.alloc([]const u8, scripts.len);
+    errdefer allocator.free(names);
+    var written: usize = 0;
+    errdefer {
+        for (names[0..written]) |name| allocator.free(name);
+    }
+
+    for (scripts, 0..) |script, index| {
+        names[index] = try allocator.dupe(u8, script.name);
+        written += 1;
+    }
+    return names;
+}
+
+fn freeStringList(allocator: std.mem.Allocator, list: []const []const u8) void {
+    if (list.len == 0) return;
+    for (list) |item| allocator.free(item);
+    allocator.free(list);
+}
+
+pub fn checkConfigError(allocator: std.mem.Allocator, path: []const u8, err: anyerror, field_path: ?[]const u8) !Check {
+    const status: Status = if (err == error.FileNotFound) .missing else .warning;
+    return .{
+        .name = try allocator.dupe(u8, "config"),
+        .status = status,
+        .detail = try std.fmt.allocPrint(allocator, "{s}: {s}", .{ path, @errorName(err) }),
+        .error_code = try allocator.dupe(u8, configErrorCode(err)),
+        .field_path = if (field_path) |value| try allocator.dupe(u8, value) else null,
+        .hint = try doctor_hints.hintForCheck(allocator, "config", status),
+    };
+}
+
+fn configErrorCode(err: anyerror) []const u8 {
+    return switch (err) {
+        error.FileNotFound => "config.file_not_found",
+        error.ConfigMustBeObject => "config.must_be_object",
+        error.MissingConfigSchemaVersion => "config.missing_schema_version",
+        error.ConfigSchemaVersionMustBeInteger => "config.schema_version_type",
+        error.UnsupportedConfigVersion => "config.unsupported_version",
+        error.ConfigUnknownField => "config.unknown_field",
+        error.ConfigPlatformMustBeObject,
+        error.ConfigToolsMustBeObject,
+        error.ConfigArtifactsMustBeObject,
+        error.ConfigRedactionMustBeObject,
+        error.ConfigScriptsMustBeObject,
+        error.ConfigFieldMustBeBool,
+        error.ConfigFieldMustBeString,
+        error.ConfigFieldMustBeStringArray,
+        => "config.field_type",
+        error.ConfigFieldMustBeNonEmptyString => "config.empty_string",
+        else => "config.invalid",
+    };
+}
+
+pub fn run(allocator: std.mem.Allocator, options: Options) ![]Check {
+    var checks = std.ArrayList(Check).empty;
+    errdefer {
+        for (checks.items) |check| check.deinit(allocator);
+        checks.deinit(allocator);
+    }
+
+    try checks.append(allocator, try checkCommand(allocator, "zig", &.{ options.zig_path, "version" }));
+    try checks.append(allocator, try checkCommand(allocator, "adb", &.{ options.adb_path, "version" }));
+    try checks.append(allocator, try checkAndroidDevices(allocator, options.adb_path));
+    if (options.android_shim_path) |path| try checks.append(allocator, try checkPath(allocator, "android-shim", path));
+    if (options.android_smoke_scenario) |path| try checks.append(allocator, try checkScenarioPath(allocator, "android-smoke-scenario", path));
+    try checks.append(allocator, try checkCommand(allocator, "xcrun", &.{ options.xcrun_path, "--version" }));
+    try checks.append(allocator, try checkIosSimulators(allocator, options.xcrun_path));
+    try checks.append(allocator, try checkIosPhysicalDevices(allocator, options.xcrun_path));
+    if (options.ios_shim_path) |path| try checks.append(allocator, try checkPath(allocator, "ios-shim", path));
+    if (options.ios_smoke_scenario) |path| try checks.append(allocator, try checkScenarioPath(allocator, "ios-smoke-scenario", path));
+
+    return try checks.toOwnedSlice(allocator);
+}
+
+fn checkPath(allocator: std.mem.Allocator, name: []const u8, path: []const u8) !Check {
+    std.fs.cwd().access(path, .{ .mode = .read_only }) catch |err| {
+        return .{
+            .name = try allocator.dupe(u8, name),
+            .status = .missing,
+            .error_code = try allocator.dupe(u8, doctor_hints.setupErrorCode(name, .missing)),
+            .detail = try std.fmt.allocPrint(allocator, "{s}: {s}", .{ path, @errorName(err) }),
+            .hint = try doctor_hints.hintForCheck(allocator, name, .missing),
+        };
+    };
+    return .{
+        .name = try allocator.dupe(u8, name),
+        .status = .ok,
+        .detail = try allocator.dupe(u8, path),
+    };
+}
+
+fn checkScenarioPath(allocator: std.mem.Allocator, name: []const u8, path: []const u8) !Check {
+    const result = try validation.validateFile(allocator, path);
+    defer result.deinit(allocator);
+
+    if (result.ok) {
+        return .{
+            .name = try allocator.dupe(u8, name),
+            .status = .ok,
+            .detail = try std.fmt.allocPrint(allocator, "{s}: ok ({s}, {d} steps)", .{ path, result.name.?, result.step_count }),
+        };
+    }
+
+    const status: Status = if (result.error_code != null and std.mem.eql(u8, result.error_code.?, "scenario.file_not_found")) .missing else .warning;
+    const code = result.error_code orelse "scenario.invalid";
+    return .{
+        .name = try allocator.dupe(u8, name),
+        .status = status,
+        .detail = try scenarioValidationDetail(allocator, path, result),
+        .error_code = try allocator.dupe(u8, code),
+        .hint = try doctor_hints.hintForCheck(allocator, name, status),
+    };
+}
+
+fn scenarioValidationDetail(allocator: std.mem.Allocator, path: []const u8, result: validation.Result) ![]const u8 {
+    const code = result.error_code orelse "scenario.invalid";
+    const message = result.message orelse "scenario is invalid";
+    if (result.path) |field_path| {
+        if (result.line) |line| {
+            if (result.column) |column| {
+                return try std.fmt.allocPrint(allocator, "{s}: invalid [{s}] {s} at {s} line {d} column {d}", .{ path, code, message, field_path, line, column });
+            }
+        }
+        return try std.fmt.allocPrint(allocator, "{s}: invalid [{s}] {s} at {s}", .{ path, code, message, field_path });
+    }
+    if (result.line) |line| {
+        if (result.column) |column| {
+            return try std.fmt.allocPrint(allocator, "{s}: invalid [{s}] {s} line {d} column {d}", .{ path, code, message, line, column });
+        }
+    }
+    return try std.fmt.allocPrint(allocator, "{s}: invalid [{s}] {s}", .{ path, code, message });
+}
+
+fn checkAndroidDevices(allocator: std.mem.Allocator, adb_path: []const u8) !Check {
+    const devices = android.listDevices(allocator, adb_path) catch |err| {
+        return .{
+            .name = try allocator.dupe(u8, "android-devices"),
+            .status = .missing,
+            .error_code = try allocator.dupe(u8, "setup.android.devices_unavailable"),
+            .detail = try std.fmt.allocPrint(allocator, "{s}: {s}", .{ adb_path, @errorName(err) }),
+            .hint = try doctor_hints.hintForCheck(allocator, "android-devices", .missing),
+        };
+    };
+    defer {
+        for (devices) |device| device.deinit(allocator);
+        allocator.free(devices);
+    }
+    if (devices.len == 0) {
+        return .{
+            .name = try allocator.dupe(u8, "android-devices"),
+            .status = .warning,
+            .error_code = try allocator.dupe(u8, "setup.android.no_devices"),
+            .detail = try allocator.dupe(u8, "0 Android device(s)"),
+            .hint = try doctor_hints.hintForCheck(allocator, "android-devices", .warning),
+            .count = 0,
+            .ready_count = 0,
+        };
+    }
+    return .{
+        .name = try allocator.dupe(u8, "android-devices"),
+        .status = .ok,
+        .detail = try std.fmt.allocPrint(allocator, "{d} Android device(s)", .{devices.len}),
+        .count = devices.len,
+        .ready_count = devices.len,
+    };
+}
+
+fn checkIosSimulators(allocator: std.mem.Allocator, xcrun_path: []const u8) !Check {
+    const devices = ios.listDevices(allocator, xcrun_path) catch |err| {
+        return .{
+            .name = try allocator.dupe(u8, "ios-simulators"),
+            .status = .missing,
+            .error_code = try allocator.dupe(u8, "setup.ios.simulators_unavailable"),
+            .detail = try std.fmt.allocPrint(allocator, "{s}: {s}", .{ xcrun_path, @errorName(err) }),
+            .hint = try doctor_hints.hintForCheck(allocator, "ios-simulators", .missing),
+        };
+    };
+    defer {
+        for (devices) |device| device.deinit(allocator);
+        allocator.free(devices);
+    }
+    if (devices.len == 0) {
+        return .{
+            .name = try allocator.dupe(u8, "ios-simulators"),
+            .status = .warning,
+            .error_code = try allocator.dupe(u8, "setup.ios.no_booted_simulators"),
+            .detail = try allocator.dupe(u8, "0 booted iOS simulator(s)"),
+            .hint = try doctor_hints.hintForCheck(allocator, "ios-simulators", .warning),
+            .count = 0,
+            .ready_count = 0,
+        };
+    }
+    return .{
+        .name = try allocator.dupe(u8, "ios-simulators"),
+        .status = .ok,
+        .detail = try std.fmt.allocPrint(allocator, "{d} booted iOS simulator(s)", .{devices.len}),
+        .count = devices.len,
+        .ready_count = devices.len,
+    };
+}
+
+fn checkIosPhysicalDevices(allocator: std.mem.Allocator, xcrun_path: []const u8) !Check {
+    const devices = ios.listPhysicalDevices(allocator, xcrun_path) catch |err| {
+        return .{
+            .name = try allocator.dupe(u8, "ios-physical-devices"),
+            .status = .missing,
+            .error_code = try allocator.dupe(u8, "setup.ios.physical_devices_unavailable"),
+            .detail = try std.fmt.allocPrint(allocator, "{s}: {s}", .{ xcrun_path, @errorName(err) }),
+            .hint = try doctor_hints.hintForCheck(allocator, "ios-physical-devices", .missing),
+        };
+    };
+    defer {
+        for (devices) |device| device.deinit(allocator);
+        allocator.free(devices);
+    }
+    if (devices.len == 0) {
+        return .{
+            .name = try allocator.dupe(u8, "ios-physical-devices"),
+            .status = .warning,
+            .error_code = try allocator.dupe(u8, "setup.ios.no_physical_devices"),
+            .detail = try allocator.dupe(u8, "0 physical iOS device(s)"),
+            .hint = try doctor_hints.hintForCheck(allocator, "ios-physical-devices", .warning),
+            .count = 0,
+            .ready_count = 0,
+        };
+    }
+    var ready_count: usize = 0;
+    for (devices) |device| {
+        if (isReadyPhysicalDeviceState(device.state)) ready_count += 1;
+    }
+    if (ready_count == 0) {
+        const breakdown = try physicalStateBreakdown(allocator, devices);
+        defer allocator.free(breakdown);
+        return .{
+            .name = try allocator.dupe(u8, "ios-physical-devices"),
+            .status = .warning,
+            .error_code = try allocator.dupe(u8, "setup.ios.no_ready_physical_devices"),
+            .detail = try std.fmt.allocPrint(allocator, "0 ready physical iOS device(s); {d} listed{s}", .{ devices.len, breakdown }),
+            .hint = try doctor_hints.hintForCheck(allocator, "ios-physical-devices", .warning),
+            .count = devices.len,
+            .ready_count = 0,
+        };
+    }
+    if (ready_count < devices.len) {
+        const breakdown = try physicalStateBreakdown(allocator, devices);
+        defer allocator.free(breakdown);
+        return .{
+            .name = try allocator.dupe(u8, "ios-physical-devices"),
+            .status = .ok,
+            .detail = try std.fmt.allocPrint(allocator, "{d} ready physical iOS device(s); {d} listed{s}", .{ ready_count, devices.len, breakdown }),
+            .count = devices.len,
+            .ready_count = ready_count,
+        };
+    }
+    return .{
+        .name = try allocator.dupe(u8, "ios-physical-devices"),
+        .status = .ok,
+        .detail = try std.fmt.allocPrint(allocator, "{d} ready physical iOS device(s)", .{ready_count}),
+        .count = devices.len,
+        .ready_count = ready_count,
+    };
+}
+
+fn isReadyPhysicalDeviceState(state: []const u8) bool {
+    return std.mem.eql(u8, state, "connected") or std.mem.eql(u8, state, "available");
+}
+
+fn physicalStateBreakdown(allocator: std.mem.Allocator, devices: []const types.DeviceInfo) ![]const u8 {
+    var disconnected: usize = 0;
+    var paired: usize = 0;
+    var unavailable: usize = 0;
+    var other: usize = 0;
+
+    for (devices) |device| {
+        if (std.mem.eql(u8, device.state, "disconnected")) {
+            disconnected += 1;
+        } else if (std.mem.eql(u8, device.state, "paired")) {
+            paired += 1;
+        } else if (std.mem.eql(u8, device.state, "unavailable")) {
+            unavailable += 1;
+        } else if (!isReadyPhysicalDeviceState(device.state)) {
+            other += 1;
+        }
+    }
+
+    var parts = std.ArrayList(u8).empty;
+    defer parts.deinit(allocator);
+    const writer = parts.writer(allocator);
+    var wrote = false;
+    if (disconnected > 0) {
+        try writer.print("disconnected={d}", .{disconnected});
+        wrote = true;
+    }
+    if (paired > 0) {
+        if (wrote) try writer.writeAll(", ");
+        try writer.print("paired={d}", .{paired});
+        wrote = true;
+    }
+    if (unavailable > 0) {
+        if (wrote) try writer.writeAll(", ");
+        try writer.print("unavailable={d}", .{unavailable});
+        wrote = true;
+    }
+    if (other > 0) {
+        if (wrote) try writer.writeAll(", ");
+        try writer.print("other={d}", .{other});
+        wrote = true;
+    }
+
+    if (!wrote) return try allocator.dupe(u8, "");
+    return try std.fmt.allocPrint(allocator, " ({s})", .{parts.items});
+}
+
+pub fn checkCommand(allocator: std.mem.Allocator, name: []const u8, argv: []const []const u8) !Check {
+    const result = command.run(allocator, argv, 1024 * 1024) catch |err| {
+        return .{
+            .name = try allocator.dupe(u8, name),
+            .status = .missing,
+            .error_code = try allocator.dupe(u8, doctor_hints.setupErrorCode(name, .missing)),
+            .detail = try std.fmt.allocPrint(allocator, "{s}: {s}", .{ argv[0], @errorName(err) }),
+            .hint = try doctor_hints.hintForCheck(allocator, name, .missing),
+        };
+    };
+    defer result.deinit(allocator);
+
+    if (result.term == .Exited and result.term.Exited == 0) {
+        return .{
+            .name = try allocator.dupe(u8, name),
+            .status = .ok,
+            .detail = try firstLine(allocator, result.stdout),
+        };
+    }
+
+    const code = if (result.term == .Exited) result.term.Exited else 255;
+    return .{
+        .name = try allocator.dupe(u8, name),
+        .status = .warning,
+        .error_code = try allocator.dupe(u8, doctor_hints.setupErrorCode(name, .warning)),
+        .detail = try std.fmt.allocPrint(allocator, "exit {d}: {s}", .{ code, std.mem.trim(u8, result.stderr, " \t\r\n") }),
+        .hint = try doctor_hints.hintForCheck(allocator, name, .warning),
+    };
+}
+
+fn firstLine(allocator: std.mem.Allocator, value: []const u8) ![]const u8 {
+    const trimmed = std.mem.trim(u8, value, " \t\r\n");
+    const end = std.mem.indexOfScalar(u8, trimmed, '\n') orelse trimmed.len;
+    return try allocator.dupe(u8, trimmed[0..end]);
+}

package/src/doctor_hints.zig

@@ -0,0 +1,52 @@
+const std = @import("std");
+
+pub const Status = enum {
+    ok,
+    warning,
+    missing,
+};
+
+pub fn setupErrorCode(name: []const u8, status: Status) []const u8 {
+    if (std.mem.eql(u8, name, "zig")) return if (status == .missing) "setup.zig.not_found" else "setup.zig.command_failed";
+    if (std.mem.eql(u8, name, "adb")) return if (status == .missing) "setup.adb.not_found" else "setup.adb.command_failed";
+    if (std.mem.eql(u8, name, "xcrun")) return if (status == .missing) "setup.xcrun.not_found" else "setup.xcrun.command_failed";
+    if (std.mem.eql(u8, name, "android-shim")) return if (status == .missing) "setup.android_shim.not_found" else "setup.android_shim.command_failed";
+    if (std.mem.eql(u8, name, "ios-shim")) return if (status == .missing) "setup.ios_shim.not_found" else "setup.ios_shim.command_failed";
+    return if (status == .missing) "setup.tool.not_found" else "setup.tool.command_failed";
+}
+
+pub fn hintForCheck(allocator: std.mem.Allocator, name: []const u8, status: Status) !?[]const u8 {
+    if (status == .ok) return null;
+    const hint =
+        if (std.mem.eql(u8, name, "zig"))
+            "Install Zig 0.15.2 or newer, ensure it is on PATH, then run zmr doctor again."
+        else if (std.mem.eql(u8, name, "adb"))
+            "Install Android SDK Platform Tools, ensure adb is on PATH, then run adb devices."
+        else if (std.mem.eql(u8, name, "android-devices"))
+            "Start an emulator or connect a device, confirm adb devices shows it, then pass --device when running scenarios."
+        else if (std.mem.eql(u8, name, "config"))
+            "Fix the config file or regenerate it with npx zmr-wizard, then run zmr doctor --strict --json --config .zmr/config.json."
+        else if (std.mem.eql(u8, name, "android-shim"))
+            "Run npx zmr-install-android-shim in the app repo or update tools.androidShimPath in .zmr/config.json."
+        else if (std.mem.eql(u8, name, "android-smoke-scenario"))
+            if (status == .warning)
+                "Run zmr validate on the configured Android smoke scenario, fix the reported issue, or update android.smokeScenario in .zmr/config.json."
+            else
+                "Run npx zmr-wizard, create the Android smoke scenario, or update android.smokeScenario in .zmr/config.json."
+        else if (std.mem.eql(u8, name, "xcrun"))
+            "Install Xcode command line tools, run xcode-select --install if needed, then run xcrun --version."
+        else if (std.mem.eql(u8, name, "ios-simulators"))
+            "Boot an iOS simulator with Xcode or xcrun simctl boot, then run xcrun simctl list devices booted."
+        else if (std.mem.eql(u8, name, "ios-physical-devices"))
+            "Connect and trust an iPhone, enable Developer Mode, confirm zmr devices --json --platform ios --ios-device-type physical reports ready:true, then pass --ios-device-type physical --device <physical-device-id>."
+        else if (std.mem.eql(u8, name, "ios-shim"))
+            "Run npx zmr-install-ios-shim in the app repo or update tools.iosShimPath in .zmr/config.json."
+        else if (std.mem.eql(u8, name, "ios-smoke-scenario"))
+            if (status == .warning)
+                "Run zmr validate on the configured iOS smoke scenario, fix the reported issue, or update ios.smokeScenario in .zmr/config.json."
+            else
+                "Run npx zmr-wizard, create the iOS smoke scenario, or update ios.smokeScenario in .zmr/config.json."
+        else
+            "Run the command manually, fix the reported setup issue, then run zmr doctor again.";
+    return try allocator.dupe(u8, hint);
+}

package/src/errors.zig

@@ -0,0 +1,55 @@
+const std = @import("std");
+
+pub const PublicError = struct {
+    code: []const u8,
+    message: []const u8,
+};
+
+pub fn classify(err: anyerror) PublicError {
+    return switch (err) {
+        error.MissingScenarioPath => .{ .code = "cli.missing_scenario", .message = "missing scenario path" },
+        error.MissingDeviceSerial => .{ .code = "cli.missing_device", .message = "missing device serial" },
+        error.MissingTraceDir => .{ .code = "cli.missing_trace_dir", .message = "missing trace directory" },
+        error.MissingAppId => .{ .code = "cli.missing_app_id", .message = "missing app id" },
+        error.MissingAdbPath => .{ .code = "cli.missing_adb_path", .message = "missing adb path" },
+        error.MissingXcrunPath => .{ .code = "cli.missing_xcrun_path", .message = "missing xcrun path" },
+        error.MissingZigPath => .{ .code = "cli.missing_zig_path", .message = "missing zig path" },
+        error.MissingPlatform => .{ .code = "cli.missing_platform", .message = "missing platform" },
+        error.UnknownCommand => .{ .code = "cli.unknown_command", .message = "unknown command" },
+        error.UnknownFlag => .{ .code = "cli.unknown_flag", .message = "unknown flag" },
+        error.MissingParam => .{ .code = "cli.missing_param", .message = "missing parameter" },
+        error.FileNotFound => .{ .code = "scenario.file_not_found", .message = "scenario file was not found" },
+        error.UnsupportedPlatform => .{ .code = "cli.unsupported_platform", .message = "unsupported platform" },
+        error.UnsupportedTransport => .{ .code = "cli.unsupported_transport", .message = "unsupported transport" },
+        error.ScenarioMustBeObject,
+        error.ScenarioMissingSteps,
+        error.ScenarioStepsMustBeArray,
+        error.StepMustBeObject,
+        error.StepMissingAction,
+        error.StepActionMustBeString,
+        error.UnknownAction,
+        error.UnknownScenarioAction,
+        error.UnknownScrollDirection,
+        error.StepMissingUrl,
+        error.StepMissingText,
+        error.StepMissingX1,
+        error.StepMissingY1,
+        error.StepMissingX2,
+        error.StepMissingY2,
+        => .{ .code = "scenario.invalid", .message = "scenario is invalid" },
+        error.SelectorMustNotBeEmpty,
+        error.MissingSelector,
+        error.StepMissingSelector,
+        error.MissingSelectors,
+        error.StepMissingSelectors,
+        error.SelectorsMustBeArray,
+        error.SelectorsMustNotBeEmpty,
+        => .{ .code = "selector.invalid", .message = "selector is invalid" },
+        error.WaitTimeout => .{ .code = "runner.wait_timeout", .message = "wait timed out" },
+        error.AssertionFailed => .{ .code = "runner.assertion_failed", .message = "assertion failed" },
+        error.SelectorNotFound => .{ .code = "runner.selector_not_found", .message = "selector not found" },
+        error.CommandFailed => .{ .code = "device.command_failed", .message = "device command failed" },
+        error.IosXCTestShimRequired => .{ .code = "ios.xctest_shim_required", .message = "iOS selector interaction requires the XCTest shim" },
+        else => .{ .code = "internal.error", .message = @errorName(err) },
+    };
+}

package/src/fake_device.zig

@@ -0,0 +1,163 @@
+const std = @import("std");
+const types = @import("types.zig");
+
+pub const FakeDevice = struct {
+    allocator: std.mem.Allocator,
+    snapshots: []types.ObservationSnapshot,
+    snapshot_index: usize = 0,
+    taps: usize = 0,
+    swipes: usize = 0,
+    erases: usize = 0,
+    hides_keyboard: usize = 0,
+    presses_back: usize = 0,
+    stopped: bool = false,
+    cleared: bool = false,
+    last_swipe: ?SwipeRecord = null,
+    last_erase_chars: u32 = 0,
+    typed_text: std.ArrayList([]const u8),
+    launched: bool = false,
+    installed_path: ?[]const u8 = null,
+    opened_link: ?[]const u8 = null,
+    settles: usize = 0,
+    last_settle_timeout_ms: u64 = 0,
+
+    pub fn init(allocator: std.mem.Allocator, snapshots: []types.ObservationSnapshot) FakeDevice {
+        return .{
+            .allocator = allocator,
+            .snapshots = snapshots,
+            .typed_text = std.ArrayList([]const u8).empty,
+        };
+    }
+
+    pub fn deinit(self: *FakeDevice) void {
+        for (self.typed_text.items) |text| self.allocator.free(text);
+        self.typed_text.deinit(self.allocator);
+        if (self.installed_path) |value| self.allocator.free(value);
+        if (self.opened_link) |value| self.allocator.free(value);
+    }
+
+    pub fn install(self: *FakeDevice, apk_path: []const u8) !void {
+        if (self.installed_path) |value| self.allocator.free(value);
+        self.installed_path = try self.allocator.dupe(u8, apk_path);
+    }
+
+    pub fn launch(self: *FakeDevice) !void {
+        self.launched = true;
+    }
+
+    pub fn stop(self: *FakeDevice) !void {
+        self.stopped = true;
+    }
+
+    pub fn clearState(self: *FakeDevice) !void {
+        self.cleared = true;
+    }
+
+    pub fn listDevices(self: *FakeDevice) ![]types.DeviceInfo {
+        const devices = try self.allocator.alloc(types.DeviceInfo, 1);
+        errdefer self.allocator.free(devices);
+        const serial = try self.allocator.dupe(u8, "fake-device-1");
+        errdefer self.allocator.free(serial);
+        const state = try self.allocator.dupe(u8, "device");
+        devices[0] = .{
+            .serial = serial,
+            .state = state,
+        };
+        return devices;
+    }
+
+    pub fn openLink(self: *FakeDevice, url: []const u8) !void {
+        if (self.opened_link) |value| self.allocator.free(value);
+        self.opened_link = try self.allocator.dupe(u8, url);
+    }
+
+    pub fn tap(self: *FakeDevice, x: i32, y: i32) !void {
+        _ = x;
+        _ = y;
+        self.taps += 1;
+    }
+
+    pub fn typeText(self: *FakeDevice, text: []const u8) !void {
+        try self.typed_text.append(self.allocator, try self.allocator.dupe(u8, text));
+    }
+
+    pub fn eraseText(self: *FakeDevice, max_chars: u32) !void {
+        self.last_erase_chars = max_chars;
+        self.erases += 1;
+    }
+
+    pub fn hideKeyboard(self: *FakeDevice) !void {
+        self.hides_keyboard += 1;
+    }
+
+    pub fn swipe(self: *FakeDevice, x1: i32, y1: i32, x2: i32, y2: i32, duration_ms: u32) !void {
+        self.swipes += 1;
+        self.last_swipe = .{
+            .x1 = x1,
+            .y1 = y1,
+            .x2 = x2,
+            .y2 = y2,
+            .duration_ms = duration_ms,
+        };
+    }
+
+    pub fn pressBack(self: *FakeDevice) !void {
+        self.presses_back += 1;
+    }
+
+    pub fn settle(self: *FakeDevice, timeout_ms: u64) !void {
+        self.settles += 1;
+        self.last_settle_timeout_ms = timeout_ms;
+    }
+
+    pub fn snapshot(self: *FakeDevice, writer: anytype) !types.ObservationSnapshot {
+        _ = writer;
+        if (self.snapshots.len == 0) return error.NoFakeSnapshots;
+        const index = @min(self.snapshot_index, self.snapshots.len - 1);
+        if (self.snapshot_index + 1 < self.snapshots.len) self.snapshot_index += 1;
+        return try cloneSnapshot(self.allocator, self.snapshots[index]);
+    }
+};
+
+pub const SwipeRecord = struct {
+    x1: i32,
+    y1: i32,
+    x2: i32,
+    y2: i32,
+    duration_ms: u32,
+};
+
+pub fn cloneSnapshot(allocator: std.mem.Allocator, source: types.ObservationSnapshot) !types.ObservationSnapshot {
+    var nodes = try allocator.alloc(types.UiNode, source.nodes.len);
+    errdefer allocator.free(nodes);
+    var initialized: usize = 0;
+    errdefer {
+        for (nodes[0..initialized]) |node| node.deinit(allocator);
+    }
+    for (source.nodes, 0..) |node, index| {
+        nodes[index] = .{
+            .stable_id = try allocator.dupe(u8, node.stable_id),
+            .class_name = try allocator.dupe(u8, node.class_name),
+            .resource_id = try types.dupeOptional(allocator, node.resource_id),
+            .text = try types.dupeOptional(allocator, node.text),
+            .content_desc = try types.dupeOptional(allocator, node.content_desc),
+            .bounds = node.bounds,
+            .enabled = node.enabled,
+            .visible = node.visible,
+            .selected = node.selected,
+        };
+        initialized += 1;
+    }
+    return .{
+        .id = try allocator.dupe(u8, source.id),
+        .timestamp_ms = source.timestamp_ms,
+        .viewport = source.viewport,
+        .active_package = try types.dupeOptional(allocator, source.active_package),
+        .active_activity = try types.dupeOptional(allocator, source.active_activity),
+        .screenshot_artifact = try types.dupeOptional(allocator, source.screenshot_artifact),
+        .tree_artifact = try types.dupeOptional(allocator, source.tree_artifact),
+        .focused_node_id = try types.dupeOptional(allocator, source.focused_node_id),
+        .log_delta = try types.dupeOptional(allocator, source.log_delta),
+        .nodes = nodes,
+    };
+}