#Requires -Version 7.4

function Get-vSEALPlugin {
    <#
    .SYNOPSIS
        Returns plugin metadata for CLI discovery and documentation.

    .DESCRIPTION
        Queries the plugin registry and returns metadata for all available
        plugins including name, version, status, category, and supported phases.

        This is the public API for CLI tools and administrators to discover
        available vSEAL plugins and their configuration options.

    .PARAMETER Name
        Filter plugins by name. Supports wildcards (*).
        Matching is case-insensitive.

    .PARAMETER Status
        Filter plugins by status. Valid values: Valid, Skipped, Error.
        Accepts multiple values: -Status Valid,Skipped

    .EXAMPLE
        Get-vSEALPlugin

        Returns all available plugins with their metadata.

    .EXAMPLE
        Get-vSEALPlugin -Name "defender"

        Returns metadata for the defender plugin.

    .EXAMPLE
        Get-vSEALPlugin -Name "*def*"

        Returns plugins with "def" in the name (case-insensitive).

    .EXAMPLE
        Get-vSEALPlugin -Status Valid

        Returns only plugins that are valid and applicable.

    .EXAMPLE
        Get-vSEALPlugin -Status Valid,Skipped

        Returns plugins that are either valid or skipped (excludes errors).

    .EXAMPLE
        Get-vSEALPlugin | ConvertTo-Json -Depth 5

        Returns all plugins as JSON for CLI consumption.

    .OUTPUTS
        [PSCustomObject[]] Array of plugin metadata objects with PSTypeName 'vSEAL.Plugin'.

        Each object contains:
        - Name: Plugin name from TOML (e.g., 'defender')
        - Version: Plugin version from TOML (e.g., '1.0.0')
        - Status: Discovery status ('Valid', 'Skipped', 'Error')
        - Source: Plugin origin ('local', 'shared', 'built-in')
        - Category: Plugin category from TOML (e.g., 'edr', 'system')
        - Phases: Array of supported phases (e.g., @('Seal', 'Engage'))
        - Priority: Execution priority (lower runs first)
        - PluginPath: Full path to plugin folder
        - SkipReason: Why plugin was skipped (when Status='Skipped')
        - ErrorMessage: Error details (when Status='Error')
    #>
    [CmdletBinding()]
    [OutputType([PSCustomObject[]])]
    param(
        [Parameter()]
        [string[]]$Name,

        [Parameter()]
        [ValidateSet('Valid', 'Skipped', 'Error')]
        [string[]]$Status
    )

    # Resolve plugin paths
    $builtInPluginPath = Join-Path -Path $PSScriptRoot -ChildPath '..\Plugins'
    $localPluginPath = Join-Path -Path $PSScriptRoot -ChildPath '..\plugins-custom'
    $sharedPluginPath = Join-Path -Path $env:ProgramData -ChildPath 'vSEAL\plugins'

    # Get all registered plugins from registry (local > shared > built-in)
    $registry = Get-vSEALPluginRegistry -BuiltInPath $builtInPluginPath -LocalPath $localPluginPath -SharedPath $sharedPluginPath

    # Transform registry entries to PSCustomObject array
    $plugins = @()

    foreach ($pluginName in $registry.Keys) {
        $entry = $registry[$pluginName]

        $plugins += [PSCustomObject]@{
            PSTypeName   = 'vSEAL.Plugin'
            Name         = $entry.Name
            Version      = $entry.Version
            Status       = $entry.Status
            Source       = $entry.Source
            Category     = $entry.Category
            Phases       = $entry.Phases
            Priority     = $entry.Priority
            PluginPath   = $entry.PluginPath
            SkipReason   = $entry.SkipReason
            ErrorMessage = $entry.ErrorMessage
        }
    }

    # Apply name filter if provided (case-insensitive wildcard match)
    if ($Name) {
        $plugins = @($plugins | Where-Object {
            foreach ($n in $Name) {
                if ($_.Name -like $n) { return $true }
            }
            return $false
        })
    }

    # Apply status filter if provided
    if ($Status) {
        $plugins = @($plugins | Where-Object { $_.Status -in $Status })
    }

    # Ensure we always return an array (use Write-Output with -NoEnumerate to prevent unwrapping)
    Write-Output -NoEnumerate $plugins
}
