mobitru-mobile-cli 1.0.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 1.0.0
+
+Initial release. Drives real Android and iOS devices on Mobitru cloud via Appium.
+
+- Device booking (immediate use + future reservations) — native or web sessions, custom lease duration
+- Observation: screenshots, accessibility snapshots, screen-size, orientation
+- Interaction: taps by ref or pixel coordinates, typing, swipes (directional + multi-point), hardware button presses
+- Apps: launch / terminate / is-installed / install / OTA install / uninstall
+- Artifacts: list, info, upload (APK/IPA, target auto-detected), download
+- Recording (screen video), device logs (logcat / syslog), crashlogs
+- Network conditions: throttling (named presets + custom bandwidth/latency), device GPS, outbound IP geolocation
+- HTTP traffic capture (HAR, Android only)
+- CPU/memory profiler, camera image mock, biometric touch mock
+- Espresso (Android) and XCUITest (iOS) test runs — async submit + status polling
+- Custom Appium scripts via `appium-run` (mocha-style, single-job-at-a-time)
+- Web sessions: `open-url`, `click-web-element`
+- Session state persists across CLI invocations
+- Bundled agent skill installable via `mobitru-mobile-cli install --skills=claude|agents`

package/README.md

@@ -0,0 +1,201 @@
+# mobitru-mobile-cli
+
+CLI for AI agents to automate mobile app testing on the Mobitru cloud platform.
+
+Drives a **real Android phone or iOS device on Mobitru cloud** via Appium. Session state (active booking, Appium session) persists across short-lived CLI invocations so each command stays cheap. No local emulator.
+
+## Installation
+
+```bash
+npm install -g mobitru-mobile-cli
+```
+
+## Quick start
+
+```bash
+# 1. Configure once (env vars OR ~/.mobitru-cli/config.json)
+export DEVICE_FARM_BASE_URL=app.mobitru.com
+export DEVICE_FARM_API_KEY=mobitru_ak_...
+export DEVICE_FARM_SLUG=your-slug
+
+# 2. Automate
+mobitru-mobile-cli device-list android
+mobitru-mobile-cli device-use <serial>
+mobitru-mobile-cli snapshot
+mobitru-mobile-cli tap e3
+mobitru-mobile-cli type "user@example.com" --submit
+mobitru-mobile-cli screenshot
+mobitru-mobile-cli device-release
+```
+
+## Configuration
+
+Credentials are resolved in order: **env vars → `~/.mobitru-cli/config.json`**.
+
+| Field | Env var | Description |
+|---|---|---|
+| `baseUrl` | `DEVICE_FARM_BASE_URL` | Mobitru REST API host |
+| `apiKey` | `DEVICE_FARM_API_KEY` | API key (`mobitru_ak_...`) |
+| `slug` | `DEVICE_FARM_SLUG` | Billing/workspace slug |
+| `wid` | `DEVICE_FARM_WID` | Workspace ID (default `"0"`) |
+
+```bash
+mobitru-mobile-cli config          # inspect resolved credentials (api key redacted)
+```
+
+## Session lifecycle
+
+```bash
+mobitru-mobile-cli device-list android                # ios | android
+mobitru-mobile-cli device-use <serial>                # native session, 180-min lease
+mobitru-mobile-cli device-use <serial> --duration=30  # custom lease in minutes
+mobitru-mobile-cli device-use <serial> --web          # browser (web) session
+
+mobitru-mobile-cli device-release                     # release cloud slot (always do this)
+mobitru-mobile-cli stop                               # release + reset session state
+```
+
+> ⚠️ **One active booking at a time.** Switching devices requires `device-release` first, then a 30-60s cloud cleanup window before the released serial is re-bookable. Pick a different serial to recover faster.
+
+Switching between native and web sessions on the **same device** is fast (~5-10s, booking preserved). Switching to a **different device** incurs the cleanup window.
+
+## Parallel devices
+
+The CLI holds one device per daemon. For multiple devices in parallel, run separate CLIs with isolated daemon dirs:
+
+```bash
+# Terminal 1
+MOBITRU_CLI_HOME=/tmp/run-a mobitru-mobile-cli device-use <serial-a>
+
+# Terminal 2
+MOBITRU_CLI_HOME=/tmp/run-b mobitru-mobile-cli device-use <serial-b>
+```
+
+Each daemon has its own state, socket, and Appium session — they never collide.
+
+## Commands
+
+### Observation
+```bash
+screenshot [--output=<path>]               # PNG to disk; stdout: { path, bytes }
+snapshot [--output=<path>]                 # AX tree to disk; stdout: { path, refCount }
+screen-size                                # device pixel dimensions
+```
+
+### Interaction
+```bash
+tap <ref>                                  # tap an element by snapshot ref (e1..eN)
+tap-at <x> <y>                             # tap raw pixel coordinates
+type <text> [--submit]                     # type into focused field; --submit presses ENTER
+swipe <up|down|left|right> [--force=0.5]   # full-screen directional gesture
+continuous-swipe <x,y> <x,y> [...]         # multi-point drag (2..20 points)
+press <HOME|BACK|VOLUME_UP|VOLUME_DOWN|ENTER|DPAD_*>
+get-orientation | set-orientation <portrait|landscape>
+```
+
+### Web session
+```bash
+open-url <url>                             # navigate the device browser (--web sessions only)
+click-web-element <selector>               # CSS selector click
+```
+
+### Apps
+```bash
+launch <app-id>                            # com.android.chrome / com.apple.mobilesafari
+terminate <app-id>
+is-installed <app-id>
+install-app <artifact-id>                  # blocks until installation completes
+install-app-ota <ota-url>                  # iOS only — install from OTA manifest
+uninstall-app <app-id>
+```
+
+### Artifacts
+```bash
+artifacts-list
+artifacts-info <id>
+artifacts-upload <file> [--alias=<name>]   # APK or IPA; target auto-detected by extension
+artifacts-download <id> [--output=<path>]
+```
+
+### Bookings (future reservations)
+```bash
+bookings-list [--till=<iso>]
+bookings-info <id>
+booking-create --name=<n> --start=<iso> --end=<iso> --devices=<serial>[,<serial>...] [--private]
+booking-cancel <id>
+```
+
+### Recording, logs, crashlogs
+```bash
+recording-start                            # screen video; returns max-duration
+recording-stop                             # returns recordingId
+recording-download <recordingId> [--output=<path>]
+logs-start | logs-stop                     # device logs (logcat / syslog)
+crashlogs [--output=<path>]                # zip of crash reports
+```
+
+### Network conditions
+```bash
+throttling-presets                         # list named presets
+throttling-status
+throttling-enable <preset>                 # 3g, 4g, edge, custom, ...
+throttling-enable custom --download=<kbps> --upload=<kbps> --latency=<ms>
+throttling-disable
+
+geolocation-get | geolocation-set <lat> <lng>
+ip-location-list | ip-location-set <country-code|DEFAULT>
+```
+
+### HTTP traffic, profiler, mock injection
+```bash
+http-inspection-start [--capture-binary] [--no-capture-response-content]   # Android only
+http-inspection-stop
+har-download <har-id> [--output=<path>]
+
+profiler-start <appPackage>                # target must be running
+profiler-stop [--output=<path>]
+
+inject-image <path> [--content-type=<mime>] [--name=<file>]   # camera frame mock
+inject-touch <valid|invalid>                                  # biometric mock
+```
+
+### Test runs
+```bash
+espresso-run --app=<id> --test=<id> --runner=<class> [--serial=<s>] [--filter=...] [--shards=N]
+xcuitest-run --serial=<s> --app=<id> --test=<id> [--no-resign]
+espresso-list | espresso-status <run-id> | espresso-cancel <run-id>
+xcuitest-list | xcuitest-status <run-id> | xcuitest-cancel <run-id>
+```
+
+### Appium scripts (custom WebDriver tests)
+```bash
+appium-run <script.js> [--timeout=<ms>] [--capabilities=<json>]
+appium-status | appium-logs | appium-cancel
+```
+
+### Lifecycle
+```bash
+status                                     # show session state
+stop                                       # release device + reset session
+config                                     # inspect resolved credentials
+```
+
+## Artifacts
+
+Auto-generated files (screenshots, snapshots, recordings, logs, …) land in the **artifact directory**:
+
+| Setting | Path |
+|---|---|
+| Default | `<CWD>/.mobitru-mobile-cli/` |
+| Override | `MOBILE_CLI_OUTPUT_DIR=/your/path mobitru-mobile-cli ...` |
+
+The artifact dir is resolved **per-invocation** from the shell CWD. If you `cd` between commands, files land relative to the new CWD. Pass `--output=<absolute-path>` for unambiguous placement, or stay in one directory for the duration of a session.
+
+## Agent skill
+
+Install the bundled skill so your agent knows how to use the CLI:
+
+```bash
+mobitru-mobile-cli install --skills=claude     # → .claude/skills/mobitru-mobile-cli/
+mobitru-mobile-cli install --skills=agents     # → .agents/skills/mobitru-mobile-cli/
+```