failsnap 0.1.0

package/dist/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { runAndSnap } from "./capture.js";
+import { copyToClipboard, findClipboardTool } from "./clipboard.js";
+import { buildDoctorReport } from "./doctor.js";
+import { joinCommand } from "./runner.js";
+import { latestReportPath } from "./report.js";
+import { FAILSNAP_DIR, LATEST_REPORT_REL } from "./paths.js";
+import { startShell } from "./shell.js";
+const program = new Command();
+program
+    .name("failsnap")
+    .description("Turn a failed dev command into an AI-ready debugging report.")
+    .version("0.1.0")
+    .enablePositionalOptions();
+program
+    .command("run <command...>", { isDefault: true })
+    .description(`run a command; on failure, write ${LATEST_REPORT_REL} (default)`)
+    .passThroughOptions()
+    .allowUnknownOption()
+    .action(async (parts) => {
+    const result = await runAndSnap(joinCommand(parts));
+    process.exitCode = result.exitCode;
+});
+program
+    .command("shell")
+    .description("start a monitored interactive shell session")
+    .action(async () => {
+    await startShell();
+});
+program
+    .command("last")
+    .description("print the path of the latest report")
+    .action(() => {
+    const reportPath = latestReportPath();
+    if (reportPath) {
+        process.stdout.write(reportPath + "\n");
+    }
+    else {
+        process.stderr.write("[failsnap] no report found — run a failing command first\n");
+        process.exitCode = 1;
+    }
+});
+program
+    .command("copy")
+    .description("copy the latest report to the clipboard")
+    .action(async () => {
+    const reportPath = latestReportPath();
+    if (!reportPath) {
+        process.stderr.write("[failsnap] no report found — run a failing command first\n");
+        process.exitCode = 1;
+        return;
+    }
+    const tool = findClipboardTool();
+    if (!tool) {
+        process.stdout.write("[failsnap] no clipboard tool found (looked for wl-copy, xclip, xsel)\n" +
+            `[failsnap] the report is at: ${reportPath}\n`);
+        return;
+    }
+    const ok = await copyToClipboard(fs.readFileSync(reportPath, "utf8"), tool);
+    if (ok) {
+        process.stdout.write(`[failsnap] report copied to clipboard (via ${tool.cmd})\n`);
+    }
+    else {
+        process.stdout.write(`[failsnap] could not copy with ${tool.cmd}\n` +
+            `[failsnap] the report is at: ${reportPath}\n`);
+    }
+});
+program
+    .command("doctor")
+    .description("show what would be detected and collected, without running anything")
+    .action(() => {
+    process.stdout.write(buildDoctorReport());
+});
+program
+    .command("clean")
+    .description(`remove the ${FAILSNAP_DIR} directory`)
+    .action(() => {
+    const dir = path.join(process.cwd(), FAILSNAP_DIR);
+    if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        process.stdout.write(`[failsnap] removed ${dir}\n`);
+    }
+    else {
+        process.stdout.write("[failsnap] nothing to clean\n");
+    }
+});
+program.parseAsync(process.argv);

package/dist/monitored-shell.js

@@ -0,0 +1,204 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import { BoundedLineBuffer } from "./output-buffer.js";
+/** Pick a real shell: $SHELL, else bash, else sh. */
+export function resolveInteractiveShell() {
+    if (process.platform === "win32")
+        return process.env.ComSpec || "cmd.exe";
+    return process.env.SHELL || "/bin/bash";
+}
+/**
+ * A single long-lived shell process driven over stdin. Because every command
+ * runs in the *same* shell, `cd`, `export`, `source`, aliases and quoted paths
+ * all behave exactly as the user expects — no command-string parsing on our side.
+ *
+ * Each command is followed by a unique sentinel that echoes `$?` and `$PWD`, so
+ * we can detect completion, capture the real exit code, and track the cwd. The
+ * sentinel lines are stripped before anything is captured or displayed.
+ */
+export class MonitoredShell {
+    child;
+    shell;
+    cwd;
+    closed = false;
+    alive = true;
+    nonce = randomBytes(8).toString("hex");
+    outMark = `__FAILSNAP_OUT_${this.nonce}__`;
+    errMark = `__FAILSNAP_ERR_${this.nonce}__`;
+    outRe;
+    constructor(opts = {}) {
+        this.shell = opts.shell ?? resolveInteractiveShell();
+        this.cwd = opts.cwd ?? process.cwd();
+        // outMark<TAB>exitcode<TAB>pwd  (tab is delimiter; rare in paths)
+        this.outRe = new RegExp(`${this.outMark}\\t(\\d+)\\t([^\\n]*)`);
+        this.child = spawn(this.shell, [], {
+            cwd: this.cwd,
+            env: process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child.on("exit", () => {
+            this.alive = false;
+        });
+        // A broken stdin pipe (shell already gone) must not crash failsnap.
+        this.child.stdin.on("error", () => { });
+        // Best-effort: let non-interactive bash expand aliases like an interactive one.
+        this.child.stdin.write("shopt -s expand_aliases 2>/dev/null\n");
+    }
+    /** False once the underlying shell process has exited. */
+    get isAlive() {
+        return this.alive;
+    }
+    /** Run one command to completion, streaming output live and capturing it. */
+    run(command, opts = {}) {
+        const start = Date.now();
+        const stdoutBuf = new BoundedLineBuffer();
+        const stderrBuf = new BoundedLineBuffer();
+        const outputBuf = new BoundedLineBuffer();
+        const outDecoder = new StringDecoder("utf8");
+        const errDecoder = new StringDecoder("utf8");
+        return new Promise((resolve) => {
+            // Shell already dead (e.g. a previous `exit`): don't hang.
+            if (!this.alive) {
+                resolve({
+                    command,
+                    exitCode: 1,
+                    durationMs: 0,
+                    stdout: "",
+                    stderr: "",
+                    output: "failsnap: shell session has ended\n",
+                    signal: null,
+                    cwd: this.cwd,
+                });
+                return;
+            }
+            let exitCode = null;
+            let signalName = null;
+            let newCwd = this.cwd;
+            let errDone = false;
+            let outCarry = "";
+            let errCarry = "";
+            let settled = false;
+            const tryFinish = () => {
+                if (settled || exitCode === null || !errDone)
+                    return;
+                settled = true;
+                cleanup();
+                this.cwd = newCwd;
+                resolve({
+                    command,
+                    exitCode,
+                    durationMs: Date.now() - start,
+                    stdout: stdoutBuf.toString(),
+                    stderr: stderrBuf.toString(),
+                    output: outputBuf.toString(),
+                    signal: signalName,
+                    cwd: newCwd,
+                });
+            };
+            // Process complete lines from one stream; return leftover partial line.
+            const onStdout = (chunk) => {
+                outCarry += outDecoder.write(chunk);
+                let nl;
+                while ((nl = outCarry.indexOf("\n")) !== -1) {
+                    const line = outCarry.slice(0, nl);
+                    outCarry = outCarry.slice(nl + 1);
+                    const m = this.outRe.exec(line);
+                    if (m) {
+                        // Emit any real output that shared the marker's line, then drop the marker.
+                        const pre = line.slice(0, m.index);
+                        if (pre) {
+                            stdoutBuf.push(pre);
+                            outputBuf.push(pre);
+                            if (!opts.silent)
+                                process.stdout.write(pre);
+                        }
+                        exitCode = Number(m[1]);
+                        if (m[2])
+                            newCwd = m[2];
+                        tryFinish();
+                        continue;
+                    }
+                    stdoutBuf.push(line + "\n");
+                    outputBuf.push(line + "\n");
+                    if (!opts.silent)
+                        process.stdout.write(line + "\n");
+                }
+            };
+            const onStderr = (chunk) => {
+                errCarry += errDecoder.write(chunk);
+                let nl;
+                while ((nl = errCarry.indexOf("\n")) !== -1) {
+                    const line = errCarry.slice(0, nl);
+                    errCarry = errCarry.slice(nl + 1);
+                    const idx = line.indexOf(this.errMark);
+                    if (idx !== -1) {
+                        const pre = line.slice(0, idx);
+                        if (pre) {
+                            stderrBuf.push(pre);
+                            outputBuf.push(pre);
+                            if (!opts.silent)
+                                process.stderr.write(pre);
+                        }
+                        errDone = true;
+                        tryFinish();
+                        continue;
+                    }
+                    stderrBuf.push(line + "\n");
+                    outputBuf.push(line + "\n");
+                    if (!opts.silent)
+                        process.stderr.write(line + "\n");
+                }
+            };
+            // If the shell exits before the sentinels (e.g. the command was `exit 7`),
+            // resolve with the shell's own exit code instead of hanging forever.
+            const onExit = (code, signal) => {
+                if (settled)
+                    return;
+                if (exitCode === null)
+                    exitCode = code ?? (signal ? 128 : 1);
+                if (signal)
+                    signalName = signal;
+                errDone = true;
+                tryFinish();
+            };
+            const cleanup = () => {
+                this.child.stdout.off("data", onStdout);
+                this.child.stderr.off("data", onStderr);
+                this.child.off("exit", onExit);
+            };
+            this.child.stdout.on("data", onStdout);
+            this.child.stderr.on("data", onStderr);
+            this.child.once("exit", onExit);
+            // Run the command, then capture $? and $PWD before the sentinels reset them.
+            const driver = `${command}\n` +
+                `__rc=$?; printf '%s\\t%s\\t%s\\n' "${this.outMark}" "$__rc" "$PWD"; ` +
+                `printf '%s\\n' "${this.errMark}" 1>&2\n`;
+            this.child.stdin.write(driver);
+        });
+    }
+    get currentCwd() {
+        return this.cwd;
+    }
+    /** The shell binary backing this session. */
+    get shellPath() {
+        return this.shell;
+    }
+    /** Forward an interrupt to the running command. */
+    interrupt() {
+        if (!this.closed)
+            this.child.kill("SIGINT");
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.child.stdin.end("exit\n");
+        }
+        catch {
+            /* ignore */
+        }
+        this.child.kill();
+    }
+}

package/dist/output-buffer.js

@@ -0,0 +1,63 @@
+// In-memory capture budget: how many lines we *retain* from a command's output
+// (first 200 + last 800). Distinct from report.ts's MAX_REPORT_OUTPUT_LINES,
+// which controls how many lines are *displayed* in the Markdown report.
+export const DEFAULT_HEAD_LINES = 200;
+export const DEFAULT_TAIL_LINES = 800;
+/** Cap a single line so output with no newlines can't grow without bound. */
+const MAX_LINE_CHARS = 64 * 1024;
+/**
+ * Bounds captured output in memory: keeps the first `headLines` and the last
+ * `tailLines` lines, dropping the middle and recording how many lines were lost.
+ * Prevents OOM on commands that emit huge output (and keeps reports within an
+ * LLM-friendly size).
+ */
+export class BoundedLineBuffer {
+    headLines;
+    tailLines;
+    head = [];
+    tail = [];
+    pending = "";
+    dropped = 0;
+    constructor(headLines = DEFAULT_HEAD_LINES, tailLines = DEFAULT_TAIL_LINES) {
+        this.headLines = headLines;
+        this.tailLines = tailLines;
+    }
+    push(text) {
+        this.pending += text;
+        let nl;
+        while ((nl = this.pending.indexOf("\n")) !== -1) {
+            this.addLine(this.pending.slice(0, nl));
+            this.pending = this.pending.slice(nl + 1);
+        }
+        // A single line longer than the cap is flushed eagerly to bound memory.
+        if (this.pending.length > MAX_LINE_CHARS) {
+            this.addLine(this.pending);
+            this.pending = "";
+        }
+    }
+    addLine(line) {
+        if (this.head.length < this.headLines) {
+            this.head.push(line);
+            return;
+        }
+        this.tail.push(line);
+        if (this.tail.length > this.tailLines) {
+            this.tail.shift();
+            this.dropped++;
+        }
+    }
+    /** Number of lines dropped from the middle. */
+    get droppedLines() {
+        return this.dropped;
+    }
+    toString() {
+        const lines = [...this.head];
+        if (this.dropped > 0) {
+            lines.push(`... (${this.dropped} lines truncated) ...`);
+        }
+        lines.push(...this.tail);
+        if (this.pending.length > 0)
+            lines.push(this.pending);
+        return lines.join("\n");
+    }
+}

package/dist/paths.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+/**
+ * Single source of truth for FailSnap's on-disk layout. Every reference to a
+ * report path or filename — including user-facing messages in shell mode —
+ * must come from here so they can never drift out of sync.
+ *
+ *   .failsnap/
+ *   ├─ latest.md       (LATEST_REPORT)
+ *   ├─ latest.log      (LATEST_LOG)
+ *   └─ snapshots/      (SNAPSHOTS_DIR)
+ *      └─ <timestamp>/{report.md, raw.log}   (SNAPSHOT_REPORT / SNAPSHOT_LOG)
+ */
+export const FAILSNAP_DIR = ".failsnap";
+export const LATEST_REPORT = "latest.md";
+export const LATEST_LOG = "latest.log";
+export const SNAPSHOTS_DIR = "snapshots";
+export const SNAPSHOT_REPORT = "report.md";
+export const SNAPSHOT_LOG = "raw.log";
+/** Filename of the report written before the latest.md/latest.log layout. */
+export const LEGACY_REPORT = "report.md";
+/** `.failsnap/latest.md` — for display in messages. */
+export const LATEST_REPORT_REL = `${FAILSNAP_DIR}/${LATEST_REPORT}`;
+/** `.failsnap/latest.log` — for display in messages. */
+export const LATEST_LOG_REL = `${FAILSNAP_DIR}/${LATEST_LOG}`;
+export function failsnapDir(cwd) {
+    return path.join(cwd, FAILSNAP_DIR);
+}

package/dist/redact.js

@@ -0,0 +1,91 @@
+const REDACTED = "[REDACTED]";
+/** Matches any redaction placeholder, e.g. [REDACTED] or [REDACTED_PRIVATE_KEY]. */
+const PLACEHOLDER = String.raw `\[REDACTED(?:_[A-Z_]+)?\]`;
+/**
+ * Names that mark a key/value pair as sensitive when they appear in the key,
+ * e.g. OPENAI_API_KEY=..., "jwtSecret": "...", DATABASE_URL=...
+ */
+const SENSITIVE_KEY = "(?:api[_-]?key|apikey|access[_-]?key|secret[_-]?access[_-]?key|secret[_-]?key|client[_-]?secret|auth[_-]?token|secret|token|password|passwd|pwd|database[_-]?url|db[_-]?url|conn(?:ection)?[_-]?string|jwt|credential|private[_-]?key)";
+/**
+ * Reject keys where the sensitive word is only a prefix of a benign field name
+ * (secretName, tokenCount, keyId, ...). These name/describe a secret rather than
+ * holding one, so redacting them is a false positive.
+ */
+const BENIGN_SUFFIX = "(?![_-]?(?:name|names|count|id|ids|type|length|len|index|prefix|suffix|format|path|file|field|label|enabled|required)\\b)";
+const KEY = `[A-Za-z0-9_-]*${SENSITIVE_KEY}${BENIGN_SUFFIX}[A-Za-z0-9_-]*`;
+const RULES = [
+    // --- Multiline secrets (must run first, before per-line rules) ---
+    // PEM blocks: -----BEGIN [RSA|EC|OPENSSH|PGP ...] PRIVATE KEY----- ... -----END ...-----
+    {
+        pattern: /-----BEGIN [^-\n]*PRIVATE KEY[^-\n]*-----[\s\S]*?-----END [^-\n]*PRIVATE KEY[^-\n]*-----/g,
+        replacement: "[REDACTED_PRIVATE_KEY]",
+    },
+    // --- key/value pairs ---
+    // key = "value" / key: 'value'  (JSON, YAML, TS/JS config, quoted env).
+    // (?!PLACEHOLDER) keeps the pass idempotent and preserves typed labels.
+    {
+        pattern: new RegExp(`((?:["']?)${KEY}(?:["']?)\\s*[=:]\\s*)(["'])(?!${PLACEHOLDER})[^"'\\n]*\\2`, "gi"),
+        replacement: `$1$2${REDACTED}$2`,
+    },
+    // KEY=value unquoted (env-file / shell style)
+    {
+        pattern: new RegExp(`(${KEY}\\s*=\\s*)(?!${PLACEHOLDER})([^\\s"']+)`, "gi"),
+        replacement: `$1${REDACTED}`,
+    },
+    // .npmrc auth tokens: //registry.example.com/:_authToken=xxx  and  _authToken=xxx
+    {
+        pattern: /((?:\/\/[^\s]*:)?_authToken\s*=\s*)(?!\[REDACTED)\S+/gi,
+        replacement: `$1${REDACTED}`,
+    },
+    // aws_secret_access_key context, 40-char value (covers odd quoting/spacing)
+    {
+        pattern: /(aws_secret_access_key\s*[=:]\s*)(?!\[REDACTED)["']?[A-Za-z0-9/+]{40}["']?/gi,
+        replacement: `$1${REDACTED}`,
+    },
+    // --- Authorization headers ---
+    { pattern: /(bearer\s+)[A-Za-z0-9\-._~+/]+=*/gi, replacement: `$1${REDACTED}` },
+    { pattern: /(basic\s+)[A-Za-z0-9+/]{8,}=*/gi, replacement: `$1${REDACTED}` },
+    // --- Known token shapes (no surrounding key needed) ---
+    // OpenAI / Anthropic style keys (sk-..., sk-ant-...)
+    { pattern: /\bsk-[A-Za-z0-9_-]{10,}\b/g, replacement: REDACTED },
+    // Stripe live secret/restricted keys (sk_live_, rk_live_)
+    { pattern: /\b(?:sk|rk)_live_[0-9A-Za-z]{10,}\b/g, replacement: REDACTED },
+    // GitHub tokens
+    { pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g, replacement: REDACTED },
+    { pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, replacement: REDACTED },
+    // GitLab personal access tokens
+    { pattern: /\bglpat-[A-Za-z0-9_-]{10,}\b/g, replacement: REDACTED },
+    // npm tokens
+    { pattern: /\bnpm_[A-Za-z0-9]{20,}\b/g, replacement: REDACTED },
+    // Slack tokens
+    { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, replacement: REDACTED },
+    // Google API keys
+    { pattern: /\bAIza[0-9A-Za-z\-_]{35}\b/g, replacement: REDACTED },
+    // SendGrid API keys
+    { pattern: /\bSG\.[\w-]{16,}\.[\w-]{16,}\b/g, replacement: REDACTED },
+    // AWS access key ids
+    { pattern: /\bAKIA[0-9A-Z]{16}\b/g, replacement: REDACTED },
+    // JWTs (three base64url segments starting with eyJ)
+    {
+        pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}\b/g,
+        replacement: REDACTED,
+    },
+    // --- Credentials embedded in URLs: scheme://user:pass@host ---
+    {
+        pattern: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/]+):([^\s@/]+)@/gi,
+        replacement: `$1$2:${REDACTED}@`,
+    },
+];
+/**
+ * Redact API keys, tokens, passwords, private keys and connection strings from
+ * text. Best-effort and pattern-based: it catches the well-known secret shapes
+ * and `sensitiveKey = value` pairs, but cannot guarantee removal of arbitrary
+ * high-entropy strings. Running it twice yields the same result (idempotent).
+ */
+export function redact(text) {
+    let result = text;
+    for (const rule of RULES) {
+        result = result.replace(rule.pattern, rule.replacement);
+    }
+    return result;
+}

package/dist/report.js

@@ -0,0 +1,185 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectTypeLabel } from "./detect.js";
+import { redact } from "./redact.js";
+import { stripAnsi } from "./ansi.js";
+import { LATEST_LOG, LATEST_REPORT, LEGACY_REPORT, FAILSNAP_DIR, SNAPSHOT_LOG, SNAPSHOT_REPORT, SNAPSHOTS_DIR, } from "./paths.js";
+// Re-export so existing importers keep working through report.js.
+export { FAILSNAP_DIR, LATEST_REPORT, LATEST_LOG } from "./paths.js";
+/** Strip terminal control codes, then redact secrets, before anything is shown. */
+function sanitize(output) {
+    return redact(stripAnsi(output));
+}
+/** Human-readable interpretation of a fatal signal. */
+function signalNote(signal) {
+    switch (signal) {
+        case "SIGKILL":
+            return "Terminated by SIGKILL — force-killed, often by the OS out-of-memory (OOM) killer. Check memory usage.";
+        case "SIGSEGV":
+            return "Terminated by SIGSEGV — segmentation fault (a native-level crash).";
+        case "SIGABRT":
+            return "Terminated by SIGABRT — the process aborted itself (assertion/fatal error).";
+        case "SIGINT":
+            return "Interrupted by SIGINT (Ctrl-C).";
+        case "SIGTERM":
+            return "Terminated by SIGTERM (a graceful termination request).";
+        case "SIGFPE":
+            return "Terminated by SIGFPE — arithmetic error (e.g. divide by zero).";
+        default:
+            return `Terminated by ${signal}.`;
+    }
+}
+// How many trailing output lines to *display* in the Markdown report. Distinct
+// from output-buffer.ts's DEFAULT_HEAD_LINES/DEFAULT_TAIL_LINES, which bound how
+// much output is *retained* in memory; the full retained log is saved to disk.
+const MAX_REPORT_OUTPUT_LINES = 200;
+function timestampSlug(date = new Date()) {
+    const p = (n) => String(n).padStart(2, "0");
+    return (`${date.getFullYear()}-${p(date.getMonth() + 1)}-${p(date.getDate())}` +
+        `_${p(date.getHours())}-${p(date.getMinutes())}-${p(date.getSeconds())}`);
+}
+/**
+ * Path of the most recent report, or null if none exists.
+ * Falls back to the legacy `report.md` written by pre-0.1 versions.
+ */
+export function latestReportPath(cwd = process.cwd()) {
+    const dir = path.join(cwd, FAILSNAP_DIR);
+    for (const name of [LATEST_REPORT, LEGACY_REPORT]) {
+        const candidate = path.join(dir, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+function formatDuration(ms) {
+    return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
+}
+function fenceFor(content) {
+    // Grow the fence if the content itself contains backtick fences.
+    let fence = "```";
+    while (content.includes(fence))
+        fence += "`";
+    return fence;
+}
+function codeBlock(content, lang = "") {
+    const fence = fenceFor(content);
+    return `${fence}${lang}\n${content.replace(/\n$/, "")}\n${fence}`;
+}
+function languageFor(file) {
+    if (file.endsWith(".json"))
+        return "json";
+    if (file.endsWith(".toml"))
+        return "toml";
+    if (file.endsWith(".xml"))
+        return "xml";
+    if (file.endsWith(".gradle") || file.endsWith(".kts"))
+        return "groovy";
+    if (/\.(ts|mts|cts)$/.test(file))
+        return "ts";
+    if (/\.(js|mjs|cjs)$/.test(file))
+        return "js";
+    return "";
+}
+function tailLines(text, max) {
+    const lines = text.replace(/\n$/, "").split("\n");
+    if (lines.length <= max)
+        return { text: lines.join("\n"), truncated: 0 };
+    return {
+        text: lines.slice(-max).join("\n"),
+        truncated: lines.length - max,
+    };
+}
+function envTable(env) {
+    const rows = [
+        ["OS", env.os],
+        ["Shell", env.shell],
+        ["Working directory", env.cwd],
+        ["Node", env.node ?? "not found"],
+        ["npm", env.npm ?? "not found"],
+        ["pnpm", env.pnpm ?? "not found"],
+        ["Python", env.python ?? "not found"],
+        ["Java", env.java ?? "not found"],
+        ["Git branch", env.gitBranch ?? "not a git repository"],
+        [
+            "Git status",
+            env.gitDirty === null ? "n/a" : env.gitDirty ? "dirty (uncommitted changes)" : "clean",
+        ],
+    ];
+    return [
+        "| | |",
+        "|---|---|",
+        ...rows.map(([k, v]) => `| **${k}** | ${v.replace(/\|/g, "\\|")} |`),
+    ].join("\n");
+}
+export function buildReportMarkdown(input) {
+    const safeOutput = sanitize(input.output);
+    const { text: shownOutput, truncated } = tailLines(safeOutput || "(no output)", MAX_REPORT_OUTPUT_LINES);
+    const projectLine = input.projectTypes.length > 0
+        ? input.projectTypes.map(projectTypeLabel).join(", ")
+        : "unknown";
+    const sections = [];
+    sections.push("# FailSnap Report");
+    sections.push(`Generated: ${new Date().toISOString()}`);
+    sections.push("## Failed Command");
+    sections.push([
+        `- **Command:** \`${input.command}\``,
+        `- **Exit code:** ${input.exitCode}`,
+        ...(input.signal ? [`- **Signal:** ${signalNote(input.signal)}`] : []),
+        `- **Duration:** ${formatDuration(input.durationMs)}`,
+        `- **Directory:** \`${input.cwd}\``,
+    ].join("\n"));
+    sections.push("## Environment");
+    sections.push(envTable(input.env));
+    sections.push("## Project");
+    sections.push(`Detected project type: **${projectLine}**`);
+    sections.push("## Command Output");
+    if (truncated > 0) {
+        sections.push(`_Showing the last ${MAX_REPORT_OUTPUT_LINES} lines (${truncated} earlier lines omitted; full output in \`${FAILSNAP_DIR}/${LATEST_LOG}\`)._`);
+    }
+    sections.push(codeBlock(shownOutput, "text"));
+    if (input.files.length > 0) {
+        sections.push("## Relevant Files");
+        for (const file of input.files) {
+            sections.push(`### \`${file.path}\``);
+            sections.push(codeBlock(file.content, languageFor(file.path)));
+        }
+    }
+    sections.push("## AI Debugging Prompt");
+    sections.push([
+        "Paste this entire report into ChatGPT, Claude, Codex, or Cursor together with the request below.",
+        "",
+        "> The command above failed. Using the captured output, environment, and project files in this report, please provide:",
+        ">",
+        "> 1. **Root cause** — what exactly went wrong and why.",
+        "> 2. **Exact fix** — the precise change that resolves it.",
+        "> 3. **Commands to run** — every command, in order.",
+        "> 4. **Files to edit** — each file and the exact edit to make.",
+        "> 5. **Verification steps** — how to confirm the problem is fixed.",
+    ].join("\n"));
+    return sections.join("\n\n") + "\n";
+}
+/**
+ * Write the report for a failed command:
+ *
+ *   .failsnap/latest.md / latest.log           — always the most recent failure
+ *   .failsnap/snapshots/<timestamp>/report.md  — kept permanently, never overwritten
+ *
+ * Everything is redacted before it touches disk.
+ */
+export function generateReport(input) {
+    const dir = path.join(input.cwd, FAILSNAP_DIR);
+    const base = path.join(dir, SNAPSHOTS_DIR, timestampSlug());
+    let snapshotDir = base;
+    for (let n = 2; fs.existsSync(snapshotDir); n++)
+        snapshotDir = `${base}_${n}`;
+    fs.mkdirSync(snapshotDir, { recursive: true });
+    const markdown = buildReportMarkdown(input);
+    const log = sanitize(input.output);
+    fs.writeFileSync(path.join(snapshotDir, SNAPSHOT_REPORT), markdown, "utf8");
+    fs.writeFileSync(path.join(snapshotDir, SNAPSHOT_LOG), log, "utf8");
+    const reportPath = path.join(dir, LATEST_REPORT);
+    const rawLogPath = path.join(dir, LATEST_LOG);
+    fs.writeFileSync(reportPath, markdown, "utf8");
+    fs.writeFileSync(rawLogPath, log, "utf8");
+    return { dir, reportPath, rawLogPath, snapshotDir };
+}