Merge pull request #16 from tablackburn/chore/workflow-template-guards

Skip template-incompatible CI/Publish jobs on un-initialized template

Author: tablackburn

.github/workflows/CI.yaml

@@ -18,7 +18,23 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      # Skip lint on the un-initialized template — the literal `./{{ModuleName}}`
+      # path argument can't be parsed by PowerShell (the double braces split into
+      # mismatched script-block delimiters), so Invoke-ScriptAnalyzer fails with
+      # a positional-argument error before it ever touches the folder. Same
+      # marker as the unit-tests job below.
+      - name: Detect template state
+        id: template_guard
+        shell: bash
+        run: |
+          if [ -f CHANGELOG.template.md ]; then
+            echo "is_template=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_template=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Cache PowerShell modules
+        if: steps.template_guard.outputs.is_template == 'false'
         id: cache-lint-modules
         uses: actions/cache@v5
         with:
@@ -28,13 +44,14 @@ jobs:
             ${{ runner.os }}-psmodules-lint-
 
       - name: Install PSScriptAnalyzer
-        if: steps.cache-lint-modules.outputs.cache-hit != 'true'
+        if: steps.template_guard.outputs.is_template == 'false' && steps.cache-lint-modules.outputs.cache-hit != 'true'
         shell: pwsh
         run: |
           Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
           Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
 
       - name: Run PSScriptAnalyzer
+        if: steps.template_guard.outputs.is_template == 'false'
         shell: pwsh
         run: |
           $results = Invoke-ScriptAnalyzer -Path ./{{ModuleName}} -Recurse -Settings PSGallery -ReportSummary
@@ -63,7 +80,27 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      # Skip subsequent steps on the un-initialized template — Build's
+      # GENERATEMARKDOWN task can't import the manifest while {{GUID}} is still
+      # a literal placeholder. Marker: CHANGELOG.template.md exists only
+      # pre-init; Initialize-Template.ps1 moves it onto CHANGELOG.md during
+      # init, so downstream repos run the full job. The marker path contains
+      # no placeholder token, so init's substitution loop leaves this guard
+      # intact when the workflow is copied into a new module.
+      # hashFiles() is not allowed in jobs.<job_id>.if, so we evaluate it in a
+      # step and gate downstream steps on the resulting output.
+      - name: Detect template state
+        id: template_guard
+        shell: bash
+        run: |
+          if [ -f CHANGELOG.template.md ]; then
+            echo "is_template=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_template=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Cache PowerShell modules
+        if: steps.template_guard.outputs.is_template == 'false'
         uses: actions/cache@v5
         with:
           path: |
@@ -74,23 +111,24 @@ jobs:
             ${{ runner.os }}-psmodules-
 
       - name: Build and Test
+        if: steps.template_guard.outputs.is_template == 'false'
         shell: pwsh
         run: |
           New-Item -Path out -ItemType Directory -Force | Out-Null
           ./build.ps1 -Task Build,Test -Bootstrap
 
       - name: Upload Coverage to Codecov
+        if: success() && steps.template_guard.outputs.is_template == 'false'
         uses: codecov/codecov-action@v6
-        if: success()
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: out/codeCoverage.xml
           flags: ${{ matrix.os }}
           fail_ci_if_error: false
 
       - name: Upload Test Results
+        if: always() && steps.template_guard.outputs.is_template == 'false'
         uses: actions/upload-artifact@v7
-        if: always()
         with:
           name: test-results-${{ matrix.os }}
           path: out/

.github/workflows/PublishModuleToPowerShellGallery.yaml

@@ -21,8 +21,26 @@ jobs:
         with:
           fetch-depth: 0
 
+      # Never publish the un-initialized template — the .psd1 still has
+      # {{ModuleName}} and {{GUID}} placeholders. Same marker as CI.yaml:
+      # CHANGELOG.template.md exists only pre-init. hashFiles() is not allowed
+      # in jobs.<job_id>.if, so we evaluate it in a step and gate the
+      # version-detection and release-check steps on the resulting output;
+      # everything downstream cascades on those steps' outputs and skips
+      # naturally when they don't run.
+      - name: Detect template state
+        id: template_guard
+        shell: bash
+        run: |
+          if [ -f CHANGELOG.template.md ]; then
+            echo "is_template=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_template=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Get Module Version
         id: version
+        if: steps.template_guard.outputs.is_template == 'false'
         shell: pwsh
         run: |
           $manifest = Import-PowerShellDataFile -Path ./{{ModuleName}}/{{ModuleName}}.psd1
@@ -32,6 +50,7 @@ jobs:
 
       - name: Check if Release Exists
         id: check_release
+        if: steps.template_guard.outputs.is_template == 'false'
         shell: bash
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Initialize-Template.ps1

@@ -242,8 +242,9 @@ if (Test-Path -Path $templateModuleFolder) {
     # Rename example function files
     $publicFolder = Join-Path -Path $moduleFolder -ChildPath 'Public'
     $privateFolder = Join-Path -Path $moduleFolder -ChildPath 'Private'
-    $testPublicFolder = Join-Path -Path $PSScriptRoot -ChildPath 'tests/Unit/Public'
-    $testPrivateFolder = Join-Path -Path $PSScriptRoot -ChildPath 'tests/Unit/Private'
+    $testUnitFolder = Join-Path -Path (Join-Path -Path $PSScriptRoot -ChildPath 'tests') -ChildPath 'Unit'
+    $testPublicFolder = Join-Path -Path $testUnitFolder -ChildPath 'Public'
+    $testPrivateFolder = Join-Path -Path $testUnitFolder -ChildPath 'Private'
 
     $foldersToCheck = @($publicFolder, $privateFolder, $testPublicFolder, $testPrivateFolder)
 
@@ -280,21 +281,34 @@ if (Test-Path -Path $docsFolder) {
 }
 
 # Replace template-facing README.md with the module-facing README.template.md
-# (placeholders inside README.template.md were already substituted by the file-processing loop above)
+# (placeholders inside README.template.md were already substituted by the file-processing loop above).
+# If the destination already exists (e.g., the user is re-running init after customizing it),
+# leave both files in place and warn — manually resolving is safer than overwriting customizations.
 $readmeTemplate = Join-Path -Path $PSScriptRoot -ChildPath 'README.template.md'
 $readmePath = Join-Path -Path $PSScriptRoot -ChildPath 'README.md'
 if (Test-Path -Path $readmeTemplate) {
-    Move-Item -Path $readmeTemplate -Destination $readmePath -Force
-    Write-Host '  Generated module README.md from template' -ForegroundColor Green
+    if (Test-Path -Path $readmePath) {
+        Write-Warning '  README.md already exists; leaving it in place. Resolve README.template.md manually.'
+    }
+    else {
+        Move-Item -Path $readmeTemplate -Destination $readmePath
+        Write-Host '  Generated module README.md from template' -ForegroundColor Green
+    }
 }
 
 # Replace template-facing CHANGELOG.md with the module-facing CHANGELOG.template.md
-# (placeholders inside CHANGELOG.template.md were already substituted by the file-processing loop above)
+# (placeholders inside CHANGELOG.template.md were already substituted by the file-processing loop above).
+# Same guard as README above — preserve any existing CHANGELOG.md rather than clobber it.
 $changelogTemplate = Join-Path -Path $PSScriptRoot -ChildPath 'CHANGELOG.template.md'
 $changelogPath = Join-Path -Path $PSScriptRoot -ChildPath 'CHANGELOG.md'
 if (Test-Path -Path $changelogTemplate) {
-    Move-Item -Path $changelogTemplate -Destination $changelogPath -Force
-    Write-Host '  Generated module CHANGELOG.md from template' -ForegroundColor Green
+    if (Test-Path -Path $changelogPath) {
+        Write-Warning '  CHANGELOG.md already exists; leaving it in place. Resolve CHANGELOG.template.md manually.'
+    }
+    else {
+        Move-Item -Path $changelogTemplate -Destination $changelogPath
+        Write-Host '  Generated module CHANGELOG.md from template' -ForegroundColor Green
+    }
 }
 
 # Initialize Git repository if requested

tests/ManifestHelpers.psm1

@@ -123,9 +123,10 @@ function Compare-SemVerPrerelease {
 
         if ($firstIsNumeric -and $secondIsNumeric) {
             # SemVer 2.0.0 permits arbitrarily large numeric identifiers — use BigInteger
-            # rather than [long] to avoid overflow.
-            $firstNum = [bigint]$firstId
-            $secondNum = [bigint]$secondId
+            # rather than [long] to avoid overflow. [bigint] is a PS 7+ accelerator only,
+            # so spell out the full type for Windows PowerShell 5.1 compatibility.
+            $firstNum = [System.Numerics.BigInteger]$firstId
+            $secondNum = [System.Numerics.BigInteger]$secondId
 
             if ($firstNum -lt $secondNum) {
                 return -1