@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/coding-standards/powershell/examples/admin-example.ps1

@@ -0,0 +1,272 @@
+<#
+.SYNOPSIS
+    Administrative tools example demonstrating AD/Exchange management with efficient filtering.
+
+.DESCRIPTION
+    Complete example showing:
+    - Active Directory user management with server-side filtering
+    - Bulk operations with error handling
+    - Audit logging and reporting
+    - Exchange mailbox management
+    - Progress reporting for long-running operations
+
+.PARAMETER Action
+    Action to perform (AuditInactiveUsers, DisableInactiveUsers, ExportMailboxSizes)
+
+.PARAMETER DaysInactive
+    Number of days to consider a user inactive
+
+.PARAMETER OutputPath
+    Path for output reports
+
+.EXAMPLE
+    .\admin-example.ps1 -Action AuditInactiveUsers -DaysInactive 90 -OutputPath C:\Reports
+#>
+
+#Requires -Version 7.4
+#Requires -Modules ActiveDirectory
+
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)]
+    [ValidateSet('AuditInactiveUsers', 'DisableInactiveUsers', 'ExportMailboxSizes')]
+    [string]$Action,
+    
+    [Parameter()]
+    [ValidateRange(1, 365)]
+    [int]$DaysInactive = 90,
+    
+    [Parameter()]
+    [ValidateScript({ Test-Path $_ -PathType Container })]
+    [string]$OutputPath = $PWD
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+#region Helper Functions
+
+function Write-AuditLog
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Message,
+        
+        [Parameter()]
+        [ValidateSet('Info', 'Warning', 'Error')]
+        [string]$Level = 'Info',
+        
+        [Parameter()]
+        [string]$LogPath = (Join-Path $OutputPath "audit-$(Get-Date -Format 'yyyy-MM-dd').log")
+    )
+    
+    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
+    $logEntry = "[$timestamp] [$Level] $Message"
+    
+    Add-Content -Path $LogPath -Value $logEntry
+    
+    switch ($Level)
+    {
+        'Info'    { Write-Verbose $Message }
+        'Warning' { Write-Warning $Message }
+        'Error'   { Write-Error $Message }
+    }
+}
+
+#endregion
+
+#region Active Directory Functions
+
+function Get-InactiveADUsers
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [int]$DaysInactive
+    )
+    
+    Write-AuditLog "Searching for users inactive for $DaysInactive days"
+    
+    $cutoffDate = (Get-Date).AddDays(-$DaysInactive)
+    
+    # ✅ GOOD: Server-side filtering with -Filter parameter
+    $filterParams = @{
+        Filter = "LastLogonDate -lt '$cutoffDate' -and Enabled -eq 'True'"
+        Properties = @(
+            'LastLogonDate'
+            'EmailAddress'
+            'Department'
+            'Manager'
+            'Created'
+        )
+        ErrorAction = 'Stop'
+    }
+    
+    try
+    {
+        $users = Get-ADUser @filterParams
+        Write-AuditLog "Found $($users.Count) inactive users"
+        
+        return $users | Select-Object `
+            Name,
+            SamAccountName,
+            EmailAddress,
+            Department,
+            LastLogonDate,
+            @{Name='DaysInactive'; Expression={ ((Get-Date) - $_.LastLogonDate).Days }},
+            Created
+    }
+    catch
+    {
+        Write-AuditLog "Failed to query AD users: $_" -Level Error
+        throw
+    }
+}
+
+function Disable-InactiveADUsersBulk
+{
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline)]
+        [Microsoft.ActiveDirectory.Management.ADUser[]]$Users
+    )
+    
+    begin
+    {
+        $successCount = 0
+        $failureCount = 0
+        $errors = [System.Collections.Generic.List[PSObject]]::new()
+        $totalUsers = @($Users).Count
+        $currentUser = 0
+    }
+    
+    process
+    {
+        foreach ($user in $Users)
+        {
+            $currentUser++
+            $percentComplete = ($currentUser / $totalUsers) * 100
+            
+            Write-Progress -Activity "Disabling Inactive Users" `
+                -Status "Processing $($user.SamAccountName)" `
+                -PercentComplete $percentComplete `
+                -CurrentOperation "$currentUser of $totalUsers"
+            
+            if ($PSCmdlet.ShouldProcess($user.SamAccountName, 'Disable AD User'))
+            {
+                try
+                {
+                    # Disable user and add description
+                    $description = "Disabled on $(Get-Date -Format 'yyyy-MM-dd') - Inactive for $DaysInactive days"
+
+                    Set-ADUser -Identity $user.SamAccountName `
+                        -Enabled $false `
+                        -Description $description `
+                        -ErrorAction Stop
+
+                    $successCount++
+                    Write-AuditLog "Disabled user: $($user.SamAccountName)"
+                }
+                catch
+                {
+                    $failureCount++
+                    $errorObj = [PSCustomObject]@{
+                        User = $user.SamAccountName
+                        Error = $_.Exception.Message
+                        Timestamp = Get-Date
+                    }
+                    $errors.Add($errorObj)
+                    Write-AuditLog "Failed to disable $($user.SamAccountName): $_" -Level Warning
+                }
+            }
+        }
+    }
+
+    end
+    {
+        Write-Progress -Activity "Disabling Inactive Users" -Completed
+
+        $summary = "Bulk disable complete: $successCount succeeded, $failureCount failed"
+        Write-AuditLog $summary
+        Write-Host "`n$summary" -ForegroundColor $(if ($failureCount -eq 0) { 'Green' } else { 'Yellow' })
+
+        if ($errors.Count -gt 0)
+        {
+            $errorReport = Join-Path $OutputPath "disable-errors-$(Get-Date -Format 'yyyy-MM-dd-HHmmss').csv"
+            $errors | Export-Csv -Path $errorReport -NoTypeInformation
+            Write-Host "Error report saved to: $errorReport" -ForegroundColor Yellow
+        }
+    }
+}
+
+#endregion
+
+#region Main Execution
+
+try
+{
+    Write-Host "Starting administrative action: $Action" -ForegroundColor Cyan
+    Write-AuditLog "Starting action: $Action with parameters: DaysInactive=$DaysInactive"
+
+    switch ($Action)
+    {
+        'AuditInactiveUsers'
+        {
+            $inactiveUsers = Get-InactiveADUsers -DaysInactive $DaysInactive
+
+            if ($inactiveUsers.Count -gt 0)
+            {
+                $reportPath = Join-Path $OutputPath "inactive-users-$(Get-Date -Format 'yyyy-MM-dd-HHmmss').csv"
+                $inactiveUsers | Export-Csv -Path $reportPath -NoTypeInformation
+
+                Write-Host "`n✓ Found $($inactiveUsers.Count) inactive users" -ForegroundColor Green
+                Write-Host "Report saved to: $reportPath" -ForegroundColor Cyan
+
+                # Display summary
+                $inactiveUsers | Group-Object Department |
+                    Select-Object Name, Count |
+                    Sort-Object Count -Descending |
+                    Format-Table -AutoSize
+            }
+            else
+            {
+                Write-Host "`n✓ No inactive users found" -ForegroundColor Green
+            }
+        }
+
+        'DisableInactiveUsers'
+        {
+            $inactiveUsers = Get-InactiveADUsers -DaysInactive $DaysInactive
+
+            if ($inactiveUsers.Count -gt 0)
+            {
+                Write-Host "`nFound $($inactiveUsers.Count) inactive users to disable" -ForegroundColor Yellow
+                $inactiveUsers | Disable-InactiveADUsersBulk -WhatIf:$WhatIfPreference
+            }
+            else
+            {
+                Write-Host "`n✓ No inactive users to disable" -ForegroundColor Green
+            }
+        }
+
+        'ExportMailboxSizes'
+        {
+            Write-Host "`nExporting mailbox sizes..." -ForegroundColor Cyan
+            Write-AuditLog "Mailbox size export not implemented in this example"
+            Write-Host "✓ This action would export mailbox sizes (not implemented)" -ForegroundColor Yellow
+        }
+    }
+
+    Write-AuditLog "Action completed successfully: $Action"
+    Write-Host "`n✓ Administrative action completed successfully" -ForegroundColor Green
+}
+catch
+{
+    Write-AuditLog "Action failed: $_" -Level Error
+    Write-Host "`n✗ Administrative action failed: $_" -ForegroundColor Red
+    exit 1
+}
+
+#endregion
+

package/augment-extensions/coding-standards/powershell/examples/automation-example.ps1

@@ -0,0 +1,173 @@
+<#
+.SYNOPSIS
+    Automated system maintenance script with comprehensive error handling and logging.
+
+.DESCRIPTION
+    This script demonstrates PowerShell automation best practices including:
+    - Comment-based help
+    - Parameter validation
+    - Error handling with try/catch
+    - Logging and auditing
+    - Progress reporting
+    - Cleanup operations
+
+.PARAMETER ComputerName
+    Target computer(s) for maintenance operations.
+
+.PARAMETER LogPath
+    Path to log file. Defaults to script directory.
+
+.PARAMETER SkipDiskCleanup
+    Skip disk cleanup operations.
+
+.PARAMETER WhatIf
+    Show what would happen without making changes.
+
+.EXAMPLE
+    .\automation-example.ps1 -ComputerName 'SERVER01'
+    Run maintenance on SERVER01 with default settings.
+
+.EXAMPLE
+    .\automation-example.ps1 -ComputerName 'SERVER01','SERVER02' -SkipDiskCleanup -WhatIf
+    Preview maintenance on multiple servers without disk cleanup.
+
+.NOTES
+    Author: PowerShell Standards Team
+    Version: 1.0.0
+    Requires: PowerShell 7.4+
+#>
+
+#Requires -Version 7.4
+#Requires -RunAsAdministrator
+
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory, ValueFromPipeline)]
+    [ValidateNotNullOrEmpty()]
+    [string[]]$ComputerName,
+    
+    [Parameter()]
+    [ValidateScript({ Test-Path (Split-Path $_) })]
+    [string]$LogPath = (Join-Path $PSScriptRoot 'maintenance.log'),
+    
+    [Parameter()]
+    [switch]$SkipDiskCleanup
+)
+
+begin
+{
+    # Initialize logging
+    function Write-Log
+    {
+        [CmdletBinding()]
+        param(
+            [Parameter(Mandatory)]
+            [ValidateSet('Info', 'Warning', 'Error', 'Success')]
+            [string]$Level,
+            
+            [Parameter(Mandatory)]
+            [string]$Message
+        )
+        
+        $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
+        $logEntry = "[$timestamp] [$Level] $Message"
+        
+        Add-Content -Path $LogPath -Value $logEntry
+        
+        switch ($Level)
+        {
+            'Info' { Write-Verbose $Message }
+            'Warning' { Write-Warning $Message }
+            'Error' { Write-Error $Message }
+            'Success' { Write-Output $Message }
+        }
+    }
+    
+    Write-Log -Level Info -Message "Starting maintenance script"
+    Write-Log -Level Info -Message "Target computers: $($ComputerName -join ', ')"
+    
+    $totalComputers = $ComputerName.Count
+    $currentComputer = 0
+}
+
+process
+{
+    foreach ($computer in $ComputerName)
+    {
+        $currentComputer++
+        $percentComplete = ($currentComputer / $totalComputers) * 100
+        
+        Write-Progress -Activity "System Maintenance" `
+                      -Status "Processing $computer" `
+                      -PercentComplete $percentComplete `
+                      -CurrentOperation "Computer $currentComputer of $totalComputers"
+        
+        try
+        {
+            # Test connectivity
+            Write-Log -Level Info -Message "Testing connectivity to $computer"
+            
+            if (-not (Test-Connection -ComputerName $computer -Count 1 -Quiet))
+            {
+                throw "Computer $computer is not reachable"
+            }
+            
+            # Get system information
+            Write-Log -Level Info -Message "Gathering system information from $computer"
+            
+            $session = New-CimSession -ComputerName $computer -ErrorAction Stop
+            
+            try
+            {
+                $os = Get-CimInstance -CimSession $session -ClassName Win32_OperatingSystem
+                $disk = Get-CimInstance -CimSession $session -ClassName Win32_LogicalDisk -Filter "DeviceID='C:'"
+                
+                Write-Log -Level Info -Message "$computer - OS: $($os.Caption), Free Space: $([math]::Round($disk.FreeSpace / 1GB, 2)) GB"
+                
+                # Check disk space
+                $freeSpacePercent = ($disk.FreeSpace / $disk.Size) * 100
+                
+                if ($freeSpacePercent -lt 10)
+                {
+                    Write-Log -Level Warning -Message "$computer - Low disk space: $([math]::Round($freeSpacePercent, 2))%"
+                    
+                    if (-not $SkipDiskCleanup)
+                    {
+                        if ($PSCmdlet.ShouldProcess($computer, "Clean temporary files"))
+                        {
+                            Write-Log -Level Info -Message "$computer - Starting disk cleanup"
+                            # Disk cleanup logic here
+                            Write-Log -Level Success -Message "$computer - Disk cleanup completed"
+                        }
+                    }
+                }
+                
+                # Check for pending updates
+                Write-Log -Level Info -Message "$computer - Checking for pending updates"
+                
+                # Update check logic here
+                
+                Write-Log -Level Success -Message "$computer - Maintenance completed successfully"
+            }
+            finally
+            {
+                Remove-CimSession -CimSession $session
+            }
+        }
+        catch
+        {
+            Write-Log -Level Error -Message "$computer - Maintenance failed: $($_.Exception.Message)"
+            
+            # Continue processing other computers
+            continue
+        }
+    }
+}
+
+end
+{
+    Write-Progress -Activity "System Maintenance" -Completed
+    Write-Log -Level Info -Message "Maintenance script completed"
+    Write-Output "Log file: $LogPath"
+}
+

package/augment-extensions/coding-standards/powershell/examples/cloud-example.ps1

@@ -0,0 +1,243 @@
+<#
+.SYNOPSIS
+    Azure/AWS cloud orchestration example demonstrating authentication and resource management.
+
+.DESCRIPTION
+    Complete example showing:
+    - Azure authentication (Managed Identity, Service Principal)
+    - AWS authentication (IAM roles, profiles)
+    - Resource provisioning and management
+    - Error handling and logging
+    - Idempotent operations
+
+.PARAMETER Environment
+    Target environment (Dev, Test, Prod)
+
+.PARAMETER CloudProvider
+    Cloud provider to use (Azure, AWS)
+
+.EXAMPLE
+    .\cloud-example.ps1 -Environment Dev -CloudProvider Azure
+#>
+
+#Requires -Version 7.4
+#Requires -Modules Az.Accounts, Az.Resources
+
+[CmdletBinding(SupportsShouldProcess)]
+param(
+    [Parameter(Mandatory)]
+    [ValidateSet('Dev', 'Test', 'Prod')]
+    [string]$Environment,
+    
+    [Parameter(Mandatory)]
+    [ValidateSet('Azure', 'AWS')]
+    [string]$CloudProvider
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+#region Azure Functions
+
+function Connect-AzureEnvironment
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$TenantId,
+        
+        [Parameter()]
+        [switch]$UseManagedIdentity
+    )
+    
+    try
+    {
+        if ($UseManagedIdentity)
+        {
+            Write-Verbose "Connecting to Azure using Managed Identity"
+            Connect-AzAccount -Identity -ErrorAction Stop
+        }
+        else
+        {
+            Write-Verbose "Connecting to Azure using Service Principal"
+            # In production, retrieve from Key Vault or secure storage
+            $credential = Get-Credential -Message "Enter Service Principal credentials"
+            $appId = Read-Host "Enter Application ID"
+            
+            Connect-AzAccount -ServicePrincipal -TenantId $TenantId `
+                -Credential $credential -ApplicationId $appId -ErrorAction Stop
+        }
+        
+        Write-Host "✓ Connected to Azure" -ForegroundColor Green
+    }
+    catch
+    {
+        Write-Error "Failed to connect to Azure: $_"
+        throw
+    }
+}
+
+function New-AzureResourceDeployment
+{
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ResourceGroupName,
+        
+        [Parameter(Mandatory)]
+        [string]$Location,
+        
+        [Parameter()]
+        [hashtable]$Tags = @{}
+    )
+    
+    if ($PSCmdlet.ShouldProcess($ResourceGroupName, 'Create/Update Resource Group'))
+    {
+        try
+        {
+            # Idempotent: Check if resource group exists
+            $rg = Get-AzResourceGroup -Name $ResourceGroupName -ErrorAction SilentlyContinue
+            
+            if ($null -eq $rg)
+            {
+                Write-Verbose "Creating new resource group: $ResourceGroupName"
+                $rg = New-AzResourceGroup -Name $ResourceGroupName -Location $Location -Tag $Tags
+                Write-Host "✓ Created resource group: $ResourceGroupName" -ForegroundColor Green
+            }
+            else
+            {
+                Write-Verbose "Resource group already exists: $ResourceGroupName"
+                # Update tags if different
+                if ($Tags.Count -gt 0)
+                {
+                    Set-AzResourceGroup -Name $ResourceGroupName -Tag $Tags | Out-Null
+                    Write-Host "✓ Updated resource group tags" -ForegroundColor Green
+                }
+            }
+            
+            return $rg
+        }
+        catch
+        {
+            Write-Error "Failed to create/update resource group: $_"
+            throw
+        }
+    }
+}
+
+#endregion
+
+#region AWS Functions
+
+function Connect-AWSEnvironment
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ProfileName,
+        
+        [Parameter(Mandatory)]
+        [string]$Region
+    )
+    
+    try
+    {
+        # Set AWS credentials from profile
+        Set-AWSCredential -ProfileName $ProfileName -ErrorAction Stop
+        Set-DefaultAWSRegion -Region $Region -ErrorAction Stop
+
+        Write-Host "✓ Connected to AWS (Profile: $ProfileName, Region: $Region)" -ForegroundColor Green
+    }
+    catch
+    {
+        Write-Error "Failed to connect to AWS: $_"
+        throw
+    }
+}
+
+#endregion
+
+#region Main Execution
+
+try
+{
+    Write-Host "Starting cloud orchestration for $CloudProvider ($Environment environment)" -ForegroundColor Cyan
+
+    # Environment-specific configuration
+    $config = @{
+        Dev = @{
+            Azure = @{
+                TenantId = '00000000-0000-0000-0000-000000000000'
+                Location = 'eastus'
+                ResourceGroupName = 'rg-dev-example'
+            }
+            AWS = @{
+                ProfileName = 'dev-profile'
+                Region = 'us-east-1'
+            }
+        }
+        Test = @{
+            Azure = @{
+                TenantId = '11111111-1111-1111-1111-111111111111'
+                Location = 'centralus'
+                ResourceGroupName = 'rg-test-example'
+            }
+            AWS = @{
+                ProfileName = 'test-profile'
+                Region = 'us-west-2'
+            }
+        }
+        Prod = @{
+            Azure = @{
+                TenantId = '22222222-2222-2222-2222-222222222222'
+                Location = 'westus'
+                ResourceGroupName = 'rg-prod-example'
+            }
+            AWS = @{
+                ProfileName = 'prod-profile'
+                Region = 'us-east-1'
+            }
+        }
+    }
+
+    $envConfig = $config[$Environment][$CloudProvider]
+
+    # Common tags
+    $tags = @{
+        Environment = $Environment
+        ManagedBy = 'PowerShell'
+        CreatedDate = (Get-Date -Format 'yyyy-MM-dd')
+    }
+
+    switch ($CloudProvider)
+    {
+        'Azure'
+        {
+            Connect-AzureEnvironment -TenantId $envConfig.TenantId -UseManagedIdentity:$false
+
+            $deployment = New-AzureResourceDeployment `
+                -ResourceGroupName $envConfig.ResourceGroupName `
+                -Location $envConfig.Location `
+                -Tags $tags `
+                -WhatIf:$WhatIfPreference
+
+            Write-Host "`n✓ Azure deployment completed successfully" -ForegroundColor Green
+        }
+
+        'AWS'
+        {
+            Connect-AWSEnvironment -ProfileName $envConfig.ProfileName -Region $envConfig.Region
+
+            # AWS resource creation would go here
+            Write-Host "`n✓ AWS deployment completed successfully" -ForegroundColor Green
+        }
+    }
+}
+catch
+{
+    Write-Error "Cloud orchestration failed: $_"
+    exit 1
+}
+
+#endregion
+