@delorenj/claude-notifications 1.1.0 → 2.0.0

package/FIXES.md

@@ -0,0 +1,75 @@
+# Claude Notifications - Install Process Fixes
+
+## Issues Identified and Fixed
+
+### 1. **Path Migration Inconsistency** ✅ FIXED
+**Problem:** The code migrated from `~/.local/share/sounds/` to `~/.config/claude-notifications/sounds/` but cleanup logic was inconsistent and error-prone.
+**Solution:** 
+- Created centralized `cleanupLegacySoundFiles()` function in `lib/config.js`
+- Properly handles multiple legacy paths with extensible architecture
+- Safe error handling for file operations
+
+### 2. **Missing Configuration Directory Creation** ✅ FIXED  
+**Problem:** Installation could fail if the `~/.config/claude-notifications/` directory didn't exist.
+**Solution:**
+- Added `ensureConfigDirectory()` function to create parent directories
+- Both sound file creation functions now call this before attempting to write
+- Prevents installation failures due to missing directories
+
+### 3. **Incomplete Configuration Migration** ✅ FIXED
+**Problem:** Config migration only handled `secondSound` → `soundType` but didn't validate or save migrated configs.
+**Solution:**
+- Enhanced `getConfig()` with comprehensive migration logic
+- Validates `soundType` values and resets invalid ones  
+- Automatically saves migrated configurations back to disk
+- Clear console logging for migration events
+
+### 4. **Poor Error Handling During Installation** ✅ FIXED
+**Problem:** Installation would fail completely if any single step failed, with no graceful degradation.
+**Solution:**
+- Individual sound file creation returns success/failure status
+- Installation continues even if one sound file fails
+- More informative error messages and status reporting
+- Better test notification feedback
+
+### 5. **Incorrect Reference in test.sh** ✅ FIXED
+**Problem:** `test.sh` referenced non-existent `./install.sh` script.
+**Solution:** Updated error message to reference correct installation commands.
+
+### 6. **Missing Temp Directory Error Handling** ✅ FIXED  
+**Problem:** Sound generation could fail if temporary directory creation failed.
+**Solution:** Added try/catch around temp directory creation with early return on failure.
+
+## Technical Improvements
+
+### Enhanced Error Resilience
+- Installation now continues even if Claude Code config can't be found/updated
+- Sound file creation has individual success tracking
+- Temp directory operations are safely handled
+
+### Better User Experience
+- More descriptive status messages during installation
+- Clear indication of what worked vs. what failed
+- Improved usage instructions after installation
+- Better test feedback
+
+### Code Organization
+- Centralized path management and cleanup logic
+- Consistent error handling patterns
+- Proper separation of concerns between modules
+
+### Backward Compatibility
+- Automatic cleanup of old sound file locations
+- Migration of legacy configuration formats
+- Extensible architecture for future path changes
+
+## Files Modified
+- `bin/claude-notifications.js` - Main installer improvements
+- `lib/config.js` - Enhanced configuration management and migration
+- `test.sh` - Fixed installation reference
+
+## Next Steps for Production
+1. Test installation on clean system
+2. Test upgrade from legacy installation
+3. Verify sound file generation on different platforms
+4. Test Claude Code integration

package/README.md

@@ -20,8 +20,9 @@ That's it! 🎉 The package will automatically:
 ## Features
 
 - 🎵 **Final Fantasy Dream Harp** - Classic C-D-E-G ascending/(optional)descending pattern
+- 🔔 **Service Desk Bell** - Optional short, crisp bell sound for a quick "done!" signal
 - 🔊 **Cross-Platform Audio** - Works on Linux and macOS
-- 🖥️ **Desktop Notifications** - Visual notifications with Claude Code branding
+- 🖥️ **Desktop Notifications** - Visual notifications with Claude Code branding (optional)
 - 🪝 **Auto-Integration** - Automatically configures Claude Code hooks
 - ⚡ **Zero Configuration** - Works out of the box
 -  webhook **Webhook Support** - Trigger a webhook in addition to or instead of the sound
@@ -37,9 +38,15 @@ After installation, Claude Code will begin notifying you when it finishes or is
 # Trigger notification manually
 claude-notify
 
+# Trigger bell notification manually
+claude-notify --bell
+
 # Test the system
 claude-notifications test
 
+# Test the bell sound
+claude-notifications test-bell
+
 # Reinstall/repair
 claude-notifications install
 
@@ -121,6 +128,8 @@ Create a configuration file at `~/.config/claude-notifications/settings.json`.
 ```json
 {
   "sound": true,
+  "soundType": "claude-notification",
+  "desktopNotification": false,
   "webhook": {
     "enabled": true,
     "url": "https://maker.ifttt.com/trigger/claude_notification/with/key/YOUR_KEY",
@@ -131,7 +140,11 @@ Create a configuration file at `~/.config/claude-notifications/settings.json`.
 
 **Configuration Options:**
 
-- `sound`: (boolean) Whether to play the notification sound. Defaults to `true`.
+- `sound`: (boolean) Whether to play notification sounds. Defaults to `true`.
+- `soundType`: (string) Which sound to play. Available options:
+  - `"claude-notification"` - Final Fantasy dream harp (default)
+  - `"claude-notification-bell"` - Service desk bell
+- `desktopNotification`: (boolean) Whether to show desktop notification banners. Defaults to `false`.
 - `webhook.enabled`: (boolean) Whether to trigger the webhook. Defaults to `false`.
 - `webhook.url`: (string) The URL to send the POST request to.
 - `webhook.replaceSound`: (boolean) If `true`, the sound will not play when a webhook is triggered. Defaults to `false`.
@@ -144,6 +157,10 @@ The webhook will be sent as a `POST` request with a JSON payload:
 }
 ```
 
+### Sound Files
+
+Sound files are stored in `~/.config/claude-notifications/sounds/` and can be customized by replacing the `.wav` files in that directory.
+
 ### Create Custom Patterns
 
 Use `sox` to create new victory fanfares:

package/bin/claude-notifications.js

@@ -4,6 +4,7 @@ const { execSync, spawn } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
+const { ensureConfigDirectory, ensureSoundsDirectory, getSoundPath, SOUND_TYPES, soundsDir } = require("../lib/config");
 
 const colors = {
   red: "\x1b[31m",
@@ -106,13 +107,9 @@ function updateClaudeCodeConfig() {
 }
 
 function createSoundFile() {
-  const soundDir = path.join(os.homedir(), ".local", "share", "sounds");
-  const soundFile = path.join(soundDir, "claude-notification.wav");
-
-  // Create directory if it doesn't exist
-  if (!fs.existsSync(soundDir)) {
-    fs.mkdirSync(soundDir, { recursive: true });
-  }
+  ensureConfigDirectory();
+  ensureSoundsDirectory();
+  const soundFile = getSoundPath(SOUND_TYPES.HARP);
 
   // Check if sox is available
   try {
@@ -138,8 +135,13 @@ function createSoundFile() {
 
   // Create individual note files first (safer approach)
   const tempDir = path.join(os.tmpdir(), "claude-notifications");
-  if (!fs.existsSync(tempDir)) {
-    fs.mkdirSync(tempDir, { recursive: true });
+  try {
+    if (!fs.existsSync(tempDir)) {
+      fs.mkdirSync(tempDir, { recursive: true });
+    }
+  } catch (error) {
+    log("red", `❌ Cannot create temp directory: ${error.message}`);
+    return false;
   }
 
   const notes = [
@@ -207,6 +209,80 @@ function createSoundFile() {
   }
 }
 
+function generateBellSoxCommand(outputFile) {
+  // Bell sound parameters - adjust these to customize the bell
+  const bellParams = {
+    // Base tone generation
+    duration: 0.1, // Length of the initial bell strike (seconds)
+    frequency: 1600, // Pitch of the bell (Hz) - higher = more "ting", lower = more "dong"
+
+    // Fade envelope
+    fadeIn: 0, // Fade in time (seconds) - 0 for immediate attack
+    fadeDuration: 0.1, // Total fade duration (seconds)
+    fadeOut: 0.05, // Fade out time (seconds) - creates the bell decay
+
+    // Volume
+    volume: 0.9, // Master volume (0.0 to 1.0)
+
+    // Echo effect parameters (creates the "ringing" quality)
+    echoGain: 0.5, // Overall echo volume (0.0 to 1.0)
+    echoDecay: 0.5, // How quickly echoes fade (0.0 to 1.0)
+
+    // Individual echo delays and volumes (milliseconds, volume)
+    echo1: { delay: 250, volume: 0.2 }, // First echo - quarter second delay
+    echo2: { delay: 500, volume: 0.05 }, // Second echo - half second delay
+    echo3: { delay: 750, volume: 0.01 }, // Third echo - three quarter second delay
+
+    // Reverb parameters (adds spatial depth)
+    reverb: {
+      roomSize: 40, // Room size percentage (0-100) - larger = more spacious
+      preDelay: 65, // Pre-delay in ms - time before reverb starts
+      reverbTime: 100, // Reverb decay time percentage (0-100)
+      wetGain: 100, // Wet signal gain percentage (0-100) - reverb volume
+      dryGain: 12, // Dry signal gain percentage (0-100) - original signal volume
+      stereoDepth: 0, // Stereo depth (0-100) - 0 = mono, higher = wider stereo
+    },
+  };
+
+  // Build the sox command with clear parameter mapping
+  const command = [
+    "sox -n", // Generate from nothing (null input)
+    `"${outputFile}"`, // Output file
+    `synth ${bellParams.duration} sine ${bellParams.frequency}`, // Generate sine wave
+    `fade ${bellParams.fadeIn} ${bellParams.fadeDuration} ${bellParams.fadeOut}`, // Apply fade envelope
+    `vol ${bellParams.volume}`, // Set volume
+    `echos ${bellParams.echoGain} ${bellParams.echoDecay}`, // Echo effect base settings
+    `${bellParams.echo1.delay} ${bellParams.echo1.volume}`, // Echo 1: 250ms delay, 0.2 volume
+    `${bellParams.echo2.delay} ${bellParams.echo2.volume}`, // Echo 2: 500ms delay, 0.1 volume
+    `${bellParams.echo3.delay} ${bellParams.echo3.volume}`, // Echo 3: 750ms delay, 0.05 volume
+    `reverb ${bellParams.reverb.roomSize} ${bellParams.reverb.preDelay}`, // Reverb room & pre-delay
+    `${bellParams.reverb.reverbTime} ${bellParams.reverb.wetGain}`, // Reverb time & wet gain
+    `${bellParams.reverb.dryGain} ${bellParams.reverb.stereoDepth}`, // Dry gain & stereo depth
+  ].join(" ");
+
+  return command;
+}
+
+function createBellSoundFile() {
+  ensureConfigDirectory();
+  ensureSoundsDirectory();
+  const soundFile = getSoundPath(SOUND_TYPES.BELL);
+
+  log("blue", "🔔 Generating service desk bell sound...");
+
+  try {
+    // Generate the bell sound using our documented sox command builder
+    const bellCommand = generateBellSoxCommand(soundFile);
+    execSync(bellCommand, { stdio: "ignore", timeout: 5000 });
+
+    log("green", "✅ Bell sound file created successfully!");
+    return true;
+  } catch (error) {
+    log("red", `❌ Error creating bell sound file: ${error.message}`);
+    return false;
+  }
+}
+
 function main() {
   const command = process.argv[2];
 
@@ -215,38 +291,55 @@ function main() {
     case undefined:
       log("blue", "🎵 Installing Claude Notifications...");
 
-      if (createSoundFile()) {
-        updateClaudeCodeConfig();
-        log("green", "🎉 Installation complete!");
-        log("blue", "🧪 Testing notification...");
+      const soundCreated = createSoundFile();
+      const bellCreated = createBellSoundFile();
+      
+      if (soundCreated && bellCreated) {
+        log("green", "✅ Sound files created successfully!");
+      } else if (soundCreated || bellCreated) {
+        log("yellow", "⚠️  Some sound files failed to create, but installation can continue");
+      } else {
+        log("red", "❌ Failed to create sound files. Please check if sox is installed and try again.");
+        process.exit(1);
+      }
+      
+      // Always try to update Claude Code config, but don't fail if it's not found
+      updateClaudeCodeConfig();
+      
+      log("green", "🎉 Installation complete!");
+      log("blue", "🧪 Testing notification...");
 
-        // Test the notification
-        const testProcess = spawn(
-          "node",
-          [path.join(__dirname, "claude-notify.js")],
-          {
-            stdio: "inherit",
-          },
-        );
+      // Test the notification
+      const testProcess = spawn(
+        "node",
+        [path.join(__dirname, "claude-notify.js")],
+        {
+          stdio: "inherit",
+        },
+      );
 
-        testProcess.on("close", () => {
+      testProcess.on("close", (code) => {
+        if (code === 0) {
           log(
             "green",
-            "✅ Test complete! You should have heard a dreamy notification!",
+            "✅ Test complete! You should have heard a delightful notification!",
           );
-          console.log("");
-          log("blue", "Usage:");
-          console.log(
-            "  claude-notify          # Trigger notification manually",
-          );
-          console.log("  claude-notifications   # This installer");
-          console.log("");
-          log(
-            "blue",
-            "Claude Code will now beckon you back with a pleasant notification when it finishes responses or is waiting for your input! 🎮",
-          );
-        });
-      }
+        } else {
+          log("yellow", "⚠️  Test notification had issues, but installation completed");
+        }
+        console.log("");
+        log("blue", "Usage:");
+        console.log(
+          "  claude-notify              # Trigger notification manually",
+        );
+        console.log("  claude-notify --bell       # Trigger bell notification");
+        console.log("  claude-notifications test   # Test the notifications");
+        console.log("");
+        log(
+          "blue",
+          "Claude Code will now beckon you back with pleasant notifications! 🎮",
+        );
+      });
       break;
 
     case "test":
@@ -256,21 +349,26 @@ function main() {
       });
       break;
 
+    case "test-bell":
+      log("blue", "🔔 Testing bell notification...");
+      spawn("node", [path.join(__dirname, "claude-notify.js"), "--bell"], {
+        stdio: "inherit",
+      });
+      break;
+
     case "uninstall":
       log("blue", "🗑️  Uninstalling Claude Notifications...");
 
-      const soundFile = path.join(
-        os.homedir(),
-        ".local",
-        "share",
-        "sounds",
-        "claude-notification.wav",
-      );
-      if (fs.existsSync(soundFile)) {
-        fs.unlinkSync(soundFile);
-        log("green", "✅ Removed sound file");
+      // Remove sounds directory
+      if (fs.existsSync(soundsDir)) {
+        fs.rmSync(soundsDir, { recursive: true, force: true });
+        log("green", "✅ Removed sounds directory");
       }
 
+      // Clean up old sound files from legacy location
+      const { cleanupLegacySoundFiles } = require("../lib/config");
+      cleanupLegacySoundFiles();
+
       log(
         "yellow",
         "⚠️  Please manually remove the stop hook from your Claude Code config",
@@ -289,6 +387,7 @@ function main() {
       console.log("Commands:");
       console.log("  install    Install notifications (default)");
       console.log("  test       Test the notification");
+      console.log("  test-bell  Test the bell notification");
       console.log("  uninstall  Remove notifications");
       console.log("  help       Show this help");
       break;

package/bin/claude-notify.js

@@ -6,19 +6,31 @@ const path = require('path');
 const os = require('os');
 const http = require('http');
 const https = require('https');
-const { getConfig } = require('../lib/config');
+const { getConfig, getSoundPath, SOUND_TYPES } = require('../lib/config');
 
 const config = getConfig();
 
+// Check for command line arguments
+const args = process.argv.slice(2);
+const useBell = args.includes('--bell') || args.includes('-b');
+const showConfig = args.includes('-c') || args.includes('--config');
+
 function playSound() {
   if (!config.sound) {
     return;
   }
 
-  const soundFile = path.join(os.homedir(), '.local', 'share', 'sounds', 'claude-notification.wav');
+  // Determine which sound to play
+  let soundType = config.soundType;
+  if (useBell) {
+    soundType = SOUND_TYPES.BELL;
+  }
+
+  const soundFile = getSoundPath(soundType);
   
   if (!fs.existsSync(soundFile)) {
-    process.stdout.write('\x07');
+    console.warn(`Sound file not found: ${soundFile}`);
+    process.stdout.write('\x07'); // Fallback to system beep
     return;
   }
 
@@ -97,7 +109,73 @@ function showNotification() {
   });
 }
 
+function showConfigInfo() {
+  const configPath = path.join(os.homedir(), '.config', 'claude-notifications', 'settings.json');
+  const soundsDir = path.join(os.homedir(), '.config', 'claude-notifications', 'sounds');
+  
+  console.log('🔍 Claude Notifications Config Debug Info:');
+  console.log('');
+  console.log('📁 Config file location:');
+  console.log(`   ${configPath}`);
+  console.log(`   Exists: ${fs.existsSync(configPath) ? '✅' : '❌'}`);
+  
+  if (fs.existsSync(configPath)) {
+    try {
+      const configContent = fs.readFileSync(configPath, 'utf-8');
+      console.log('   Content:');
+      console.log(`   ${configContent.split('\n').map(line => `   ${line}`).join('\n')}`);
+    } catch (error) {
+      console.log(`   Error reading: ${error.message}`);
+    }
+  }
+  
+  console.log('');
+  console.log('🔊 Sounds directory:');
+  console.log(`   ${soundsDir}`);
+  console.log(`   Exists: ${fs.existsSync(soundsDir) ? '✅' : '❌'}`);
+  
+  if (fs.existsSync(soundsDir)) {
+    try {
+      const soundFiles = fs.readdirSync(soundsDir);
+      console.log('   Files:');
+      soundFiles.forEach(file => {
+        const filePath = path.join(soundsDir, file);
+        const stats = fs.statSync(filePath);
+        console.log(`   - ${file} (${Math.round(stats.size / 1024)}KB)`);
+      });
+    } catch (error) {
+      console.log(`   Error reading directory: ${error.message}`);
+    }
+  }
+  
+  console.log('');
+  console.log('⚙️  Current config values:');
+  console.log(`   sound: ${config.sound}`);
+  console.log(`   soundType: ${config.soundType}`);
+  console.log(`   desktopNotification: ${config.desktopNotification}`);
+  console.log(`   webhook.enabled: ${config.webhook.enabled}`);
+  
+  console.log('');
+  console.log('🎵 Sound file paths:');
+  const { SOUND_TYPES, getSoundPath } = require('../lib/config');
+  Object.values(SOUND_TYPES).forEach(soundType => {
+    const soundPath = getSoundPath(soundType);
+    console.log(`   ${soundType}: ${soundPath}`);
+    console.log(`   Exists: ${fs.existsSync(soundPath) ? '✅' : '❌'}`);
+  });
+  
+  console.log('');
+  console.log('🔧 Command line args:');
+  console.log(`   useBell: ${useBell}`);
+  console.log(`   showConfig: ${showConfig}`);
+}
+
 function main() {
+  if (showConfig) {
+    showConfigInfo();
+    return;
+  }
+  
   if (config.webhook.enabled) {
     triggerWebhook();
     if (!config.webhook.replaceSound) {
@@ -105,7 +183,9 @@ function main() {
     }
   } else {
     playSound();
-    showNotification();
+    if (config.desktopNotification) {
+      showNotification();
+    }
   }
 }
 

package/lib/config.js

@@ -3,10 +3,19 @@ const path = require('path');
 const os = require('os');
 
 const configPath = path.join(os.homedir(), '.config', 'claude-notifications', 'settings.json');
+const soundsDir = path.join(os.homedir(), '.config', 'claude-notifications', 'sounds');
+
+// Available sound types (filenames without extension)
+const SOUND_TYPES = {
+  HARP: 'claude-notification',
+  BELL: 'claude-notification-bell'
+};
 
 function getConfig() {
   const defaultConfig = {
     sound: true,
+    soundType: SOUND_TYPES.HARP,  // Default to harp sound
+    desktopNotification: false,
     webhook: {
       enabled: false,
       url: null,
@@ -21,6 +30,35 @@ function getConfig() {
   try {
     const configContent = fs.readFileSync(configPath, 'utf-8');
     const userConfig = JSON.parse(configContent);
+    
+    // Handle migration from old configurations
+    let migrated = false;
+    
+    // Migration 1: old 'secondSound' config to 'soundType'
+    if (userConfig.secondSound === true && !userConfig.soundType) {
+      userConfig.soundType = SOUND_TYPES.BELL;
+      delete userConfig.secondSound;
+      migrated = true;
+    }
+    
+    // Migration 2: ensure soundType is valid
+    if (userConfig.soundType && !Object.values(SOUND_TYPES).includes(userConfig.soundType)) {
+      console.warn(`Invalid soundType '${userConfig.soundType}', resetting to default`);
+      userConfig.soundType = SOUND_TYPES.HARP;
+      migrated = true;
+    }
+    
+    // Save migrated config back to file
+    if (migrated) {
+      try {
+        ensureConfigDirectory();
+        fs.writeFileSync(configPath, JSON.stringify({ ...defaultConfig, ...userConfig }, null, 2));
+        console.log('Configuration migrated successfully');
+      } catch (writeError) {
+        console.error('Failed to save migrated config:', writeError);
+      }
+    }
+    
     return { ...defaultConfig, ...userConfig };
   } catch (error) {
     console.error('Error reading or parsing config file:', error);
@@ -28,4 +66,78 @@ function getConfig() {
   }
 }
 
-module.exports = { getConfig };
+function getSoundPath(soundType) {
+  return path.join(soundsDir, `${soundType}.wav`);
+}
+
+function ensureConfigDirectory() {
+  const configDir = path.dirname(configPath);
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+}
+
+function ensureSoundsDirectory() {
+  if (!fs.existsSync(soundsDir)) {
+    fs.mkdirSync(soundsDir, { recursive: true });
+  }
+}
+
+function cleanupLegacySoundFiles() {
+  // Clean up old sound files from legacy locations
+  const legacyPaths = [
+    // Legacy location 1: ~/.local/share/sounds/
+    {
+      dir: path.join(os.homedir(), '.local', 'share', 'sounds'),
+      files: ['claude-notification.wav', 'claude-notification-bell.wav']
+    },
+    // Add more legacy paths here if needed in future migrations
+  ];
+  
+  let cleanedCount = 0;
+  
+  legacyPaths.forEach(({ dir, files }) => {
+    if (fs.existsSync(dir)) {
+      files.forEach(file => {
+        const filePath = path.join(dir, file);
+        if (fs.existsSync(filePath)) {
+          try {
+            fs.unlinkSync(filePath);
+            console.log(`✅ Removed legacy sound file: ${filePath}`);
+            cleanedCount++;
+          } catch (error) {
+            console.error(`❌ Failed to remove legacy sound file ${filePath}:`, error);
+          }
+        }
+      });
+      
+      // Try to remove empty directory if it only contained our files
+      try {
+        const remainingFiles = fs.readdirSync(dir);
+        if (remainingFiles.length === 0) {
+          fs.rmdirSync(dir);
+          console.log(`✅ Removed empty legacy directory: ${dir}`);
+        }
+      } catch (error) {
+        // Directory not empty or can't be removed, that's fine
+      }
+    }
+  });
+  
+  if (cleanedCount > 0) {
+    console.log(`✅ Cleaned up ${cleanedCount} legacy sound file(s)`);
+  }
+  
+  return cleanedCount;
+}
+
+module.exports = { 
+  getConfig, 
+  getSoundPath, 
+  ensureConfigDirectory,
+  ensureSoundsDirectory,
+  cleanupLegacySoundFiles,
+  SOUND_TYPES,
+  soundsDir,
+  configPath
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delorenj/claude-notifications",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Delightful Notification for Claude Code",
   "main": "index.js",
   "bin": {