snapfail 0.0.21 → 0.0.23

package/dist/index.js

@@ -267,6 +267,68 @@ function formatIncidentList(data, total, status) {
   ${bold(String(total))} ${status ?? "unresolved"} incident${total !== 1 ? "s" : ""}`;
   return table + summary;
 }
+function formatLLMContext(group, samples) {
+  const lines = [];
+  lines.push(`# Incident: ${group.title}`);
+  lines.push(`Group ID: ${group.id}`);
+  lines.push(`Fingerprint: ${group.fingerprint}`);
+  lines.push(`Occurrences: ${group.count}  |  First: ${new Date(group.firstSeen).toISOString()}  |  Last: ${new Date(group.lastSeen).toISOString()}`);
+  lines.push(`Environments: ${group.environments.join(", ")}`);
+  lines.push(`Status: ${group.status}`);
+  lines.push("");
+  lines.push("## Error");
+  lines.push(`Type: ${group.errorType}`);
+  lines.push(`Message: ${samples[0]?.errorMessage ?? group.title}`);
+  lines.push(`Normalized: ${samples[0]?.normalizedMessage ?? group.title}`);
+  if (samples[0] && samples[0].stackFrames.length > 0) {
+    lines.push("");
+    lines.push("## Stack");
+    for (const f of samples[0].stackFrames) {
+      lines.push(`  ${f.fn ?? "(anonymous)"}  ${f.file}:${f.line}${f.col != null ? `:${f.col}` : ""}`);
+    }
+  }
+  for (let i = 0;i < samples.length; i++) {
+    const s = samples[i];
+    lines.push("");
+    lines.push(`## Sample ${i + 1} / ${group.sampleIds.length}`);
+    lines.push(`Device: ${s.device.userAgent}`);
+    if (s.device.viewport) {
+      lines.push(`Viewport: ${s.device.viewport.width}x${s.device.viewport.height}  Language: ${s.device.language ?? "unknown"}`);
+    }
+    lines.push(`URL: ${s.url}`);
+    if (s.route)
+      lines.push(`Route: ${s.route}`);
+    lines.push(`Environment: ${s.environmentMode}`);
+    if (s.consoleEntries.length > 0) {
+      lines.push("");
+      lines.push("### Console");
+      for (const e of s.consoleEntries) {
+        const args = e.args.map((a) => String(a)).join(" ");
+        lines.push(`  [${e.level}] ${args}`);
+      }
+    }
+    if (s.networkEntries.length > 0) {
+      lines.push("");
+      lines.push("### Network");
+      for (const n of s.networkEntries) {
+        const status = n.status ? ` \u2192 ${n.status}` : n.error ? ` \u2192 ERROR` : "";
+        lines.push(`  ${n.method} ${n.url}${status} (${n.durationMs}ms)`);
+      }
+    }
+    if (s.timeline.length > 0) {
+      lines.push("");
+      lines.push("### Timeline");
+      for (const e of s.timeline) {
+        lines.push(`  +${e.t}ms  ${e.kind}: ${e.summary}`);
+      }
+    }
+    if (i < samples.length - 1)
+      lines.push(`
+---`);
+  }
+  return lines.join(`
+`);
+}
 function formatIncidentDetail(group, sample) {
   const lines = [];
   lines.push(bold(`${group.errorType}: ${truncate(group.title, 80)}`));
@@ -1876,9 +1938,7 @@ ${r2}
 }).prompt();
 
 // src/skill.ts
-function generateSkillMd(config, framework) {
-  return `# snapfail
-
+var SKILL_BODY = `
 snapfail captures browser error context (stack, console, network, replay timeline)
 and stores it so you can diagnose root causes. Evidence is structured for LLM reasoning.
 
@@ -1890,14 +1950,18 @@ When the user reports an error or unexpected behavior in their app, run:
 snapfail incidents --json
 \`\`\`
 
-Then drill into a specific incident:
+Then get full structured context for a specific incident:
 
 \`\`\`
-snapfail incident <id> --json
+snapfail explain <id>
 \`\`\`
 
-**Always use \`--json\` when querying from the LLM** \u2014 it returns structured data
-without ANSI color codes.
+\`snapfail explain\` outputs all captured evidence (stack, console, network, timeline, device,
+multiple samples) formatted as structured text. **Read it and reason about the root cause
+yourself** \u2014 do not delegate this to another model.
+
+**Always use \`--json\` when querying from the LLM** for \`incidents\` and \`incident\` \u2014
+it returns structured data without ANSI color codes.
 
 ## Commands
 
@@ -1906,34 +1970,47 @@ snapfail incidents [--status=unresolved|resolved|ignored] [--json]
   List incident groups. Default status: unresolved.
 
 snapfail incident <id> [--sample <n>] [--json]
-  Show incident detail: group summary + most recent sample (stack, console, network, timeline).
-  Use --sample <n> (0-indexed) to compare different occurrences of the same error.
+  Group summary + one sample (stack, console, network, timeline).
+  Use --sample <n> (0-indexed) to compare different occurrences.
 
 snapfail explain <id>
-  AI diagnosis: root cause, plain summary, fix prompt. (requires @snapfail/ai)
+  Outputs structured evidence for up to 3 samples. Read and diagnose directly.
 \`\`\`
 
+All commands accept \`--pk <project_key>\` to override the project key from \`.env\`.
+
 ## Interpreting an incident
 
-Key fields from \`snapfail incident <id> --json\`:
+Key fields:
 
 - \`group.title\` \u2014 normalized error message (dynamic values replaced with [uuid], [id], etc.)
-- \`group.count\` \u2014 total occurrences
-- \`group.environments\` \u2014 where it happened: "dev" | "prod"
+- \`group.count\` \u2014 total occurrences (\u2260 number of groups)
+- \`group.environments\` \u2014 "dev" | "prod"
 - \`group.severity\` \u2014 "critical" | "error" | "warning"
 - \`sample.stackFrames\` \u2014 call stack at the time of the error
-- \`sample.consoleEntries\` \u2014 last ~15s of console output before the error
-- \`sample.networkEntries\` \u2014 last ~15s of network requests (scrubbed)
-- \`sample.timeline\` \u2014 derived user interaction sequence (clicks, navigation, mutations)
+- \`sample.consoleEntries\` \u2014 console output before the error
+- \`sample.networkEntries\` \u2014 network requests (auth headers scrubbed)
+- \`sample.timeline\` \u2014 user interaction sequence (clicks, navigation, mutations)
+- \`sample.device.userAgent\` \u2014 browser/OS \u2014 critical for mobile/in-app browser bugs
 - \`sample.url\` / \`sample.route\` \u2014 where the error occurred
-
+`;
+function generateSkillMd(config, framework) {
+  return `# snapfail
+${SKILL_BODY}
 ## Config
 
 Project key: \`${config.projectKey}\`
 Endpoint: \`${config.endpoint}\`
-${framework ? `Framework: ${framework}
-` : ""}
-Config file: \`.snapfail.json\` (gitignored)
+${framework ? `Framework: \`${framework}\`
+` : ""}`;
+}
+function generateGlobalSkillMd() {
+  return `# snapfail
+${SKILL_BODY}
+## Project key
+
+The project key is read automatically from \`SNAPFAIL_PROJECT_KEY\` in \`.env\` or the shell.
+Pass \`--pk <key>\` to override when querying a specific project.
 `;
 }
 
@@ -2254,10 +2331,10 @@ async function runInit(cwd = process.cwd()) {
     writeProjectKey(selectedKey, cwd, "NEXT_PUBLIC_SNAPFAIL_PROJECT_KEY");
   addToGitignore(cwd, ".env");
   log.success("SNAPFAIL_PROJECT_KEY written to .env");
-  const skillDir = join2(cwd, ".agents", "skills", "snapfail");
+  const skillDir = join2(cwd, ".claude", "skills", "snapfail");
   mkdirSync2(skillDir, { recursive: true });
   writeFileSync3(join2(skillDir, "SKILL.md"), generateSkillMd({ projectKey: selectedKey, endpoint: DEFAULT_ENDPOINT }, framework), "utf-8");
-  log.success("SKILL.md created at .agents/skills/snapfail/SKILL.md");
+  log.success("SKILL.md created at .claude/skills/snapfail/SKILL.md");
   const pm = detectPackageManager(cwd);
   if (framework === "astro") {
     const cfg = findConfigFile(cwd, ["astro.config.ts", "astro.config.mjs", "astro.config.js"]);
@@ -2306,70 +2383,41 @@ async function runInit(cwd = process.cwd()) {
 }
 
 // src/commands/explain.ts
-async function fetchDiagnosis(config, id, force) {
-  const url = new URL(`${config.endpoint}/api/diagnose/${id}`);
-  if (force)
-    url.searchParams.set("force", "1");
-  let res;
-  try {
-    res = await fetch(url.toString(), {
-      method: "POST",
-      headers: { "X-Project-Key": config.projectKey, "Content-Type": "application/json" },
-      body: "{}"
-    });
-  } catch (err) {
-    throw new Error(`Network error: ${err instanceof Error ? err.message : String(err)}`);
-  }
-  if (res.status === 401)
-    throw new Error("Unauthorized: check your project key.");
-  if (res.status === 404)
-    return null;
-  if (res.status === 422)
-    throw new Error("No samples available to diagnose this incident.");
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new Error(`API error ${res.status}: ${body}`);
-  }
-  return res.json();
-}
-function confidenceColor(c3) {
-  if (c3 === "high")
-    return green(c3);
-  if (c3 === "medium")
-    return yellow(c3);
-  return red(c3);
-}
-function formatDiagnosis(d) {
-  const lines = [];
-  lines.push(bold("Root cause"));
-  lines.push(`  ${d.rootCause}`);
-  lines.push("");
-  lines.push(bold("In plain language"));
-  lines.push(`  ${d.plainSummary}`);
-  if (d.fixPrompt) {
-    lines.push("");
-    lines.push(bold("Fix prompt") + dim(" (paste into your AI assistant)"));
-    lines.push(`  ${d.fixPrompt}`);
-  }
-  lines.push("");
-  lines.push(dim("Confidence:") + " " + confidenceColor(d.confidence) + dim("  \xB7  analyzed ") + d.analyzedSampleIds.length + dim(" samples  \xB7  model: ") + dim(d.model));
-  return lines.join(`
-`);
-}
 async function runExplain(opts) {
   requireSession();
   const config = loadConfig(process.cwd(), opts.pk);
-  const diagnosis = await fetchDiagnosis(config, opts.id, opts.force ?? false);
-  if (!diagnosis) {
+  const result = await fetchIncident(config, opts.id);
+  if (!result) {
     console.error(`Incident ${opts.id} not found.`);
     process.exit(1);
   }
+  const { group, sample } = result;
+  const samples = [sample];
+  for (let i2 = 1;i2 < Math.min(group.sampleIds.length, 3); i2++) {
+    const s = await fetchSample(config, opts.id, i2);
+    if (s)
+      samples.push(s);
+  }
   if (opts.json) {
-    process.stdout.write(JSON.stringify(diagnosis, null, 2) + `
+    process.stdout.write(JSON.stringify({ group, samples }, null, 2) + `
 `);
     return;
   }
-  console.log(formatDiagnosis(diagnosis));
+  process.stdout.write(formatLLMContext(group, samples) + `
+`);
+}
+
+// src/commands/skill.ts
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync3, existsSync as existsSync4 } from "fs";
+import { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
+var SKILL_DIR = join3(homedir2(), ".claude", "skills", "snapfail");
+var SKILL_FILE = join3(SKILL_DIR, "SKILL.md");
+async function runSkill() {
+  mkdirSync3(SKILL_DIR, { recursive: true });
+  const existed = existsSync4(SKILL_FILE);
+  writeFileSync4(SKILL_FILE, generateGlobalSkillMd(), "utf-8");
+  console.log(existed ? `Updated ${SKILL_FILE}` : `Created ${SKILL_FILE}`);
 }
 
 // src/index.ts
@@ -2406,6 +2454,10 @@ async function main() {
       await runInit();
       return;
     }
+    if (command === "skill") {
+      await runSkill();
+      return;
+    }
     if (command === "incidents") {
       await runIncidents({
         json,
@@ -2433,11 +2485,11 @@ async function main() {
         console.error("Usage: snapfail explain <id> [--force] [--json]");
         process.exit(1);
       }
-      await runExplain({ id, force: flags["force"] === true, json, pk });
+      await runExplain({ id, json, pk });
       return;
     }
     console.error(`Unknown command: ${command}`);
-    console.error(`snapfail v${VERSION} \u2014 Usage: snapfail [incidents|incident|init|explain] [--version]`);
+    console.error(`snapfail v${VERSION} \u2014 Usage: snapfail [incidents|incident|init|explain|skill] [--version]`);
     process.exit(1);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapfail",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "type": "module",
   "description": "CLI for snapfail — project setup, incident inspection and AI diagnostics",
   "license": "MIT",

package/src/index.ts

@@ -3,6 +3,7 @@ import { runIncidents } from "./commands/incidents.ts";
 import { runIncident } from "./commands/incident.ts";
 import { runInit } from "./commands/init.ts";
 import { runExplain } from "./commands/explain.ts";
+import { runSkill } from "./commands/skill.ts";
 
 function parseArgs(argv: string[]): {
   command: string;
@@ -48,6 +49,11 @@ async function main(): Promise<void> {
       return;
     }
 
+    if (command === "skill") {
+      await runSkill();
+      return;
+    }
+
     if (command === "incidents") {
       await runIncidents({
         json,
@@ -78,12 +84,12 @@ async function main(): Promise<void> {
         console.error("Usage: snapfail explain <id> [--force] [--json]");
         process.exit(1);
       }
-      await runExplain({ id, force: flags["force"] === true, json, pk });
+      await runExplain({ id, json, pk });
       return;
     }
 
     console.error(`Unknown command: ${command}`);
-    console.error(`snapfail v${VERSION} — Usage: snapfail [incidents|incident|init|explain] [--version]`);
+    console.error(`snapfail v${VERSION} — Usage: snapfail [incidents|incident|init|explain|skill] [--version]`);
     process.exit(1);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);