@htekdev/actions-debugger 1.0.53 → 1.0.55

package/errors/caching-artifacts/caching-artifacts-037.yml

@@ -0,0 +1,95 @@
+id: caching-artifacts-037
+title: "upload-artifact if-no-files-found defaults to 'warn' — empty upload succeeds, download job fails"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - upload-artifact
+  - if-no-files-found
+  - artifacts
+  - silent
+  - warn
+  - download
+patterns:
+  - regex: 'No files were found with the provided path'
+    flags: i
+  - regex: 'No artifact uploads were performed'
+    flags: i
+  - regex: 'was not found for the associated workflow run'
+    flags: i
+error_messages:
+  - "No files were found with the provided path: ./dist. No artifacts will be uploaded."
+  - "Warning: No files were found with the provided path: build/"
+  - "No artifact uploads were performed."
+  - "Error: An artifact named build-output was not found for the associated workflow run."
+root_cause: |
+  The if-no-files-found input of actions/upload-artifact defaults to warn, not error.
+  When the upload path: glob matches no files — because the build directory is missing,
+  a glob pattern is wrong, the working-directory setting differs from the upload path,
+  or a preceding build step failed silently — the upload step logs a warning message and
+  exits with code 0 (success).
+
+  The calling workflow sees a green upload step in the UI. The problem only surfaces in
+  the downstream job that calls actions/download-artifact, which fails with an error like
+  "An artifact named X was not found for the associated workflow run."
+
+  Developers spend time debugging the download step or the job that uses the artifact when
+  the real problem — the build not producing output — occurred earlier, often in a different
+  job. The default warn behavior exists for optional artifacts, but it is a frequent source
+  of confusion for required CI artifacts.
+fix: |
+  Set if-no-files-found: error on every upload step where the artifact is required.
+  The upload step will immediately fail with a descriptive error message that names the
+  missing path, pointing directly to the correct job.
+
+  Reserve warn or ignore only for genuinely optional artifacts — for example, test
+  screenshots that only exist when tests fail, or coverage reports that may be skipped
+  in some build configurations.
+fix_code:
+  - language: yaml
+    label: "Correct: fail immediately when required build output is missing"
+    code: |
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: ./dist/
+          if-no-files-found: error   # Fail here — not in the downstream download job
+  - language: yaml
+    label: "Optional artifact — keep warn or ignore"
+    code: |
+      - name: Upload test screenshots (optional — only exist on test failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-screenshots
+          path: ./test-results/screenshots/
+          if-no-files-found: ignore   # OK — screenshots only exist when tests fail
+  - language: yaml
+    label: "Verify build output before uploading"
+    code: |
+      - name: Verify dist/ was built
+        run: |
+          if [ ! -d "./dist" ] || [ -z "$(ls -A ./dist)" ]; then
+            echo "ERROR: dist/ directory is empty or missing"
+            exit 1
+          fi
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: ./dist/
+          if-no-files-found: error
+prevention:
+  - "Default to if-no-files-found: error in all CI pipeline templates for required artifacts"
+  - "Note that upload path: is relative to GITHUB_WORKSPACE, not the step's working-directory setting"
+  - "Add an explicit build verification step before upload to fail fast with a clear message"
+  - "Audit existing workflows: any upload-artifact step without if-no-files-found: error is a silent failure risk"
+  - "When a build step uses continue-on-error: true, verify it did not silently skip output generation before uploading"
+docs:
+  - url: "https://github.com/actions/upload-artifact#inputs"
+    label: "actions/upload-artifact: Input parameters reference"
+  - url: "https://github.com/actions/upload-artifact/blob/main/RELEASES.md"
+    label: "actions/upload-artifact: Release notes"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "GitHub Docs: Storing and sharing data from a workflow"

package/errors/permissions-auth/permissions-auth-039.yml

@@ -0,0 +1,108 @@
+id: permissions-auth-039
+title: "setup-node registry-url creates .npmrc but NODE_AUTH_TOKEN not set → npm E401"
+category: permissions-auth
+severity: error
+tags:
+  - setup-node
+  - npm
+  - registry
+  - authentication
+  - publish
+  - node_auth_token
+patterns:
+  - regex: 'npm ERR! code E401'
+    flags: i
+  - regex: 'npm ERR! 401 Unauthorized'
+    flags: i
+  - regex: 'npm ERR! need auth'
+    flags: i
+  - regex: 'npm error code EBADAUTH'
+    flags: i
+error_messages:
+  - "npm ERR! code E401"
+  - "npm ERR! 401 Unauthorized - PUT https://registry.npmjs.org/@scope/package-name"
+  - "npm ERR! need auth You need to authorize this machine using `npm adduser`"
+  - "npm error code EBADAUTH"
+root_cause: |
+  When registry-url is set in actions/setup-node, the action generates an .npmrc file
+  containing a token placeholder line such as:
+    //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
+
+  The variable name NODE_AUTH_TOKEN is hardcoded in this template and must be supplied
+  as an environment variable at runtime on every step that communicates with the registry.
+
+  If the npm publish or npm install step does not declare
+  `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` in its env: block, the placeholder expands
+  to an empty string. npm sends an unauthenticated request and receives HTTP 401
+  Unauthorized from the registry.
+
+  The setup-node step itself succeeds with no warnings — there is no validation that
+  NODE_AUTH_TOKEN will be set. The 401 only surfaces during the npm command, misleading
+  developers to investigate the token or registry configuration rather than the missing
+  env: declaration.
+fix: |
+  Add NODE_AUTH_TOKEN to the env: block of every step that runs npm commands against the
+  authenticated registry. The variable name must be exactly NODE_AUTH_TOKEN — npm reads
+  it directly from the .npmrc template generated by setup-node.
+
+  For GitHub Packages (npm.pkg.github.com), use secrets.GITHUB_TOKEN.
+  For npmjs.com, use a dedicated automation token stored as a repository secret (e.g. NPM_TOKEN).
+
+  If all registry requests — including npm install of private scoped packages — need
+  authentication (not just publish), also set always-auth: true in the setup-node step.
+fix_code:
+  - language: yaml
+    label: "Correct: NODE_AUTH_TOKEN on the publish step"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+  - language: yaml
+    label: "GitHub Packages registry variant"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@your-org'
+
+      - name: Publish to GitHub Packages
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Private package install with always-auth"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@your-org'
+          always-auth: true    # Send auth on all requests, not just publish
+
+      - name: Install dependencies (includes private scoped packages)
+        run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Every npm step that interacts with an authenticated registry must declare NODE_AUTH_TOKEN in its env: block"
+  - "Setting registry-url in setup-node does NOT automatically forward any secrets to npm — the env: mapping is always required"
+  - "Use always-auth: true in setup-node when npm install (not just publish) must authenticate, such as for private scoped packages"
+  - "Store your npm automation token as a repository secret: Settings → Secrets and variables → Actions → New repository secret"
+  - "For GitHub Packages, NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} is sufficient — no separate token needed"
+docs:
+  - url: "https://github.com/actions/setup-node#publishing-to-npmjs-and-github-packages-registries"
+    label: "actions/setup-node: Publishing to registries"
+  - url: "https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry"
+    label: "GitHub Docs: Working with the npm registry"
+  - url: "https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow"
+    label: "npm Docs: Using private packages in CI/CD"

package/errors/runner-environment/runner-environment-111.yml

@@ -0,0 +1,93 @@
+id: runner-environment-111
+title: "setup-node node-version: 'latest' silently upgrades to new Node.js major, breaking engines field"
+category: runner-environment
+severity: silent-failure
+tags:
+  - setup-node
+  - node-version
+  - latest
+  - engines
+  - breaking-change
+  - major-version
+  - semver
+patterns:
+  - regex: 'The engine "node" is incompatible with this module'
+    flags: i
+  - regex: 'EBADENGINE.*Unsupported engine'
+    flags: i
+  - regex: 'npm warn EBADENGINE'
+    flags: i
+  - regex: 'engine.*node.*incompatible.*Expected version'
+    flags: i
+error_messages:
+  - "error The engine \"node\" is incompatible with this module. Expected version \">=18 <21\". Got \"23.x.x\""
+  - "npm warn EBADENGINE Unsupported engine { required: { node: '>=16 <20' }, current: { node: 'v22.0.0' } }"
+  - "npm error code EBADENGINE"
+  - "error This package requires Node.js >= 18.0.0 and <= 22.x"
+root_cause: |
+  When node-version: 'latest' is used in actions/setup-node, the action resolves the
+  alias against the official Node.js release schedule manifest on every workflow run.
+  When Node.js releases a new major version (e.g. v23.0.0, v24.0.0), the next run silently
+  downloads and activates the new major without any warning in the setup-node step output.
+
+  Packages that declare an engines constraint in their package.json (e.g.
+  engines: { node: ">=18 <22" }) then fail during npm install or yarn install with
+  EBADENGINE because the newly installed version exceeds the accepted range.
+
+  The setup-node step itself succeeds and logs the installed version; the failure only
+  appears downstream when the package manager processes the engines field. Because the
+  workflow ran successfully for months before the Node.js major release, developers
+  are not expecting a version bump and may incorrectly blame a dependency change.
+
+  Native addons and frameworks that have not yet published compatibility updates for the
+  new major can also fail during postinstall or build steps.
+fix: |
+  Pin to a specific LTS major version string (e.g. '20', '22') rather than 'latest'.
+  LTS majors receive security patches but do not automatically jump to a new major.
+
+  Alternatively, use the node-version-file input to read the version from a .nvmrc or
+  .node-version file committed to the repository. This keeps the Node.js version
+  consistent between local development and CI and makes version upgrades explicit
+  (a PR changes the version file).
+fix_code:
+  - language: yaml
+    label: "Pin to a specific LTS major (recommended)"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'   # Pinned LTS major — will not jump to Node 24 automatically
+          cache: 'npm'
+  - language: yaml
+    label: "Use .nvmrc for repo-defined version shared with local dev"
+    code: |
+      # .nvmrc (committed to repository root)
+      # 22.x
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'   # Same version in local dev and CI
+          cache: 'npm'
+  - language: yaml
+    label: "Pin with explicit patch version for maximum reproducibility"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.13.1'   # Exact patch — fully reproducible but requires manual updates
+          cache: 'npm'
+prevention:
+  - "Never use node-version: 'latest' in production or long-lived CI workflows — pin to an LTS major"
+  - "Prefer '18', '20', or '22' (active LTS) — these receive security patches without surprise major bumps"
+  - "Use node-version-file pointing to .nvmrc to keep local development and CI on the same version"
+  - "Use Renovate or Dependabot to automate controlled Node.js upgrades with a PR and changelog review"
+  - "Test new Node.js majors in a dedicated branch before adopting them in main CI"
+  - "Declare an engines field in package.json to make your Node.js version requirement explicit and testable"
+docs:
+  - url: "https://github.com/actions/setup-node#supported-version-syntax"
+    label: "actions/setup-node: Supported version syntax"
+  - url: "https://nodejs.org/en/about/previous-releases"
+    label: "Node.js: Release schedule and LTS versions"
+  - url: "https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines"
+    label: "npm: package.json engines field documentation"

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

@@ -0,0 +1,100 @@
+id: silent-failures-054
+title: "Windows CRLF line endings in committed scripts cause bad interpreter error on Linux runners"
+category: silent-failures
+severity: error
+tags:
+  - checkout
+  - crlf
+  - line-endings
+  - windows
+  - bash
+  - gitattributes
+  - bad-interpreter
+patterns:
+  - regex: 'bad interpreter.*No such file or directory'
+    flags: i
+  - regex: '\^M: command not found'
+    flags: ''
+  - regex: '/bin/bash\^M'
+    flags: ''
+  - regex: '\r: command not found'
+    flags: ''
+error_messages:
+  - "/bin/bash^M: bad interpreter: No such file or directory"
+  - "^M: command not found"
+  - ": /bin/sh^M: bad interpreter: No such file or directory"
+  - "syntax error: unexpected end of file"
+root_cause: |
+  Shell scripts, Python files, and other text files committed from Windows workstations
+  where core.autocrlf is false (or not configured) retain Windows CRLF (\r\n) line endings.
+  actions/checkout preserves committed bytes exactly — it does not normalize line endings.
+
+  On a Linux runner, the kernel reads the shebang line #!/bin/bash\r as the interpreter
+  path /bin/bash^M (with a literal carriage return appended). No file with that name exists,
+  so the kernel returns "bad interpreter: No such file or directory." The error message
+  looks like a missing binary or path problem, masking the true cause: CRLF line endings.
+
+  This is a classic silent failure because:
+  - The developer's Windows machine runs the script correctly
+  - The checkout step succeeds with no warnings about line endings
+  - The failure only manifests when the script is executed on a Linux runner
+  - Most text editors hide the ^M characters, so the file looks normal in review
+fix: |
+  Add a .gitattributes file to the repository root specifying LF normalization for text
+  files. This instructs Git to store files with LF endings in the repository regardless
+  of the committer's OS or local git configuration.
+
+  After adding .gitattributes, re-normalize all tracked files: stage all files with the
+  renormalize flag (e.g. `add --renormalize .` via the CLI), then commit the result.
+  Without this step, already-committed CRLF files remain unchanged.
+
+  Also add a CI detection step to catch any future regressions before they reach main.
+fix_code:
+  - language: yaml
+    label: ".gitattributes — enforce LF for scripts and text files"
+    code: |
+      # .gitattributes (add to repository root)
+
+      # Normalize all text files to LF in the repository
+      * text=auto eol=lf
+
+      # Explicitly enforce LF for scripts and config files
+      *.sh   text eol=lf
+      *.bash text eol=lf
+      *.py   text eol=lf
+      *.yml  text eol=lf
+      *.yaml text eol=lf
+      *.json text eol=lf
+
+      # Keep CRLF for Windows-specific files
+      *.bat text eol=crlf
+      *.cmd text eol=crlf
+  - language: yaml
+    label: "CI step to detect CRLF in shell and Python scripts"
+    code: |
+      - name: Check for CRLF line endings in scripts
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - name: Detect CRLF
+            run: |
+              found=$(find . -name '*.sh' -o -name '*.py' -o -name '*.yml' | \
+                xargs file 2>/dev/null | grep CRLF || true)
+              if [ -n "$found" ]; then
+                echo "ERROR: CRLF line endings detected in the following files:"
+                echo "$found"
+                exit 1
+              fi
+prevention:
+  - "Add .gitattributes with `* text=auto eol=lf` to every repository that may be edited on Windows"
+  - "Re-normalize existing files after adding .gitattributes: use the CLI `add --renormalize .` flag, then commit"
+  - "Configure the autocrlf setting on Windows development machines: set core.autocrlf=input so CRLF is converted to LF on commit"
+  - "Configure your editor (VS Code, Notepad++, JetBrains) to use LF line endings for shell and YAML files by default"
+  - "Add a CRLF detection step in CI to fail PRs that introduce Windows line endings into script files"
+docs:
+  - url: "https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings"
+    label: "GitHub Docs: Configuring Git to handle line endings"
+  - url: "https://git-scm.com/docs/gitattributes"
+    label: "Git: gitattributes documentation"
+  - url: "https://github.com/actions/checkout/issues/135"
+    label: "actions/checkout Issue #135: Line ending normalization"

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

@@ -0,0 +1,99 @@
+id: silent-failures-055
+title: "'github.event_name' is 'workflow_call' inside reusable workflows — not the caller's event"
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - event_name
+  - github-context
+  - conditional
+  - silent
+patterns:
+  - regex: 'github\.event_name\s*==\s*[''"]push[''"]'
+    flags: i
+  - regex: 'github\.event_name\s*==\s*[''"]pull_request[''"]'
+    flags: i
+  - regex: 'github\.event_name\s*==\s*[''"]workflow_dispatch[''"]'
+    flags: i
+error_messages:
+  - "Evaluating: github.event_name == 'push' => false"
+  - "Step skipped: if condition 'github.event_name == \"push\"' was false"
+root_cause: |
+  When a workflow is called as a reusable workflow via on: workflow_call, GitHub Actions
+  sets github.event_name to "workflow_call" inside that workflow — NOT to the triggering
+  event from the caller workflow.
+
+  A common mistake is to write conditional logic in a reusable workflow that checks
+  github.event_name expecting the caller's event (push, pull_request, workflow_dispatch,
+  etc.). These conditions always evaluate to false when the workflow is invoked via
+  workflow_call, silently skipping the affected steps or entire jobs.
+
+  The behaviour is especially confusing because developers often test the reusable workflow
+  in isolation via workflow_dispatch — in which case github.event_name IS correct. The
+  silent skip only appears when the workflow is called from another workflow, and the skipped
+  step or job disappears from the run summary with no error message.
+fix: |
+  Pass the caller's event name as an explicit input to the reusable workflow. The caller
+  reads github.event_name from its own context (where it is correct) and passes it as a
+  string input. Inside the reusable workflow, check inputs.caller_event (or whatever name
+  you choose) instead of github.event_name.
+
+  Alternatively, restructure so that event-specific logic stays in the caller workflow and
+  the reusable workflow only receives final parameters — not the raw event name.
+fix_code:
+  - language: yaml
+    label: "Problem: event_name check always false in reusable workflow"
+    code: |
+      # reusable.yml — WRONG: event_name is always "workflow_call" here
+      on:
+        workflow_call:
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy only on push
+              if: github.event_name == 'push'   # Always false — event_name is "workflow_call"
+              run: echo "Deploying..."
+  - language: yaml
+    label: "Fix: accept caller_event as an explicit input"
+    code: |
+      # reusable.yml — CORRECT: accept the caller's event as an input
+      on:
+        workflow_call:
+          inputs:
+            caller_event:
+              type: string
+              required: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy only on push
+              if: inputs.caller_event == 'push'   # Correct — uses the passed-in value
+              run: echo "Deploying..."
+  - language: yaml
+    label: "Caller workflow: pass github.event_name as input"
+    code: |
+      # caller.yml — pass the caller's event name to the reusable workflow
+      on: [push, pull_request]
+
+      jobs:
+        call-reusable:
+          uses: ./.github/workflows/reusable.yml
+          with:
+            caller_event: ${{ github.event_name }}   # "push" or "pull_request"
+prevention:
+  - "Never use 'github.event_name' in a reusable workflow to detect the caller's event — it will always be 'workflow_call'"
+  - "Pass event-specific data as explicit inputs; document expected values in the input description field"
+  - "When testing a reusable workflow via workflow_dispatch, simulate the production caller_event value via inputs to catch conditional errors early"
+  - "The same rule applies to github.event.* properties — many will be empty or refer to the workflow_call event, not the caller's event"
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows"
+    label: "GitHub Docs: Reusing workflows"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub Docs: github context reference"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations"
+    label: "GitHub Docs: Reusable workflow limitations"

package/errors/triggers/triggers-039.yml

@@ -0,0 +1,115 @@
+id: triggers-039
+title: "'github.sha' in pull_request_target points to base branch HEAD, not the PR's head commit"
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request_target
+  - github-sha
+  - base-branch
+  - pr-head
+  - checkout
+  - security
+  - silent
+patterns:
+  - regex: 'pull_request_target'
+    flags: i
+  - regex: 'github\.event\.pull_request\.head\.sha'
+    flags: i
+  - regex: 'github\.sha.*pull_request_target'
+    flags: i
+error_messages:
+  - "Tests passed but PR code was never executed (checked out base branch at github.sha)"
+root_cause: |
+  The pull_request_target event fires in the context of the BASE branch of a pull request,
+  not the PR's head branch. Consequently, github.sha inside a pull_request_target workflow
+  is the HEAD commit SHA of the BASE branch — typically main or master — not the PR
+  contributor's changes.
+
+  This design is intentional: pull_request_target runs with repository secrets and write
+  permissions available, so GitHub restricts it to trusted base-branch code to prevent
+  malicious PR code from exfiltrating secrets. However, it causes a silent logic error when
+  developers expect github.sha (or the default actions/checkout behaviour, which checks out
+  github.sha) to build and test the PR's changes.
+
+  The result is a CI run that appears to succeed — but it compiled and tested the base
+  branch code, not the pull request's changes. The PR author sees green CI even though
+  their changes were never executed.
+fix: |
+  To work with PR head code in a pull_request_target workflow, explicitly specify the PR
+  head SHA using github.event.pull_request.head.sha in the checkout step's ref: input.
+
+  SECURITY WARNING: checking out untrusted PR code in a workflow that has access to secrets
+  creates a pwn-request vulnerability. Only check out PR head code in jobs with minimal
+  permissions and no secret exposure.
+
+  For most CI use cases — building, linting, testing — use the standard pull_request event
+  instead of pull_request_target. The pull_request event correctly checks out PR changes
+  but runs without repository secrets, which is the safe and intended design.
+fix_code:
+  - language: yaml
+    label: "Problem: default checkout in pull_request_target checks out base branch"
+    code: |
+      on: pull_request_target
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              # No ref specified — uses github.sha which is BASE branch HEAD, not PR code
+            - run: npm test   # Tests base branch, not the PR changes
+  - language: yaml
+    label: "Explicit PR head checkout (only when no secrets are exposed)"
+    code: |
+      on: pull_request_target
+
+      jobs:
+        label-and-check:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write   # Minimal permissions — no secrets
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}
+                # Only safe because this job has no secret access
+                # Do NOT add secrets: or environment: to jobs that do this
+  - language: yaml
+    label: "Recommended: use pull_request for testing, pull_request_target only for privileged operations"
+    code: |
+      # Standard PR testing — pull_request has no secrets but correctly checks out PR changes
+      on: pull_request
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              # github.sha is the PR merge commit — correct for testing PR changes
+            - run: npm test
+
+      ---
+      # Separate privileged workflow for labeling/commenting — uses pull_request_target
+      # This one works with base-branch context (github.sha = base HEAD) — which is correct
+      # for privileged operations that should only run trusted code
+      on: pull_request_target
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            - uses: actions/labeler@v5
+prevention:
+  - "Default to 'pull_request' event for building and testing PR code — it correctly checks out PR changes and has no secrets"
+  - "Use 'pull_request_target' only for privileged operations that genuinely need secrets or write permissions (labeling, commenting, deployment approval)"
+  - "Never expose repository secrets in the same job that checks out untrusted PR head code via github.event.pull_request.head.sha"
+  - "Add a comment next to any pull_request_target checkout step documenting which ref is used and why it is safe"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "GitHub Docs: pull_request_target event"
+  - url: "https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/"
+    label: "GitHub Security Lab: Preventing pwn requests"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions"
+    label: "GitHub Docs: Security hardening for GitHub Actions"

package/errors/yaml-syntax/yaml-syntax-038.yml

@@ -0,0 +1,91 @@
+id: yaml-syntax-038
+title: "'::save-state::' and '::get-state::' workflow commands deprecated — upgrade to GITHUB_STATE"
+category: yaml-syntax
+severity: warning
+tags:
+  - save-state
+  - get-state
+  - deprecated
+  - workflow-commands
+  - environment-files
+  - GITHUB_STATE
+patterns:
+  - regex: 'The `save-state` command is deprecated'
+    flags: i
+  - regex: 'The `get-state` command is deprecated'
+    flags: i
+  - regex: '::save-state name='
+    flags: ''
+  - regex: '::get-state name='
+    flags: ''
+error_messages:
+  - "Warning: The `save-state` command is deprecated and will be disabled soon. Please upgrade to using Environment Files."
+  - "Warning: The `get-state` command is deprecated and will be disabled soon. Please upgrade to using Environment Files."
+root_cause: |
+  GitHub Actions originally provided workflow commands ::save-state name=FOO::value and
+  ::get-state name=FOO:: as a way to persist data between the main body of a step and its
+  pre: or post: hooks in JavaScript actions.
+
+  GitHub deprecated these commands when it introduced environment files (GITHUB_STATE,
+  GITHUB_ENV, GITHUB_OUTPUT) as a more robust alternative. Workflows and actions that use
+  the old echo "::save-state name=...::value" or echo "::get-state name=...:" syntax now
+  produce deprecation warnings in workflow logs.
+
+  When these commands are eventually disabled, steps using them will silently fail to persist
+  state — the post: hook will read an empty string from the state variable, causing subtle
+  logic errors. Actions published to the Marketplace are particularly affected because older
+  versions used these commands before the deprecation was announced.
+fix: |
+  Replace the deprecated workflow commands with the GITHUB_STATE environment file approach:
+  - To write state: append "KEY=value" to $GITHUB_STATE (shell) or write to
+    process.env['GITHUB_STATE'] (Node.js)
+  - To read state in pre:/post: hooks: read the environment variable STATE_<KEY>
+
+  In shell-based steps the pattern is identical to GITHUB_ENV and GITHUB_OUTPUT.
+  In JavaScript actions, upgrade to @actions/core v1.10.0+ and use the saveState() and
+  getState() helpers, which internally write to GITHUB_STATE.
+fix_code:
+  - language: yaml
+    label: "Deprecated: ::save-state:: and ::get-state:: commands (produces warnings)"
+    code: |
+      # DEPRECATED — produces warning in logs, will eventually break
+      - name: Save state (deprecated)
+        run: echo "::save-state name=SERVER_PID::12345"
+
+      - name: Read state in post step (deprecated)
+        run: echo "Saved PID was $(echo "::get-state name=SERVER_PID::")"
+  - language: yaml
+    label: "Correct: GITHUB_STATE environment file"
+    code: |
+      # Write state to GITHUB_STATE file
+      - name: Save state
+        run: echo "SERVER_PID=12345" >> $GITHUB_STATE
+
+      # State is automatically available as STATE_<KEY> in later phases
+      - name: Read state (available in main, pre, and post phases)
+        run: echo "Server PID was $STATE_SERVER_PID"
+  - language: yaml
+    label: "PowerShell equivalent"
+    code: |
+      - name: Save state (PowerShell)
+        shell: pwsh
+        run: |
+          "SERVER_PID=12345" | Out-File -FilePath $env:GITHUB_STATE -Append
+
+      - name: Read state (PowerShell)
+        shell: pwsh
+        run: |
+          Write-Host "Server PID was $env:STATE_SERVER_PID"
+prevention:
+  - "Audit actions with pre: or post: hooks — these are the primary consumers of save-state/get-state"
+  - "Upgrade to @actions/core v1.10.0+ which uses GITHUB_STATE internally via saveState()/getState()"
+  - "Search existing workflows and composite actions for '::save-state' and '::get-state' patterns before they are disabled"
+  - "Pin to action versions that have migrated to GITHUB_STATE; check CHANGELOG for migration notes"
+  - "The same deprecation cycle affected ::set-output:: (now GITHUB_OUTPUT) and ::set-env:: (now GITHUB_ENV)"
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#environment-files"
+    label: "GitHub Docs: Workflow commands — environment files"
+  - url: "https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/"
+    label: "GitHub Changelog: Deprecating save-state and set-output commands (Oct 2022)"
+  - url: "https://github.com/actions/toolkit/releases/tag/%40actions%2Fcore%401.10.0"
+    label: "actions/toolkit: @actions/core v1.10.0 release notes"

package/errors/yaml-syntax/yaml-syntax-039.yml

@@ -0,0 +1,115 @@
+id: yaml-syntax-039
+title: "'type: choice' not supported for workflow_call inputs — validation error when combining with workflow_dispatch"
+category: yaml-syntax
+severity: error
+tags:
+  - workflow_call
+  - workflow_dispatch
+  - inputs
+  - type-choice
+  - validation
+  - combined-triggers
+patterns:
+  - regex: 'Input type .choice. is not supported'
+    flags: i
+  - regex: 'Unexpected value .choice.'
+    flags: i
+  - regex: 'Invalid workflow file.*type.*choice'
+    flags: i
+error_messages:
+  - "Invalid workflow file: Input type 'choice' is not supported for workflow_call triggers. Allowed types: boolean, number, string"
+  - "Unexpected value 'choice', expected one of: boolean, number, string"
+  - "Invalid value for inputs.*.type: 'choice'"
+root_cause: |
+  GitHub Actions supports different input types depending on the trigger:
+  - workflow_dispatch supports: boolean, choice, environment, number, string
+  - workflow_call supports only: boolean, number, string
+
+  When developers combine both triggers in the same workflow file (a common pattern for
+  workflows that can be called by other workflows AND dispatched manually), they define a
+  shared inputs: block. If those shared inputs use type: choice — valid for workflow_dispatch
+  but not workflow_call — the workflow fails schema validation with a cryptic error.
+
+  The error message does not always clearly indicate which trigger is rejecting the type,
+  causing developers to search for choice support across GitHub Actions documentation rather
+  than recognising it as a trigger-specific limitation. The same restriction applies to
+  type: environment.
+fix: |
+  For inputs shared between workflow_dispatch and workflow_call, use type: string and
+  document the allowed values in the description field. The GitHub UI renders a free-text
+  field for manual dispatch instead of a dropdown, but callers still pass controlled values.
+
+  For strict input validation, add a shell step at the start of the job that fails if the
+  input value is not in the allowed set.
+
+  If the dropdown UI is essential for manual dispatch, create a thin dispatcher workflow
+  (workflow_dispatch only with type: choice) that calls the main reusable workflow passing
+  the validated value as a string.
+fix_code:
+  - language: yaml
+    label: "Problem: type: choice breaks workflow_call validation"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice           # Valid for workflow_dispatch only
+              options: [dev, staging, prod]
+        workflow_call:
+          inputs:
+            environment:
+              type: choice           # INVALID for workflow_call — causes validation error
+  - language: yaml
+    label: "Fix: use type: string with documented allowed values"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: string
+              description: "Target environment. Allowed values: dev, staging, prod"
+              default: dev
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              description: "Target environment. Allowed values: dev, staging, prod"
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate environment input
+              run: |
+                case "${{ inputs.environment }}" in
+                  dev|staging|prod) echo "Environment: ${{ inputs.environment }}" ;;
+                  *) echo "Invalid environment: ${{ inputs.environment }}"; exit 1 ;;
+                esac
+  - language: yaml
+    label: "Alternative: dispatcher wrapper preserves dropdown UI for manual runs"
+    code: |
+      # dispatcher.yml — manual dispatch wrapper with choice dropdown
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              options: [dev, staging, prod]
+
+      jobs:
+        dispatch:
+          uses: ./.github/workflows/deploy.yml    # calls the reusable workflow
+          with:
+            environment: ${{ inputs.environment }}  # passes as string
+prevention:
+  - "workflow_call inputs support only: boolean, number, string — not choice or environment"
+  - "Use type: string with a description listing allowed values when an input is shared across both triggers"
+  - "Add input validation as the first job step to fail fast when an unexpected value is passed via workflow_call"
+  - "Run actionlint locally before pushing — it catches unsupported input types at development time"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_callinputs"
+    label: "GitHub Docs: on.workflow_call.inputs syntax"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputs"
+    label: "GitHub Docs: on.workflow_dispatch.inputs syntax"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint: static checker for GitHub Actions workflow files"

package/package.json

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