failsnap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FailSnap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# FailSnap
+
+> Capture a failed dev command. Paste it into any AI. Get a real answer.
+
+When something breaks, you waste time copy-pasting terminal output, hunting down your Node version, and re-explaining your project setup — every single time. FailSnap does all of that automatically in one command.
+
+![FailSnap demo](./demo.gif)
+
+---
+
+## What it does
+
+Run any command through FailSnap:
+
+```bash
+failsnap npm run dev
+```
+
+If the command fails, FailSnap saves a structured Markdown report to `.failsnap/latest.md` — ready to paste directly into Claude, ChatGPT, Cursor, or any AI.
+
+If the command succeeds, nothing happens. Zero noise.
+
+The report includes everything an AI needs to actually help you:
+
+- The full command output (stdout + stderr)
+- Your OS, shell, Node / npm / Python / Java versions
+- Git branch and status
+- Relevant config files (`package.json`, `tsconfig.json`, `pyproject.toml`, etc.)
+- Project type auto-detected (Node, Python, Java, …)
+- **Secrets automatically masked** before anything is written to disk
+
+---
+
+## Install
+
+```bash
+npm install -g failsnap
+```
+
+Requires Node.js 18+. Works on Linux, macOS, and Windows.
+
+---
+
+## Usage
+
+### One-shot capture
+
+Prefix any command with `failsnap`:
+
+```bash
+failsnap npm run dev
+failsnap python main.py
+failsnap cargo build
+```
+
+### Paste to AI immediately
+
+```bash
+failsnap copy          # copy the latest report to your clipboard
+```
+
+### Watch mode
+
+For longer sessions, start a persistent shell that captures every failing
+command automatically — no need to prefix each one with `failsnap`:
+
+```bash
+failsnap shell
+```
+
+```console
+$ failsnap shell
+[failsnap] monitored shell started (/bin/bash)
+[failsnap] failed commands are captured to .failsnap/latest.md automatically
+[failsnap] cd / export / source / aliases all persist across commands
+[failsnap] type "exit" to leave
+[failsnap] ~/project $ npm test
+
+... test output ...
+
+[failsnap] command failed (exit code 1)
+[failsnap] report:   ~/project/.failsnap/latest.md
+[failsnap] raw log:  ~/project/.failsnap/latest.log
+[failsnap] snapshot: ~/project/.failsnap/snapshots/2026-06-12_01-50-09
+[failsnap] ~/project $ export API_BASE=http://localhost:3000
+[failsnap] ~/project $ exit
+[failsnap] bye
+```
+
+The shell keeps your `cd`, `export`, `source`, and `alias` state across
+commands — just like your normal terminal. Successful commands run normally;
+only failures are snapshotted.
+
+### Other commands
+
+```bash
+failsnap last          # print the path of the latest report
+failsnap doctor        # preview what would be collected, without running anything
+failsnap clean         # delete the .failsnap/ directory (reports + snapshots)
+```
+
+---
+
+## Why not just copy-paste the terminal output?
+
+| | Copy-paste | FailSnap |
+|---|---|---|
+| Command output | ✅ | ✅ |
+| Runtime versions | ❌ manual | ✅ auto |
+| Git state | ❌ manual | ✅ auto |
+| Config files | ❌ manual | ✅ auto |
+| Secret masking | ❌ none | ✅ best-effort |
+| Repeatable | ❌ | ✅ |
+
+The difference is context. An AI that knows your Node version, your `tsconfig`, and your git branch gives a different answer than one that just sees a stack trace.
+
+---
+
+## Security
+
+FailSnap is fully local. No server, no account, no telemetry, no network.
+
+Secrets are masked before anything is written to disk using pattern matching for common formats: API keys, tokens, PEM private key blocks, Bearer headers, URL credentials, and more.
+
+**This is best-effort masking, not a guarantee.** Pattern-based detection can miss novel or custom secret formats. Before sharing a report outside your machine, review it — `failsnap last` prints its path.
+
+`.failsnap/` is automatically added to your `.gitignore`.
+
+---
+
+## How the report looks
+
+Generated by `failsnap node app.js` in a small Node project, where `app.js`
+imports a module that doesn't exist (front of the report shown; output and
+later sections elided):
+
+````markdown
+# FailSnap Report
+
+Generated: 2026-06-11T16:48:52.015Z
+
+## Failed Command
+
+- **Command:** `node app.js`
+- **Exit code:** 1
+- **Duration:** 29ms
+- **Directory:** `/tmp/failsnap-demo`
+
+## Environment
+
+| | |
+|---|---|
+| **OS** | Linux 5.15.0-139-generic (x64) |
+| **Shell** | /bin/bash |
+| **Working directory** | /tmp/failsnap-demo |
+| **Node** | v24.16.0 |
+| **npm** | 11.13.0 |
+| **pnpm** | not found |
+| **Python** | Python 3.8.10 |
+| **Java** | not found |
+| **Git branch** | not a git repository |
+| **Git status** | n/a |
+
+## Project
+
+Detected project type: **Node.js**
+
+## Command Output
+
+```text
+...
+Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/tmp/failsnap-demo/nope.js' imported from /tmp/failsnap-demo/app.js
+    at finalizeResolution (node:internal/modules/esm/resolve:271:11)
+    ...
+```
+````
+
+The full report continues with a **Relevant Files** section (your
+`package.json`, `tsconfig.json`, … redacted and inlined) and an
+**AI Debugging Prompt** that tells the AI exactly what to give back: root
+cause, exact fix, commands to run, files to edit, and verification steps.
+
+---
+
+## Limitations
+
+- Secret masking is pattern-based. Review reports before sharing externally.
+- Very large outputs are truncated (first 200 / last 800 lines kept).
+- Shell built-ins (`export`, `source`) persist within a `failsnap shell` session but not across sessions.
+- Windows clipboard uses `clip`; Linux requires `wl-copy`, `xclip`, or `xsel` to be installed.
+
+---
+
+## Contributing
+
+Issues and PRs welcome. Run tests with:
+
+```bash
+npm run build
+npx vitest run
+```
+
+---
+
+## License
+
+MIT

package/dist/ansi.js

@@ -0,0 +1,14 @@
+// ANSI / terminal control sequences. Tools emit these even when stdout isn't a
+// TTY (e.g. FORCE_COLOR), and they hurt readability for humans and LLMs alike.
+// Built with the RegExp constructor + \u escapes so no raw control chars live in
+// source.
+// OSC: ESC ] ... terminated by BEL () or ST (ESC \). Titles / hyperlinks.
+const OSC = new RegExp("\\u001b\\][^\\u0007\\u001b]*(?:\\u0007|\\u001b\\\\)", "g");
+// CSI: ESC [ params intermediates final-byte. Colors, cursor moves, clears.
+const CSI = new RegExp("\\u001b\\[[0-?]*[ -/]*[@-~]", "g");
+// Other two-character escapes: ESC followed by a single Fe/Fp/Fs byte.
+const ESCAPE = new RegExp("\\u001b[@-Z\\\\-_]", "g");
+/** Remove ANSI escape sequences from text. */
+export function stripAnsi(text) {
+    return text.replace(OSC, "").replace(CSI, "").replace(ESCAPE, "");
+}

package/dist/capture.js

@@ -0,0 +1,46 @@
+import { collectEnvInfo } from "./env.js";
+import { detectProjectTypes } from "./detect.js";
+import { collectRelevantFiles } from "./files.js";
+import { ensureGitignore } from "./gitignore.js";
+import { generateReport } from "./report.js";
+import { runCommand } from "./runner.js";
+import { FAILSNAP_DIR } from "./paths.js";
+/**
+ * If `result` failed, snapshot environment + project context for the directory
+ * the command ran in and write `.failsnap/latest.md`, `.failsnap/latest.log`, and
+ * a timestamped snapshot under `.failsnap/snapshots/`. Returns the report paths,
+ * or null on success. Shared by one-shot mode and the monitored shell.
+ */
+export function snapshotFailure(result, opts = {}) {
+    if (result.exitCode === 0)
+        return null;
+    const cwd = opts.cwd ?? process.cwd();
+    const report = generateReport({
+        command: result.command,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        output: result.output,
+        signal: result.signal,
+        cwd,
+        env: collectEnvInfo(cwd),
+        projectTypes: detectProjectTypes(cwd),
+        files: collectRelevantFiles(cwd),
+    });
+    const ignored = ensureGitignore(cwd);
+    if (!opts.silent) {
+        process.stderr.write(`\n[failsnap] command failed (exit code ${result.exitCode})\n` +
+            `[failsnap] report:   ${report.reportPath}\n` +
+            `[failsnap] raw log:  ${report.rawLogPath}\n` +
+            `[failsnap] snapshot: ${report.snapshotDir}\n` +
+            (ignored ? `[failsnap] added ${FAILSNAP_DIR}/ to .gitignore\n` : ""));
+    }
+    return report;
+}
+/**
+ * Run a command once through the user's shell; snapshot on failure.
+ */
+export async function runAndSnap(command, opts = {}) {
+    const result = await runCommand(command, opts);
+    const report = snapshotFailure(result, { cwd: opts.cwd, silent: opts.silent });
+    return { ...result, report };
+}

package/dist/clipboard.js

@@ -0,0 +1,48 @@
+import { spawn, spawnSync } from "node:child_process";
+const LINUX_TOOLS = [
+    { cmd: "wl-copy", args: [] },
+    { cmd: "xclip", args: ["-selection", "clipboard"] },
+    { cmd: "xsel", args: ["--clipboard", "--input"] },
+];
+function candidatesFor(platform) {
+    if (platform === "darwin")
+        return [{ cmd: "pbcopy", args: [] }];
+    if (platform === "win32")
+        return [{ cmd: "clip", args: [] }];
+    return LINUX_TOOLS;
+}
+function commandExists(cmd, platform) {
+    const checker = platform === "win32" ? "where" : "which";
+    try {
+        const res = spawnSync(checker, [cmd], { stdio: "ignore", timeout: 5000 });
+        return res.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** First available clipboard tool for this platform, or null if none. */
+export function findClipboardTool(platform = process.platform) {
+    for (const tool of candidatesFor(platform)) {
+        if (commandExists(tool.cmd, platform))
+            return tool;
+    }
+    return null;
+}
+/** Pipe text into a clipboard tool. Resolves false on any failure; never throws. */
+export function copyToClipboard(text, tool) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(tool.cmd, tool.args, { stdio: ["pipe", "ignore", "ignore"] });
+        }
+        catch {
+            return resolve(false);
+        }
+        child.on("error", () => resolve(false));
+        child.on("close", (code) => resolve(code === 0));
+        child.stdin.on("error", () => resolve(false));
+        child.stdin.write(text);
+        child.stdin.end();
+    });
+}

package/dist/detect.js

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import path from "node:path";
+const LABELS = {
+    node: "Node.js",
+    typescript: "TypeScript",
+    vite: "Vite",
+    nextjs: "Next.js",
+    python: "Python",
+    "java-maven": "Java (Maven)",
+    "java-gradle": "Java (Gradle)",
+};
+export function projectTypeLabel(type) {
+    return LABELS[type];
+}
+/** Detect every project type that applies to the given directory. */
+export function detectProjectTypes(dir = process.cwd()) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const has = (name) => entries.includes(name);
+    const hasPrefix = (prefix) => entries.some((e) => e.startsWith(prefix) && fs.statSync(path.join(dir, e)).isFile());
+    const types = [];
+    if (has("package.json"))
+        types.push("node");
+    if (has("tsconfig.json"))
+        types.push("typescript");
+    if (hasPrefix("vite.config."))
+        types.push("vite");
+    if (hasPrefix("next.config."))
+        types.push("nextjs");
+    if (has("pyproject.toml") || has("requirements.txt"))
+        types.push("python");
+    if (has("pom.xml"))
+        types.push("java-maven");
+    if (has("build.gradle") || has("build.gradle.kts"))
+        types.push("java-gradle");
+    return types;
+}

package/dist/doctor.js

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { detectProjectTypes, projectTypeLabel } from "./detect.js";
+import { collectRelevantFiles, EXCLUDED_DIRS, MAX_FILE_SIZE } from "./files.js";
+function git(args, cwd) {
+    try {
+        const res = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 10_000 });
+        if (res.error || res.status !== 0)
+            return null;
+        return res.stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+function detectPackageManager(dir) {
+    const locks = [
+        ["pnpm-lock.yaml", "pnpm"],
+        ["yarn.lock", "yarn"],
+        ["bun.lockb", "bun"],
+        ["bun.lock", "bun"],
+        ["package-lock.json", "npm"],
+    ];
+    for (const [lock, manager] of locks) {
+        if (fs.existsSync(path.join(dir, lock)))
+            return `${manager} (${lock})`;
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+        if (typeof pkg.packageManager === "string") {
+            return `${pkg.packageManager} (package.json "packageManager")`;
+        }
+    }
+    catch {
+        // no package.json or unparsable: fall through
+    }
+    return null;
+}
+/**
+ * Build the `failsnap doctor` output: what FailSnap detects and what it
+ * would collect for this directory, without running anything.
+ */
+export function buildDoctorReport(dir = process.cwd()) {
+    const types = detectProjectTypes(dir);
+    const files = collectRelevantFiles(dir).map((f) => f.path);
+    const packageManager = detectPackageManager(dir);
+    const envExists = fs.existsSync(path.join(dir, ".env"));
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"], dir);
+    const dirty = branch === null ? null : git(["status", "--porcelain"], dir);
+    const lines = [];
+    const section = (title, items) => {
+        lines.push("", `${title}:`);
+        for (const item of items)
+            lines.push(`- ${item}`);
+    };
+    lines.push("FailSnap Doctor");
+    section("Directory", [dir]);
+    section("Project", types.length > 0 ? types.map(projectTypeLabel) : ["no known project type detected"]);
+    if (packageManager)
+        section("Package manager", [packageManager]);
+    section("Will collect", files.length > 0 ? files : ["nothing (no relevant config files found)"]);
+    section("Will exclude", [
+        ".env files (never collected; .env.example is the only exception)",
+        ...[...EXCLUDED_DIRS].map((d) => `${d}/`),
+        `files larger than ${Math.round(MAX_FILE_SIZE / 1024)}KB`,
+    ]);
+    section("Git", branch === null
+        ? ["not a git repository"]
+        : [
+            `branch: ${branch}`,
+            `status: ${dirty && dirty.length > 0 ? "dirty (uncommitted changes)" : "clean"}`,
+        ]);
+    const security = ["Secret redaction enabled (output and collected files)"];
+    if (envExists)
+        security.push(".env detected but will not be collected");
+    section("Security", security);
+    return lines.join("\n") + "\n";
+}

package/dist/env.js

@@ -0,0 +1,36 @@
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+function runRaw(cmd, args, cwd) {
+    try {
+        const res = spawnSync(cmd, args, { cwd, encoding: "utf8", timeout: 10_000 });
+        if (res.error || res.status !== 0)
+            return null;
+        // Some tools (java) print their version to stderr.
+        return (res.stdout || res.stderr || "").trim();
+    }
+    catch {
+        return null;
+    }
+}
+function run(cmd, args, cwd) {
+    const out = runRaw(cmd, args, cwd);
+    if (out === null)
+        return null;
+    return out.split("\n")[0] || null;
+}
+export function collectEnvInfo(cwd = process.cwd()) {
+    const gitBranch = run("git", ["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+    const gitStatus = gitBranch === null ? null : runRaw("git", ["status", "--porcelain"], cwd);
+    return {
+        os: `${os.type()} ${os.release()} (${os.arch()})`,
+        shell: process.env.SHELL || process.env.ComSpec || "unknown",
+        cwd,
+        node: process.version,
+        npm: run("npm", ["--version"]),
+        pnpm: run("pnpm", ["--version"]),
+        python: run("python3", ["--version"]) ?? run("python", ["--version"]),
+        java: run("java", ["-version"]),
+        gitBranch,
+        gitDirty: gitStatus === null ? null : gitStatus.length > 0,
+    };
+}

package/dist/files.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+import { redact } from "./redact.js";
+export const MAX_FILE_SIZE = 100 * 1024; // 100 KB
+export const EXCLUDED_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".git",
+]);
+/** Exact file names worth including in a report. */
+const EXACT_CANDIDATES = [
+    "package.json",
+    "tsconfig.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    ".env.example",
+];
+/** Prefix-matched config files (vite.config.ts, next.config.mjs, ...). */
+const PREFIX_CANDIDATES = ["vite.config.", "next.config."];
+function isCandidate(name) {
+    // Never include real env files; only the .env.example template is allowed.
+    if (name === ".env" || (name.startsWith(".env.") && name !== ".env.example")) {
+        return false;
+    }
+    if (EXACT_CANDIDATES.includes(name))
+        return true;
+    return PREFIX_CANDIDATES.some((p) => name.startsWith(p));
+}
+/**
+ * Collect (and redact) project config files relevant for debugging.
+ * Only looks at the project root; excluded directories are never entered.
+ */
+export function collectRelevantFiles(dir = process.cwd()) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const name of entries.sort()) {
+        if (EXCLUDED_DIRS.has(name))
+            continue;
+        if (!isCandidate(name))
+            continue;
+        const fullPath = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile() || stat.size > MAX_FILE_SIZE)
+            continue;
+        try {
+            files.push({ path: name, content: redact(fs.readFileSync(fullPath, "utf8")) });
+        }
+        catch {
+            // unreadable file: skip
+        }
+    }
+    return files;
+}

package/dist/gitignore.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FAILSNAP_DIR } from "./paths.js";
+/** Walk up from `dir` looking for a `.git` entry; return true if inside a repo. */
+function isInGitRepo(dir) {
+    let current = path.resolve(dir);
+    for (;;) {
+        if (fs.existsSync(path.join(current, ".git")))
+            return true;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+/** True if any line of the .gitignore already ignores the .failsnap directory. */
+function alreadyIgnored(content) {
+    return content.split(/\r?\n/).some((line) => {
+        const trimmed = line.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+        return trimmed === FAILSNAP_DIR;
+    });
+}
+/**
+ * Ensure `.failsnap/` is git-ignored for the project at `cwd`.
+ *
+ * Best-effort and conservative: only acts inside a git repository, never
+ * duplicates an existing rule, and swallows any I/O error. Returns true only
+ * when it actually added the entry.
+ */
+export function ensureGitignore(cwd = process.cwd()) {
+    try {
+        if (!isInGitRepo(cwd))
+            return false;
+        const file = path.join(cwd, ".gitignore");
+        const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+        if (existing && alreadyIgnored(existing))
+            return false;
+        const prefix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+        fs.appendFileSync(file, `${prefix}${FAILSNAP_DIR}/\n`, "utf8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}