#215 feat: enhance Update-NovaModuleTool with improved workflow and WhatIf support

refactor(Update-NovaModuleTools): align with terminal-ux-design principles
Fixes #228

Author: stiwicourage

CHANGELOG.md

@@ -30,6 +30,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `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.
 - `Test-NovaBuild` now shows progress across the main test phases, ends with the result file path plus a coverage summary and next-step hint when tests pass, uses a test-plan summary in `-WhatIf` mode, and fails with more actionable guidance when Pester or coverage checks fail.
+- `Update-NovaModuleTool` now ends with a visible up-to-date, preview, cancelled, or updated summary, skips prerelease confirmation during `-WhatIf`, shows progress for the actual self-update step, and suggests `Get-NovaProjectInfo -Installed` after a successful update.
 
 ### Deprecated
 

RELEASE_NOTE.md

@@ -26,6 +26,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `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.
 - `Test-NovaBuild` now shows progress across the main test phases, ends with the result file path plus a coverage summary and next-step hint when tests pass, uses a test-plan summary in `-WhatIf` mode, and fails with more actionable guidance when Pester or coverage checks fail.
+- `Update-NovaModuleTool` now ends with a visible up-to-date, preview, cancelled, or updated summary, skips prerelease confirmation during `-WhatIf`, shows progress for the actual self-update step, and suggests `Get-NovaProjectInfo -Installed` after a successful update.
 
 ### Deprecated
 

docs/NovaModuleTools/en-US/Update-NovaModuleTools.md

@@ -38,7 +38,9 @@ When prerelease notifications are enabled, `Update-NovaModuleTool` may target a
 
 Stable updates do not require prerelease confirmation.
 
-After a successful update, `Update-NovaModuleTool` prints the release notes link from the installed module manifest.
+When a newer version is available, `Update-NovaModuleTool` shows progress while it installs the update and reads the release-notes link from the updated module. Every command path ends with a visible summary: up-to-date, preview, cancelled, or updated.
+
+After a successful update, `Update-NovaModuleTool` prints the release notes link from the installed module manifest and suggests `Get-NovaProjectInfo -Installed` as the next verification step.
 
 ## EXAMPLES
 
@@ -48,7 +50,7 @@ After a successful update, `Update-NovaModuleTool` prints the release notes link
 PS> Update-NovaModuleTool
 ```
 
-Updates the installed `NovaModuleTools` module by using the stored prerelease preference to resolve the update candidate.
+Updates the installed `NovaModuleTools` module by using the stored prerelease preference to resolve the update candidate, then prints the current version, target version, and the next suggested verification step.
 
 ### EXAMPLE 2
 
@@ -76,13 +78,13 @@ Successful updates print the release notes link from the installed module manife
 PS> Update-NovaModuleTool -WhatIf
 ```
 
-Previews the resolved update action without running `Update-Module`.
+Previews the resolved update action without prompting for prerelease confirmation or running `Update-Module`.
 
 ## PARAMETERS
 
 ### -WhatIf
 
-Shows what would happen if the cmdlet runs. `Update-NovaModuleTool` resolves the target version first, then previews the selected stable or prerelease update action without changing the installed module.
+Shows what would happen if the cmdlet runs. `Update-NovaModuleTool` resolves the target version first, then previews the selected stable or prerelease update action without prompting for prerelease confirmation or changing the installed module.
 
 ```yaml
 Type: System.Management.Automation.SwitchParameter
@@ -147,8 +149,11 @@ If the PowerShell Gallery cannot be reached well enough to resolve an update can
 
 Use `Get-NovaUpdateNotificationPreference` and `Set-NovaUpdateNotificationPreference` to inspect or change the stored prerelease setting.
 
+Use `Ctrl+C` if you need to stop an active self-update before `Update-Module` finishes.
+
 ## RELATED LINKS
 
 - [Get-NovaUpdateNotificationPreference](./Get-NovaUpdateNotificationPreference.md)
 - [Set-NovaUpdateNotificationPreference](./Set-NovaUpdateNotificationPreference.md)
+- [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)
 - [Invoke-NovaBuild](./Invoke-NovaBuild.md)

src/private/update/GetNovaModuleSelfUpdateWorkflowContext.ps1

@@ -4,7 +4,7 @@ function Get-NovaModuleSelfUpdateWorkflowContext {
         [pscustomobject]$Preference,
         [pscustomobject]$InstalledModule,
         [pscustomobject]$LookupResult,
-        [int]$TimeoutMilliseconds = 10000
+        [hashtable]$WorkflowParams = @{}
     )
 
     $resolvedPreference = if ($null -ne $Preference) {
@@ -20,7 +20,7 @@ function Get-NovaModuleSelfUpdateWorkflowContext {
     $resolvedLookupResult = if ($null -ne $LookupResult) {
         $LookupResult
     } else {
-        Invoke-NovaModuleUpdateLookup -AllowPrereleaseNotifications:$resolvedPreference.PrereleaseNotificationsEnabled -TimeoutMilliseconds $TimeoutMilliseconds
+        Invoke-NovaModuleUpdateLookup -AllowPrereleaseNotifications:$resolvedPreference.PrereleaseNotificationsEnabled -TimeoutMilliseconds 10000
     }
 
     if ($null -eq $resolvedLookupResult) {
@@ -38,6 +38,7 @@ function Get-NovaModuleSelfUpdateWorkflowContext {
         Preference = $resolvedPreference
         InstalledModule = $resolvedInstalledModule
         LookupResult = $resolvedLookupResult
+        WorkflowParams = $WorkflowParams
         Plan = $plan
         Action = $action
     }

src/private/update/InvokeNovaModuleSelfUpdateWorkflow.ps1

@@ -7,7 +7,8 @@ function Invoke-NovaModuleSelfUpdateOrStop {
     try {
         $null = Invoke-NovaModuleSelfUpdate -ModuleName $Plan.ModuleName -AllowPrerelease:$Plan.UsedAllowPrerelease
     } catch {
-        Stop-NovaOperation -Message $_.Exception.Message -ErrorId 'Nova.Dependency.ModuleSelfUpdateFailed' -Category InvalidOperation -TargetObject $Plan.ModuleName
+        $message = "NovaModuleTools self-update failed: $( $_.Exception.Message ) Confirm that the PowerShell Gallery is reachable and that this session can update installed modules, then rerun Update-NovaModuleTool."
+        Stop-NovaOperation -Message $message -ErrorId 'Nova.Dependency.ModuleSelfUpdateFailed' -Category InvalidOperation -TargetObject $Plan.ModuleName
     }
 }
 
@@ -30,16 +31,190 @@ function Complete-NovaModuleSelfUpdateResult {
 function Invoke-NovaModuleSelfUpdateWorkflow {
     [CmdletBinding()]
     param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$ShouldRun
+    )
+
+    $progressActivity = 'Updating NovaModuleTools'
+    $result = $null
+
+    if (Test-NovaModuleSelfUpdateWorkflowShouldSkipExecution -WorkflowContext $WorkflowContext -ShouldRun:$ShouldRun) {
+        $result = Complete-NovaModuleSelfUpdateResult -Plan $WorkflowContext.Plan -ReleaseNotesUri $null
+        Write-NovaModuleSelfUpdateWorkflowResult -Result $result -WorkflowContext $WorkflowContext
+        return $result
+    }
+
+    try {
+        Invoke-NovaModuleSelfUpdateWorkflowStep -Activity $progressActivity -Status (Get-NovaModuleSelfUpdateWorkflowUpdateStatus -WorkflowContext $WorkflowContext) -PercentComplete 80 -Action {
+            Invoke-NovaModuleSelfUpdateOrStop -Plan $WorkflowContext.Plan
+        }
+
+        $WorkflowContext.Plan.Updated = $true
+        $releaseNotesUri = Invoke-NovaModuleSelfUpdateWorkflowStep -Activity $progressActivity -Status 'Reading release notes from the updated module' -PercentComplete 95 -Action {
+            Get-NovaModuleReleaseNotesUri
+        }
+
+        $result = Complete-NovaModuleSelfUpdateResult -Plan $WorkflowContext.Plan -ReleaseNotesUri $releaseNotesUri
+    } finally {
+        Write-Progress -Activity $progressActivity -Completed
+    }
+
+    Write-NovaModuleSelfUpdateWorkflowResult -Result $result -WorkflowContext $WorkflowContext
+    return $result
+}
+
+function Test-NovaModuleSelfUpdateWorkflowShouldSkipExecution {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$ShouldRun
+    )
+
+    return (-not $WorkflowContext.Plan.UpdateAvailable) -or (-not $ShouldRun)
+}
+
+function Invoke-NovaModuleSelfUpdateWorkflowStep {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$Activity,
+        [Parameter(Mandatory)][string]$Status,
+        [Parameter(Mandatory)][int]$PercentComplete,
+        [Parameter(Mandatory)][scriptblock]$Action
+    )
+
+    Write-Progress -Activity $Activity -Status $Status -PercentComplete $PercentComplete
+    & $Action
+}
+
+function Write-NovaModuleSelfUpdateWorkflowResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Result,
         [Parameter(Mandatory)][pscustomobject]$WorkflowContext
     )
 
-    $plan = $WorkflowContext.Plan
-    if (-not $plan.UpdateAvailable) {
-        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
+    $whatIfEnabled = Test-NovaModuleSelfUpdateWorkflowWhatIfEnabled -WorkflowContext $WorkflowContext
+    Write-Message (Get-NovaModuleSelfUpdateWorkflowStatusMessage -Result $Result -WhatIfEnabled:$whatIfEnabled) -color (Get-NovaModuleSelfUpdateWorkflowStatusColor -Result $Result)
+    Write-Message "Current version: $( $Result.CurrentVersion )"
+
+    $targetVersionLine = Get-NovaModuleSelfUpdateWorkflowTargetVersionLine -Result $Result
+    if (-not [string]::IsNullOrWhiteSpace($targetVersionLine)) {
+        Write-Message $targetVersionLine
+    }
+
+    $repositoryLine = Get-NovaModuleSelfUpdateWorkflowRepositoryLine -Result $Result
+    if (-not [string]::IsNullOrWhiteSpace($repositoryLine)) {
+        Write-Message $repositoryLine
+    }
+
+    foreach ($line in (Get-NovaModuleSelfUpdateWorkflowNextStepLine -Result $Result -WhatIfEnabled:$whatIfEnabled)) {
+        Write-Message $line
     }
+}
 
-    Invoke-NovaModuleSelfUpdateOrStop -Plan $plan
-    $plan.Updated = $true
-    $releaseNotesUri = Get-NovaModuleReleaseNotesUri
-    return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $releaseNotesUri
+function Test-NovaModuleSelfUpdateWorkflowWhatIfEnabled {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    return $WorkflowContext.WorkflowParams.ContainsKey('WhatIf') -and $WorkflowContext.WorkflowParams.WhatIf
+}
+
+function Get-NovaModuleSelfUpdateWorkflowUpdateStatus {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    if ($WorkflowContext.Plan.IsPrereleaseTarget) {
+        return "Installing prerelease version $( $WorkflowContext.Plan.TargetVersion )"
+    }
+
+    return "Installing version $( $WorkflowContext.Plan.TargetVersion )"
+}
+
+function Get-NovaModuleSelfUpdateWorkflowStatusMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Result,
+        [switch]$WhatIfEnabled
+    )
+
+    if (-not $Result.UpdateAvailable) {
+        return 'NovaModuleTools is already up to date.'
+    }
+
+    if ($WhatIfEnabled) {
+        return 'Self-update plan ready for NovaModuleTools'
+    }
+
+    if ($Result.Cancelled) {
+        return 'Self-update cancelled for NovaModuleTools.'
+    }
+
+    return "Updated NovaModuleTools to version $( $Result.TargetVersion )."
+}
+
+function Get-NovaModuleSelfUpdateWorkflowStatusColor {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Result
+    )
+
+    if ($Result.Cancelled) {
+        return 'Blue'
+    }
+
+    return 'Green'
+}
+
+function Get-NovaModuleSelfUpdateWorkflowTargetVersionLine {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Result
+    )
+
+    if (-not $Result.UpdateAvailable) {
+        return $null
+    }
+
+    return "Target version: $( $Result.TargetVersion )"
+}
+
+function Get-NovaModuleSelfUpdateWorkflowRepositoryLine {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Result
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Result.LookupRepository)) {
+        return $null
+    }
+
+    return "Repository: $( $Result.LookupRepository )"
+}
+
+function Get-NovaModuleSelfUpdateWorkflowNextStepLine {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Result,
+        [switch]$WhatIfEnabled
+    )
+
+    if (-not $Result.UpdateAvailable -or $Result.Cancelled) {
+        return @()
+    }
+
+    if ($WhatIfEnabled) {
+        return @(
+            'Next step:'
+            "Run Update-NovaModuleTool without -WhatIf when you are ready to install version $( $Result.TargetVersion )."
+        )
+    }
+
+    return @(
+        'Next step:'
+        'Get-NovaProjectInfo -Installed'
+    )
 }

src/public/UpdateNovaModuleTools.ps1

@@ -3,22 +3,22 @@ function Update-NovaModuleTool {
     [Alias('Update-NovaModuleTools')]
     param()
 
-    $workflowContext = Get-NovaModuleSelfUpdateWorkflowContext
+    $workflowContext = Get-NovaModuleSelfUpdateWorkflowContext -WorkflowParams @{WhatIf = [bool]$WhatIfPreference}
     $plan = $workflowContext.Plan
-    if (-not $plan.UpdateAvailable) {
-        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
+    if ($plan.IsPrereleaseTarget -and -not $WhatIfPreference) {
+        $prereleaseConfirmed = Confirm-NovaPrereleaseModuleUpdate -Cmdlet $PSCmdlet -CurrentVersion $plan.CurrentVersion -TargetVersion $plan.TargetVersion
+        if (-not $prereleaseConfirmed) {
+            $plan.Cancelled = $true
+            return Invoke-NovaModuleSelfUpdateWorkflow -WorkflowContext $workflowContext -ShouldRun:$false
+        }
     }
 
-    if ($plan.IsPrereleaseTarget -and -not (Confirm-NovaPrereleaseModuleUpdate -Cmdlet $PSCmdlet -CurrentVersion $plan.CurrentVersion -TargetVersion $plan.TargetVersion)) {
-        $plan.Cancelled = $true
-        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
+    $shouldRun = $plan.UpdateAvailable -and $PSCmdlet.ShouldProcess($plan.ModuleName, $workflowContext.Action)
+    if (-not $shouldRun) {
+        $plan.Cancelled = (-not $WhatIfPreference) -and $plan.UpdateAvailable
     }
 
-    if (-not $PSCmdlet.ShouldProcess($plan.ModuleName, $workflowContext.Action)) {
-        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
-    }
-
-    $result = Invoke-NovaModuleSelfUpdateWorkflow -WorkflowContext $workflowContext
+    $result = Invoke-NovaModuleSelfUpdateWorkflow -WorkflowContext $workflowContext -ShouldRun:$shouldRun
     Write-NovaModuleReleaseNotesLink -ReleaseNotesUri $result.ReleaseNotesUri
     return $result
 }

tests/ArchitectureGuardrails.Tests.ps1

@@ -95,7 +95,7 @@ Describe 'Architecture guardrails' {
             [pscustomobject]@{Path = 'src/public/PublishNovaModule.ps1'; ExpectedHelpers = @('Get-NovaDynamicDeliveryParameterDictionary', 'Get-NovaProjectInfo', 'Get-NovaPublishWorkflowContext', 'Get-NovaShouldProcessForwardingParameter', 'Invoke-NovaPublishWorkflow', 'Write-NovaPublishWorkflowContext')}
             [pscustomobject]@{Path = 'src/public/SetNovaUpdateNotificationPreference.ps1'; ExpectedHelpers = @('Get-NovaUpdateNotificationPreferenceChangeContext', 'Invoke-NovaUpdateNotificationPreferenceChange')}
             [pscustomobject]@{Path = 'src/public/TestNovaBuild.ps1'; ExpectedHelpers = @('Get-NovaTestWorkflowContext', 'Invoke-NovaTestWorkflow', 'New-NovaTestDynamicParameterDictionary')}
-            [pscustomobject]@{Path = 'src/public/UpdateNovaModuleTools.ps1'; ExpectedHelpers = @('Complete-NovaModuleSelfUpdateResult', 'Confirm-NovaPrereleaseModuleUpdate', 'Get-NovaModuleSelfUpdateWorkflowContext', 'Invoke-NovaModuleSelfUpdateWorkflow', 'Write-NovaModuleReleaseNotesLink')}
+            [pscustomobject]@{Path = 'src/public/UpdateNovaModuleTools.ps1'; ExpectedHelpers = @('Confirm-NovaPrereleaseModuleUpdate', 'Get-NovaModuleSelfUpdateWorkflowContext', 'Invoke-NovaModuleSelfUpdateWorkflow', 'Write-NovaModuleReleaseNotesLink')}
             [pscustomobject]@{Path = 'src/public/UpdateNovaModuleVersion.ps1'; ExpectedHelpers = @('Get-NovaVersionUpdateWorkflowContext', 'Invoke-NovaVersionUpdateCiActivation', 'Invoke-NovaVersionUpdateWorkflow', 'Write-NovaVersionUpdateResultOutput')}
         )
         $expectedPaths = @($testCases | ForEach-Object Path | Sort-Object)

tests/private/update/GetNovaModuleSelfUpdateWorkflowContext.Tests.ps1

@@ -28,6 +28,17 @@ Describe 'Get-NovaModuleSelfUpdateWorkflowContext' {
         $ctx.Action | Should -Be 'Update NovaModuleTools to prerelease version 3.0.0-rc1'
     }
 
+    It 'carries forwarded workflow parameters into the context' {
+        Mock Read-NovaUpdateNotificationPreference {[pscustomobject]@{PrereleaseNotificationsEnabled=$false}}
+        Mock Get-NovaInstalledModuleVersionInfo {[pscustomobject]@{Version='1.0.0'}}
+        Mock Invoke-NovaModuleUpdateLookup {[pscustomobject]@{Version='2.0.0'}}
+        Mock Get-NovaModuleSelfUpdatePlan {[pscustomobject]@{TargetVersion='2.0.0'; IsPrereleaseTarget=$false}}
+
+        $ctx = Get-NovaModuleSelfUpdateWorkflowContext -WorkflowParams @{WhatIf = $true}
+
+        $ctx.WorkflowParams.WhatIf | Should -BeTrue
+    }
+
     It 'throws when no lookup result is available' {
         Mock Read-NovaUpdateNotificationPreference {[pscustomobject]@{PrereleaseNotificationsEnabled=$false}}
         Mock Get-NovaInstalledModuleVersionInfo {[pscustomobject]@{Version='1.0.0'}}

tests/private/update/InvokeNovaModuleSelfUpdateWorkflow.TestSupport.ps1

@@ -1,3 +1,5 @@
 function Invoke-NovaModuleSelfUpdate {param([string]$ModuleName,[switch]$AllowPrerelease)}
 function Get-NovaModuleReleaseNotesUri {'https://example.com/notes'}
 function Stop-NovaOperation {param([string]$Message,[string]$ErrorId,$Category,$TargetObject) throw [System.Management.Automation.ErrorRecord]::new([System.Exception]::new($Message),$ErrorId,$Category,$TargetObject)}
+function Write-Message {param([string]$Text, [string]$color)}
+function Write-Progress {param([string]$Activity, [string]$Status, [int]$PercentComplete, [switch]$Completed)}