#215 feat: enhance Publish-NovaModule with progress reporting and next-step guidance

stiwicourage · stiwicourage · commit ea1763cd9de2 · 2026-05-24T15:38:31.000+02:00
refactor(Publish-NovaModule): align with terminal-ux-design principles Fixes #225
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -27,6 +27,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `Invoke-NovaCli` now treats blank command input as root help, reports unknown commands with clearer recovery guidance, and ships a dedicated PlatyPS help topic for the PowerShell wrapper surface.
 - `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.
 
 ### Deprecated
 
diff --git a/RELEASE_NOTE.md b/RELEASE_NOTE.md
@@ -23,6 +23,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `Invoke-NovaCli` now treats blank command input as root help, reports unknown commands with clearer recovery guidance, and ships a dedicated help topic for the PowerShell wrapper surface.
 - `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.
 
 ### Deprecated
 
diff --git a/docs/NovaModuleTools/en-US/Publish-NovaModule.md b/docs/NovaModuleTools/en-US/Publish-NovaModule.md
@@ -45,10 +45,12 @@ Use `-ContinuousIntegration` when the same CI/self-hosting session should switch
 Use `-OverrideWarning` only when you intentionally want the nested build to continue even though a file under
 `src/public` contains zero or multiple top-level functions.
 
-This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the resolved publish target and workflow without building, testing, or publishing.
+This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` when you want the normal build-validation flow to run but the nested publish step to stay in preview mode.
 
 Use `-Confirm` when you want PowerShell to prompt before the publish workflow starts.
 
+During a publish run, Nova shows progress for the build-validation phase, the publish phase, the local import phase when applicable, and the CI restore phase when `-ContinuousIntegration` is used. When the run completes, Nova prints the publish target together with the next suggested verification step. In `-WhatIf` mode, Nova ends with a publish-plan summary instead of a publish-completed summary.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
@@ -89,7 +91,7 @@ Prompts before the repository publish workflow starts.
 PS> Publish-NovaModule -Local -WhatIf
 ```
 
-Previews the local publish workflow and target directory without making changes. No module copy or import happens when `-WhatIf` is used.
+Runs the normal build-validation flow, then previews the local publish target directory without copying or importing the module.
 
 ### EXAMPLE 6
 
@@ -300,6 +302,8 @@ When `-ContinuousIntegration` is used, Nova restores the built `dist/` module af
 `Publish-NovaModule` uses `SupportsShouldProcess`, so `Get-Help Publish-NovaModule -Full` should surface native
 `-WhatIf` and `-Confirm` support.
 
+Use `Ctrl+C` if you need to stop a running publish workflow before the publish step finishes.
+
 ## RELATED LINKS
 
 - [Invoke-NovaBuild](./Invoke-NovaBuild.md)
diff --git a/src/private/release/InvokeNovaPublishWorkflow.ps1 b/src/private/release/InvokeNovaPublishWorkflow.ps1
@@ -8,6 +8,15 @@ function Test-NovaPublishWorkflowShouldImportLocalModule {
     return $ShouldRun -and $null -ne $WorkflowContext.LocalPublishActivation
 }
 
+function Test-NovaPublishWorkflowWhatIfEnabled {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    return $WorkflowContext.WorkflowParams.ContainsKey('WhatIf') -and $WorkflowContext.WorkflowParams.WhatIf
+}
+
 function Invoke-NovaPublishWorkflowCiRestore {
     [CmdletBinding()]
     param(
@@ -22,6 +31,19 @@ function Invoke-NovaPublishWorkflowCiRestore {
     }
 }
 
+function Invoke-NovaPublishWorkflowStep {
+    [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 Invoke-NovaPublishWorkflow {
     [CmdletBinding()]
     param(
@@ -32,20 +54,140 @@ function Invoke-NovaPublishWorkflow {
     $publishParams = $WorkflowContext.PublishParams
     $continuousIntegrationRequested = ($WorkflowContext.PSObject.Properties.Name -contains 'ContinuousIntegrationRequested') -and $WorkflowContext.ContinuousIntegrationRequested
     $shouldImportPublishedLocalModule = Test-NovaPublishWorkflowShouldImportLocalModule -WorkflowContext $WorkflowContext -ShouldRun:$ShouldRun
-    $ciRestoreAction = ${function:Invoke-NovaPublishWorkflowCiRestore}
-    $importBuiltModuleForCiAction = ${function:Import-NovaBuiltModuleForCi}
+    $whatIfEnabled = Test-NovaPublishWorkflowWhatIfEnabled -WorkflowContext $WorkflowContext
+    $progressActivity = 'Running Nova publish workflow'
+    $importedLocalModule = $false
+    $restoredBuiltModule = $false
+
+    try {
+        Invoke-NovaPublishWorkflowStep -Activity $progressActivity -Status (Get-NovaPublishWorkflowValidationStatus -WorkflowContext $WorkflowContext) -PercentComplete 35 -Action {
+            Invoke-NovaBuildValidation -WorkflowContext $WorkflowContext
+        }
+
+        Invoke-NovaPublishWorkflowStep -Activity $progressActivity -Status (Get-NovaPublishWorkflowPublishStatus -WorkflowContext $WorkflowContext -WhatIfEnabled:$whatIfEnabled) -PercentComplete 75 -Action {
+            & $WorkflowContext.PublishInvocation.Action @publishParams
+        }
+
+        if ($shouldImportPublishedLocalModule) {
+            Invoke-NovaPublishWorkflowStep -Activity $progressActivity -Status 'Importing the published local module' -PercentComplete 90 -Action {
+                $null = & $WorkflowContext.LocalPublishActivation.ImportAction -ProjectName $WorkflowContext.PublishInvocation.Parameters.ProjectInfo.ProjectName -ManifestPath $WorkflowContext.LocalPublishActivation.ManifestPath
+            }
+            $importedLocalModule = $true
+            Write-Verbose "Module copy to local path complete and imported from $( $WorkflowContext.LocalPublishActivation.ManifestPath )"
+        }
+
+        if ($ShouldRun -and $continuousIntegrationRequested) {
+            Invoke-NovaPublishWorkflowStep -Activity $progressActivity -Status 'Refreshing the current session with the built module' -PercentComplete 98 -Action {
+                $null = Import-NovaBuiltModuleForCi -ProjectInfo $WorkflowContext.ProjectInfo
+            }
+            $restoredBuiltModule = $true
+        }
+    } finally {
+        Write-Progress -Activity $progressActivity -Completed
+    }
 
-    Invoke-NovaBuildValidation -WorkflowContext $WorkflowContext
+    Write-NovaPublishWorkflowResult -WorkflowContext $WorkflowContext -WhatIfEnabled:$whatIfEnabled -ImportedLocalModule:$importedLocalModule -RestoredBuiltModule:$restoredBuiltModule
+}
 
-    & $WorkflowContext.PublishInvocation.Action @publishParams
+function Get-NovaPublishWorkflowValidationStatus {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
 
-    if (-not $shouldImportPublishedLocalModule) {
-        & $ciRestoreAction -WorkflowContext $WorkflowContext -ShouldRun:$ShouldRun -ContinuousIntegrationRequested:$continuousIntegrationRequested -ImportBuiltModuleForCiAction $importBuiltModuleForCiAction
-        return
+    if ($WorkflowContext.SkipTestsRequested) {
+        return 'Building publish output with tests skipped'
     }
 
-    $null = & $WorkflowContext.LocalPublishActivation.ImportAction -ProjectName $WorkflowContext.PublishInvocation.Parameters.ProjectInfo.ProjectName -ManifestPath $WorkflowContext.LocalPublishActivation.ManifestPath
-    Write-Verbose "Module copy to local path complete and imported from $( $WorkflowContext.LocalPublishActivation.ManifestPath )"
+    return 'Building and testing publish output'
+}
 
-    & $ciRestoreAction -WorkflowContext $WorkflowContext -ShouldRun:$ShouldRun -ContinuousIntegrationRequested:$continuousIntegrationRequested -ImportBuiltModuleForCiAction $importBuiltModuleForCiAction
+function Get-NovaPublishWorkflowPublishStatus {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled
+    )
+
+    $targetDescription = if ($WorkflowContext.PublishInvocation.IsLocal) {
+        'the local module path'
+    } else {
+        "repository $( $WorkflowContext.PublishInvocation.Target )"
+    }
+
+    if ($WhatIfEnabled) {
+        return "Previewing publish to $targetDescription"
+    }
+
+    return "Publishing to $targetDescription"
+}
+
+function Write-NovaPublishWorkflowResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled,
+        [switch]$ImportedLocalModule,
+        [switch]$RestoredBuiltModule
+    )
+
+    Write-Message (Get-NovaPublishWorkflowStatusMessage -WorkflowContext $WorkflowContext -WhatIfEnabled:$WhatIfEnabled) -color Green
+    Write-Message "Publish target: $( $WorkflowContext.PublishInvocation.Target )"
+
+    if ($WorkflowContext.SkipTestsRequested) {
+        Write-Message 'Pre-publish tests were skipped for this run.'
+    }
+
+    if ($ImportedLocalModule) {
+        Write-Message "The published local module is loaded from $( $WorkflowContext.LocalPublishActivation.ManifestPath )."
+    }
+
+    if ($RestoredBuiltModule) {
+        Write-Message 'The freshly built dist module is loaded again for later commands in this session.'
+    }
+
+    foreach ($line in (Get-NovaPublishWorkflowNextStepLine -WorkflowContext $WorkflowContext -WhatIfEnabled:$WhatIfEnabled)) {
+        Write-Message $line
+    }
+}
+
+function Get-NovaPublishWorkflowStatusMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return "Publish plan ready for $( $WorkflowContext.ProjectInfo.ProjectName )"
+    }
+
+    return "Published Nova module: $( $WorkflowContext.ProjectInfo.ProjectName )"
+}
+
+function Get-NovaPublishWorkflowNextStepLine {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return @(
+            'Next step:'
+            'Run Publish-NovaModule without -WhatIf when you are ready to publish the module.'
+        )
+    }
+
+    if ($WorkflowContext.PublishInvocation.IsLocal) {
+        return @(
+            'Next step:'
+            'Get-NovaProjectInfo -Installed'
+        )
+    }
+
+    return @(
+        'Next step:'
+        "Find-Module $( $WorkflowContext.ProjectInfo.ProjectName ) -Repository $( $WorkflowContext.PublishInvocation.Target )"
+    )
 }
diff --git a/tests/private/release/InvokeNovaPublishWorkflow.TestSupport.ps1 b/tests/private/release/InvokeNovaPublishWorkflow.TestSupport.ps1
@@ -0,0 +1,27 @@
+function Import-NovaBuiltModuleForCi {
+    param($ProjectInfo)
+
+    $script:ciImportCalls += 1
+}
+
+function Invoke-NovaBuildValidation {
+    param($WorkflowContext)
+
+    $script:validationCalls += 1
+}
+
+function Write-Message {
+    param(
+        [string]$Text,
+        [string]$color
+    )
+}
+
+function Write-Progress {
+    param(
+        [string]$Activity,
+        [string]$Status,
+        [int]$PercentComplete,
+        [switch]$Completed
+    )
+}
diff --git a/tests/private/release/InvokeNovaPublishWorkflow.Tests.ps1 b/tests/private/release/InvokeNovaPublishWorkflow.Tests.ps1
@@ -1,8 +1,7 @@
 BeforeAll {
     $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
     . (Join-Path $projectRoot 'src/private/release/InvokeNovaPublishWorkflow.ps1')
-    function Import-NovaBuiltModuleForCi {param($ProjectInfo) $script:ciImportCalls += 1}
-    function Invoke-NovaBuildValidation {param($WorkflowContext) $script:validationCalls += 1}
+    . (Join-Path $PSScriptRoot 'InvokeNovaPublishWorkflow.TestSupport.ps1')
 }
 
 Describe 'Test-NovaPublishWorkflowShouldImportLocalModule' {
@@ -20,6 +19,18 @@ Describe 'Test-NovaPublishWorkflowShouldImportLocalModule' {
     }
 }
 
+Describe 'Test-NovaPublishWorkflowWhatIfEnabled' {
+    It 'returns true when WorkflowParams.WhatIf is enabled' {
+        $ctx = [pscustomobject]@{WorkflowParams = @{WhatIf = $true}}
+        Test-NovaPublishWorkflowWhatIfEnabled -WorkflowContext $ctx | Should -BeTrue
+    }
+
+    It 'returns false when WorkflowParams.WhatIf is not enabled' {
+        $ctx = [pscustomobject]@{WorkflowParams = @{}}
+        Test-NovaPublishWorkflowWhatIfEnabled -WorkflowContext $ctx | Should -BeFalse
+    }
+}
+
 Describe 'Invoke-NovaPublishWorkflowCiRestore' {
     It 'invokes the importer when ShouldRun and CI requested' {
         $script:calls = 0
@@ -41,39 +52,99 @@ Describe 'Invoke-NovaPublishWorkflow' {
         $script:publishCalls = 0
         $script:localImportCalls = 0
         $script:ciImportCalls = 0
+        Mock Write-Message {}
+        Mock Write-Progress {}
     }
 
-    It 'runs validation and publish; skips local import when activation is null' {
+    It 'runs validation and publish, reports progress, and suggests how to verify repository publish' {
         Mock Invoke-NovaBuildValidation {$script:validationCalls += 1}
         $ctx = [pscustomobject]@{
             PublishParams = @{}
-            PublishInvocation = [pscustomobject]@{Action = {param() $script:publishCalls += 1}}
+            PublishInvocation = [pscustomobject]@{Action = {param() $script:publishCalls += 1}; Target = 'PSGallery'; IsLocal = $false}
             LocalPublishActivation = $null
-            ProjectInfo = [pscustomobject]@{}
+            ProjectInfo = [pscustomobject]@{ProjectName = 'NovaModuleTools'}
+            WorkflowParams = @{}
+            SkipTestsRequested = $false
             ContinuousIntegrationRequested = $false
         }
         Invoke-NovaPublishWorkflow -WorkflowContext $ctx -ShouldRun
         $script:validationCalls | Should -Be 1
         $script:publishCalls | Should -Be 1
         $script:localImportCalls | Should -Be 0
+        Assert-MockCalled Write-Progress -Times 3
+        Assert-MockCalled Write-Message -Times 4
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Published Nova module: NovaModuleTools' -and $color -eq 'Green'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Find-Module NovaModuleTools -Repository PSGallery'
+        }
     }
 
-    It 'imports local published module when LocalPublishActivation is set' {
+    It 'imports the local published module, restores the built module in CI, and reports the result' {
         Mock Invoke-NovaBuildValidation {$script:validationCalls += 1}
         $ctx = [pscustomobject]@{
             PublishParams = @{}
             PublishInvocation = [pscustomobject]@{
                 Action = {param() $script:publishCalls += 1}
+                IsLocal = $true
+                Target = '/modules'
                 Parameters = [pscustomobject]@{ProjectInfo = [pscustomobject]@{ProjectName='Mod'}}
             }
             LocalPublishActivation = [pscustomobject]@{
                 ManifestPath='/m/Mod.psd1'
                 ImportAction = {param($ProjectName,$ManifestPath) $script:localImportCalls += 1}
             }
-            ProjectInfo = [pscustomobject]@{}
-            ContinuousIntegrationRequested = $false
+            ProjectInfo = [pscustomobject]@{ProjectName = 'Mod'}
+            WorkflowParams = @{}
+            SkipTestsRequested = $true
+            ContinuousIntegrationRequested = $true
         }
         Invoke-NovaPublishWorkflow -WorkflowContext $ctx -ShouldRun
         $script:localImportCalls | Should -Be 1
+        $script:ciImportCalls | Should -Be 1
+        Assert-MockCalled Write-Progress -Times 5
+        Assert-MockCalled Write-Message -Times 6
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Pre-publish tests were skipped for this run.'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'The published local module is loaded from /m/Mod.psd1.'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'The freshly built dist module is loaded again for later commands in this session.'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Get-NovaProjectInfo -Installed'
+        }
+    }
+
+    It 'writes a publish plan summary in WhatIf mode without importing or restoring modules' {
+        Mock Invoke-NovaBuildValidation {$script:validationCalls += 1}
+        $ctx = [pscustomobject]@{
+            PublishParams = @{WhatIf = $true}
+            PublishInvocation = [pscustomobject]@{Action = {param() $script:publishCalls += 1}; Target = 'PSGallery'; IsLocal = $false}
+            LocalPublishActivation = [pscustomobject]@{
+                ManifestPath='/m/Mod.psd1'
+                ImportAction = {param($ProjectName,$ManifestPath) $script:localImportCalls += 1}
+            }
+            ProjectInfo = [pscustomobject]@{ProjectName = 'NovaModuleTools'}
+            WorkflowParams = @{WhatIf = $true}
+            SkipTestsRequested = $false
+            ContinuousIntegrationRequested = $true
+        }
+
+        Invoke-NovaPublishWorkflow -WorkflowContext $ctx
+
+        $script:publishCalls | Should -Be 1
+        $script:localImportCalls | Should -Be 0
+        $script:ciImportCalls | Should -Be 0
+        Assert-MockCalled Write-Message -Times 4
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Publish plan ready for NovaModuleTools' -and $color -eq 'Green'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Run Publish-NovaModule without -WhatIf when you are ready to publish the module.'
+        }
     }
 }
