pingthings 0.3.0 → 0.5.0

package/src/cli/browse.js

@@ -0,0 +1,75 @@
+import { readConfig } from '../config.js';
+import { listPacks } from '../packs.js';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings browse [category]
+
+Browse packs by category.
+
+With no arguments, shows all categories with pack counts.
+With a category, shows packs in that category.
+
+Categories: military, arena, fantasy, sci-fi, fps, retro, ui, transport, spooky, racing
+
+Examples:
+  pingthings browse              List all categories
+  pingthings browse military     Show military packs
+  pingthings browse sci-fi       Show sci-fi packs
+`);
+}
+
+export default function browse(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const config = readConfig();
+  const packs = listPacks();
+  const category = args[0];
+
+  if (!category) {
+    // Show all categories with counts
+    const categories = {};
+    for (const pack of packs) {
+      const cat = pack.category || 'other';
+      if (!categories[cat]) categories[cat] = [];
+      categories[cat].push(pack);
+    }
+
+    console.log('\nCategories:\n');
+    for (const [cat, catPacks] of Object.entries(categories).sort()) {
+      const totalSounds = catPacks.reduce((sum, p) => sum + p.soundCount, 0);
+      console.log(`  ${cat.padEnd(14)} ${catPacks.length} pack${catPacks.length === 1 ? '' : 's'}, ${totalSounds} sounds`);
+      for (const p of catPacks) {
+        const active = p.name === config.activePack ? ' *' : '  ';
+        console.log(`  ${active} └ ${p.name}`);
+      }
+    }
+    console.log('\n  * = active pack');
+    console.log('  Run "pingthings browse <category>" to see details.\n');
+    return;
+  }
+
+  // Show packs in a specific category
+  const filtered = packs.filter(p => (p.category || 'other') === category);
+
+  if (filtered.length === 0) {
+    console.error(`No packs found in category: ${category}`);
+    const allCats = [...new Set(packs.map(p => p.category || 'other'))].sort();
+    console.error(`Available categories: ${allCats.join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`\n${category} packs:\n`);
+  for (const pack of filtered) {
+    const active = pack.name === config.activePack ? ' *' : '  ';
+    console.log(`${active} ${pack.name}  (${pack.soundCount} sounds)`);
+    if (pack.description) {
+      console.log(`     ${pack.description}`);
+    }
+    console.log(`     License: ${pack.license}`);
+  }
+  console.log('\n  * = active pack\n');
+}

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/search.js

@@ -0,0 +1,81 @@
+import { readConfig } from '../config.js';
+import { listPacks, getPackSounds } from '../packs.js';
+import { basename } from 'node:path';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings search <term>
+
+Search across all packs by name, description, category, or sound filename.
+
+Arguments:
+  term    Text to search for (case-insensitive)
+
+Examples:
+  pingthings search sword         Find packs/sounds with "sword"
+  pingthings search military      Find military category packs
+  pingthings search explosion     Find explosion sounds
+  pingthings search coin          Find coin/pickup sounds
+`);
+}
+
+export default function search(args) {
+  const term = args[0];
+
+  if (!term || term === '--help' || term === '-h') {
+    showHelp();
+    if (!term) process.exit(1);
+    return;
+  }
+
+  const query = term.toLowerCase();
+  const config = readConfig();
+  const packs = listPacks();
+  const results = { packs: [], sounds: [] };
+
+  for (const pack of packs) {
+    // Check pack-level matches
+    const packMatch =
+      pack.name.toLowerCase().includes(query) ||
+      pack.description.toLowerCase().includes(query) ||
+      (pack.category || '').toLowerCase().includes(query);
+
+    if (packMatch) {
+      results.packs.push(pack);
+    }
+
+    // Check individual sounds
+    const sounds = getPackSounds(pack.name);
+    for (const sound of sounds) {
+      const name = basename(sound).toLowerCase();
+      if (name.includes(query)) {
+        results.sounds.push({ pack: pack.name, sound: basename(sound), path: sound });
+      }
+    }
+  }
+
+  if (results.packs.length === 0 && results.sounds.length === 0) {
+    console.log(`No results for "${term}".`);
+    return;
+  }
+
+  if (results.packs.length > 0) {
+    console.log(`\nPacks matching "${term}":\n`);
+    for (const pack of results.packs) {
+      const active = pack.name === config.activePack ? ' *' : '  ';
+      console.log(`${active} ${pack.name}  (${pack.category}, ${pack.soundCount} sounds)`);
+      if (pack.description) {
+        console.log(`     ${pack.description}`);
+      }
+    }
+  }
+
+  if (results.sounds.length > 0) {
+    console.log(`\nSounds matching "${term}":\n`);
+    for (const s of results.sounds) {
+      console.log(`   ${s.pack} / ${s.sound}`);
+    }
+  }
+
+  console.log('');
+}