Add PowerShell module

[ltrzesniewski]

This adds PowerShell support 🎉

I built this script around @lzybkr's prototype, so I added him as co-author (I hope that's ok). I wouldn't know where to start without his contribution.

I'm not a PowerShell expert, so this was a nice opportunity to learn some stuff. I think it's ok, but I would appreciate if someone more knowledgeable in the matter could review this though.

It would be nice if other PowerShell users could test this with their configs and report any issues. I wouldn't be surprised if there are some remaining bugs or missing features.

Fixes #84

Warning

Because of other changes on the main branch, please set the following environment variables to temporary file paths when testing:

$env:ATUIN_DB_PATH = "temp_atuin_dev.db"
$env:ATUIN_RECORD_STORE_PATH = "temp_atuin_records.db"

Otherwise, the database schema will be migrated to a new format, and you will have to stay with the Atuin version from this branch.

Installation

atuin init powershell | Out-String | Invoke-Expression

This requires atuin to be in the path and the PSReadLine module to be installed, which is the case by default.

Tests

I tested this on the following:

• PowerShell 7.4.6 / PSReadLine 2.3.5 / Windows (the latest one)
• PowerShell 5.1.22621.4391 / PSReadLine 2.0.0 / Windows (the one shipped with Windows)
• PowerShell 7.4.6 / PSReadLine 2.3.5 / Ubuntu WSL (strangely, it didn't behave exactly like the Windows version)

I also tested this with and without my custom Oh My Posh prompt. It works fine in both cases, except that since my OMP config contains "newline": true, my prompt is multiline and shifts downwards by a single line on each atuin search -i invocation. This can be adjusted with the $env:ATUIN_POWERSHELL_PROMPT_OFFSET environment variable (e.g. I set mine to -1 to account for the additional prompt line).

Other notes

I added the following before the first draw call, since I got Atuin drawing over my PS prompt without entirely erasing it:

if settings.inline_height > 0 {
    terminal.clear()?;
}

Checks

• I am happy for maintainers to push small adjustments to this PR, to speed up the review cycle
• I have checked that there are no existing pull requests for the same thing

[Master-Hash]

I've tested it and everything works well. Now I'm a happy user. Thank you for your work!

[justunsix]

Thank you @ltrzesniewski and lzybkr, appreciate the work ❤️

Confirming Successful Test on

• PowerShell 7.4.6 / PSReadLine 2.3.5 / Windows 11 10.0.26100 N/A Build 26100
• PowerShell 5.1.26100.2161 / PSReadLine 2.3.6 / Windows 11 10.0.26100 N/A Build 26100

About Tests

Details on test steps and commands run at https://github.com/justunsix/rust-tests/blob/main/atuin-tests/pr2543/README.md

• How to build from PR branch

• Commands executed to test

• Test platform versions

• Also tested successfully with nushell 0.101.0 in same environment

Error not related to PR

Sharing an error found during testing in case others find it during their testing, though it is a local issue and not related to the PR itself.

The error also occurs when testing with atuin/main in nushell in the same environment, so error
is not caused by changes in the PR.

• During testing, there was an error running atuin search -i:

Error: migration 20230531212437 was previously applied but has been modified
>>
>> Location:
>>     C:\Users\user1\usr\reference\atuin\crates\atuin-client\src\record\sqlite_store.rs:61:9
Error:: The term 'Error:' is not recognized as a name of a cmdlet, function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

• Detailed trace and local fix: https://github.com/justunsix/rust-tests/blob/main/atuin-tests/pr2543/README.md#error-migration-20230531212437-and-fix-to-delete-old-files

• C:\Users\user1\usr\reference\atuin\ is where the PR was built

• There was a problem with the local ~/.local/share/atuin/records.db. Fix was to delete records.db and have a new one generated.

• The system could run powershell and nushell fine with atuin and they successfully shared ~/.local/share/atuin/

[ltrzesniewski]

@justunsix thanks for testing and the detailed report! Sorry, I should have mentioned the database issue in the OP, I'll add a warning right now. 😬

[ltrzesniewski]

I found an issue with encoding and pushed a fix: PSConsoleReadLine prompt editing functions are now called in UTF-8 mode in order to handle Atuin search results correctly when those contain codepoints invalid in the current console encoding.

I took the opportunity to add support for an ATUIN_POWERSHELL_PROMPT_OFFSET environment variable (please tell me if you'd prefer a better name) that adds an offset to the Y position of the prompt when returning from atuin search -i, which is useful when the prompt is multi-line.

The compiler was also complaining about an elided lifetime, but not every time for some reason, so I made it explicit.

[justunsix]

Re-tested after the push and confirming successful tests on:

• PowerShell 7.4.6 / PSReadline 2.3.5 / Ubuntu 24.04.1 LTS
• PowerShell 7.4.6 / PSReadLine 2.3.5 / Windows 11 10.0.26100 N/A Build 26100
• PowerShell 5.1.26100.2161 / PSReadLine 2.3.6 / Windows 11 10.0.26100 N/A Build 26100

Additions from the earlier testing:

• Confirmed using a multiple line prompt and setting $env:ATUIN_POWERSHELL_PROMPT_OFFSET=-3 as an example with a 4 line prompt prevents extra lines being added in the terminal when using atuin search -i and making a selection. For tests, used a Starship prompt.

• Tested more atuin commands across different sessions

• Added testing on Ubuntu

Comments:

• Regarding the offset, was thinking later the docs will need to be updated and inform the user of the setting.
• So, I drafted what could be in the installation, Installing the shell plugin section summarizing what the PR can do; can be discussed later.

<TabItem label="powershell">
    Add

    ```shell
    atuin init powershell | Out-String | Invoke-Expression
    ```

    to your $PROFILE file.
    
    If you use a prompt that has more than one line, also add 
    
    ```shell
    $env:ATUIN_POWERSHELL_PROMPT_OFFSET=-X
    ```
    
    to your $PROFILE file. 
    
    Replace X with the number of lines in your prompt, but take away 1. 
    For example, if your prompt has 2 lines, the environment variable would be -1.
</TabItem>