#Requires -Version 7.4

function Test-vSEALTaskExists {
    <#
    .SYNOPSIS
        Tests if a scheduled task exists.

    .DESCRIPTION
        Checks whether a Windows scheduled task with the specified path/name exists on the system.
        Uses Get-ScheduledTask with error handling to determine existence.
        Supports wildcard characters (* and ?) for matching tasks with dynamic names
        (e.g., tasks with GUID or SID suffixes).
        Returns $false on any error (never throws).

    .PARAMETER Name
        The full task path including task name.
        Example: 'Microsoft\Windows\Defrag\ScheduledDefrag'
        Can include or omit leading backslash.
        Supports wildcard characters (* and ?) for matching dynamic task names.

    .OUTPUTS
        [bool] $true if the task exists, $false otherwise.

    .EXAMPLE
        Test-vSEALTaskExists -Name 'Microsoft\Windows\Defrag\ScheduledDefrag'
        Returns $true if the scheduled defrag task exists.

    .EXAMPLE
        Test-vSEALTaskExists -Name 'NonExistentTask'
        Returns $false if the task does not exist.

    .EXAMPLE
        if (Test-vSEALTaskExists -Name 'Microsoft\Windows\Maintenance\WinSAT') {
            Write-Host 'WinSAT maintenance task exists'
        }
        Conditional check for task existence.

    .EXAMPLE
        Test-vSEALTaskExists -Name 'Microsoft\Windows\UpdateOrchestrator\*'
        Returns $true if any task exists in the UpdateOrchestrator folder.
        Useful for checking tasks with dynamic GUID/SID suffixes.
    #>
    [CmdletBinding()]
    [OutputType([bool])]
    param(
        [Parameter(Mandatory, Position = 0)]
        [ValidateNotNullOrEmpty()]
        [SupportsWildcards()]
        [string]$Name
    )

    Write-vSEALLog -Message "Testing if task [$Name] exists..." -Level 'VERBOSE'

    # Normalize input: remove leading backslash if present
    $normalizedName = $Name.TrimStart('\')

    # Parse task path and name
    # For 'Microsoft\Windows\Defrag\ScheduledDefrag'
    # TaskName = 'ScheduledDefrag'
    # TaskPath = '\Microsoft\Windows\Defrag\'
    $parts = $normalizedName -split '\\'
    $taskName = $parts[-1]
    if ($parts.Length -gt 1) {
        $taskPath = '\' + ($parts[0..($parts.Length - 2)] -join '\') + '\'
    }
    else {
        $taskPath = '\'
    }

    Write-vSEALLog -Message "Parsed task: TaskPath='$taskPath', TaskName='$taskName'" -Level 'VERBOSE'

    try {
        $task = Get-ScheduledTask -TaskPath $taskPath -TaskName $taskName -ErrorAction Stop
        if ($task) {
            Write-vSEALLog -Message "Task [$Name] exists." -Level 'VERBOSE'
            return $true
        }
        else {
            Write-vSEALLog -Message "Task [$Name] does not exist." -Level 'VERBOSE'
            return $false
        }
    }
    catch [Microsoft.PowerShell.Cmdletization.Cim.CimJobException] {
        # Task not found - this is the expected exception type
        Write-vSEALLog -Message "Task [$Name] does not exist (CimJobException)." -Level 'VERBOSE'
        return $false
    }
    catch {
        # Other error - still return false, don't throw
        Write-vSEALLog -Message "Task [$Name] check failed: $($_.Exception.Message)" -Level 'VERBOSE'
        return $false
    }
}
