@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/coding-standards/powershell/module.json

@@ -0,0 +1,165 @@
+{
+  "name": "powershell-standards",
+  "version": "1.0.0",
+  "displayName": "PowerShell Coding Standards",
+  "description": "Comprehensive PowerShell coding standards for professional, maintainable, and secure PowerShell code across automation, modules, DSC, cloud orchestration, administrative tools, cross-platform scripts, and legacy migrations.",
+  "type": "coding-standards",
+  "author": "Augment Extensions",
+  "license": "MIT",
+  "keywords": [
+    "powershell",
+    "coding-standards",
+    "automation",
+    "modules",
+    "dsc",
+    "cloud",
+    "azure",
+    "aws",
+    "admin",
+    "cross-platform",
+    "legacy",
+    "pester",
+    "security",
+    "performance"
+  ],
+  "augment": {
+    "characterCount": 162000,
+    "priority": "high",
+    "category": "coding-standards",
+    "appliesTo": {
+      "languages": ["powershell"],
+      "filePatterns": ["**/*.ps1", "**/*.psm1", "**/*.psd1"],
+      "frameworks": [
+        "pester",
+        "dsc",
+        "azure-powershell",
+        "aws-powershell"
+      ]
+    },
+    "categories": {
+      "automation": {
+        "description": "Task automation and scheduled tasks",
+        "rules": ["automation-scripts.md"],
+        "examples": ["automation-example.ps1"]
+      },
+      "modules": {
+        "description": "PowerShell modules and advanced functions",
+        "rules": ["modules-functions.md"],
+        "examples": ["module-example.psm1"]
+      },
+      "dsc": {
+        "description": "Desired State Configuration",
+        "rules": ["dsc-configurations.md"],
+        "examples": ["dsc-example.ps1"]
+      },
+      "cloud": {
+        "description": "Cloud orchestration (Azure, AWS)",
+        "rules": ["cloud-orchestration.md"],
+        "examples": ["cloud-example.ps1"]
+      },
+      "admin": {
+        "description": "Administrative tools (AD, Exchange, SQL)",
+        "rules": ["administrative-tools.md"],
+        "examples": ["admin-example.ps1"]
+      },
+      "cross-platform": {
+        "description": "Cross-platform PowerShell scripts",
+        "rules": ["cross-platform-scripts.md"],
+        "examples": ["cross-platform-example.ps1"]
+      },
+      "legacy": {
+        "description": "Legacy Windows PowerShell to PowerShell Core migration",
+        "rules": ["legacy-migrations.md"],
+        "examples": ["legacy-migration-example.ps1"]
+      }
+    },
+    "universalRules": [
+      "universal-standards.md",
+      "naming-conventions.md",
+      "error-handling.md",
+      "security-practices.md",
+      "performance-optimization.md",
+      "testing-guidelines.md"
+    ]
+  },
+  "installation": {
+    "required": false,
+    "instructions": "This module is automatically loaded when working with PowerShell files. Configure categories in .augment/powershell-config.json"
+  },
+  "configuration": {
+    "file": ".augment/powershell-config.json",
+    "schema": {
+      "powershell_categories": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["automation", "modules", "dsc", "cloud", "admin", "cross-platform", "legacy"]
+        },
+        "description": "Project categories to apply"
+      },
+      "powershell_version": {
+        "type": "string",
+        "description": "Minimum PowerShell version",
+        "default": "7.4"
+      },
+      "strict_mode": {
+        "type": "boolean",
+        "description": "Enforce Set-StrictMode",
+        "default": true
+      },
+      "static_analysis": {
+        "type": "object",
+        "properties": {
+          "tool": {
+            "type": "string",
+            "enum": ["PSScriptAnalyzer"]
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["Error", "Warning", "Information"]
+          }
+        }
+      },
+      "testing": {
+        "type": "object",
+        "properties": {
+          "framework": {
+            "type": "string",
+            "enum": ["Pester"]
+          },
+          "version": {
+            "type": "string",
+            "default": "5.x"
+          }
+        }
+      },
+      "code_style": {
+        "type": "object",
+        "properties": {
+          "indentation": {
+            "type": "integer",
+            "default": 4
+          },
+          "brace_style": {
+            "type": "string",
+            "enum": ["Allman", "K&R"]
+          }
+        }
+      }
+    }
+  },
+  "dependencies": {
+    "powershell": {
+      "PSScriptAnalyzer": ">=1.21.0",
+      "Pester": ">=5.0.0"
+    }
+  },
+  "links": {
+    "homepage": "https://github.com/augment-code/augment-extensions",
+    "documentation": "https://github.com/augment-code/augment-extensions/tree/main/augment-extensions/coding-standards/powershell",
+    "powershell": "https://docs.microsoft.com/en-us/powershell/",
+    "pester": "https://pester.dev/",
+    "psscriptanalyzer": "https://github.com/PowerShell/PSScriptAnalyzer"
+  }
+}
+

package/augment-extensions/coding-standards/powershell/rules/administrative-tools.md

@@ -0,0 +1,439 @@
+# PowerShell Administrative Tools
+
+Best practices for AD, Exchange, SQL management, filtering, and bulk operations.
+
+## Active Directory Management
+
+### Efficient User Queries
+
+```powershell
+#Requires -Modules ActiveDirectory
+
+# ✅ GOOD: Server-side filtering with -Filter
+function Get-InactiveADUsers
+{
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [int]$DaysInactive = 90,
+        
+        [Parameter()]
+        [string]$SearchBase
+    )
+    
+    $cutoffDate = (Get-Date).AddDays(-$DaysInactive)
+    
+    $params = @{
+        Filter = "LastLogonDate -lt '$cutoffDate' -and Enabled -eq 'True'"
+        Properties = 'LastLogonDate', 'EmailAddress', 'Department'
+        ErrorAction = 'Stop'
+    }
+    
+    if ($SearchBase)
+    {
+        $params['SearchBase'] = $SearchBase
+    }
+    
+    Get-ADUser @params | Select-Object Name, SamAccountName, LastLogonDate, EmailAddress, Department
+}
+
+# ❌ BAD: Client-side filtering with Where-Object
+# Get-ADUser -Filter * | Where-Object { $_.LastLogonDate -lt $cutoffDate }
+```
+
+### Bulk User Operations
+
+```powershell
+function Update-ADUsersBulk
+{
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline)]
+        [Microsoft.ActiveDirectory.Management.ADUser[]]$Users,
+        
+        [Parameter(Mandatory)]
+        [hashtable]$Properties
+    )
+    
+    begin
+    {
+        $successCount = 0
+        $failureCount = 0
+        $errors = @()
+    }
+    
+    process
+    {
+        foreach ($user in $Users)
+        {
+            if ($PSCmdlet.ShouldProcess($user.SamAccountName, 'Update AD User'))
+            {
+                try
+                {
+                    Set-ADUser -Identity $user.SamAccountName @Properties -ErrorAction Stop
+                    $successCount++
+                    Write-Verbose "Updated user: $($user.SamAccountName)"
+                }
+                catch
+                {
+                    $failureCount++
+                    $errors += [PSCustomObject]@{
+                        User = $user.SamAccountName
+                        Error = $_.Exception.Message
+                    }
+                    Write-Warning "Failed to update $($user.SamAccountName): $_"
+                }
+            }
+        }
+    }
+    
+    end
+    {
+        Write-Output "Bulk update complete: $successCount succeeded, $failureCount failed"
+        if ($errors.Count -gt 0)
+        {
+            Write-Output "Errors:"
+            $errors | Format-Table -AutoSize
+        }
+    }
+}
+
+# Usage
+Get-InactiveADUsers -DaysInactive 90 | Update-ADUsersBulk -Properties @{ Department = 'Inactive' }
+```
+
+### Group Membership Management
+
+```powershell
+function Add-ADUserToGroupsBulk
+{
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        [Parameter(Mandatory)]
+        [string]$UserName,
+        
+        [Parameter(Mandatory)]
+        [string[]]$GroupNames
+    )
+    
+    try
+    {
+        $user = Get-ADUser -Identity $UserName -ErrorAction Stop
+        
+        foreach ($groupName in $GroupNames)
+        {
+            if ($PSCmdlet.ShouldProcess($groupName, "Add $UserName to group"))
+            {
+                try
+                {
+                    Add-ADGroupMember -Identity $groupName -Members $user -ErrorAction Stop
+                    Write-Verbose "Added $UserName to $groupName"
+                }
+                catch
+                {
+                    Write-Warning "Failed to add to $groupName: $_"
+                }
+            }
+        }
+    }
+    catch
+    {
+        Write-Error "User not found: $UserName"
+        throw
+    }
+}
+```
+
+## Exchange Management
+
+### Mailbox Operations
+
+```powershell
+#Requires -Modules ExchangeOnlineManagement
+
+function Get-LargeMailboxes
+{
+    [CmdletBinding()]
+    param(
+        [Parameter()]
+        [int]$SizeThresholdGB = 50
+    )
+    
+    $thresholdBytes = $SizeThresholdGB * 1GB
+    
+    Get-Mailbox -ResultSize Unlimited | ForEach-Object {
+        $stats = Get-MailboxStatistics -Identity $_.Identity
+        
+        if ($stats.TotalItemSize.Value.ToBytes() -gt $thresholdBytes)
+        {
+            [PSCustomObject]@{
+                DisplayName = $_.DisplayName
+                PrimarySmtpAddress = $_.PrimarySmtpAddress
+                SizeGB = [math]::Round($stats.TotalItemSize.Value.ToBytes() / 1GB, 2)
+                ItemCount = $stats.ItemCount
+                LastLogonTime = $stats.LastLogonTime
+            }
+        }
+    }
+}
+```
+
+### Distribution List Management
+
+```powershell
+function Export-DistributionListMembers
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$GroupName,
+
+        [Parameter(Mandatory)]
+        [string]$OutputPath
+    )
+
+    try
+    {
+        $members = Get-DistributionGroupMember -Identity $GroupName -ResultSize Unlimited
+
+        $members | Select-Object DisplayName, PrimarySmtpAddress, RecipientType |
+            Export-Csv -Path $OutputPath -NoTypeInformation
+
+        Write-Output "Exported $($members.Count) members to $OutputPath"
+    }
+    catch
+    {
+        Write-Error "Failed to export distribution list: $_"
+        throw
+    }
+}
+```
+
+## SQL Server Management
+
+### Database Queries
+
+```powershell
+#Requires -Modules SqlServer
+
+function Invoke-SQLQueryWithRetry
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ServerInstance,
+
+        [Parameter(Mandatory)]
+        [string]$Database,
+
+        [Parameter(Mandatory)]
+        [string]$Query,
+
+        [Parameter()]
+        [int]$QueryTimeout = 30,
+
+        [Parameter()]
+        [int]$MaxRetries = 3
+    )
+
+    $attempt = 0
+
+    while ($attempt -lt $MaxRetries)
+    {
+        $attempt++
+
+        try
+        {
+            $params = @{
+                ServerInstance = $ServerInstance
+                Database = $Database
+                Query = $Query
+                QueryTimeout = $QueryTimeout
+                ErrorAction = 'Stop'
+            }
+
+            $result = Invoke-Sqlcmd @params
+            return $result
+        }
+        catch
+        {
+            Write-Warning "Query attempt $attempt failed: $_"
+
+            if ($attempt -lt $MaxRetries)
+            {
+                Start-Sleep -Seconds 2
+            }
+            else
+            {
+                throw
+            }
+        }
+    }
+}
+```
+
+### Database Backup
+
+```powershell
+function Backup-SQLDatabaseWithValidation
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$ServerInstance,
+
+        [Parameter(Mandatory)]
+        [string]$Database,
+
+        [Parameter(Mandatory)]
+        [string]$BackupPath
+    )
+
+    try
+    {
+        $timestamp = Get-Date -Format 'yyyyMMdd_HHmmss'
+        $backupFile = Join-Path $BackupPath "$Database`_$timestamp.bak"
+
+        # Perform backup
+        Backup-SqlDatabase -ServerInstance $ServerInstance `
+                          -Database $Database `
+                          -BackupFile $backupFile `
+                          -CompressionOption On `
+                          -ErrorAction Stop
+
+        Write-Verbose "Backup created: $backupFile"
+
+        # Verify backup
+        $verifyQuery = "RESTORE VERIFYONLY FROM DISK = '$backupFile'"
+        Invoke-Sqlcmd -ServerInstance $ServerInstance -Query $verifyQuery -ErrorAction Stop
+
+        Write-Output "Backup verified successfully: $backupFile"
+
+        return $backupFile
+    }
+    catch
+    {
+        Write-Error "Backup failed: $_"
+        throw
+    }
+}
+```
+
+## Auditing and Logging
+
+### Comprehensive Audit Logging
+
+```powershell
+function Write-AuditLog
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateSet('Info', 'Warning', 'Error', 'Success')]
+        [string]$Level,
+
+        [Parameter(Mandatory)]
+        [string]$Message,
+
+        [Parameter()]
+        [string]$LogPath = 'C:\Logs\AdminTools.log',
+
+        [Parameter()]
+        [hashtable]$AdditionalData = @{}
+    )
+
+    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
+    $user = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+    $computer = $env:COMPUTERNAME
+
+    $logEntry = [PSCustomObject]@{
+        Timestamp = $timestamp
+        Level = $Level
+        User = $user
+        Computer = $computer
+        Message = $Message
+        AdditionalData = ($AdditionalData | ConvertTo-Json -Compress)
+    }
+
+    # Ensure log directory exists
+    $logDir = Split-Path $LogPath
+    if (-not (Test-Path $logDir))
+    {
+        New-Item -Path $logDir -ItemType Directory -Force | Out-Null
+    }
+
+    # Write to log file
+    $logEntry | Export-Csv -Path $LogPath -Append -NoTypeInformation
+
+    # Also write to appropriate stream
+    switch ($Level)
+    {
+        'Info' { Write-Verbose $Message }
+        'Warning' { Write-Warning $Message }
+        'Error' { Write-Error $Message }
+        'Success' { Write-Output $Message }
+    }
+}
+```
+
+### Change Tracking
+
+```powershell
+function Invoke-AdminTaskWithAudit
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$TaskName,
+
+        [Parameter(Mandatory)]
+        [scriptblock]$ScriptBlock,
+
+        [Parameter()]
+        [hashtable]$Parameters = @{}
+    )
+
+    $startTime = Get-Date
+
+    Write-AuditLog -Level Info -Message "Starting task: $TaskName" -AdditionalData $Parameters
+
+    try
+    {
+        $result = & $ScriptBlock
+        $duration = (Get-Date) - $startTime
+
+        Write-AuditLog -Level Success -Message "Task completed: $TaskName" -AdditionalData @{
+            Duration = $duration.TotalSeconds
+            Result = ($result | ConvertTo-Json -Compress -Depth 2)
+        }
+
+        return $result
+    }
+    catch
+    {
+        $duration = (Get-Date) - $startTime
+
+        Write-AuditLog -Level Error -Message "Task failed: $TaskName" -AdditionalData @{
+            Duration = $duration.TotalSeconds
+            Error = $_.Exception.Message
+        }
+
+        throw
+    }
+}
+```
+
+## Best Practices
+
+1. **Use server-side filtering** - Filter with -Filter parameter, not Where-Object
+2. **Implement bulk operations** - Process multiple items efficiently
+3. **Add comprehensive logging** - Track all administrative actions
+4. **Use ShouldProcess** - For all destructive operations
+5. **Implement retry logic** - Handle transient failures
+6. **Validate before execution** - Check prerequisites
+7. **Export results** - Save operation results for auditing
+8. **Use specific properties** - Don't retrieve all properties unnecessarily
+9. **Handle errors gracefully** - Continue processing on individual failures
+10. **Document changes** - Maintain audit trail of all modifications
+
+