@htekdev/actions-debugger 1.0.0

package/dist/utils/yaml-parser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Workflow YAML analysis utilities.
+ * Parses GitHub Actions workflow YAML and checks for common mistakes.
+ */
+import type { DiagnosticFinding } from "../db/types.js";
+/**
+ * Analyze a workflow YAML string for common issues.
+ */
+export declare function analyzeWorkflow(workflowYaml: string): DiagnosticFinding[];
+//# sourceMappingURL=yaml-parser.d.ts.map

package/dist/utils/yaml-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-parser.d.ts","sourceRoot":"","sources":["../../src/utils/yaml-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AA4BxD;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAiJzE"}

package/dist/utils/yaml-parser.js

@@ -0,0 +1,142 @@
+/**
+ * Workflow YAML analysis utilities.
+ * Parses GitHub Actions workflow YAML and checks for common mistakes.
+ */
+import yaml from "js-yaml";
+/**
+ * Analyze a workflow YAML string for common issues.
+ */
+export function analyzeWorkflow(workflowYaml) {
+    const findings = [];
+    // Check for tab characters (before parsing — YAML rejects tabs)
+    if (workflowYaml.includes("\t")) {
+        findings.push({
+            severity: "critical",
+            message: "Tab characters detected — GitHub Actions requires spaces for indentation.",
+            fix: "Replace all tabs with spaces (2-space indentation recommended).",
+            fix_code: "# Use .editorconfig:\nindent_style = space\nindent_size = 2",
+        });
+    }
+    let workflow;
+    try {
+        workflow = yaml.load(workflowYaml);
+    }
+    catch (err) {
+        findings.push({
+            severity: "critical",
+            message: `YAML parse error: ${err.message}`,
+            fix: "Fix the YAML syntax error before proceeding.",
+        });
+        return findings;
+    }
+    if (!workflow || typeof workflow !== "object") {
+        findings.push({
+            severity: "critical",
+            message: "Workflow is empty or not a valid YAML object.",
+            fix: "Ensure the file contains a valid GitHub Actions workflow.",
+        });
+        return findings;
+    }
+    // Check jobs
+    if (!workflow.jobs || Object.keys(workflow.jobs).length === 0) {
+        findings.push({
+            severity: "critical",
+            message: "No jobs defined in workflow.",
+            fix: "Add at least one job under the `jobs:` key.",
+        });
+        return findings;
+    }
+    const hasTopLevelPermissions = !!workflow.permissions;
+    for (const [jobName, job] of Object.entries(workflow.jobs)) {
+        // Missing runs-on
+        if (!job["runs-on"]) {
+            findings.push({
+                severity: "critical",
+                message: `Job '${jobName}' is missing 'runs-on'.`,
+                fix: "Add runs-on: ubuntu-latest (or another runner label).",
+                fix_code: `jobs:\n  ${jobName}:\n    runs-on: ubuntu-latest`,
+            });
+        }
+        // Missing permissions
+        if (!hasTopLevelPermissions && !job.permissions) {
+            findings.push({
+                severity: "high",
+                message: `Job '${jobName}' has no 'permissions:' block — defaults are read-only since Feb 2023.`,
+                fix: "Add explicit permissions for the GITHUB_TOKEN.",
+                fix_code: `permissions:\n  contents: read`,
+            });
+        }
+        // Missing timeout
+        if (!job["timeout-minutes"]) {
+            findings.push({
+                severity: "medium",
+                message: `Job '${jobName}' has no 'timeout-minutes' — default is 6 hours.`,
+                fix: "Add timeout-minutes to prevent runaway jobs.",
+                fix_code: `jobs:\n  ${jobName}:\n    timeout-minutes: 30`,
+            });
+        }
+        // Check steps
+        for (const step of job.steps ?? []) {
+            // Deprecated set-output
+            if (step.run?.includes("::set-output")) {
+                findings.push({
+                    severity: "high",
+                    message: `Step '${step.name ?? "unnamed"}' uses deprecated set-output command.`,
+                    fix: "Use $GITHUB_OUTPUT instead.",
+                    fix_code: 'echo "key=value" >> $GITHUB_OUTPUT',
+                    relatedError: "runner-environment-005",
+                });
+            }
+            // Deprecated set-env
+            if (step.run?.includes("::set-env")) {
+                findings.push({
+                    severity: "high",
+                    message: `Step '${step.name ?? "unnamed"}' uses deprecated set-env command.`,
+                    fix: "Use $GITHUB_ENV instead.",
+                    fix_code: 'echo "KEY=value" >> $GITHUB_ENV',
+                });
+            }
+            // Deprecated action versions
+            if (step.uses) {
+                // Node 16 actions
+                if (step.uses.match(/actions\/upload-artifact@v3/)) {
+                    findings.push({
+                        severity: "high",
+                        message: `Step uses actions/upload-artifact@v3 — v4 is current and uses a different backend.`,
+                        fix: "Upgrade to actions/upload-artifact@v4. Note: v3 and v4 artifacts are incompatible.",
+                        relatedError: "caching-artifacts-004",
+                    });
+                }
+                if (step.uses.match(/actions\/download-artifact@v3/)) {
+                    findings.push({
+                        severity: "high",
+                        message: `Step uses actions/download-artifact@v3 — v4 is current.`,
+                        fix: "Upgrade to actions/download-artifact@v4. Ensure upload and download versions match.",
+                    });
+                }
+            }
+            // if: with pipe scalar
+            if (step.if && typeof step.if === "string") {
+                if (step.if.trim().startsWith("|\n") || step.if.trim().startsWith("|")) {
+                    findings.push({
+                        severity: "medium",
+                        message: `Step '${step.name ?? "unnamed"}' if: condition uses pipe scalar — will always be true.`,
+                        fix: "Remove the pipe character. Write the condition on a single line.",
+                        relatedError: "yaml-syntax-007",
+                    });
+                }
+                // Secrets in if conditions
+                if (step.if.includes("secrets.")) {
+                    findings.push({
+                        severity: "medium",
+                        message: `Step '${step.name ?? "unnamed"}' uses secrets.* in if: condition — secrets context is not available in if:.`,
+                        fix: "Pass the secret to an env var first, then check the env var in the if: condition.",
+                        relatedError: "yaml-syntax-005",
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=yaml-parser.js.map

package/dist/utils/yaml-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-parser.js","sourceRoot":"","sources":["../../src/utils/yaml-parser.ts"],"names":[],"mappings":"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"}

package/errors/_schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Actions Debugger Error Entry",
+  "description": "Schema for GitHub Actions error database entries",
+  "type": "object",
+  "required": ["id", "title", "category", "severity", "patterns", "root_cause", "fix"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z-]+-\\d{3}$",
+      "description": "Unique ID: {category}-{number}"
+    },
+    "title": {
+      "type": "string",
+      "description": "Human-readable error title"
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "yaml-syntax",
+        "silent-failures",
+        "runner-environment",
+        "permissions-auth",
+        "caching-artifacts",
+        "triggers",
+        "concurrency-timing",
+        "known-unsolved"
+      ]
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["error", "warning", "silent-failure", "limitation"]
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "patterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["regex"],
+        "properties": {
+          "regex": { "type": "string" },
+          "flags": { "type": "string", "default": "i" }
+        }
+      }
+    },
+    "error_messages": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Exact error message strings for full-text search"
+    },
+    "root_cause": { "type": "string" },
+    "fix": { "type": "string" },
+    "fix_code": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "language": { "type": "string" },
+          "label": { "type": "string" },
+          "code": { "type": "string" }
+        }
+      }
+    },
+    "prevention": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "docs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "url": { "type": "string", "format": "uri" },
+          "label": { "type": "string" }
+        }
+      }
+    },
+    "source": {
+      "type": "object",
+      "properties": {
+        "article": { "type": "string", "format": "uri" },
+        "section": { "type": "string" }
+      }
+    }
+  }
+}

package/errors/caching-artifacts/cache-miss.yml

@@ -0,0 +1,56 @@
+id: caching-artifacts-001
+title: "Cache Miss Despite Recent Save"
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - artifacts
+  - restore-keys
+  - branch-scope
+  - performance
+patterns:
+  - regex: "Cache not found for input keys: .*"
+    flags: "i"
+  - regex: "Failed to restore: .*"
+    flags: "i"
+  - regex: "Received 429 response while trying to reserve cache"
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys"
+  - "Received 429 response while trying to reserve cache"
+root_cause: |
+  GitHub Actions caches are scoped by key, version, and branch. A cache saved on one branch
+  is not always visible from another branch, and a small key mismatch can force a full miss.
+  High-volume repositories can also hit cache service throttling, which makes cache restore
+  or save behavior look flaky.
+
+  This is especially confusing when a previous run clearly saved a cache but the next run
+  still reports a miss.
+fix: |
+  Design cache keys intentionally, add `restore-keys` for partial matches, and understand the
+  branch visibility rules. Prime important caches on the default branch and avoid creating an
+  overly specific key for data that should be shared more broadly.
+fix_code:
+  - language: yaml
+    label: "Use restore keys and stable cache key prefixes"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+prevention:
+  - "Keep cache keys stable enough to be reusable, but specific enough to avoid stale restores."
+  - "Use `restore-keys` for partial fallback instead of a single exact key."
+  - "Prime caches on the default branch for the widest reuse."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "Caching dependencies to speed up workflows"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Cache misses despite recent saves"

package/errors/caching-artifacts/upload-artifact-v4-breaking.yml

@@ -0,0 +1,67 @@
+id: caching-artifacts-004
+title: "upload-artifact v3 → v4 Breaking Changes"
+category: caching-artifacts
+severity: error
+tags:
+  - artifacts
+  - upload-artifact
+  - download-artifact
+  - v4
+  - compatibility
+patterns:
+  - regex: "Artifact not found for name: .*"
+    flags: "i"
+  - regex: "Unable to find any artifacts for the associated workflow"
+    flags: "i"
+  - regex: "The requested artifact was not found"
+    flags: "i"
+error_messages:
+  - "Artifact not found for name: build-output"
+  - "Unable to find any artifacts for the associated workflow"
+  - "The requested artifact was not found"
+root_cause: |
+  The v4 artifact actions use a different backend and behavior than v3. Mixing
+  `actions/upload-artifact@v3` with `actions/download-artifact@v4` can produce confusing
+  artifact-not-found failures even when the earlier upload step seemed successful.
+
+  The safest rule is to keep upload and download artifact actions on the same major version,
+  and preferably migrate both sides to v4 together.
+fix: |
+  Upgrade both upload and download steps to v4 in the same workflow or workflow chain.
+  Re-test artifact names exactly as written, because name mismatches compound the version
+  mismatch problem.
+fix_code:
+  - language: yaml
+    label: "Use matching artifact action versions"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+
+        consume:
+          runs-on: ubuntu-latest
+          needs: build
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+prevention:
+  - "Upgrade upload and download artifact actions together, not one side at a time."
+  - "Keep artifact names consistent and explicit across jobs."
+  - "Retest cross-workflow artifact usage after action major-version upgrades."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts"
+    label: "Store and share data with workflow artifacts"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Artifact v4 breaking changes"

package/errors/concurrency-timing/jobs-cancelled-unexpectedly.yml

@@ -0,0 +1,60 @@
+id: concurrency-timing-001
+title: "Jobs Cancelled Unexpectedly"
+category: concurrency-timing
+severity: warning
+tags:
+  - concurrency
+  - cancellation
+  - matrix
+  - timing
+  - branch-isolation
+patterns:
+  - regex: "Canceling since a higher priority waiting request for '.+' exists"
+    flags: "i"
+  - regex: "The workflow run was canceled because another workflow run with the same concurrency group was queued"
+    flags: "i"
+  - regex: "Operation was canceled\\."
+    flags: "i"
+error_messages:
+  - "Canceling since a higher priority waiting request for 'deploy' exists"
+  - "Operation was canceled."
+root_cause: |
+  Concurrency groups are global to the repository unless you scope them yourself. If every
+  branch uses the same group name, a push on one branch can cancel a run on a completely
+  different branch. Matrix jobs can make this harder to spot because only some legs appear to
+  vanish, even though the concurrency rule is what canceled them.
+
+  The workflow is behaving exactly as configured, but the group name is too broad.
+fix: |
+  Include branch or ref information in the concurrency group so only related runs cancel one
+  another. Keep `cancel-in-progress: true` only when you truly want a new run to replace the
+  older run for the same ref.
+fix_code:
+  - language: yaml
+    label: "Scope concurrency groups by workflow and ref"
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              node: [18, 20]
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Never use a bare group like `deploy` or `ci` unless cross-branch cancellation is intentional."
+  - "Include `${{ github.ref }}` or `${{ github.head_ref || github.ref }}` in concurrency groups."
+  - "Review concurrency settings any time runs are mysteriously disappearing."
+docs:
+  - url: "https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency"
+    label: "Control the concurrency of workflows and jobs"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Unexpected cancellations from concurrency"

package/errors/known-unsolved/no-step-retry.yml

@@ -0,0 +1,53 @@
+id: known-unsolved-002
+title: "No Step-Level Retry"
+category: known-unsolved
+severity: limitation
+tags:
+  - retry
+  - steps
+  - limitation
+  - flakiness
+  - resilience
+patterns:
+  - regex: "Process completed with exit code [0-9]+"
+    flags: "i"
+  - regex: 'curl: \(28\) Operation timed out'
+    flags: "i"
+  - regex: "npm ERR! network"
+    flags: "i"
+error_messages:
+  - "Process completed with exit code 1"
+  - "curl: (28) Operation timed out"
+root_cause: |
+  GitHub Actions can rerun jobs and whole workflows, but it does not provide native retry
+  semantics for a single arbitrary step. That means flaky network calls, package registry
+  hiccups, and transient shell commands fail the step immediately unless you build a retry
+  wrapper yourself.
+
+  This is a platform limitation rather than a YAML mistake.
+fix: |
+  Wrap the flaky command in a retry helper or use a marketplace action such as
+  `nick-fields/retry` when retry semantics are needed for one step only.
+fix_code:
+  - language: yaml
+    label: "Retry a flaky step with nick-fields/retry"
+    code: |
+      - name: Retry npm install
+        uses: nick-fields/retry@v3
+        with:
+          timeout_minutes: 15
+          max_attempts: 3
+          retry_wait_seconds: 20
+          command: npm ci
+prevention:
+  - "Assume external network calls are flaky and wrap them in retries if they are business-critical."
+  - "Prefer idempotent commands for steps that may need retry wrappers."
+  - "Document step-level retry strategy because GitHub Actions does not provide it natively."
+docs:
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "Re-running workflows and jobs"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Platform limitations: no step-level retry"

package/errors/permissions-auth/github-token-403.yml

@@ -0,0 +1,64 @@
+id: permissions-auth-001
+title: "GITHUB_TOKEN Permission Denied (403)"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - permissions
+  - 403
+  - auth
+  - push
+patterns:
+  - regex: "remote: Permission to .+\\.git denied to github-actions\\[bot\\]"
+    flags: "i"
+  - regex: "fatal: unable to access 'https://github\\.com/.+': The requested URL returned error: 403"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "remote: Permission to org/repo.git denied to github-actions[bot]."
+  - "fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
+  - "Resource not accessible by integration"
+root_cause: |
+  Since February 2023, newly created repositories default `GITHUB_TOKEN` to read-only
+  permissions in many cases. A workflow that tries to push commits, create releases, or
+  modify pull requests without an explicit `permissions:` block can suddenly fail with 403
+  or integration access errors.
+
+  The token exists, but it does not have the scopes the job assumed it had.
+fix: |
+  Add the minimum required `permissions:` block at the workflow or job level. For pushes,
+  tags, or release creation, that usually means `contents: write`. For pull request comments
+  or checks, grant the specific write permission those APIs require.
+fix_code:
+  - language: yaml
+    label: "Grant explicit write permissions to GITHUB_TOKEN"
+    code: |
+      name: Release
+
+      on:
+        push:
+          branches:
+            - main
+
+      permissions:
+        contents: write
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: git push origin HEAD:main
+prevention:
+  - "Assume `GITHUB_TOKEN` is read-only unless you explicitly grant the needed permission."
+  - "Set least-privilege `permissions:` blocks on every workflow instead of relying on defaults."
+  - "Match API usage to the smallest write scope required."
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
+    label: "Automatic token authentication"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions"
+    label: "permissions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "GITHUB_TOKEN 403 and read-only defaults"

package/errors/permissions-auth/oidc-aws-failure.yml

@@ -0,0 +1,85 @@
+id: permissions-auth-002
+title: "OIDC Federation Failures with AWS"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - aws
+  - sts
+  - iam
+  - federation
+patterns:
+  - regex: "Not authorized to perform sts:AssumeRoleWithWebIdentity"
+    flags: "i"
+  - regex: "InvalidIdentityToken"
+    flags: "i"
+  - regex: "No OpenIDConnect provider found in your account"
+    flags: "i"
+  - regex: "audience.*sts\\.amazonaws\\.com"
+    flags: "i"
+error_messages:
+  - "Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "InvalidIdentityToken"
+  - "No OpenIDConnect provider found in your account"
+root_cause: |
+  GitHub's OIDC token must match the AWS IAM trust policy exactly. Failures usually come
+  from one of three mismatches: the workflow is missing `id-token: write`, the IAM role
+  trust policy expects the wrong `aud` value, or the `sub` claim does not match the repo,
+  branch, environment, or tag that is actually requesting the token.
+
+  Any one of those mismatches is enough for AWS STS to reject the federation request.
+fix: |
+  Grant `id-token: write`, verify the GitHub OIDC provider exists in AWS, and align the IAM
+  trust policy's `aud` and `sub` conditions with the workflow that is assuming the role.
+fix_code:
+  - language: yaml
+    label: "Grant OIDC permission in the workflow"
+    code: |
+      permissions:
+        id-token: write
+        contents: read
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
+                aws-region: us-east-1
+  - language: json
+    label: "Example AWS trust policy for GitHub OIDC"
+    code: |
+      {
+        "Version": "2012-10-17",
+        "Statement": [
+          {
+            "Effect": "Allow",
+            "Principal": {
+              "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
+            },
+            "Action": "sts:AssumeRoleWithWebIdentity",
+            "Condition": {
+              "StringEquals": {
+                "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
+              },
+              "StringLike": {
+                "token.actions.githubusercontent.com:sub": "repo:owner/repo:ref:refs/heads/main"
+              }
+            }
+          }
+        ]
+      }
+prevention:
+  - "Treat the OIDC `aud` and `sub` claims as part of your contract and document them with the role."
+  - "Test branch, tag, and environment-specific subjects before rolling OIDC out broadly."
+  - "Always include `id-token: write` when using cloud federation from GitHub Actions."
+docs:
+  - url: "https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services"
+    label: "Configuring OpenID Connect in Amazon Web Services"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect"
+    label: "About security hardening with OpenID Connect"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "OIDC federation with AWS"