@sylphx/flow 1.0.1 → 1.0.3

package/src/utils/audio-player.ts

@@ -0,0 +1,345 @@
+/**
+ * Cross-Platform Audio Player
+ * Detects and uses available audio players across different platforms
+ *
+ * Supported players (in priority order):
+ * - macOS: afplay (built-in)
+ * - Linux: mpg123, mpg321, play (sox), aplay, mplayer, cvlc
+ * - Windows: powershell (built-in), cmdmp3
+ * - Universal: mplayer, omxplayer (Raspberry Pi)
+ */
+
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Audio player configuration
+ */
+interface AudioPlayer {
+  name: string;
+  command: string;
+  args: (filePath: string) => string[];
+  platforms: NodeJS.Platform[];
+  checkAvailability?: () => Promise<boolean>;
+}
+
+/**
+ * Available audio players in priority order
+ */
+const AUDIO_PLAYERS: AudioPlayer[] = [
+  // macOS built-in
+  {
+    name: 'afplay',
+    command: 'afplay',
+    args: (file) => [file],
+    platforms: ['darwin'],
+  },
+
+  // Linux players (in priority order)
+  {
+    name: 'mpg123',
+    command: 'mpg123',
+    args: (file) => ['-q', file], // quiet mode
+    platforms: ['linux', 'freebsd', 'openbsd'],
+  },
+  {
+    name: 'mpg321',
+    command: 'mpg321',
+    args: (file) => ['-q', file], // quiet mode
+    platforms: ['linux', 'freebsd', 'openbsd'],
+  },
+  {
+    name: 'play',
+    command: 'play',
+    args: (file) => ['-q', file], // sox play command
+    platforms: ['linux', 'freebsd', 'openbsd', 'darwin'],
+  },
+  {
+    name: 'aplay',
+    command: 'aplay',
+    args: (file) => ['-q', file], // ALSA player
+    platforms: ['linux'],
+  },
+  {
+    name: 'mplayer',
+    command: 'mplayer',
+    args: (file) => ['-really-quiet', file],
+    platforms: ['linux', 'freebsd', 'openbsd', 'darwin', 'win32'],
+  },
+  {
+    name: 'cvlc',
+    command: 'cvlc',
+    args: (file) => ['--play-and-exit', '--quiet', file], // VLC command-line
+    platforms: ['linux', 'freebsd', 'openbsd', 'darwin', 'win32'],
+  },
+  {
+    name: 'omxplayer',
+    command: 'omxplayer',
+    args: (file) => ['-o', 'local', file], // Raspberry Pi
+    platforms: ['linux'],
+  },
+
+  // Windows players
+  {
+    name: 'powershell',
+    command: 'powershell',
+    args: (file) => [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      `(New-Object Media.SoundPlayer "${file}").PlaySync()`
+    ],
+    platforms: ['win32'],
+    // PowerShell Media.SoundPlayer only supports WAV files
+    checkAvailability: async () => {
+      // Check if we're on Windows and file is WAV
+      return process.platform === 'win32';
+    }
+  },
+  {
+    name: 'cmdmp3',
+    command: 'cmdmp3',
+    args: (file) => [file],
+    platforms: ['win32'],
+  },
+];
+
+/**
+ * Cached available player to avoid repeated checks
+ */
+let cachedPlayer: AudioPlayer | null = null;
+let cacheChecked = false;
+
+/**
+ * Check if a command is available in PATH
+ */
+async function isCommandAvailable(command: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    // Try to execute the command with --version or --help
+    const proc = spawn(command, ['--version'], {
+      stdio: 'ignore',
+      shell: true
+    });
+
+    proc.on('error', () => resolve(false));
+    proc.on('exit', (code) => {
+      // Some commands return non-zero for --version, so just check if they exist
+      resolve(true);
+    });
+
+    // Timeout after 1 second
+    setTimeout(() => {
+      proc.kill();
+      resolve(false);
+    }, 1000);
+  });
+}
+
+/**
+ * Detect the first available audio player for current platform
+ */
+export async function detectAudioPlayer(): Promise<AudioPlayer | null> {
+  if (cacheChecked && cachedPlayer) {
+    return cachedPlayer;
+  }
+
+  const currentPlatform = process.platform;
+
+  // Filter players for current platform
+  const compatiblePlayers = AUDIO_PLAYERS.filter(
+    (player) => player.platforms.includes(currentPlatform)
+  );
+
+  // Check each player in priority order
+  for (const player of compatiblePlayers) {
+    // Custom availability check if provided
+    if (player.checkAvailability) {
+      const isAvailable = await player.checkAvailability();
+      if (!isAvailable) continue;
+    }
+
+    // Check if command is available
+    const isAvailable = await isCommandAvailable(player.command);
+    if (isAvailable) {
+      cachedPlayer = player;
+      cacheChecked = true;
+      return player;
+    }
+  }
+
+  cacheChecked = true;
+  return null;
+}
+
+/**
+ * Play audio file using the best available player
+ * @param filePath Absolute path to audio file
+ * @param options Playback options
+ * @returns Promise that resolves when playback completes or rejects on error
+ */
+export async function playSound(
+  filePath: string,
+  options?: {
+    volume?: number; // 0-100 (not supported by all players)
+    background?: boolean; // Play in background (default: true)
+    timeout?: number; // Max playback duration in ms (default: 5000)
+  }
+): Promise<void> {
+  const {
+    background = true,
+    timeout = 5000
+  } = options || {};
+
+  // Check if file exists
+  if (!existsSync(filePath)) {
+    throw new Error(`Audio file not found: ${filePath}`);
+  }
+
+  // Detect available player
+  const player = await detectAudioPlayer();
+  if (!player) {
+    throw new Error('No audio player available on this system');
+  }
+
+  return new Promise((resolve, reject) => {
+    const args = player.args(filePath);
+    const proc = spawn(player.command, args, {
+      stdio: 'ignore',
+      detached: background,
+    });
+
+    // If background mode, unref and resolve immediately
+    if (background) {
+      proc.unref();
+      resolve();
+      return;
+    }
+
+    // Otherwise wait for completion
+    let timeoutId: NodeJS.Timeout | null = null;
+
+    proc.on('error', (error) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      reject(new Error(`Audio player error: ${error.message}`));
+    });
+
+    proc.on('exit', (code) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Audio player exited with code ${code}`));
+      }
+    });
+
+    // Timeout protection
+    if (timeout > 0) {
+      timeoutId = setTimeout(() => {
+        proc.kill();
+        reject(new Error(`Audio playback timeout after ${timeout}ms`));
+      }, timeout);
+    }
+  });
+}
+
+/**
+ * Get information about the detected audio player
+ */
+export async function getAudioPlayerInfo(): Promise<{
+  available: boolean;
+  player: string | null;
+  platform: string;
+}> {
+  const player = await detectAudioPlayer();
+
+  return {
+    available: player !== null,
+    player: player?.name || null,
+    platform: process.platform
+  };
+}
+
+/**
+ * Built-in system sounds for different platforms
+ */
+export const SYSTEM_SOUNDS = {
+  // macOS system sounds
+  darwin: {
+    glass: '/System/Library/Sounds/Glass.aiff',
+    hero: '/System/Library/Sounds/Hero.aiff',
+    pop: '/System/Library/Sounds/Pop.aiff',
+    ping: '/System/Library/Sounds/Ping.aiff',
+    purr: '/System/Library/Sounds/Purr.aiff',
+    submarine: '/System/Library/Sounds/Submarine.aiff',
+    blow: '/System/Library/Sounds/Blow.aiff',
+    bottle: '/System/Library/Sounds/Bottle.aiff',
+    frog: '/System/Library/Sounds/Frog.aiff',
+    funk: '/System/Library/Sounds/Funk.aiff',
+    morse: '/System/Library/Sounds/Morse.aiff',
+  },
+  // Linux typical locations (may vary)
+  linux: {
+    complete: '/usr/share/sounds/freedesktop/stereo/complete.oga',
+    message: '/usr/share/sounds/freedesktop/stereo/message.oga',
+    bell: '/usr/share/sounds/freedesktop/stereo/bell.oga',
+    dialog: '/usr/share/sounds/freedesktop/stereo/dialog-information.oga',
+  },
+  // Windows - would need .wav files
+  win32: {
+    // Windows Media directory sounds
+    notify: 'C:\\Windows\\Media\\Windows Notify.wav',
+    ding: 'C:\\Windows\\Media\\Windows Ding.wav',
+    chord: 'C:\\Windows\\Media\\chord.wav',
+  }
+} as const;
+
+/**
+ * Get default system sound for current platform
+ */
+export function getDefaultSystemSound(): string | null {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    return SYSTEM_SOUNDS.darwin.glass;
+  } else if (platform === 'linux') {
+    // Check which sound exists
+    const sounds = Object.values(SYSTEM_SOUNDS.linux);
+    for (const sound of sounds) {
+      if (existsSync(sound)) {
+        return sound;
+      }
+    }
+  } else if (platform === 'win32') {
+    // Check which sound exists
+    const sounds = Object.values(SYSTEM_SOUNDS.win32);
+    for (const sound of sounds) {
+      if (existsSync(sound)) {
+        return sound;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Play system notification sound
+ */
+export async function playNotificationSound(): Promise<void> {
+  const soundPath = getDefaultSystemSound();
+
+  if (!soundPath) {
+    // No system sound available, just return silently
+    return;
+  }
+
+  try {
+    await playSound(soundPath, { background: true, timeout: 3000 });
+  } catch (error) {
+    // Fail silently - don't crash on sound playback errors
+    if (process.env.DEBUG) {
+      console.error('[Audio] Failed to play notification sound:', error);
+    }
+  }
+}

package/src/utils/cli-output.ts

@@ -0,0 +1,266 @@
+/**
+ * CLI Output Utilities
+ * Provides structured output for CLI commands with proper logging separation
+ */
+
+import { logger } from './logger.js';
+
+/**
+ * CLI output levels
+ */
+export type CLIOutputLevel = 'info' | 'success' | 'warning' | 'error';
+
+/**
+ * CLI output interface
+ */
+export interface ICLIOutput {
+  /**
+   * Print user-facing message
+   */
+  print(message: string, level?: CLIOutputLevel): void;
+
+  /**
+   * Print success message
+   */
+  success(message: string): void;
+
+  /**
+   * Print warning message
+   */
+  warning(message: string): void;
+
+  /**
+   * Print error message
+   */
+  error(message: string): void;
+
+  /**
+   * Print info message
+   */
+  info(message: string): void;
+
+  /**
+   * Print formatted data
+   */
+  table(data: Record<string, unknown>[]): void;
+
+  /**
+   * Print formatted list
+   */
+  list(items: string[], options?: { numbered?: boolean; bullet?: string }): void;
+}
+
+/**
+ * CLI output implementation
+ */
+export class CLIOutput implements ICLIOutput {
+  private colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+  };
+
+  private icons = {
+    info: 'ℹ️',
+    success: '✅',
+    warning: '⚠️',
+    error: '❌',
+  };
+
+  print(message: string, level: CLIOutputLevel = 'info'): void {
+    // Log internally for debugging
+    logger.debug('CLI output', { message, level });
+
+    // Output to user
+    switch (level) {
+      case 'success':
+        this.success(message);
+        break;
+      case 'warning':
+        this.warning(message);
+        break;
+      case 'error':
+        this.error(message);
+        break;
+      default:
+        this.info(message);
+        break;
+    }
+  }
+
+  success(message: string): void {
+    console.log(`${this.icons.success} ${this.colors.green}${message}${this.colors.reset}`);
+    logger.info('CLI success output', { message });
+  }
+
+  warning(message: string): void {
+    console.log(`${this.icons.warning} ${this.colors.yellow}${message}${this.colors.reset}`);
+    logger.warn('CLI warning output', { message });
+  }
+
+  error(message: string): void {
+    console.error(`${this.icons.error} ${this.colors.red}${message}${this.colors.reset}`);
+    logger.error('CLI error output', { message });
+  }
+
+  info(message: string): void {
+    console.log(`${this.icons.info} ${message}`);
+    logger.info('CLI info output', { message });
+  }
+
+  table(data: Record<string, unknown>[]): void {
+    if (data.length === 0) {
+      this.info('No data to display');
+      return;
+    }
+
+    // Simple table formatting
+    const headers = Object.keys(data[0]);
+    const columnWidths = headers.map((header) =>
+      Math.max(header.length, ...data.map((row) => String(row[header] || '').length))
+    );
+
+    // Print header
+    const headerRow = headers.map((header, i) => header.padEnd(columnWidths[i])).join(' | ');
+    console.log(this.colors.bright + headerRow + this.colors.reset);
+    console.log('-'.repeat(headerRow.length));
+
+    // Print rows
+    data.forEach((row) => {
+      const rowStr = headers
+        .map((header, i) => String(row[header] || '').padEnd(columnWidths[i]))
+        .join(' | ');
+      console.log(rowStr);
+    });
+
+    logger.debug('CLI table output', {
+      headers,
+      rowCount: data.length,
+      columnWidths,
+    });
+  }
+
+  list(items: string[], options: { numbered?: boolean; bullet?: string } = {}): void {
+    const { numbered = false, bullet = '•' } = options;
+
+    if (items.length === 0) {
+      this.info('No items to display');
+      return;
+    }
+
+    items.forEach((item, index) => {
+      const prefix = numbered ? `${index + 1}.` : bullet;
+      console.log(`${prefix} ${item}`);
+    });
+
+    logger.debug('CLI list output', {
+      itemCount: items.length,
+      numbered,
+      bullet,
+    });
+  }
+
+  /**
+   * Print formatted memory entry
+   */
+  memoryEntry(
+    entry: {
+      namespace: string;
+      key: string;
+      value: unknown;
+      updated_at: string;
+    },
+    index?: number
+  ): void {
+    const prefix = index !== undefined ? `${index + 1}.` : '•';
+    const safeValue = entry.value || '';
+    const value =
+      typeof safeValue === 'string'
+        ? safeValue.substring(0, 50) + (safeValue.length > 50 ? '...' : '')
+        : `${JSON.stringify(safeValue).substring(0, 50)}...`;
+
+    console.log(`${prefix} ${entry.namespace}:${entry.key}`);
+    console.log(`   Value: ${value}`);
+    console.log(`   Updated: ${entry.updated_at}`);
+    console.log('');
+
+    logger.debug('CLI memory entry output', {
+      namespace: entry.namespace,
+      key: entry.key,
+      valueLength: String(entry.value || '').length,
+    });
+  }
+
+  /**
+   * Print search results summary
+   */
+  searchSummary(query: string, results: number, namespace?: string): void {
+    console.log(`${this.colors.cyan}🔍 Search results for pattern: ${query}${this.colors.reset}`);
+
+    if (namespace) {
+      console.log(`${this.colors.dim}Namespace: ${namespace}${this.colors.reset}`);
+    }
+
+    console.log(`${this.colors.bright}Found: ${results} results${this.colors.reset}\n`);
+
+    logger.info('CLI search summary', { query, results, namespace });
+  }
+
+  /**
+   * Print list summary
+   */
+  listSummary(namespace: string, count: number, total?: number): void {
+    if (namespace && namespace !== 'all') {
+      console.log(
+        `${this.colors.cyan}📋 Memory entries in namespace: ${namespace}${this.colors.reset}`
+      );
+      console.log(`${this.colors.bright}Total: ${count} entries${this.colors.reset}\n`);
+    } else if (total) {
+      console.log(
+        `${this.colors.cyan}📋 All memory entries (showing first ${count})${this.colors.reset}`
+      );
+      console.log(`${this.colors.bright}Total: ${total} entries${this.colors.reset}\n`);
+    }
+
+    logger.info('CLI list summary', { namespace, count, total });
+  }
+
+  /**
+   * Print empty state message
+   */
+  emptyState(type: 'entries' | 'results' | 'data', context?: string): void {
+    const messages = {
+      entries: 'No entries found',
+      results: 'No matching entries found',
+      data: 'No data to display',
+    };
+
+    let message = messages[type];
+    if (context) {
+      message += ` in ${context}`;
+    }
+    message += '.';
+
+    this.info(message);
+    logger.debug('CLI empty state', { type, context, message });
+  }
+}
+
+// Global CLI output instance
+export const cli = new CLIOutput();
+
+/**
+ * Convenience functions
+ */
+export const print = (message: string, level?: CLIOutputLevel) => cli.print(message, level);
+export const success = (message: string) => cli.success(message);
+export const warning = (message: string) => cli.warning(message);
+export const error = (message: string) => cli.error(message);
+export const info = (message: string) => cli.info(message);