explain-my-error 1.0.9 → 1.0.11

package/README.md

@@ -1,13 +1,19 @@
-# explain-my-error
-
 ![explain-my-error CLI screenshot](./cli-screenshot.svg)
 
+# explain-my-error
+
 Turn confusing programming errors into clear fixes directly in your terminal.
 
 `explain-my-error` returns:
 
 - A plain-English explanation
 - Common root causes
+- Likely root cause based on context
+- 2-3 alternative hypotheses with confidence
+- Ranked fix plans (fast patch / proper fix / long-term fix)
+- Framework-specific recipes (React/Next.js/Node/Express/TypeScript)
+- Copy-paste remediation commands
+- Verify checklist
 - A practical fix
 - A code example
 - An ELI5 summary
@@ -90,6 +96,26 @@ explain-my-error explain "TypeError: Cannot read property 'map' of undefined"
 eme explain "ReferenceError: x is not defined"
 ```
 
+### Context-aware input
+
+```bash
+eme explain "TypeError: Cannot read property 'map' of undefined" \
+  --framework react \
+  --runtime "node 20" \
+  --stack "at App (src/App.tsx:12:5)" \
+  --code "items.map(item => item.id)"
+```
+
+```bash
+eme explain --stack-file ./error.log --code-file ./src/App.tsx --framework nextjs
+```
+
+### JSON mode
+
+```bash
+eme explain "ReferenceError: x is not defined" --json
+```
+
 ### Piped input
 
 ```bash
@@ -109,6 +135,11 @@ explain-my-error [command]
 Commands:
 
 - `explain [error...]` Explain a programming error
+- `--json` Return structured JSON output
+- `--stack`, `--stack-file` Add stack trace context
+- `--code`, `--code-file` Add code snippet context
+- `--runtime` Add runtime context
+- `--framework` Add framework context
 - `--help` Show CLI help
 - `--version` Show CLI version
 

package/dist/cli.js

@@ -18,13 +18,45 @@ import axios from "axios";
 
 // src/types/error.ts
 import { z } from "zod";
+var hypothesisSchema = z.object({
+  hypothesis: z.string().min(1),
+  confidence: z.number().min(0).max(1),
+  why: z.string().min(1)
+});
+var fixPlanSchema = z.object({
+  plan: z.enum(["fast_patch", "proper_fix", "long_term_fix"]),
+  summary: z.string().min(1),
+  steps: z.array(z.string().min(1)).min(1),
+  tradeoffs: z.object({
+    risk: z.string().min(1),
+    performance: z.string().min(1),
+    maintainability: z.string().min(1)
+  })
+});
+var frameworkRecipeSchema = z.object({
+  framework: z.string().min(1),
+  when_to_use: z.string().min(1),
+  steps: z.array(z.string().min(1)).min(1),
+  code_snippet: z.string().min(1)
+});
+var remediationBlockSchema = z.object({
+  title: z.string().min(1),
+  commands: z.array(z.string().min(1)).min(1),
+  snippet: z.string().optional()
+});
 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)
+  eli5: z.string().min(1),
+  likely_root_cause: z.string().min(1),
+  hypotheses: z.array(hypothesisSchema).min(1).max(3),
+  fix_plans: z.array(fixPlanSchema).min(3),
+  framework_recipes: z.array(frameworkRecipeSchema).min(1),
+  remediation_blocks: z.array(remediationBlockSchema).min(1),
+  verify_checklist: z.array(z.string().min(1)).min(1)
 });
 
 // src/services/ai.ts
@@ -125,23 +157,160 @@ function stringifyField(value) {
   }
   return String(value);
 }
+function toStringArray(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stringifyField(item)).map((item) => item.trim()).filter(Boolean);
+  }
+  return stringifyField(value).split(/\n|,/).map((item) => item.trim()).filter(Boolean);
+}
+function toConfidence(value) {
+  if (typeof value === "number") {
+    return Math.max(0, Math.min(1, value));
+  }
+  const parsed = Number(stringifyField(value));
+  if (!Number.isNaN(parsed)) {
+    return Math.max(0, Math.min(1, parsed));
+  }
+  return 0.5;
+}
 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);
+  const commonCauses = toStringArray(data.common_causes);
+  const hypothesesRaw = Array.isArray(data.hypotheses) ? data.hypotheses : [];
+  const hypotheses = hypothesesRaw.map((item) => {
+    const row = item;
+    return {
+      hypothesis: stringifyField(row?.hypothesis),
+      confidence: toConfidence(row?.confidence),
+      why: stringifyField(row?.why)
+    };
+  }).filter((item) => item.hypothesis && item.why).slice(0, 3);
+  const fixPlansRaw = Array.isArray(data.fix_plans) ? data.fix_plans : [];
+  const normalizedFixPlans = fixPlansRaw.map((item, index) => {
+    const row = item;
+    const defaultPlan = index === 0 ? "fast_patch" : index === 1 ? "proper_fix" : "long_term_fix";
+    const planText = stringifyField(row?.plan || defaultPlan).toLowerCase();
+    const plan = planText === "fast_patch" || planText === "proper_fix" || planText === "long_term_fix" ? planText : defaultPlan;
+    const tradeoffs = row?.tradeoffs ?? {};
+    return {
+      plan,
+      summary: stringifyField(row?.summary),
+      steps: toStringArray(row?.steps),
+      tradeoffs: {
+        risk: stringifyField(tradeoffs.risk || "Unknown"),
+        performance: stringifyField(tradeoffs.performance || "Unknown"),
+        maintainability: stringifyField(tradeoffs.maintainability || "Unknown")
+      }
+    };
+  }).filter((item) => item.summary && item.steps.length > 0);
+  const fixPlans = normalizedFixPlans.length >= 3 ? normalizedFixPlans.slice(0, 3) : [
+    {
+      plan: "fast_patch",
+      summary: stringifyField(data.fix),
+      steps: [stringifyField(data.fix) || "Apply a defensive guard around the failing line."],
+      tradeoffs: {
+        risk: "May hide deeper data contract issues.",
+        performance: "Minimal runtime overhead.",
+        maintainability: "Good short-term, revisit for root-cause cleanup."
+      }
+    },
+    {
+      plan: "proper_fix",
+      summary: "Fix data flow and initialization path.",
+      steps: [
+        "Trace where the failing value is created.",
+        "Initialize value before usage and add proper null checks.",
+        "Add a regression test for this scenario."
+      ],
+      tradeoffs: {
+        risk: "Moderate code changes.",
+        performance: "Neutral to slightly improved.",
+        maintainability: "Better long-term readability and reliability."
+      }
+    },
+    {
+      plan: "long_term_fix",
+      summary: "Enforce stronger contracts and prevention tooling.",
+      steps: [
+        "Enable stricter type checks and lint rules.",
+        "Introduce runtime validation for external inputs.",
+        "Create reusable utility guards in shared modules."
+      ],
+      tradeoffs: {
+        risk: "Requires broader refactor.",
+        performance: "Potential minor validation overhead.",
+        maintainability: "Highest long-term stability."
+      }
+    }
+  ];
+  const frameworkRecipesRaw = Array.isArray(data.framework_recipes) ? data.framework_recipes : [];
+  const frameworkRecipes = frameworkRecipesRaw.map((item) => {
+    const row = item;
+    return {
+      framework: stringifyField(row?.framework),
+      when_to_use: stringifyField(row?.when_to_use),
+      steps: toStringArray(row?.steps),
+      code_snippet: stringifyField(row?.code_snippet)
+    };
+  }).filter(
+    (item) => item.framework && item.when_to_use && item.steps.length > 0 && item.code_snippet
+  );
+  const remediationBlocksRaw = Array.isArray(data.remediation_blocks) ? data.remediation_blocks : [];
+  const remediationBlocks = remediationBlocksRaw.map((item) => {
+    const row = item;
+    return {
+      title: stringifyField(row?.title),
+      commands: toStringArray(row?.commands),
+      snippet: stringifyField(row?.snippet) || void 0
+    };
+  }).filter((item) => item.title && item.commands.length > 0);
+  const verifyChecklist = toStringArray(data.verify_checklist);
+  const title = stringifyField(data.title);
+  const explanation = stringifyField(data.explanation);
+  const codeExample = stringifyField(data.code_example);
+  const fix = stringifyField(data.fix);
+  const likelyRootCause = stringifyField(data.likely_root_cause) || commonCauses[0] || "Insufficient context from error text.";
   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)
+    title: title || "Unknown error",
+    explanation: explanation || "Unable to derive explanation from model response.",
+    common_causes: commonCauses.length > 0 ? commonCauses : ["Insufficient context in provided error text."],
+    fix: fix || "Add guards and trace value initialization before the failing line.",
+    code_example: codeExample || "// Add null checks around the failing line.",
+    eli5: stringifyField(data.eli5) || "Your code expected one thing, but got something different.",
+    likely_root_cause: likelyRootCause,
+    hypotheses: hypotheses.length > 0 ? hypotheses : [
+      {
+        hypothesis: likelyRootCause,
+        confidence: 0.6,
+        why: "Derived from error pattern and available context."
+      }
+    ],
+    fix_plans: fixPlans,
+    framework_recipes: frameworkRecipes.length > 0 ? frameworkRecipes : [
+      {
+        framework: "Node.js",
+        when_to_use: "Default runtime fallback when framework is unknown.",
+        steps: [
+          "Validate all external data before use.",
+          "Guard nullable values before method calls.",
+          "Add test coverage for this failure path."
+        ],
+        code_snippet: "const safeValue = input ?? defaultValue;"
+      }
+    ],
+    remediation_blocks: remediationBlocks.length > 0 ? remediationBlocks : [
+      {
+        title: "Quick remediation commands",
+        commands: ["npm run test", "npm run lint"]
+      }
+    ],
+    verify_checklist: verifyChecklist.length > 0 ? verifyChecklist : ["Re-run failing command.", "Confirm no regression in related flows."]
   };
 }
-async function explainErrorWithAI(errorMessage) {
+async function explainErrorWithAI(errorMessage, context = {}) {
   const apiKey = process.env.GROQ_API_KEY;
   if (!apiKey) {
     throw new Error(
@@ -159,14 +328,44 @@ async function explainErrorWithAI(errorMessage) {
       ].join("\n")
     );
   }
-  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 prompt = `You are a senior software engineer helping debug errors with context.
+Return STRICT JSON only (no markdown) with fields:
+- title
+- explanation
+- common_causes (string[])
+- fix
+- code_example
+- eli5
+- likely_root_cause
+- hypotheses (2-3 items): [{ hypothesis, confidence (0..1), why }]
+- fix_plans (exactly 3): [
+  { plan: "fast_patch", summary, steps[], tradeoffs: { risk, performance, maintainability } },
+  { plan: "proper_fix", summary, steps[], tradeoffs: { risk, performance, maintainability } },
+  { plan: "long_term_fix", summary, steps[], tradeoffs: { risk, performance, maintainability } }
+]
+- framework_recipes (1+): [{ framework, when_to_use, steps[], code_snippet }]
+- remediation_blocks (1+): [{ title, commands[], snippet? }]
+- verify_checklist (string[])
+
+Use provided runtime/framework/code/stack context to produce context-aware likely root cause and framework-specific fixes.`;
+  const contextBlock = [
+    `Error message:
+${errorMessage}`,
+    `Runtime:
+${context.runtime ?? "unknown"}`,
+    `Framework:
+${context.framework ?? "unknown"}`,
+    `Stack trace:
+${context.stackTrace ?? "not provided"}`,
+    `Code snippet:
+${context.codeSnippet ?? "not provided"}`
+  ].join("\n\n");
   const requestBody = {
     messages: [
       { role: "system", content: prompt },
       {
         role: "user",
-        content: `Error message:
-${errorMessage}
+        content: `${contextBlock}
 
 Return strict JSON only.`
       }
@@ -229,8 +428,42 @@ 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 list(items) {
+  return items.map((item, index) => `${index + 1}. ${item}`).join("\n");
+}
 function formatExplainedError(result) {
-  const commonCauses = result.common_causes.map((cause, index) => pc.white(`${index + 1}. ${cause}`)).join("\n");
+  const commonCauses = list(result.common_causes);
+  const hypotheses = result.hypotheses.map(
+    (item, index) => `${index + 1}. ${item.hypothesis}
+   confidence: ${(item.confidence * 100).toFixed(0)}%
+   why: ${item.why}`
+  ).join("\n\n");
+  const fixPlans = result.fix_plans.map((plan) => {
+    const label = plan.plan === "fast_patch" ? "Fast Patch" : plan.plan === "proper_fix" ? "Proper Fix" : "Long-Term Fix";
+    return [
+      `${pc.bold(pc.green(label))}: ${plan.summary}`,
+      ...plan.steps.map((step, index) => `  ${index + 1}. ${step}`),
+      `  tradeoffs -> risk: ${plan.tradeoffs.risk}; performance: ${plan.tradeoffs.performance}; maintainability: ${plan.tradeoffs.maintainability}`
+    ].join("\n");
+  }).join("\n\n");
+  const frameworkRecipes = result.framework_recipes.map(
+    (recipe) => [
+      `${pc.bold(pc.cyan(recipe.framework))}: ${recipe.when_to_use}`,
+      ...recipe.steps.map((step, index) => `  ${index + 1}. ${step}`),
+      "  snippet:",
+      recipe.code_snippet.split("\n").map((lineText) => `    ${lineText}`).join("\n")
+    ].join("\n")
+  ).join("\n\n");
+  const remediationBlocks = result.remediation_blocks.map((blockItem) => {
+    const snippet = blockItem.snippet?.trim() ? `
+  snippet:
+${blockItem.snippet.split("\n").map((lineText) => `    ${lineText}`).join("\n")}` : "";
+    return [
+      `${pc.bold(pc.green(blockItem.title))}`,
+      ...blockItem.commands.map((command) => `  $ ${command}`)
+    ].join("\n") + snippet;
+  }).join("\n\n");
+  const verifyChecklist = list(result.verify_checklist);
   const hero = [
     pc.cyan(line("=")),
     framedLine(pc.bold(pc.cyan("EXPLAIN MY ERROR"))),
@@ -241,16 +474,27 @@ function formatExplainedError(result) {
     hero,
     "",
     `${pc.bold(pc.cyan("ERROR"))}: ${pc.bold(pc.white(result.title))}`,
+    `${pc.bold(pc.yellow("LIKELY ROOT CAUSE"))}: ${pc.white(result.likely_root_cause)}`,
     "",
     block("EXPLANATION", result.explanation),
     "",
     block("COMMON CAUSES", commonCauses),
     "",
+    block("HYPOTHESES (WITH CONFIDENCE)", hypotheses),
+    "",
+    block("RANKED FIX PLANS", fixPlans),
+    "",
     `${pc.bold(pc.green("FIX"))}
 ${pc.white(result.fix)}`,
     "",
     block("CODE EXAMPLE", result.code_example),
     "",
+    block("FRAMEWORK-SPECIFIC RECIPES", frameworkRecipes),
+    "",
+    block("COPY-PASTE REMEDIATION", remediationBlocks),
+    "",
+    block("VERIFY CHECKLIST", verifyChecklist),
+    "",
     block("ELI5", result.eli5),
     "",
     pc.dim('Tip: run `eme explain "<error>"` for quick mode.')
@@ -279,7 +523,16 @@ var logger = {
 };
 
 // src/commands/explain.ts
-async function runExplainCommand(errorMessage, deps = {}) {
+function isDepsObject(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return "explainError" in candidate || "createSpinner" in candidate || "formatOutput" in candidate || "log" in candidate;
+}
+async function runExplainCommand(errorMessage, optionsOrDeps = { output: "pretty" }, depsArg = {}) {
+  const options = isDepsObject(optionsOrDeps) ? { output: "pretty" } : optionsOrDeps;
+  const deps = isDepsObject(optionsOrDeps) ? optionsOrDeps : depsArg;
   const explainError = deps.explainError ?? explainErrorWithAI;
   const createSpinner = deps.createSpinner ?? ((text) => ora(text).start());
   const formatOutput = deps.formatOutput ?? formatExplainedError;
@@ -290,10 +543,14 @@ async function runExplainCommand(errorMessage, deps = {}) {
   }
   const spinner = createSpinner("Analyzing your error...");
   try {
-    const result = await explainError(errorMessage.trim());
+    const result = await explainError(errorMessage.trim(), options.context);
     spinner.succeed("Explanation ready.");
     log.info("");
-    log.info(formatOutput(result));
+    if (options.output === "json") {
+      log.info(JSON.stringify(result, null, 2));
+    } else {
+      log.info(formatOutput(result));
+    }
   } catch (error) {
     spinner.fail("Could not explain this error.");
     const message = error instanceof Error ? error.message : "Unknown error";
@@ -321,6 +578,46 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf8").trim();
 }
+async function safeReadText(filePath) {
+  if (!filePath) {
+    return void 0;
+  }
+  try {
+    return await readFile(filePath, "utf8");
+  } catch {
+    return void 0;
+  }
+}
+async function detectFrameworkFromPackageJson() {
+  try {
+    const raw = await readFile("package.json", "utf8");
+    const pkg = JSON.parse(raw);
+    const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+    if ("next" in deps) return "Next.js";
+    if ("react" in deps) return "React";
+    if ("express" in deps) return "Express";
+    if ("typescript" in deps) return "TypeScript";
+    if ("fastify" in deps) return "Fastify";
+    if ("nestjs" in deps || "@nestjs/core" in deps) return "NestJS";
+  } catch {
+  }
+  return void 0;
+}
+async function buildExplainOptions(options) {
+  const stackFromFile = await safeReadText(options.stackFile);
+  const codeFromFile = await safeReadText(options.codeFile);
+  const detectedFramework = await detectFrameworkFromPackageJson();
+  const context = {
+    stackTrace: options.stack ?? stackFromFile,
+    codeSnippet: options.code ?? codeFromFile,
+    runtime: options.runtime ?? `Node ${process.version}`,
+    framework: options.framework ?? detectedFramework ?? "unknown"
+  };
+  return {
+    output: options.json ? "json" : "pretty",
+    context
+  };
+}
 async function promptForError() {
   if (!process.stdin.isTTY) {
     return "";
@@ -427,32 +724,58 @@ Input modes:
   3) Pipe from files/commands
      $ cat error.txt | explain-my-error
      $ pnpm run build 2>&1 | eme
+
+Power features:
+  - Context-aware analysis: pass stack traces, code snippets, runtime, and framework.
+  - Structured output: use --json for machine-readable responses.
+  - Auto framework detection: best-effort detection from local package.json.
 `
   );
-  program.command("explain").description("Explain a programming error message").argument("[error...]", "Error message to analyze").addHelpText(
+  program.command("explain").description("Explain a programming error message").argument("[error...]", "Error message to analyze").option("--json", "Output structured JSON").option("--stack <stackTrace>", "Additional stack trace context").option("--stack-file <path>", "Read stack trace from a file").option("--code <codeSnippet>", "Additional code snippet context").option("--code-file <path>", "Read code snippet from a file").option("--runtime <runtime>", "Runtime context (example: node 20, bun 1.1)").option("--framework <framework>", "Framework context (example: react, nextjs, express)").addHelpText(
     "after",
     `
+Context options:
+  --stack       inline stack trace text
+  --stack-file  file path for stack trace
+  --code        inline code snippet text
+  --code-file   file path for code snippet
+  --runtime     runtime label (default: current Node version)
+  --framework   framework label (auto-detected when possible)
+
+Output modes:
+  default pretty output includes:
+    - likely root cause
+    - 2-3 hypotheses with confidence
+    - ranked fix plans (fast/proper/long-term) with tradeoffs
+    - framework-specific recipes
+    - remediation commands and verify checklist
+
+  --json output includes the same data in machine-readable JSON.
+
 Examples:
   $ explain-my-error explain "SyntaxError: Unexpected token }"
   $ eme explain "Module not found: Can't resolve 'axios'"
   $ cat error.txt | explain-my-error explain
+  $ eme explain "TypeError: Cannot read property 'map' of undefined" --framework react --runtime "node 20"
+  $ eme explain --stack-file ./error.log --code-file ./src/app.ts --json
 `
-  ).action(async (errorParts) => {
+  ).action(async (errorParts, options) => {
     const inlineError = errorParts.join(" ").trim();
     const pipedError = inlineError ? "" : await readStdinFn();
     const promptedError = !inlineError && !pipedError ? await promptForErrorFn() : "";
     const finalError = inlineError || pipedError || promptedError;
+    const explainOptions = await buildExplainOptions(options);
     const hasApiKey = await ensureApiKeyFn();
     if (!hasApiKey) {
       log.warn("GROQ_API_KEY is required. Set it and run again.");
       return;
     }
-    await runExplain(finalError);
+    await runExplain(finalError, explainOptions);
   });
   program.action(async () => {
     if (stdinIsTTY()) {
       const promptedError = await promptForErrorFn();
-      await runExplain(promptedError);
+      await runExplain(promptedError, await buildExplainOptions({}));
       return;
     }
     const pipedError = await readStdinFn();
@@ -465,7 +788,7 @@ Examples:
       log.warn("GROQ_API_KEY is required. Set it and run again.");
       return;
     }
-    await runExplain(pipedError);
+    await runExplain(pipedError, await buildExplainOptions({}));
   });
   await program.parseAsync(argv);
 }