#215 feat: enhance New-NovaModulePackage with progress reporting and next-step guidance

refactor(New-NovaModulePackage): align with terminal-ux-design principles
Fixes #224

Author: stiwicourage

CHANGELOG.md

@@ -26,6 +26,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `Invoke-NovaBuild` now shows progress for the main build phases, ends with the output module directory plus the next suggested validation step, and explains the refreshed session when `-ContinuousIntegration` reloads the built module.
 - `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.
 
 ### Deprecated
 

RELEASE_NOTE.md

@@ -22,6 +22,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `Invoke-NovaBuild` now shows progress for the main build phases, ends with the output module directory plus the next suggested validation step, and explains the refreshed session when `-ContinuousIntegration` reloads the built module.
 - `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.
 
 ### Deprecated
 

docs/NovaModuleTools/en-US/New-NovaModulePackage.md

@@ -35,6 +35,8 @@ Use `-OverrideWarning` only when you intentionally want the nested build to cont
 
 The package is written to `artifacts/packages/` by default. You can override generic package metadata through the optional `Package` section in `project.json`.
 
+During a packaging run, Nova shows progress for the build-validation phase and the artifact-creation phase. When packaging completes, Nova prints the package target together with the next suggested step. In `-WhatIf` mode, Nova ends with a package-plan summary instead of a package-created summary.
+
 Use this `project.json` shape when you want to control package types and the package output directory:
 
 ```json
@@ -275,6 +277,8 @@ When `-SkipTests` is used, only `Test-NovaBuild` is skipped. Build still runs.
 
 Files under `src/public` are expected to contain exactly one top-level function each. `-OverrideWarning` bypasses that guard only for the current packaging run.
 
+Use `Ctrl+C` if you need to stop a running packaging workflow before the package artifacts are created.
+
 ## RELATED LINKS
 
 - [Invoke-NovaBuild](./Invoke-NovaBuild.md)

src/private/package/InvokeNovaPackageWorkflow.ps1

@@ -5,11 +5,140 @@ function Invoke-NovaPackageWorkflow {
         [switch]$ShouldRun
     )
 
-    Invoke-NovaBuildValidation -WorkflowContext $WorkflowContext
+    $whatIfEnabled = Test-NovaPackageWorkflowWhatIfEnabled -WorkflowContext $WorkflowContext
+    $progressActivity = 'Creating Nova package artifacts'
 
-    if (-not $ShouldRun) {
-        return
+    try {
+        Invoke-NovaPackageWorkflowStep -Activity $progressActivity -Status (Get-NovaPackageValidationStatus -WorkflowContext $WorkflowContext) -PercentComplete 30 -Action {
+            Invoke-NovaBuildValidation -WorkflowContext $WorkflowContext
+        }
+
+        if (-not $ShouldRun) {
+            if ($whatIfEnabled) {
+                Write-NovaPackageWorkflowResult -WorkflowContext $WorkflowContext -WhatIfEnabled
+            }
+
+            return
+        }
+
+        $artifacts = Invoke-NovaPackageWorkflowStep -Activity $progressActivity -Status 'Creating package artifacts' -PercentComplete 85 -Action {
+            Invoke-NovaPackageArtifactCreation -WorkflowContext $WorkflowContext
+        }
+    } finally {
+        Write-Progress -Activity $progressActivity -Completed
+    }
+
+    Write-NovaPackageWorkflowResult -WorkflowContext $WorkflowContext -Artifacts $artifacts
+    return $artifacts
+}
+
+function Invoke-NovaPackageWorkflowStep {
+    [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 Test-NovaPackageWorkflowWhatIfEnabled {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    return ($WorkflowContext.WorkflowParams.ContainsKey('WhatIf') -and $WorkflowContext.WorkflowParams.WhatIf)
+}
+
+function Get-NovaPackageValidationStatus {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
+
+    if ($WorkflowContext.SkipTestsRequested) {
+        return 'Building package input with tests skipped'
     }
 
-    return Invoke-NovaPackageArtifactCreation -WorkflowContext $WorkflowContext
+    return 'Building and testing package input'
+}
+
+function Write-NovaPackageWorkflowResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [AllowNull()][AllowEmptyCollection()][object[]]$Artifacts = @(),
+        [switch]$WhatIfEnabled
+    )
+
+    $resolvedArtifacts = @($Artifacts)
+    $statusMessage = Get-NovaPackageWorkflowStatusMessage -WorkflowContext $WorkflowContext -ArtifactCount $resolvedArtifacts.Count -WhatIfEnabled:$WhatIfEnabled
+    Write-Message $statusMessage -color Green
+    Write-Message "Package target: $( Get-NovaPackageWorkflowResultTarget -WorkflowContext $WorkflowContext -Artifacts $resolvedArtifacts -WhatIfEnabled:$WhatIfEnabled )"
+
+    foreach ($line in (Get-NovaPackageWorkflowNextStepLine -WhatIfEnabled:$WhatIfEnabled)) {
+        Write-Message $line
+    }
+}
+
+function Get-NovaPackageWorkflowStatusMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [Parameter(Mandatory)][int]$ArtifactCount,
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return "Package plan ready for $( $WorkflowContext.ProjectInfo.ProjectName )"
+    }
+
+    if ($ArtifactCount -eq 1) {
+        return "Created 1 package artifact for $( $WorkflowContext.ProjectInfo.ProjectName )"
+    }
+
+    return "Created $ArtifactCount package artifacts for $( $WorkflowContext.ProjectInfo.ProjectName )"
+}
+
+function Get-NovaPackageWorkflowResultTarget {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Artifacts,
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return $WorkflowContext.Target
+    }
+
+    $resolvedOutputDirectories = @($Artifacts | ForEach-Object OutputDirectory | Sort-Object -Unique)
+    if ($resolvedOutputDirectories.Count -eq 0) {
+        return $WorkflowContext.Target
+    }
+
+    return ($resolvedOutputDirectories -join ', ')
+}
+
+function Get-NovaPackageWorkflowNextStepLine {
+    [CmdletBinding()]
+    param(
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return @(
+            'Next step:'
+            'Run New-NovaModulePackage without -WhatIf when you are ready to create the package artifacts.'
+        )
+    }
+
+    return @(
+        'Next step:'
+        'Deploy-NovaPackage'
+    )
 }

tests/private/package/InvokeNovaPackageWorkflow.TestSupport.ps1

@@ -0,0 +1,18 @@
+function Invoke-NovaBuildValidation {
+    param($WorkflowContext)
+
+    $script:validated = $true
+}
+
+function Invoke-NovaPackageArtifactCreation {
+    param($WorkflowContext)
+
+    return @([pscustomobject]@{PackagePath = '/p'})
+}
+
+function Write-Message {
+    param(
+        [string]$Text,
+        [string]$color
+    )
+}

tests/private/package/InvokeNovaPackageWorkflow.Tests.ps1

@@ -1,29 +1,67 @@
 BeforeAll {
     $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
     . (Join-Path $projectRoot 'src/private/package/InvokeNovaPackageWorkflow.ps1')
-
-    function Invoke-NovaBuildValidation {param($WorkflowContext) $script:validated = $true}
-    function Invoke-NovaPackageArtifactCreation {param($WorkflowContext) return @([pscustomobject]@{PackagePath='/p'})}
+    . (Join-Path $PSScriptRoot 'InvokeNovaPackageWorkflow.TestSupport.ps1')
 }
 
 Describe 'Invoke-NovaPackageWorkflow' {
     BeforeEach {
         $script:validated = $false
+        Mock Write-Message {}
+        Mock Write-Progress {}
     }
 
     It 'validates the build and returns without creating artifacts when ShouldRun is false' {
         Mock Invoke-NovaPackageArtifactCreation {}
-        $result = Invoke-NovaPackageWorkflow -WorkflowContext ([pscustomobject]@{})
+        $result = Invoke-NovaPackageWorkflow -WorkflowContext ([pscustomobject]@{
+            WorkflowParams = @{}
+            SkipTestsRequested = $false
+            ProjectInfo = [pscustomobject]@{ProjectName = 'Demo'}
+            Target = '/p/Demo.1.0.0.nupkg'
+        })
         $script:validated | Should -BeTrue
         Should -Invoke Invoke-NovaPackageArtifactCreation -Times 0
+        Assert-MockCalled Write-Progress -Times 2
         $result | Should -BeNullOrEmpty
     }
 
-    It 'creates artifacts when ShouldRun is set' {
-        $artifacts = @([pscustomobject]@{PackagePath='/p'})
+    It 'creates artifacts, reports progress, and prints the next suggested step when ShouldRun is set' {
+        $artifacts = @([pscustomobject]@{PackagePath='/p/Demo.1.0.0.nupkg'; OutputDirectory='/p'})
         Mock Invoke-NovaPackageArtifactCreation {return $artifacts}
-        $result = Invoke-NovaPackageWorkflow -WorkflowContext ([pscustomobject]@{}) -ShouldRun
+        $result = Invoke-NovaPackageWorkflow -WorkflowContext ([pscustomobject]@{
+            WorkflowParams = @{}
+            SkipTestsRequested = $false
+            ProjectInfo = [pscustomobject]@{ProjectName = 'Demo'}
+            Target = '/p/Demo.1.0.0.nupkg'
+        }) -ShouldRun
         Should -Invoke Invoke-NovaPackageArtifactCreation -Times 1
+        Assert-MockCalled Write-Progress -Times 3
+        Assert-MockCalled Write-Message -Times 3
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Created 1 package artifact for Demo' -and $color -eq 'Green'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Deploy-NovaPackage'
+        }
         @($result).Count | Should -Be 1
     }
+
+    It 'writes a package plan summary in WhatIf mode' {
+        $result = Invoke-NovaPackageWorkflow -WorkflowContext ([pscustomobject]@{
+            WorkflowParams = @{WhatIf = $true}
+            SkipTestsRequested = $true
+            ProjectInfo = [pscustomobject]@{ProjectName = 'Demo'}
+            Target = '/p/Demo.1.0.0.nupkg'
+        })
+
+        $script:validated | Should -BeTrue
+        Assert-MockCalled Write-Message -Times 3
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Package plan ready for Demo' -and $color -eq 'Green'
+        }
+        Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+            $Text -eq 'Run New-NovaModulePackage without -WhatIf when you are ready to create the package artifacts.'
+        }
+        $result | Should -BeNullOrEmpty
+    }
 }