feat(#201): mirror scaffold and update helper tests

 Add source-mirrored, dot-source-first Pester test files for the small
 and well-isolated helpers under src/private/scaffold and
 src/private/update so each unit-level helper has a focused test file
 under tests/private/scaffold or tests/private/update instead of being
 covered only through broad legacy coverage files. The remaining
 workflow-level scaffold and update helpers stay covered by the existing
 broad tests for now.

Author: stiwicourage

CHANGELOG.md

@@ -22,6 +22,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
     - `Initialize-NovaModule` and `% nova init` now check for newer NovaModuleTools releases before the first interactive scaffold question and reuse the same non-blocking update warning behavior already used by build.
 - `Test-NovaBuild` and `% nova test` now enforce `Pester.CodeCoverage.CoveragePercentTarget` from `project.json` when `CodeCoverage.Enabled` is `true`, failing the test run when measured coverage drops below the configured target.
 - Added a non-blocking `scripts/build/Get-TestMirrorStatus.ps1` helper that reports `src/**/*.ps1` files without a matching mirrored test file under `tests/`, to support the migration to the source-mirrored, dot-source-first test layout.
+- Added mirrored, dot-source-first Pester test files for scaffold and update private helpers (`src/private/scaffold/*.ps1` and `src/private/update/*.ps1`), so each unit-level helper now has a focused test file under `tests/private/scaffold/` or `tests/private/update/` instead of being covered only through broad legacy coverage files.
 
 
 ### Changed

tests/private/scaffold/AssertNovaModuleQuestionAnswerValid.Tests.ps1

@@ -0,0 +1,41 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/scaffold/AssertNovaModuleQuestionAnswerValid.ps1')
+
+    function Get-AwesomePromptValidationFailure {param($Ask, $Value)}
+    function Stop-NovaOperation {
+        param([string]$Message, [string]$ErrorId, $Category, $TargetObject)
+        throw $Message
+    }
+}
+
+Describe 'Assert-NovaModuleQuestionAnswerValid' {
+    BeforeAll {
+        $script:question = [pscustomobject]@{Name = 'ProjectName'}
+    }
+
+    It 'returns silently when the validator reports no failure' {
+        Mock Get-AwesomePromptValidationFailure {return $null}
+        Mock Stop-NovaOperation {throw 'should not be called'}
+
+        {Assert-NovaModuleQuestionAnswerValid -Question $script:question -Value 'NovaThing'} | Should -Not -Throw
+        Assert-MockCalled Stop-NovaOperation -Times 0
+    }
+
+    It 'stops the operation when the validator reports a failure' {
+        Mock Get-AwesomePromptValidationFailure {
+            return [pscustomobject]@{
+                Message = 'invalid name'
+                ErrorId = 'Nova.Validation.ProjectName'
+                Category = 'InvalidArgument'
+                TargetObject = $Value
+            }
+        }
+        Mock Stop-NovaOperation {throw "$Message ($ErrorId)"}
+
+        {Assert-NovaModuleQuestionAnswerValid -Question $script:question -Value 'bad name'} | Should -Throw '*invalid name*'
+        Assert-MockCalled Stop-NovaOperation -Times 1 -ParameterFilter {
+            $Message -eq 'invalid name' -and $ErrorId -eq 'Nova.Validation.ProjectName'
+        }
+    }
+}

tests/private/scaffold/CopyNovaExampleProjectTemplate.Tests.ps1

@@ -0,0 +1,32 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/scaffold/CopyNovaExampleProjectTemplate.ps1')
+
+    function Get-NovaModuleProjectTemplatePath {param([switch]$Example)}
+}
+
+Describe 'Copy-NovaExampleProjectTemplate' {
+    BeforeAll {
+        $script:templateRoot = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) ([guid]::NewGuid().Guid))
+        $null = New-Item -ItemType Directory -Path (Join-Path $script:templateRoot 'src')
+        Set-Content -LiteralPath (Join-Path $script:templateRoot 'project.json') -Value '{}' -NoNewline
+        Set-Content -LiteralPath (Join-Path $script:templateRoot 'src/example.ps1') -Value '# example' -NoNewline
+
+        $script:destination = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) ([guid]::NewGuid().Guid))
+    }
+
+    AfterAll {
+        Remove-Item -LiteralPath $script:templateRoot -Recurse -Force -ErrorAction SilentlyContinue
+        Remove-Item -LiteralPath $script:destination -Recurse -Force -ErrorAction SilentlyContinue
+    }
+
+    It 'copies every template item under the resolved template root into the destination' {
+        Mock Get-NovaModuleProjectTemplatePath {return (Join-Path $script:templateRoot 'project.json')}
+
+        Copy-NovaExampleProjectTemplate -DestinationPath $script:destination.FullName
+
+        Test-Path -LiteralPath (Join-Path $script:destination 'project.json') | Should -BeTrue
+        Test-Path -LiteralPath (Join-Path $script:destination 'src/example.ps1') | Should -BeTrue
+        Assert-MockCalled Get-NovaModuleProjectTemplatePath -Times 1 -ParameterFilter {$Example.IsPresent}
+    }
+}

tests/private/scaffold/GetNovaModuleAgenticCopilotTemplateRoot.Tests.ps1

@@ -0,0 +1,19 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/scaffold/GetNovaModuleAgenticCopilotTemplateRoot.ps1')
+
+    function Get-ResourceFilePath {param([string]$FileName)}
+}
+
+Describe 'Get-NovaModuleAgenticCopilotTemplateRoot' {
+    It 'returns the directory that owns the agentic-copilot sentinel file' {
+        Mock Get-ResourceFilePath {return '/resources/agentic-copilot/AGENTS.md'}
+
+        $root = Get-NovaModuleAgenticCopilotTemplateRoot
+
+        $root | Should -Be (Split-Path -Parent '/resources/agentic-copilot/AGENTS.md')
+        Assert-MockCalled Get-ResourceFilePath -Times 1 -ParameterFilter {
+            $FileName -like '*agentic-copilot*AGENTS.md'
+        }
+    }
+}

tests/private/scaffold/GetNovaModuleProjectTemplatePath.Tests.ps1

@@ -0,0 +1,30 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/scaffold/GetNovaModuleProjectTemplatePath.ps1')
+
+    function Get-ResourceFilePath {param([string]$FileName) return "/resources/$FileName"}
+}
+
+Describe 'Get-NovaModuleProjectTemplatePath' {
+    It 'resolves the standard template path through Get-ResourceFilePath' {
+        Mock Get-ResourceFilePath {return "/resources/$FileName"}
+
+        $path = Get-NovaModuleProjectTemplatePath
+
+        $path | Should -Be '/resources/ProjectTemplate.json'
+        Assert-MockCalled Get-ResourceFilePath -Times 1 -ParameterFilter {
+            $FileName -eq 'ProjectTemplate.json'
+        }
+    }
+
+    It 'resolves the example template path under example/project.json when -Example is set' {
+        Mock Get-ResourceFilePath {return "/resources/$FileName"}
+
+        $path = Get-NovaModuleProjectTemplatePath -Example
+
+        $path | Should -Match 'example.+project\.json$'
+        Assert-MockCalled Get-ResourceFilePath -Times 1 -ParameterFilter {
+            $FileName -like 'example*project.json'
+        }
+    }
+}

tests/private/scaffold/GetNovaModuleScaffoldPaths.Tests.ps1

@@ -0,0 +1,19 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/scaffold/GetNovaModuleScaffoldPaths.ps1')
+}
+
+Describe 'Get-NovaModuleScaffoldLayout' {
+    It 'composes scaffold paths under the provided base path and project name' {
+        $layout = Get-NovaModuleScaffoldLayout -Path '/tmp/projects' -ProjectName 'DemoModule'
+
+        $layout.Project | Should -Be (Join-Path '/tmp/projects' 'DemoModule')
+        $layout.Src | Should -Be (Join-Path $layout.Project 'src')
+        $layout.Private | Should -Be (Join-Path $layout.Src 'private')
+        $layout.Public | Should -Be (Join-Path $layout.Src 'public')
+        $layout.Resources | Should -Be (Join-Path $layout.Src 'resources')
+        $layout.Classes | Should -Be (Join-Path $layout.Src 'classes')
+        $layout.Tests | Should -Be (Join-Path $layout.Project 'tests')
+        $layout.ProjectJsonFile | Should -Be (Join-Path $layout.Project 'project.json')
+    }
+}

tests/private/scaffold/InvokeNovaModuleInitializationWorkflow.Tests.ps1

@@ -0,0 +1,49 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/scaffold/InvokeNovaModuleInitializationWorkflow.ps1')
+
+    function Initialize-NovaModuleScaffold {param($Answer, $Paths, [switch]$Example)}
+    function Write-NovaModuleProjectJson {param($Answer, [string]$ProjectJsonFile, [switch]$Example)}
+    function Initialize-NovaModuleAgenticCopilotScaffold {param($Answer, [string]$ProjectRoot, [switch]$Example)}
+    function Write-Message {param([Parameter(ValueFromPipeline = $true)]$InputObject, [string]$color)}
+}
+
+Describe 'Invoke-NovaModuleInitializationWorkflow' {
+    BeforeAll {
+        $script:context = [pscustomobject]@{
+            AnswerSet = @{ProjectName = 'DemoModule'; EnableAgenticCopilot = 'No'}
+            Layout = [pscustomobject]@{Project = '/tmp/DemoModule'; ProjectJsonFile = '/tmp/DemoModule/project.json'}
+            Example = $false
+        }
+    }
+
+    It 'initializes the scaffold and writes the project.json before announcing completion' {
+        Mock Initialize-NovaModuleScaffold {}
+        Mock Write-NovaModuleProjectJson {}
+        Mock Initialize-NovaModuleAgenticCopilotScaffold {}
+        Mock Write-Message {}
+
+        Invoke-NovaModuleInitializationWorkflow -WorkflowContext $script:context
+
+        Assert-MockCalled Initialize-NovaModuleScaffold -Times 1
+        Assert-MockCalled Write-NovaModuleProjectJson -Times 1
+        Assert-MockCalled Initialize-NovaModuleAgenticCopilotScaffold -Times 0
+        Assert-MockCalled Write-Message -Times 1
+    }
+
+    It 'invokes the Agentic Copilot scaffold step when the answer set requests it' {
+        Mock Initialize-NovaModuleScaffold {}
+        Mock Write-NovaModuleProjectJson {}
+        Mock Initialize-NovaModuleAgenticCopilotScaffold {}
+        Mock Write-Message {}
+
+        $contextWithAgentic = [pscustomobject]@{
+            AnswerSet = @{ProjectName = 'DemoModule'; EnableAgenticCopilot = 'Yes'}
+            Layout = [pscustomobject]@{Project = '/tmp/DemoModule'; ProjectJsonFile = '/tmp/DemoModule/project.json'}
+            Example = $false
+        }
+        Invoke-NovaModuleInitializationWorkflow -WorkflowContext $contextWithAgentic
+
+        Assert-MockCalled Initialize-NovaModuleAgenticCopilotScaffold -Times 1
+    }
+}

tests/private/scaffold/ResolveNovaModuleScaffoldBasePath.Tests.ps1

@@ -0,0 +1,35 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/scaffold/ResolveNovaModuleScaffoldBasePath.ps1')
+
+    function Stop-NovaOperation {
+        param([string]$Message, [string]$ErrorId, $Category, $TargetObject)
+        throw $Message
+    }
+}
+
+Describe 'Resolve-NovaModuleScaffoldBasePath' {
+    BeforeAll {
+        $script:tempDir = (Resolve-Path -LiteralPath (New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) ([guid]::NewGuid().Guid)))).Path
+    }
+
+    AfterAll {
+        Remove-Item -LiteralPath $script:tempDir -Recurse -Force -ErrorAction SilentlyContinue
+    }
+
+    It 'returns the full resolved path when the directory exists' {
+        $result = Resolve-NovaModuleScaffoldBasePath -Path $script:tempDir
+        $result | Should -Be ([System.IO.Path]::GetFullPath($script:tempDir))
+    }
+
+    It 'normalizes mixed separators before resolving' {
+        $mixed = $script:tempDir -replace '/', '\'
+        $result = Resolve-NovaModuleScaffoldBasePath -Path $mixed
+        $result | Should -Be ([System.IO.Path]::GetFullPath($script:tempDir))
+    }
+
+    It 'stops the operation when the path does not exist' {
+        $missing = Join-Path $script:tempDir ('missing-' + [guid]::NewGuid().Guid)
+        {Resolve-NovaModuleScaffoldBasePath -Path $missing} | Should -Throw '*Not a valid path*'
+    }
+}

tests/private/update/ConfirmNovaPrereleaseModuleUpdate.Tests.ps1

@@ -0,0 +1,41 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/update/ConfirmNovaPrereleaseModuleUpdate.ps1')
+
+    function Get-NovaPrereleaseModuleUpdateConfirmationPrompt {
+        param([string]$CurrentVersion, [string]$TargetVersion)
+        return [pscustomobject]@{Caption = 'caption'; Message = 'message'; Choice = [ordered]@{Y='Yes';N='No'}; Default = 'N'}
+    }
+
+    function Read-AwesomeChoicePrompt {
+        param($Ask, $HostUi)
+        return 'Y'
+    }
+}
+
+Describe 'Confirm-NovaPrereleaseModuleUpdate' {
+    BeforeAll {
+        $script:fakeCmdlet = [pscustomobject]@{Host = [pscustomobject]@{UI = [pscustomobject]@{Name = 'stub'}}}
+    }
+
+    It 'returns true when the user selects Yes' {
+        Mock Read-AwesomeChoicePrompt {return 'Y'}
+        Confirm-NovaPrereleaseModuleUpdate -Cmdlet $script:fakeCmdlet -CurrentVersion '1.0.0' -TargetVersion '2.0.0-beta1' | Should -BeTrue
+    }
+
+    It 'returns false when the user selects No' {
+        Mock Read-AwesomeChoicePrompt {return 'N'}
+        Confirm-NovaPrereleaseModuleUpdate -Cmdlet $script:fakeCmdlet -CurrentVersion '1.0.0' -TargetVersion '2.0.0-beta1' | Should -BeFalse
+    }
+
+    It 'builds the prompt from the current and target version inputs' {
+        Mock Get-NovaPrereleaseModuleUpdateConfirmationPrompt {return [pscustomobject]@{Caption = 'caption'; Message = 'message'; Choice = [ordered]@{Y='Yes';N='No'}; Default = 'N'}}
+        Mock Read-AwesomeChoicePrompt {return 'N'}
+
+        Confirm-NovaPrereleaseModuleUpdate -Cmdlet $script:fakeCmdlet -CurrentVersion '1.0.0' -TargetVersion '2.0.0-beta1' | Out-Null
+
+        Assert-MockCalled Get-NovaPrereleaseModuleUpdateConfirmationPrompt -Times 1 -ParameterFilter {
+            $CurrentVersion -eq '1.0.0' -and $TargetVersion -eq '2.0.0-beta1'
+        }
+    }
+}

tests/private/update/ConvertToNovaModuleSelfUpdatePlan.Tests.ps1

@@ -0,0 +1,113 @@
+BeforeAll {
+    $projectRoot = Split-Path -Parent (Split-Path -Parent (Split-Path -Parent $PSScriptRoot))
+    . (Join-Path $projectRoot 'src/private/update/ConvertToNovaModuleSelfUpdatePlan.ps1')
+}
+
+Describe 'Get-NovaModuleSelfUpdateLookupCandidate' {
+    It 'returns null when the lookup result is null' {
+        Get-NovaModuleSelfUpdateLookupCandidate -LookupResult $null -PrereleaseNotificationsEnabled $true | Should -BeNullOrEmpty
+    }
+
+    It 'prefers the prerelease candidate when prerelease notifications are enabled' {
+        $lookup = [pscustomobject]@{
+            Prerelease = [pscustomobject]@{Version = '2.0.0-beta1'}
+            Stable = [pscustomobject]@{Version = '1.5.0'}
+        }
+        (Get-NovaModuleSelfUpdateLookupCandidate -LookupResult $lookup -PrereleaseNotificationsEnabled $true).Version | Should -Be '2.0.0-beta1'
+    }
+
+    It 'prefers the stable candidate when prerelease notifications are disabled' {
+        $lookup = [pscustomobject]@{
+            Prerelease = [pscustomobject]@{Version = '2.0.0-beta1'}
+            Stable = [pscustomobject]@{Version = '1.5.0'}
+        }
+        (Get-NovaModuleSelfUpdateLookupCandidate -LookupResult $lookup -PrereleaseNotificationsEnabled $false).Version | Should -Be '1.5.0'
+    }
+
+    It 'falls back to the prerelease candidate when no stable candidate exists and prerelease notifications are disabled' {
+        $lookup = [pscustomobject]@{
+            Prerelease = [pscustomobject]@{Version = '2.0.0-beta1'}
+            Stable = $null
+        }
+        (Get-NovaModuleSelfUpdateLookupCandidate -LookupResult $lookup -PrereleaseNotificationsEnabled $false).Version | Should -Be '2.0.0-beta1'
+    }
+}
+
+Describe 'Get-NovaModuleSelfUpdateLookupRepository' {
+    It 'returns the candidate repository when the candidate carries one' {
+        $candidate = [pscustomobject]@{Repository = 'CandidateRepo'}
+        $lookup = [pscustomobject]@{SourceRepository = 'LookupRepo'}
+        Get-NovaModuleSelfUpdateLookupRepository -LookupResult $lookup -LookupCandidate $candidate | Should -Be 'CandidateRepo'
+    }
+
+    It 'falls back to the lookup result SourceRepository when the candidate lacks Repository' {
+        $candidate = [pscustomobject]@{Version = '1.0.0'}
+        $lookup = [pscustomobject]@{SourceRepository = 'LookupRepo'}
+        Get-NovaModuleSelfUpdateLookupRepository -LookupResult $lookup -LookupCandidate $candidate | Should -Be 'LookupRepo'
+    }
+
+    It 'returns null when neither the candidate nor the lookup result carries a repository' {
+        $candidate = [pscustomobject]@{Version = '1.0.0'}
+        $lookup = [pscustomobject]@{Version = '1.0.0'}
+        Get-NovaModuleSelfUpdateLookupRepository -LookupResult $lookup -LookupCandidate $candidate | Should -BeNullOrEmpty
+    }
+}
+
+Describe 'Get-NovaModuleSelfUpdatePlanContext' {
+    It 'returns empty lookup fields when no lookup result is available' {
+        $context = Get-NovaModuleSelfUpdatePlanContext -LookupResult $null -PrereleaseNotificationsEnabled $true
+        $context.LookupCandidateVersion | Should -BeNullOrEmpty
+        $context.LookupCandidateChannel | Should -BeNullOrEmpty
+        $context.LookupRepository | Should -BeNullOrEmpty
+        $context.PrereleaseNotificationsEnabled | Should -BeTrue
+    }
+
+    It 'populates lookup candidate metadata when the lookup result has a stable candidate' {
+        $lookup = [pscustomobject]@{
+            Prerelease = $null
+            Stable = [pscustomobject]@{Version = '1.5.0'; Channel = 'Stable'; Repository = 'PSGallery'}
+            SourceRepository = 'PSGallery'
+        }
+        $context = Get-NovaModuleSelfUpdatePlanContext -LookupResult $lookup -PrereleaseNotificationsEnabled $false
+
+        $context.LookupCandidateVersion | Should -Be '1.5.0'
+        $context.LookupCandidateChannel | Should -Be 'Stable'
+        $context.LookupRepository | Should -Be 'PSGallery'
+    }
+}
+
+Describe 'ConvertTo-NovaModuleSelfUpdatePlan' {
+    BeforeAll {
+        $script:installed = [pscustomobject]@{ModuleName = 'NovaModuleTools'; Version = '1.0.0'}
+        $script:context = [pscustomobject]@{
+            LookupCandidateVersion = '2.0.0-beta1'
+            LookupCandidateChannel = 'Prerelease'
+            LookupRepository = 'PSGallery'
+            PrereleaseNotificationsEnabled = $true
+        }
+    }
+
+    It 'returns a no-update plan when no target version is provided' {
+        $plan = ConvertTo-NovaModuleSelfUpdatePlan -InstalledModule $script:installed -PlanContext $script:context
+
+        $plan.TargetVersion | Should -BeNullOrEmpty
+        $plan.UpdateAvailable | Should -BeFalse
+        $plan.IsPrereleaseTarget | Should -BeFalse
+        $plan.UsedAllowPrerelease | Should -BeFalse
+    }
+
+    It 'marks the plan as an available update when a target version is provided' {
+        $plan = ConvertTo-NovaModuleSelfUpdatePlan -InstalledModule $script:installed -PlanContext $script:context -TargetVersion '2.0.0'
+
+        $plan.TargetVersion | Should -Be '2.0.0'
+        $plan.UpdateAvailable | Should -BeTrue
+        $plan.IsPrereleaseTarget | Should -BeFalse
+    }
+
+    It 'flags prerelease target plans through IsPrereleaseTarget and UsedAllowPrerelease' {
+        $plan = ConvertTo-NovaModuleSelfUpdatePlan -InstalledModule $script:installed -PlanContext $script:context -TargetVersion '2.0.0-beta1' -PrereleaseTarget
+
+        $plan.IsPrereleaseTarget | Should -BeTrue
+        $plan.UsedAllowPrerelease | Should -BeTrue
+    }
+}