@htekdev/actions-debugger 1.0.113 → 1.0.114

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

@@ -0,0 +1,141 @@
+id: silent-failures-102
+title: 'Matrix include: Property Boolean Values Coerced to Strings — Conditional Jobs Silently Misbehave'
+category: silent-failures
+severity: silent-failure
+tags:
+  - matrix
+  - include
+  - boolean
+  - string-coercion
+  - if-condition
+  - fromJSON
+patterns:
+  - regex: 'matrix\.[a-z_]+\s*==\s*(?:true|false)\b'
+    flags: 'i'
+  - regex: 'if:\s*\$\{\{\s*matrix\.[a-z_]+\s*\}\}'
+    flags: 'i'
+error_messages:
+  - "if: ${{ matrix.enabled }}"
+  - "if: ${{ matrix.enabled == false }}"
+  - "if: ${{ matrix.deploy == true }}"
+root_cause: |
+  All matrix property values — including those injected via `include:` entries — are coerced to
+  **strings** before expression evaluation at runtime. A matrix property configured as:
+
+  ```yaml
+  strategy:
+    matrix:
+      include:
+        - os: ubuntu-latest
+          enabled: false
+        - os: windows-latest
+          enabled: true
+  ```
+
+  produces `matrix.enabled` equal to the string `"false"` or `"true"`, not the boolean
+  `false` / `true`. This creates two distinct silent failure modes:
+
+  1. `if: ${{ matrix.enabled }}` — the string `"false"` is **truthy** in GitHub Actions expression
+     syntax (non-empty string = true). The job/step **always runs** even when the intent is to skip
+     entries where `enabled: false`.
+
+  2. `if: ${{ matrix.enabled == false }}` — compares a string against a boolean. In GitHub
+     Actions expression syntax, `"false" == false` evaluates to `false` (type mismatch). The
+     condition **always evaluates to false**, silently skipping every include entry regardless
+     of the configured value.
+
+  In both cases the workflow completes without errors or warnings. Only the observable runtime
+  behavior is wrong: jobs that should be skipped always run, or jobs that should run are
+  silently skipped.
+
+  This is distinct from composite action boolean input coercion (silent-failures-004), which
+  covers `inputs.*` properties. Matrix properties have no `type:` annotation — they are always
+  strings at expression evaluation time.
+fix: |
+  Use `fromJSON()` to parse the matrix property string into a native boolean before comparison:
+
+  - `if: ${{ fromJSON(matrix.enabled) }}` ✅ — `fromJSON("false")` → boolean `false` (falsy), skips correctly
+  - `if: ${{ fromJSON(matrix.enabled) == false }}` ✅ — correct boolean comparison
+  - `if: ${{ matrix.enabled }}` ❌ — string `"false"` is truthy, job always runs
+  - `if: ${{ matrix.enabled == false }}` ❌ — string vs boolean comparison, always evaluates to false
+
+  The same `fromJSON()` pattern applies to steps inside the matrix job:
+  ```yaml
+  steps:
+    - name: Deploy step
+      if: ${{ fromJSON(matrix.deploy) }}
+      run: ./deploy.sh
+  ```
+fix_code:
+  - language: yaml
+    label: 'Correct: fromJSON() converts string to native boolean'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - os: ubuntu-latest
+                  enabled: true
+                  deploy: false
+                - os: windows-latest
+                  enabled: false
+                  deploy: false
+          runs-on: ${{ matrix.os }}
+          # ✅ Correct: fromJSON() parses "false" → boolean false (falsy)
+          if: ${{ fromJSON(matrix.enabled) }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Deploy (conditional step)
+              # ✅ Correct: fromJSON() for step-level boolean matrix property
+              if: ${{ fromJSON(matrix.deploy) }}
+              run: echo "Deploying on ${{ matrix.os }}"
+
+  - language: yaml
+    label: 'Wrong: string "false" is truthy — job always runs'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - os: ubuntu-latest
+                  enabled: true
+                - os: windows-latest
+                  enabled: false
+          runs-on: ${{ matrix.os }}
+          # ❌ Wrong: matrix.enabled is the string "false", which is truthy
+          if: ${{ matrix.enabled }}
+          steps:
+            - run: echo "This always runs even when enabled: false"
+
+  - language: yaml
+    label: 'Wrong: string vs boolean comparison always false'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              include:
+                - name: job-a
+                  skip: false
+                - name: job-b
+                  skip: true
+          # ❌ Wrong: "false" == false is always false in Actions expressions
+          if: ${{ matrix.skip == false }}
+          steps:
+            - run: echo "This never runs for any include entry"
+prevention:
+  - 'Always wrap boolean matrix property references in fromJSON() — e.g., if: ${{ fromJSON(matrix.enabled) }}'
+  - 'Add a test matrix entry with the boolean set to false and verify the job is actually skipped before relying on the condition in production'
+  - 'Consider using string sentinel values (e.g., skip: "yes"/"no") and comparing with == to avoid the boolean coercion ambiguity entirely'
+  - 'Document in the workflow that all matrix properties are runtime strings — reviewers often assume boolean values remain boolean'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-a-matrix-for-your-jobs'
+    label: 'Using a matrix for your jobs — GitHub Actions docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson'
+    label: 'fromJSON() expression function — GitHub Actions docs'
+  - url: 'https://stackoverflow.com/questions/77059002/how-to-use-matrix-variables-to-conditionally-run-jobs-in-a-github-actions-workfl'
+    label: 'Stack Overflow Q77059002 — matrix boolean coercion and fromJSON() fix'

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

@@ -0,0 +1,119 @@
+id: silent-failures-104
+title: '`github.event.inputs.X` Returns Empty String (Not Declared Default) for `on: schedule` and Other Non-Dispatch Triggers — Use `inputs.X` Instead'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-event-inputs
+  - inputs-context
+  - schedule
+  - workflow-dispatch
+  - multi-trigger
+  - empty-string
+  - default-value
+  - context
+  - boolean-input
+patterns:
+  - regex: 'github\.event\.inputs\.[a-zA-Z_][a-zA-Z0-9_-]*'
+    flags: 'g'
+  - regex: 'on:\s*\n(?:.*\n)*?\s+schedule:'
+    flags: 'im'
+error_messages:
+  - "Deploy target is empty — expected a non-empty value from github.event.inputs.environment"
+  - "Error: Input required and not supplied"
+  - "github.event.inputs.dry_run was '' but expected 'false'"
+root_cause: |
+  Multi-trigger workflows that combine `on: schedule` (or `on: push`, `on: pull_request`,
+  etc.) with `on: workflow_dispatch` commonly read input values via
+  `${{ github.event.inputs.X }}`. This silently produces wrong results for all
+  non-dispatch runs because:
+
+  - **`github.event.inputs.X`** is populated ONLY when the workflow is triggered via
+    `workflow_dispatch`. For every other event type — including `schedule`, `push`,
+    and `pull_request` — `github.event.inputs` is null or an empty object. Accessing a
+    property returns `""` (empty string). The `default:` declared in the `inputs:` block
+    is NEVER applied through this context.
+
+  - **`inputs.X`** correctly returns the declared `default:` value for non-dispatch
+    triggers, and the actual provided value for dispatch-triggered runs.
+
+  **Silent failure patterns:**
+
+  1. **Boolean gate inverted on schedule** — `if: github.event.inputs.dry_run == 'false'`
+     evaluates to `false` on schedule runs (because `"" != "false"`), so deployment steps
+     that should run on the nightly schedule are silently skipped.
+
+  2. **Non-empty guard always fails** — `if: github.event.inputs.target != ''` is always
+     `false` on schedule even when the intended behavior is to run with the default target.
+
+  3. **String comparison breaks** — `${{ github.event.inputs.environment == 'staging' }}`
+     is `false` on schedule because the empty string does not match any environment name.
+
+  Unlike `inputs.X`, `github.event.inputs.X` has no concept of a fallback default — it
+  returns `""` for every non-dispatch event.
+
+  **Distinct from sf-077** (which covers `workflow_call` — where `github.event.inputs`
+  is null because reusable workflows use the `inputs` context, not `github.event.inputs`).
+  **Distinct from sf-072** (which covers the `inputs.X` context being empty on non-dispatch,
+  not the `github.event.inputs.X` context).
+fix: |
+  Replace all `github.event.inputs.X` references with `inputs.X` in any workflow that
+  uses multiple triggers. The `inputs` context is populated for `workflow_dispatch` and
+  `workflow_call` events, and returns the declared `default:` value for all other triggers.
+fix_code:
+  - language: yaml
+    label: "Broken — github.event.inputs.X ignores defaults on schedule runs"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+            environment:
+              type: string
+              default: production
+
+      jobs:
+        deploy:
+          steps:
+            # ❌ On schedule: dry_run="" (not "false"), environment="" (not "production")
+            - run: echo "Env=${{ github.event.inputs.environment }}"
+            # ❌ This if-condition is always false on schedule — step silently skipped!
+            - if: github.event.inputs.dry_run == 'false'
+              run: ./deploy.sh --env ${{ github.event.inputs.environment }}
+  - language: yaml
+    label: "Fixed — use inputs.X which applies declared defaults on all non-dispatch runs"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+            environment:
+              type: string
+              default: production
+
+      jobs:
+        deploy:
+          steps:
+            # ✓ On schedule: dry_run="false", environment="production" (defaults applied)
+            - run: echo "Env=${{ inputs.environment }}"
+            # ✓ Correctly runs on schedule (dry_run defaults to "false")
+            - if: inputs.dry_run == 'false'
+              run: ./deploy.sh --env ${{ inputs.environment }}
+prevention:
+  - "Always use `inputs.X` (not `github.event.inputs.X`) in any workflow with more than one trigger — `inputs.X` applies declared defaults for non-dispatch runs"
+  - "Audit all `github.event.inputs.*` references in workflows that also include `on: schedule`, `on: push`, or `on: pull_request` triggers"
+  - "Add a debug step in the workflow to log `inputs.*` values on each run — catching empty-input regressions before they cause silent deploy failures"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#inputs-context"
+    label: "GitHub Actions inputs context — recommended approach for reading workflow inputs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "Context availability — github.event.inputs is only set for workflow_dispatch triggers"
+  - url: "https://github.com/orgs/community/discussions"
+    label: "GitHub Community Discussions — multi-trigger workflows with workflow_dispatch inputs"

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

@@ -0,0 +1,137 @@
+id: yaml-syntax-068
+title: 'Composite Action run: Steps Use Caller Workspace as Working Directory — github.action_path Required for Bundled Scripts'
+category: yaml-syntax
+severity: error
+tags:
+  - composite-action
+  - github-action-path
+  - working-directory
+  - relative-path
+  - script
+  - file-not-found
+patterns:
+  - regex: 'run:\s*\./[^\s]+'
+    flags: 'i'
+  - regex: 'No such file or directory.*\./'
+    flags: 'i'
+  - regex: 'bash:.*\./.*: No such file or directory'
+    flags: 'i'
+error_messages:
+  - "bash: ./scripts/build.sh: No such file or directory"
+  - "/bin/bash: ./entrypoint.sh: No such file or directory"
+  - "Error: Process completed with exit code 127."
+  - "bash: line 1: ./setup.sh: No such file or directory"
+root_cause: |
+  When a composite action (whether local `uses: ./` or published `uses: org/action@v1`) runs a
+  `run:` step, the **working directory is the caller's workspace** (`github.workspace`), not the
+  action's own directory. Any relative path like `run: ./scripts/build.sh` resolves against the
+  caller repository root — not the composite action's repository.
+
+  This affects both published composite actions (referenced as `uses: org/my-action@v1`) and
+  local composite actions stored inside the same repository. Developers commonly write:
+
+  ```yaml
+  # In action.yml of org/my-action
+  runs:
+    using: composite
+    steps:
+      - name: Run bundled script
+        run: ./scripts/build.sh    # ❌ Resolves against CALLER workspace, not action directory
+        shell: bash
+  ```
+
+  When a caller uses `uses: org/my-action@v1`, `./scripts/build.sh` resolves to the caller's
+  `$GITHUB_WORKSPACE/scripts/build.sh`, which does not exist — producing "No such file or
+  directory" or exit code 127.
+
+  **Contrast with JavaScript/Docker actions:** In those action types, the action executes in its
+  own context. Composite actions are different — their steps are injected into the caller's
+  job environment and run with the caller's working directory.
+
+  The correct way to reference files bundled inside a composite action is to use
+  `${{ github.action_path }}`, which always points to the directory containing the action's
+  `action.yml` file, regardless of where the action is called from.
+fix: |
+  Replace relative paths in composite action `run:` steps with `${{ github.action_path }}/`:
+
+  ```yaml
+  # In action.yml
+  runs:
+    using: composite
+    steps:
+      - name: Run bundled script
+        run: ${{ github.action_path }}/scripts/build.sh   # ✅ Always resolves to action directory
+        shell: bash
+  ```
+
+  If the script must be made executable, add a `chmod` step using `github.action_path`:
+
+  ```yaml
+  steps:
+    - name: Make script executable
+      run: chmod +x ${{ github.action_path }}/scripts/build.sh
+      shell: bash
+
+    - name: Run bundled script
+      run: ${{ github.action_path }}/scripts/build.sh
+      shell: bash
+  ```
+
+  `github.action_path` is always set to the directory of the currently executing action's
+  `action.yml`, even for deeply nested composite actions calling other composite actions.
+fix_code:
+  - language: yaml
+    label: 'Correct: github.action_path for bundled scripts'
+    code: |
+      # In action.yml of your composite action (org/my-action)
+      name: 'My Action'
+      description: 'Does something useful'
+      runs:
+        using: composite
+        steps:
+          - name: Make script executable
+            run: chmod +x ${{ github.action_path }}/scripts/build.sh
+            shell: bash
+
+          - name: Run bundled build script
+            # ✅ github.action_path always points to the action's directory
+            run: ${{ github.action_path }}/scripts/build.sh
+            shell: bash
+
+          - name: Run inline Python from action directory
+            run: python ${{ github.action_path }}/tools/generate.py
+            shell: bash
+
+  - language: yaml
+    label: 'Wrong: relative path resolves against caller workspace'
+    code: |
+      # In action.yml of your composite action (org/my-action)
+      name: 'My Action'
+      runs:
+        using: composite
+        steps:
+          - name: Run bundled script
+            # ❌ Wrong: ./scripts/build.sh resolves against the CALLER's $GITHUB_WORKSPACE
+            # Fails with: bash: ./scripts/build.sh: No such file or directory
+            run: ./scripts/build.sh
+            shell: bash
+
+          # ❌ Also wrong: explicitly using github.workspace points to caller repo root
+          - name: Run script using workspace
+            run: ${{ github.workspace }}/scripts/build.sh
+            shell: bash
+
+prevention:
+  - 'Never use relative paths (./path) or github.workspace in composite action run: steps to reference the action''s own bundled files — always use github.action_path'
+  - 'Test composite actions by calling them from a separate test repository, not just the same repository where they are defined — relative paths that work locally (same repo) silently break when called externally'
+  - 'Add a step to verify the script exists at the expected path as the first step of your composite action during development: run: ls ${{ github.action_path }}/scripts/'
+  - 'Composite actions that call other composite actions each get their own github.action_path — do not pass it between actions as an input'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'github.action_path context — GitHub Actions docs'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action'
+    label: 'Creating a composite action — GitHub Actions docs'
+  - url: 'https://github.com/actions/runner/issues/1348'
+    label: 'actions/runner#1348 — Local composite actions always relative to top level repository'
+  - url: 'https://stackoverflow.com/questions/77033208/github-action-composite-type-not-working-in-other-repositories-due-to-missing'
+    label: 'Stack Overflow — Composite action not working in other repositories due to missing action files'

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

@@ -0,0 +1,118 @@
+id: yaml-syntax-069
+title: 'Job-level `env:` Variables Silently Resolve to Empty String in `services.*.image` and `container.image`'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - services
+  - container
+  - env-context
+  - image
+  - context-availability
+  - job-level-env
+  - silent-failure
+patterns:
+  - regex: 'image:\s*\S*\$\{\{\s*env\.'
+    flags: 'im'
+  - regex: 'Error response from daemon: manifest for \S+: not found'
+    flags: 'i'
+  - regex: 'invalid reference format'
+    flags: 'i'
+error_messages:
+  - "Error response from daemon: manifest for redis: not found: manifest unknown"
+  - "Error response from daemon: manifest for postgres: not found"
+  - "invalid reference format"
+  - "Error: Container action is using an invalid image"
+  - "Unable to pull image 'redis:': invalid reference format"
+root_cause: |
+  GitHub Actions evaluates `services.*.image` and `container.image` expressions BEFORE
+  the job's environment scope is initialized. At evaluation time, the `env` context only
+  contains WORKFLOW-level `env:` variables (defined in the top-level `env:` block). Any
+  `env:` variable declared inside `jobs.<job_id>.env:` is NOT yet in scope and silently
+  evaluates to empty string `""`.
+
+  Example of the broken pattern:
+
+  ```yaml
+  jobs:
+    test:
+      env:
+        REDIS_VERSION: '7.2'     # ← job-level env: NOT available in services below
+      services:
+        redis:
+          image: 'redis:${{ env.REDIS_VERSION }}'   # ← evaluates to "redis:" (empty tag)
+  ```
+
+  The expression `redis:${{ env.REDIS_VERSION }}` resolves to `redis:` which Docker treats
+  as an invalid or missing tag, causing the service to fail to start — often with
+  "manifest not found" or "invalid reference format" errors.
+
+  **Context availability in `services.*.image` and `container.image`**:
+
+  | Context       | Available? |
+  |---------------|------------|
+  | `github`      | ✅ Yes     |
+  | `inputs`      | ✅ Yes     |
+  | `vars`        | ✅ Yes     |
+  | `secrets`     | ✅ Yes     |
+  | `matrix`      | ✅ Yes     |
+  | `env` (workflow-level) | ✅ Yes |
+  | `env` (job-level)      | ❌ No — silently empty |
+  | `steps.*`     | ❌ No — no steps have run yet |
+  | `needs.*`     | ❌ No |
+
+  This affects any image version that a developer attempts to centralize in their job's
+  local `env:` block — a common pattern for organizing service dependencies.
+fix: |
+  Move the image-version environment variable from the job-level `env:` block to the
+  WORKFLOW-level `env:` block (outside `jobs:`). Alternatively, use `vars` context
+  (repository/org variables) for externalized configuration, or pin the version inline.
+fix_code:
+  - language: yaml
+    label: "Broken — job-level env silently empty in services.image"
+    code: |
+      jobs:
+        test:
+          env:
+            REDIS_VERSION: '7.2'   # ← job-level: NOT visible in services below
+          services:
+            redis:
+              image: 'redis:${{ env.REDIS_VERSION }}'  # resolves to "redis:" — fails
+  - language: yaml
+    label: "Fixed — move version to workflow-level env"
+    code: |
+      env:
+        REDIS_VERSION: '7.2'       # ← workflow-level: visible in services.image
+
+      jobs:
+        test:
+          services:
+            redis:
+              image: 'redis:${{ env.REDIS_VERSION }}'  # resolves to "redis:7.2" ✓
+  - language: yaml
+    label: "Alternative — use vars context (repository variable)"
+    code: |
+      # Set REDIS_VERSION in repository Settings → Secrets and variables → Variables
+      jobs:
+        test:
+          services:
+            redis:
+              image: 'redis:${{ vars.REDIS_VERSION }}'  # always available ✓
+  - language: yaml
+    label: "Alternative — pin version inline (simplest)"
+    code: |
+      jobs:
+        test:
+          services:
+            redis:
+              image: 'redis:7.2'   # no expression needed if version doesn't change often
+prevention:
+  - "Always define image-version env vars at the WORKFLOW level (top-level `env:`) when they are referenced in `services:` or `container:`"
+  - "Lint workflows with the GitHub VS Code extension or actionlint — it flags unsupported context references in service/container image fields"
+  - "When a service fails to pull, check the exact image name in the runner log — an empty or malformed tag (e.g., `redis:`) indicates this context-availability issue"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Actions context availability — which contexts are valid in each workflow field"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idservicesservice_idimage"
+    label: "jobs.<job_id>.services.<service_id>.image — workflow syntax reference"
+  - url: "https://github.com/orgs/community/discussions"
+    label: "GitHub Community Discussions — GitHub Actions service container configuration"

package/package.json

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