Neocities 0.1

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [StartAutomating]

Build/GitHub/Jobs/BuildNeocities.psd1

@@ -0,0 +1,39 @@
+@{
+    "runs-on" = "ubuntu-latest"    
+    if = '${{ success() }}'
+    steps = @(
+        @{
+            name = 'Check out repository'
+            uses = 'actions/checkout@v2'
+        },
+        @{
+            name = 'GitLogger'
+            uses = 'GitLogging/GitLoggerAction@main'
+            id = 'GitLogger'
+        },
+        @{
+            name = 'Use PSSVG Action'
+            uses = 'StartAutomating/PSSVG@main'
+            id = 'PSSVG'
+        },
+        @{
+            name = 'Use PipeScript Action'
+            uses = 'StartAutomating/PipeScript@main'
+            id = 'PipeScript'
+        },        
+        'RunEZOut',
+        'RunHelpOut',
+        @{
+            name = 'Use PSJekyll Action'
+            uses = 'PowerShellWeb/PSJekyll@main'
+            id = 'PSJekyll'
+        }
+        <#@{
+            name = 'Run WebSocket (on branch)'
+            if   = '${{github.ref_name != ''main''}}'
+            uses = './'
+            id = 'WebSocketAction'
+        },#>
+        # 'BuildAndPublishContainer'
+    )
+}

Build/GitHub/Steps/PublishTestResults.psd1

@@ -0,0 +1,10 @@
+@{
+    name = 'PublishTestResults'
+    uses = 'actions/upload-artifact@main'
+    with = @{
+        name = 'PesterResults'
+        path = '**.TestResults.xml'
+    }
+    if = '${{always()}}'
+}
+

Build/Neocities.GitHubWorkflow.PSDevOps.ps1

@@ -0,0 +1,15 @@
+#requires -Module PSDevOps
+Import-BuildStep -SourcePath (
+    Join-Path $PSScriptRoot 'GitHub'
+) -BuildSystem GitHubWorkflow
+
+Push-Location ($PSScriptRoot | Split-Path)
+
+New-GitHubWorkflow -Name "Build Module" -On Push, 
+    PullRequest, Demand -Job TestPowerShellOnLinux, 
+    TagReleaseAndPublish, BuildNeocities -Environment ([Ordered]@{
+        REGISTRY = 'ghcr.io'
+        IMAGE_NAME = '${{ github.repository }}'
+    }) -OutputPath .\.github\workflows\Build.yml
+
+Pop-Location

Build/Neocities.HelpOut.ps1

@@ -0,0 +1,14 @@
+#requires -Module HelpOut
+
+#region Load the Module
+$ModuleName = 'Neocities'
+Push-Location ($PSScriptRoot | Split-Path)
+if (-not (Get-Module $ModuleName)) {
+    Import-Module .\ -Global -PassThru | Out-Host
+}
+#endregion Load the Module
+
+# This will save the MarkdownHelp to the docs folder, and output all of the files created.
+Save-MarkdownHelp -PassThru -Module $ModuleName -ExcludeCommandType Alias
+
+Pop-Location

Build/Neocities.ezout.ps1

@@ -0,0 +1,39 @@
+#requires -Module EZOut
+#  Install-Module EZOut or https://github.com/StartAutomating/EZOut
+$myFile = $MyInvocation.MyCommand.ScriptBlock.File
+$myRoot = $myFile | Split-Path | Split-Path
+$myModuleName = $myFile | Split-Path | Split-Path | Split-Path -Leaf
+Push-Location $myRoot
+$formatting = @(
+    # Add your own Write-FormatView here,
+    # or put them in a Formatting or Views directory
+    foreach ($potentialDirectory in 'Formatting','Views','Types') {
+        Join-Path $myRoot $potentialDirectory |
+            Get-ChildItem -ea ignore |
+            Import-FormatView -FilePath {$_.Fullname}
+    }
+)
+
+$destinationRoot = $myRoot
+
+if ($formatting) {
+    $myFormatFilePath = Join-Path $destinationRoot "$myModuleName.format.ps1xml"
+    # You can also output to multiple paths by passing a hashtable to -OutputPath.
+    $formatting | Out-FormatData -Module $MyModuleName -OutputPath $myFormatFilePath
+}
+
+$types = @(
+    # Add your own Write-TypeView statements here
+    # or declare them in the 'Types' directory
+    Join-Path $myRoot Types |
+        Get-Item -ea ignore |
+        Import-TypeView
+
+)
+
+if ($types) {
+    $myTypesFilePath = Join-Path $destinationRoot "$myModuleName.types.ps1xml"
+    # You can also output to multiple paths by passing a hashtable to -OutputPath.
+    $types | Out-TypeData -OutputPath $myTypesFilePath
+}
+Pop-Location

Commands/Connect-Neocities.ps1

@@ -0,0 +1,33 @@
+function Connect-Neocities
+{
+    <#
+    .SYNOPSIS
+        Connect to Neocities
+    .DESCRIPTION
+        Connect to Neocities using a credential object. 
+
+        This will create a session that can be used to authenticate to the Neocities API.
+    .LINK
+        Get-Neocities
+    #>
+    param(
+    # The Neocities credential
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [Alias(
+        'Credentials', # Plural aliases are nice
+        'PSCredential', # so are parameters that match the type name.
+        'NeocitiesCredential', # A contextual alias is a good idea, too.
+        'NeocitiesCredentials' # And you may need to pluralize that contextual alias.
+    )]
+    [PSCredential]
+    $Credential
+    )
+
+    begin {
+        $NeocitiesApi = "https://neocities.org/api"
+    }
+
+    process {
+        Invoke-RestMethod -Uri ($NeocitiesApi,'key' -join '/') -Credential $Credential -Authentication Basic
+    }
+}

Commands/Get-Neocities.ps1

@@ -0,0 +1,122 @@
+function Get-Neocities
+{
+    <#
+    .SYNOPSIS
+        Gets neocities information
+    .DESCRIPTION
+        Gets neocities information from the neocities API, or lists the files in your neocities site.
+    .EXAMPLE
+        Get-Neocities
+    .EXAMPLE    
+        Get-Neocities -Credential $neocitiesCredential
+    .EXAMPLE
+        Get-Neocities -List
+    #>
+    [Alias('neocities')]
+    [CmdletBinding(DefaultParameterSetName='info')]
+    param(
+    # If set, will list the files in your neocities site
+    [Parameter(Mandatory,ValueFromPipelineByPropertyName,ParameterSetName='list')]
+    [switch]
+    $List,
+
+    # The credential used to connect.  
+    # This only needs to be provided once per module session
+    # (every time the module is imported)
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [Alias(
+        'Credentials', # Plural aliases are nice
+        'PSCredential', # so are parameters that match the type name.
+        'NeocitiesCredential', # A contextual alias is a good idea, too.
+        'NeocitiesCredentials' # And you may need to pluralize that contextual alias.
+    )]
+    [PSCredential]
+    $Credential,
+
+    # The access token used to connect.
+    # This only needs to be provided once per module session
+    # (every time the module is imported)
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [string]
+    $AccessToken
+    )
+
+    begin {
+        $NeocitiesApi = "https://neocities.org/api"
+    }
+
+    process {
+        # The parameter set name contains the route
+        $parameterSet = $PSCmdlet.ParameterSetName        
+        # and we want to use this to decorate all returned values with a type name
+        $psuedoNamespace = "neocities"
+        $pseudoType = "$parameterSet"
+        # Start by constructing the parameters for Invoke-RestMethod
+        $InvokeSplat = [Ordered]@{
+            Uri = "$NeocitiesApi", $PSCmdlet.ParameterSetName -join '/'
+        }        
+
+        # If an access token was provided
+        if ($AccessToken)
+        {
+            # use it
+            $InvokeSplat.Headers = @{Authorization = "Bearer $AccessToken"}
+            # and cache it for later use
+            $script:NeocitiesAccessToken = $AccessToken
+        } 
+        elseif ($Credential)
+        {
+            # If a credential was provided, use it
+            $InvokeSplat.Credential = $Credential
+            # and cache it for later use
+            $script:NeoCitiesCredential = $Credential
+            # (don't forget to set authentication to basic)
+            $InvokeSplat.Authentication = 'Basic'
+        }
+        elseif ($script:NeocitiesAccessToken) {
+            # If we had a cached access token, use it
+            $InvokeSplat.Headers = @{Authorization = "Bearer $($script:NeocitiesAccessToken)"}
+        }
+        elseif ($script:NeoCitiesCredential) {
+            # If we had a cached credential, use it
+            $InvokeSplat.Credential = $script:NeoCitiesCredential
+            # and don't forget to set authentication to basic.
+            $InvokeSplat.Authentication = 'Basic'
+        }
+
+        # If neither an access token nor a credential was provided, we can't do anything.
+        if (-not $InvokeSplat.Credential -and -not $InvokeSplat.Headers)
+        {
+            # so error out.
+            Write-Error "No -Credential provided"
+            return
+        }
+
+
+        # Write a little verbose message to let the user know what we're doing
+        Write-Verbose "Requesting $($InvokeSplat.Uri)"
+        # and get a response from neocities.
+        $neocitiesResponse = Invoke-RestMethod @InvokeSplat
+        switch ($parameterSet) {
+            info {
+                # If we're getting info, we want to return the info object
+                $neocitiesResponse = $neocitiesResponse.info        
+            }
+            list {
+                # If we're listing files, we want to return the files object
+                $neocitiesResponse = @($neocitiesResponse.files)
+                # and we want to return each as a 'file', not a 'list'
+                $pseudoType = 'file'
+            }
+        }
+
+        # Go over each response
+        foreach ($neoResponse in $neocitiesResponse) {
+            # and decorate them with the type name
+            $neoResponse.pstypenames.clear()
+            $neoResponse.pstypenames.insert(0, ($psuedoNamespace, $pseudoType -join '.'))
+            # and output the response.
+            $neoResponse
+        }        
+    }
+}

Commands/Remove-Neocities.ps1

@@ -0,0 +1,115 @@
+function Remove-Neocities
+{
+    <#
+    .SYNOPSIS
+        Removes files from neocities
+    .DESCRIPTION
+        Removes files from a neocities site using the neocities API.
+    #>
+    [CmdletBinding(DefaultParameterSetName='delete',SupportsShouldProcess,ConfirmImpact='High')]
+    param(
+    # The name of the file to remove.
+    [Parameter(Mandatory,ValueFromPipelineByPropertyName)]
+    [Alias('FullName','Path')]
+    [string[]]
+    $FileName,
+
+
+    # The neocities credential
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [Alias(
+        'Credentials', # Plural aliases are nice
+        'PSCredential', # so are parameters that match the type name.
+        'NeocitiesCredential', # A contextual alias is a good idea, too.
+        'NeocitiesCredentials' # And you may need to pluralize that contextual alias.
+    )]
+    [PSCredential]
+    $Credential,
+
+    # The neocities access token.  
+    [Parameter(ValueFromPipelineByPropertyName)]
+    [string]
+    $AccessToken
+    )
+
+    begin {
+        $NeocitiesApi = "https://neocities.org/api"
+    }
+
+    process {
+        $parameterSet = $PSCmdlet.ParameterSetName
+        $psuedoNamespace = "neocities"
+        $pseudoType = "$parameterSet"
+        $InvokeSplat = [Ordered]@{
+            Uri = "$NeocitiesApi", $PSCmdlet.ParameterSetName -join '/'
+            Method = 'POST'
+        }
+
+        # If an access token was provided
+        if ($AccessToken)
+        {
+            # use it
+            $InvokeSplat.Headers = @{Authorization = "Bearer $AccessToken"}
+            # and cache it for later use
+            $script:NeocitiesAccessToken = $AccessToken
+        } 
+        elseif ($Credential)
+        {
+            # If a credential was provided, use it
+            $InvokeSplat.Credential = $Credential
+            # and cache it for later use
+            $script:NeoCitiesCredential = $Credential
+            # (don't forget to set authentication to basic)
+            $InvokeSplat.Authentication = 'Basic'
+        }
+        elseif ($script:NeocitiesAccessToken) {
+            # If we had a cached access token, use it
+            $InvokeSplat.Headers = @{Authorization = "Bearer $($script:NeocitiesAccessToken)"}
+        }
+        elseif ($script:NeoCitiesCredential) {
+            # If we had a cached credential, use it
+            $InvokeSplat.Credential = $script:NeoCitiesCredential
+            # and don't forget to set authentication to basic.
+            $InvokeSplat.Authentication = 'Basic'
+        }
+
+        # If neither an access token nor a credential was provided, we can't do anything.
+        if (-not $InvokeSplat.Credential -and -not $InvokeSplat.Headers)
+        {
+            # so error out.
+            Write-Error "No -Credential provided"
+            return
+        }
+
+        # For every file name provided, we need to remove it from the neocities site.
+        foreach ($file in $fileName) {
+            # Despite the name taking an array, we need to remove one file at a time.
+            $InvokeSplat.Body = 
+                [web.httputility]::UrlEncode("filenames[]"),'=',[web.httputility]::UrlEncode($file) -join ''
+            Write-Verbose "Requesting $($InvokeSplat.Uri)"
+            # If -WhatIf was specified, we need to remove the credential and headers from the splat
+            if ($WhatIfPreference) {
+                $splatCopy = [Ordered]@{} + $InvokeSplat
+                $splatCopy.Remove('Credential')
+                $splatCopy.Remove('Headers')
+                # and then output the splat to the pipeline
+                $splatCopy
+                continue
+            }
+            # If we did not confirm the deletion
+            if (-not $PSCmdlet.ShouldProcess("Delete $file")) {
+                # skip it.
+                continue
+            }
+
+            # Get the response from neocities.
+            $neocitiesResponse = Invoke-RestMethod @InvokeSplat
+            # and decorate any response so that we know it was a deletion. 
+            foreach ($neoResponse in $neocitiesResponse) {
+                $neoResponse.pstypenames.clear()
+                $neoResponse.pstypenames.insert(0, ($psuedoNamespace, $pseudoType -join '.'))
+                $neoResponse
+            }
+        }                                
+    }
+}