oopsx 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devesh@760
+
+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,95 @@
+# oopsx
+
+A CLI that plays a meme sound when your terminal command fails.
+
+Wrap any command with `oopsx`. If it fails (non-zero exit code), you hear a sound. If it passes, nothing happens. Your original output and exit code are preserved.
+
+```
+$ oopsx git puhs origin main
+fatal: 'puhs' is not a git command.
+🔊 *plays sound*
+```
+
+## Install
+
+```bash
+npm install -g oopsx
+```
+
+Or run without installing:
+
+```bash
+npx oopsx ls /nonexistent/path
+```
+
+Or via curl (macOS / Linux):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/devesh760/oopsx/main/install.sh | bash
+```
+
+## Usage
+
+```bash
+oopsx <command>
+```
+
+```bash
+oopsx ls /does/not/exist          # plays default sound on failure
+oopsx --sound ~/bruh.mp3 npm test # use a custom sound
+oopsx --url https://x.com/f.mp3 make build  # download + cache a sound
+oopsx --volume 50 python script.py           # set volume (0-100)
+oopsx --sound ~/oof.mp3 --set-default echo hi  # save as default
+oopsx --once cargo build          # play only once per session
+```
+
+## Options
+
+| Option              | Description                                   |
+| ------------------- | --------------------------------------------- |
+| `--sound <path>`    | Use a local `.mp3` or `.wav` file             |
+| `--url <url>`       | Download and cache a sound from a URL         |
+| `--volume <0-100>`  | Playback volume (default: `80`)               |
+| `--set-default`     | Save the resolved sound as the new default    |
+| `--once`            | Play sound only once per shell session        |
+
+## How it works
+
+1. Runs your command with inherited stdio — you see all output as normal.
+2. If exit code is `0`, does nothing.
+3. If exit code is non-zero, plays a sound.
+4. Exits with the **same exit code** as your command.
+
+A default sound is bundled out of the box. You can replace it with `--sound <file> --set-default`.
+
+Sound priority: `--sound` > `--url` > `~/.merr/default.mp3`
+
+## Config
+
+Stored in `~/.merr/`:
+
+```
+~/.merr/
+├── config.json    # volume
+├── default.mp3    # default sound
+└── sounds/        # cached URL downloads
+```
+
+## Platform support
+
+| Platform | Backend              |
+| -------- | -------------------- |
+| macOS    | `afplay` (built-in)  |
+| Linux    | `aplay` / `mpg123`   |
+| Windows  | PowerShell fallback  |
+
+## Uninstall
+
+```bash
+npm uninstall -g oopsx
+rm -rf ~/.merr
+```
+
+## License
+
+MIT

package/bin/merr.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { runCommand } from "../src/runner.js";
+import { resolveSound, playAudio, setDefault, setVolume } from "../src/sound.js";
+import { readConfig } from "../src/config.js";
+
+const SESSION_KEY = `OOPSX_PLAYED_${process.ppid}`;
+
+const program = new Command();
+
+program
+  .name("oopsx")
+  .description("Play a meme sound when your terminal command fails")
+  .version("1.0.0")
+  .argument("<command...>", "Shell command to execute")
+  .option("--sound <path>", "Use a local sound file (mp3/wav)")
+  .option("--url <url>", "Download and cache a sound from a URL")
+  .option("--volume <number>", "Playback volume 0–100", parseInt)
+  .option("--set-default", "Persist the resolved sound as the default")
+  .option("--once", "Play sound only once per shell session")
+  .allowUnknownOption(true)
+  .action(async (commandArgs, options) => {
+    const config = readConfig();
+    const volume = options.volume ?? config.volume ?? 80;
+
+    // Persist volume if explicitly provided
+    if (options.volume !== undefined) {
+      setVolume(options.volume);
+    }
+
+    const exitCode = await runCommand(commandArgs);
+
+    if (exitCode === 0) {
+      process.exit(0);
+    }
+
+    // --once: skip if already played in this shell session
+    if (options.once && process.env[SESSION_KEY]) {
+      process.exit(exitCode);
+    }
+
+    const soundFile = await resolveSound(options);
+
+    if (!soundFile) {
+      process.exit(exitCode);
+    }
+
+    // --set-default: persist the resolved sound
+    if (options.setDefault) {
+      setDefault(soundFile);
+    }
+
+    try {
+      await playAudio(soundFile, volume);
+    } catch (err) {
+      console.error(`Sound playback failed: ${err.message}`);
+    }
+
+    // Mark as played for --once (only useful if parent reads env, but we set it anyway)
+    if (options.once) {
+      process.env[SESSION_KEY] = "1";
+    }
+
+    process.exit(exitCode);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "oopsx",
+  "version": "0.0.1",
+  "description": "Play a meme sound when your terminal command fails",
+  "type": "module",
+  "bin": {
+    "oopsx": "./bin/merr.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/"
+  ],
+  "keywords": [
+    "cli",
+    "meme",
+    "sound",
+    "error",
+    "terminal",
+    "fun"
+  ],
+  "author": "devesh@760 <drajawat760@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devesh760/oopsx.git"
+  },
+  "homepage": "https://github.com/devesh760/oopsx#readme",
+  "bugs": {
+    "url": "https://github.com/devesh760/oopsx/issues"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "play-sound": "^1.1.6"
+  }
+}

package/src/config.js

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const MERR_DIR = join(homedir(), ".merr");
+const SOUNDS_DIR = join(MERR_DIR, "sounds");
+const CONFIG_PATH = join(MERR_DIR, "config.json");
+const DEFAULT_SOUND_PATH = join(MERR_DIR, "default.mp3");
+const BUNDLED_SOUND_PATH = join(__dirname, "..", "assets", "default.mp3");
+
+const DEFAULT_CONFIG = {
+  volume: 80,
+};
+
+const ensureDir = (dir) => {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+};
+
+const ensureDirs = () => {
+  ensureDir(MERR_DIR);
+  ensureDir(SOUNDS_DIR);
+};
+
+const readConfig = () => {
+  ensureDirs();
+  if (!existsSync(CONFIG_PATH)) return { ...DEFAULT_CONFIG };
+
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+};
+
+const writeConfig = (config) => {
+  ensureDirs();
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
+};
+
+const updateConfig = (partial) => {
+  const current = readConfig();
+  const updated = { ...current, ...partial };
+  writeConfig(updated);
+  return updated;
+};
+
+export {
+  MERR_DIR,
+  SOUNDS_DIR,
+  CONFIG_PATH,
+  DEFAULT_SOUND_PATH,
+  BUNDLED_SOUND_PATH,
+  readConfig,
+  writeConfig,
+  updateConfig,
+  ensureDirs,
+};

package/src/runner.js

@@ -0,0 +1,26 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Execute a shell command, piping stdout/stderr through to the parent process.
+ * Returns the exit code of the child process.
+ */
+const runCommand = (commandArgs) =>
+  new Promise((resolve) => {
+    const [cmd, ...args] = commandArgs;
+
+    const child = spawn(cmd, args, {
+      stdio: "inherit",
+      shell: true,
+    });
+
+    child.on("error", (err) => {
+      console.error(`Failed to start command: ${err.message}`);
+      resolve(1);
+    });
+
+    child.on("close", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+
+export { runCommand };

package/src/sound.js

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { existsSync, createWriteStream, copyFileSync } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { join } from "node:path";
+import playSound from "play-sound";
+import {
+  SOUNDS_DIR,
+  DEFAULT_SOUND_PATH,
+  BUNDLED_SOUND_PATH,
+  readConfig,
+  updateConfig,
+  ensureDirs,
+} from "./config.js";
+
+const player = playSound();
+
+/** Hash a URL to create a deterministic cache filename. */
+const hashUrl = (url) =>
+  createHash("sha1").update(url).digest("hex");
+
+/** Download a file from a URL and save it to disk. */
+const downloadFile = async (url, dest) => {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+  if (!res.body) throw new Error("Empty response body");
+  await pipeline(res.body, createWriteStream(dest));
+};
+
+/** Get cached path for a URL, downloading if not already cached. */
+const resolveFromUrl = async (url) => {
+  ensureDirs();
+  const hash = hashUrl(url);
+  const cached = join(SOUNDS_DIR, `${hash}.mp3`);
+
+  if (!existsSync(cached)) {
+    console.log(`⬇  Downloading sound from ${url}...`);
+    await downloadFile(url, cached);
+    console.log(`✓  Cached at ${cached}`);
+  }
+
+  return cached;
+};
+
+/**
+ * Resolve which sound file to play based on CLI options.
+ * Priority: --sound > --url > default
+ */
+const resolveSound = async (options) => {
+  if (options.sound) {
+    if (!existsSync(options.sound)) {
+      console.error(`Error: sound file not found: ${options.sound}`);
+      return null;
+    }
+    return options.sound;
+  }
+
+  if (options.url) {
+    try {
+      return await resolveFromUrl(options.url);
+    } catch (err) {
+      console.error(`Error downloading sound: ${err.message}`);
+      return null;
+    }
+  }
+
+  if (existsSync(DEFAULT_SOUND_PATH)) return DEFAULT_SOUND_PATH;
+
+  // Auto-copy bundled sound on first run
+  if (existsSync(BUNDLED_SOUND_PATH)) {
+    ensureDirs();
+    copyFileSync(BUNDLED_SOUND_PATH, DEFAULT_SOUND_PATH);
+    return DEFAULT_SOUND_PATH;
+  }
+
+  console.warn(
+    "Warning: No default sound found. Run with --sound <file> --set-default to set one."
+  );
+  return null;
+};
+
+/** Play an audio file at the given volume (0–100). */
+const playAudio = (filePath, volume = 80) =>
+  new Promise((resolve, reject) => {
+    const vol = Math.max(0, Math.min(100, volume));
+    // afplay on macOS supports volume as 0-255 scale; we normalize 0-100 → 0-2.55
+    const opts = process.platform === "darwin"
+      ? { afplay: ["-v", (vol / 100 * 2).toFixed(2)] }
+      : {};
+
+    player.play(filePath, opts, (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+
+/** Persist a sound file as the default for future runs. */
+const setDefault = (filePath) => {
+  ensureDirs();
+  copyFileSync(filePath, DEFAULT_SOUND_PATH);
+  console.log(`✓  Default sound saved to ${DEFAULT_SOUND_PATH}`);
+};
+
+/** Persist volume to config. */
+const setVolume = (vol) => {
+  updateConfig({ volume: vol });
+};
+
+export { resolveSound, playAudio, setDefault, setVolume, resolveFromUrl };