# 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.

## Electron download cache

The platform jobs in [pr-node-modules.yml](../pr-node-modules.yml) also warm a
separate Electron download cache on `main`. The
[setup-electron](../../actions/setup-electron/action.yml) action shares cache
handling and download retries with the Linux, macOS, and Windows PR test
workflows:

- By default, restore cached archives and validate/prepare Electron, downloading
  with up to three attempts as needed. PR jobs use this mode without saving.
- `lookup-only: 'true'` only checks for a cache entry, without restoring archives,
  preparing Electron, or saving. This mode does not require npm dependencies.
- `save-cache: 'true'` also saves after successful setup on a cache miss.

The cache stores `@electron/get`'s original download archives, not the prepared
`.build/electron` application. Its key includes the runner OS, target
architecture, and a hash of `.npmrc` and `build/checksums/electron.txt`. Ordinary
`package-lock.json` changes do not invalidate it. If a downloader update changes
the cache format, bump the `electron-download-v1` prefix in `setup-electron`.

The paths match `@electron/get`'s platform defaults, including `XDG_CACHE_HOME`
on Linux and `LOCALAPPDATA` on Windows. Cache paths and keys are handled within
the action.

Even on a cache hit, PR jobs run `npm run electron` to validate and prepare the
application from the cached archives using the current checkout. Checksum
validation remains enabled: the current downloader still fetches
`SHASUMS256.txt` from GitHub, so this cache avoids the large ZIP downloads but
does not make Electron setup entirely network-independent.

On `main`, an Electron cache hit uses lookup-only checks and skips downloading
Electron. On a miss, the platform job restores `node_modules` (or installs them
if that cache also misses), then invokes `setup-electron` with `save-cache: 'true'`.
This checks the cache again before preparing and saving Electron, while keeping
already-warm jobs from extracting dependency archives unnecessarily.