dexterm-cli 0.1.1 → 0.1.2

package/dist/packages/voice/src/stt/whisper.js

@@ -15,15 +15,25 @@ export const WHISPER_BIN = process.env.DEXTERM_WHISPER_BIN || 'whisper-cli';
 export const WHISPER_MODEL = process.env.DEXTERM_WHISPER_MODEL || join(homedir(), '.dexterm', 'models', 'ggml-base.en.bin');
 /** Where the user is told to put the model (doctor fix line). */
 export const WHISPER_MODEL_DIR = join(homedir(), '.dexterm', 'models');
-/** Pick a mic-capture tool: sox (`rec`) first, then ffmpeg's avfoundation input. */
-function pickRecorder() {
+/**
+ * Pick a mic-capture tool, best-first. sox (`rec`) is cross-platform; `arecord` (alsa-utils) is the
+ * native Linux capture tool (task-1408) and finalises its WAV header on SIGINT; ffmpeg is last and its
+ * input format is platform-specific (avfoundation on macOS, alsa on Linux). All write a 16 kHz mono
+ * 16-bit WAV, which is what whisper.cpp wants. Returns null when nothing is installed.
+ */
+export function pickRecorder() {
     if (which('rec'))
         return { cmd: 'rec', args: (wav) => ['-q', '-c', '1', '-r', '16000', '-b', '16', wav], stopSignal: 'SIGINT' };
     if (which('sox'))
         return { cmd: 'sox', args: (wav) => ['-q', '-d', '-c', '1', '-r', '16000', '-b', '16', wav], stopSignal: 'SIGINT' };
+    if (process.platform !== 'darwin' && which('arecord')) {
+        return { cmd: 'arecord', args: (wav) => ['-q', '-f', 'S16_LE', '-c', '1', '-r', '16000', wav], stopSignal: 'SIGINT' };
+    }
     if (which('ffmpeg')) {
-        const dev = process.env.DEXTERM_FFMPEG_MIC || ':default';
-        return { cmd: 'ffmpeg', args: (wav) => ['-hide_banner', '-loglevel', 'error', '-f', 'avfoundation', '-i', dev, '-ac', '1', '-ar', '16000', '-y', wav], stopSignal: 'SIGINT' };
+        const linux = process.platform === 'linux';
+        const fmt = linux ? 'alsa' : 'avfoundation';
+        const dev = process.env.DEXTERM_FFMPEG_MIC || (linux ? 'default' : ':default');
+        return { cmd: 'ffmpeg', args: (wav) => ['-hide_banner', '-loglevel', 'error', '-f', fmt, '-i', dev, '-ac', '1', '-ar', '16000', '-y', wav], stopSignal: 'SIGINT' };
     }
     return null;
 }

package/dist/packages/voice/src/tts/espeak.js

@@ -0,0 +1,131 @@
+// Portable (Linux/Windows) TTS via espeak-ng (task-1393 Part 2). espeak-ng is free, local, ships in or
+// installs trivially on every Linux distro, and runs on Windows too. It is the "works everywhere" baseline
+// off macOS; a Piper neural voice is a higher-quality upgrade that needs a downloaded model (see doctor).
+//
+// It carries the SAME contract as the macOS engine: text is SANITISED and delivered on STDIN (espeak-ng
+// treats `[[…]]` as phoneme input, so stripping it is a safety requirement, not a nicety), a new speak()
+// cleanly interrupts the current one (single queue), and the default voice is an explicit deep British
+// male (`en-gb+m3`) — never a surprise.
+//
+// VERIFICATION NOTE: the logic is unit-tested against a fake binary; it was NOT run against real
+// espeak-ng audio because the Linux (WSL) box was unreachable during this task. See the handoff.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { sanitizeSpeech } from "./voices.js";
+/** espeak-ng first (actively maintained), then the older espeak. Overridable for tests. */
+export const ESPEAK_BIN = process.env.DEXTERM_ESPEAK_BIN || '';
+/** The default portable voice: a British male. `+m3` is a deeper male variant. */
+export const DEFAULT_ESPEAK_VOICE = 'en-gb+m3';
+/** espeak words-per-minute default (close to the macOS 190 feel). */
+export const DEFAULT_ESPEAK_RATE = 175;
+function which(bin) {
+    if (!bin)
+        return null;
+    if (bin.includes('/') || bin.includes('\\'))
+        return existsSync(bin) ? bin : null;
+    for (const p of (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':')) {
+        if (!p)
+            continue;
+        if (existsSync(join(p, bin)))
+            return join(p, bin);
+        if (process.platform === 'win32' && existsSync(join(p, `${bin}.exe`)))
+            return join(p, `${bin}.exe`);
+    }
+    return null;
+}
+/** Resolve the espeak binary path: an explicit override, else espeak-ng, else espeak. */
+export function resolveEspeakBin() {
+    return which(ESPEAK_BIN) || which('espeak-ng') || which('espeak');
+}
+/**
+ * espeak voice names are language codes, optionally with a variant: `en`, `en-gb`, `en-us+m3`, `de+f2`.
+ * A macOS voice name like "Eddy (English (UK))" or "Daniel" is NOT one and must never be passed to
+ * espeak verbatim (task-1408 residual) — it would be an invalid `-v` argument. This matches only the
+ * espeak form, so a Mac voice name is rejected and the engine default is used instead.
+ */
+const ESPEAK_VOICE_RE = /^[a-z]{2,3}(-[a-z0-9]+)*(\+[a-z0-9]+)?$/i;
+/** A valid espeak voice token, or null when `configured` is empty or is a macOS voice name. */
+export function espeakVoiceFor(configured) {
+    const v = configured?.trim();
+    if (!v)
+        return null;
+    return ESPEAK_VOICE_RE.test(v) ? v : null;
+}
+export class EspeakTts {
+    name = 'espeak';
+    label = 'espeak-ng (local, no key)';
+    defaultVoice;
+    current = null;
+    constructor(defaultVoice = DEFAULT_ESPEAK_VOICE) { this.defaultVoice = defaultVoice; }
+    get voiceName() { return this.defaultVoice; }
+    async available() { return resolveEspeakBin() !== null; }
+    /** espeak-ng has no per-machine "installed voices" list the user cycles; the default covers it. */
+    async listVoices() { return [this.defaultVoice]; }
+    speak(text, opts = {}) {
+        this.stopCurrent(); // single queue: never two speakers at once
+        const bin = resolveEspeakBin();
+        const voice = opts.voice ?? this.defaultVoice;
+        const rate = opts.rate ?? DEFAULT_ESPEAK_RATE;
+        const safe = sanitizeSpeech(text);
+        const args = ['-v', voice, '-s', String(rate)];
+        if (typeof opts.pitch === 'number' && Number.isFinite(opts.pitch)) {
+            args.push('-p', String(Math.max(0, Math.min(99, Math.round(opts.pitch))))); // 0-99, lower = deeper
+        }
+        args.push('--stdin'); // read the utterance from stdin — never an argv word
+        let child = null;
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        const finish = () => { if (!stopped) {
+            stopped = true;
+            if (this.current === handle)
+                this.current = null;
+            resolve();
+        } };
+        try {
+            if (!bin)
+                throw new Error('espeak not found');
+            child = spawn(bin, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            child.stdin?.on('error', () => { });
+            try {
+                child.stdin?.end(safe);
+            }
+            catch { /* child gone */ }
+            child.on('spawn', () => { if (!stopped)
+                opts.onFirstAudio?.(); });
+            child.on('error', finish);
+            child.on('close', finish);
+        }
+        catch {
+            queueMicrotask(finish); // no espeak → degrade to text
+        }
+        const handle = {
+            done,
+            stop: () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                if (this.current === handle)
+                    this.current = null;
+                try {
+                    child?.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+                resolve();
+            },
+        };
+        this.current = handle;
+        return handle;
+    }
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/packages/voice/src/tts/piper.js

@@ -0,0 +1,206 @@
+// Piper neural TTS engine (task-1408). Piper is a free, local, no-key neural text-to-speech engine
+// (rhasspy/piper, MIT) that sounds markedly better than espeak-ng. Off macOS it is the PREFERRED
+// speech-out engine; espeak-ng stays the last-resort baseline (see engines.ts). Verified in Docker
+// (task-1397/task-1408): the prebuilt Linux binary + the en_GB-alan-medium voice write a valid,
+// non-silent 22.05 kHz WAV that whisper.cpp transcribes almost word-for-word.
+//
+// It carries the SAME contract as the macOS `say` and espeak engines:
+//   - text is SANITISED (sanitizeSpeech strips `[[…]]`, control chars, a leading `-`, caps length)
+//   - text is delivered on STDIN, never as an argv word
+//   - a new speak() cleanly INTERRUPTS the current one — one queue, never two voices at once
+//   - the voice is fixed by the downloaded MODEL, never by a macOS voice name (so config.voice.name,
+//     which on a Mac is e.g. "Eddy (English (UK))", is NEVER passed verbatim to Piper)
+//
+// Piper has no audio output of its own: it synthesises to a WAV, which we then play through the
+// platform player (aplay / paplay / ffplay — detected and reported by the doctor). Containers have no
+// audio device, so real playback is unverified; synthesis-to-file IS verified (synthToFile + whisper).
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sanitizeSpeech } from "./voices.js";
+/** The Piper voice dexterm defaults to off macOS: a British male, medium quality (local, no key). */
+export const DEFAULT_PIPER_VOICE = 'en_GB-alan-medium';
+/** Where the downloaded Piper voice model lives (see `dexterm voice download piper-voice`). */
+export const PIPER_MODEL = process.env.DEXTERM_PIPER_MODEL
+    || join(homedir(), '.dexterm', 'models', `${DEFAULT_PIPER_VOICE}.onnx`);
+/** Audio players we can hand a WAV to, best-first. Reported by the doctor so the user knows which plays. */
+export const PIPER_PLAYERS = ['aplay', 'paplay', 'ffplay'];
+function which(bin) {
+    if (!bin)
+        return null;
+    if (bin.includes('/') || bin.includes('\\'))
+        return existsSync(bin) ? bin : null;
+    const sep = process.platform === 'win32' ? ';' : ':';
+    for (const p of (process.env.PATH ?? '').split(sep)) {
+        if (!p)
+            continue;
+        if (existsSync(join(p, bin)))
+            return join(p, bin);
+        if (process.platform === 'win32' && existsSync(join(p, `${bin}.exe`)))
+            return join(p, `${bin}.exe`);
+    }
+    return null;
+}
+/**
+ * Resolve the Piper binary. We look at an explicit override, then the dexterm-local install
+ * (`~/.dexterm/piper/piper`, where the prebuilt release is extracted), then PATH. NOTE: Debian's
+ * `apt install piper` is an UNRELATED gaming-mouse tool, so the doctor steers users to the rhasspy
+ * prebuilt release rather than apt; a wrong `piper` on PATH simply fails to synth and voice degrades
+ * to text (it never crashes).
+ */
+export function resolvePiperBin() {
+    return which(process.env.DEXTERM_PIPER_BIN || '')
+        || which(join(homedir(), '.dexterm', 'piper', 'piper'))
+        || which('piper');
+}
+/** The player that will play Piper's WAV, or null when none is installed. */
+export function pickPlayer() {
+    const override = process.env.DEXTERM_AUDIO_PLAYER;
+    if (override)
+        return which(override) ? override : null;
+    for (const p of PIPER_PLAYERS)
+        if (which(p))
+            return p;
+    return null;
+}
+/** Argv to play a finished WAV through the given player (quiet, exits on end, no window). */
+function playerArgs(player, wav) {
+    switch (player) {
+        case 'ffplay': return ['-nodisp', '-autoexit', '-loglevel', 'quiet', wav];
+        case 'paplay': return [wav];
+        case 'aplay':
+        default: return ['-q', wav];
+    }
+}
+export class PiperTts {
+    name = 'piper';
+    label = 'Piper (neural, local, no key)';
+    model;
+    /** The utterance currently playing. A new speak() stops it first, so there is only ever one. */
+    current = null;
+    constructor(model = PIPER_MODEL) { this.model = model; }
+    /** The voice id this engine speaks with (the model basename), for the status line. */
+    get voiceName() { return DEFAULT_PIPER_VOICE; }
+    /** True when Piper can speak ALOUD here: the binary, the voice model and a player are all present. */
+    async available() {
+        return resolvePiperBin() !== null && existsSync(this.model) && pickPlayer() !== null;
+    }
+    /** True when Piper can SYNTHESISE here (binary + model) even with no audio device (used for the proof). */
+    canSynth() {
+        return resolvePiperBin() !== null && existsSync(this.model);
+    }
+    /** Piper's voice is the model; there is no per-machine installed-voice list to cycle. */
+    async listVoices() { return [DEFAULT_PIPER_VOICE]; }
+    /**
+     * Synthesise `text` to a WAV at `outPath`. Resolves on success, rejects on a missing binary/model or a
+     * non-zero exit. This is the engine's testable, audio-device-free core — the Docker proof and the unit
+     * tests drive it directly. The text is sanitised and delivered on stdin, exactly as speak() does.
+     */
+    synthToFile(text, outPath, opts = {}) {
+        const bin = resolvePiperBin();
+        const safe = sanitizeSpeech(text);
+        return new Promise((resolve, reject) => {
+            if (!bin) {
+                reject(new Error('piper binary not found'));
+                return;
+            }
+            const args = ['--model', this.model, '--output_file', outPath];
+            if (typeof opts.lengthScale === 'number' && Number.isFinite(opts.lengthScale)) {
+                args.push('--length_scale', String(opts.lengthScale)); // >1 = slower speech
+            }
+            let child;
+            try {
+                child = spawn(bin, args, { stdio: ['pipe', 'ignore', 'pipe'] });
+            }
+            catch (e) {
+                reject(e);
+                return;
+            }
+            let err = '';
+            child.stderr?.on('data', (d) => { err += d; });
+            child.stdin?.on('error', () => { });
+            // Piper reads one line of text from stdin; the sanitiser already collapsed newlines to one line.
+            try {
+                child.stdin?.end(safe + '\n');
+            }
+            catch { /* child gone */ }
+            child.on('error', reject);
+            child.on('close', (code) => code === 0
+                ? resolve()
+                : reject(new Error(`piper exit ${code}: ${err.slice(-200)}`)));
+        });
+    }
+    speak(text, opts = {}) {
+        this.stopCurrent(); // single queue: never two speakers at once
+        const player = pickPlayer();
+        // rate: map the words-per-minute feel to Piper's length_scale (lower rate → slower → larger scale).
+        const lengthScale = typeof opts.rate === 'number' && opts.rate > 0 ? Math.max(0.5, Math.min(2, 190 / opts.rate)) : undefined;
+        let child = null;
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        const dir = mkdtempSync(join(tmpdir(), 'dexterm-piper-'));
+        const wav = join(dir, 'speech.wav');
+        const cleanup = () => { try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ } };
+        const finish = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            if (this.current === handle)
+                this.current = null;
+            cleanup();
+            resolve();
+        };
+        const handle = {
+            done,
+            stop: () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                if (this.current === handle)
+                    this.current = null;
+                try {
+                    child?.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+                cleanup();
+                resolve();
+            },
+        };
+        this.current = handle;
+        if (!player) {
+            queueMicrotask(finish);
+            return handle;
+        } // no player → can't speak aloud; degrade to text
+        // Synthesise, then play. Piper's RTF is ~0.16, so synth is fast; first audio is the player spawn.
+        this.synthToFile(text, wav, lengthScale !== undefined ? { lengthScale } : {}).then(() => {
+            if (stopped)
+                return;
+            try {
+                child = spawn(player, playerArgs(player, wav), { stdio: 'ignore' });
+                child.on('spawn', () => { if (!stopped)
+                    opts.onFirstAudio?.(); });
+                child.on('error', finish);
+                child.on('close', finish);
+            }
+            catch {
+                finish();
+            }
+        }).catch(finish); // synth failed (bad binary/model) → degrade to text
+        return handle;
+    }
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/packages/voice/src/tts/say.js

@@ -1,15 +1,29 @@
-// macOS `say` TTS engine (task-1282). `say` ships with macOS, needs no key and no network, so it is
-// the free/portable default (SPEC: macOS say first). It streams to the audio device as it synthesises,
-// so time-to-first-audio is close to process spawn. speak() is interruptible via stop() (SIGTERM to
-// the child), which is how a key or the user starting to talk cuts a reply short.
+// macOS `say` TTS engine (task-1282, hardened task-1393). `say` ships with macOS, needs no key and no
+// network, so it is the free/portable default (SPEC: macOS say first). It streams to the audio device,
+// so time-to-first-audio is close to process spawn. speak() is interruptible via stop() (SIGTERM to the
+// child), which is how a key or the user starting to talk cuts a reply short.
+//
+// task-1393 hardening:
+//   - text is SANITISED (no `[[…]]` embedded commands, no leading-`-` flag, addresses shortened, capped)
+//   - text is delivered on STDIN (`say -f -`), never as the last argv word
+//   - a new speak() cleanly INTERRUPTS the current one, so two `say` processes never overlap (one queue)
+//   - the voice is always EXPLICIT (resolved to a deep British male upstream); it never falls back to the
+//     machine's system voice
 import { spawn } from 'node:child_process';
 import { execFile } from 'node:child_process';
+import { parseSayVoices, sanitizeSpeech } from "./voices.js";
 export const SAY_BIN = process.env.DEXTERM_SAY_BIN || 'say';
+/** Consistent speaking rate (words-per-minute-ish) for every reply path. */
+export const DEFAULT_RATE = 190;
 export class SayTts {
     name = 'say';
     label = 'macOS say (built-in, no key)';
     defaultVoice;
+    /** The utterance currently playing. A new speak() stops it first, so there is only ever one. */
+    current = null;
     constructor(defaultVoice) { this.defaultVoice = defaultVoice; }
+    /** The resolved default voice this engine speaks with — used to seed the controller / status line. */
+    get voiceName() { return this.defaultVoice; }
     async available() {
         if (process.platform !== 'darwin')
             return false;
@@ -23,22 +37,12 @@ export class SayTts {
             }
         });
     }
-    /** Parse `say -v '?'`: each line is "Name            en_US    # sample text". */
-    async listVoices() {
+    /** Installed voices with their locale. Robust against the single-space padding on long voice names. */
+    async listVoicesDetailed() {
         return new Promise((resolve) => {
             try {
                 execFile(SAY_BIN, ['-v', '?'], { timeout: 5000, maxBuffer: 1 << 20 }, (err, stdout) => {
-                    if (err || !stdout) {
-                        resolve([]);
-                        return;
-                    }
-                    const names = [];
-                    for (const line of stdout.split('\n')) {
-                        const m = line.match(/^(.+?)\s{2,}[a-z]{2}(?:[_-][A-Za-z]+)?\s/);
-                        if (m)
-                            names.push(m[1].trim());
-                    }
-                    resolve(names);
+                    resolve(err || !stdout ? [] : parseSayVoices(stdout));
                 });
             }
             catch {
@@ -46,45 +50,64 @@ export class SayTts {
             }
         });
     }
+    /** Selectable voice names (the TtsEngine contract). */
+    async listVoices() {
+        return (await this.listVoicesDetailed()).map((v) => v.name);
+    }
     speak(text, opts = {}) {
+        // One queue: cut off whatever is playing so two `say` processes never overlap (clean interrupt).
+        this.stopCurrent();
         const voice = opts.voice ?? this.defaultVoice;
-        const rate = opts.rate ?? 190;
+        const rate = opts.rate ?? DEFAULT_RATE;
+        // Sanitise the UNTRUSTED text first, then prepend our own TRUSTED pitch command. Order matters: the
+        // sanitiser strips any `[[…]]` the text tried to smuggle, so only our validated `[[pbas N]]` survives.
+        let safe = sanitizeSpeech(text);
+        if (typeof opts.pitch === 'number' && Number.isFinite(opts.pitch)) {
+            const pbas = Math.max(0, Math.min(100, Math.round(opts.pitch)));
+            safe = `[[pbas ${pbas}]] ${safe}`;
+        }
         const args = [];
         if (voice)
             args.push('-v', voice);
-        args.push('-r', String(rate), text);
+        args.push('-r', String(rate));
+        args.push('-f', '-'); // read the utterance from stdin — the text is NEVER an argv word
         let child = null;
         let stopped = false;
         let resolve;
         const done = new Promise((r) => { resolve = r; });
+        const finish = () => { if (!stopped) {
+            stopped = true;
+            if (this.current === handle)
+                this.current = null;
+            resolve();
+        } };
         try {
-            child = spawn(SAY_BIN, args, { stdio: 'ignore' });
-            // `say` has no first-sample hook; the spawn event is the closest honest lower bound and is what
-            // the latency table reports as "first spoken word" for this engine.
+            child = spawn(SAY_BIN, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            // Nothing is spoken until stdin is closed; write the sanitised text and end it.
+            child.stdin?.on('error', () => { });
+            try {
+                child.stdin?.end(safe);
+            }
+            catch { /* child gone */ }
+            // `say` has no first-sample hook; the spawn event is the closest honest lower bound and is what the
+            // latency table reports as "first spoken word" for this engine.
             child.on('spawn', () => { if (!stopped)
                 opts.onFirstAudio?.(); });
-            child.on('error', () => { if (!stopped) {
-                stopped = true;
-                resolve();
-            } });
-            child.on('close', () => { if (!stopped) {
-                stopped = true;
-                resolve();
-            } });
+            child.on('error', finish);
+            child.on('close', finish);
         }
         catch {
             // No `say` on this machine: resolve immediately so the caller degrades to text.
-            queueMicrotask(() => { if (!stopped) {
-                stopped = true;
-                resolve();
-            } });
+            queueMicrotask(finish);
         }
-        return {
+        const handle = {
             done,
             stop: () => {
                 if (stopped)
                     return;
                 stopped = true;
+                if (this.current === handle)
+                    this.current = null;
                 try {
                     child?.kill('SIGTERM');
                 }
@@ -92,5 +115,18 @@ export class SayTts {
                 resolve();
             },
         };
+        this.current = handle;
+        return handle;
+    }
+    /** Stop the currently-playing utterance, if any. */
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
     }
 }