@htekdev/actions-debugger 1.0.111 → 1.0.113

package/errors/runner-environment/sparse-checkout-cone-mode-not-honored-git-pre-237.yml

@@ -0,0 +1,121 @@
+id: 'runner-environment-182'
+title: 'actions/checkout sparse-checkout-cone-mode: true not honored when container git < 2.37'
+category: 'runner-environment'
+severity: 'error'
+tags:
+  - sparse-checkout
+  - cone-mode
+  - git-version
+  - container
+  - checkout
+  - self-hosted
+patterns:
+  - regex: 'sparse-checkout-cone-mode.*true.*container'
+    flags: 'i'
+  - regex: 'git.*2\.[12][0-9]\.'
+    flags: 'i'
+  - regex: 'core\.sparseCheckoutConeMode.*not set'
+    flags: 'i'
+error_messages:
+  - "Expected full checkout but only subdirectory present"
+  - "Sibling files missing from sparse checkout cone"
+  - "core.sparseCheckoutConeMode"
+root_cause: |
+  `actions/checkout` enables sparse-checkout cone mode by setting
+  `core.sparseCheckoutConeMode = true` in the git config. However, the
+  `git sparse-checkout set` command requires the explicit `--cone` flag to
+  activate cone mode in Git versions **before 2.37.0**.
+
+  Starting with Git 2.37.0, cone mode became the default for `git sparse-checkout`.
+  In earlier Git versions, cone mode must be opted into with `--cone`. The
+  `actions/checkout` action does NOT pass `--cone` explicitly, so when running
+  inside a container image with Git < 2.37 (e.g., `ubuntu:22.04` ships with
+  Git 2.34.1), setting `sparse-checkout-cone-mode: true` has no effect.
+
+  The result is that cone mode is silently ignored. The checkout runs in non-cone
+  (gitignore pattern) mode instead, which means:
+  - Root-level sibling files that should be included in cone mode are absent
+  - Only the exact subdirectory specified is checked out, without the expected
+    parent-level files
+  - Subsequent steps that depend on root-level files (e.g., package.json, .env,
+    Makefile) fail with "file not found" errors that appear unrelated to checkout
+
+  Reported in actions/checkout#1868 (Aug 2024).
+fix: |
+  Option 1 (recommended): Upgrade Git in the container to 2.37.0 or later.
+  For containers based on Ubuntu 22.04, install a newer Git via PPA:
+    add-apt-repository ppa:git-core/ppa && apt-get install git
+
+  Option 2: Add an explicit `git sparse-checkout init --cone` step AFTER checkout
+  to force cone mode activation retroactively. This is a workaround for containers
+  where upgrading Git is not possible.
+
+  Option 3: Use GitHub-hosted runners (ubuntu-latest, ubuntu-24.04) which ship
+  with Git >= 2.43, where cone mode works correctly by default.
+
+  Option 4: If specific file patterns are required (not just directories), use
+  `sparse-checkout-cone-mode: false` with root-anchored `/pattern` patterns
+  instead of relying on cone mode.
+fix_code:
+  - language: yaml
+    label: 'Upgrade git in container before checkout (Ubuntu 22.04 example)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: ubuntu:22.04
+          steps:
+            - name: Upgrade git to 2.37+ for sparse-checkout cone mode support
+              run: |
+                apt-get update -qq
+                apt-get install -y software-properties-common
+                add-apt-repository -y ppa:git-core/ppa
+                apt-get update -qq
+                apt-get install -y git
+                git --version  # Verify >= 2.37
+
+            - uses: actions/checkout@v4
+              with:
+                sparse-checkout: |
+                  src
+                  config
+                sparse-checkout-cone-mode: true   # Now honored after Git 2.37+ installed
+  - language: yaml
+    label: 'Workaround: force --cone after checkout on old Git'
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: src
+          sparse-checkout-cone-mode: true
+
+      # Explicitly enable cone mode on Git < 2.37 (workaround for actions/checkout#1868)
+      - name: Force cone mode on old git
+        run: |
+          git sparse-checkout init --cone
+          git sparse-checkout set src
+  - language: yaml
+    label: 'Use GitHub-hosted runner to avoid old git versions'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest  # Ships with Git 2.43+ — cone mode works correctly
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                sparse-checkout: |
+                  src
+                  config
+                # sparse-checkout-cone-mode: true  # Default, works on ubuntu-latest
+prevention:
+  - "Check the git version in container images before relying on sparse-checkout cone mode: run 'git --version' in a workflow step."
+  - "Upgrade container base images to Ubuntu 24.04 or Debian 12 which ship with Git >= 2.39."
+  - "Pin to GitHub-hosted runners (ubuntu-latest, ubuntu-24.04) for consistent Git versions that support cone mode."
+  - "After setting up sparse checkout, add a debug step printing 'git config core.sparseCheckoutConeMode' to verify cone mode is active."
+docs:
+  - url: 'https://github.com/actions/checkout/issues/1868'
+    label: 'actions/checkout#1868 — sparse-checkout-cone-mode not honored on git < 2.37'
+  - url: 'https://git-scm.com/docs/git-sparse-checkout/2.37.0'
+    label: 'Git 2.37 release notes — cone mode becomes the default for sparse-checkout'
+  - url: 'https://github.com/actions/checkout?tab=readme-ov-file'
+    label: 'actions/checkout — sparse-checkout inputs documentation'

package/errors/silent-failures/silent-failures-099.yml

@@ -0,0 +1,104 @@
+id: silent-failures-099
+title: 'setup-node registry-url auto-sets NODE_AUTH_TOKEN which blocks npm OIDC provenance publish'
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-node
+  - npm
+  - oidc
+  - provenance
+  - NODE_AUTH_TOKEN
+  - registry-url
+  - publish
+patterns:
+  - regex: 'npm publish.*--provenance'
+    flags: 'i'
+  - regex: 'npm (ERR!|error) code E401'
+    flags: 'i'
+  - regex: 'NODE_AUTH_TOKEN.*publish|npm.*oidc.*token'
+    flags: 'i'
+error_messages:
+  - "npm error code E401"
+  - "npm error 401 Unauthorized - PUT https://registry.npmjs.org/"
+  - "npm publish --provenance"
+root_cause: |
+  When actions/setup-node is used with `registry-url`, it automatically generates a
+  `.npmrc` file containing `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`. This
+  binds npm authentication to the NODE_AUTH_TOKEN environment variable at publish time.
+
+  For npm OIDC publishing (`npm publish --provenance`), npm requires that no
+  `_authToken` is set (or that it is empty string), so that npm can use the GitHub
+  Actions OIDC token to authenticate and attach a sigstore provenance attestation.
+
+  However, if NODE_AUTH_TOKEN is present in the environment — even set by setup-node's
+  own post-install logic (authutil.ts sets a default value when registry-url is
+  provided) — npm uses that token for auth instead of OIDC. This silently bypasses the
+  OIDC flow in one of two ways:
+    1. NODE_AUTH_TOKEN is set to a valid npm publish token → publish succeeds but
+       WITHOUT provenance attestation (silent failure, no error thrown).
+    2. NODE_AUTH_TOKEN is set to a wrong/expired value (e.g., GitHub token) → npm
+       rejects with E401 Unauthorized, making it seem like a credential problem.
+
+  Both cases confuse developers who believe setup-node + --provenance "just works".
+  The root: setup-node's auto-set NODE_AUTH_TOKEN takes precedence over OIDC.
+
+  Source: actions/setup-node#1440 (23 reactions, closed May 2026 — setup-node v5+ adds
+  a new behavior where OIDC is respected, but pre-v5 or misconfigured workflows still
+  hit this).
+fix: |
+  Option 1 (recommended — explicit unset in publish step):
+  Unset NODE_AUTH_TOKEN in the npm publish step's `env:` block so that OIDC can take
+  over. An empty string `""` causes npm to ignore the .npmrc token reference.
+
+  Option 2: Remove `registry-url` from setup-node if you don't need .npmrc written
+  (e.g., when publishing to npmjs.org with OIDC only). setup-node only writes .npmrc
+  when registry-url is explicitly set.
+
+  Option 3: Upgrade to actions/setup-node@v5+ which fixed the default NODE_AUTH_TOKEN
+  behavior to not override OIDC when the token is unset.
+
+  Option 4: Set `auth-token: ""` in the setup-node step (setup-node v5.5.0+).
+fix_code:
+  - language: yaml
+    label: 'Unset NODE_AUTH_TOKEN in the npm publish step to allow OIDC'
+    code: |
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish with provenance
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ''   # Explicitly empty so npm uses OIDC instead of token auth
+  - language: yaml
+    label: 'Correct OIDC provenance publish permissions'
+    code: |
+      permissions:
+        contents: read
+        id-token: write   # Required for OIDC token — without this npm --provenance fails
+
+      steps:
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+            registry-url: 'https://registry.npmjs.org'
+
+        - run: npm publish --provenance --access public
+          env:
+            NODE_AUTH_TOKEN: ''
+prevention:
+  - 'Always set `id-token: write` permission when using npm --provenance OIDC publishing'
+  - 'Set `NODE_AUTH_TOKEN: ""` explicitly in the env of the npm publish step when using OIDC'
+  - 'Upgrade to actions/setup-node v5+ which corrected the default NODE_AUTH_TOKEN behavior'
+  - 'Verify provenance attestation was created: check the package page on npmjs.org for the attestations badge'
+  - 'Avoid setting registry-url in setup-node if only using OIDC and no npm install caching is needed'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1440'
+    label: 'actions/setup-node#1440: Don''t default NPM_AUTH_TOKEN to support NPM OIDC (23 reactions, closed May 2026)'
+  - url: 'https://docs.npmjs.com/generating-provenance-statements'
+    label: 'npm Docs: Generating provenance statements'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds'
+    label: 'GitHub Docs: Artifact attestations for build provenance'
+  - url: 'https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-npm'
+    label: 'setup-node advanced usage: publishing to npm'

package/errors/silent-failures/sparse-checkout-non-cone-gitignore-depth-extra-paths.yml

@@ -0,0 +1,96 @@
+id: 'silent-failures-100'
+title: 'sparse-checkout-cone-mode: false matches file patterns at any depth, checking out unintended paths'
+category: 'silent-failures'
+severity: 'silent-failure'
+tags:
+  - sparse-checkout
+  - cone-mode
+  - gitignore-patterns
+  - checkout
+  - extra-files
+patterns:
+  - regex: 'sparse-checkout-cone-mode:\s*false'
+    flags: 'i'
+  - regex: 'sparse.checkout.*cone.mode.*false'
+    flags: 'i'
+  - regex: 'non.cone mode.*sparse'
+    flags: 'i'
+error_messages:
+  - "Run actions/checkout@v4"
+  - "sparse-checkout-cone-mode: false"
+  - "Unexpected files present in workspace"
+root_cause: |
+  When `sparse-checkout-cone-mode: false` is set, `actions/checkout` uses
+  gitignore-style pattern matching for sparse checkout. In this non-cone mode,
+  a pattern like `myfile.yaml` (without a leading `/`) is interpreted as a
+  gitignore glob that matches `myfile.yaml` at ANY depth in the repository tree,
+  not just at the root. This causes `folderA/myfile.yaml`,
+  `folderB/subdir/myfile.yaml`, and all other path-depth occurrences of the
+  filename to be checked out alongside the intended root-level `myfile.yaml`.
+
+  Similarly, a pattern like `scripts` matches not just the top-level `scripts/`
+  directory but any directory or file named `scripts` at any depth.
+
+  The checkout step reports success with no error — the silent failure is that
+  the workspace contains more files than the developer expected, which can:
+  - Cause unintended files to be processed by downstream steps
+  - Inflate workspace size beyond what sparse checkout was intended to achieve
+  - Cause cache keys computed from workspace contents to be incorrect
+  - Introduce security risks if sensitive files at unexpected paths are included
+
+  Reported in actions/checkout#1628 (Feb 2024, multiple reproductions).
+  Non-cone mode is also deprecated by the Git project for these and other reasons.
+fix: |
+  Option 1 (recommended): Switch to cone mode (the default).
+  Cone mode only accepts directory names, not patterns. It always includes root-level
+  files and all files under the specified directories. It is faster and predictable.
+
+  Option 2: Anchor non-cone patterns to the root with a leading `/`.
+  In gitignore syntax, a leading `/` anchors the pattern to the root of the tree,
+  so `/myfile.yaml` matches only the root-level file, not `/subfolder/myfile.yaml`.
+
+  Option 3: Use `filter: blob:none` (partial clone) instead of sparse-checkout
+  when you need to avoid downloading specific large binary assets rather than
+  limiting which files are checked out.
+fix_code:
+  - language: yaml
+    label: 'Switch from non-cone to cone mode (recommended)'
+    code: |
+      # BEFORE (non-cone mode — patterns match at any depth)
+      # - uses: actions/checkout@v4
+      #   with:
+      #     sparse-checkout-cone-mode: false
+      #     sparse-checkout: |
+      #       myfile.yaml
+      #       scripts
+
+      # AFTER (cone mode — specify directory names; root files always included)
+      - uses: actions/checkout@v4
+        with:
+          # sparse-checkout-cone-mode: true  # This is the default — safe to omit
+          sparse-checkout: |
+            scripts
+            # Root-level files are always included in cone mode automatically
+  - language: yaml
+    label: 'Anchor non-cone patterns to root with leading / if you must use non-cone mode'
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout-cone-mode: false
+          sparse-checkout: |
+            /myfile.yaml      # Leading / anchors to repo root only
+            /scripts          # Only the top-level scripts/ directory
+            # WITHOUT leading /, 'scripts' would match any 'scripts' dir at any depth
+prevention:
+  - "Avoid sparse-checkout-cone-mode: false unless you specifically need gitignore-style pattern matching."
+  - "When using non-cone mode, always prefix patterns with / to anchor them to the repository root."
+  - "After a sparse checkout, validate workspace contents by printing ls -R or find . to spot unexpected files."
+  - "Prefer cone mode (the default) — it is faster, predictable, and not deprecated."
+  - "For excluding large binary files rather than limiting directory scope, use partial clone with filter: blob:none."
+docs:
+  - url: 'https://github.com/actions/checkout/issues/1628'
+    label: 'actions/checkout#1628 — sparse-checkout checks out undefined paths in non-cone mode'
+  - url: 'https://git-scm.com/docs/git-sparse-checkout#_non_cone_problems'
+    label: 'Git docs — Non-cone mode problems and deprecation notice'
+  - url: 'https://github.com/actions/checkout?tab=readme-ov-file#fetch-only-a-single-file'
+    label: 'actions/checkout — Sparse-checkout usage and cone-mode default'

package/errors/silent-failures/upload-download-artifact-silent-failure-windows-heap-corruption.yml

@@ -0,0 +1,90 @@
+id: silent-failures-101
+title: "upload-artifact/download-artifact fails silently with no error message on Windows (exit -1073740791)"
+category: silent-failures
+severity: error
+tags:
+  - upload-artifact
+  - download-artifact
+  - windows
+  - silent-failure
+  - node-crash
+  - heap-corruption
+patterns:
+  - regex: 'Node Action run completed with exit code -1073740791'
+    flags: 'i'
+  - regex: '^Finalizing artifact upload\s*$'
+    flags: 'im'
+  - regex: '^Downloading single artifact\s*$'
+    flags: 'im'
+error_messages:
+  - "##[debug]Node Action run completed with exit code -1073740791"
+  - "Finalizing artifact upload"
+  - "Downloading single artifact"
+root_cause: |
+  A Promise rejection during blob upload (upload-artifact) or HTTP chunk download
+  (download-artifact) causes the Node.js process to terminate abruptly on Windows
+  with exit code -1073740791 (STATUS_HEAP_CORRUPTION / 0xC0000409). Node exits
+  before the catch handler runs, so no error message is ever logged — the step
+  fails silently with no diagnostic output.
+
+  The underlying race was in actions/toolkit's HTTP client: when a blob transfer
+  encounters a network blip or ABS latency spike, an unhandled promise rejection
+  aborts the Node process on Windows. The bug manifests more frequently on Windows
+  runners, on large artifacts (>100MB), and during periods of elevated Azure Blob
+  Storage latency.
+
+  Typical log signatures:
+  - upload-artifact: logs stop after "Finalizing artifact upload" — the
+    "Artifact ... successfully finalized. Artifact ID ..." confirmation line
+    is absent.
+  - download-artifact: logs stop after "Downloading single artifact" — the
+    "Artifact download completed successfully" line is absent, and debug logs
+    show "Node Action run completed with exit code -1073740791".
+fix: |
+  1. Re-run the failed job — the bug is transient and sporadic; most reruns succeed.
+  2. Upgrade to upload-artifact v4.6.0+ and download-artifact v4.2.0+ / v8.0.2+
+     which include the fix from actions/toolkit#2406 (deferred promise creation
+     in chunk loops and propagated download errors).
+  3. If using a Windows runner and seeing frequent failures, split large artifacts
+     into smaller named chunks to reduce per-blob transfer time.
+fix_code:
+  - language: yaml
+    label: "Upgrade artifact actions to fixed versions"
+    code: |
+      # upload-artifact v4.6.0+ includes fix for silent heap corruption exit
+      - uses: actions/upload-artifact@v4
+        with:
+          name: my-artifact
+          path: dist/
+
+      # download-artifact v4.2.0+ / v8.0.2+ includes fix
+      - uses: actions/download-artifact@v4
+        with:
+          name: my-artifact
+  - language: yaml
+    label: "Workaround: split large artifacts to reduce per-blob transfer failures"
+    code: |
+      # Upload separate chunks instead of one large artifact
+      - uses: actions/upload-artifact@v4
+        with:
+          name: my-artifact-binaries
+          path: dist/binaries/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: my-artifact-assets
+          path: dist/assets/
+prevention:
+  - "Pin upload-artifact to v4.6.0+ and download-artifact to v4.2.0+/v8.0.2+ which include the heap corruption fix"
+  - "Monitor Windows runner jobs for sporadic step failures with no error output — a rerun is the immediate workaround"
+  - "Prefer uploading many smaller artifacts over one large artifact to reduce per-blob transfer window"
+  - "Enable debug logging (ACTIONS_RUNNER_DEBUG=true) to surface the exit code -1073740791 diagnostic line"
+docs:
+  - url: "https://github.com/actions/upload-artifact/issues/806"
+    label: "[bug] Upload failed without an error output (upload-artifact#806)"
+  - url: "https://github.com/actions/download-artifact/issues/475"
+    label: "[bug] Action failed without any error message (download-artifact#475)"
+  - url: "https://github.com/actions/toolkit/pull/2406"
+    label: "Fix: Propagate download error and verify length (toolkit#2406)"
+  - url: "https://github.com/actions/download-artifact/pull/479"
+    label: "Fix: Defer promise creation into chunk loop to prevent unhandled rejections on Windows (download-artifact#479)"

package/package.json

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