Back language model tools and the Command Explorer with new LSP requests

.github/copilot-instructions.md

@@ -0,0 +1,110 @@
+# Copilot Instructions for PowerShell Editor Services
+
+## Build & Test
+
+Requires .NET SDK 8.0+. Use `dotnet` directly for building and testing — it's faster and
+requires no extra tooling. The `Invoke-Build` script requires the `InvokeBuild` and `platyPS`
+PowerShell modules (platyPS is `#Requires`'d at the top, so the whole script fails without it),
+and is mainly needed to assemble the full PowerShell module for release.
+
+```powershell
+# Build (run both; Hosting depends on the core library)
+dotnet publish src/PowerShellEditorServices/PowerShellEditorServices.csproj -f netstandard2.0
+dotnet publish src/PowerShellEditorServices.Hosting/PowerShellEditorServices.Hosting.csproj -f net8.0
+
+# Run all unit tests
+dotnet test test/PowerShellEditorServices.Test/ --framework net8.0
+
+# Run a single test by name
+dotnet test test/PowerShellEditorServices.Test/ --framework net8.0 --filter "FullyQualifiedName~CompletesCommandInFile"
+
+# Run tests by trait category
+dotnet test test/PowerShellEditorServices.Test/ --framework net8.0 --filter "Category=Completions"
+
+# Run E2E tests
+dotnet test test/PowerShellEditorServices.Test.E2E/ --framework net8.0
+```
+
+For assembling the full module or running the complete CI suite (including Windows PowerShell
+5.1 targets), use `Invoke-Build` with the `InvokeBuild` and `platyPS` modules installed:
+
+```powershell
+Invoke-Build Build           # full build + module assembly + help generation
+Invoke-Build TestPS74        # unit tests via build script
+Invoke-Build TestE2EPwsh     # E2E tests via build script
+Invoke-Build Build -Configuration Release  # required before PRs (enforces XML doc comments)
+```
+
+`src/PowerShellEditorServices.Hosting/BuildInfo.cs` is auto-generated by the build script and
+git-ignored for changes. Do not edit it manually.
+
+## Architecture
+
+PowerShell Editor Services (PSES) is a **Language Server Protocol (LSP)** and **Debug Adapter
+Protocol (DAP)** server for PowerShell, consumed by VS Code and other editors.
+
+### Projects
+
+- **`src/PowerShellEditorServices`** (`netstandard2.0`) — Core library containing all LSP/DAP
+  handlers, services, and the PowerShell execution engine. Namespace:
+  `Microsoft.PowerShell.EditorServices`.
+- **`src/PowerShellEditorServices.Hosting`** (`net8.0`, `net462`) — Entry point layer that loads
+  PSES into a PowerShell process via `StartEditorServicesCommand`. Uses a custom
+  `AssemblyLoadContext` (`PsesLoadContext`) on .NET Core to isolate dependencies.
+- **`module/PowerShellEditorServices/`** — The shipped PowerShell module. The build assembles
+  compiled binaries into `bin/Core/` (net8.0) and `bin/Desktop/` (net462). The module manifest
+  loads the appropriate DLL based on PowerShell edition.
+
+### Key Services (registered in `PsesServiceCollectionExtensions`)
+
+- **`PsesInternalHost`** — The central PowerShell execution host. Also implements
+  `IRunspaceContext` and `IInternalPowerShellExecutionService`.
+- **`WorkspaceService`** — Manages open documents and workspace files.
+- **`SymbolsService`** — Provides symbol navigation (go-to-definition, find references).
+- **`AnalysisService`** — Integrates PSScriptAnalyzer for real-time diagnostics.
+- **`ConfigurationService`** — Manages editor/client settings.
+- **`ExtensionService`** — Supports the `$psEditor` API for editor extensions.
+
+### LSP/DAP Handler Pattern
+
+Handlers live under `Services/<Feature>/Handlers/` and follow a consistent pattern:
+
+- Class name: `Pses<Feature>Handler`, marked `internal`
+- Inherits from an OmniSharp base class (e.g., `CompletionHandlerBase`, `HoverHandlerBase`)
+- Dependencies injected via constructor (`ILoggerFactory`, services)
+- Overrides `CreateRegistrationOptions()` and `Handle()`
+- Uses `LspUtils.PowerShellDocumentSelector` for document registration
+
+### Server Setup
+
+- `PsesLanguageServer` — Configures and runs the LSP server using OmniSharp
+- `PsesDebugServer` — Configures and runs the DAP server
+- Both use `Microsoft.Extensions.DependencyInjection` for service registration
+
+## Conventions
+
+### C# Style
+
+- All files require the copyright header: `// Copyright (c) Microsoft Corporation.` /
+  `// Licensed under the MIT License.`
+- `.editorconfig` enforces many rules as **errors**, including unused variables, async/threading
+  rules (`VSTHRD*`), and modern C# idioms (pattern matching, null checks, expression bodies).
+- Roslynator analyzers are enabled for formatting and code quality.
+- Use `Microsoft.Extensions.Logging` (`ILogger<T>` via `ILoggerFactory`) for all logging.
+
+### Testing
+
+- **Framework:** xUnit with `Xunit.SkippableFact` for conditionally skipped tests.
+- **Host setup:** Use `PsesHostFactory.Create(loggerFactory)` to get an isolated
+  `PsesInternalHost` for testing. Tests implement `IAsyncLifetime` for async setup/teardown.
+- **Traits:** Tests use `[Trait("Category", "...")]` for filtering (e.g., `"Completions"`,
+  `"Symbols"`).
+- **Fixtures:** Test PowerShell scripts live in `test/PowerShellEditorServices.Test/Fixtures/`.
+- **E2E tests** are in a separate project (`PowerShellEditorServices.Test.E2E`) and test the
+  full LSP client-server interaction.
+
+### Multi-targeting
+
+The core library targets `netstandard2.0` for compatibility with both .NET Core and .NET
+Framework. The hosting project and tests dual-target `net8.0` and `net462` (Windows PowerShell
+5.1). Non-Windows platforms skip `net462` targets.

src/PowerShellEditorServices/Server/PsesLanguageServer.cs

@@ -121,6 +121,7 @@ public async Task StartAsync()
                     .WithHandler<GetCommentHelpHandler>()
                     .WithHandler<EvaluateHandler>()
                     .WithHandler<GetCommandHandler>()
+                    .WithHandler<GetModuleHandler>()
                     .WithHandler<ShowHelpHandler>()
                     .WithHandler<ExpandAliasHandler>()
                     .WithHandler<PsesSemanticTokensHandler>()

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

@@ -2,7 +2,9 @@
 // Licensed under the MIT License.
 
 using System.Collections.Generic;
+using System.Linq;
 using System.Management.Automation;
+using System.Management.Automation.Runspaces;
 using System.Threading;
 using System.Threading.Tasks;
 using MediatR;
@@ -14,7 +16,37 @@ namespace Microsoft.PowerShell.EditorServices.Handlers
     [Serial, Method("powerShell/getCommand", Direction.ClientToServer)]
     internal interface IGetCommandHandler : IJsonRpcRequestHandler<GetCommandParams, List<PSCommandMessage>> { }
 
-    internal class GetCommandParams : IRequest<List<PSCommandMessage>> { }
+    internal class GetCommandParams : IRequest<List<PSCommandMessage>>
+    {
+        /// <summary>
+        /// An optional name (supports wildcards) to scope the returned commands.
+        /// When omitted, all commands are returned.
+        /// </summary>
+        public string Name { get; set; }
+
+        /// <summary>
+        /// An optional module name (supports wildcards) to scope the returned
+        /// commands. When omitted, commands from all modules are returned.
+        /// </summary>
+        public string Module { get; set; }
+
+        /// <summary>
+        /// When true, the expensive parameter and parameter-set metadata is not
+        /// resolved or returned. Callers that only need command names and modules
+        /// (such as the Command Explorer tree) should set this to avoid the large
+        /// serialization cost of the full command table.
+        /// </summary>
+        public bool ExcludeParameters { get; set; }
+
+        /// <summary>
+        /// When true, module-less functions and scripts that PowerShell's default
+        /// session provides (e.g. cd.., prompt, TabExpansion2) are omitted. These
+        /// are interactive shell conveniences and engine plumbing rather than
+        /// commands a user authored or imported, so the Command Explorer hides them.
+        /// Module-provided commands (including built-in modules) are never affected.
+        /// </summary>
+        public bool ExcludeDefaultFunctions { get; set; }
+    }
 
     /// <summary>
     /// Describes the message to get the details for a single PowerShell Command
@@ -24,6 +56,7 @@ internal class PSCommandMessage
     {
         public string Name { get; set; }
         public string ModuleName { get; set; }
+        public string ModuleVersion { get; set; }
         public string DefaultParameterSet { get; set; }
         public Dictionary<string, ParameterMetadata> Parameters { get; set; }
         public System.Collections.ObjectModel.ReadOnlyCollection<CommandParameterSetInfo> ParameterSets { get; set; }
@@ -39,11 +72,28 @@ public async Task<List<PSCommandMessage>> Handle(GetCommandParams request, Cance
         {
             PSCommand psCommand = new();
 
-            // Executes the following:
-            // Get-Command -CommandType Function,Cmdlet,ExternalScript | Sort-Object -Property Name
+            // Executes the following, scoping by name and/or module when provided
+            // so we don't serialize the entire command table (which is expensive):
+            // Get-Command -CommandType Function,Cmdlet,ExternalScript [-Name <name>] [-Module <module>] | Sort-Object -Property Name
             psCommand
                 .AddCommand(@"Microsoft.PowerShell.Core\Get-Command")
-                    .AddParameter("CommandType", new[] { "Function", "Cmdlet", "ExternalScript" })
+                    .AddParameter("CommandType", new[] { "Function", "Cmdlet", "ExternalScript" });
+
+            if (!string.IsNullOrEmpty(request.Name))
+            {
+                psCommand.AddParameter("Name", request.Name);
+            }
+
+            if (!string.IsNullOrEmpty(request.Module))
+            {
+                psCommand.AddParameter("Module", request.Module);
+            }
+
+            // A name or module filter that matches nothing writes a non-terminating
+            // error; ignore it so we simply return an empty list instead.
+            psCommand.AddParameter("ErrorAction", "Ignore");
+
+            psCommand
                 .AddCommand(@"Microsoft.PowerShell.Utility\Sort-Object")
                     .AddParameter("Property", "Name");
 
@@ -54,6 +104,39 @@ public async Task<List<PSCommandMessage>> Handle(GetCommandParams request, Cance
             {
                 foreach (CommandInfo command in result)
                 {
+                    // Skip commands injected by the editor's terminal integration
+                    // (the PSES host's fake PSConsoleHostReadLine and VS Code's
+                    // shell-integration helpers); they are implementation details,
+                    // not real commands the user authored or imported.
+                    if (IsEditorInjectedCommand(command))
+                    {
+                        continue;
+                    }
+
+                    // Optionally drop PowerShell's default-session shell functions
+                    // (and the install's profile-resource script), which are
+                    // module-less and not meaningful in the command list.
+                    if (request.ExcludeDefaultFunctions
+                        && IsDefaultSessionFunction(command))
+                    {
+                        continue;
+                    }
+
+                    // When only names/modules are requested, skip resolving the
+                    // parameter metadata entirely. Accessing Parameters/ParameterSets
+                    // forces PowerShell to compute (and we then serialize) the full
+                    // metadata, which is the dominant cost for the whole command table.
+                    if (request.ExcludeParameters)
+                    {
+                        commandList.Add(new PSCommandMessage
+                        {
+                            Name = command.Name,
+                            ModuleName = command.ModuleName,
+                            ModuleVersion = command.Version?.ToString()
+                        });
+                        continue;
+                    }
+
                     // Some info objects have a quicker way to get the DefaultParameterSet. These
                     // are also the most likely to show up so win-win.
                     string defaultParameterSet = null;
@@ -84,6 +167,7 @@ public async Task<List<PSCommandMessage>> Handle(GetCommandParams request, Cance
                     {
                         Name = command.Name,
                         ModuleName = command.ModuleName,
+                        ModuleVersion = command.Version?.ToString(),
                         Parameters = command.Parameters,
                         ParameterSets = command.ParameterSets,
                         DefaultParameterSet = defaultParameterSet
@@ -93,5 +177,74 @@ public async Task<List<PSCommandMessage>> Handle(GetCommandParams request, Cance
 
             return commandList;
         }
+
+        // Names of helper functions injected by VS Code's terminal shell
+        // integration script (shellIntegration.ps1), which the PSES host executes.
+        // These are editor plumbing rather than user- or module-provided commands.
+        private static readonly HashSet<string> s_shellIntegrationFunctions = new(System.StringComparer.OrdinalIgnoreCase)
+        {
+            "__VSCode-Escape-Value",
+            "Set-MappedKeyHandler",
+            "Set-MappedKeyHandlers"
+        };
+
+        // Identifies commands injected by the editor's terminal integration that
+        // should not be surfaced as real commands.
+        private static bool IsEditorInjectedCommand(CommandInfo command)
+        {
+            if (command.CommandType != CommandTypes.Function)
+            {
+                return false;
+            }
+
+            // The fake global PSConsoleHostReadLine function that the PSES host
+            // defines for terminal shell integration (see PsesInternalHost.cs) has
+            // no real version, whereas the genuine PSReadLine export always reports
+            // a real version, so that export is never matched here.
+            if (command.Name == "PSConsoleHostReadLine"
+                && (command.Version is null
+                    || (command.Version.Major == 0
+                        && command.Version.Minor == 0
+                        && command.Version.Build <= 0
+                        && command.Version.Revision <= 0)))
+            {
+                return true;
+            }
+
+            return s_shellIntegrationFunctions.Contains(command.Name);
+        }
+
+        // The names of the functions that PowerShell's default session state
+        // provides (cd.., cd\, cd~, Clear-Host, exec, help, oss, Pause, prompt,
+        // TabExpansion2). Enumerated once from InitialSessionState so the list stays
+        // correct across PowerShell versions rather than being hard-coded.
+        private static readonly System.Lazy<HashSet<string>> s_defaultSessionFunctions = new(() =>
+            new HashSet<string>(
+                InitialSessionState.CreateDefault2().Commands
+                    .OfType<SessionStateFunctionEntry>()
+                    .Select(static entry => entry.Name),
+                System.StringComparer.OrdinalIgnoreCase));
+
+        // Identifies module-less functions and scripts that PowerShell's default
+        // session provides — interactive shell conveniences and engine plumbing that
+        // aren't meaningful in the command list. Only matches commands with no module,
+        // so a module-provided command (including built-in modules) is never affected.
+        private static bool IsDefaultSessionFunction(CommandInfo command)
+        {
+            if (!string.IsNullOrEmpty(command.ModuleName))
+            {
+                return false;
+            }
+
+            // The profile-resource script shipped alongside the PowerShell install
+            // (e.g. pwsh.profile.resource.ps1) is install plumbing, not a user script.
+            if (command.CommandType == CommandTypes.ExternalScript)
+            {
+                return command.Name.StartsWith("pwsh.profile.resource", System.StringComparison.OrdinalIgnoreCase);
+            }
+
+            return command.CommandType == CommandTypes.Function
+                && s_defaultSessionFunctions.Value.Contains(command.Name);
+        }
     }
 }