Remove-DockerArtifact.ps1

function Remove-DockerArtifact
{
    <#
    .SYNOPSIS
        Cleans up unused Docker artifacts with safety controls.

    .DESCRIPTION
        Removes unused Docker images, networks, build cache, and (optionally) stopped containers, volumes,
        Buildx builder instances, and Docker Desktop build history.
        Supports -WhatIf/-Confirm and lets you choose between pruning all unused images or only dangling ones.
        For -WhatIf, EstimatedReclaimable is calculated by scanning unused images so you know what would be freed.

        By default:
        - Unused images (not just dangling) are pruned
        - Unused networks and build cache are pruned
        - Stopped containers are NOT removed unless -IncludeStoppedContainers is specified
        - Volumes are NOT removed unless -IncludeVolumes is specified
        - Buildx builder instances are NOT removed unless -IncludeBuildxBuilders is specified
        - Docker Desktop build history is NOT removed unless -IncludeBuildHistory is specified

        Cross-platform compatible with PowerShell 5.1+ on Windows, macOS, and Linux. Requires Docker CLI
        to be installed and available in PATH.

    .PARAMETER All
        Convenience switch that includes all cleanup categories: stopped containers, unused volumes,
        Buildx builder instances, and Docker Desktop build history.

    .PARAMETER IncludeStoppedContainers
        Also remove stopped containers. When specified, cleanup uses 'docker system prune' to mirror Docker's
        built-in behavior (including images, networks, build cache, and optionally volumes).

    .PARAMETER DanglingImagesOnly
        Restrict image pruning to dangling images only (same as omitting '--all'). By default, all unused
        images are pruned to maximize reclaimed space.

    .PARAMETER IncludeVolumes
        Also prune unused volumes. Volumes can hold data you care about; use -WhatIf or -Confirm first if unsure.

    .PARAMETER IncludeBuildxBuilders
        Also remove Buildx builders that use the 'docker-container' driver. This removes their BuildKit
        containers so pinned images like 'moby/buildkit:buildx-stable-1' can be pruned in the same run.

    .PARAMETER IncludeBuildHistory
        Also remove Docker Desktop build records from the current buildx builder and prune BuildKit cache.
        This runs:
        - 'docker buildx history rm --all' (removes records shown in Docker Desktop Build History)
        - 'docker buildx prune --all --force' (removes reusable build cache entries)

    .EXAMPLE
        PS > Remove-DockerArtifact
        PS > # Unused images (all), networks, and build cache pruned; containers and volumes untouched

        Runs a safe cleanup that leaves stopped containers and volumes alone while reclaiming image, network,
        and build cache space.

    .EXAMPLE
        PS > Remove-DockerArtifact -IncludeStoppedContainers -IncludeVolumes

        Performs a full 'docker system prune --all --volumes', removing stopped containers, unused images,
        networks, build cache, and unused volumes.

    .EXAMPLE
        PS > Remove-DockerArtifact -DanglingImagesOnly -IncludeStoppedContainers

        Mirrors 'docker system prune' default behavior: removes stopped containers, dangling images, unused
        networks, and build cache while keeping non-dangling unused images.

    .EXAMPLE
        PS > Remove-DockerArtifact -IncludeStoppedContainers -WhatIf

        Shows what a full system prune would remove without actually deleting anything and displays an
        estimated reclaimable size for unused images.

    .EXAMPLE
        PS > Remove-DockerArtifact -IncludeVolumes -Confirm

        Prompts for confirmation before removing unused volumes along with images, networks, and build cache.

    .EXAMPLE
        PS > Remove-DockerArtifact -IncludeBuildHistory

        Includes Docker Desktop build history cleanup by removing build records and pruning build cache.

    .EXAMPLE
        PS > Remove-DockerArtifact -IncludeBuildxBuilders

        Removes Buildx builders that use the docker-container driver so their BuildKit containers no longer
        hold BuildKit images in-use.

    .EXAMPLE
        PS > Remove-DockerArtifact -All

        Includes stopped containers, unused volumes, Buildx builder instances, and Docker Desktop build
        history in a single cleanup run.

    .OUTPUTS
        [PSCustomObject]
        Returns an object with summary information:
        - ContainersPruned      : $true if stopped containers were included
        - VolumesPruned         : $true if volumes were included
        - BuildxBuildersPruned  : $true if Buildx builder removal was included
        - BuildHistoryPruned    : $true if Docker Desktop build history cleanup was included
        - ImageMode             : 'AllUnused' or 'DanglingOnly'
        - EstimatedReclaimable  : Estimated unused image size in -WhatIf runs; otherwise reports not calculated
        - TotalSpaceFreed       : Total space freed based on prune output (formatted string)
        - Errors                : Number of errors encountered

    .NOTES
        - Requires Docker CLI
        - Respects -WhatIf and -Confirm for safety
        - Buildx builder cleanup only targets builders using the 'docker-container' driver
        - When -IncludeStoppedContainers is not used, pruning is composed of targeted image/network/builder
          commands to avoid touching containers

        Author: Jon LaBelle
        License: MIT
        Source: https://github.com/jonlabelle/pwsh-profile/blob/main/Functions/Developer/Remove-DockerArtifact.ps1

    .LINK
        https://docs.docker.com/reference/cli/docker/system/prune/

    .LINK
        https://docs.docker.com/reference/cli/docker/volume/prune/

    .LINK
        https://docs.docker.com/reference/cli/docker/buildx/prune/
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '')]
    [CmdletBinding(SupportsShouldProcess)]
    [OutputType([PSCustomObject])]
    param(
        [Parameter()]
        [Switch]$All,

        [Parameter()]
        [Switch]$IncludeStoppedContainers,

        [Parameter()]
        [Switch]$DanglingImagesOnly,

        [Parameter()]
        [Switch]$IncludeVolumes,

        [Parameter()]
        [Switch]$IncludeBuildxBuilders,

        [Parameter()]
        [Switch]$IncludeBuildHistory
    )

    begin
    {
        Write-Verbose 'Starting Docker artifacts cleanup'

        $stats = @{
            ContainersPruned = $false
            VolumesPruned = $false
            BuildxBuildersPruned = $false
            BuildHistoryPruned = $false
            ImageMode = if ($DanglingImagesOnly) { 'DanglingOnly' } else { 'AllUnused' }
            SpaceFreedBytes = [int64]0
            EstimatedReclaimableBytes = [int64]0
            EstimatedReclaimableEstimateSucceeded = $false
            Errors = 0
        }

        $dockerCommand = Get-Command -Name 'docker' -ErrorAction SilentlyContinue
        if (-not $dockerCommand)
        {
            throw 'Docker is not installed or not available in PATH. Please install Docker and try again.'
        }

        Write-Verbose "Docker found at: $($dockerCommand.Source)"

        if ($All -and $DanglingImagesOnly)
        {
            throw 'The -All and -DanglingImagesOnly parameters cannot be used together.'
        }

        function Convert-SizeStringToBytes
        {
            param([String]$SizeString)

            if ([string]::IsNullOrWhiteSpace($SizeString))
            {
                return [int64]0
            }

            $clean = $SizeString.Trim()
            $clean = $clean -replace '\(.*\)', '' -replace '\s+', ''

            if ($clean -match '^(?<Value>[0-9]+(?:\.[0-9]+)?)(?<Unit>[kmgtpe]?i?b)?$')
            {
                $value = [double]$matches['Value']
                $unit = $matches['Unit'].ToLower()
                switch ($unit)
                {
                    'kb' { return [int64]($value * 1KB) }
                    'kib' { return [int64]($value * 1KB) }
                    'mb' { return [int64]($value * 1MB) }
                    'mib' { return [int64]($value * 1MB) }
                    'gb' { return [int64]($value * 1GB) }
                    'gib' { return [int64]($value * 1GB) }
                    'tb' { return [int64]($value * 1TB) }
                    'tib' { return [int64]($value * 1TB) }
                    default { return [int64]$value }
                }
            }

            return [int64]0
        }

        function Format-ByteSize
        {
            param([int64]$Bytes)

            switch ($Bytes)
            {
                { $_ -ge 1TB } { '{0:N2} TB' -f ($_ / 1TB); break }
                { $_ -ge 1GB } { '{0:N2} GB' -f ($_ / 1GB); break }
                { $_ -ge 1MB } { '{0:N2} MB' -f ($_ / 1MB); break }
                { $_ -ge 1KB } { '{0:N2} KB' -f ($_ / 1KB); break }
                default { '{0} bytes' -f $_ }
            }
        }

        function Convert-ImageId
        {
            param([string]$Id)
            if ([string]::IsNullOrWhiteSpace($Id))
            {
                return $null
            }

            $trimmed = $Id.Trim()
            if ($trimmed.Length -gt 12)
            {
                return $trimmed.Substring(0, 12)
            }

            return $trimmed
        }

        function Get-UnusedImageEstimate
        {
            param([Switch]$DanglingOnly)

            try
            {
                $inUseIds = @()
                try
                {
                    $inUseIds = & $dockerCommand.Name ps -a --format '{{.ImageID}}' 2>&1 |
                    ForEach-Object { $_.ToString().Trim() } |
                    Where-Object { $_ -ne '' }
                }
                catch
                {
                    Write-Verbose "Failed to collect in-use container images: $($_.Exception.Message)"
                }

                $inUseSet = New-Object System.Collections.Generic.HashSet[string]
                foreach ($id in $inUseIds)
                {
                    $normalized = Convert-ImageId $id
                    if ($normalized) { $null = $inUseSet.Add($normalized) }
                }

                $imagesOutput = & $dockerCommand.Name image ls --format '{{json .}}' 2>&1
                $totalBytes = [int64]0
                $count = 0

                foreach ($line in $imagesOutput)
                {
                    $lineText = $line.ToString()
                    if ([string]::IsNullOrWhiteSpace($lineText)) { continue }
                    try
                    {
                        $img = $lineText | ConvertFrom-Json
                        $imageId = Convert-ImageId $img.ID
                        $isDangling = ($img.Repository -eq '<none>') -or ($img.Tag -eq '<none>')

                        if ($DanglingOnly -and -not $isDangling)
                        {
                            continue
                        }

                        $isInUse = $false
                        if ($imageId)
                        {
                            foreach ($inUse in $inUseSet)
                            {
                                if ($inUse -and ($imageId.StartsWith($inUse, [System.StringComparison]::OrdinalIgnoreCase) -or
                                        $inUse.StartsWith($imageId, [System.StringComparison]::OrdinalIgnoreCase)))
                                {
                                    $isInUse = $true
                                    break
                                }
                            }
                        }

                        if (-not $isInUse)
                        {
                            $count++
                            $totalBytes += Convert-SizeStringToBytes $img.Size
                        }
                    }
                    catch
                    {
                        Write-Verbose "Failed to parse docker image entry for estimation: $($_.Exception.Message)"
                    }
                }

                return [PSCustomObject]@{
                    Count = $count
                    Bytes = $totalBytes
                }
            }
            catch
            {
                Write-Verbose "Failed to estimate unused images: $($_.Exception.Message)"
                return [PSCustomObject]@{
                    Count = 0
                    Bytes = 0
                }
            }
        }

        function Invoke-DockerPrune
        {
            param(
                [String[]]$Arguments,
                [String]$Description
            )

            $reclaimedBytes = [int64]0
            if ($PSCmdlet.ShouldProcess('Docker daemon', $Description))
            {
                try
                {
                    $output = & $dockerCommand.Name @Arguments 2>&1
                    $exitCode = $LASTEXITCODE
                    if ($exitCode -ne 0)
                    {
                        $stats.Errors++
                        $errorSummary = $null
                        if ($output)
                        {
                            $errorSummary = $output |
                            ForEach-Object { $_.ToString().Trim() } |
                            Where-Object { $_ -ne '' } |
                            Select-Object -First 1
                        }

                        if ($errorSummary)
                        {
                            Write-Warning "Failed to run 'docker $($Arguments -join ' ')' (exit code $exitCode): $errorSummary"
                        }
                        else
                        {
                            Write-Warning "Failed to run 'docker $($Arguments -join ' ')' (exit code $exitCode)."
                        }

                        return [int64]0
                    }

                    foreach ($line in $output)
                    {
                        if ($line -match 'Total reclaimed space:\s*(.+)$')
                        {
                            $reclaimedBytes = Convert-SizeStringToBytes $matches[1]
                            break
                        }
                        elseif ($line -match '^Total:\s*(.+)$')
                        {
                            # buildx prune reports reclaimed size as "Total: <size>"
                            $reclaimedBytes = Convert-SizeStringToBytes $matches[1]
                            break
                        }
                    }
                }
                catch
                {
                    $stats.Errors++
                    Write-Warning "Failed to run 'docker $($Arguments -join ' ')': $($_.Exception.Message)"
                }
            }
            else
            {
                Write-Verbose "WhatIf: Would run 'docker $($Arguments -join ' ')'"
            }

            return $reclaimedBytes
        }

        function Remove-BuildxContainerBuilders
        {
            [CmdletBinding(SupportsShouldProcess)]
            param()

            $builderNames = @()
            $listArgs = @('buildx', 'ls', '--format', '{{json .}}')

            try
            {
                $listOutput = & $dockerCommand.Name @listArgs 2>&1
                $listExitCode = $LASTEXITCODE
                if ($listExitCode -ne 0)
                {
                    $stats.Errors++
                    $errorSummary = $null
                    if ($listOutput)
                    {
                        $errorSummary = $listOutput |
                        ForEach-Object { $_.ToString().Trim() } |
                        Where-Object { $_ -ne '' } |
                        Select-Object -First 1
                    }

                    if ($errorSummary)
                    {
                        Write-Warning "Failed to run 'docker $($listArgs -join ' ')' (exit code $listExitCode): $errorSummary"
                    }
                    else
                    {
                        Write-Warning "Failed to run 'docker $($listArgs -join ' ')' (exit code $listExitCode)."
                    }

                    return
                }

                foreach ($line in $listOutput)
                {
                    $lineText = $line.ToString()
                    if ([string]::IsNullOrWhiteSpace($lineText)) { continue }
                    try
                    {
                        $builder = $lineText | ConvertFrom-Json
                        if ($builder -and
                            $builder.Driver -eq 'docker-container' -and
                            -not [string]::IsNullOrWhiteSpace($builder.Name))
                        {
                            $builderNames += $builder.Name.Trim()
                        }
                    }
                    catch
                    {
                        Write-Verbose "Failed to parse buildx builder entry: $($_.Exception.Message)"
                    }
                }
            }
            catch
            {
                $stats.Errors++
                Write-Warning "Failed to run 'docker $($listArgs -join ' ')': $($_.Exception.Message)"
                return
            }

            $builderNames = $builderNames | Sort-Object -Unique
            if (-not $builderNames -or $builderNames.Count -eq 0)
            {
                Write-Verbose 'No docker-container Buildx builders found to remove.'
                return
            }

            foreach ($builderName in $builderNames)
            {
                $removeArgs = @('buildx', 'rm', '--force', $builderName)
                $description = "docker $($removeArgs -join ' ')"
                if ($PSCmdlet.ShouldProcess("Docker Buildx builder '$builderName'", $description))
                {
                    try
                    {
                        $removeOutput = & $dockerCommand.Name @removeArgs 2>&1
                        $removeExitCode = $LASTEXITCODE
                        if ($removeExitCode -ne 0)
                        {
                            $stats.Errors++
                            $errorSummary = $null
                            if ($removeOutput)
                            {
                                $errorSummary = $removeOutput |
                                ForEach-Object { $_.ToString().Trim() } |
                                Where-Object { $_ -ne '' } |
                                Select-Object -First 1
                            }

                            if ($errorSummary)
                            {
                                Write-Warning "Failed to run 'docker $($removeArgs -join ' ')' (exit code $removeExitCode): $errorSummary"
                            }
                            else
                            {
                                Write-Warning "Failed to run 'docker $($removeArgs -join ' ')' (exit code $removeExitCode)."
                            }
                        }
                    }
                    catch
                    {
                        $stats.Errors++
                        Write-Warning "Failed to run 'docker $($removeArgs -join ' ')': $($_.Exception.Message)"
                    }
                }
                else
                {
                    Write-Verbose "WhatIf: Would run 'docker $($removeArgs -join ' ')'"
                }
            }
        }
    }

    process
    {
        $includeStoppedContainersEffective = $IncludeStoppedContainers -or $All
        $includeVolumesEffective = $IncludeVolumes -or $All
        $includeBuildxBuildersEffective = $IncludeBuildxBuilders -or $All
        $includeBuildHistoryEffective = $IncludeBuildHistory -or $All

        # Estimate unused image space only for WhatIf previews
        $shouldEstimate = $WhatIfPreference -eq $true
        if ($shouldEstimate)
        {
            $estimate = Get-UnusedImageEstimate -DanglingOnly:$DanglingImagesOnly
            if ($estimate)
            {
                $stats.EstimatedReclaimableEstimateSucceeded = $true
                $stats.EstimatedReclaimableBytes = $estimate.Bytes
            }
        }

        $reclaimedTotal = [int64]0

        if ($includeBuildxBuildersEffective)
        {
            $stats.BuildxBuildersPruned = $true
            Remove-BuildxContainerBuilders
        }

        if ($includeStoppedContainersEffective)
        {
            $stats.ContainersPruned = $true
            $systemPruneArgs = @('system', 'prune', '--force')
            if (-not $DanglingImagesOnly)
            {
                $systemPruneArgs += '--all'
            }
            if ($includeVolumesEffective)
            {
                $stats.VolumesPruned = $true
                $systemPruneArgs += '--volumes'
            }

            $reclaimedTotal += Invoke-DockerPrune -Arguments $systemPruneArgs -Description "docker $($systemPruneArgs -join ' ')"
        }
        else
        {
            $imageArgs = @('image', 'prune', '--force')
            if (-not $DanglingImagesOnly)
            {
                $imageArgs += '--all'
            }
            $reclaimedTotal += Invoke-DockerPrune -Arguments $imageArgs -Description "docker $($imageArgs -join ' ')"

            $networkArgs = @('network', 'prune', '--force')
            $reclaimedTotal += Invoke-DockerPrune -Arguments $networkArgs -Description "docker $($networkArgs -join ' ')"

            $builderArgs = @('builder', 'prune', '--force')
            if (-not $DanglingImagesOnly)
            {
                $builderArgs += '--all'
            }
            $reclaimedTotal += Invoke-DockerPrune -Arguments $builderArgs -Description "docker $($builderArgs -join ' ')"

            if ($includeVolumesEffective)
            {
                $stats.VolumesPruned = $true
                $volumeArgs = @('volume', 'prune', '--force')
                $reclaimedTotal += Invoke-DockerPrune -Arguments $volumeArgs -Description "docker $($volumeArgs -join ' ')"
            }
        }

        if ($includeBuildHistoryEffective)
        {
            $stats.BuildHistoryPruned = $true
            $buildHistoryRecordsArgs = @('buildx', 'history', 'rm', '--all')
            $reclaimedTotal += Invoke-DockerPrune -Arguments $buildHistoryRecordsArgs -Description "docker $($buildHistoryRecordsArgs -join ' ')"

            $buildHistoryArgs = @('buildx', 'prune', '--all', '--force')
            $reclaimedTotal += Invoke-DockerPrune -Arguments $buildHistoryArgs -Description "docker $($buildHistoryArgs -join ' ')"
        }
    }

    end
    {
        $stats.SpaceFreedBytes = $reclaimedTotal

        $isWhatIf = $WhatIfPreference -eq $true
        $estimateSucceeded = $stats.EstimatedReclaimableEstimateSucceeded -eq $true
        $estimatedDisplay = if ($isWhatIf)
        {
            if (-not $estimateSucceeded)
            {
                'Unable to estimate (unknown)'
            }
            elseif ($stats.EstimatedReclaimableBytes -gt 0)
            {
                Format-ByteSize $stats.EstimatedReclaimableBytes
            }
            else
            {
                '0 bytes (nothing unused detected)'
            }
        }
        else
        {
            'Not calculated (use -WhatIf to preview)'
        }

        $result = [PSCustomObject]@{
            ContainersPruned = $stats.ContainersPruned
            VolumesPruned = $stats.VolumesPruned
            BuildxBuildersPruned = $stats.BuildxBuildersPruned
            BuildHistoryPruned = $stats.BuildHistoryPruned
            ImageMode = $stats.ImageMode
            EstimatedReclaimable = $estimatedDisplay
            TotalSpaceFreed = Format-ByteSize $stats.SpaceFreedBytes
            Errors = $stats.Errors
        }

        Write-Host "`nDocker Cleanup Summary:" -ForegroundColor Cyan
        Write-Host "  Containers pruned : $($result.ContainersPruned)" -ForegroundColor White
        Write-Host "  Volumes pruned    : $($result.VolumesPruned)" -ForegroundColor White
        Write-Host "  Buildx builders   : $($result.BuildxBuildersPruned)" -ForegroundColor White
        Write-Host "  Build history     : $($result.BuildHistoryPruned)" -ForegroundColor White
        Write-Host "  Image mode        : $($result.ImageMode)" -ForegroundColor White

        if ($isWhatIf)
        {
            Write-Host "  Estimated reclaimable: $($result.EstimatedReclaimable)" -ForegroundColor Yellow
            Write-Host '  No changes made (WhatIf).' -ForegroundColor Yellow
        }

        Write-Host "  Space freed       : $($result.TotalSpaceFreed)" -ForegroundColor Green

        if ($result.Errors -gt 0)
        {
            Write-Host "  Errors            : $($result.Errors)" -ForegroundColor Red
        }

        Write-Verbose 'Docker cleanup completed'
        return $result
    }
}

# Create 'docker-prune' alias only if it doesn't already exist
if (-not (Get-Command -Name 'docker-prune' -ErrorAction SilentlyContinue))
{
    try
    {
        Write-Verbose "Creating 'docker-prune' alias for Remove-DockerArtifact"
        Set-Alias -Name 'docker-prune' -Value 'Remove-DockerArtifact' -Force -ErrorAction Stop
    }
    catch
    {
        Write-Warning "Remove-DockerArtifact: Could not create 'docker-prune' alias: $($_.Exception.Message)"
    }
}