@htekdev/actions-debugger 1.0.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +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)

package/dist/db/loader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * YAML error database loader.
+ * Reads all YAML files from errors/ directory and builds an in-memory database.
+ */
+import type { ErrorDatabase } from "./types.js";
+/**
+ * Load the error database from YAML files.
+ * @param errorsDir - Optional custom path to errors directory
+ * @returns Populated ErrorDatabase
+ */
+export declare function loadErrorDatabase(errorsDir?: string): Promise<ErrorDatabase>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/db/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/db/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAc,aAAa,EAAiB,MAAM,YAAY,CAAC;AAE3E;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA2ClF"}

package/dist/db/loader.js

@@ -0,0 +1,76 @@
+/**
+ * YAML error database loader.
+ * Reads all YAML files from errors/ directory and builds an in-memory database.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { globSync } from "glob";
+import yaml from "js-yaml";
+/**
+ * Load the error database from YAML files.
+ * @param errorsDir - Optional custom path to errors directory
+ * @returns Populated ErrorDatabase
+ */
+export async function loadErrorDatabase(errorsDir) {
+    const dir = errorsDir ?? findErrorsDir();
+    if (!existsSync(dir)) {
+        throw new Error(`Errors directory not found: ${dir}`);
+    }
+    const yamlFiles = globSync("**/*.yml", { cwd: dir, absolute: true });
+    const entries = [];
+    for (const file of yamlFiles) {
+        // Skip schema file
+        if (basename(file) === "_schema.json")
+            continue;
+        try {
+            const content = readFileSync(file, "utf-8");
+            const entry = yaml.load(content);
+            // Basic validation
+            if (!entry.id || !entry.title || !entry.category) {
+                console.warn(`Skipping invalid entry: ${file} (missing required fields)`);
+                continue;
+            }
+            entries.push(entry);
+        }
+        catch (err) {
+            console.warn(`Failed to parse ${file}: ${err.message}`);
+        }
+    }
+    // Build indexes
+    const categories = new Map();
+    const byId = new Map();
+    for (const entry of entries) {
+        byId.set(entry.id, entry);
+        const catEntries = categories.get(entry.category) ?? [];
+        catEntries.push(entry);
+        categories.set(entry.category, catEntries);
+    }
+    return { entries, categories, byId };
+}
+/**
+ * Find the errors directory relative to this file or the package root.
+ */
+function findErrorsDir() {
+    // When running from source (src/db/loader.ts)
+    const thisFile = fileURLToPath(import.meta.url);
+    const srcDir = dirname(dirname(thisFile));
+    const rootDir = dirname(srcDir);
+    // Check for errors/ at package root
+    const candidate = resolve(rootDir, "errors");
+    if (existsSync(candidate)) {
+        return candidate;
+    }
+    // When installed as npm package, errors/ is in the package
+    const npmCandidate = resolve(rootDir, "..", "errors");
+    if (existsSync(npmCandidate)) {
+        return npmCandidate;
+    }
+    // Fallback: look relative to cwd
+    const cwdCandidate = resolve(process.cwd(), "errors");
+    if (existsSync(cwdCandidate)) {
+        return cwdCandidate;
+    }
+    throw new Error("Could not find errors directory. Set ACTIONS_DEBUGGER_ERRORS_DIR or pass errorsDir to loadErrorDatabase().");
+}
+//# sourceMappingURL=loader.js.map

package/dist/db/loader.js.map

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

package/dist/db/search.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pattern matching engine for error lookup.
+ * Matches error messages against regex patterns from the error database.
+ */
+import type { ErrorDatabase, SearchResult } from "./types.js";
+/**
+ * Match an error message against all patterns in the database.
+ * Returns results sorted by match confidence.
+ */
+export declare function lookupByPattern(db: ErrorDatabase, errorMessage: string, maxResults?: number): SearchResult[];
+/**
+ * Search the database by keyword across title, root_cause, fix, and tags.
+ */
+export declare function searchByKeyword(db: ErrorDatabase, query: string, options?: {
+    category?: string;
+    severity?: string;
+    maxResults?: number;
+}): SearchResult[];
+//# sourceMappingURL=search.d.ts.map

package/dist/db/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/db/search.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAc,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK1E;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,aAAa,EACjB,YAAY,EAAE,MAAM,EACpB,UAAU,GAAE,MAAU,GACrB,YAAY,EAAE,CAehB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,YAAY,EAAE,CAwDhB"}

package/dist/db/search.js

@@ -0,0 +1,123 @@
+/**
+ * Pattern matching engine for error lookup.
+ * Matches error messages against regex patterns from the error database.
+ */
+/** Maximum input length to match against (prevent ReDoS on huge logs) */
+const MAX_INPUT_LENGTH = 10_000;
+/**
+ * Match an error message against all patterns in the database.
+ * Returns results sorted by match confidence.
+ */
+export function lookupByPattern(db, errorMessage, maxResults = 3) {
+    // Truncate input for safety
+    const input = errorMessage.slice(0, MAX_INPUT_LENGTH);
+    const results = [];
+    for (const entry of db.entries) {
+        const score = matchEntry(entry, input);
+        if (score > 0) {
+            results.push({ entry, score, matchType: score >= 100 ? "regex" : score >= 50 ? "exact" : "fuzzy" });
+        }
+    }
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, maxResults);
+}
+/**
+ * Search the database by keyword across title, root_cause, fix, and tags.
+ */
+export function searchByKeyword(db, query, options) {
+    const { category, severity, maxResults = 10 } = options ?? {};
+    const queryLower = query.toLowerCase();
+    const queryTerms = queryLower.split(/\s+/).filter(t => t.length > 1);
+    const results = [];
+    for (const entry of db.entries) {
+        // Apply filters
+        if (category && entry.category !== category)
+            continue;
+        if (severity && entry.severity !== severity)
+            continue;
+        let score = 0;
+        // Title match (highest weight)
+        const titleLower = entry.title.toLowerCase();
+        if (titleLower.includes(queryLower)) {
+            score += 100;
+        }
+        else {
+            for (const term of queryTerms) {
+                if (titleLower.includes(term))
+                    score += 30;
+            }
+        }
+        // Tag match
+        for (const tag of entry.tags ?? []) {
+            const tagStr = String(tag).toLowerCase();
+            if (queryTerms.includes(tagStr))
+                score += 25;
+        }
+        // Root cause match
+        const rootCauseLower = entry.root_cause.toLowerCase();
+        for (const term of queryTerms) {
+            if (rootCauseLower.includes(term))
+                score += 15;
+        }
+        // Fix match
+        const fixLower = entry.fix.toLowerCase();
+        for (const term of queryTerms) {
+            if (fixLower.includes(term))
+                score += 10;
+        }
+        // Error messages match
+        for (const msg of entry.error_messages ?? []) {
+            if (msg.toLowerCase().includes(queryLower)) {
+                score += 50;
+                break;
+            }
+        }
+        if (score > 0) {
+            results.push({ entry, score, matchType: "keyword" });
+        }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, maxResults);
+}
+/**
+ * Score an entry against an error message input.
+ */
+function matchEntry(entry, input) {
+    let bestScore = 0;
+    // 1. Regex pattern matching (highest confidence)
+    for (const pattern of entry.patterns ?? []) {
+        try {
+            const flags = pattern.flags ?? "i";
+            const re = new RegExp(pattern.regex, flags);
+            if (re.test(input)) {
+                bestScore = Math.max(bestScore, 100);
+            }
+        }
+        catch {
+            // Invalid regex — skip
+            continue;
+        }
+    }
+    // 2. Exact error message matching
+    for (const msg of entry.error_messages ?? []) {
+        if (input.includes(msg)) {
+            bestScore = Math.max(bestScore, 80);
+        }
+        // Partial match
+        const msgLower = msg.toLowerCase();
+        const inputLower = input.toLowerCase();
+        if (inputLower.includes(msgLower)) {
+            bestScore = Math.max(bestScore, 60);
+        }
+    }
+    // 3. Title keyword matching (lowest confidence)
+    const inputLower = input.toLowerCase();
+    const titleWords = entry.title.toLowerCase().split(/\s+/);
+    const matchingWords = titleWords.filter(w => w.length > 3 && inputLower.includes(w));
+    if (matchingWords.length >= 2) {
+        bestScore = Math.max(bestScore, 20 + matchingWords.length * 5);
+    }
+    return bestScore;
+}
+//# sourceMappingURL=search.js.map

package/dist/db/search.js.map

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

package/dist/db/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * TypeScript interfaces for the GitHub Actions error database.
+ */
+export interface ErrorPattern {
+    regex: string;
+    flags?: string;
+}
+export interface FixCode {
+    language: string;
+    label: string;
+    code: string;
+}
+export interface DocLink {
+    url: string;
+    label: string;
+}
+export interface ErrorSource {
+    article: string;
+    section: string;
+}
+export interface ErrorEntry {
+    id: string;
+    title: string;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    tags: string[];
+    patterns: ErrorPattern[];
+    error_messages?: string[];
+    root_cause: string;
+    fix: string;
+    fix_code?: FixCode[];
+    prevention?: string[];
+    docs?: DocLink[];
+    source?: ErrorSource;
+}
+export type ErrorCategory = "yaml-syntax" | "silent-failures" | "runner-environment" | "permissions-auth" | "caching-artifacts" | "triggers" | "concurrency-timing" | "known-unsolved";
+export type ErrorSeverity = "error" | "warning" | "silent-failure" | "limitation";
+export interface ErrorDatabase {
+    entries: ErrorEntry[];
+    categories: Map<ErrorCategory, ErrorEntry[]>;
+    byId: Map<string, ErrorEntry>;
+}
+export interface SearchResult {
+    entry: ErrorEntry;
+    score: number;
+    matchType: "regex" | "exact" | "fuzzy" | "keyword";
+}
+export interface DiagnosticFinding {
+    severity: "critical" | "high" | "medium" | "low";
+    message: string;
+    line?: number;
+    fix: string;
+    fix_code?: string;
+    relatedError?: string;
+}
+export interface CategoryInfo {
+    name: ErrorCategory;
+    count: number;
+    severities: Record<ErrorSeverity, number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/db/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/db/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,mBAAmB,GACnB,UAAU,GACV,oBAAoB,GACpB,gBAAgB,CAAC;AAErB,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,gBAAgB,GAAG,YAAY,CAAC;AAElF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,UAAU,EAAE,GAAG,CAAC,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IAC7C,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;CAC3C"}

package/dist/db/types.js

@@ -0,0 +1,5 @@
+/**
+ * TypeScript interfaces for the GitHub Actions error database.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/db/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/db/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * @htekdev/actions-debugger — MCP server entry point.
+ *
+ * 65+ real GitHub Actions errors, queryable by agents.
+ * Runs as a stdio MCP server for Claude Desktop, Copilot CLI, Cursor, etc.
+ *
+ * Usage:
+ *   npx @htekdev/actions-debugger
+ *
+ * Source: https://htek.dev/articles/github-actions-debugging-guide
+ */
+export { loadErrorDatabase } from "./db/loader.js";
+export { lookupError } from "./tools/lookup-error.js";
+export { diagnoseWorkflow } from "./tools/diagnose-workflow.js";
+export { suggestFix } from "./tools/suggest-fix.js";
+export { listCategories } from "./tools/list-categories.js";
+export { searchErrors } from "./tools/search-errors.js";
+export type { ErrorEntry, ErrorDatabase, ErrorCategory, ErrorSeverity, SearchResult, DiagnosticFinding, CategoryInfo, } from "./db/types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG;AAQH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EACV,UAAU,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * @htekdev/actions-debugger — MCP server entry point.
+ *
+ * 65+ real GitHub Actions errors, queryable by agents.
+ * Runs as a stdio MCP server for Claude Desktop, Copilot CLI, Cursor, etc.
+ *
+ * Usage:
+ *   npx @htekdev/actions-debugger
+ *
+ * Source: https://htek.dev/articles/github-actions-debugging-guide
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadErrorDatabase } from "./db/loader.js";
+import { registerTools } from "./server.js";
+// Re-export programmatic API
+export { loadErrorDatabase } from "./db/loader.js";
+export { lookupError } from "./tools/lookup-error.js";
+export { diagnoseWorkflow } from "./tools/diagnose-workflow.js";
+export { suggestFix } from "./tools/suggest-fix.js";
+export { listCategories } from "./tools/list-categories.js";
+export { searchErrors } from "./tools/search-errors.js";
+/**
+ * Start the MCP server if running as CLI.
+ */
+async function main() {
+    const db = await loadErrorDatabase();
+    const server = new Server({ name: "actions-debugger", version: "1.0.0" }, { capabilities: { tools: {} } });
+    registerTools(server, db);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// Only start server when running as CLI (not when imported as library)
+const isMainModule = process.argv[1] &&
+    (process.argv[1].endsWith("index.js") ||
+        process.argv[1].endsWith("actions-debugger"));
+if (isMainModule) {
+    main().catch((err) => {
+        console.error("Fatal error:", err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,6BAA6B;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAWxD;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,GAAG,MAAM,iBAAiB,EAAE,CAAC;IAErC,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC9C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAE1B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,uEAAuE;AACvE,MAAM,YAAY,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACf,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAElD,IAAI,YAAY,EAAE,CAAC;IACjB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MCP Server setup — registers all tools with the MCP server.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { ErrorDatabase } from "./db/types.js";
+/**
+ * Register all tools with the MCP server.
+ */
+export declare function registerTools(server: Server, db: ErrorDatabase): void;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,eAAe,CAAC;AAiHlE;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAqErE"}