agentvibes 5.12.0 → 5.13.0

package/src/cli/list-voices.js

@@ -1,114 +1,218 @@
-#!/usr/bin/env node
-/**
- * Voice List Display - Beautiful multi-column voice listing
- * Called by voice-manager.sh to display voices with boxen formatting
- */
-
-import { formatVoicesList } from '../utils/list-formatter.js';
-import fs from 'fs';
-import path from 'path';
-import { execFileSync } from 'child_process';
-import os from 'os';
-
-/**
- * Get Piper voices from voice directory
- */
-function getPiperVoices(voiceDir, currentVoice) {
-  const voices = [];
-
-  if (!fs.existsSync(voiceDir)) {
-    return voices;
-  }
-
-  const files = fs.readdirSync(voiceDir);
-  for (const file of files) {
-    if (file.endsWith('.onnx')) {
-      const voiceName = path.basename(file, '.onnx');
-      voices.push({
-        name: voiceName,
-        lang: extractLanguage(voiceName),
-        current: voiceName === currentVoice
-      });
-    }
-  }
-
-  return voices.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-/**
- * Get macOS voices using say -v ?
- */
-function getMacOSVoices(currentVoice) {
-  const voices = [];
-
-  if (os.platform() !== 'darwin') {
-    return voices;
-  }
-
-  try {
-    const output = execFileSync('say', ['-v', '?'], { encoding: 'utf8' }); // NOSONAR - Safe: checking macOS say voices from system PATH
-    const lines = output.split('\n');
-
-    for (const line of lines) {
-      if (!line.trim()) continue;
-
-      const parts = line.trim().split(/\s+/);
-      if (parts.length >= 2) {
-        const voiceName = parts[0];
-        const lang = parts[1];
-
-        voices.push({
-          name: voiceName,
-          lang,
-          current: voiceName === currentVoice
-        });
-      }
-    }
-  } catch (error) {
-    // say command failed
-  }
-
-  return voices;
-}
-
-/**
- * Extract language code from voice name
- */
-function extractLanguage(voiceName) {
-  const match = voiceName.match(/^([a-z]{2}_[A-Z]{2})/);
-  return match ? match[1] : '';
-}
-
-/**
- * Main function
- */
-function main() {
-  const args = process.argv.slice(2);
-
-  // Parse arguments
-  const provider = args[0] || 'piper';
-  const currentVoice = args[1] || '';
-  const voiceDir = args[2] || '';
-
-  let voices = [];
-  let providerName = 'Piper TTS';
-
-  if (provider === 'piper') {
-    voices = getPiperVoices(voiceDir, currentVoice);
-    providerName = 'Piper TTS';
-  } else if (provider === 'macos') {
-    voices = getMacOSVoices(currentVoice);
-    providerName = 'macOS TTS';
-  }
-
-  // Display with boxen
-  const output = formatVoicesList(voices, {
-    provider: providerName,
-    columns: 2,
-    showUsage: true
-  });
-
-  console.log(output);
-}
-
-main();
+#!/usr/bin/env node
+/**
+ * Voice List Display - Beautiful multi-column voice listing
+ * Called by voice-manager.sh to display voices with boxen formatting
+ */
+
+import { formatVoicesList } from '../utils/list-formatter.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+import os from 'os';
+import {
+  KOKORO_VOICE_IDS,
+  kokoroGender,
+  ELEVENLABS_VOICES,
+} from '../services/provider-voice-catalog.js';
+import {
+  listVoices as catalogListVoices,
+  getProvider,
+} from '../services/provider-catalog.js';
+
+/**
+ * Get Piper voices from voice directory
+ */
+function getPiperVoices(voiceDir, currentVoice) {
+  const voices = [];
+
+  if (!fs.existsSync(voiceDir)) {
+    return voices;
+  }
+
+  const files = fs.readdirSync(voiceDir);
+  for (const file of files) {
+    if (file.endsWith('.onnx')) {
+      const voiceName = path.basename(file, '.onnx');
+      voices.push({
+        name: voiceName,
+        lang: extractLanguage(voiceName),
+        current: voiceName === currentVoice
+      });
+    }
+  }
+
+  return voices.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Get macOS voices using say -v ?
+ */
+function getMacOSVoices(currentVoice) {
+  const voices = [];
+
+  if (os.platform() !== 'darwin') {
+    return voices;
+  }
+
+  try {
+    const output = execFileSync('say', ['-v', '?'], { encoding: 'utf8' }); // NOSONAR - Safe: checking macOS say voices from system PATH
+    const lines = output.split('\n');
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      const parts = line.trim().split(/\s+/);
+      if (parts.length >= 2) {
+        const voiceName = parts[0];
+        const lang = parts[1];
+
+        voices.push({
+          name: voiceName,
+          lang,
+          current: voiceName === currentVoice
+        });
+      }
+    }
+  } catch (error) {
+    // say command failed
+  }
+
+  return voices;
+}
+
+/**
+ * Kokoro voice ids follow `<lang><sex>_name`. The first char is the language.
+ * Map it to a human-readable language label for the listing.
+ */
+const KOKORO_LANG_LABELS = {
+  a: 'en-US', b: 'en-GB', j: 'ja', z: 'zh', e: 'es',
+  f: 'fr', h: 'hi', i: 'it', p: 'pt-BR', k: 'ko',
+};
+
+/**
+ * Get Kokoro voices from the canonical catalog (KOKORO_VOICE_IDS).
+ * Kokoro's voice set is a fixed catalog, not discovered on disk.
+ */
+function getKokoroVoices(currentVoice) {
+  return KOKORO_VOICE_IDS.map((id) => ({
+    name: id,
+    lang: KOKORO_LANG_LABELS[id[0]] || '',
+    gender: kokoroGender(id),
+    current: id === currentVoice,
+  }));
+}
+
+/**
+ * Get ElevenLabs voices from the canonical catalog (ELEVENLABS_VOICES).
+ * The listing shows the friendly name; matching against currentVoice accepts
+ * either the friendly name or the raw voice_id.
+ */
+function getElevenLabsVoices(currentVoice) {
+  return ELEVENLABS_VOICES.map((v) => ({
+    name: v.name,
+    lang: v.lang || '',
+    gender: v.gender || '',
+    current: v.name === currentVoice || v.id === currentVoice,
+  }));
+}
+
+/**
+ * Get Soprano voices from the canonical catalog. Soprano is voiceModel `single`
+ * (design §3.1): exactly one canonical voice, soprano-default — no picker.
+ */
+function getSopranoVoices(currentVoice) {
+  return catalogListVoices('soprano').map((v) => ({
+    name: v.id,
+    lang: '',
+    gender: v.gender || '',
+    current: v.id === currentVoice || currentVoice === '' || currentVoice === 'soprano',
+  }));
+}
+
+/**
+ * Extract language code from voice name
+ */
+function extractLanguage(voiceName) {
+  const match = voiceName.match(/^([a-z]{2}_[A-Z]{2})/);
+  return match ? match[1] : '';
+}
+
+/**
+ * Discovered providers list-voices enumerates HERE, each via its own platform
+ * discovery path (piper: `*.onnx` disk glob; macos: `say -v ?`). Other discovered
+ * providers (windows-piper / windows-sapi) are enumerated by the Windows lister,
+ * not this Unix/darwin CLI, so they fall to the honest "no voice list" label —
+ * preserving pre-AVI-S9.5 output. Adding a record with a static/name-to-id/single
+ * voiceModel adds a list arm for free (no edit here needed).
+ */
+const LISTABLE_DISCOVERED = new Set(['piper', 'macos']);
+
+/**
+ * Resolve a provider token to its voice list + display label by iterating the
+ * Provider Catalog (src/services/provider-catalog.js) and branching ONLY on the
+ * record's `voiceModel` — replacing the former four hardcoded per-provider
+ * equality branches (AVI-S9.5 / design row 19). Unknown tokens keep the honest
+ * "no voice list available" label from AVI-S8.1.
+ *
+ * @param {string} provider
+ * @param {string} currentVoice
+ * @param {string} voiceDir
+ * @returns {{ voices: object[], providerName: string }}
+ */
+function selectVoices(provider, currentVoice, voiceDir) {
+  const record = getProvider(provider);
+  if (!record) {
+    return { voices: [], providerName: `${provider} (no voice list available)` };
+  }
+
+  // Label preserves the pre-existing strings exactly (macOS uses "TTS", not the
+  // catalog display name "macOS Say"); all others equal record.displayName.
+  const providerName = record.id === 'macos' ? 'macOS TTS' : record.displayName;
+
+  switch (record.voiceModel) {
+    case 'static': // kokoro
+      return { voices: getKokoroVoices(currentVoice), providerName };
+    case 'name-to-id': // elevenlabs
+      return { voices: getElevenLabsVoices(currentVoice), providerName };
+    case 'single': // soprano
+      return { voices: getSopranoVoices(currentVoice), providerName };
+    case 'discovered':
+    default:
+      if (record.id === 'piper') return { voices: getPiperVoices(voiceDir, currentVoice), providerName };
+      if (record.id === 'macos') return { voices: getMacOSVoices(currentVoice), providerName };
+      // A discovered provider without a discovery path on this platform: label
+      // it honestly instead of rendering an empty list under a wrong provider.
+      return { voices: [], providerName: `${provider} (no voice list available)` };
+  }
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  // Parse arguments
+  const provider = args[0] || 'piper';
+  const currentVoice = args[1] || '';
+  const voiceDir = args[2] || '';
+
+  const { voices, providerName } = selectVoices(provider, currentVoice, voiceDir);
+
+  // Display with boxen
+  const output = formatVoicesList(voices, {
+    provider: providerName,
+    columns: 2,
+    showUsage: true
+  });
+
+  console.log(output);
+}
+
+// Only run when invoked as a CLI (keeps selectVoices importable by tests).
+const _invokedDirectly = process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (_invokedDirectly) main();
+
+export { selectVoices, LISTABLE_DISCOVERED };

package/src/console/bling.js

@@ -0,0 +1,71 @@
+/**
+ * AgentVibes — Shared "bling" readiness cue.
+ *
+ * A short, fire-and-forget chime played the instant a preview is committed, so
+ * silence during synthesis / an SSH round-trip never reads as a hang. Used by
+ * BOTH the voice picker (setup-tab.js) and the music-preview surfaces
+ * (music-tab.js, track-picker.js) so they can't drift.
+ *
+ * `buildBlingCommand` was originally defined in setup-tab.js; it was moved here
+ * and is re-exported from setup-tab.js for backward compatibility (existing
+ * imports and tests keep working).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+/**
+ * Build the fire-and-forget "preview ready" cue command for a platform. Pure
+ * (no spawning here, so it is unit-testable). Plays the bundled CC0 wav when
+ * present, else falls back to a system sound (Windows) / freedesktop cue or
+ * terminal bell (POSIX). stdio is ignored by the caller, so the POSIX bell is
+ * redirected to /dev/tty rather than the discarded stdout.
+ * @param {string} platform - process.platform value
+ * @param {string} wavPath - absolute path to the bling wav
+ * @param {boolean} haveWav - whether wavPath exists on disk
+ * @returns {{command: string, args: string[]}}
+ */
+export function buildBlingCommand(platform, wavPath, haveWav) {
+  if (platform === 'win32') {
+    const ps = haveWav
+      ? `Add-Type -AssemblyName System.Windows.Forms; (New-Object System.Media.SoundPlayer('${wavPath.replace(/'/g, "''")}')).PlaySync()`
+      : '[System.Media.SystemSounds]::Asterisk.Play(); Start-Sleep -Milliseconds 700';
+    return { command: 'powershell', args: ['-NoProfile', '-Command', ps] };
+  }
+  if (haveWav) {
+    // Pass wavPath as a positional arg ($1) so the path is never interpolated
+    // into the shell string (prevents injection / breakage on special chars).
+    const sh = 'paplay "$1" 2>/dev/null || aplay -q "$1" 2>/dev/null || printf "\\a" > /dev/tty 2>/dev/null';
+    return { command: 'bash', args: ['-c', sh, '--', wavPath] };
+  }
+  const sh = 'paplay /usr/share/sounds/freedesktop/stereo/message.oga 2>/dev/null || printf "\\a" > /dev/tty 2>/dev/null';
+  return { command: 'bash', args: ['-c', sh] };
+}
+
+/**
+ * Resolve the bundled CC0 bling wav for a package root.
+ * Sound: "Ui sounds - Shimmering success" by Philip_Berger, CC0 (freesound
+ * #648212). See .claude/audio/ui/CREDITS.txt.
+ * @param {string} packageRoot - AgentVibes package/repo root
+ * @returns {string}
+ */
+export function resolveBlingWav(packageRoot) {
+  return path.join(packageRoot, '.claude', 'audio', 'ui', 'bling-success.wav');
+}
+
+/**
+ * Play the readiness cue, fire-and-forget. Detached + unref'd + errors
+ * swallowed, so it never blocks the UI or fails a preview. A missing wav falls
+ * back to a platform system sound via buildBlingCommand.
+ * @param {string} packageRoot - AgentVibes package/repo root
+ */
+export function playBlingCue(packageRoot) {
+  try {
+    const wav = resolveBlingWav(packageRoot);
+    const { command, args } = buildBlingCommand(process.platform, wav, fs.existsSync(wav));
+    const cue = spawn(command, args, { stdio: 'ignore', detached: true }); // NOSONAR
+    cue.on('error', () => { /* best-effort cue; a spawn failure must not surface */ });
+    cue.unref();
+  } catch { /* the readiness cue is purely cosmetic — never break the preview */ }
+}

package/src/console/music-preview.js

@@ -0,0 +1,79 @@
+/**
+ * AgentVibes — Shared music-preview transport helpers.
+ *
+ * Both music-preview surfaces (the Music tab and the track-picker widget) must
+ * make the same remote-vs-local decision: a transport provider routes audio to
+ * a remote receiver, so a local MP3 preview would be silent on a headless box
+ * and must be forwarded instead. This module holds the provider-resolve and the
+ * remote-forward spawn so the two surfaces can't drift.
+ *
+ * The caller owns UI feedback (status text, error messages) and attaches its own
+ * exit/error/stderr handlers to the returned child process.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+
+// Transport providers route audio to a remote receiver; local MP3 playback is
+// silent on a headless/remote box, so track previews must be forwarded instead.
+export const REMOTE_PROVIDERS = ['ssh-remote', 'agentvibes-receiver'];
+
+/**
+ * Resolve the active provider and the project dir it was read from, using the
+ * same search order as the voice pickers (CLAUDE_PROJECT_DIR → cwd → package →
+ * home). Returns { remote, projectDir } so a remote preview can forward the
+ * track to the receiver and tell the sender which .claude dir to resolve.
+ * @param {string} packageRoot - AgentVibes package/repo root (package fallback)
+ * @returns {{ remote: boolean, projectDir: string }}
+ */
+export function resolveMusicProvider(packageRoot) {
+  const dirs = [process.env.CLAUDE_PROJECT_DIR, process.cwd(), packageRoot, os.homedir()].filter(Boolean);
+  for (const d of dirs) {
+    const p = path.join(d, '.claude', 'tts-provider.txt');
+    try {
+      if (fs.existsSync(p)) {
+        const provider = fs.readFileSync(p, 'utf8').trim();
+        return { remote: REMOTE_PROVIDERS.includes(provider), projectDir: d };
+      }
+    } catch { /* next */ }
+  }
+  return { remote: false, projectDir: '' };
+}
+
+/**
+ * Resolve the SSH sender script path, preferring the package-bundled copy and
+ * falling back to the project's .claude/hooks copy.
+ * @param {string} packageRoot
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveRemoteSender(packageRoot, projectDir) {
+  const pkgSender = path.resolve(packageRoot, '.claude', 'hooks', 'play-tts-ssh-remote.sh');
+  return fs.existsSync(pkgSender)
+    ? pkgSender
+    : path.join(projectDir, '.claude', 'hooks', 'play-tts-ssh-remote.sh');
+}
+
+/**
+ * Spawn the SSH sender to forward a music track to the receiver, or stop the
+ * current one. Fire-and-forget (the sender exits after handing the payload to
+ * SSH; the receiver plays/stops asynchronously). Returns the child process so
+ * the caller can wire its own exit/error/stderr handlers for UI feedback.
+ *
+ * @param {object} opts
+ * @param {string} opts.packageRoot
+ * @param {string} opts.projectDir
+ * @param {object} opts.env         - base spawn env (e.g. buildAudioEnv())
+ * @param {string} [opts.track]     - track filename to play (ignored when stop)
+ * @param {boolean} [opts.stop]     - send an explicit music-stop signal instead
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnMusicRemote({ packageRoot, projectDir, env, track = null, stop = false }) {
+  const senderPath = resolveRemoteSender(packageRoot, projectDir);
+  const spawnEnv = { ...env, CLAUDE_PROJECT_DIR: projectDir };
+  if (stop) spawnEnv.AGENTVIBES_MUSIC_STOP = '1';
+  else spawnEnv.AGENTVIBES_MUSIC_ONLY = track;
+  return spawn('bash', [senderPath, '', ''], { stdio: ['ignore', 'ignore', 'pipe'], detached: true, env: spawnEnv }); // NOSONAR
+}

package/src/console/tabs/music-tab.js

@@ -11,43 +11,20 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
-import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { buildAudioEnv, spawnMp3Player } from '../audio-env.js';
+import { resolveMusicProvider, spawnMusicRemote } from '../music-preview.js';
+import { playBlingCue } from '../bling.js';
 import { t } from '../../i18n/strings.js';
 
 const _MUSIC_TAB_DIR = path.dirname(fileURLToPath(import.meta.url));
 
-// Package-relative tracks dir — used as fallback when cwd has no .claude/audio/tracks/
-const _PKG_TRACKS_DIR = path.resolve(
-  _MUSIC_TAB_DIR, '..', '..', '..', '.claude', 'audio', 'tracks'
-);
-
-// Transport providers route audio to a remote receiver; local MP3 playback is
-// silent on a headless/remote box, so track previews must be forwarded instead.
-const _REMOTE_PROVIDERS = ['ssh-remote', 'agentvibes-receiver'];
+// AgentVibes package/repo root — used to resolve bundled assets (tracks dir,
+// bling cue) and as the package fallback when resolving the active provider.
+const _PKG_ROOT = path.resolve(_MUSIC_TAB_DIR, '..', '..', '..');
 
-/**
- * Resolve the active provider and the project dir it was read from, using the
- * same search order as the voice pickers (CLAUDE_PROJECT_DIR → cwd → package →
- * home). Returns { remote, projectDir } so a remote preview can forward the
- * track to the receiver and tell the sender which .claude dir to resolve.
- */
-function _resolveMusicProvider() {
-  const projectRoot = path.resolve(_MUSIC_TAB_DIR, '..', '..', '..');
-  const dirs = [process.env.CLAUDE_PROJECT_DIR, process.cwd(), projectRoot, os.homedir()].filter(Boolean);
-  for (const d of dirs) {
-    const p = path.join(d, '.claude', 'tts-provider.txt');
-    try {
-      if (fs.existsSync(p)) {
-        const provider = fs.readFileSync(p, 'utf8').trim();
-        return { remote: _REMOTE_PROVIDERS.includes(provider), projectDir: d };
-      }
-    } catch { /* next */ }
-  }
-  return { remote: false, projectDir: '' };
-}
+// Package-relative tracks dir — used as fallback when cwd has no .claude/audio/tracks/
+const _PKG_TRACKS_DIR = path.join(_PKG_ROOT, '.claude', 'audio', 'tracks');
 
 const IS_TEST = process.env.AGENTVIBES_TEST_MODE === 'true';
 
@@ -591,16 +568,9 @@ export function createMusicTab(screen, services) {
    * @param {{track?:string, stop?:boolean}} opts
    */
   function _sendMusicRemote(mp, { track = null, stop = false } = {}) {
-    const _pkgSender = path.resolve(_MUSIC_TAB_DIR, '..', '..', '..', '.claude', 'hooks', 'play-tts-ssh-remote.sh');
-    const senderPath = fs.existsSync(_pkgSender)
-      ? _pkgSender
-      : path.join(mp.projectDir, '.claude', 'hooks', 'play-tts-ssh-remote.sh');
-    const env = { ..._spawnEnv, CLAUDE_PROJECT_DIR: mp.projectDir };
-    if (stop) env.AGENTVIBES_MUSIC_STOP = '1';
-    else env.AGENTVIBES_MUSIC_ONLY = track;
     let rproc;
     try {
-      rproc = spawn('bash', [senderPath, '', ''], { stdio: ['ignore', 'ignore', 'pipe'], detached: true, env }); // NOSONAR
+      rproc = spawnMusicRemote({ packageRoot: _PKG_ROOT, projectDir: mp.projectDir, env: _spawnEnv, track, stop });
     } catch {
       previewLine.setContent('{red-fg}Remote music preview failed{/red-fg}');
       screen.render();
@@ -646,7 +616,7 @@ export function createMusicTab(screen, services) {
     // is silent on a headless box). The receiver auto-stops any prior track when
     // a new one arrives; pressing Space on the currently-playing track sends an
     // explicit stop (toggle off).
-    const _mp = _resolveMusicProvider();
+    const _mp = resolveMusicProvider(_PKG_ROOT);
     if (_mp.remote) {
       if (_remotePlayingTrackId === trackId) {
         _sendMusicRemote(_mp, { stop: true });
@@ -655,6 +625,9 @@ export function createMusicTab(screen, services) {
         screen.render();
         return;
       }
+      // Bling first (fire-and-forget, plays locally) — same readiness cue as the
+      // voice preview — then forward the track to the receiver.
+      playBlingCue(_PKG_ROOT);
       const rlabel = _allTracks.find(t => t.id === trackId)?.label ?? formatTrackLabel(trackId);
       if (_sendMusicRemote(_mp, { track: trackId })) {
         _remotePlayingTrackId = trackId;
@@ -678,6 +651,10 @@ export function createMusicTab(screen, services) {
     _killPlayingProcess();
     _playingTrackId = null;
 
+    // Bling first (fire-and-forget) — same readiness cue as the voice preview —
+    // then start local playback.
+    playBlingCue(_PKG_ROOT);
+
     const proc = spawnMp3Player(trackPath, _spawnEnv);
     if (!proc) {
       const installHint = process.platform === 'win32'