snapfail 0.0.22 → 0.0.24

package/dist/index.js

@@ -1938,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.
 
@@ -1952,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
 
@@ -1968,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.
 `;
 }
 
@@ -2316,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"]);
@@ -2392,6 +2407,19 @@ async function runExplain(opts) {
 `);
 }
 
+// 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
 function parseArgs(argv) {
   const [, , rawCommand = "incidents", ...rest] = argv;
@@ -2426,6 +2454,10 @@ async function main() {
       await runInit();
       return;
     }
+    if (command === "skill") {
+      await runSkill();
+      return;
+    }
     if (command === "incidents") {
       await runIncidents({
         json,
@@ -2457,7 +2489,7 @@ async function main() {
       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,19 +1,13 @@
 {
   "name": "snapfail",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "type": "module",
   "description": "CLI for snapfail — project setup, incident inspection and AI diagnostics",
   "license": "MIT",
   "bin": {
-    "snapfail": "./src/index.ts"
-  },
-  "main": "./src/index.ts",
-  "publishConfig": {
-    "bin": {
-      "snapfail": "./dist/index.js"
-    },
-    "main": "./dist/index.js"
+    "snapfail": "./dist/index.js"
   },
+  "main": "./dist/index.js",
   "files": ["dist"],
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target bun --format esm --sourcemap=none",

package/src/index.ts

@@ -1,97 +0,0 @@
-#!/usr/bin/env bun
-import { runIncidents } from "./commands/incidents.ts";
-import { runIncident } from "./commands/incident.ts";
-import { runInit } from "./commands/init.ts";
-import { runExplain } from "./commands/explain.ts";
-
-function parseArgs(argv: string[]): {
-  command: string;
-  args: string[];
-  flags: Record<string, string | boolean>;
-} {
-  const [, , rawCommand = "incidents", ...rest] = argv;
-  const command = rawCommand;
-  const args: string[] = [];
-  const flags: Record<string, string | boolean> = {};
-
-  for (const token of rest) {
-    if (token.startsWith("--")) {
-      const eq = token.indexOf("=");
-      if (eq !== -1) {
-        flags[token.slice(2, eq)] = token.slice(eq + 1);
-      } else {
-        flags[token.slice(2)] = true;
-      }
-    } else {
-      args.push(token);
-    }
-  }
-
-  return { command, args, flags };
-}
-
-const VERSION = "0.0.18";
-
-async function main(): Promise<void> {
-  const { command, args, flags } = parseArgs(process.argv);
-  const json = flags["json"] === true;
-  const pk = typeof flags["pk"] === "string" ? flags["pk"] : undefined;
-
-  if (command === "--version" || command === "-v" || flags["version"] === true) {
-    console.log(VERSION);
-    return;
-  }
-
-  try {
-    if (command === "init") {
-      await runInit();
-      return;
-    }
-
-    if (command === "incidents") {
-      await runIncidents({
-        json,
-        pk,
-        status: typeof flags["status"] === "string" ? flags["status"] : undefined,
-        limit: typeof flags["limit"] === "string" ? parseInt(flags["limit"]) : undefined,
-        offset: typeof flags["offset"] === "string" ? parseInt(flags["offset"]) : undefined,
-      });
-      return;
-    }
-
-    if (command === "incident") {
-      const id = args[0];
-      if (!id) {
-        console.error("Usage: snapfail incident <id> [--sample <n>] [--json]");
-        process.exit(1);
-      }
-      const sampleFlag = flags["sample"];
-      const sample =
-        typeof sampleFlag === "string" ? parseInt(sampleFlag) : undefined;
-      await runIncident({ id, sample, json, pk, delete: flags["delete"] === true });
-      return;
-    }
-
-    if (command === "explain") {
-      const id = args[0];
-      if (!id) {
-        console.error("Usage: snapfail explain <id> [--force] [--json]");
-        process.exit(1);
-      }
-      await runExplain({ id, json, pk });
-      return;
-    }
-
-    console.error(`Unknown command: ${command}`);
-    console.error(`snapfail v${VERSION} — Usage: snapfail [incidents|incident|init|explain] [--version]`);
-    process.exit(1);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`Error: ${message}`);
-    process.exit(1);
-  }
-}
-
-if (import.meta.main) {
-  main();
-}