#215 feat: enhance Set-NovaUpdateNotificationPreference with WhatIf support and improved messaging

refactor(Set-NovaUpdateNotificationPreference): align with terminal-ux-design principles
Fixes #226

Author: stiwicourage

CHANGELOG.md

@@ -28,6 +28,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `Invoke-NovaRelease` now shows progress for the main release phases, ends with the publish target plus a next-step hint, and uses a plan summary instead of a success summary when `-WhatIf` previews the release.
 - `New-NovaModulePackage` now shows progress for build validation and artifact creation, ends with the package target plus the next suggested deployment step, and uses a package-plan summary in `-WhatIf` mode.
 - `Publish-NovaModule` now shows progress for build validation, publish, local import, and CI restore phases, ends with the publish target plus a suggested verification step, and uses a publish-plan summary in `-WhatIf` mode.
+- `Set-NovaUpdateNotificationPreference` now ends with a clear success or preview summary, prints the settings file path, suggests `Get-NovaUpdateNotificationPreference` as the next verification step, and gives a more actionable validation error when no enable/disable switch is supplied.
 
 ### Deprecated
 

RELEASE_NOTE.md

@@ -24,6 +24,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `Invoke-NovaRelease` now shows progress for the main release phases, ends with the publish target plus a next-step hint, and uses a plan summary instead of a success summary when `-WhatIf` previews the release.
 - `New-NovaModulePackage` now shows progress for build validation and artifact creation, ends with the package target plus the next suggested deployment step, and uses a package-plan summary in `-WhatIf` mode.
 - `Publish-NovaModule` now shows progress for build validation, publish, local import, and CI restore phases, ends with the publish target plus a suggested verification step, and uses a publish-plan summary in `-WhatIf` mode.
+- `Set-NovaUpdateNotificationPreference` now ends with a clear success or preview summary, prints the settings file path, suggests `Get-NovaUpdateNotificationPreference` as the next verification step, and gives a more actionable validation error when no enable/disable switch is supplied.
 
 ### Deprecated
 

docs/NovaModuleTools/en-US/Set-NovaUpdateNotificationPreference.md

@@ -38,6 +38,8 @@ The same stored preference is also used by `Update-NovaModuleTool` (alias: `Upda
 
 Stable self-updates remain available and do not require prerelease eligibility.
 
+When the preference changes, Nova prints the settings file path together with the next recommended verification command. In `-WhatIf` mode, Nova ends with a preview summary instead of writing the preference file.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
@@ -46,7 +48,7 @@ Stable self-updates remain available and do not require prerelease eligibility.
 PS> Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications
 ```
 
-Turns off prerelease self-update eligibility and restricts `Update-NovaModuleTool` to stable releases only.
+Turns off prerelease self-update eligibility, keeps stable releases available, and suggests `Get-NovaUpdateNotificationPreference` as the next verification step.
 
 ### EXAMPLE 2
 
@@ -55,15 +57,15 @@ PS> Set-NovaUpdateNotificationPreference -EnablePrereleaseNotifications
 ```
 
 Turns prerelease self-update eligibility back on, which allows `Update-NovaModuleTool` /
-`Update-NovaModuleTools` to consider a prerelease target again.
+`Update-NovaModuleTools` to consider a prerelease target again and suggests `Get-NovaUpdateNotificationPreference` as the next verification step.
 
 ### EXAMPLE 3
 
 ```text
 PS> Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications -WhatIf
 ```
 
-Previews the change that would disable prerelease self-update eligibility.
+Previews the change that would disable prerelease self-update eligibility without writing the settings file.
 
 ### EXAMPLE 4
 
@@ -195,6 +197,8 @@ Returns the current prerelease self-update state, the always-available stable-up
 
 Use this command together with `Get-NovaUpdateNotificationPreference` when you want to confirm the stored setting.
 
+Use `-WhatIf` or `-Confirm` when you want an easy way to preview or stop the change before the settings file is updated.
+
 ## RELATED LINKS
 
 - [Get-NovaUpdateNotificationPreference](./Get-NovaUpdateNotificationPreference.md)

src/private/update/GetNovaUpdateNotificationPreferenceChangeContext.ps1

@@ -2,24 +2,27 @@ function Get-NovaUpdateNotificationPreferenceChangeContext {
     [CmdletBinding()]
     param(
         [switch]$EnablePrereleaseNotifications,
-        [switch]$DisablePrereleaseNotifications
+        [switch]$DisablePrereleaseNotifications,
+        [hashtable]$WorkflowParams = @{}
     )
 
     if ($EnablePrereleaseNotifications.IsPresent) {
         return [pscustomobject]@{
             PrereleaseNotificationsEnabled = $true
             Target = Get-NovaUpdateSettingsFilePath
-            Action = 'Enable prerelease update notifications'
+            Action = 'Enable prerelease self-update notifications'
+            WorkflowParams = $WorkflowParams
         }
     }
 
     if ($DisablePrereleaseNotifications.IsPresent) {
         return [pscustomobject]@{
             PrereleaseNotificationsEnabled = $false
             Target = Get-NovaUpdateSettingsFilePath
-            Action = 'Disable prerelease update notifications'
+            Action = 'Disable prerelease self-update notifications'
+            WorkflowParams = $WorkflowParams
         }
     }
 
-    Stop-NovaOperation -Message 'Specify either -EnablePrereleaseNotifications or -DisablePrereleaseNotifications.' -ErrorId 'Nova.Validation.UpdateNotificationPreferenceChangeRequired' -Category InvalidArgument -TargetObject 'PrereleaseNotifications'
+    Stop-NovaOperation -Message 'Specify either -EnablePrereleaseNotifications or -DisablePrereleaseNotifications. Example: Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications' -ErrorId 'Nova.Validation.UpdateNotificationPreferenceChangeRequired' -Category InvalidArgument -TargetObject 'PrereleaseNotifications'
 }

src/private/update/InvokeNovaUpdateNotificationPreferenceChange.ps1

@@ -1,9 +1,135 @@
 function Invoke-NovaUpdateNotificationPreferenceChange {
     [CmdletBinding()]
     param(
-        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$ShouldRun
     )
 
+    $whatIfEnabled = Test-NovaUpdateNotificationPreferenceChangeWhatIfEnabled -WorkflowContext $WorkflowContext
+    if (-not $ShouldRun) {
+        if ($whatIfEnabled) {
+            Write-NovaUpdateNotificationPreferenceChangeResult -WorkflowContext $WorkflowContext -WhatIfEnabled
+        }
+
+        return
+    }
+
     Write-NovaUpdateNotificationPreference -PrereleaseNotificationsEnabled:$WorkflowContext.PrereleaseNotificationsEnabled
-    return Get-NovaUpdateNotificationPreferenceStatus
+    $status = Get-NovaUpdateNotificationPreferenceStatus
+    Write-NovaUpdateNotificationPreferenceChangeResult -WorkflowContext $WorkflowContext -Status $status
+    return $status
+}
+
+function Test-NovaUpdateNotificationPreferenceChangeWhatIfEnabled {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    return $WorkflowContext.WorkflowParams.ContainsKey('WhatIf') -and $WorkflowContext.WorkflowParams.WhatIf
+}
+
+function Write-NovaUpdateNotificationPreferenceChangeResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [AllowNull()][pscustomobject]$Status,
+        [switch]$WhatIfEnabled
+    )
+
+    Write-Message (Get-NovaUpdateNotificationPreferenceChangeStatusMessage -WorkflowContext $WorkflowContext -WhatIfEnabled:$WhatIfEnabled) -color Green
+    Write-Message "Settings file: $( Get-NovaUpdateNotificationPreferenceChangeSettingsPath -WorkflowContext $WorkflowContext -Status $Status )"
+    Write-Message (Get-NovaUpdateNotificationPreferenceChangeAvailabilityMessage -WhatIfEnabled:$WhatIfEnabled)
+
+    foreach ($line in (Get-NovaUpdateNotificationPreferenceChangeNextStepLine -WorkflowContext $WorkflowContext -WhatIfEnabled:$WhatIfEnabled)) {
+        Write-Message $line
+    }
+}
+
+function Get-NovaUpdateNotificationPreferenceChangeStatusMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled
+    )
+
+    $stateText = Get-NovaUpdateNotificationPreferenceChangeStateText -PrereleaseNotificationsEnabled:$WorkflowContext.PrereleaseNotificationsEnabled
+    if ($WhatIfEnabled) {
+        return "Notification preference plan ready: prerelease self-updates $stateText"
+    }
+
+    return "Prerelease self-updates are now $stateText."
+}
+
+function Get-NovaUpdateNotificationPreferenceChangeSettingsPath {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [AllowNull()][pscustomobject]$Status
+    )
+
+    if ($null -ne $Status -and ($Status.PSObject.Properties.Name -contains 'SettingsPath')) {
+        return $Status.SettingsPath
+    }
+
+    return $WorkflowContext.Target
+}
+
+function Get-NovaUpdateNotificationPreferenceChangeAvailabilityMessage {
+    [CmdletBinding()]
+    param(
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return 'Stable self-updates would remain available.'
+    }
+
+    return 'Stable self-updates remain available.'
+}
+
+function Get-NovaUpdateNotificationPreferenceChangeNextStepLine {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return @(
+            'Next step:'
+            "Run $( Get-NovaUpdateNotificationPreferenceChangeCommandLine -WorkflowContext $WorkflowContext ) without -WhatIf when you are ready to store the preference."
+        )
+    }
+
+    return @(
+        'Next step:'
+        'Get-NovaUpdateNotificationPreference'
+    )
+}
+
+function Get-NovaUpdateNotificationPreferenceChangeCommandLine {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    if ($WorkflowContext.PrereleaseNotificationsEnabled) {
+        return 'Set-NovaUpdateNotificationPreference -EnablePrereleaseNotifications'
+    }
+
+    return 'Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications'
+}
+
+function Get-NovaUpdateNotificationPreferenceChangeStateText {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][bool]$PrereleaseNotificationsEnabled
+    )
+
+    if ($PrereleaseNotificationsEnabled) {
+        return 'enabled'
+    }
+
+    return 'disabled'
 }

src/public/SetNovaUpdateNotificationPreference.ps1

@@ -8,11 +8,12 @@ function Set-NovaUpdateNotificationPreference {
         [switch]$DisablePrereleaseNotifications
     )
 
-    $workflowContext = Get-NovaUpdateNotificationPreferenceChangeContext -EnablePrereleaseNotifications:$EnablePrereleaseNotifications -DisablePrereleaseNotifications:$DisablePrereleaseNotifications
+    $workflowContext = Get-NovaUpdateNotificationPreferenceChangeContext -EnablePrereleaseNotifications:$EnablePrereleaseNotifications -DisablePrereleaseNotifications:$DisablePrereleaseNotifications -WorkflowParams @{WhatIf = [bool]$WhatIfPreference}
 
-    if (-not $PSCmdlet.ShouldProcess($workflowContext.Target, $workflowContext.Action)) {
+    $shouldRun = $PSCmdlet.ShouldProcess($workflowContext.Target, $workflowContext.Action)
+    if (-not $shouldRun -and -not $WhatIfPreference) {
         return
     }
 
-    return Invoke-NovaUpdateNotificationPreferenceChange -WorkflowContext $workflowContext
+    return Invoke-NovaUpdateNotificationPreferenceChange -WorkflowContext $workflowContext -ShouldRun:$shouldRun
 }

tests/private/update/GetNovaUpdateNotificationPreferenceChangeContext.Tests.ps1

@@ -16,21 +16,23 @@ Describe 'Get-NovaUpdateNotificationPreferenceChangeContext' {
     }
 
     It 'returns an enable context when -EnablePrereleaseNotifications is set' {
-        $context = Get-NovaUpdateNotificationPreferenceChangeContext -EnablePrereleaseNotifications
+        $context = Get-NovaUpdateNotificationPreferenceChangeContext -EnablePrereleaseNotifications -WorkflowParams @{WhatIf = $true}
 
         $context.PrereleaseNotificationsEnabled | Should -BeTrue
-        $context.Action | Should -Be 'Enable prerelease update notifications'
+        $context.Action | Should -Be 'Enable prerelease self-update notifications'
         $context.Target | Should -Not -BeNullOrEmpty
+        $context.WorkflowParams | Should -BeOfType Hashtable
+        $context.WorkflowParams.WhatIf | Should -BeTrue
     }
 
     It 'returns a disable context when -DisablePrereleaseNotifications is set' {
         $context = Get-NovaUpdateNotificationPreferenceChangeContext -DisablePrereleaseNotifications
 
         $context.PrereleaseNotificationsEnabled | Should -BeFalse
-        $context.Action | Should -Be 'Disable prerelease update notifications'
+        $context.Action | Should -Be 'Disable prerelease self-update notifications'
     }
 
     It 'throws via Stop-NovaOperation when neither switch is provided' {
-        {Get-NovaUpdateNotificationPreferenceChangeContext} | Should -Throw '*Specify either*'
+        {Get-NovaUpdateNotificationPreferenceChangeContext} | Should -Throw '*Example: Set-NovaUpdateNotificationPreference -DisablePrereleaseNotifications*'
     }
 }

tests/private/update/InvokeNovaUpdateNotificationPreferenceChange.Tests.ps1

@@ -4,20 +4,74 @@ BeforeAll {
 
     function Write-NovaUpdateNotificationPreference {param([bool]$PrereleaseNotificationsEnabled)}
     function Get-NovaUpdateNotificationPreferenceStatus {return [pscustomobject]@{PrereleaseNotificationsEnabled = $true; SettingsPath = '/tmp/x.json'}}
+    function Write-Message {param([string]$Text, [string]$color)}
+}
+
+Describe 'Test-NovaUpdateNotificationPreferenceChangeWhatIfEnabled' {
+    It 'returns true when WorkflowParams.WhatIf is enabled' {
+        $workflowContext = [pscustomobject]@{WorkflowParams = @{WhatIf = $true}}
+        Test-NovaUpdateNotificationPreferenceChangeWhatIfEnabled -WorkflowContext $workflowContext | Should -BeTrue
+    }
+
+    It 'returns false when WorkflowParams.WhatIf is not enabled' {
+        $workflowContext = [pscustomobject]@{WorkflowParams = @{}}
+        Test-NovaUpdateNotificationPreferenceChangeWhatIfEnabled -WorkflowContext $workflowContext | Should -BeFalse
+    }
 }
 
 Describe 'Invoke-NovaUpdateNotificationPreferenceChange' {
+    BeforeEach {
+        Mock Write-Message {}
+    }
+
     It 'writes the requested preference and returns the resulting status' {
         Mock Write-NovaUpdateNotificationPreference {}
         Mock Get-NovaUpdateNotificationPreferenceStatus {return [pscustomobject]@{PrereleaseNotificationsEnabled = $false; SettingsPath = '/tmp/x.json'}}
 
-        $workflowContext = [pscustomobject]@{PrereleaseNotificationsEnabled = $false; Action = 'Disable prerelease update notifications'; Target = '/tmp/x.json'}
-        $status = Invoke-NovaUpdateNotificationPreferenceChange -WorkflowContext $workflowContext
+        $workflowContext = [pscustomobject]@{
+            PrereleaseNotificationsEnabled = $false
+            Action = 'Disable prerelease self-update notifications'
+            Target = '/tmp/x.json'
+            WorkflowParams = @{}
+        }
+        $status = Invoke-NovaUpdateNotificationPreferenceChange -WorkflowContext $workflowContext -ShouldRun
 
         Assert-MockCalled Write-NovaUpdateNotificationPreference -Times 1 -ParameterFilter {
             $PrereleaseNotificationsEnabled -eq $false
         }
         Assert-MockCalled Get-NovaUpdateNotificationPreferenceStatus -Times 1
+        Assert-MockCalled Write-Message -Times 4
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Prerelease self-updates are now disabled.' -and $color -eq 'Green'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Get-NovaUpdateNotificationPreference'
+        }
         $status.PrereleaseNotificationsEnabled | Should -BeFalse
     }
+
+    It 'writes a preview summary in WhatIf mode without storing the preference' {
+        Mock Write-NovaUpdateNotificationPreference {}
+        Mock Get-NovaUpdateNotificationPreferenceStatus {}
+
+        $workflowContext = [pscustomobject]@{
+            PrereleaseNotificationsEnabled = $true
+            Action = 'Enable prerelease self-update notifications'
+            Target = '/tmp/x.json'
+            WorkflowParams = @{WhatIf = $true}
+        }
+
+        $status = Invoke-NovaUpdateNotificationPreferenceChange -WorkflowContext $workflowContext
+
+        Assert-MockCalled Write-NovaUpdateNotificationPreference -Times 0
+        Assert-MockCalled Get-NovaUpdateNotificationPreferenceStatus -Times 0
+        Assert-MockCalled Write-Message -Times 4
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Notification preference plan ready: prerelease self-updates enabled' -and $color -eq 'Green'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Run Set-NovaUpdateNotificationPreference -EnablePrereleaseNotifications without -WhatIf when you are ready to store the preference.'
+        }
+        $status | Should -BeNullOrEmpty
+    }
 }

tests/public/SetNovaUpdateNotificationPreference.TestSupport.ps1

@@ -0,0 +1,30 @@
+function Get-NovaUpdateNotificationPreferenceChangeContext {
+    param(
+        [switch]$EnablePrereleaseNotifications,
+        [switch]$DisablePrereleaseNotifications,
+        [hashtable]$WorkflowParams
+    )
+
+    $script:ctxArgs = @{
+        Enable = [bool]$EnablePrereleaseNotifications
+        Disable = [bool]$DisablePrereleaseNotifications
+        WhatIf = $WorkflowParams.WhatIf
+    }
+
+    return [pscustomobject]@{
+        Target = 'nm'
+        Action = 'Set'
+        WorkflowParams = $WorkflowParams
+    }
+}
+
+function Invoke-NovaUpdateNotificationPreferenceChange {
+    param(
+        $WorkflowContext,
+        [switch]$ShouldRun
+    )
+
+    $script:invoked = $true
+    $script:shouldRun = [bool]$ShouldRun
+    return [pscustomobject]@{Changed = $true}
+}