Return help text from the powerShell/showHelp request

Convert `powerShell/showHelp` from a fire-and-forget notification into a
request that returns `ShowHelpResult { HelpText }`, so the client can render
help in a read-only editor pane (and the language model `get_help` tool can
reuse the same path) instead of printing into the integrated console.

The handler captures `Get-Help -Full | Out-String` and `.Trim()`s both ends —
`Out-String` pads the output with a leading and trailing blank line, which
looked wrong in the help pane and in tool output.

Drafted by Copilot (Claude Opus 4.8).

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

Author: andyleejordan

src/PowerShellEditorServices/Services/PowerShell/Handlers/ShowHelpHandler.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+using System.Collections.Generic;
 using System.Management.Automation;
 using System.Threading;
 using System.Threading.Tasks;
@@ -11,74 +12,67 @@
 
 namespace Microsoft.PowerShell.EditorServices.Handlers
 {
-    [Serial, Method("powerShell/showHelp")]
-    internal interface IShowHelpHandler : IJsonRpcNotificationHandler<ShowHelpParams> { }
+    [Serial, Method("powerShell/showHelp", Direction.ClientToServer)]
+    internal interface IShowHelpHandler : IJsonRpcRequestHandler<ShowHelpParams, ShowHelpResult> { }
 
-    internal class ShowHelpParams : IRequest
+    internal class ShowHelpParams : IRequest<ShowHelpResult>
     {
         public string Text { get; set; }
     }
 
+    internal class ShowHelpResult
+    {
+        public string HelpText { get; set; }
+    }
+
     internal class ShowHelpHandler : IShowHelpHandler
     {
         private readonly IInternalPowerShellExecutionService _executionService;
 
         public ShowHelpHandler(IInternalPowerShellExecutionService executionService) => _executionService = executionService;
 
-        public async Task<Unit> Handle(ShowHelpParams request, CancellationToken cancellationToken)
+        public async Task<ShowHelpResult> Handle(ShowHelpParams request, CancellationToken cancellationToken)
         {
-            // TODO: Refactor to not rerun the function definition every time.
-            const string CheckHelpScript = @"
+            // Resolves the command and returns its full help as a string so the
+            // client can display it (e.g. in an editor pane) or pass it to a
+            // language model tool. Returns a friendly message if the command
+            // cannot be found rather than throwing.
+            const string GetHelpScript = @"
                 [System.Diagnostics.DebuggerHidden()]
                 [CmdletBinding()]
                 param (
                     [String]$CommandName
                 )
-                try {
-                    $command = Microsoft.PowerShell.Core\Get-Command $CommandName -ErrorAction Stop
-                } catch [System.Management.Automation.CommandNotFoundException] {
-                    $PSCmdlet.ThrowTerminatingError($PSItem)
+                $command = Microsoft.PowerShell.Core\Get-Command $CommandName -ErrorAction Ignore
+                if ($null -eq $command) {
+                    return ""No command named '$CommandName' was found.""
                 }
-                try {
-                    $helpUri = [Microsoft.PowerShell.Commands.GetHelpCodeMethods]::GetHelpUri($command)
-
-                    $oldSslVersion = [System.Net.ServicePointManager]::SecurityProtocol
-                    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
-
-                    # HEAD means we don't need the content itself back, just the response header
-                    $status = (Microsoft.PowerShell.Utility\Invoke-WebRequest -Method Head -Uri $helpUri -TimeoutSec 5 -ErrorAction Stop).StatusCode
-                    if ($status -lt 400) {
-                        $null = Microsoft.PowerShell.Core\Get-Help $CommandName -Online
-                        return
-                    }
-                } catch {
-                    # Ignore - we want to drop out to Get-Help -Full
-                } finally {
-                    [System.Net.ServicePointManager]::SecurityProtocol = $oldSslVersion
-                }
-
-                return Microsoft.PowerShell.Core\Get-Help $CommandName -Full
+                return (Microsoft.PowerShell.Core\Get-Help $CommandName -Full | Microsoft.PowerShell.Utility\Out-String)
                 ";
 
-            string helpParams = request.Text;
-            if (string.IsNullOrEmpty(helpParams)) { helpParams = "Get-Help"; }
+            string commandName = request.Text;
+            if (string.IsNullOrEmpty(commandName)) { commandName = "Get-Help"; }
 
-            PSCommand checkHelpPSCommand = new PSCommand()
-                .AddScript(CheckHelpScript, useLocalScope: true)
-                .AddArgument(helpParams);
+            PSCommand getHelpCommand = new PSCommand()
+                .AddScript(GetHelpScript, useLocalScope: true)
+                .AddArgument(commandName);
 
-            // TODO: Rather than print the help in the console, we should send the string back
-            //       to VSCode to display in a help pop-up (or similar)
-            await _executionService.ExecutePSCommandAsync<PSObject>(
-                checkHelpPSCommand,
+            IReadOnlyList<string> results = await _executionService.ExecutePSCommandAsync<string>(
+                getHelpCommand,
                 cancellationToken,
                 new PowerShellExecutionOptions
                 {
-                    RequiresForeground = true,
-                    WriteOutputToHost = true,
                     ThrowOnError = false
                 }).ConfigureAwait(false);
-            return Unit.Value;
+
+            // Get-Help piped through Out-String is padded with a leading blank
+            // line and trailing blank lines (a console-formatter artifact); trim
+            // both so the help pane and the language model tool get clean output.
+            string helpText = results is { Count: > 0 }
+                ? string.Concat(results).Trim()
+                : string.Empty;
+
+            return new ShowHelpResult { HelpText = helpText };
         }
     }
 }