zeno-mobile-runner 0.1.2 → 0.1.8

package/docs/expo-smoke.md

@@ -0,0 +1,79 @@
+# Expo Smoke Test
+
+This is the quickest public smoke path for an Expo app. It proves that the npm
+package installs, the wizard scaffolds a scenario, ZMR can launch an iOS app,
+and the runner can produce screenshots, traces, HTML reports, JUnit XML, and
+redacted trace bundles.
+
+Run the flow below on a local iOS simulator before treating a specific app build
+as validated.
+
+```bash
+npx create-expo-app@latest /tmp/zmr-expo-smoke --template blank --yes
+cd /tmp/zmr-expo-smoke
+npm install --save-dev zeno-mobile-runner
+
+npx zmr-wizard --yes --dir . \
+  --app-id com.example.zenoexposmoke \
+  --ios \
+  --package-json
+```
+
+Boot a simulator, then build and launch the app:
+
+```bash
+xcrun simctl boot <simulator-udid>
+npx expo run:ios --device <simulator-name>
+```
+
+Run the generated ZMR scenario:
+
+```bash
+npx zmr run .zmr/ios-smoke.json \
+  --platform ios \
+  --device booted \
+  --trace-dir traces/zmr-ios \
+  --json
+
+npx zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml
+npx zmr export traces/zmr-ios --out traces/zmr-ios-redacted.zmrtrace --redact
+```
+
+Expected result shape:
+
+```json
+{
+  "ok": true,
+  "status": "passed",
+  "scenario": "iOS smoke",
+  "appId": "com.example.zenoexposmoke",
+  "traceDir": "traces/zmr-ios",
+  "eventCount": 8,
+  "snapshotCount": 2,
+  "partialFailureCount": 0
+}
+```
+
+This smoke validates the platform-level loop: app launch, health check,
+screenshot capture, trace collection, HTML/JUnit report generation, and
+redacted export. For selector-grade React Native or Expo assertions on iOS, add
+the XCTest shim described in [app integration](app-integration.md).
+
+Android follows the same pattern with a connected emulator or device:
+
+```bash
+npx zmr-wizard --yes --dir . \
+  --app-id com.example.zenoexposmoke \
+  --android \
+  --package-json
+
+npx zmr run .zmr/android-smoke.json \
+  --platform android \
+  --device emulator-5554 \
+  --trace-dir traces/zmr-android \
+  --json
+```
+
+Do not commit traces, screenshots, bundle identifiers, private app names, or
+credentials from a real product app. Use `zmr export --redact`, and add
+`--omit-screenshots` when visual artifacts may contain sensitive data.

package/docs/install.md

@@ -54,8 +54,9 @@ zig build-exe src/main.zig -target aarch64-macos.15.0 -O ReleaseSafe -femit-bin=
 ./zig-out/bin/zmr version
 ```
 
-On macOS hosts where Zig can infer the target, `zig build test` and `zig build`
-are also valid.
+On hosts where Zig can infer the target and locate the system SDK, `zig build`
+can also build the binary. The explicit target form above is the supported
+verification path used by CI and release gates.
 
 ## First Run Without A Device
 

package/docs/npm.md

@@ -68,6 +68,8 @@ This creates:
 `.zmr/AGENTS.md` gives AI agents an app-local operating note with strict
 doctor/validate commands, schema discovery, direct `zmr run` smoke commands,
 JSON-RPC and MCP startup commands, selector guidance, the exact
+`zmr discover --from-trace traces/zmr-agent --out .zmr/discovered/replay-smoke.json --include-actions --validate --json`
+trace-to-test command,
 `zmr explain traces/zmr-agent --json` failure-triage command, the exact
 `zmr export traces/zmr-agent --out traces/zmr-agent-redacted.zmrtrace --redact`
 redacted trace export command.
@@ -91,12 +93,12 @@ Add app-local scripts:
     "zmr:schemas": "zmr schemas --json",
     "zmr:validate": "zmr validate --json .zmr/android-smoke.json && zmr validate --json .zmr/ios-smoke.json",
     "zmr:android": "zmr run .zmr/android-smoke.json --device emulator-5554 --trace-dir traces/zmr-android",
-    "zmr:android:report": "zmr report traces/zmr-android --out traces/zmr-android/report.html",
-    "zmr:android:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id com.example.mobiletest --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && \"$ZMR_BIN\" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html",
+    "zmr:android:report": "zmr report traces/zmr-android --out traces/zmr-android/report.html --junit traces/zmr-android/junit.xml",
+    "zmr:android:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/android-smoke.json --device emulator-5554 --app-id com.example.mobiletest --runs 20 --trace-root traces/zmr-android-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 30000 && \"$ZMR_BIN\" report traces/zmr-android-reliability --out traces/zmr-android-reliability/report.html --junit traces/zmr-android-reliability/junit.xml",
     "zmr:matrix": "ZMR_BIN=${ZMR_BIN:-zmr} zmr-device-matrix --matrix .zmr/device-matrix.json --trace-root traces/zmr-matrix --min-pass-rate 100 --max-failures 0",
     "zmr:ios": "zmr run .zmr/ios-smoke.json --platform ios --device booted --trace-dir traces/zmr-ios",
-    "zmr:ios:report": "zmr report traces/zmr-ios --out traces/zmr-ios/report.html",
-    "zmr:ios:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id com.example.mobiletest --xcrun xcrun --runs 20 --trace-root traces/zmr-ios-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 45000 && \"$ZMR_BIN\" report traces/zmr-ios-reliability --out traces/zmr-ios-reliability/report.html",
+    "zmr:ios:report": "zmr report traces/zmr-ios --out traces/zmr-ios/report.html --junit traces/zmr-ios/junit.xml",
+    "zmr:ios:reliability": "export ZMR_BIN=\"${ZMR_BIN:-zmr}\"; zmr-benchmark --zmr .zmr/ios-smoke.json --platform ios --device booted --app-id com.example.mobiletest --xcrun xcrun --runs 20 --trace-root traces/zmr-ios-reliability --min-pass-rate 100 --max-failures 0 --max-p95-ms 45000 && \"$ZMR_BIN\" report traces/zmr-ios-reliability --out traces/zmr-ios-reliability/report.html --junit traces/zmr-ios-reliability/junit.xml",
     "zmr:pilot": "zmr-pilot-gate --android --ios --android-app-root . --android-app-id com.example.mobiletest --android-device emulator-5554 --ios-app-root . --ios-app-path ./build/Debug-iphonesimulator/Sample.app --ios-app-id com.example.mobiletest --ios-device booted --runs 20 --min-pass-rate 100 --max-failures 0 --evidence-out traces/zmr-pilots/evidence.jsonl",
     "zmr:readiness": "zmr-release-readiness --evidence traces/zmr-pilots/evidence.jsonl --target production --json",
     "zmr:serve": "zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent",
@@ -341,6 +343,58 @@ npm run pack:npm
 
 That command builds release binaries, copies them into `prebuilds/`, and runs `npm pack`.
 
+Tagged GitHub releases publish through npm trusted publishing, not a long-lived
+`NPM_TOKEN` secret. Configure the npm package trusted publisher before relying
+on the tag workflow:
+
+- Package: `zeno-mobile-runner`
+- Provider: GitHub Actions
+- Repository: `johnmikel/zeno-mobile-runner`
+- Workflow file: `release.yml`
+
+The release workflow already requests `id-token: write`, builds the npm tarball
+from the tag, attests the generated release artifacts, uploads the GitHub
+release assets, verifies exactly one local npm tarball exists under `./dist/`,
+and then publishes that tarball with public access.
+
+Trusted publishing requires a current npm runtime. The tag workflow uses Node
+24 so the npm CLI can exchange the GitHub Actions OIDC identity for publish
+authorization.
+
+### Manual publish with passkey or 2FA
+
+Use trusted publishing for normal tagged releases. If you need to publish a
+verified local tarball manually, authenticate first:
+
+```bash
+npm login --auth-type=web
+npm whoami
+```
+
+The browser/passkey step must finish before publishing. If `npm whoami` returns
+`E401 Unauthorized`, the local machine is not authenticated and `npm publish`
+will fail.
+
+Build and verify the package before publishing:
+
+```bash
+./scripts/ci-gate.sh
+npm pack --dry-run --json
+npm run pack:npm
+```
+
+Publish the generated tarball from `dist/`:
+
+```bash
+npm publish ./dist/zeno-mobile-runner-<version>.tgz --access public
+```
+
+If npm returns `E403` with a two-factor authentication message, the account or
+organization requires either a current interactive 2FA challenge or a granular
+automation token configured to bypass 2FA. For local passkey accounts, rerun
+`npm login --auth-type=web`, complete the passkey challenge in the browser, and
+confirm `npm whoami` before retrying the same `npm publish` command.
+
 ## Node API
 
 ```js

package/docs/production-readiness.md

@@ -0,0 +1,123 @@
+# Production Readiness
+
+ZMR is a public developer preview. The npm package is live, release artifacts
+are signed by GitHub release attestations, and local app teams can collect
+repeatable Android, iOS simulator, and physical iOS evidence. ZMR should not be
+called production-stable until the gates below are met and kept passing.
+
+## Current Release Standard
+
+Every public release should satisfy:
+
+- `bash tests/docs-readiness-test.sh`
+- `bash tests/public-safety-test.sh`
+- `npm test`
+- `zig test src/test_harness.zig -target aarch64-macos.15.0`
+- `./scripts/release-gate.sh`
+- `npm run pack:npm`
+- `./scripts/verify-release-artifacts.sh --dist dist`
+- at least one trace or benchmark report rendered with `zmr report --junit`,
+  or a pilot wrapper run that produced both `report.html` and `junit.xml`
+- a fresh npm install smoke:
+
+  ```bash
+  npm install --save-dev zeno-mobile-runner
+  npx zmr version --json
+  ```
+
+Tagged releases are expected to build release archives, generate
+`RELEASE_MANIFEST.json`, publish GitHub artifact attestations, upload release
+assets, and publish the npm tarball through trusted publishing after the npm
+package is configured with the `release.yml` trusted publisher.
+
+CI runs retain `traces/`, `zig-cache/coverage/`, and `zig-out/bin/zmr` for 14
+days when those files are produced. Tagged releases retain `dist/` as a
+workflow artifact for 30 days in addition to GitHub release assets.
+
+## Product Gates Before 1.0
+
+| Area | Required evidence | Current status |
+| --- | --- | --- |
+| Android emulator | 20-run pilot gate with zero failures and trace/report artifacts | Supported by `zmr-pilot-gate` and demo app |
+| Android physical device | 20-run pilot gate on a real connected device | Supported by ADB flow; app teams must collect evidence |
+| iOS simulator | 20-run pilot gate with XCTest shim selectors, screenshots, and reports | Supported by iOS demo and app-local shim |
+| iOS physical device | 20-run pilot gate on a real trusted device | Supported for lifecycle and shim screenshots; needs repeated public evidence |
+| React Native | Public setup guidance plus selector-grade app evidence using stable labels or ids | Guidance exists; repeated public demo evidence is still needed |
+| Expo | Public smoke, dev-client scaffold, and iOS/Android run evidence | Basic iOS smoke is documented; repeated matrix evidence is still needed |
+| Flutter | Platform-level Android/iOS smoke using semantics, deep links, and screenshots | Supported at platform level; widget-tree claims are intentionally out of scope |
+| Agent workflows | MCP and JSON-RPC loop with semantic snapshots, typed actions, traces, redacted export, guarded trace exploration, and scenario validation | Supported and enforced by the `agent workflow smoke` readiness gate; `zmr explore` is review-first and trace-backed, and an unbounded autonomous crawler is not shipped |
+| CI reporting | HTML reports plus JUnit XML artifacts from trace, benchmark, and pilot directories | Supported by `zmr report --junit` and pilot wrappers |
+| Trace privacy | Redacted export path, denylist/allowlist controls, and public-safety tests | Supported and gated |
+| Release supply chain | Trusted npm publish, GitHub artifact attestations, checksums, SBOM, and release manifest | Workflow is ready; npm trusted publisher must be configured in package settings |
+
+## Reliability Evidence
+
+Use repeated app-local pilots before making app or device claims:
+
+```bash
+zmr-pilot-gate \
+  --android \
+  --ios \
+  --android-app-root . \
+  --android-app-id com.example.mobiletest \
+  --android-device emulator-5554 \
+  --ios-app-root . \
+  --ios-app-path ./build/Debug-iphonesimulator/Sample.app \
+  --ios-app-id com.example.mobiletest \
+  --ios-device booted \
+  --ios-shim ./.zmr/ios-shim \
+  --runs 20 \
+  --min-pass-rate 100 \
+  --max-failures 0 \
+  --evidence-out traces/zmr-pilots/evidence.jsonl
+```
+
+Then summarize readiness:
+
+```bash
+zmr-release-readiness \
+  --evidence traces/zmr-pilots/evidence.jsonl \
+  --target production \
+  --json
+```
+
+Keep the generated evidence in the app repository unless it is fully redacted
+and safe to publish.
+
+## Agentic Standard
+
+ZMR is agentic when an external agent can work from structured state instead of
+screenscraping or guessing:
+
+- `zmr doctor --json` explains setup state and remediation.
+- `zmr schemas --json` exposes machine-readable contracts.
+- `zmr validate --json` catches scenario mistakes before device runs.
+- `zmr serve` exposes JSON-RPC for long-running sessions.
+- `zmr mcp` exposes MCP tools for semantic snapshots, typed actions, and
+  assertion-grade checks.
+- `zmr explain --json` summarizes failed traces.
+- `zmr report --junit` emits CI-compatible test results from trace and
+  benchmark evidence.
+- `zmr export --redact` produces shareable trace bundles.
+- `zmr-release-readiness --target production` requires the `agent workflow
+  smoke` gate, satisfied by a passed `./scripts/release-gate.sh` row or
+  structured evidence for MCP, JSON-RPC, semantic snapshots, typed actions,
+  trace events, trace explanation, trace discovery/exploration, scenario
+  validation, and redacted export.
+
+The safe discovery pattern is still external-agent-first: observe with
+`semantic_snapshot`, choose one typed action, record successful steps into a
+candidate scenario, validate it, rerun it deterministically, and require human
+review before committing generated tests.
+
+## Claims Policy
+
+- Claim Android and iOS app-level support only for flows that pass local pilot
+  evidence on the target device class.
+- Claim React Native and Expo support through app-level lifecycle, deep links,
+  accessibility labels, selectors, screenshots, traces, and reports.
+- Claim Flutter support at the Android/iOS app level when the app exposes stable
+  semantics, labels, ids, or deep links.
+- Do not claim Flutter widget-tree inspection, Dart state inspection, managed
+  device-farm coverage, or a built-in autonomous test writer until those
+  features exist and have public evidence.

package/docs/protocol-fixtures/core-session.responses.jsonl

@@ -1,4 +1,4 @@
-{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.2","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","trace.events","trace.export"]}}
+{"jsonrpc":"2.0","id":1,"result":{"name":"zmr","version":"0.1.8","protocolVersion":"2026-04-28","protocol":{"version":"2026-04-28","minimumCompatibleVersion":"2026-04-28","stability":"dev-preview","breakingChangePolicy":"version-and-changelog"},"platforms":["android","ios"],"platformSupport":{"android":{"status":"supported","deviceTypes":["emulator","physical"],"automation":["adb","uiautomator","android-shim"]},"ios":{"status":"supported","deviceTypes":["simulator","physical"],"automation":["simctl","devicectl","xctest-shim"],"physicalDevices":true}},"iosPreview":false,"transports":["stdio","tcp"],"methods":["runner.capabilities","device.list","session.create","session.close","app.install","app.launch","app.stop","app.openLink","app.clearState","observe.snapshot","observe.semanticSnapshot","ui.tap","ui.type","ui.eraseText","ui.hideKeyboard","ui.swipe","ui.pressBack","ui.scrollUntilVisible","wait.until","wait.any","wait.gone","assert.visible","assert.notVisible","assert.healthy","scenario.validate","trace.events","trace.explore","trace.discover","trace.explain","trace.export"]}}
 {"jsonrpc":"2.0","id":2,"result":[{"serial":"fake-device-1","state":"device","ready":true}]}
 {"jsonrpc":"2.0","id":3,"result":{"sessionId":"default"}}
 {"jsonrpc":"2.0","id":4,"result":true}