# node_modules cache scripts

Shared helpers used by the GitHub Actions workflows to store and restore the
`node_modules` cache. They exist so the archive format and compression flags
live in a single place instead of being duplicated across every workflow.

Each script takes an action argument:

| Script | Platform | `archive` | `extract` |
| ------ | -------- | --------- | --------- |
| `cache.sh <action>` | Linux / macOS | Create `node-modules.tzst` (cache miss) | Restore `node-modules.tzst` (cache hit) |
| `cache.ps1 <action>` | Windows | Create `cache.7z` (cache miss) | Restore `cache.7z` (cache hit) |

Linux/macOS use multi-threaded `zstd` (`node-modules.tzst`); Windows uses 7-Zip
(`cache.7z`). The archive must NOT be named `cache.tzst`: `actions/cache` names
its own tarball `cache.tzst` and passes `--exclude cache.tzst`, which would drop
our archive and save an empty cache. The two families are not interchangeable,
so the cache key already encodes the OS (`node_modules-linux-*`,
`node_modules-windows-*`, …).

Example usage from a workflow step:

```yaml
- name: Extract node_modules cache
  if: steps.cache-node-modules.outputs.cache-hit == 'true'
  run: ./.github/workflows/node_modules_cache/cache.sh extract

- name: Create node_modules archive
  if: steps.cache-node-modules.outputs.cache-hit != 'true'
  run: ./.github/workflows/node_modules_cache/cache.sh archive
```

If you change the archive format or flags, update both the `archive` and
`extract` branch of the script, and bump `build/.cachesalt` to invalidate
existing caches.