@htekdev/actions-debugger 1.0.0 → 1.0.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Hector Flores (htekdev)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Hector Flores (htekdev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,108 +1,108 @@
-# @htekdev/actions-debugger
-
-[![CI](https://github.com/htekdev/actions-debugger/actions/workflows/ci.yml/badge.svg)](https://github.com/htekdev/actions-debugger/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/@htekdev/actions-debugger)](https://www.npmjs.com/package/@htekdev/actions-debugger)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-> 65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.
-
-**Stop debugging the same CI failures over and over.** This repo packages 65+ real-world GitHub Actions error scenarios — with regex-matchable patterns, root causes, and copy-paste fixes — into formats that both humans and AI agents can consume.
-
-## What's Inside
-
-```
-errors/              → Structured YAML error database (65+ entries)
-src/                 → MCP server (TypeScript + @modelcontextprotocol/sdk)
-.github/skills/      → Copilot CLI skills for CI debugging
-.github/agents/      → Copilot agent definition
-```
-
-## Quick Start
-
-### As an MCP Server (Claude Desktop, Copilot CLI, Cursor, etc.)
-
-```bash
-npx @htekdev/actions-debugger
-```
-
-Add to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "actions-debugger": {
-      "command": "npx",
-      "args": ["@htekdev/actions-debugger"]
-    }
-  }
-}
-```
-
-**Client config locations:**
-- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
-- **Cursor**: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
-- **VS Code (Copilot Chat)**: `.vscode/mcp.json`
-- **Copilot CLI**: `.github/mcp.json` (repo-level)
-- **Windsurf**: `~/.codeium/windsurf/mcp_config.json`
-
-### As a Copilot CLI Skill (No MCP Required)
-
-Copy `.github/skills/actions-debugging/SKILL.md` to your repo's `.github/skills/` directory. Reference it in your agent:
-
-```markdown
-> **Skill reference:** For CI debugging, use the `actions-debugging` skill.
-```
-
-### Programmatic (npm Package)
-
-```typescript
-import { loadErrorDatabase, lookupError, diagnoseWorkflow } from "@htekdev/actions-debugger";
-
-const db = await loadErrorDatabase();
-
-// Lookup by error message
-const matches = lookupError(db, "Permission to org/repo.git denied");
-console.log(matches[0].fix);
-
-// Analyze a workflow
-const issues = diagnoseWorkflow(db, workflowYamlString);
-```
-
-## MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `lookup_error` | Match an error message against 65+ known issues |
-| `diagnose_workflow` | Static analysis of workflow YAML for common mistakes |
-| `suggest_fix` | Contextual fix suggestions from error context |
-| `search_errors` | Full-text search by keyword, category, severity |
-| `list_categories` | Browse error categories with counts |
-
-## Error Categories
-
-| Category | Description |
-|----------|-------------|
-| `yaml-syntax` | YAML validation, key typos, expression errors |
-| `silent-failures` | No error shown, but wrong behavior |
-| `runner-environment` | Runner issues, disk space, Docker, PATH |
-| `permissions-auth` | GITHUB_TOKEN, OIDC, secrets, 403s |
-| `caching-artifacts` | Cache misses, artifact v4 changes, corruption |
-| `triggers` | Workflow not running, cron issues, dispatch |
-| `concurrency-timing` | Job cancellation, matrix, timeouts |
-| `known-unsolved` | Platform limitations with no fix |
-
-## Contributing
-
-See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for how to add new error entries. It's easy:
-
-1. Create a YAML file in the appropriate `errors/{category}/` directory
-2. Follow the schema in `errors/_schema.json`
-3. Open a PR — CI validates your entry automatically
-
-## Source
-
-All error scenarios sourced from: **[The Definitive GitHub Actions Debugging Guide](https://htek.dev/articles/github-actions-debugging-guide)**
-
-## License
-
-MIT — [Hector Flores](https://htek.dev) (htekdev)
+# @htekdev/actions-debugger
+
+[![CI](https://github.com/htekdev/actions-debugger/actions/workflows/ci.yml/badge.svg)](https://github.com/htekdev/actions-debugger/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@htekdev/actions-debugger)](https://www.npmjs.com/package/@htekdev/actions-debugger)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> 65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.
+
+**Stop debugging the same CI failures over and over.** This repo packages 65+ real-world GitHub Actions error scenarios — with regex-matchable patterns, root causes, and copy-paste fixes — into formats that both humans and AI agents can consume.
+
+## What's Inside
+
+```
+errors/              → Structured YAML error database (65+ entries)
+src/                 → MCP server (TypeScript + @modelcontextprotocol/sdk)
+.github/skills/      → Copilot CLI skills for CI debugging
+.github/agents/      → Copilot agent definition
+```
+
+## Quick Start
+
+### As an MCP Server (Claude Desktop, Copilot CLI, Cursor, etc.)
+
+```bash
+npx @htekdev/actions-debugger
+```
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "actions-debugger": {
+      "command": "npx",
+      "args": ["@htekdev/actions-debugger"]
+    }
+  }
+}
+```
+
+**Client config locations:**
+- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- **Cursor**: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
+- **VS Code (Copilot Chat)**: `.vscode/mcp.json`
+- **Copilot CLI**: `.github/mcp.json` (repo-level)
+- **Windsurf**: `~/.codeium/windsurf/mcp_config.json`
+
+### As a Copilot CLI Skill (No MCP Required)
+
+Copy `.github/skills/actions-debugging/SKILL.md` to your repo's `.github/skills/` directory. Reference it in your agent:
+
+```markdown
+> **Skill reference:** For CI debugging, use the `actions-debugging` skill.
+```
+
+### Programmatic (npm Package)
+
+```typescript
+import { loadErrorDatabase, lookupError, diagnoseWorkflow } from "@htekdev/actions-debugger";
+
+const db = await loadErrorDatabase();
+
+// Lookup by error message
+const matches = lookupError(db, "Permission to org/repo.git denied");
+console.log(matches[0].fix);
+
+// Analyze a workflow
+const issues = diagnoseWorkflow(db, workflowYamlString);
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `lookup_error` | Match an error message against 65+ known issues |
+| `diagnose_workflow` | Static analysis of workflow YAML for common mistakes |
+| `suggest_fix` | Contextual fix suggestions from error context |
+| `search_errors` | Full-text search by keyword, category, severity |
+| `list_categories` | Browse error categories with counts |
+
+## Error Categories
+
+| Category | Description |
+|----------|-------------|
+| `yaml-syntax` | YAML validation, key typos, expression errors |
+| `silent-failures` | No error shown, but wrong behavior |
+| `runner-environment` | Runner issues, disk space, Docker, PATH |
+| `permissions-auth` | GITHUB_TOKEN, OIDC, secrets, 403s |
+| `caching-artifacts` | Cache misses, artifact v4 changes, corruption |
+| `triggers` | Workflow not running, cron issues, dispatch |
+| `concurrency-timing` | Job cancellation, matrix, timeouts |
+| `known-unsolved` | Platform limitations with no fix |
+
+## Contributing
+
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for how to add new error entries. It's easy:
+
+1. Create a YAML file in the appropriate `errors/{category}/` directory
+2. Follow the schema in `errors/_schema.json`
+3. Open a PR — CI validates your entry automatically
+
+## Source
+
+All error scenarios sourced from: **[The Definitive GitHub Actions Debugging Guide](https://htek.dev/articles/github-actions-debugging-guide)**
+
+## License
+
+MIT — [Hector Flores](https://htek.dev) (htekdev)

package/errors/_schema.json

@@ -1,89 +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" }
-      }
-    }
-  }
-}
+{
+  "$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/artifact-storage-quota-exceeded.yml

@@ -0,0 +1,118 @@
+id: caching-artifacts-006
+title: "Artifact Upload Fails: Storage Quota Exceeded or 413 Request Too Large"
+category: caching-artifacts
+severity: error
+tags:
+  - artifacts
+  - upload-artifact
+  - storage-quota
+  - 413
+  - size-limit
+patterns:
+  - regex: "Artifact storage quota has been hit"
+    flags: "i"
+  - regex: "Unable to upload any new artifacts"
+    flags: "i"
+  - regex: "413 Request Entity Too Large"
+    flags: "i"
+  - regex: "Create Artifact Container failed"
+    flags: "i"
+  - regex: "No space left on device"
+    flags: "i"
+  - regex: "Status Code: 500 Internal Server Error"
+    flags: "i"
+error_messages:
+  - "Create Artifact Container failed: Artifact storage quota has been hit. Unable to upload any new artifacts"
+  - "413 Request Entity Too Large"
+  - "Unexpected response. Unable to upload chunk to pipelines.actions.githubusercontent.com... Status Code: 500 Internal Server Error"
+  - "Unhandled exception. System.IO.IOException: No space left on device"
+root_cause: |
+  Artifact upload failures in GitHub Actions have three distinct root causes:
+
+  1. **Repository/org storage quota exceeded** (`Artifact storage quota has been hit`):
+     GitHub includes a limited amount of artifact storage per plan (e.g., 500 MB for
+     free, 2 GB for Teams, 50 GB for Enterprise). When the cumulative size of all stored
+     artifacts crosses this limit, the backend refuses to create new artifact containers
+     and every new upload fails immediately.
+
+  2. **Upload chunk too large / server error** (`413 Request Entity Too Large` or `500`):
+     GitHub Actions uploads artifacts in chunks. If a single artifact or its chunk
+     exceeds the backend's per-request limits, the server returns 413 or 500. This
+     typically happens with artifacts larger than ~2 GB in a single upload call.
+
+  3. **Runner disk space exhausted** (`No space left on device`):
+     The hosted runner's ephemeral disk (typically ~14 GB on ubuntu-latest) fills up
+     during artifact packaging/compression. This is common when building large binaries,
+     Docker images, or test results that accumulate over a long job.
+
+  Old or unretained artifacts accumulate silently — developers rarely clean up artifacts
+  manually, so quota errors often appear suddenly after months of builds.
+fix: |
+  **For storage quota errors:**
+  - Delete old artifacts via the GitHub UI (Actions → Artifacts) or the REST API.
+  - Lower artifact retention days using the `retention-days` parameter on upload-artifact
+    so old artifacts expire automatically.
+  - If quota is still consistently exceeded, upgrade the plan or add Actions storage.
+
+  **For 413 / chunk errors:**
+  - Split the artifact into smaller logical pieces using multiple upload-artifact steps.
+  - Compress before uploading (zip/tar the directory first) to reduce payload size.
+
+  **For runner disk exhaustion:**
+  - Use a self-hosted runner with more disk, or add a disk-cleanup step early in the job.
+  - Upload intermediate artifacts (e.g., build outputs) before running additional steps
+    that generate more disk usage.
+fix_code:
+  - language: yaml
+    label: "Set retention to auto-expire artifacts and avoid quota buildup"
+    code: |
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+          retention-days: 7   # Delete after 7 days; default is 90
+  - language: yaml
+    label: "Split large artifacts into logical pieces"
+    code: |
+      - uses: actions/upload-artifact@v4
+        with:
+          name: binaries-linux
+          path: dist/linux/
+          retention-days: 3
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: binaries-windows
+          path: dist/windows/
+          retention-days: 3
+  - language: yaml
+    label: "Free up runner disk space before large uploads"
+    code: |
+      - name: Free disk space
+        run: |
+          df -h
+          sudo apt-get clean
+          sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc
+          df -h
+  - language: yaml
+    label: "Delete all artifacts older than N days via API"
+    code: |
+      - name: Delete old artifacts
+        uses: c-hive/gha-remove-artifacts@v1
+        with:
+          age: '1 week'
+          skip-recent: 3
+prevention:
+  - "Always set `retention-days` on upload-artifact — the 90-day default accumulates quota quickly in active repos."
+  - "Monitor Actions storage usage in your org settings (Settings → Billing → Actions) before you hit the limit."
+  - "Add a disk-space check step (`df -h`) at the start of jobs that produce large build outputs."
+  - "Split artifacts by purpose (binaries, test results, logs) so each part stays below chunk limits."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "Storing and sharing data from a workflow (artifacts)"
+  - url: "https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions#included-storage-and-minutes"
+    label: "About billing for GitHub Actions — included storage"
+  - url: "https://stackoverflow.com/questions/70730786/github-actions-create-artifact-container-failed-artifact-storage-quota-has-b"
+    label: "Stack Overflow: Artifact storage quota has been hit"
+  - url: "https://github.com/actions/upload-artifact/issues/9"
+    label: "upload-artifact#9 — chunk upload failures and size limits"