feat(#97): clean up output and result contracts for structured data (#127)

* feat(#97): clean up output and result contracts for structured data
- Enhance output structure for version updates and module installations
- Introduce ReleaseNotesUri in update workflows for better user feedback
- Refactor functions to return structured data consistently

* feat(#97): enhance CLI output and result contracts for structured data
- Add tests for formatted CLI command results
- Implement tests for version update handling with WhatIf scenarios
- Ensure release notes URI is correctly resolved in update messages

Author: stiwicourage

CHANGELOG.md

@@ -106,6 +106,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - CI bump now reuses the already activated built-module command when the current session is already running from
     `dist/`, so publish-then-bump prerelease automation can continue in the same session without losing private helper
     bindings.
+- Keep standalone `nova bump` output stable by formatting version-update results in the CLI layer instead of relying on
+  PowerShell's default object rendering.
+    - `nova bump --what-if` and `% run.ps1` now surface a predictable summary for previous version, new version, label,
+      and commit count.
 
 ### Changed
 

src/private/cli/FormatNovaCliCommandResult.ps1

@@ -13,20 +13,61 @@ function Test-NovaCliNoUpdateResult {
     return ($propertyNames -contains 'UpdateAvailable') -and ($propertyNames -contains 'CurrentVersion') -and -not $Result.UpdateAvailable
 }
 
-function Format-NovaCliCommandResult {
+function Test-NovaCliVersionUpdateResult {
     [CmdletBinding()]
     param(
         [string]$Command,
         [object]$Result
     )
 
-    if (-not (Test-NovaCliNoUpdateResult -Command $Command -Result $Result)) {
-        return $Result
+    if ($Command -ne 'bump' -or $null -eq $Result) {
+        return $false
+    }
+
+    $propertyNames = @($Result.PSObject.Properties.Name)
+    foreach ($requiredPropertyName in @('PreviousVersion', 'NewVersion', 'Label', 'CommitCount', 'Applied')) {
+        if ($propertyNames -notcontains $requiredPropertyName) {
+            return $false
+        }
+    }
+
+    return $true
+}
+
+function Format-NovaCliVersionUpdateResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Result
+    )
+
+    $summaryPrefix = if ($Result.Applied) {
+        'Version bump completed:'
     }
+    else {
+        'Version plan:'
+    }
+
+    return "$summaryPrefix $( $Result.PreviousVersion ) -> $( $Result.NewVersion ) | Label: $( $Result.Label ) | Commits: $( $Result.CommitCount )"
+}
 
-    return @(
-        "You're up to date!"
-        "$( $Result.ModuleName ) $( $Result.CurrentVersion ) is currently the newest version available."
+function Format-NovaCliCommandResult {
+    [CmdletBinding()]
+    param(
+        [string]$Command,
+        [object]$Result
     )
+
+    if (Test-NovaCliNoUpdateResult -Command $Command -Result $Result) {
+        return @(
+            "You're up to date!"
+            "$( $Result.ModuleName ) $( $Result.CurrentVersion ) is currently the newest version available."
+        )
+    }
+
+    if (Test-NovaCliVersionUpdateResult -Command $Command -Result $Result) {
+        return Format-NovaCliVersionUpdateResult -Result $Result
+    }
+
+    return $Result
 }
 

src/private/cli/InvokeNovaCliCommandRoute.ps1

@@ -64,6 +64,16 @@ function Invoke-NovaCliUpdateRouteCommand {
     Format-NovaCliCommandResult -Command $InvocationContext.Command -Result $result
 }
 
+function Invoke-NovaCliBumpRouteCommand {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$InvocationContext
+    )
+
+    $result = Invoke-NovaCliParsedCommand -InvocationContext $InvocationContext -ParserCommand 'ConvertFrom-NovaBumpCliArgument' -ActionCommand 'Update-NovaModuleVersion'
+    return Format-NovaCliCommandResult -Command $InvocationContext.Command -Result $result
+}
+
 function Invoke-NovaCliNotificationRouteCommand {
     [CmdletBinding()]
     param(
@@ -125,7 +135,7 @@ function Invoke-NovaCliCommandRoute {
             return Invoke-NovaCliInitCommand -Arguments $InvocationContext.Arguments -ForwardedParameters $mutatingCommonParameters -WhatIfEnabled:$InvocationContext.WhatIfEnabled
         }
         'bump' {
-            return Invoke-NovaCliParsedCommand -InvocationContext $InvocationContext -ParserCommand 'ConvertFrom-NovaBumpCliArgument' -ActionCommand 'Update-NovaModuleVersion'
+            return Invoke-NovaCliBumpRouteCommand -InvocationContext $InvocationContext
         }
         'update' {
             return Invoke-NovaCliUpdateRouteCommand -InvocationContext $InvocationContext

src/private/cli/InvokeNovaCliInstallWorkflow.ps1

@@ -10,12 +10,13 @@ function Invoke-NovaCliInstallWorkflow {
         Write-Warning "Installed nova to $( $WorkflowContext.TargetDirectory ), but that directory is not currently in PATH. Add it to your shell profile before using nova directly from zsh/bash."
     }
 
-    Write-NovaModuleReleaseNotesLink
+    $releaseNotesUri = Get-NovaModuleReleaseNotesUri
 
     return [pscustomobject]@{
         CommandName = 'nova'
         InstalledPath = $installedPath
         DestinationDirectory = $WorkflowContext.TargetDirectory
         DirectoryOnPath = $directoryOnPath
+        ReleaseNotesUri = $releaseNotesUri
     }
 }

src/private/release/InvokeNovaVersionUpdateWorkflow.ps1

@@ -6,15 +6,16 @@ function Invoke-NovaVersionUpdateWorkflow {
         [switch]$WhatIfEnabled
     )
 
+    $versionWriteResult = $null
     if ($ShouldRun) {
-        Set-NovaModuleVersion -ProjectInfo $WorkflowContext.ProjectInfo -Label $WorkflowContext.Label -PreviewRelease:$WorkflowContext.PreviewRelease -Confirm:$false
+        $versionWriteResult = Set-NovaModuleVersion -ProjectInfo $WorkflowContext.ProjectInfo -Label $WorkflowContext.Label -PreviewRelease:$WorkflowContext.PreviewRelease -Confirm:$false
     }
 
     if (-not (Test-NovaVersionUpdateResultRequired -ShouldRun:$ShouldRun -WhatIfEnabled:$WhatIfEnabled)) {
         return
     }
 
-    return Get-NovaVersionUpdateResult -WorkflowContext $WorkflowContext
+    return Get-NovaVersionUpdateResult -WorkflowContext $WorkflowContext -Applied:($null -ne $versionWriteResult -and $versionWriteResult.Applied)
 }
 
 function Test-NovaVersionUpdateResultRequired {
@@ -30,13 +31,15 @@ function Test-NovaVersionUpdateResultRequired {
 function Get-NovaVersionUpdateResult {
     [CmdletBinding()]
     param(
-        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$Applied
     )
 
     return [pscustomobject]@{
         PreviousVersion = $WorkflowContext.PreviousVersion
         NewVersion = $WorkflowContext.NewVersion
         Label = $WorkflowContext.Label
         CommitCount = $WorkflowContext.CommitCount
+        Applied = [bool]$Applied
     }
 }

src/private/release/SetNovaModuleVersion.ps1

@@ -1,3 +1,21 @@
+function Get-NovaModuleVersionWriteResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$ProjectFile,
+        [Parameter(Mandatory)][string]$PreviousVersion,
+        [Parameter(Mandatory)][string]$NewVersion,
+        [switch]$Applied
+    )
+
+    return [pscustomobject]@{
+        ProjectFile = $ProjectFile
+        Target = [System.IO.Path]::GetFileName($ProjectFile)
+        PreviousVersion = $PreviousVersion
+        NewVersion = $NewVersion
+        Applied = [bool]$Applied
+    }
+}
+
 function Set-NovaModuleVersion {
     [CmdletBinding(SupportsShouldProcess = $true)]
     param(
@@ -11,13 +29,16 @@ function Set-NovaModuleVersion {
 
     $versionUpdatePlan = Get-NovaVersionUpdatePlan -ProjectInfo $ProjectInfo -Label $Label -PreviewRelease:$PreviewRelease -StableRelease:$StableRelease
     $jsonContent = Read-ProjectJsonData -ProjectJsonPath $versionUpdatePlan.ProjectFile
+    $previousVersion = [string]$jsonContent.Version
     $newVersion = $versionUpdatePlan.NewVersion.ToString()
     $target = [System.IO.Path]::GetFileName($versionUpdatePlan.ProjectFile)
     $action = "Set module version to $newVersion"
 
-    if ( $PSCmdlet.ShouldProcess($target, $action)) {
-        $jsonContent.Version = $newVersion
-        Write-Host "Version bumped to : $newVersion"
-        Write-ProjectJsonData -ProjectJsonPath $versionUpdatePlan.ProjectFile -Data $jsonContent
+    if (-not $PSCmdlet.ShouldProcess($target, $action)) {
+        return Get-NovaModuleVersionWriteResult -ProjectFile $versionUpdatePlan.ProjectFile -PreviousVersion $previousVersion -NewVersion $newVersion
     }
+
+    $jsonContent.Version = $newVersion
+    Write-ProjectJsonData -ProjectJsonPath $versionUpdatePlan.ProjectFile -Data $jsonContent
+    return Get-NovaModuleVersionWriteResult -ProjectFile $versionUpdatePlan.ProjectFile -PreviousVersion $previousVersion -NewVersion $newVersion -Applied
 }

src/private/shared/WriteNovaModuleReleaseNotesLink.ps1

@@ -1,13 +1,36 @@
+function Get-NovaModuleReleaseNotesMessage {
+    [CmdletBinding(DefaultParameterSetName = 'Module')]
+    param(
+        [Parameter(ParameterSetName = 'Module')]
+        [object]$Module = $ExecutionContext.SessionState.Module,
+        [Parameter(ParameterSetName = 'Uri')]
+        [AllowNull()][string]$ReleaseNotesUri
+    )
+
+    if ($PSCmdlet.ParameterSetName -eq 'Module') {
+        $ReleaseNotesUri = Get-NovaModuleReleaseNotesUri -Module $Module
+    }
+
+    if ( [string]::IsNullOrWhiteSpace($ReleaseNotesUri)) {
+        return $null
+    }
+
+    return "Release notes: $($ReleaseNotesUri.Trim() )"
+}
+
 function Write-NovaModuleReleaseNotesLink {
-    [CmdletBinding()]
+    [CmdletBinding(DefaultParameterSetName = 'Module')]
     param(
-        [object]$Module = $ExecutionContext.SessionState.Module
+        [Parameter(ParameterSetName = 'Module')]
+        [object]$Module = $ExecutionContext.SessionState.Module,
+        [Parameter(ParameterSetName = 'Uri')]
+        [AllowNull()][string]$ReleaseNotesUri
     )
 
-    $releaseNotesUri = Get-NovaModuleReleaseNotesUri -Module $Module
-    if ($null -eq $releaseNotesUri) {
+    $message = Get-NovaModuleReleaseNotesMessage @PSBoundParameters
+    if ($null -eq $message) {
         return
     }
 
-    Write-Host "Release notes: $releaseNotesUri"
+    Write-Host $message
 }

src/private/update/InvokeNovaModuleSelfUpdateWorkflow.ps1

@@ -12,6 +12,22 @@ function Invoke-NovaModuleSelfUpdateOrStop {
     }
 }
 
+function Complete-NovaModuleSelfUpdateResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Plan,
+        [AllowNull()][string]$ReleaseNotesUri
+    )
+
+    if ($Plan.PSObject.Properties.Name -contains 'ReleaseNotesUri') {
+        $Plan.ReleaseNotesUri = $ReleaseNotesUri
+        return $Plan
+    }
+
+    $Plan | Add-Member -NotePropertyName 'ReleaseNotesUri' -NotePropertyValue $ReleaseNotesUri
+    return $Plan
+}
+
 function Invoke-NovaModuleSelfUpdateWorkflow {
     [CmdletBinding()]
     param(
@@ -20,11 +36,11 @@ function Invoke-NovaModuleSelfUpdateWorkflow {
 
     $plan = $WorkflowContext.Plan
     if (-not $plan.UpdateAvailable) {
-        return $plan
+        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
     }
 
     Invoke-NovaModuleSelfUpdateOrStop -Plan $plan
     $plan.Updated = $true
-    Write-NovaModuleReleaseNotesLink
-    return $plan
+    $releaseNotesUri = Get-NovaModuleReleaseNotesUri
+    return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $releaseNotesUri
 }

src/public/InstallNovaCli.ps1

@@ -11,5 +11,7 @@ function Install-NovaCli {
         return
     }
 
-    return Invoke-NovaCliInstallWorkflow -WorkflowContext $workflowContext
+    $result = Invoke-NovaCliInstallWorkflow -WorkflowContext $workflowContext
+    Write-NovaModuleReleaseNotesLink -ReleaseNotesUri $result.ReleaseNotesUri
+    return $result
 }

src/public/UpdateNovaModuleTools.ps1

@@ -6,17 +6,19 @@ function Update-NovaModuleTool {
     $workflowContext = Get-NovaModuleSelfUpdateWorkflowContext
     $plan = $workflowContext.Plan
     if (-not $plan.UpdateAvailable) {
-        return $plan
+        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
     }
 
     if ($plan.IsPrereleaseTarget -and -not (Confirm-NovaPrereleaseModuleUpdate -Cmdlet $PSCmdlet -CurrentVersion $plan.CurrentVersion -TargetVersion $plan.TargetVersion)) {
         $plan.Cancelled = $true
-        return $plan
+        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
     }
 
     if (-not $PSCmdlet.ShouldProcess($plan.ModuleName, $workflowContext.Action)) {
-        return $plan
+        return Complete-NovaModuleSelfUpdateResult -Plan $plan -ReleaseNotesUri $null
     }
 
-    return Invoke-NovaModuleSelfUpdateWorkflow -WorkflowContext $workflowContext
+    $result = Invoke-NovaModuleSelfUpdateWorkflow -WorkflowContext $workflowContext
+    Write-NovaModuleReleaseNotesLink -ReleaseNotesUri $result.ReleaseNotesUri
+    return $result
 }