refactor: use explicit flags for app run argument parsing

Replace heuristic positional parsing (sniffing for '/' or '.apk'/'.app'
in args) with explicit --apk/--app and --device flags. Bare positional
args are still accepted as device names for convenience and backward
compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: abueide

plugins/android/virtenv/scripts/domain/deploy.sh

@@ -303,24 +303,33 @@ android_launch_app() {
 }
 
 # Run Android app (build, install, launch)
-# Usage: android_run_app [apk_path] [device]
-#   apk_path - Optional path to APK file. If provided, skips build step.
-#   device   - Optional device name. If omitted, uses ANDROID_DEFAULT_DEVICE.
+# Usage: android_run_app [--apk <path>] [--device <name>] [<device>]
+#   --apk <path>    - Path to APK file. If provided, skips build step.
+#   --device <name> - Device name. If omitted, uses ANDROID_DEFAULT_DEVICE.
+#   Bare positional arg is treated as device name for convenience.
 android_run_app() {
-  # Parse arguments - first arg could be APK path or device name
   apk_arg=""
   device_choice=""
 
-  if [ $# -gt 0 ]; then
-    # If first arg looks like a file path (contains / or ends with .apk), treat as APK
-    if printf '%s' "$1" | grep -q -e '/' -e '\.apk$'; then
-      apk_arg="$1"
-      shift
-    fi
-  fi
-
-  # Remaining arg is device choice
-  device_choice="${1:-}"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --apk)
+        apk_arg="${2:-}"
+        shift 2
+        ;;
+      --device)
+        device_choice="${2:-}"
+        shift 2
+        ;;
+      *)
+        # Bare positional arg: treat as device name for convenience
+        if [ -z "$device_choice" ]; then
+          device_choice="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
 
   # ---- Resolve Device Selection ----
 

plugins/android/virtenv/scripts/user/android.sh

@@ -39,7 +39,7 @@ Commands:
   emulator reset                   Reset all emulator AVDs
   app status                       Check if deployed app is running
   app stop                         Stop the deployed app
-  run [apk_path] [device]          Start emulator, install, and launch app
+  run [--apk path] [--device name] Start emulator, install, and launch app
 
 Examples:
   android.sh deploy
@@ -55,8 +55,8 @@ Examples:
   android.sh app stop
   android.sh run                             # Start emulator, install, launch
   android.sh run max                         # Same, but on 'max' device
-  android.sh run path/to/app.apk             # Install provided APK
-  android.sh run path/to/app.apk max         # Install APK on 'max' device
+  android.sh run --apk path/to/app.apk      # Install provided APK
+  android.sh run --apk app.apk --device max  # Install APK on 'max' device
 
 Note: Configuration is managed via environment variables in devbox.json.
 Note: Build your app with gradle directly (e.g., cd android && ./gradlew assembleDebug)
@@ -536,23 +536,32 @@ case "$command_name" in
 
   # --------------------------------------------------------------------------
   # run - Build, install, and launch app on emulator
-  # Usage: android.sh run [apk_path] [device]
+  # Usage: android.sh run [--apk <path>] [--device <name>] [device]
   # --------------------------------------------------------------------------
   run)
-    # Parse arguments - first arg could be APK path or device name
+    # Parse arguments
     apk_arg=""
     device_name=""
 
-    if [ $# -gt 0 ]; then
-      # If first arg looks like a file path (contains / or ends with .apk), treat as APK
-      if printf '%s' "$1" | grep -q -e '/' -e '\.apk$'; then
-        apk_arg="$1"
-        shift
-      fi
-    fi
-
-    # Remaining arg is device name
-    device_name="${1:-}"
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --apk)
+          apk_arg="${2:-}"
+          shift 2
+          ;;
+        --device)
+          device_name="${2:-}"
+          shift 2
+          ;;
+        *)
+          # Bare positional arg: treat as device name for convenience
+          if [ -z "$device_name" ]; then
+            device_name="$1"
+          fi
+          shift
+          ;;
+      esac
+    done
 
     # Source layer 3 dependencies
     avd_script="${scripts_dir%/}/domain/avd.sh"
@@ -591,12 +600,16 @@ case "$command_name" in
     android_start_emulator "$device_name"
 
     echo ""
-    # Pass both APK (if provided) and device name to run
+    # Pass both APK (if provided) and device name to run with explicit flags
+    run_args=""
     if [ -n "$apk_arg" ]; then
-      android_run_app "$apk_arg" "$device_name"
-    else
-      android_run_app "$device_name"
+      run_args="--apk $apk_arg"
+    fi
+    if [ -n "$device_name" ]; then
+      run_args="$run_args --device $device_name"
     fi
+    # shellcheck disable=SC2086
+    android_run_app $run_args
     ;;
 
   # --------------------------------------------------------------------------

plugins/ios/virtenv/scripts/domain/deploy.sh

@@ -327,24 +327,33 @@ ios_run_build() {
 # ============================================================================
 
 # Build, install, and launch app on simulator
-# Usage: ios_run_app [app_path] [device]
-#   app_path - Optional path to .app bundle. If provided, skips build step.
-#   device   - Optional device name. If omitted, uses IOS_DEFAULT_DEVICE.
+# Usage: ios_run_app [--app <path>] [--device <name>] [<device>]
+#   --app <path>    - Path to .app bundle. If provided, skips build step.
+#   --device <name> - Device name. If omitted, uses IOS_DEFAULT_DEVICE.
+#   Bare positional arg is treated as device name for convenience.
 ios_run_app() {
-  # Parse arguments - first arg could be .app path or device name
   app_arg=""
   device_choice=""
 
-  if [ $# -gt 0 ]; then
-    # If first arg looks like a path (contains / or ends with .app), treat as app path
-    if printf '%s' "$1" | grep -q -e '/' -e '\.app$'; then
-      app_arg="$1"
-      shift
-    fi
-  fi
-
-  # Remaining arg is device choice
-  device_choice="${1:-}"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --app)
+        app_arg="${2:-}"
+        shift 2
+        ;;
+      --device)
+        device_choice="${2:-}"
+        shift 2
+        ;;
+      *)
+        # Bare positional arg: treat as device name for convenience
+        if [ -z "$device_choice" ]; then
+          device_choice="$1"
+        fi
+        shift
+        ;;
+    esac
+  done
 
   # ---- Start Deployment ----
 

plugins/ios/virtenv/scripts/user/ios.sh

@@ -14,7 +14,7 @@ Commands:
   simulator reset
   app status                 Check if deployed app is running
   app stop                   Stop the deployed app
-  run [app_path] [device]    Start simulator, install, and launch app
+  run [--app path] [--device name]  Start simulator, install, and launch app
   xcodebuild [args...]
   config show
   info
@@ -486,7 +486,40 @@ case "$command_name" in
   run)
     # shellcheck disable=SC1090
     . "${script_dir}/domain/deploy.sh"
-    ios_run_app "$@"
+
+    # Parse arguments
+    _run_app_arg=""
+    _run_device=""
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --app)
+          _run_app_arg="${2:-}"
+          shift 2
+          ;;
+        --device)
+          _run_device="${2:-}"
+          shift 2
+          ;;
+        *)
+          # Bare positional arg: treat as device name for convenience
+          if [ -z "$_run_device" ]; then
+            _run_device="$1"
+          fi
+          shift
+          ;;
+      esac
+    done
+
+    # Forward with explicit flags
+    _run_args=""
+    if [ -n "$_run_app_arg" ]; then
+      _run_args="--app $_run_app_arg"
+    fi
+    if [ -n "$_run_device" ]; then
+      _run_args="$_run_args --device $_run_device"
+    fi
+    # shellcheck disable=SC2086
+    ios_run_app $_run_args
     ;;
   config)
     sub="${1-}"