[AdbRunner] Add ADB forward port management (#351)

(follow-up to #305)

Adds the symmetric forward-port pair to the reverse-port methods that landed
in #305. Same `AdbPortSpec` / `AdbPortRule` / `AdbProtocol` types — just four
new methods.

| Method                                          | adb command                                |
|-------------------------------------------------|--------------------------------------------|
| ForwardPortAsync(serial, local, remote)         | adb -s <serial> forward <local> <remote>   |
| RemoveForwardPortAsync(serial, local)           | adb -s <serial> forward --remove <local>   |
| RemoveAllForwardPortsAsync(serial)              | adb -s <serial> forward --remove-all       |
| ListForwardPortsAsync(serial)                   | adb forward --list (filtered by serial)    |

`adb forward` and `adb reverse` are not interchangeable — they connect
opposite directions. `forward` is host->device (the IDE/harness reaches a
service running on the device) and is the path used for JDWP debugger
attach (`forward tcp:N jdwp:<pid>`), perf-tracing endpoints exposed by the
runtime, and host-side DevFlow agent connect when the agent listens on a
device port.

Output-format note for `--list`: `adb forward --list` emits one line per
rule across all devices in the form `<serial> <local> <remote>` (different
from `(reverse) <remote> <local>`). `ListForwardPortsAsync` uses the
unscoped `adb forward --list` and filters to the requested serial in
`ParseForwardListOutput`. Serial match is case-sensitive (matches adb).

- 12 new parser tests in `ParseForwardListOutput_*` mirroring the reverse
  parser tests (single rule, multiple rules, serial filtering, empty
  output, malformed lines, non-tcp specs, Windows line endings, tab
  separation, case sensitivity).
- 7 new parameter-validation tests covering empty serial / null spec for
  the four new public methods.

- VS Code MAUI extension ServiceHub->CLI migration (`forwardPort` in
  `MauiAndroidPlatform.ts` — debugger configurations, perf tooling).
- MAUI DevTools CLI (dotnet/maui-labs#197) — `maui android port forward`
  group, sibling of the existing `reverse` surface.
- Visual Studio `ClientTools.Platform` — same paths that drive reverse
  today.

Discussed in
#305 (comment)

### Address review feedback: capture stdout in ThrowIfFailed, parser asymmetry comment, drop null!, remove test region dividers

- ForwardPortAsync/RemoveForwardPortAsync/RemoveAllForwardPortsAsync now capture stdout and pass it to ProcessUtils.ThrowIfFailed (matches repo convention; adb sometimes writes errors to stdout).

- Added <remarks> block on ParseForwardListOutput calling out the field-order asymmetry vs ParseReverseListOutput (forward: serial local remote; reverse: (reverse) remote local).

- Replaced '(AdbPortSpec) null!' with '(AdbPortSpec) null' in 3 forward-port test sites to match reverse-test convention and repo no-null-forgiving rule.

- Removed all '// --- ... ---' region-like divider comments in AdbRunnerTests.cs (per jonathanpeppers feedback in PR #351).

### Fix RemoveAllForwardPortsAsync to honour per-serial scope

The underlying 'adb forward --remove-all' (and the wire-protocol equivalent 'host-serial:<serial>:killforward-all') is daemon-global -- the '-s <serial>' flag does not scope it. The previous implementation would silently remove forwards for every connected device despite the method's per-device API contract.

Reimplement by listing forwards for the given serial via ListForwardPortsAsync and removing them individually via RemoveForwardPortAsync. Update the XML docs to describe the actual behaviour.

Add two new tests using a recording subclass of AdbRunner that overrides ListForwardPortsAsync and RemoveForwardPortAsync to verify (1) only ports for the requested serial are removed, and (2) an empty listing is a no-op.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: rmarinho

src/Xamarin.Android.Tools.AndroidSdk/PublicAPI/net10.0/PublicAPI.Unshipped.txt

@@ -199,6 +199,10 @@ virtual Xamarin.Android.Tools.AdbRunner.ListReversePortsAsync(string! serial, Sy
 virtual Xamarin.Android.Tools.AdbRunner.RemoveAllReversePortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
 virtual Xamarin.Android.Tools.AdbRunner.RemoveReversePortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! remote, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
 virtual Xamarin.Android.Tools.AdbRunner.ReversePortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! remote, Xamarin.Android.Tools.AdbPortSpec! local, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+virtual Xamarin.Android.Tools.AdbRunner.ForwardPortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! local, Xamarin.Android.Tools.AdbPortSpec! remote, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+virtual Xamarin.Android.Tools.AdbRunner.ListForwardPortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AdbPortRule!>!>!
+virtual Xamarin.Android.Tools.AdbRunner.RemoveAllForwardPortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+virtual Xamarin.Android.Tools.AdbRunner.RemoveForwardPortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! local, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
 Xamarin.Android.Tools.AvdManagerRunner.ListDeviceProfilesAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AvdDeviceProfile!>!>!
 Xamarin.Android.Tools.AvdDeviceProfile
 Xamarin.Android.Tools.AvdDeviceProfile.AvdDeviceProfile(string! Id) -> void

src/Xamarin.Android.Tools.AndroidSdk/PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt

@@ -199,6 +199,10 @@ virtual Xamarin.Android.Tools.AdbRunner.ListReversePortsAsync(string! serial, Sy
 virtual Xamarin.Android.Tools.AdbRunner.RemoveAllReversePortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
 virtual Xamarin.Android.Tools.AdbRunner.RemoveReversePortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! remote, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
 virtual Xamarin.Android.Tools.AdbRunner.ReversePortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! remote, Xamarin.Android.Tools.AdbPortSpec! local, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+virtual Xamarin.Android.Tools.AdbRunner.ForwardPortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! local, Xamarin.Android.Tools.AdbPortSpec! remote, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+virtual Xamarin.Android.Tools.AdbRunner.ListForwardPortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AdbPortRule!>!>!
+virtual Xamarin.Android.Tools.AdbRunner.RemoveAllForwardPortsAsync(string! serial, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
+virtual Xamarin.Android.Tools.AdbRunner.RemoveForwardPortAsync(string! serial, Xamarin.Android.Tools.AdbPortSpec! local, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task!
 Xamarin.Android.Tools.AvdManagerRunner.ListDeviceProfilesAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyList<Xamarin.Android.Tools.AvdDeviceProfile!>!>!
 Xamarin.Android.Tools.AvdDeviceProfile
 Xamarin.Android.Tools.AvdDeviceProfile.AvdDeviceProfile(string! Id) -> void

src/Xamarin.Android.Tools.AndroidSdk/Runners/AdbRunner.cs

@@ -355,6 +355,145 @@ internal static IReadOnlyList<AdbPortRule> ParseReverseListOutput (IEnumerable<s
 		return rules;
 	}
 
+	/// <summary>
+	/// Sets up forward port forwarding via 'adb -s &lt;serial&gt; forward &lt;local&gt; &lt;remote&gt;'.
+	/// The host-side &lt;local&gt; socket is forwarded to the device-side &lt;remote&gt; socket,
+	/// the symmetric pair to <see cref="ReversePortAsync"/>.
+	/// </summary>
+	/// <param name="serial">Device serial number.</param>
+	/// <param name="local">Local (host-side) port spec.</param>
+	/// <param name="remote">Remote (device-side) port spec.</param>
+	/// <param name="cancellationToken">Cancellation token.</param>
+	public virtual async Task ForwardPortAsync (string serial, AdbPortSpec local, AdbPortSpec remote, CancellationToken cancellationToken = default)
+	{
+		if (string.IsNullOrWhiteSpace (serial))
+			throw new ArgumentException ("Serial must not be empty.", nameof (serial));
+		if (local is null)
+			throw new ArgumentNullException (nameof (local));
+		if (remote is null)
+			throw new ArgumentNullException (nameof (remote));
+		if (local.Port <= 0 || local.Port > 65535)
+			throw new ArgumentOutOfRangeException (nameof (local), local.Port, "Port must be between 1 and 65535.");
+		if (remote.Port <= 0 || remote.Port > 65535)
+			throw new ArgumentOutOfRangeException (nameof (remote), remote.Port, "Port must be between 1 and 65535.");
+
+		var psi = ProcessUtils.CreateProcessStartInfo (adbPath, "-s", serial, "forward", local.ToSocketSpec (), remote.ToSocketSpec ());
+		using var stdout = new StringWriter ();
+		using var stderr = new StringWriter ();
+		var exitCode = await ProcessUtils.StartProcess (psi, stdout, stderr, cancellationToken, environmentVariables).ConfigureAwait (false);
+		ProcessUtils.ThrowIfFailed (exitCode, $"adb -s {serial} forward {local} {remote}", stderr, stdout);
+	}
+
+	/// <summary>
+	/// Removes a specific forward port forwarding rule via
+	/// 'adb -s &lt;serial&gt; forward --remove &lt;local&gt;'.
+	/// </summary>
+	/// <param name="serial">Device serial number.</param>
+	/// <param name="local">Local (host-side) port spec to remove.</param>
+	/// <param name="cancellationToken">Cancellation token.</param>
+	public virtual async Task RemoveForwardPortAsync (string serial, AdbPortSpec local, CancellationToken cancellationToken = default)
+	{
+		if (string.IsNullOrWhiteSpace (serial))
+			throw new ArgumentException ("Serial must not be empty.", nameof (serial));
+		if (local is null)
+			throw new ArgumentNullException (nameof (local));
+		if (local.Port <= 0 || local.Port > 65535)
+			throw new ArgumentOutOfRangeException (nameof (local), local.Port, "Port must be between 1 and 65535.");
+
+		var psi = ProcessUtils.CreateProcessStartInfo (adbPath, "-s", serial, "forward", "--remove", local.ToSocketSpec ());
+		using var stdout = new StringWriter ();
+		using var stderr = new StringWriter ();
+		var exitCode = await ProcessUtils.StartProcess (psi, stdout, stderr, cancellationToken, environmentVariables).ConfigureAwait (false);
+		ProcessUtils.ThrowIfFailed (exitCode, $"adb -s {serial} forward --remove {local}", stderr, stdout);
+	}
+
+	/// <summary>
+	/// Removes all forward port forwarding rules for the specified device.
+	/// </summary>
+	/// <remarks>
+	/// The underlying <c>adb forward --remove-all</c> command (and its wire-protocol
+	/// equivalent <c>host-serial:&lt;serial&gt;:killforward-all</c>) operates globally on the
+	/// adb daemon — the <c>-s &lt;serial&gt;</c> flag does not scope it, and calling it
+	/// would remove forwards for every connected device. To honour the per-device
+	/// contract of this method, we list the forwards for <paramref name="serial"/>
+	/// via <see cref="ListForwardPortsAsync"/> and remove them individually via
+	/// <see cref="RemoveForwardPortAsync"/>.
+	/// </remarks>
+	public virtual async Task RemoveAllForwardPortsAsync (string serial, CancellationToken cancellationToken = default)
+	{
+		if (string.IsNullOrWhiteSpace (serial))
+			throw new ArgumentException ("Serial must not be empty.", nameof (serial));
+
+		var rules = await ListForwardPortsAsync (serial, cancellationToken).ConfigureAwait (false);
+		foreach (var rule in rules) {
+			cancellationToken.ThrowIfCancellationRequested ();
+			await RemoveForwardPortAsync (serial, rule.Local, cancellationToken).ConfigureAwait (false);
+		}
+	}
+
+	/// <summary>
+	/// Lists active forward port forwarding rules for the specified device via
+	/// 'adb forward --list'.
+	/// The underlying command always lists rules across all devices, so the
+	/// result is filtered to entries matching <paramref name="serial"/>.
+	/// </summary>
+	public virtual async Task<IReadOnlyList<AdbPortRule>> ListForwardPortsAsync (string serial, CancellationToken cancellationToken = default)
+	{
+		if (string.IsNullOrWhiteSpace (serial))
+			throw new ArgumentException ("Serial must not be empty.", nameof (serial));
+
+		using var stdout = new StringWriter ();
+		using var stderr = new StringWriter ();
+		var psi = ProcessUtils.CreateProcessStartInfo (adbPath, "forward", "--list");
+		var exitCode = await ProcessUtils.StartProcess (psi, stdout, stderr, cancellationToken, environmentVariables).ConfigureAwait (false);
+		ProcessUtils.ThrowIfFailed (exitCode, $"adb forward --list", stderr, stdout);
+
+		return ParseForwardListOutput (stdout.ToString ().Split ('\n'), serial);
+	}
+
+	/// <summary>
+	/// Parses the output of 'adb forward --list'.
+	/// Each line is "&lt;serial&gt; &lt;local&gt; &lt;remote&gt;", e.g. "emulator-5554 tcp:5000 tcp:6000".
+	/// Only rules matching <paramref name="serial"/> are returned. Lines with
+	/// unparseable socket specs are skipped.
+	/// </summary>
+	/// <remarks>
+	/// Note the field-order asymmetry vs <see cref="ParseReverseListOutput"/>:
+	///   forward --list: &lt;serial&gt; &lt;local&gt; &lt;remote&gt;
+	///   reverse --list: (reverse) &lt;remote&gt; &lt;local&gt;
+	/// Both parsers construct an <see cref="AdbPortRule"/> whose constructor takes
+	/// (Remote, Local), so the order in which we pass the parsed parts differs between
+	/// the two parsers — keep that in mind when modifying either of them.
+	/// </remarks>
+	internal static IReadOnlyList<AdbPortRule> ParseForwardListOutput (IEnumerable<string> lines, string serial)
+	{
+		var rules = new List<AdbPortRule> ();
+		if (string.IsNullOrEmpty (serial))
+			return rules;
+
+		foreach (var line in lines) {
+			var trimmed = line.Trim ();
+			if (string.IsNullOrEmpty (trimmed))
+				continue;
+
+			// Expected format: "<serial> <local> <remote>" — see <remarks> above for
+			// the field-order asymmetry with reverse --list.
+			var parts = trimmed.Split ((char[]?) null, StringSplitOptions.RemoveEmptyEntries);
+			if (parts.Length < 3)
+				continue;
+
+			if (!string.Equals (parts [0], serial, StringComparison.Ordinal))
+				continue;
+
+			var local = AdbPortSpec.TryParse (parts [1]);
+			var remote = AdbPortSpec.TryParse (parts [2]);
+			if (local is { } l && remote is { } r)
+				rules.Add (new AdbPortRule (r, l));
+		}
+
+		return rules;
+	}
+
 	/// <summary>
 	/// Parses the output lines from 'adb devices -l'.
 	/// Accepts an <see cref="IEnumerable{T}"/> to avoid allocating a joined string.