@htekdev/actions-debugger 1.0.0 → 1.0.2

package/errors/runner-environment/disk-space.yml

@@ -1,57 +1,57 @@
-id: runner-environment-002
-title: "Runner Out of Disk Space"
-category: runner-environment
-severity: error
-tags:
-  - runner
-  - disk-space
-  - docker
-  - enospc
-  - ubuntu-latest
-patterns:
-  - regex: "No space left on device"
-    flags: "i"
-  - regex: "ENOSPC"
-    flags: "i"
-  - regex: "write .+ no space left on device"
-    flags: "i"
-error_messages:
-  - "No space left on device"
-  - "ENOSPC: no space left on device"
-root_cause: |
-  GitHub-hosted runners have finite disk space, and large Docker layers, Android SDKs,
-  toolchains, browser caches, or build artifacts can exhaust it mid-job. This frequently
-  shows up on `ubuntu-latest` when workflows build containers or multiple large targets.
-
-  The underlying job logic may be correct, but the runner image simply runs out of storage.
-fix: |
-  Free disk space early in the job, reduce artifact retention, and avoid downloading heavy
-  toolchains you do not need. If the workload is consistently too large, move the job to a
-  larger runner or split the build across jobs.
-fix_code:
-  - language: yaml
-    label: "Free disk space before heavy build steps"
-    code: |
-      jobs:
-        build:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - uses: jlumbroso/free-disk-space@v1
-              with:
-                large-packages: true
-                docker-images: true
-                tool-cache: false
-            - run: docker build -t app .
-prevention:
-  - "Measure disk usage before and after large build steps with `df -h`."
-  - "Delete temporary artifacts and caches you do not need inside the job."
-  - "Avoid monolithic jobs that build every target on one runner."
-docs:
-  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners"
-    label: "About GitHub-hosted runners"
-  - url: "https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job"
-    label: "Choosing the runner for a job"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Runner disk space exhaustion"
+id: runner-environment-002
+title: "Runner Out of Disk Space"
+category: runner-environment
+severity: error
+tags:
+  - runner
+  - disk-space
+  - docker
+  - enospc
+  - ubuntu-latest
+patterns:
+  - regex: "No space left on device"
+    flags: "i"
+  - regex: "ENOSPC"
+    flags: "i"
+  - regex: "write .+ no space left on device"
+    flags: "i"
+error_messages:
+  - "No space left on device"
+  - "ENOSPC: no space left on device"
+root_cause: |
+  GitHub-hosted runners have finite disk space, and large Docker layers, Android SDKs,
+  toolchains, browser caches, or build artifacts can exhaust it mid-job. This frequently
+  shows up on `ubuntu-latest` when workflows build containers or multiple large targets.
+
+  The underlying job logic may be correct, but the runner image simply runs out of storage.
+fix: |
+  Free disk space early in the job, reduce artifact retention, and avoid downloading heavy
+  toolchains you do not need. If the workload is consistently too large, move the job to a
+  larger runner or split the build across jobs.
+fix_code:
+  - language: yaml
+    label: "Free disk space before heavy build steps"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: jlumbroso/free-disk-space@v1
+              with:
+                large-packages: true
+                docker-images: true
+                tool-cache: false
+            - run: docker build -t app .
+prevention:
+  - "Measure disk usage before and after large build steps with `df -h`."
+  - "Delete temporary artifacts and caches you do not need inside the job."
+  - "Avoid monolithic jobs that build every target on one runner."
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners"
+  - url: "https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job"
+    label: "Choosing the runner for a job"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner disk space exhaustion"

package/errors/runner-environment/docker-buildx-not-setup.yml

@@ -0,0 +1,106 @@
+id: runner-environment-014
+title: "Docker BuildKit / buildx Not Enabled by Default — Legacy Build Flags Fail"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - buildx
+  - BuildKit
+  - multi-platform
+  - cache-from
+  - runner
+  - container
+patterns:
+  - regex: "buildx.*not found"
+    flags: "i"
+  - regex: "failed to solve.*no matching manifest"
+    flags: "i"
+  - regex: "DOCKER_BUILDKIT.*invalid"
+    flags: "i"
+  - regex: "multi-platform build is not supported"
+    flags: "i"
+  - regex: "unknown flag: --platform"
+    flags: "i"
+error_messages:
+  - "ERROR: multiple platforms feature is currently not supported for docker driver."
+  - "error: failed to solve: no matching manifest for linux/arm64 in the manifest list entries"
+  - "unknown flag: --platform"
+  - "docker: 'buildx' is not a docker command."
+root_cause: |
+  GitHub Actions runners ship with Docker installed, but the default `docker` driver
+  does not support multi-platform builds (`--platform linux/arm64,linux/amd64`) or
+  advanced BuildKit features like `--cache-from=type=gha`. These require the `docker-container`
+  driver via `docker buildx`.
+
+  On Ubuntu runners, `DOCKER_BUILDKIT=1` is available but `buildx` multi-platform support
+  requires a buildx builder instance to be set up explicitly. When workflows use
+  `docker/build-push-action@v5` or `docker buildx build` without first running
+  `docker/setup-buildx-action`, the build fails with driver capability errors.
+
+  Additionally, `cache-from: type=gha` (GitHub Actions cache) only works with the
+  BuildKit `docker-container` driver — it fails silently or errors on the default `docker`
+  driver.
+fix: |
+  Always call `docker/setup-buildx-action` before any `docker buildx` command or before
+  using `docker/build-push-action`. For multi-platform builds, pass the platform list
+  to the setup step.
+fix_code:
+  - language: yaml
+    label: "WRONG — multi-platform build without buildx setup"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Build multi-platform image
+          run: |
+            docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .
+            # ERROR: multiple platforms feature is currently not supported for docker driver
+  - language: yaml
+    label: "CORRECT — setup buildx before multi-platform build"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - name: Set up Docker Buildx
+          uses: docker/setup-buildx-action@v3   # creates docker-container driver
+
+        - name: Login to registry
+          uses: docker/login-action@v3
+          with:
+            registry: ghcr.io
+            username: ${{ github.actor }}
+            password: ${{ secrets.GITHUB_TOKEN }}
+
+        - name: Build and push
+          uses: docker/build-push-action@v6
+          with:
+            context: .
+            platforms: linux/amd64,linux/arm64
+            push: true
+            tags: ghcr.io/${{ github.repository }}:latest
+            cache-from: type=gha
+            cache-to: type=gha,mode=max
+  - language: yaml
+    label: "CORRECT — single platform with GHA cache (still needs buildx)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: docker/setup-buildx-action@v3
+        - uses: docker/build-push-action@v6
+          with:
+            context: .
+            push: false
+            load: true
+            tags: myapp:test
+            cache-from: type=gha
+            cache-to: type=gha,mode=max
+prevention:
+  - "Always add `docker/setup-buildx-action@v3` as a step before any `docker buildx` or `docker/build-push-action` usage."
+  - "Use `docker/build-push-action` instead of raw `docker build` for all CI image builds — it handles BuildKit setup and caching correctly."
+  - "For ARM64/multi-arch builds, expect 3-5x longer build times on x86 runners due to QEMU emulation."
+docs:
+  - url: "https://docs.docker.com/build/ci/github-actions/"
+    label: "Docker Build in GitHub Actions (Docker docs)"
+  - url: "https://github.com/docker/setup-buildx-action"
+    label: "docker/setup-buildx-action"
+  - url: "https://github.com/docker/build-push-action"
+    label: "docker/build-push-action"

package/errors/runner-environment/macos-homebrew-path.yml

@@ -0,0 +1,90 @@
+id: runner-environment-011
+title: "macOS Runner Homebrew Binaries Not on PATH After brew install"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - homebrew
+  - PATH
+  - runner
+  - shell
+  - binary
+patterns:
+  - regex: "command not found.*brew"
+    flags: "i"
+  - regex: "brew: command not found"
+    flags: "i"
+  - regex: "/opt/homebrew/bin.*not found"
+    flags: "i"
+  - regex: "zsh: command not found"
+    flags: "i"
+error_messages:
+  - "zsh: command not found: <tool>"
+  - "Error: Process completed with exit code 127."
+  - "/usr/bin/env: '<tool>': No such file or directory"
+root_cause: |
+  GitHub Actions macOS runners (including `macos-14` and `macos-15` on Apple Silicon)
+  use zsh as the default shell. Homebrew installs binaries to `/opt/homebrew/bin` on
+  Apple Silicon (`macos-14`+) and `/usr/local/bin` on Intel (`macos-13`), but these
+  paths are not always added to `$PATH` for subsequent steps automatically.
+
+  When a step runs `brew install sometool` and then a **later step** attempts to use
+  `sometool`, the binary may not be on `$PATH` because Homebrew's shellenv was never
+  sourced into the Actions runner's shell environment.
+
+  Additionally, `macos-14` moved to Apple Silicon, changing the Homebrew prefix from
+  `/usr/local` to `/opt/homebrew`, which breaks hardcoded path assumptions in scripts
+  that worked on `macos-13`.
+fix: |
+  After installing with Homebrew, explicitly add the binary path to `$GITHUB_PATH`
+  (which persists across subsequent steps in the same job). Alternatively, use
+  `brew --prefix` to get the correct path regardless of architecture.
+fix_code:
+  - language: yaml
+    label: "WRONG — tool installed but not accessible in next step"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install tool
+              run: brew install sometool
+
+            - name: Use tool
+              run: sometool --version   # Error: zsh: command not found: sometool
+  - language: yaml
+    label: "CORRECT — add brew prefix to GITHUB_PATH"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install tool
+              run: |
+                brew install sometool
+                # Add homebrew bin to path for all subsequent steps
+                echo "$(brew --prefix)/bin" >> $GITHUB_PATH
+
+            - name: Use tool
+              run: sometool --version   # works
+  - language: yaml
+    label: "CORRECT — source shellenv in a single step"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install and run in same step
+              run: |
+                brew install sometool
+                eval "$(brew shellenv)"
+                sometool --version
+prevention:
+  - "After `brew install`, append `$(brew --prefix)/bin` to `$GITHUB_PATH` to persist it across steps."
+  - "Use `brew --prefix <formula>` to get formula-specific paths rather than hardcoding `/usr/local` or `/opt/homebrew`."
+  - "When upgrading from `macos-13` to `macos-14`+, audit any hardcoded `/usr/local` paths for the Homebrew prefix change."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-system-path"
+    label: "Adding a system path (GITHUB_PATH)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub-hosted runners — supported environments"

package/errors/runner-environment/node-runtime-deprecation.yml

@@ -1,56 +1,56 @@
-id: runner-environment-009
-title: "Node.js Runtime Deprecation"
-category: runner-environment
-severity: warning
-tags:
-  - node
-  - runtime
-  - deprecation
-  - marketplace-actions
-  - compatibility
-patterns:
-  - regex: "Node\\.js 16 actions are deprecated"
-    flags: "i"
-  - regex: "Please update the following actions to use Node\\.js 20"
-    flags: "i"
-  - regex: "runs using Node 16 are deprecated"
-    flags: "i"
-error_messages:
-  - "Node.js 16 actions are deprecated."
-  - "Please update the following actions to use Node.js 20."
-root_cause: |
-  Some marketplace actions bundle a Node.js runtime. When GitHub deprecates an older
-  runtime such as Node 16, workflows can start emitting warnings or eventually fail if the
-  referenced action version has not been updated.
-
-  This is usually caused by pinning an old major version of an action long after the runner
-  platform has moved on.
-fix: |
-  Upgrade the affected action to a maintained version that uses the current supported Node
-  runtime. Review pinned SHAs and major versions for checkout, setup, artifact, and cache
-  actions first because they are common sources of these warnings.
-fix_code:
-  - language: yaml
-    label: "Upgrade action versions to Node 20-compatible releases"
-    code: |
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/setup-node@v4
-          with:
-            node-version: 20
-        - uses: actions/upload-artifact@v4
-          with:
-            name: build-output
-            path: dist/
-prevention:
-  - "Review GitHub Actions deprecation notices and keep marketplace action versions current."
-  - "Prefer supported major versions from official `actions/*` repositories."
-  - "Audit pinned SHAs periodically so old runtimes do not linger unnoticed."
-docs:
-  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
-    label: "JavaScript action runtime metadata"
-  - url: "https://docs.github.com/en/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions"
-    label: "Metadata syntax for GitHub Actions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Node runtime deprecation warnings"
+id: runner-environment-009
+title: "Node.js Runtime Deprecation"
+category: runner-environment
+severity: warning
+tags:
+  - node
+  - runtime
+  - deprecation
+  - marketplace-actions
+  - compatibility
+patterns:
+  - regex: "Node\\.js 16 actions are deprecated"
+    flags: "i"
+  - regex: "Please update the following actions to use Node\\.js 20"
+    flags: "i"
+  - regex: "runs using Node 16 are deprecated"
+    flags: "i"
+error_messages:
+  - "Node.js 16 actions are deprecated."
+  - "Please update the following actions to use Node.js 20."
+root_cause: |
+  Some marketplace actions bundle a Node.js runtime. When GitHub deprecates an older
+  runtime such as Node 16, workflows can start emitting warnings or eventually fail if the
+  referenced action version has not been updated.
+
+  This is usually caused by pinning an old major version of an action long after the runner
+  platform has moved on.
+fix: |
+  Upgrade the affected action to a maintained version that uses the current supported Node
+  runtime. Review pinned SHAs and major versions for checkout, setup, artifact, and cache
+  actions first because they are common sources of these warnings.
+fix_code:
+  - language: yaml
+    label: "Upgrade action versions to Node 20-compatible releases"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: 20
+        - uses: actions/upload-artifact@v4
+          with:
+            name: build-output
+            path: dist/
+prevention:
+  - "Review GitHub Actions deprecation notices and keep marketplace action versions current."
+  - "Prefer supported major versions from official `actions/*` repositories."
+  - "Audit pinned SHAs periodically so old runtimes do not linger unnoticed."
+docs:
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
+    label: "JavaScript action runtime metadata"
+  - url: "https://docs.github.com/en/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions"
+    label: "Metadata syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Node runtime deprecation warnings"

package/errors/runner-environment/node20-to-node24-migration.yml

@@ -0,0 +1,118 @@
+id: runner-environment-016
+title: "Node 20 → Node 24 Forced Migration Breaks Actions and macOS 13 Runners"
+category: runner-environment
+severity: error
+tags:
+  - node
+  - node24
+  - deprecation
+  - macos
+  - arm32
+  - runtime-migration
+patterns:
+  - regex: "Node\\.?20 actions are deprecated"
+    flags: "i"
+  - regex: "Please update the following actions to use Node\\.?24"
+    flags: "i"
+  - regex: "node20 is deprecated"
+    flags: "i"
+  - regex: "macOS 13.*not supported.*Node 24"
+    flags: "i"
+  - regex: "ARM32.*no longer supported"
+    flags: "i"
+error_messages:
+  - "Node.js 20 actions are deprecated. Please update the following actions to use Node.js 24."
+  - "node20 is deprecated and will be disabled in a future runner release."
+  - "Error: This action requires Node.js 24 or higher. Current version: 20."
+root_cause: |
+  GitHub announced deprecation of Node 20 on Actions runners on September 19, 2025
+  (editor updated May 19, 2026: migration date confirmed June 16, 2026). Starting
+  June 16, 2026, all GitHub-hosted runners default to Node 24.
+
+  Three distinct breakage scenarios exist:
+
+  1. **Marketplace actions using `runs.using: 'node20'`** — any third-party or custom
+     action that declares `runs.using: node20` in its `action.yml` will emit deprecation
+     warnings and eventually fail when GitHub removes Node 20 from runners later in 2026.
+
+  2. **macOS 13 (and older) runners are incompatible with Node 24** — Node 24 dropped
+     support for macOS 13.4 and lower. Workflows specifying `runs-on: macos-13` (or older
+     images) fail at the runner startup phase or produce unexpected errors from the
+     Node-based runner bootstrapper.
+
+  3. **ARM32 self-hosted runners** — Node 24 has no official ARM32 support. Self-hosted
+     runners on ARM32 hardware silently lose the ability to execute Node-based actions
+     after the Node 20 removal milestone.
+fix: |
+  **For action authors:** Update `action.yml` to declare `runs.using: 'node24'` and
+  test locally with Node 24. Publish a new release so downstream consumers pick it up.
+
+  **For workflow authors:**
+  - Upgrade all `uses:` pins to the latest major version that ships with Node 24 support
+    (e.g. `actions/checkout@v4 → @v4` already Node-24-ready; `actions/setup-node@v4`
+    already Node-24-ready).
+  - Replace `runs-on: macos-13` with `runs-on: macos-latest` or `macos-14+`.
+  - For ARM32 self-hosted runners: migrate to ARM64 hardware or use container-based
+    execution that bundles its own Node runtime.
+
+  **Temporary escape hatch (not for production long-term):**
+  Set `ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION=true` in the workflow `env` block to
+  continue using Node 20 until GitHub removes it from runners later in 2026.
+fix_code:
+  - language: yaml
+    label: "Upgrade pinned action versions to Node 24-compatible releases"
+    code: |
+      steps:
+        # Pin to latest major — all official actions already ship Node 24 builds
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+        - uses: actions/upload-artifact@v4
+          with:
+            name: dist
+            path: dist/
+  - language: yaml
+    label: "Migrate macOS runner from macos-13 to macos-latest"
+    code: |
+      jobs:
+        build:
+          # macos-13 is incompatible with Node 24 — use macos-latest (14+)
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Temporary escape hatch — keep Node 20 until explicit removal"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            # WARNING: temporary only — Node 20 will be fully removed later in 2026
+            ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: 'true'
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Test Node 24 compatibility before the mandatory cutover"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            # Force Node 24 to test compatibility ahead of the June 16 cutover
+            FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+          steps:
+            - uses: actions/checkout@v4
+prevention:
+  - "Subscribe to GitHub changelog https://github.blog/changelog/label/actions/ for deprecation notices."
+  - "Run `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true` in CI to catch Node 24 incompatibilities early."
+  - "Avoid pinning to old major versions of `actions/*` — use floating major tags (e.g. @v4)."
+  - "Audit custom/internal actions for `runs.using: node20` declarations before the June 16, 2026 migration date."
+  - "Migrate macOS CI to macos-14 or macos-latest to ensure Node 24 compatibility."
+docs:
+  - url: "https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/"
+    label: "GitHub Changelog: Deprecation of Node 20 on GitHub Actions runners"
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
+    label: "Metadata syntax: runs.using for JavaScript actions"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "Supported runners and hardware resources"

package/errors/runner-environment/npm-ci-lockfile-mismatch.yml

@@ -0,0 +1,112 @@
+id: runner-environment-015
+title: "npm ci Fails with Lockfile Mismatch or Missing package-lock.json"
+category: runner-environment
+severity: error
+tags:
+  - npm
+  - npm-ci
+  - lockfile
+  - package-lock.json
+  - dependencies
+  - node
+  - reproducible
+patterns:
+  - regex: "npm ci.*can only install.*package-lock\\.json"
+    flags: "i"
+  - regex: "Missing script.*ci"
+    flags: "i"
+  - regex: "npm ERR! code EUSAGE"
+    flags: "i"
+  - regex: "npm warn saveError ENOENT.*package-lock\\.json"
+    flags: "i"
+  - regex: "npm ERR!.*lock file.*older npm"
+    flags: "i"
+  - regex: "EBADENGINE"
+    flags: "i"
+error_messages:
+  - "npm error The `npm ci` command can only install with an existing package-lock.json"
+  - "npm warn saveError ENOENT: no such file or directory, open '/home/runner/work/.../package-lock.json'"
+  - "npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync."
+  - "npm error Missing: <package>@<version> from lock file"
+root_cause: |
+  `npm ci` is strict by design — it requires `package-lock.json` to be present and
+  exactly in sync with `package.json`. It fails in several common CI scenarios:
+
+  1. **No lockfile committed** — developers add `package-lock.json` to `.gitignore`
+     (common in library repos) — `npm ci` refuses to run.
+
+  2. **Lockfile out of sync** — a developer ran `npm install` locally which updated
+     the lockfile, but committed `package.json` without the updated lockfile, or vice versa.
+     `npm ci` reports "Missing: package@version from lock file."
+
+  3. **Lockfile from incompatible npm version** — npm v6 lockfiles (lockfileVersion 1)
+     cannot be used with `npm ci` in npm v7+ projects that use workspaces, and vice versa.
+
+  4. **Monorepo workspace packages not locked** — `package-lock.json` at root does not
+     lock workspace packages listed in `packages/*` if each sub-package has its own
+     `package.json` without being part of the root workspaces config.
+fix: |
+  Commit `package-lock.json` to the repository (do not gitignore it in apps). Keep
+  `package.json` and `package-lock.json` in sync by running `npm install` locally
+  after any manifest change and committing both files together.
+fix_code:
+  - language: yaml
+    label: "CORRECT — npm ci with Node version matrix and lockfile caching"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              node-version: ['18.x', '20.x']
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node-version }}
+                cache: npm                 # caches ~/.npm using package-lock.json hash
+
+            - name: Install dependencies
+              run: npm ci                  # fails fast if lockfile is out of sync
+
+            - name: Run tests
+              run: npm test
+  - language: yaml
+    label: "Detect lockfile sync issues before CI"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: 20
+
+        - name: Verify lockfile is up to date
+          run: |
+            npm install --package-lock-only
+            git diff --exit-code package-lock.json || {
+              echo "::error::package-lock.json is out of sync with package.json"
+              echo "Run 'npm install' locally and commit the updated lockfile"
+              exit 1
+            }
+
+        - run: npm ci
+  - language: bash
+    label: "Fix gitignore — ensure lockfile is tracked"
+    code: |
+      # If package-lock.json is gitignored, remove it from .gitignore
+      grep -v "package-lock.json" .gitignore > .gitignore.tmp && mv .gitignore.tmp .gitignore
+      git add package-lock.json
+      git commit -m "chore: track package-lock.json for reproducible CI"
+prevention:
+  - "Always commit `package-lock.json` to git — never gitignore it in application repos."
+  - "Run `npm install` (not just `npm ci`) locally after any `package.json` change and commit both files atomically."
+  - "Add a `Verify lockfile` step to CI that runs `npm install --package-lock-only && git diff --exit-code package-lock.json` to catch drift early."
+  - "Renovate Bot and Dependabot automatically keep lockfiles in sync when configured correctly."
+docs:
+  - url: "https://docs.npmjs.com/cli/v10/commands/npm-ci"
+    label: "npm ci (npmjs docs)"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#caching-npm-packages"
+    label: "Caching npm packages"
+  - url: "https://github.com/actions/setup-node#caching-global-packages-data"
+    label: "actions/setup-node — npm caching"