@mytechtoday/augment-extensions 0.2.0 → 0.4.0

package/augment-extensions/coding-standards/powershell/rules/automation-scripts.md

@@ -0,0 +1,240 @@
+# PowerShell Automation Scripts
+
+Best practices for task automation, scheduled tasks, and output formatting.
+
+## Script Structure
+
+### Complete Automation Script Template
+
+```powershell
+#Requires -Version 7.4
+<#
+.SYNOPSIS
+    Brief description of what the script does
+
+.DESCRIPTION
+    Detailed description of the script's purpose and functionality
+
+.PARAMETER LogPath
+    Path to the log file
+
+.PARAMETER EmailRecipient
+    Email address for notifications
+
+.EXAMPLE
+    .\Backup-Database.ps1 -LogPath "C:\Logs\backup.log"
+
+.NOTES
+    Author: Your Name
+    Date: 2024-01-30
+    Version: 1.0
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)]
+    [ValidateScript({ Test-Path (Split-Path $_) })]
+    [string]$LogPath,
+    
+    [Parameter()]
+    [ValidatePattern('^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$')]
+    [string]$EmailRecipient
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Script logic here
+```
+
+## Logging
+
+### Structured Logging Function
+
+```powershell
+function Write-AutomationLog
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Message,
+        
+        [ValidateSet('Info', 'Warning', 'Error', 'Success')]
+        [string]$Level = 'Info',
+        
+        [string]$LogPath = "$PSScriptRoot\automation.log"
+    )
+    
+    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
+    $logEntry = "[$timestamp] [$Level] $Message"
+    
+    # Console output with color
+    switch ($Level)
+    {
+        'Info'    { Write-Host $logEntry -ForegroundColor Cyan }
+        'Warning' { Write-Warning $logEntry }
+        'Error'   { Write-Error $logEntry }
+        'Success' { Write-Host $logEntry -ForegroundColor Green }
+    }
+    
+    # File output
+    Add-Content -Path $LogPath -Value $logEntry
+}
+
+# Usage
+Write-AutomationLog -Message "Starting backup process" -Level Info
+Write-AutomationLog -Message "Backup completed successfully" -Level Success
+```
+
+## Error Handling for Automation
+
+### Robust Error Handling
+
+```powershell
+try
+{
+    Write-AutomationLog "Starting database backup"
+    
+    # Backup logic
+    Backup-SqlDatabase -ServerInstance "localhost" -Database "MyDB"
+    
+    Write-AutomationLog "Backup completed successfully" -Level Success
+}
+catch
+{
+    $errorMessage = "Backup failed: $($_.Exception.Message)"
+    Write-AutomationLog $errorMessage -Level Error
+    
+    # Send notification
+    Send-MailMessage -To $EmailRecipient -Subject "Backup Failed" -Body $errorMessage
+    
+    # Exit with error code
+    exit 1
+}
+finally
+{
+    Write-AutomationLog "Backup process finished"
+}
+```
+
+## Scheduled Task Integration
+
+### Create Scheduled Task
+
+```powershell
+# Register scheduled task
+$action = New-ScheduledTaskAction -Execute 'PowerShell.exe' `
+    -Argument '-NoProfile -ExecutionPolicy Bypass -File "C:\Scripts\Backup-Database.ps1"'
+
+$trigger = New-ScheduledTaskTrigger -Daily -At 2am
+
+$principal = New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest
+
+$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 5)
+
+Register-ScheduledTask -TaskName "Daily Database Backup" `
+    -Action $action `
+    -Trigger $trigger `
+    -Principal $principal `
+    -Settings $settings `
+    -Description "Automated daily database backup"
+```
+
+### Script for Scheduled Execution
+
+```powershell
+#Requires -Version 7.4
+#Requires -RunAsAdministrator
+
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Set up transcript logging
+$transcriptPath = "C:\Logs\Backup-$(Get-Date -Format 'yyyyMMdd-HHmmss').log"
+Start-Transcript -Path $transcriptPath
+
+try
+{
+    # Your automation logic
+    Write-Output "Starting automated task at $(Get-Date)"
+    
+    # Perform work
+    
+    Write-Output "Task completed successfully at $(Get-Date)"
+    exit 0
+}
+catch
+{
+    Write-Error "Task failed: $_"
+    exit 1
+}
+finally
+{
+    Stop-Transcript
+}
+```
+
+## Output Formatting
+
+### Structured Output
+
+```powershell
+# Return objects, not strings
+function Get-BackupStatus
+{
+    [CmdletBinding()]
+    param()
+    
+    [PSCustomObject]@{
+        Timestamp = Get-Date
+        Status = 'Success'
+        FilesBackedUp = 150
+        TotalSize = '2.5 GB'
+        Duration = '00:05:23'
+    }
+}
+
+# Usage
+$status = Get-BackupStatus
+$status | Format-Table
+$status | Export-Csv -Path "backup-status.csv" -NoTypeInformation
+$status | ConvertTo-Json | Out-File "backup-status.json"
+```
+
+### Progress Reporting
+
+```powershell
+$items = 1..100
+$totalItems = $items.Count
+
+foreach ($i in 0..($totalItems - 1))
+{
+    $percentComplete = ($i / $totalItems) * 100
+    
+    Write-Progress -Activity "Processing Items" `
+        -Status "Processing item $($i + 1) of $totalItems" `
+        -PercentComplete $percentComplete
+    
+    # Process item
+    Start-Sleep -Milliseconds 100
+}
+
+Write-Progress -Activity "Processing Items" -Completed
+```
+
+## Best Practices
+
+1. **Use comment-based help** - Document all parameters and examples
+2. **Enable strict mode** - Catch errors early
+3. **Implement logging** - Track execution and errors
+4. **Handle errors gracefully** - Use try/catch/finally
+5. **Return objects** - Not formatted strings
+6. **Use transcript logging** - For scheduled tasks
+7. **Set exit codes** - 0 for success, non-zero for failure
+8. **Validate parameters** - Use validation attributes
+9. **Send notifications** - Email or webhook on failure
+10. **Test thoroughly** - Before scheduling
+

package/augment-extensions/coding-standards/powershell/rules/cloud-orchestration.md

@@ -0,0 +1,384 @@
+# PowerShell Cloud Orchestration
+
+Best practices for Azure/AWS PowerShell, ARM/Bicep integration, and authentication patterns.
+
+## Azure PowerShell
+
+### Authentication
+
+```powershell
+#Requires -Version 7.4
+#Requires -Modules Az.Accounts, Az.Resources
+
+# ✅ GOOD: Use managed identity in Azure
+function Connect-AzureWithManagedIdentity
+{
+    [CmdletBinding()]
+    param()
+    
+    try
+    {
+        # Connect using managed identity
+        Connect-AzAccount -Identity -ErrorAction Stop
+        Write-Verbose "Connected to Azure using Managed Identity"
+    }
+    catch
+    {
+        Write-Error "Failed to connect with Managed Identity: $_"
+        throw
+    }
+}
+
+# ✅ GOOD: Use service principal for automation
+function Connect-AzureWithServicePrincipal
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$TenantId,
+        
+        [Parameter(Mandatory)]
+        [string]$ApplicationId,
+        
+        [Parameter(Mandatory)]
+        [PSCredential]$Credential
+    )
+    
+    $params = @{
+        ServicePrincipal = $true
+        TenantId = $TenantId
+        Credential = $Credential
+        ApplicationId = $ApplicationId
+    }
+    
+    Connect-AzAccount @params -ErrorAction Stop
+}
+
+# ❌ BAD: Interactive login in automation
+# Connect-AzAccount  # Don't use in scripts
+```
+
+### Resource Management
+
+```powershell
+function New-AzureResourceGroup
+{
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        [Parameter(Mandatory)]
+        [ValidatePattern('^[a-zA-Z0-9-_]+$')]
+        [string]$ResourceGroupName,
+        
+        [Parameter(Mandatory)]
+        [ValidateSet('eastus', 'westus', 'centralus', 'northeurope', 'westeurope')]
+        [string]$Location,
+        
+        [Parameter()]
+        [hashtable]$Tags = @{}
+    )
+    
+    if ($PSCmdlet.ShouldProcess($ResourceGroupName, 'Create Resource Group'))
+    {
+        try
+        {
+            $params = @{
+                Name = $ResourceGroupName
+                Location = $Location
+                Tag = $Tags
+                ErrorAction = 'Stop'
+            }
+            
+            $rg = New-AzResourceGroup @params
+            Write-Verbose "Created resource group: $($rg.ResourceGroupName)"
+            return $rg
+        }
+        catch
+        {
+            Write-Error "Failed to create resource group: $_"
+            throw
+        }
+    }
+}
+```
+
+### ARM Template Deployment
+
+```powershell
+function Deploy-AzureARMTemplate
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ResourceGroupName,
+        
+        [Parameter(Mandatory)]
+        [ValidateScript({ Test-Path $_ -PathType Leaf })]
+        [string]$TemplateFile,
+        
+        [Parameter()]
+        [ValidateScript({ Test-Path $_ -PathType Leaf })]
+        [string]$ParametersFile,
+        
+        [Parameter()]
+        [string]$DeploymentName = "deployment-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+    )
+    
+    try
+    {
+        $deployParams = @{
+            ResourceGroupName = $ResourceGroupName
+            TemplateFile = $TemplateFile
+            Name = $DeploymentName
+            Mode = 'Incremental'
+            ErrorAction = 'Stop'
+        }
+        
+        if ($ParametersFile)
+        {
+            $deployParams['TemplateParameterFile'] = $ParametersFile
+        }
+        
+        # Validate template first
+        $validation = Test-AzResourceGroupDeployment @deployParams
+        if ($validation)
+        {
+            Write-Error "Template validation failed: $($validation.Message)"
+            return
+        }
+        
+        # Deploy template
+        $deployment = New-AzResourceGroupDeployment @deployParams -Verbose
+        Write-Output "Deployment completed: $($deployment.ProvisioningState)"
+        return $deployment
+    }
+    catch
+    {
+        Write-Error "Deployment failed: $_"
+        throw
+    }
+}
+```
+
+### Bicep Integration
+
+```powershell
+function Deploy-BicepTemplate
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ResourceGroupName,
+
+        [Parameter(Mandatory)]
+        [ValidateScript({ Test-Path $_ -PathType Leaf })]
+        [string]$BicepFile,
+
+        [Parameter()]
+        [hashtable]$Parameters = @{}
+    )
+
+    try
+    {
+        # Build Bicep to ARM
+        $armTemplate = $BicepFile -replace '\.bicep$', '.json'
+        bicep build $BicepFile --outfile $armTemplate
+
+        if (-not (Test-Path $armTemplate))
+        {
+            throw "Bicep build failed"
+        }
+
+        # Deploy ARM template
+        $deployParams = @{
+            ResourceGroupName = $ResourceGroupName
+            TemplateFile = $armTemplate
+            TemplateParameterObject = $Parameters
+            ErrorAction = 'Stop'
+        }
+
+        New-AzResourceGroupDeployment @deployParams -Verbose
+    }
+    finally
+    {
+        # Clean up generated ARM template
+        if (Test-Path $armTemplate)
+        {
+            Remove-Item $armTemplate -Force
+        }
+    }
+}
+```
+
+## AWS PowerShell
+
+### Authentication
+
+```powershell
+#Requires -Modules AWS.Tools.Common, AWS.Tools.EC2
+
+# ✅ GOOD: Use IAM role in EC2
+function Initialize-AWSCredentials
+{
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [string]$ProfileName,
+
+        [Parameter()]
+        [string]$Region = 'us-east-1'
+    )
+
+    try
+    {
+        if ($ProfileName)
+        {
+            # Use named profile
+            Set-AWSCredential -ProfileName $ProfileName
+        }
+        else
+        {
+            # Use instance profile (IAM role)
+            $instanceProfile = Invoke-RestMethod -Uri 'http://169.254.169.254/latest/meta-data/iam/security-credentials/' -TimeoutSec 2
+            Write-Verbose "Using instance profile: $instanceProfile"
+        }
+
+        Set-DefaultAWSRegion -Region $Region
+        Write-Verbose "AWS credentials initialized for region: $Region"
+    }
+    catch
+    {
+        Write-Error "Failed to initialize AWS credentials: $_"
+        throw
+    }
+}
+```
+
+### EC2 Instance Management
+
+```powershell
+function New-EC2InstanceWithTags
+{
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ImageId,
+
+        [Parameter(Mandatory)]
+        [string]$InstanceType,
+
+        [Parameter(Mandatory)]
+        [string]$KeyName,
+
+        [Parameter()]
+        [hashtable]$Tags = @{}
+    )
+
+    if ($PSCmdlet.ShouldProcess("EC2 Instance", "Create"))
+    {
+        try
+        {
+            # Create instance
+            $instance = New-EC2Instance -ImageId $ImageId `
+                                       -InstanceType $InstanceType `
+                                       -KeyName $KeyName `
+                                       -MinCount 1 `
+                                       -MaxCount 1
+
+            $instanceId = $instance.Instances[0].InstanceId
+            Write-Verbose "Created instance: $instanceId"
+
+            # Wait for instance to exist
+            Start-Sleep -Seconds 5
+
+            # Apply tags
+            $tagList = $Tags.GetEnumerator() | ForEach-Object {
+                [Amazon.EC2.Model.Tag]@{
+                    Key = $_.Key
+                    Value = $_.Value
+                }
+            }
+
+            New-EC2Tag -Resource $instanceId -Tag $tagList
+            Write-Output "Instance $instanceId created and tagged"
+
+            return $instanceId
+        }
+        catch
+        {
+            Write-Error "Failed to create EC2 instance: $_"
+            throw
+        }
+    }
+}
+```
+
+## Error Handling and Retry Logic
+
+### Implement Retry for Transient Failures
+
+```powershell
+function Invoke-CloudCommandWithRetry
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [scriptblock]$ScriptBlock,
+
+        [Parameter()]
+        [int]$MaxRetries = 3,
+
+        [Parameter()]
+        [int]$RetryDelaySeconds = 5
+    )
+
+    $attempt = 0
+    $success = $false
+
+    while (-not $success -and $attempt -lt $MaxRetries)
+    {
+        $attempt++
+
+        try
+        {
+            $result = & $ScriptBlock
+            $success = $true
+            return $result
+        }
+        catch
+        {
+            Write-Warning "Attempt $attempt failed: $_"
+
+            if ($attempt -lt $MaxRetries)
+            {
+                Write-Verbose "Retrying in $RetryDelaySeconds seconds..."
+                Start-Sleep -Seconds $RetryDelaySeconds
+            }
+            else
+            {
+                Write-Error "All $MaxRetries attempts failed"
+                throw
+            }
+        }
+    }
+}
+
+# Usage
+$result = Invoke-CloudCommandWithRetry -ScriptBlock {
+    Get-AzVM -ResourceGroupName 'MyRG' -Name 'MyVM'
+} -MaxRetries 3
+```
+
+## Best Practices
+
+1. **Use managed identities** - Avoid storing credentials
+2. **Implement retry logic** - Handle transient failures
+3. **Validate before deployment** - Test templates first
+4. **Use parameter splatting** - Improve readability
+5. **Tag all resources** - For cost tracking and organization
+6. **Use specific modules** - Import only what you need
+7. **Handle regions properly** - Set default region
+8. **Implement proper logging** - Track all operations
+9. **Use ShouldProcess** - For destructive operations
+10. **Clean up resources** - Remove temporary resources in finally blocks
+
+