Public/New-GhostTheme.ps1

function New-GhostTheme {
    <#
    .SYNOPSIS
        Uploads a theme to the Ghost site.

    .DESCRIPTION
        Uploads a theme and returns it, with the warnings Ghost has about it. The theme is a zip file, or the
        folder of a theme, which is packed first: without the folders node_modules and dist, without files and
        folders whose name starts with a dot, and without zip files.

        Ghost names a theme after the zip file. For a folder that is the name in its package.json; -Name gives
        another one. A theme with that name that is already on the site is replaced, also when it is the active
        theme, so uploading a new version of the active theme puts it live. The names of the themes that come
        with Ghost, such as source and casper, cannot be used.

        Ghost checks the theme the way gscan does and refuses a theme with fatal errors; the error lists them.
        An uploaded theme is not shown on the site until it is activated: use -Activate or Enable-GhostTheme.

        A theme does not hold the routes of a site. Ghost does not let an integration upload routes.yaml: do
        that in Ghost Admin, under Settings > Labs.

    .EXAMPLE
        New-GhostTheme -Path ./dist/my-theme.zip

        Uploads the theme. The site keeps showing the theme that is active.

    .EXAMPLE
        New-GhostTheme -Path ./my-theme -Activate

        Packs the folder of the theme, uploads it and activates it.

    .EXAMPLE
        (New-GhostTheme -Path ./my-theme -Name 'my-theme-preview').warnings | Format-List -Property rule, details

        Uploads the theme under another name, next to the theme that is live, and shows what Ghost warns about.

    .LINK
        https://docs.ghost.org/admin-api/themes/uploading-a-theme

    .LINK
        https://docs.ghost.org/admin-api/themes/overview
    #>

    [CmdletBinding(SupportsShouldProcess)]
    [OutputType('Ghost.Theme')]
    param(
        # The zip file of a theme, or the folder of a theme. The path is taken literally: wildcards are not
        # expanded.
        [Parameter(Mandatory, Position = 0, ValueFromPipeline, ValueFromPipelineByPropertyName)]
        [Alias('FullName')]
        [ValidateNotNullOrEmpty()]
        [string] $Path,

        # Name to store the theme under. Defaults to the name of the zip file or, for a folder, to the name in
        # its package.json.
        [ValidateNotNullOrEmpty()]
        [string] $Name,

        # Activate the theme once it is uploaded.
        [switch] $Activate
    )

    begin {
        Test-GhostConnection
        $resources = Get-GhostAPIData -Endpoint $MyInvocation.MyCommand.Name
    }

    process {
        try {
            if (-not (Test-Path -LiteralPath $Path)) {
                throw "The theme '$Path' does not exist."
            }
            $source = (Resolve-Path -LiteralPath $Path).ProviderPath.TrimEnd('\', '/')

            if (Test-Path -LiteralPath $source -PathType Container) {
                $content = ConvertTo-GhostThemeArchive -Path $source

                $themeName = [System.IO.Path]::GetFileName($source)
                $packagePath = Join-Path -Path $source -ChildPath 'package.json'
                $package = ConvertFrom-Json -InputObject ([System.IO.File]::ReadAllText($packagePath))
                $packageName = $package.PSObject.Properties['name']
                if ($packageName -and $packageName.Value) {
                    $themeName = [string] $packageName.Value
                }
            }
            else {
                if ([System.IO.Path]::GetExtension($source) -ne '.zip') {
                    throw "'$Path' is neither a zip file nor the folder of a theme."
                }
                $content = [System.IO.File]::ReadAllBytes($source)
                $themeName = [System.IO.Path]::GetFileNameWithoutExtension($source)
            }
            if ($PSBoundParameters.ContainsKey('Name')) {
                $themeName = $Name
            }

            $form = @{
                FileName        = "$themeName.zip"
                FileContent     = $content
                FileContentType = 'application/zip'
            }
            $form = ConvertTo-MultipartContent @form

            $uri = New-URIString -Endpoint $resources.URI

            if ($PSCmdlet.ShouldProcess($themeName, $resources.Description)) {
                $request = @{
                    Uri         = $uri
                    Method      = $resources.Method
                    Content     = $form.Content
                    ContentType = $form.ContentType
                    Success     = $resources.Success
                }
                $result = Submit-Request @request
                $result = @(Test-ReturnFormat -Result $result -Location $resources.Result)

                if ($Activate) {
                    # The name as Ghost stored it, which can differ from the name that was sent.
                    $result | ForEach-Object { Enable-GhostTheme -Name $_.name -Confirm:$false }
                }
                else {
                    Set-ObjectTypeName -InputObject $result -TypeName $resources.TypeName
                }
            }
        }
        catch {
            $failure = $_

            # Ghost says that a theme has errors, and which ones only in the details. Without them the message
            # leaves the caller guessing.
            $rules = @()
            $ghostError = $failure.Exception.Data['GhostError']
            if ($failure.FullyQualifiedErrorId -like 'ThemeValidationError*' -and $ghostError) {
                $details = $ghostError.PSObject.Properties['details']
                $errors = if ($details -and $details.Value) { $details.Value.PSObject.Properties['errors'] }
                if ($errors) {
                    $rules = @(
                        foreach ($item in $errors.Value) {
                            # The rules are written for a web page.
                            '- {0}' -f ([string] $item.rule -replace '<[^>]+>')
                        }
                    )
                }
            }
            if ($rules.Count -gt 0) {
                $newLine = [System.Environment]::NewLine
                $message = $failure.Exception.Message + $newLine + ($rules -join $newLine)
                $exception = [System.InvalidOperationException]::new($message, $failure.Exception)
                foreach ($key in $failure.Exception.Data.Keys) {
                    $exception.Data[$key] = $failure.Exception.Data[$key]
                }
                $failure = [System.Management.Automation.ErrorRecord]::new(
                    $exception,
                    'ThemeValidationError',
                    [System.Management.Automation.ErrorCategory]::InvalidData,
                    $failure.TargetObject
                )
            }

            $PSCmdlet.ThrowTerminatingError($failure)
        }
    }
}