zig-mobile-runner 0.1.0

package/clients/swift/Sources/ZMRFakeSession/main.swift

@@ -0,0 +1,86 @@
+import Foundation
+import ZMRClient
+
+struct Options {
+    var zmr = "zig-out/bin/zmr"
+    var adb = "tests/fake-adb.sh"
+    var device = "fake-android-1"
+    var appID = "com.example.mobiletest"
+    var traceDir = "traces/demo-swift-client"
+    var traceOut = "traces/demo-swift-client-redacted.zmrtrace"
+}
+
+func parseOptions(_ arguments: [String]) throws -> Options {
+    var options = Options()
+    var index = 0
+    while index < arguments.count {
+        let argument = arguments[index]
+        guard index + 1 < arguments.count else {
+            throw NSError(domain: "ZMRFakeSession", code: 2, userInfo: [NSLocalizedDescriptionKey: "\(argument) requires a value"])
+        }
+        let value = arguments[index + 1]
+        switch argument {
+        case "--zmr": options.zmr = value
+        case "--adb": options.adb = value
+        case "--device": options.device = value
+        case "--app-id": options.appID = value
+        case "--trace-dir": options.traceDir = value
+        case "--trace-out": options.traceOut = value
+        default:
+            throw NSError(domain: "ZMRFakeSession", code: 2, userInfo: [NSLocalizedDescriptionKey: "unknown argument: \(argument)"])
+        }
+        index += 2
+    }
+    return options
+}
+
+func object(_ value: Any) throws -> [String: Any] {
+    guard let object = value as? [String: Any] else {
+        throw ZMRError.invalidResponse
+    }
+    return object
+}
+
+do {
+    let options = try parseOptions(Array(CommandLine.arguments.dropFirst()))
+    let client = ZMRClient(
+        executable: options.zmr,
+        arguments: [
+            "serve",
+            "--transport", "stdio",
+            "--device", options.device,
+            "--app-id", options.appID,
+            "--adb", options.adb,
+            "--trace-dir", options.traceDir
+        ]
+    )
+    try client.start()
+    defer { client.close() }
+
+    let capabilities = try object(try client.call("runner.capabilities"))
+    try client.createSession()
+    _ = try client.call("app.openLink", params: ["url": "exampleapp://swift-client"])
+    _ = try client.call("wait.until", params: ["visible": ["text": "Dashboard"], "timeoutMs": 1000])
+    _ = try client.call("ui.tap", params: ["selector": ["text": "Sign in"]])
+    _ = try client.call("ui.type", params: ["text": "agent@example.com", "selector": ["resourceId": "email-login-email-input"]])
+    _ = try client.call("assert.notVisible", params: ["selector": ["text": "Application has crashed"], "timeoutMs": 100])
+    _ = try client.assertHealthy(timeoutMs: 100)
+    let snapshot = try client.snapshot()
+    let exported = try object(try client.call("trace.export", params: ["out": options.traceOut, "redact": true, "includeScreenshots": true]))
+    let events = try object(try client.call("trace.events", params: ["afterSeq": 0, "limit": 10]))
+
+    let nodes = snapshot["nodes"] as? [Any] ?? []
+    let summary: [String: Any] = [
+        "protocolVersion": capabilities["protocolVersion"] ?? "",
+        "activePackage": snapshot["activePackage"] ?? "",
+        "nodes": nodes.count,
+        "events": events["nextSeq"] ?? 0,
+        "traceDir": options.traceDir,
+        "traceOut": exported["out"] ?? options.traceOut
+    ]
+    let data = try JSONSerialization.data(withJSONObject: summary, options: [.sortedKeys])
+    print(String(data: data, encoding: .utf8) ?? "{}")
+} catch {
+    fputs("\(error)\n", stderr)
+    exit(1)
+}

package/clients/typescript/README.md

@@ -0,0 +1,34 @@
+# ZMR TypeScript Reference Client
+
+Zero-dependency ESM client for ZMR's newline-delimited JSON-RPC protocol.
+
+```js
+import { createZmrClient } from "./index.mjs";
+
+const zmr = createZmrClient({
+  command: "zmr",
+  args: [
+    "serve",
+    "--transport", "stdio",
+    "--device", "emulator-5554",
+    "--app-id", "com.example.mobiletest",
+    "--trace-dir", "traces/agent-session",
+  ],
+});
+
+try {
+  await zmr.createSession();
+  await zmr.openLink("exampleapp://e2e-auth?probe=1");
+  await zmr.waitUntil({ text: "E2E auth probe" }, { timeoutMs: 30000 });
+  const snapshot = await zmr.snapshot();
+  const events = await zmr.traceEvents(0, { limit: 100 });
+  console.log(snapshot.nodes);
+  console.log(events.events.length);
+  await zmr.exportTrace("traces/agent-session-redacted.zmrtrace", { redact: true, omitScreenshots: true });
+} finally {
+  await zmr.close();
+}
+```
+
+The runtime is plain JavaScript (`index.mjs`) with TypeScript declarations
+(`index.d.ts`) so consumers can use it without a build step.

package/clients/typescript/examples/fake-session.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import path from "node:path";
+import url from "node:url";
+import { createZmrClient } from "../index.mjs";
+
+const root = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), "../../..");
+
+const zmr = createZmrClient({
+  command: path.join(root, "zig-out", "bin", "zmr"),
+  args: [
+    "serve",
+    "--transport", "stdio",
+    "--device", "fake-android-1",
+    "--app-id", "com.example.mobiletest",
+    "--adb", path.join(root, "tests", "fake-adb.sh"),
+    "--trace-dir", "traces/demo-typescript-client",
+  ],
+});
+
+try {
+  const capabilities = await zmr.capabilities();
+  await zmr.createSession();
+  await zmr.openLink("exampleapp://e2e-auth?probe=1");
+  await zmr.assertHealthy({ timeoutMs: 100 });
+  const snapshot = await zmr.snapshot();
+  const events = await zmr.traceEvents(0, { limit: 20 });
+  await zmr.exportTrace("traces/demo-typescript-client-redacted.zmrtrace", { redact: true, omitScreenshots: true });
+  console.log(JSON.stringify({
+    protocolVersion: capabilities.protocolVersion,
+    activePackage: snapshot.activePackage,
+    nodes: snapshot.nodes.length,
+    events: events.events.length,
+  }));
+} finally {
+  await zmr.close();
+}

package/clients/typescript/index.d.ts

@@ -0,0 +1,144 @@
+export interface ZmrClientOptions {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  stderr?: "inherit" | "ignore" | "pipe";
+}
+
+export interface Selector {
+  id?: string;
+  resourceId?: string;
+  text?: string;
+  textContains?: string;
+  contentDesc?: string;
+  contentDescContains?: string;
+  className?: string;
+}
+
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+export interface UiNode {
+  stableId: string;
+  className: string;
+  resourceId?: string | null;
+  text?: string | null;
+  contentDesc?: string | null;
+  bounds: { x: number; y: number; width: number; height: number };
+  enabled: boolean;
+  visible: boolean;
+  selected: boolean;
+}
+
+export interface ObservationSnapshot {
+  id: string;
+  timestampMs: number;
+  viewport: Viewport;
+  displayDensityDpi?: number | null;
+  activePackage?: string | null;
+  activeActivity?: string | null;
+  screenshotArtifact?: string | null;
+  treeArtifact?: string | null;
+  focusedNodeId?: string | null;
+  logDelta?: string | null;
+  nodes: UiNode[];
+}
+
+export interface SemanticNode {
+  id: string;
+  role: "button" | "textbox" | "switch" | "checkbox" | "radio" | "image" | "text" | "node" | string;
+  name: string;
+  selector: Record<string, string>;
+  source: {
+    className: string;
+    resourceId?: string | null;
+    text?: string | null;
+    contentDesc?: string | null;
+  };
+  bounds: { x: number; y: number; width: number; height: number; centerX: number; centerY: number };
+  enabled: boolean;
+  visible: boolean;
+  selected: boolean;
+  interactive: boolean;
+  recommendedAction?: "tap" | "type" | null | string;
+}
+
+export interface SemanticSnapshot {
+  id: string;
+  timestampMs: number;
+  viewport: Viewport;
+  activePackage?: string | null;
+  activeActivity?: string | null;
+  focusedNodeId?: string | null;
+  nodes: SemanticNode[];
+  summary: {
+    nodeCount: number;
+    interactiveCount: number;
+    visibleText: string[];
+  };
+}
+
+export interface PlatformSupport {
+  status: "supported" | "preview" | "unsupported" | string;
+  deviceTypes: string[];
+  automation: string[];
+  physicalDevices?: boolean;
+}
+
+export interface Capabilities {
+  name: string;
+  version: string;
+  protocolVersion: string;
+  platforms: string[];
+  platformSupport?: Record<string, PlatformSupport>;
+  iosPreview?: boolean;
+  transports: string[];
+  methods: string[];
+}
+
+export interface DeviceInfo {
+  serial: string;
+  state: string;
+  ready: boolean;
+}
+
+export interface ZmrClient {
+  request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  capabilities(): Promise<Capabilities>;
+  createSession(): Promise<{ sessionId: string }>;
+  closeSession(): Promise<boolean>;
+  devices(): Promise<DeviceInfo[]>;
+  launch(): Promise<boolean>;
+  stop(): Promise<boolean>;
+  clearState(): Promise<boolean>;
+  openLink(url: string): Promise<boolean>;
+  snapshot(): Promise<ObservationSnapshot>;
+  semanticSnapshot(): Promise<SemanticSnapshot>;
+  tap(selector: Selector): Promise<boolean>;
+  typeText(text: string, options?: { selector?: Selector }): Promise<boolean>;
+  eraseText(options?: { selector?: Selector; maxChars?: number }): Promise<boolean>;
+  hideKeyboard(): Promise<boolean>;
+  swipe(input: { x1: number; y1: number; x2: number; y2: number; durationMs?: number }): Promise<boolean>;
+  pressBack(): Promise<boolean>;
+  scrollUntilVisible(selector: Selector, options?: { direction?: "up" | "down"; timeoutMs?: number }): Promise<boolean>;
+  waitUntil(selector: Selector, options?: { timeoutMs?: number }): Promise<boolean>;
+  waitAny(selectors: Selector[], options?: { timeoutMs?: number }): Promise<{ matchedIndex: number } | false>;
+  waitGone(selector: Selector, options?: { timeoutMs?: number }): Promise<boolean>;
+  assertVisible(selector: Selector, options?: { timeoutMs?: number }): Promise<boolean>;
+  assertNotVisible(selector: Selector, options?: { timeoutMs?: number }): Promise<boolean>;
+  assertHealthy(options?: { timeoutMs?: number }): Promise<boolean>;
+  exportTrace(out: string, options?: { redact?: boolean; omitScreenshots?: boolean }): Promise<Record<string, unknown>>;
+  traceEvents(afterSeq?: number, options?: { limit?: number }): Promise<Record<string, unknown>>;
+  close(): Promise<void>;
+}
+
+export class ZmrRpcError extends Error {
+  code?: number;
+  publicCode?: string;
+  data?: unknown;
+}
+
+export function createZmrClient(options: ZmrClientOptions): ZmrClient;

package/clients/typescript/index.mjs

@@ -0,0 +1,192 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+export class ZmrRpcError extends Error {
+  constructor(error) {
+    super(error?.message || "ZMR JSON-RPC error");
+    this.name = "ZmrRpcError";
+    this.code = error?.code;
+    this.publicCode = error?.publicCode;
+    this.data = error?.data;
+  }
+}
+
+export function createZmrClient(options) {
+  return new ZmrClient(options);
+}
+
+export class ZmrClient {
+  #child;
+  #nextId = 1;
+  #pending = new Map();
+  #closed = false;
+
+  constructor(options) {
+    if (!options?.command) throw new Error("createZmrClient requires command");
+    this.#child = spawn(options.command, options.args ?? [], {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["pipe", "pipe", options.stderr ?? "inherit"],
+    });
+
+    const lines = readline.createInterface({ input: this.#child.stdout });
+    lines.on("line", (line) => this.#handleLine(line));
+    this.#child.on("error", (error) => this.#rejectAll(error));
+    this.#child.on("exit", (code, signal) => {
+      this.#closed = true;
+      if (this.#pending.size > 0) {
+        this.#rejectAll(new Error(`zmr process exited with ${signal ?? code}`));
+      }
+    });
+  }
+
+  request(method, params = {}) {
+    if (this.#closed) return Promise.reject(new Error("zmr client is closed"));
+    const id = this.#nextId++;
+    const message = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#child.stdin.write(`${JSON.stringify(message)}\n`, (error) => {
+        if (!error) return;
+        this.#pending.delete(id);
+        reject(error);
+      });
+    });
+  }
+
+  capabilities() {
+    return this.request("runner.capabilities", {});
+  }
+
+  createSession() {
+    return this.request("session.create", {});
+  }
+
+  closeSession() {
+    return this.request("session.close", {});
+  }
+
+  devices() {
+    return this.request("device.list", {});
+  }
+
+  launch() {
+    return this.request("app.launch", {});
+  }
+
+  stop() {
+    return this.request("app.stop", {});
+  }
+
+  clearState() {
+    return this.request("app.clearState", {});
+  }
+
+  openLink(url) {
+    return this.request("app.openLink", { url });
+  }
+
+  snapshot() {
+    return this.request("observe.snapshot", {});
+  }
+
+  semanticSnapshot() {
+    return this.request("observe.semanticSnapshot", {});
+  }
+
+  tap(selector) {
+    return this.request("ui.tap", { selector });
+  }
+
+  typeText(text, options = {}) {
+    return this.request("ui.type", { ...options, text });
+  }
+
+  eraseText(options = {}) {
+    return this.request("ui.eraseText", options);
+  }
+
+  hideKeyboard() {
+    return this.request("ui.hideKeyboard", {});
+  }
+
+  swipe(input) {
+    return this.request("ui.swipe", input);
+  }
+
+  pressBack() {
+    return this.request("ui.pressBack", {});
+  }
+
+  scrollUntilVisible(selector, options = {}) {
+    return this.request("ui.scrollUntilVisible", { selector, ...options });
+  }
+
+  waitUntil(selector, options = {}) {
+    return this.request("wait.until", { visible: selector, ...options });
+  }
+
+  waitAny(selectors, options = {}) {
+    return this.request("wait.any", { selectors, ...options });
+  }
+
+  waitGone(selector, options = {}) {
+    return this.request("wait.gone", { selector, ...options });
+  }
+
+  assertVisible(selector, options = {}) {
+    return this.request("assert.visible", { selector, ...options });
+  }
+
+  assertNotVisible(selector, options = {}) {
+    return this.request("assert.notVisible", { selector, ...options });
+  }
+
+  assertHealthy(options = {}) {
+    return this.request("assert.healthy", options);
+  }
+
+  exportTrace(out, options = {}) {
+    return this.request("trace.export", { out, ...options });
+  }
+
+  traceEvents(afterSeq = 0, options = {}) {
+    return this.request("trace.events", { afterSeq, ...options });
+  }
+
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#child.stdin.end();
+    if (this.#child.exitCode == null && this.#child.signalCode == null) {
+      this.#child.kill();
+    }
+  }
+
+  #handleLine(line) {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (error) {
+      this.#rejectAll(error);
+      return;
+    }
+
+    const pending = this.#pending.get(message.id);
+    if (!pending) return;
+    this.#pending.delete(message.id);
+    if (message.error) {
+      pending.reject(new ZmrRpcError(message.error));
+    } else {
+      pending.resolve(message.result);
+    }
+  }
+
+  #rejectAll(error) {
+    for (const pending of this.#pending.values()) {
+      pending.reject(error);
+    }
+    this.#pending.clear();
+  }
+}

package/clients/typescript/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@zmr/client",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "private": true
+}

package/docs/adr/0001-agent-native-runner-boundary.md

@@ -0,0 +1,31 @@
+# 0001: Agent-Native Runner Boundary
+
+## Status
+
+Accepted.
+
+## Context
+
+ZMR is intended for AI agents and deterministic automation, but embedding an
+LLM inside the runner would make device control harder to test, version, and
+secure. The runner needs a small, stable control surface that external agents,
+scripts, and SDKs can consume.
+
+## Decision
+
+ZMR does not embed an LLM. Zig owns orchestration, device control,
+JSON-RPC/session handling, scenario execution, wait/assertion logic, and trace
+generation. External agents decide what to do next by reading structured
+observations and calling typed actions.
+
+The public agent contract is JSON-RPC over stdio or localhost TCP, plus
+machine-readable CLI JSON and public schemas.
+
+## Consequences
+
+- The core runner remains deterministic and testable without model calls.
+- Agents can be swapped without changing device adapters.
+- Trace output records what happened at the protocol/action layer, which makes
+  failures explainable without replaying model reasoning.
+- Higher-level planning, natural-language test generation, and app-specific
+  heuristics belong in external clients or app-local `.zmr/` assets.

package/docs/adr/0002-app-local-zmr-contract.md

@@ -0,0 +1,39 @@
+# 0002: App-Local `.zmr/` Contract
+
+## Status
+
+Accepted.
+
+## Context
+
+Mobile app repositories need a predictable place for runner configuration,
+smoke scenarios, shim commands, and setup scripts. ZMR should be installable as
+an npm dev dependency, but it should also work from source checkouts and
+release archives.
+
+## Decision
+
+`.zmr/` is the app-local contract. The default config file is
+`.zmr/config.json`, validated by `schemas/config.schema.json`. ZMR commands
+auto-discover the config from the app checkout, and explicit CLI flags always
+override config defaults.
+
+`zmr-wizard` and `zmr init --app` scaffold the same shape:
+
+- `.zmr/config.json`
+- `.zmr/android-smoke.json`
+- `.zmr/ios-smoke.json`
+- `.zmr/AGENTS.md`
+- optional shim commands and source files
+- app package script suggestions
+- `traces/` ignored by default
+
+## Consequences
+
+- App-specific scenarios and private traces stay in the app repository, not in
+  the public ZMR repo.
+- npm, source, and release-archive installs share one integration model.
+- Agents can discover the same setup state humans use through `zmr doctor`,
+  `zmr schemas`, `.zmr/config.json`, and `.zmr/AGENTS.md`.
+- Generated files need backwards-compatible schema handling and clear
+  diagnostics because app repositories may pin older versions.

package/docs/adr/0003-ios-simulator-xctest-shim.md

@@ -0,0 +1,41 @@
+# 0003: iOS XCTest Shim
+
+## Status
+
+Accepted.
+
+## Context
+
+`xcrun simctl` is good for simulator lifecycle, screenshots, logs, deep links,
+and app install/launch, but it is not enough for robust selector-driven UI
+automation. `xcrun devicectl` provides physical-device lifecycle operations,
+but it still does not provide the selector-grade UI semantics ZMR needs. ZMR
+needs iOS behavior that matches Android scenario semantics where the platforms
+overlap.
+
+## Decision
+
+iOS support uses three layers:
+
+- `xcrun simctl` for lifecycle, install, launch, stop, open link, clear state,
+  screenshots, logs, and device discovery.
+- `xcrun devicectl` for physical-device discovery, install, launch, deep-link
+  launch, clear-state uninstall, and best-effort stop.
+- An app-local XCTest/XCUIAutomation shim for hierarchy snapshots, element
+  queries, screenshots, tap, type, erase text, keyboard control, swipe, and app
+  state on simulators and physical devices.
+
+V1 iOS clear-state semantics are best-effort app uninstall by bundle id.
+Physical-device log capture remains limited until a supported capture channel is
+available.
+
+## Consequences
+
+- iOS selector actions use platform automation APIs instead of coordinate-only
+  shelling.
+- App repositories must wire a UI test target when they need selector-grade iOS
+  runs.
+- The internal shim protocol can evolve during the dev preview, while public
+  behavior remains the ZMR CLI, scenario format, JSON-RPC methods, and schemas.
+- Physical iOS support depends on local signing, provisioning, Developer Mode,
+  pairing, and `devicectl` transport state.

package/docs/adr/0004-benchmark-claims-and-baseline-collection.md

@@ -0,0 +1,37 @@
+# 0004: Benchmark Claims And Baseline Collection
+
+## Status
+
+Accepted.
+
+## Context
+
+ZMR should eventually demonstrate speed, reliability, and diagnostics against
+existing app-local automation, but public fixtures cannot assume a private app,
+private credentials, or a specific third-party runner.
+
+## Decision
+
+Public ZMR benchmarking remains tool-agnostic:
+
+- `zmr-benchmark` records repeated ZMR scenario runs and can append rows to a
+  shared comparison JSONL file.
+- `zmr-benchmark-command` records repeated app-local baseline commands.
+- `zmr-compare-benchmarks` compares normalized candidate and baseline rows and
+  can enforce candidate pass-rate, failure-count, mean-speedup, and p95-speedup
+  gates.
+
+Public docs describe the measurement method and output shape. They do not make
+real-app speed claims unless equivalent candidate and baseline flows were run
+under the same local conditions and the report can be shared safely.
+
+## Consequences
+
+- Benchmark infrastructure is reusable without hardcoded private app details.
+- App teams can compare against whatever runner they already use by wrapping a
+  command.
+- CI can fail when a speed or reliability claim is not supported by the latest
+  repeated-run data.
+- Public performance statements require fair inputs: same app build, same
+  device/simulator state, same user path, repeated runs, and trace-backed
+  failure diagnostics.

package/docs/adr/README.md

@@ -0,0 +1,12 @@
+# Architecture Decisions
+
+Accepted architecture decisions for ZMR are recorded here so product docs,
+protocol docs, and implementation choices stay aligned.
+
+- [0001: Agent-Native Runner Boundary](0001-agent-native-runner-boundary.md)
+- [0002: App-Local `.zmr/` Contract](0002-app-local-zmr-contract.md)
+- [0003: iOS XCTest Shim](0003-ios-simulator-xctest-shim.md)
+- [0004: Benchmark Claims And Baseline Collection](0004-benchmark-claims-and-baseline-collection.md)
+
+ADRs describe current decisions, not permanent constraints. A later ADR can
+supersede an earlier decision when the product or support matrix changes.