#215 feat: enhance Invoke-NovaBuild with progress reporting and next steps guidance

Closes refactor(Install-NovaCli): align with terminal-ux-design principles
Fixes #219
Closes refactor(Invoke-NovaAgenticCopilotScaffold): align with terminal-ux-design principles
Fixes #220
Closes refactor(Invoke-NovaBuild): align with terminal-ux-design principles
Fixes #221

Author: stiwicourage

CHANGELOG.md

@@ -23,6 +23,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `Initialize-NovaModule` now shows scaffold progress, ends with the created project root plus the next suggested cmdlet, and fails with clearer guidance when the target project folder already exists.
 - `Install-NovaCli` now prints the installed launcher path, suggests the next command to run, and gives a clearer `PATH` warning when the destination directory is not yet available from the shell.
 - `Invoke-NovaAgenticCopilotScaffold` now shows apply progress, ends with the project root plus suggested review and validation steps, and fails with clearer cancellation guidance when the overwrite warning is declined.
+- `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.
 
 ### Deprecated
 

RELEASE_NOTE.md

@@ -19,6 +19,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `Initialize-NovaModule` now shows scaffold progress, ends with the project root and the next suggested cmdlet, and gives clearer recovery guidance when the target project folder already exists.
 - `Install-NovaCli` now prints the installed launcher path, suggests the next command to run, and gives a clearer `PATH` warning when the launcher directory is not yet available from the shell.
 - `Invoke-NovaAgenticCopilotScaffold` now shows apply progress, ends with the project root plus suggested review and validation steps, and gives clearer cancellation guidance when the overwrite warning is declined.
+- `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.
 
 ### Deprecated
 

docs/NovaModuleTools/en-US/Invoke-NovaBuild.md

@@ -29,6 +29,8 @@ PS> Invoke-NovaBuild [-ContinuousIntegration] [-OverrideWarning] [-WhatIf] [-Con
 
 This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the build target without clearing `dist/` or generating new build output.
 
+During a real build, Nova shows progress for the main build phases and ends with the output module directory plus the next suggested validation step.
+
 Use `-ContinuousIntegration` when the same PowerShell session needs to keep using the freshly built `dist/` module after the build completes. In CI/self-hosting flows, that re-activates the built module before the command returns.
 
 Use `-OverrideWarning` only when you intentionally want to continue a build even though a file under `src/public`
@@ -62,15 +64,15 @@ If `Preamble` is configured, those lines are written at the very top of the gene
 PS> Invoke-NovaBuild
 ```
 
-Builds the current project into `dist/<ProjectName>/`.
+Builds the current project into `dist/<ProjectName>/`, prints the output module directory, and suggests `Test-NovaBuild` as the next validation step.
 
 ### EXAMPLE 2
 
 ```text
 PS> Invoke-NovaBuild -Verbose
 ```
 
-Builds the current project and writes verbose progress for the build workflow.
+Builds the current project, shows phase progress for the build workflow, and writes verbose details from the underlying build helpers.
 
 ### EXAMPLE 3
 
@@ -172,6 +174,8 @@ When `-ContinuousIntegration` is used together with a real build, the command re
 
 Files under `src/public` are expected to contain exactly one top-level function each. Use `-OverrideWarning` only when you intentionally want to bypass that guard for the current build.
 
+Use `Ctrl+C` if you need to stop a running build before all phases complete.
+
 ## RELATED LINKS
 
 - [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)

src/private/build/InvokeNovaBuildWorkflow.ps1

@@ -7,19 +7,81 @@ function Invoke-NovaBuildWorkflow {
     $projectInfo = $WorkflowContext.ProjectInfo
     $continuousIntegrationRequested = ($WorkflowContext.PSObject.Properties.Name -contains 'ContinuousIntegrationRequested') -and $WorkflowContext.ContinuousIntegrationRequested
     $overrideWarningRequested = ($WorkflowContext.PSObject.Properties.Name -contains 'OverrideWarningRequested') -and $WorkflowContext.OverrideWarningRequested
+    $progressActivity = 'Building Nova module'
 
-    Assert-NovaPublicFunctionFileLayout -ProjectInfo $projectInfo -OverrideWarningRequested:$overrideWarningRequested
-    Reset-ProjectDist -ProjectInfo $projectInfo -Confirm:$false
-    Build-Module -ProjectInfo $projectInfo
-    Invoke-NovaBuildDuplicateValidation -ProjectInfo $projectInfo
-    Build-Manifest -ProjectInfo $projectInfo
-    Build-Help -ProjectInfo $projectInfo
-    Copy-ProjectResource -ProjectInfo $projectInfo
-    Invoke-NovaModuleUpdateNotificationSafely
-
-    if ($continuousIntegrationRequested) {
-        $null = Import-NovaBuiltModuleForCi -ProjectInfo $projectInfo
+    try {
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Validating public command layout' -PercentComplete 10 -Action {
+            Assert-NovaPublicFunctionFileLayout -ProjectInfo $projectInfo -OverrideWarningRequested:$overrideWarningRequested
+        }
+
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Resetting dist output' -PercentComplete 20 -Action {
+            Reset-ProjectDist -ProjectInfo $projectInfo -Confirm:$false
+        }
+
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Building module output' -PercentComplete 35 -Action {
+            Build-Module -ProjectInfo $projectInfo
+        }
+
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Validating duplicate function names' -PercentComplete 50 -Action {
+            Invoke-NovaBuildDuplicateValidation -ProjectInfo $projectInfo
+        }
+
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Writing module manifest' -PercentComplete 65 -Action {
+            Build-Manifest -ProjectInfo $projectInfo
+        }
+
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Building command help' -PercentComplete 78 -Action {
+            Build-Help -ProjectInfo $projectInfo
+        }
+
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Copying project resources' -PercentComplete 88 -Action {
+            Copy-ProjectResource -ProjectInfo $projectInfo
+        }
+
+        Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Checking update notifications' -PercentComplete 94 -Action {
+            Invoke-NovaModuleUpdateNotificationSafely
+        }
+
+        if ($continuousIntegrationRequested) {
+            Invoke-NovaBuildWorkflowStep -Activity $progressActivity -Status 'Refreshing the current session with the built module' -PercentComplete 98 -Action {
+                $null = Import-NovaBuiltModuleForCi -ProjectInfo $projectInfo
+            }
+        }
+    } finally {
+        Write-Progress -Activity $progressActivity -Completed
     }
+
+    Write-NovaBuildWorkflowResult -ProjectInfo $projectInfo -ContinuousIntegrationRequested:$continuousIntegrationRequested
+}
+
+function Invoke-NovaBuildWorkflowStep {
+    [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-NovaBuildWorkflowResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$ProjectInfo,
+        [switch]$ContinuousIntegrationRequested
+    )
+
+    Write-Message "Built Nova module: $( $ProjectInfo.ProjectName )" -color Green
+    Write-Message "Output module: $( $ProjectInfo.OutputModuleDir )"
+
+    if ($ContinuousIntegrationRequested) {
+        Write-Message 'The freshly built dist module is loaded for later commands in this session.'
+    }
+
+    Write-Message 'Next step: Test-NovaBuild'
 }
 
 function Invoke-NovaBuildDuplicateValidation {
@@ -34,4 +96,3 @@ function Invoke-NovaBuildDuplicateValidation {
 
     Assert-BuiltModuleHasNoDuplicateFunctionName -ProjectInfo $ProjectInfo
 }
-

tests/private/build/InvokeNovaBuildWorkflow.TestSupport.ps1

@@ -7,3 +7,4 @@ function Build-Help {param($ProjectInfo)}
 function Copy-ProjectResource {param($ProjectInfo)}
 function Invoke-NovaModuleUpdateNotificationSafely {}
 function Import-NovaBuiltModuleForCi {param($ProjectInfo)}
+function Write-Message {param([string]$Text, [string]$color)}

tests/private/build/InvokeNovaBuildWorkflow.Tests.ps1

@@ -6,7 +6,49 @@ BeforeAll {
 }
 
 Describe 'Invoke-NovaBuildWorkflow' {
-    It 'uses the shared module update notification before the optional CI import step' {
+    It 'reports progress, runs the build steps in order, and prints the next suggested validation step' {
+        $global:steps = @()
+        try {
+            $workflowContext = [pscustomobject]@{
+                ProjectInfo = [pscustomobject]@{
+                    ProjectName = 'NovaModuleTools'
+                    OutputModuleDir = '/tmp/dist/NovaModuleTools'
+                    FailOnDuplicateFunctionNames = $true
+                }
+                ContinuousIntegrationRequested = $false
+            }
+
+            Mock Assert-NovaPublicFunctionFileLayout {$global:steps += 'public-layout'}
+            Mock Reset-ProjectDist {$global:steps += 'reset'}
+            Mock Build-Module {$global:steps += 'module'}
+            Mock Assert-BuiltModuleHasNoDuplicateFunctionName {$global:steps += 'duplicates'}
+            Mock Build-Manifest {$global:steps += 'manifest'}
+            Mock Build-Help {$global:steps += 'help'}
+            Mock Copy-ProjectResource {$global:steps += 'resources'}
+            Mock Invoke-NovaModuleUpdateNotificationSafely {$global:steps += 'notification'}
+            Mock Import-NovaBuiltModuleForCi {$global:steps += 'ci'}
+            Mock Write-Message {}
+            Mock Write-Progress {}
+
+            Invoke-NovaBuildWorkflow -WorkflowContext $workflowContext
+
+            $global:steps -join ',' | Should -Be 'public-layout,reset,module,duplicates,manifest,help,resources,notification'
+            Assert-MockCalled Invoke-NovaModuleUpdateNotificationSafely -Times 1
+            Assert-MockCalled Import-NovaBuiltModuleForCi -Times 0
+            Assert-MockCalled Write-Progress -Times 9
+            Assert-MockCalled Write-Message -Times 3
+            Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+                $Text -eq 'Built Nova module: NovaModuleTools' -and $color -eq 'Green'
+            }
+            Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+                $Text -eq 'Next step: Test-NovaBuild'
+            }
+        } finally {
+            Remove-Variable -Name steps -Scope Global -ErrorAction SilentlyContinue
+        }
+    }
+
+    It 'uses the shared module update notification before the optional CI import step and reports the refreshed session' {
         $global:steps = @()
         try {
             $workflowContext = [pscustomobject]@{
@@ -27,12 +69,18 @@ Describe 'Invoke-NovaBuildWorkflow' {
             Mock Copy-ProjectResource {$global:steps += 'resources'}
             Mock Invoke-NovaModuleUpdateNotificationSafely {$global:steps += 'notification'}
             Mock Import-NovaBuiltModuleForCi {$global:steps += 'ci'}
+            Mock Write-Message {}
+            Mock Write-Progress {}
 
             Invoke-NovaBuildWorkflow -WorkflowContext $workflowContext
 
             $global:steps -join ',' | Should -Be 'public-layout,reset,module,duplicates,manifest,help,resources,notification,ci'
-            Assert-MockCalled Invoke-NovaModuleUpdateNotificationSafely -Times 1
             Assert-MockCalled Import-NovaBuiltModuleForCi -Times 1
+            Assert-MockCalled Write-Progress -Times 10
+            Assert-MockCalled Write-Message -Times 4
+            Assert-MockCalled Write-Message -Times 1 -ParameterFilter {
+                $Text -eq 'The freshly built dist module is loaded for later commands in this session.'
+            }
         } finally {
             Remove-Variable -Name steps -Scope Global -ErrorAction SilentlyContinue
         }