@htekdev/actions-debugger 1.0.93 → 1.0.94

package/errors/runner-environment/macos-xcrun-simctl-no-developer-tools.yml

@@ -0,0 +1,84 @@
+id: runner-environment-161
+title: 'macOS ARM64 runners: xcrun simctl fails — Xcode developer tools not selected'
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - xcrun
+  - simctl
+  - xcode
+  - ios
+  - arm64
+  - xcode-select
+  - macos-14
+  - macos-15
+patterns:
+  - regex: 'xcrun: error: unable to find utility "simctl"'
+    flags: 'i'
+  - regex: 'xcode-select.*tool.*requires Xcode'
+    flags: 'i'
+  - regex: 'active developer directory.*command line tools instance'
+    flags: 'i'
+  - regex: 'xcode-select: note: No developer tools were found'
+    flags: 'i'
+error_messages:
+  - 'xcrun: error: unable to find utility "simctl", not a developer tool or in PATH'
+  - 'xcode-select: error: tool ''xcodebuild'' requires Xcode, but active developer directory ''/Library/Developer/CommandLineTools'' is a command line tools instance'
+  - 'xcode-select: note: No developer tools were found, requesting install'
+root_cause: |
+  macOS 14 (macos-14) and macOS 15 (macos-15) GitHub-hosted runners include
+  multiple Xcode versions and also have Xcode Command Line Tools installed. When
+  the active developer directory is set to the Command Line Tools path
+  (/Library/Developer/CommandLineTools) rather than a full Xcode.app installation,
+  tools that require full Xcode — xcrun simctl, xcodebuild, instruments, codesign,
+  and others — fail with "unable to find utility" or "requires Xcode" errors.
+
+  The runners have a default Xcode selected at image creation time, but this can
+  be changed or reset by steps earlier in the workflow (e.g., a Homebrew install
+  that runs xcode-select internally). iOS simulator builds on the ARM64 macos-14
+  and macos-15 runners are the most common trigger because simctl is exclusively
+  a full Xcode tool with no Command Line Tools counterpart.
+fix: |
+  Explicitly select a full Xcode version using xcode-select or DEVELOPER_DIR at
+  the start of the workflow. List available Xcode versions with
+  ls /Applications/Xcode*.app to find what is pre-installed on the runner.
+fix_code:
+  - language: yaml
+    label: 'Explicitly select Xcode at workflow start'
+    code: |
+      - name: Select Xcode version
+        run: |
+          sudo xcode-select -s /Applications/Xcode_16.2.app
+          xcode-select --print-path
+  - language: yaml
+    label: 'Use DEVELOPER_DIR env var for all Xcode steps'
+    code: |
+      jobs:
+        ios-build:
+          runs-on: macos-15
+          env:
+            DEVELOPER_DIR: /Applications/Xcode_16.2.app/Contents/Developer
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: |
+                xcrun simctl list devicetypes | head -5
+                xcodebuild -scheme MyApp -sdk iphonesimulator build
+  - language: yaml
+    label: 'List available Xcode versions on the runner'
+    code: |
+      - name: List Xcode versions
+        run: ls /Applications/Xcode*.app
+        # Shows all pre-installed Xcode versions to pick the correct path
+prevention:
+  - 'Always run xcode-select -p at the start of iOS/macOS workflows to verify the active developer directory'
+  - 'Pin the Xcode version explicitly using xcode-select or DEVELOPER_DIR instead of relying on runner defaults'
+  - 'Check the runner image README at github.com/actions/runner-images for pre-installed Xcode versions per image'
+  - 'Use the setup-xcode community action for simplified Xcode version selection'
+docs:
+  - url: 'https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md'
+    label: 'macOS 15 runner image README — pre-installed Xcode versions'
+  - url: 'https://developer.apple.com/documentation/xcode/selecting-the-xcode-that-tools-will-use'
+    label: 'Apple Developer: Selecting the Xcode that tools will use'
+  - url: 'https://github.com/actions/runner-images/issues'
+    label: 'actions/runner-images GitHub Issues — macOS Xcode selection reports'

package/errors/runner-environment/node-22-openssl-legacy-provider-removed.yml

@@ -0,0 +1,96 @@
+id: runner-environment-162
+title: 'Node.js 22 removed --openssl-legacy-provider — webpack 4 and Create React App builds fail'
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node-22
+  - openssl
+  - webpack
+  - create-react-app
+  - lts
+  - setup-node
+  - openssl-legacy-provider
+patterns:
+  - regex: 'ERR_OSSL_UNSUPPORTED'
+    flags: 'i'
+  - regex: '--openssl-legacy-provider is not allowed in NODE_OPTIONS'
+    flags: 'i'
+  - regex: 'error:0308010C:digital envelope routines::unsupported'
+    flags: 'i'
+  - regex: 'opensslErrorStack.*digital envelope routines.*initialization error'
+    flags: 'i'
+error_messages:
+  - 'Error: error:0308010C:digital envelope routines::unsupported'
+  - 'node: --openssl-legacy-provider is not allowed in NODE_OPTIONS'
+  - 'opensslErrorStack: [ ''error:03000086:digital envelope routines::initialization error'' ]'
+root_cause: |
+  Node.js 22 (LTS since October 2024) completed the removal of the
+  --openssl-legacy-provider CLI flag that was first deprecated in Node.js 18.
+  When node-version: 'lts/*' or node-version: '22' in setup-node resolves to
+  Node.js 22, workflows that build webpack 4 projects, older Create React App
+  setups, or any tool using MD4/RC4/legacy OpenSSL algorithms fail with
+  ERR_OSSL_UNSUPPORTED.
+
+  The common Node.js 17/18 workaround of setting
+  NODE_OPTIONS=--openssl-legacy-provider now causes a secondary error:
+  "--openssl-legacy-provider is not allowed in NODE_OPTIONS" on Node.js 22.
+  This double-failure — the original OpenSSL error AND the workaround error —
+  makes the root cause difficult to diagnose.
+
+  This is distinct from runner-environment-111 (setup-node major version upgrade
+  breaking engines field). That entry covers package.json engines compatibility;
+  this entry covers a specific CLI flag removal at the Node.js runtime level.
+fix: |
+  The correct fix is to upgrade webpack to version 5 or migrate the project away
+  from Create React App. As a temporary workaround, pin node-version to '20'
+  while the webpack upgrade is in progress. Do not use --openssl-legacy-provider
+  as it is removed in Node.js 22 and will also error on Node.js 22.
+fix_code:
+  - language: yaml
+    label: 'Pin to Node.js 20 LTS as temporary workaround'
+    code: |
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'   # Pin to Node 20 while upgrading webpack to v5
+          cache: 'npm'
+  - language: yaml
+    label: 'Use .nvmrc to enforce Node version across all environments'
+    code: |
+      # .nvmrc contains: 20
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+  - language: yaml
+    label: 'Test builds against Node.js 22 in a separate matrix job'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              node: ['20', '22']
+            fail-fast: false
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+                cache: 'npm'
+            - run: npm ci
+            - run: npm run build
+prevention:
+  - 'Upgrade to webpack 5 — webpack 4 uses MD4 hashes that depend on legacy OpenSSL algorithms'
+  - 'Do not set NODE_OPTIONS=--openssl-legacy-provider in workflow env — it was a temporary workaround removed in Node 22'
+  - 'Use node-version-file (.nvmrc or .node-version) to prevent automatic major version upgrades when lts/* resolves to a new major'
+  - 'Run a separate CI matrix job targeting Node.js 22 to detect future incompatibilities before they block your default branch'
+docs:
+  - url: 'https://nodejs.org/en/blog/release/v22.0.0'
+    label: 'Node.js 22 release notes — OpenSSL legacy provider removal'
+  - url: 'https://github.com/webpack/webpack/issues/14532'
+    label: 'webpack GitHub issue: ERR_OSSL_UNSUPPORTED on Node.js 17+'
+  - url: 'https://docs.github.com/en/actions/use-cases-and-examples/building-and-testing/building-and-testing-nodejs#specifying-the-nodejs-version'
+    label: 'GitHub Docs: Specifying the Node.js version in setup-node'

package/errors/runner-environment/setup-java-temurin-java8-arm64-not-available.yml

@@ -0,0 +1,93 @@
+id: runner-environment-163
+title: 'actions/setup-java Temurin distribution has no Java 8 builds for macOS ARM64 runners'
+category: runner-environment
+severity: error
+tags:
+  - setup-java
+  - temurin
+  - java-8
+  - arm64
+  - macos-14
+  - macos-15
+  - apple-silicon
+  - adoptium
+patterns:
+  - regex: 'No matching distribution found for Java version 8.*Temurin'
+    flags: 'i'
+  - regex: 'Downloading Java 8.*Temurin.*aarch64.*Error'
+    flags: 'i'
+  - regex: 'Error: No matching distribution found for'
+    flags: 'i'
+  - regex: 'Could not find satisfied version for SemVer.*8.*temurin'
+    flags: 'i'
+error_messages:
+  - 'Error: No matching distribution found for Java version 8 and distribution Temurin'
+  - 'Downloading Java 8 (Temurin) aarch64... Not Found'
+  - 'Could not find satisfied version for SemVer 8 using temurin on darwin aarch64'
+root_cause: |
+  Eclipse Temurin (the continuation of AdoptOpenJDK) does not publish Java 8
+  (JDK 1.8) builds for macOS ARM64 (Apple Silicon / aarch64). Java 8 reached
+  end-of-life for Temurin production support, and no ARM64 macOS binaries were
+  ever released for that version.
+
+  The macos-14 and macos-15 GitHub-hosted runners use ARM64 hardware (M-series
+  chips). When a workflow specifies distribution: temurin with java-version: '8',
+  actions/setup-java cannot find a compatible download and fails. The error is
+  surprising because the identical workflow succeeds on macos-13 (Intel x86_64)
+  where Temurin Java 8 builds do exist.
+
+  This manifests when teams migrate from macos-13 to macos-14/15 for performance
+  or cost reasons without first auditing whether their Java version is supported
+  on ARM64.
+fix: |
+  Preferred: Upgrade to Java 11, 17, or 21 LTS — all of which have Temurin
+  ARM64 macOS builds. If Java 8 is strictly required for the build, use the
+  Zulu distribution (Azul), which publishes Java 8 builds for macOS ARM64.
+  As a last resort, use macos-13 (Intel) for legacy Java 8 jobs.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to Java 17 LTS with Temurin (recommended)'
+    code: |
+      - name: Setup Java 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'   # Temurin supports ARM64 for Java 11, 17, 21
+  - language: yaml
+    label: 'Use Zulu distribution for Java 8 on ARM64 (workaround)'
+    code: |
+      - name: Setup Java 8 via Zulu (ARM64-compatible)
+        uses: actions/setup-java@v4
+        with:
+          distribution: zulu    # Azul Zulu provides Java 8 for macOS ARM64
+          java-version: '8'
+  - language: yaml
+    label: 'Matrix build — Java 8 on Intel, Java 17 on ARM64'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              include:
+                - runner: macos-13     # Intel — Temurin Java 8 available
+                  java: '8'
+                - runner: macos-15     # ARM64 — Temurin Java 17 only
+                  java: '17'
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/setup-java@v4
+              with:
+                distribution: temurin
+                java-version: ${{ matrix.java }}
+prevention:
+  - 'Upgrade to Java 11, 17, or 21 LTS — Java 8 is past EOL for Temurin and has no ARM64 macOS builds'
+  - 'When migrating from macos-13 (Intel) to macos-14/15 (ARM64), audit all Java version requirements first'
+  - 'Use the Zulu distribution as a drop-in replacement for Java 8 when ARM64 support is required'
+  - 'Check Adoptium release availability at adoptium.net/temurin/releases before assuming a version exists on your target platform'
+docs:
+  - url: 'https://adoptium.net/temurin/releases/?version=8&os=mac&arch=aarch64'
+    label: 'Eclipse Temurin releases — Java 8 macOS AArch64 availability'
+  - url: 'https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#supported-distributions'
+    label: 'actions/setup-java: Supported distributions and platforms'
+  - url: 'https://endoflife.date/eclipse-temurin'
+    label: 'Eclipse Temurin end-of-life dates'

package/errors/runner-environment/ubuntu-tzdata-apt-hang-noninteractive-required.yml

@@ -0,0 +1,84 @@
+id: runner-environment-160
+title: 'ubuntu-24.04 apt-get install hangs on tzdata interactive timezone prompt'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - apt-get
+  - tzdata
+  - noninteractive
+  - hang
+  - debian-frontend
+patterns:
+  - regex: 'Please select the geographic area in which you live'
+    flags: 'i'
+  - regex: 'Configuring tzdata'
+    flags: 'i'
+  - regex: 'debconf: unable to initialize frontend: Dialog'
+    flags: 'i'
+error_messages:
+  - 'Please select the geographic area in which you live.'
+  - 'Configuring tzdata'
+  - 'debconf: unable to initialize frontend: Dialog'
+  - 'debconf: falling back to frontend: Readline'
+root_cause: |
+  When installing packages that depend on tzdata (tzdata itself, libssl-dev, php,
+  libpq-dev, and many others) without setting DEBIAN_FRONTEND=noninteractive,
+  apt-get sends interactive prompts for timezone configuration to the TTY. GitHub
+  Actions runner steps have no interactive TTY to respond to debconf prompts, so
+  the step hangs indefinitely until the 6-hour job timeout is reached.
+
+  Ubuntu 24.04 runners are particularly susceptible because the debconf default
+  frontend is "dialog", which requires a terminal. The hang appears to come from
+  a frozen step with no output — making it look like a performance issue rather
+  than a prompt waiting for input.
+
+  The symptom is often indirect: a workflow step that installs a package with
+  tzdata as a transitive dependency (not an explicitly installed package) silently
+  hangs. Developers are surprised because the same apt-get install command works
+  fine in an interactive shell.
+fix: |
+  Set DEBIAN_FRONTEND=noninteractive in the step or job env block before running
+  apt-get install. For tzdata specifically, pre-configure the timezone using
+  environment variables or a symlink before installation.
+fix_code:
+  - language: yaml
+    label: 'Set DEBIAN_FRONTEND at step level'
+    code: |
+      - name: Install dependencies
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y tzdata libssl-dev
+  - language: yaml
+    label: 'Set DEBIAN_FRONTEND at job level (applies to all steps)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-24.04
+          env:
+            DEBIAN_FRONTEND: noninteractive
+          steps:
+            - name: Install dependencies
+              run: |
+                sudo apt-get update
+                sudo apt-get install -y tzdata
+  - language: yaml
+    label: 'Pre-configure timezone to avoid the prompt entirely'
+    code: |
+      - name: Install tzdata non-interactively
+        run: |
+          sudo ln -snf /usr/share/zoneinfo/UTC /etc/localtime
+          echo UTC | sudo tee /etc/timezone
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata
+prevention:
+  - 'Always set DEBIAN_FRONTEND=noninteractive when running apt-get in CI environments'
+  - 'Set DEBIAN_FRONTEND at the job level env block to protect all steps automatically'
+  - 'Check transitive dependencies with apt-cache show <package> to detect tzdata deps early'
+  - 'Add a timeout-minutes to critical steps so tzdata hangs fail fast instead of blocking for 6 hours'
+docs:
+  - url: 'https://manpages.ubuntu.com/manpages/noble/man7/debconf.7.html'
+    label: 'debconf manual page — debconf frontends and noninteractive mode'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables'
+    label: 'GitHub Actions: Store information in variables'

package/package.json

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