zig-mobile-runner 0.1.0

package/src/trace_summary_diagnostic.zig

@@ -0,0 +1,202 @@
+const std = @import("std");
+const trace = @import("trace.zig");
+
+pub const DiagnosticEvent = struct {
+    kind: ?[]u8 = null,
+    status: ?[]u8 = null,
+    snapshot_id: ?[]u8 = null,
+    artifact_status: ?[]u8 = null,
+    semantic_status: ?[]u8 = null,
+    error_name: ?[]u8 = null,
+    screenshot_artifact: ?[]u8 = null,
+    source: ?[]u8 = null,
+    active_package: ?[]u8 = null,
+    active_activity: ?[]u8 = null,
+    visible_texts: ?[]u8 = null,
+    nearest_matches: ?[]u8 = null,
+
+    pub fn deinit(self: *DiagnosticEvent, allocator: std.mem.Allocator) void {
+        if (self.kind) |value| allocator.free(value);
+        if (self.status) |value| allocator.free(value);
+        if (self.snapshot_id) |value| allocator.free(value);
+        if (self.artifact_status) |value| allocator.free(value);
+        if (self.semantic_status) |value| allocator.free(value);
+        if (self.error_name) |value| allocator.free(value);
+        if (self.screenshot_artifact) |value| allocator.free(value);
+        if (self.source) |value| allocator.free(value);
+        if (self.active_package) |value| allocator.free(value);
+        if (self.active_activity) |value| allocator.free(value);
+        if (self.visible_texts) |value| allocator.free(value);
+        if (self.nearest_matches) |value| allocator.free(value);
+    }
+
+    pub fn fromPayload(allocator: std.mem.Allocator, kind_value: []const u8, payload: std.json.ObjectMap) !DiagnosticEvent {
+        return .{
+            .kind = try allocator.dupe(u8, kind_value),
+            .status = try dupeOptionalString(allocator, stringField(payload, "status")),
+            .snapshot_id = try dupeOptionalString(allocator, stringField(payload, "snapshotId")),
+            .artifact_status = try dupeOptionalString(allocator, stringField(payload, "artifactStatus")),
+            .semantic_status = try dupeOptionalString(allocator, stringField(payload, "semanticStatus")),
+            .error_name = try dupeOptionalString(allocator, stringField(payload, "error")),
+            .screenshot_artifact = try dupeOptionalString(allocator, stringField(payload, "screenshotArtifact")),
+            .source = try dupeOptionalString(allocator, stringField(payload, "source")),
+            .active_package = try dupeOptionalString(allocator, stringField(payload, "activePackage")),
+            .active_activity = try dupeOptionalString(allocator, stringField(payload, "activeActivity")),
+            .visible_texts = if (payload.get("visibleTexts")) |value| try joinStringArray(allocator, value, 8) else null,
+            .nearest_matches = if (payload.get("nearestTextMatches")) |value| try joinNearestMatches(allocator, value, 5) else null,
+        };
+    }
+};
+
+pub fn writeJson(writer: anytype, diagnostic: DiagnosticEvent) !void {
+    try writer.writeAll("{\"kind\":");
+    try trace.writeJsonString(writer, diagnostic.kind.?);
+    if (diagnostic.status) |value| {
+        try writer.writeAll(",\"status\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.snapshot_id) |value| {
+        try writer.writeAll(",\"snapshotId\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.artifact_status) |value| {
+        try writer.writeAll(",\"artifactStatus\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.semantic_status) |value| {
+        try writer.writeAll(",\"semanticStatus\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.error_name) |value| {
+        try writer.writeAll(",\"error\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.screenshot_artifact) |value| {
+        try writer.writeAll(",\"screenshotArtifact\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.source) |value| {
+        try writer.writeAll(",\"source\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.active_package) |value| {
+        try writer.writeAll(",\"activePackage\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.active_activity) |value| {
+        try writer.writeAll(",\"activeActivity\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (diagnostic.visible_texts) |value| {
+        try writer.writeAll(",\"visibleTexts\":");
+        try writeJoinedStringArrayJson(writer, value);
+    }
+    if (diagnostic.nearest_matches) |value| {
+        try writer.writeAll(",\"nearestTextMatches\":");
+        try writeJoinedStringArrayJson(writer, value);
+    }
+    try writer.writeAll("}");
+}
+
+pub fn writePartialJson(writer: anytype, partial: DiagnosticEvent) !void {
+    try writer.writeAll("{\"kind\":");
+    try trace.writeJsonString(writer, partial.kind.?);
+    if (partial.status) |value| {
+        try writer.writeAll(",\"status\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (partial.artifact_status) |value| {
+        try writer.writeAll(",\"artifactStatus\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (partial.semantic_status) |value| {
+        try writer.writeAll(",\"semanticStatus\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (partial.error_name) |value| {
+        try writer.writeAll(",\"error\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (partial.screenshot_artifact) |value| {
+        try writer.writeAll(",\"screenshotArtifact\":");
+        try trace.writeJsonString(writer, value);
+    }
+    if (partial.source) |value| {
+        try writer.writeAll(",\"source\":");
+        try trace.writeJsonString(writer, value);
+    }
+    try writer.writeAll("}");
+}
+
+fn writeJoinedStringArrayJson(writer: anytype, value: []const u8) !void {
+    try writer.writeAll("[");
+    var first = true;
+    var parts = std.mem.splitSequence(u8, value, " | ");
+    while (parts.next()) |part| {
+        if (!first) try writer.writeAll(",");
+        first = false;
+        try trace.writeJsonString(writer, part);
+    }
+    try writer.writeAll("]");
+}
+
+fn joinStringArray(allocator: std.mem.Allocator, value: std.json.Value, limit: usize) !?[]u8 {
+    if (value != .array or value.array.items.len == 0) return null;
+    var out = std.ArrayList(u8).empty;
+    errdefer out.deinit(allocator);
+    var written: usize = 0;
+    for (value.array.items) |item| {
+        if (item != .string) continue;
+        if (written > 0) try out.writer(allocator).writeAll(" | ");
+        try out.writer(allocator).writeAll(item.string);
+        written += 1;
+        if (written >= limit) break;
+    }
+    if (written == 0) {
+        out.deinit(allocator);
+        return null;
+    }
+    return try out.toOwnedSlice(allocator);
+}
+
+fn joinNearestMatches(allocator: std.mem.Allocator, value: std.json.Value, limit: usize) !?[]u8 {
+    if (value != .array or value.array.items.len == 0) return null;
+    var out = std.ArrayList(u8).empty;
+    errdefer out.deinit(allocator);
+    var written: usize = 0;
+    for (value.array.items) |item| {
+        if (item != .object) continue;
+        const text = stringField(item.object, "text") orelse continue;
+        if (written > 0) try out.writer(allocator).writeAll(" | ");
+        try out.writer(allocator).writeAll(text);
+        if (intField(item.object, "score")) |score| {
+            try out.writer(allocator).print(" (score {d})", .{score});
+        }
+        written += 1;
+        if (written >= limit) break;
+    }
+    if (written == 0) {
+        out.deinit(allocator);
+        return null;
+    }
+    return try out.toOwnedSlice(allocator);
+}
+
+fn dupeOptionalString(allocator: std.mem.Allocator, value: ?[]const u8) !?[]u8 {
+    if (value) |actual| return try allocator.dupe(u8, actual);
+    return null;
+}
+
+fn stringField(object: std.json.ObjectMap, key: []const u8) ?[]const u8 {
+    const value = object.get(key) orelse return null;
+    if (value != .string) return null;
+    return value.string;
+}
+
+fn intField(object: std.json.ObjectMap, key: []const u8) ?i64 {
+    const value = object.get(key) orelse return null;
+    return switch (value) {
+        .integer => |actual| actual,
+        else => null,
+    };
+}

package/src/types.zig

@@ -0,0 +1,120 @@
+const std = @import("std");
+
+pub const Allocator = std.mem.Allocator;
+
+pub const Bounds = struct {
+    x: i32 = 0,
+    y: i32 = 0,
+    width: i32 = 0,
+    height: i32 = 0,
+
+    pub fn centerX(self: Bounds) i32 {
+        return self.x + @divTrunc(self.width, 2);
+    }
+
+    pub fn centerY(self: Bounds) i32 {
+        return self.y + @divTrunc(self.height, 2);
+    }
+};
+
+pub const Viewport = struct {
+    width: u32 = 0,
+    height: u32 = 0,
+};
+
+pub const UiNode = struct {
+    stable_id: []const u8,
+    class_name: []const u8,
+    resource_id: ?[]const u8 = null,
+    text: ?[]const u8 = null,
+    content_desc: ?[]const u8 = null,
+    bounds: Bounds = .{},
+    enabled: bool = true,
+    visible: bool = true,
+    selected: bool = false,
+
+    pub fn deinit(self: UiNode, allocator: Allocator) void {
+        allocator.free(self.stable_id);
+        allocator.free(self.class_name);
+        if (self.resource_id) |value| allocator.free(value);
+        if (self.text) |value| allocator.free(value);
+        if (self.content_desc) |value| allocator.free(value);
+    }
+};
+
+pub const ObservationSnapshot = struct {
+    id: []const u8,
+    timestamp_ms: i64,
+    viewport: Viewport = .{},
+    display_density_dpi: ?u32 = null,
+    active_package: ?[]const u8 = null,
+    active_activity: ?[]const u8 = null,
+    screenshot_artifact: ?[]const u8 = null,
+    tree_artifact: ?[]const u8 = null,
+    focused_node_id: ?[]const u8 = null,
+    log_delta: ?[]const u8 = null,
+    nodes: []UiNode = &.{},
+
+    pub fn deinit(self: ObservationSnapshot, allocator: Allocator) void {
+        allocator.free(self.id);
+        if (self.active_package) |value| allocator.free(value);
+        if (self.active_activity) |value| allocator.free(value);
+        if (self.screenshot_artifact) |value| allocator.free(value);
+        if (self.tree_artifact) |value| allocator.free(value);
+        if (self.focused_node_id) |value| allocator.free(value);
+        if (self.log_delta) |value| allocator.free(value);
+        for (self.nodes) |node| node.deinit(allocator);
+        allocator.free(self.nodes);
+    }
+};
+
+pub const StructuredError = struct {
+    code: []const u8,
+    message: []const u8,
+
+    pub fn deinit(self: StructuredError, allocator: Allocator) void {
+        allocator.free(self.code);
+        allocator.free(self.message);
+    }
+};
+
+pub const ActionStatus = enum {
+    ok,
+    not_found,
+    timeout,
+    device_error,
+    protocol_error,
+};
+
+pub const ActionResult = struct {
+    status: ActionStatus,
+    elapsed_ms: u64,
+    action: []const u8,
+    target: ?[]const u8 = null,
+    before_snapshot_id: ?[]const u8 = null,
+    after_snapshot_id: ?[]const u8 = null,
+    err: ?StructuredError = null,
+
+    pub fn deinit(self: ActionResult, allocator: Allocator) void {
+        allocator.free(self.action);
+        if (self.target) |value| allocator.free(value);
+        if (self.before_snapshot_id) |value| allocator.free(value);
+        if (self.after_snapshot_id) |value| allocator.free(value);
+        if (self.err) |value| value.deinit(allocator);
+    }
+};
+
+pub const DeviceInfo = struct {
+    serial: []const u8,
+    state: []const u8,
+
+    pub fn deinit(self: DeviceInfo, allocator: Allocator) void {
+        allocator.free(self.serial);
+        allocator.free(self.state);
+    }
+};
+
+pub fn dupeOptional(allocator: Allocator, value: ?[]const u8) !?[]const u8 {
+    if (value) |actual| return try allocator.dupe(u8, actual);
+    return null;
+}

package/src/uiautomator.zig

@@ -0,0 +1,164 @@
+const std = @import("std");
+const types = @import("types.zig");
+
+pub fn parseHierarchy(allocator: std.mem.Allocator, xml: []const u8) ![]types.UiNode {
+    var nodes = std.ArrayList(types.UiNode).empty;
+    errdefer {
+        for (nodes.items) |node| node.deinit(allocator);
+        nodes.deinit(allocator);
+    }
+
+    var cursor: usize = 0;
+    var index: usize = 0;
+    while (std.mem.indexOfPos(u8, xml, cursor, "<node")) |start| {
+        const end = std.mem.indexOfScalarPos(u8, xml, start, '>') orelse break;
+        const tag = xml[start..end];
+        const class_name = try attrOwned(allocator, tag, "class") orelse try allocator.dupe(u8, "");
+        errdefer allocator.free(class_name);
+        const resource_id = try attrOwned(allocator, tag, "resource-id");
+        errdefer if (resource_id) |value| allocator.free(value);
+        var text = try attrOwned(allocator, tag, "text");
+        errdefer if (text) |value| allocator.free(value);
+        var content_desc = try attrOwned(allocator, tag, "content-desc");
+        errdefer if (content_desc) |value| allocator.free(value);
+        const bounds_text = try attrOwned(allocator, tag, "bounds");
+        defer if (bounds_text) |value| allocator.free(value);
+
+        const bounds = if (bounds_text) |value| parseBounds(value) catch types.Bounds{} else types.Bounds{};
+        const enabled = parseBoolAttr(tag, "enabled", true);
+        const selected = parseBoolAttr(tag, "selected", false);
+        const visible = bounds.width > 0 and bounds.height > 0;
+        text = emptyToNullOwned(allocator, text);
+        content_desc = emptyToNullOwned(allocator, content_desc);
+        const stable_id = try stableId(allocator, index, class_name, resource_id, text, content_desc, bounds);
+
+        try nodes.append(allocator, .{
+            .stable_id = stable_id,
+            .class_name = class_name,
+            .resource_id = resource_id,
+            .text = text,
+            .content_desc = content_desc,
+            .bounds = bounds,
+            .enabled = enabled,
+            .visible = visible,
+            .selected = selected,
+        });
+
+        index += 1;
+        cursor = end + 1;
+    }
+
+    return try nodes.toOwnedSlice(allocator);
+}
+
+fn emptyToNullOwned(allocator: std.mem.Allocator, value: ?[]const u8) ?[]const u8 {
+    if (value) |actual| {
+        if (actual.len == 0) {
+            allocator.free(actual);
+            return null;
+        }
+    }
+    return value;
+}
+
+fn attrOwned(allocator: std.mem.Allocator, tag: []const u8, name: []const u8) !?[]const u8 {
+    var cursor: usize = 0;
+    while (std.mem.indexOfPos(u8, tag, cursor, name)) |pos| {
+        const eq = pos + name.len;
+        if (eq + 1 < tag.len and tag[eq] == '=' and tag[eq + 1] == '"') {
+            const value_start = eq + 2;
+            const value_end = std.mem.indexOfScalarPos(u8, tag, value_start, '"') orelse return error.MalformedAttribute;
+            return try xmlUnescape(allocator, tag[value_start..value_end]);
+        }
+        cursor = pos + name.len;
+    }
+    return null;
+}
+
+fn xmlUnescape(allocator: std.mem.Allocator, input: []const u8) ![]const u8 {
+    var out = std.ArrayList(u8).empty;
+    errdefer out.deinit(allocator);
+    var i: usize = 0;
+    while (i < input.len) {
+        if (std.mem.startsWith(u8, input[i..], "&amp;")) {
+            try out.append(allocator, '&');
+            i += 5;
+        } else if (std.mem.startsWith(u8, input[i..], "&lt;")) {
+            try out.append(allocator, '<');
+            i += 4;
+        } else if (std.mem.startsWith(u8, input[i..], "&gt;")) {
+            try out.append(allocator, '>');
+            i += 4;
+        } else if (std.mem.startsWith(u8, input[i..], "&quot;")) {
+            try out.append(allocator, '"');
+            i += 6;
+        } else if (std.mem.startsWith(u8, input[i..], "&apos;")) {
+            try out.append(allocator, '\'');
+            i += 6;
+        } else {
+            try out.append(allocator, input[i]);
+            i += 1;
+        }
+    }
+    return try out.toOwnedSlice(allocator);
+}
+
+fn parseBoolAttr(tag: []const u8, name: []const u8, default_value: bool) bool {
+    var cursor: usize = 0;
+    while (std.mem.indexOfPos(u8, tag, cursor, name)) |pos| {
+        const eq = pos + name.len;
+        if (eq + 1 < tag.len and tag[eq] == '=' and tag[eq + 1] == '"') {
+            const value_start = eq + 2;
+            const value_end = std.mem.indexOfScalarPos(u8, tag, value_start, '"') orelse return default_value;
+            return std.mem.eql(u8, tag[value_start..value_end], "true");
+        }
+        cursor = pos + name.len;
+    }
+    return default_value;
+}
+
+pub fn parseBounds(input: []const u8) !types.Bounds {
+    if (input.len < 10 or input[0] != '[') return error.MalformedBounds;
+    const comma_1 = std.mem.indexOfScalar(u8, input, ',') orelse return error.MalformedBounds;
+    const close_1 = std.mem.indexOfScalarPos(u8, input, comma_1, ']') orelse return error.MalformedBounds;
+    const open_2 = std.mem.indexOfScalarPos(u8, input, close_1, '[') orelse return error.MalformedBounds;
+    const comma_2 = std.mem.indexOfScalarPos(u8, input, open_2, ',') orelse return error.MalformedBounds;
+    const close_2 = std.mem.indexOfScalarPos(u8, input, comma_2, ']') orelse return error.MalformedBounds;
+
+    const x1 = try std.fmt.parseInt(i32, input[1..comma_1], 10);
+    const y1 = try std.fmt.parseInt(i32, input[comma_1 + 1 .. close_1], 10);
+    const x2 = try std.fmt.parseInt(i32, input[open_2 + 1 .. comma_2], 10);
+    const y2 = try std.fmt.parseInt(i32, input[comma_2 + 1 .. close_2], 10);
+
+    return .{
+        .x = x1,
+        .y = y1,
+        .width = @max(0, x2 - x1),
+        .height = @max(0, y2 - y1),
+    };
+}
+
+fn stableId(
+    allocator: std.mem.Allocator,
+    index: usize,
+    class_name: []const u8,
+    resource_id: ?[]const u8,
+    text: ?[]const u8,
+    content_desc: ?[]const u8,
+    bounds: types.Bounds,
+) ![]const u8 {
+    if (resource_id) |value| {
+        if (value.len > 0) return try std.fmt.allocPrint(allocator, "rid:{s}:{d}", .{ value, index });
+    }
+    if (content_desc) |value| {
+        if (value.len > 0) return try std.fmt.allocPrint(allocator, "desc:{s}:{d}", .{ value, index });
+    }
+    if (text) |value| {
+        if (value.len > 0) return try std.fmt.allocPrint(allocator, "text:{s}:{d}", .{ value, index });
+    }
+    return try std.fmt.allocPrint(
+        allocator,
+        "node:{s}:{d}:{d}:{d}:{d}:{d}",
+        .{ class_name, bounds.x, bounds.y, bounds.width, bounds.height, index },
+    );
+}

package/src/validation.zig

@@ -0,0 +1,187 @@
+const std = @import("std");
+const errors = @import("errors.zig");
+const scenario = @import("scenario.zig");
+
+pub const Result = struct {
+    ok: bool,
+    name: ?[]const u8 = null,
+    app_id: ?[]const u8 = null,
+    step_count: usize = 0,
+    error_code: ?[]const u8 = null,
+    message: ?[]const u8 = null,
+    path: ?[]const u8 = null,
+    line: ?usize = null,
+    column: ?usize = null,
+
+    pub fn deinit(self: Result, allocator: std.mem.Allocator) void {
+        if (self.name) |value| allocator.free(value);
+        if (self.app_id) |value| allocator.free(value);
+        if (self.error_code) |value| allocator.free(value);
+        if (self.message) |value| allocator.free(value);
+        if (self.path) |value| allocator.free(value);
+    }
+};
+
+pub fn validateFile(allocator: std.mem.Allocator, path: []const u8) !Result {
+    const content = std.fs.cwd().readFileAlloc(allocator, path, 16 * 1024 * 1024) catch |err| return failure(allocator, null, err);
+    defer allocator.free(content);
+    const script = scenario.parseSlice(allocator, content) catch |err| return failure(allocator, content, err);
+    defer script.deinit(allocator);
+    return success(allocator, script);
+}
+
+pub fn validateSlice(allocator: std.mem.Allocator, content: []const u8) !Result {
+    const script = scenario.parseSlice(allocator, content) catch |err| return failure(allocator, content, err);
+    defer script.deinit(allocator);
+    return success(allocator, script);
+}
+
+fn success(allocator: std.mem.Allocator, script: scenario.Scenario) !Result {
+    return .{
+        .ok = true,
+        .name = try allocator.dupe(u8, script.name),
+        .app_id = try dupeOptionalString(allocator, script.app_id),
+        .step_count = script.steps.len,
+    };
+}
+
+fn dupeOptionalString(allocator: std.mem.Allocator, value: ?[]const u8) !?[]u8 {
+    if (value) |actual| return try allocator.dupe(u8, actual);
+    return null;
+}
+
+fn failure(allocator: std.mem.Allocator, content: ?[]const u8, err: anyerror) !Result {
+    const classified = errors.classify(err);
+    const diagnostic = if (content) |actual| try diagnoseFailure(allocator, actual, err) else Diagnostic{};
+    errdefer diagnostic.deinit(allocator);
+    const code = if (diagnostic.line != null and diagnostic.path == null and std.mem.eql(u8, classified.code, "internal.error"))
+        "scenario.invalid"
+    else
+        classified.code;
+    const message = if (diagnostic.line != null and diagnostic.path == null and std.mem.eql(u8, classified.code, "internal.error"))
+        "malformed scenario json"
+    else
+        classified.message;
+    return .{
+        .ok = false,
+        .error_code = try allocator.dupe(u8, code),
+        .message = try allocator.dupe(u8, message),
+        .path = diagnostic.path,
+        .line = diagnostic.line,
+        .column = diagnostic.column,
+    };
+}
+
+const Diagnostic = struct {
+    path: ?[]const u8 = null,
+    line: ?usize = null,
+    column: ?usize = null,
+
+    fn deinit(self: Diagnostic, allocator: std.mem.Allocator) void {
+        if (self.path) |value| allocator.free(value);
+    }
+};
+
+fn diagnoseFailure(allocator: std.mem.Allocator, content: []const u8, err: anyerror) !Diagnostic {
+    if (syntaxLocation(allocator, content)) |location| return location;
+    return switch (err) {
+        error.ScenarioMustBeObject => try pathDiagnostic(allocator, content, "$", null),
+        error.ScenarioMissingSteps,
+        error.ScenarioStepsMustBeArray,
+        => try pathDiagnostic(allocator, content, "$.steps", "steps"),
+        error.StepMissingAction,
+        error.StepActionMustBeString,
+        error.UnknownAction,
+        error.UnknownScenarioAction,
+        => try pathDiagnostic(allocator, content, "$.steps[].action", "action"),
+        error.UnknownScrollDirection,
+        => try pathDiagnostic(allocator, content, "$.steps[].direction", "direction"),
+        error.StepMissingUrl,
+        => try pathDiagnostic(allocator, content, "$.steps[].url", "url"),
+        error.StepMissingText,
+        => try pathDiagnostic(allocator, content, "$.steps[].text", "text"),
+        error.StepMissingX1,
+        => try pathDiagnostic(allocator, content, "$.steps[].x1", "x1"),
+        error.StepMissingY1,
+        => try pathDiagnostic(allocator, content, "$.steps[].y1", "y1"),
+        error.StepMissingX2,
+        => try pathDiagnostic(allocator, content, "$.steps[].x2", "x2"),
+        error.StepMissingY2,
+        => try pathDiagnostic(allocator, content, "$.steps[].y2", "y2"),
+        error.MissingSelector,
+        error.StepMissingSelector,
+        error.SelectorMustNotBeEmpty,
+        => try pathDiagnostic(allocator, content, "$.steps[].selector", "selector"),
+        error.MissingSelectors,
+        error.StepMissingSelectors,
+        error.SelectorsMustBeArray,
+        error.SelectorsMustNotBeEmpty,
+        => try pathDiagnostic(allocator, content, "$.steps[].selectors", "selectors"),
+        else => .{},
+    };
+}
+
+fn syntaxLocation(allocator: std.mem.Allocator, content: []const u8) ?Diagnostic {
+    var scanner = std.json.Scanner.initCompleteInput(allocator, content);
+    defer scanner.deinit();
+    var diagnostics = std.json.Diagnostics{};
+    scanner.enableDiagnostics(&diagnostics);
+    const parsed = std.json.parseFromTokenSource(std.json.Value, allocator, &scanner, .{}) catch {
+        return .{
+            .line = @as(usize, @intCast(diagnostics.getLine())),
+            .column = @as(usize, @intCast(diagnostics.getColumn())),
+        };
+    };
+    parsed.deinit();
+    return null;
+}
+
+fn pathDiagnostic(allocator: std.mem.Allocator, content: []const u8, path: []const u8, key: ?[]const u8) !Diagnostic {
+    var diagnostic = Diagnostic{ .path = try allocator.dupe(u8, path) };
+    if (key) |actual| {
+        if (findJsonKeyOffset(allocator, content, actual)) |offset| {
+            const location = lineColumnForOffset(content, offset);
+            diagnostic.line = location.line;
+            diagnostic.column = location.column;
+        }
+    } else {
+        const offset = firstNonWhitespaceOffset(content) orelse 0;
+        const location = lineColumnForOffset(content, offset);
+        diagnostic.line = location.line;
+        diagnostic.column = location.column;
+    }
+    return diagnostic;
+}
+
+fn findJsonKeyOffset(allocator: std.mem.Allocator, content: []const u8, key: []const u8) ?usize {
+    const needle = std.fmt.allocPrint(allocator, "\"{s}\"", .{key}) catch return null;
+    defer allocator.free(needle);
+    return std.mem.indexOf(u8, content, needle);
+}
+
+fn firstNonWhitespaceOffset(content: []const u8) ?usize {
+    for (content, 0..) |byte, index| switch (byte) {
+        ' ', '\t', '\r', '\n' => {},
+        else => return index,
+    };
+    return null;
+}
+
+const SourceLocation = struct {
+    line: usize,
+    column: usize,
+};
+
+fn lineColumnForOffset(content: []const u8, offset: usize) SourceLocation {
+    var line: usize = 1;
+    var column: usize = 1;
+    for (content[0..@min(offset, content.len)]) |byte| {
+        if (byte == '\n') {
+            line += 1;
+            column = 1;
+        } else {
+            column += 1;
+        }
+    }
+    return .{ .line = line, .column = column };
+}

package/src/version.zig

@@ -0,0 +1,22 @@
+pub const runner_version = "0.1.0";
+pub const protocol_version = "2026-04-28";
+pub const protocol_min_compatible_version = "2026-04-28";
+pub const protocol_stability = "dev-preview";
+pub const protocol_breaking_change_policy = "version-and-changelog";
+
+pub fn writePlain(writer: anytype) !void {
+    try writer.print("zmr {s} protocol {s}\n", .{ runner_version, protocol_version });
+}
+
+pub fn writeJson(writer: anytype) !void {
+    try writer.print(
+        "{{\"name\":\"zmr\",\"version\":\"{s}\",\"protocolVersion\":\"{s}\",\"minimumCompatibleProtocolVersion\":\"{s}\",\"stability\":\"{s}\",\"breakingChangePolicy\":\"{s}\"}}\n",
+        .{
+            runner_version,
+            protocol_version,
+            protocol_min_compatible_version,
+            protocol_stability,
+            protocol_breaking_change_policy,
+        },
+    );
+}