#Requires -Version 5.1
<#
.SYNOPSIS
    Shared helper functions for the Local CI/CD System scripts.

.DESCRIPTION
    Import this module at the top of any CI script that needs WinRM session
    options or vmrun wrappers:

        Import-Module (Join-Path $PSScriptRoot '_Common.psm1') -Force

    Exported functions:
      New-CISessionOption  — PSSessionOption for WinRM over self-signed TLS
      Resolve-VmrunPath    — Validates vmrun.exe path, throws if missing
      Invoke-Vmrun         — Uniform vmrun -T ws wrapper; returns ExitCode + Output
#>
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

function New-CISessionOption {
<#
.SYNOPSIS
    Returns a PSSessionOption for WinRM HTTPS with self-signed certificate.
.DESCRIPTION
    All CI build VMs use a self-signed TLS cert on WinRM port 5986.
    This option set skips CA, CN, and revocation checks — appropriate for
    an isolated lab network where PKI is not present.
.OUTPUTS
    [System.Management.Automation.Remoting.PSSessionOption]
#>
    [OutputType([System.Management.Automation.Remoting.PSSessionOption])]
    [CmdletBinding()]
    param()
    New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
}

function Resolve-VmrunPath {
<#
.SYNOPSIS
    Validates that vmrun.exe exists at the specified path and returns it.
.DESCRIPTION
    Throws a descriptive error if the file is not found, rather than letting
    a later & call fail with a less useful message.
.PARAMETER VmrunPath
    Full path to vmrun.exe.
    Default: C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe
.OUTPUTS
    [string] The validated VmrunPath.
#>
    [OutputType([string])]
    [CmdletBinding()]
    param(
        [string] $VmrunPath = 'C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe'
    )
    if (-not (Test-Path $VmrunPath -PathType Leaf)) {
        throw "vmrun.exe not found at: $VmrunPath`nInstall VMware Workstation Pro and update -VmrunPath."
    }
    return $VmrunPath
}

function Invoke-Vmrun {
<#
.SYNOPSIS
    Runs a vmrun -T ws <Operation> command and returns output and exit code.
.DESCRIPTION
    Uniform wrapper so all vmrun calls share the same -T ws flag and output
    capture pattern. Use -ThrowOnError for operations that must succeed
    (clone, start); omit it for best-effort operations (stop, getState).
.PARAMETER VmrunPath
    Full path to vmrun.exe.
.PARAMETER Operation
    vmrun sub-command: clone, start, stop, deleteVM, list, getState,
    listSnapshots, getGuestIPAddress, etc.
.PARAMETER Arguments
    Additional positional arguments after the operation name.
.PARAMETER ThrowOnError
    When set, throws if vmrun exits non-zero.
.OUTPUTS
    [pscustomobject] with:
      ExitCode [int]     — vmrun exit code
      Output   [string[]] — combined stdout/stderr lines
#>
    [OutputType([pscustomobject])]
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)] [string]   $VmrunPath,
        [Parameter(Mandatory)] [string]   $Operation,
        [string[]]                        $Arguments    = @(),
        [switch]                          $ThrowOnError
    )
    $cmdArgs = @('-T', 'ws', $Operation) + $Arguments
    $output  = & $VmrunPath @cmdArgs 2>&1
    $exit    = $LASTEXITCODE

    if ($ThrowOnError -and $exit -ne 0) {
        throw "vmrun $Operation failed (exit $exit): $($output -join '; ')"
    }

    return [pscustomobject]@{
        ExitCode = $exit
        Output   = $output
    }
}

Export-ModuleMember -Function New-CISessionOption, Resolve-VmrunPath, Invoke-Vmrun