Enhance Nova CLI commands with improved feedback and error handling (#236)

* fix(#215): restore deploy help related links

* fix(#215): close raw upload coverage gaps

* #215 fix: nomalize command help related links

* #215 fix(#217): clarify update notification perference status

* #215 feat: enhance scaffold feedback and error handling in Initialize-NovaModule

* #215 feat: enhance Invoke-NovaAgenticCopilotScaffold with progress feedback and clearer cancellation guidance

* #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

* #215 feat: enhance Invoke-NovaCli command handling with improved help and error messages
refactor(Invoke-NovaCli): align with terminal-ux-design principles
Fixes #222

* #215 feat: enhance Invoke-NovaRelease with progress reporting and next-step guidance
refactor(Invoke-NovaRelease): align with terminal-ux-design principles
Fixes #223

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

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

* #215 feat: enhance Publish-NovaModule with progress reporting and next-step guidance
refactor(Publish-NovaModule): align with terminal-ux-design principles
Fixes #225

* #215 feat: enhance Set-NovaUpdateNotificationPreference with WhatIf support and improved messaging
refactor(Set-NovaUpdateNotificationPreference): align with terminal-ux-design principles
Fixes #226

* #215 feat: enhance Test-NovaBuild with progress reporting and actionable guidance in WhatIf mode
refactor(Test-NovaBuild): align with terminal-ux-design principles
Fixes #227

* #215 feat: enhance Update-NovaModuleTool with improved workflow and WhatIf support
refactor(Update-NovaModuleTools): align with terminal-ux-design principles
Fixes #228

* #215 feat: enhance version update workflow with progress reporting and detailed summaries
refactor(Update-NovaModuleVersion): align with terminal-ux-design principles
Fixes #229

* #215 feat: add tests for NovaPackage and NovaTest workflows, enhancing coverage and status messaging

Author: stiwicourage

CHANGELOG.md

@@ -21,6 +21,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `Get-NovaProjectInfo` now fails with clearer recovery guidance when `-Path` does not exist, points to a file, or the target folder is missing `project.json`.
 - `Get-NovaUpdateNotificationPreference -Verbose` now explains whether Nova is reading a stored preference or the built-in default, and the command help now points read-only PowerShell users to the matching `% nova notification` workflow.
 - `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.
+- `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.
+- `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

@@ -17,6 +17,17 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `Get-NovaProjectInfo` now explains how to recover when `-Path` is invalid or the target folder is not a Nova project root.
 - `Get-NovaUpdateNotificationPreference -Verbose` now tells you whether Nova is using a stored update-notification preference or the built-in default, and the help now points to the matching `% nova notification` workflow.
 - `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.
+- `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.
+- `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/Install-NovaCli.md

@@ -30,7 +30,8 @@ PS> Install-NovaCli [[-DestinationDirectory] <string>] [-Force] [-WhatIf] [-Conf
 By default, the launcher is installed to `~/.local/bin/nova` on macOS and Linux. If that directory is not on your
 `PATH`, the command warns so you can update your shell profile.
 
-After a successful install, `Install-NovaCli` also prints the release notes link from the installed module manifest.
+After a successful install, `Install-NovaCli` prints the installed launcher path, suggests the next command to run,
+and also prints the release notes link from the installed module manifest.
 
 Use this command when you want `nova` to be available directly from your shell as the launcher-oriented CLI entrypoint.
 
@@ -168,8 +169,13 @@ Returns the installed command name, destination directory, installed path, and w
 
 ## NOTES
 
-After running `Install-NovaCli`, add the destination directory to your shell `PATH` if needed.
+`Install-NovaCli` currently supports macOS and Linux. On Windows, use `Invoke-NovaCli` from `pwsh` after importing
+NovaModuleTools.
+
+After running `Install-NovaCli`, add the destination directory to your shell `PATH` if needed, start a new shell,
+and then run `nova --help` to confirm the launcher is available.
 
 ## RELATED LINKS
 
+- [Update-NovaModuleTool](./Update-NovaModuleTools.md)
 - [Publish-NovaModule](./Publish-NovaModule.md)

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

@@ -34,6 +34,8 @@ By default the workflow shows an overwrite warning before it updates the managed
 
 The target path must contain a valid `project.json`. Invalid project metadata or an invalid short name stops the command with a clear validation error.
 
+During apply or refresh, Nova shows progress for the main scaffold phases and ends with the project root plus the next suggested review and validation steps.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
@@ -201,6 +203,8 @@ This workflow does not persist `ShortName` to `project.json` and does not infer
 
 `README.md`, `CHANGELOG.md`, and `RELEASE_NOTE.md` are created only when they are missing.
 
+Press `Ctrl+C` before confirming the overwrite warning if you want to cancel the apply without changing files.
+
 ## RELATED LINKS
 
 - [Initialize-NovaModule](./Initialize-NovaModule.md)

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)

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

@@ -0,0 +1,191 @@
+---
+document type: cmdlet
+external help file: NovaModuleTools-Help.xml
+HelpUri: ''
+Locale: en-US
+Module Name: NovaModuleTools
+ms.date: 05/24/2026
+PlatyPS schema version: 2024-05-01
+title: Invoke-NovaCli
+---
+
+# Invoke-NovaCli
+
+## SYNOPSIS
+
+Runs Nova's launcher-style command routing from PowerShell.
+
+## SYNTAX
+
+### __AllParameterSets
+
+```text
+PS> Invoke-NovaCli [[-Command] <string>] [[-Arguments] <string[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+`Invoke-NovaCli` is the PowerShell entrypoint behind the launcher-style `nova <command>` workflow.
+
+Use this cmdlet when you want Nova's routed CLI experience from inside PowerShell, including root help, per-command help, and the routed command surfaces such as `build`, `test`, `package`, `publish`, `release`, `update`, and `notification`.
+
+When `-Command` is omitted or blank, Nova falls back to the root CLI help.
+
+This cmdlet forwards `-WhatIf` and `-Confirm` semantics to the routed command surface instead of treating `Invoke-NovaCli` itself as the mutating operation owner.
+
+Use `Get-Help Invoke-NovaCli -Full` when you want the PowerShell wrapper help. Use `nova --help`, `nova <command> --help`, or `nova --help <command>` when you want launcher-native CLI help.
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+```text
+PS> Invoke-NovaCli
+```
+
+Shows the root Nova CLI help.
+
+### EXAMPLE 2
+
+```text
+PS> Invoke-NovaCli build --help
+```
+
+Shows the short help for the routed `build` command by using launcher-style arguments from PowerShell.
+
+### EXAMPLE 3
+
+```text
+PS> Invoke-NovaCli --help build
+```
+
+Shows the long help for the routed `build` command.
+
+### EXAMPLE 4
+
+```text
+PS> Invoke-NovaCli publish --repository PSGallery --api-key <key> -WhatIf
+```
+
+Previews the routed publish workflow without changing files or publishing artifacts.
+
+## PARAMETERS
+
+### -Arguments
+
+Pass the remaining launcher-style arguments for the routed command.
+
+Use CLI syntax here, for example `--help`, `--verbose`, `--what-if`, or route-specific flags such as `--repository`.
+
+```yaml
+Type: System.String[]
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+  - Name: (All)
+    Position: 1
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: true
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### -Command
+
+Choose the routed Nova command to run, for example `build`, `test`, `package`, `publish`, `release`, `notification`, `update`, or the root help/version forms such as `--help` and `--version`.
+
+When this parameter is omitted or blank, Nova shows the root CLI help.
+
+```yaml
+Type: System.String
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+  - Name: (All)
+    Position: 0
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### -Confirm
+
+Forward confirmation behavior to routed mutating commands that support Nova's CLI confirmation flow.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: ''
+SupportsWildcards: false
+Aliases:
+  - cf
+ParameterSets:
+  - Name: (All)
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### -WhatIf
+
+Forward preview behavior to routed commands that support Nova's non-destructive preview flow.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: ''
+SupportsWildcards: false
+Aliases:
+  - wi
+ParameterSets:
+  - Name: (All)
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+You can't pipe objects to this cmdlet.
+
+## OUTPUTS
+
+### System.Object
+
+This cmdlet returns the routed command result or CLI help text for help and version requests.
+
+## NOTES
+
+`Invoke-NovaCli` is a PowerShell wrapper around Nova's launcher-style command routing. The routed command surfaces keep CLI syntax such as `--help`, `--verbose`, and `--what-if`.
+
+Use `Ctrl+C` if you need to cancel a running routed workflow.
+
+## RELATED LINKS
+
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)
+- [Test-NovaBuild](./Test-NovaBuild.md)
+- [Install-NovaCli](./Install-NovaCli.md)
+- [NovaModuleTools Module](./NovaModuleTools.md)

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

@@ -57,6 +57,8 @@ When local release mode is selected, the resolved local publish target is previe
 
 This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the entire release workflow and resolved publish target without building, testing, versioning, or publishing.
 
+During the workflow, Nova shows progress for the main release phases. When the workflow completes, Nova prints the publish target and a short next-step hint. In `-WhatIf` mode, Nova ends with a release-plan summary instead of a release-complete message.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
@@ -323,6 +325,8 @@ When `-ContinuousIntegration` is used, the release workflow restores the built `
 `Invoke-NovaRelease` uses `SupportsShouldProcess`, so `Get-Help Invoke-NovaRelease -Full` surfaces native `-WhatIf`
 and `-Confirm` support.
 
+Use `Ctrl+C` if you need to stop a running release before all phases complete.
+
 ## RELATED LINKS
 
 - [Invoke-NovaBuild](./Invoke-NovaBuild.md)

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)

docs/NovaModuleTools/en-US/NovaModuleTools.md

@@ -32,6 +32,10 @@ Shows whether prerelease update notifications are enabled. Stable release notifi
 
 Installs the bundled command-line launcher into a user command directory on macOS or Linux.
 
+### `PS> Invoke-NovaCli`
+
+Runs Nova's launcher-style command routing from inside PowerShell.
+
 ### `PS> Invoke-NovaBuild`
 
 Builds the current NovaModuleTools project into a ready-to-import PowerShell module.

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)