@juspay/neurolink 9.93.2 → 9.94.1

package/dist/cli/utils/audioPlayer.d.ts

@@ -6,32 +6,67 @@
  *
  * @module cli/utils/audioPlayer
  */
-import type { AudioFormat } from "../../lib/types/index.js";
+import type { TTSAudioFormat, CliAudioPlayerCommand } from "../../lib/types/index.js";
 /**
  * Get the file extension for an audio format
  *
  * @param format - Audio format
  * @returns File extension string (e.g., "mp3", "wav")
  */
-export declare function getAudioExtension(format: AudioFormat): string;
+export declare function getAudioExtension(format: TTSAudioFormat): string;
+/**
+ * Escape a value for interpolation inside a single-quoted PowerShell string.
+ * PowerShell's single-quoted strings only treat `''` as a literal `'` — unlike
+ * shell/execFile argv, this string is parsed by powershell.exe itself, so an
+ * unescaped quote (e.g. a Windows username like `O'Brien` under `%TEMP%`)
+ * would break out of the string and let the remainder run as PS code.
+ */
+export declare function escapePowerShellSingleQuoted(value: string): string;
+/**
+ * Build the ordered list of player commands to try for a file.
+ *
+ * The list is tried in order until one succeeds; a missing binary (ENOENT) or a
+ * decode failure simply advances to the next candidate.
+ *
+ * The Linux ordering is the crux of the mp3-playback fix (#1138): `paplay`
+ * (PulseAudio) and `aplay` (ALSA) only decode libsndfile/PCM formats and
+ * **cannot** decode mp3/AAC. Since `--tts-format` defaults to mp3, compressed
+ * formats must lead with real decoders (ffplay/mpv/mpg123/cvlc); paplay/aplay
+ * remain only as last-resort fallbacks (and still work for wav/ogg).
+ *
+ * @param filePath - Path to the audio file
+ * @param format - Audio format
+ * @param platform - Platform id (defaults to `process.platform`; injectable for tests)
+ * @returns Ordered player commands; empty for unsupported platforms
+ */
+export declare function getPlayerCandidates(filePath: string, format: TTSAudioFormat, platform?: NodeJS.Platform): CliAudioPlayerCommand[];
+/**
+ * Build a helpful, format-aware error message when no player could decode the file.
+ *
+ * Exported for testing: the message a user sees when Linux mp3 playback finds no
+ * decoder must name the real fix (ffmpeg/mpv/mpg123/VLC or `--tts-format wav`),
+ * not the misleading "install PulseAudio" that paplay-only routing produced (#1138).
+ */
+export declare function buildPlaybackErrorMessage(platform: NodeJS.Platform, format: TTSAudioFormat, attempts: string[]): string;
 /**
  * Play audio from a buffer using platform-specific CLI tools
  *
- * Writes the buffer to a temporary file, plays it using the appropriate
- * system audio player, and cleans up the temp file afterward.
+ * Writes the buffer to a temporary file, plays it using the first available
+ * system audio player that can decode the format, and cleans up the temp file.
  *
  * Supported platforms:
- * - macOS: uses `afplay` (built-in, supports mp3/wav/aac/flac)
- * - Linux: uses `paplay` for non-wav, `aplay` for wav
- * - Windows: uses PowerShell SoundPlayer (wav) or WMPlayer.OCX (mp3)
+ * - macOS: `afplay` (built-in; decodes mp3/wav/aac/flac)
+ * - Linux: real decoders (ffplay/mpv/mpg123/cvlc) for compressed formats,
+ *   aplay/paplay for wav — falling through the list until one works
+ * - Windows: PowerShell SoundPlayer (wav) or WMPlayer.OCX (compressed)
  *
  * @param buffer - Audio data buffer
  * @param format - Audio format (mp3, wav, ogg, opus)
- * @throws Error if playback fails or platform is unsupported
+ * @throws Error if no available player can play the audio, or platform is unsupported
  *
  * @example
  * ```typescript
  * await playAudio(audioBuffer, "mp3");
  * ```
  */
-export declare function playAudio(buffer: Buffer, format: AudioFormat): Promise<void>;
+export declare function playAudio(buffer: Buffer, format: TTSAudioFormat): Promise<void>;

package/dist/cli/utils/audioPlayer.js

@@ -7,11 +7,25 @@
  * @module cli/utils/audioPlayer
  */
 import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+/** Wall-clock cap on a single player invocation; a hung decoder must not block the CLI forever. */
+const PLAYER_TIMEOUT_MS = 30_000;
+/**
+ * Single source of truth for format -> temp-file-extension. Formats outside this
+ * playback-supported set (m4a, flac, webm, mp4, mpeg, mpga, pcm16) fall back to
+ * "mp3" — `playAudio` only ever receives the four formats below in practice.
+ */
+const AUDIO_EXTENSIONS = {
+    mp3: "mp3",
+    wav: "wav",
+    ogg: "ogg",
+    opus: "opus",
+};
 /**
  * Get the file extension for an audio format
  *
@@ -19,73 +33,145 @@ const execFileAsync = promisify(execFile);
  * @returns File extension string (e.g., "mp3", "wav")
  */
 export function getAudioExtension(format) {
-    switch (format) {
-        case "mp3":
-            return "mp3";
-        case "wav":
-            return "wav";
-        case "ogg":
-            return "ogg";
-        case "opus":
-            return "opus";
-        default:
-            return "mp3";
-    }
+    return AUDIO_EXTENSIONS[format] ?? "mp3";
+}
+/** ffmpeg's ffplay decodes every format we emit; quiet + auto-exit for CLI use. */
+function ffplayCommand(filePath) {
+    return {
+        command: "ffplay",
+        args: ["-nodisp", "-autoexit", "-loglevel", "quiet", filePath],
+    };
 }
 /**
- * Get the platform-specific audio player command and arguments
+ * Escape a value for interpolation inside a single-quoted PowerShell string.
+ * PowerShell's single-quoted strings only treat `''` as a literal `'` — unlike
+ * shell/execFile argv, this string is parsed by powershell.exe itself, so an
+ * unescaped quote (e.g. a Windows username like `O'Brien` under `%TEMP%`)
+ * would break out of the string and let the remainder run as PS code.
+ */
+export function escapePowerShellSingleQuoted(value) {
+    return value.replace(/'/g, "''");
+}
+/**
+ * Build the ordered list of player commands to try for a file.
+ *
+ * The list is tried in order until one succeeds; a missing binary (ENOENT) or a
+ * decode failure simply advances to the next candidate.
+ *
+ * The Linux ordering is the crux of the mp3-playback fix (#1138): `paplay`
+ * (PulseAudio) and `aplay` (ALSA) only decode libsndfile/PCM formats and
+ * **cannot** decode mp3/AAC. Since `--tts-format` defaults to mp3, compressed
+ * formats must lead with real decoders (ffplay/mpv/mpg123/cvlc); paplay/aplay
+ * remain only as last-resort fallbacks (and still work for wav/ogg).
  *
  * @param filePath - Path to the audio file
  * @param format - Audio format
- * @returns Object with command and args for execFile
+ * @param platform - Platform id (defaults to `process.platform`; injectable for tests)
+ * @returns Ordered player commands; empty for unsupported platforms
  */
-function getPlayerCommand(filePath, format) {
-    const platform = process.platform;
+export function getPlayerCandidates(filePath, format, platform = process.platform) {
+    const isWav = format === "wav";
     switch (platform) {
         case "darwin":
-            return { command: "afplay", args: [filePath] };
+            // afplay decodes mp3/wav/aac/flac natively.
+            return [{ command: "afplay", args: [filePath] }];
         case "linux":
-            if (format === "wav") {
-                return { command: "aplay", args: [filePath] };
+            if (isWav) {
+                // WAV/PCM: ALSA and PulseAudio both decode it; ffplay as a backstop.
+                return [
+                    { command: "aplay", args: [filePath] },
+                    { command: "paplay", args: [filePath] },
+                    ffplayCommand(filePath),
+                ];
+            }
+            // Compressed formats (mp3/ogg/opus): lead with decoders that actually
+            // handle them, then fall back to paplay/aplay (which work for some
+            // formats but never mp3).
+            return [
+                ffplayCommand(filePath),
+                {
+                    command: "mpv",
+                    args: ["--no-video", "--really-quiet", filePath],
+                },
+                ...(format === "mp3"
+                    ? [{ command: "mpg123", args: ["-q", filePath] }]
+                    : []),
+                {
+                    command: "cvlc",
+                    args: ["--play-and-exit", "--no-loop", "--intf", "dummy", filePath],
+                },
+                { command: "paplay", args: [filePath] },
+                { command: "aplay", args: [filePath] },
+            ];
+        case "win32": {
+            // filePath is embedded inside a single-quoted PS string below, so it must
+            // be escaped — a Windows username with an apostrophe (e.g. `O'Brien`,
+            // present in `%TEMP%`) would otherwise break out of the string.
+            const psPath = escapePowerShellSingleQuoted(filePath);
+            if (isWav) {
+                return [
+                    {
+                        command: "powershell",
+                        args: [
+                            "-NoProfile",
+                            "-Command",
+                            `(New-Object System.Media.SoundPlayer '${psPath}').PlaySync()`,
+                        ],
+                    },
+                ];
             }
-            return { command: "paplay", args: [filePath] };
-        case "win32":
-            if (format === "wav") {
-                return {
+            return [
+                {
                     command: "powershell",
                     args: [
                         "-NoProfile",
                         "-Command",
-                        `(New-Object System.Media.SoundPlayer '${filePath}').PlaySync()`,
+                        `$player = New-Object -ComObject WMPlayer.OCX; $player.URL = '${psPath}'; $player.controls.play(); Start-Sleep -Seconds 1; while ($player.playState -eq 3) { Start-Sleep -Milliseconds 100 }; $player.close()`,
                     ],
-                };
-            }
-            return {
-                command: "powershell",
-                args: [
-                    "-NoProfile",
-                    "-Command",
-                    `$player = New-Object -ComObject WMPlayer.OCX; $player.URL = '${filePath}'; $player.controls.play(); Start-Sleep -Seconds 1; while ($player.playState -eq 3) { Start-Sleep -Milliseconds 100 }; $player.close()`,
-                ],
-            };
+                },
+            ];
+        }
         default:
-            throw new Error(`Unsupported platform: ${platform}. Audio playback is supported on macOS, Linux, and Windows.`);
+            return [];
     }
 }
+/**
+ * Build a helpful, format-aware error message when no player could decode the file.
+ *
+ * Exported for testing: the message a user sees when Linux mp3 playback finds no
+ * decoder must name the real fix (ffmpeg/mpv/mpg123/VLC or `--tts-format wav`),
+ * not the misleading "install PulseAudio" that paplay-only routing produced (#1138).
+ */
+export function buildPlaybackErrorMessage(platform, format, attempts) {
+    const tried = attempts.length ? ` (tried: ${attempts.join("; ")})` : "";
+    if (platform === "linux") {
+        if (format === "wav") {
+            return `Could not play wav audio${tried}. Install ALSA (aplay) or PulseAudio (paplay).`;
+        }
+        // mpg123 only decodes mp3 (see getPlayerCandidates) — recommending it for
+        // ogg/opus failures would send users chasing a decoder that can't help.
+        if (format === "mp3") {
+            return `Could not play mp3 audio${tried}. paplay/aplay cannot decode mp3; install one of: ffmpeg (ffplay), mpv, mpg123, or VLC (cvlc) — or use --tts-format wav.`;
+        }
+        return `Could not play ${format} audio${tried}. Install ffmpeg (ffplay), mpv, or VLC (cvlc) — or use --tts-format wav.`;
+    }
+    return `Could not play ${format} audio${tried}. Ensure a system audio player is installed and available in PATH.`;
+}
 /**
  * Play audio from a buffer using platform-specific CLI tools
  *
- * Writes the buffer to a temporary file, plays it using the appropriate
- * system audio player, and cleans up the temp file afterward.
+ * Writes the buffer to a temporary file, plays it using the first available
+ * system audio player that can decode the format, and cleans up the temp file.
  *
  * Supported platforms:
- * - macOS: uses `afplay` (built-in, supports mp3/wav/aac/flac)
- * - Linux: uses `paplay` for non-wav, `aplay` for wav
- * - Windows: uses PowerShell SoundPlayer (wav) or WMPlayer.OCX (mp3)
+ * - macOS: `afplay` (built-in; decodes mp3/wav/aac/flac)
+ * - Linux: real decoders (ffplay/mpv/mpg123/cvlc) for compressed formats,
+ *   aplay/paplay for wav — falling through the list until one works
+ * - Windows: PowerShell SoundPlayer (wav) or WMPlayer.OCX (compressed)
  *
  * @param buffer - Audio data buffer
  * @param format - Audio format (mp3, wav, ogg, opus)
- * @throws Error if playback fails or platform is unsupported
+ * @throws Error if no available player can play the audio, or platform is unsupported
  *
  * @example
  * ```typescript
@@ -94,36 +180,47 @@ function getPlayerCommand(filePath, format) {
  */
 export async function playAudio(buffer, format) {
     const ext = getAudioExtension(format);
-    const tempFile = path.join(os.tmpdir(), `nl-tts-${Date.now()}.${ext}`);
+    // randomUUID (not just Date.now()) avoids two concurrent calls in the same
+    // millisecond racing on the same temp path.
+    const tempFile = path.join(os.tmpdir(), `nl-tts-${randomUUID()}.${ext}`);
     try {
         // Write audio buffer to temp file
         await fs.promises.writeFile(tempFile, buffer);
-        const { command, args } = getPlayerCommand(tempFile, format);
-        try {
-            await execFileAsync(command, args);
+        const candidates = getPlayerCandidates(tempFile, format);
+        if (candidates.length === 0) {
+            throw new Error(`Unsupported platform: ${process.platform}. Audio playback is supported on macOS, Linux, and Windows.`);
         }
-        catch (execError) {
-            const err = execError;
-            // Handle binary not found
-            if (err.code === "ENOENT") {
-                if (process.platform === "linux" && command === "paplay") {
-                    // Fallback to aplay on Linux
-                    try {
-                        await execFileAsync("aplay", [tempFile]);
-                        return;
-                    }
-                    catch (fallbackError) {
-                        const fbErr = fallbackError;
-                        if (fbErr.code === "ENOENT") {
-                            throw new Error("Neither paplay nor aplay found. Install PulseAudio (paplay) or ALSA (aplay) for audio playback.", { cause: fallbackError });
-                        }
-                        throw fallbackError;
-                    }
-                }
-                throw new Error(`Audio player '${command}' not found. Ensure it is installed and available in PATH.`, { cause: execError });
+        const attempts = [];
+        for (const { command, args } of candidates) {
+            try {
+                // `timeout` guards against a hung decoder (e.g. blocked on the audio
+                // device) so playback can't stall the CLI forever; SIGTERM lets the
+                // player shut down cleanly before Node force-kills it.
+                await execFileAsync(command, args, {
+                    timeout: PLAYER_TIMEOUT_MS,
+                    killSignal: "SIGTERM",
+                });
+                return; // Played successfully.
+            }
+            catch (execError) {
+                const err = execError;
+                // Every failure (missing binary, decode error, or timeout) is
+                // recorded and surfaced in the final error below — none are lost.
+                // We still advance to the next candidate rather than aborting on the
+                // first non-ENOENT failure: `command` existing but failing on this
+                // particular file (e.g. a corrupt stream, or one decoder lacking
+                // codec support) doesn't mean the *next* candidate will fail too,
+                // and failing fast here would defeat the multi-decoder fallback
+                // that #1138 exists to provide.
+                const detail = err.killed
+                    ? `timed out after ${PLAYER_TIMEOUT_MS}ms`
+                    : err.code === "ENOENT"
+                        ? "not installed"
+                        : (err.message ?? "failed");
+                attempts.push(`${command}: ${detail}`);
             }
-            throw execError;
         }
+        throw new Error(buildPlaybackErrorMessage(process.platform, format, attempts));
     }
     finally {
         // Always clean up temp file

package/dist/lib/proxy/rollingProxyServer.d.ts

@@ -0,0 +1,3 @@
+import type { RollingProxyServer, RollingProxyServerOptions } from "../types/index.js";
+/** Keep one public listener stable while serving workers start and rotate. */
+export declare function startRollingProxyServer(options: RollingProxyServerOptions): Promise<RollingProxyServer>;

package/dist/lib/proxy/rollingProxyServer.js

@@ -0,0 +1,149 @@
+import { createServer } from "node:net";
+import { ErrorFactory } from "../utils/errorHandling.js";
+import { RollingWorkerSupervisor } from "./rollingWorkerSupervisor.js";
+const DEFAULT_RECOVERY_DELAY_MS = 250;
+const DEFAULT_MAX_RECOVERY_DELAY_MS = 10_000;
+/** Keep one public listener stable while serving workers start and rotate. */
+export async function startRollingProxyServer(options) {
+    let desiredVersion = options.initialVersion;
+    let closing = false;
+    let listening = false;
+    let recoveryFailures = 0;
+    let recoveryTimer;
+    const recoveryDelayMs = Math.max(1, options.recoveryDelayMs ?? DEFAULT_RECOVERY_DELAY_MS);
+    const maxRecoveryDelayMs = Math.max(recoveryDelayMs, options.maxRecoveryDelayMs ?? DEFAULT_MAX_RECOVERY_DELAY_MS);
+    const scheduleRecovery = () => {
+        if (closing || !listening || recoveryTimer) {
+            return;
+        }
+        const delay = Math.min(maxRecoveryDelayMs, recoveryDelayMs * 2 ** Math.min(recoveryFailures, 8));
+        options.log?.(`[proxy-supervisor] scheduling worker recovery version=${desiredVersion} delayMs=${delay}`);
+        recoveryTimer = setTimeout(() => {
+            recoveryTimer = undefined;
+            // An explicit replace() may have started (or completed) a generation
+            // while this timer was pending. Re-validate before recovering so we never
+            // launch a duplicate generation that conflicts with the requested worker.
+            const snapshot = supervisor.snapshot();
+            if (closing || snapshot.active || snapshot.candidate) {
+                return;
+            }
+            void supervisor.replace(desiredVersion).then(() => {
+                recoveryFailures = 0;
+            }, (error) => {
+                recoveryFailures += 1;
+                options.log?.(`[proxy-supervisor] worker recovery failed: ${error instanceof Error ? error.message : String(error)}`);
+                scheduleRecovery();
+            });
+        }, delay);
+        recoveryTimer.unref?.();
+    };
+    const stateChanged = (snapshot) => {
+        try {
+            options.onStateChange?.(snapshot);
+        }
+        catch (error) {
+            options.log?.(`[proxy-supervisor] failed to publish server state: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (listening && !closing && !snapshot.active && !snapshot.candidate) {
+            scheduleRecovery();
+        }
+    };
+    const supervisor = new RollingWorkerSupervisor({
+        spawnWorker: options.spawnWorker,
+        readyTimeoutMs: options.readyTimeoutMs,
+        socketQueueLimit: options.socketQueueLimit,
+        socketQueueTimeoutMs: options.socketQueueTimeoutMs,
+        shutdownTimeoutMs: options.shutdownTimeoutMs,
+        onStateChange: stateChanged,
+        log: options.log,
+    });
+    const listener = createServer({ pauseOnConnect: true }, (socket) => {
+        supervisor.acceptSocket(socket);
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            listener.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            listener.off("error", onError);
+            resolve();
+        };
+        listener.once("error", onError);
+        listener.once("listening", onListening);
+        listener.listen(options.port, options.host);
+    }).catch(async (error) => {
+        await supervisor.close();
+        throw error;
+    });
+    listening = true;
+    try {
+        await supervisor.start(desiredVersion);
+    }
+    catch (error) {
+        recoveryFailures = 1;
+        options.log?.(`[proxy-supervisor] initial worker failed; listener will remain available during recovery: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!supervisor.snapshot().active) {
+        scheduleRecovery();
+    }
+    const address = listener.address();
+    if (!address || typeof address === "string") {
+        listener.close();
+        void supervisor.close();
+        throw ErrorFactory.proxyWorkerLifecycle("rolling proxy listener did not expose a TCP address");
+    }
+    return {
+        address: { host: options.host, port: address.port },
+        replace: async (expectedVersion) => {
+            // Adopt the requested version as the recovery target up front (once it is
+            // a valid version string) so the autonomous recovery loop converges on it
+            // even if this explicit call collides with an in-flight recovery
+            // replacement — otherwise recovery keeps re-targeting a stale version and
+            // starves the caller (e.g. an update rollback) for the whole retry window.
+            const isValidVersion = /^\d+\.\d+\.\d+$/.test(expectedVersion);
+            if (isValidVersion) {
+                desiredVersion = expectedVersion;
+            }
+            // Cancel any pending recovery so it cannot race this explicit
+            // replacement and spawn a second, conflicting generation.
+            if (recoveryTimer) {
+                clearTimeout(recoveryTimer);
+                recoveryTimer = undefined;
+            }
+            try {
+                const snapshot = await supervisor.replace(expectedVersion);
+                recoveryFailures = 0;
+                return snapshot;
+            }
+            catch (error) {
+                // The explicit replacement failed (invalid version, closed, or a
+                // conflicting replacement is already in progress). Since we cancelled
+                // the pending recovery timer above, re-schedule recovery when nothing
+                // is serving so a crashed worker is not left unreplaced.
+                const snapshot = supervisor.snapshot();
+                if (!snapshot.active && !snapshot.candidate) {
+                    scheduleRecovery();
+                }
+                throw error;
+            }
+        },
+        snapshot: () => supervisor.snapshot(),
+        close: async () => {
+            if (closing) {
+                return;
+            }
+            closing = true;
+            listening = false;
+            if (recoveryTimer) {
+                clearTimeout(recoveryTimer);
+                recoveryTimer = undefined;
+            }
+            const listenerClosed = new Promise((resolve, reject) => {
+                listener.close((error) => (error ? reject(error) : resolve()));
+            });
+            await Promise.all([listenerClosed, supervisor.close()]);
+        },
+    };
+}
+//# sourceMappingURL=rollingProxyServer.js.map

package/dist/lib/proxy/rollingWorkerProcess.d.ts

@@ -0,0 +1,2 @@
+import type { RollingWorkerHandle, SpawnProxySocketWorkerOptions } from "../types/index.js";
+export declare function spawnProxySocketWorker(options: SpawnProxySocketWorkerOptions): RollingWorkerHandle;