mobile-wdio-kit 0.1.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "mobile-wdio-kit",
+  "version": "0.1.0",
+  "description": "Scaffold a production-ready WebdriverIO + Appium mobile framework with environment checks (doctor).",
+  "type": "module",
+  "license": "ISC",
+  "author": "Manoj Kumar Salugu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Assign4/mobile-agentic-wdio-poc.git",
+    "directory": "packages/mobile-wdio-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/Assign4/mobile-agentic-wdio-poc/issues"
+  },
+  "homepage": "https://github.com/Assign4/mobile-agentic-wdio-poc#readme",
+  "keywords": [
+    "webdriverio",
+    "appium",
+    "mobile",
+    "testing",
+    "android",
+    "ios",
+    "cursor",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "mobile-wdio-kit": "bin/cli.mjs",
+    "mwk": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "template",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node ./scripts/verify-template.mjs"
+  }
+}

package/template/.cursor/mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "wdio-mcp": {
+      "command": "sh",
+      "args": ["scripts/mcp-with-appium.sh"],
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "ANDROID_HOME": "${env:HOME}/Library/Android/sdk",
+        "ANDROID_SDK_ROOT": "${env:HOME}/Library/Android/sdk"
+      }
+    }
+  }
+}

package/template/.cursor/rules/wdio-mcp-mobile.mdc

@@ -0,0 +1,52 @@
+---
+description: Local Android/iOS automation with wdio-mcp — session start, natural phrasing, demo auto-login
+alwaysApply: true
+---
+
+# wdio-mcp (local mobile)
+
+The MCP server exposes tools with **fixed names** (for example `start_session`). You cannot rename the tool in Cursor; treat the user’s chat as **natural language** that you map to those tools.
+
+This repo **patches `@wdio/mcp`** (`patches/@wdio+mcp+*.patch`, applied on `npm install`): for the **WebdriverIO demo APK** (`android.wdio.native.app` in `appPath`) and **iOS demo** (`ios-demo` in `appPath`), **`start_session` alone** completes login using `MOBILE_USERNAME` / `MOBILE_PASSWORD` (loaded via `scripts/mcp-with-appium.sh` sourcing `.env`). The session response text mentions demo auto-login when it succeeded.
+
+## Map user intent → `start_session`
+
+Call **`start_session`** before any other wdio-mcp automation tool (`click_element`, `tap_element`, `get_elements`, etc.). There is no active driver until `start_session` succeeds.
+
+When the user says any of the following (or similar), they mean **start a mobile session** — i.e. call **`start_session`** with the right platform and **absolute `appPath`**:
+
+- “Start a session”, “start session”, “open a session”
+- “Launch the app”, “open the app”, “start the app”, “run the app”
+- “Open Android / the APK / the emulator app”
+- “Launch iOS”, “open the **.app**”, “start on simulator”, “run the iOS build”
+
+If they do not specify platform, prefer **Android** when the conversation is about this repo’s default demo APK; use **iOS** when they mention simulator, `.app`, or iOS explicitly.
+
+### Android (`platform: "android"`)
+
+- `automationName`: `"UiAutomator2"`
+- **`appPath`**: absolute path from repo root — read `ANDROID_APP_PATH` from `.env` and `resolve(projectRoot, ANDROID_APP_PATH)`, or default `apps/android.wdio.native.app.v2.0.0.apk`
+- **`deviceName`**: match `adb devices` (e.g. `emulator-5554`) or `ANDROID_DEVICE_NAME` from `.env`
+- **`appiumConfig`**: `{ "host": "<APPIUM_HOST>", "port": <APPIUM_PORT>, "path": "/" }` (defaults `127.0.0.1`, `4723`)
+- `autoGrantPermissions`: `true` when launching the demo app (matches project smoke script)
+
+### iOS (`platform: "ios"`)
+
+- `automationName`: `"XCUITest"`
+- **`appPath`**: absolute path to the **`.app` bundle** — read `IOS_APP_PATH` from `.env` (e.g. `./apps/ios-demo.app`) and `resolve(projectRoot, IOS_APP_PATH)`. The user saying “launch the app” on iOS means this bundle path, not an APK.
+- **`deviceName`**: `IOS_DEVICE_NAME` from `.env` or the simulator name the user specifies
+- **`appiumConfig`**: same host/port/path pattern as Android when using local Appium
+
+## After `start_session` on the demo app
+
+**Do not** run a separate login tool sequence unless the user opts out of built-in auto-login or the response says auto-login failed.
+
+**Opt-out** (launch only, stay logged out): set `WDIO_MCP_DEMO_AUTO_LOGIN=0` (or `false`) in `.cursor/mcp.json` under `wdio-mcp` → `env`, reload the window / restart MCP, then `start_session` again. Or use a non-demo `appPath` (no built-in login). If the user says “only launch” or “don’t log in”, tell them to use that env flag (or a different app); do not assume you must drive the login UI yourself after a successful demo `start_session`.
+
+For **non-demo** apps, there is no built-in login; drive the UI with `click_element` / `set_value` as needed.
+
+Use `get_elements` when you need to see the current hierarchy.
+
+## Teardown
+
+Call **`close_session`** when the user is done or asks to tear down.

package/template/.env.example

@@ -0,0 +1,33 @@
+ANDROID_APP_PATH=./apps/android.wdio.native.app.v2.0.0.apk
+ANDROID_DEVICE_NAME="Android Emulator"
+ANDROID_UDID=
+
+IOS_APP_PATH=./apps/ios-demo.app
+IOS_DEVICE_NAME="iPhone 15"
+IOS_BUNDLE_ID=com.example.demo
+
+APPIUM_HOST=127.0.0.1
+APPIUM_PORT=4723
+
+MOBILE_USERNAME=test@webdriver.io
+MOBILE_PASSWORD=Test1234!
+
+# Patched wdio-mcp (see patches/): set to 0 or false to skip built-in demo-app login after start_session.
+# WDIO_MCP_DEMO_AUTO_LOGIN=0
+
+ARTIFACTS_DIR=./artifacts
+
+# LambdaTest-style cloud (optional)
+CLOUD_USERNAME=
+CLOUD_ACCESS_KEY=
+CLOUD_HOSTNAME=mobile-hub.lambdatest.com
+CLOUD_PATH=/wd/hub
+BUILD_NAME=wdio-mobile
+
+ANDROID_CLOUD_DEVICE="Galaxy S24"
+ANDROID_CLOUD_PLATFORM_VERSION=14
+ANDROID_CLOUD_APP=
+
+IOS_CLOUD_DEVICE="iPhone 15"
+IOS_CLOUD_PLATFORM_VERSION=17
+IOS_CLOUD_APP=

package/template/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/template/README.md

@@ -0,0 +1,158 @@
+# Mobile WDIO (minimal)
+
+WebdriverIO **Mocha** specs for native **Android / iOS**, plus official **`@wdio/mcp`** so Cursor can drive the app from chat. No Cucumber and no custom MCP server—configs, page objects, locators, env, Vitest unit tests, and a small **`patch-package`** patch on `@wdio/mcp` so `start_session` can complete demo login in one step.
+
+**Open source:** [LICENSE](./LICENSE) (ISC). **Trademarks, demo APK, npm deps, patches:** read [THIRD_PARTY.md](./THIRD_PARTY.md) before you publish or redistribute. **Publishing the CLI:** [RELEASING.md](./RELEASING.md).
+
+## Layout
+
+```text
+configs/           wdio.local.*.conf.ts, wdio.cloud.*.conf.ts, wdio.shared.ts
+src/env.ts         dotenv-backed settings
+src/specs/         *.spec.ts (Mocha)
+src/pages/         small screen helpers
+src/locators/      Android / iOS selectors
+scripts/           android-env.sh, ensure-appium.mjs, mcp-with-appium.sh (Cursor MCP entry), ping-appium.mjs, run-mcp-android-smoke.sh
+patches/           patch-package diff for @wdio/mcp (demo auto-login after start_session)
+.cursor/rules/     wdio-mcp-mobile.mdc (agent: session + demo auto-login, Android/iOS app paths)
+.cursor/mcp.json → `sh scripts/mcp-with-appium.sh` (do **not** use `npm run mcp:server` as the MCP command: npm prints to stdout and breaks JSON-RPC on stdio)
+```
+
+## Setup
+
+1. Copy `.env.example` → `.env`.
+2. Put apps under `apps/` or set `ANDROID_APP_PATH` / `IOS_APP_PATH`.
+3. Install drivers: `npm run appium:driver:android` (and iOS if needed).
+
+## Scaffold & environment check (`mobile-wdio-kit`)
+
+The **`mobile-wdio-kit`** package (`packages/mobile-wdio-kit`) copies an embedded **template** of this repo, then runs **`npm install`**, **`patch-package`**, copies **`.env.example` → `.env`**, and downloads the **WebdriverIO demo Android APK** (APKs are not shipped inside the npm tarball).
+
+**Where projects are created:** `create <path>` resolves the directory with Node’s `path.resolve()` from your **shell’s current working directory**—not from the global npm install location. So `mobile-wdio-kit create ~/Desktop/foo` creates on the Desktop regardless of whether you ran the command from `~/Projects` or elsewhere (and `~/...` works even inside quotes thanks to CLI tilde expansion).
+
+```bash
+npx mobile-wdio-kit@latest create ./my-mobile-tests
+cd my-mobile-tests
+npm run doctor
+```
+
+```bash
+npm install -g mobile-wdio-kit   # after publish
+mobile-wdio-kit create ./my-mobile-tests
+```
+
+From a **git clone** of this repo (path must include `mobile-agentic-wdio-poc`):
+
+```bash
+cd mobile-agentic-wdio-poc
+npm install -g ./packages/mobile-wdio-kit
+```
+
+**Doctor** checks Node, Android SDK / `adb`, demo APK, `.env`, Appium drivers, Xcode/simctl (macOS), and Appium `/status`. Here: `npm run doctor` or `npm run setup:demo-android` (APK only). Generated apps use a **vendored** doctor so `npm install` does not require this package on the registry.
+
+Maintainers: `npm run kit:sync`, then publish—see [RELEASING.md](./RELEASING.md) and [packages/mobile-wdio-kit/README.md](./packages/mobile-wdio-kit/README.md).
+
+## CLI tests
+
+```bash
+npm run test:android    # ensures emulator if none online, then WDIO + Appium service
+npm run test:ios        # local Appium; you provide simulator/device
+npm run test:cloud:android
+npm run test:cloud:ios
+```
+
+Demo credentials: `test@webdriver.io` / `Test1234!` (override with `MOBILE_USERNAME` / `MOBILE_PASSWORD`).
+
+## Cursor / MCP (prompt-driven testing)
+
+With the default `.cursor/mcp.json`, **Cursor starts the MCP server via `scripts/mcp-with-appium.sh`**. That script starts **Appium in the background** if nothing is listening on `APPIUM_HOST` / `APPIUM_PORT` (logs under `artifacts/appium-mcp.log`), then runs `wdio-mcp`. If no device is online, it **starts an AVD in the background** but does not wait for a cold boot (Cursor’s MCP client times out if the launcher blocks for minutes). Prefer `adb devices` showing `device` before you enable the MCP server, or wait for the emulator to finish booting before calling `start_session`.
+
+**Do not** set the MCP command to `npm run mcp:server`: npm echoes script lines to stdout, which corrupts the MCP protocol and produces errors like `Unexpected token '>'` / `is not valid JSON`.
+
+To run Appium yourself (e.g. debugging), use `npm run appium:start` or `npx appium --address 127.0.0.1 --port 4723` as before.
+
+### 1. Emulator or device (when not using Cursor MCP)
+
+```bash
+adb devices   # should list one device/emulator as "device"
+```
+
+The MCP launcher runs the same check and can boot an AVD if none is online (see `scripts/android-env.sh`).
+
+### 2. Confirm Appium is ready (optional)
+
+```bash
+npm run mcp:ping-appium
+```
+
+You should see `Appium ready at http://127.0.0.1:4723/status`.
+
+### 3. Cursor
+
+1. Open **this repo** as the workspace root (so `.cursor/mcp.json` `cwd` resolves correctly; if you use a multi-root workspace, set `cwd` in `.cursor/mcp.json` to the full path of this project).
+2. **Cursor Settings → MCP**: ensure **wdio-mcp** is enabled (toggle on). Reload the window after changing MCP config so the new launcher runs.
+3. Start an **Agent** chat with MCP allowed. The workspace rule **`.cursor/rules/wdio-mcp-mobile.mdc`** explains behavior. For this repo’s **WebdriverIO demo** Android APK / iOS `.app`, a **patched** `wdio-mcp` runs the login flow **inside** `start_session` (credentials from `.env`: `MOBILE_USERNAME` / `MOBILE_PASSWORD`; the launcher script sources `.env`). One prompt like “start session” is enough to be **logged in and past the success dialog**, ready to explore. To **skip** that behavior, set `WDIO_MCP_DEMO_AUTO_LOGIN=0` under `env` in `.cursor/mcp.json` and reload.
+
+**Short example prompts**
+
+```text
+Start an Android session (use .env for app path, device, Appium).
+```
+
+```text
+Launch the demo app on the emulator — I want to explore after login.
+```
+
+```text
+Start an iOS session with the .app under apps/ (resolve IOS_APP_PATH from .env), then close_session when done.
+```
+
+**Explicit prompt (Android demo app)**
+
+Use this when you want every capability spelled out. Replace `<ABSOLUTE_PATH_TO_REPO>` with the real path (e.g. from `pwd` in the project root). Match `deviceName` to `adb devices` (often `emulator-5554`).
+
+```text
+Use wdio-mcp tools only. Call start_session for Android with:
+- appPath: <ABSOLUTE_PATH_TO_REPO>/apps/android.wdio.native.app.v2.0.0.apk
+- deviceName: emulator-5554
+- automationName: UiAutomator2
+- autoGrantPermissions: true
+- appiumConfig: host 127.0.0.1, port 4723, path /
+
+Demo login runs inside start_session; use get_elements to explore. close_session when done.
+```
+
+**Explicit prompt (iOS simulator, `.app` bundle)**
+
+Point `appPath` at the **directory** ending in `.app` (from `IOS_APP_PATH`, resolved to an absolute path). Set `platform: ios`, `automationName: XCUITest`, and `deviceName` to your simulator (e.g. from `IOS_DEVICE_NAME` in `.env`).
+
+```text
+Use wdio-mcp only. start_session: platform ios, automationName XCUITest, appPath <ABSOLUTE_PATH_TO_REPO>/apps/ios-demo.app, deviceName iPhone 15, appiumConfig host 127.0.0.1 port 4723 path /. Demo login runs inside start_session; close_session when done.
+```
+
+### 4. Test the MCP stack without Cursor
+
+This starts Appium, runs the official MCP client over stdio, drives the same login flow, then stops Appium:
+
+```bash
+npm run test:mcp:android
+```
+
+### Manual server (debugging)
+
+```bash
+npm run mcp:server:with-appium   # same as Cursor: emulator + Appium + MCP
+npm run mcp:server               # MCP only; Appium must already be running
+```
+
+Use these if you need to run the MCP server outside Cursor’s managed process.
+
+## Validate (no device)
+
+```bash
+npm run validate
+```
+
+## Failure artifacts
+
+On a failed spec, WDIO saves `artifacts/screenshots/<test-title>.png` (see `configs/wdio.shared.ts`).

package/template/THIRD_PARTY.md

@@ -0,0 +1,39 @@
+# Third-party software, trademarks, and demo assets
+
+This document is for **attribution and transparency**. It is **not legal advice**. If you ship a product or publish a package, have your own counsel review licenses and trademark use.
+
+## Trademarks
+
+- **WebdriverIO**, **Appium**, and related marks belong to their respective owners (e.g. OpenJS Foundation / project communities).
+- **Android** is a trademark of Google LLC.
+- **Apple**, **iOS**, **Xcode**, and **Simulator** are trademarks of Apple Inc.
+- **Cursor** is a trademark of Anysphere, Inc.
+- **LambdaTest** is a trademark of LambdaTest Inc.
+
+This project is **not affiliated with, endorsed by, or sponsored by** those organizations unless explicitly stated. Use their marks only in ways that comply with their brand guidelines.
+
+## Demo Android application (APK)
+
+The optional setup script downloads the **WebdriverIO native demo app** binary from the upstream project (default URL is defined in `scripts/download-demo-android.mjs`). That app and its branding are subject to **their** license and terms—not this repo’s `LICENSE` file.
+
+- Source / releases: [webdriverio/native-demo-app](https://github.com/webdriverio/native-demo-app)
+
+Verify the license in that repository before redistributing the APK or using it in commercial contexts.
+
+## npm dependencies
+
+Runtime and development dependencies (WebdriverIO, Appium, drivers, Vitest, `patch-package`, etc.) are each licensed under **their own** terms (MIT, Apache-2.0, and others). After `npm install`, see each package’s `LICENSE` or `package.json` `license` field, or run:
+
+```bash
+npx license-checker --summary
+```
+
+(Install `license-checker` globally or use another SBOM tool you prefer.)
+
+## Patch applied to `@wdio/mcp`
+
+This repo includes a **`patch-package`** patch under `patches/` that modifies `@wdio/mcp` in `node_modules` after install. The **original `@wdio/mcp` code** remains under its upstream license; the patch is a derivative change applied on your machine at install time. Keep the patch file and this notice if you redistribute a project that relies on it.
+
+## `mobile-wdio-kit` npm package
+
+The `packages/mobile-wdio-kit` package **bundles a template** copied from this repository (configs, scripts, tests, etc.) and **vendored doctor scripts**. Publishing that tarball does not transfer ownership of third-party code; attribution and upstream licenses still apply as above.

package/template/apps/.gitkeep

@@ -0,0 +1 @@
+

package/template/configs/wdio.cloud.android.conf.ts

@@ -0,0 +1,31 @@
+import type { Capabilities, Options } from "@wdio/types";
+import { env, requireCloudCredentials } from "../src/env.ts";
+import { sharedMobileConfig } from "./wdio.shared.ts";
+
+const { user, key } = requireCloudCredentials();
+
+export const config: Options.Testrunner &
+  Capabilities.WithRequestedTestrunnerCapabilities = {
+  ...sharedMobileConfig,
+  user,
+  key,
+  protocol: "https",
+  hostname: env.cloudHostname,
+  port: 443,
+  path: env.cloudPath,
+  services: [],
+  capabilities: [
+    {
+      platformName: "Android",
+      "appium:automationName": "UiAutomator2",
+      "appium:deviceName": env.android.cloudDevice,
+      "appium:platformVersion": env.android.cloudPlatformVersion,
+      "appium:app": env.android.cloudApp,
+      "lt:options": {
+        build: `${env.buildName} — Android`,
+        name: "Mobile login",
+        isRealMobile: true,
+      },
+    },
+  ],
+};

package/template/configs/wdio.cloud.ios.conf.ts

@@ -0,0 +1,31 @@
+import type { Capabilities, Options } from "@wdio/types";
+import { env, requireCloudCredentials } from "../src/env.ts";
+import { sharedMobileConfig } from "./wdio.shared.ts";
+
+const { user, key } = requireCloudCredentials();
+
+export const config: Options.Testrunner &
+  Capabilities.WithRequestedTestrunnerCapabilities = {
+  ...sharedMobileConfig,
+  user,
+  key,
+  protocol: "https",
+  hostname: env.cloudHostname,
+  port: 443,
+  path: env.cloudPath,
+  services: [],
+  capabilities: [
+    {
+      platformName: "iOS",
+      "appium:automationName": "XCUITest",
+      "appium:deviceName": env.ios.cloudDevice,
+      "appium:platformVersion": env.ios.cloudPlatformVersion,
+      "appium:app": env.ios.cloudApp,
+      "lt:options": {
+        build: `${env.buildName} — iOS`,
+        name: "Mobile login",
+        isRealMobile: true,
+      },
+    },
+  ],
+};

package/template/configs/wdio.local.android.conf.ts

@@ -0,0 +1,23 @@
+import type { Capabilities, Options } from "@wdio/types";
+import { env } from "../src/env.ts";
+import { sharedMobileConfig } from "./wdio.shared.ts";
+
+export const config: Options.Testrunner &
+  Capabilities.WithRequestedTestrunnerCapabilities = {
+  ...sharedMobileConfig,
+  hostname: env.appiumHost,
+  port: env.appiumPort,
+  path: "/",
+  services: ["appium"],
+  capabilities: [
+    {
+      platformName: "Android",
+      "appium:automationName": "UiAutomator2",
+      "appium:deviceName": env.android.deviceName,
+      ...(env.android.udid ? { "appium:udid": env.android.udid } : {}),
+      "appium:app": env.android.appPath,
+      "appium:autoGrantPermissions": true,
+      "appium:noReset": false,
+    },
+  ],
+};

package/template/configs/wdio.local.ios.conf.ts

@@ -0,0 +1,23 @@
+import type { Capabilities, Options } from "@wdio/types";
+import { env } from "../src/env.ts";
+import { sharedMobileConfig } from "./wdio.shared.ts";
+
+export const config: Options.Testrunner &
+  Capabilities.WithRequestedTestrunnerCapabilities = {
+  ...sharedMobileConfig,
+  hostname: env.appiumHost,
+  port: env.appiumPort,
+  path: "/",
+  services: ["appium"],
+  capabilities: [
+    {
+      platformName: "iOS",
+      "appium:automationName": "XCUITest",
+      "appium:deviceName": env.ios.deviceName,
+      "appium:app": env.ios.appPath,
+      "appium:bundleId": env.ios.bundleId,
+      "appium:autoAcceptAlerts": true,
+      "appium:noReset": false,
+    },
+  ],
+};

package/template/configs/wdio.shared.ts

@@ -0,0 +1,36 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Options } from "@wdio/types";
+import { env } from "../src/env.ts";
+import { safeFilePart } from "../src/lib/safeFilePart.ts";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const specGlob = join(root, "src/specs/**/*.spec.ts");
+
+/** Shared WDIO options for all mobile configs (Mocha + plain specs). */
+export const sharedMobileConfig: Partial<Options.Testrunner> = {
+  runner: "local",
+  specs: [specGlob],
+  maxInstances: 1,
+  logLevel: "info",
+  waitforTimeout: 15_000,
+  connectionRetryTimeout: 120_000,
+  connectionRetryCount: 1,
+  framework: "mocha",
+  mochaOpts: { timeout: 90_000 },
+  reporters: ["spec"],
+  before: () => {
+    mkdirSync(join(env.artifactsDir, "screenshots"), { recursive: true });
+  },
+  afterTest: async (test, _ctx, { passed }) => {
+    if (passed) return;
+    const name = safeFilePart(test.title || "failed");
+    const path = join(env.artifactsDir, "screenshots", `${name}.png`);
+    try {
+      await browser.saveScreenshot(path);
+    } catch {
+      // Session or UiAutomator2 may already be dead (e.g. adb device offline).
+    }
+  },
+};

package/template/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "mobile-agentic-wdio-poc",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "WebdriverIO + Appium mobile tests, Cursor MCP, Vitest (scaffolded via mobile-wdio-kit).",
+  "scripts": {
+    "postinstall": "patch-package",
+    "test:android": "sh scripts/run-android-local.sh",
+    "test:ios": "wdio run configs/wdio.local.ios.conf.ts",
+    "test:cloud:android": "wdio run configs/wdio.cloud.android.conf.ts",
+    "test:cloud:ios": "wdio run configs/wdio.cloud.ios.conf.ts",
+    "test:mcp:android": "sh scripts/run-mcp-android-smoke.sh",
+    "mcp:server": "wdio-mcp",
+    "mcp:server:with-appium": "MCP_BLOCK_UNTIL_EMULATOR_READY=1 sh scripts/mcp-with-appium.sh",
+    "mcp:ping-appium": "node scripts/ping-appium.mjs",
+    "appium:start": "sh scripts/run-appium-local.sh",
+    "appium:driver:android": "appium driver install --source=npm appium-uiautomator2-driver@4.2.9",
+    "appium:driver:ios": "appium driver install xcuitest",
+    "typecheck": "tsc --noEmit",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:coverage": "vitest run --coverage",
+    "validate": "npm run typecheck && npm run test:unit:coverage",
+    "setup:demo-android": "node scripts/download-demo-android.mjs",
+    "doctor": "node scripts/doctor-runner.mjs --cwd ."
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Assign4/mobile-agentic-wdio-poc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Assign4/mobile-agentic-wdio-poc/issues"
+  },
+  "homepage": "https://github.com/Assign4/mobile-agentic-wdio-poc#readme",
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.5.2",
+    "@wdio/appium-service": "^9.27.0",
+    "@wdio/cli": "^9.27.0",
+    "@wdio/local-runner": "^9.27.0",
+    "@wdio/mcp": "^3.2.2",
+    "@wdio/mocha-framework": "^9.27.0",
+    "@wdio/spec-reporter": "^9.27.0",
+    "appium": "^2.19.0",
+    "appium-uiautomator2-driver": "^4.2.9",
+    "dotenv": "^17.4.0",
+    "expect-webdriverio": "^5.6.5",
+    "node-addon-api": "^8.7.0",
+    "node-gyp": "^12.2.0",
+    "patch-package": "^8.0.1",
+    "typescript": "^6.0.2",
+    "vitest": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "webdriverio": "^9.27.0"
+  }
+}

package/template/patches/@wdio+mcp+3.2.2.patch

@@ -0,0 +1,87 @@
+diff --git a/node_modules/@wdio/mcp/lib/server.js b/node_modules/@wdio/mcp/lib/server.js
+index 718f1b4..e9e2a00 100755
+--- a/node_modules/@wdio/mcp/lib/server.js
++++ b/node_modules/@wdio/mcp/lib/server.js
+@@ -3607,6 +3607,65 @@ Note: Unable to set window size (${windowWidth}x${windowHeight}). ${e}`;
+     }]
+   };
+ }
++async function wdioMcpAppendDemoAutoLoginNote(browser, platform2, appPath) {
++  if (process.env.WDIO_MCP_DEMO_AUTO_LOGIN === "0" || process.env.WDIO_MCP_DEMO_AUTO_LOGIN === "false") {
++    return "";
++  }
++  if (!appPath || typeof appPath !== "string") {
++    return "";
++  }
++  const isAndroidDemo = platform2 === "android" && /android\.wdio\.native\.app/i.test(appPath);
++  const isIosDemo = platform2 === "ios" && /ios-demo/i.test(appPath);
++  if (!isAndroidDemo && !isIosDemo) {
++    return "";
++  }
++  const waitMs = 25e3;
++  const user = process.env.MOBILE_USERNAME || "test@webdriver.io";
++  const pass = process.env.MOBILE_PASSWORD || "Test1234!";
++  const clickSel = async (selector) => {
++    await browser.waitUntil(browser.$(selector).isExisting, { timeout: waitMs });
++    await browser.$(selector).scrollIntoView({ block: "center", inline: "center" });
++    await browser.$(selector).click();
++  };
++  const setSel = async (selector, value) => {
++    await browser.waitUntil(browser.$(selector).isExisting, { timeout: waitMs });
++    await browser.$(selector).scrollIntoView({ block: "center", inline: "center" });
++    await browser.$(selector).clearValue();
++    await browser.$(selector).setValue(value);
++  };
++  try {
++    await clickSel("~Login");
++    await clickSel("~button-login-container");
++    await setSel("~input-email", user);
++    await setSel("~input-password", pass);
++    try {
++      await clickSel("~Login-screen");
++    } catch {
++    }
++    await clickSel("~button-LOGIN");
++    const deadline = Date.now() + 2e4;
++    let src = "";
++    while (Date.now() < deadline) {
++      src = await browser.getPageSource();
++      if (/success/i.test(src)) {
++        break;
++      }
++      await new Promise((r) => setTimeout(r, 400));
++    }
++    if (!/success/i.test(src)) {
++      throw new Error("success state not found after tapping LOGIN");
++    }
++    if (isAndroidDemo) {
++      await clickSel('//android.widget.Button[@text="OK"]');
++    } else {
++      await clickSel("~OK");
++    }
++    return "\n\nDemo auto-login: finished (credentials from MOBILE_USERNAME / MOBILE_PASSWORD). Ready for exploration.";
++  } catch (e) {
++    return `
++Demo auto-login failed: ${e}. Session is still active; complete login manually if needed.`;
++  }
++}
+ async function startMobileSession(args) {
+   const { platform: platform2, appPath, app, deviceName, noReset } = args;
+   if (!appPath && !app && noReset !== true) {
+@@ -3640,6 +3699,7 @@ async function startMobileSession(args) {
+     appiumConfig: { hostname: serverConfig.hostname, port: serverConfig.port, path: serverConfig.path },
+     steps: []
+   });
++  const demoLoginNote = await wdioMcpAppendDemoAutoLoginNote(browser, platform2, appPath);
+   const appInfo = appPath ? `
+ App: ${appPath}` : "\nApp: (connected to running app)";
+   const detachNote = shouldAutoDetach ? "\n\n(Auto-detach enabled: session will be preserved on close. Use close_session({ detach: false }) to force terminate.)" : "";
+@@ -3649,7 +3709,7 @@ App: ${appPath}` : "\nApp: (connected to running app)";
+         type: "text",
+         text: `${platform2} app session started with sessionId: ${sessionId}
+ Device: ${deviceName}${appInfo}
+-Appium Server: ${serverConfig.hostname}:${serverConfig.port}${serverConfig.path}${detachNote}`
++Appium Server: ${serverConfig.hostname}:${serverConfig.port}${serverConfig.path}${detachNote}${demoLoginNote}`
+       }
+     ]
+   };