#Requires -Version 7.4

function Convert-vSEALRegistryPath {
    <#
    .SYNOPSIS
        Converts registry key paths to PowerShell provider format.

    .DESCRIPTION
        Converts registry key paths (HKLM:, HKCU:, etc.) to the full
        Microsoft.PowerShell.Core\Registry:: provider format.

    .PARAMETER Key
        The registry key path to convert.

    .PARAMETER Wow6432Node
        Redirect to 32-bit registry view on 64-bit systems.

    .PARAMETER SID
        User SID to convert HKCU paths to HKEY_USERS\SID format.

    .OUTPUTS
        [string] The converted registry path.
    #>
    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Key,

        [switch]$Wow6432Node,

        [string]$SID
    )

    # Registry hive mappings (patterns consume the optional colon and optional backslash)
    # Supports both "HKLM:\Path" (PowerShell style) and "HKLM\Path" (short format)
    $hiveMappings = @{
        '^HKLM:?\\?'                = 'HKEY_LOCAL_MACHINE\'
        '^HKCU:?\\?'                = 'HKEY_CURRENT_USER\'
        '^HKU:?\\?'                 = 'HKEY_USERS\'
        '^HKCR:?\\?'                = 'HKEY_CLASSES_ROOT\'
        '^HKCC:?\\?'                = 'HKEY_CURRENT_CONFIG\'
        '^HKEY_LOCAL_MACHINE\\?'    = 'HKEY_LOCAL_MACHINE\'
        '^HKEY_CURRENT_USER\\?'     = 'HKEY_CURRENT_USER\'
        '^HKEY_USERS\\?'            = 'HKEY_USERS\'
        '^HKEY_CLASSES_ROOT\\?'     = 'HKEY_CLASSES_ROOT\'
        '^HKEY_CURRENT_CONFIG\\?'   = 'HKEY_CURRENT_CONFIG\'
    }

    $convertedKey = $Key

    # Convert short hive names to full names
    foreach ($pattern in $hiveMappings.Keys) {
        if ($convertedKey -match $pattern) {
            $replacement = $hiveMappings[$pattern]
            $convertedKey = $convertedKey -replace $pattern, $replacement
            break
        }
    }

    # Strip any existing provider prefix
    $convertedKey = $convertedKey -replace '^Microsoft\.PowerShell\.Core\\Registry::', ''
    $convertedKey = $convertedKey -replace '^Registry::', ''

    # Handle WOW6432Node redirection on 64-bit systems
    if ($Wow6432Node -and [Environment]::Is64BitProcess) {
        $wow64Patterns = @{
            '^(HKEY_LOCAL_MACHINE\\SOFTWARE)\\(.+)$' = '$1\WOW6432Node\$2'
            '^(HKEY_CURRENT_USER\\SOFTWARE)\\(.+)$'  = '$1\WOW6432Node\$2'
        }
        foreach ($pattern in $wow64Patterns.Keys) {
            if ($convertedKey -match $pattern) {
                $convertedKey = $convertedKey -replace $pattern, $wow64Patterns[$pattern]
                break
            }
        }
    }

    # Handle SID conversion for HKCU
    if ($SID) {
        if ($convertedKey -notmatch '^HKEY_CURRENT_USER\\') {
            throw [System.InvalidOperationException]::new(
                "SID parameter specified but the registry hive is not HKEY_CURRENT_USER."
            )
        }
        $convertedKey = $convertedKey -replace '^HKEY_CURRENT_USER\\', "HKEY_USERS\$SID\"
    }

    # Normalize any double backslashes that might have occurred
    $convertedKey = $convertedKey -replace '\\\\', '\'

    # Validate the resulting hive
    $validHives = @(
        'HKEY_LOCAL_MACHINE',
        'HKEY_CURRENT_USER',
        'HKEY_USERS',
        'HKEY_CLASSES_ROOT',
        'HKEY_CURRENT_CONFIG'
    )
    $matchedHive = $validHives | Where-Object { $convertedKey.StartsWith("$_\") -or $convertedKey -eq $_ }
    if (-not $matchedHive) {
        throw [System.ArgumentException]::new(
            "Unable to detect valid registry hive in path: $Key"
        )
    }

    # Add the PowerShell provider prefix
    return "Microsoft.PowerShell.Core\Registry::$convertedKey"
}
