failsnap 0.1.0

package/dist/runner.js

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process";
+import os from "node:os";
+import { StringDecoder } from "node:string_decoder";
+import { BoundedLineBuffer } from "./output-buffer.js";
+const SIGNALS = os.constants.signals;
+/** Exit code for a process killed by a signal, by the 128+N convention. */
+function signalExitCode(signal) {
+    const num = SIGNALS[signal];
+    return num ? 128 + num : 1;
+}
+export function defaultShell() {
+    if (process.platform === "win32")
+        return process.env.ComSpec || "cmd.exe";
+    return process.env.SHELL || "/bin/sh";
+}
+/** Quote argv parts back into a single shell command string. */
+export function joinCommand(parts) {
+    return parts
+        .map((p) => /[^\w@%+=:,./-]/.test(p) ? `'${p.replace(/'/g, `'\\''`)}'` : p)
+        .join(" ");
+}
+/**
+ * Run a command through the user's shell, streaming stdout/stderr live
+ * while capturing everything for the report.
+ */
+export function runCommand(command, opts = {}) {
+    const shell = opts.shell ?? defaultShell();
+    const isWin = process.platform === "win32";
+    const args = isWin ? ["/d", "/s", "/c", command] : ["-c", command];
+    const start = Date.now();
+    return new Promise((resolve) => {
+        const child = spawn(shell, args, {
+            cwd: opts.cwd ?? process.cwd(),
+            env: process.env,
+            stdio: ["inherit", "pipe", "pipe"],
+        });
+        // Bounded buffers keep memory flat on huge output. Separate StringDecoders
+        // per stream so a multibyte char split across chunk boundaries isn't
+        // corrupted (live streaming still writes raw bytes to the terminal).
+        const stdoutBuf = new BoundedLineBuffer();
+        const stderrBuf = new BoundedLineBuffer();
+        const outputBuf = new BoundedLineBuffer();
+        const stdoutDecoder = new StringDecoder("utf8");
+        const stderrDecoder = new StringDecoder("utf8");
+        child.stdout.on("data", (chunk) => {
+            const text = stdoutDecoder.write(chunk);
+            stdoutBuf.push(text);
+            outputBuf.push(text);
+            if (!opts.silent)
+                process.stdout.write(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = stderrDecoder.write(chunk);
+            stderrBuf.push(text);
+            outputBuf.push(text);
+            if (!opts.silent)
+                process.stderr.write(chunk);
+        });
+        // Forward Ctrl+C to the child instead of killing failsnap itself.
+        const onSigint = () => child.kill("SIGINT");
+        process.on("SIGINT", onSigint);
+        const finish = (exitCode, signal = null) => {
+            process.removeListener("SIGINT", onSigint);
+            // Flush any bytes held back by the decoders for an incomplete sequence.
+            const stdoutTail = stdoutDecoder.end();
+            const stderrTail = stderrDecoder.end();
+            if (stdoutTail) {
+                stdoutBuf.push(stdoutTail);
+                outputBuf.push(stdoutTail);
+            }
+            if (stderrTail) {
+                stderrBuf.push(stderrTail);
+                outputBuf.push(stderrTail);
+            }
+            resolve({
+                command,
+                exitCode,
+                durationMs: Date.now() - start,
+                stdout: stdoutBuf.toString(),
+                stderr: stderrBuf.toString(),
+                output: outputBuf.toString(),
+                signal,
+            });
+        };
+        child.on("error", (err) => {
+            const message = `failsnap: failed to start command: ${err.message}\n`;
+            stderrBuf.push(message);
+            outputBuf.push(message);
+            if (!opts.silent)
+                process.stderr.write(message);
+            finish(127);
+        });
+        child.on("close", (code, signal) => {
+            if (code !== null)
+                return finish(code, null);
+            finish(signal ? signalExitCode(signal) : 1, signal ?? null);
+        });
+    });
+}

package/dist/shell.js

@@ -0,0 +1,101 @@
+import os from "node:os";
+import readline from "node:readline";
+import { snapshotFailure } from "./capture.js";
+import { MonitoredShell } from "./monitored-shell.js";
+import { LATEST_REPORT_REL } from "./paths.js";
+const PREFIX = "[failsnap]";
+function shortCwd(cwd) {
+    const home = os.homedir();
+    return cwd.startsWith(home) ? "~" + cwd.slice(home.length) : cwd;
+}
+/**
+ * Line reader backed by a queue so that lines arriving while a command is
+ * running (pasted blocks, piped stdin) are not dropped, unlike rl.question.
+ */
+function createLineReader(rl) {
+    const queue = [];
+    let pending = null;
+    let closed = false;
+    rl.on("line", (line) => {
+        if (pending) {
+            const resolve = pending;
+            pending = null;
+            resolve(line);
+        }
+        else {
+            queue.push(line);
+        }
+    });
+    rl.on("close", () => {
+        closed = true;
+        if (pending) {
+            const resolve = pending;
+            pending = null;
+            resolve(null);
+        }
+    });
+    return () => {
+        if (queue.length > 0)
+            return Promise.resolve(queue.shift());
+        if (closed)
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            pending = resolve;
+        });
+    };
+}
+/**
+ * Monitored shell mode: a single long-lived shell runs every command the user
+ * types, so `cd`, `export`, `source` and aliases persist across commands with
+ * no command-string parsing on our side. Output is streamed live and captured;
+ * failing commands automatically produce a report under `.failsnap/`.
+ */
+export async function startShell() {
+    const shell = new MonitoredShell();
+    process.stdout.write(`${PREFIX} monitored shell started (${shell.shellPath})\n` +
+        `${PREFIX} failed commands are captured to ${LATEST_REPORT_REL} automatically\n` +
+        `${PREFIX} cd / export / source / aliases all persist across commands\n` +
+        `${PREFIX} type "exit" to leave\n`);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    // Ctrl+C at the prompt clears the current line instead of killing the shell.
+    rl.on("SIGINT", () => {
+        rl.write(null, { ctrl: true, name: "u" });
+        process.stdout.write("^C\n");
+        rl.prompt(true);
+    });
+    const nextLine = createLineReader(rl);
+    for (;;) {
+        rl.setPrompt(`${PREFIX} ${shortCwd(shell.currentCwd)} $ `);
+        rl.prompt(true);
+        const line = await nextLine();
+        if (line === null)
+            break; // stdin closed (Ctrl+D)
+        const command = line.trim();
+        if (command.length === 0)
+            continue;
+        if (command === "exit" || command === "quit")
+            break;
+        // Hand the terminal to the running command; Ctrl+C interrupts it.
+        rl.pause();
+        const onSigint = () => shell.interrupt();
+        process.on("SIGINT", onSigint);
+        try {
+            const result = await shell.run(command);
+            snapshotFailure(result, { cwd: result.cwd });
+        }
+        finally {
+            process.removeListener("SIGINT", onSigint);
+            rl.resume();
+        }
+        if (!shell.isAlive) {
+            process.stdout.write(`${PREFIX} shell session ended\n`);
+            break;
+        }
+    }
+    shell.close();
+    rl.close();
+    process.stdout.write(`${PREFIX} bye\n`);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "failsnap",
+  "version": "0.1.0",
+  "description": "Turn a failed dev command into an AI-ready debugging report.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MuyajakiMuyaho/failsnap.git"
+  },
+  "homepage": "https://github.com/MuyajakiMuyaho/failsnap#readme",
+  "bugs": {
+    "url": "https://github.com/MuyajakiMuyaho/failsnap/issues"
+  },
+  "bin": {
+    "failsnap": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "cli",
+    "debugging",
+    "ai",
+    "error-report",
+    "developer-tools"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}