dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/voice/src/download.js

@@ -0,0 +1,184 @@
+// Voice model downloader (task-1408). The whisper.cpp base.en model and the Piper en_GB-alan-medium
+// voice are NOT shipped (free-forever rule: no bundled large binaries, no keys). dexterm downloads them
+// on request, and ONLY on request:
+//   - from the OFFICIAL source (the ggml-org / rhasspy repositories on Hugging Face),
+//   - after EXPLICIT user confirmation (never a silent auto-download),
+//   - and verified against a checksum pinned here from the upstream LFS pointer, so a corrupted or
+//     tampered download is rejected and never written into place.
+//
+// This module is pure logic + injected fetch/confirm/log, so it is unit-testable with a fake registry
+// and never touches the real network in tests. The CLI (`dexterm voice download …`) wires the real
+// global fetch, a readline y/N prompt, and stdout.
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, rename, rm, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { once } from 'node:events';
+/** Total download size of a spec, in whole MB (for the prompt). */
+export function specSizeMB(spec) {
+    return Math.round(spec.files.reduce((n, f) => n + (f.size ?? 0), 0) / (1024 * 1024));
+}
+/**
+ * The downloadable voice models, keyed by id. `home` is the dexterm home (~/.dexterm) so tests can
+ * point it at a temp dir. Checksums are pinned from the upstream Hugging Face LFS pointers (verified
+ * 2026-10-16): ggerganov/whisper.cpp and rhasspy/piper-voices@v1.0.0.
+ */
+export function modelRegistry(home = join(homedir(), '.dexterm')) {
+    const models = join(home, 'models');
+    return {
+        whisper: {
+            id: 'whisper',
+            label: 'whisper.cpp base.en (speech-to-text)',
+            note: 'whisper.cpp base.en — on-device speech recognition, ~141 MB, MIT (ggml-org/whisper.cpp)',
+            files: [{
+                    url: 'https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin',
+                    dest: join(models, 'ggml-base.en.bin'),
+                    sha256: 'a03779c86df3323075f5e796cb2ce5029f00ec8869eee3fdfb897afe36c6d002',
+                    size: 147964211,
+                }],
+        },
+        'piper-voice': {
+            id: 'piper-voice',
+            label: 'Piper en_GB-alan-medium (neural voice)',
+            note: 'Piper en_GB-alan-medium — British male neural voice, ~61 MB, MIT (rhasspy/piper-voices)',
+            files: [
+                {
+                    url: 'https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium/en_GB-alan-medium.onnx',
+                    dest: join(models, 'en_GB-alan-medium.onnx'),
+                    sha256: '0a309668932205e762801f1efc2736cd4b0120329622adf62be09e56339d3330',
+                    size: 63201294,
+                },
+                {
+                    url: 'https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_GB/alan/medium/en_GB-alan-medium.onnx.json',
+                    dest: join(models, 'en_GB-alan-medium.onnx.json'),
+                    validateJson: true,
+                },
+            ],
+        },
+    };
+}
+/** sha256 of an existing file, or null if it cannot be read. */
+async function fileSha256(path) {
+    try {
+        const h = createHash('sha256');
+        h.update(await readFile(path));
+        return h.digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `file` is already present AND valid (checksum match, or parses as JSON for config files). */
+async function isPresentAndValid(file) {
+    if (!existsSync(file.dest))
+        return false;
+    if (file.validateJson) {
+        try {
+            JSON.parse(await readFile(file.dest, 'utf8'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (file.sha256)
+        return (await fileSha256(file.dest)) === file.sha256.toLowerCase();
+    return true;
+}
+/**
+ * Download and verify one file. Streams to a `.part` temp alongside the destination (bounded memory),
+ * verifies size + sha256 (or JSON), then atomically renames into place. On ANY failure the temp is
+ * removed and nothing is written to the destination.
+ */
+async function downloadFile(file, fetchImpl, log) {
+    await mkdir(dirname(file.dest), { recursive: true });
+    const tmp = `${file.dest}.part`;
+    await rm(tmp, { force: true });
+    log(`  ↓ ${file.url}`);
+    let res;
+    try {
+        res = await fetchImpl(file.url, { redirect: 'follow' });
+    }
+    catch (e) {
+        throw new Error(`download failed (${file.url}): ${e.message}`);
+    }
+    if (!res.ok || !res.body)
+        throw new Error(`download failed (${file.url}): HTTP ${res.status}`);
+    const hash = createHash('sha256');
+    const out = createWriteStream(tmp);
+    let bytes = 0;
+    try {
+        for await (const chunk of Readable.fromWeb(res.body)) {
+            const buf = chunk;
+            bytes += buf.length;
+            hash.update(buf);
+            if (!out.write(buf))
+                await once(out, 'drain');
+        }
+        out.end();
+        await once(out, 'finish');
+    }
+    catch (e) {
+        out.destroy();
+        await rm(tmp, { force: true });
+        throw new Error(`download failed (${file.url}): ${e.message}`);
+    }
+    // Verify before anything lands at the real path.
+    try {
+        if (file.size !== undefined && bytes !== file.size) {
+            throw new Error(`size mismatch: got ${bytes} bytes, expected ${file.size}`);
+        }
+        if (file.sha256) {
+            const got = hash.digest('hex');
+            if (got !== file.sha256.toLowerCase())
+                throw new Error(`checksum mismatch: got ${got}, expected ${file.sha256}`);
+        }
+        else if (file.validateJson) {
+            JSON.parse(await readFile(tmp, 'utf8'));
+        }
+    }
+    catch (e) {
+        await rm(tmp, { force: true });
+        throw new Error(`verification failed (${file.url}): ${e.message}`);
+    }
+    await rename(tmp, file.dest);
+    const mb = (bytes / (1024 * 1024)).toFixed(1);
+    log(`  ✓ ${file.dest} (${mb} MB${file.sha256 ? ', sha256 ok' : ', json ok'})`);
+}
+/**
+ * Download a model after explicit confirmation. If every file is already present and valid, returns
+ * `already` WITHOUT prompting or touching the network. Otherwise it builds a one-prompt summary of what
+ * will be fetched and where, calls `confirm()`, and only then downloads + verifies each missing file.
+ */
+export async function downloadModel(spec, deps) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const log = deps.log ?? (() => { });
+    const presence = await Promise.all(spec.files.map(isPresentAndValid));
+    const missing = spec.files.filter((_, i) => !presence[i]);
+    if (missing.length === 0) {
+        log(`${spec.label} is already installed and verified.`);
+        return { status: 'already', files: spec.files.map((f) => f.dest) };
+    }
+    const dir = dirname(spec.files[0].dest);
+    const prompt = [
+        `Download ${spec.note}`,
+        `  from the official source to ${dir}`,
+        `  ${missing.length} file${missing.length === 1 ? '' : 's'}, ~${specSizeMB(spec)} MB, checksum-verified. Proceed?`,
+    ].join('\n');
+    if (!(await deps.confirm(prompt))) {
+        log('Cancelled — nothing downloaded.');
+        return { status: 'cancelled', files: spec.files.filter((_, i) => presence[i]).map((f) => f.dest) };
+    }
+    for (const f of missing)
+        await downloadFile(f, fetchImpl, log);
+    log(`${spec.label} installed.`);
+    return { status: 'ok', files: spec.files.map((f) => f.dest) };
+}
+/** Which model files exist and verify right now (for a status report; never touches the network). */
+export async function modelStatus(spec) {
+    const files = await Promise.all(spec.files.map(async (f) => ({ dest: f.dest, ok: await isPresentAndValid(f) })));
+    return { installed: files.every((f) => f.ok), files };
+}

package/dist/packages/voice/src/engines.js

@@ -0,0 +1,84 @@
+// Engine selection (task-1282). Picks the STT and TTS engines for this machine, honouring explicit
+// env overrides and falling back gracefully. The app degrades to text (never crashes) when nothing is
+// available; selectStt() returns null in that case and the controller says so.
+import { AppleStt } from "./stt/apple.js";
+import { WhisperStt } from "./stt/whisper.js";
+import { FakeStt } from "./stt/fake.js";
+import { SayTts } from "./tts/say.js";
+import { EspeakTts, espeakVoiceFor } from "./tts/espeak.js";
+import { PiperTts } from "./tts/piper.js";
+import { FakeTts } from "./tts/fake.js";
+import { resolveVoice } from "./tts/voices.js";
+/**
+ * Resolve the STT engine. `auto` prefers Apple Speech (on-device, streaming), then whisper base.en,
+ * then none. An explicit choice is returned even if it later proves unavailable, so the doctor and the
+ * status line can report exactly why voice-in is off.
+ */
+export async function selectStt(choice = process.env.DEXTERM_VOICE_STT || 'auto') {
+    if (choice === 'none')
+        return null;
+    if (choice === 'fake')
+        return new FakeStt();
+    if (choice === 'apple')
+        return new AppleStt();
+    if (choice === 'whisper')
+        return new WhisperStt();
+    // auto: probe in preference order.
+    const apple = new AppleStt();
+    if (await apple.available())
+        return apple;
+    const whisper = new WhisperStt();
+    if (await whisper.available())
+        return whisper;
+    return null;
+}
+/**
+ * Resolve the default `say` voice for this machine: the user's configured voice if it is installed and
+ * safe, else a deep British male (Daniel first), never a novelty voice and never the OS system default.
+ * Returns the full resolution (voice + why) so the controller and `dexterm doctor` can show it.
+ */
+export async function resolveSayVoice(say, configured) {
+    const installed = await say.listVoicesDetailed();
+    return resolveVoice({ configured, installed });
+}
+/**
+ * Resolve the TTS engine. `auto` uses macOS `say` when present, else none (voice replies off). When
+ * `say` is chosen, its default voice is resolved to an explicit deep British male so it can NEVER fall
+ * back to the machine's system voice (task-1393). `configuredVoice` is the user's `config.voice.name`.
+ */
+export async function selectTts(choice = process.env.DEXTERM_VOICE_TTS || 'auto', configuredVoice) {
+    if (choice === 'none')
+        return null;
+    if (choice === 'fake')
+        return new FakeTts();
+    // Piper and espeak are the off-macOS engines. A macOS voice name (config.voice.name is e.g.
+    // "Eddy (English (UK))") is NEVER passed to them verbatim: Piper's voice is its model, and espeak
+    // only honours a real espeak voice token (espeakVoiceFor drops a Mac name → the British default).
+    if (choice === 'piper') {
+        const p = new PiperTts();
+        return (await p.available()) ? p : null;
+    }
+    if (choice === 'espeak') {
+        const e = new EspeakTts(espeakVoiceFor(configuredVoice) ?? undefined);
+        return (await e.available()) ? e : null;
+    }
+    // On macOS, prefer `say`. Off macOS, `say` does not exist — use the portable engines below.
+    if (choice === 'say' || (choice === 'auto' && process.platform === 'darwin')) {
+        const probe = new SayTts();
+        if (choice === 'auto' && !(await probe.available()))
+            return null;
+        const r = await resolveSayVoice(probe, configuredVoice);
+        // No safe voice installed (only novelty voices): voice-out stays OFF so `say` can never be invoked
+        // without an explicit voice and fall back to the machine's system voice (task-1393). Text still works.
+        if (r.voice === null)
+            return null;
+        return new SayTts(r.voice);
+    }
+    // auto, non-darwin: Piper (neural, higher quality) when it can speak aloud, else espeak-ng, else
+    // text-only. Neither engine is ever handed a macOS voice name (task-1408).
+    const piper = new PiperTts();
+    if (await piper.available())
+        return piper;
+    const espeak = new EspeakTts(espeakVoiceFor(configuredVoice) ?? undefined);
+    return (await espeak.available()) ? espeak : null;
+}

package/dist/packages/voice/src/index.js

@@ -0,0 +1,20 @@
+// @dexterm/voice — JARVIS voice mode (task-1282). Public surface.
+//
+// Free and portable by requirement: macOS `say` for speech-out, on-device Apple Speech (compiled with
+// swiftc) or local whisper.cpp for speech-in — no paid APIs, no shipped keys. Voice can only ask the
+// analyst or trigger its existing safe actions; it can NEVER confirm, sign, or execute a trade.
+export * from "./types.js";
+export { route, isSafe } from "./router.js";
+export { spokenSummary, splitSentences } from "./summary.js";
+export { VoiceController } from "./controller.js";
+export { selectStt, selectTts, resolveSayVoice } from "./engines.js";
+export { voiceDoctor } from "./doctor.js";
+export { resolveVoice, isBannedVoice, normalizeVoiceName, parseSayVoices, sanitizeSpeech, BANNED_VOICE_NAMES, BRITISH_MALE_PREFERENCE, MAX_SPEAK_CHARS, VOICE_STYLE_DEFAULTS, voiceStyleDefaults, } from "./tts/voices.js";
+export { SayTts, DEFAULT_RATE } from "./tts/say.js";
+export { EspeakTts, DEFAULT_ESPEAK_VOICE, resolveEspeakBin, espeakVoiceFor } from "./tts/espeak.js";
+export { PiperTts, DEFAULT_PIPER_VOICE, PIPER_MODEL, PIPER_PLAYERS, resolvePiperBin, pickPlayer } from "./tts/piper.js";
+export { FakeTts } from "./tts/fake.js";
+export { WhisperStt, WHISPER_MODEL, WHISPER_MODEL_DIR, pickRecorder } from "./stt/whisper.js";
+export { modelRegistry, downloadModel, modelStatus, specSizeMB, } from "./download.js";
+export { AppleStt, ensureHelper } from "./stt/apple.js";
+export { FakeStt } from "./stt/fake.js";