🛠️ [fix] Add cache-format upgrade workflow, unify colorscript execution, and bump module/help versions

✨ [feat] Add Ensure-CacheFormatVersion.ps1
 - 🧩 Implements Update-CacheFormatVersion to manage cache-metadata.json (Version, ModuleVersion, UpdatedUtc) and purge existing *.cache files when the format version changes.
 - ⚠️ Includes robust error handling and Write-Verbose diagnostics to avoid breaking initialization on IO/parse failures.

🚜 [refactor] Integrate cache-format upgrade into initialization
 - 🔁 Call Update-CacheFormatVersion from Initialize-CacheDirectory immediately after resolving/creating the cache directory (both primary resolution and fallback) so caches are validated/upgraded and stale .cache files are removed automatically.

🚜 [refactor] Unify colorscript execution to isolated process
 - 🖥️ Remove the fast in-process execution path and always spawn an isolated PowerShell process to preserve ANSI sequences and console rendering fidelity.
 - 🧭 When running for cache builds (ForCache), set child env var COLOR_SCRIPTS_ENHANCED_CACHE_BUILD='1' so the subprocess can detect cache-build context; fail-safe verbose handling if env cannot be written.

🔧 [build] Bump ModuleVersion and update ReleaseNotes
 - 🔢 Update ModuleVersion to '2025.11.05.1912' in the module manifest and adjust the ReleaseNotes header to the new stamp.

📝 [docs] Sync localized HelpInfo UICultureVersion stamps
 - 🌐 Update SupportedUICultures / UICultureVersion for localized HelpInfo.xml files (en-US, de, es, fr, it, ja, nl, pt, ru, zh-CN) to match the new module stamp.

🧪 [test] Update tests to initialize cache directory and pass explicit cache path
 - 🔎 Tests now call Initialize-CacheDirectory inside module scope to retrieve $script:CacheDir and pass the explicit testCachePath into test blocks, ensuring tests operate on the real cache location and not an assumed variable.

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.1634'
+    ModuleVersion = '2025.11.05.1912'
 
     # Supported PSEditions
     CompatiblePSEditions = @('Desktop', 'Core')
@@ -211,7 +211,7 @@ PERFECT FOR
 
             # ReleaseNotes of this module
             ReleaseNotes = @'
-Version 2025.11.05.1634:
+Version 2025.11.05.1912:
 - Enhanced caching system with OS-wide cache in AppData
 - 6-19x performance improvement
 - Cache stored in centralized location

ColorScripts-Enhanced/Private/Ensure-CacheFormatVersion.ps1

@@ -0,0 +1,79 @@
+if (-not $script:CacheFormatVersion) {
+    $script:CacheFormatVersion = 2
+}
+
+function Update-CacheFormatVersion {
+    param(
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string]$CacheDirectory
+    )
+
+    if (-not (Test-Path -LiteralPath $CacheDirectory -PathType Container)) {
+        return
+    }
+
+    $metadataPath = Join-Path -Path $CacheDirectory -ChildPath 'cache-metadata.json'
+    $currentVersion = $null
+
+    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
+                }
+            }
+        }
+        catch {
+            Write-Verbose ("Cache metadata read failed: {0}" -f $_.Exception.Message)
+            $currentVersion = $null
+        }
+    }
+
+    $targetVersion = [int]$script:CacheFormatVersion
+    if ($currentVersion -eq $targetVersion) {
+        return
+    }
+
+    try {
+        Get-ChildItem -LiteralPath $CacheDirectory -Filter '*.cache' -File -ErrorAction Stop | ForEach-Object {
+            try {
+                Remove-Item -LiteralPath $_.FullName -Force -ErrorAction Stop
+            }
+            catch {
+                Write-Verbose ("Failed to remove cache file '{0}': {1}" -f $_.FullName, $_.Exception.Message)
+            }
+        }
+    }
+    catch {
+        Write-Verbose ("Cache purge enumeration failed: {0}" -f $_.Exception.Message)
+    }
+
+    $moduleVersion = $null
+    try {
+        if ($ExecutionContext.SessionState -and $ExecutionContext.SessionState.Module) {
+            $moduleVersion = $ExecutionContext.SessionState.Module.Version.ToString()
+        }
+    }
+    catch {
+        $moduleVersion = $null
+    }
+
+    $metadataObject = [pscustomobject]@{
+        Version       = $targetVersion
+        ModuleVersion = $moduleVersion
+        UpdatedUtc    = (Get-Date).ToUniversalTime().ToString('o')
+    }
+
+    $metadataJson = $metadataObject | ConvertTo-Json -Depth 3
+    $encoding = New-Object System.Text.UTF8Encoding($false)
+
+    try {
+        [System.IO.File]::WriteAllText($metadataPath, $metadataJson, $encoding)
+    }
+    catch {
+        Write-Verbose ("Cache metadata write failed: {0}" -f $_.Exception.Message)
+    }
+}

ColorScripts-Enhanced/Private/Initialize-CacheDirectory.ps1

@@ -74,6 +74,7 @@ function Initialize-CacheDirectory {
         if ($resolvedCacheDir) {
             $script:CacheDir = $resolvedCacheDir
             $script:CacheInitialized = $true
+            Update-CacheFormatVersion -CacheDirectory $script:CacheDir
             return
         }
 
@@ -98,5 +99,6 @@ function Initialize-CacheDirectory {
 
         $script:CacheDir = $resolvedFallback
         $script:CacheInitialized = $true
+        Update-CacheFormatVersion -CacheDirectory $script:CacheDir
     }
 }

ColorScripts-Enhanced/Private/Invoke-ColorScriptProcess.ps1

@@ -1,9 +1,8 @@
 function Invoke-ColorScriptProcess {
     <#
     .SYNOPSIS
-        Executes a colorscript and captures its output.
-        For cache building, uses fast in-process execution.
-        For display, can use isolated process if needed.
+        Executes a colorscript and captures its output using an isolated process
+        to preserve ANSI sequences and console rendering fidelity.
     #>
     [CmdletBinding()]
     param(
@@ -28,39 +27,6 @@ function Invoke-ColorScriptProcess {
         return $result
     }
 
-    # Fast in-process execution for cache building
-    if ($ForCache) {
-        try {
-            $oldLocation = Get-Location -PSProvider FileSystem
-            $scriptDirectory = [System.IO.Path]::GetDirectoryName($ScriptPath)
-            if ($scriptDirectory) {
-                Set-Location -LiteralPath $scriptDirectory -ErrorAction SilentlyContinue
-            }
-
-            $scriptContent = & $script:FileReadAllTextDelegate $ScriptPath $script:Utf8NoBomEncoding
-            $scriptBlock = [ScriptBlock]::Create($scriptContent)
-
-            $output = & $scriptBlock *>&1 | Out-String
-
-            $result.StdOut = $output
-            $result.ExitCode = 0
-            $result.Success = $true
-        }
-        catch {
-            $result.StdErr = $_.Exception.Message
-            $result.ExitCode = 1
-            $result.Success = $false
-        }
-        finally {
-            if ($oldLocation) {
-                Set-Location -LiteralPath $oldLocation -ErrorAction SilentlyContinue
-            }
-        }
-
-        return $result
-    }
-
-    # Original isolated process execution for display
     $executable = Get-PowerShellExecutable
     $scriptDirectory = [System.IO.Path]::GetDirectoryName($ScriptPath)
     $process = $null
@@ -86,6 +52,15 @@ function Invoke-ColorScriptProcess {
         $startInfo.StandardOutputEncoding = [System.Text.Encoding]::UTF8
         $startInfo.StandardErrorEncoding = [System.Text.Encoding]::UTF8
 
+        if ($ForCache) {
+            try {
+                $startInfo.EnvironmentVariables['COLOR_SCRIPTS_ENHANCED_CACHE_BUILD'] = '1'
+            }
+            catch {
+                Write-Verbose ("Unable to set cache build environment variable: {0}" -f $_.Exception.Message)
+            }
+        }
+
         if ($scriptDirectory) {
             $startInfo.WorkingDirectory = $scriptDirectory
         }

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.1634</UICultureVersion>
+      <UICultureVersion>2025.11.05.1912</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.1634</UICultureVersion>
+      <UICultureVersion>2025.11.05.1912</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.1634</UICultureVersion>
+      <UICultureVersion>2025.11.05.1912</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.1634</UICultureVersion>
+      <UICultureVersion>2025.11.05.1912</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.1634</UICultureVersion>
+      <UICultureVersion>2025.11.05.1912</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.1634</UICultureVersion>
+      <UICultureVersion>2025.11.05.1912</UICultureVersion>
     </UICulture>
   </SupportedUICultures>
 </HelpInfo>