GitHubRepository.ps1

$localized = data {
ConvertFrom-StringData @'
    ResolvedDestinationPath     = Resolved destination path '{0}'.
    ResolvedSourcePath          = Resolved source path '{0}'.
    ExpandingZipArchive         = Expanding Zip archive '{0}'.
    CreatingDirectory           = Creating target directory '{0}'.
    ExtractingZipArchiveEntry   = Extracting Zip archive entry '{0}'.
    ClosingZipArchive           = Closing Zip archive '{0}'.
    CleaningRepositoryDirectory = Cleaning repository directory '{0}'.

    TargetFileExistsWarning     = Target file '{0}' already exists.

    InvalidDestinationPathError = Invalid destination path '{0}' specified.
'@
}

function ExpandZipArchive {
<#
    .SYNOPSIS
        Extracts a GitHub Zip archive.
    .NOTES
        This is an internal function and should not be called directly.
    .LINK
        This function is derived from the VirtualEngine.Compression (https://github.com/VirtualEngine/Compression) module.
    .OUTPUTS
        A System.IO.FileInfo object for each extracted file.
#>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess','')]
    [OutputType([System.IO.FileInfo])]
    param (
        # Source path to the Zip Archive.
        [Parameter(Mandatory, ValueFromPipelineByPropertyName, Position = 0)] [ValidateNotNullOrEmpty()]
        [Alias('PSPath','FullName')] [System.String[]] $Path,
        
        # Destination file path to extract the Zip Archive item to.
        [Parameter(Mandatory, ValueFromPipelineByPropertyName, Position = 1)] [ValidateNotNullOrEmpty()]
        [System.String] $DestinationPath,
        
        # GitHub repository name
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()]
        [System.String] $Repository,
        
        # GitHub repository branch name
        [Parameter(ValueFromPipelineByPropertyName, Position = 2)] [ValidateNotNullOrEmpty()]
        [System.String] $Branch = 'master',

        [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()]
        [System.String] $OverrideRepository,
        
        # Overwrite existing files
        [Parameter(ValueFromPipelineByPropertyName)]
        [System.Management.Automation.SwitchParameter] $Force,
        
        ## Remove root folders/files in archive from destination path.
        [Parameter(ValueFromPipelineByPropertyName)]
        [System.Management.Automation.SwitchParameter] $Clean
    )
    begin {
        ## Validate destination path      
        if (-not (Test-Path -Path $DestinationPath -IsValid)) {
            throw ($localized.InvalidDestinationPathError -f $DestinationPath);
        }
        $DestinationPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($DestinationPath);
        Write-Verbose ($localized.ResolvedDestinationPath -f $DestinationPath);
        [Ref] $null = NewDirectory -Path $DestinationPath;
        foreach ($pathItem in $Path) {
            foreach ($resolvedPath in $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($pathItem)) {
                Write-Verbose ($localized.ResolvedSourcePath -f $resolvedPath);
                $LiteralPath += $resolvedPath;
            }
        }
        ## If all tests passed, load the required .NET assemblies
        Write-Debug 'Loading ''System.IO.Compression'' .NET binaries.';
        Add-Type -AssemblyName 'System.IO.Compression';
        Add-Type -AssemblyName 'System.IO.Compression.FileSystem';
    } # end begin
    process {
        if ($Clean) {
            ## Remove repository directory before expanding any items..
            $repositoryPath = Join-Path -Path $DestinationPath -ChildPath $Repository;
            if ($OverrideRepository) {
                $repositoryPath = Join-Path -Path $DestinationPath -ChildPath $OverrideRepository;
            }
            Write-Verbose ($localized.CleaningRepositoryDirectory -f $repositoryPath);
            if (Test-Path -Path $repositoryPath -PathType Container) {
                Remove-Item -Path $repositoryPath -Force -Recurse -ErrorAction Stop;
            }
        }

        foreach ($pathEntry in $LiteralPath) {
            try {
                Write-Verbose ($localized.ExpandingZipArchive -f $pathEntry);
                $zipArchive = [System.IO.Compression.ZipFile]::OpenRead($pathEntry);
                $expandZipArchiveItemParams = @{
                    InputObject = [ref] $zipArchive.Entries;
                    DestinationPath = $DestinationPath;
                    Repository = $Repository;
                    Branch = $Branch;
                    Force = $Force;
                }
                if ($OverrideRepository) {
                    $expandZipArchiveItemParams['OverrideRepository'] = $OverrideRepository;
                }
                ExpandZipArchiveItem @expandZipArchiveItemParams;
            } # end try
            catch {
                Write-Error $_.Exception;
            }
            finally {
                ## Close the file handle
                CloseZipArchive;
            }
        } # end foreach
    } # end process
} #end function ExpandZipArchive

function ExpandZipArchiveItem {
<#
    .SYNOPSIS
        Extracts file(s) from a GitHub Zip archive.
    .NOTES
        This is an internal function and should not be called directly.
    .LINK
        This function is derived from the VirtualEngine.Compression (https://github.com/VirtualEngine/Compression) module.
    .OUTPUTS
        A System.IO.FileInfo object for each extracted file.
#>
    [CmdletBinding(DefaultParameterSetName='Path', SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
    [OutputType([System.IO.FileInfo])]
    param (
        # Reference to Zip archive item.
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0, ParameterSetName = 'InputObject')]
        [ValidateNotNullOrEmpty()] [System.IO.Compression.ZipArchiveEntry[]] [Ref] $InputObject,

        # Destination file path to extract the Zip Archive item to.
        [Parameter(Mandatory = $true, ValueFromPipelineByPropertyName = $true, Position = 1)]
        [ValidateNotNullOrEmpty()] [System.String] $DestinationPath,

        # GitHub repository name
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)] [System.String] $Repository,

        # GitHub repository branch name
        [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [System.String] $Branch = 'master',

        ## Override repository name
        [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [System.String] $OverrideRepository,
        
        # Overwrite existing physical filesystem files
        [Parameter(ValueFromPipelineByPropertyName)]
        [System.Management.Automation.SwitchParameter] $Force
    )
    begin {
        Write-Debug 'Loading ''System.IO.Compression'' .NET binaries.';
        Add-Type -AssemblyName 'System.IO.Compression';
        Add-Type -AssemblyName 'System.IO.Compression.FileSystem';
    }
    process {
        try {
            ## Regex for locating the <RepositoryName>-<Branch>\ root directory

            $searchString = '^{0}-{1}\\' -f $Repository, $Branch;
            $replacementString = '{0}\' -f $Repository;
            if ($OverrideRepository) {
                $replacementString = '{0}\' -f $OverrideRepository;
            }
            
            foreach ($zipArchiveEntry in $InputObject) {

                if ($zipArchiveEntry.FullName.Contains('/')) {
                    ## We need to create the directory path as the ExtractToFile extension method won't do this and will throw an exception
                    $pathSplit = $zipArchiveEntry.FullName.Split('/');
                    $relativeDirectoryPath = New-Object System.Text.StringBuilder;

                    ## Generate the relative directory name
                    for ($pathSplitPart = 0; $pathSplitPart -lt ($pathSplit.Count -1); $pathSplitPart++) {
                        [ref] $null = $relativeDirectoryPath.AppendFormat('{0}\', $pathSplit[$pathSplitPart]); 
                    }
                    ## Rename the GitHub \<RepositoryName>-<Branch>\ root directory to \<RepositoryName>\
                    $relativePath = ($relativeDirectoryPath.ToString() -replace $searchString, $replacementString).TrimEnd('\');
         
                    ## Create the destination directory path, joining the relative directory name
                    $directoryPath = Join-Path -Path $DestinationPath -ChildPath $relativePath;
                    [ref] $null = NewDirectory -Path $directoryPath;
                        
                    $fullDestinationFilePath = Join-Path -Path $directoryPath -ChildPath $zipArchiveEntry.Name;
                } # end if
                else {
                    ## Just a file in the root so just use the $DestinationPath
                    $fullDestinationFilePath = Join-Path -Path $DestinationPath -ChildPath $zipArchiveEntry.Name;
                } # end else

                if ([System.String]::IsNullOrEmpty($zipArchiveEntry.Name)) {
                    ## This is a folder and we need to create the directory path as the
                    ## ExtractToFile extension method won't do this and will throw an exception
                    $pathSplit = $zipArchiveEntry.FullName.Split('/');
                    $relativeDirectoryPath = New-Object System.Text.StringBuilder;
                
                    ## Generate the relative directory name
                    for ($pathSplitPart = 0; $pathSplitPart -lt ($pathSplit.Count -1); $pathSplitPart++) {
                        [ref] $null = $relativeDirectoryPath.AppendFormat('{0}\', $pathSplit[$pathSplitPart]); 
                    }
                    
                    ## Rename the GitHub \<RepositoryName>-<Branch>\ root directory to \<RepositoryName>\
                    $relativePath = ($relativeDirectoryPath.ToString() -replace $searchString, $replacementString).TrimEnd('\');
         
                    ## Create the destination directory path, joining the relative directory name
                    $directoryPath = Join-Path -Path $DestinationPath -ChildPath $relativePath;
                    [ref] $null = NewDirectory -Path $directoryPath;
                        
                    $fullDestinationFilePath = Join-Path -Path $directoryPath -ChildPath $zipArchiveEntry.Name;
                }
                elseif (-not $Force -and (Test-Path -Path $fullDestinationFilePath -PathType Leaf)) {
                    ## Are we overwriting existing files (-Force)?
                    Write-Warning ($localized.TargetFileExistsWarning -f $fullDestinationFilePath);
                }
                else {
                    ## Just overwrite any existing file
                    if ($Force -or $PSCmdlet.ShouldProcess($fullDestinationFilePath, 'Expand')) {
                        Write-Debug ($localized.ExtractingZipArchiveEntry -f $fullDestinationFilePath);
                        [System.IO.Compression.ZipFileExtensions]::ExtractToFile($zipArchiveEntry, $fullDestinationFilePath, $true);
                        ## Return a FileInfo object to the pipline
                        Write-Output (Get-Item -Path $fullDestinationFilePath);
                    }
                } # end if
            } # end foreach zipArchiveEntry
        } # end try
        catch {
            Write-Error $_.Exception;
        }
    } # end process
} #end function ExpandZipArchiveItem

function CloseZipArchive {
<#
    .SYNOPSIS
        Tidies up and closes Zip Archive and file handles
#>
    [CmdletBinding()]
    param ()
    process {
        Write-Verbose ($localized.ClosingZipArchive -f $Path);
        if ($null -ne $zipArchive) {
            $zipArchive.Dispose();
        }
        if ($null -ne $fileStream) {
            $fileStream.Close();
        }
    } # end process
} #end function CloseZipArchive

function NewDirectory {
    <#
        .SYNOPSIS
           Creates a file system directory.
        .DESCRIPTION
           The New-Directory cmdlet will create the target directory if it doesn't already
           exist. If the target path already exists, the cmdlet does nothing.
        .INPUTS
           You can pipe multiple strings or multiple System.IO.DirectoryInfo
           objects to this cmdlet.
        .OUTPUTS
           System.IO.DirectoryInfo
        .NOTES
            This is an internal function and should not be called directly.
    #>
    [CmdletBinding(DefaultParameterSetName = 'ByString', SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
    [OutputType([System.IO.DirectoryInfo])]
    param (
        # Target filesystem directory to create
        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName, Position = 0, ParameterSetName = 'ByDirectoryInfo')]
        [ValidateNotNullOrEmpty()] [System.IO.DirectoryInfo[]] $InputObject,
        
        # Target filesystem directory to create
        [Parameter(Mandatory, ValueFromPipelineByPropertyName, Position = 0, ParameterSetName = 'ByString')]
        [ValidateNotNullOrEmpty()] [Alias('PSPath')] [System.String[]] $Path
    )
    begin {
        Write-Debug ('Using parameter set ''{0}''.' -f $PSCmdlet.ParameterSetName);
    }
    process {
        switch ($PSCmdlet.ParameterSetName) {
            'ByString' {
                foreach ($directoryPath in $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path)) {
                    Write-Debug ('Testing target directory ''{0}''.' -f $directoryPath);
                    if (-not (Test-Path -Path $directoryPath -PathType Container)) {
                        if ($PSCmdlet.ShouldProcess($directoryPath, 'Create')) {
                            Write-Verbose ($localized.CreatingDirectory -f $directoryPath);
                            Write-Output (New-Item -Path $directoryPath -ItemType Directory);
                        }
                    }
                    else {
                        Write-Debug ('Target directory ''{0}'' already exists.' -f $Directory);
                        Write-Output (Get-Item -Path $directoryPath);
                    }
                } # end foreach
            } # end ByString

            'ByDirectoryInfo' {
                 foreach ($directoryInfo in $InputObject) {
                    Write-Debug ('Testing target directory ''{0}''.' -f $directoryInfo.FullName);
                    if (-not ($directoryInfo.Exists)) {
                        if ($PSCmdlet.ShouldProcess($directoryInfo.FullName, 'Create')) {
                            Write-Verbose ($localized.CreatingDirectory -f $directoryInfo.FullName);
                            Write-Output (New-Item -Path $directoryInfo.FullName -ItemType Directory);
                        }
                    }
                    else {
                        Write-Debug ('Target directory ''{0}'' already exists.' -f $directoryInfo.FullName);
                        Write-Output $directoryInfo;
                    }
                } # end foreach
            } #end ByDirectoryInfo
        } #end switch
    } # end process
} #end function NewDirectory

function ResolveGitHubUri {
<#
    .SYNOPSIS
        Resolves the correct GitHub URI for the specified Owner, Repository and Branch.
#>
    [CmdletBinding()]
    [OutputType([System.Uri])]
    param (
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [System.String] $Owner,
        
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [System.String] $Repository,
        
        [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()]
        [System.String] $Branch = 'master'
    )
    process {
        $uri = 'https://github.com/{0}/{1}/archive/{2}.zip' -f $Owner, $Repository, $Branch;
        return New-Object -TypeName System.Uri -ArgumentList $uri;
    } #end process
} #end function ResolveGitHubUri

function Install-GitHubRepository {
<#
    .SYNOPSIS
        Downloads, extracts and installs a repository directly from GitHub.
    .DESCRIPTION
        The Install-GitHubRepository cmdlet will download and extract a GitHub repository. This will typically be development PowerShell modules or DSC resources.
        
        Install-GitHubRepository is primary intended to help bootstrap the installation of Powershell modules and DSC resources that have not (yet) been published to the PowerShell Gallery or have been updated on a development branch and are needed for testing purposes.
    .PARAMETER Owner
        Specifies the owner of the GitHub repository from whom to download the module.
    .PARAMETER Repository
        Specifies the GitHub repository name to download.
    .PARAMETER Branch
        Specifies the specific Git repository branch to download. If this is not specified it defaults to the 'master' branch.
    .PARAMETER DestinationPath
        Specifies the path to the folder in which you want the command to save GitHub repository. Enter the path to a folder, but do not specify a file name or file name extension. If this parameter is not specified, it defaults to the '$env:ProgramFiles\WindowsPowershell\Modules' directory.
    .PARAMETER OverrideRepository
        Specifies overriding the repository name when it's expanded to disk. Use this parameter when the extracted Zip file path does not meet your requirements, i.e. when the repository name does not match the Powershell module name.
    .PARAMETER Force
        Forces the extraction of files from an archive file. By default, any files that exist on the local file system are not overwritten.
    .PARAMETER Clean
        Removes the existing repository folder from the local file system before extracting the archive. This ensures that local repository matches the source GitHub repository. Note: this should only be used with PowerShell module/DSC repositories.
#>
    [CmdletBinding(DefaultParameterSetName = 'Clean')]
    [OutputType([System.IO.DirectoryInfo])]
    param (
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [System.String] $Owner,
        
        [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
        [System.String] $Repository,
        
        [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()]
        [System.String] $Branch = 'master',
        
        [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()]
        [System.String] $DestinationPath = "$env:ProgramFiles\WindowsPowershell\Modules",
        
        [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()]
        [System.String] $OverrideRepository,
        
        [Parameter(ValueFromPipelineByPropertyName, ParameterSetName = 'Force')]
        [System.Management.Automation.SwitchParameter] $Force,
        
        [Parameter(ValueFromPipelineByPropertyName, ParameterSetName = 'Clean')]
        [System.Management.Automation.SwitchParameter] $Clean
    )
    process {
        $uri = ResolveGitHubUri -Owner $Owner -Repository $Repository -Branch $Branch;
        $tempDestinationFilename = '{0}-{1}.zip' -f $Repository, $Branch;
        $tempDestinationPath = Join-Path -Path $env:TEMP -ChildPath $tempDestinationFilename;
        [ref] $null = Invoke-WebRequest -Uri $uri.AbsoluteUri -OutFile $tempDestinationPath;
        Unblock-File -Path $tempDestinationPath;

        $expandZipArchiveParams = @{
            Path = $tempDestinationPath;
            DestinationPath = $DestinationPath;
            Repository = $Repository;
            Branch = $Branch;
            Force = $Force;
            Clean = $Clean;
        }
        if ($OverrideRepository) {
            $expandZipArchiveParams['OverrideRepository'] = $OverrideRepository;
        }
        [ref] $null = ExpandZipArchive @expandZipArchiveParams;
        
        $modulePath = Join-Path -Path $DestinationPath -ChildPath $Repository;
        if ($OverrideRepository) { $modulePath = Join-Path -Path $DestinationPath -ChildPath $OverrideRepository; }
        
        return (Get-Item -Path $modulePath);
    } #end process
} #end function Install-GitHubRepository