doc updates & app id detection

Author: abueide

README.md

@@ -5,19 +5,39 @@ Reproducible, project-local development environments for Android, iOS, and React
 ## Quick Start
 
 ```bash
-# Add Android plugin to your project
-echo '{
-  "include": ["github:segment-integrations/devbox-plugins?dir=plugins/android"]
-}' > devbox.json
+# Initialize devbox in your project
+devbox init
+
+# Add the Android plugin include to your devbox.json
+# (devbox add only works for packages, not plugins — edit devbox.json manually)
+```
 
+Add the plugin to your `devbox.json`:
+
+```json
+{
+  "include": ["github:segment-integrations/devbox-plugins?dir=plugins/android"],
+  "packages": {
+    "jdk17": "latest",
+    "gradle": "latest"
+  },
+  "env": {
+    "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk"
+  }
+}
+```
+
+```bash
 # Enter development environment
 devbox shell
 
 # Start emulator and run app
-devbox run start-emu
-devbox run start-app
+devbox run start:emu
+devbox run start
 ```
 
+The app's package name is auto-detected from the APK at install time.
+
 **New to devbox-plugins?** Check out the [Quick Start Guide](wiki/guides/quick-start.md) for detailed setup instructions.
 
 ## Features
@@ -103,14 +123,14 @@ Each example includes device definitions, test suites, and build scripts.
 
 ```bash
 # Android
-devbox run start-emu        # Start Android emulator
-devbox run start-app        # Build and launch app
-devbox run stop-emu         # Stop emulator
+devbox run start:emu        # Start Android emulator
+devbox run start            # Build, install, and launch app
+devbox run stop:emu         # Stop emulator
 
 # iOS
-devbox run start-sim        # Start iOS simulator
-devbox run start-ios        # Build and launch app
-devbox run stop-sim         # Stop simulator
+devbox run start:sim        # Start iOS simulator
+devbox run start:ios        # Build and launch app
+devbox run stop:sim         # Stop simulator
 
 # Device management
 devbox run android.sh devices list

devbox.json

@@ -102,6 +102,9 @@
       "test:plugin:android:devices": [
         "bash plugins/tests/android/test-devices.sh"
       ],
+      "test:plugin:android:apk-detection": [
+        "(cd examples/android && devbox run bash ../../plugins/tests/android/test-apk-detection.sh)"
+      ],
       "test:plugin:android:emulator-detection": [
         "(cd examples/android && devbox run bash ../../plugins/tests/android/test-emulator-detection.sh)"
       ],
@@ -110,7 +113,8 @@
       ],
       "test:plugin:android": [
         "devbox run test:plugin:android:lib",
-        "devbox run test:plugin:android:devices"
+        "devbox run test:plugin:android:devices",
+        "devbox run test:plugin:android:apk-detection"
       ],
       "test:plugin:android:all": [
         "echo 'Running all Android plugin tests (including emulator tests)...'",

examples/android/devbox.d/android/devices/devices.lock

@@ -14,5 +14,5 @@
     }
   ],
   "checksum": "8df4d3393b61fbbb08e45cf8762f95c521316938e514527916e4fce88a849d57",
-  "generated_at": "2026-02-18T16:48:27Z"
+  "generated_at": "2026-02-18T17:45:12Z"
 }

examples/android/devbox.json

@@ -20,7 +20,7 @@
       "stop:emu": [
         "android.sh emulator stop"
       ],
-      "run": [
+      "start": [
         "android.sh run ${1:-${ANDROID_DEFAULT_DEVICE:-max}}"
       ],
       "test": [

examples/android/tests/test-suite.yaml

@@ -123,12 +123,19 @@ processes:
       android.sh run ${ANDROID_APP_APK:-app/build/outputs/apk/debug/app-debug.apk}
 
       echo ""
-      echo "Waiting for app to start..."
+      # Resolve app ID: env var > auto-detected from APK > fail
+      app_id="${ANDROID_APP_ID:-$(cat ${ANDROID_RUNTIME_DIR}/app-id.txt 2>/dev/null || true)}"
+      if [ -z "$app_id" ]; then
+        echo "ERROR: Cannot determine app ID. Set ANDROID_APP_ID or run deploy first." >&2
+        exit 1
+      fi
+
+      echo "Waiting for app to start ($app_id)..."
       max_attempts=10
       attempt=0
       while [ $attempt -lt $max_attempts ]; do
-        if adb -s $serial shell pidof ${ANDROID_APP_ID:-com.example.devbox} >/dev/null 2>&1; then
-          echo "✓ App process running (PID: $(adb -s $serial shell pidof ${ANDROID_APP_ID:-com.example.devbox}))"
+        if adb -s $serial shell pidof "$app_id" >/dev/null 2>&1; then
+          echo "✓ App process running (PID: $(adb -s $serial shell pidof "$app_id"))"
           exit 0
         fi
         attempt=$((attempt + 1))
@@ -161,7 +168,8 @@ processes:
       # In pure mode (CI), stop app and emulator for reproducibility
       if [ "${IN_NIX_SHELL:-}" = "pure" ]; then
         echo "🧹 Cleaning up (pure mode): stopping app and emulator..."
-        adb -s $serial shell am force-stop ${ANDROID_APP_ID:-com.example.devbox} 2>/dev/null || true
+        app_id="${ANDROID_APP_ID:-$(cat ${ANDROID_RUNTIME_DIR}/app-id.txt 2>/dev/null || true)}"
+        [ -n "$app_id" ] && adb -s $serial shell am force-stop "$app_id" 2>/dev/null || true
         android.sh emulator stop || true
         echo "✓ App stopped, emulator stopped"
       else

examples/react-native/devbox.d/android/devices/devices.lock

@@ -14,5 +14,5 @@
     }
   ],
   "checksum": "f5bfab3fdcbe8a23858954c18b1fa86d28a3316e801523aa6d4aa72ca9cf5ab7",
-  "generated_at": "2026-02-18T17:12:39Z"
+  "generated_at": "2026-02-18T17:21:12Z"
 }

examples/react-native/devbox.d/ios/devices/devices.lock

@@ -10,5 +10,5 @@
     }
   ],
   "checksum": "4d5276f203d7ad62860bfc067f76194df53be449d4aa8a3b2d069855ec1f3232",
-  "generated_at": "2026-02-18T17:12:40Z"
+  "generated_at": "2026-02-18T17:21:13Z"
 }

examples/react-native/tests/test-suite-all-e2e.yaml

@@ -266,12 +266,19 @@ processes:
       . ${ANDROID_RUNTIME_DIR}/scripts/init/setup.sh
       serial=$(cat ${ANDROID_RUNTIME_DIR}/emulator-serial.txt 2>/dev/null || echo emulator-5554)
 
-      echo "Waiting for app to start..."
+      # Resolve app ID: env var > auto-detected from APK > fail
+      app_id="${ANDROID_APP_ID:-$(cat ${ANDROID_RUNTIME_DIR}/app-id.txt 2>/dev/null || true)}"
+      if [ -z "$app_id" ]; then
+        echo "ERROR: Cannot determine app ID. Set ANDROID_APP_ID or run deploy first." >&2
+        exit 1
+      fi
+
+      echo "Waiting for app to start ($app_id)..."
       max_attempts=10
       attempt=0
       while [ $attempt -lt $max_attempts ]; do
-        if adb -s $serial shell pidof ${ANDROID_APP_ID:-com.reactnativeexample} >/dev/null 2>&1; then
-          echo "✓ App process running (PID: $(adb -s $serial shell pidof ${ANDROID_APP_ID:-com.reactnativeexample}))"
+        if adb -s $serial shell pidof "$app_id" >/dev/null 2>&1; then
+          echo "✓ App process running (PID: $(adb -s $serial shell pidof "$app_id"))"
           exit 0
         fi
         attempt=$((attempt + 1))
@@ -333,7 +340,8 @@ processes:
         # Cleanup Android
         . ${ANDROID_RUNTIME_DIR}/scripts/init/setup.sh
         serial=$(cat ${ANDROID_RUNTIME_DIR}/emulator-serial.txt 2>/dev/null || echo emulator-5554)
-        adb -s $serial shell am force-stop ${ANDROID_APP_ID:-com.reactnativeexample} 2>/dev/null || true
+        app_id="${ANDROID_APP_ID:-$(cat ${ANDROID_RUNTIME_DIR}/app-id.txt 2>/dev/null || true)}"
+        [ -n "$app_id" ] && adb -s $serial shell am force-stop "$app_id" 2>/dev/null || true
         android.sh emulator stop || true
 
         # Cleanup iOS

examples/react-native/tests/test-suite-android-e2e.yaml

@@ -173,12 +173,19 @@ processes:
       . ${ANDROID_RUNTIME_DIR}/scripts/init/setup.sh
       serial=$(cat ${ANDROID_RUNTIME_DIR}/emulator-serial.txt 2>/dev/null || echo emulator-5554)
 
-      echo "Waiting for app to start..."
+      # Resolve app ID: env var > auto-detected from APK > fail
+      app_id="${ANDROID_APP_ID:-$(cat ${ANDROID_RUNTIME_DIR}/app-id.txt 2>/dev/null || true)}"
+      if [ -z "$app_id" ]; then
+        echo "ERROR: Cannot determine app ID. Set ANDROID_APP_ID or run deploy first." >&2
+        exit 1
+      fi
+
+      echo "Waiting for app to start ($app_id)..."
       max_attempts=10
       attempt=0
       while [ $attempt -lt $max_attempts ]; do
-        if adb -s $serial shell pidof ${ANDROID_APP_ID:-com.reactnativeexample} >/dev/null 2>&1; then
-          echo "✓ App process running (PID: $(adb -s $serial shell pidof ${ANDROID_APP_ID:-com.reactnativeexample}))"
+        if adb -s $serial shell pidof "$app_id" >/dev/null 2>&1; then
+          echo "✓ App process running (PID: $(adb -s $serial shell pidof "$app_id"))"
           exit 0
         fi
         attempt=$((attempt + 1))
@@ -210,7 +217,8 @@ processes:
 
       if [ "${IN_NIX_SHELL:-}" = "pure" ]; then
         echo "🧹 Cleaning up (pure mode)..."
-        adb -s $serial shell am force-stop ${ANDROID_APP_ID:-com.reactnativeexample} 2>/dev/null || true
+        app_id="${ANDROID_APP_ID:-$(cat ${ANDROID_RUNTIME_DIR}/app-id.txt 2>/dev/null || true)}"
+        [ -n "$app_id" ] && adb -s $serial shell am force-stop "$app_id" 2>/dev/null || true
         android.sh emulator stop || true
         echo "✓ App stopped, emulator stopped"
       else

plugins/android/REFERENCE.md

@@ -61,7 +61,7 @@ Configure the plugin by setting environment variables in `plugin.json`. These ar
 
 ### Run app
 
-- `devbox run run [apk_path] [device]`
+- `devbox run start [apk_path] [device]`
   - Builds, installs, and launches the app on the emulator
   - If `apk_path` is provided, skips build step and installs provided APK
   - If no arguments, builds project and installs APK matched by `ANDROID_APP_APK`