Add simulator app lifecycle APIs (install/uninstall/launch/terminate/get_app_container)

[rmarinho]

Summary

Add app lifecycle management APIs to Xamarin.MacDev.SimulatorService so the MAUI DevTools CLI can install, launch, terminate, and uninstall apps on iOS/tvOS/watchOS/visionOS simulators without consumers shelling out to xcrun simctl directly.

Context

SimulatorService already exposes List, Create, Boot, Shutdown, Erase, and Delete (added in #149). The next gap for MAUI tooling is the post-boot app loop. Today, both the MAUI DevTools CLI and DevFlow integration tests fall back to raw xcrun simctl install|launch|terminate|uninstall — see maui-labs#197 for the full audit.

The SimCtl low-level wrapper is already in place and RunJson (PR #170) supports --json-output for any subcommand that needs structured parsing.

Proposed API

namespace Xamarin.MacDev;

public partial class SimulatorService
{
    /// Install an app bundle (.app) onto a booted simulator.
    /// Pattern: xcrun simctl install <udid> <path>
    public bool Install(string udidOrName, string appBundlePath);

    /// Uninstall an app by bundle identifier.
    /// Pattern: xcrun simctl uninstall <udid> <bundleId>
    public bool Uninstall(string udidOrName, string bundleIdentifier);

    /// Launch an app by bundle identifier. Returns the launched process ID, or null on failure.
    /// Pattern: xcrun simctl launch [--console] [--terminate-running-process] <udid> <bundleId> [args...]
    public int? Launch(
        string udidOrName,
        string bundleIdentifier,
        IEnumerable<string>? args = null,
        IDictionary<string, string>? environment = null,
        bool waitForDebugger = false,
        bool terminateRunningProcess = false);

    /// Terminate a running app by bundle identifier.
    /// Pattern: xcrun simctl terminate <udid> <bundleId>
    public bool Terminate(string udidOrName, string bundleIdentifier);

    /// Get the install path of an installed app, or null if not installed.
    /// Pattern: xcrun simctl get_app_container <udid> <bundleId>
    public string? GetAppContainer(string udidOrName, string bundleIdentifier, AppContainer container = AppContainer.App);
}

public enum AppContainer { App, Data, Groups }

Launch should parse the xcrun simctl launch output of the form com.example.app: 12345 to extract the PID, with the same logging conventions as Create.

environment keys are passed via xcrun simctl launch --setenv KEY=VALUE (one flag per pair).

Consumer

• MAUI DevTools CLI (dotnet/maui-labs) — maui apple simulator install|uninstall|launch|stop|app-container subcommands. See maui-labs#197 audit.
• DevFlow integration tests (dotnet/maui-labs) — iOSSimulatorFixture, MacCatalystFixture currently call xcrun simctl directly to install + launch the sample app.
• IDE extensions for the Run on simulator flow.

Related

• Add simulator management APIs (maui apple simulator) #149 (closed) — original simulator management APIs (List/Create/Boot/Shutdown/Erase/Delete)
• Add simulator runtime management APIs (maui apple runtime) #150 (closed) — runtime management
• Use simctl --json-output flag to avoid stdout pollution #170 (merged) — simctl --json-output support
• maui-labs #197 — DevFlow skill audit, consumer follow-up

Out of scope

launch --console-pty, launch --start-suspended, and launch --wait-for-debugger are documented but can be added in follow-up issues if/when consumers need them. This issue covers the minimum surface MAUI DevTools needs.