pingthings 0.4.0 → 0.5.0

package/README.md

@@ -137,8 +137,11 @@ For different sounds based on what Claude is doing, set up multiple hooks:
 | `pingthings browse [category]` | Browse packs by category |
 | `pingthings search <term>` | Search packs and sounds |
 | `pingthings sounds [pack]` | List individual sounds in a pack |
+| `pingthings random-pack` | Switch to a random pack |
 | `pingthings install <source>` | Install a pack from GitHub or local path |
 | `pingthings uninstall <pack>` | Remove a user-installed pack |
+| `pingthings doctor` | Diagnose audio setup and configuration |
+| `pingthings completions <shell>` | Generate shell completions (bash/zsh/fish) |
 
 ## Configuration
 
@@ -231,6 +234,12 @@ Clean modern UI notification sounds by **Kenney** — 18 sounds including confir
 ### kenney-scifi
 Futuristic sci-fi notification sounds by **Kenney** — 18 sounds including computer noises, force fields, lasers, explosions, and thrusters. License: CC0.
 
+### xonotic-announcer
+Arena FPS announcer voice lines from **Xonotic** — 15 sounds including "awesome!", "amazing!", "impressive!", "prepare for battle!", "terminated!". License: GPL v2+.
+
+### fighting-announcer
+Fighting game announcer voice lines — 20 sounds including "Fight!", "Victory!", "K.O!", "Game Over!", "Ready?", "You Win!". License: CC-BY 4.0.
+
 ## Custom packs
 
 Place packs in `~/.config/pingthings/packs/<pack-name>/`:
@@ -291,6 +300,9 @@ pingthings theme reset        # back to defaults
 | `arena` | Arena announcer with FPS weapons for errors |
 | `fantasy` | Medieval fantasy — Wesnoth + 0 A.D. civilizations |
 | `ancient` | Ancient world — 7kaa soldiers + 0 A.D. voices |
+| `professional` | Clean and minimal — Kenney UI sounds for everything |
+| `8bit` | Pure retro — 8-bit chiptune for everything |
+| `space` | Space station — Warzone 2100 + Kenney sci-fi |
 | `chaos` | Different pack for every event — maximum variety |
 
 ## Tools

package/bin/pingthings.js

@@ -26,6 +26,9 @@ const commands = {
   create: () => import('../src/cli/create.js'),
   theme: () => import('../src/cli/theme.js'),
   'test-events': () => import('../src/cli/test-events.js'),
+  'random-pack': () => import('../src/cli/random-pack.js'),
+  doctor: () => import('../src/cli/doctor.js'),
+  completions: () => import('../src/cli/completions.js'),
 };
 
 function showHelp() {
@@ -47,9 +50,12 @@ Commands:
   theme [name]       Apply a sound theme (maps events across packs)
   config [key] [val] Show or update configuration
   init               Set up Claude Code hooks automatically
+  random-pack        Switch to a random pack
   create <dir>       Create a new pack from a folder of audio files
   install <source>   Install a pack from GitHub or URL
   uninstall <pack>   Remove a user-installed pack
+  doctor             Diagnose audio setup and configuration
+  completions <shell> Generate shell completions (bash/zsh/fish)
 
 Options:
   --help, -h         Show this help message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pingthings",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Notification sounds for Claude Code and other CLI tools",
   "type": "module",
   "license": "GPL-2.0",

package/packs/fighting-announcer/manifest.json

@@ -0,0 +1,62 @@
+{
+  "name": "fighting-announcer",
+  "description": "Fighting game announcer voice lines",
+  "version": "1.0.0",
+  "license": "CC-BY-4.0",
+  "credits": "Alba MacKenna (https://opengameart.org/content/voice-pack%E2%94%82fighting-game-announcer)",
+  "category": "arena",
+  "sounds": [
+    "sounds/begin.wav",
+    "sounds/complete.wav",
+    "sounds/congratulations.wav",
+    "sounds/defeat.wav",
+    "sounds/failure.wav",
+    "sounds/fight.wav",
+    "sounds/final-round.wav",
+    "sounds/finish.wav",
+    "sounds/game-over.wav",
+    "sounds/get-set.wav",
+    "sounds/go.wav",
+    "sounds/great.wav",
+    "sounds/high-score.wav",
+    "sounds/new-record.wav",
+    "sounds/no-contest.wav",
+    "sounds/ready.wav",
+    "sounds/sudden-death.wav",
+    "sounds/victory.wav",
+    "sounds/you-lose.wav",
+    "sounds/you-win.wav"
+  ],
+  "events": {
+    "done": [
+      "sounds/complete.wav",
+      "sounds/great.wav",
+      "sounds/finish.wav",
+      "sounds/new-record.wav"
+    ],
+    "permission": [
+      "sounds/fight.wav",
+      "sounds/ready.wav",
+      "sounds/get-set.wav",
+      "sounds/begin.wav",
+      "sounds/go.wav"
+    ],
+    "complete": [
+      "sounds/victory.wav",
+      "sounds/you-win.wav",
+      "sounds/congratulations.wav",
+      "sounds/high-score.wav"
+    ],
+    "error": [
+      "sounds/game-over.wav",
+      "sounds/defeat.wav",
+      "sounds/you-lose.wav",
+      "sounds/failure.wav"
+    ],
+    "blocked": [
+      "sounds/sudden-death.wav",
+      "sounds/final-round.wav",
+      "sounds/no-contest.wav"
+    ]
+  }
+}

package/packs/wesnoth-combat/manifest.json

@@ -2,7 +2,7 @@
   "name": "wesnoth-combat",
   "description": "Fantasy combat and magic sounds from Battle for Wesnoth",
   "version": "1.0.0",
-  "license": "GPL-2.0",
+  "license": "GPL-2.0-or-later",
   "credits": "Battle for Wesnoth contributors (https://github.com/wesnoth/wesnoth) — licensed under GPL v2+",
   "category": "fantasy",
   "sounds": [

package/packs/xonotic-announcer/manifest.json

@@ -0,0 +1,52 @@
+{
+  "name": "xonotic-announcer",
+  "description": "Arena FPS announcer voice lines from Xonotic",
+  "version": "1.0.0",
+  "license": "GPL-2.0-or-later",
+  "credits": "Xonotic Project (https://github.com/xonotic/xonotic-data.pk3dir)",
+  "category": "arena",
+  "sounds": [
+    "sounds/1fragleft.wav",
+    "sounds/airshot.wav",
+    "sounds/amazing.wav",
+    "sounds/awesome.wav",
+    "sounds/begin.wav",
+    "sounds/botlike.wav",
+    "sounds/electrobitch.wav",
+    "sounds/headshot.wav",
+    "sounds/impressive.wav",
+    "sounds/lastsecond.wav",
+    "sounds/leadgained.wav",
+    "sounds/narrowly.wav",
+    "sounds/prepareforbattle.wav",
+    "sounds/terminated.wav",
+    "sounds/yoda.wav"
+  ],
+  "events": {
+    "done": [
+      "sounds/awesome.wav",
+      "sounds/amazing.wav",
+      "sounds/impressive.wav",
+      "sounds/airshot.wav"
+    ],
+    "permission": [
+      "sounds/prepareforbattle.wav",
+      "sounds/begin.wav",
+      "sounds/1fragleft.wav"
+    ],
+    "complete": [
+      "sounds/yoda.wav",
+      "sounds/botlike.wav",
+      "sounds/leadgained.wav"
+    ],
+    "error": [
+      "sounds/terminated.wav",
+      "sounds/headshot.wav",
+      "sounds/electrobitch.wav"
+    ],
+    "blocked": [
+      "sounds/lastsecond.wav",
+      "sounds/narrowly.wav"
+    ]
+  }
+}

package/src/cli/completions.js

@@ -0,0 +1,182 @@
+function showHelp() {
+  console.log(`
+Usage: pingthings completions <shell>
+
+Generate shell completion script.
+
+Arguments:
+  shell    bash, zsh, or fish
+
+Install:
+  pingthings completions bash >> ~/.bashrc
+  pingthings completions zsh >> ~/.zshrc
+  pingthings completions fish > ~/.config/fish/completions/pingthings.fish
+`);
+}
+
+const COMMANDS = [
+  'play', 'list', 'select', 'browse', 'search', 'sounds',
+  'use', 'preview', 'test-events', 'theme', 'config',
+  'init', 'create', 'install', 'uninstall', 'random-pack', 'doctor', 'completions',
+];
+
+const THEMES = [
+  'retro', 'sci-fi', 'arena', 'fantasy', 'ancient',
+  'professional', '8bit', 'space', 'chaos', 'reset',
+];
+
+const EVENTS = ['done', 'permission', 'complete', 'error', 'blocked'];
+
+function bash() {
+  return `# pingthings bash completions
+_pingthings() {
+  local cur prev commands
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  commands="${COMMANDS.join(' ')}"
+
+  case "\${prev}" in
+    pingthings)
+      COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )
+      return 0
+      ;;
+    use|preview|sounds|test-events|uninstall)
+      local packs=$(pingthings list 2>/dev/null | grep -oE '\\S+-\\S+' | head -20)
+      COMPREPLY=( $(compgen -W "\${packs}" -- "\${cur}") )
+      return 0
+      ;;
+    theme)
+      COMPREPLY=( $(compgen -W "${THEMES.join(' ')}" -- "\${cur}") )
+      return 0
+      ;;
+    --event|-e)
+      COMPREPLY=( $(compgen -W "${EVENTS.join(' ')}" -- "\${cur}") )
+      return 0
+      ;;
+    browse)
+      local cats="military arena fantasy sci-fi fps retro ui transport spooky racing"
+      COMPREPLY=( $(compgen -W "\${cats}" -- "\${cur}") )
+      return 0
+      ;;
+    completions)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${cur}") )
+      return 0
+      ;;
+  esac
+
+  return 0
+}
+complete -F _pingthings pingthings`;
+}
+
+function zsh() {
+  return `# pingthings zsh completions
+_pingthings() {
+  local -a commands themes events
+  commands=(
+    'play:Play a sound from the active pack'
+    'list:Show available sound packs'
+    'select:Interactive pack selector'
+    'browse:Browse packs by category'
+    'search:Search packs and sounds'
+    'sounds:List individual sounds in a pack'
+    'use:Set the active sound pack'
+    'preview:Preview a random sound from a pack'
+    'test-events:Play all event sounds'
+    'theme:Apply a sound theme'
+    'config:Show or update configuration'
+    'init:Set up Claude Code hooks'
+    'create:Create a pack from audio files'
+    'install:Install a pack from GitHub or local path'
+    'uninstall:Remove a user-installed pack'
+    'random-pack:Switch to a random pack'
+    'doctor:Diagnose audio setup'
+    'completions:Generate shell completions'
+  )
+  themes=(${THEMES.join(' ')})
+  events=(${EVENTS.join(' ')})
+
+  _arguments '1:command:->cmds' '*::arg:->args'
+
+  case "$state" in
+    cmds)
+      _describe -t commands 'pingthings command' commands
+      ;;
+    args)
+      case $words[1] in
+        use|preview|sounds|test-events|uninstall)
+          local packs=($(pingthings list 2>/dev/null | grep -oE '\\S+-\\S+' | head -20))
+          _describe -t packs 'pack' packs
+          ;;
+        theme)
+          _describe -t themes 'theme' themes
+          ;;
+        browse)
+          local cats=(military arena fantasy sci-fi fps retro ui transport spooky racing)
+          _describe -t categories 'category' cats
+          ;;
+        completions)
+          _describe -t shells 'shell' '(bash zsh fish)'
+          ;;
+      esac
+      ;;
+  esac
+}
+compdef _pingthings pingthings`;
+}
+
+function fish() {
+  const lines = [
+    '# pingthings fish completions',
+    'complete -c pingthings -f',
+  ];
+
+  const cmdDescs = {
+    play: 'Play a sound', list: 'Show packs', select: 'Interactive picker',
+    browse: 'Browse by category', search: 'Search packs', sounds: 'List sounds',
+    use: 'Set active pack', preview: 'Preview a pack', 'test-events': 'Test event sounds',
+    theme: 'Apply a theme', config: 'Configuration', init: 'Set up hooks',
+    create: 'Create a pack', install: 'Install a pack', uninstall: 'Remove a pack',
+    'random-pack': 'Random pack', doctor: 'Diagnose setup', completions: 'Shell completions',
+  };
+
+  for (const [cmd, desc] of Object.entries(cmdDescs)) {
+    lines.push(`complete -c pingthings -n '__fish_use_subcommand' -a '${cmd}' -d '${desc}'`);
+  }
+
+  for (const t of THEMES) {
+    lines.push(`complete -c pingthings -n '__fish_seen_subcommand_from theme' -a '${t}'`);
+  }
+
+  for (const e of EVENTS) {
+    lines.push(`complete -c pingthings -n '__fish_seen_subcommand_from play' -l 'event' -a '${e}'`);
+  }
+
+  return lines.join('\n');
+}
+
+export default function completions(args) {
+  const shell = args[0];
+
+  if (!shell || shell === '--help' || shell === '-h') {
+    showHelp();
+    if (!shell) process.exit(1);
+    return;
+  }
+
+  switch (shell) {
+    case 'bash':
+      console.log(bash());
+      break;
+    case 'zsh':
+      console.log(zsh());
+      break;
+    case 'fish':
+      console.log(fish());
+      break;
+    default:
+      console.error(`Unknown shell: ${shell}. Use bash, zsh, or fish.`);
+      process.exit(1);
+  }
+}

package/src/cli/config.js

@@ -1,6 +1,6 @@
 import { readConfig, writeConfig, VALID_MODES, VALID_EVENTS } from '../config.js';
 
-const VALID_KEYS = ['activePack', 'mode', 'specificSound', 'volume', 'eventPacks'];
+const VALID_KEYS = ['activePack', 'mode', 'specificSound', 'volume', 'eventPacks', 'cooldown', 'quietHours'];
 
 function showHelp() {
   console.log(`
@@ -17,13 +17,16 @@ Keys:
   mode            random, specific, or informational
   specificSound   Sound name for specific mode
   volume          Playback volume (0-100)
+  cooldown        Avoid repeating the same sound (true/false)
+  quietHours      Mute during hours, e.g. "22-7" (10pm-7am)
   eventPacks      Per-event pack overrides (use "pingthings config eventPacks.<event> <pack>")
 
 Examples:
   pingthings config                          Show full config
-  pingthings config volume                   Show current volume
   pingthings config volume 50               Set volume to 50%
-  pingthings config mode informational      Enable event-based sounds
+  pingthings config cooldown false          Disable cooldown
+  pingthings config quietHours 22-7         Mute 10pm to 7am
+  pingthings config quietHours null         Disable quiet hours
   pingthings config eventPacks.error openarena-announcer
 `);
 }
@@ -109,6 +112,32 @@ export default function config(args) {
     return;
   }
 
+  // Validate cooldown
+  if (key === 'cooldown') {
+    if (value !== 'true' && value !== 'false') {
+      console.error('Cooldown must be true or false.');
+      process.exit(1);
+    }
+    const cfg = readConfig();
+    cfg.cooldown = value === 'true';
+    writeConfig(cfg);
+    console.log(`cooldown set to: ${cfg.cooldown}`);
+    return;
+  }
+
+  // Validate quietHours
+  if (key === 'quietHours') {
+    if (value !== 'null' && !/^\d{1,2}-\d{1,2}$/.test(value)) {
+      console.error('Quiet hours must be in format "HH-HH" (e.g., "22-7") or "null" to disable.');
+      process.exit(1);
+    }
+    const cfg = readConfig();
+    cfg.quietHours = value === 'null' ? null : value;
+    writeConfig(cfg);
+    console.log(`quietHours set to: ${cfg.quietHours ?? '(disabled)'}`);
+    return;
+  }
+
   // Two args: set value
   const cfg = readConfig();
   cfg[key] = value === 'null' ? null : value;

package/src/cli/create.js

@@ -24,7 +24,7 @@ Examples:
 `);
 }
 
-export default async function create(args) {
+export default function create(args) {
   if (args.includes('--help') || args.includes('-h')) {
     showHelp();
     return;

package/src/cli/doctor.js

@@ -0,0 +1,134 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { platform, homedir } from 'node:os';
+import { readConfig, getConfigDir } from '../config.js';
+import { listPacks } from '../packs.js';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings doctor
+
+Diagnose audio setup, check player availability, verify packs,
+and validate Claude Code hook configuration.
+`);
+}
+
+function check(label, fn) {
+  try {
+    const result = fn();
+    if (result === true) {
+      console.log(`  OK  ${label}`);
+    } else if (result === false) {
+      console.log(`  !!  ${label}`);
+    } else {
+      console.log(`  OK  ${label}: ${result}`);
+    }
+    return result;
+  } catch (err) {
+    console.log(`  !!  ${label}: ${err.message}`);
+    return false;
+  }
+}
+
+function commandExists(cmd) {
+  try {
+    execFileSync('which', [cmd], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export default function doctor(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  console.log('\npingthings doctor\n');
+
+  // Platform
+  console.log('Platform:');
+  check('Operating system', () => {
+    const os = platform();
+    const names = { darwin: 'macOS', linux: 'Linux', win32: 'Windows' };
+    return names[os] || os;
+  });
+
+  // Audio player
+  console.log('\nAudio player:');
+  let hasPlayer = false;
+  if (platform() === 'darwin') {
+    hasPlayer = check('afplay available', () => commandExists('afplay'));
+  } else if (platform() === 'linux') {
+    const pa = check('paplay available (PulseAudio/PipeWire)', () => commandExists('paplay'));
+    const al = check('aplay available (ALSA)', () => commandExists('aplay'));
+    hasPlayer = pa || al;
+  } else if (platform() === 'win32') {
+    hasPlayer = check('PowerShell available', () => commandExists('powershell'));
+  }
+  if (!hasPlayer) {
+    console.log('\n  No audio player found! Sounds will not play.');
+    if (platform() === 'linux') {
+      console.log('  Install: sudo apt install pulseaudio-utils (Ubuntu/Debian)');
+      console.log('  Or: sudo apt install alsa-utils');
+    }
+  }
+
+  // Config
+  console.log('\nConfiguration:');
+  const config = readConfig();
+  check('Config directory', () => getConfigDir());
+  check('Active pack', () => config.activePack);
+  check('Mode', () => config.mode);
+  check('Volume', () => `${config.volume}%`);
+  if (config.quietHours) {
+    check('Quiet hours', () => config.quietHours);
+  }
+
+  // Packs
+  console.log('\nPacks:');
+  const packs = listPacks();
+  check('Built-in packs', () => {
+    const builtIn = packs.filter(p => p.isBuiltIn);
+    return `${builtIn.length} packs, ${builtIn.reduce((s, p) => s + p.soundCount, 0)} sounds`;
+  });
+  check('User packs', () => {
+    const user = packs.filter(p => !p.isBuiltIn);
+    return user.length > 0 ? `${user.length} packs` : 'none';
+  });
+
+  // Active pack validation
+  const activePack = packs.find(p => p.name === config.activePack);
+  if (!activePack) {
+    check('Active pack exists', () => { throw new Error(`"${config.activePack}" not found`); });
+  } else {
+    check('Active pack valid', () => `${activePack.name} (${activePack.soundCount} sounds)`);
+  }
+
+  // Claude Code hooks
+  console.log('\nClaude Code integration:');
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const hooks = settings.hooks || {};
+      const hasPingthings = JSON.stringify(hooks).includes('pingthings');
+      check('settings.json found', () => true);
+      check('pingthings hooks configured', () => hasPingthings);
+      if (hasPingthings) {
+        const hookTypes = Object.keys(hooks).filter(k =>
+          JSON.stringify(hooks[k]).includes('pingthings')
+        );
+        check('Hook events', () => hookTypes.join(', '));
+      }
+    } catch {
+      check('settings.json valid', () => false);
+    }
+  } else {
+    check('settings.json found', () => { throw new Error('Run "pingthings init" to set up'); });
+  }
+
+  console.log('');
+}

package/src/cli/init.js

@@ -113,13 +113,16 @@ export default async function init(args) {
     output: process.stdout,
   });
 
-  rl.question('Choose (1 or 2): ', (answer) => {
-    const choice = answer.trim();
-    if (choice === '2') {
-      applyHooks('informational');
-    } else {
-      applyHooks('basic');
-    }
-    rl.close();
+  await new Promise((resolve) => {
+    rl.question('Choose (1 or 2): ', (answer) => {
+      const choice = answer.trim();
+      if (choice === '2') {
+        applyHooks('informational');
+      } else {
+        applyHooks('basic');
+      }
+      rl.close();
+      resolve();
+    });
   });
 }

package/src/cli/play.js

@@ -1,4 +1,4 @@
-import { readConfig, VALID_EVENTS } from '../config.js';
+import { readConfig, VALID_EVENTS, getLastPlayed, setLastPlayed, isQuietHours } from '../config.js';
 import { getPackSounds, getEventSounds, pickRandom, resolvePack } from '../packs.js';
 import { playSound } from '../player.js';
 import { basename } from 'node:path';
@@ -133,5 +133,26 @@ export default function play(args) {
     process.exit(1);
   }
 
+  // Quiet hours check
+  if (isQuietHours(config)) {
+    return;
+  }
+
+  // Cooldown: avoid playing the same sound twice in a row
+  if (config.cooldown && !parsed.sound) {
+    const lastPlayed = getLastPlayed();
+    if (soundFile === lastPlayed) {
+      // Pick a different sound from the same pool
+      const pool = parsed.event
+        ? getEventSounds(config.eventPacks?.[parsed.event] || packName, parsed.event)
+        : getPackSounds(packName);
+      if (pool.length > 1) {
+        const alternatives = pool.filter(s => s !== lastPlayed);
+        soundFile = pickRandom(alternatives);
+      }
+    }
+  }
+
+  setLastPlayed(soundFile);
   playSound(soundFile, config.volume);
 }

package/src/cli/random-pack.js

@@ -0,0 +1,44 @@
+import { readConfig, writeConfig } from '../config.js';
+import { listPacks, getPackSounds, pickRandom } from '../packs.js';
+import { playSound } from '../player.js';
+import { basename } from 'node:path';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings random-pack
+
+Switch to a random pack for variety. Plays a preview sound from the new pack.
+`);
+}
+
+export default function randomPack(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const config = readConfig();
+  const packs = listPacks();
+
+  if (packs.length <= 1) {
+    console.log('Only one pack available.');
+    return;
+  }
+
+  // Pick a different pack than the current one
+  const others = packs.filter(p => p.name !== config.activePack);
+  const chosen = others[Math.floor(Math.random() * others.length)];
+
+  config.activePack = chosen.name;
+  writeConfig(config);
+
+  const sounds = getPackSounds(chosen.name);
+  if (sounds.length > 0) {
+    const sample = pickRandom(sounds);
+    console.log(`Switched to: ${chosen.name} (${chosen.category})`);
+    console.log(`Preview: ${basename(sample)}`);
+    playSound(sample, config.volume);
+  } else {
+    console.log(`Switched to: ${chosen.name}`);
+  }
+}

package/src/cli/select.js

@@ -45,37 +45,41 @@ export default async function select(args) {
     output: process.stdout,
   });
 
-  const ask = () => {
-    rl.question('> ', (answer) => {
-      const trimmed = answer.trim().toLowerCase();
-
-      if (trimmed === 'q' || trimmed === 'quit' || trimmed === '') {
+  await new Promise((resolve) => {
+    const ask = () => {
+      rl.question('> ', (answer) => {
+        const trimmed = answer.trim().toLowerCase();
+
+        if (trimmed === 'q' || trimmed === 'quit' || trimmed === '') {
+          rl.close();
+          resolve();
+          return;
+        }
+
+        const num = parseInt(trimmed, 10);
+        if (isNaN(num) || num < 1 || num > packs.length) {
+          console.log(`Enter 1-${packs.length} or q to quit.`);
+          ask();
+          return;
+        }
+
+        const chosen = packs[num - 1];
+        config.activePack = chosen.name;
+        writeConfig(config);
+
+        // Preview a sound from the chosen pack
+        const sounds = getPackSounds(chosen.name);
+        if (sounds.length > 0) {
+          const sample = sounds[Math.floor(Math.random() * sounds.length)];
+          playSound(sample, config.volume);
+        }
+
+        console.log(`\nActive pack set to: ${chosen.name}`);
         rl.close();
-        return;
-      }
-
-      const num = parseInt(trimmed, 10);
-      if (isNaN(num) || num < 1 || num > packs.length) {
-        console.log(`Enter 1-${packs.length} or q to quit.`);
-        ask();
-        return;
-      }
-
-      const chosen = packs[num - 1];
-      config.activePack = chosen.name;
-      writeConfig(config);
-
-      // Preview a sound from the chosen pack
-      const sounds = getPackSounds(chosen.name);
-      if (sounds.length > 0) {
-        const sample = sounds[Math.floor(Math.random() * sounds.length)];
-        playSound(sample, config.volume);
-      }
-
-      console.log(`\nActive pack set to: ${chosen.name}`);
-      rl.close();
-    });
-  };
-
-  ask();
+        resolve();
+      });
+    };
+
+    ask();
+  });
 }

package/src/cli/uninstall.js

@@ -25,6 +25,11 @@ export default function uninstall(args) {
     return;
   }
 
+  if (packName.includes('..') || packName.includes('/') || packName.includes('\\')) {
+    console.error('Invalid pack name.');
+    process.exit(1);
+  }
+
   const userPackDir = join(getConfigDir(), 'packs', packName);
 
   if (!existsSync(userPackDir)) {

package/src/config.js

@@ -8,6 +8,8 @@ const DEFAULTS = {
   specificSound: null,
   volume: 100,
   eventPacks: {},
+  cooldown: true,
+  quietHours: null,
 };
 
 export function getConfigDir() {
@@ -45,6 +47,34 @@ export function getDefaults() {
   return { ...DEFAULTS };
 }
 
+export function getLastPlayed() {
+  const path = join(getConfigDir(), '.last-played');
+  try {
+    return readFileSync(path, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+export function setLastPlayed(soundPath) {
+  const path = join(getConfigDir(), '.last-played');
+  try {
+    writeFileSync(path, soundPath, 'utf8');
+  } catch {}
+}
+
+export function isQuietHours(config) {
+  if (!config.quietHours) return false;
+  const [start, end] = config.quietHours.split('-').map(Number);
+  if (isNaN(start) || isNaN(end)) return false;
+  const hour = new Date().getHours();
+  if (start < end) {
+    return hour >= start && hour < end;
+  }
+  // Wraps midnight (e.g., 22-7)
+  return hour >= start || hour < end;
+}
+
 export const VALID_MODES = ['random', 'specific', 'informational'];
 
 export const VALID_EVENTS = ['done', 'permission', 'complete', 'error', 'blocked'];

package/src/player.js

@@ -2,17 +2,23 @@ import { spawn, execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { platform } from 'node:os';
 
+function commandExists(cmd) {
+  try {
+    execFileSync('which', [cmd], { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function getPlayerCommand() {
   switch (platform()) {
     case 'darwin':
       return 'afplay';
     case 'linux': {
-      try {
-        execFileSync('which', ['paplay'], { stdio: 'pipe' });
-        return 'paplay';
-      } catch {
-        return 'aplay';
-      }
+      if (commandExists('paplay')) return 'paplay';
+      if (commandExists('aplay')) return 'aplay';
+      return null;
     }
     case 'win32':
       return 'powershell';
@@ -26,20 +32,16 @@ function buildArgs(cmd, filePath, volume) {
 
   switch (cmd) {
     case 'afplay': {
-      // afplay volume: 0.0 to 1.0
       const afplayVol = (vol / 100).toFixed(2);
       return ['-v', afplayVol, filePath];
     }
     case 'paplay': {
-      // paplay volume: 0 to 65536 (100% = 65536)
       const paplayVol = Math.round((vol / 100) * 65536).toString();
       return ['--volume', paplayVol, filePath];
     }
     case 'aplay':
-      // aplay doesn't support volume natively
       return [filePath];
     case 'powershell': {
-      // PowerShell SoundPlayer doesn't support volume, but it plays the file
       const script = `(New-Object System.Media.SoundPlayer '${filePath.replace(/'/g, "''")}').PlaySync()`;
       return ['-NoProfile', '-Command', script];
     }
@@ -55,7 +57,8 @@ export function playSound(filePath, volume) {
 
   const cmd = getPlayerCommand();
   if (!cmd) {
-    throw new Error(`Unsupported platform: ${platform()}. Supported: macOS, Linux, Windows.`);
+    // No audio player available — skip silently (e.g. CI environments)
+    return;
   }
 
   const args = buildArgs(cmd, filePath, volume);
@@ -65,6 +68,8 @@ export function playSound(filePath, volume) {
     stdio: 'ignore',
   });
 
+  // Handle spawn errors gracefully (command not found, permission denied)
+  child.on('error', () => {});
   child.unref();
 }
 
@@ -75,7 +80,7 @@ export function playSoundSync(filePath, volume) {
 
   const cmd = getPlayerCommand();
   if (!cmd) {
-    throw new Error(`Unsupported platform: ${platform()}. Supported: macOS, Linux, Windows.`);
+    return;
   }
 
   const args = buildArgs(cmd, filePath, volume);