ExternalCommand.psm1

function Invoke-ExternalCommand
{
    <#
    .SYNOPSIS
    This is a helper function that runs a external executable binary and checks
    exit code for success to see if an error occurred. If an non 0 exit code is
    detected then an exception is thrown by default. It also properly creates
    and escapes arguments supplied via Arguments array parameter. Supports UTF8
    and whitespace in the argument values.
    .PARAMETER Command
    Executable name/command to run. Must be available at PATH env var or you can specify full path to the binary.
    .PARAMETER Arguments
    Arguments string array to path to Command as arguments
    .PARAMETER HideArguments
    List indexes (starting with 0) of arguments you would like to obscure in the message that command and its
    arguments that being executed.
    .PARAMETER DontEscapeArguments
    List indexes (starting with 0) of arguments you would like to skip escape logic on. 
    When used, unless is a simple argument it's on you to escape it correctly
    .PARAMETER OutVarStdout
    Provide variable name that will be used to save STDOUT output of the command execution.
    .PARAMETER OutVarStderr
    Provide variable name that will be used to save STDERR output of the command execution.
    .PARAMETER OutVarCode
    Provide variable name that will be used to save process exit code.
    .PARAMETER Return
    By default this function returns $null, if specified you will get this object:
    @{Stdout="Contains Stdout",Stderr="Contains Stderr",All="Stdout and Stderr output as it was generated",Code="Int from process exit code"}
    Stdout output sequence order is guaranteed, while Stderr lines sequence might be out of order (eventing nature?).
    .PARAMETER IgnoreExitCode
    Specify if you expect non 0 exit code from the Command and would like to avoid non 0 exit code exception.
    .PARAMETER HideStdout
    Specify if don't want STDOUT to be written to the host
    .PARAMETER HideStderr
    Specify if don't want STDERR to be written to the host
    .PARAMETER HideCommand
    Specify if don't want `Running command` informational message to be written to the host STDERR
    .EXAMPLE
    > Invoke-ExternalCommand -Command git -Arguments version
    Running command [ C:\Program Files\Git\cmd\git.exe ] with arguments: "version"
    git version 2.20.1.windows.1

    > Invoke-ExternalCommand -Command helm -Arguments version,--client
    Running command [ C:\ProgramData\chocolatey\bin\helm.exe ] with arguments: "version" "--client"
    Client: &version.Version{SemVer:"v2.12.2", GitCommit:"7d2b0c73d734f6586ed222a567c5d103fed435be", GitTreeState:"clean"}

    > Invoke-ExternalCommand -Command helm -Arguments versiondd,--client
    Running command [ C:\ProgramData\chocolatey\bin\helm.exe ] with arguments: "versiondd" "--client"
    Error: unknown command "versiondd" for "helm"
    Did you mean this?


        version
    Run 'helm --help' for usage.

    Command returned non zero exit code of '1'. Command: helm
    At C:\Users\user\dev\ps-modules\Igloo.Powershell.ExternalCommand\Igloo.Powershell.ExternalCommand.psm1:237 char:9
    +         throw ([string]::Format("Command returned non zero exit code  ...
    +         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : OperationStopped: (Command returne.... Command: helm:String) [], RuntimeException
    + FullyQualifiedErrorId : Command returned non zero exit code of '1'. Command: helm
    #>
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param (
        [Parameter(Mandatory = 1)][string]$Command,
        [string[]]$Arguments = @(),
        [int[]]$HideArguments = @(),
        [int[]]$DontEscapeArguments = @(),
        [string]$OutVarStdout = $null,
        [string]$OutVarStderr = $null,
        [string]$OutVarCode = $null,
        [switch]$Return,
        [switch]$IgnoreExitCode,
        [switch]$HideStdout,
        [switch]$HideStderr,
        [switch]$HideCommand
    )
    # setting desired $ErrorActionPreference, backup old one
    $OldErrorActionPreference = $ErrorActionPreference
    $ErrorActionPreference = "Stop"

    $CommandObject = (Get-Command $Command -CommandType Application -ErrorAction Ignore | Select-Object -First 1)
    if (!$CommandObject)
    {
        throw "Invalid application name\path provided (Cmdlets not supported): $Command"
    }

    # for debug info hiding args
    # looping through all arguments
    $ArgsToShow = New-Object System.Collections.Generic.List[String]

    for ($i = 0; $i -lt $Arguments.length; $i++)
    {
        # replacing sensitive arguments with "<sensitive>"
        if ($HideArguments -contains $i)
        {
            $ArgsToShow.Add("<sensitive>")
        }
        else
        {
            $ArgsToShow.Add($Arguments[$i])
        }
    }
    if ($ArgsToShow.Length -gt 0)
    {
        $ArgsToShow = (EscapeArguments -Arguments $ArgsToShow -DontEscapeArguments $DontEscapeArguments)
    }
    # Displaying what will be executed
    if (!$HideCommand)
    {
        # output to STDERR not to corrupt STDOUT
        [Console]::Error.WriteLine([string]::Format("Running command [{0}] with arguments: {1}", $CommandObject.Source, $ArgsToShow -join " "))
    }

    $pinfo = New-Object System.Diagnostics.ProcessStartInfo
    # Full pth to the binary
    $pinfo.FileName = $CommandObject.Source
    # enable UTF-8 Support and redirecting STDERR and STDOUT
    $pinfo.StandardOutputEncoding = New-Object System.Text.UTF8Encoding $false
    $pinfo.StandardErrorEncoding = New-Object System.Text.UTF8Encoding $false
    $pinfo.RedirectStandardError = $true
    $pinfo.RedirectStandardOutput = $true

    # please no shell
    $pinfo.UseShellExecute = $false

    # set process working directory
    $pinfo.WorkingDirectory = (Get-Location).Path

    # adding arguments if needed
    if ($Arguments.Length -gt 0)
    {
        $pinfo.Arguments = (EscapeArguments -Arguments $Arguments -DontEscapeArguments $DontEscapeArguments)
    }

    # Creating process
    $p = New-Object System.Diagnostics.Process
    $p.StartInfo = $pinfo

    # https://xiaalex.wordpress.com/2013/05/03/use-asynchronous-read-on-standard-output-of-a-process/

    # object in which we will capture STDOUT and STDERR
    $Results = @{
        Stderr     = ""
        Stdout     = ""
        All        = ""
        Code       = 0
        HideStderr = $HideStderr
    }

    # Event handler for STDERR lines
    # Additional output handler to print STDERR into console realtime and capture it into var
    $ErrAction = {
        $EventData = $Event.SourceEventArgs.Data
        if (![String]::IsNullOrWhiteSpace($EventData))
        {
            $Event.MessageData.Stderr += "$EventData`n"
            $Event.MessageData.All += "$EventData`n"
            if (!$Event.MessageData.HideStderr)
            {
                [Console]::Error.WriteLine($EventData)
            }
        }
    }

    # STDOUT might get captured out of sequence
    $ErrEvent = Register-ObjectEvent -InputObject $p -EventName ErrorDataReceived -Action $ErrAction -MessageData $Results
    # Start command process
    $p.Start() | Out-Null

    # Start triggering events for STDERR
    $p.BeginErrorReadLine();

    # running until process have exited and ErrorDataReceived events are done and no more data in StandardOutput stream
    do
    {
        # capturing STDOUT this way guaranties sequence of lines (important)
        $StdoutLine = $p.StandardOutput.ReadLine()
        if ($null -ne $StdoutLine)
        {
            if (!$HideStdout)
            {
                Write-Host $StdoutLine -ForegroundColor Green
            }
            $Results.Stdout += $StdoutLine
            $Results.All += $StdoutLine
            if (!$p.StandardOutput.EndOfStream)
            {
                # dont add new line at the end
                $Results.Stdout += "`n"
                $Results.All += "`n"
            }
        }
    } while (!$p.HasExited -or !$ErrEvent.HasMoreData -or !$p.StandardOutput.EndOfStream)
    Unregister-Event -SourceIdentifier $ErrEvent.Name

    # Cleanup flag we used in the error event handler
    $Results.Remove('HideStderr')

    # Some Trimming
    $Results.Stderr = $Results.Stderr.TrimEnd("`n")
    $Results.All = $Results.All.TrimEnd("`n")

    # Saving exit code
    $Results.Code = $p.ExitCode

    # Exit code check if not asked to ignore it
    if ( ($Results.Code -ne 0) -and !$IgnoreExitCode)
    {
        throw ([string]::Format("Command returned non zero exit code of '{0}'. Command: {1}`nSTDERR: {2}", $p.ExitCode, $Command, $Results.Stderr))
    }

    # Setting OutVarCode variable if requested
    if ($OutVarCode)
    {
        $PSCmdlet.SessionState.PSVariable.Set($OutVarCode, $Results.Code)
    }

    # Setting OutVarStderr variable if requested
    if ($OutVarStderr)
    {
        $PSCmdlet.SessionState.PSVariable.Set($OutVarStderr, $Results.Stderr)
    }

    # Setting OutVarStdout variable if requested
    if ($OutVarStdout)
    {
        $PSCmdlet.SessionState.PSVariable.Set($OutVarStdout, $Results.Stdout)
    }

    # Restoring $ErrorActionPreference on success
    $ErrorActionPreference = $OldErrorActionPreference

    # Returning if requested
    if ($Return)
    {
        return $Results
    }
    return $null
}


function EscapeArguments
{
    <#
    .SYNOPSIS
    Utility function to convert list of arguments from array of string to properly escaped string of arguments
    .PARAMETER Arguments
    Array of stings with arguments values
    .PARAMETER DontEscapeArguments
    List indexes (starting with 0) of arguments you would like to skip escape logic on. 
    #>
    param (
        [string[]]$Arguments,
        [int[]]$DontEscapeArguments = @()
    )
    $EscapedArguments = New-Object System.Collections.Generic.List[String]
    $ArgPosition = -1
    foreach ($EscapedArg in $Arguments)
    {
        $ArgPosition++
        if ($DontEscapeArguments.Contains($ArgPosition))
        {
            $EscapedArguments.Add($EscapedArg)
            Write-Host "Unescaped Arguments: $EscapedArg"    
            continue
        }
        # https://docs.microsoft.com/en-gb/windows/desktop/api/shellapi/nf-shellapi-commandlinetoargvw
        # https://stackoverflow.com/questions/21314633/how-do-i-pass-a-literal-double-quote-from-powershell-to-a-native-command

        # stdlib Rules: 
        # 2N backslashes + " ==> N backslashes and begin/end quote
        # 2N+1 backslashes + " ==> N backslashes + literal " 
        # N backslashes ==> N backslashes

        # escaping double quotes as we use them to indicate start/end of argument
        $EscapedArg = $EscapedArg.Replace('"', '\"')

        # double all the slashes followed by \" (no more org before quote, so quote is never end/begin arg char)
        $EscapedArg = $EscapedArg -replace '(\\+)\\\"', '$1$1\"'

        # double all the slashes at the end of the argument
        $EscapedArg = $EscapedArg -replace '(\\+)$', '$1$1'

        # wrapping argument
        $EscapedArg = "`"$EscapedArg`""

        # appending to result
        $EscapedArguments.Add($EscapedArg)
        Write-Verbose "Escaped Arguments: $EscapedArg"

    }
    return $EscapedArguments -join " "
}