zeno-mobile-runner 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Mikel Regida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# Zeno Mobile Runner
+
+> Agent-native mobile UI automation for React Native, Expo, Flutter, and native Android/iOS apps.
+
+[![CI](https://github.com/johnmikel/zeno-mobile-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/johnmikel/zeno-mobile-runner/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/johnmikel/zeno-mobile-runner?include_prereleases)](https://github.com/johnmikel/zeno-mobile-runner/releases)
+[![npm](https://img.shields.io/npm/v/zeno-mobile-runner)](https://www.npmjs.com/package/zeno-mobile-runner)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+ZMR gives AI agents and test harnesses a typed mobile control plane. It can
+install and launch apps, observe the UI, choose an action, wait for the screen to
+settle, assert state, and export a replayable trace. The runner does not embed an
+LLM. Agents stay outside and use ZMR through CLI JSON, scenarios, JSON-RPC, MCP,
+or optional protocol clients.
+
+## Install
+
+Inside a mobile app repo:
+
+```bash
+npm install --save-dev zeno-mobile-runner
+npx zmr-wizard --app-id com.example.mobiletest --package-json
+npx zmr doctor --strict --json --config .zmr/config.json
+```
+
+Run a generated smoke scenario:
+
+```bash
+npm run zmr:validate
+npm run zmr:android
+npm run zmr:ios
+```
+
+## React Native, Expo, and Flutter
+
+ZMR works below the JavaScript or Dart framework layer. It drives the installed
+Android or iOS app through platform lifecycle commands, deep links, accessibility
+semantics, screenshots, logs, selector actions, waits, assertions, and traces.
+
+- **React Native:** prefer `testID`, `accessibilityLabel`, stable text, and deep
+  links for direct navigation into important states.
+- **Expo development builds:** pass `--expo-dev-client-scheme <scheme>` to the
+  wizard so ZMR scaffolds dev-client open-link scenarios.
+- **Flutter:** ZMR supports Flutter apps at the Android and iOS app level when
+  the app exposes stable semantics labels, text, deep links, or native ids. It is
+  not a Flutter widget-tree driver and does not inspect Flutter internals.
+- **Native Android/iOS:** use resource ids, content descriptions, accessibility
+  identifiers, XCTest labels, and app-owned deep links.
+
+See [docs/frameworks.md](docs/frameworks.md) and
+[docs/app-integration.md](docs/app-integration.md) for app-side setup guidance.
+
+## Why ZMR
+
+- **Agent-native protocol:** structured snapshots, semantic mobile trees,
+  actions, waits, assertions, live trace events, and redacted trace export over
+  JSON-RPC or MCP.
+- **Trace-first debugging:** every run can produce screenshots, UI trees, logs,
+  timings, action inputs, assertion results, and an HTML report.
+- **Fast local core:** Zig owns orchestration, subprocess control, selectors,
+  waits, retries, scenario execution, and packaged binaries.
+- **App-local setup:** `.zmr/config.json`, smoke scenarios, shim commands, and
+  traces live in the app repo.
+- **Android and iOS:** Android uses ADB/UI Automator plus an optional native
+  shim. iOS simulators use `simctl`; physical iOS devices use `devicectl`;
+  selector-grade iOS automation uses the XCTest/XCUIAutomation shim.
+
+## Scenario Example
+
+ZMR scenarios are JSON so agents and build scripts can generate, validate, and
+mutate them without a second DSL.
+
+```json
+{
+  "name": "Login smoke",
+  "appId": "com.example.mobiletest",
+  "steps": [
+    { "action": "launch" },
+    { "action": "assertHealthy", "timeoutMs": 5000 },
+    { "action": "tap", "selector": { "resourceId": "email" } },
+    { "action": "typeText", "text": "user@example.com" },
+    { "action": "tap", "selector": { "resourceId": "password" } },
+    { "action": "typeText", "text": "password" },
+    { "action": "tap", "selector": { "text": "Login" } },
+    { "action": "waitVisible", "selector": { "text": "Welcome" }, "timeoutMs": 30000 }
+  ]
+}
+```
+
+Useful commands:
+
+```bash
+zmr version --json
+zmr schemas --json
+zmr devices --json
+zmr init --app --json --dir . --app-id com.example.mobiletest
+zmr validate --json .zmr/login-smoke.json
+zmr run .zmr/login-smoke.json --json --trace-dir traces/login-smoke
+zmr explain --json traces/login-smoke
+zmr import flow-yaml .zmr/legacy-flow.yaml --out .zmr/legacy-flow.json
+zmr export traces/login-smoke --out traces/login-smoke-redacted.zmrtrace --redact
+```
+
+See [docs/scenario-authoring.md](docs/scenario-authoring.md) for selector and
+wait guidance.
+
+## Agent Workflow
+
+Agents can use the CLI, JSON-RPC, or MCP surface. Start JSON-RPC over stdio:
+
+```bash
+zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+Agents that support the Model Context Protocol can use the native MCP surface:
+
+```bash
+zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+The MCP server exposes mobile-specific tools such as `semantic_snapshot`, `tap`,
+`type`, `wait_visible`, `trace_events`, and `trace_export`.
+
+## Optional Protocol Clients
+
+Clients are thin wrappers around `zmr serve --transport stdio`. They do not
+replace the runner; they make it easier for agents and test code to call the
+same JSON-RPC protocol.
+
+TypeScript and Python are the most common starting points for app teams and
+agent harnesses. Go, Rust, Swift, and Kotlin clients are reference integrations
+for teams that want to embed the protocol from those ecosystems.
+
+| Language | Entry point | Example |
+| --- | --- | --- |
+| TypeScript | `clients/typescript/index.mjs` + `index.d.ts` | `node clients/typescript/examples/fake-session.mjs` |
+| Python | `clients/python/zmr_client.py` + `pyproject.toml` | `python3 clients/python/examples/fake_session.py` |
+| Go | `clients/go/zmr/client.go` | `go run ./clients/go/examples/fake-session` |
+| Rust | `clients/rust/src/lib.rs` | `cargo run --manifest-path clients/rust/Cargo.toml --example fake_session` |
+| Swift | `clients/swift/Sources/ZMRClient` | `swift build --package-path clients/swift` |
+| Kotlin | `clients/kotlin/src/main/kotlin/dev/zmr` | `gradle -p clients/kotlin build` |
+
+See [clients/README.md](clients/README.md), [docs/clients.md](docs/clients.md),
+and [docs/client-installation.md](docs/client-installation.md).
+
+## Platform Support
+
+| Target | Status | Notes |
+| --- | --- | --- |
+| Android emulator | Supported | ADB/UI Automator, optional Android shim, emulator lifecycle helpers |
+| Android physical device | Supported | Requires ADB connection and app build/install surface |
+| iOS simulator | Supported | `simctl` plus app-local XCTest/XCUIAutomation shim for native selector actions, native waits, and bounded snapshots |
+| iOS physical device | Supported, validate locally | `devicectl` lifecycle plus app-local XCTest/XCUIAutomation shim; run pilots on your own app/device before relying on it in CI |
+| Cloud device farms | Not included | ZMR is focused on local and self-managed device targets in this preview |
+
+Current release: `0.1.2` developer preview. Protocol version:
+`2026-04-28`.
+
+## Documentation
+
+- [FEATURES.md](FEATURES.md): complete feature list and limitations
+- [docs/install.md](docs/install.md): source, npm, Homebrew, and app setup
+- [docs/frameworks.md](docs/frameworks.md): React Native, Expo, Flutter, and native app guidance
+- [docs/app-integration.md](docs/app-integration.md): app-side Android/iOS shims
+- [docs/scenario-authoring.md](docs/scenario-authoring.md): selectors, waits, and scenario design
+- [docs/protocol.md](docs/protocol.md): JSON-RPC methods and schemas
+- [docs/ai-agents.md](docs/ai-agents.md): JSON-RPC and MCP agent workflows
+- [docs/clients.md](docs/clients.md): language client guide
+- [docs/client-installation.md](docs/client-installation.md): npm, Homebrew, TS, Python, Go, Rust, Swift, and Kotlin setup
+- [docs/trace-privacy.md](docs/trace-privacy.md): safe trace export
+- [docs/troubleshooting.md](docs/troubleshooting.md): common setup and runtime issues
+- [skills/zmr-mobile-testing/SKILL.md](skills/zmr-mobile-testing/SKILL.md): reusable agent skill
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+ZMR is a local mobile automation runner. It can collect screenshots, UI trees,
+logs, app ids, device metadata, and scenario inputs. Treat raw traces as
+sensitive.
+
+## Supported Versions
+
+The current supported line is `0.1.x` dev preview. Security fixes should target
+the latest dev-preview branch until a stable release exists.
+
+## Reporting A Vulnerability
+
+Open a private security advisory on GitHub when available. If private advisory
+reporting is not enabled, contact the repository maintainer through the channel
+listed in the project profile.
+
+Include:
+
+- ZMR version and platform.
+- Reproduction steps.
+- Whether the issue exposes screenshots, logs, trace data, credentials, or
+  device access.
+- A minimal scenario or redacted trace bundle when possible.
+
+Do not publish raw traces from private apps in public issues.
+
+## Trace Handling
+
+- Use `zmr export --redact` before sharing trace bundles.
+- Do not share raw screenshot artifacts from private apps.
+- Do not paste logs that include tokens, emails, API keys, or device identifiers.
+- Prefer fake-device reproductions for public bug reports.
+

package/build.zig

@@ -0,0 +1,38 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe = b.addExecutable(.{
+        .name = "zmr",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/main.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+
+    b.installArtifact(exe);
+
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
+
+    const run_step = b.step("run", "Run zmr");
+    run_step.dependOn(&run_cmd.step);
+
+    const unit_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/main.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    const run_unit_tests = b.addRunArtifact(unit_tests);
+
+    const test_step = b.step("test", "Run unit tests");
+    test_step.dependOn(&run_unit_tests.step);
+}

package/build.zig.zon

@@ -0,0 +1,7 @@
+.{
+    .name = .zig_mobile_runner,
+    .version = "0.0.1",
+    .minimum_zig_version = "0.15.2",
+    .paths = .{""},
+    .fingerprint = 0x5a9670ea13a33fab,
+}

package/clients/README.md

@@ -0,0 +1,149 @@
+# ZMR Language Clients
+
+ZMR clients are small wrappers around the same newline-delimited JSON-RPC
+protocol exposed by:
+
+```bash
+zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent
+```
+
+They are intended for AI agents, CI harnesses, and app teams that want typed
+or idiomatic calls without reimplementing JSON-RPC framing. TypeScript and
+Python are the most direct starting points for app and agent automation. Go,
+Rust, Swift, and Kotlin stay available as reference integrations for teams that
+want to embed host-side orchestration in those ecosystems.
+Each client includes `devices()` for `device.list`, including the portable
+`ready` boolean, and a semantic snapshot helper for `observe.semanticSnapshot`
+so agents can work from normalized roles, selectors, bounds, and recommended
+actions instead of raw platform hierarchy classes.
+The TypeScript and Python clients expose the broadest app-facing control
+surface: session lifecycle, app launch/stop/link/state, snapshot and semantic
+snapshot, tap/type/erase/hide-keyboard/swipe/back/scroll, waits, assertions,
+trace event polling, and trace export. The Go, Rust, Swift, and Kotlin clients
+show the same protocol shape in other host languages and are useful starting
+points for custom integration work.
+Use the `assertHealthy`/`assert_healthy` helper after launches, links, and major
+navigation steps to catch native crash overlays and development-client failures
+without hand-maintaining negative selectors in every client.
+
+For install commands across package managers, see
+[docs/client-installation.md](../docs/client-installation.md).
+
+## TypeScript
+
+Runtime: `clients/typescript/index.mjs`
+Types: `clients/typescript/index.d.ts`
+
+```bash
+node clients/typescript/examples/fake-session.mjs
+```
+
+```js
+import { createZmrClient } from "./clients/typescript/index.mjs";
+
+const zmr = createZmrClient({
+  command: "zmr",
+  args: ["serve", "--transport", "stdio", "--config", ".zmr/config.json"],
+});
+```
+
+## Python
+
+Runtime: `clients/python/zmr_client.py`
+
+```bash
+python3 -m pip install "git+https://github.com/johnmikel/zeno-mobile-runner.git#subdirectory=clients/python"
+```
+
+```bash
+python3 clients/python/examples/fake_session.py
+```
+
+```python
+from zmr_client import ZmrClient
+
+with ZmrClient("zmr", ["serve", "--transport", "stdio", "--config", ".zmr/config.json"]) as zmr:
+    snapshot = zmr.snapshot()
+```
+
+## Go
+
+Runtime: `clients/go/zmr/client.go`
+
+```bash
+go get github.com/johnmikel/zeno-mobile-runner/clients/go@main
+```
+
+```bash
+go run ./clients/go/examples/fake-session \
+  --zmr ./zig-out/bin/zmr \
+  --adb ./tests/fake-adb.sh \
+  --trace-dir traces/demo-go-client
+```
+
+```go
+client, err := zmr.Start(ctx, "zmr", "serve", "--transport", "stdio", "--config", ".zmr/config.json")
+```
+
+## Rust
+
+Runtime: `clients/rust/src/lib.rs`
+
+Cargo packages library code from `src/lib.rs` by convention. Because this repo
+is not yet published as a Rust crate, consume the client from a local checkout:
+
+```bash
+git submodule add https://github.com/johnmikel/zeno-mobile-runner.git vendor/zeno-mobile-runner
+```
+
+```toml
+[dependencies]
+zmr-client = { path = "vendor/zeno-mobile-runner/clients/rust" }
+```
+
+```bash
+cargo run --manifest-path clients/rust/Cargo.toml --example fake_session -- \
+  --zmr ./zig-out/bin/zmr \
+  --adb ./tests/fake-adb.sh \
+  --trace-dir traces/demo-rust-client
+```
+
+```rust
+let mut client = zmr_client::Client::start("zmr", ["serve", "--transport", "stdio", "--config", ".zmr/config.json"])?;
+let snapshot = client.snapshot()?;
+```
+
+## Swift
+
+Runtime: `clients/swift/Sources/ZMRClient/ZMRClient.swift`
+
+Use the Swift client from a local SwiftPM package path until it is published as
+a standalone Swift package:
+
+```bash
+git submodule add https://github.com/johnmikel/zeno-mobile-runner.git vendor/zeno-mobile-runner
+```
+
+```swift
+.package(path: "vendor/zeno-mobile-runner/clients/swift")
+```
+
+Swift is useful for macOS host-side automation next to iOS app code. It is not
+an SDK embedded in the app under test.
+
+## Kotlin
+
+Runtime: `clients/kotlin/src/main/kotlin/dev/zmr/ZmrClient.kt`
+
+```bash
+git submodule add https://github.com/johnmikel/zeno-mobile-runner.git vendor/zeno-mobile-runner
+gradle -p vendor/zeno-mobile-runner/clients/kotlin build
+```
+
+Kotlin is useful for Android teams that want host-side orchestration in Kotlin.
+It still drives the external `zmr` binary.
+
+Rust has `src/lib.rs` because Cargo packages libraries from that path by
+convention. The other clients use the equivalent idiomatic layout for their
+ecosystem: ESM entry file for TypeScript, a pip-installable Python module, a Go
+package directory, a SwiftPM package, and a Gradle/Kotlin source package.

package/clients/go/README.md

@@ -0,0 +1,24 @@
+# ZMR Go Client
+
+Small standard-library JSON-RPC client for driving `zmr serve --transport stdio`
+from Go agents and test harnesses.
+
+```go
+client, err := zmr.Start(ctx, "zmr", "serve", "--transport", "stdio")
+if err != nil {
+    panic(err)
+}
+defer client.Close()
+
+snapshot, err := client.Snapshot(ctx)
+healthy, err := client.AssertHealthy(ctx, 1000)
+```
+
+Run the fake-session example from the repository root:
+
+```sh
+go run ./clients/go/examples/fake-session \
+  --zmr ./zig-out/bin/zmr \
+  --adb ./tests/fake-adb.sh \
+  --trace-dir traces/demo-go-client
+```

package/clients/go/examples/fake-session/main.go

@@ -0,0 +1,93 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/johnmikel/zeno-mobile-runner/clients/go/zmr"
+)
+
+func main() {
+	zmrBin := flag.String("zmr", "zig-out/bin/zmr", "zmr executable")
+	adb := flag.String("adb", "tests/fake-adb.sh", "adb executable or fake adb script")
+	device := flag.String("device", "fake-android-1", "device serial")
+	appID := flag.String("app-id", "com.example.mobiletest", "app id")
+	traceDir := flag.String("trace-dir", "traces/demo-go-client", "trace directory")
+	traceOut := flag.String("trace-out", "traces/demo-go-client-redacted.zmrtrace", "trace export path")
+	flag.Parse()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	client, err := zmr.Start(ctx,
+		*zmrBin,
+		"serve",
+		"--transport", "stdio",
+		"--device", *device,
+		"--app-id", *appID,
+		"--adb", *adb,
+		"--trace-dir", *traceDir,
+	)
+	if err != nil {
+		fail(err)
+	}
+	defer client.Close()
+
+	capabilities, err := client.Capabilities(ctx)
+	if err != nil {
+		fail(err)
+	}
+	if _, err := client.CreateSession(ctx); err != nil {
+		fail(err)
+	}
+	if _, err := client.OpenLink(ctx, "exampleapp://go-client"); err != nil {
+		fail(err)
+	}
+	if _, err := client.WaitUntil(ctx, map[string]interface{}{"text": "Dashboard"}, 1000); err != nil {
+		fail(err)
+	}
+	if _, err := client.Tap(ctx, map[string]interface{}{"text": "Sign in"}); err != nil {
+		fail(err)
+	}
+	if _, err := client.TypeText(ctx, "agent@example.com", map[string]interface{}{"resourceId": "email-login-email-input"}); err != nil {
+		fail(err)
+	}
+	if _, err := client.AssertNotVisible(ctx, map[string]interface{}{"text": "Application has crashed"}, 100); err != nil {
+		fail(err)
+	}
+	if _, err := client.AssertHealthy(ctx, 100); err != nil {
+		fail(err)
+	}
+	snapshot, err := client.Snapshot(ctx)
+	if err != nil {
+		fail(err)
+	}
+	exported, err := client.ExportTrace(ctx, *traceOut, true, true)
+	if err != nil {
+		fail(err)
+	}
+	events, err := client.TraceEvents(ctx, 0, 10)
+	if err != nil {
+		fail(err)
+	}
+
+	summary := map[string]interface{}{
+		"protocolVersion": capabilities.ProtocolVersion,
+		"activePackage":   snapshot.ActivePackage,
+		"nodes":           len(snapshot.Nodes),
+		"events":          events.NextSeq,
+		"traceDir":        *traceDir,
+		"traceOut":        exported.Out,
+	}
+	encoded, _ := json.Marshal(summary)
+	fmt.Println(string(encoded))
+}
+
+func fail(err error) {
+	fmt.Fprintln(os.Stderr, err)
+	os.Exit(1)
+}

package/clients/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/johnmikel/zeno-mobile-runner/clients/go
+
+go 1.22