zig-mobile-runner 0.1.0

package/schemas/README.md

@@ -0,0 +1,26 @@
+# ZMR Schemas
+
+This directory contains draft 2020-12 JSON Schemas for public ZMR file and protocol payloads.
+
+- `scenario.schema.json`: scenario files consumed by `zmr run` and `zmr validate`
+- `snapshot.schema.json`: `ObservationSnapshot` JSON emitted by live RPC and persisted trace snapshots, including viewport and optional display density metrics
+- `semantic-snapshot.schema.json`: agent-optimized semantic tree emitted by `observe.semanticSnapshot` and `zmr mcp` `semantic_snapshot`
+- `action-result.schema.json`: typed action result shape reserved for richer protocol responses
+- `trace-event.schema.json`: one JSONL event row from `events.jsonl`
+- `trace-manifest.schema.json`: `trace.json` summary for one traced run
+- `json-rpc.schema.json`: JSON-RPC requests and responses used by `zmr serve`
+- `zmr-config.schema.json`: app-local `.zmr/config.json` defaults used by the CLI and npm wizard, including Android emulator lifecycle defaults
+- `doctor-output.schema.json`: machine-readable `zmr doctor --json` setup diagnostics, including remediation hints for actionable checks
+- `init-output.schema.json`: machine-readable `zmr init --json` bootstrap output for scenario and app-local `.zmr/` initialization
+- `import-output.schema.json`: machine-readable `zmr import --json` output for one-time scenario migration helpers
+- `devices-output.schema.json`: machine-readable `zmr devices --json` output for Android, iOS simulator, and physical iOS discovery
+- `validate-output.schema.json`: machine-readable `zmr validate --json` scenario preflight output
+- `version-output.schema.json`: machine-readable `zmr version --json` output for runner and protocol compatibility discovery
+- `capabilities-output.schema.json`: machine-readable `runner.capabilities` JSON-RPC result for protocol, platform support, transport, and method discovery
+- `explain-output.schema.json`: machine-readable `zmr explain --json` failure triage output for agents and CI
+- `run-output.schema.json`: machine-readable `zmr run --json` terminal run summary output
+- `release-manifest.schema.json`: machine-readable `RELEASE_MANIFEST.json` emitted with release archives
+- `release-readiness-output.schema.json`: machine-readable `zmr-release-readiness --json` release evidence gate output
+- `schemas-output.schema.json`: machine-readable `zmr schemas --json` index of public schema names, paths, ids, and descriptions
+
+The Zig test suite verifies these files parse as JSON. Full schema validation is intentionally left to client tooling for now.

package/schemas/action-result.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/action-result.schema.json",
+  "title": "ZMR ActionResult",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "elapsedMs", "action"],
+  "properties": {
+    "status": {
+      "enum": ["ok", "not_found", "timeout", "device_error", "protocol_error"]
+    },
+    "elapsedMs": { "type": "integer", "minimum": 0 },
+    "action": { "type": "string" },
+    "target": { "type": ["string", "null"] },
+    "beforeSnapshotId": { "type": ["string", "null"] },
+    "afterSnapshotId": { "type": ["string", "null"] },
+    "error": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "type": "string" },
+        "message": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/capabilities-output.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/capabilities-output.schema.json",
+  "title": "ZMR Capabilities Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name",
+    "version",
+    "protocolVersion",
+    "protocol",
+    "platforms",
+    "platformSupport",
+    "iosPreview",
+    "transports",
+    "methods"
+  ],
+  "properties": {
+    "name": { "const": "zmr" },
+    "version": { "type": "string", "minLength": 1 },
+    "protocolVersion": { "type": "string", "minLength": 1 },
+    "protocol": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "minimumCompatibleVersion",
+        "stability",
+        "breakingChangePolicy"
+      ],
+      "properties": {
+        "version": { "type": "string", "minLength": 1 },
+        "minimumCompatibleVersion": { "type": "string", "minLength": 1 },
+        "stability": { "type": "string", "minLength": 1 },
+        "breakingChangePolicy": { "type": "string", "minLength": 1 }
+      }
+    },
+    "platforms": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "enum": ["android", "ios"] },
+      "uniqueItems": true
+    },
+    "platformSupport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["android", "ios"],
+      "properties": {
+        "android": { "$ref": "#/$defs/platformSupport" },
+        "ios": {
+          "allOf": [{ "$ref": "#/$defs/platformSupport" }],
+          "required": ["status", "deviceTypes", "automation", "physicalDevices"],
+          "properties": {
+            "physicalDevices": { "const": true }
+          }
+        }
+      }
+    },
+    "iosPreview": { "const": false },
+    "transports": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "enum": ["stdio", "tcp"] },
+      "uniqueItems": true
+    },
+    "methods": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  },
+  "$defs": {
+    "platformSupport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "deviceTypes", "automation"],
+      "properties": {
+        "status": { "enum": ["supported", "preview", "unsupported"] },
+        "deviceTypes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": ["emulator", "physical", "simulator"]
+          },
+          "uniqueItems": true
+        },
+        "automation": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "physicalDevices": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/devices-output.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/devices-output.schema.json",
+  "title": "ZMR Devices Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["platform", "count", "devices"],
+  "properties": {
+    "platform": { "enum": ["android", "ios"] },
+    "count": { "type": "integer", "minimum": 0 },
+    "devices": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["serial", "state", "ready"],
+        "properties": {
+          "serial": { "type": "string", "minLength": 1 },
+          "state": { "type": "string", "minLength": 1 },
+          "ready": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

package/schemas/doctor-output.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/doctor-output.schema.json",
+  "title": "ZMR Doctor Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "checks"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "checks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/check" }
+    }
+  },
+  "$defs": {
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "status", "detail"],
+      "properties": {
+        "name": {
+          "enum": [
+            "zig",
+            "config",
+            "adb",
+            "android-devices",
+            "android-shim",
+            "android-smoke-scenario",
+            "xcrun",
+            "ios-simulators",
+            "ios-physical-devices",
+            "ios-shim",
+            "ios-smoke-scenario"
+          ]
+        },
+        "status": { "enum": ["ok", "warning", "missing"] },
+        "errorCode": { "type": "string", "minLength": 1 },
+        "detail": { "type": "string" },
+        "count": { "type": "integer", "minimum": 0 },
+        "readyCount": { "type": "integer", "minimum": 0 },
+        "scriptCount": { "type": "integer", "minimum": 0 },
+        "scriptNames": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "fieldPath": { "type": "string", "minLength": 1 },
+        "hint": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/explain-output.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/explain-output.schema.json",
+  "title": "ZMR Explain Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "scenario", "status"],
+  "properties": {
+    "ok": { "const": true },
+    "traceDir": { "type": "string", "minLength": 1 },
+    "scenario": { "type": "string" },
+    "status": { "type": "string", "minLength": 1 },
+    "appId": { "type": "string", "minLength": 1 },
+    "durationMs": { "type": "integer", "minimum": 0 },
+    "eventCount": { "type": "integer", "minimum": 0 },
+    "snapshotCount": { "type": "integer", "minimum": 0 },
+    "failedStepIndex": { "type": "integer", "minimum": 0 },
+    "error": { "type": "string", "minLength": 1 },
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 },
+        "snapshotId": { "type": "string", "minLength": 1 },
+        "artifactStatus": { "type": "string", "minLength": 1 },
+        "semanticStatus": { "type": "string", "minLength": 1 },
+        "error": { "type": "string", "minLength": 1 },
+        "screenshotArtifact": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "activePackage": { "type": "string", "minLength": 1 },
+        "activeActivity": { "type": "string", "minLength": 1 },
+        "visibleTexts": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "nearestTextMatches": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "lastEvent": { "type": "string", "minLength": 1 },
+    "nextCommands": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/schemas/import-output.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/import-output.schema.json",
+  "title": "ZMR Import Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "format", "source", "out", "name", "appId", "stepCount", "next", "nextCommands"],
+  "properties": {
+    "ok": { "const": true },
+    "format": { "enum": ["flow-yaml"] },
+    "source": { "type": "string", "minLength": 1 },
+    "out": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "appId": { "type": ["string", "null"] },
+    "stepCount": { "type": "integer", "minimum": 0 },
+    "next": { "type": "string", "minLength": 1 },
+    "nextCommands": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/schemas/init-output.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/init-output.schema.json",
+  "title": "ZMR Init Output",
+  "oneOf": [
+    { "$ref": "#/$defs/appInit" },
+    { "$ref": "#/$defs/scenarioInit" }
+  ],
+  "$defs": {
+    "appInit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ok", "mode", "dir", "appId", "created", "configPath", "deviceMatrixPath", "agentInstructionsPath", "next", "nextCommands", "smokeCommands"],
+      "properties": {
+        "ok": { "const": true },
+        "mode": { "const": "app" },
+        "dir": { "type": "string", "minLength": 1 },
+        "appId": { "type": "string", "minLength": 1 },
+        "created": {
+          "type": "array",
+          "minItems": 4,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "configPath": { "type": "string", "minLength": 1 },
+        "androidScenarioPath": { "type": "string", "minLength": 1 },
+        "iosScenarioPath": { "type": "string", "minLength": 1 },
+        "androidDevClientScenarioPath": { "type": "string", "minLength": 1 },
+        "iosDevClientScenarioPath": { "type": "string", "minLength": 1 },
+        "deviceMatrixPath": { "type": "string", "minLength": 1 },
+        "agentInstructionsPath": { "type": "string", "minLength": 1 },
+        "next": { "type": "string", "minLength": 1 },
+        "nextCommands": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "smokeCommands": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "scriptCount": { "type": "integer", "minimum": 0 },
+        "scriptNames": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "scenarioInit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ok", "mode", "appId", "created", "next", "nextCommands"],
+      "properties": {
+        "ok": { "const": true },
+        "mode": { "const": "scenario" },
+        "appId": { "type": "string", "minLength": 1 },
+        "created": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "next": { "type": "string", "minLength": 1 },
+        "nextCommands": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/json-rpc.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/json-rpc.schema.json",
+  "title": "ZMR JSON-RPC Message",
+  "oneOf": [
+    { "$ref": "#/$defs/request" },
+    { "$ref": "#/$defs/successResponse" },
+    { "$ref": "#/$defs/errorResponse" }
+  ],
+  "$defs": {
+    "id": {
+      "type": ["string", "integer", "null"]
+    },
+    "request": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "id", "method"],
+      "properties": {
+        "jsonrpc": { "const": "2.0" },
+        "id": { "$ref": "#/$defs/id" },
+        "method": { "type": "string" },
+        "params": {}
+      }
+    },
+    "successResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "id", "result"],
+      "properties": {
+        "jsonrpc": { "const": "2.0" },
+        "id": { "$ref": "#/$defs/id" },
+        "result": {}
+      }
+    },
+    "errorResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["jsonrpc", "id", "error"],
+      "properties": {
+        "jsonrpc": { "const": "2.0" },
+        "id": { "$ref": "#/$defs/id" },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": { "type": "integer" },
+            "message": { "type": "string" },
+            "publicCode": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/release-manifest.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/release-manifest.schema.json",
+  "title": "ZMR Release Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "name", "version", "generatedAt", "releaseBaseUrl", "artifacts", "totals"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "releaseBaseUrl": { "type": ["string", "null"] },
+    "artifacts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "type", "sizeBytes", "sha256"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "type": { "enum": ["archive", "npm-package", "sbom", "notices", "homebrew-formula", "notarization-receipt", "metadata"] },
+          "sizeBytes": { "type": "integer", "minimum": 0 },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "target": { "type": "string", "minLength": 1 },
+          "platform": { "type": "string", "minLength": 1 },
+          "arch": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifacts", "archives", "sizeBytes"],
+      "properties": {
+        "artifacts": { "type": "integer", "minimum": 1 },
+        "archives": { "type": "integer", "minimum": 1 },
+        "sizeBytes": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/release-readiness-output.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/release-readiness-output.schema.json",
+  "title": "ZMR Release Readiness Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "target", "status", "evidence", "evidenceFiles", "passed", "satisfied", "failed", "planned", "missing", "insufficient", "blocked", "requirements", "nextSteps", "recommendedWording", "claimLimitations"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "target": { "enum": ["dev-preview", "production", "market-claim"] },
+    "status": { "enum": ["ready", "blocked"] },
+    "evidence": { "type": "string", "minLength": 1 },
+    "evidenceFiles": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "passed": {
+      "type": "array",
+      "description": "Raw evidence row names whose status is passed. A passed row can still be insufficient for a requirement; use satisfied for proven requirements.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "satisfied": {
+      "type": "array",
+      "description": "Requirement names that are fully satisfied after threshold and evidence validation.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "failed": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "planned": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "missing": {
+      "type": "array",
+      "description": "Required evidence rows or evidence files that are absent or unreadable. Passed rows that fail validation are listed in insufficient instead.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "insufficient": {
+      "type": "array",
+      "description": "Requirement names with passed evidence rows that do not satisfy threshold, target, device, app, or benchmark proof requirements.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "blocked": {
+      "type": "array",
+      "description": "Requirement names that are not satisfied, including missing, failed, planned, and insufficient evidence rows.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "requirements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "status"],
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "status": { "const": "satisfied" }
+              },
+              "required": ["status"]
+            },
+            "then": {
+              "required": ["evidenceName"]
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "status": { "enum": ["missing", "planned", "failed", "insufficient"] }
+              },
+              "required": ["status"]
+            },
+            "then": {
+              "required": ["reason"]
+            }
+          }
+        ],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "status": {
+            "enum": ["satisfied", "missing", "planned", "failed", "insufficient"]
+          },
+          "evidenceName": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "nextSteps": {
+      "type": "array",
+      "description": "Shortest executable remediation plan. A next step may cover multiple blocked requirements when one command writes several evidence rows.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["requirement", "command", "commands", "covers"],
+        "properties": {
+          "requirement": { "type": "string", "minLength": 1 },
+          "command": { "type": "string", "minLength": 1 },
+          "commands": {
+            "type": "array",
+            "description": "Executable command sequence for this next step. command is the shell-joined legacy representation.",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "covers": {
+            "type": "array",
+            "description": "Blocked requirement or evidence issue labels this next step is intended to resolve.",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "recommendedWording": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Safe wording for the checked release claim. Agents should quote or paraphrase this instead of inferring a stronger claim from ok/status alone."
+    },
+    "claimLimitations": {
+      "type": "array",
+      "description": "Claims that remain unsupported by the checked evidence.",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/schemas/run-output.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://zmr.dev/schemas/run-output.schema.json",
+  "title": "ZMR Run Output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "status"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "status": { "enum": ["passed", "failed", "partial"] },
+    "scenario": { "type": "string", "minLength": 1 },
+    "appId": { "type": "string", "minLength": 1 },
+    "traceDir": { "type": "string", "minLength": 1 },
+    "eventsPath": { "type": "string", "minLength": 1 },
+    "artifactsDir": { "type": "string", "minLength": 1 },
+    "durationMs": { "type": "integer", "minimum": 0 },
+    "eventCount": { "type": "integer", "minimum": 0 },
+    "snapshotCount": { "type": "integer", "minimum": 0 },
+    "partialFailureCount": { "type": "integer", "minimum": 0 },
+    "partialFailure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "minLength": 1 },
+        "artifactStatus": { "type": "string", "minLength": 1 },
+        "semanticStatus": { "type": "string", "minLength": 1 },
+        "error": { "type": "string", "minLength": 1 },
+        "screenshotArtifact": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "failedStepIndex": { "type": "integer", "minimum": 0 },
+    "error": { "type": "string", "minLength": 1 },
+    "reportPath": { "type": "string", "minLength": 1 },
+    "nextCommands": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}