@htekdev/actions-debugger 1.0.134 → 1.0.135

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

@@ -0,0 +1,144 @@
+id: runner-environment-249
+title: '`actions/github-script@v9` breaking changes — `const getOctokit` SyntaxError + `require(''@actions/github'')` ERR_REQUIRE_ESM'
+category: runner-environment
+severity: error
+tags:
+  - github-script
+  - v9
+  - breaking-change
+  - getOctokit
+  - esm
+  - require
+  - SyntaxError
+  - octokit
+patterns:
+  - regex: 'SyntaxError.*Identifier.*getOctokit.*already been declared'
+    flags: 'i'
+  - regex: "require.*@actions/github.*ERR_REQUIRE_ESM|ERR_REQUIRE_ESM.*@actions/github"
+    flags: 'i'
+  - regex: 'github-script.*v9.*const getOctokit|const getOctokit.*github-script.*v9'
+    flags: 'i'
+  - regex: "require.*@actions/github.*ES Module.*not supported"
+    flags: 'i'
+error_messages:
+  - "SyntaxError: Identifier 'getOctokit' has already been declared"
+  - "Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/@actions/github/lib/github.js is not supported."
+  - "Instead change the require of index.js to a dynamic import() which is available in all CommonJS modules."
+root_cause: |
+  `actions/github-script@v9.0.0` (released April 9, 2026) introduced two breaking changes
+  compared to v8 and earlier:
+
+  BREAKING CHANGE 1: `getOctokit` is now an injected function parameter
+  In v9, the `getOctokit` factory function is injected directly into the script's
+  execution context as a named function parameter (alongside `github`, `context`, `core`,
+  etc.). This means `getOctokit` is now a declared parameter name in the script scope.
+
+  If a script re-declares `getOctokit` using `const` or `let`, JavaScript throws a
+  SyntaxError at parse time because re-declaring a `const`/`let` binding that already
+  exists in scope is illegal:
+
+    const getOctokit = require('@octokit/rest').Octokit  // ❌ SyntaxError in v9
+    let getOctokit = ...                                  // ❌ SyntaxError in v9
+
+  Using `var` avoids this issue because `var` allows redeclaration in the same scope
+  (though the injected value will be shadowed).
+
+  BREAKING CHANGE 2: `require('@actions/github')` no longer works
+  `@actions/github` v9 is an ESM-only package. The `github-script` execution context
+  is CommonJS (CJS). Calling `require('@actions/github')` from within a script will
+  fail at runtime:
+
+    const { getOctokit } = require('@actions/github')   // ❌ ERR_REQUIRE_ESM in v9
+
+  This pattern was previously used in v7/v8 scripts to create secondary Octokit
+  clients with custom tokens. In v9, this is replaced by the injected `getOctokit`
+  function parameter, which eliminates the need to require `@actions/github` at all.
+
+  Impact: Scripts that used `require('@actions/github')` to create custom clients
+  (e.g., for cross-organization access or GitHub App tokens) will fail when the
+  action is upgraded or when `@latest` resolves to v9.
+fix: |
+  FIX FOR BREAKING CHANGE 1 (SyntaxError: 'getOctokit' already declared):
+  Remove or rename the local `getOctokit` variable declaration. The injected
+  `getOctokit` is available directly in the script scope without any import.
+  If you need to keep the variable name, use `var` instead of `const`/`let` — or
+  simply rename the local variable to something else.
+
+  FIX FOR BREAKING CHANGE 2 (ERR_REQUIRE_ESM from require('@actions/github')):
+  Replace the `require('@actions/github')` pattern with the injected `getOctokit`
+  function. In v9, `getOctokit(token)` is available directly in the script context
+  and accepts a PAT or GitHub App token to create a secondary authenticated client.
+
+  General recommendation: pin to `actions/github-script@v9` explicitly and
+  migrate your scripts using the patterns below.
+fix_code:
+  - language: yaml
+    label: 'Fix SyntaxError — use injected getOctokit directly, remove const/let redeclaration'
+    code: |
+      - uses: actions/github-script@v9
+        with:
+          script: |
+            # ❌ v8 and earlier — required declaration to get getOctokit:
+            # const { getOctokit } = require('@actions/github')
+            # const myOctokit = getOctokit(process.env.MY_TOKEN)
+
+            # ❌ v9 SyntaxError — can't redeclare the injected getOctokit parameter:
+            # const getOctokit = require('@actions/github').getOctokit   // SyntaxError!
+
+            # ✅ v9 — getOctokit is injected directly; use it without any import:
+            const myOctokit = getOctokit(process.env.MY_TOKEN)
+            const result = await myOctokit.rest.repos.get({
+              owner: 'my-org',
+              repo: 'my-private-repo',
+            })
+            core.info(`Repo: ${result.data.full_name}`)
+        env:
+          MY_TOKEN: ${{ secrets.MY_CROSS_REPO_TOKEN }}
+
+  - language: yaml
+    label: 'Fix ERR_REQUIRE_ESM — replace require(''@actions/github'') with injected getOctokit'
+    code: |
+      - uses: actions/github-script@v9
+        with:
+          script: |
+            # ❌ v8 pattern — fails with ERR_REQUIRE_ESM in v9:
+            # const { getOctokit } = require('@actions/github')
+            # const crossOrgClient = getOctokit(process.env.CROSS_ORG_TOKEN)
+
+            # ✅ v9 pattern — use injected getOctokit directly:
+            const crossOrgClient = getOctokit(process.env.CROSS_ORG_TOKEN)
+            await crossOrgClient.rest.issues.create({
+              owner: 'other-org',
+              repo: 'other-repo',
+              title: 'Cross-org issue from Actions',
+              body: 'Created via github-script v9 getOctokit factory'
+            })
+        env:
+          CROSS_ORG_TOKEN: ${{ secrets.CROSS_ORG_PAT }}
+
+  - language: yaml
+    label: 'Use dynamic import() as alternative for @actions/github internals'
+    code: |
+      - uses: actions/github-script@v9
+        with:
+          script: |
+            # If you need @actions/github internals beyond getOctokit/github,
+            # use dynamic import() — ESM packages can be imported this way in github-script:
+            const actionsGithub = await import('@actions/github')
+            const customClient = actionsGithub.getOctokit(process.env.MY_TOKEN)
+            core.info('Loaded via dynamic import')
+        env:
+          MY_TOKEN: ${{ secrets.MY_TOKEN }}
+prevention:
+  - "Pin `uses: actions/github-script@v9` (not `@latest`) to control when you upgrade and avoid surprise breaking changes"
+  - "Remove all `require('@actions/github')` calls from github-script scripts — use the injected `getOctokit` function parameter instead"
+  - "Never re-declare `getOctokit`, `github`, `context`, `core`, `exec`, `glob`, `io`, `fetch`, or `require` with `const`/`let` — these are all injected parameters in v9"
+  - "When creating secondary Octokit clients, use `getOctokit(token)` directly without any imports — this pattern works in all versions of github-script that inject the factory"
+  - "Review the v9.0.0 release notes when upgrading from v8: https://github.com/actions/github-script/releases/tag/v9.0.0"
+docs:
+  - url: 'https://github.com/actions/github-script/releases/tag/v9.0.0'
+    label: 'actions/github-script v9.0.0 release notes — breaking changes (April 9, 2026)'
+  - url: 'https://github.com/actions/github-script#creating-additional-clients-with-getoctokit'
+    label: 'actions/github-script README — Creating additional clients with getOctokit (v9 pattern)'
+  - url: 'https://github.com/actions/github-script/pull/700'
+    label: 'actions/github-script PR#700 — add getOctokit to script context, upgrade @actions/github v9'

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

@@ -0,0 +1,125 @@
+id: yaml-syntax-078
+title: '`vars.*` context returns empty string for undefined configuration variables, causing "unexpected value ''" in reusable workflow with: inputs'
+category: yaml-syntax
+severity: error
+tags:
+  - vars-context
+  - reusable-workflow
+  - workflow-call
+  - configuration-variables
+  - empty-string
+  - unexpected-value
+patterns:
+  - regex: 'evaluate reusable workflow inputs.*unexpected value'
+    flags: 'i'
+  - regex: 'vars\.\w+.*unexpected value|unexpected value.*vars\.\w+'
+    flags: 'i'
+  - regex: 'unexpected value ''''.*reusable.*input|reusable.*input.*unexpected value '''''
+    flags: 'i'
+error_messages:
+  - "evaluate reusable workflow inputs: key 'my-input': unexpected value ''"
+  - "evaluate reusable workflow inputs: unexpected value '' for boolean input"
+  - "Error: evaluate reusable workflow inputs: ... unexpected value ''"
+root_cause: |
+  When a caller workflow passes a `vars.*` context expression to a reusable workflow's
+  `with:` input, and that configuration variable is not defined in the repository or
+  organization settings, `${{ vars.SOME_VAR }}` evaluates to an empty string `""`.
+
+  Reusable workflow inputs that are typed as `boolean` or `number` (or have strict
+  validation) reject the empty string `""` with the error:
+    evaluate reusable workflow inputs: ... unexpected value ''
+
+  For `type: boolean` inputs, the only valid values are `"true"` or `"false"`.
+  An empty string `""` is not a valid boolean and triggers this error.
+  For `type: number` inputs, `""` is not parseable as a number.
+
+  Even for `type: string` inputs with `required: true`, some versions of the runner
+  treat `""` as "not provided" and reject it with this error.
+
+  Root causes of the empty string:
+  1. The developer never created the configuration variable in the repository/organization
+     Settings → Variables UI. `vars.*` is the context for configuration variables (set
+     in the UI), NOT for environment variables set with `env:` in the workflow YAML.
+  2. The variable was created at the wrong scope — e.g., created as an environment-level
+     variable but the workflow doesn't reference a matching environment.
+  3. The variable name was mistyped — `vars.MY_VAR` but the setting is named `MY_VAr`
+     (case-sensitive match is required).
+
+  This is a common confusion: developers sometimes set `env:` workflow-level variables
+  expecting them to be accessible via `vars.*`, but `vars.*` only resolves variables
+  set in the GitHub repository/organization/environment Settings UI.
+fix: |
+  Option 1 — Create the configuration variable in GitHub Settings:
+  Go to your repository (or organization/environment) Settings → Secrets and variables
+  → Actions → Variables tab, and create the variable `SOME_VAR` with the desired value.
+  The `vars.SOME_VAR` expression will then resolve correctly.
+
+  Option 2 — Provide a fallback default using the `||` operator in the caller workflow:
+  Pass `${{ vars.SOME_VAR || 'default-value' }}` to avoid passing an empty string when
+  the variable is unset. The reusable workflow input then receives `'default-value'`
+  instead of `''`.
+
+  Option 3 — Use the `inputs.` default in the reusable workflow definition:
+  In the reusable workflow's `on.workflow_call.inputs`, set a `default:` value so the
+  input has a sensible fallback even when the caller passes an empty string.
+
+  For boolean inputs specifically — always coerce `vars.*` to boolean in the caller:
+  Use `${{ vars.ENABLE_FEATURE == 'true' }}` to convert the string variable value to
+  a proper boolean rather than passing the raw string.
+fix_code:
+  - language: yaml
+    label: 'Caller workflow — provide default fallback for undefined vars.*'
+    code: |
+      jobs:
+        call-reusable:
+          uses: org/repo/.github/workflows/reusable.yml@main
+          with:
+            # ❌ Fails with "unexpected value ''" if SOME_ARG_A is not set:
+            # some-arg-a: ${{ vars.SOME_ARG_A }}
+
+            # ✅ Provide a fallback when the variable is unset:
+            some-arg-a: ${{ vars.SOME_ARG_A || 'default-value' }}
+
+            # ✅ For boolean inputs — convert the string to actual boolean:
+            # enable-feature: ${{ vars.ENABLE_FEATURE == 'true' }}
+
+  - language: yaml
+    label: 'Reusable workflow — define a default for the input'
+    code: |
+      # In the reusable workflow definition:
+      on:
+        workflow_call:
+          inputs:
+            some-arg-a:
+              type: string
+              required: false   # Make it optional if a default makes sense
+              default: 'default-value'
+              description: 'Argument A (can be overridden by vars.SOME_ARG_A in caller)'
+
+      # ✅ Now even if caller passes '' or omits the input, the default is used
+
+  - language: yaml
+    label: 'Caller workflow — coerce vars.* string to boolean for boolean inputs'
+    code: |
+      jobs:
+        call-reusable:
+          uses: org/repo/.github/workflows/reusable.yml@main
+          with:
+            # ❌ Passing vars.ENABLE_FEATURE ('true'/'false' string or '') to bool input:
+            # enable-feature: ${{ vars.ENABLE_FEATURE }}
+
+            # ✅ Coerce the string value to an actual boolean:
+            enable-feature: ${{ vars.ENABLE_FEATURE == 'true' }}
+prevention:
+  - "Use `vars.*` only for configuration variables set in the GitHub repository/organization/environment Settings UI — not for `env:` YAML workflow variables"
+  - "Always provide a `||` fallback when passing `vars.*` to a reusable workflow input: `${{ vars.MY_VAR || 'default' }}`"
+  - "For boolean reusable workflow inputs, coerce `vars.*` strings with `${{ vars.FLAG == 'true' }}` instead of passing the raw string"
+  - "Verify the variable name and scope in Settings → Secrets and variables → Actions → Variables before using it in a workflow"
+  - "Set `required: false` with a `default:` in the reusable workflow definition to make inputs resilient to empty string values"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/variables#using-the-vars-context-to-access-configuration-variable-values'
+    label: 'GitHub Docs — vars context for configuration variables (distinct from env: YAML variables)'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow'
+    label: 'GitHub Docs — Using inputs in a reusable workflow (types, required, defaults)'
+  - url: 'https://stackoverflow.com/questions/79949037/consumers-callers-vars-value-passed-and-blank-strings-for-reusable-inputs'
+    label: "Stack Overflow — Consumer's/caller's vars value passed and blank strings for reusable inputs (May 2026)"

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

@@ -0,0 +1,148 @@
+id: yaml-syntax-079
+title: 'Invalid (non-IANA) timezone value in on.schedule.cron — actionlint "invalid timezone must be a valid IANA timezone name" + GitHub workflow validation failure'
+category: yaml-syntax
+severity: error
+tags:
+  - schedule
+  - cron
+  - timezone
+  - IANA
+  - actionlint
+  - validation
+  - common-mistake
+patterns:
+  - regex: 'invalid timezone.*must be a valid IANA timezone name'
+    flags: 'i'
+  - regex: 'invalid timezone.*schedule event'
+    flags: 'i'
+  - regex: 'schedule.*timezone.*not.*valid.*IANA|IANA.*timezone.*invalid.*schedule'
+    flags: 'i'
+error_messages:
+  - 'invalid timezone "PST" in schedule event. it must be a valid IANA timezone name [events]'
+  - 'invalid timezone "EST" in schedule event. it must be a valid IANA timezone name [events]'
+  - 'invalid timezone "Asia/Somewhere" in schedule event. it must be a valid IANA timezone name [events]'
+  - 'invalid timezone "UTC+5" in schedule event. it must be a valid IANA timezone name [events]'
+  - 'invalid timezone "India" in schedule event. it must be a valid IANA timezone name [events]'
+root_cause: |
+  GitHub Actions added IANA timezone support for scheduled workflows in March 2026. The
+  `timezone:` field under `on.schedule` accepts an IANA Time Zone Database name
+  (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). GitHub and actionlint both
+  validate that the provided string is a recognized IANA timezone name.
+
+  The most common mistakes are using timezone ABBREVIATIONS or OFFSET STRINGS instead
+  of proper IANA names:
+
+  | Invalid (rejected)     | Valid IANA replacement          |
+  |------------------------|---------------------------------|
+  | PST                    | America/Los_Angeles             |
+  | EST                    | America/New_York                |
+  | CST                    | America/Chicago                 |
+  | MST                    | America/Denver                  |
+  | BST                    | Europe/London                   |
+  | CET / CEST             | Europe/Berlin or Europe/Paris   |
+  | IST                    | Asia/Kolkata                    |
+  | JST                    | Asia/Tokyo                      |
+  | AEST                   | Australia/Sydney                |
+  | UTC+5 / GMT+5 / +05:30 | Asia/Karachi or Asia/Kolkata    |
+  | India                  | Asia/Kolkata                    |
+
+  IANA timezone abbreviations (PST, EST, etc.) are NOT part of the IANA Time Zone
+  Database specification — they are informal abbreviations used in human communication
+  that map ambiguously to multiple official zones. Similarly, UTC offset strings like
+  "UTC+5" or "GMT-8" are not valid IANA names.
+
+  The only valid form is the `Region/City` (or `Region/Sub-Region/City`) format used
+  in the IANA TZ database, or the special zones like `UTC`, `Etc/UTC`, `Etc/GMT+N`.
+
+  Note: actionlint validates IANA timezone strings as of v0.7.4 (March 30, 2026),
+  released to support the new `timezone:` field. The check was further fixed in commit
+  f48c0a4 to ensure completeness of the timezone validation.
+fix: |
+  Replace the timezone abbreviation or offset string with the correct IANA timezone name.
+  The IANA Time Zone Database uses `Region/City` format (e.g., `America/New_York`).
+
+  You can look up your timezone at:
+  - https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+  - https://www.iana.org/time-zones
+  - https://nodatime.org/TimeZones (interactive timezone selector)
+
+  Common fixes:
+  - `timezone: PST` → `timezone: America/Los_Angeles`
+  - `timezone: EST` → `timezone: America/New_York`
+  - `timezone: IST` → `timezone: Asia/Kolkata`
+  - `timezone: UTC+5:30` → `timezone: Asia/Kolkata`
+fix_code:
+  - language: yaml
+    label: 'Use IANA timezone names — common US timezone fixes'
+    code: |
+      on:
+        schedule:
+          # ❌ PST is NOT a valid IANA name:
+          # - cron: '0 9 * * 1-5'
+          #   timezone: 'PST'
+
+          # ✅ Use the IANA Region/City format:
+          - cron: '0 9 * * 1-5'
+            timezone: 'America/Los_Angeles'  # Pacific (handles PST/PDT automatically)
+
+          # Other US regions:
+          # timezone: 'America/New_York'    # Eastern (EST/EDT)
+          # timezone: 'America/Chicago'     # Central (CST/CDT)
+          # timezone: 'America/Denver'      # Mountain (MST/MDT)
+          # timezone: 'Pacific/Honolulu'    # Hawaii (HST)
+
+  - language: yaml
+    label: 'Use IANA timezone names — India, Europe, Asia fixes'
+    code: |
+      on:
+        schedule:
+          # ❌ IST is NOT a valid IANA name:
+          # - cron: '30 9 * * *'
+          #   timezone: 'IST'
+
+          # ✅ India Standard Time:
+          - cron: '30 9 * * *'
+            timezone: 'Asia/Kolkata'
+
+          # Other common IANA names:
+          # timezone: 'Europe/London'       # UK (BST/GMT)
+          # timezone: 'Europe/Berlin'       # Germany (CET/CEST)
+          # timezone: 'Europe/Paris'        # France (CET/CEST)
+          # timezone: 'Asia/Tokyo'          # Japan (JST)
+          # timezone: 'Asia/Shanghai'       # China (CST)
+          # timezone: 'Australia/Sydney'    # Australia Eastern (AEST/AEDT)
+
+  - language: yaml
+    label: 'Fix UTC offset strings — use Etc/GMT or a Region/City name'
+    code: |
+      on:
+        schedule:
+          # ❌ UTC offset strings are NOT valid IANA names:
+          # - cron: '0 8 * * *'
+          #   timezone: 'UTC+5:30'   # wrong
+          # - cron: '0 8 * * *'
+          #   timezone: 'GMT+5'      # wrong
+
+          # ✅ Use the Region/City form instead:
+          - cron: '0 8 * * *'
+            timezone: 'Asia/Karachi'  # UTC+5 (Pakistan)
+
+          # Note: Etc/GMT zones use inverted sign convention (POSIX):
+          # Etc/GMT-5 is UTC+5 (confusingly inverted) — prefer Region/City names
+prevention:
+  - "Always use `Region/City` IANA timezone names (e.g., `America/New_York`) — never abbreviations like PST, EST, IST"
+  - "Look up the correct IANA name using the Wikipedia tz database list before using a new timezone"
+  - "Run `actionlint` locally (v0.7.4+) before pushing — it validates IANA timezone strings in on.schedule"
+  - "Use `UTC` explicitly for UTC schedules — it is a valid IANA name unlike `GMT+0` or `UTC+0`"
+  - "Remember that IANA names handle DST automatically (America/New_York switches between EST and EDT); abbreviations like EST are fixed-offset and ambiguous"
+docs:
+  - url: 'https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#onschedule'
+    label: 'GitHub Docs — on.schedule syntax including timezone field'
+  - url: 'https://en.wikipedia.org/wiki/List_of_tz_database_time_zones'
+    label: 'Wikipedia — List of IANA tz database timezone names'
+  - url: 'https://github.com/rhysd/actionlint/blob/main/docs/checks.md#cron-syntax-and-iana-timezone-string-at-onschedule'
+    label: 'actionlint docs — CRON syntax and IANA timezone string validation at on.schedule'
+  - url: 'https://github.com/rhysd/actionlint/issues/638'
+    label: 'actionlint #638 — Add support for timezone schedule triggers (fixed in v0.7.4)'
+  - url: 'https://github.com/rhysd/actionlint/commit/f48c0a493f9e25e99443136b413cde503258c745'
+    label: 'actionlint commit f48c0a4 — fix timezone check is incomplete (March 30, 2026)'

package/package.json

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