Prep 1.1.0 release

README.md

@@ -4,13 +4,20 @@
 
 A PowerShell module for Sonatype Nexus repository server administration
 
-## Try it out!
+## Installation
+
+### From the PowerShell Gallery
+
+```powershell
+Install-Module NexuShell -Scope CurrentUser -Force
+```
+
+### From Chocolatey CLI
+
+```powershell
+choco install NexuShell -y -s https://community.chocolatey.org/api/v2
+```
 
-1. Clone this repo and run `.\build.ps1 -Build` from the cloned folder
-2. Import the module with `Import-Module .\Output\NexuShell\NexuShell.psd1` from the cloned folder
-3. Discover the available commands with `Get-Command -Module NexuShell`
-4. Explore the available commands with `Get-Help`
-5. Start having fun!
 
 ### Documentation
 

src/private/New-HttpQueryString.ps1

@@ -0,0 +1,31 @@
+function New-HttpQueryString
+{
+    #Shamelessly taken from https://powershellmagazine.com/2019/06/14/pstip-a-better-way-to-generate-http-query-strings-in-powershell/
+    [CmdletBinding()]
+    param 
+    (
+        [Parameter(Mandatory = $true)]
+        [String]
+        $Uri,
+
+        [Parameter(Mandatory = $true)]
+        [Hashtable]
+        $QueryParameter
+    )
+    # Add System.Web
+    Add-Type -AssemblyName System.Web
+
+    # Create a http name value collection from an empty string
+    $nvCollection = [System.Web.HttpUtility]::ParseQueryString([String]::Empty)
+
+    foreach ($key in $QueryParameter.Keys)
+    {
+        $nvCollection.Add($key, $QueryParameter.$key)
+    }
+
+    # Build the uri
+    $uriRequest = [System.UriBuilder]$uri
+    $uriRequest.Query = $nvCollection.ToString()
+
+    return $uriRequest.Uri.OriginalString
+}

src/public/Formats/Get-NexusFormat.ps1

@@ -0,0 +1,52 @@
+function Get-NexusFormat {
+    <#
+    .SYNOPSIS
+    Returns detailed format information
+
+    .DESCRIPTION
+    Returns detailed information about the upload specifications for each format supported
+
+    .PARAMETER RepositoryFormat
+    Retrieve information about a specific format
+
+    .EXAMPLE
+    Get-NexusFormat
+
+    .EXAMPLE
+    Get-NexusFormat -RepositoryFormat nuget
+    #>
+    [Cmdletbinding(HelpUri='https://steviecoaster.github.io/NexuShell/Formats/Get-NexusFormat/')]
+    Param(
+        [Parameter()]
+        [Alias('Format')]
+        [ValidateSet('helm',
+            'r',
+            'pypi',
+            'docker',
+            'yum',
+            'rubygems',
+            'nuget',
+            'npm',
+            'raw',
+            'apt',
+            'maven2'
+        )]
+        [String]
+        $RepositoryFormat
+    )
+    begin {
+        if (-not $header) {
+            throw "Not connected to Nexus server! Run Connect-NexusServer first."
+        }
+
+        $urislug = if (-not $RepositoryFormat) {
+            "/service/rest/v1/formats/upload-specs"
+        }
+        else {
+            "/service/rest/v1/formats/$RepositoryFormat/upload-specs"
+        }
+    }
+    process {
+        Invoke-Nexus -UriSlug $urislug -Method 'GET'
+    }
+}

src/public/Security/ContentSelector/Get-NexusContentSelector.ps1

@@ -18,7 +18,7 @@ function Get-NexusContentSelector {
     .NOTES
 
     #>
-    [CmdletBinding(HelpUri='')]
+    [CmdletBinding(HelpUri='https://steviecoaster.github.io/NexuShell/Security/Content%20Selectors/Get-NexusContentSelector/')]
     Param(
         [Parameter()]
         [String[]]

src/public/Security/ContentSelector/New-NexusContentSelector.ps1

@@ -21,7 +21,7 @@ function New-NexusContentSelector {
     .NOTES
 
     #>
-    [CmdletBinding(HelpUri='')]
+    [CmdletBinding(HelpUri='https://steviecoaster.github.io/NexuShell/Security/Content%20Selectors/New-NexusContentSelector/')]
     Param(
         [Parameter(Mandatory)]
         [String]

src/public/Security/ContentSelector/Remove-NexusContentSelector.ps1

@@ -24,7 +24,7 @@ function Remove-NexusContentSelector {
     .NOTES
 
     #>
-    [CmdletBinding(HelpUri = '',SupportsShouldProcess,ConfirmImpact='High')]
+    [CmdletBinding(HelpUri = 'https://steviecoaster.github.io/NexuShell/Security/Content%20Selectors/Remove-NexusContentSelector/',SupportsShouldProcess,ConfirmImpact='High')]
     Param(
         [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
         [ArgumentCompleter( {

src/public/Security/ContentSelector/Set-NexusContentSelector.ps1

@@ -21,7 +21,7 @@ function Set-NexusContentSelector {
     .NOTES
 
     #>
-    [CmdletBinding(HelpUri='')]
+    [CmdletBinding(HelpUri='https://steviecoaster.github.io/NexuShell/Security/Content%20Selectors/Set-NexusContentSelector/')]
     Param(
         [Parameter(Mandatory)]
         [ArgumentCompleter({

src/public/Tags/Add-NexusTagAssociation.ps1

@@ -0,0 +1,56 @@
+function Add-NexusTagAssociation {
+    <#
+    .SYNOPSIS
+    Tags a component with the provided tag name based on the search query parameters
+
+    .DESCRIPTION
+    Tags a component based on the Query terms based via hashtable to the API endpoint.
+
+    .PARAMETER Tag
+    The tag to apply to the component(s)
+
+    .PARAMETER SearchQuery
+    A hashtable of search parameters by which to tag components
+
+    .EXAMPLE
+    Add-NexusTag -Tag SampleTag -SearchQuery @{ format = 'nuget' ; repository = 'ChocolateyPackages'}
+
+    .LINK
+    https://help.sonatype.com/en/tagging.html
+    #>
+    [CmdletBinding(HelpUri='https://steviecoaster.github.io/NexuShell/Tags/Add-NexusTagAssociation/')]
+    Param(
+        [Parameter(Mandatory)]
+        [String]
+        $Tag,
+
+        [Parameter()]
+        [hashtable]
+        $SearchQuery
+    )
+
+    begin {
+        if (-not $header) {
+            throw "Not connected to Nexus server! Run Connect-NexusServer first."
+        }
+
+        $urislug = '/service/rest/v1/tags/associate/{0}' -f $Tag
+    }
+
+    process {
+        $UriBase = "$($protocol)://$($Hostname):$($port)$($ContextPath)"
+        $Uri = $UriBase + $UriSlug
+
+        $tagUrl = New-HttpQueryString -Uri $uri -QueryParameter $SearchQuery
+
+        $Params = @{
+            Headers = $header
+            ContentType = 'application/json'
+            Uri = $tagUrl
+            Method = 'POST'
+            UseBasicParsing = $true
+        }
+
+        Invoke-RestMethod @Params
+    }
+}

src/public/Tags/Get-NexusTag.ps1

@@ -0,0 +1,33 @@
+function Get-NexusTag {
+    [Cmdletbinding(HelpUri = 'https://steviecoaster.github.io/NexuShell/Tags/Get-NexusTag/')]
+    Param(
+        [Parameter()]
+        [String]
+        $Name
+    )
+
+    begin {
+
+        if (-not $header) {
+            throw "Not connected to Nexus server! Run Connect-NexusServer first."
+        }
+
+        $urislug = if (-not $Name) {
+            '/service/rest/v1/tags'
+        }
+        else {
+            "/service/rest/v1/tags/$Name"
+        }
+
+    }
+
+    process {
+        if(-not $Name){
+            $result = Invoke-Nexus -Urislug $urislug -Method GET
+            $result.items
+        } else {
+            Invoke-Nexus -UriSlug $urislug -Method GET
+        }
+    }
+
+}

src/public/Tags/New-NexusTag.ps1

@@ -0,0 +1,70 @@
+function New-NexusTag {
+<#
+.SYNOPSIS
+Create a tag
+
+.DESCRIPTION
+Create a tag in Nexus Repository. Useful with CI/CD platforms, similar to git tags.
+
+.PARAMETER Tag
+The friendly name of the tag
+
+.PARAMETER Attributes
+Any additional metadata you wish to tag a component with
+
+.EXAMPLE
+ $tag = @{
+    name = 'SampleTag'
+    attributes = @{
+        jvm = '9'
+        builtby = 'Jenkins'
+    }
+ }
+
+ New-NexusTag @tag
+
+.LINK
+https://help.sonatype.com/en/tagging.html
+#>
+    [CmdletBinding(HelpUri='https://steviecoaster.github.io/NexuShell/Tags/New-NexusTag/')]
+    Param(
+        [Parameter(Mandatory)]
+        [ValidateLength(1,256)]
+        [String]
+        $Tag,
+
+        [Parameter()]
+        [hashtable]
+        $Attributes
+    )
+    begin{
+        if (-not $header) {
+            throw "Not connected to Nexus server! Run Connect-NexusServer first."
+        }
+
+        $urislug = '/service/rest/v1/tags'
+
+        if ($Tag.Length -gt 256) {
+            throw "Name cannot exceed 256 characters."
+        }
+
+        if ($Tag -notmatch '^[a-zA-Z0-9_.-]+$') {
+            throw "Name can only contain letters, numbers, underscores, hyphens, and dots."
+        }
+
+        if ($Tag -match '^[_\.]') {
+            throw "Name cannot start with an underscore or dot."
+        }
+    }
+
+    process {
+
+        $body = @{
+            name = $Tag
+            attributes = $Attributes
+        }
+
+        Invoke-Nexus -Urislug $urislug -Body $body -Method POST
+    }
+
+}

src/public/Tags/Remove-NexusTag.ps1

@@ -0,0 +1,58 @@
+function Remove-NexusTag {
+    <#
+    .SYNOPSIS
+    Removes a tag from Sonatype Nexus
+
+    .DESCRIPTION
+    Removes a tag from Nexus. Completely disassociates all tagged components. Use Remove-NexusTagAssociation to modify tags on individual components.
+
+    .PARAMETER Tag
+    The tag to remove
+
+    .PARAMETER Force
+    Don't prompt for confirmation.
+
+    .EXAMPLE
+    Remove-NexusTag -Tag SampleTag
+
+    This will prompt you to confirm the deletion
+
+    .EXAMPLE
+    Remove-NexusTag -Tag SampleTag -Force
+
+    No prompts for confirmation. Potentially dangerous. Use -Whatif if not sure of results
+
+    .LINK
+    https://help.sonatype.com/en/tagging.html
+    #>
+    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High', HelpUri = 'https://steviecoaster.github.io/NexuShell/Tags/Remove-NexusTag/')]
+    Param(
+        [Parameter(Mandatory)]
+        [String]
+        $Tag,
+
+        [Parameter()]
+        [Switch]
+        $Force
+    )
+    begin {
+        if (-not $header) {
+            throw "Not connected to Nexus server! Run Connect-NexusServer first."
+        }
+
+        $urislug = '/service/rest/v1/tags/{0}' -f $Tag
+    }
+    process {
+        if ($Force -and -not $Confirm) {
+            $ConfirmPreference = 'None'
+            if ($PSCmdlet.ShouldProcess("$($_)", "Remove Tag")) {
+                Invoke-Nexus -Urislug $urislug -Method 'DELETE'
+            }
+        }
+        else {
+            if ($PSCmdlet.ShouldProcess("$($_)", "Remove Tag")) {
+                Invoke-Nexus -Urislug $urislug -Method 'DELETE'
+            }
+        }
+    }
+}