opencode-smart-voice-notify 1.2.5 → 1.3.0

package/util/desktop-notify.js

@@ -0,0 +1,319 @@
+import notifier from 'node-notifier';
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Desktop Notification Module for OpenCode Smart Voice Notify
+ * 
+ * Provides cross-platform native desktop notifications using node-notifier.
+ * Supports Windows Toast, macOS Notification Center, and Linux notify-send.
+ * 
+ * Platform-specific behaviors:
+ * - Windows: Uses SnoreToast for Windows 8+ toast notifications
+ * - macOS: Uses terminal-notifier for Notification Center
+ * - Linux: Uses notify-send (requires libnotify-bin package)
+ * 
+ * @module util/desktop-notify
+ * @see docs/ARCHITECT_PLAN.md - Phase 1, Task 1.2
+ */
+
+/**
+ * Debug logging to file.
+ * Only logs when config.debugLog is enabled.
+ * Writes to ~/.config/opencode/logs/smart-voice-notify-debug.log
+ * 
+ * @param {string} message - Message to log
+ * @param {boolean} enabled - Whether debug logging is enabled
+ */
+const debugLog = (message, enabled = false) => {
+  if (!enabled) return;
+  
+  try {
+    const configDir = process.env.OPENCODE_CONFIG_DIR || path.join(os.homedir(), '.config', 'opencode');
+    const logsDir = path.join(configDir, 'logs');
+    
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+    
+    const logFile = path.join(logsDir, 'smart-voice-notify-debug.log');
+    const timestamp = new Date().toISOString();
+    fs.appendFileSync(logFile, `[${timestamp}] [desktop-notify] ${message}\n`);
+  } catch (e) {
+    // Silently fail - logging should never break the plugin
+  }
+};
+
+/**
+ * Get the current platform identifier.
+ * @returns {'darwin' | 'win32' | 'linux'} Platform string
+ */
+export const getPlatform = () => os.platform();
+
+/**
+ * Check if desktop notifications are likely to work on this platform.
+ * 
+ * @returns {{ supported: boolean, reason?: string }} Support status and reason if not supported
+ */
+export const checkNotificationSupport = () => {
+  const platform = getPlatform();
+  
+  switch (platform) {
+    case 'darwin':
+      // macOS always supports notifications via terminal-notifier (bundled)
+      return { supported: true };
+      
+    case 'win32':
+      // Windows 8+ supports toast notifications via SnoreToast (bundled)
+      return { supported: true };
+      
+    case 'linux':
+      // Linux requires notify-send from libnotify-bin package
+      // We don't check for its existence here - node-notifier handles the fallback
+      return { supported: true };
+      
+    default:
+      return { supported: false, reason: `Unsupported platform: ${platform}` };
+  }
+};
+
+/**
+ * Build platform-specific notification options.
+ * Normalizes options across different platforms while respecting their unique capabilities.
+ * 
+ * @param {string} title - Notification title
+ * @param {string} message - Notification body/message
+ * @param {object} options - Additional options
+ * @param {number} [options.timeout=5] - Notification timeout in seconds
+ * @param {boolean} [options.sound=false] - Whether to play a sound (platform-specific)
+ * @param {string} [options.icon] - Absolute path to notification icon
+ * @param {string} [options.subtitle] - Subtitle (macOS only)
+ * @param {string} [options.urgency] - Urgency level: 'low', 'normal', 'critical' (Linux only)
+ * @returns {object} Platform-normalized notification options
+ */
+const buildPlatformOptions = (title, message, options = {}) => {
+  const platform = getPlatform();
+  const { timeout = 5, sound = false, icon, subtitle, urgency } = options;
+  
+  // Base options common to all platforms
+  const baseOptions = {
+    title: title || 'OpenCode',
+    message: message || '',
+    sound: sound,
+    wait: false // Don't block - fire and forget
+  };
+  
+  // Add icon if provided and exists
+  if (icon && fs.existsSync(icon)) {
+    baseOptions.icon = icon;
+  }
+  
+  // Platform-specific options
+  switch (platform) {
+    case 'darwin':
+      // macOS Notification Center options
+      return {
+        ...baseOptions,
+        timeout: timeout,
+        subtitle: subtitle || undefined
+      };
+      
+    case 'win32':
+      // Windows Toast options
+      return {
+        ...baseOptions,
+        // Windows doesn't use timeout the same way - notifications persist until dismissed
+        // sound can be true/false or a system sound name
+        sound: sound
+      };
+      
+    case 'linux':
+      // Linux notify-send options
+      return {
+        ...baseOptions,
+        timeout: timeout, // Timeout in seconds
+        urgency: urgency || 'normal', // low, normal, critical
+        'app-name': 'OpenCode Smart Notify'
+      };
+      
+    default:
+      return baseOptions;
+  }
+};
+
+/**
+ * Send a native desktop notification.
+ * 
+ * This is the main function for sending cross-platform desktop notifications.
+ * It handles platform-specific options and gracefully fails if notifications
+ * are not supported or the notifier encounters an error.
+ * 
+ * @param {string} title - Notification title
+ * @param {string} message - Notification body/message
+ * @param {object} [options={}] - Notification options
+ * @param {number} [options.timeout=5] - Notification timeout in seconds
+ * @param {boolean} [options.sound=false] - Whether to play a sound
+ * @param {string} [options.icon] - Absolute path to notification icon
+ * @param {string} [options.subtitle] - Subtitle (macOS only)
+ * @param {string} [options.urgency='normal'] - Urgency level (Linux only)
+ * @param {boolean} [options.debugLog=false] - Enable debug logging
+ * @returns {Promise<{ success: boolean, error?: string }>} Result object
+ * 
+ * @example
+ * // Simple notification
+ * await sendDesktopNotification('Task Complete', 'Your code is ready for review');
+ * 
+ * @example
+ * // With options
+ * await sendDesktopNotification('Permission Required', 'Agent needs approval', {
+ *   timeout: 10,
+ *   urgency: 'critical',
+ *   sound: true
+ * });
+ */
+export const sendDesktopNotification = async (title, message, options = {}) => {
+  // Handle null/undefined options gracefully
+  const opts = options || {};
+  const debug = opts.debugLog || false;
+  
+  try {
+    // Check platform support
+    const support = checkNotificationSupport();
+    if (!support.supported) {
+      debugLog(`Notification not supported: ${support.reason}`, debug);
+      return { success: false, error: support.reason };
+    }
+    
+    // Build platform-specific options
+    const notifyOptions = buildPlatformOptions(title, message, opts);
+    
+    debugLog(`Sending notification: "${title}" - "${message}" (platform: ${getPlatform()})`, debug);
+    
+    // Send notification using promise wrapper
+    return new Promise((resolve) => {
+      notifier.notify(notifyOptions, (error, response) => {
+        if (error) {
+          debugLog(`Notification error: ${error.message}`, debug);
+          resolve({ success: false, error: error.message });
+        } else {
+          debugLog(`Notification sent successfully (response: ${response})`, debug);
+          resolve({ success: true });
+        }
+      });
+    });
+  } catch (error) {
+    debugLog(`Notification exception: ${error.message}`, debug);
+    return { success: false, error: error.message };
+  }
+};
+
+/**
+ * Send a notification for session idle (task completion).
+ * Pre-configured for task completion notifications.
+ * 
+ * @param {string} message - Notification message
+ * @param {object} [options={}] - Additional options
+ * @param {string} [options.projectName] - Project name to include in title
+ * @param {boolean} [options.debugLog=false] - Enable debug logging
+ * @returns {Promise<{ success: boolean, error?: string }>} Result object
+ */
+export const notifyTaskComplete = async (message, options = {}) => {
+  const title = options.projectName 
+    ? `✅ ${options.projectName} - Task Complete`
+    : '✅ OpenCode - Task Complete';
+    
+  return sendDesktopNotification(title, message, {
+    timeout: 5,
+    sound: false, // We handle sound separately in the main plugin
+    ...options
+  });
+};
+
+/**
+ * Send a notification for permission requests.
+ * Pre-configured for permission request notifications (more urgent).
+ * 
+ * @param {string} message - Notification message
+ * @param {object} [options={}] - Additional options
+ * @param {string} [options.projectName] - Project name to include in title
+ * @param {number} [options.count=1] - Number of permission requests
+ * @param {boolean} [options.debugLog=false] - Enable debug logging
+ * @returns {Promise<{ success: boolean, error?: string }>} Result object
+ */
+export const notifyPermissionRequest = async (message, options = {}) => {
+  const count = options.count || 1;
+  const title = options.projectName 
+    ? `⚠️ ${options.projectName} - Permission Required`
+    : count > 1 
+      ? `⚠️ ${count} Permissions Required`
+      : '⚠️ OpenCode - Permission Required';
+      
+  return sendDesktopNotification(title, message, {
+    timeout: 10, // Longer timeout for permissions
+    urgency: 'critical', // Higher urgency on Linux
+    sound: false, // We handle sound separately
+    ...options
+  });
+};
+
+/**
+ * Send a notification for question requests (SDK v1.1.7+).
+ * Pre-configured for question notifications.
+ * 
+ * @param {string} message - Notification message
+ * @param {object} [options={}] - Additional options
+ * @param {string} [options.projectName] - Project name to include in title
+ * @param {number} [options.count=1] - Number of questions
+ * @param {boolean} [options.debugLog=false] - Enable debug logging
+ * @returns {Promise<{ success: boolean, error?: string }>} Result object
+ */
+export const notifyQuestion = async (message, options = {}) => {
+  const count = options.count || 1;
+  const title = options.projectName 
+    ? `❓ ${options.projectName} - Question`
+    : count > 1 
+      ? `❓ ${count} Questions Need Your Input`
+      : '❓ OpenCode - Question';
+      
+  return sendDesktopNotification(title, message, {
+    timeout: 8,
+    urgency: 'normal',
+    sound: false, // We handle sound separately
+    ...options
+  });
+};
+
+/**
+ * Send a notification for error events.
+ * Pre-configured for error notifications (most urgent).
+ * 
+ * @param {string} message - Notification message
+ * @param {object} [options={}] - Additional options
+ * @param {string} [options.projectName] - Project name to include in title
+ * @param {boolean} [options.debugLog=false] - Enable debug logging
+ * @returns {Promise<{ success: boolean, error?: string }>} Result object
+ */
+export const notifyError = async (message, options = {}) => {
+  const title = options.projectName 
+    ? `❌ ${options.projectName} - Error`
+    : '❌ OpenCode - Error';
+      
+  return sendDesktopNotification(title, message, {
+    timeout: 15, // Longer timeout for errors
+    urgency: 'critical',
+    sound: false, // We handle sound separately
+    ...options
+  });
+};
+
+// Default export for convenience
+export default {
+  sendDesktopNotification,
+  notifyTaskComplete,
+  notifyPermissionRequest,
+  notifyQuestion,
+  notifyError,
+  checkNotificationSupport,
+  getPlatform
+};

package/util/focus-detect.js

@@ -0,0 +1,372 @@
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import detectTerminal from 'detect-terminal';
+
+/**
+ * Focus Detection Module for OpenCode Smart Voice Notify
+ * 
+ * Detects whether the user is currently looking at the OpenCode terminal.
+ * Used to suppress notifications when the user is already focused on the terminal.
+ * 
+ * Platform support:
+ * - macOS: Full support using AppleScript to check frontmost app
+ * - Windows: Not supported (returns false - no reliable API)
+ * - Linux: Not supported (returns false - varies by desktop environment)
+ * 
+ * @module util/focus-detect
+ * @see docs/ARCHITECT_PLAN.md - Phase 3, Task 3.2
+ */
+
+const execAsync = promisify(exec);
+
+// ========================================
+// CACHING CONFIGURATION
+// ========================================
+
+/**
+ * Cache for focus detection results.
+ * Prevents excessive system calls (AppleScript execution).
+ */
+let focusCache = {
+  isFocused: false,
+  timestamp: 0,
+  terminalName: null
+};
+
+/**
+ * Cache TTL in milliseconds.
+ * Focus detection results are cached for this duration.
+ * 500ms provides a good balance between responsiveness and performance.
+ */
+const CACHE_TTL_MS = 500;
+
+/**
+ * List of known terminal application names for macOS.
+ * These are matched against the frontmost application name.
+ * The detect-terminal package helps identify which terminal is in use.
+ */
+export const KNOWN_TERMINALS_MACOS = [
+  'Terminal',
+  'iTerm',
+  'iTerm2',
+  'Hyper',
+  'Alacritty',
+  'kitty',
+  'WezTerm',
+  'Tabby',
+  'Warp',
+  'Rio',
+  'Ghostty',
+  // VS Code and other IDEs with integrated terminals
+  'Code',
+  'Visual Studio Code',
+  'VSCodium',
+  'Cursor',
+  'Windsurf',
+  'Zed',
+  // JetBrains IDEs
+  'IntelliJ IDEA',
+  'WebStorm',
+  'PyCharm',
+  'PhpStorm',
+  'GoLand',
+  'RubyMine',
+  'CLion',
+  'DataGrip',
+  'Rider',
+  'Android Studio'
+];
+
+// ========================================
+// DEBUG LOGGING
+// ========================================
+
+/**
+ * Debug logging to file.
+ * Only logs when enabled.
+ * Writes to ~/.config/opencode/logs/smart-voice-notify-debug.log
+ * 
+ * @param {string} message - Message to log
+ * @param {boolean} enabled - Whether debug logging is enabled
+ */
+const debugLog = (message, enabled = false) => {
+  if (!enabled) return;
+  
+  try {
+    const configDir = process.env.OPENCODE_CONFIG_DIR || path.join(os.homedir(), '.config', 'opencode');
+    const logsDir = path.join(configDir, 'logs');
+    
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+    
+    const logFile = path.join(logsDir, 'smart-voice-notify-debug.log');
+    const timestamp = new Date().toISOString();
+    fs.appendFileSync(logFile, `[${timestamp}] [focus-detect] ${message}\n`);
+  } catch (e) {
+    // Silently fail - logging should never break the plugin
+  }
+};
+
+// ========================================
+// PLATFORM DETECTION
+// ========================================
+
+/**
+ * Get the current platform identifier.
+ * @returns {'darwin' | 'win32' | 'linux'} Platform string
+ */
+export const getPlatform = () => os.platform();
+
+/**
+ * Check if focus detection is supported on this platform.
+ * 
+ * @returns {{ supported: boolean, reason?: string }} Support status
+ */
+export const isFocusDetectionSupported = () => {
+  const platform = getPlatform();
+  
+  switch (platform) {
+    case 'darwin':
+      return { supported: true };
+    case 'win32':
+      return { supported: false, reason: 'Windows focus detection not supported - no reliable API' };
+    case 'linux':
+      return { supported: false, reason: 'Linux focus detection not supported - varies by desktop environment' };
+    default:
+      return { supported: false, reason: `Unsupported platform: ${platform}` };
+  }
+};
+
+// ========================================
+// TERMINAL DETECTION
+// ========================================
+
+/**
+ * Detect the current terminal emulator using detect-terminal package.
+ * Caches the result since the terminal doesn't change during execution.
+ * 
+ * @param {boolean} debug - Enable debug logging
+ * @returns {string | null} Terminal name or null if not detected
+ */
+let cachedTerminalName = null;
+let terminalDetectionAttempted = false;
+
+export const getTerminalName = (debug = false) => {
+  // Return cached result if already detected
+  if (terminalDetectionAttempted) {
+    return cachedTerminalName;
+  }
+  
+  try {
+    terminalDetectionAttempted = true;
+    // Prefer the outer terminal (GUI app) over multiplexers like tmux/screen
+    const terminal = detectTerminal({ preferOuter: true });
+    cachedTerminalName = terminal || null;
+    debugLog(`Detected terminal: ${cachedTerminalName}`, debug);
+    return cachedTerminalName;
+  } catch (e) {
+    debugLog(`Terminal detection failed: ${e.message}`, debug);
+    return null;
+  }
+};
+
+// ========================================
+// FOCUS DETECTION - macOS
+// ========================================
+
+/**
+ * AppleScript to get the frontmost application name.
+ * Uses System Events to determine which app is currently focused.
+ */
+const APPLESCRIPT_GET_FRONTMOST = `
+tell application "System Events"
+  set frontApp to first application process whose frontmost is true
+  return name of frontApp
+end tell
+`;
+
+/**
+ * Get the name of the frontmost application on macOS.
+ * 
+ * @param {boolean} debug - Enable debug logging
+ * @returns {Promise<string | null>} Frontmost app name or null on error
+ */
+const getFrontmostAppMacOS = async (debug = false) => {
+  try {
+    const { stdout } = await execAsync(`osascript -e '${APPLESCRIPT_GET_FRONTMOST}'`, {
+      timeout: 2000, // 2 second timeout
+      maxBuffer: 1024 // Small buffer - we only expect app name
+    });
+    
+    const appName = stdout.trim();
+    debugLog(`Frontmost app: "${appName}"`, debug);
+    return appName;
+  } catch (e) {
+    debugLog(`Failed to get frontmost app: ${e.message}`, debug);
+    return null;
+  }
+};
+
+/**
+ * Check if the frontmost app is a known terminal on macOS.
+ * 
+ * @param {string} appName - The frontmost application name
+ * @param {boolean} debug - Enable debug logging
+ * @returns {boolean} True if the app is a known terminal
+ */
+const isKnownTerminal = (appName, debug = false) => {
+  if (!appName) return false;
+  
+  // Direct match
+  if (KNOWN_TERMINALS_MACOS.some(t => t.toLowerCase() === appName.toLowerCase())) {
+    debugLog(`"${appName}" is a known terminal (direct match)`, debug);
+    return true;
+  }
+  
+  // Partial match (for apps like "iTerm2" matching "iTerm")
+  if (KNOWN_TERMINALS_MACOS.some(t => appName.toLowerCase().includes(t.toLowerCase()))) {
+    debugLog(`"${appName}" is a known terminal (partial match)`, debug);
+    return true;
+  }
+  
+  // Check if the detected terminal from detect-terminal matches
+  const detectedTerminal = getTerminalName(debug);
+  if (detectedTerminal && appName.toLowerCase().includes(detectedTerminal.toLowerCase())) {
+    debugLog(`"${appName}" matches detected terminal "${detectedTerminal}"`, debug);
+    return true;
+  }
+  
+  debugLog(`"${appName}" is NOT a known terminal`, debug);
+  return false;
+};
+
+// ========================================
+// MAIN FOCUS DETECTION FUNCTION
+// ========================================
+
+/**
+ * Check if the OpenCode terminal is currently focused.
+ * 
+ * This function detects whether the user is currently looking at the terminal
+ * where OpenCode is running. Used to suppress notifications when the user
+ * is already paying attention to the terminal.
+ * 
+ * Platform behavior:
+ * - macOS: Uses AppleScript to check the frontmost application
+ * - Windows: Always returns false (not supported)
+ * - Linux: Always returns false (not supported)
+ * 
+ * Results are cached for 500ms to avoid excessive system calls.
+ * 
+ * @param {object} [options={}] - Options
+ * @param {boolean} [options.debugLog=false] - Enable debug logging
+ * @returns {Promise<boolean>} True if terminal is focused, false otherwise
+ * 
+ * @example
+ * const focused = await isTerminalFocused({ debugLog: true });
+ * if (focused) {
+ *   console.log('User is looking at the terminal - skip notification');
+ * }
+ */
+export const isTerminalFocused = async (options = {}) => {
+  const debug = options?.debugLog || false;
+  const now = Date.now();
+  
+  // Check cache first
+  if (now - focusCache.timestamp < CACHE_TTL_MS) {
+    debugLog(`Using cached focus result: ${focusCache.isFocused}`, debug);
+    return focusCache.isFocused;
+  }
+  
+  const platform = getPlatform();
+  
+  // Platform-specific implementation
+  if (platform === 'darwin') {
+    try {
+      const frontmostApp = await getFrontmostAppMacOS(debug);
+      const isFocused = isKnownTerminal(frontmostApp, debug);
+      
+      // Update cache
+      focusCache = {
+        isFocused,
+        timestamp: now,
+        terminalName: frontmostApp
+      };
+      
+      debugLog(`Focus detection complete: ${isFocused} (frontmost: "${frontmostApp}")`, debug);
+      return isFocused;
+    } catch (e) {
+      debugLog(`Focus detection error: ${e.message}`, debug);
+      // On error, assume not focused (fail open - still notify)
+      focusCache = {
+        isFocused: false,
+        timestamp: now,
+        terminalName: null
+      };
+      return false;
+    }
+  }
+  
+  // Windows and Linux: Not supported
+  if (platform === 'win32') {
+    debugLog('Focus detection not supported on Windows', debug);
+  } else if (platform === 'linux') {
+    debugLog('Focus detection not supported on Linux', debug);
+  } else {
+    debugLog(`Focus detection not supported on platform: ${platform}`, debug);
+  }
+  
+  // Cache the result even for unsupported platforms
+  focusCache = {
+    isFocused: false,
+    timestamp: now,
+    terminalName: null
+  };
+  
+  return false;
+};
+
+/**
+ * Clear the focus detection cache.
+ * Useful for testing or when forcing a fresh check.
+ */
+export const clearFocusCache = () => {
+  focusCache = {
+    isFocused: false,
+    timestamp: 0,
+    terminalName: null
+  };
+};
+
+/**
+ * Reset the terminal detection cache.
+ * Useful for testing.
+ */
+export const resetTerminalDetection = () => {
+  cachedTerminalName = null;
+  terminalDetectionAttempted = false;
+};
+
+/**
+ * Get the current cache state.
+ * Useful for testing and debugging.
+ * 
+ * @returns {{ isFocused: boolean, timestamp: number, terminalName: string | null }} Cache state
+ */
+export const getCacheState = () => ({ ...focusCache });
+
+// Default export for convenience
+export default {
+  isTerminalFocused,
+  isFocusDetectionSupported,
+  getTerminalName,
+  getPlatform,
+  clearFocusCache,
+  resetTerminalDetection,
+  getCacheState,
+  KNOWN_TERMINALS_MACOS
+};