agentvibes 3.5.9 → 4.0.0

package/src/console/audio-env.js

@@ -0,0 +1,123 @@
+/**
+ * AgentVibes — Cross-platform audio environment helpers.
+ *
+ * Provides PULSE_SERVER-safe environment and MP3/WAV player detection
+ * that works on native Linux, WSL2, macOS, and Windows.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Build a spawn environment with correct PULSE_SERVER handling.
+ *
+ * - If PULSE_SERVER is already set in the environment, keep it.
+ * - On WSL2, set it to the wslg PulseServer socket if it exists.
+ * - On native Linux / macOS / Windows, do NOT set it (use system default).
+ *
+ * Also extends PATH so pipx-installed binaries (piper) are found.
+ *
+ * @returns {Object} Environment object safe to pass to child_process.spawn
+ */
+export function buildAudioEnv() {
+  const env = {
+    ...process.env,
+    PATH: [process.env.PATH, path.join(os.homedir(), '.local', 'bin'), '/usr/local/bin']
+      .filter(Boolean).join(process.platform === 'win32' ? ';' : ':'),
+  };
+
+  if (process.env.PULSE_SERVER) {
+    env.PULSE_SERVER = process.env.PULSE_SERVER;
+  } else if (fs.existsSync('/mnt/wslg/PulseServer')) {
+    env.PULSE_SERVER = 'unix:/mnt/wslg/PulseServer';
+  }
+  // else: leave PULSE_SERVER unset — native PulseAudio/PipeWire uses its default socket
+
+  return env;
+}
+
+// ---------------------------------------------------------------------------
+// Player detection
+
+/** @typedef {{ bin: string, args: (file: string) => string[] }} Player */
+
+/** MP3-capable players in preference order */
+const MP3_PLAYERS = [
+  { bin: 'ffplay',  args: (f) => ['-nodisp', '-autoexit', '-loglevel', 'quiet', f] },
+  { bin: 'play',    args: (f) => [f] },        // sox
+  { bin: 'mpg123',  args: (f) => ['-q', f] },
+  { bin: 'cvlc',    args: (f) => ['--play-and-exit', '--no-video', f] },
+  { bin: 'mpv',     args: (f) => ['--no-video', '--really-quiet', f] },
+  { bin: 'afplay',  args: (f) => [f] },        // macOS
+];
+
+/** WAV-capable players in preference order */
+const WAV_PLAYERS = [
+  { bin: 'aplay',   args: (f) => [f] },        // ALSA (Linux)
+  { bin: 'paplay',  args: (f) => [f] },        // PulseAudio
+  { bin: 'play',    args: (f) => [f] },        // sox
+  { bin: 'ffplay',  args: (f) => ['-nodisp', '-autoexit', '-loglevel', 'quiet', f] },
+  { bin: 'afplay',  args: (f) => [f] },        // macOS
+  { bin: 'mpv',     args: (f) => ['--no-video', '--really-quiet', f] },
+  { bin: 'cvlc',    args: (f) => ['--play-and-exit', '--no-video', f] },
+];
+
+/** Windows players — use PowerShell's SoundPlayer for WAV */
+const WIN_WAV_PLAYER = {
+  bin: 'powershell',
+  args: (f) => ['-NoProfile', '-Command',
+    `(New-Object Media.SoundPlayer '${f.replace(/'/g, "''")}').PlaySync()`],
+};
+
+/**
+ * Detect the first available player from a list.
+ * Caches results per list so `which` is only called once per binary.
+ *
+ * @param {Player[]} players
+ * @param {Object} env - Environment to use for `which`
+ * @returns {Player|null}
+ */
+const _cache = new Map();
+function _detect(players, env) {
+  for (const p of players) {
+    if (_cache.has(p.bin)) {
+      if (_cache.get(p.bin)) return p;
+      continue;
+    }
+    const r = spawnSync('which', [p.bin], { stdio: 'pipe', env });
+    const found = r.status === 0;
+    _cache.set(p.bin, found);
+    if (found) return p;
+  }
+  return null;
+}
+
+/**
+ * Detect the best available MP3 player.
+ * On Windows, falls back to ffplay/mpv if installed, otherwise null.
+ *
+ * @param {Object} [env] - Environment (defaults to buildAudioEnv())
+ * @returns {Player|null}
+ */
+export function detectMp3Player(env) {
+  env = env || buildAudioEnv();
+  return _detect(MP3_PLAYERS, env);
+}
+
+/**
+ * Detect the best available WAV player.
+ * On Windows, uses PowerShell SoundPlayer as built-in fallback.
+ *
+ * @param {Object} [env] - Environment (defaults to buildAudioEnv())
+ * @returns {Player|null}
+ */
+export function detectWavPlayer(env) {
+  env = env || buildAudioEnv();
+  if (process.platform === 'win32') {
+    // Try cross-platform players first, fall back to PowerShell
+    return _detect(WAV_PLAYERS, env) || WIN_WAV_PLAYER;
+  }
+  return _detect(WAV_PLAYERS, env);
+}

package/src/console/brand-colors.js

@@ -0,0 +1,13 @@
+/**
+ * AgentVibes TUI — Brand Color Constants
+ *
+ * Single source of truth for the two primary brand colors.
+ * Change BRAND_PINK or BRAND_BLUE here to update every modal title,
+ * button, and the "Vibes" logotype across the entire TUI.
+ */
+
+/** Magenta-pink used for modal titles and the "Vibes" logotype. */
+export const BRAND_PINK = '#f06292';  // Light magenta — Pink 300
+
+/** Indigo blue used for default button backgrounds and primary accents. */
+export const BRAND_BLUE = '#3949ab';

package/src/console/footer-config.js

@@ -0,0 +1,42 @@
+/**
+ * AgentVibes TUI Console — Context Footer Configuration
+ * Story 6.3: Color-Coded Context Footer System
+ *
+ * Per-tab footer colors and keyboard shortcut hint text.
+ * Keys are styled in magenta ({#ff00ff-fg}{bold}); actions follow in plain text.
+ */
+
+/** Fallback footer background color */
+export const DEFAULT_FOOTER_COLOR = '#1a237e';
+
+/** Helper: wrap a key label in magenta bold tags */
+function key(label) {
+  return `{#ff00ff-fg}{bold}[${label}]{/bold}{/#ff00ff-fg}`;
+}
+
+export const FOOTER_CONFIG = {
+  settings: {
+    color: '#2196f3',
+    text: ` ${key('↑↓')} Navigate  ${key('←→')} Same Row  ${key('Enter')} Activate  ${key('Space')} Preview  ${key('Esc')} Cancel`,
+  },
+  voices: {
+    color: '#00bcd4',
+    text: ` ${key('1-6')} Sort  ${key('/')} Search  ${key('P')} Provider  ${key('F')} Favorites  ${key('Space')} Preview  ${key('*')} Fav  ${key('I')} Install`,
+  },
+  music: {
+    color: '#ff9800',
+    text: ` ${key('Space')} Preview  ${key('Enter')} Select  ${key('M')} Toggle  ${key('*')} Fav  ${key('F')} Filter  ${key('↑↓')} Navigate`,
+  },
+  readme: {
+    color: '#455a64',
+    text: ` ${key('↑↓')} Scroll  ${key('PgUp/PgDn')} Page  ${key('Home/End')} Jump`,
+  },
+  help: {
+    color: '#607d8b',
+    text: ` ${key('↑↓')} Scroll  ${key('Q')} Quit`,
+  },
+  install: {
+    color: '#1a237e',
+    text: ` ${key('↑↓')} Navigate  ${key('Enter')} Select  ${key('Esc')} Back`,
+  },
+};

package/src/console/modals/modal-overlay.js

@@ -0,0 +1,247 @@
+/**
+ * AgentVibes TUI Console — Modal Overlay Component
+ * Story 6.4: Modal Overlay Component
+ *
+ * Provides a reusable dim-overlay + centered-container modal for the TUI.
+ * Used by stories 7.7 (Personality), 7.8 (Voice), 7.9 (Music) selector modals.
+ *
+ * Integration with NavigationService:
+ *   - openModal() sets isModalOpen() = true (blocks S/V/M/A/R/H/I/T shortcuts)
+ *   - closeModal() restores modal-closed state
+ *   - pushFocus/popFocus manage keyboard focus across open/close
+ */
+
+import blessed from 'blessed';
+
+// Brand colours consistent with app.js and UX design plan
+const COLORS = {
+  headerBg: '#1a237e',
+  contentBg: '#0a0e1a',
+  activeTab: '#3949ab',
+  textWhite: 'white',
+  overlayBg: '#000000',
+};
+
+export class ModalOverlay {
+  /**
+   * @param {object} screen - Blessed screen instance (or stub in tests)
+   * @param {NavigationService} nav - Navigation service for modal state management
+   * @param {object} [opts={}]
+   * @param {string} [opts.title='Modal'] - Default modal title
+   */
+  constructor(screen, nav, opts = {}) {
+    this._screen = screen;
+    this._nav = nav;
+    this._onApply = null;
+    this._focusedButton = 'apply'; // M1: tracks which footer button has focus ('apply'|'cancel')
+
+    const title = opts.title ?? 'Modal';
+    this._title = title; // L1: stored for external access
+
+    // Detect test/stub environment: real blessed screens have a .program property.
+    // When using a stub screen (no .program), create lightweight object stubs
+    // instead of real blessed widgets to avoid "No active screen." errors.
+    const isTestMode = !screen.program;
+
+    if (isTestMode) {
+      this._overlay    = { hidden: true };
+      this._container  = { hidden: true, key: () => {}, focus: () => {} };
+      this._titleBar   = { setContent: () => {} };
+      this._contentBox = { hidden: true };
+      this._footerBar  = { hidden: true, setContent: () => {} }; // setContent needed by _updateFooter
+    } else {
+      // Full-screen dim overlay — sits beneath the modal container
+      this._overlay = blessed.box({
+        top: 0,
+        left: 0,
+        width: '100%',
+        height: '100%',
+        style: { bg: COLORS.overlayBg },
+        hidden: true,
+      });
+
+      // Centered modal container with border
+      this._container = blessed.box({
+        top: 'center',
+        left: 'center',
+        width: '60%',
+        height: '60%',
+        border: { type: 'line' },
+        style: {
+          fg: COLORS.textWhite,
+          bg: COLORS.contentBg,
+          border: { fg: COLORS.activeTab },
+        },
+        hidden: true,
+        keys: true,
+        mouse: true,
+      });
+
+      // Title bar — top row of container
+      this._titleBar = blessed.box({
+        parent: this._container,
+        top: 0,
+        left: 0,
+        width: '100%',
+        height: 1,
+        content: ` ${title}`,
+        tags: true,
+        style: {
+          fg: COLORS.textWhite,
+          bg: COLORS.headerBg,
+        },
+      });
+
+      // Scrollable content area — callers append their UI here via getContentBox()
+      this._contentBox = blessed.box({
+        parent: this._container,
+        top: 1,
+        left: 0,
+        width: '100%',
+        bottom: 2,
+        scrollable: true,
+        alwaysScroll: true,
+        keys: true,
+        style: {
+          fg: COLORS.textWhite,
+          bg: COLORS.contentBg,
+        },
+      });
+
+      // Footer strip with focusable Apply / Cancel buttons
+      this._footerBar = blessed.box({
+        parent: this._container,
+        bottom: 0,
+        left: 0,
+        width: '100%',
+        height: 2,
+        content: '  ► {bold}[Apply]{/bold}   [Cancel]',
+        tags: true,
+        style: {
+          fg: COLORS.textWhite,
+          bg: COLORS.headerBg,
+        },
+      });
+
+      // Append to screen in z-order: overlay first (bottom), container on top
+      this._screen.append(this._overlay);
+      this._screen.append(this._container);
+
+      // M1: Tab cycles focus indicator between Apply and Cancel
+      this._container.key(['tab'], () => {
+        this._focusedButton = this._focusedButton === 'apply' ? 'cancel' : 'apply';
+        this._updateFooter();
+        this._screen.render();
+      });
+
+      // Enter activates the currently focused footer button (M1: checks _focusedButton)
+      this._container.key(['enter'], () => {
+        if (this._focusedButton === 'apply') {
+          this._handleApply();
+        } else {
+          this.close();
+        }
+      });
+
+      this._container.key(['escape'], () => this.close());
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+
+  /**
+   * Open the modal overlay.
+   * Shows the dim overlay + container, updates NavigationService modal state,
+   * pushes current focus to the focus stack, and renders the screen.
+   * @param {Function|null} [onApply] - Called when user activates Apply
+   */
+  open(onApply = null) {
+    // H2: Guard against double-open — prevents stacked pushFocus calls
+    if (this._nav.isModalOpen()) return;
+
+    this._onApply = onApply;
+    this._focusedButton = 'apply'; // Reset focus to Apply on each open
+    this._overlay.hidden = false;
+    this._container.hidden = false;
+
+    this._nav.openModal(() => {
+      // Push current focus so we can restore on close
+      this._nav.pushFocus(this._screen.focused);
+      this._container.focus();
+    });
+
+    this._updateFooter();
+    this._screen.render();
+  }
+
+  /**
+   * Close the modal overlay.
+   * Hides overlay + container, restores NavigationService modal state,
+   * pops saved focus, and renders the screen.
+   *
+   * Guard: uses widget-state (overlay.hidden) rather than isModalOpen().
+   * Reason: Blessed.js fires multiple Esc handlers in registration order.
+   * navigation.js registers its handler first and calls nav.closeModal()
+   * before app.js calls modal.close() — so isModalOpen() is already false
+   * when we arrive here, causing the old guard to return early and leave
+   * the overlay/container visible on screen.
+   */
+  close() {
+    // H1: Widget-state guard — safe against dual-handler Esc ordering
+    if (this._overlay.hidden) return;
+    this._overlay.hidden = true;
+    this._container.hidden = true;
+    // H1: navigation.js may have already called closeModal() — only call if still open
+    if (this._nav.isModalOpen()) this._nav.closeModal();
+    const prev = this._nav.popFocus();
+    if (prev && typeof prev.focus === 'function') prev.focus();
+    this._screen.render();
+  }
+
+  /**
+   * Returns the inner content box so callers (7.7-7.9) can append their UI.
+   * @returns {object} Blessed box (or stub in tests)
+   */
+  getContentBox() {
+    return this._contentBox;
+  }
+
+  /**
+   * Update the modal title bar text.
+   * @param {string} text
+   */
+  setTitle(text) {
+    this._titleBar.setContent(` ${text}`);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+
+  /**
+   * M1: Render the footer with a ► cursor on the currently focused button.
+   */
+  _updateFooter() {
+    const applyLabel  = this._focusedButton === 'apply'  ? '► {bold}[Apply]{/bold}' : '  [Apply]';
+    const cancelLabel = this._focusedButton === 'cancel' ? '► {bold}[Cancel]{/bold}' : '  [Cancel]';
+    this._footerBar.setContent(`  ${applyLabel}   ${cancelLabel}`);
+  }
+
+  _handleApply() {
+    if (typeof this._onApply === 'function') {
+      this._onApply();
+    }
+    this.close();
+  }
+}
+
+/**
+ * Factory function for creating a ModalOverlay.
+ * @param {object} screen - Blessed screen
+ * @param {NavigationService} nav - Navigation service
+ * @param {object} [opts={}]
+ * @returns {ModalOverlay}
+ */
+export function createModalOverlay(screen, nav, opts = {}) {
+  return new ModalOverlay(screen, nav, opts);
+}

package/src/console/navigation.js

@@ -0,0 +1,60 @@
+/**
+ * AgentVibes TUI Console — Global Keyboard Navigation
+ * Story 6.2: Tab Bar & Global Keyboard Navigation
+ *
+ * Registers all global key bindings on the Blessed screen.
+ * Tab shortcuts (S/V/M/A/R/H/I) are blocked when a modal is open.
+ */
+
+/** Map of key → tab ID for global tab shortcut keys */
+const KEY_TO_TAB = {
+  's': 'settings', 'S': 'settings',
+  'v': 'voices',   'V': 'voices',
+  'm': 'music',    'M': 'music',
+  'r': 'readme',   'R': 'readme',
+  'h': 'help',     'H': 'help',
+  'i': 'install',  'I': 'install',
+};
+
+/**
+ * Register all global keyboard navigation handlers on the Blessed screen.
+ *
+ * Handlers registered:
+ *   S/V/M/A/R/H/I → switchTab (blocked when modal is open)
+ *   Tab / T/t      → cycleTab forward (blocked when modal is open)
+ *   Shift+Tab      → cycleTab backward (blocked when modal is open)
+ *   Escape         → closeModal (only when modal is open)
+ *
+ * Arrow keys (left/right) are intentionally NOT used for tab cycling —
+ * individual tabs use left/right for in-element navigation (e.g. row siblings).
+ *
+ * NOTE: Q / Ctrl+C are already registered in app.js (_registerHandlers).
+ * Do NOT re-register them here — that would stack duplicate quit handlers.
+ *
+ * @param {object} screen - Blessed screen instance (or stub in tests)
+ * @param {import('../services/navigation-service.js').NavigationService} navigationService
+ */
+export function setupNavigation(screen, navigationService) {
+  // Tab switching shortcuts — one handler per key (both cases)
+  for (const [key, tabId] of Object.entries(KEY_TO_TAB)) {
+    screen.key([key], () => {
+      if (!navigationService.isModalOpen()) {
+        navigationService.switchTab(tabId);
+      }
+    });
+  }
+
+  // T → cycle to next tab (Tab itself is handled by the tab bar and footer only)
+  screen.key(['t', 'T'], () => {
+    if (!navigationService.isModalOpen()) {
+      navigationService.cycleTab();
+    }
+  });
+
+  // Escape — close modal (story 6.4 will expand modal handling)
+  screen.key(['escape'], () => {
+    if (navigationService.isModalOpen()) {
+      navigationService.closeModal();
+    }
+  });
+}