support powershell for completions

[maxandersen]

it would be awesome if aesh like its support fish,zsh,etc. could support powershell as psh works on mutliple OS and in particular windows.

Register-ArgumentCompleter -Native -CommandName mycli -ScriptBlock {
    param($wordToComplete, $commandAst, $cursorPosition)

    mycli --aesh-complete -- $commandAst.ToString() |
        ForEach-Object {
            [System.Management.Automation.CompletionResult]::new(
                $_,
                $_,
                'ParameterValue',
                $_
            )
        }
}

PowerShell supports custom dynamic argument completion through Register-ArgumentCompleter, including for native commands via the -Native option:

• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/register-argumentcompleter
• https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_argument_completion

would be awesome if this also included geneation/setup of the completion scripts.

[stalep]

Implementation Plan

After investigating the current shell completion architecture and PowerShell's Register-ArgumentCompleter API, here is how PowerShell support can be added.

How it fits the existing architecture

The current architecture has three clean layers that PowerShell slots into naturally:

1. ShellType enum — add POWERSHELL("_complete.ps1")
2. ShellCompletionGenerator — new PowerShellCompletionGenerator with generate() and generateDynamic()
3. AeshRuntimeRunner — add PowerShell to detectShell(), getCompletionInstallPath(), and --aesh-completion powershell

Dynamic completion script

PowerShell uses Register-ArgumentCompleter -Native with a ScriptBlock that calls back to the Java process via --aesh-complete:

Register-ArgumentCompleter -Native -CommandName mycli -ScriptBlock {
    param($wordToComplete, $commandAst, $cursorPosition)

    $tokens = $commandAst.ToString().Split(" ", [StringSplitOptions]::RemoveEmptyEntries)
    $args = if ($tokens.Length -gt 1) { $tokens[1..($tokens.Length - 1)] } else { @() }

    $hasTrailingSpace = $commandAst.ToString().EndsWith(" ")
    if ($hasTrailingSpace) { $args += "" }

    & mycli --aesh-complete -- @args 2>$null | ForEach-Object {
        $parts = $_ -split "`t", 2
        $text = $parts[0].Trim()
        if ($text -eq "__aesh_file__") {
            Get-ChildItem -Path "$wordToComplete*" -ErrorAction SilentlyContinue |
                ForEach-Object {
                    [System.Management.Automation.CompletionResult]::new(
                        $_.Name, $_.Name, "ProviderItem", $_.FullName)
                }
        } elseif ($text -eq "__aesh_dir__") {
            Get-ChildItem -Path "$wordToComplete*" -Directory -ErrorAction SilentlyContinue |
                ForEach-Object {
                    [System.Management.Automation.CompletionResult]::new(
                        $_.Name, $_.Name, "ProviderContainer", $_.FullName)
                }
        } elseif ($text) {
            $desc = if ($parts.Length -gt 1) { $parts[1] } else { $text }
            [System.Management.Automation.CompletionResult]::new(
                $text, $text, "ParameterValue", $desc)
        }
    }
}

Key points:

• -Native flag is for non-PowerShell commands (Java CLIs) — available in PS 5.1+ and PS 7+
• Tab-separated descriptions from --aesh-complete map to the toolTip parameter of CompletionResult
• __aesh_file__ / __aesh_dir__ sentinels handled via Get-ChildItem
• Trailing space detection for subcommand context (same approach as Fish)
• 2>$null suppresses stderr from the Java process

Shell detection

PowerShell detection in detectShell():

// PowerShell sets PSModulePath
if (System.getenv("PSModulePath") != null)
    return ShellType.POWERSHELL;

However, PSModulePath can leak across shell environments (e.g., running bash inside Windows Terminal). Explicit --aesh-completion powershell is more reliable. See open question #2 below.

Install path

PowerShell completion scripts should be placed in a dedicated directory and sourced from the profile:

Platform	Path
Windows	$HOME\Documents\PowerShell\Completions\<program>.ps1
macOS/Linux	$HOME/.config/powershell/completions/<program>.ps1

The install step would also need to add a source line to the user's profile ($PROFILE):

# Add to $PROFILE:
Get-ChildItem "$HOME/.config/powershell/completions/*.ps1" | ForEach-Object { . $_ }

Static completion

For static completion (hardcoded candidates without --aesh-complete callback), the script would use PowerShell's switch statement on the token position to return predefined candidates. This is less common for PowerShell — dynamic is the natural approach.

Estimated scope

Component	Lines
ShellType.POWERSHELL enum value	~3
PowerShellCompletionGenerator (dynamic + static)	~120
forShell() switch case	~2
detectShell() PowerShell detection	~5
getCompletionInstallPath() PowerShell path	~10
Tests	~40
Total	~180

Compatibility

• PowerShell 5.1 (Windows PowerShell): Register-ArgumentCompleter -Native supported
• PowerShell 7+ (cross-platform): full support on Windows, macOS, Linux
• No impact on existing shells: self-contained new generator, no changes to bash/zsh/fish code

---

Open Questions

1. Static completion support?

Should we generate static PowerShell completion scripts (with hardcoded candidate lists), or start with dynamic-only? Dynamic is what the issue shows and is the more natural PowerShell pattern. Static would require a more complex script with hardcoded switch statements per subcommand.

Recommendation: Start with dynamic-only. Static can be added later if needed.

2. Auto-detection vs explicit only?

Should detectShell() try to auto-detect PowerShell (via PSModulePath env var), or require explicit --aesh-completion powershell?

Auto-detection is unreliable because:

• PSModulePath can leak when running bash inside Windows Terminal
• PowerShell is rarely the login shell on Linux/macOS
• Users might have PowerShell installed but use bash day-to-day

Recommendation: Support both, but be conservative — only auto-detect if no other shell is detected first (make PowerShell the last fallback in detectShell()). The explicit --aesh-completion powershell flag should be the primary path.

3. Accept pwsh as alias?

The PowerShell 7 binary is called pwsh (not powershell). Should --aesh-completion pwsh work as an alias for --aesh-completion powershell?

Recommendation: Yes — accept both powershell and pwsh in the ShellType parsing. The enum value would be POWERSHELL but the string parser would accept either.

4. Install mechanism

The bash/zsh/fish install writes a single file to a well-known directory. PowerShell is different:

• The completion script needs to be sourced from the user's $PROFILE
• There's no standard "completions directory" that's auto-sourced

Should the install:

• (a) Write the script to a completions directory AND add a source line to $PROFILE?
• (b) Just write the script and tell the user to add the source line manually?
• (c) Append directly to $PROFILE?

Recommendation: Option (b) for safety — write the file, print instructions for the user to add . path/to/completion.ps1 to their $PROFILE. Modifying $PROFILE automatically could surprise users.

5. Description support

PowerShell's CompletionResult supports rich descriptions (tooltip text shown on hover). The --aesh-complete output already includes tab-separated descriptions. Should we pass these through as tooltips?

Recommendation: Yes — this is essentially free and gives a better completion experience in PowerShell than in bash/zsh/fish where descriptions are more limited.

[maxandersen]

looks about right - i would just use pwsh for name instead of handling both powershell and pwsh.

the most tricky is how to best handle setup/installation - but suggestions here about writing out file and instruct how to use it seem like a good start!