refactor(ci): fix caching and improve [ci-] tag handling

.github/actions/xahau-ga-build/action.yml

@@ -47,6 +47,18 @@ inputs:
     description: 'GCC version to use for Clang toolchain (e.g. 11, 13)'
     required: false
     default: ''
+  ccache_max_size:
+    description: 'Maximum ccache size'
+    required: false
+    default: '2G'
+  ccache_hash_dir:
+    description: 'Whether to include directory paths in hash'
+    required: false
+    default: 'true'
+  ccache_compiler_check:
+    description: 'How to check compiler for changes'
+    required: false
+    default: 'content'
 
 runs:
   using: 'composite'
@@ -59,28 +71,63 @@ runs:
         SAFE_BRANCH=$(echo "${{ github.ref_name }}" | tr -c 'a-zA-Z0-9_.-' '-')
         echo "name=${SAFE_BRANCH}" >> $GITHUB_OUTPUT
 
-    - name: Restore ccache directory for default branch
+    - name: Restore ccache directory for main branch
       if: inputs.ccache_enabled == 'true'
       id: ccache-restore
-      uses: actions/cache/restore@v4
+      uses: ./.github/actions/xahau-ga-cache-restore
       with:
         path: ~/.ccache-main
         key: ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ inputs.main_branch }}
         restore-keys: |
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-
+        cache-type: ccache-main
 
     - name: Restore ccache directory for current branch
       if: inputs.ccache_enabled == 'true' && steps.safe-branch.outputs.name != inputs.main_branch
       id: ccache-restore-current-branch
-      uses: actions/cache/restore@v4
+      uses: ./.github/actions/xahau-ga-cache-restore
       with:
         path: ~/.ccache-current
         key: ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ steps.safe-branch.outputs.name }}
         restore-keys: |
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-${{ inputs.main_branch }}
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-${{ inputs.configuration }}-
           ${{ runner.os }}-ccache-v${{ inputs.cache_version }}-${{ inputs.compiler-id }}-
+        cache-type: ccache-current
+
+    - name: Configure ccache
+      if: inputs.ccache_enabled == 'true'
+      shell: bash
+      run: |
+        # Create cache directories
+        mkdir -p ~/.ccache-main ~/.ccache-current
+
+        # Configure ccache settings AFTER cache restore (prevents stale cached config)
+        ccache --set-config=max_size=${{ inputs.ccache_max_size }}
+        ccache --set-config=hash_dir=${{ inputs.ccache_hash_dir }}
+        ccache --set-config=compiler_check=${{ inputs.ccache_compiler_check }}
+
+        # Determine if we're on the main branch
+        if [ "${{ steps.safe-branch.outputs.name }}" = "${{ inputs.main_branch }}" ]; then
+          # Main branch: use main branch cache only
+          ccache --set-config=cache_dir="$HOME/.ccache-main"
+          echo "CCACHE_DIR=$HOME/.ccache-main" >> $GITHUB_ENV
+          echo "📦 Main branch: using ~/.ccache-main"
+        else
+          # Feature branch: use current branch cache with main as secondary (read-only fallback)
+          ccache --set-config=cache_dir="$HOME/.ccache-current"
+          ccache --set-config=secondary_storage="file:$HOME/.ccache-main"
+          echo "CCACHE_DIR=$HOME/.ccache-current" >> $GITHUB_ENV
+          echo "📦 Feature branch: using ~/.ccache-current with ~/.ccache-main as secondary"
+        fi
+
+        # Print config for verification
+        echo "=== ccache configuration ==="
+        ccache -p
+
+        # Zero statistics before the build
+        ccache -z
 
     - name: Configure project
       shell: bash
@@ -96,14 +143,27 @@ runs:
         if [ -n "${{ inputs.cxx }}" ]; then
           export CXX="${{ inputs.cxx }}"
         fi
-
-
-        # Configure ccache launcher args
-        CCACHE_ARGS=""
+
+        # Create wrapper toolchain that overlays ccache on top of Conan's toolchain
+        # This enables ccache for the main app build without affecting Conan dependency builds
         if [ "${{ inputs.ccache_enabled }}" = "true" ]; then
-          CCACHE_ARGS="-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache"
+          cat > wrapper_toolchain.cmake <<'EOF'
+        # Include Conan's generated toolchain first (sets compiler, flags, etc.)
+        # Note: CMAKE_CURRENT_LIST_DIR is the directory containing this wrapper (.build/)
+        include(${CMAKE_CURRENT_LIST_DIR}/build/generators/conan_toolchain.cmake)
+
+        # Overlay ccache configuration for main application build
+        # This does NOT affect Conan dependency builds (already completed)
+        set(CMAKE_C_COMPILER_LAUNCHER ccache CACHE STRING "C compiler launcher" FORCE)
+        set(CMAKE_CXX_COMPILER_LAUNCHER ccache CACHE STRING "C++ compiler launcher" FORCE)
+        EOF
+          TOOLCHAIN_FILE="wrapper_toolchain.cmake"
+          echo "✅ Created wrapper toolchain with ccache enabled"
+        else
+          TOOLCHAIN_FILE="build/generators/conan_toolchain.cmake"
+          echo "ℹ️  Using Conan toolchain directly (ccache disabled)"
         fi
-        
+
         # Configure C++ standard library if specified
         # libstdcxx used for clang-14/16 to work around missing lexicographical_compare_three_way in libc++
         # libcxx can be used with clang-17+ which has full C++20 support
@@ -143,31 +203,48 @@ runs:
         # So we get: .build/build/generators/ with our non-standard folder name
         cmake .. \
           -G "${{ inputs.generator }}" \
-          $CCACHE_ARGS \
           ${CMAKE_CXX_FLAGS:+-DCMAKE_CXX_FLAGS="$CMAKE_CXX_FLAGS"} \
-          -DCMAKE_TOOLCHAIN_FILE:FILEPATH=build/generators/conan_toolchain.cmake \
+          -DCMAKE_TOOLCHAIN_FILE:FILEPATH=${TOOLCHAIN_FILE} \
           -DCMAKE_BUILD_TYPE=${{ inputs.configuration }}
 
+    - name: Show ccache config before build
+      if: inputs.ccache_enabled == 'true'
+      shell: bash
+      run: |
+        echo "=========================================="
+        echo "ccache configuration before build"
+        echo "=========================================="
+        ccache -p
+        echo ""
+
     - name: Build project
       shell: bash
       run: |
         cd ${{ inputs.build_dir }}
-        cmake --build . --config ${{ inputs.configuration }} --parallel $(nproc)
+
+        # Check for verbose build flag in commit message
+        VERBOSE_FLAG=""
+        if echo "${XAHAU_GA_COMMIT_MSG}" | grep -q '\[ci-ga-cmake-verbose\]'; then
+          echo "🔊 [ci-ga-cmake-verbose] detected - enabling verbose output"
+          VERBOSE_FLAG="-- -v"
+        fi
+
+        cmake --build . --config ${{ inputs.configuration }} --parallel $(nproc) ${VERBOSE_FLAG}
 
     - name: Show ccache statistics
       if: inputs.ccache_enabled == 'true'
       shell: bash
       run: ccache -s
 
-    - name: Save ccache directory for default branch
-      if: always() && inputs.ccache_enabled == 'true' && steps.safe-branch.outputs.name == inputs.main_branch
+    - name: Save ccache directory for main branch
+      if: success() && inputs.ccache_enabled == 'true' && steps.safe-branch.outputs.name == inputs.main_branch
       uses: actions/cache/save@v4
       with:
         path: ~/.ccache-main
         key: ${{ steps.ccache-restore.outputs.cache-primary-key }}
 
     - name: Save ccache directory for current branch
-      if: always() && inputs.ccache_enabled == 'true' && steps.safe-branch.outputs.name != inputs.main_branch
+      if: success() && inputs.ccache_enabled == 'true' && steps.safe-branch.outputs.name != inputs.main_branch
       uses: actions/cache/save@v4
       with:
         path: ~/.ccache-current

.github/actions/xahau-ga-cache-restore/action.yml

@@ -0,0 +1,146 @@
+name: 'Cache Restore'
+description: 'Restores cache with optional clearing based on commit message tags'
+
+inputs:
+  path:
+    description: 'A list of files, directories, and wildcard patterns to cache'
+    required: true
+  key:
+    description: 'An explicit key for restoring the cache'
+    required: true
+  restore-keys:
+    description: 'An ordered list of prefix-matched keys to use for restoring stale cache if no cache hit occurred for key'
+    required: false
+    default: ''
+  cache-type:
+    description: 'Type of cache (for logging purposes, e.g., "ccache-main", "Conan")'
+    required: false
+    default: 'cache'
+  fail-on-cache-miss:
+    description: 'Fail the workflow if cache entry is not found'
+    required: false
+    default: 'false'
+  lookup-only:
+    description: 'Check if a cache entry exists for the given input(s) without downloading it'
+    required: false
+    default: 'false'
+  additional-clear-keys:
+    description: 'Additional cache keys to clear (newline separated)'
+    required: false
+    default: ''
+
+outputs:
+  cache-hit:
+    description: 'A boolean value to indicate an exact match was found for the primary key'
+    value: ${{ steps.restore-cache.outputs.cache-hit }}
+  cache-primary-key:
+    description: 'The key that was used to restore the cache'
+    value: ${{ steps.restore-cache.outputs.cache-primary-key }}
+  cache-matched-key:
+    description: 'The key that was used to restore the cache (exact or prefix match)'
+    value: ${{ steps.restore-cache.outputs.cache-matched-key }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Clear cache if requested via commit message
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        echo "=========================================="
+        echo "${{ inputs.cache-type }} cache clear tag detection"
+        echo "=========================================="
+        echo "Searching for: [ci-ga-clear-cache] or [ci-ga-clear-cache:*]"
+        echo ""
+
+        CACHE_KEY="${{ inputs.key }}"
+
+        # Extract search terms if present (e.g., "ccache" from "[ci-ga-clear-cache:ccache]")
+        SEARCH_TERMS=$(echo "${XAHAU_GA_COMMIT_MSG}" | grep -o '\[ci-ga-clear-cache:[^]]*\]' | sed 's/\[ci-ga-clear-cache://;s/\]//' || echo "")
+
+        SHOULD_CLEAR=false
+
+        if [ -n "${SEARCH_TERMS}" ]; then
+          # Search terms provided - check if THIS cache key matches ALL terms (AND logic)
+          echo "🔍 [ci-ga-clear-cache:${SEARCH_TERMS}] detected"
+          echo "Checking if cache key matches search terms..."
+          echo "  Cache key: ${CACHE_KEY}"
+          echo "  Search terms: ${SEARCH_TERMS}"
+          echo ""
+
+          MATCHES=true
+          for term in ${SEARCH_TERMS}; do
+            if ! echo "${CACHE_KEY}" | grep -q "${term}"; then
+              MATCHES=false
+              echo "  ✗ Key does not contain '${term}'"
+              break
+            else
+              echo "  ✓ Key contains '${term}'"
+            fi
+          done
+
+          if [ "${MATCHES}" = "true" ]; then
+            echo ""
+            echo "✅ Cache key matches all search terms - will clear cache"
+            SHOULD_CLEAR=true
+          else
+            echo ""
+            echo "⏭️  Cache key doesn't match search terms - skipping cache clear"
+          fi
+        elif echo "${XAHAU_GA_COMMIT_MSG}" | grep -q '\[ci-ga-clear-cache\]'; then
+          # No search terms - always clear this job's cache
+          echo "🗑️  [ci-ga-clear-cache] detected in commit message"
+          echo "Clearing ${{ inputs.cache-type }} cache for key: ${CACHE_KEY}"
+          SHOULD_CLEAR=true
+        fi
+
+        if [ "${SHOULD_CLEAR}" = "true" ]; then
+          echo ""
+          echo "Deleting ${{ inputs.cache-type }} caches via GitHub API..."
+
+          # Delete primary cache key
+          echo "Checking for cache: ${CACHE_KEY}"
+          if gh cache list --key "${CACHE_KEY}" --json key --jq '.[].key' | grep -q "${CACHE_KEY}"; then
+            echo "  Deleting: ${CACHE_KEY}"
+            gh cache delete "${CACHE_KEY}" || true
+            echo "  ✓ Deleted"
+          else
+            echo "  ℹ️  Not found"
+          fi
+
+          # Delete additional keys if provided
+          if [ -n "${{ inputs.additional-clear-keys }}" ]; then
+            echo ""
+            echo "Checking additional keys..."
+            while IFS= read -r key; do
+              [ -z "${key}" ] && continue
+              echo "Checking for cache: ${key}"
+              if gh cache list --key "${key}" --json key --jq '.[].key' | grep -q "${key}"; then
+                echo "  Deleting: ${key}"
+                gh cache delete "${key}" || true
+                echo "  ✓ Deleted"
+              else
+                echo "  ℹ️  Not found"
+              fi
+            done <<< "${{ inputs.additional-clear-keys }}"
+          fi
+
+          echo ""
+          echo "✅ ${{ inputs.cache-type }} cache cleared successfully"
+          echo "Build will proceed from scratch"
+        else
+          echo ""
+          echo "ℹ️  No ${{ inputs.cache-type }} cache clear requested"
+        fi
+        echo "=========================================="
+
+    - name: Restore cache
+      id: restore-cache
+      uses: actions/cache/restore@v4
+      with:
+        path: ${{ inputs.path }}
+        key: ${{ inputs.key }}
+        restore-keys: ${{ inputs.restore-keys }}
+        fail-on-cache-miss: ${{ inputs.fail-on-cache-miss }}
+        lookup-only: ${{ inputs.lookup-only }}