zig-mobile-runner 0.1.0

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,255 @@
+# Zig Mobile Runner
+
+> Agent-native mobile UI automation for Android, iOS simulators, and physical iOS devices.
+
+[![CI](https://github.com/johnmikel/zig-mobile-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/johnmikel/zig-mobile-runner/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/johnmikel/zig-mobile-runner?include_prereleases)](https://github.com/johnmikel/zig-mobile-runner/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+ZMR gives AI agents and test harnesses a typed mobile control plane: observe the
+app, choose an action, wait for the UI to settle, assert state, and export a
+replayable trace. The runner does not embed an LLM. Agents stay outside and use
+ZMR through JSON-RPC, CLI JSON, scenarios, and language clients.
+
+## Why ZMR
+
+- **AI-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 release artifacts.
+- **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.
+
+## Install
+
+Inside a mobile app repo:
+
+```bash
+# Available after the npm registry package is published:
+npm install --save-dev zig-mobile-runner
+npx zmr-wizard --app-id com.example.mobiletest --package-json
+npx zmr doctor --strict --json --config .zmr/config.json
+```
+
+For Expo development builds, add `--expo-dev-client-scheme <scheme>` to the
+wizard command.
+
+Today, install the release tarball from GitHub:
+
+```bash
+npm install --save-dev https://github.com/johnmikel/zig-mobile-runner/releases/download/v0.1.0/zig-mobile-runner-0.1.0.tgz
+npx zmr-wizard --app-id com.example.mobiletest --package-json
+npx zmr doctor --strict --json --config .zmr/config.json
+```
+
+From source:
+
+```bash
+git clone https://github.com/johnmikel/zig-mobile-runner.git
+cd zig-mobile-runner
+zig build-exe src/main.zig -target aarch64-macos.15.0 -O Debug -femit-bin=zig-out/bin/zmr
+./zig-out/bin/zmr version
+```
+
+Release archives and npm tarballs are attached to GitHub releases. The npm
+registry package is pending publish.
+
+Homebrew is the preferred binary install for teams that do not use JavaScript:
+
+```bash
+brew install --build-from-source ./dist/homebrew/zmr.rb
+```
+
+## Try It
+
+No device required:
+
+```bash
+./scripts/demo.sh
+```
+
+Real iOS simulator demo:
+
+```bash
+npx zmr-demo-ios --out /tmp/zmr-ios-demo --device booted
+```
+
+The demo command boots an available simulator when none is already running.
+
+Android app-local pilot:
+
+```bash
+zmr-pilot-gate \
+  --android \
+  --android-app-root /path/to/mobile-app \
+  --android-app-id com.example.mobiletest \
+  --android-device emulator-5554 \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl
+```
+
+iOS app-local pilot:
+
+```bash
+zmr-pilot-gate \
+  --ios \
+  --ios-app-root /path/to/mobile-app \
+  --ios-app-path /path/to/mobile-app/build/Debug-iphonesimulator/Sample.app \
+  --ios-app-id com.example.mobiletest \
+  --ios-device booted \
+  --ios-shim /path/to/mobile-app/.zmr/ios-shim \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --evidence-out /path/to/mobile-app/traces/zmr-pilots/evidence.jsonl
+```
+
+## Scenario Example
+
+ZMR scenarios are JSON today because JSON is strict, schema-validatable, and
+easy for agents and code generators to emit.
+
+```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 }
+  ]
+}
+```
+
+Validate before touching a device:
+
+```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
+```
+
+Stable JSON outputs are documented with schemas:
+`version-output.schema.json`, `schemas-output.schema.json`,
+`capabilities-output.schema.json`, `init-output.schema.json`,
+`devices-output.schema.json`, `validate-output.schema.json`,
+`run-output.schema.json`, `explain-output.schema.json`,
+`semantic-snapshot.schema.json`, `release-manifest.schema.json`,
+`release-readiness-output.schema.json`, and `RELEASE_MANIFEST.json`.
+
+See [docs/dsl.md](docs/dsl.md) for the DSL decision and roadmap.
+
+## Agent And Language 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.
+
+```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`.
+
+| 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` |
+
+Rust uses `src/lib.rs` because that is the idiomatic crate layout. TypeScript
+uses `index.mjs` plus declarations, Python uses a pip-installable module, Go
+uses a package directory under `clients/go/zmr`, Swift uses SwiftPM, and Kotlin
+uses Gradle.
+
+See [clients/README.md](clients/README.md), [docs/client-installation.md](docs/client-installation.md),
+and [docs/ai-agents.md](docs/ai-agents.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, evidence-gated | `devicectl` lifecycle plus app-local XCTest/XCUIAutomation shim; run the physical pilot before claiming device reliability |
+| Cloud device farms | Not yet | Planned after local matrix certification |
+
+Current release: `0.1.0` developer preview. Protocol version:
+`2026-04-28`. Latest local coverage run: `94.40%` line coverage.
+
+## Documentation
+
+- [FEATURES.md](FEATURES.md): complete feature list and limitations
+- [docs/install.md](docs/install.md): source, archive, npm, and app setup
+- [docs/app-integration.md](docs/app-integration.md): app-side Android/iOS shims
+- [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/dsl.md](docs/dsl.md): scenario DSL decision and roadmap
+- [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/market-positioning.md](docs/market-positioning.md): competitive positioning
+- [docs/adr/](docs/adr/): architecture decision records
+- [docs/shipping.md](docs/shipping.md): release gate and support matrix
+- [docs/release-audit.md](docs/release-audit.md): prompt-to-artifact completion audit
+- [docs/trace-privacy.md](docs/trace-privacy.md): safe trace export
+- [skills/zmr-mobile-testing/SKILL.md](skills/zmr-mobile-testing/SKILL.md): reusable agent skill
+
+## Release Gate
+
+Before publishing:
+
+```bash
+./scripts/release-gate.sh
+./scripts/build-release.sh
+./scripts/verify-release-artifacts.sh
+npm pack --dry-run
+```
+
+The release gate runs formatting, shell syntax checks, client tests, public
+safety scans, Zig tests, the no-device demo, coverage, archive generation,
+checksum/manifest verification, host archive smoke, and npm package dry-run.
+
+Release-candidate evidence can be checked explicitly:
+
+```bash
+zmr-release-readiness --evidence traces/release-candidate/<run>/evidence.jsonl \
+  --target dev-preview
+```
+
+Use `--target production` only after repeated real app/device pilots exist, and
+`--target market-claim` only after same-host/device benchmark comparison
+evidence exists.
+
+## 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,144 @@
+# 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.
+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, Python, Go, and Rust clients expose the same core 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.
+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/zig-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/zig-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/zig-mobile-runner.git vendor/zig-mobile-runner
+```
+
+```toml
+[dependencies]
+zmr-client = { path = "vendor/zig-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/zig-mobile-runner.git vendor/zig-mobile-runner
+```
+
+```swift
+.package(path: "vendor/zig-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/zig-mobile-runner.git vendor/zig-mobile-runner
+gradle -p vendor/zig-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/zig-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/zig-mobile-runner/clients/go
+
+go 1.22