@ycodium-ai/plugin-devices 0.2.3817 → 0.2.3904

package/skills/mobile-devices/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: mobile-devices
+description: Build, install, run, and operate a mobile app on an Android Emulator or iOS Simulator through the Devices plugin, then verify its screens, forms, and logs. Use when a task needs an app running on a device, not only unit tests. Covers React Native and Expo, Flutter, and native projects, and what to do when build tools are missing.
+---
+
+# Mobile devices
+
+Use the Devices plugin to run a mobile app on an emulator or simulator on the machine hosting this conversation, and to check what the app really does. The user can watch the same device in the Devices panel.
+
+## Find the tools
+
+The plugin provides `devices_device_list`, `devices_device_open`, `devices_device_screenshot`, and `devices_device_close`. Your harness may add its usual MCP server prefix. If the plugin was enabled during the conversation and these names are missing, use `ycodium_plugin_tools` with `pluginId: "devices"` and call the returned tools through `ycodium_plugin_call`.
+
+Everything else goes through the `agent-device` command that `devices_device_open` returns.
+
+## Open a device
+
+1. Call `devices_device_list`. It reports which platforms this machine can run, why one is unavailable, and which devices exist.
+2. Call `devices_device_open` with a `deviceId`, or with a `platform` to use the booted device or the first one. It boots the device and shows it to the user.
+3. Keep the returned `agentDevice.command` and `targetArgs`. Use that exact executable and pass those flags on every command, because a login shell may reset `PATH`.
+
+iOS Simulators need macOS with Xcode. On Windows and Linux, test Android and say that iOS was not run.
+
+If no Android device exists, ask the user to choose **Prepare simulator environment** in the Devices panel. It downloads a private SDK and one API 35 emulator; it needs no system-wide install and takes several minutes. The same panel adds an API 30 emulator when a task needs an older Android.
+
+## Drive and inspect
+
+```text
+<agent-device> open <package-or-bundle-id> <flags>     # or: open <app> <deep-link-url>
+<agent-device> snapshot -i <flags>                     # accessibility tree with @eN refs
+<agent-device> click @e3 <flags>
+<agent-device> fill @e5 "text" <flags>
+<agent-device> screenshot <file.png> <flags>
+<agent-device> install <app> <path-to-.apk-or-.app> <flags>
+<agent-device> help                                    # workflow guides
+```
+
+Prefer snapshot refs to coordinates, and take a new snapshot after every navigation because refs go stale. The first Android snapshot installs a small helper app on the device. `devices_device_screenshot` shows you what the user sees.
+
+`adb`, `xcrun simctl`, and the like remain available for anything `agent-device` does not cover. The private Android SDK is not on `PATH`: its tools are under `<Ycodium home>/plugin-data/devices/environments/android/sdk/platform-tools`.
+
+## Build and install
+
+Pick the lightest route that covers the change. JavaScript-only changes need a bundler, not a native rebuild. Native code, native dependencies, and config plugins need a rebuild.
+
+### React Native and Expo
+
+Start the bundler on a free port, then make it reachable from the emulator and open the development client:
+
+```sh
+npx expo start --dev-client --lan --port <port>
+adb -s <serial> reverse tcp:<port> tcp:<port>
+adb -s <serial> shell am start -W -a android.intent.action.VIEW \
+  -d '<scheme>://expo-development-client/?url=http%3A%2F%2Flocalhost%3A<port>'
+```
+
+Set `REACT_NATIVE_PACKAGER_HOSTNAME=localhost` so the client asks for `localhost`. Build a development APK once with `npx expo prebuild` and `./gradlew :app:assembleDebug -PreactNativeArchitectures=x86_64`, then install it. Only that one ABI is needed for an x86_64 emulator, and building it is much faster.
+
+The development client opens a developer menu on first launch. Dismiss it before sending the app a deep link, or the link is dropped without an error. Changing the device font scale recreates the activity and reopens that menu.
+
+### Flutter
+
+```sh
+flutter devices
+flutter run -d <serial>
+```
+
+### Native Android and iOS
+
+```sh
+./gradlew :app:assembleDebug      # then install app/build/outputs/apk/debug/app-debug.apk
+xcodebuild -scheme <scheme> -sdk iphonesimulator -derivedDataPath build
+```
+
+The Android Emulator reaches the host machine at `10.0.2.2`. The iOS Simulator shares the host's `127.0.0.1`.
+
+## Check the result
+
+- Confirm the running code is the code you changed: the bundle came from this project's bundler, or the APK was built after the edit.
+- Exercise the real flow on the device, then read the screen with a snapshot or screenshot. A successful command only means input was delivered.
+- Read logs for failures: `adb -s <serial> logcat -d -t 400`. React Native sends JavaScript logs to the bundler's output rather than to logcat.
+- Report what was not run, such as iOS on a Windows machine.
+
+## Missing tools
+
+| Missing                     | What to do                                                                                                     |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Android SDK or emulator     | Have the user prepare the environment in the Devices panel                                                     |
+| Gradle, NDK, or build-tools | Install with `sdkmanager` into a project-owned SDK. The private Devices SDK holds only what the emulator needs |
+| JDK                         | Install JDK 17 and set `JAVA_HOME`. The private environment does not include one                               |
+| Xcode                       | Tell the user iOS needs Xcode on macOS, and continue on Android if the change allows it                        |
+
+## Windows path limits
+
+Native Android builds fail on Windows when a path reaches 260 characters, which `node_modules` managed by pnpm makes easy. The usual signs are `build.ninja still dirty` and `Stat failed`.
+
+- Move CMake output to a short directory, for example through `gradle.beforeProject` in `settings.gradle`, setting `android.externalNativeBuild.cmake.buildStagingDirectory` to a path such as `C:/cx/<project>`.
+- With pnpm, set `virtualStoreDirMaxLength: 40` in `pnpm-workspace.yaml` and reinstall.
+- If Metro crashes with `EMFILE`, limit file concurrency or exclude large directories from its watcher.
+- If Gradle fails a TLS handshake through a local proxy, pass `-Djava.net.useSystemProxies=false` and add download retries.
+
+## When something stalls
+
+- If `adb` hangs or the panel says the ADB server did not answer, a target of `adb reverse` may have died. On Windows this stalls the whole adb server until something listens on that port again. Listen on the port briefly, then remove the rule with `adb reverse --remove`.
+- If a phone-sized app runs out of memory, debug React Native builds can use more than 1.5 GB. The private emulator has 2 GB, so a release build is the fair test of memory.
+- If the panel shows no video, read the error in the panel first, then check `adb devices`.
+
+## Finish
+
+Remove rules you added with `adb reverse` first, then stop only the bundlers and servers you started. Stopping a server while its rule is still in place can stall adb. Call `devices_device_close` when done, with `shutdown: true` only if the user wants the device off.