No user documentation?

[Priddles]

The Short

Could not figure out how to run in STDIO mode. Could find no up-to-date documentation.

The Long

After discovering that this project has a general STDIO LSP mode, I wasted time between the:

1. README (that has been saying "detailed usage documentation...coming soon!" since 2017)
2. Docs (that haven't changed since 2016)
3. Issue comments

before eventually figuring it out by referring to COC's code.

I still have no idea what possible -AdditionalModules or -FeatureFlags exist, or whether I've even configured PSES correctly.

I would really appreciate some up-to-date documentation!

[rjmholt]

The number of users directly interfacing with PSES is pretty low (< 10), so documenting the module properly has been in the backlog while we try to address some of the issues people have been facing (which may have API impacts).

If you're looking to use PSES in a new way, we're really happy to work with you or to answer any questions you've got.

You said in the other issue you want to use this with the neovim LanguageClient plugin. We've played around with that but @yatli's plugin seemed to work better (he added the stdio support). But as I say, we're really happy to work with you get PSES working -- ideally then we'll have a record here of the steps required.

Another point of reference that might be helpful is the integration testing client I recently added:

PowerShellEditorServices/tools/PsesPsClient/PsesPsClient.psm1

Lines 31 to 179 in 66cfe69

	function Start-PsesServer
	{
	[CmdletBinding(SupportsShouldProcess)]
	[OutputType([PsesServerInfo])]
	param(
	[Parameter()]
	[ValidateNotNullOrEmpty()]
	[string]
	$EditorServicesPath = "$script:PsesBundledModulesDir/PowerShellEditorServices/Start-EditorServices.ps1",
	[Parameter()]
	[ValidateNotNullOrEmpty()]
	[string]
	$LogPath,
	[Parameter()]
	[ValidateSet("Diagnostic", "Normal", "Verbose", "Error")]
	[string]
	$LogLevel = 'Diagnostic',
	[Parameter()]
	[ValidateNotNullOrEmpty()]
	[string]
	$SessionDetailsPath,
	[Parameter()]
	[ValidateNotNull()]
	[string[]]
	$FeatureFlags = @('PSReadLine'),
	[Parameter()]
	[ValidateNotNullOrEmpty()]
	[string]
	$HostName = 'PSES Test Host',
	[Parameter()]
	[ValidateNotNullOrEmpty()]
	[string]
	$HostProfileId = 'TestHost',
	[Parameter()]
	[ValidateNotNull()]
	[version]
	$HostVersion = '1.99',
	[Parameter()]
	[ValidateNotNull()]
	[string[]]
	$AdditionalModules = @('PowerShellEditorServices.VSCode'),
	[Parameter()]
	[ValidateNotNullOrEmpty()]
	[string]
	$BundledModulesPath,
	[Parameter()]
	[switch]
	$EnableConsoleRepl,
	[Parameter()]
	[string]
	$ErrorFile
	)
	$EditorServicesPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($EditorServicesPath)
	$instanceId = Get-RandomHexString
	$tempDir = [System.IO.Path]::GetTempPath()
	if (-not $LogPath)
	{
	$LogPath = Join-Path $tempDir "pseslogs_$instanceId.log"
	}
	if (-not $SessionDetailsPath)
	{
	$SessionDetailsPath = Join-Path $tempDir "psessession_$instanceId.log"
	}
	if (-not $BundledModulesPath)
	{
	$BundledModulesPath = $script:PsesBundledModulesDir
	}
	$editorServicesOptions = @{
	LogPath = $LogPath
	LogLevel = $LogLevel
	SessionDetailsPath = $SessionDetailsPath
	FeatureFlags = $FeatureFlags
	HostName = $HostName
	HostProfileId = $HostProfileId
	HostVersion = $HostVersion
	AdditionalModules = $AdditionalModules
	BundledModulesPath = $BundledModulesPath
	EnableConsoleRepl = $EnableConsoleRepl
	}
	$startPsesCommand = Unsplat -Prefix "& '$EditorServicesPath'" -SplatParams $editorServicesOptions
	$pwshPath = (Get-Process -Id $PID).Path
	if (-not $PSCmdlet.ShouldProcess("& '$pwshPath' -Command '$startPsesCommand'"))
	{
	return
	}
	$startArgs = @(
	'-NoLogo',
	'-NoProfile',
	'-NoExit',
	'-Command',
	$startPsesCommand
	)
	$startProcParams = @{
	PassThru = $true
	FilePath = $pwshPath
	ArgumentList = $startArgs
	}
	if ($ErrorFile)
	{
	$startProcParams.RedirectStandardError = $ErrorFile
	}
	$serverProcess = Start-Process @startProcParams
	$sessionPath = $editorServicesOptions.SessionDetailsPath
	$i = 0
	while (-not (Test-Path $sessionPath))
	{
	if ($i -ge 10)
	{
	throw "No session file found - server failed to start"
	}
	Start-Sleep 1
	$null = $i++
	}
	return [PsesServerInfo]@{
	PsesProcess = $serverProcess
	SessionDetails = Get-Content -Raw $editorServicesOptions.SessionDetailsPath | ConvertFrom-Json
	StartupOptions = $editorServicesOptions
	LogPath = $LogPath
	}
	}

[Priddles]

Less than 10 users...wow.

I did get PSES working with LanguageClient, and I opened this issue mainly because when I first found the repository, not even the starting point (the Start-EditorServices.ps1 script) was obvious.

One thing that is particularly frustrating about (Neo)vim, is that changing plugins that affect you almost every keystroke can be a huge effort, especially when you have spent considerable time tweaking those plugins. That said, I think I will try out COC after what you've told me.

Thank you for the reference script! It was helpful.

[Priddles]

On an unrelated note (and feel free to delete this comment), I wanted to know what you thought of how I presented the issue.

How could I improve it?

[rjmholt]

Less than 10 users...wow.

Well maybe more like < 100, but still 3-4 orders of magnitude behind the VSCode extension. Most people using PSES directly contact us, bake their invocation and then forget about it again.

One thing that is particularly frustrating about (Neo)vim, is that changing plugins that affect you almost every keystroke can be a huge effort, especially when you have spent considerable time tweaking those plugins. That said, I think I will try out COC after what you've told me.

Yeah our vim story is something we'd like to improve over time. I've been quite a big vim user in the past (but less so now I'm on Windows a lot), and I would like to see PSES made more friendly for a less bells-and-whistles text editor.

But we have a bunch of performance work to do first, which should make some of the vim experience a bit better.

On an unrelated note (and feel free to delete this comment), I wanted to know what you thought of how I presented the issue.

I very much appreciated that you took a constructive tact. We often deserve some criticism and issues are the right place to level it, but it's a lot easier to help people when they're actually looking to collaboratively solve the problem.

I think you laid out your issue well, gave good background (to prevent the XY problem) and looked into the problem somewhat yourself (which is really useful for us to understand the problem plus for people searching for the same results).

[TylerLeonhardt]

FWIW, @corbob did get it working with LanguageClient-Neovim but COC was just so much better so we all put effort in that

[TylerLeonhardt]

We should maybe add a page in PowerShell docs repo? @SteveL-MSFT thoughts?

This would be a doc on how to leverage/start PowerShell Editor Services out of the context of vscode