pingthings 0.8.0 → 0.9.0

package/bin/pingthings.js

@@ -23,6 +23,9 @@ const commands = {
   install: () => import('../src/cli/install.js'),
   uninstall: () => import('../src/cli/uninstall.js'),
   init: () => import('../src/cli/init.js'),
+  setup: () => import('../src/cli/setup.js'),
+  demo: () => import('../src/cli/demo.js'),
+  stats: () => import('../src/cli/stats.js'),
   create: () => import('../src/cli/create.js'),
   theme: () => import('../src/cli/theme.js'),
   'test-events': () => import('../src/cli/test-events.js'),
@@ -51,7 +54,10 @@ Commands:
   test-events [pack] Play all event sounds to hear what each one sounds like
   theme [name]       Apply a sound theme (maps events across packs)
   config [key] [val] Show or update configuration
+  demo               Play one sound from every pack — showroom tour
+  stats              Show usage statistics
   init               Set up Claude Code hooks automatically
+  setup <ide>        Configure hooks for any IDE (cursor, copilot, codex, etc.)
   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

package/package.json

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

package/src/cli/demo.js

@@ -0,0 +1,36 @@
+import { readConfig } from '../config.js';
+import { listPacks, getPackSounds, pickRandom } from '../packs.js';
+import { playSoundSync } from '../player.js';
+import { basename } from 'node:path';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings demo
+
+Play one sound from every pack — a showroom tour of all your notification sounds.
+`);
+}
+
+export default function demo(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const config = readConfig();
+  const packs = listPacks();
+
+  console.log(`\n  PINGTHINGS DEMO — ${packs.length} packs\n`);
+
+  for (const pack of packs) {
+    const sounds = getPackSounds(pack.name);
+    if (sounds.length === 0) continue;
+
+    const sound = pickRandom(sounds);
+    const active = pack.name === config.activePack ? ' *' : '  ';
+    console.log(`${active} ${pack.name.padEnd(22)} ${basename(sound)}`);
+    playSoundSync(sound, config.volume);
+  }
+
+  console.log(`\n  * = active pack\n`);
+}

package/src/cli/play.js

@@ -2,10 +2,11 @@ import { readConfig, VALID_EVENTS, getLastPlayed, setLastPlayed, isQuietHours }
 import { getPackSounds, getEventSounds, pickRandom, resolvePack } from '../packs.js';
 import { playSound } from '../player.js';
 import { sendNotification } from '../notify.js';
+import { recordPlay } from './stats.js';
 import { basename } from 'node:path';
 
 function parseArgs(args) {
-  const result = { sound: null, event: null, notify: false };
+  const result = { sound: null, event: null, notify: false, silent: false };
 
   for (let i = 0; i < args.length; i++) {
     if ((args[i] === '--event' || args[i] === '-e') && args[i + 1]) {
@@ -13,6 +14,8 @@ function parseArgs(args) {
       i++;
     } else if (args[i] === '--notify' || args[i] === '-n') {
       result.notify = true;
+    } else if (args[i] === '--silent' || args[i] === '-s') {
+      result.silent = true;
     } else if (args[i] === '--help' || args[i] === '-h') {
       showHelp();
       process.exit(0);
@@ -136,8 +139,9 @@ export default function play(args) {
     process.exit(1);
   }
 
-  // Quiet hours check
-  if (isQuietHours(config)) {
+  // Quiet hours or silent mode — skip playback
+  if (isQuietHours(config) || parsed.silent) {
+    recordPlay(packName, parsed.event);
     return;
   }
 
@@ -145,7 +149,6 @@ export default function play(args) {
   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);
@@ -158,6 +161,7 @@ export default function play(args) {
 
   setLastPlayed(soundFile);
   playSound(soundFile, config.volume);
+  recordPlay(packName, parsed.event);
 
   // Desktop notification
   if (parsed.notify || config.notifications) {

package/src/cli/setup.js

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline';
+
+const IDES = {
+  'claude-code': {
+    name: 'Claude Code',
+    configPath: () => join(homedir(), '.claude', 'settings.json'),
+    generate: (mode) => ({
+      hooks: mode === 'informational' ? {
+        Notification: [{ matcher: '', hooks: [{ type: 'command', command: 'pingthings play --event permission' }] }],
+        Stop: [{ matcher: '', hooks: [{ type: 'command', command: 'pingthings play --event complete' }] }],
+        PostToolUseFailure: [{ matcher: '', hooks: [{ type: 'command', command: 'pingthings play --event error' }] }],
+        StopFailure: [{ matcher: '', hooks: [{ type: 'command', command: 'pingthings play --event blocked' }] }],
+      } : {
+        Notification: [{ matcher: '', hooks: [{ type: 'command', command: 'pingthings play' }] }],
+      },
+    }),
+  },
+  cursor: {
+    name: 'Cursor',
+    configPath: () => join(homedir(), '.cursor', 'hooks.json'),
+    generate: (mode) => ({
+      version: 1,
+      hooks: mode === 'informational' ? {
+        stop: [{ command: 'pingthings play --event complete' }],
+        afterFileEdit: [{ command: 'pingthings play --event done' }],
+      } : {
+        stop: [{ command: 'pingthings play' }],
+      },
+    }),
+  },
+  copilot: {
+    name: 'GitHub Copilot',
+    configPath: () => join('.github', 'hooks', 'pingthings.json'),
+    generate: (mode) => ({
+      version: 1,
+      hooks: mode === 'informational' ? {
+        sessionEnd: [{ type: 'command', bash: 'pingthings play --event complete' }],
+        postToolUse: [{ type: 'command', bash: 'pingthings play --event done' }],
+        errorOccurred: [{ type: 'command', bash: 'pingthings play --event error' }],
+      } : {
+        sessionEnd: [{ type: 'command', bash: 'pingthings play' }],
+      },
+    }),
+  },
+  codex: {
+    name: 'OpenAI Codex',
+    configPath: () => join(homedir(), '.codex', 'config.toml'),
+    generate: () => null, // TOML, handle separately
+    toml: 'notify = ["pingthings", "play", "--event", "complete"]\n',
+  },
+  windsurf: {
+    name: 'Windsurf',
+    configPath: () => join('.windsurf', 'hooks.json'),
+    generate: (mode) => ({
+      hooks: mode === 'informational' ? {
+        post_cascade_response: [{ command: 'pingthings play --event complete' }],
+        post_write_code: [{ command: 'pingthings play --event done' }],
+      } : {
+        post_cascade_response: [{ command: 'pingthings play' }],
+      },
+    }),
+  },
+  gemini: {
+    name: 'Gemini CLI',
+    configPath: () => join(homedir(), '.gemini', 'settings.json'),
+    generate: (mode) => ({
+      hooks: mode === 'informational' ? {
+        SessionEnd: [{ matcher: '*', hooks: [{ type: 'command', command: 'pingthings play --event complete' }] }],
+        AfterTool: [{ matcher: '*', hooks: [{ type: 'command', command: 'pingthings play --event done' }] }],
+        Notification: [{ matcher: 'error', hooks: [{ type: 'command', command: 'pingthings play --event error' }] }],
+      } : {
+        SessionEnd: [{ matcher: '*', hooks: [{ type: 'command', command: 'pingthings play' }] }],
+      },
+    }),
+  },
+};
+
+function showHelp() {
+  console.log(`
+Usage: pingthings setup <ide>
+
+Configure pingthings hooks for your IDE/coding tool.
+
+Supported IDEs:
+  claude-code    Claude Code CLI
+  cursor         Cursor AI editor
+  copilot        GitHub Copilot CLI
+  codex          OpenAI Codex CLI
+  windsurf       Windsurf (Cascade)
+  gemini         Gemini CLI
+
+Options:
+  --basic          Random sounds (no event mapping)
+  --informational  Event-based sounds (recommended)
+
+Examples:
+  pingthings setup cursor
+  pingthings setup copilot --informational
+  pingthings setup codex
+`);
+}
+
+function writeJsonConfig(path, config) {
+  const dir = join(path, '..');
+  mkdirSync(dir, { recursive: true });
+
+  let existing = {};
+  if (existsSync(path)) {
+    try {
+      existing = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {}
+  }
+
+  const merged = { ...existing, ...config };
+  if (existing.hooks && config.hooks) {
+    merged.hooks = { ...existing.hooks, ...config.hooks };
+  }
+
+  const tmpPath = path + '.tmp';
+  writeFileSync(tmpPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  renameSync(tmpPath, path);
+}
+
+export default async function setup(args) {
+  const ideName = args[0];
+
+  if (!ideName || ideName === '--help' || ideName === '-h') {
+    showHelp();
+    if (!ideName) process.exit(1);
+    return;
+  }
+
+  const ide = IDES[ideName];
+  if (!ide) {
+    console.error(`Unknown IDE: ${ideName}`);
+    console.error(`Supported: ${Object.keys(IDES).join(', ')}`);
+    process.exit(1);
+  }
+
+  let mode = 'informational';
+  if (args.includes('--basic')) mode = 'basic';
+
+  const configPath = ide.configPath();
+
+  console.log(`\nSetting up pingthings for ${ide.name}...\n`);
+
+  if (ideName === 'codex') {
+    // Codex uses TOML
+    mkdirSync(join(configPath, '..'), { recursive: true });
+    if (existsSync(configPath)) {
+      const existing = readFileSync(configPath, 'utf8');
+      if (existing.includes('pingthings')) {
+        console.log('pingthings is already configured in Codex.');
+        return;
+      }
+      writeFileSync(configPath, existing + '\n' + ide.toml, 'utf8');
+    } else {
+      writeFileSync(configPath, ide.toml, 'utf8');
+    }
+    console.log(`Written to: ${configPath}`);
+    console.log('Codex will run "pingthings play --event complete" on agent-turn-complete.');
+  } else {
+    const config = ide.generate(mode);
+    writeJsonConfig(configPath, config);
+    console.log(`Written to: ${configPath}`);
+    console.log(`Mode: ${mode}`);
+  }
+
+  console.log('\nRestart your IDE for hooks to take effect.');
+}

package/src/cli/stats.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readConfig, getConfigDir } from '../config.js';
+import { listPacks } from '../packs.js';
+
+function showHelp() {
+  console.log(`
+Usage: pingthings stats
+
+Show usage statistics — total sounds, packs, play count, and more.
+`);
+}
+
+function getStatsPath() {
+  return join(getConfigDir(), 'stats.json');
+}
+
+export function recordPlay(packName, event) {
+  const statsPath = getStatsPath();
+  let stats = { totalPlays: 0, packPlays: {}, eventPlays: {}, dailyPlays: {} };
+
+  if (existsSync(statsPath)) {
+    try {
+      stats = JSON.parse(readFileSync(statsPath, 'utf8'));
+    } catch {}
+  }
+
+  stats.totalPlays = (stats.totalPlays || 0) + 1;
+
+  if (!stats.packPlays) stats.packPlays = {};
+  stats.packPlays[packName] = (stats.packPlays[packName] || 0) + 1;
+
+  if (event) {
+    if (!stats.eventPlays) stats.eventPlays = {};
+    stats.eventPlays[event] = (stats.eventPlays[event] || 0) + 1;
+  }
+
+  const today = new Date().toISOString().split('T')[0];
+  if (!stats.dailyPlays) stats.dailyPlays = {};
+  stats.dailyPlays[today] = (stats.dailyPlays[today] || 0) + 1;
+
+  try {
+    writeFileSync(statsPath, JSON.stringify(stats, null, 2) + '\n', 'utf8');
+  } catch {}
+}
+
+export default function stats(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    showHelp();
+    return;
+  }
+
+  const packs = listPacks();
+  const totalSounds = packs.reduce((s, p) => s + p.soundCount, 0);
+  const statsPath = getStatsPath();
+
+  console.log('\n  PINGTHINGS STATS\n');
+  console.log(`  Packs installed:    ${packs.length}`);
+  console.log(`  Total sounds:       ${totalSounds}`);
+  console.log(`  Categories:         ${new Set(packs.map(p => p.category)).size}`);
+
+  if (!existsSync(statsPath)) {
+    console.log('\n  No play history yet. Start using pingthings!\n');
+    return;
+  }
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(statsPath, 'utf8'));
+  } catch {
+    console.log('\n  No play history yet.\n');
+    return;
+  }
+
+  console.log(`\n  Total plays:        ${data.totalPlays || 0}`);
+
+  const today = new Date().toISOString().split('T')[0];
+  console.log(`  Plays today:        ${data.dailyPlays?.[today] || 0}`);
+
+  if (data.packPlays && Object.keys(data.packPlays).length > 0) {
+    const sorted = Object.entries(data.packPlays).sort((a, b) => b[1] - a[1]);
+    console.log(`\n  Most played packs:`);
+    for (const [pack, count] of sorted.slice(0, 5)) {
+      console.log(`    ${pack.padEnd(24)} ${count} plays`);
+    }
+  }
+
+  if (data.eventPlays && Object.keys(data.eventPlays).length > 0) {
+    console.log(`\n  Events:`);
+    for (const [event, count] of Object.entries(data.eventPlays)) {
+      console.log(`    ${event.padEnd(16)} ${count}`);
+    }
+  }
+
+  console.log('');
+}

package/src/cli/theme.js

@@ -90,6 +90,50 @@ const THEMES = {
       blocked: 'kenney-scifi',
     },
   },
+  'developer': {
+    description: 'AI assistant vibes — droid announcer + human voiceover',
+    activePack: 'droid-announcer',
+    eventPacks: {
+      done: 'droid-announcer',
+      permission: 'droid-announcer',
+      complete: 'kenney-voiceover',
+      error: 'droid-announcer',
+      blocked: 'kenney-voiceover',
+    },
+  },
+  'arcade': {
+    description: 'Full arcade experience — 8-bit everything',
+    activePack: 'retro-8bit',
+    eventPacks: {
+      done: 'retro-8bit',
+      permission: 'retro-movement',
+      complete: 'retro-8bit',
+      error: 'retro-weapons',
+      blocked: 'retro-weapons',
+    },
+  },
+  'tabletop': {
+    description: 'Tavern sounds — RPG foley meets material impacts',
+    activePack: 'kenney-rpg',
+    eventPacks: {
+      done: 'kenney-rpg',
+      permission: 'kenney-rpg',
+      complete: 'kenney-impacts',
+      error: 'kenney-impacts',
+      blocked: 'kenney-impacts',
+    },
+  },
+  'tournament': {
+    description: 'Fighting game tournament — multiple announcers',
+    activePack: 'kenney-fighter',
+    eventPacks: {
+      done: 'fighting-announcer',
+      permission: 'kenney-fighter',
+      complete: 'kenney-fighter',
+      error: 'fighting-announcer',
+      blocked: 'xonotic-announcer',
+    },
+  },
   'chaos': {
     description: 'Random pack for every event — maximum variety',
     activePack: '7kaa-soldiers',