@htekdev/actions-debugger 1.0.50 → 1.0.51

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

@@ -0,0 +1,110 @@
+id: runner-environment-106
+title: 'Windows Server 2019 (windows-2019) runner retired April 1, 2025 — jobs fail or queue indefinitely'
+category: runner-environment
+severity: error
+tags:
+  - windows-2019
+  - runner-retirement
+  - windows-server-2019
+  - deprecated-runner
+  - github-hosted
+  - runs-on
+  - visual-studio-2019
+patterns:
+  - regex: 'runs-on:\s*windows-2019'
+    flags: 'i'
+  - regex: 'No runner matching the specified labels was found.*windows-2019|Requested labels:\s*windows-2019'
+    flags: 'i'
+error_messages:
+  - 'No runner matching the specified labels was found: windows-2019'
+  - '##[error]No runner matching the specified labels was found'
+  - 'Runner not found matching labels: [windows-2019]'
+root_cause: |
+  GitHub retired the Windows Server 2019 (windows-2019) GitHub-hosted runner on
+  April 1, 2025. After this date, workflows specifying runs-on: windows-2019 can
+  no longer be scheduled on a GitHub-hosted runner matching that label.
+
+  GitHub announced the deprecation in September 2024 (90+ days notice) with
+  brownout periods beginning before the hard cutoff. windows-latest had already
+  transitioned to point to windows-2022 (Windows Server 2022 with Visual Studio
+  2022) on October 28, 2024, giving teams an early signal.
+
+  Workflows most affected:
+  - Files explicitly specifying runs-on: windows-2019 (not windows-latest)
+  - Builds relying on Visual Studio 2019 toolset version v142 MSBuild tools
+  - .csproj files with hardcoded <PlatformToolset>v142</PlatformToolset>
+  - Workflows using .NET Framework or SDK behaviors specific to the VS2019 era
+  - Actions pinned to a major version that internally specified windows-2019
+  - Forks and template repositories written before windows-2022 was the default
+
+  A secondary migration concern: workflows that used windows-latest and relied on
+  VS2019 behavior were silently broken when windows-latest moved to windows-2022
+  in October 2024. Pinning to windows-2019 was a common workaround — the
+  retirement forced resolution of both the workaround and the underlying toolset
+  incompatibility simultaneously.
+fix: |
+  Replace runs-on: windows-2019 with a supported Windows runner label:
+
+  - windows-2022     — Windows Server 2022, Visual Studio 2022 (toolset v143)
+  - windows-2025     — Windows Server 2025, Visual Studio 2022 (available 2025)
+  - windows-latest   — currently maps to windows-2022
+
+  If your workflow uses MSBuild and specifies PlatformToolset=v142 (VS2019
+  toolset), you have two options:
+  1. Update project files to remove the explicit PlatformToolset element and
+     let MSBuild select the installed toolset automatically (preferred).
+  2. Migrate the .csproj to PlatformToolset v143 (VS2022 toolset).
+
+  Check these locations for VS2019-specific behavior:
+  - .csproj files with <PlatformToolset>v142</PlatformToolset>
+  - Hardcoded paths like C:\Program Files (x86)\Microsoft Visual Studio\2019\...
+  - vcpkg toolchain files referencing VS2019 installs
+  - Workflow env: blocks with hardcoded VSINSTALLDIR paths
+fix_code:
+  - language: yaml
+    label: 'Replace retired windows-2019 with windows-2022'
+    code: |
+      jobs:
+        build:
+          # Before: runs-on: windows-2019  <- retired April 1, 2025
+          runs-on: windows-2022
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Setup MSBuild
+              uses: microsoft/setup-msbuild@v2
+
+            - name: Build solution
+              run: msbuild solution.sln /p:Configuration=Release /p:Platform="Any CPU"
+              # If build fails on toolset version, update PlatformToolset in .csproj
+              # from v142 (VS2019) to v143 (VS2022) or remove it to auto-select
+
+  - language: yaml
+    label: 'Matrix across Windows versions to verify migration before cutover'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              # windows-2019 removed — retired April 1, 2025
+              os: [windows-2022]
+            fail-fast: false
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Setup MSBuild
+              uses: microsoft/setup-msbuild@v2
+            - name: Build
+              run: msbuild solution.sln /p:Configuration=Release
+prevention:
+  - 'Use windows-latest or windows-2022 — never pin to a specific older Windows runner label for long-lived workflows'
+  - 'Avoid hardcoding Visual Studio toolset versions (v142, v143) in .csproj files — let MSBuild auto-select the installed toolset'
+  - 'Subscribe to GitHub Changelog at github.blog/changelog to receive runner retirement announcements before hard cutoff dates'
+  - 'Test on windows-2022 in a feature branch before any deprecation deadline to catch VS toolset migration issues early'
+docs:
+  - url: 'https://github.blog/changelog/2024-09-12-windows-2019-actions-runner-image-brownout-and-deprecation/'
+    label: 'GitHub Changelog: Windows 2019 runner image brownout and deprecation'
+  - 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 Docs: Supported GitHub-hosted runners and hardware resources'
+  - url: 'https://github.com/actions/runner-images'
+    label: 'actions/runner-images: GitHub-hosted runner image specifications'

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

@@ -0,0 +1,105 @@
+id: runner-environment-107
+title: 'Ubuntu 24.04 runner: unversioned python command absent — /usr/bin/env: python: No such file or directory'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - python
+  - python3
+  - unversioned-alias
+  - command-not-found
+  - ubuntu-noble
+  - ubuntu-latest
+patterns:
+  - regex: '/usr/bin/env:\s*[''"]?python[''"]?:\s*No such file|python:\s*command not found'
+    flags: 'i'
+  - regex: 'runs-on:\s*ubuntu-2[4-9]|runs-on:\s*ubuntu-latest'
+    flags: 'i'
+error_messages:
+  - '/usr/bin/env: python: No such file or directory'
+  - 'python: command not found'
+  - '##[error]Process completed with exit code 127.'
+root_cause: |
+  Ubuntu 24.04 (Noble Numbat) does not install the unversioned python command by
+  default. Only python3 (Python 3.12+) is present in the PATH. This follows
+  PEP 394 guidance and a deliberate Ubuntu packaging decision: the
+  python3-is-python package (which creates a /usr/bin/python -> python3 symlink)
+  is not pre-installed on GitHub-hosted Ubuntu 24.04 runners.
+
+  As of November 2024, ubuntu-latest on GitHub-hosted runners maps to ubuntu-24.04.
+  Workflows that ran on ubuntu-latest (previously ubuntu-22.04) began failing
+  because Ubuntu 22.04 runners had side-effected python aliases through
+  actions/setup-python or the python-is-python3 shim, while the Ubuntu 24.04
+  baseline has no unversioned python at all.
+
+  Affected patterns:
+  - run: python script.py
+  - run: python -m pytest
+  - Shell scripts with #!/usr/bin/env python shebang lines
+  - Makefile targets invoking python
+  - Third-party composite actions that call python internally without setup-python
+  - pip invocations — pip is also absent (only pip3 available)
+fix: |
+  Option 1 (recommended): Use actions/setup-python before any step that needs
+  Python. This installs a versioned Python and creates both python and python3
+  symlinks in PATH, resolving the problem portably across all runner OS versions.
+
+  Option 2: Replace all python invocations with python3 in workflow files.
+  Also replace pip with pip3 or python3 -m pip. Works if you control all scripts
+  but misses shebangs in vendor code or third-party tools.
+
+  Option 3: Install the alias manually in a setup step:
+    sudo apt-get install -y python-is-python3
+  This creates the /usr/bin/python -> python3 symlink immediately. The package is
+  already in the apt cache — install is fast with no download required.
+fix_code:
+  - language: yaml
+    label: 'Use actions/setup-python (recommended — portable across all runner versions)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+              # Creates both python and python3 aliases in PATH
+
+            - name: Install dependencies
+              run: python -m pip install -r requirements.txt
+
+            - name: Run tests
+              run: python -m pytest tests/
+
+  - language: yaml
+    label: 'Install python-is-python3 alias for scripts with hardcoded python shebangs'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install python alias
+              run: sudo apt-get install -y python-is-python3
+              # Creates /usr/bin/python -> python3 symlink
+              # Fast: package already in apt cache on ubuntu-24.04
+
+            - name: Run script with python shebang
+              run: ./scripts/legacy-build.sh
+              # Script uses #!/usr/bin/env python internally
+prevention:
+  - 'Always use actions/setup-python in workflows that invoke python — portable and creates the python alias on all runner OS versions'
+  - 'Avoid relying on system Python; python version and alias availability varies between Ubuntu 22.04 and 24.04'
+  - 'When ubuntu-latest bumps to a new Ubuntu version, search run: blocks and scripts for bare python and pip invocations'
+  - 'Pin ubuntu-24.04 explicitly during transition testing rather than ubuntu-latest to catch breakage before it hits production'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/9654'
+    label: 'runner-images#9654: python command not found on Ubuntu 24.04'
+  - url: 'https://github.com/actions/runner-images'
+    label: 'actions/runner-images: GitHub-hosted runner image specifications'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python: Set up a Python environment for use in Actions'

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

@@ -0,0 +1,109 @@
+id: runner-environment-108
+title: 'Ubuntu 22.04 runner: libssl.so.1.1 missing — binaries compiled on Ubuntu 20.04 fail with cannot open shared object file'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-22
+  - libssl
+  - openssl3
+  - shared-library
+  - binary-compatibility
+  - ubuntu-jammy
+  - dynamic-linking
+patterns:
+  - regex: 'libssl\.so\.1\.1.*cannot open shared object file|error while loading shared libraries: libssl\.so\.1\.1'
+    flags: 'i'
+  - regex: 'libcrypto\.so\.1\.1.*cannot open shared object file'
+    flags: 'i'
+error_messages:
+  - 'error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory'
+  - '/usr/lib/x86_64-linux-gnu/libssl.so.1.1: No such file or directory'
+  - 'error while loading shared libraries: libcrypto.so.1.1: cannot open shared object file: No such file or directory'
+root_cause: |
+  Ubuntu 22.04 (Jammy) ships OpenSSL 3.0, replacing OpenSSL 1.1. The shared
+  library libssl.so.1.1 is absent — the libssl1.1 package that provided it is
+  not available in the Ubuntu 22.04 (jammy) package repository at all; it was
+  a focal (Ubuntu 20.04) package only.
+
+  When ubuntu-latest transitioned from Ubuntu 20.04 to Ubuntu 22.04 in 2022,
+  CI pipelines that downloaded or shipped pre-compiled binaries started failing
+  because those binaries were dynamically linked against libssl1.1. Common
+  scenarios that trigger this error:
+
+  - Self-hosted runners migrated from Ubuntu 20.04 to 22.04 while tool cache
+    contains pre-compiled focal binaries
+  - Docker images with pre-compiled binaries using libssl1.1 run in container
+    jobs on ubuntu-22.04 hosts
+  - Ruby gems with native extensions (mysql2, pg, ruby-openssl) compiled on
+    Ubuntu 20.04 and installed from a cached bundler path
+  - Node.js native add-ons (node-gyp built) that link against libssl1.1
+  - Custom CLI tools shipped as pre-built .deb or tar.gz for Ubuntu 20.04
+  - Python C extension packages (pycurl, cryptography old versions) with
+    libssl1.1 runtime dependency
+
+  libcrypto.so.1.1 is also absent — tools linked against both libraries fail
+  with the same error on whichever library is loaded first.
+fix: |
+  Option 1 (best long-term): Recompile the affected binary for Ubuntu 22.04 or
+  later against OpenSSL 3.0 (libssl3). Ubuntu 20.04 reached end-of-standard-support
+  in April 2025 — new binaries should target OpenSSL 3.0.
+
+  Option 2: Install a libssl1.1 compatibility .deb backported from Ubuntu 20.04
+  focal. Add an install step using the focal security archive. This is a
+  temporary workaround — the package receives no security patches on 22.04.
+
+  Option 3: Use a container job with ubuntu:20.04 base image for steps that
+  require libssl1.1, isolating the dependency from the host runner OS.
+
+  Option 4: Pin runs-on: ubuntu-20.04 temporarily while planning recompile.
+  ubuntu-20.04 runners will eventually be retired — plan a migration timeline.
+fix_code:
+  - language: yaml
+    label: 'Install libssl1.1 compatibility shim from Ubuntu 20.04 focal archive (temporary workaround)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install libssl1.1 compatibility shim
+              run: |
+                wget -q http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+                sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
+              # WARNING: Temporary workaround only. Recompile binary against OpenSSL 3.0 for the permanent fix.
+
+            - name: Run legacy binary
+              run: ./vendor/legacy-tool
+
+  - language: yaml
+    label: 'Use container job with ubuntu:20.04 base image to isolate libssl1.1 dependency'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: ubuntu:20.04
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install prerequisites
+              run: |
+                apt-get update
+                apt-get install -y libssl1.1 curl
+
+            - name: Run legacy binary
+              run: ./vendor/legacy-tool
+              # Binary now runs with libssl1.1 available in container
+prevention:
+  - 'Compile release binaries against the same OpenSSL version as the target runner OS (3.0 for Ubuntu 22.04+)'
+  - 'When upgrading ubuntu-latest, audit all pre-compiled binaries with ldd to check for libssl.so.1.1 dynamic dependencies before rolling out'
+  - 'Use statically-linked binaries or distroless container images for tools that must run across multiple Ubuntu versions'
+  - 'In matrix workflows, include ubuntu-22.04 alongside ubuntu-20.04 to catch OpenSSL ABI incompatibilities before retirement deadlines'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/6399'
+    label: 'runner-images#6399: libssl.so.1.1 missing on Ubuntu 22.04'
+  - url: 'https://wiki.openssl.org/index.php/OpenSSL_3.0'
+    label: 'OpenSSL 3.0 migration guide — ABI compatibility with OpenSSL 1.1'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners'
+    label: 'GitHub Docs: About GitHub-hosted runners'

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

@@ -0,0 +1,121 @@
+id: runner-environment-109
+title: 'macOS 14+ (Apple Silicon) runner: Homebrew prefix changed from /usr/local to /opt/homebrew — hardcoded paths fail'
+category: runner-environment
+severity: error
+tags:
+  - macos-14
+  - apple-silicon
+  - homebrew
+  - arm64
+  - path
+  - macos-sonoma
+  - opt-homebrew
+  - cross-architecture
+patterns:
+  - regex: '/usr/local/(bin/brew|Cellar|opt)\b'
+    flags: 'i'
+  - regex: 'No such file or directory.*(/usr/local/bin/brew|/usr/local/opt|/usr/local/Cellar)'
+    flags: 'i'
+error_messages:
+  - '/usr/local/bin/brew: No such file or directory'
+  - 'Error: No such file or directory @ rb_sysopen - /usr/local/Cellar'
+  - '/usr/local/opt/openssl: No such file or directory'
+  - 'pkg-config: /usr/local/opt/openssl/lib/pkgconfig: No such file or directory'
+root_cause: |
+  Homebrew on Apple Silicon (ARM64) installs to /opt/homebrew, while Homebrew on
+  Intel x86-64 installs to /usr/local. This architectural split was introduced when
+  Homebrew added native Apple Silicon support in early 2021.
+
+  GitHub-hosted macOS runners on Apple Silicon hardware (macos-14, macos-15, and
+  macos-latest since October 2024) use /opt/homebrew as the Homebrew prefix.
+  Workflows migrating from macOS 12 or macOS 13 (Intel x86-64) to macOS 14+
+  (Apple Silicon) break when they reference hardcoded /usr/local paths:
+
+  - /usr/local/bin/brew — the brew binary itself
+  - /usr/local/Cellar/package-name — installed package files
+  - /usr/local/opt/package-name — formula options/keg link (very common for
+    openssl, readline, libpq, libyaml, icu4c, pkg-config)
+  - PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig in env: blocks
+  - OPENSSL_ROOT_DIR=/usr/local/opt/openssl in build steps
+  - LDFLAGS=-L/usr/local/opt/readline/lib for native extension builds
+  - CPPFLAGS=-I/usr/local/opt/openssl/include for C/C++ compilation
+  - Shell scripts that source /usr/local/etc/profile.d/
+
+  Commonly broken language ecosystems:
+  - Ruby gems with native extensions (nokogiri --with-opt-dir=/usr/local/opt/openssl)
+  - Python packages (pycurl, psycopg2, cryptography) with hardcoded CPPFLAGS
+  - Node.js native add-ons reading PKG_CONFIG_PATH pointing to /usr/local/opt
+  - Go builds with CGO_CFLAGS referencing /usr/local/include
+fix: |
+  Replace all hardcoded /usr/local/opt and /usr/local/Cellar paths with the
+  dynamic output of brew --prefix [formula-name].
+
+  The portable pattern:
+    OPENSSL_ROOT_DIR=$(brew --prefix openssl)
+    PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig"
+
+  brew --prefix returns /usr/local/opt/package on Intel and /opt/homebrew/opt/package
+  on Apple Silicon — making it correct on both architectures automatically.
+
+  For the Homebrew root itself, use the $HOMEBREW_PREFIX environment variable
+  which is pre-set by the runner image to the correct prefix (/usr/local or
+  /opt/homebrew) depending on the runner architecture.
+
+  Actionlint does not flag hardcoded /usr/local paths — a manual audit of
+  env: blocks and run: scripts is required when migrating runner architectures.
+fix_code:
+  - language: yaml
+    label: 'Use brew --prefix for portable formula paths across Intel and Apple Silicon'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest   # macos-14+ on Apple Silicon (/opt/homebrew)
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install dependencies
+              run: brew install openssl readline libpq
+
+            - name: Set library paths (portable — works on Intel and Apple Silicon)
+              run: |
+                echo "OPENSSL_ROOT_DIR=$(brew --prefix openssl)" >> $GITHUB_ENV
+                echo "PKG_CONFIG_PATH=$(brew --prefix openssl)/lib/pkgconfig:$(brew --prefix readline)/lib/pkgconfig" >> $GITHUB_ENV
+                echo "LDFLAGS=-L$(brew --prefix openssl)/lib -L$(brew --prefix readline)/lib" >> $GITHUB_ENV
+                echo "CPPFLAGS=-I$(brew --prefix openssl)/include -I$(brew --prefix readline)/include" >> $GITHUB_ENV
+                # DO NOT hardcode /usr/local/opt/... — breaks on Apple Silicon (/opt/homebrew)
+
+            - name: Install native gems
+              run: bundle install
+
+  - language: yaml
+    label: 'Use $HOMEBREW_PREFIX env variable for Homebrew root references'
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Install tool
+              run: brew install libffi
+
+            - name: Build with native dependency
+              run: |
+                # $HOMEBREW_PREFIX is pre-set by the runner image
+                # Intel macOS 12/13:   /usr/local
+                # Apple Silicon 14/15: /opt/homebrew
+                export LIBRARY_PATH="$HOMEBREW_PREFIX/lib:$LIBRARY_PATH"
+                export C_INCLUDE_PATH="$HOMEBREW_PREFIX/include:$C_INCLUDE_PATH"
+                make install
+prevention:
+  - 'Never hardcode /usr/local/opt, /usr/local/Cellar, or /usr/local/bin/brew — always use brew --prefix <formula> at runtime'
+  - 'Use $HOMEBREW_PREFIX (set by runner images) for generic Homebrew root path references'
+  - 'When migrating from macos-12/13 (Intel) to macos-14+ (Apple Silicon), grep workflow files and scripts for /usr/local/ strings'
+  - 'Test with runs-on: macos-14 in a feature branch before switching macos-latest to catch architecture-specific path failures'
+docs:
+  - url: 'https://docs.brew.sh/Installation'
+    label: 'Homebrew Installation docs: default prefix differences between Intel and Apple Silicon'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md'
+    label: 'actions/runner-images: macOS 14 ARM64 image README'
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners'
+    label: 'GitHub Docs: About GitHub-hosted runners — macOS runner architecture details'

package/package.json

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