@htekdev/actions-debugger 1.0.40 → 1.0.41

package/errors/caching-artifacts/setup-node-npm-cache-monorepo-lockfile-not-found.yml

@@ -0,0 +1,118 @@
+id: caching-artifacts-032
+title: 'setup-node cache: npm silently skips caching in monorepos — lockfile not at workspace root'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - setup-node
+  - npm
+  - cache
+  - monorepo
+  - lockfile
+  - cache-dependency-path
+  - silent-failure
+patterns:
+  - regex: "Warning: No file found for: package-lock\\.json"
+    flags: 'i'
+  - regex: 'No file found for.*No cache will be (saved|restored)'
+    flags: 'i'
+  - regex: 'cache-dependency-path.*not found|No lockfile found'
+    flags: 'i'
+error_messages:
+  - "Warning: No file found for: package-lock.json"
+  - "Warning: No file found for: yarn.lock"
+  - "Warning: No file found for: pnpm-lock.yaml"
+  - "No file found for: package-lock.json. No cache will be saved."
+root_cause: |
+  actions/setup-node with cache: 'npm' (or 'yarn' / 'pnpm') searches for the
+  package manager lockfile at the workspace root ($GITHUB_WORKSPACE) by default.
+
+  In monorepos where the lockfile lives in a subdirectory (apps/frontend/,
+  packages/api/, etc.), or when the workflow uses working-directory: to change
+  the build context, setup-node logs a warning and continues WITHOUT configuring
+  a cache. The step exits 0, making this a silent failure.
+
+  The result: npm ci (or yarn install / pnpm install) downloads all dependencies
+  from the network on every workflow run, as though no cache were configured.
+  Build times are identical to runs with no cache setting at all.
+
+  The warning message ("No file found for: package-lock.json") is easily missed
+  in long step logs and does not fail the step, so developers often go weeks
+  without noticing the cache was never active.
+
+  The same behavior applies when:
+  - yarn.lock is not at workspace root
+  - pnpm-lock.yaml is not at workspace root
+  - Multiple lockfiles exist across packages (only the first match is used
+    unless cache-dependency-path is explicitly set to a glob)
+fix: |
+  Use the cache-dependency-path input to specify the path to the lockfile
+  relative to the workspace root. Supports glob patterns for monorepos.
+
+  Single package in subdirectory:
+    cache-dependency-path: 'frontend/package-lock.json'
+
+  Multiple lockfiles across a monorepo:
+    cache-dependency-path: '**/package-lock.json'
+
+  Using a glob creates a combined cache key from all matched lockfiles. Any
+  change to any package lockfile invalidates the shared cache — this is
+  correct behavior for a monorepo where cross-package installs are common.
+fix_code:
+  - language: yaml
+    label: 'Single package in subdirectory — point cache-dependency-path at lockfile'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'
+                cache: 'npm'
+                # WRONG (omitted): setup-node looks at $GITHUB_WORKSPACE/package-lock.json
+                # and silently skips caching when not found there
+
+                # CORRECT: path relative to $GITHUB_WORKSPACE
+                cache-dependency-path: 'frontend/package-lock.json'
+
+            - name: Install dependencies
+              working-directory: frontend
+              run: npm ci
+  - language: yaml
+    label: 'Monorepo — cache all packages using glob pattern'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '22'
+                cache: 'npm'
+                # Glob matches all package-lock.json files anywhere in the repo
+                # Combined hash from all matched lockfiles forms the cache key
+                cache-dependency-path: '**/package-lock.json'
+
+            - name: Install root dependencies
+              run: npm ci
+
+            - name: Install frontend dependencies
+              working-directory: packages/frontend
+              run: npm ci
+prevention:
+  - 'Always set cache-dependency-path when the lockfile is not in the repository root'
+  - 'Use **/package-lock.json glob in monorepos to cover all packages with a single cache configuration'
+  - 'Verify caching is active by checking setup-node logs for "Cache restored successfully" or "Cache saved"'
+  - 'Check for "No file found for: package-lock.json" warnings as early signal that caching is silently disabled'
+  - 'When using working-directory: on install steps, ensure cache-dependency-path is also adjusted to match'
+docs:
+  - url: 'https://github.com/actions/setup-node#caching-global-packages-data'
+    label: 'actions/setup-node: Caching global packages data — cache-dependency-path input'
+  - url: 'https://github.com/actions/setup-node/issues/530'
+    label: 'actions/setup-node#530: cache: npm silently skips in monorepos without cache-dependency-path'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows'
+    label: 'GitHub Docs: Caching dependencies to speed up workflows — lockfile path configuration'

package/errors/concurrency-timing/cancel-in-progress-queued-run-status-never-posts.yml

@@ -0,0 +1,111 @@
+id: concurrency-timing-027
+title: 'Queued run cancelled by cancel-in-progress before any job starts — required status check never posts, PR permanently blocked'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - required-status-check
+  - branch-protection
+  - pr-blocked
+  - status-check
+patterns:
+  - regex: 'This run was cancelled because another run in the same concurrency group'
+    flags: 'i'
+  - regex: 'Waiting for.*status.*reported|Expected.*Waiting'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled because another run in the same concurrency group is in progress."
+  - "Waiting for status to be reported"
+root_cause: |
+  When cancel-in-progress: true cancels a workflow run that was queued but had
+  not yet started any job, GitHub does NOT post a status (pending, cancelled, or
+  failure) to the commit SHA. The run silently disappears from the run list.
+
+  Branch protection rules that require a specific status check (e.g., "CI / test")
+  only observe statuses that were posted. A run cancelled before its first job
+  starts never posts any status — not even "pending".
+
+  Impact on PRs with high push frequency:
+  1. Developer opens PR, pushes commit A — run starts, posts "pending"
+  2. Developer pushes fix commit B — run for A is cancelled, run for B is queued
+  3. Developer pushes commit C before B's run starts — B's run cancelled (never
+     started), run for C queued
+  4. Run for C finally starts and posts statuses
+  5. But if C is also cancelled before starting, the commit has NO status
+  6. Branch protection shows the required check as "Expected" forever
+  7. PR cannot be merged — the Merge button stays disabled indefinitely
+
+  This condition is self-healing if a new commit is pushed (starting a fresh
+  run that won't be cancelled), but in rapid-push scenarios the window persists
+  for many minutes and developers mistakenly believe the CI is broken.
+fix: |
+  Option 1 — Queue instead of cancel (safest):
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.ref }}"
+      cancel-in-progress: false
+
+  Runs queue behind one another; every commit eventually gets a status posted.
+
+  Option 2 — Status anchor job:
+  Add a minimal first job that completes instantly. Its "queued" + "in_progress"
+  status is posted to the commit SHA immediately, ensuring GitHub registers the
+  run before any cancellation can remove the status.
+
+  Option 3 — GitHub Actions recommended pattern:
+  Use cancel-in-progress: true for the expensive test jobs only, and have a
+  separate fast-posting job that always runs (not subject to concurrency group).
+fix_code:
+  - language: yaml
+    label: 'Queue runs instead of cancelling — every commit gets a status'
+    code: |
+      on:
+        pull_request:
+
+      concurrency:
+        # Queue instead of cancel — latest run waits, but always posts status
+        group: '${{ github.workflow }}-${{ github.ref }}'
+        cancel-in-progress: false
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: 'Status anchor job — posts status immediately before cancel window'
+    code: |
+      on:
+        pull_request:
+
+      concurrency:
+        group: '${{ github.workflow }}-${{ github.ref }}'
+        cancel-in-progress: true    # OK — anchor ensures status is posted first
+
+      jobs:
+        # Minimal job: completes in seconds, ensuring a status is recorded on the SHA
+        anchor:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "CI registered for ${{ github.sha }}"
+
+        # Expensive test job that is safe to cancel
+        test:
+          needs: anchor
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - 'Avoid cancel-in-progress: true on workflows whose jobs are required status checks for branch protection'
+  - 'Use cancel-in-progress: false with queuing semantics when PR mergeability must be preserved on every commit'
+  - 'Add a lightweight anchor job as the first required job to ensure a status posts before any cancel window closes'
+  - 'Monitor PRs stuck with Expected required checks — check whether recent commits had all their runs cancelled before starting'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency'
+    label: 'GitHub Actions: Using concurrency — cancel-in-progress behavior'
+  - url: 'https://github.com/orgs/community/discussions/21280'
+    label: 'GitHub Community: Required status check never posts when run cancelled before start (120+ reactions)'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging'
+    label: 'GitHub Docs: Required status checks — how commit statuses are evaluated for branch protection'

package/errors/concurrency-timing/step-timeout-not-supported-job-holds-runner.yml

@@ -0,0 +1,101 @@
+id: concurrency-timing-025
+title: 'No step-level timeout — a hung step holds the runner slot for up to 6 hours'
+category: concurrency-timing
+severity: limitation
+tags:
+  - timeout
+  - hung-step
+  - runner-slot
+  - step
+  - limitation
+  - self-hosted-runner
+patterns:
+  - regex: 'The runner has received a shutdown signal'
+    flags: 'i'
+  - regex: 'Error: The process.*timed out after \d+ minutes'
+    flags: 'i'
+  - regex: 'Canceling since the workflow was cancelled'
+    flags: 'i'
+error_messages:
+  - "The runner has received a shutdown signal. This can happen when the runner service is stopped, or a manually started runner is canceled."
+  - "Error: The process '/usr/bin/bash' failed with exit code 124"
+  - "Canceling since the workflow was cancelled."
+root_cause: |
+  GitHub Actions supports timeout-minutes at the job level only. There is no
+  per-step timeout. A single run: step that hangs (network call blocked, test
+  suite deadlocked, subprocess waiting on stdin) holds the entire job until
+  the job-level timeout fires.
+
+  The default job timeout is 6 hours (360 minutes) for GitHub-hosted runners
+  and 35 days (unlimited in practice) for self-hosted runners. A single hung
+  step therefore silently consumes 6 hours of runner minutes and one complete
+  runner slot before GitHub kills the job.
+
+  Runner slot starvation is the secondary effect: while the hung job occupies a
+  runner, queued jobs wait. On self-hosted runners with limited capacity one
+  hung step can block an entire team's CI queue indefinitely.
+
+  This is a documented platform limitation tracked in actions/runner#1120
+  (220+ reactions, open since 2020) with no scheduled fix date.
+fix: |
+  Apply one of these workarounds depending on operating system:
+
+  Linux/macOS: Wrap the command with the system timeout utility (seconds):
+    run: timeout 300 ./integration-test.sh
+
+  Cross-platform: Use curl/Invoke-RestMethod built-in timeout options for
+  network calls, and test-runner native timeouts for test suites.
+
+  Always set timeout-minutes explicitly on every job to establish a hard upper
+  bound regardless of which step hangs.
+fix_code:
+  - language: yaml
+    label: 'Set explicit job timeout and use OS timeout for individual steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30    # explicit ceiling — never rely on 6h default
+
+          steps:
+            - uses: actions/checkout@v4
+
+            # Linux/macOS: system timeout (in seconds)
+            - name: Run integration tests
+              run: timeout 180 ./scripts/integration-test.sh
+
+            # Network call with built-in timeout
+            - name: Fetch external resource
+              run: |
+                curl --max-time 60 --retry 3 https://api.example.com/data -o data.json
+  - language: yaml
+    label: 'Self-hosted runner — conservative timeout prevents slot starvation'
+    code: |
+      jobs:
+        deploy:
+          runs-on: [self-hosted, production]
+          timeout-minutes: 45    # critical on self-hosted — hung jobs block all runners
+
+          steps:
+            - name: Deploy with timeout guard
+              shell: pwsh
+              run: |
+                $job = Start-Job { ./deploy.ps1 }
+                if (-not (Wait-Job $job -Timeout 120)) {
+                  Stop-Job $job
+                  throw "Deploy script timed out after 120s"
+                }
+                Receive-Job $job
+prevention:
+  - 'Always set explicit timeout-minutes on every job — never rely on the 6-hour GitHub-hosted default'
+  - 'Use OS-level timeout utilities (timeout on Linux/macOS) for individual network calls and scripts'
+  - 'Configure test-runner-native timeouts for test suites — they are more granular than job timeouts'
+  - 'Monitor runner queue depth on self-hosted runners — sudden growth often signals a hung step holding a slot'
+  - 'Set timeout-minutes: 5 on jobs you know should complete quickly to catch regressions early'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Actions: jobs.<id>.timeout-minutes — job-level timeout (no step-level equivalent)'
+  - url: 'https://github.com/actions/runner/issues/1120'
+    label: 'actions/runner#1120: Feature request — step-level timeout (220+ reactions, open since 2020)'
+  - url: 'https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits'
+    label: 'GitHub Actions usage limits — default job timeout values per runner type'

package/errors/concurrency-timing/workflow-dispatch-push-shared-concurrency-silent-cancel.yml

@@ -0,0 +1,104 @@
+id: concurrency-timing-026
+title: 'workflow_dispatch run silently cancelled when push to same branch shares the concurrency group'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow-dispatch
+  - cancel-in-progress
+  - push
+  - manual-trigger
+  - silent-cancel
+patterns:
+  - regex: 'This run was cancelled because another run in the same concurrency group'
+    flags: 'i'
+  - regex: 'Canceling run due to.*concurrency group'
+    flags: 'i'
+  - regex: 'This run has been canceled'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled because another run in the same concurrency group is in progress."
+  - "Canceling run due to a newer request for the same concurrency group."
+  - "This run has been canceled."
+root_cause: |
+  A common concurrency pattern groups runs by workflow name and ref:
+
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.ref }}"
+      cancel-in-progress: true
+
+  workflow_dispatch and push events on the same branch share identical
+  github.workflow and github.ref values, so they are placed in the same
+  concurrency slot.
+
+  A developer manually triggers a workflow_dispatch run (e.g., to deploy to
+  staging, run a migration, or kick off a release). While it is running, any
+  push to that branch — including a small documentation fix or revert — creates
+  a new run in the same concurrency slot and immediately cancels the in-progress
+  manual dispatch with no notification.
+
+  The developer discovers this only when checking on the deployment minutes
+  later to find it was cancelled mid-run. The automatic push run that replaced
+  it may be completely irrelevant to the manual operation.
+fix: |
+  Include github.event_name in the concurrency group key to give workflow_dispatch
+  and push events separate concurrency slots:
+
+    concurrency:
+      group: "${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}"
+      cancel-in-progress: true
+
+  workflow_dispatch runs now share a slot only with other workflow_dispatch runs
+  on the same branch, and push runs share a slot only with other push runs.
+
+  For deployment or migration workflows where even manual-vs-manual cancellation
+  is undesirable, use cancel-in-progress: false and let runs queue.
+fix_code:
+  - language: yaml
+    label: 'Include event_name in concurrency group — isolates manual from automatic triggers'
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:
+
+      concurrency:
+        # event_name isolates push and workflow_dispatch into separate concurrency slots
+        group: '${{ github.workflow }}-${{ github.event_name }}-${{ github.ref_name }}'
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Separate workflow file for manual operations — no cancel-in-progress'
+    code: |
+      # deploy-manual.yml — only triggered by workflow_dispatch
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: 'Target environment'
+              required: true
+              type: choice
+              options: [staging, production]
+
+      # No shared concurrency group with push workflows
+      concurrency:
+        group: 'manual-deploy-${{ github.event.inputs.environment }}'
+        # cancel-in-progress defaults to false — manual deploys queue, not cancel
+prevention:
+  - 'Always include github.event_name in concurrency group keys for workflows triggered by both push and workflow_dispatch'
+  - 'Use separate workflow files for manual deployment operations to avoid shared concurrency with automated triggers'
+  - 'Add a summary step or Telegram/Slack notification in the cleanup phase to alert when a run is cancelled mid-execution'
+  - 'Audit all concurrency group patterns when adding workflow_dispatch to an existing automated workflow'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency'
+    label: 'GitHub Actions: Using concurrency — group patterns and cancel-in-progress'
+  - url: 'https://github.com/orgs/community/discussions/5435'
+    label: 'GitHub Community: workflow_dispatch cancelled by push with same concurrency group'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context'
+    label: 'GitHub context: github.event_name property'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.40",
+  "version": "1.0.41",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",