moqi-tui 0.2.0

package/lib/voice.js

@@ -0,0 +1,405 @@
+/**
+ * Push-to-talk dictation, transcribed on this machine and nowhere else.
+ *
+ * The whole point of this feature is that a prompt spoken into the composer
+ * never becomes somebody else's training data, so there is no cloud endpoint
+ * here and no API key to lose: audio is captured by whatever recorder the
+ * system already has and handed to a local `whisper.cpp` binary. That also
+ * means the app cannot depend on any of it. A machine with no microphone
+ * stack, no whisper build, or no model is the normal case, not the error
+ * case — so every probe below reports what is missing in one line a person
+ * can act on, and the app is otherwise untouched.
+ *
+ * Nothing in this module is a runtime dependency of the bundle: the recorder
+ * and the transcriber are external processes discovered on `PATH`, and the
+ * decision logic is pure so it can be tested without either of them.
+ * @module
+ */
+import { execFile, spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, isAbsolute, join } from 'node:path';
+/** How long a transcription may run before it is killed, in milliseconds. */
+export const TRANSCRIBE_TIMEOUT_MS = 120_000;
+/** How long a recorder gets to flush its WAV header after a stop, in milliseconds. */
+export const RECORDER_FLUSH_MS = 2000;
+/**
+ * Recorders in the order they are preferred.
+ *
+ * `arecord` comes first because on Linux it is part of alsa-utils, which is
+ * already installed anywhere sound works at all, and it talks to ALSA
+ * directly. `rec` and `sox` are the same program wearing two names; `rec`
+ * defaults to the system input device while `sox` has to be told `-d`, which
+ * is why they cannot share one entry.
+ */
+export const RECORDERS = [
+    {
+        command: 'arecord',
+        packageName: 'alsa-utils',
+        args: (target) => ['-q', '-f', 'S16_LE', '-r', '16000', '-c', '1', '-t', 'wav', target],
+    },
+    {
+        command: 'rec',
+        packageName: 'sox',
+        args: (target) => ['-q', '-r', '16000', '-c', '1', '-b', '16', target],
+    },
+    {
+        command: 'sox',
+        packageName: 'sox',
+        args: (target) => ['-q', '-d', '-r', '16000', '-c', '1', '-b', '16', target],
+    },
+];
+/**
+ * Names whisper.cpp has shipped its command-line front end under.
+ *
+ * `whisper-cli` is what upstream builds today and `whisper-cpp` is what most
+ * distributions rename it to. Plain `main` is last on purpose: it is the
+ * historic name of the build output and still what an in-tree build produces,
+ * but it is far too generic to trust ahead of anything else on `PATH`.
+ */
+export const WHISPER_COMMANDS = [
+    'whisper-cli',
+    'whisper-cpp',
+    'whisper.cpp',
+    'whisper',
+    'main',
+];
+/** Directories searched for a model when none was configured. */
+export const MODEL_DIRECTORIES = [
+    '~/.cache/whisper',
+    '~/.local/share/whisper',
+    '/usr/share/whisper.cpp',
+    '/usr/local/share/whisper.cpp',
+];
+/**
+ * Model files looked for inside each directory, best first.
+ *
+ * Dictation is a handful of seconds of one speaker close to the microphone,
+ * which `base` already handles, so the ordering trades accuracy for the
+ * latency a person is standing there waiting through. English-only weights
+ * win their size class because they are measurably better at it.
+ */
+export const MODEL_FILES = [
+    'ggml-base.en.bin',
+    'ggml-base.bin',
+    'ggml-small.en.bin',
+    'ggml-small.bin',
+    'ggml-medium.en.bin',
+    'ggml-medium.bin',
+    'ggml-tiny.en.bin',
+    'ggml-tiny.bin',
+];
+/** Expand a leading `~` against the home directory the probe reports. */
+function expandHome(path, home) {
+    if (path === '~')
+        return home;
+    if (path.startsWith('~/'))
+        return join(home, path.slice(2));
+    return path;
+}
+/**
+ * Decide whether voice input can run, and with what.
+ *
+ * Pure apart from the injected probe, because the interesting part is the
+ * order the three dependencies are reported in and that is worth testing
+ * without a microphone: the recorder comes first because it is the one a
+ * person is most likely to already have, then the binary, then the weights —
+ * which is also the order in which they get harder to install.
+ */
+export function resolveVoiceSetup(options, probe) {
+    const recorder = RECORDERS.find((candidate) => probe.hasCommand(candidate.command));
+    if (recorder === undefined)
+        return { ok: false, gap: { kind: 'recorder' } };
+    const named = firstConfigured(options.binary, options.envBinary);
+    let binary;
+    if (named !== undefined) {
+        // A path was spelled out, so a miss is a mistake worth naming rather than
+        // something to quietly paper over with a `PATH` lookup.
+        const path = expandHome(named.value, probe.home);
+        const present = isAbsolute(path) || path.includes('/') ? probe.exists(path) : probe.hasCommand(path);
+        if (!present) {
+            return { ok: false, gap: { kind: 'binary-missing', path, source: named.source } };
+        }
+        binary = path;
+    }
+    else {
+        const found = WHISPER_COMMANDS.find((candidate) => probe.hasCommand(candidate));
+        if (found === undefined)
+            return { ok: false, gap: { kind: 'binary' } };
+        binary = found;
+    }
+    const model = resolveModel(options, probe);
+    if (!model.ok)
+        return model;
+    return {
+        ok: true,
+        setup: {
+            recorder,
+            binary,
+            model: model.path,
+            language: options.language === undefined || options.language.trim() === ''
+                ? undefined
+                : options.language.trim(),
+        },
+    };
+}
+/** The configured value that wins, with where it came from. */
+function firstConfigured(flag, env) {
+    // The flag beats the environment: it is the more deliberate of the two, and
+    // it is the one a person can change without editing a shell profile.
+    if (flag !== undefined && flag.trim() !== '')
+        return { value: flag.trim(), source: 'flag' };
+    if (env !== undefined && env.trim() !== '')
+        return { value: env.trim(), source: 'env' };
+    return undefined;
+}
+/** Resolve the weights from the flag, the environment, or the default search. */
+export function resolveModel(options, probe) {
+    const named = firstConfigured(options.model, options.envModel);
+    if (named !== undefined) {
+        const path = expandHome(named.value, probe.home);
+        if (!probe.exists(path)) {
+            return { ok: false, gap: { kind: 'model-missing', path, source: named.source } };
+        }
+        return { ok: true, path };
+    }
+    // Directory-major: a machine with both a distribution package and a hand
+    // downloaded model should use the one it downloaded, which is the one in
+    // the home directory, even when the packaged one is the larger weights.
+    for (const directory of MODEL_DIRECTORIES) {
+        const base = expandHome(directory, probe.home);
+        for (const file of MODEL_FILES) {
+            const candidate = join(base, file);
+            if (probe.exists(candidate))
+                return { ok: true, path: candidate };
+        }
+    }
+    return { ok: false, gap: { kind: 'model-unfound' } };
+}
+/**
+ * One line saying what is missing and how to get it.
+ *
+ * Deliberately a single sentence with a concrete next step in it: this lands
+ * in the footer, which is one line wide, and an error there that only says
+ * "voice unavailable" costs the reader a search through the README.
+ */
+export function voiceGapMessage(gap) {
+    switch (gap.kind) {
+        case 'recorder':
+            return 'no recorder — run: npm run setup-voice, or install alsa-utils or sox';
+        case 'binary':
+            return 'no whisper binary — run: npm run setup-voice, or set MOQI_WHISPER_BIN';
+        case 'binary-missing':
+            return `no whisper binary at ${gap.path} — fix ${sourceLabel(gap.source, 'bin')}`;
+        case 'model-missing':
+            return `no model at ${gap.path} — fix ${sourceLabel(gap.source, 'model')}`;
+        case 'model-unfound':
+            return 'no whisper model — run: npm run setup-voice, or pass --voice-model';
+    }
+}
+/** Name the knob that produced a bad path, so the fix is unambiguous. */
+function sourceLabel(source, which) {
+    if (source === 'flag')
+        return which === 'bin' ? '--voice-bin' : '--voice-model';
+    return which === 'bin' ? 'MOQI_WHISPER_BIN' : 'MOQI_WHISPER_MODEL';
+}
+/**
+ * Arguments for one transcription run.
+ *
+ * `-np` suppresses whisper.cpp's banner and progress so the only thing left
+ * on stdout is the transcript; the segment timestamps are deliberately kept,
+ * because they are the one marker that reliably separates a result line from
+ * whatever a given build still prints alongside it.
+ */
+export function whisperArgs(setup, wavPath) {
+    const args = ['-m', setup.model, '-f', wavPath, '-np'];
+    if (setup.language !== undefined)
+        args.push('-l', setup.language);
+    return args;
+}
+/** Segment markers whisper emits for audio that carries no speech. */
+const NON_SPEECH = /^[[(](?:blank_audio|silence|music|sound|noise|inaudible)[\])]$/i;
+/**
+ * Turn whisper's stdout into the text a person meant to say.
+ *
+ * whisper.cpp prints one line per segment, `[00:00:00.000 --> 00:00:02.000]`
+ * and then the words. When any such line is present those lines are the whole
+ * answer and everything else is noise from a build that ignored `-np`; when
+ * none is, the build was asked for plain output and the lines are the text —
+ * minus the log chatter, which is recognisable by its `prefix:` shape.
+ */
+export function parseWhisperText(stdout) {
+    const timestamped = [];
+    const plain = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (line === '')
+            continue;
+        const segment = /^\[\d{2}:\d{2}:\d{2}\.\d{3}\s*-->\s*\d{2}:\d{2}:\d{2}\.\d{3}\]\s*(.*)$/.exec(line);
+        if (segment !== null) {
+            const text = (segment[1] ?? '').trim();
+            if (text !== '' && !NON_SPEECH.test(text))
+                timestamped.push(text);
+            continue;
+        }
+        // A log line from whisper or its loader, e.g. `whisper_init_from_file:` or
+        // `main: processing ...`. Real speech can contain a colon, but not one
+        // sitting directly after a leading run of identifier characters.
+        if (/^[a-z_][a-z0-9_.]*\s*:/i.test(line))
+            continue;
+        if (line.startsWith('[') || line.startsWith('<'))
+            continue;
+        if (!NON_SPEECH.test(line))
+            plain.push(line);
+    }
+    const parts = timestamped.length > 0 ? timestamped : plain;
+    return parts.join(' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * The text to splice into the composer at `cursor`.
+ *
+ * Dictation is usually appended to something already typed, and two utterances
+ * running together into one word is the kind of small wrongness that makes a
+ * feature feel broken, so a separator is added when the character before the
+ * cursor is not already one.
+ */
+export function insertionFor(value, cursor, transcript) {
+    const text = transcript.trim();
+    if (text === '')
+        return '';
+    const before = value.slice(0, Math.max(cursor, 0));
+    if (before === '' || /\s$/.test(before))
+        return text;
+    return ` ${text}`;
+}
+/** Whether a command resolves to an executable somewhere on `PATH`. */
+export function hasCommand(command, env = process.env) {
+    if (command.includes('/'))
+        return fileExists(command);
+    const path = env['PATH'] ?? '';
+    for (const directory of path.split(delimiter)) {
+        if (directory === '')
+            continue;
+        try {
+            accessSync(join(directory, command), constants.X_OK);
+            return true;
+        }
+        catch {
+            // Not here, or not executable; keep walking the rest of PATH.
+        }
+    }
+    return false;
+}
+/** Whether a path exists and is readable. */
+export function fileExists(path) {
+    try {
+        accessSync(path, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The probe that answers against the real filesystem. */
+export function systemProbe(env = process.env) {
+    return {
+        hasCommand: (command) => hasCommand(command, env),
+        exists: fileExists,
+        home: homedir(),
+    };
+}
+/** Read the environment half of the configuration. */
+export function voiceOptionsFromEnv(env = process.env) {
+    return {
+        envModel: env['MOQI_WHISPER_MODEL'],
+        envBinary: env['MOQI_WHISPER_BIN'],
+        language: env['MOQI_WHISPER_LANG'],
+    };
+}
+/**
+ * Start the recorder.
+ *
+ * stdio is fully detached from this process's own: the app owns the alternate
+ * screen buffer, and a recorder writing a warning onto it would tear the frame
+ * apart with no way to repaint the damage.
+ */
+export function startRecording(setup, wavPath) {
+    const child = spawn(setup.recorder.command, setup.recorder.args(wavPath), {
+        stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return { child, wavPath };
+}
+/**
+ * Stop the recorder and wait for the file to be finished.
+ *
+ * SIGINT rather than SIGTERM because both recorders treat it as "wrap up":
+ * they close the WAV and go back and write the real length into the header.
+ * Killed harder, the file is left claiming a length of zero and whisper reads
+ * nothing out of it. The hard kill is only the fallback for a recorder that
+ * ignores the polite request.
+ */
+export function stopRecording(recording) {
+    return new Promise((resolve) => {
+        const child = recording.child;
+        if (child.exitCode !== null || child.signalCode !== null) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // Already gone; the exit handler below has the resolve either way.
+            }
+            resolve();
+        }, RECORDER_FLUSH_MS);
+        timer.unref?.();
+        child.once('exit', () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        try {
+            child.kill('SIGINT');
+        }
+        catch {
+            clearTimeout(timer);
+            resolve();
+        }
+    });
+}
+/**
+ * Transcribe one WAV file and return the text.
+ *
+ * Rejects with a one-line message rather than an exec error, because the
+ * caller puts whatever comes back straight into a status line that is one
+ * line wide.
+ */
+export function transcribe(setup, wavPath) {
+    return new Promise((resolve, reject) => {
+        execFile(setup.binary, whisperArgs(setup, wavPath), { timeout: TRANSCRIBE_TIMEOUT_MS, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error !== null) {
+                reject(new Error(transcribeError(error, String(stderr))));
+                return;
+            }
+            resolve(parseWhisperText(String(stdout)));
+        });
+    });
+}
+/** A one-line reason a transcription run failed. */
+export function transcribeError(error, stderr) {
+    const code = error?.code;
+    if (code === 'ENOENT')
+        return 'whisper binary vanished mid-run';
+    if (code === 'ETIMEDOUT')
+        return 'whisper timed out';
+    // whisper says why on stderr; node's own message is the whole command line
+    // echoed back, which is useless in a footer.
+    const detail = stderr
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line !== '' && /error|failed|cannot|unable/i.test(line));
+    if (detail !== undefined)
+        return `whisper: ${detail}`;
+    return error instanceof Error ? error.message.split('\n')[0] ?? 'whisper failed' : 'whisper failed';
+}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "moqi-tui",
+  "version": "0.2.0",
+  "description": "Moqi — the unspoken understanding between you and your harness. A terminal app for DeepSeek Harness: bordered composer, live token counter, slash palette, markdown transcript with syntax-highlighted code.",
+  "type": "module",
+  "license": "MIT",
+  "author": "JWE24-code <292770342+JWE24-code@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JWE24-code/moqi.git"
+  },
+  "bin": {
+    "moqi": "bin/moqi.mjs"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./tui-host": {
+      "types": "./lib/types/tui-host.d.ts",
+      "default": "./lib/tui-host.js"
+    }
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/types/**/*.d.ts",
+    "bin/*.mjs",
+    "scripts/install-profile.mjs",
+    "scripts/harness-root.mjs",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "link-types": "node scripts/link-harness-types.mjs",
+    "install-profile": "node scripts/install-profile.mjs",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test && npm run test:package",
+    "test": "node tests/harness-root-smoke.mjs && node --experimental-strip-types tests/offline-imports-smoke.ts && node --experimental-strip-types tests/keys-smoke.ts && node --experimental-strip-types tests/render-smoke.ts && node --experimental-strip-types tests/atfile-smoke.ts && node --experimental-strip-types tests/panels-smoke.ts && node --experimental-strip-types tests/selection-smoke.ts && node --experimental-strip-types tests/rewind-smoke.ts && node --experimental-strip-types tests/jobs-smoke.ts && node --experimental-strip-types tests/cross-find-smoke.ts && node --experimental-strip-types tests/tui-host-smoke.ts && node --experimental-strip-types tests/mcp-smoke.ts && node --experimental-strip-types tests/i18n-smoke.ts && node --experimental-strip-types tests/render-cache-smoke.ts && node --experimental-strip-types tests/vim-smoke.ts && node --experimental-strip-types tests/queue-smoke.ts && node --experimental-strip-types tests/persist.ts && node --experimental-strip-types tests/stream-smoke.ts && node --experimental-strip-types tests/tool-detail-smoke.ts && node --experimental-strip-types tests/export-smoke.ts && node --experimental-strip-types tests/sessions-store-smoke.ts && node --experimental-strip-types tests/rename-smoke.ts && node --experimental-strip-types tests/fleet-smoke.ts && node --experimental-strip-types tests/theme-smoke.ts && node --experimental-strip-types tests/plugins-smoke.ts && node --experimental-strip-types tests/voice-smoke.ts && node --experimental-strip-types tests/patch-smoke.ts && node --experimental-strip-types tests/pty.ts",
+    "preview": "node --experimental-strip-types tests/preview.ts",
+    "test:pty": "node --experimental-strip-types tests/pty.ts",
+    "setup-voice": "node scripts/install-voice.mjs",
+    "bench": "node --experimental-strip-types scripts/bench-render.ts",
+    "test:live": "MOQI_LIVE=1 node --experimental-strip-types tests/live-pty.ts",
+    "test:package": "node scripts/verify-package.mjs"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-agent": "*",
+    "@deepseek-ai/dsh-agent-default-model": "*",
+    "@deepseek-ai/dsh-attachment": "*",
+    "@deepseek-ai/dsh-brand": "*",
+    "@deepseek-ai/dsh-cmdline": "*",
+    "@deepseek-ai/dsh-llm": "*",
+    "@deepseek-ai/dsh-session": "*",
+    "@deepseek-ai/dsh-session-query": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent-default-model": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-attachment": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-brand": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-cmdline": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-query": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "moqi",
+    "deepseek",
+    "dsh",
+    "tui",
+    "terminal",
+    "agent"
+  ]
+}

package/scripts/harness-root.mjs

@@ -0,0 +1,88 @@
+/**
+ * Find the installed Harness and make its `@deepseek-ai` packages resolvable.
+ *
+ * A plugin resolves `@deepseek-ai/*` from the dsh installation anchor at
+ * runtime. That works when the plugin lives inside the profile's own
+ * `node_modules` — but this app is linked from wherever it was installed, so
+ * Node resolves imports from the *package's* directory and never sees the
+ * anchor. Linking the harness packages into the package's own `node_modules`
+ * is what closes that gap, and it keeps exactly one copy of each package (the
+ * harness's), which matters: a second `@deepseek-ai/cordis` would be a
+ * different `Service` class.
+ * @module
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readdirSync, rmSync, realpathSync, symlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * The installed dsh package root.
+ *
+ * `DSH_INSTALL_ROOT` wins (a test or a non-standard install), else the `dsh`
+ * binary on PATH is resolved and walked up to the directory owning a
+ * `package.json`.
+ *
+ * @returns the root, or `undefined` with no throw — callers decide whether
+ *   that is fatal (the installer warns) or fatal-with-help (the type linker).
+ */
+export function findDshRoot() {
+  const fromEnvironment = process.env['DSH_INSTALL_ROOT']
+  if (fromEnvironment !== undefined && existsSync(join(fromEnvironment, 'package.json'))) {
+    return fromEnvironment
+  }
+  let binary = ''
+  try {
+    binary = execFileSync('sh', ['-c', 'command -v dsh'], { encoding: 'utf8' }).trim()
+  } catch {
+    return undefined
+  }
+  if (binary === '') return undefined
+  let current = dirname(realpathSync(binary))
+  for (let depth = 0; depth < 6; depth += 1) {
+    if (existsSync(join(current, 'package.json'))) return current
+    current = dirname(current)
+  }
+  return undefined
+}
+
+/** Where the harness's own packages live inside an installation. */
+export function harnessPackageDir(dshRoot) {
+  return join(dshRoot, 'node_modules', '@deepseek-ai')
+}
+
+/**
+ * Make every harness `@deepseek-ai` package resolvable from `packageRoot`.
+ *
+ * Existing entries are replaced, so re-running is idempotent. Failures are
+ * collected rather than thrown: a read-only global install should still leave
+ * a working profile behind if the harness packages were resolvable some other
+ * way, and the caller reports what it could not link.
+ *
+ * @returns the names linked and the names that failed.
+ */
+export function linkHarnessPackages(packageRoot, dshRoot) {
+  const source = harnessPackageDir(dshRoot)
+  const linked = []
+  const failed = []
+  if (!existsSync(source)) return { linked, failed }
+
+  const target = join(packageRoot, 'node_modules', '@deepseek-ai')
+  try {
+    mkdirSync(target, { recursive: true })
+  } catch {
+    return { linked, failed }
+  }
+
+  for (const name of readdirSync(source)) {
+    const to = join(target, name)
+    try {
+      rmSync(to, { recursive: true, force: true })
+      symlinkSync(join(source, name), to, 'dir')
+      linked.push(name)
+    } catch {
+      failed.push(name)
+    }
+  }
+  return { linked, failed }
+}