explain-my-error 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial production-ready CLI for explaining programming errors with Groq.
+- Interactive input mode, inline argument mode, and piped input support.
+- Open Agent Skill definition in `skills/SKILL.md`.
+- Test suite with Vitest for CLI and command flows.
+- Production build pipeline using tsup + Biome + TypeScript checks.
+- GitHub Actions CI workflow for automated quality checks.
+

package/README.md

@@ -0,0 +1,116 @@
+# explain-my-error
+
+![explain-my-error CLI screenshot](./cli-screenshot.svg)
+
+Turn confusing programming errors into clear fixes directly in your terminal.
+
+`explain-my-error` returns:
+
+- A plain-English explanation
+- Common root causes
+- A practical fix
+- A code example
+- An ELI5 summary
+
+Alias included: `eme`
+
+## Install
+
+Install in a project:
+
+```bash
+npm i explain-my-error
+```
+
+Install globally (recommended for CLI usage from anywhere):
+
+```bash
+npm i -g explain-my-error
+```
+
+## Usage
+
+### Interactive mode
+
+```bash
+explain-my-error
+```
+
+```bash
+eme
+```
+
+### Inline message
+
+```bash
+explain-my-error explain "TypeError: Cannot read property 'map' of undefined"
+```
+
+```bash
+eme explain "ReferenceError: x is not defined"
+```
+
+### Piped input
+
+```bash
+cat error.txt | explain-my-error
+```
+
+```bash
+npm run build 2>&1 | eme
+```
+
+## Command reference
+
+```bash
+explain-my-error [command]
+```
+
+Commands:
+
+- `explain [error...]` Explain a programming error
+- `--help` Show CLI help
+- `--version` Show CLI version
+
+
+## Example output
+
+```text
+========================================================================
+| EXPLAIN MY ERROR                                                     |
+| AI powered debugging for humans                                      |
+========================================================================
+
+ERROR: TypeError: Cannot read property 'map' of undefined
+
+------------------------------------------------------------------------
+EXPLANATION
+This happens when .map() is called on a variable that is undefined.
+------------------------------------------------------------------------
+
+------------------------------------------------------------------------
+COMMON CAUSES
+1. API data not loaded
+2. State not initialized
+3. Incorrect variable reference
+------------------------------------------------------------------------
+
+FIX
+Ensure the array exists before calling map.
+
+------------------------------------------------------------------------
+CODE EXAMPLE
+const items = data?.items ?? [];
+items.map(...)
+------------------------------------------------------------------------
+
+------------------------------------------------------------------------
+ELI5
+Your code expected a box of toys (an array), but the toy box was empty.
+------------------------------------------------------------------------
+```
+
+## Open Agent Skill
+
+- Skill spec: `skills/SKILL.md`
+- Skill function: `runExplainErrorSkill(input)`

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+
+// src/cli-entry.ts
+import "dotenv/config";
+
+// src/cli.ts
+import { createInterface } from "readline/promises";
+import { Command } from "commander";
+import pc3 from "picocolors";
+
+// src/commands/explain.ts
+import ora from "ora";
+
+// src/services/ai.ts
+import axios from "axios";
+
+// src/types/error.ts
+import { z } from "zod";
+var explainedErrorSchema = z.object({
+  title: z.string().min(1),
+  explanation: z.string().min(1),
+  common_causes: z.array(z.string().min(1)).min(1),
+  fix: z.string().min(1),
+  code_example: z.string().min(1),
+  eli5: z.string().min(1)
+});
+
+// src/services/ai.ts
+var GROQ_API_URL = "https://api.groq.com/openai/v1/chat/completions";
+var PRIMARY_GROQ_MODEL = "llama3-70b-8192";
+var FALLBACK_GROQ_MODEL = process.env.GROQ_FALLBACK_MODEL ?? "llama-3.3-70b-versatile";
+function extractJson(content) {
+  const trimmed = content.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    const match = trimmed.match(/\{[\s\S]*\}/);
+    if (!match) {
+      throw new Error("AI did not return valid JSON.");
+    }
+    return JSON.parse(match[0]);
+  }
+}
+function stringifyField(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value == null) {
+    return "";
+  }
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+function normalizeResponseShape(payload) {
+  if (!payload || typeof payload !== "object") {
+    return payload;
+  }
+  const data = payload;
+  const rawCauses = data.common_causes;
+  const commonCauses = Array.isArray(rawCauses) ? rawCauses.map((item) => stringifyField(item)).filter(Boolean) : stringifyField(rawCauses).split(/\n|,/).map((item) => item.trim()).filter(Boolean);
+  return {
+    title: stringifyField(data.title),
+    explanation: stringifyField(data.explanation),
+    common_causes: commonCauses,
+    fix: stringifyField(data.fix),
+    code_example: stringifyField(data.code_example),
+    eli5: stringifyField(data.eli5)
+  };
+}
+async function explainErrorWithAI(errorMessage) {
+  const apiKey = process.env.GROQ_API_KEY;
+  if (!apiKey) {
+    throw new Error("Missing GROQ_API_KEY environment variable.");
+  }
+  const prompt = "You are a senior software engineer. Explain the programming error and return JSON with fields: title, explanation, common_causes, fix, code_example, eli5.";
+  const requestBody = {
+    messages: [
+      { role: "system", content: prompt },
+      {
+        role: "user",
+        content: `Error message:
+${errorMessage}
+
+Return strict JSON only.`
+      }
+    ],
+    temperature: 0.2
+  };
+  const requestConfig = {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    timeout: 3e4
+  };
+  let response;
+  try {
+    response = await axios.post(
+      GROQ_API_URL,
+      { model: PRIMARY_GROQ_MODEL, ...requestBody },
+      requestConfig
+    );
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      const providerMessage = typeof error.response?.data?.error?.message === "string" ? error.response.data.error.message : error.message;
+      const isModelDecommissioned = providerMessage.toLowerCase().includes("decommissioned") || providerMessage.toLowerCase().includes("no longer supported");
+      if (isModelDecommissioned) {
+        response = await axios.post(
+          GROQ_API_URL,
+          { model: FALLBACK_GROQ_MODEL, ...requestBody },
+          requestConfig
+        );
+      } else {
+        throw new Error(`Groq API request failed: ${providerMessage}`);
+      }
+    } else {
+      throw error;
+    }
+  }
+  const content = response.data?.choices?.[0]?.message?.content;
+  if (typeof content !== "string" || !content.trim()) {
+    throw new Error("AI response was empty.");
+  }
+  const parsed = extractJson(content);
+  const normalized = normalizeResponseShape(parsed);
+  return explainedErrorSchema.parse(normalized);
+}
+
+// src/utils/formatter.ts
+import pc from "picocolors";
+var CARD_WIDTH = 72;
+function line(char = "-") {
+  return char.repeat(CARD_WIDTH);
+}
+function pad(text) {
+  return text.length > CARD_WIDTH - 4 ? `${text.slice(0, CARD_WIDTH - 7)}...` : text;
+}
+function framedLine(text) {
+  return `| ${pad(text).padEnd(CARD_WIDTH - 4)} |`;
+}
+function block(title, body) {
+  const rows = body.split("\n").map((row) => pc.white(row));
+  return [pc.cyan(line()), pc.bold(pc.cyan(title)), ...rows, pc.cyan(line())].join("\n");
+}
+function formatExplainedError(result) {
+  const commonCauses = result.common_causes.map((cause, index) => pc.white(`${index + 1}. ${cause}`)).join("\n");
+  const hero = [
+    pc.cyan(line("=")),
+    framedLine(pc.bold(pc.cyan("EXPLAIN MY ERROR"))),
+    framedLine(pc.dim("AI powered debugging for humans")),
+    pc.cyan(line("="))
+  ].join("\n");
+  return [
+    hero,
+    "",
+    `${pc.bold(pc.cyan("ERROR"))}: ${pc.bold(pc.white(result.title))}`,
+    "",
+    block("EXPLANATION", result.explanation),
+    "",
+    block("COMMON CAUSES", commonCauses),
+    "",
+    `${pc.bold(pc.green("FIX"))}
+${pc.white(result.fix)}`,
+    "",
+    block("CODE EXAMPLE", result.code_example),
+    "",
+    block("ELI5", result.eli5),
+    "",
+    pc.dim('Tip: run `eme explain "<error>"` for quick mode.')
+  ].join("\n");
+}
+
+// src/utils/logger.ts
+import pc2 from "picocolors";
+var logger = {
+  info(message) {
+    process.stdout.write(`${pc2.white(message)}
+`);
+  },
+  success(message) {
+    process.stdout.write(`${pc2.green(`OK: ${message}`)}
+`);
+  },
+  warn(message) {
+    process.stderr.write(`${pc2.yellow(`WARN: ${message}`)}
+`);
+  },
+  error(message) {
+    process.stderr.write(`${pc2.red(`ERROR: ${message}`)}
+`);
+  }
+};
+
+// src/commands/explain.ts
+async function runExplainCommand(errorMessage, deps = {}) {
+  const explainError = deps.explainError ?? explainErrorWithAI;
+  const createSpinner = deps.createSpinner ?? ((text) => ora(text).start());
+  const formatOutput = deps.formatOutput ?? formatExplainedError;
+  const log = deps.log ?? logger;
+  if (!errorMessage?.trim()) {
+    log.warn("Please provide an error message.");
+    return;
+  }
+  const spinner = createSpinner("Analyzing your error...");
+  try {
+    const result = await explainError(errorMessage.trim());
+    spinner.succeed("Explanation ready.");
+    log.info("");
+    log.info(formatOutput(result));
+  } catch (error) {
+    spinner.fail("Could not explain this error.");
+    const message = error instanceof Error ? error.message : "Unknown error";
+    log.error(message);
+  }
+}
+
+// src/cli.ts
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    return "";
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+async function promptForError() {
+  if (!process.stdin.isTTY) {
+    return "";
+  }
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    logger.info(pc3.cyan("Paste an error message and press Enter."));
+    logger.info(pc3.dim('Example: TypeError: Cannot read property "map" of undefined'));
+    while (true) {
+      const answer = await rl.question(pc3.bold(pc3.cyan("\n> Error message: ")));
+      const trimmed = answer.trim();
+      if (trimmed) {
+        return trimmed;
+      }
+      logger.warn("Error message cannot be empty. Please try again.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+async function runCli(argv = process.argv, deps = {}) {
+  const runExplain = deps.runExplain ?? runExplainCommand;
+  const readStdinFn = deps.readStdin ?? readStdin;
+  const promptForErrorFn = deps.promptForError ?? promptForError;
+  const stdinIsTTY = deps.stdinIsTTY ?? (() => Boolean(process.stdin.isTTY));
+  const log = deps.log ?? logger;
+  const program = new Command();
+  program.name("explain-my-error").description("Explain programming errors with AI").version("1.0.0").addHelpText(
+    "after",
+    `
+Input modes:
+  1) Interactive (default)
+     $ explain-my-error
+     $ eme
+
+  2) Inline argument
+     $ explain-my-error explain "TypeError: Cannot read property 'map' of undefined"
+     $ eme explain "ReferenceError: x is not defined"
+
+  3) Pipe from files/commands
+     $ cat error.txt | explain-my-error
+     $ pnpm run build 2>&1 | eme
+`
+  );
+  program.command("explain").description("Explain a programming error message").argument("[error...]", "Error message to analyze").addHelpText(
+    "after",
+    `
+Examples:
+  $ explain-my-error explain "SyntaxError: Unexpected token }"
+  $ eme explain "Module not found: Can't resolve 'axios'"
+  $ cat error.txt | explain-my-error explain
+`
+  ).action(async (errorParts) => {
+    const inlineError = errorParts.join(" ").trim();
+    const pipedError = inlineError ? "" : await readStdinFn();
+    const promptedError = !inlineError && !pipedError ? await promptForErrorFn() : "";
+    const finalError = inlineError || pipedError || promptedError;
+    await runExplain(finalError);
+  });
+  program.action(async () => {
+    if (stdinIsTTY()) {
+      const promptedError = await promptForErrorFn();
+      await runExplain(promptedError);
+      return;
+    }
+    const pipedError = await readStdinFn();
+    if (!pipedError) {
+      log.warn('No input detected. Use: explain-my-error explain "<error message>"');
+      return;
+    }
+    await runExplain(pipedError);
+  });
+  await program.parseAsync(argv);
+}
+
+// src/cli-entry.ts
+runCli().catch((error) => {
+  const message = error instanceof Error ? error.message : "Unexpected CLI failure";
+  process.stderr.write(`${message}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli-entry.ts","../src/cli.ts","../src/commands/explain.ts","../src/services/ai.ts","../src/types/error.ts","../src/utils/formatter.ts","../src/utils/logger.ts"],"sourcesContent":["#!/usr/bin/env node\nimport \"dotenv/config\";\nimport { runCli } from \"./cli.js\";\n\nrunCli().catch((error: unknown) => {\n  const message = error instanceof Error ? error.message : \"Unexpected CLI failure\";\n  process.stderr.write(`${message}\\n`);\n  process.exit(1);\n});\n","import { createInterface } from \"node:readline/promises\";\nimport { Command } from \"commander\";\nimport pc from \"picocolors\";\nimport { runExplainCommand } from \"./commands/explain.js\";\nimport { logger } from \"./utils/logger.js\";\n\nasync function readStdin(): Promise<string> {\n  if (process.stdin.isTTY) {\n    return \"\";\n  }\n\n  const chunks: Buffer[] = [];\n  for await (const chunk of process.stdin) {\n    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\n  }\n  return Buffer.concat(chunks).toString(\"utf8\").trim();\n}\n\nasync function promptForError(): Promise<string> {\n  if (!process.stdin.isTTY) {\n    return \"\";\n  }\n\n  const rl = createInterface({\n    input: process.stdin,\n    output: process.stdout,\n  });\n\n  try {\n    logger.info(pc.cyan(\"Paste an error message and press Enter.\"));\n    logger.info(pc.dim('Example: TypeError: Cannot read property \"map\" of undefined'));\n    while (true) {\n      const answer = await rl.question(pc.bold(pc.cyan(\"\\n> Error message: \")));\n      const trimmed = answer.trim();\n\n      if (trimmed) {\n        return trimmed;\n      }\n\n      logger.warn(\"Error message cannot be empty. Please try again.\");\n    }\n  } finally {\n    rl.close();\n  }\n}\n\ntype CliLogger = {\n  warn(message: string): void;\n};\n\ntype RunCliDeps = {\n  runExplain?: (errorMessage: string) => Promise<void>;\n  readStdin?: () => Promise<string>;\n  promptForError?: () => Promise<string>;\n  stdinIsTTY?: () => boolean;\n  log?: CliLogger;\n};\n\nexport async function runCli(argv: string[] = process.argv, deps: RunCliDeps = {}): Promise<void> {\n  const runExplain = deps.runExplain ?? runExplainCommand;\n  const readStdinFn = deps.readStdin ?? readStdin;\n  const promptForErrorFn = deps.promptForError ?? promptForError;\n  const stdinIsTTY = deps.stdinIsTTY ?? (() => Boolean(process.stdin.isTTY));\n  const log = deps.log ?? logger;\n\n  const program = new Command();\n\n  program\n    .name(\"explain-my-error\")\n    .description(\"Explain programming errors with AI\")\n    .version(\"1.0.0\")\n    .addHelpText(\n      \"after\",\n      `\nInput modes:\n  1) Interactive (default)\n     $ explain-my-error\n     $ eme\n\n  2) Inline argument\n     $ explain-my-error explain \"TypeError: Cannot read property 'map' of undefined\"\n     $ eme explain \"ReferenceError: x is not defined\"\n\n  3) Pipe from files/commands\n     $ cat error.txt | explain-my-error\n     $ pnpm run build 2>&1 | eme\n`,\n    );\n\n  program\n    .command(\"explain\")\n    .description(\"Explain a programming error message\")\n    .argument(\"[error...]\", \"Error message to analyze\")\n    .addHelpText(\n      \"after\",\n      `\nExamples:\n  $ explain-my-error explain \"SyntaxError: Unexpected token }\"\n  $ eme explain \"Module not found: Can't resolve 'axios'\"\n  $ cat error.txt | explain-my-error explain\n`,\n    )\n    .action(async (errorParts: string[]) => {\n      const inlineError = errorParts.join(\" \").trim();\n      const pipedError = inlineError ? \"\" : await readStdinFn();\n      const promptedError = !inlineError && !pipedError ? await promptForErrorFn() : \"\";\n      const finalError = inlineError || pipedError || promptedError;\n      await runExplain(finalError);\n    });\n\n  program.action(async () => {\n    if (stdinIsTTY()) {\n      const promptedError = await promptForErrorFn();\n      await runExplain(promptedError);\n      return;\n    }\n\n    const pipedError = await readStdinFn();\n    if (!pipedError) {\n      log.warn('No input detected. Use: explain-my-error explain \"<error message>\"');\n      return;\n    }\n    await runExplain(pipedError);\n  });\n\n  await program.parseAsync(argv);\n}\n","import ora from \"ora\";\nimport { explainErrorWithAI } from \"../services/ai.js\";\nimport type { ExplainedError } from \"../types/error.js\";\nimport { formatExplainedError } from \"../utils/formatter.js\";\nimport { logger } from \"../utils/logger.js\";\n\ntype SpinnerLike = {\n  succeed(text: string): void;\n  fail(text: string): void;\n};\n\ntype ExplainLogger = {\n  info(message: string): void;\n  warn(message: string): void;\n  error(message: string): void;\n};\n\ntype RunExplainDeps = {\n  explainError?: (errorMessage: string) => Promise<ExplainedError>;\n  createSpinner?: (text: string) => SpinnerLike;\n  formatOutput?: (result: ExplainedError) => string;\n  log?: ExplainLogger;\n};\n\nexport async function runExplainCommand(\n  errorMessage: string,\n  deps: RunExplainDeps = {},\n): Promise<void> {\n  const explainError = deps.explainError ?? explainErrorWithAI;\n  const createSpinner = deps.createSpinner ?? ((text: string) => ora(text).start());\n  const formatOutput = deps.formatOutput ?? formatExplainedError;\n  const log = deps.log ?? logger;\n\n  if (!errorMessage?.trim()) {\n    log.warn(\"Please provide an error message.\");\n    return;\n  }\n\n  const spinner = createSpinner(\"Analyzing your error...\");\n\n  try {\n    const result = await explainError(errorMessage.trim());\n    spinner.succeed(\"Explanation ready.\");\n    log.info(\"\");\n    log.info(formatOutput(result));\n  } catch (error) {\n    spinner.fail(\"Could not explain this error.\");\n    const message = error instanceof Error ? error.message : \"Unknown error\";\n    log.error(message);\n  }\n}\n","import axios from \"axios\";\nimport { type ExplainedError, explainedErrorSchema } from \"../types/error.js\";\n\nconst GROQ_API_URL = \"https://api.groq.com/openai/v1/chat/completions\";\nconst PRIMARY_GROQ_MODEL = \"llama3-70b-8192\";\nconst FALLBACK_GROQ_MODEL = process.env.GROQ_FALLBACK_MODEL ?? \"llama-3.3-70b-versatile\";\n\ntype GroqChatResponse = {\n  choices?: Array<{ message?: { content?: string } }>;\n};\n\nfunction extractJson(content: string): unknown {\n  const trimmed = content.trim();\n\n  try {\n    return JSON.parse(trimmed);\n  } catch {\n    const match = trimmed.match(/\\{[\\s\\S]*\\}/);\n    if (!match) {\n      throw new Error(\"AI did not return valid JSON.\");\n    }\n    return JSON.parse(match[0]);\n  }\n}\n\nfunction stringifyField(value: unknown): string {\n  if (typeof value === \"string\") {\n    return value;\n  }\n  if (value == null) {\n    return \"\";\n  }\n  if (typeof value === \"object\") {\n    try {\n      return JSON.stringify(value, null, 2);\n    } catch {\n      return String(value);\n    }\n  }\n  return String(value);\n}\n\nfunction normalizeResponseShape(payload: unknown): unknown {\n  if (!payload || typeof payload !== \"object\") {\n    return payload;\n  }\n\n  const data = payload as Record<string, unknown>;\n\n  const rawCauses = data.common_causes;\n  const commonCauses = Array.isArray(rawCauses)\n    ? rawCauses.map((item) => stringifyField(item)).filter(Boolean)\n    : stringifyField(rawCauses)\n        .split(/\\n|,/)\n        .map((item) => item.trim())\n        .filter(Boolean);\n\n  return {\n    title: stringifyField(data.title),\n    explanation: stringifyField(data.explanation),\n    common_causes: commonCauses,\n    fix: stringifyField(data.fix),\n    code_example: stringifyField(data.code_example),\n    eli5: stringifyField(data.eli5),\n  };\n}\n\nexport async function explainErrorWithAI(errorMessage: string): Promise<ExplainedError> {\n  const apiKey = process.env.GROQ_API_KEY;\n  if (!apiKey) {\n    throw new Error(\"Missing GROQ_API_KEY environment variable.\");\n  }\n\n  const prompt =\n    \"You are a senior software engineer. Explain the programming error and return JSON with fields: title, explanation, common_causes, fix, code_example, eli5.\";\n\n  const requestBody = {\n    messages: [\n      { role: \"system\" as const, content: prompt },\n      {\n        role: \"user\" as const,\n        content: `Error message:\\n${errorMessage}\\n\\nReturn strict JSON only.`,\n      },\n    ],\n    temperature: 0.2,\n  };\n\n  const requestConfig = {\n    headers: {\n      Authorization: `Bearer ${apiKey}`,\n      \"Content-Type\": \"application/json\",\n    },\n    timeout: 30000,\n  };\n\n  let response: { data?: GroqChatResponse };\n  try {\n    response = await axios.post(\n      GROQ_API_URL,\n      { model: PRIMARY_GROQ_MODEL, ...requestBody },\n      requestConfig,\n    );\n  } catch (error) {\n    if (axios.isAxiosError(error)) {\n      const providerMessage =\n        typeof error.response?.data?.error?.message === \"string\"\n          ? error.response.data.error.message\n          : error.message;\n\n      const isModelDecommissioned =\n        providerMessage.toLowerCase().includes(\"decommissioned\") ||\n        providerMessage.toLowerCase().includes(\"no longer supported\");\n\n      if (isModelDecommissioned) {\n        response = await axios.post(\n          GROQ_API_URL,\n          { model: FALLBACK_GROQ_MODEL, ...requestBody },\n          requestConfig,\n        );\n      } else {\n        throw new Error(`Groq API request failed: ${providerMessage}`);\n      }\n    } else {\n      throw error;\n    }\n  }\n\n  const content = response.data?.choices?.[0]?.message?.content;\n  if (typeof content !== \"string\" || !content.trim()) {\n    throw new Error(\"AI response was empty.\");\n  }\n\n  const parsed = extractJson(content);\n  const normalized = normalizeResponseShape(parsed);\n  return explainedErrorSchema.parse(normalized);\n}\n","import { z } from \"zod\";\n\nexport const explainedErrorSchema = z.object({\n  title: z.string().min(1),\n  explanation: z.string().min(1),\n  common_causes: z.array(z.string().min(1)).min(1),\n  fix: z.string().min(1),\n  code_example: z.string().min(1),\n  eli5: z.string().min(1),\n});\n\nexport type ExplainedError = z.infer<typeof explainedErrorSchema>;\n","import pc from \"picocolors\";\nimport type { ExplainedError } from \"../types/error.js\";\n\nconst CARD_WIDTH = 72;\n\nfunction line(char = \"-\"): string {\n  return char.repeat(CARD_WIDTH);\n}\n\nfunction pad(text: string): string {\n  return text.length > CARD_WIDTH - 4 ? `${text.slice(0, CARD_WIDTH - 7)}...` : text;\n}\n\nfunction framedLine(text: string): string {\n  return `| ${pad(text).padEnd(CARD_WIDTH - 4)} |`;\n}\n\nfunction block(title: string, body: string): string {\n  const rows = body.split(\"\\n\").map((row) => pc.white(row));\n  return [pc.cyan(line()), pc.bold(pc.cyan(title)), ...rows, pc.cyan(line())].join(\"\\n\");\n}\n\nexport function formatExplainedError(result: ExplainedError): string {\n  const commonCauses = result.common_causes\n    .map((cause, index) => pc.white(`${index + 1}. ${cause}`))\n    .join(\"\\n\");\n  const hero = [\n    pc.cyan(line(\"=\")),\n    framedLine(pc.bold(pc.cyan(\"EXPLAIN MY ERROR\"))),\n    framedLine(pc.dim(\"AI powered debugging for humans\")),\n    pc.cyan(line(\"=\")),\n  ].join(\"\\n\");\n\n  return [\n    hero,\n    \"\",\n    `${pc.bold(pc.cyan(\"ERROR\"))}: ${pc.bold(pc.white(result.title))}`,\n    \"\",\n    block(\"EXPLANATION\", result.explanation),\n    \"\",\n    block(\"COMMON CAUSES\", commonCauses),\n    \"\",\n    `${pc.bold(pc.green(\"FIX\"))}\\n${pc.white(result.fix)}`,\n    \"\",\n    block(\"CODE EXAMPLE\", result.code_example),\n    \"\",\n    block(\"ELI5\", result.eli5),\n    \"\",\n    pc.dim('Tip: run `eme explain \"<error>\"` for quick mode.'),\n  ].join(\"\\n\");\n}\n","import pc from \"picocolors\";\n\nexport const logger = {\n  info(message: string): void {\n    process.stdout.write(`${pc.white(message)}\\n`);\n  },\n  success(message: string): void {\n    process.stdout.write(`${pc.green(`OK: ${message}`)}\\n`);\n  },\n  warn(message: string): void {\n    process.stderr.write(`${pc.yellow(`WARN: ${message}`)}\\n`);\n  },\n  error(message: string): void {\n    process.stderr.write(`${pc.red(`ERROR: ${message}`)}\\n`);\n  },\n};\n"],"mappings":"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","names":["pc","pc","pc"]}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+
+type CliLogger = {
+    warn(message: string): void;
+};
+type RunCliDeps = {
+    runExplain?: (errorMessage: string) => Promise<void>;
+    readStdin?: () => Promise<string>;
+    promptForError?: () => Promise<string>;
+    stdinIsTTY?: () => boolean;
+    log?: CliLogger;
+};
+declare function runCli(argv?: string[], deps?: RunCliDeps): Promise<void>;
+
+declare const explainedErrorSchema: z.ZodObject<{
+    title: z.ZodString;
+    explanation: z.ZodString;
+    common_causes: z.ZodArray<z.ZodString, "many">;
+    fix: z.ZodString;
+    code_example: z.ZodString;
+    eli5: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    explanation: string;
+    common_causes: string[];
+    fix: string;
+    code_example: string;
+    eli5: string;
+}, {
+    title: string;
+    explanation: string;
+    common_causes: string[];
+    fix: string;
+    code_example: string;
+    eli5: string;
+}>;
+type ExplainedError = z.infer<typeof explainedErrorSchema>;
+
+declare function explainError(errorMessage: string): Promise<ExplainedError>;
+
+declare function explainErrorWithAI(errorMessage: string): Promise<ExplainedError>;
+
+declare const explainErrorSkillInputSchema: z.ZodObject<{
+    error: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    error: string;
+}, {
+    error: string;
+}>;
+type ExplainErrorSkillInput = z.infer<typeof explainErrorSkillInputSchema>;
+declare function runExplainErrorSkill(input: ExplainErrorSkillInput): Promise<ExplainedError>;
+
+export { type ExplainedError, explainError, explainErrorWithAI, runCli, runExplainErrorSkill };

package/dist/index.js

@@ -0,0 +1,327 @@
+// src/cli.ts
+import { createInterface } from "readline/promises";
+import { Command } from "commander";
+import pc3 from "picocolors";
+
+// src/commands/explain.ts
+import ora from "ora";
+
+// src/services/ai.ts
+import axios from "axios";
+
+// src/types/error.ts
+import { z } from "zod";
+var explainedErrorSchema = z.object({
+  title: z.string().min(1),
+  explanation: z.string().min(1),
+  common_causes: z.array(z.string().min(1)).min(1),
+  fix: z.string().min(1),
+  code_example: z.string().min(1),
+  eli5: z.string().min(1)
+});
+
+// src/services/ai.ts
+var GROQ_API_URL = "https://api.groq.com/openai/v1/chat/completions";
+var PRIMARY_GROQ_MODEL = "llama3-70b-8192";
+var FALLBACK_GROQ_MODEL = process.env.GROQ_FALLBACK_MODEL ?? "llama-3.3-70b-versatile";
+function extractJson(content) {
+  const trimmed = content.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    const match = trimmed.match(/\{[\s\S]*\}/);
+    if (!match) {
+      throw new Error("AI did not return valid JSON.");
+    }
+    return JSON.parse(match[0]);
+  }
+}
+function stringifyField(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value == null) {
+    return "";
+  }
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+function normalizeResponseShape(payload) {
+  if (!payload || typeof payload !== "object") {
+    return payload;
+  }
+  const data = payload;
+  const rawCauses = data.common_causes;
+  const commonCauses = Array.isArray(rawCauses) ? rawCauses.map((item) => stringifyField(item)).filter(Boolean) : stringifyField(rawCauses).split(/\n|,/).map((item) => item.trim()).filter(Boolean);
+  return {
+    title: stringifyField(data.title),
+    explanation: stringifyField(data.explanation),
+    common_causes: commonCauses,
+    fix: stringifyField(data.fix),
+    code_example: stringifyField(data.code_example),
+    eli5: stringifyField(data.eli5)
+  };
+}
+async function explainErrorWithAI(errorMessage) {
+  const apiKey = process.env.GROQ_API_KEY;
+  if (!apiKey) {
+    throw new Error("Missing GROQ_API_KEY environment variable.");
+  }
+  const prompt = "You are a senior software engineer. Explain the programming error and return JSON with fields: title, explanation, common_causes, fix, code_example, eli5.";
+  const requestBody = {
+    messages: [
+      { role: "system", content: prompt },
+      {
+        role: "user",
+        content: `Error message:
+${errorMessage}
+
+Return strict JSON only.`
+      }
+    ],
+    temperature: 0.2
+  };
+  const requestConfig = {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    timeout: 3e4
+  };
+  let response;
+  try {
+    response = await axios.post(
+      GROQ_API_URL,
+      { model: PRIMARY_GROQ_MODEL, ...requestBody },
+      requestConfig
+    );
+  } catch (error) {
+    if (axios.isAxiosError(error)) {
+      const providerMessage = typeof error.response?.data?.error?.message === "string" ? error.response.data.error.message : error.message;
+      const isModelDecommissioned = providerMessage.toLowerCase().includes("decommissioned") || providerMessage.toLowerCase().includes("no longer supported");
+      if (isModelDecommissioned) {
+        response = await axios.post(
+          GROQ_API_URL,
+          { model: FALLBACK_GROQ_MODEL, ...requestBody },
+          requestConfig
+        );
+      } else {
+        throw new Error(`Groq API request failed: ${providerMessage}`);
+      }
+    } else {
+      throw error;
+    }
+  }
+  const content = response.data?.choices?.[0]?.message?.content;
+  if (typeof content !== "string" || !content.trim()) {
+    throw new Error("AI response was empty.");
+  }
+  const parsed = extractJson(content);
+  const normalized = normalizeResponseShape(parsed);
+  return explainedErrorSchema.parse(normalized);
+}
+
+// src/utils/formatter.ts
+import pc from "picocolors";
+var CARD_WIDTH = 72;
+function line(char = "-") {
+  return char.repeat(CARD_WIDTH);
+}
+function pad(text) {
+  return text.length > CARD_WIDTH - 4 ? `${text.slice(0, CARD_WIDTH - 7)}...` : text;
+}
+function framedLine(text) {
+  return `| ${pad(text).padEnd(CARD_WIDTH - 4)} |`;
+}
+function block(title, body) {
+  const rows = body.split("\n").map((row) => pc.white(row));
+  return [pc.cyan(line()), pc.bold(pc.cyan(title)), ...rows, pc.cyan(line())].join("\n");
+}
+function formatExplainedError(result) {
+  const commonCauses = result.common_causes.map((cause, index) => pc.white(`${index + 1}. ${cause}`)).join("\n");
+  const hero = [
+    pc.cyan(line("=")),
+    framedLine(pc.bold(pc.cyan("EXPLAIN MY ERROR"))),
+    framedLine(pc.dim("AI powered debugging for humans")),
+    pc.cyan(line("="))
+  ].join("\n");
+  return [
+    hero,
+    "",
+    `${pc.bold(pc.cyan("ERROR"))}: ${pc.bold(pc.white(result.title))}`,
+    "",
+    block("EXPLANATION", result.explanation),
+    "",
+    block("COMMON CAUSES", commonCauses),
+    "",
+    `${pc.bold(pc.green("FIX"))}
+${pc.white(result.fix)}`,
+    "",
+    block("CODE EXAMPLE", result.code_example),
+    "",
+    block("ELI5", result.eli5),
+    "",
+    pc.dim('Tip: run `eme explain "<error>"` for quick mode.')
+  ].join("\n");
+}
+
+// src/utils/logger.ts
+import pc2 from "picocolors";
+var logger = {
+  info(message) {
+    process.stdout.write(`${pc2.white(message)}
+`);
+  },
+  success(message) {
+    process.stdout.write(`${pc2.green(`OK: ${message}`)}
+`);
+  },
+  warn(message) {
+    process.stderr.write(`${pc2.yellow(`WARN: ${message}`)}
+`);
+  },
+  error(message) {
+    process.stderr.write(`${pc2.red(`ERROR: ${message}`)}
+`);
+  }
+};
+
+// src/commands/explain.ts
+async function runExplainCommand(errorMessage, deps = {}) {
+  const explainError2 = deps.explainError ?? explainErrorWithAI;
+  const createSpinner = deps.createSpinner ?? ((text) => ora(text).start());
+  const formatOutput = deps.formatOutput ?? formatExplainedError;
+  const log = deps.log ?? logger;
+  if (!errorMessage?.trim()) {
+    log.warn("Please provide an error message.");
+    return;
+  }
+  const spinner = createSpinner("Analyzing your error...");
+  try {
+    const result = await explainError2(errorMessage.trim());
+    spinner.succeed("Explanation ready.");
+    log.info("");
+    log.info(formatOutput(result));
+  } catch (error) {
+    spinner.fail("Could not explain this error.");
+    const message = error instanceof Error ? error.message : "Unknown error";
+    log.error(message);
+  }
+}
+
+// src/cli.ts
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    return "";
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+async function promptForError() {
+  if (!process.stdin.isTTY) {
+    return "";
+  }
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    logger.info(pc3.cyan("Paste an error message and press Enter."));
+    logger.info(pc3.dim('Example: TypeError: Cannot read property "map" of undefined'));
+    while (true) {
+      const answer = await rl.question(pc3.bold(pc3.cyan("\n> Error message: ")));
+      const trimmed = answer.trim();
+      if (trimmed) {
+        return trimmed;
+      }
+      logger.warn("Error message cannot be empty. Please try again.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+async function runCli(argv = process.argv, deps = {}) {
+  const runExplain = deps.runExplain ?? runExplainCommand;
+  const readStdinFn = deps.readStdin ?? readStdin;
+  const promptForErrorFn = deps.promptForError ?? promptForError;
+  const stdinIsTTY = deps.stdinIsTTY ?? (() => Boolean(process.stdin.isTTY));
+  const log = deps.log ?? logger;
+  const program = new Command();
+  program.name("explain-my-error").description("Explain programming errors with AI").version("1.0.0").addHelpText(
+    "after",
+    `
+Input modes:
+  1) Interactive (default)
+     $ explain-my-error
+     $ eme
+
+  2) Inline argument
+     $ explain-my-error explain "TypeError: Cannot read property 'map' of undefined"
+     $ eme explain "ReferenceError: x is not defined"
+
+  3) Pipe from files/commands
+     $ cat error.txt | explain-my-error
+     $ pnpm run build 2>&1 | eme
+`
+  );
+  program.command("explain").description("Explain a programming error message").argument("[error...]", "Error message to analyze").addHelpText(
+    "after",
+    `
+Examples:
+  $ explain-my-error explain "SyntaxError: Unexpected token }"
+  $ eme explain "Module not found: Can't resolve 'axios'"
+  $ cat error.txt | explain-my-error explain
+`
+  ).action(async (errorParts) => {
+    const inlineError = errorParts.join(" ").trim();
+    const pipedError = inlineError ? "" : await readStdinFn();
+    const promptedError = !inlineError && !pipedError ? await promptForErrorFn() : "";
+    const finalError = inlineError || pipedError || promptedError;
+    await runExplain(finalError);
+  });
+  program.action(async () => {
+    if (stdinIsTTY()) {
+      const promptedError = await promptForErrorFn();
+      await runExplain(promptedError);
+      return;
+    }
+    const pipedError = await readStdinFn();
+    if (!pipedError) {
+      log.warn('No input detected. Use: explain-my-error explain "<error message>"');
+      return;
+    }
+    await runExplain(pipedError);
+  });
+  await program.parseAsync(argv);
+}
+
+// src/explain.ts
+async function explainError(errorMessage) {
+  return explainErrorWithAI(errorMessage);
+}
+
+// src/skills/explainError.skill.ts
+import { z as z2 } from "zod";
+var explainErrorSkillInputSchema = z2.object({
+  error: z2.string().min(1, "error is required")
+});
+async function runExplainErrorSkill(input) {
+  const parsedInput = explainErrorSkillInputSchema.parse(input);
+  return explainErrorWithAI(parsedInput.error);
+}
+export {
+  explainError,
+  explainErrorWithAI,
+  runCli,
+  runExplainErrorSkill
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/commands/explain.ts","../src/services/ai.ts","../src/types/error.ts","../src/utils/formatter.ts","../src/utils/logger.ts","../src/explain.ts","../src/skills/explainError.skill.ts"],"sourcesContent":["import { createInterface } from \"node:readline/promises\";\nimport { Command } from \"commander\";\nimport pc from \"picocolors\";\nimport { runExplainCommand } from \"./commands/explain.js\";\nimport { logger } from \"./utils/logger.js\";\n\nasync function readStdin(): Promise<string> {\n  if (process.stdin.isTTY) {\n    return \"\";\n  }\n\n  const chunks: Buffer[] = [];\n  for await (const chunk of process.stdin) {\n    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));\n  }\n  return Buffer.concat(chunks).toString(\"utf8\").trim();\n}\n\nasync function promptForError(): Promise<string> {\n  if (!process.stdin.isTTY) {\n    return \"\";\n  }\n\n  const rl = createInterface({\n    input: process.stdin,\n    output: process.stdout,\n  });\n\n  try {\n    logger.info(pc.cyan(\"Paste an error message and press Enter.\"));\n    logger.info(pc.dim('Example: TypeError: Cannot read property \"map\" of undefined'));\n    while (true) {\n      const answer = await rl.question(pc.bold(pc.cyan(\"\\n> Error message: \")));\n      const trimmed = answer.trim();\n\n      if (trimmed) {\n        return trimmed;\n      }\n\n      logger.warn(\"Error message cannot be empty. Please try again.\");\n    }\n  } finally {\n    rl.close();\n  }\n}\n\ntype CliLogger = {\n  warn(message: string): void;\n};\n\ntype RunCliDeps = {\n  runExplain?: (errorMessage: string) => Promise<void>;\n  readStdin?: () => Promise<string>;\n  promptForError?: () => Promise<string>;\n  stdinIsTTY?: () => boolean;\n  log?: CliLogger;\n};\n\nexport async function runCli(argv: string[] = process.argv, deps: RunCliDeps = {}): Promise<void> {\n  const runExplain = deps.runExplain ?? runExplainCommand;\n  const readStdinFn = deps.readStdin ?? readStdin;\n  const promptForErrorFn = deps.promptForError ?? promptForError;\n  const stdinIsTTY = deps.stdinIsTTY ?? (() => Boolean(process.stdin.isTTY));\n  const log = deps.log ?? logger;\n\n  const program = new Command();\n\n  program\n    .name(\"explain-my-error\")\n    .description(\"Explain programming errors with AI\")\n    .version(\"1.0.0\")\n    .addHelpText(\n      \"after\",\n      `\nInput modes:\n  1) Interactive (default)\n     $ explain-my-error\n     $ eme\n\n  2) Inline argument\n     $ explain-my-error explain \"TypeError: Cannot read property 'map' of undefined\"\n     $ eme explain \"ReferenceError: x is not defined\"\n\n  3) Pipe from files/commands\n     $ cat error.txt | explain-my-error\n     $ pnpm run build 2>&1 | eme\n`,\n    );\n\n  program\n    .command(\"explain\")\n    .description(\"Explain a programming error message\")\n    .argument(\"[error...]\", \"Error message to analyze\")\n    .addHelpText(\n      \"after\",\n      `\nExamples:\n  $ explain-my-error explain \"SyntaxError: Unexpected token }\"\n  $ eme explain \"Module not found: Can't resolve 'axios'\"\n  $ cat error.txt | explain-my-error explain\n`,\n    )\n    .action(async (errorParts: string[]) => {\n      const inlineError = errorParts.join(\" \").trim();\n      const pipedError = inlineError ? \"\" : await readStdinFn();\n      const promptedError = !inlineError && !pipedError ? await promptForErrorFn() : \"\";\n      const finalError = inlineError || pipedError || promptedError;\n      await runExplain(finalError);\n    });\n\n  program.action(async () => {\n    if (stdinIsTTY()) {\n      const promptedError = await promptForErrorFn();\n      await runExplain(promptedError);\n      return;\n    }\n\n    const pipedError = await readStdinFn();\n    if (!pipedError) {\n      log.warn('No input detected. Use: explain-my-error explain \"<error message>\"');\n      return;\n    }\n    await runExplain(pipedError);\n  });\n\n  await program.parseAsync(argv);\n}\n","import ora from \"ora\";\nimport { explainErrorWithAI } from \"../services/ai.js\";\nimport type { ExplainedError } from \"../types/error.js\";\nimport { formatExplainedError } from \"../utils/formatter.js\";\nimport { logger } from \"../utils/logger.js\";\n\ntype SpinnerLike = {\n  succeed(text: string): void;\n  fail(text: string): void;\n};\n\ntype ExplainLogger = {\n  info(message: string): void;\n  warn(message: string): void;\n  error(message: string): void;\n};\n\ntype RunExplainDeps = {\n  explainError?: (errorMessage: string) => Promise<ExplainedError>;\n  createSpinner?: (text: string) => SpinnerLike;\n  formatOutput?: (result: ExplainedError) => string;\n  log?: ExplainLogger;\n};\n\nexport async function runExplainCommand(\n  errorMessage: string,\n  deps: RunExplainDeps = {},\n): Promise<void> {\n  const explainError = deps.explainError ?? explainErrorWithAI;\n  const createSpinner = deps.createSpinner ?? ((text: string) => ora(text).start());\n  const formatOutput = deps.formatOutput ?? formatExplainedError;\n  const log = deps.log ?? logger;\n\n  if (!errorMessage?.trim()) {\n    log.warn(\"Please provide an error message.\");\n    return;\n  }\n\n  const spinner = createSpinner(\"Analyzing your error...\");\n\n  try {\n    const result = await explainError(errorMessage.trim());\n    spinner.succeed(\"Explanation ready.\");\n    log.info(\"\");\n    log.info(formatOutput(result));\n  } catch (error) {\n    spinner.fail(\"Could not explain this error.\");\n    const message = error instanceof Error ? error.message : \"Unknown error\";\n    log.error(message);\n  }\n}\n","import axios from \"axios\";\nimport { type ExplainedError, explainedErrorSchema } from \"../types/error.js\";\n\nconst GROQ_API_URL = \"https://api.groq.com/openai/v1/chat/completions\";\nconst PRIMARY_GROQ_MODEL = \"llama3-70b-8192\";\nconst FALLBACK_GROQ_MODEL = process.env.GROQ_FALLBACK_MODEL ?? \"llama-3.3-70b-versatile\";\n\ntype GroqChatResponse = {\n  choices?: Array<{ message?: { content?: string } }>;\n};\n\nfunction extractJson(content: string): unknown {\n  const trimmed = content.trim();\n\n  try {\n    return JSON.parse(trimmed);\n  } catch {\n    const match = trimmed.match(/\\{[\\s\\S]*\\}/);\n    if (!match) {\n      throw new Error(\"AI did not return valid JSON.\");\n    }\n    return JSON.parse(match[0]);\n  }\n}\n\nfunction stringifyField(value: unknown): string {\n  if (typeof value === \"string\") {\n    return value;\n  }\n  if (value == null) {\n    return \"\";\n  }\n  if (typeof value === \"object\") {\n    try {\n      return JSON.stringify(value, null, 2);\n    } catch {\n      return String(value);\n    }\n  }\n  return String(value);\n}\n\nfunction normalizeResponseShape(payload: unknown): unknown {\n  if (!payload || typeof payload !== \"object\") {\n    return payload;\n  }\n\n  const data = payload as Record<string, unknown>;\n\n  const rawCauses = data.common_causes;\n  const commonCauses = Array.isArray(rawCauses)\n    ? rawCauses.map((item) => stringifyField(item)).filter(Boolean)\n    : stringifyField(rawCauses)\n        .split(/\\n|,/)\n        .map((item) => item.trim())\n        .filter(Boolean);\n\n  return {\n    title: stringifyField(data.title),\n    explanation: stringifyField(data.explanation),\n    common_causes: commonCauses,\n    fix: stringifyField(data.fix),\n    code_example: stringifyField(data.code_example),\n    eli5: stringifyField(data.eli5),\n  };\n}\n\nexport async function explainErrorWithAI(errorMessage: string): Promise<ExplainedError> {\n  const apiKey = process.env.GROQ_API_KEY;\n  if (!apiKey) {\n    throw new Error(\"Missing GROQ_API_KEY environment variable.\");\n  }\n\n  const prompt =\n    \"You are a senior software engineer. Explain the programming error and return JSON with fields: title, explanation, common_causes, fix, code_example, eli5.\";\n\n  const requestBody = {\n    messages: [\n      { role: \"system\" as const, content: prompt },\n      {\n        role: \"user\" as const,\n        content: `Error message:\\n${errorMessage}\\n\\nReturn strict JSON only.`,\n      },\n    ],\n    temperature: 0.2,\n  };\n\n  const requestConfig = {\n    headers: {\n      Authorization: `Bearer ${apiKey}`,\n      \"Content-Type\": \"application/json\",\n    },\n    timeout: 30000,\n  };\n\n  let response: { data?: GroqChatResponse };\n  try {\n    response = await axios.post(\n      GROQ_API_URL,\n      { model: PRIMARY_GROQ_MODEL, ...requestBody },\n      requestConfig,\n    );\n  } catch (error) {\n    if (axios.isAxiosError(error)) {\n      const providerMessage =\n        typeof error.response?.data?.error?.message === \"string\"\n          ? error.response.data.error.message\n          : error.message;\n\n      const isModelDecommissioned =\n        providerMessage.toLowerCase().includes(\"decommissioned\") ||\n        providerMessage.toLowerCase().includes(\"no longer supported\");\n\n      if (isModelDecommissioned) {\n        response = await axios.post(\n          GROQ_API_URL,\n          { model: FALLBACK_GROQ_MODEL, ...requestBody },\n          requestConfig,\n        );\n      } else {\n        throw new Error(`Groq API request failed: ${providerMessage}`);\n      }\n    } else {\n      throw error;\n    }\n  }\n\n  const content = response.data?.choices?.[0]?.message?.content;\n  if (typeof content !== \"string\" || !content.trim()) {\n    throw new Error(\"AI response was empty.\");\n  }\n\n  const parsed = extractJson(content);\n  const normalized = normalizeResponseShape(parsed);\n  return explainedErrorSchema.parse(normalized);\n}\n","import { z } from \"zod\";\n\nexport const explainedErrorSchema = z.object({\n  title: z.string().min(1),\n  explanation: z.string().min(1),\n  common_causes: z.array(z.string().min(1)).min(1),\n  fix: z.string().min(1),\n  code_example: z.string().min(1),\n  eli5: z.string().min(1),\n});\n\nexport type ExplainedError = z.infer<typeof explainedErrorSchema>;\n","import pc from \"picocolors\";\nimport type { ExplainedError } from \"../types/error.js\";\n\nconst CARD_WIDTH = 72;\n\nfunction line(char = \"-\"): string {\n  return char.repeat(CARD_WIDTH);\n}\n\nfunction pad(text: string): string {\n  return text.length > CARD_WIDTH - 4 ? `${text.slice(0, CARD_WIDTH - 7)}...` : text;\n}\n\nfunction framedLine(text: string): string {\n  return `| ${pad(text).padEnd(CARD_WIDTH - 4)} |`;\n}\n\nfunction block(title: string, body: string): string {\n  const rows = body.split(\"\\n\").map((row) => pc.white(row));\n  return [pc.cyan(line()), pc.bold(pc.cyan(title)), ...rows, pc.cyan(line())].join(\"\\n\");\n}\n\nexport function formatExplainedError(result: ExplainedError): string {\n  const commonCauses = result.common_causes\n    .map((cause, index) => pc.white(`${index + 1}. ${cause}`))\n    .join(\"\\n\");\n  const hero = [\n    pc.cyan(line(\"=\")),\n    framedLine(pc.bold(pc.cyan(\"EXPLAIN MY ERROR\"))),\n    framedLine(pc.dim(\"AI powered debugging for humans\")),\n    pc.cyan(line(\"=\")),\n  ].join(\"\\n\");\n\n  return [\n    hero,\n    \"\",\n    `${pc.bold(pc.cyan(\"ERROR\"))}: ${pc.bold(pc.white(result.title))}`,\n    \"\",\n    block(\"EXPLANATION\", result.explanation),\n    \"\",\n    block(\"COMMON CAUSES\", commonCauses),\n    \"\",\n    `${pc.bold(pc.green(\"FIX\"))}\\n${pc.white(result.fix)}`,\n    \"\",\n    block(\"CODE EXAMPLE\", result.code_example),\n    \"\",\n    block(\"ELI5\", result.eli5),\n    \"\",\n    pc.dim('Tip: run `eme explain \"<error>\"` for quick mode.'),\n  ].join(\"\\n\");\n}\n","import pc from \"picocolors\";\n\nexport const logger = {\n  info(message: string): void {\n    process.stdout.write(`${pc.white(message)}\\n`);\n  },\n  success(message: string): void {\n    process.stdout.write(`${pc.green(`OK: ${message}`)}\\n`);\n  },\n  warn(message: string): void {\n    process.stderr.write(`${pc.yellow(`WARN: ${message}`)}\\n`);\n  },\n  error(message: string): void {\n    process.stderr.write(`${pc.red(`ERROR: ${message}`)}\\n`);\n  },\n};\n","import { explainErrorWithAI } from \"./services/ai.js\";\nimport type { ExplainedError } from \"./types/error.js\";\n\nexport async function explainError(errorMessage: string): Promise<ExplainedError> {\n  return explainErrorWithAI(errorMessage);\n}\n","import { z } from \"zod\";\nimport { explainErrorWithAI } from \"../services/ai.js\";\nimport type { ExplainedError } from \"../types/error.js\";\n\nconst explainErrorSkillInputSchema = z.object({\n  error: z.string().min(1, \"error is required\"),\n});\n\nexport type ExplainErrorSkillInput = z.infer<typeof explainErrorSkillInputSchema>;\n\nexport async function runExplainErrorSkill(input: ExplainErrorSkillInput): Promise<ExplainedError> {\n  const parsedInput = explainErrorSkillInputSchema.parse(input);\n  return explainErrorWithAI(parsedInput.error);\n}\n"],"mappings":"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","names":["pc","pc","explainError","pc","z","z"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "explain-my-error",
+  "version": "1.0.0",
+  "description": "AI-powered CLI to explain programming errors with fixes and ELI5 output.",
+  "type": "module",
+  "bin": {
+    "explain-my-error": "./dist/cli.js",
+    "eme": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills/SKILL.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "cli",
+    "errors",
+    "debugging",
+    "ai",
+    "groq",
+    "agent-skill"
+  ],
+  "author": "Awais Ali",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awaisaly/explain-my-error.git"
+  },
+  "homepage": "https://github.com/awaisaly/explain-my-error#readme",
+  "bugs": {
+    "url": "https://github.com/awaisaly/explain-my-error/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "axios": "^1.8.4",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "ora": "^8.1.1",
+    "picocolors": "^1.1.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.13.10",
+    "tsup": "^8.3.5",
+    "typescript": "^5.8.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build",
+    "release": "pnpm run check && pnpm publish",
+    "release:patch": "pnpm run check && pnpm version patch && pnpm publish",
+    "release:minor": "pnpm run check && pnpm version minor && pnpm publish",
+    "release:major": "pnpm run check && pnpm version major && pnpm publish"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,79 @@
+# explain_error
+
+## Metadata
+
+```yaml
+name: explain_error
+description: Explains programming errors and provides fixes.
+```
+
+- Name: `explain_error`
+- Description: `Explains programming errors and provides fixes.`
+
+## Description
+
+This skill takes a raw programming error string and returns a structured explanation that is easy for both humans and agents to consume.
+
+## Input schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "error": {
+      "type": "string",
+      "description": "Programming error message"
+    }
+  },
+  "required": ["error"]
+}
+```
+
+## Output schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "title": { "type": "string" },
+    "explanation": { "type": "string" },
+    "common_causes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "fix": { "type": "string" },
+    "code_example": { "type": "string" },
+    "eli5": { "type": "string" }
+  }
+}
+```
+
+## Implementation
+
+- Runtime entrypoint: `src/skills/explainError.skill.ts`
+- Exported function: `runExplainErrorSkill(input)`
+
+## Example input
+
+```json
+{
+  "error": "TypeError: Cannot read property 'map' of undefined"
+}
+```
+
+## Example output
+
+```json
+{
+  "title": "TypeError: Cannot read property 'map' of undefined",
+  "explanation": "This happens when .map() is called on a variable that is undefined.",
+  "common_causes": [
+    "API data not loaded",
+    "State not initialized",
+    "Incorrect variable reference"
+  ],
+  "fix": "Ensure the array exists before calling map.",
+  "code_example": "const items = data?.items ?? [];\\nitems.map(...)",
+  "eli5": "Your code expected a box of toys (an array), but the toy box was empty."
+}
+```