blockmine 1.24.0 → 1.27.0

package/.claude/skills/systems-engineering/resources/powershell-scripting.md

@@ -1,482 +0,0 @@
-# PowerShell Scripting
-
-Comprehensive guide to PowerShell scripting for system administration, automation, and remote management.
-
-## PowerShell Fundamentals
-
-### Cmdlets and Pipeline
-
-PowerShell uses verb-noun cmdlets that pass objects (not text) through the pipeline:
-
-```powershell
-# Basic cmdlets
-Get-Process | Where-Object {$_.CPU -gt 100} | Sort-Object CPU -Descending
-Get-Service | Select-Object Name, Status | Format-Table
-Get-ChildItem *.log | Export-Csv "files.csv" -NoTypeInformation
-
-# Objects have properties and methods
-$process = Get-Process -Name "powershell" | Select-Object -First 1
-$process | Get-Member
-$process.CPU
-$process.WorkingSet
-
-# Filter, group, measure
-Get-Process | Where-Object {$_.WorkingSet -gt 100MB}
-Get-Service | Group-Object Status
-Get-ChildItem -Recurse | Measure-Object -Property Length -Sum
-```
-
-### Variables and Data Types
-
-```powershell
-# Variables
-$name = "Server01"
-$count = 42
-$enabled = $true
-
-# Arrays
-$servers = @("web01", "web02", "web03")
-
-# Hash tables
-$config = @{
-    Server = "web01"
-    Port = 443
-    Enabled = $true
-}
-
-# Typed variables
-[string]$name = "Test"
-[int]$number = 42
-[datetime]$date = Get-Date
-```
-
-## Script Structure and Functions
-
-### Script Template
-
-```powershell
-<#.SYNOPSIS Brief description #>
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory=$true)][string]$ServerName,
-    [int]$Timeout = 30
-)
-Write-Verbose "Processing server: $ServerName"
-```
-
-### Functions
-
-```powershell
-function Test-ServiceStatus {
-    [CmdletBinding()]
-    param(
-        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
-        [string[]]$ServiceName,
-
-        [ValidateSet('Running', 'Stopped')]
-        [string]$ExpectedStatus = 'Running'
-    )
-
-    begin {
-        $results = @()
-    }
-
-    process {
-        foreach ($name in $ServiceName) {
-            $service = Get-Service -Name $name -ErrorAction SilentlyContinue
-            if ($service) {
-                $results += [PSCustomObject]@{
-                    Name = $name
-                    Status = $service.Status
-                    IsExpected = ($service.Status -eq $ExpectedStatus)
-                }
-            }
-        }
-    }
-
-    end {
-        return $results
-    }
-}
-
-# Usage
-Test-ServiceStatus -ServiceName "WinRM", "W32Time"
-"WinRM", "Spooler" | Test-ServiceStatus
-```
-
-## Error Handling
-
-### Try-Catch-Finally
-
-```powershell
-function Copy-FileWithRetry {
-    param([string]$Source, [string]$Destination, [int]$MaxRetries = 3)
-
-    $attempt = 0
-    while ($attempt -lt $MaxRetries) {
-        $attempt++
-        try {
-            Copy-Item -Path $Source -Destination $Destination -ErrorAction Stop
-            return
-        }
-        catch [System.IO.IOException] {
-            Write-Warning "IO error: $_"
-            Start-Sleep -Seconds 2
-        }
-        catch {
-            Write-Error "Unexpected error: $_"
-            throw
-        }
-    }
-    throw "Failed after $MaxRetries attempts"
-}
-```
-
-### Error Action Preference
-
-```powershell
-# Global preference
-$ErrorActionPreference = "Stop"  # Stop, Continue, SilentlyContinue
-
-# Per-cmdlet
-Get-Service -Name "NonExistent" -ErrorAction SilentlyContinue
-
-# Check results
-$?  # $true if last command succeeded
-$LASTEXITCODE  # Exit code of last external command
-$Error[0]  # Most recent error
-
-# Common patterns
-if (Get-Command "az" -ErrorAction SilentlyContinue) {
-    Write-Host "Azure CLI is installed"
-}
-
-if (Test-Path "config.json") {
-    $config = Get-Content "config.json" | ConvertFrom-Json
-}
-```
-
-## Parameters and Validation
-
-```powershell
-function New-UserAccount {
-    [CmdletBinding(SupportsShouldProcess=$true)]
-    param(
-        [Parameter(Mandatory=$true)]
-        [string]$Username,
-
-        [ValidateSet('Admin', 'User', 'Guest')]
-        [string]$Role,
-
-        [ValidatePattern('^[\w\.-]+@[\w\.-]+\.\w+$')]
-        [string]$Email,
-
-        [ValidateRange(1, 365)]
-        [int]$PasswordExpiryDays = 90,
-
-        [ValidateLength(1, 50)]
-        [string]$Description,
-
-        [switch]$Force
-    )
-
-    if ($PSCmdlet.ShouldProcess($Username, "Create user")) {
-        Write-Host "Creating user: $Username with role: $Role"
-    }
-}
-
-# Usage
-New-UserAccount -Username "jdoe" -Role "User" -WhatIf
-```
-
-## Modules
-
-### Creating a Module
-
-```powershell
-# MyTools.psm1
-function Get-SystemInfo {
-    [PSCustomObject]@{
-        ComputerName = $env:COMPUTERNAME
-        OS = (Get-CimInstance Win32_OperatingSystem).Caption
-        MemoryGB = [math]::Round((Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory/1GB, 2)
-    }
-}
-
-function Test-Port {
-    param([string]$ComputerName, [int]$Port)
-    try {
-        $tcp = New-Object System.Net.Sockets.TcpClient
-        $tcp.Connect($ComputerName, $Port)
-        $tcp.Close()
-        return $true
-    }
-    catch { return $false }
-}
-
-Export-ModuleMember -Function Get-SystemInfo, Test-Port
-```
-
-### Using Modules
-
-```powershell
-# Import and manage
-Import-Module -Name "MyTools"
-Get-Module -ListAvailable
-Get-Module
-Remove-Module -Name "MyTools"
-
-# PowerShell Gallery
-Install-Module -Name "Posh-SSH" -Scope CurrentUser
-Find-Module -Name "*Azure*"
-Update-Module -Name "Posh-SSH"
-```
-
-## Remote Management
-
-### PowerShell Remoting
-
-```powershell
-# Enable remoting
-Enable-PSRemoting -Force
-
-# Run command remotely
-Invoke-Command -ComputerName "server01" -ScriptBlock { Get-Service -Name "WinRM" }
-Invoke-Command -ComputerName "server01", "server02" -ScriptBlock { Get-EventLog -LogName System -Newest 10 }
-
-# With credentials and arguments
-$cred = Get-Credential
-Invoke-Command -ComputerName "server01" -Credential $cred -ArgumentList "WinRM" -ScriptBlock {
-    param($ServiceName)
-    Get-Service -Name $ServiceName
-}
-
-# Persistent sessions
-$session = New-PSSession -ComputerName "server01"
-Invoke-Command -Session $session -ScriptBlock { Get-Process | Export-Csv "C:\temp\processes.csv" }
-Copy-Item -Path ".\config.json" -Destination "C:\app\" -ToSession $session
-Remove-PSSession -Session $session
-```
-
-## Desired State Configuration (DSC)
-
-```powershell
-Configuration WebServerConfig {
-    param([string[]]$ComputerName = "localhost")
-
-    Import-DscResource -ModuleName PSDesiredStateConfiguration
-
-    Node $ComputerName {
-        WindowsFeature IIS {
-            Ensure = "Present"
-            Name = "Web-Server"
-        }
-
-        File WebsiteContent {
-            Ensure = "Present"
-            Type = "Directory"
-            DestinationPath = "C:\inetpub\wwwroot\mysite"
-            DependsOn = "[WindowsFeature]IIS"
-        }
-
-        Service W3SVC {
-            Name = "W3SVC"
-            State = "Running"
-            StartupType = "Automatic"
-            DependsOn = "[WindowsFeature]IIS"
-        }
-    }
-}
-
-# Generate and apply
-WebServerConfig -ComputerName "web01" -OutputPath "C:\DSC\Configs"
-Start-DscConfiguration -Path "C:\DSC\Configs" -Wait -Verbose
-Test-DscConfiguration
-```
-
-## Common Cmdlets
-
-### Get, Set, New, Remove
-
-```powershell
-# Files
-Get-ChildItem -Path "C:\Logs" -Recurse -Filter "*.log"
-Get-Content -Path "app.log" -Tail 50
-
-# Services and processes
-Get-Service | Where-Object {$_.Status -eq "Running"}
-Get-Process | Sort-Object CPU -Descending | Select-Object -First 10
-
-# System
-Get-ComputerInfo
-Get-CimInstance Win32_OperatingSystem
-Get-EventLog -LogName Application -Newest 100
-
-# Network
-Get-NetAdapter
-Get-NetIPAddress
-Get-NetTCPConnection -State Established
-
-# Set (modify)
-Set-Service -Name "Spooler" -StartupType Automatic
-Set-Content -Path "config.txt" -Value "Setting=Value"
-
-# New (create)
-New-Item -Path "C:\Temp\NewFolder" -ItemType Directory
-New-LocalUser -Name "AppUser" -Password (ConvertTo-SecureString "P@ss" -AsPlainText -Force)
-
-# Remove (delete)
-Remove-Item -Path "C:\Temp\OldFiles" -Recurse -Force
-Remove-LocalUser -Name "TempUser"
-```
-
-## Testing with Pester
-
-```powershell
-# Install Pester
-Install-Module -Name Pester -Force -SkipPublisherCheck
-
-# Test file
-BeforeAll { . "$PSScriptRoot\MyFunctions.ps1" }
-
-Describe "Get-DiskInfo" {
-    It "Returns disk information" {
-        $result = Get-DiskInfo
-        $result | Should -Not -BeNullOrEmpty
-        $result.PSObject.Properties.Name | Should -Contain "Drive"
-    }
-}
-
-Describe "Test-ServiceRunning" {
-    It "Handles stopped services" {
-        Mock Get-Service { [PSCustomObject]@{ Status = "Stopped" } }
-        Test-ServiceRunning -Name "Test" | Should -Be $false
-    }
-}
-
-Invoke-Pester -Path ".\MyFunctions.Tests.ps1"
-```
-
-## Best Practices
-
-1. **Use Approved Verbs**: `Get-Verb` lists approved verbs (Good: Get-UserInfo, Bad: Fetch-UserInfo)
-
-2. **Implement -WhatIf and -Confirm**:
-```powershell
-function Remove-OldLogs {
-    [CmdletBinding(SupportsShouldProcess=$true)]
-    param([int]$DaysOld = 30)
-    $files = Get-ChildItem -Path "C:\Logs" -Filter "*.log" |
-        Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-$DaysOld)}
-    foreach ($file in $files) {
-        if ($PSCmdlet.ShouldProcess($file.Name, "Delete")) { Remove-Item $file.FullName }
-    }
-}
-Remove-OldLogs -WhatIf
-```
-
-3. **Always Handle Errors**: Use try-catch with ErrorAction Stop
-
-4. **Use CmdletBinding**: Enables -Verbose, -Debug, -ErrorAction, -WarningAction parameters
-
-## PowerShell vs Bash for Linux Admins
-
-```powershell
-# List files: ls/dir -> Get-ChildItem
-# Find files: find / -name "*.log" -> Get-ChildItem -Path / -Recurse -Filter "*.log"
-# Search: grep "error" file.log -> Select-String -Pattern "error" -Path file.log
-# Processes: ps aux -> Get-Process | kill -9 PID -> Stop-Process -Id PID -Force
-# Pipes: ps aux | grep firefox -> Get-Process | Where-Object {$_.Name -like "*firefox*"}
-# Variables: var="value" -> $var = "value"
-# Conditionals: if [ $x -eq 5 ] -> if ($x -eq 5) {}
-# Operators: -eq, -ne, -gt, -lt, -like, -match (same concept, different syntax)
-```
-
-## Real-World Example: System Health Check
-
-```powershell
-function Get-SystemHealth {
-    param([string]$ComputerName = $env:COMPUTERNAME)
-
-    $health = @{ ComputerName = $ComputerName; Status = "Healthy"; Issues = @() }
-
-    # Check disk space
-    Get-PSDrive -PSProvider FileSystem | Where-Object {$_.Free} | ForEach-Object {
-        $percentFree = ($_.Free / ($_.Used + $_.Free)) * 100
-        if ($percentFree -lt 10) {
-            $health.Issues += "Disk $($_.Name): Low space"
-            $health.Status = "Warning"
-        }
-    }
-
-    # Check critical services
-    @("WinRM", "W32Time", "Dnscache") | ForEach-Object {
-        $service = Get-Service -Name $_ -ErrorAction SilentlyContinue
-        if ($service.Status -ne "Running") {
-            $health.Issues += "Service $_ is $($service.Status)"
-            $health.Status = "Critical"
-        }
-    }
-
-    # Check memory
-    $os = Get-CimInstance Win32_OperatingSystem
-    $memUsed = (($os.TotalVisibleMemorySize - $os.FreePhysicalMemory) / $os.TotalVisibleMemorySize) * 100
-    if ($memUsed -gt 90) {
-        $health.Issues += "High memory: $([math]::Round($memUsed,1))%"
-        $health.Status = "Warning"
-    }
-
-    return [PSCustomObject]$health
-}
-
-# Usage
-$result = Get-SystemHealth
-$result | ConvertTo-Json | Out-File "health-report.json"
-
-if ($result.Status -ne "Healthy") {
-    Send-MailMessage -To "admin@example.com" `
-        -Subject "System Alert: $($result.ComputerName)" `
-        -Body ($result.Issues -join "`n")
-}
-```
-
-## Additional Real-World Examples
-
-### Automated Backup
-
-```powershell
-function Start-Backup {
-    param([string]$Source, [string]$Destination, [int]$RetentionDays = 7)
-
-    $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
-    $backupPath = Join-Path $Destination "Backup_$timestamp"
-
-    Copy-Item -Path $Source -Destination $backupPath -Recurse -ErrorAction Stop
-
-    # Cleanup old backups
-    Get-ChildItem -Path $Destination -Directory |
-        Where-Object {$_.CreationTime -lt (Get-Date).AddDays(-$RetentionDays)} |
-        Remove-Item -Recurse -Force
-}
-```
-
-### Log Analysis
-
-```powershell
-function Get-ErrorsFromLog {
-    param([string]$LogPath, [int]$Hours = 24)
-
-    $since = (Get-Date).AddHours(-$Hours)
-    Get-Content $LogPath |
-        Select-String -Pattern "ERROR|FATAL" |
-        ForEach-Object {
-            if ($_.Line -match '(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})') {
-                if ([datetime]$matches[1] -gt $since) {
-                    [PSCustomObject]@{ Timestamp = [datetime]$matches[1]; Message = $_.Line }
-                }
-            }
-        } | Sort-Object Timestamp
-}
-```
-
-This guide provides production-ready PowerShell patterns for system administration and automation.