ci: keep npm download caches from Turbo snapshot growth (#5655)

* ci: keep npm download caches from Turbo snapshot growth

Per-commit static and portable Turbo snapshots had filled the 10 GB Actions
cache, which is what makes warm npm ci cheap. Trusted static runs now keep two
generations and one download-cache writer per host.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(ci): declare cache retention types for strict checks

Typecheck imports cache-retention.mjs and needs a sibling declaration.
The generation count stays module-private so knip does not report it.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(ci): keep compatible caches and qualification read-only

Npm dedupe deletes a record only when another has the same key, version,
and ref. Cache deletion moves to a follow-up workflow so reusable
qualification can keep its read-only token.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(ci): retain caches after failed default-branch runs

Static and build save Turbo snapshots before later lanes finish. Retention
now follows a failed, timed-out, or cancelled trusted run, not only a green one.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* test(cli): pass application trace input as a file

The CLI already reads workflow JSON from a path. Putting the full
application Evidence document on argv exceeds the runner argument limit.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(ci): retain deep and Knip snapshots without deleting a repeated id

Fast and deep static checks publish rea-static-deep-v1 and knip-meta-v1
entries per commit. Retention prunes those families with the same two-generation
rule. A cache id listed twice is one record; inconsistent repeats abort
before any delete.

Co-authored-by: morluto <morluto@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>

.github/actions/npm-cache/action.yml

@@ -1,5 +1,10 @@
 name: Cache npm package downloads
-description: Restore npm's download cache and save it only from trusted default-branch events.
+description: Restore npm's download cache. Trusted default-branch jobs that opt in may save it.
+inputs:
+  save:
+    description: Save the shared download cache when this event is allowed to write it.
+    required: false
+    default: "false"
 outputs:
   can-save:
     description: Whether this run may update the shared npm download cache.
@@ -23,20 +28,25 @@ runs:
           can_save=true
         fi
         cache_key="npm-download-${RUNNER_OS}-${runtime_arch}-${LOCKFILES_HASH}"
+        # Same platform only. A lockfile change can reuse tarballs from the previous key.
+        restore_key="npm-download-${RUNNER_OS}-${runtime_arch}-"
         {
           printf 'can-save=%s\n' "${can_save}"
           printf 'path=%s\n' "${cache_path}"
           printf 'key=%s\n' "${cache_key}"
+          printf 'restore-key=%s\n' "${restore_key}"
         } >> "${GITHUB_OUTPUT}"
     - name: Restore and save npm package downloads
-      if: steps.context.outputs.can-save == 'true'
+      if: steps.context.outputs.can-save == 'true' && inputs.save == 'true'
       uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
       with:
         path: ${{ steps.context.outputs.path }}
         key: ${{ steps.context.outputs.key }}
+        restore-keys: ${{ steps.context.outputs.restore-key }}
     - name: Restore npm package downloads without saving
-      if: steps.context.outputs.can-save != 'true'
+      if: steps.context.outputs.can-save != 'true' || inputs.save != 'true'
       uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
       with:
         path: ${{ steps.context.outputs.path }}
         key: ${{ steps.context.outputs.key }}
+        restore-keys: ${{ steps.context.outputs.restore-key }}

.github/workflows/cache-retention.yml

@@ -0,0 +1,57 @@
+name: Cache retention
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+# Qualification calls ci.yml with actions: read. A nested workflow cannot raise
+# that token, so cache deletion stays in this workflow.
+permissions:
+  contents: read
+  actions: write
+
+concurrency:
+  group: cache-retention-${{ github.event.workflow_run.head_sha }}
+  cancel-in-progress: false
+
+jobs:
+  retain:
+    name: Retain Turbo snapshots and npm download caches
+    # Checkout and run only a same-repository default-branch commit. Pull
+    # requests, including forks, do not reach these steps. Static and build
+    # save Turbo snapshots before later lanes finish, so a failed, timed-out,
+    # or cancelled run still retains those snapshots.
+    if: >-
+      (github.event.workflow_run.conclusion == 'success' ||
+      github.event.workflow_run.conclusion == 'failure' ||
+      github.event.workflow_run.conclusion == 'timed_out' ||
+      github.event.workflow_run.conclusion == 'cancelled') &&
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      github.event.workflow_run.head_branch == github.event.repository.default_branch &&
+      (github.event.workflow_run.event == 'push' ||
+      github.event.workflow_run.event == 'schedule' ||
+      github.event.workflow_run.event == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version-file: .nvmrc
+      - name: Retain current Turbo snapshots and npm download caches
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CI_REPOSITORY: ${{ github.repository }}
+          CACHE_PREFIX: rea-static-v1-${{ runner.os }}-${{ runner.arch }}-
+          CACHE_KEEP_KEY: rea-static-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', '.npmrc', 'package-lock.json') }}-${{ github.event.workflow_run.head_sha }}
+          CACHE_DEEP_PREFIX: rea-static-deep-v1-${{ runner.os }}-${{ runner.arch }}-
+          CACHE_DEEP_KEEP_KEY: rea-static-deep-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', '.npmrc', 'package-lock.json') }}-${{ github.event.workflow_run.head_sha }}
+          CACHE_KNIP_PREFIX: knip-meta-v1-${{ runner.os }}-
+          CACHE_KNIP_KEEP_KEY: knip-meta-v1-${{ runner.os }}-${{ hashFiles('knip.json', 'tsconfig.json', 'package.json', 'package-lock.json') }}-${{ github.event.workflow_run.head_sha }}
+          CACHE_PORTABLE_PREFIX: rea-portable-build-v2-${{ runner.os }}-${{ runner.arch }}-
+          DEDUPE_NPM_DOWNLOADS: "true"
+        run: node scripts/ci/cache-retention.mjs

.github/workflows/ci.yml

@@ -146,6 +146,9 @@ jobs:
       - name: Cache npm package downloads
         id: npm-cache
         uses: ./.github/actions/npm-cache
+        with:
+          # Linux x64 writer. Parallel Linux jobs restore this key.
+          save: "true"
       - run: npm ci
       - name: Restore static task cache
         if: needs.changes.outputs.code == 'true'
@@ -658,6 +661,9 @@ jobs:
       - name: Cache npm package downloads
         id: npm-cache
         uses: ./.github/actions/npm-cache
+        with:
+          # ubuntu-latest is the Linux x64 writer above. Other hosts save their own key.
+          save: ${{ matrix.os != 'ubuntu-latest' }}
       - name: Verify native runtime identity
         env:
           EXPECTED_CI_PLATFORM: ${{ matrix.platform }}
@@ -794,6 +800,8 @@ jobs:
       - name: Cache npm package downloads
         id: npm-cache
         uses: ./.github/actions/npm-cache
+        with:
+          save: "true"
       - run: npm ci
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with: