Add EmulatorRunner for emulator CLI operations

src/Xamarin.Android.Tools.AndroidSdk/EnvironmentVariableNames.cs

@@ -40,5 +40,11 @@ internal static class EnvironmentVariableNames
 		/// Executable file extensions (Windows).
 		/// </summary>
 		public const string PathExt = "PATHEXT";
+
+		/// <summary>
+		/// Overrides the default location for Android user-specific data
+		/// (AVDs, preferences, etc.). Defaults to $HOME/.android.
+		/// </summary>
+		public const string AndroidUserHome = "ANDROID_USER_HOME";
 	}
 }

src/Xamarin.Android.Tools.AndroidSdk/Models/AdbDeviceInfo.cs

@@ -0,0 +1,84 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Xamarin.Android.Tools;
+
+/// <summary>
+/// Represents the type of an Android device.
+/// </summary>
+public enum AdbDeviceType
+{
+	Device,
+	Emulator
+}
+
+/// <summary>
+/// Represents the status of an Android device.
+/// </summary>
+public enum AdbDeviceStatus
+{
+	Online,
+	Offline,
+	Unauthorized,
+	NoPermissions,
+	NotRunning,
+	Unknown
+}
+
+/// <summary>
+/// Represents an Android device or emulator from 'adb devices -l' output.
+/// Mirrors the metadata produced by dotnet/android's GetAvailableAndroidDevices task.
+/// </summary>
+public class AdbDeviceInfo
+{
+	/// <summary>
+	/// Serial number of the device (e.g., "emulator-5554", "0A041FDD400327").
+	/// For non-running emulators, this is the AVD name.
+	/// </summary>
+	public string Serial { get; set; } = string.Empty;
+
+	/// <summary>
+	/// Human-friendly description of the device (e.g., "Pixel 7 API 35", "Pixel 6 Pro").
+	/// </summary>
+	public string Description { get; set; } = string.Empty;
+
+	/// <summary>
+	/// Device type: Device or Emulator.
+	/// </summary>
+	public AdbDeviceType Type { get; set; }
+
+	/// <summary>
+	/// Device status: Online, Offline, Unauthorized, NoPermissions, NotRunning, Unknown.
+	/// </summary>
+	public AdbDeviceStatus Status { get; set; }
+
+	/// <summary>
+	/// AVD name for emulators (e.g., "pixel_7_api_35"). Null for physical devices.
+	/// </summary>
+	public string? AvdName { get; set; }
+
+	/// <summary>
+	/// Device model from adb properties (e.g., "Pixel_6_Pro").
+	/// </summary>
+	public string? Model { get; set; }
+
+	/// <summary>
+	/// Product name from adb properties (e.g., "raven").
+	/// </summary>
+	public string? Product { get; set; }
+
+	/// <summary>
+	/// Device code name from adb properties (e.g., "raven").
+	/// </summary>
+	public string? Device { get; set; }
+
+	/// <summary>
+	/// Transport ID from adb properties.
+	/// </summary>
+	public string? TransportId { get; set; }
+
+	/// <summary>
+	/// Whether this device is an emulator.
+	/// </summary>
+	public bool IsEmulator => Type == AdbDeviceType.Emulator;
+}

src/Xamarin.Android.Tools.AndroidSdk/Models/AvdInfo.cs

@@ -0,0 +1,11 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Xamarin.Android.Tools;
+
+public class AvdInfo
+{
+	public string Name { get; set; } = string.Empty;
+	public string? DeviceProfile { get; set; }
+	public string? Path { get; set; }
+}

src/Xamarin.Android.Tools.AndroidSdk/Models/EmulatorBootOptions.cs

@@ -0,0 +1,18 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+
+namespace Xamarin.Android.Tools
+{
+	/// <summary>
+	/// Options for booting an Android emulator.
+	/// </summary>
+	public class EmulatorBootOptions
+	{
+		public TimeSpan BootTimeout { get; set; } = TimeSpan.FromSeconds (300);
+		public string? AdditionalArgs { get; set; }
+		public bool ColdBoot { get; set; }
+		public TimeSpan PollInterval { get; set; } = TimeSpan.FromMilliseconds (500);
+	}
+}

src/Xamarin.Android.Tools.AndroidSdk/Models/EmulatorBootResult.cs

@@ -0,0 +1,15 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Xamarin.Android.Tools
+{
+	/// <summary>
+	/// Result of an emulator boot operation.
+	/// </summary>
+	public class EmulatorBootResult
+	{
+		public bool Success { get; set; }
+		public string? Serial { get; set; }
+		public string? ErrorMessage { get; set; }
+	}
+}

src/Xamarin.Android.Tools.AndroidSdk/ProcessUtils.cs

@@ -203,6 +203,73 @@ static string JoinArguments (string[] args)
 		}
 #endif
 
+		/// <summary>
+		/// Throws <see cref="InvalidOperationException"/> when <paramref name="exitCode"/> is non-zero.
+		/// Includes stderr/stdout context in the message when available.
+		/// </summary>
+		public static void ThrowIfFailed (int exitCode, string command, string? stderr = null, string? stdout = null)
+		{
+			if (exitCode == 0)
+				return;
+
+			var message = $"'{command}' failed with exit code {exitCode}.";
+
+			if (!string.IsNullOrEmpty (stderr))
+				message += $" stderr:{Environment.NewLine}{stderr!.Trim ()}";
+			if (!string.IsNullOrEmpty (stdout))
+				message += $" stdout:{Environment.NewLine}{stdout!.Trim ()}";
+
+			throw new InvalidOperationException (message);
+		}
+
+		/// <summary>
+		/// Validates that <paramref name="value"/> is not null or empty.
+		/// Throws <see cref="ArgumentNullException"/> for null values and
+		/// <see cref="ArgumentException"/> for empty strings.
+		/// </summary>
+		public static void ValidateNotNullOrEmpty (string? value, string paramName)
+		{
+			if (value is null)
+				throw new ArgumentNullException (paramName);
+			if (value.Length == 0)
+				throw new ArgumentException ("Value cannot be an empty string.", paramName);
+		}
+
+		/// <summary>
+		/// Searches versioned cmdline-tools directories (descending) and "latest" for a specific tool binary.
+		/// Falls back to the legacy tools/bin path. Returns null if not found.
+		/// </summary>
+		public static string? FindCmdlineTool (string sdkPath, string toolName, string extension)
+		{
+			var cmdlineToolsDir = Path.Combine (sdkPath, "cmdline-tools");
+
+			if (Directory.Exists (cmdlineToolsDir)) {
+				var subdirs = new List<(string name, Version? version)> ();
+				foreach (var dir in Directory.GetDirectories (cmdlineToolsDir)) {
+					var name = Path.GetFileName (dir);
+					if (string.IsNullOrEmpty (name) || name == "latest")
+						continue;
+					Version.TryParse (name, out var v);
+					subdirs.Add ((name, v ?? new Version (0, 0)));
+				}
+				subdirs.Sort ((a, b) => b.version!.CompareTo (a.version));
+
+				// Check versioned directories first (highest version first), then "latest"
+				foreach (var (name, _) in subdirs) {
+					var toolPath = Path.Combine (cmdlineToolsDir, name, "bin", toolName + extension);
+					if (File.Exists (toolPath))
+						return toolPath;
+				}
+				var latestPath = Path.Combine (cmdlineToolsDir, "latest", "bin", toolName + extension);
+				if (File.Exists (latestPath))
+					return latestPath;
+			}
+
+			// Legacy fallback: tools/bin/<tool>
+			var legacyPath = Path.Combine (sdkPath, "tools", "bin", toolName + extension);
+			return File.Exists (legacyPath) ? legacyPath : null;
+		}
+
 		internal static IEnumerable<string> FindExecutablesInPath (string executable)
 		{
 			var path        = Environment.GetEnvironmentVariable (EnvironmentVariableNames.Path) ?? "";