pingthings 0.4.0 → 0.6.0

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', 'notifications'];
 
 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 boolean keys
+  if (key === 'notifications' || key === 'cooldown') {
+    if (value !== 'true' && value !== 'false') {
+      console.error(`${key} must be true or false.`);
+      process.exit(1);
+    }
+    const cfg = readConfig();
+    cfg[key] = value === 'true';
+    writeConfig(cfg);
+    console.log(`${key} set to: ${cfg[key]}`);
+    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/first-run.js

@@ -0,0 +1,59 @@
+import { createInterface } from 'node:readline';
+import { writeConfig, getDefaults } from '../config.js';
+import { listPacks, getPackSounds, pickRandom } from '../packs.js';
+import { playSound } from '../player.js';
+import { basename } from 'node:path';
+
+export async function runFirstTimeSetup() {
+  const packs = listPacks();
+
+  console.log('\n  ================================================');
+  console.log('     WELCOME TO PINGTHINGS!');
+  console.log('     Your terminal is about to get a LOT cooler.');
+  console.log('  ================================================\n');
+  console.log('  Let\'s pick your first sound pack.\n');
+
+  for (let i = 0; i < packs.length; i++) {
+    console.log(`    ${i + 1}. ${packs[i].name}  (${packs[i].category})`);
+    console.log(`       ${packs[i].description}`);
+  }
+
+  console.log('\n  Enter a number to preview, then press enter to confirm.\n');
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  const chosen = await new Promise((resolve) => {
+    const ask = () => {
+      rl.question('  Pick a pack (1-' + packs.length + '): ', (answer) => {
+        const num = parseInt(answer.trim(), 10);
+        if (isNaN(num) || num < 1 || num > packs.length) {
+          console.log(`  Enter a number between 1 and ${packs.length}.`);
+          ask();
+          return;
+        }
+
+        const pack = packs[num - 1];
+        const sounds = getPackSounds(pack.name);
+        if (sounds.length > 0) {
+          const sample = pickRandom(sounds);
+          console.log(`\n  Preview: ${basename(sample)}`);
+          playSound(sample);
+        }
+
+        resolve(pack);
+      });
+    };
+    ask();
+  });
+
+  // Save config
+  const config = getDefaults();
+  config.activePack = chosen.name;
+  writeConfig(config);
+
+  console.log(`\n  Active pack set to: ${chosen.name}`);
+  console.log('\n  Quick tip: Run "pingthings init" to set up Claude Code hooks.');
+  console.log('  Or just run "pingthings play" anytime to hear a sound.\n');
+
+  rl.close();
+}

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,15 +1,18 @@
-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 { sendNotification } from '../notify.js';
 import { basename } from 'node:path';
 
 function parseArgs(args) {
-  const result = { sound: null, event: null };
+  const result = { sound: null, event: null, notify: false };
 
   for (let i = 0; i < args.length; i++) {
     if ((args[i] === '--event' || args[i] === '-e') && args[i + 1]) {
       result.event = args[i + 1];
       i++;
+    } else if (args[i] === '--notify' || args[i] === '-n') {
+      result.notify = true;
     } else if (args[i] === '--help' || args[i] === '-h') {
       showHelp();
       process.exit(0);
@@ -133,5 +136,32 @@ 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);
+
+  // Desktop notification
+  if (parsed.notify || config.notifications) {
+    const event = parsed.event || 'notification';
+    sendNotification('pingthings', `${event}: ${basename(soundFile)}`);
+  }
 }

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)) {