#215 feat: enhance version update workflow with progress reporting and detailed summaries

refactor(Update-NovaModuleVersion): align with terminal-ux-design principles
Fixes #229

Author: stiwicourage

CHANGELOG.md

@@ -31,6 +31,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `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.
+- `Update-NovaModuleVersion` now ends with a visible preview, cancelled, or updated summary, prints the resolved version file plus the detected/applied release label, shows progress while writing `project.json`, and suggests the next command to run after the bump.
 
 ### Deprecated
 

RELEASE_NOTE.md

@@ -27,6 +27,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `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.
+- `Update-NovaModuleVersion` now ends with a visible preview, cancelled, or updated summary, prints the resolved version file plus the detected/applied release label, shows progress while writing `project.json`, and suggests the next command to run after the bump.
 
 ### Deprecated
 

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

@@ -43,7 +43,7 @@ When Git tags exist, only commits since the latest tag are considered. If Git-ba
 If the repository exists but has no commits yet, the command stops with: `Cannot bump version because the repository
 has no commits yet. Create an initial commit first.`
 
-This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the calculated release label and the exact next version without changing the stored version.
+This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the calculated release label and the exact next version without changing the stored version. The command now ends with a clear plan, cancellation, or success summary, prints the resolved version file plus the detected/applied release label, and suggests the next step to run.
 
 Use `-ContinuousIntegration` when the same session should first re-activate the built `dist/` module before the version bump workflow starts. This is useful in CI/self-hosting flows where an earlier command changed the active module state.
 
@@ -58,7 +58,7 @@ When the current version is already a prerelease for the selected release line,
 PS> Update-NovaModuleVersion
 ```
 
-Updates the version in the current project using the release label inferred from recent commit messages.
+Updates the version in the current project using the release label inferred from recent commit messages, then prints the version file plus the next suggested validation step.
 
 ### EXAMPLE 2
 
@@ -81,7 +81,7 @@ Label: Minor
 CommitCount: 12
 ```
 
-Shows the calculated version update without modifying `project.json`.
+Shows the calculated version update without modifying `project.json`, then ends with a version-update plan summary and a reminder to rerun without `-WhatIf` when you are ready to write the new version.
 
 ### EXAMPLE 4
 
@@ -111,7 +111,7 @@ Label: Minor
 CommitCount: 12
 ```
 
-Shows how `-Preview` keeps the detected semantic label for reporting but deterministically enters the next patch preview track when the current version is stable.
+Shows how `-Preview` keeps the detected semantic label for reporting but deterministically enters the next patch preview track when the current version is stable, while the plan summary still points to the exact next version that would be written.
 
 ### EXAMPLE 6
 
@@ -165,7 +165,7 @@ Label: Major
 CommitCount: 34
 ```
 
-Shows how stable `0.y.z` bumps still warn that `1.0.0` must be set manually when the API becomes stable, while breaking-change commits on that line continue to plan the next minor version instead of jumping straight to `1.0.0`.
+Shows how stable `0.y.z` bumps still warn that `1.0.0` must be set manually when the API becomes stable, while breaking-change commits on that line continue to plan the next minor version instead of jumping straight to `1.0.0`. The plan output also keeps both the detected and applied release labels visible.
 
 ### EXAMPLE 10
 

src/private/release/InvokeNovaVersionUpdateWorkflow.ps1

@@ -7,25 +7,46 @@ function Invoke-NovaVersionUpdateWorkflow {
     )
 
     $versionWriteResult = $null
-    if ($ShouldRun) {
-        $versionWriteResult = Set-NovaModuleVersion -ProjectInfo $WorkflowContext.ProjectInfo -Label (Get-NovaVersionUpdateEffectiveLabel -WorkflowContext $WorkflowContext) -PreviewRelease:$WorkflowContext.PreviewRelease -Confirm:$false
+    $progressActivity = 'Updating Nova module version'
+    try {
+        if ($ShouldRun) {
+            $versionWriteResult = Invoke-NovaVersionUpdateWorkflowStep -Activity $progressActivity -Status (Get-NovaVersionUpdateApplyStatus -WorkflowContext $WorkflowContext) -PercentComplete 80 -Action {
+                Set-NovaModuleVersion -ProjectInfo $WorkflowContext.ProjectInfo -Label (Get-NovaVersionUpdateEffectiveLabel -WorkflowContext $WorkflowContext) -PreviewRelease:$WorkflowContext.PreviewRelease -Confirm:$false
+            }
+        }
     }
-
-    if (-not (Test-NovaVersionUpdateResultRequired -ShouldRun:$ShouldRun -WhatIfEnabled:$WhatIfEnabled)) {
-        return
+    finally {
+        if ($ShouldRun) {
+            Write-Progress -Activity $progressActivity -Completed
+        }
     }
 
-    return Get-NovaVersionUpdateResult -WorkflowContext $WorkflowContext -Applied:($null -ne $versionWriteResult -and $versionWriteResult.Applied)
+    $wasApplied = $null -ne $versionWriteResult -and $versionWriteResult.Applied
+    $wasCancelled = (-not $ShouldRun) -and (-not $WhatIfEnabled)
+    return Get-NovaVersionUpdateResult -WorkflowContext $WorkflowContext -Applied:$wasApplied -Previewed:$WhatIfEnabled -Cancelled:$wasCancelled
 }
 
-function Test-NovaVersionUpdateResultRequired {
+function Invoke-NovaVersionUpdateWorkflowStep {
     [CmdletBinding()]
     param(
-        [switch]$ShouldRun,
-        [switch]$WhatIfEnabled
+        [Parameter(Mandatory)][string]$Activity,
+        [Parameter(Mandatory)][string]$Status,
+        [Parameter(Mandatory)][int]$PercentComplete,
+        [Parameter(Mandatory)][scriptblock]$Action
+    )
+
+    Write-Progress -Activity $Activity -Status $Status -PercentComplete $PercentComplete
+    return & $Action
+}
+
+function Get-NovaVersionUpdateApplyStatus {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
     )
 
-    return $ShouldRun -or $WhatIfEnabled
+    $target = Get-NovaVersionUpdateTarget -WorkflowContext $WorkflowContext
+    return "Writing version $( $WorkflowContext.NewVersion ) to $target"
 }
 
 function Get-NovaVersionUpdateEffectiveLabel {
@@ -34,28 +55,35 @@ function Get-NovaVersionUpdateEffectiveLabel {
         [Parameter(Mandatory)][pscustomobject]$WorkflowContext
     )
 
-    if ($WorkflowContext.PSObject.Properties.Name -contains 'EffectiveLabel' -and -not [string]::IsNullOrWhiteSpace($WorkflowContext.EffectiveLabel)) {
-        return $WorkflowContext.EffectiveLabel
+    $effectiveLabel = Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'EffectiveLabel'
+    if (-not [string]::IsNullOrWhiteSpace($effectiveLabel)) {
+        return $effectiveLabel
     }
 
-    return $WorkflowContext.Label
+    return Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'Label'
 }
 
 function Get-NovaVersionUpdateResult {
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
-        [switch]$Applied
+        [switch]$Applied,
+        [switch]$Previewed,
+        [switch]$Cancelled
     )
 
     return [pscustomobject]@{
-        PreviousVersion = $WorkflowContext.PreviousVersion
-        NewVersion = $WorkflowContext.NewVersion
-        Label = $WorkflowContext.Label
+        PreviousVersion = Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'PreviousVersion'
+        NewVersion = Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'NewVersion'
+        Label = Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'Label'
         EffectiveLabel = Get-NovaVersionUpdateEffectiveLabel -WorkflowContext $WorkflowContext
         AdvisoryMessage = Get-NovaVersionUpdateAdvisoryMessage -WorkflowContext $WorkflowContext
-        CommitCount = $WorkflowContext.CommitCount
+        CommitCount = Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'CommitCount'
+        ProjectFile = Get-NovaVersionUpdateProjectFile -WorkflowContext $WorkflowContext
+        Target = Get-NovaVersionUpdateTarget -WorkflowContext $WorkflowContext
         Applied = [bool]$Applied
+        Previewed = [bool]$Previewed
+        Cancelled = [bool]$Cancelled
     }
 }
 
@@ -65,10 +93,53 @@ function Get-NovaVersionUpdateAdvisoryMessage {
         [Parameter(Mandatory)][pscustomobject]$WorkflowContext
     )
 
-    if ($WorkflowContext.PSObject.Properties.Name -notcontains 'AdvisoryMessage') {
+    return Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'AdvisoryMessage'
+}
+
+function Get-NovaVersionUpdateProjectFile {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    $projectInfo = Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'ProjectInfo'
+    if ($null -eq $projectInfo) {
+        return $null
+    }
+
+    $projectFileProperty = $projectInfo.PSObject.Properties['ProjectJSON']
+    if ($null -eq $projectFileProperty) {
         return $null
     }
 
-    return $WorkflowContext.AdvisoryMessage
+    return $projectFileProperty.Value
+}
+
+function Get-NovaVersionUpdateTarget {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    $projectFile = Get-NovaVersionUpdateProjectFile -WorkflowContext $WorkflowContext
+    if (-not [string]::IsNullOrWhiteSpace($projectFile)) {
+        return [System.IO.Path]::GetFileName($projectFile)
+    }
+
+    return Get-NovaVersionUpdateWorkflowPropertyValue -WorkflowContext $WorkflowContext -Name 'Target'
 }
 
+function Get-NovaVersionUpdateWorkflowPropertyValue {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [Parameter(Mandatory)][string]$Name
+    )
+
+    $property = $WorkflowContext.PSObject.Properties[$Name]
+    if ($null -eq $property) {
+        return $null
+    }
+
+    return $property.Value
+}

src/private/release/WriteNovaVersionUpdateResultMessages.ps1

@@ -33,8 +33,14 @@ function Write-NovaVersionUpdateResultOutput {
         Write-Warning $advisoryMessage
     }
 
-    if ($Result.Applied) {
-        Write-Host "Version bumped to : $( $Result.NewVersion )"
+    Write-Message (Get-NovaVersionUpdateResultStatusMessage -Result $Result) -color (Get-NovaVersionUpdateResultStatusColor -Result $Result)
+
+    foreach ($line in (Get-NovaVersionUpdateResultDetailText -Result $Result)) {
+        Write-Message $line
+    }
+
+    foreach ($line in (Get-NovaVersionUpdateResultNextStepText -Result $Result)) {
+        Write-Message $line
     }
 }
 
@@ -44,11 +50,137 @@ function Get-NovaVersionUpdateResultAdvisoryMessage {
         [Parameter(Mandatory)][object]$Result
     )
 
-    if ($Result.PSObject.Properties.Name -notcontains 'AdvisoryMessage') {
-        return $null
+    return Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'AdvisoryMessage'
+}
+
+function Get-NovaVersionUpdateResultStatusMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
+
+    if ([bool](Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'Cancelled')) {
+        return 'Version update cancelled before changing project.json.'
+    }
+
+    if ([bool](Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'Previewed')) {
+        return "Version update plan ready -> $( Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'NewVersion' )"
+    }
+
+    return "Updated project version to $( Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'NewVersion' )"
+}
+
+function Get-NovaVersionUpdateResultStatusColor {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
+
+    if ([bool](Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'Cancelled')) {
+        return 'Blue'
+    }
+
+    return 'Green'
+}
+
+function Get-NovaVersionUpdateResultDetailText {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
+
+    $lines = @()
+    $targetLine = Get-NovaVersionUpdateResultTargetLine -Result $Result
+    if (-not [string]::IsNullOrWhiteSpace($targetLine)) {
+        $lines += $targetLine
+    }
+
+    $lines += "Previous version: $( Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'PreviousVersion' )"
+    $lines += "New version: $( Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'NewVersion' )"
+    $lines += Get-NovaVersionUpdateResultLabelText -Result $Result
+
+    $commitCount = Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'CommitCount'
+    if ($null -ne $commitCount) {
+        $lines += "Commits considered: $commitCount"
+    }
+
+    return $lines
+}
+
+function Get-NovaVersionUpdateResultTargetLine {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
+
+    $projectFile = Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'ProjectFile'
+    if (-not [string]::IsNullOrWhiteSpace($projectFile)) {
+        return "Version file: $projectFile"
+    }
+
+    $target = Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'Target'
+    if (-not [string]::IsNullOrWhiteSpace($target)) {
+        return "Version file: $target"
     }
 
-    return $Result.AdvisoryMessage
+    return $null
 }
 
+function Get-NovaVersionUpdateResultLabelText {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
 
+    $effectiveLabel = [string](Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'EffectiveLabel')
+    $detectedLabel = [string](Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'Label')
+    if ($effectiveLabel -eq $detectedLabel) {
+        return @("Release label: $effectiveLabel")
+    }
+
+    return @(
+        "Detected release label: $detectedLabel"
+        "Applied release label: $effectiveLabel"
+    )
+}
+
+function Get-NovaVersionUpdateResultNextStepText {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
+
+    if ([bool](Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'Cancelled')) {
+        return @(
+            'Next step:'
+            'Run Update-NovaModuleVersion again when you are ready to write the new version to project.json.'
+        )
+    }
+
+    if ([bool](Get-NovaVersionUpdateResultPropertyValue -Result $Result -Name 'Previewed')) {
+        return @(
+            'Next step:'
+            'Run Update-NovaModuleVersion without -WhatIf when you are ready to apply the version change.'
+        )
+    }
+
+    return @(
+        'Next step:'
+        'Invoke-NovaBuild'
+    )
+}
+
+function Get-NovaVersionUpdateResultPropertyValue {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result,
+        [Parameter(Mandatory)][string]$Name
+    )
+
+    $property = $Result.PSObject.Properties[$Name]
+    if ($null -eq $property) {
+        return $null
+    }
+
+    return $property.Value
+}