zig-mobile-runner 0.1.0

package/examples/ios-shim-smoke.json

@@ -0,0 +1,23 @@
+{
+  "name": "ZMR iOS shim selector demo",
+  "appId": "com.example.mobiletest",
+  "steps": [
+    { "action": "launch" },
+    {
+      "action": "waitVisible",
+      "selector": { "text": "Continue" },
+      "timeoutMs": 1000
+    },
+    {
+      "action": "tap",
+      "selector": { "resourceId": "continue_button" }
+    },
+    {
+      "action": "typeText",
+      "selector": { "resourceId": "demo_input" },
+      "text": "hello"
+    },
+    { "action": "hideKeyboard" },
+    { "action": "snapshot" }
+  ]
+}

package/examples/ios-smoke.json

@@ -0,0 +1,9 @@
+{
+  "name": "ZMR iOS simulator smoke demo",
+  "appId": "com.example.mobiletest",
+  "steps": [
+    { "action": "launch" },
+    { "action": "openLink", "url": "exampleapp:///e2e-auth?probe=1" },
+    { "action": "snapshot" }
+  ]
+}

package/go.work

@@ -0,0 +1,3 @@
+go 1.22
+
+use ./clients/go

package/npm/agents.mjs

@@ -0,0 +1,183 @@
+import {
+  devClientReportCommand,
+  matrixCommand,
+  pilotGateCommand,
+  readinessCommand,
+  reliabilityCommand,
+  smokeReportCommand,
+  smokeRunCommand,
+  validateCommand,
+} from "./commands.mjs";
+
+export function nextStepCommands(config, { android = true, ios = true, packageScripts = false } = {}) {
+  const command = (scriptName, directCommand) => ({
+    label: scriptName,
+    command: packageScripts ? `npm run ${scriptName}` : directCommand,
+  });
+  const steps = [];
+  if (android) {
+    steps.push(command("zmr:android", config.scripts.android));
+    steps.push(command("zmr:android:report", config.scripts.androidReport));
+    if (config.scripts.androidDevClient) steps.push(command("zmr:android:dev-client", config.scripts.androidDevClient));
+    if (config.scripts.androidDevClientReport) steps.push(command("zmr:android:dev-client:report", config.scripts.androidDevClientReport));
+    steps.push(command("zmr:android:reliability", config.scripts.androidReliability));
+  }
+  if (ios) {
+    steps.push(command("zmr:ios", config.scripts.ios));
+    steps.push(command("zmr:ios:report", config.scripts.iosReport));
+    if (config.scripts.iosDevClient) steps.push(command("zmr:ios:dev-client", config.scripts.iosDevClient));
+    if (config.scripts.iosDevClientReport) steps.push(command("zmr:ios:dev-client:report", config.scripts.iosDevClientReport));
+    steps.push(command("zmr:ios:reliability", config.scripts.iosReliability));
+  }
+  if (android || ios) {
+    steps.push(command("zmr:matrix", config.scripts.matrix));
+    steps.push(command("zmr:pilot", config.scripts.pilotGate));
+    if (android && ios) steps.push(command("zmr:readiness", config.scripts.readiness));
+  }
+  steps.push(command("zmr:serve", config.scripts.serve));
+  steps.push(command("zmr:mcp", config.scripts.mcp));
+  steps.push(command("zmr:explain", config.scripts.explain));
+  steps.push(command("zmr:export", config.scripts.exportTrace));
+  steps.push(command("zmr:schemas", config.scripts.schemas));
+  steps.push(command("zmr:validate", config.scripts.validate));
+  steps.push(command("zmr:doctor", config.scripts.doctor));
+  return steps;
+}
+
+export function agentInstructions(appId, { android = true, ios = true, packageScripts = false, scripts = {} } = {}) {
+  const command = (name, fallback) => scripts[name] ?? fallback;
+  const appCommand = (scriptName, directCommand) => packageScripts ? `npm run ${scriptName}` : directCommand;
+  const doctorCommand = appCommand("zmr:doctor", command("doctor", "zmr doctor --strict --json --config .zmr/config.json"));
+  const schemasCommand = appCommand("zmr:schemas", command("schemas", "zmr schemas --json"));
+  const validateDirectCommand = command("validate", validateCommand({ android, ios }));
+  const validateAppCommand = appCommand("zmr:validate", validateDirectCommand);
+  const serveCommand = appCommand("zmr:serve", command("serve", "zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent"));
+  const mcpCommand = appCommand("zmr:mcp", command("mcp", "zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"));
+  const explainCommand = appCommand("zmr:explain", command("explain", "zmr explain traces/zmr-agent --json"));
+  const exportCommand = appCommand("zmr:export", command("exportTrace", "zmr export traces/zmr-agent --out traces/zmr-agent-redacted.zmrtrace --redact"));
+  const setupChecks = [
+    doctorCommand,
+    schemasCommand,
+    validateAppCommand,
+  ];
+  const directRuns = [];
+  const nextStepScripts = {
+    doctor: command("doctor", "zmr doctor --strict --json --config .zmr/config.json"),
+    schemas: command("schemas", "zmr schemas --json"),
+    matrix: command("matrix", matrixCommand()),
+    pilotGate: command("pilotGate", pilotGateCommand({ android, ios, appId })),
+    serve: command("serve", "zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent"),
+    mcp: command("mcp", "zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent"),
+    explain: command("explain", "zmr explain traces/zmr-agent --json"),
+    exportTrace: command("exportTrace", "zmr export traces/zmr-agent --out traces/zmr-agent-redacted.zmrtrace --redact"),
+  };
+  nextStepScripts.validate = validateDirectCommand;
+  if (android) {
+    directRuns.push(appCommand("zmr:android", command("android", smokeRunCommand({ platform: "android" }))));
+    directRuns.push(appCommand("zmr:android:report", command("androidReport", smokeReportCommand({ platform: "android" }))));
+    nextStepScripts.android = command("android", smokeRunCommand({ platform: "android" }));
+    nextStepScripts.androidReport = command("androidReport", smokeReportCommand({ platform: "android" }));
+    if (scripts.androidDevClient) {
+      directRuns.push(appCommand("zmr:android:dev-client", scripts.androidDevClient));
+      directRuns.push(appCommand("zmr:android:dev-client:report", command("androidDevClientReport", scripts.androidDevClientReport ?? devClientReportCommand({ platform: "android" }))));
+      nextStepScripts.androidDevClient = command("androidDevClient", scripts.androidDevClient);
+      nextStepScripts.androidDevClientReport = command("androidDevClientReport", scripts.androidDevClientReport ?? devClientReportCommand({ platform: "android" }));
+    }
+    nextStepScripts.androidReliability = command("androidReliability", reliabilityCommand({
+      scenario: ".zmr/android-smoke.json",
+      device: "emulator-5554",
+      appId,
+      traceRoot: "traces/zmr-android-reliability",
+      maxP95Ms: 30000,
+    }));
+  }
+  if (ios) {
+    directRuns.push(appCommand("zmr:ios", command("ios", smokeRunCommand({ platform: "ios" }))));
+    directRuns.push(appCommand("zmr:ios:report", command("iosReport", smokeReportCommand({ platform: "ios" }))));
+    nextStepScripts.ios = command("ios", smokeRunCommand({ platform: "ios" }));
+    nextStepScripts.iosReport = command("iosReport", smokeReportCommand({ platform: "ios" }));
+    if (scripts.iosDevClient) {
+      directRuns.push(appCommand("zmr:ios:dev-client", scripts.iosDevClient));
+      directRuns.push(appCommand("zmr:ios:dev-client:report", command("iosDevClientReport", scripts.iosDevClientReport ?? devClientReportCommand({ platform: "ios" }))));
+      nextStepScripts.iosDevClient = command("iosDevClient", scripts.iosDevClient);
+      nextStepScripts.iosDevClientReport = command("iosDevClientReport", scripts.iosDevClientReport ?? devClientReportCommand({ platform: "ios" }));
+    }
+    nextStepScripts.iosReliability = command("iosReliability", reliabilityCommand({
+      scenario: ".zmr/ios-smoke.json",
+      platform: "ios",
+      device: "booted",
+      appId,
+      xcrun: "xcrun",
+      traceRoot: "traces/zmr-ios-reliability",
+      maxP95Ms: 45000,
+    }));
+  }
+  if (android && ios) {
+    nextStepScripts.readiness = command("readiness", readinessCommand());
+  }
+  const readinessCommandText = appCommand("zmr:readiness", command("readiness", readinessCommand()));
+  const appSectionTitle = packageScripts ? "App Scripts" : "App Commands";
+  const appSectionCommands = nextStepCommands({ scripts: nextStepScripts }, { android, ios, packageScripts })
+    .map((step) => step.command);
+  const releaseClaims = android && ios
+    ? `\`\`\`bash
+${readinessCommandText}
+\`\`\`
+
+Do not claim production readiness from smoke runs alone. Use \`satisfied\` for proven requirements; do not infer readiness from raw \`passed\` evidence. Use \`recommendedWording\` and keep \`claimLimitations\` intact when summarizing readiness. When readiness is blocked, follow \`nextSteps[].commands\` in order. Use \`nextSteps[].covers\` to map each command back to the blocked requirements it resolves.`
+    : "Do not claim production readiness from a single-platform setup. Enable Android and iOS, then collect the full pilot evidence matrix before running the production readiness gate.";
+
+  return `# ZMR Agent Instructions
+
+App id: \`${appId}\`
+
+Start from the app checkout. Keep generated scenarios and config under \`.zmr/\`, and write run output under \`traces/\`.
+
+## Setup Checks
+
+\`\`\`bash
+${setupChecks.join("\n")}
+\`\`\`
+
+## Interactive Agent Session
+
+\`\`\`bash
+${serveCommand}
+${mcpCommand}
+\`\`\`
+
+Use \`semantic_snapshot\` before choosing tap or type actions. Prefer selectors from accessibility identifiers, resource ids, labels, or exact text before coordinates. Export redacted traces before sharing artifacts.
+
+## Failure Triage
+
+\`\`\`bash
+${explainCommand}
+\`\`\`
+
+Use the JSON explanation before editing selectors. It includes the terminal status, partial visual-capture diagnostics, and the last useful failure context.
+
+## Trace Sharing
+
+\`\`\`bash
+${exportCommand}
+\`\`\`
+
+Add \`--omit-screenshots\` when visual artifacts may contain sensitive data.
+
+## Smoke Runs
+
+\`\`\`bash
+${directRuns.join("\n")}
+\`\`\`
+
+## Release Claims
+
+${releaseClaims}
+
+## ${appSectionTitle}
+
+\`\`\`bash
+${appSectionCommands.join("\n")}
+\`\`\`
+`;
+}

package/npm/app-config.mjs

@@ -0,0 +1,95 @@
+import {
+  devClientReportCommand,
+  devClientRunCommand,
+  matrixCommand,
+  pilotGateCommand,
+  readinessCommand,
+  reliabilityCommand,
+  smokeReportCommand,
+  smokeRunCommand,
+  validateCommand,
+} from "./commands.mjs";
+
+export function appConfig(appId, { android = true, ios = true, androidShim = "", iosShim = "", expoDevClientScheme = "" } = {}) {
+  const androidCommand = smokeRunCommand({ platform: "android", androidShim });
+  const iosCommand = smokeRunCommand({ platform: "ios", iosShim });
+  const scripts = {
+    doctor: "zmr doctor --strict --json --config .zmr/config.json",
+    schemas: "zmr schemas --json",
+    validate: validateCommand({ android, ios, expoDevClientScheme }),
+    matrix: matrixCommand(),
+    pilotGate: pilotGateCommand({ android, ios, appId, iosShim }),
+    serve: "zmr serve --transport stdio --config .zmr/config.json --trace-dir traces/zmr-agent",
+    mcp: "zmr mcp --config .zmr/config.json --trace-dir traces/zmr-agent",
+    explain: "zmr explain traces/zmr-agent --json",
+    exportTrace: "zmr export traces/zmr-agent --out traces/zmr-agent-redacted.zmrtrace --redact",
+  };
+  if (android) {
+    scripts.android = androidCommand;
+    scripts.androidReport = smokeReportCommand({ platform: "android" });
+    scripts.androidReliability = reliabilityCommand({
+      scenario: ".zmr/android-smoke.json",
+      device: "emulator-5554",
+      appId,
+      androidShim,
+      traceRoot: "traces/zmr-android-reliability",
+      maxP95Ms: 30000,
+    });
+  }
+  if (ios) {
+    scripts.ios = iosCommand;
+    scripts.iosReport = smokeReportCommand({ platform: "ios" });
+    scripts.iosReliability = reliabilityCommand({
+      scenario: ".zmr/ios-smoke.json",
+      platform: "ios",
+      device: "booted",
+      appId,
+      xcrun: "xcrun",
+      iosShim,
+      traceRoot: "traces/zmr-ios-reliability",
+      maxP95Ms: 45000,
+    });
+  }
+  if (expoDevClientScheme) {
+    if (android) {
+      scripts.androidDevClient = devClientRunCommand({ platform: "android" });
+      scripts.androidDevClientReport = devClientReportCommand({ platform: "android" });
+    }
+    if (ios) {
+      scripts.iosDevClient = devClientRunCommand({ platform: "ios" });
+      scripts.iosDevClientReport = devClientReportCommand({ platform: "ios" });
+    }
+  }
+  if (android && ios) {
+    scripts.readiness = readinessCommand();
+  }
+  const config = {
+    schemaVersion: 1,
+    appId,
+    android: {
+      enabled: android,
+      defaultDevice: "emulator-5554",
+      smokeScenario: ".zmr/android-smoke.json",
+      traceDir: "traces/zmr-android",
+    },
+    ios: {
+      enabled: ios,
+      defaultDevice: "booted",
+      smokeScenario: ".zmr/ios-smoke.json",
+      traceDir: "traces/zmr-ios",
+    },
+    artifacts: {
+      screenshots: true,
+      hierarchy: true,
+      logs: true,
+      screenRecording: false,
+    },
+    scripts,
+  };
+  if (androidShim || iosShim) {
+    config.tools = {};
+    if (androidShim) config.tools.androidShimPath = androidShim;
+    if (iosShim) config.tools.iosShimPath = iosShim;
+  }
+  return config;
+}

package/npm/build-zmr.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const out = path.join(root, "zig-out", "bin", process.platform === "win32" ? "zmr.exe" : "zmr");
+fs.mkdirSync(path.dirname(out), { recursive: true });
+
+const args = ["build-exe", "src/main.zig", "-O", "ReleaseSafe", `-femit-bin=${out}`];
+if (process.platform === "darwin" && process.arch === "arm64") {
+  args.splice(2, 0, "-target", "aarch64-macos.15.0");
+}
+
+const result = spawnSync("zig", args, { cwd: root, stdio: "inherit" });
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(127);
+}
+process.exit(result.status ?? 1);

package/npm/commands.mjs

@@ -0,0 +1,104 @@
+export function smokeRunCommand({ platform, androidShim = "", iosShim = "" }) {
+  if (platform === "android") {
+    const args = ["zmr", "run", ".zmr/android-smoke.json", "--device", "emulator-5554", "--trace-dir", "traces/zmr-android"];
+    if (androidShim) args.push("--android-shim", androidShim);
+    return shellJoin(args);
+  }
+  if (platform === "ios") {
+    const args = ["zmr", "run", ".zmr/ios-smoke.json", "--platform", "ios", "--device", "booted", "--trace-dir", "traces/zmr-ios"];
+    if (iosShim) args.push("--ios-shim", iosShim);
+    return shellJoin(args);
+  }
+  throw new Error(`unsupported smoke run platform: ${platform}`);
+}
+
+export function smokeReportCommand({ platform }) {
+  if (platform === "android") return "zmr report traces/zmr-android --out traces/zmr-android/report.html";
+  if (platform === "ios") return "zmr report traces/zmr-ios --out traces/zmr-ios/report.html";
+  throw new Error(`unsupported smoke report platform: ${platform}`);
+}
+
+export function validateCommand({ android = true, ios = true, expoDevClientScheme = "" } = {}) {
+  const scenarios = [];
+  if (android) scenarios.push(".zmr/android-smoke.json");
+  if (ios) scenarios.push(".zmr/ios-smoke.json");
+  if (expoDevClientScheme && android) scenarios.push(".zmr/android-dev-client-smoke.json");
+  if (expoDevClientScheme && ios) scenarios.push(".zmr/ios-dev-client-open-link.json");
+  return scenarios.map((scenario) => shellJoin(["zmr", "validate", "--json", scenario])).join(" && ");
+}
+
+export function pilotGateCommand({ android, ios, appId, iosShim = "" }) {
+  const args = ["zmr-pilot-gate"];
+  if (android) args.push("--android");
+  if (ios) args.push("--ios");
+  if (android) args.push("--android-app-root", ".", "--android-app-id", appId, "--android-device", "emulator-5554");
+  if (ios) {
+    args.push("--ios-app-root", ".", "--ios-app-path", "./build/Debug-iphonesimulator/Sample.app", "--ios-app-id", appId, "--ios-device", "booted");
+    if (iosShim) args.push("--ios-shim", iosShim);
+  }
+  args.push("--runs", "20", "--min-pass-rate", "100", "--max-failures", "0", "--evidence-out", "traces/zmr-pilots/evidence.jsonl");
+  return shellJoin(args);
+}
+
+export function matrixCommand() {
+  return "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";
+}
+
+export function readinessCommand() {
+  return "zmr-release-readiness --evidence traces/zmr-pilots/evidence.jsonl --target production --json";
+}
+
+export function reliabilityCommand({ scenario, platform = "", device, appId, xcrun = "", androidShim = "", iosShim = "", traceRoot, maxP95Ms }) {
+  const args = [
+    "zmr-benchmark",
+    "--zmr",
+    scenario,
+  ];
+  if (platform) args.push("--platform", platform);
+  args.push("--device", device, "--app-id", appId);
+  if (xcrun) args.push("--xcrun", xcrun);
+  if (androidShim) args.push("--android-shim", androidShim);
+  if (iosShim) args.push("--ios-shim", iosShim);
+  args.push(
+    "--runs",
+    "20",
+    "--trace-root",
+    traceRoot,
+    "--min-pass-rate",
+    "100",
+    "--max-failures",
+    "0",
+    "--max-p95-ms",
+    String(maxP95Ms),
+  );
+  return `export ZMR_BIN="\${ZMR_BIN:-zmr}"; ${shellJoin(args)} && "$ZMR_BIN" report ${shellQuote(traceRoot)} --out ${shellQuote(`${traceRoot}/report.html`)}`;
+}
+
+export function devClientRunCommand({ platform }) {
+  if (platform === "android") {
+    return "zmr run .zmr/android-dev-client-smoke.json --device emulator-5554 --trace-dir traces/zmr-android-dev-client";
+  }
+  if (platform === "ios") {
+    return "zmr run .zmr/ios-dev-client-open-link.json --platform ios --device booted --trace-dir traces/zmr-ios-dev-client";
+  }
+  throw new Error(`unsupported dev-client platform: ${platform}`);
+}
+
+export function devClientReportCommand({ platform }) {
+  if (platform === "android") return "zmr report traces/zmr-android-dev-client --out traces/zmr-android-dev-client/report.html";
+  if (platform === "ios") return "zmr report traces/zmr-ios-dev-client --out traces/zmr-ios-dev-client/report.html";
+  throw new Error(`unsupported dev-client report platform: ${platform}`);
+}
+
+export function shellJoin(args) {
+  return args.map((arg, index) => {
+    if (index === 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(arg)) return arg;
+    return shellQuote(arg);
+  }).join(" ");
+}
+
+export function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:=@%+,-]+$/.test(text)) return text;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}

package/npm/generated-files.mjs

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+import { applyPackageScripts } from "./package-scripts.mjs";
+
+export function ensureTraceIgnore(root, { cwd = process.cwd() } = {}) {
+  const file = path.join(root, ".gitignore");
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (/^traces\/$/m.test(existing)) return null;
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  fs.writeFileSync(file, `${existing}${prefix}${existing.length > 0 ? "\n" : ""}# ZMR local run artifacts\ntraces/\n`);
+  return path.relative(cwd, file);
+}
+
+export function writeJsonFile(file, value, { overwrite = false, cwd = process.cwd() } = {}) {
+  return writeGeneratedFile(file, `${JSON.stringify(value, null, 2)}\n`, { overwrite, cwd });
+}
+
+export function writeTextFile(file, value, { overwrite = false, cwd = process.cwd() } = {}) {
+  return writeGeneratedFile(file, value, { overwrite, cwd });
+}
+
+export function writeScaffoldFiles(root, files, { cwd = process.cwd() } = {}) {
+  const results = [];
+  for (const file of files) {
+    const fullPath = path.join(root, file.path);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    const result = file.kind === "json"
+      ? writeJsonFile(fullPath, file.value, { overwrite: file.overwrite, cwd })
+      : writeTextFile(fullPath, file.value, { overwrite: file.overwrite, cwd });
+    if (result) results.push(result);
+  }
+  return results;
+}
+
+export function writePackageScripts(root, config, { android = true, ios = true, cwd = process.cwd() } = {}) {
+  const file = path.join(root, "package.json");
+  const pkg = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  return writeJsonFile(file, applyPackageScripts(pkg, config, { android, ios }), { overwrite: true, cwd });
+}
+
+function writeGeneratedFile(file, value, { overwrite = false, cwd = process.cwd() } = {}) {
+  const existed = fs.existsSync(file);
+  if (existed && !overwrite) return null;
+  fs.writeFileSync(file, value);
+  return {
+    path: path.relative(cwd, file),
+    status: existed ? "updated" : "created",
+  };
+}

package/npm/index.mjs

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function rootDir() {
+  return packageRoot;
+}
+
+export function resolveBinary(env = process.env, platform = process.platform, arch = process.arch) {
+  if (env.ZMR_BIN) return env.ZMR_BIN;
+
+  const exe = platform === "win32" ? "zmr.exe" : "zmr";
+  const candidates = [
+    path.join(packageRoot, "prebuilds", `${platform}-${arch}`, exe),
+    path.join(packageRoot, "zig-out", "bin", exe),
+    path.join(packageRoot, "dist", `zmr-${platform}-${arch}`, exe),
+  ];
+
+  for (const candidate of candidates) {
+    if (isExecutable(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+export function spawnZmr(args = [], options = {}) {
+  const binary = resolveBinary(options.env ?? process.env);
+  if (!binary) {
+    throw new Error(missingBinaryMessage());
+  }
+  return spawn(binary, args, {
+    stdio: options.stdio ?? "inherit",
+    cwd: options.cwd,
+    env: options.env,
+  });
+}
+
+export function runZmr(args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawnZmr(args, options);
+    } catch (error) {
+      reject(error);
+      return;
+    }
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (code === 0) resolve({ code, signal });
+      else reject(new Error(`zmr exited with ${signal ?? code}`));
+    });
+  });
+}
+
+export function missingBinaryMessage() {
+  return [
+    "Could not find a zmr binary.",
+    "Set ZMR_BIN=/path/to/zmr, run `npm run build:zmr`, or install a release package that includes prebuilt binaries.",
+    `Package root: ${packageRoot}`,
+    `Host: ${os.platform()} ${os.arch()}`,
+  ].join("\n");
+}
+
+function isExecutable(candidate) {
+  try {
+    fs.accessSync(candidate, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/npm/init-app.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import path from "node:path";
+import {
+  appInitOutput,
+  ensureTraceIgnore,
+  nextStepCommands,
+  packageScripts,
+  parseScaffoldArgs,
+  scaffoldPlan,
+  writePackageScripts,
+  writeScaffoldFiles,
+} from "./scaffold.mjs";
+
+const options = parseArgs(process.argv.slice(2));
+const {
+  dir,
+  appId,
+  android,
+  androidShim,
+  ios,
+  iosShim,
+  expoDevClientScheme,
+  packageJson,
+} = options;
+
+if (!appId) {
+  console.error("--app-id cannot be empty");
+  process.exit(2);
+}
+
+const targetDir = path.resolve(dir, ".zmr");
+const appRoot = path.resolve(dir);
+const plan = scaffoldPlan(appId, { android, ios, androidShim, iosShim, expoDevClientScheme, packageScripts: packageJson });
+const { config, files } = plan;
+writeScaffoldFiles(targetDir, files);
+ensureTraceIgnore(appRoot);
+if (packageJson) {
+  const result = writePackageScripts(appRoot, config, { android, ios, cwd: appRoot });
+  if (result && !options.json) console.log(`${result.status} ${result.path}`);
+}
+
+if (options.json) {
+  process.stdout.write(`${JSON.stringify(appInitOutput(appRoot, appId, plan, { packageScripts: packageJson }))}\n`);
+  process.exit(0);
+}
+
+console.log(`created ${path.relative(appRoot, targetDir)}`);
+console.log("");
+console.log("Next steps");
+printNextSteps(config.scripts, { packageScripts: packageJson });
+console.log("");
+if (!packageJson) {
+  console.log("Add scripts like:");
+  console.log(JSON.stringify(packageScripts(config), null, 2));
+}
+
+function usage() {
+  console.log("Usage: zmr-init [--dir <app-root>] [--app-id <bundle-or-application-id>] [--android] [--android-shim <path>] [--ios] [--ios-shim <path>] [--expo-dev-client-scheme <scheme>] [--package-json] [--json]");
+}
+
+function parseArgs(args) {
+  try {
+    const parsed = parseScaffoldArgs(args, { packageJson: true });
+    if (parsed.help) {
+      usage();
+      process.exit(0);
+    }
+    return parsed;
+  } catch (error) {
+    console.error(error.message);
+    usage();
+    process.exit(2);
+  }
+}
+
+function printNextSteps(scripts, { packageScripts: usePackageScripts = false } = {}) {
+  for (const step of nextStepCommands({ scripts }, { android, ios, packageScripts: usePackageScripts })) {
+    console.log(`  ${step.command}`);
+  }
+}