ROMFASTSQL/proxmox/lxc108-oracle/roa-windows-setup/scripts/lib/logging-functions.ps1

#Requires -Version 5.1

<#
.SYNOPSIS
    Logging utility functions for ROA Oracle setup scripts.

.DESCRIPTION
    Provides standardized logging functions with timestamps, colors, and file output.
    All log messages are written to both console and optional log file.

.NOTES
    File Name      : logging-functions.ps1
    Prerequisite   : PowerShell 5.1 or higher
    Copyright 2024 : ROMFAST
#>

# Script-level variables for logging
$script:LogFile = $null
$script:LogLevel = 'Info'

<#
.SYNOPSIS
    Initialize the log file with a header.

.DESCRIPTION
    Creates or clears a log file and writes a header with timestamp and script info.

.PARAMETER LogPath
    Path to the log file.

.PARAMETER ScriptName
    Name of the calling script for the header.

.EXAMPLE
    Initialize-LogFile -LogPath "C:\logs\setup.log" -ScriptName "01-setup-database.ps1"
#>
function Initialize-LogFile {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$LogPath,

        [Parameter(Mandatory = $false)]
        [string]$ScriptName = "ROA Setup"
    )

    $script:LogFile = $LogPath

    # Create directory if it doesn't exist
    $logDir = Split-Path -Path $LogPath -Parent
    if ($logDir -and -not (Test-Path -Path $logDir)) {
        New-Item -ItemType Directory -Path $logDir -Force | Out-Null
    }

    # Write header
    $header = @"
================================================================================
  ROA Oracle Setup Log
  Script: $ScriptName
  Started: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')
  Computer: $env:COMPUTERNAME
  User: $env:USERNAME
================================================================================

"@

    Set-Content -Path $LogPath -Value $header -Encoding UTF8
}

<#
.SYNOPSIS
    Write a log message with timestamp.

.DESCRIPTION
    Writes a timestamped message to console and log file. Supports different
    message types (Info, Warning, Error, Success, Debug).

.PARAMETER Message
    The message to log.

.PARAMETER Level
    The log level: Info, Warning, Error, Success, Debug.

.PARAMETER NoConsole
    If specified, only writes to log file.

.EXAMPLE
    Write-Log "Starting database setup" -Level Info
#>
function Write-Log {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$Message,

        [Parameter(Mandatory = $false)]
        [ValidateSet('Info', 'Warning', 'Error', 'Success', 'Debug')]
        [string]$Level = 'Info',

        [Parameter(Mandatory = $false)]
        [switch]$NoConsole
    )

    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
    $logMessage = "[$timestamp] [$Level] $Message"

    # Write to log file if initialized
    if ($script:LogFile) {
        Add-Content -Path $script:LogFile -Value $logMessage -Encoding UTF8
    }

    # Write to console with appropriate color
    if (-not $NoConsole) {
        $color = switch ($Level) {
            'Info'    { 'White' }
            'Warning' { 'Yellow' }
            'Error'   { 'Red' }
            'Success' { 'Green' }
            'Debug'   { 'Cyan' }
            default   { 'White' }
        }

        $prefix = switch ($Level) {
            'Info'    { '[INFO]   ' }
            'Warning' { '[WARN]   ' }
            'Error'   { '[ERROR]  ' }
            'Success' { '[OK]     ' }
            'Debug'   { '[DEBUG]  ' }
            default   { '[INFO]   ' }
        }

        Write-Host "$prefix$Message" -ForegroundColor $color
    }
}

<#
.SYNOPSIS
    Write an error message in red.

.DESCRIPTION
    Convenience function for logging error messages.

.PARAMETER Message
    The error message to log.

.EXAMPLE
    Write-LogError "Failed to connect to database"
#>
function Write-LogError {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$Message
    )

    Write-Log -Message $Message -Level Error
}

<#
.SYNOPSIS
    Write a success message in green.

.DESCRIPTION
    Convenience function for logging success messages.

.PARAMETER Message
    The success message to log.

.EXAMPLE
    Write-LogSuccess "Database created successfully"
#>
function Write-LogSuccess {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$Message
    )

    Write-Log -Message $Message -Level Success
}

<#
.SYNOPSIS
    Write a warning message in yellow.

.DESCRIPTION
    Convenience function for logging warning messages.

.PARAMETER Message
    The warning message to log.

.EXAMPLE
    Write-LogWarning "User already exists, skipping creation"
#>
function Write-LogWarning {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$Message
    )

    Write-Log -Message $Message -Level Warning
}

<#
.SYNOPSIS
    Write a debug message in cyan.

.DESCRIPTION
    Convenience function for logging debug messages.

.PARAMETER Message
    The debug message to log.

.EXAMPLE
    Write-LogDebug "SQL command: SELECT * FROM dual"
#>
function Write-LogDebug {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$Message
    )

    Write-Log -Message $Message -Level Debug
}

<#
.SYNOPSIS
    Write a section header to the log.

.DESCRIPTION
    Writes a formatted section header for visual separation in logs.

.PARAMETER Title
    The section title.

.EXAMPLE
    Write-LogSection "Creating Tablespace ROA"
#>
function Write-LogSection {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$Title
    )

    $separator = "=" * 60
    $message = @"

$separator
  $Title
$separator
"@

    if ($script:LogFile) {
        Add-Content -Path $script:LogFile -Value $message -Encoding UTF8
    }

    Write-Host ""
    Write-Host $separator -ForegroundColor Cyan
    Write-Host "  $Title" -ForegroundColor Cyan
    Write-Host $separator -ForegroundColor Cyan
}

<#
.SYNOPSIS
    Close the log file with a footer.

.DESCRIPTION
    Writes a closing footer to the log file with completion status.

.PARAMETER Success
    Indicates if the script completed successfully.

.EXAMPLE
    Close-LogFile -Success $true
#>
function Close-LogFile {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $false)]
        [bool]$Success = $true
    )

    if ($script:LogFile) {
        $status = if ($Success) { "COMPLETED SUCCESSFULLY" } else { "COMPLETED WITH ERRORS" }
        $footer = @"

================================================================================
  $status
  Finished: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')
================================================================================
"@
        Add-Content -Path $script:LogFile -Value $footer -Encoding UTF8
    }
}

# Note: Functions are available when dot-sourced (. .\logging-functions.ps1)
# Do NOT use Export-ModuleMember - it only works inside .psm1 modules