zig-mobile-runner 0.1.0

package/src/cli_run.zig

@@ -0,0 +1,259 @@
+const std = @import("std");
+
+const android = @import("android.zig");
+const android_emulator = @import("android_emulator.zig");
+const cli_output = @import("cli_output.zig");
+const config_paths = @import("config_paths.zig");
+const ios = @import("ios.zig");
+const runner = @import("runner.zig");
+const run_options = @import("run_options.zig");
+const scenario = @import("scenario.zig");
+const trace = @import("trace.zig");
+
+pub const ParsedArgs = struct {
+    raw: run_options.RawRunOptions = .{},
+    adb_path: []const u8 = "adb",
+    emulator_path: []const u8 = "emulator",
+    avdmanager_path: []const u8 = "avdmanager",
+    xcrun_path: []const u8 = "xcrun",
+    adb_path_set: bool = false,
+    emulator_path_set: bool = false,
+    avdmanager_path_set: bool = false,
+    xcrun_path_set: bool = false,
+    config_path: ?[]const u8 = null,
+    json: bool = false,
+};
+
+pub fn parseArgs(args: []const []const u8) !ParsedArgs {
+    var parsed = ParsedArgs{};
+    var index: usize = 0;
+    while (index < args.len) : (index += 1) {
+        const arg = args[index];
+        if (std.mem.eql(u8, arg, "--device")) {
+            index += 1;
+            parsed.raw.serial = if (index < args.len) args[index] else return error.MissingDeviceSerial;
+        } else if (std.mem.eql(u8, arg, "--trace-dir")) {
+            index += 1;
+            parsed.raw.trace_dir = if (index < args.len) args[index] else return error.MissingTraceDir;
+        } else if (std.mem.eql(u8, arg, "--app-id")) {
+            index += 1;
+            parsed.raw.app_id = if (index < args.len) args[index] else return error.MissingAppId;
+        } else if (std.mem.eql(u8, arg, "--adb")) {
+            index += 1;
+            parsed.adb_path = if (index < args.len) args[index] else return error.MissingAdbPath;
+            parsed.adb_path_set = true;
+        } else if (std.mem.eql(u8, arg, "--emulator")) {
+            index += 1;
+            parsed.emulator_path = if (index < args.len) args[index] else return error.MissingEmulatorPath;
+            parsed.emulator_path_set = true;
+        } else if (std.mem.eql(u8, arg, "--avdmanager")) {
+            index += 1;
+            parsed.avdmanager_path = if (index < args.len) args[index] else return error.MissingAvdmanagerPath;
+            parsed.avdmanager_path_set = true;
+        } else if (std.mem.eql(u8, arg, "--android-shim")) {
+            index += 1;
+            parsed.raw.android_shim_path = if (index < args.len) args[index] else return error.MissingAndroidShimPath;
+        } else if (std.mem.eql(u8, arg, "--xcrun")) {
+            index += 1;
+            parsed.xcrun_path = if (index < args.len) args[index] else return error.MissingXcrunPath;
+            parsed.xcrun_path_set = true;
+        } else if (std.mem.eql(u8, arg, "--ios-shim")) {
+            index += 1;
+            parsed.raw.ios_shim_path = if (index < args.len) args[index] else return error.MissingIosShimPath;
+        } else if (std.mem.eql(u8, arg, "--platform")) {
+            index += 1;
+            parsed.raw.platform = try parsePlatform(if (index < args.len) args[index] else return error.MissingPlatform);
+        } else if (std.mem.eql(u8, arg, "--ios-device-type")) {
+            index += 1;
+            parsed.raw.ios_device_type = try parseIosDeviceType(if (index < args.len) args[index] else return error.MissingIosDeviceType);
+        } else if (std.mem.eql(u8, arg, "--config")) {
+            index += 1;
+            parsed.config_path = if (index < args.len) args[index] else return error.MissingConfigPath;
+        } else if (std.mem.eql(u8, arg, "--screen-record")) {
+            parsed.raw.screen_recording = true;
+        } else if (std.mem.eql(u8, arg, "--no-screen-record")) {
+            parsed.raw.screen_recording = false;
+        } else if (std.mem.eql(u8, arg, "--android-avd")) {
+            index += 1;
+            parsed.raw.android_avd_name = if (index < args.len) args[index] else return error.MissingAndroidAvdName;
+        } else if (std.mem.eql(u8, arg, "--restore-snapshot")) {
+            index += 1;
+            parsed.raw.android_restore_snapshot = if (index < args.len) args[index] else return error.MissingAndroidSnapshotName;
+        } else if (std.mem.eql(u8, arg, "--create-avd-if-missing")) {
+            parsed.raw.android_create_avd_if_missing = true;
+        } else if (std.mem.eql(u8, arg, "--avd-system-image")) {
+            index += 1;
+            parsed.raw.android_avd_system_image = if (index < args.len) args[index] else return error.MissingAndroidAvdSystemImage;
+        } else if (std.mem.eql(u8, arg, "--avd-device")) {
+            index += 1;
+            parsed.raw.android_avd_device_profile = if (index < args.len) args[index] else return error.MissingAndroidAvdDeviceProfile;
+        } else if (std.mem.eql(u8, arg, "--reset-emulator")) {
+            parsed.raw.android_reset_before_run = true;
+        } else if (std.mem.eql(u8, arg, "--wait-emulator")) {
+            parsed.raw.android_wait_ready = true;
+        } else if (std.mem.eql(u8, arg, "--json")) {
+            parsed.json = true;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (parsed.raw.scenario_path == null) {
+            parsed.raw.scenario_path = arg;
+        } else {
+            return error.UnknownFlag;
+        }
+    }
+    return parsed;
+}
+
+pub fn run(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {
+    var raw_args = std.ArrayList([]const u8).empty;
+    defer raw_args.deinit(allocator);
+    while (args.next()) |arg| try raw_args.append(allocator, arg);
+
+    const parsed = try parseArgs(raw_args.items);
+    const raw = parsed.raw;
+    var adb_path = parsed.adb_path;
+    var emulator_path = parsed.emulator_path;
+    var avdmanager_path = parsed.avdmanager_path;
+    var xcrun_path = parsed.xcrun_path;
+
+    const actual_config_path = parsed.config_path orelse config_paths.default_path;
+    var owned_config_paths = std.ArrayList([]const u8).empty;
+    defer {
+        for (owned_config_paths.items) |path| allocator.free(path);
+        owned_config_paths.deinit(allocator);
+    }
+    var config_root: ?[]const u8 = null;
+    defer if (config_root) |root| allocator.free(root);
+
+    var loaded_config = try config_paths.loadIfPresent(allocator, parsed.config_path);
+    defer if (loaded_config) |*cfg| cfg.deinit(allocator);
+    if (loaded_config) |cfg| {
+        config_root = try config_paths.rootForPath(allocator, actual_config_path);
+        if (!parsed.adb_path_set) {
+            if (cfg.tools.adb_path) |path| adb_path = try config_paths.ownCommandPath(allocator, &owned_config_paths, config_root.?, path);
+        }
+        if (!parsed.emulator_path_set) {
+            if (cfg.tools.emulator_path) |path| emulator_path = try config_paths.ownCommandPath(allocator, &owned_config_paths, config_root.?, path);
+        }
+        if (!parsed.avdmanager_path_set) {
+            if (cfg.tools.avdmanager_path) |path| avdmanager_path = try config_paths.ownCommandPath(allocator, &owned_config_paths, config_root.?, path);
+        }
+        if (!parsed.xcrun_path_set) {
+            if (cfg.tools.xcrun_path) |path| xcrun_path = try config_paths.ownCommandPath(allocator, &owned_config_paths, config_root.?, path);
+        }
+    }
+    const resolved = if (loaded_config) |cfg| run_options.resolveRun(raw, cfg) else run_options.resolveRun(raw, null);
+    var capture = if (loaded_config) |cfg| run_options.traceCapture(cfg) else trace.CaptureOptions{};
+    if (raw.screen_recording) |enabled| capture.capture_screen_recording = enabled;
+    const scenario_path = if (raw.scenario_path == null and config_root != null and resolved.scenario_path != null)
+        try config_paths.ownFilePath(allocator, &owned_config_paths, config_root.?, resolved.scenario_path.?)
+    else
+        resolved.scenario_path orelse return error.MissingScenarioPath;
+    const trace_dir = if (raw.trace_dir == null and config_root != null and resolved.trace_dir != null)
+        try config_paths.ownFilePath(allocator, &owned_config_paths, config_root.?, resolved.trace_dir.?)
+    else
+        resolved.trace_dir;
+    const android_shim_path = if (raw.android_shim_path == null and config_root != null and resolved.android_shim_path != null)
+        try config_paths.ownFilePath(allocator, &owned_config_paths, config_root.?, resolved.android_shim_path.?)
+    else
+        resolved.android_shim_path;
+    const ios_shim_path = if (raw.ios_shim_path == null and config_root != null and resolved.ios_shim_path != null)
+        try config_paths.ownFilePath(allocator, &owned_config_paths, config_root.?, resolved.ios_shim_path.?)
+    else
+        resolved.ios_shim_path;
+
+    const script = try scenario.parseFile(allocator, scenario_path);
+    defer script.deinit(allocator);
+    const app_id = if (raw.app_id) |_| resolved.app_id else script.app_id orelse resolved.app_id;
+
+    const run_error: ?anyerror = blk: {
+        switch (resolved.platform) {
+            .android => {
+                if (run_options.androidPreflight(resolved, adb_path, emulator_path, avdmanager_path)) |preflight| {
+                    try android_emulator.runPreflight(allocator, preflight);
+                }
+                var device = try android.AndroidDevice.initWithShim(allocator, adb_path, resolved.serial, app_id, android_shim_path);
+                defer device.deinit();
+                runAndroidWithTrace(allocator, &device, script, trace_dir, capture) catch |err| break :blk err;
+            },
+            .ios => {
+                var device = try ios.IosDevice.initWithKindAndShim(allocator, xcrun_path, resolved.serial, app_id, iosTargetKind(resolved.ios_device_type), ios_shim_path);
+                defer device.deinit();
+                runWithTrace(allocator, &device, script, trace_dir, capture) catch |err| break :blk err;
+            },
+        }
+        break :blk null;
+    };
+
+    if (parsed.json) try cli_output.writeRunSummaryJson(
+        allocator,
+        std.fs.File.stdout().deprecatedWriter(),
+        trace_dir,
+        script.name,
+        app_id,
+        run_error,
+    );
+    if (run_error) |err| return err;
+}
+
+fn runAndroidWithTrace(
+    allocator: std.mem.Allocator,
+    device: *android.AndroidDevice,
+    script: scenario.Scenario,
+    trace_dir: ?[]const u8,
+    capture: trace.CaptureOptions,
+) !void {
+    if (trace_dir == null or !capture.capture_screen_recording) {
+        return try runWithTrace(allocator, device, script, trace_dir, capture);
+    }
+
+    var trace_writer = try trace.TraceWriter.initWithOptions(allocator, trace_dir.?, capture);
+    defer trace_writer.deinit();
+
+    var recording = device.startScreenRecording("/sdcard/zmr-trace-screenrecord.mp4") catch null;
+    defer if (recording) |*rec| {
+        if (rec.stopAndPull(&trace_writer, "screenrecord.mp4")) |artifact_path| {
+            allocator.free(artifact_path);
+            trace_writer.recordEvent("trace.screenRecording", "{\"artifact\":\"artifacts/screenrecord.mp4\"}") catch {};
+        } else |_| {}
+        rec.deinit();
+    };
+
+    return try runner.runScenario(allocator, device, script, &trace_writer, .{});
+}
+
+fn runWithTrace(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    script: scenario.Scenario,
+    trace_dir: ?[]const u8,
+    capture: trace.CaptureOptions,
+) !void {
+    var trace_writer: ?trace.TraceWriter = null;
+    if (trace_dir) |dir| {
+        trace_writer = try trace.TraceWriter.initWithOptions(allocator, dir, capture);
+    }
+    defer if (trace_writer) |*tw| tw.deinit();
+
+    if (trace_writer) |*tw| return try runner.runScenario(allocator, device, script, tw, .{});
+    return try runner.runScenario(allocator, device, script, null, .{});
+}
+
+pub fn parsePlatform(value: []const u8) !run_options.Platform {
+    if (std.mem.eql(u8, value, "android")) return .android;
+    if (std.mem.eql(u8, value, "ios")) return .ios;
+    return error.UnsupportedPlatform;
+}
+
+fn parseIosDeviceType(value: []const u8) !run_options.IosDeviceType {
+    if (std.mem.eql(u8, value, "simulator")) return .simulator;
+    if (std.mem.eql(u8, value, "physical")) return .physical;
+    return error.UnsupportedIosDeviceType;
+}
+
+fn iosTargetKind(value: run_options.IosDeviceType) ios.TargetKind {
+    return switch (value) {
+        .simulator => .simulator,
+        .physical => .physical,
+    };
+}

package/src/cli_serve.zig

@@ -0,0 +1,287 @@
+const std = @import("std");
+
+const android = @import("android.zig");
+const config = @import("config.zig");
+const config_paths = @import("config_paths.zig");
+const ios = @import("ios.zig");
+const json_rpc = @import("json_rpc.zig");
+const mcp = @import("mcp.zig");
+const run_options = @import("run_options.zig");
+const trace = @import("trace.zig");
+
+pub const ServeArgs = struct {
+    raw: run_options.RawServeOptions = .{},
+    adb_path: []const u8 = "adb",
+    xcrun_path: []const u8 = "xcrun",
+    transport: []const u8 = "stdio",
+    port: u16 = 8765,
+    config_path: ?[]const u8 = null,
+};
+
+pub const McpArgs = struct {
+    raw: run_options.RawServeOptions = .{},
+    adb_path: []const u8 = "adb",
+    xcrun_path: []const u8 = "xcrun",
+    config_path: ?[]const u8 = null,
+};
+
+const ResolvedContext = struct {
+    resolved: run_options.ResolvedServeOptions,
+    adb_path: []const u8,
+    xcrun_path: []const u8,
+    trace_dir: ?[]const u8,
+    android_shim_path: ?[]const u8,
+    ios_shim_path: ?[]const u8,
+    capture: trace.CaptureOptions,
+};
+
+pub fn parseServeArgs(args: []const []const u8) !ServeArgs {
+    var parsed = ServeArgs{};
+    var index: usize = 0;
+    while (index < args.len) : (index += 1) {
+        const arg = args[index];
+        if (std.mem.eql(u8, arg, "--transport")) {
+            index += 1;
+            parsed.transport = if (index < args.len) args[index] else return error.MissingTransport;
+            if (!std.mem.eql(u8, parsed.transport, "stdio") and !std.mem.eql(u8, parsed.transport, "tcp")) {
+                return error.UnsupportedTransport;
+            }
+        } else if (std.mem.eql(u8, arg, "--port")) {
+            index += 1;
+            const value = if (index < args.len) args[index] else return error.MissingPort;
+            parsed.port = try std.fmt.parseInt(u16, value, 10);
+        } else {
+            try parseCommonArg(args, &index, &parsed.raw, &parsed.adb_path, &parsed.xcrun_path, &parsed.config_path);
+        }
+    }
+    return parsed;
+}
+
+pub fn parseMcpArgs(args: []const []const u8) !McpArgs {
+    var parsed = McpArgs{};
+    var index: usize = 0;
+    while (index < args.len) : (index += 1) {
+        try parseCommonArg(args, &index, &parsed.raw, &parsed.adb_path, &parsed.xcrun_path, &parsed.config_path);
+    }
+    return parsed;
+}
+
+pub fn runServe(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {
+    var raw_args = std.ArrayList([]const u8).empty;
+    defer raw_args.deinit(allocator);
+    while (args.next()) |arg| try raw_args.append(allocator, arg);
+
+    const parsed = try parseServeArgs(raw_args.items);
+    var owned_config_paths = std.ArrayList([]const u8).empty;
+    defer {
+        for (owned_config_paths.items) |path| allocator.free(path);
+        owned_config_paths.deinit(allocator);
+    }
+    var config_root: ?[]const u8 = null;
+    defer if (config_root) |root| allocator.free(root);
+
+    var loaded_config = try config_paths.loadIfPresent(allocator, parsed.config_path);
+    defer if (loaded_config) |*cfg| cfg.deinit(allocator);
+
+    const context = try resolveContext(allocator, parsed.raw, parsed.adb_path, parsed.xcrun_path, parsed.config_path, loaded_config, &owned_config_paths, &config_root);
+    switch (context.resolved.platform) {
+        .android => {
+            var device = try android.AndroidDevice.initWithShim(allocator, context.adb_path, context.resolved.serial, context.resolved.app_id, context.android_shim_path);
+            defer device.deinit();
+            try serveWithDevice(allocator, &device, parsed.transport, parsed.port, context.trace_dir, context.resolved.app_id, context.capture);
+        },
+        .ios => {
+            var device = try ios.IosDevice.initWithKindAndShim(allocator, context.xcrun_path, context.resolved.serial, context.resolved.app_id, iosTargetKind(context.resolved.ios_device_type), context.ios_shim_path);
+            defer device.deinit();
+            try serveWithDevice(allocator, &device, parsed.transport, parsed.port, context.trace_dir, context.resolved.app_id, context.capture);
+        },
+    }
+}
+
+pub fn runMcp(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {
+    var raw_args = std.ArrayList([]const u8).empty;
+    defer raw_args.deinit(allocator);
+    while (args.next()) |arg| try raw_args.append(allocator, arg);
+
+    const parsed = try parseMcpArgs(raw_args.items);
+    var owned_config_paths = std.ArrayList([]const u8).empty;
+    defer {
+        for (owned_config_paths.items) |path| allocator.free(path);
+        owned_config_paths.deinit(allocator);
+    }
+    var config_root: ?[]const u8 = null;
+    defer if (config_root) |root| allocator.free(root);
+
+    var loaded_config = try config_paths.loadIfPresent(allocator, parsed.config_path);
+    defer if (loaded_config) |*cfg| cfg.deinit(allocator);
+
+    const context = try resolveContext(allocator, parsed.raw, parsed.adb_path, parsed.xcrun_path, parsed.config_path, loaded_config, &owned_config_paths, &config_root);
+    switch (context.resolved.platform) {
+        .android => {
+            var device = try android.AndroidDevice.initWithShim(allocator, context.adb_path, context.resolved.serial, context.resolved.app_id, context.android_shim_path);
+            defer device.deinit();
+            try serveMcpWithDevice(allocator, &device, context.trace_dir, context.resolved.app_id, context.capture);
+        },
+        .ios => {
+            var device = try ios.IosDevice.initWithKindAndShim(allocator, context.xcrun_path, context.resolved.serial, context.resolved.app_id, iosTargetKind(context.resolved.ios_device_type), context.ios_shim_path);
+            defer device.deinit();
+            try serveMcpWithDevice(allocator, &device, context.trace_dir, context.resolved.app_id, context.capture);
+        },
+    }
+}
+
+fn parseCommonArg(
+    args: []const []const u8,
+    index: *usize,
+    raw: *run_options.RawServeOptions,
+    adb_path: *[]const u8,
+    xcrun_path: *[]const u8,
+    config_path: *?[]const u8,
+) !void {
+    const arg = args[index.*];
+    if (std.mem.eql(u8, arg, "--device")) {
+        index.* += 1;
+        raw.serial = if (index.* < args.len) args[index.*] else return error.MissingDeviceSerial;
+    } else if (std.mem.eql(u8, arg, "--app-id")) {
+        index.* += 1;
+        raw.app_id = if (index.* < args.len) args[index.*] else return error.MissingAppId;
+    } else if (std.mem.eql(u8, arg, "--trace-dir")) {
+        index.* += 1;
+        raw.trace_dir = if (index.* < args.len) args[index.*] else return error.MissingTraceDir;
+    } else if (std.mem.eql(u8, arg, "--adb")) {
+        index.* += 1;
+        adb_path.* = if (index.* < args.len) args[index.*] else return error.MissingAdbPath;
+    } else if (std.mem.eql(u8, arg, "--android-shim")) {
+        index.* += 1;
+        raw.android_shim_path = if (index.* < args.len) args[index.*] else return error.MissingAndroidShimPath;
+    } else if (std.mem.eql(u8, arg, "--xcrun")) {
+        index.* += 1;
+        xcrun_path.* = if (index.* < args.len) args[index.*] else return error.MissingXcrunPath;
+    } else if (std.mem.eql(u8, arg, "--ios-shim")) {
+        index.* += 1;
+        raw.ios_shim_path = if (index.* < args.len) args[index.*] else return error.MissingIosShimPath;
+    } else if (std.mem.eql(u8, arg, "--platform")) {
+        index.* += 1;
+        raw.platform = try parsePlatform(if (index.* < args.len) args[index.*] else return error.MissingPlatform);
+    } else if (std.mem.eql(u8, arg, "--ios-device-type")) {
+        index.* += 1;
+        raw.ios_device_type = try parseIosDeviceType(if (index.* < args.len) args[index.*] else return error.MissingIosDeviceType);
+    } else if (std.mem.eql(u8, arg, "--config")) {
+        index.* += 1;
+        config_path.* = if (index.* < args.len) args[index.*] else return error.MissingConfigPath;
+    } else {
+        return error.UnknownFlag;
+    }
+}
+
+fn resolveContext(
+    allocator: std.mem.Allocator,
+    raw: run_options.RawServeOptions,
+    explicit_adb_path: []const u8,
+    explicit_xcrun_path: []const u8,
+    config_path: ?[]const u8,
+    loaded_config: ?config.Config,
+    owned_config_paths: *std.ArrayList([]const u8),
+    config_root: *?[]const u8,
+) !ResolvedContext {
+    var adb_path = explicit_adb_path;
+    var xcrun_path = explicit_xcrun_path;
+    const actual_config_path = config_path orelse config_paths.default_path;
+
+    if (loaded_config) |cfg| {
+        config_root.* = try config_paths.rootForPath(allocator, actual_config_path);
+        if (std.mem.eql(u8, adb_path, "adb")) {
+            if (cfg.tools.adb_path) |path| adb_path = try config_paths.ownCommandPath(allocator, owned_config_paths, config_root.*.?, path);
+        }
+        if (std.mem.eql(u8, xcrun_path, "xcrun")) {
+            if (cfg.tools.xcrun_path) |path| xcrun_path = try config_paths.ownCommandPath(allocator, owned_config_paths, config_root.*.?, path);
+        }
+    }
+
+    const resolved = if (loaded_config) |cfg| run_options.resolveServe(raw, cfg) else run_options.resolveServe(raw, null);
+    const capture = if (loaded_config) |cfg| run_options.traceCapture(cfg) else trace.CaptureOptions{};
+    const trace_dir = if (raw.trace_dir == null and config_root.* != null and resolved.trace_dir != null)
+        try config_paths.ownFilePath(allocator, owned_config_paths, config_root.*.?, resolved.trace_dir.?)
+    else
+        resolved.trace_dir;
+    const android_shim_path = if (raw.android_shim_path == null and config_root.* != null and resolved.android_shim_path != null)
+        try config_paths.ownFilePath(allocator, owned_config_paths, config_root.*.?, resolved.android_shim_path.?)
+    else
+        resolved.android_shim_path;
+    const ios_shim_path = if (raw.ios_shim_path == null and config_root.* != null and resolved.ios_shim_path != null)
+        try config_paths.ownFilePath(allocator, owned_config_paths, config_root.*.?, resolved.ios_shim_path.?)
+    else
+        resolved.ios_shim_path;
+
+    return .{
+        .resolved = resolved,
+        .adb_path = adb_path,
+        .xcrun_path = xcrun_path,
+        .trace_dir = trace_dir,
+        .android_shim_path = android_shim_path,
+        .ios_shim_path = ios_shim_path,
+        .capture = capture,
+    };
+}
+
+fn serveMcpWithDevice(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    trace_dir: ?[]const u8,
+    app_id: []const u8,
+    capture: trace.CaptureOptions,
+) !void {
+    var trace_writer: ?trace.TraceWriter = null;
+    if (trace_dir) |dir| {
+        trace_writer = try trace.TraceWriter.initWithOptions(allocator, dir, capture);
+        try trace_writer.?.startManifest("mcp session", app_id);
+    }
+    defer if (trace_writer) |*tw| tw.deinit();
+    const live_trace = if (trace_writer) |*tw| tw else null;
+    try mcp.serveStdioWithTrace(allocator, device, live_trace);
+}
+
+fn serveWithDevice(
+    allocator: std.mem.Allocator,
+    device: anytype,
+    transport: []const u8,
+    port: u16,
+    trace_dir: ?[]const u8,
+    app_id: []const u8,
+    capture: trace.CaptureOptions,
+) !void {
+    var trace_writer: ?trace.TraceWriter = null;
+    if (trace_dir) |dir| {
+        trace_writer = try trace.TraceWriter.initWithOptions(allocator, dir, capture);
+        try trace_writer.?.startManifest("json-rpc session", app_id);
+    }
+    defer if (trace_writer) |*tw| tw.deinit();
+    const live_trace = if (trace_writer) |*tw| tw else null;
+
+    if (std.mem.eql(u8, transport, "stdio")) {
+        try json_rpc.serveStdioWithTrace(allocator, device, live_trace);
+    } else if (std.mem.eql(u8, transport, "tcp")) {
+        try json_rpc.serveTcpWithTrace(allocator, device, port, live_trace);
+    } else {
+        return error.UnsupportedTransport;
+    }
+}
+
+fn parsePlatform(value: []const u8) !run_options.Platform {
+    if (std.mem.eql(u8, value, "android")) return .android;
+    if (std.mem.eql(u8, value, "ios")) return .ios;
+    return error.UnsupportedPlatform;
+}
+
+fn parseIosDeviceType(value: []const u8) !run_options.IosDeviceType {
+    if (std.mem.eql(u8, value, "simulator")) return .simulator;
+    if (std.mem.eql(u8, value, "physical")) return .physical;
+    return error.UnsupportedIosDeviceType;
+}
+
+fn iosTargetKind(value: run_options.IosDeviceType) ios.TargetKind {
+    return switch (value) {
+        .simulator => .simulator,
+        .physical => .physical,
+    };
+}

package/src/cli_trace.zig

@@ -0,0 +1,111 @@
+const std = @import("std");
+
+const bundle = @import("bundle.zig");
+const report = @import("report.zig");
+
+pub const ReportArgs = struct {
+    input_path: []const u8,
+    out_path: ?[]const u8 = null,
+};
+
+pub const ExplainArgs = struct {
+    trace_dir: ?[]const u8 = null,
+    json: bool = false,
+};
+
+pub const ExportArgs = struct {
+    trace_dir: []const u8,
+    out_path: ?[]const u8 = null,
+    redact: bool = false,
+    omit_screenshots: bool = false,
+};
+
+pub fn parseReportArgs(args: []const []const u8) !ReportArgs {
+    if (args.len == 0) return error.MissingReportInput;
+    var parsed = ReportArgs{ .input_path = args[0] };
+
+    var index: usize = 1;
+    while (index < args.len) : (index += 1) {
+        const arg = args[index];
+        if (std.mem.eql(u8, arg, "--out")) {
+            index += 1;
+            parsed.out_path = if (index < args.len) args[index] else return error.MissingReportOutput;
+        } else {
+            return error.UnknownFlag;
+        }
+    }
+    if (parsed.out_path == null) return error.MissingReportOutput;
+    return parsed;
+}
+
+pub fn parseExplainArgs(args: []const []const u8) !ExplainArgs {
+    var parsed = ExplainArgs{};
+    for (args) |arg| {
+        if (std.mem.eql(u8, arg, "--json")) {
+            parsed.json = true;
+        } else if (parsed.trace_dir == null) {
+            parsed.trace_dir = arg;
+        } else {
+            return error.UnknownFlag;
+        }
+    }
+    if (parsed.trace_dir == null) return error.MissingTraceDir;
+    return parsed;
+}
+
+pub fn parseExportArgs(args: []const []const u8) !ExportArgs {
+    if (args.len == 0) return error.MissingTraceDir;
+    var parsed = ExportArgs{ .trace_dir = args[0] };
+
+    var index: usize = 1;
+    while (index < args.len) : (index += 1) {
+        const arg = args[index];
+        if (std.mem.eql(u8, arg, "--out")) {
+            index += 1;
+            parsed.out_path = if (index < args.len) args[index] else return error.MissingTraceBundleOutput;
+        } else if (std.mem.eql(u8, arg, "--redact")) {
+            parsed.redact = true;
+        } else if (std.mem.eql(u8, arg, "--omit-screenshots")) {
+            parsed.redact = true;
+            parsed.omit_screenshots = true;
+        } else {
+            return error.UnknownFlag;
+        }
+    }
+    if (parsed.out_path == null) return error.MissingTraceBundleOutput;
+    return parsed;
+}
+
+pub fn runReport(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {
+    var raw_args = std.ArrayList([]const u8).empty;
+    defer raw_args.deinit(allocator);
+    while (args.next()) |arg| try raw_args.append(allocator, arg);
+
+    const parsed = try parseReportArgs(raw_args.items);
+    try report.writeHtmlReport(allocator, parsed.input_path, parsed.out_path.?);
+    try std.fs.File.stdout().deprecatedWriter().print("wrote {s}\n", .{parsed.out_path.?});
+}
+
+pub fn runExplain(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {
+    var raw_args = std.ArrayList([]const u8).empty;
+    defer raw_args.deinit(allocator);
+    while (args.next()) |arg| try raw_args.append(allocator, arg);
+
+    const parsed = try parseExplainArgs(raw_args.items);
+    const stdout = std.fs.File.stdout().deprecatedWriter();
+    if (parsed.json) return try report.writeTraceExplanationJson(allocator, parsed.trace_dir.?, stdout);
+    try report.writeTraceExplanation(allocator, parsed.trace_dir.?, stdout);
+}
+
+pub fn runExport(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {
+    var raw_args = std.ArrayList([]const u8).empty;
+    defer raw_args.deinit(allocator);
+    while (args.next()) |arg| try raw_args.append(allocator, arg);
+
+    const parsed = try parseExportArgs(raw_args.items);
+    try bundle.exportTraceBundleWithOptions(allocator, parsed.trace_dir, parsed.out_path.?, .{
+        .redact = parsed.redact,
+        .omit_screenshots = parsed.omit_screenshots,
+    });
+    try std.fs.File.stdout().deprecatedWriter().print("wrote {s}\n", .{parsed.out_path.?});
+}