Merge pull request #1076 from Romanitho/copilot

Add documentation and refactor WAU PowerShell scripts

Author: Romanitho

Sources/Winget-AutoUpdate/User-Run.ps1

@@ -1,73 +1,84 @@
 <#
 .SYNOPSIS
-Handle user interaction from shortcuts and show a Toast notification
+    Handles user-initiated WAU update checks via shortcut.
 
 .DESCRIPTION
-Act on shortcut run
+    Provides a user-facing interface to manually trigger WAU update checks.
+    Displays toast notifications for status updates (starting, running,
+    completed, or error). Waits for the scheduled task to complete and
+    shows the result.
 
 .EXAMPLE
-.\user-run.ps1
+    .\User-Run.ps1
 
+.NOTES
+    Triggered by desktop shortcut or Start menu entry.
+    Uses the Winget-AutoUpdate scheduled task.
+    Shows error details from logs\error.txt if update check fails.
 #>
 
+# Check if WAU is currently running
 function Test-WAUisRunning {
-	If (((Get-ScheduledTask -TaskName 'Winget-AutoUpdate').State -eq 'Running') -or ((Get-ScheduledTask -TaskName 'Winget-AutoUpdate-UserContext').State -eq 'Running')) {
-		Return $True
-	}
+    If (((Get-ScheduledTask -TaskName 'Winget-AutoUpdate').State -eq 'Running') -or ((Get-ScheduledTask -TaskName 'Winget-AutoUpdate-UserContext').State -eq 'Running')) {
+        Return $True
+    }
 }
 
 <# MAIN #>
 
-#Get Working Dir
+# Set working directory
 $Script:WorkingDir = $PSScriptRoot
 
-#Load external functions
+# Load required functions
 . $WorkingDir\functions\Get-NotifLocale.ps1
 . $WorkingDir\functions\Start-NotifTask.ps1
 
-#Get Toast Locale function
+# Load notification locale
 Get-NotifLocale
 
-#Set common variables
+# Set common notification parameters
 $OnClickAction = "$WorkingDir\logs\updates.log"
 $Button1Text = $NotifLocale.local.outputs.output[11].message
 
 try {
-	#Check if WAU is currently running
-	if (Test-WAUisRunning) {
-		$Message = $NotifLocale.local.outputs.output[8].message
-		$MessageType = "warning"
-		Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
-		break
-	}
-	#Run scheduled task
-	Get-ScheduledTask -TaskName "Winget-AutoUpdate" -ErrorAction Stop | Start-ScheduledTask -ErrorAction Stop
-	#Starting check - Send notification
-	$Message = $NotifLocale.local.outputs.output[6].message
-	$MessageType = "info"
-	Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
-	#Sleep until the task is done
-	While (Test-WAUisRunning) {
-		Start-Sleep 3
-	}
+    # Check if WAU is already running
+    if (Test-WAUisRunning) {
+        $Message = $NotifLocale.local.outputs.output[8].message
+        $MessageType = "warning"
+        Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
+        break
+    }
 
-	#Test if there was a list_/winget_error
-	if (Test-Path "$WorkingDir\logs\error.txt") {
-		$MessageType = "error"
-		$Critical = Get-Content "$WorkingDir\logs\error.txt" -Raw
-		$Critical = $Critical.Trim()
-		$Critical = $Critical.Substring(0, [Math]::Min($Critical.Length, 50))
-		$Message = "Critical:`n$Critical..."
-	}
-	else {
-		$MessageType = "success"
-		$Message = $NotifLocale.local.outputs.output[9].message
-	}
-	Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
+    # Start the WAU scheduled task
+    Get-ScheduledTask -TaskName "Winget-AutoUpdate" -ErrorAction Stop | Start-ScheduledTask -ErrorAction Stop
+
+    # Send "starting" notification
+    $Message = $NotifLocale.local.outputs.output[6].message
+    $MessageType = "info"
+    Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
+
+    # Wait for task completion
+    While (Test-WAUisRunning) {
+        Start-Sleep 3
+    }
+
+    # Check for errors in the update process
+    if (Test-Path "$WorkingDir\logs\error.txt") {
+        $MessageType = "error"
+        $Critical = Get-Content "$WorkingDir\logs\error.txt" -Raw
+        $Critical = $Critical.Trim()
+        $Critical = $Critical.Substring(0, [Math]::Min($Critical.Length, 50))
+        $Message = "Critical:`n$Critical..."
+    }
+    else {
+        $MessageType = "success"
+        $Message = $NotifLocale.local.outputs.output[9].message
+    }
+    Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
 }
 catch {
-	#Check failed - Just send notification
-	$Message = $NotifLocale.local.outputs.output[7].message
-	$MessageType = "error"
-	Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
+    # Handle task start failure
+    $Message = $NotifLocale.local.outputs.output[7].message
+    $MessageType = "error"
+    Start-NotifTask -Message $Message -MessageType $MessageType -Button1Text $Button1Text -Button1Action $OnClickAction -ButtonDismiss -UserRun
 }

Sources/Winget-AutoUpdate/WAU-Notify.ps1

@@ -1,24 +1,38 @@
-#Send Notify Script
+<#
+.SYNOPSIS
+    Displays a toast notification to the logged-in user.
 
-#get xml notif config
+.DESCRIPTION
+    Reads notification configuration from an XML file and displays
+    a Windows toast notification using the ToastNotificationManager API.
+    This script is called by a scheduled task when WAU runs in system context.
+
+.NOTES
+    Configuration file: config\notif.xml
+    Launcher ID: Windows.SystemToast.WAU.Notification
+#>
+
+# Get WAU installation path from registry
 $WAUinstalledPath = Get-ItemPropertyValue -Path "HKLM:\SOFTWARE\Romanitho\Winget-AutoUpdate\" -Name InstallLocation
+
+# Load notification XML configuration
 [xml]$NotifConf = Get-Content "$WAUinstalledPath\config\notif.xml" -Encoding UTF8 -ErrorAction SilentlyContinue
 if (!($NotifConf)) {
     break
 }
 
-#Load Assemblies
+# Load Windows notification assemblies
 [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
 [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
 
-#Prepare XML
+# Parse notification XML
 $ToastXml = [Windows.Data.Xml.Dom.XmlDocument]::New()
 $ToastXml.LoadXml($NotifConf.OuterXml)
 
-#Specify Launcher App ID
+# Specify toast launcher ID
 $LauncherID = "Windows.SystemToast.WAU.Notification"
 
-#Prepare and Create Toast
+# Create and display the notification
 $ToastMessage = [Windows.UI.Notifications.ToastNotification]::New($ToastXML)
 $ToastMessage.Tag = $NotifConf.toast.tag
 [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($LauncherID).Show($ToastMessage)

Sources/Winget-AutoUpdate/WAU-Policies.ps1

@@ -1,45 +1,51 @@
 <#
 .SYNOPSIS
-Handle GPO/Polices
+    Applies Group Policy settings to WAU scheduled tasks.
 
 .DESCRIPTION
-Daily update settings from policies
+    Reads WAU configuration from GPO registry keys and updates the
+    Winget-AutoUpdate scheduled task triggers accordingly.
+    Handles daily, bi-daily, weekly, bi-weekly, and monthly schedules,
+    as well as logon triggers and time delays.
+
+.NOTES
+    This script is executed by the WAU-Policies scheduled task.
+    GPO registry path: HKLM:\SOFTWARE\Policies\Romanitho\Winget-AutoUpdate
+    Logs applied settings to: logs\LatestAppliedSettings.txt
 #>
 
-#Import functions
+# Import configuration function
 . "$PSScriptRoot\functions\Get-WAUConfig.ps1"
 
-#Check if GPO Management is detected
+# Check if GPO management is enabled
 $GPOManagementDetected = Get-ItemProperty "HKLM:\SOFTWARE\Policies\Romanitho\Winget-AutoUpdate" -ErrorAction SilentlyContinue
 
 if ($GPOManagementDetected) {
 
-    #Get WAU settings
+    # Load WAU configuration (with GPO overrides)
     $WAUConfig = Get-WAUConfig
 
-    #Log init
+    # Initialize logging
     $GPOLogDirectory = Join-Path -Path $WAUConfig.InstallLocation -ChildPath "logs"
     if (!(Test-Path -Path $GPOLogDirectory)) {
         New-Item -ItemType Directory -Path $GPOLogDirectory -Force | Out-Null
     }
     $GPOLogFile = Join-Path -Path $GPOLogDirectory -ChildPath "LatestAppliedSettings.txt"
     Set-Content -Path $GPOLogFile -Value "###  POLICY CYCLE - $(Get-Date)  ###`n"
 
-    #Get Winget-AutoUpdate scheduled task
+    # Get current scheduled task configuration
     $WAUTask = Get-ScheduledTask -TaskName 'Winget-AutoUpdate' -ErrorAction SilentlyContinue
-
-    #Update 'Winget-AutoUpdate' scheduled task settings
     $currentTriggers = $WAUTask.Triggers
     $configChanged = $false
 
-    #Check if LogOn trigger setting has changed
+    # === Check if LogOn trigger setting has changed ===
     $hasLogonTrigger = $currentTriggers | Where-Object { $_.CimClass.CimClassName -eq "MSFT_TaskLogonTrigger" }
     if (($WAUConfig.WAU_UpdatesAtLogon -eq 1 -and -not $hasLogonTrigger) -or
         ($WAUConfig.WAU_UpdatesAtLogon -ne 1 -and $hasLogonTrigger)) {
         $configChanged = $true
     }
 
-    #Check if schedule type has changed
+    # === Detect current schedule type ===
     $currentIntervalType = "None"
     foreach ($trigger in $currentTriggers) {
         if ($trigger.CimClass.CimClassName -eq "MSFT_TaskDailyTrigger" -and $trigger.DaysInterval -eq 1) {
@@ -72,7 +78,7 @@ if ($GPOManagementDetected) {
         $configChanged = $true
     }
 
-    #Check if delay has changed
+    # === Check if delay has changed ===
     $randomDelay = [TimeSpan]::ParseExact($WAUConfig.WAU_UpdatesTimeDelay, "hh\:mm", $null)
     $timeTrigger = $currentTriggers | Where-Object { $_.CimClass.CimClassName -ne "MSFT_TaskLogonTrigger" } | Select-Object -First 1
     if ($timeTrigger.RandomDelay -match '^PT(?:(\d+)H)?(?:(\d+)M)?$') {
@@ -84,7 +90,7 @@ if ($GPOManagementDetected) {
         $configChanged = $true
     }
 
-    #Check if schedule time has changed
+    # === Check if schedule time has changed ===
     if ($currentIntervalType -ne "None" -and $currentIntervalType -ne "Never") {
         if ($timeTrigger) {
             $currentTime = [DateTime]::Parse($timeTrigger.StartBoundary).ToString("HH:mm:ss")
@@ -94,12 +100,16 @@ if ($GPOManagementDetected) {
         }
     }
 
-    #Only update triggers if configuration has changed
+    # === Update triggers if configuration changed ===
     if ($configChanged) {
         $taskTriggers = @()
+
+        # Add logon trigger if enabled
         if ($WAUConfig.WAU_UpdatesAtLogon -eq 1) {
             $tasktriggers += New-ScheduledTaskTrigger -AtLogOn
         }
+
+        # Add time-based trigger based on interval type
         if ($WAUConfig.WAU_UpdatesInterval -eq "Daily") {
             $tasktriggers += New-ScheduledTaskTrigger -Daily -At $WAUConfig.WAU_UpdatesAtTime -RandomDelay $randomDelay
         }
@@ -116,20 +126,18 @@ if ($GPOManagementDetected) {
             $tasktriggers += New-ScheduledTaskTrigger -Weekly -At $WAUConfig.WAU_UpdatesAtTime -DaysOfWeek 2 -WeeksInterval 4 -RandomDelay $randomDelay
         }
 
-        #If trigger(s) set
+        # Apply new triggers or disable task
         if ($taskTriggers) {
-            #Edit scheduled task
             Set-ScheduledTask -TaskPath $WAUTask.TaskPath -TaskName $WAUTask.TaskName -Trigger $taskTriggers | Out-Null
         }
-        #If not, remove trigger(s)
         else {
-            #Remove by setting past due date
+            # Disable by setting a past due date
             $tasktriggers = New-ScheduledTaskTrigger -Once -At "01/01/1970"
             Set-ScheduledTask -TaskPath $WAUTask.TaskPath -TaskName $WAUTask.TaskName -Trigger $tasktriggers | Out-Null
         }
     }
 
-    #Log latest applied config
+    # Log applied configuration
     Add-Content -Path $GPOLogFile -Value "`nLatest applied settings:"
     $WAUConfig.PSObject.Properties | Where-Object { $_.Name -like "WAU_*" } | Select-Object Name, Value | Out-File -Encoding default -FilePath $GPOLogFile -Append