mobile-wdio-kit 0.1.0

package/template/scripts/android-env.sh

@@ -0,0 +1,102 @@
+#!/bin/sh
+# Shared Android SDK / emulator bootstrap for local scripts. Source (do not execute).
+# shellcheck shell=sh
+
+android_env_project_root() {
+  CDPATH= cd -- "$(dirname -- "$0")/.." && pwd
+}
+
+android_env_prepare_paths() {
+  PROJECT_ROOT="${PROJECT_ROOT:-$(android_env_project_root)}"
+  mkdir -p "$PROJECT_ROOT/artifacts"
+
+  if [ -z "${ANDROID_HOME:-}" ] && [ -d "$HOME/Library/Android/sdk" ]; then
+    export ANDROID_HOME="$HOME/Library/Android/sdk"
+  fi
+
+  if [ -z "${ANDROID_SDK_ROOT:-}" ] && [ -n "${ANDROID_HOME:-}" ]; then
+    export ANDROID_SDK_ROOT="$ANDROID_HOME"
+  fi
+
+  if [ -z "${JAVA_HOME:-}" ]; then
+    if [ -x "/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home/bin/java" ]; then
+      export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+    elif command -v /usr/libexec/java_home >/dev/null 2>&1; then
+      JAVA_HOME_CANDIDATE=$(/usr/libexec/java_home 2>/dev/null || true)
+      if [ -n "$JAVA_HOME_CANDIDATE" ]; then
+        export JAVA_HOME="$JAVA_HOME_CANDIDATE"
+      fi
+    fi
+  fi
+
+  if [ -n "${JAVA_HOME:-}" ]; then
+    export PATH="$JAVA_HOME/bin:$PATH"
+  fi
+
+  if [ -n "${ANDROID_HOME:-}" ]; then
+    ADB_BIN="$ANDROID_HOME/platform-tools/adb"
+    EMULATOR_BIN="$ANDROID_HOME/emulator/emulator"
+  else
+    ADB_BIN=""
+    EMULATOR_BIN=""
+  fi
+}
+
+android_env_has_device() {
+  [ -n "$ADB_BIN" ] && [ -x "$ADB_BIN" ] &&
+    "$ADB_BIN" devices | awk 'NR>1 && $2=="device" { found=1 } END { exit found ? 0 : 1 }'
+}
+
+android_env_ensure_emulator() {
+  android_env_prepare_paths
+
+  if android_env_has_device; then
+    return 0
+  fi
+
+  if [ ! -x "$EMULATOR_BIN" ] || [ ! -x "$ADB_BIN" ]; then
+    echo "Android SDK tools not found. Set ANDROID_HOME." >&2
+    exit 1
+  fi
+
+  SELECTED_AVD="${ANDROID_AVD:-$("$EMULATOR_BIN" -list-avds 2>/dev/null | sed -n '/^[A-Za-z0-9._-][A-Za-z0-9._-]*$/p' | sed -n '1p')}"
+
+  if [ -z "$SELECTED_AVD" ]; then
+    echo "No Android emulator available. Create an AVD or set ANDROID_AVD." >&2
+    exit 1
+  fi
+
+  nohup "$EMULATOR_BIN" -avd "$SELECTED_AVD" >"$PROJECT_ROOT/artifacts/emulator.log" 2>&1 &
+
+  "$ADB_BIN" wait-for-device
+  while [ "$("$ADB_BIN" shell getprop sys.boot_completed | tr -d '\r')" != "1" ]; do
+    sleep 2
+  done
+  "$ADB_BIN" shell input keyevent 82 >/dev/null 2>&1 || true
+}
+
+# Start an AVD in the background without waiting for boot. For MCP stdio: Cursor must get a
+# JSON-RPC handshake quickly; blocking on cold boot exceeds typical client timeouts.
+android_env_start_emulator_async() {
+  android_env_prepare_paths
+
+  if android_env_has_device; then
+    return 0
+  fi
+
+  if [ ! -x "$EMULATOR_BIN" ] || [ ! -x "$ADB_BIN" ]; then
+    echo "Android SDK tools not found. Set ANDROID_HOME." >&2
+    return 1
+  fi
+
+  SELECTED_AVD="${ANDROID_AVD:-$("$EMULATOR_BIN" -list-avds 2>/dev/null | sed -n '/^[A-Za-z0-9._-][A-Za-z0-9._-]*$/p' | sed -n '1p')}"
+
+  if [ -z "$SELECTED_AVD" ]; then
+    echo "No Android emulator available. Create an AVD or set ANDROID_AVD." >&2
+    return 1
+  fi
+
+  echo "[android-env] Starting emulator '$SELECTED_AVD' in the background (logs: $PROJECT_ROOT/artifacts/emulator.log). Wait for adb device before start_session." >&2
+  nohup "$EMULATOR_BIN" -avd "$SELECTED_AVD" >"$PROJECT_ROOT/artifacts/emulator.log" 2>&1 &
+  return 0
+}

package/template/scripts/doctor-cli.mjs

@@ -0,0 +1,38 @@
+/** Shared doctor argv + runner factory (used by global CLI and vendored template). */
+
+export function parseDoctorArgs(argv) {
+  const out = { cwd: process.cwd(), json: false, appiumUrl: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--json") out.json = true;
+    else if (a === "--cwd") {
+      out.cwd = argv[i + 1];
+      i += 1;
+    } else if (a === "--appium-url") {
+      out.appiumUrl = argv[i + 1];
+      i += 1;
+    } else {
+      throw new Error(`Unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+/** @param {{ runDoctor: Function; printDoctorResult: Function }} deps */
+export function createDoctorMain(deps) {
+  const { runDoctor, printDoctorResult } = deps;
+  return async function runDoctorMain(argv) {
+    const args = parseDoctorArgs(argv);
+    const result = await runDoctor({
+      cwd: args.cwd,
+      json: args.json,
+      appiumUrl: args.appiumUrl ?? undefined,
+    });
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      printDoctorResult(result);
+    }
+    return result.ok ? 0 : 1;
+  };
+}

package/template/scripts/doctor-runner.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { printDoctorResult, runDoctor } from "./mobile-wdio-doctor-core.mjs";
+import { createDoctorMain } from "./doctor-cli.mjs";
+
+const runDoctorMain = createDoctorMain({ runDoctor, printDoctorResult });
+const code = await runDoctorMain(process.argv.slice(2));
+process.exit(code);

package/template/scripts/download-demo-android.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * Downloads the WebdriverIO native demo Android APK into apps/ (for a lean npm template).
+ * Override URL: DEMO_APK_URL=https://.../file.apk
+ * Attribution / license for the binary: see THIRD_PARTY.md in this repository.
+ */
+import { createWriteStream, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const defaultUrl =
+  "https://github.com/webdriverio/native-demo-app/releases/download/v2.0.0/android.wdio.native.app.v2.0.0.apk";
+const url = process.env.DEMO_APK_URL ?? defaultUrl;
+const dest = join(
+  root,
+  "apps",
+  "android.wdio.native.app.v2.0.0.apk",
+);
+
+if (existsSync(dest) && process.env.DEMO_APK_FORCE !== "1") {
+  console.log(`Demo APK already present: ${dest}`);
+  process.exit(0);
+}
+
+mkdirSync(dirname(dest), { recursive: true });
+
+console.log(`Downloading demo APK…\n  ${url}`);
+
+const res = await fetch(url, {
+  redirect: "follow",
+  headers: {
+    "User-Agent": "mobile-wdio-kit-setup",
+    Accept: "application/octet-stream,*/*",
+  },
+});
+
+if (!res.ok || !res.body) {
+  console.error(`Download failed: HTTP ${res.status} ${res.statusText}`);
+  process.exit(1);
+}
+
+const out = createWriteStream(dest);
+await pipeline(Readable.fromWeb(res.body), out);
+console.log(`Wrote ${dest}`);

package/template/scripts/ensure-appium.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * If Appium is not ready at APPIUM_HOST:APPIUM_PORT, start it in the background
+ * (logs to artifacts/appium-mcp.log). Safe for MCP: does not touch stdout.
+ */
+import "dotenv/config";
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const host = process.env.APPIUM_HOST ?? "127.0.0.1";
+const port = Number(process.env.APPIUM_PORT ?? "4723");
+const statusUrl = `http://${host}:${port}/status`;
+
+async function ping() {
+  try {
+    const res = await fetch(statusUrl, { signal: AbortSignal.timeout(2000) });
+    if (!res.ok) return false;
+    const body = await res.json();
+    return body?.value?.ready === true;
+  } catch {
+    return false;
+  }
+}
+
+if (await ping()) {
+  console.error(`[ensure-appium] already ready at ${statusUrl}`);
+  process.exit(0);
+}
+
+mkdirSync(join(root, "artifacts"), { recursive: true });
+const logPath = join(root, "artifacts", "appium-mcp.log");
+const logFd = openSync(logPath, "a");
+const line = `\n--- ${new Date().toISOString()} starting Appium for MCP ---\n`;
+writeSync(logFd, line);
+
+const appiumBin = join(root, "node_modules", ".bin", "appium");
+const child = spawn(
+  appiumBin,
+  ["--address", host, "--port", String(port)],
+  {
+    cwd: root,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+  }
+);
+child.unref();
+
+child.on("error", (err) => {
+  console.error("[ensure-appium] failed to spawn appium:", err.message);
+  process.exit(1);
+});
+
+const deadline = Date.now() + 120_000;
+while (Date.now() < deadline) {
+  if (await ping()) {
+    console.error(`[ensure-appium] Appium ready at ${statusUrl} (log: ${logPath})`);
+    process.exit(0);
+  }
+  await new Promise((r) => setTimeout(r, 500));
+}
+
+try {
+  process.kill(child.pid, "SIGTERM");
+} catch {
+  // ignore
+}
+console.error("[ensure-appium] timed out waiting for Appium");
+process.exit(1);

package/template/scripts/mcp-with-appium.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+# Cursor MCP entry: ensure Android device/emulator, ensure Appium, then run wdio-mcp on stdio.
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+PROJECT_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
+cd "$PROJECT_ROOT"
+
+# Load .env so wdio-mcp (patched) sees MOBILE_* for demo auto-login and APPIUM_* / paths match local runs.
+if [ -f "$PROJECT_ROOT/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  . "$PROJECT_ROOT/.env"
+  set +a
+fi
+
+# shellcheck source=android-env.sh
+. "$SCRIPT_DIR/android-env.sh"
+android_env_prepare_paths
+# Blocking until boot_completed can take minutes and breaks Cursor's MCP handshake (~10s).
+# Terminal: npm run mcp:server:with-appium sets MCP_BLOCK_UNTIL_EMULATOR_READY=1 for full wait.
+if [ "${MCP_BLOCK_UNTIL_EMULATOR_READY:-0}" = "1" ]; then
+  android_env_ensure_emulator
+else
+  android_env_start_emulator_async || exit 1
+fi
+
+node "$SCRIPT_DIR/ensure-appium.mjs"
+
+exec "$PROJECT_ROOT/node_modules/.bin/wdio-mcp" "$@"

package/template/scripts/mobile-wdio-doctor-core.mjs

@@ -0,0 +1,324 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const MIN_NODE = 18;
+
+/** @typedef {{ ok: boolean; level: "ok" | "warn" | "fail"; title: string; detail?: string; fix?: string }} Check */
+
+function nodeMajor(version) {
+  const m = /^v?(\d+)/.exec(version.trim());
+  return m ? Number(m[1]) : 0;
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+    ...opts,
+  });
+  return {
+    code: r.status ?? 1,
+    out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim(),
+  };
+}
+
+function which(name) {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  const r = run(cmd, [name]);
+  return r.code === 0 ? r.out.split("\n")[0].trim() : "";
+}
+
+/**
+ * @param {{ cwd?: string; json?: boolean; appiumUrl?: string }} opts
+ */
+export async function runDoctor(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const checks = /** @type {Check[]} */ ([]);
+
+  const add = (c) => checks.push(c);
+
+  const nodeVer = process.version;
+  const major = nodeMajor(nodeVer);
+  add({
+    ok: major >= MIN_NODE,
+    level: major >= MIN_NODE ? "ok" : "fail",
+    title: `Node.js ${nodeVer}`,
+    detail: `Required: >= ${MIN_NODE}`,
+    fix:
+      major < MIN_NODE
+        ? "Install Node.js 18+ (LTS recommended) from https://nodejs.org/"
+        : undefined,
+  });
+
+  const npmWhich = which("npm");
+  add({
+    ok: Boolean(npmWhich),
+    level: npmWhich ? "ok" : "warn",
+    title: "npm on PATH",
+    detail: npmWhich || "not found",
+    fix: npmWhich ? undefined : "Install Node.js with npm, or use a version manager (nvm, fnm).",
+  });
+
+  const androidHome =
+    process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || "";
+  const sdkOk = Boolean(androidHome && existsSync(androidHome));
+  add({
+    ok: sdkOk,
+    level: sdkOk ? "ok" : "warn",
+    title: "Android SDK (ANDROID_HOME or ANDROID_SDK_ROOT)",
+    detail: sdkOk ? androidHome : "not set or path missing",
+    fix: sdkOk
+      ? undefined
+      : "Install Android Studio / cmdline-tools, then export ANDROID_HOME (e.g. ~/Library/Android/sdk on macOS).",
+  });
+
+  const adbPath = which("adb");
+  const adbOk = Boolean(adbPath);
+  add({
+    ok: adbOk,
+    level: adbOk ? "ok" : "warn",
+    title: "adb on PATH",
+    detail: adbOk ? adbPath : "not found",
+    fix: adbOk
+      ? undefined
+      : "Add platform-tools to PATH (inside your Android SDK).",
+  });
+
+  if (adbOk) {
+    const dev = run("adb", ["devices"]);
+    const lines = dev.out.split("\n").filter(Boolean);
+    const deviceLines = lines.filter(
+      (l) => l.includes("\tdevice") || l.includes("\temulator"),
+    );
+    add({
+      ok: deviceLines.length > 0,
+      level: deviceLines.length > 0 ? "ok" : "warn",
+      title: "ADB device / emulator",
+      detail:
+        deviceLines.length > 0
+          ? `${deviceLines.length} online`
+          : "no devices in `adb devices`",
+      fix:
+        deviceLines.length > 0
+          ? undefined
+          : "Start an emulator (`emulator -avd …`) or plug in a device with USB debugging.",
+    });
+  }
+
+  const javaHome = process.env.JAVA_HOME || "";
+  const javaOk = Boolean(javaHome && existsSync(javaHome));
+  add({
+    ok: javaOk,
+    level: javaOk ? "ok" : "warn",
+    title: "JAVA_HOME (recommended for Android toolchain)",
+    detail: javaOk ? javaHome : "not set or path missing",
+    fix: javaOk
+      ? undefined
+      : "Point JAVA_HOME at a JDK 17+ install (Android Studio bundled JBR works).",
+  });
+
+  const demoApk = join(cwd, "apps", "android.wdio.native.app.v2.0.0.apk");
+  const apkOk = existsSync(demoApk);
+  add({
+    ok: apkOk,
+    level: apkOk ? "ok" : "warn",
+    title: "Demo Android APK (apps/android.wdio.native.app.v2.0.0.apk)",
+    detail: apkOk ? demoApk : "missing",
+    fix: apkOk
+      ? undefined
+      : "Run `npm run setup:demo-android` in this project (or set ANDROID_APP_PATH to your app).",
+  });
+
+  const envFile = join(cwd, ".env");
+  add({
+    ok: existsSync(envFile),
+    level: existsSync(envFile) ? "ok" : "warn",
+    title: ".env present",
+    detail: existsSync(envFile) ? envFile : "missing",
+    fix: existsSync(envFile)
+      ? undefined
+      : "Copy `.env.example` to `.env` and adjust device names / paths.",
+  });
+
+  let pkg = null;
+  try {
+    pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+  } catch {
+    add({
+      ok: false,
+      level: "warn",
+      title: "package.json in cwd",
+      detail: "not readable — run doctor from the scaffolded project root",
+    });
+  }
+
+  if (pkg) {
+    const appiumBin = join(cwd, "node_modules", ".bin", "appium");
+    const appiumLocal = existsSync(appiumBin);
+    add({
+      ok: appiumLocal,
+      level: appiumLocal ? "ok" : "warn",
+      title: "Appium (local devDependency)",
+      detail: appiumLocal ? appiumBin : "run npm install in this project",
+      fix: appiumLocal ? undefined : "From project root: npm install",
+    });
+
+    if (appiumLocal) {
+      const appiumCli =
+        process.platform === "win32"
+          ? join(cwd, "node_modules", ".bin", "appium.cmd")
+          : appiumBin;
+      const exe = existsSync(appiumCli) ? appiumCli : appiumBin;
+      const drivers = spawnSync(exe, ["driver", "list", "--installed"], {
+        cwd,
+        encoding: "utf8",
+        env: process.env,
+        shell: false,
+      });
+      const driverText = `${drivers.stdout ?? ""}${drivers.stderr ?? ""}`;
+      const hasU2 = /uiautomator2/i.test(driverText);
+      const hasXc = /xcuitest/i.test(driverText);
+      add({
+        ok: hasU2,
+        level: hasU2 ? "ok" : "warn",
+        title: "Appium UiAutomator2 driver",
+        detail: hasU2 ? "installed" : "not detected",
+        fix: hasU2 ? undefined : "npm run appium:driver:android",
+      });
+      if (process.platform === "darwin") {
+        add({
+          ok: hasXc,
+          level: hasXc ? "ok" : "warn",
+          title: "Appium XCUITest driver (iOS)",
+          detail: hasXc ? "installed" : "not detected",
+          fix: hasXc ? undefined : "npm run appium:driver:ios",
+        });
+      }
+    }
+  }
+
+  if (process.platform === "darwin") {
+    const xc = run("xcodebuild", ["-version"]);
+    add({
+      ok: xc.code === 0,
+      level: xc.code === 0 ? "ok" : "warn",
+      title: "Xcode (xcodebuild)",
+      detail: xc.code === 0 ? xc.out.split("\n")[0] : xc.out || "not found",
+      fix:
+        xc.code === 0
+          ? undefined
+          : "Install Xcode from the App Store and run `xcode-select --install` if needed.",
+    });
+
+    const sim = run("xcrun", ["simctl", "list", "devices", "available"]);
+    const simOk = sim.code === 0 && /iPhone|iPad/.test(sim.out);
+    add({
+      ok: simOk,
+      level: simOk ? "ok" : "warn",
+      title: "iOS Simulator (simctl)",
+      detail: simOk ? "at least one iPhone/iPad device listing present" : sim.out || "failed",
+      fix: simOk
+        ? undefined
+        : "Open Xcode → Settings → Platforms and install a simulator runtime.",
+    });
+  } else {
+    add({
+      ok: true,
+      level: "ok",
+      title: "iOS tooling",
+      detail: "skipped (not macOS)",
+    });
+  }
+
+  const appiumUrl =
+    opts.appiumUrl ??
+    (() => {
+      try {
+        if (existsSync(join(cwd, ".env"))) {
+          const raw = readFileSync(join(cwd, ".env"), "utf8");
+          const host =
+            raw.match(/^\s*APPIUM_HOST\s*=\s*(.+)$/m)?.[1]?.trim() ??
+            "127.0.0.1";
+          const port =
+            raw.match(/^\s*APPIUM_PORT\s*=\s*(.+)$/m)?.[1]?.trim() ?? "4723";
+          return `http://${host}:${port}/status`;
+        }
+      } catch {
+        /* ignore */
+      }
+      return "http://127.0.0.1:4723/status";
+    })();
+
+  try {
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), 2500);
+    const res = await fetch(appiumUrl, { signal: ac.signal });
+    clearTimeout(t);
+    const body = res.ok ? await res.json().catch(() => ({})) : {};
+    const ready = body?.value?.ready === true;
+    add({
+      ok: ready,
+      level: ready ? "ok" : "warn",
+      title: "Appium server reachable",
+      detail: `${appiumUrl} → HTTP ${res.status}${ready ? ", ready" : ""}`,
+      fix: ready
+        ? undefined
+        : "Start Appium: npm run appium:start (or your own 127.0.0.1:4723 server).",
+    });
+  } catch (e) {
+    add({
+      ok: false,
+      level: "warn",
+      title: "Appium server reachable",
+      detail: String(/** @type {Error} */ (e).message || e),
+      fix: "Start Appium on APPIUM_HOST:APPIUM_PORT (see .env).",
+    });
+  }
+
+  const failed = checks.filter((c) => c.level === "fail");
+  const warns = checks.filter((c) => c.level === "warn");
+
+  if (opts.json) {
+    return {
+      ok: failed.length === 0,
+      summary: {
+        fail: failed.length,
+        warn: warns.length,
+        ok: checks.filter((c) => c.level === "ok").length,
+      },
+      checks,
+    };
+  }
+
+  const icon = (c) =>
+    c.level === "ok" ? "✓" : c.level === "warn" ? "!" : "✗";
+
+  const lines = [
+    "",
+    "mobile-wdio-kit — doctor",
+    "========================",
+    "",
+    ...checks.map(
+      (c) =>
+        `${icon(c)} ${c.title}${c.detail ? `\n    ${c.detail.split("\n").join("\n    ")}` : ""}${c.fix ? `\n    → ${c.fix}` : ""}`,
+    ),
+    "",
+    failed.length
+      ? `Result: ${failed.length} required check(s) failed.`
+      : warns.length
+        ? `Result: OK (with ${warns.length} warning(s)).`
+        : "Result: all checks passed.",
+    "",
+  ];
+
+  return {
+    ok: failed.length === 0,
+    text: lines.join("\n"),
+    checks,
+  };
+}
+
+export function printDoctorResult(result) {
+  if (typeof result.text === "string") process.stdout.write(result.text);
+}

package/template/scripts/ping-appium.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * Quick check that Appium is up before using wdio-mcp from Cursor.
+ * Respects APPIUM_HOST / APPIUM_PORT (same as .env).
+ */
+import "dotenv/config";
+
+const host = process.env.APPIUM_HOST ?? "127.0.0.1";
+const port = process.env.APPIUM_PORT ?? "4723";
+const url = `http://${host}:${port}/status`;
+
+const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+if (!res.ok) {
+  console.error(`Appium HTTP ${res.status} at ${url}`);
+  process.exit(1);
+}
+const body = await res.json();
+const ready = body?.value?.ready === true;
+if (!ready) {
+  console.error("Appium responded but is not ready:", JSON.stringify(body, null, 2));
+  process.exit(1);
+}
+console.log(`Appium ready at ${url}`);
+console.log(body.value?.message ?? "");

package/template/scripts/run-android-local.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+# shellcheck source=android-env.sh
+. "$SCRIPT_DIR/android-env.sh"
+
+PROJECT_ROOT=$(android_env_project_root)
+android_env_ensure_emulator
+
+exec "$PROJECT_ROOT/node_modules/.bin/wdio" run "$PROJECT_ROOT/configs/wdio.local.android.conf.ts" "$@"

package/template/scripts/run-appium-local.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+# shellcheck source=android-env.sh
+. "$SCRIPT_DIR/android-env.sh"
+
+PROJECT_ROOT=$(android_env_project_root)
+android_env_ensure_emulator
+
+exec "$PROJECT_ROOT/node_modules/.bin/appium" "$@"