Cache Action
============

A Gitea Action that caches build files as `tar.xz` archives on the runner filesystem. Simple, fast, no external dependencies.

## Inputs

| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `path` | Single directory to cache | No | `~/.cache/` |
| `key-prefix` | Prefix for the cache key | Yes | — |
| `key-file` | File to hash (SHA-256) for the cache key | Yes | — |

## Outputs

| Output | Description |
|--------|-------------|
| `cache-hit` | `true` if exact key match found, `false` otherwise |

## How It Works

1. Hashes `key-file` with SHA-256, combines with `key-prefix` as `<prefix>-<hash>`
2. Stores archives at `~/.cache/.cache-store/<key>.tar.xz`
3. Restores by extracting the archive to `/`, saves by creating one
4. Saves atomically (write to `<key>.tar.xz.tmp`, then rename)
5. Archives store the cached directory **relative** (`<basename>/...`), not its
   absolute path — a later run restores into its own `path` location, so the
   cache works across runs even though each run gets a fresh workspace

## Cache Retention

Archives are content-addressed, so old keys are never needed again — the store
is pruned automatically on every restore/save (best-effort, safe under
concurrent runners):

- The newest `CACHE_KEEP_N` (default `3`) archives per key-prefix family are
  always kept, so reverting e.g. `Cargo.lock` still hits an older key
- Anything older than `CACHE_TTL_DAYS` (default `7`) outside the keep set is
  deleted
- A hard size cap `CACHE_CAP_GB` (default `2`) deletes oldest-first when
  exceeded
- Files younger than 1 hour are never touched (in-flight save protection)
- Stale run workspaces under `~/.cache/act/*/hostexecutor` older than
  `CACHE_WORKSPACE_TTL_DAYS` (default `2`) are removed

Override the defaults per-job via `env:` (e.g. `env: { CACHE_KEEP_N: 5 }`).

## Usage

This action must be used **twice** in your workflow:

1. **Before build** — restores cache if it exists
2. **After build** — saves the cache archive (only on cache miss)

## Rust Example

```yaml
name: Rust Build
on: push

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 1. Restore cache before build
      - uses: Actions/Cache@main
        id: cache
        with:
          key-prefix: 'cargo-registry'
          key-file: 'Cargo.lock'
          path: '~/.cargo/registry'

      - name: Build
        run: cargo build --release

      # 2. Save cache after build
      - uses: Actions/Cache@main
        with:
          key-prefix: 'cargo-registry'
          key-file: 'Cargo.lock'
          path: '~/.cargo/registry'
```

## Skip Steps on Cache Hit

```yaml
name: Build with Conditional Steps
on: push

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 1. Restore cache
      - uses: Actions/Cache@main
        id: cache
        with:
          key-prefix: 'rust'
          key-file: 'Cargo.lock'
          path: '~/.cargo/registry'

      - name: Fetch dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: cargo fetch

      - name: Build
        run: cargo build --release

      # 2. Save cache
      - uses: Actions/Cache@main
        with:
          key-prefix: 'rust'
          key-file: 'Cargo.lock'
          path: '~/.cargo/registry'
```