OrionUtils.psm1

<#
================================================================================
ORION UTILS - POWERSHELL UTILITY FUNCTIONS
================================================================================

Author:        Sune Alexandersen Narud
Date:          February 9, 2026
Version:       1.6.0

HIGH LEVEL DESIGN (HLD):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PURPOSE:
OrionUtils is a collection of PowerShell utility functions for file management,
time/date operations, logging, and common administrative tasks. It provides 
reliable, tested functions for everyday automation needs.

ARCHITECTURE:
┌─────────────────────────────────────────────────────────────────────────────┐
│ FILE MANAGEMENT                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│ Remove-StaleFile          Keep N newest files, delete the rest             │
│ Test-FileLock             Check if a file is locked by another process     │
├─────────────────────────────────────────────────────────────────────────────┤
│ TIME & DATE                                                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│ Format-TimeSpan           Format TimeSpan to human-readable string         │
│ Get-TimeElapsed           Calculate time since a given date                │
├─────────────────────────────────────────────────────────────────────────────┤
│ STOPWATCH / PERFORMANCE TIMING                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│ Start-Stopwatch           Start a named stopwatch for timing               │
│ Stop-Stopwatch            Stop stopwatch and record elapsed time           │
│ Get-Stopwatch             Get running or completed stopwatch data          │
│ Reset-Stopwatch           Clear stopwatch data                             │
│ Show-StopwatchSummary     Display formatted performance summary            │
├─────────────────────────────────────────────────────────────────────────────┤
│ USER INTERACTION                                                            │
├─────────────────────────────────────────────────────────────────────────────┤
│ Wait-ForInput             Wait for key press, or timed wait with -Timer    │
├─────────────────────────────────────────────────────────────────────────────┤
│ LOGGING & METRICS                                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│ Write-Log                 Structured logging to file                       │
│ Export-MetricsToCSV       Export PSObject metrics to CSV with timestamps   │
├─────────────────────────────────────────────────────────────────────────────┤
│ SYSTEM UTILITIES                                                            │
├─────────────────────────────────────────────────────────────────────────────┤
│ Get-WindowsVersion        Convert OS version to friendly name              │
├─────────────────────────────────────────────────────────────────────────────┤
│ DEMO                                                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ Show-OrionUtilsDemo       Interactive demo of all module functions         │
├─────────────────────────────────────────────────────────────────────────────┤
│ PRIVATE FUNCTIONS                                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│ Remove-FileWithLockCheck  Internal helper for safe file deletion           │
└─────────────────────────────────────────────────────────────────────────────┘

CORE FEATURES:
• 📁 File management utilities with lock detection
• ⏱️ Time/date formatting and elapsed time calculations
• 🔒 Safe file operations with error handling
• 📝 Structured logging with multiple levels
• 📊 Metrics export to CSV with dynamic headers
• ⚡ WhatIf/Confirm support for safe testing
• 🎨 Optional integration with OrionDesign for beautiful output
• 📚 Complete Comment-Based Help documentation

DEPENDENCIES:
• PowerShell 5.1 or later
• OrionDesign module (optional, for enhanced output formatting)

USAGE PATTERNS:
Import-Module OrionUtils

# File Management
Remove-StaleFile -Path "C:\Logs" -Filter "*.log" -Keep 10
Test-FileLock -FilePath "C:\Data\file.xlsx" -Silent

# Time Operations
Format-TimeSpan -TimeSpan $stopwatch.Elapsed
Get-TimeElapsed -DateTime $lastLogin -OutputFormat Days

# Stopwatch / Performance Timing
Start-Stopwatch -Name "Data Import"
# ... your code ...
Stop-Stopwatch -Name "Data Import" -ShowElapsed
Show-StopwatchSummary

# User Interaction
Wait-ForInput -Message "Press any key to continue..."
Wait-ForInput -Timer 10 -ShowCountdown  # Timed wait with countdown

# Logging
Write-Log -Message "Process completed" -Level INFO -LogFile "C:\Logs\app.log"
Export-MetricsToCSV -Metrics $stats -Path "C:\Data\metrics.csv"

# System
Get-WindowsVersion -OSVersion "10.0.22000"

================================================================================
#>

Write-Verbose "DEBUG: OrionUtils.psm1 loaded. PSScriptRoot = $PSScriptRoot"

$root = $PSScriptRoot

# --- Load Private functions (internal only) ---
$privatePath = Join-Path $root 'Functions\Private'
if (Test-Path $privatePath) {
    Get-ChildItem -Path $privatePath -Filter *.ps1 | ForEach-Object {
        Write-Verbose "Loading private function: $($_.BaseName)"
        . $_.FullName
    }
}

# --- Load Public functions (to be exported) ---
$publicPath = Join-Path $root 'Functions\Public'
$publicFunctions = @()
if (Test-Path $publicPath) {
    Get-ChildItem -Path $publicPath -Filter *.ps1 | ForEach-Object {
        Write-Verbose "Loading public function: $($_.BaseName)"
        . $_.FullName
        $publicFunctions += $_.BaseName
    }
}

# --- Export public functions and aliases ---
if ($publicFunctions.Count -gt 0) {
    Write-Verbose "Exporting functions: $($publicFunctions -join ', ')"
    Export-ModuleMember -Function $publicFunctions
}
else {
    Write-Warning "No public functions found to export from OrionUtils"
}