✨ [feat] Add cache-format upgrade workflow, manual validation override, and Show-ColorScript -ValidateCache

 - ✨ Private/Ensure-CacheFormatVersion.ps1: add Set-CacheValidationOverride to let callers force cache validation; setting the override resets $script:CacheValidationPerformed so initialization will re-run validation.
 - ✨ Private/Ensure-CacheFormatVersion.ps1: extend Update-CacheFormatVersion to accept -MetadataFileName and write metadata using [int]$script:CacheFormatVersion (Version, ModuleVersion, UpdatedUtc).
 - ✨ Private/Ensure-CacheFormatVersion.ps1: implement purge of obsolete cache-metadata*.json files (remove files whose name != current MetadataFileName) with robust try/catch and Write-Verbose diagnostics to avoid breaking init on IO/parse failures.

🚜 [refactor] Integrate cache validation into initialization and add env override
 - 🚜 Private/Initialize-CacheDirectory.ps1: standardize metadata filename to 'cache-metadata-v{0}.json' and pass that name into Update-CacheFormatVersion.
 - 🚜 Private/Initialize-CacheDirectory.ps1: add support for COLOR_SCRIPTS_ENHANCED_VALIDATE_CACHE (accepts 1/true/yes) to force validation via environment.
 - 🚜 Private/Initialize-CacheDirectory.ps1: only run validation when forced (env), when manual override is set, or when validation hasn't been performed and the metadata file is missing; set $script:CacheValidationPerformed = $true after validation and clear the manual override. Apply same logic to the fallback resolution path.

✨ [feat] Public Show-ColorScript: add -ValidateCache switch
 - ✨ Public/Show-ColorScript.ps1: add .PARAMETER ValidateCache documentation and new [switch]$ValidateCache parameter.
 - ✨ Public/Show-ColorScript.ps1: when -ValidateCache is supplied call Set-CacheValidationOverride -Value $true so callers can force cache rebuild/validation before rendering.

🔧 [build] Bump module version and release notes header
 - 🔧 ColorScripts-Enhanced/ColorScripts-Enhanced.psd1: bump ModuleVersion => '2025.11.05.2125' and update embedded ReleaseNotes header to match the new stamp.

📝 [docs] Sync localized help UICultureVersion stamps
 - 📝 Update localized HelpInfo.xml files (en-US, de, es, fr, it, ja, nl, pt, ru, zh-CN) to the new UICultureVersion stamp to keep manifest/help metadata consistent with the module bump.

🧪 [test] Initialize cache-validation state in tests
 - 🧪 Tests/*: reset $script:CacheValidationPerformed = $false and $script:CacheValidationManualOverride = $false in test setup fixtures (CoverageExpansion, InternalCoverage, TargetedCoverage) so tests run with deterministic cache-validation state.

📝 [docs] Regenerate packaged release artifacts
 - 📝 dist/LatestReleaseNotes.md & dist/PowerShellGalleryReleaseNotes.md: regenerate release notes header/content to reflect the cache-format workflow, validation changes and module/help version bumps.

Signed-off-by: Nick2bad4u <20943337+Nick2bad4u@users.noreply.github.com>

Author: Nick2bad4u

ColorScripts-Enhanced/ColorScripts-Enhanced.psd1

@@ -11,7 +11,7 @@
     RootModule = 'ColorScripts-Enhanced.psm1'
 
     # Version number of this module.
-    ModuleVersion = '2025.11.05.1912'
+    ModuleVersion = '2025.11.05.2125'
 
     # Supported PSEditions
     CompatiblePSEditions = @('Desktop', 'Core')
@@ -211,7 +211,7 @@ PERFECT FOR
 
             # ReleaseNotes of this module
             ReleaseNotes = @'
-Version 2025.11.05.1912:
+Version 2025.11.05.2125:
 - Enhanced caching system with OS-wide cache in AppData
 - 6-19x performance improvement
 - Cache stored in centralized location

ColorScripts-Enhanced/Private/Ensure-CacheFormatVersion.ps1

@@ -2,39 +2,58 @@ if (-not $script:CacheFormatVersion) {
     $script:CacheFormatVersion = 2
 }
 
+if ($null -eq $script:CacheValidationManualOverride) {
+    $script:CacheValidationManualOverride = $false
+}
+
+if ($null -eq $script:CacheValidationPerformed) {
+    $script:CacheValidationPerformed = $false
+}
+
+function Set-CacheValidationOverride {
+    param(
+        [Parameter(Mandatory)]
+        [bool]$Value
+    )
+
+    $script:CacheValidationManualOverride = $Value
+
+    if ($Value) {
+        $script:CacheValidationPerformed = $false
+    }
+}
+
 function Update-CacheFormatVersion {
     param(
         [Parameter(Mandatory)]
         [ValidateNotNullOrEmpty()]
-        [string]$CacheDirectory
+        [string]$CacheDirectory,
+
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string]$MetadataFileName
     )
 
     if (-not (Test-Path -LiteralPath $CacheDirectory -PathType Container)) {
         return
     }
 
-    $metadataPath = Join-Path -Path $CacheDirectory -ChildPath 'cache-metadata.json'
-    $currentVersion = $null
+    $metadataPath = Join-Path -Path $CacheDirectory -ChildPath $MetadataFileName
 
-    if (Test-Path -LiteralPath $metadataPath -PathType Leaf) {
-        try {
-            $metadataJson = Get-Content -LiteralPath $metadataPath -Raw
-            if ($metadataJson) {
-                $metadata = ConvertFrom-Json -InputObject $metadataJson -ErrorAction Stop
-                if ($metadata -and $metadata.PSObject.Properties.Match('Version')) {
-                    $currentVersion = [int]$metadata.Version
+    try {
+        Get-ChildItem -LiteralPath $CacheDirectory -Filter 'cache-metadata*.json' -File -ErrorAction Stop |
+            Where-Object { $_.Name -ne $MetadataFileName } |
+                ForEach-Object {
+                    try {
+                        Remove-Item -LiteralPath $_.FullName -Force -ErrorAction Stop
+                    }
+                    catch {
+                        Write-Verbose ("Failed to remove obsolete cache metadata '{0}': {1}" -f $_.FullName, $_.Exception.Message)
+                    }
                 }
-            }
-        }
-        catch {
-            Write-Verbose ("Cache metadata read failed: {0}" -f $_.Exception.Message)
-            $currentVersion = $null
-        }
     }
-
-    $targetVersion = [int]$script:CacheFormatVersion
-    if ($currentVersion -eq $targetVersion) {
-        return
+    catch {
+        Write-Verbose ("Cache metadata cleanup failed: {0}" -f $_.Exception.Message)
     }
 
     try {
@@ -62,7 +81,7 @@ function Update-CacheFormatVersion {
     }
 
     $metadataObject = [pscustomobject]@{
-        Version       = $targetVersion
+        Version       = [int]$script:CacheFormatVersion
         ModuleVersion = $moduleVersion
         UpdatedUtc    = (Get-Date).ToUniversalTime().ToString('o')
     }

ColorScripts-Enhanced/Private/Initialize-CacheDirectory.ps1

@@ -71,10 +71,34 @@ function Initialize-CacheDirectory {
 
         $resolvedCacheDir = Resolve-PreferredDirectoryCandidate -CandidatePaths $candidatePaths -OnCreateFailure $onCreateFailure -OnResolutionFailure $onResolutionFailure
 
+        $metadataFileName = 'cache-metadata-v{0}.json' -f $script:CacheFormatVersion
+        $envValidateValue = $env:COLOR_SCRIPTS_ENHANCED_VALIDATE_CACHE
+        $forceViaEnv = $false
+        if ($envValidateValue -and $envValidateValue -match '^(1|true|yes)$') {
+            $forceViaEnv = $true
+        }
+
         if ($resolvedCacheDir) {
             $script:CacheDir = $resolvedCacheDir
             $script:CacheInitialized = $true
-            Update-CacheFormatVersion -CacheDirectory $script:CacheDir
+
+            $shouldValidate = $false
+            if ($forceViaEnv -or $script:CacheValidationManualOverride) {
+                $shouldValidate = $true
+            }
+            elseif (-not $script:CacheValidationPerformed) {
+                $metadataPath = Join-Path -Path $script:CacheDir -ChildPath $metadataFileName
+                if (-not (Test-Path -LiteralPath $metadataPath -PathType Leaf)) {
+                    $shouldValidate = $true
+                }
+            }
+
+            if ($shouldValidate) {
+                Update-CacheFormatVersion -CacheDirectory $script:CacheDir -MetadataFileName $metadataFileName
+                $script:CacheValidationPerformed = $true
+            }
+
+            $script:CacheValidationManualOverride = $false
             return
         }
 
@@ -99,6 +123,23 @@ function Initialize-CacheDirectory {
 
         $script:CacheDir = $resolvedFallback
         $script:CacheInitialized = $true
-        Update-CacheFormatVersion -CacheDirectory $script:CacheDir
+
+        $shouldValidateFallback = $false
+        if ($forceViaEnv -or $script:CacheValidationManualOverride) {
+            $shouldValidateFallback = $true
+        }
+        elseif (-not $script:CacheValidationPerformed) {
+            $metadataPath = Join-Path -Path $script:CacheDir -ChildPath $metadataFileName
+            if (-not (Test-Path -LiteralPath $metadataPath -PathType Leaf)) {
+                $shouldValidateFallback = $true
+            }
+        }
+
+        if ($shouldValidateFallback) {
+            Update-CacheFormatVersion -CacheDirectory $script:CacheDir -MetadataFileName $metadataFileName
+            $script:CacheValidationPerformed = $true
+        }
+
+        $script:CacheValidationManualOverride = $false
     }
 }

ColorScripts-Enhanced/Public/Show-ColorScript.ps1

@@ -48,6 +48,9 @@ function Show-ColorScript {
     .PARAMETER NoAnsiOutput
         Disable ANSI color codes in informational messages and rendered script text for plain-text environments.
 
+    .PARAMETER ValidateCache
+        Forces cache validation before rendering. Use when you need to rebuild cached colorscript output manually.
+
     .EXAMPLE
         Show-ColorScript
         Displays a random colorscript.
@@ -261,14 +264,21 @@ function Show-ColorScript {
 
         [Parameter()]
         [Alias('NoColor')]
-        [switch]$NoAnsiOutput
+        [switch]$NoAnsiOutput,
+
+        [Parameter()]
+        [switch]$ValidateCache
     )
 
     if ($h) {
         Show-ColorScriptHelp -CommandName 'Show-ColorScript'
         return
     }
 
+    if ($ValidateCache) {
+        Set-CacheValidationOverride -Value $true
+    }
+
     $quietRequested = $Quiet.IsPresent
     $noAnsiRequested = $NoAnsiOutput.IsPresent
 
@@ -483,4 +493,3 @@ function Show-ColorScript {
         return $selection
     }
 }
-

ColorScripts-Enhanced/de/ColorScripts-Enhanced_f77548d7-23eb-48ce-a6e0-f64b4758d995_HelpInfo.xml

@@ -4,7 +4,7 @@
   <SupportedUICultures>
     <UICulture>
       <UICultureName>de</UICultureName>
-      <UICultureVersion>2025.11.05.1912</UICultureVersion>
+      <UICultureVersion>2025.11.05.2125</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>

ColorScripts-Enhanced/en-US/ColorScripts-Enhanced_f77548d7-23eb-48ce-a6e0-f64b4758d995_HelpInfo.xml

@@ -4,7 +4,7 @@
   <SupportedUICultures>
     <UICulture>
       <UICultureName>en-US</UICultureName>
-      <UICultureVersion>2025.11.05.1912</UICultureVersion>
+      <UICultureVersion>2025.11.05.2125</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>

ColorScripts-Enhanced/es/ColorScripts-Enhanced_f77548d7-23eb-48ce-a6e0-f64b4758d995_HelpInfo.xml

@@ -4,7 +4,7 @@
   <SupportedUICultures>
     <UICulture>
       <UICultureName>es</UICultureName>
-      <UICultureVersion>2025.11.05.1912</UICultureVersion>
+      <UICultureVersion>2025.11.05.2125</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>

ColorScripts-Enhanced/fr/ColorScripts-Enhanced_f77548d7-23eb-48ce-a6e0-f64b4758d995_HelpInfo.xml

@@ -4,7 +4,7 @@
   <SupportedUICultures>
     <UICulture>
       <UICultureName>fr</UICultureName>
-      <UICultureVersion>2025.11.05.1912</UICultureVersion>
+      <UICultureVersion>2025.11.05.2125</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>

ColorScripts-Enhanced/it/ColorScripts-Enhanced_f77548d7-23eb-48ce-a6e0-f64b4758d995_HelpInfo.xml

@@ -4,7 +4,7 @@
   <SupportedUICultures>
     <UICulture>
       <UICultureName>it</UICultureName>
-      <UICultureVersion>2025.11.05.1912</UICultureVersion>
+      <UICultureVersion>2025.11.05.2125</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>

ColorScripts-Enhanced/ja/ColorScripts-Enhanced_f77548d7-23eb-48ce-a6e0-f64b4758d995_HelpInfo.xml

@@ -4,7 +4,7 @@
   <SupportedUICultures>
     <UICulture>
       <UICultureName>ja</UICultureName>
-      <UICultureVersion>2025.11.05.1912</UICultureVersion>
+      <UICultureVersion>2025.11.05.2125</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>