name: 'Cache Restore'
description: 'Restore cache from tar.xz archive on the runner filesystem'
inputs:
  path:
    description: 'Directory to cache'
    required: false
    default: ${{ github.workspace }}
  key-prefix:
    description: 'Prefix for the cache key'
    required: true
  key-file:
    description: 'File to hash for the cache key'
    required: true
outputs:
  cache-hit:
    description: 'true if exact key match found, false otherwise'
    value: ${{ steps.restore.outputs.cache-hit }}
runs:
  using: "composite"
  steps:
    - name: Restore cache
      id: restore
      shell: bash
      run: |
        CACHE_DIR="$HOME/.cache/.cache-store"
        mkdir -p "$CACHE_DIR"

        KEY_HASH=$(sha256sum "${{ inputs.key-file }}" | awk '{print $1}')
        CACHE_KEY="${{ inputs.key-prefix }}-${KEY_HASH}"
        ARCHIVE="${CACHE_DIR}/${CACHE_KEY}.tar.xz"

        EXPANDED_PATH=$(eval echo "${{ inputs.path }}")

        echo "Key file: ${{ inputs.key-file }}"
        echo "Path input: ${{ inputs.path }}"
        echo "Expanded path: ${EXPANDED_PATH}"
        echo "Cache key: ${CACHE_KEY}"
        echo "Archive path: ${ARCHIVE}"

        if [ -f "$ARCHIVE" ]; then
          echo "Cache hit: ${CACHE_KEY}"
          mkdir -p "$EXPANDED_PATH"
          # New-format archives hold entries relative to the cached directory
          # (<basename>/...), so extract into the parent of the requested
          # path. Legacy archives embed the absolute path of the run that
          # saved them; fall back to extracting them to "/" (status quo,
          # they are TTL-pruned within the retention window anyway).
          # NOTE: `|| true` is mandatory — act runs step scripts with
          # `bash -e -o pipefail`, and `head -1` closes the pipe after the
          # first line, so tar dies with SIGPIPE (141) and pipefail turns
          # that into a step failure (restore only ever "worked" before
          # this detection line existed).
          FIRST_ENTRY=$(tar -tf "$ARCHIVE" 2>/dev/null | head -1 || true)
          if [ "${FIRST_ENTRY%%/*}" = "$(basename "$EXPANDED_PATH")" ]; then
            echo "Restoring to: $(dirname "$EXPANDED_PATH")"
            tar -xf "$ARCHIVE" -C "$(dirname "$EXPANDED_PATH")" 2>/dev/null
          else
            tar -xf "$ARCHIVE" -C "/" 2>/dev/null
          fi
          if [ -d "$EXPANDED_PATH" ] && [ -n "$(ls -A "$EXPANDED_PATH" 2>/dev/null)" ]; then
            # record last use so the retention policy can expire by access time
            touch "$ARCHIVE"
            echo "cache-hit=true" >> $GITHUB_OUTPUT
          else
            echo "Cache restore failed"
            echo "cache-hit=false" >> $GITHUB_OUTPUT
          fi
        else
          echo "Cache miss: ${CACHE_KEY}"
          echo "cache-hit=false" >> $GITHUB_OUTPUT
        fi

        # Trim the shared cache store and stale workspaces (best-effort)
        bash "${{ github.action_path }}/prune.sh" || true