dexterm-cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,179 @@
+// Apple Speech STT engine (task-1282). On-device SFSpeechRecognizer via a tiny Swift helper compiled
+// on the fly with `swiftc` — no key, no network, streaming partials (the spike's recommended primary
+// engine). The compiled helper is cached under ~/.dexterm/voice-helper; it is rebuilt only when the
+// source hash changes.
+//
+// LIVE CAVEAT (disclosed in the handoff): this path needs macOS Speech + Microphone authorization,
+// which can only be granted at the Mac by a person the first time it runs. available() reports whether
+// swiftc is present and the helper compiles; it cannot assert that TCC authorization will be granted.
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { APPLE_HELPER_SWIFT } from "./apple-helper.swift.js";
+const CACHE_DIR = process.env.DEXTERM_VOICE_HELPER_DIR || join(homedir(), '.dexterm', 'voice-helper');
+const SRC = join(CACHE_DIR, 'recognize.swift');
+const BIN = join(CACHE_DIR, 'recognize');
+const SWIFTC = process.env.DEXTERM_SWIFTC || 'swiftc';
+function which(bin) {
+    if (bin.includes('/'))
+        return existsSync(bin);
+    for (const p of (process.env.PATH ?? '').split(':'))
+        if (p && existsSync(join(p, bin)))
+            return true;
+    return false;
+}
+/** Compile the helper if the cached binary is missing or older than the current source. Returns BIN or null. */
+export function ensureHelper() {
+    if (!which(SWIFTC))
+        return null;
+    try {
+        mkdirSync(CACHE_DIR, { recursive: true });
+        const hash = createHash('sha256').update(APPLE_HELPER_SWIFT).digest('hex');
+        const stamp = join(CACHE_DIR, '.srchash');
+        const fresh = existsSync(BIN) && existsSync(stamp) && readFileSync(stamp, 'utf8') === hash && statSync(BIN).size > 0;
+        if (fresh)
+            return BIN;
+        writeFileSync(SRC, APPLE_HELPER_SWIFT);
+        const r = compileSync(SRC, BIN);
+        if (!r)
+            return null;
+        writeFileSync(stamp, hash);
+        return BIN;
+    }
+    catch {
+        return null;
+    }
+}
+function compileSync(src, out) {
+    // The compile is a one-time cost (cached by source hash); doing it synchronously keeps ensureHelper
+    // simple. It is only reached from available() / listen(), both already async from the caller's view.
+    try {
+        execFileSync(SWIFTC, ['-O', '-o', out, src], { timeout: 60_000, stdio: 'ignore' });
+        return existsSync(out);
+    }
+    catch {
+        return false;
+    }
+}
+export class AppleStt {
+    name = 'apple';
+    label = 'Apple Speech (on-device, no key)';
+    async available() {
+        if (process.platform !== 'darwin')
+            return false;
+        if (!which(SWIFTC))
+            return false;
+        return ensureHelper() !== null;
+    }
+    async listen() {
+        const bin = ensureHelper();
+        if (!bin)
+            throw new Error('Apple Speech helper unavailable (need swiftc)');
+        const t0 = Date.now();
+        const child = spawn(bin, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let partial = '';
+        let firstPartialMs = null;
+        let finalText = null;
+        let finalConfidence = 1;
+        let err = '';
+        let buf = '';
+        let readySeen = false;
+        let readyResolve = null;
+        const ready = new Promise((r) => { readyResolve = r; });
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (d) => {
+            buf += d;
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, i);
+                buf = buf.slice(i + 1);
+                if (!line.trim())
+                    continue;
+                let ev;
+                try {
+                    ev = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (ev.type === 'partial' && typeof ev.text === 'string') {
+                    partial = ev.text;
+                    if (firstPartialMs === null && ev.text)
+                        firstPartialMs = Date.now() - t0;
+                }
+                else if (ev.type === 'final') {
+                    finalText = String(ev.text ?? partial);
+                    if (typeof ev.confidence === 'number')
+                        finalConfidence = ev.confidence;
+                }
+                else if (ev.type === 'ready') {
+                    readySeen = true;
+                    readyResolve?.();
+                }
+                else if (ev.type === 'error') {
+                    err = String(ev.message ?? 'speech error');
+                    readyResolve?.();
+                }
+            }
+        });
+        child.stderr?.on('data', (d) => { err += d.toString(); });
+        let closed = false;
+        let spawnError = null;
+        const settled = new Promise((resolve) => {
+            child.on('close', () => { closed = true; readyResolve?.(); resolve(); });
+            // A failed spawn (EACCES / ENOENT / EAGAIN) must never become an uncaughtException that takes the
+            // whole terminal down (task-1339, re-verify N5): record it so stop() rejects cleanly instead.
+            child.on('error', (e) => { spawnError = e; closed = true; if (!err)
+                err = `mic helper failed to start: ${e.message}`; readyResolve?.(); resolve(); });
+        });
+        // Spawn failures surface on the next tick: give them one turn so listen() rejects (the controller
+        // then says "mic/STT could not start") rather than reporting a mic that was never open.
+        await new Promise((r) => setImmediate(r));
+        if (spawnError)
+            throw new Error(err || `mic helper failed to start: ${spawnError.message}`);
+        // Force-terminate the helper so the mic process can never outlive the session (task-1282 rework D5).
+        const kill = () => {
+            if (closed)
+                return;
+            try {
+                child.kill('SIGINT');
+            }
+            catch { /* ignore */ }
+            // If SIGINT did not land promptly, escalate so the OS mic indicator can never be left on.
+            setTimeout(() => { if (!closed) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* ignore */ }
+            } }, 500).unref?.();
+        };
+        // The helper authorizes, loads the on-device model and opens the audio engine before it emits
+        // `ready`. Reporting "listening" earlier let the user talk (and press stop) into a mic that was not
+        // open yet: an empty transcript and a silent no-op. Wait for it (bounded; first run after a
+        // permission prompt can take a few seconds).
+        await Promise.race([ready, new Promise((r) => setTimeout(r, 10_000))]);
+        if (closed || !readySeen) {
+            kill();
+            throw new Error(err || (closed ? 'mic helper exited before it was ready' : 'mic helper did not become ready in 10 s (check System Settings > Privacy > Microphone / Speech Recognition for your terminal)'));
+        }
+        return {
+            stop: async () => {
+                try {
+                    child.stdin?.write('stop\n');
+                    child.stdin?.end();
+                }
+                catch { /* ignore */ }
+                await Promise.race([settled, new Promise((r) => setTimeout(r, 5000))]);
+                if (!closed)
+                    kill(); // the helper ignored `stop` within 3 s: kill it rather than orphan the mic
+                const text = (finalText ?? partial).trim();
+                if (!text && err)
+                    throw new Error(err);
+                return { text, confidence: text ? finalConfidence : 0, firstPartialMs, speakerCount: 1 };
+            },
+            cancel: () => { kill(); },
+        };
+    }
+}

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

@@ -0,0 +1,34 @@
+// An STT engine that captures no audio — listen()/stop() replay a scripted transcript. It powers the
+// headless tests and the latency harness, and the `--text`/`--script` demo, so the whole pipeline is
+// exercisable with no mic and no model.
+export class FakeStt {
+    name = 'fake';
+    label = 'fake (scripted, for tests)';
+    queue;
+    deflt;
+    /** `scripts` are consumed one per listen(); once exhausted, `fallback` is reused. */
+    constructor(scripts = [], fallback = { text: '' }) {
+        this.queue = scripts.slice();
+        this.deflt = fallback;
+    }
+    async available() { return true; }
+    async listen() {
+        const s = this.queue.shift() ?? this.deflt;
+        let settled = null;
+        const resolveResult = () => (settled ??= {
+            text: s.text,
+            confidence: s.confidence ?? 1,
+            lowConfTokens: s.lowConfTokens ?? [],
+            firstPartialMs: s.firstPartialMs ?? null,
+            speakerCount: s.speakerCount ?? 1,
+            echoFlagged: s.echoFlagged ?? false,
+        });
+        return {
+            stop: () => new Promise((resolve) => {
+                const delay = Math.max(0, s.transcribeMs ?? 0);
+                setTimeout(() => resolve(resolveResult()), delay);
+            }),
+            cancel: () => { settled = resolveResult(); },
+        };
+    }
+}

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

@@ -0,0 +1,102 @@
+// whisper.cpp STT engine (task-1282). Local, no key, no network once the model is downloaded. This is
+// the portable fallback when Apple Speech is unavailable. The spike measured `base.en` at ~3.5–4.8 s
+// batch on a CPU-only Intel Mac with good accuracy; `large-v3-turbo` was unusable (55–93 s) — so this
+// engine defaults to `base.en` and the doctor steers the user to it, never to a turbo model on CPU.
+//
+// Capture: `sox`/`rec` or `ffmpeg -f avfoundation` writes a 16 kHz mono WAV while the key is held;
+// stop() finalises the WAV and runs whisper-cli on it. The WAV lives in the OS temp dir and is
+// DELETED immediately after transcription unless DEXTERM_VOICE_RECORD=1 — nothing is kept by default.
+import { spawn } from 'node:child_process';
+import { existsSync, rmSync, mkdtempSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const WHISPER_BIN = process.env.DEXTERM_WHISPER_BIN || 'whisper-cli';
+/** Default model — base.en, the spike's accurate+usable choice. Never large-v3-turbo on CPU. */
+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() {
+    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 (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' };
+    }
+    return null;
+}
+/** Synchronous PATH check without spawning (cheap; used by available() and pickRecorder). */
+function which(bin) {
+    const paths = (process.env.PATH ?? '').split(':');
+    for (const p of paths) {
+        if (p && existsSync(join(p, bin)))
+            return true;
+    }
+    return false;
+}
+export class WhisperStt {
+    name = 'whisper';
+    label = 'whisper.cpp base.en (local, no key)';
+    model;
+    recordToDisk = process.env.DEXTERM_VOICE_RECORD === '1';
+    constructor(model = WHISPER_MODEL) { this.model = model; }
+    async available() {
+        return (which(WHISPER_BIN) || existsSync(WHISPER_BIN)) && existsSync(this.model) && pickRecorder() !== null;
+    }
+    async listen() {
+        const rec = pickRecorder();
+        if (!rec)
+            throw new Error('no mic capture tool (install sox or ffmpeg)');
+        const dir = mkdtempSync(join(tmpdir(), 'dexterm-voice-'));
+        const wav = join(dir, 'capture.wav');
+        const t0 = Date.now();
+        const recorder = spawn(rec.cmd, rec.args(wav), { stdio: 'ignore' });
+        let cancelled = false;
+        const cleanup = () => {
+            if (this.recordToDisk)
+                return; // explicit opt-in to keep the audio
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+        };
+        return {
+            stop: async () => {
+                // Ask the recorder to finalise the WAV header, then wait for it to exit.
+                try {
+                    recorder.kill(rec.stopSignal);
+                }
+                catch { /* already gone */ }
+                await new Promise((r) => { recorder.on('close', () => r()); setTimeout(r, 2000); });
+                if (cancelled || !existsSync(wav)) {
+                    cleanup();
+                    return { text: '', confidence: 0 };
+                }
+                try {
+                    const text = await transcribe(wav, this.model);
+                    return { text, confidence: text ? 0.9 : 0, firstPartialMs: null, speakerCount: 1 };
+                }
+                finally {
+                    cleanup();
+                }
+            },
+            cancel: () => { cancelled = true; try {
+                recorder.kill('SIGKILL');
+            }
+            catch { /* ignore */ } cleanup(); },
+        };
+    }
+}
+/** Run whisper-cli on a finished WAV and return the transcript text. Rejects on a non-zero exit. */
+function transcribe(wav, model) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(WHISPER_BIN, ['-m', model, '-f', wav, '-nt', '-l', 'en', '-t', '4'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '', err = '';
+        p.stdout.on('data', (d) => (out += d));
+        p.stderr.on('data', (d) => (err += d));
+        p.on('error', reject);
+        p.on('close', (code) => code === 0 ? resolve(out.replace(/\s+/g, ' ').trim()) : reject(new Error(`whisper exit ${code}: ${err.slice(-200)}`)));
+    });
+}

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

@@ -0,0 +1,44 @@
+// Turn an analyst answer into its spoken form. It used to read only the FIRST ~2 sentences; since 2026-10-12
+// the whole answer is read, so the default is now every sentence, capped for sanity (a long-form dossier). The analyst's answer arrives either as a verdict + summary lines (structured
+// skills) or as free prose (chat follow-ups); this flattens both and trims to a speakable length.
+//
+// Pure and dependency-free so it is unit-tested headless.
+const MAX_CHARS = 1800;
+/** Collapse whitespace and strip markup/markdown that would be read aloud as noise. */
+function tidy(s) {
+    return s
+        .replace(/[*_`#>]/g, ' ') // markdown emphasis / headings / code / quotes
+        .replace(/\[[^\]]*\]\([^)]*\)/g, (m) => m.replace(/\]\([^)]*\)/, ']').replace(/[[\]]/g, '')) // [label](url) -> label
+        .replace(/https?:\/\/\S+/g, 'a link')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Split into sentences on ., !, ? boundaries, keeping it simple and robust. */
+export function splitSentences(text) {
+    const t = tidy(text);
+    if (!t)
+        return [];
+    const parts = t.match(/[^.!?]+[.!?]+|[^.!?]+$/g);
+    return (parts ?? [t]).map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Build the spoken summary. A verdict (e.g. "AVOID", "LARP") is spoken first as its own short clause,
+ * then the whole answer (every summary/prose sentence unless `maxSentences` limits it). Capped at MAX_CHARS.
+ */
+export function spokenSummary(src, maxSentences = Infinity) {
+    const chunks = [];
+    const verdict = (src.verdict ?? '').trim();
+    if (verdict)
+        chunks.push(`Verdict: ${verdict}.`);
+    const body = (src.summary && src.summary.length ? src.summary.join('. ') : (src.text ?? '')).trim();
+    const sentences = splitSentences(body).slice(0, maxSentences);
+    chunks.push(...sentences);
+    let out = tidy(chunks.join(' '));
+    if (out.length > MAX_CHARS) {
+        // Cut at the last sentence boundary that fits, else hard-trim.
+        const cut = out.slice(0, MAX_CHARS);
+        const lastStop = Math.max(cut.lastIndexOf('. '), cut.lastIndexOf('! '), cut.lastIndexOf('? '));
+        out = (lastStop > 80 ? cut.slice(0, lastStop + 1) : cut.trimEnd() + '…');
+    }
+    return out;
+}

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

@@ -0,0 +1,30 @@
+// A TTS engine that produces no audio — it records what would have been spoken and resolves at once.
+// Used by the headless tests and the latency harness so speech-out is deterministic and silent.
+export class FakeTts {
+    name = 'fake';
+    label = 'fake (silent, for tests)';
+    /** Every text passed to speak(), in order, for assertions. */
+    spoken = [];
+    /** How many times stop() interrupted a live utterance. */
+    stops = 0;
+    voices;
+    constructor(voices = ['Samantha', 'Alex', 'Daniel']) { this.voices = voices; }
+    async available() { return true; }
+    async listVoices() { return this.voices.slice(); }
+    speak(text, opts = {}) {
+        this.spoken.push(text);
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        // Fire first-audio on the next tick so latency timing sees a realistic (tiny) gap, then finish.
+        const t = setTimeout(() => { if (!stopped) {
+            opts.onFirstAudio?.();
+            resolve();
+        } }, 0);
+        return {
+            done,
+            stop: () => { if (stopped)
+                return; stopped = true; clearTimeout(t); this.stops++; resolve(); },
+        };
+    }
+}

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

@@ -0,0 +1,96 @@
+// 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.
+import { spawn } from 'node:child_process';
+import { execFile } from 'node:child_process';
+export const SAY_BIN = process.env.DEXTERM_SAY_BIN || 'say';
+export class SayTts {
+    name = 'say';
+    label = 'macOS say (built-in, no key)';
+    defaultVoice;
+    constructor(defaultVoice) { this.defaultVoice = defaultVoice; }
+    async available() {
+        if (process.platform !== 'darwin')
+            return false;
+        return new Promise((resolve) => {
+            try {
+                const child = execFile(SAY_BIN, ['-v', '?'], { timeout: 4000 }, (err) => resolve(!err || err.code !== 'ENOENT'));
+                child.on('error', () => resolve(false));
+            }
+            catch {
+                resolve(false);
+            }
+        });
+    }
+    /** Parse `say -v '?'`: each line is "Name            en_US    # sample text". */
+    async listVoices() {
+        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);
+                });
+            }
+            catch {
+                resolve([]);
+            }
+        });
+    }
+    speak(text, opts = {}) {
+        const voice = opts.voice ?? this.defaultVoice;
+        const rate = opts.rate ?? 190;
+        const args = [];
+        if (voice)
+            args.push('-v', voice);
+        args.push('-r', String(rate), text);
+        let child = null;
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        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.on('spawn', () => { if (!stopped)
+                opts.onFirstAudio?.(); });
+            child.on('error', () => { if (!stopped) {
+                stopped = true;
+                resolve();
+            } });
+            child.on('close', () => { if (!stopped) {
+                stopped = true;
+                resolve();
+            } });
+        }
+        catch {
+            // No `say` on this machine: resolve immediately so the caller degrades to text.
+            queueMicrotask(() => { if (!stopped) {
+                stopped = true;
+                resolve();
+            } });
+        }
+        return {
+            done,
+            stop: () => {
+                if (stopped)
+                    return;
+                stopped = true;
+                try {
+                    child?.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+                resolve();
+            },
+        };
+    }
+}

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

@@ -0,0 +1,3 @@
+// Shared types for @dexterm/voice (task-1282). Everything here is UI- and engine-agnostic so the
+// controller can be driven headlessly with fakes in tests and with the real macOS engines in the app.
+export {};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "dexterm-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "dexterm: terminal DEX screener with a local Claude CLI analyst",
+  "author": "The dexterm authors",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "bin": {
+    "dexterm": "./dist/packages/cli/bin/dexterm.mjs"
+  },
+  "exports": {
+    ".": "./dist/packages/cli/src/index.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build-dist.mjs",
+    "prepack": "node scripts/build-dist.mjs"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@dexterm/agents": "0.0.1",
+    "@dexterm/custom": "0.0.1",
+    "@dexterm/data": "0.0.1",
+    "@dexterm/mcp": "0.0.1",
+    "@dexterm/packs": "0.0.1",
+    "@dexterm/popup": "0.0.1",
+    "@dexterm/recorder": "0.0.1",
+    "@dexterm/tui": "0.0.1",
+    "@dexterm/voice": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dexterm-xyz/dexterm.git"
+  },
+  "homepage": "https://dexterm.xyz",
+  "bugs": {
+    "url": "https://github.com/dexterm-xyz/dexterm/issues"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.