moqi-tui 0.2.0

package/lib/types/tui/view.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Frame composition: header, transcript, palette popup, composer, footer.
+ *
+ * The renderer is pure — it turns a snapshot of the app into the exact lines
+ * the screen should show, and reports where the cursor belongs. Nothing here
+ * touches the terminal or the Harness.
+ * @module
+ */
+import { type FleetView } from './fleet.ts';
+import { Composer, type Message, type Palette, type BackgroundAgent, type Picker, type Segment, type SessionSummary } from './state.ts';
+import { type AtMenu } from './atfile.ts';
+import type { PanelView } from './panels.ts';
+/** Everything the renderer needs to draw one frame. */
+export interface Snapshot {
+    columns: number;
+    rows: number;
+    title: string;
+    host: string;
+    modelName: string;
+    messages: readonly Message[];
+    /** The turn streaming in, prose and calls in arrival order. */
+    streamingSegments: readonly Segment[];
+    streamingReasoning: string;
+    streaming: boolean;
+    spinner: string;
+    status: string;
+    statusIsError: boolean;
+    overlay: string;
+    showThinking: boolean;
+    composer: Composer;
+    palette: Palette;
+    picker: Picker;
+    /** Rows scrolled up from the bottom of the transcript. */
+    scrollBack: number;
+    /** Whether each tool call is listed instead of summarized on one line. */
+    expandTools: boolean;
+    /** Open sessions, in creation order; the bar is hidden when there is one. */
+    sessions: readonly SessionSummary[];
+    /** Live agents other than the foreground one, newest last. */
+    background: readonly BackgroundAgent[];
+    /** Whether the background agents are listed instead of counted on one line. */
+    expandBackground: boolean;
+    /** Seconds the current reply has been running, for the activity line. */
+    elapsedSeconds: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    haveUsage: boolean;
+    contextLimit: number;
+    /** Output tokens per second for the last settled turn; 0 when unknown. */
+    tps?: number;
+    /** Prompt tokens served from cache, and the total prompt tokens they came from. */
+    cacheReadTokens?: number;
+    confirming: boolean;
+    /** Set while confirming: the yes/no question, drawn in the composer. */
+    confirmText?: string;
+    /** Whether a `/find` search is open, so its counter outranks the scroll hint. */
+    searchActive?: boolean;
+    /**
+     * Prompts queued while the active session's reply streams, drawn dimmed
+     * under the streaming block. Optional so snapshot builders without a
+     * queue render exactly as before.
+     */
+    queued?: readonly string[];
+    /**
+     * The cross-device overview, when one is open. Optional so every existing
+     * snapshot builder renders exactly as before.
+     */
+    fleet?: FleetView;
+    /**
+     * Push-to-talk state, while the microphone is open or whisper is running.
+     * Optional so every existing snapshot builder renders exactly as before.
+     */
+    voice?: VoicePhase;
+    /**
+     * The `@` file-completion menu, while an `@` token is being typed.
+     * Optional so every existing snapshot builder renders exactly as before.
+     */
+    atMenu?: AtMenu;
+    /**
+     * A trust-surface panel (approval, question, plan review). While one is
+     * open it owns the keyboard and replaces the transcript.
+     */
+    panel?: PanelView;
+    /**
+     * Index of the transcript turn under selection, marked with a gold bar.
+     * Optional so every existing snapshot builder renders exactly as before.
+     */
+    selectedTurn?: number;
+    /** One line a plugin contributed, drawn above the composer. */
+    pluginLine?: string;
+    /** The composer's vim mode, when modal editing is on. */
+    vimMode?: 'insert' | 'normal';
+}
+/** What push-to-talk is doing, for the footer indicator. */
+export type VoicePhase = 'recording' | 'transcribing';
+/** Geometry derived from the terminal size and the current composer height. */
+export interface Layout {
+    contentWidth: number;
+    viewportRows: number;
+    paletteRows: number;
+    inputRows: number;
+    /** Rows the `@` file-completion popup shows, excluding its border. */
+    atRows: number;
+    /** One row when a plugin contributed a status line. */
+    pluginRows: number;
+    /** Rows the background-agent strip occupies, including any border. */
+    backgroundRows: number;
+    /** Rows the session tab bar occupies (0 or 1). */
+    sessionRows: number;
+    /** Cleared on a window too short to afford the header. */
+    showHeader: boolean;
+    /** Cleared on a window too short to afford the blank separator row. */
+    showGap: boolean;
+}
+/** Compute the geometry for a frame. */
+export declare function layout(snapshot: Snapshot): Layout;
+/** Strip the scheme and trailing slash from a base URL for the header. */
+export declare function hostLabel(base: string): string;
+/**
+ * How far back the transcript can scroll: anything beyond this is empty space
+ * above the first line, so the caller clamps to it rather than letting the view
+ * drift off the top.
+ */
+export declare function maxScrollBack(snapshot: Snapshot): number;
+/**
+ * Lines of the rendered body that contain `query`, case-insensitively.
+ *
+ * Matching runs over the printable text of each line — the styled form is full
+ * of SGR escapes the user never typed — and returns indexes into the same
+ * line array the viewport slices, so a hit can be scrolled to directly.
+ */
+export declare function findMatches(snapshot: Snapshot, query: string): number[];
+/** Build a full frame plus the cursor position for the screen to place. */
+export declare function render(snapshot: Snapshot): {
+    lines: string[];
+    cursor: {
+        row: number;
+        column: number;
+    } | undefined;
+};
+/**
+ * The help text shown by `/help`, rendered as markdown in the transcript pane.
+ *
+ * It is longer than a default 80x24 window, and the overlay shows the *tail*
+ * of it, so the list has a budget: every line added here pushes one off the
+ * top, and what falls off first is the session keys. A new section therefore
+ * comes with an equal number of lines folded together further down — which is
+ * why several entries below read as two keys on one row.
+ */
+/**
+ * The key reference.
+ *
+ * The strings live in the `i18n` catalog so one list covers both languages;
+ * this export is the English one, which the render tests assert against.
+ *
+ * The overlay shows the tail of it, so the list has a budget: a new section
+ * comes with an equal number of lines folded elsewhere. A line added to one
+ * language's copy in `i18n.ts` must be added to the other, or the two drift.
+ */
+export declare const HELP_TEXT: string;
+/** The key reference in the active language, for the `/help` overlay. */
+export declare function keyReference(): string;

package/lib/types/tui/vim.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Vim modal editing for the composer.
+ *
+ * Deliberately a small subset with exact semantics: motions (`h l 0 ^ $ w b`),
+ * edits (`x X dd d$ d0 dw`), insert entries (`i I a A o O`), and `u` for undo.
+ * Anything else is ignored rather than guessed at, so an unexpected key can
+ * never mangle a draft.
+ *
+ * The composer is the only thing mutated; the app decides when to route keys
+ * here, which keeps this testable as plain state.
+ * @module
+ */
+import type { Composer } from './state.ts';
+/** Which vim mode the composer is in. */
+export type VimMode = 'insert' | 'normal';
+/** How many edits `u` can walk back. */
+export declare const VIM_UNDO_LIMIT = 100;
+/** What the caller should do with a key routed to vim mode. */
+export type VimOutcome = 
+/** The key did something to the composer; repaint. */
+'handled'
+/** The key switched modes; repaint. */
+ | 'mode'
+/** The key belongs to ordinary editing; the caller should handle it. */
+ | 'pass';
+/**
+ * Modal vim state over one composer.
+ *
+ * Insert mode is the default: enabling vim must not change what typing does.
+ * An operator key (`d`) waits for its motion, and any key that is not a valid
+ * continuation cancels it — vim's own rule, and the safe one for a draft.
+ */
+export declare class Vim {
+    enabled: boolean;
+    mode: VimMode;
+    private operator;
+    private readonly undoStack;
+    /** Turn modal editing on or off; disabling returns to insert mode. */
+    setEnabled(enabled: boolean): void;
+    /** Whether the next key should be interpreted as a command. */
+    get normal(): boolean;
+    /** Remember the draft before an edit, so `u` can restore it. */
+    private snapshot;
+    /**
+     * Vim's `w`: the start of the next word.
+     *
+     * Readline's word motion (which ctrl+right uses) stops at the END of a word,
+     * so vim mode cannot borrow it without disagreeing with every vim user's
+     * muscle memory.
+     */
+    private wordForward;
+    /** Undo the last vim edit. */
+    undo(composer: Composer): void;
+    /**
+     * Handle one key.
+     *
+     * @param name - decoded key name (`h`, `esc`, `ctrl+j`, …).
+     * @param text - printable text the key carries, if any.
+     * @param composer - the buffer being edited.
+     */
+    handle(name: string, text: string, composer: Composer): VimOutcome;
+    /** `d` plus a motion, in terms of absolute buffers offsets. */
+    private deleteMotion;
+}

package/lib/types/tui-host-core.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The `tuiHost` seam's framework-free half: what a shortcut claim and the
+ * status slot mean, with no Cordis import.
+ *
+ * It lives apart from `./tui-host.ts` so `npm test` can exercise it without a
+ * Harness on disk — the suites run from a bare `npm ci`, where `@deepseek-ai/*`
+ * does not resolve at all.
+ * @module
+ */
+/** The name the service registers under (`ctx.tuiHost`). */
+export declare const TUI_HOST_NAME = "tuiHost";
+/** One plugin-registered key combination. */
+export interface TuiShortcut {
+    /** Canonical key name the app dispatches, e.g. `ctrl+shift+g`. */
+    combo: string;
+    /** One-line description, for refusal messages and future help. */
+    label: string;
+    /** Called on the keypress; a throw is reported as a status line. */
+    handler: () => void;
+}
+/**
+ * Combinations the app itself owns.
+ *
+ * Built-ins win outright: a plugin that tries to take `ctrl+c` would be able to
+ * swallow the quit confirmation, so the registration is refused rather than
+ * silently ordered.
+ */
+export declare const RESERVED_COMBOS: ReadonlySet<string>;
+/** Why a registration was refused, or `undefined` when it was accepted. */
+export declare function shortcutProblem(combo: string, taken: ReadonlySet<string>): string | undefined;
+/** Shortcut claims, without any Cordis dependency — the testable half. */
+export declare class ShortcutRegistry {
+    private readonly shortcuts;
+    /**
+     * Claim a key combination.
+     *
+     * @returns a disposer that releases it, or `undefined` when the combination
+     *   is reserved, malformed, or already registered.
+     */
+    register(shortcut: TuiShortcut): (() => void) | undefined;
+    /** Every registered combination, in registration order. */
+    registered(): readonly TuiShortcut[];
+    /** The label for one combination, when it is claimed. */
+    labelOf(combo: string): string | undefined;
+    /**
+     * Run the handler for one key, if a plugin owns it.
+     *
+     * @returns whether the key was claimed, so the app can stop before it treats
+     *   the key as text.
+     */
+    dispatch(combo: string): boolean;
+}
+/** The one-line status slot, also independent of Cordis. */
+export declare class StatusLine {
+    private line;
+    /**
+     * Contribute the line. The slot is replaced, not stacked: a terminal has one
+     * line to give, and last registration wins — the same rule a status bar has.
+     */
+    set(text: string | undefined): () => void;
+    get(): string | undefined;
+}

package/lib/types/tui-host.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The `tuiHost` service: the seam other plugins extend this terminal with.
+ *
+ * A plugin can own a key combination (Ctrl/Alt only, built-ins always win) and
+ * can contribute one line above the composer. Everything is disposer-scoped,
+ * so an unloaded plugin leaves nothing behind — and nothing here can take the
+ * keyboard away from the app's own bindings.
+ *
+ * This module is the Cordis-bound half; the rules it delegates to live in
+ * `./tui-host-core.ts` and are re-exported here, so `moqi-tui/tui-host`
+ * remains the one import a plugin needs.
+ * @module moqi-tui/tui-host
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import type { TuiShortcut } from './tui-host-core.ts';
+export * from './tui-host-core.ts';
+/**
+ * The extension seam (`ctx.tuiHost`). Plugins register shortcuts and a status
+ * line; the app dispatches keys and draws the line, and owns nothing else.
+ */
+export declare class TuiHost extends Service {
+    private readonly shortcuts;
+    private readonly line;
+    constructor(ctx: Context);
+    /** Claim a key combination; see {@link ShortcutRegistry.register}. */
+    registerShortcut(shortcut: TuiShortcut): (() => void) | undefined;
+    /** Every registered combination, for help output and tests. */
+    registered(): readonly TuiShortcut[];
+    /** Run a key's plugin handler, if one is registered. */
+    dispatch(combo: string): boolean;
+    /** Contribute the one-line status above the composer. */
+    setStatusLine(text: string | undefined): () => void;
+    /** The status line a plugin contributed, if any. */
+    statusLine(): string | undefined;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiHost: TuiHost;
+    }
+}
+export default TuiHost;

package/lib/types/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The package version, read from the `package.json` that ships beside the
+ * emitted code, so `--version` and `/about` always agree with the manifest
+ * without a second copy of the number to keep in sync.
+ * @module moqi-tui/version
+ */
+/** This package's version, as `--version` prints it. */
+export declare const VERSION: string;

package/lib/types/voice.d.ts

@@ -0,0 +1,227 @@
+/**
+ * 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 type { ChildProcess } from 'node:child_process';
+/** How long a transcription may run before it is killed, in milliseconds. */
+export declare const TRANSCRIBE_TIMEOUT_MS = 120000;
+/** How long a recorder gets to flush its WAV header after a stop, in milliseconds. */
+export declare const RECORDER_FLUSH_MS = 2000;
+/**
+ * A recorder this app knows how to drive.
+ *
+ * Every entry must produce 16 kHz mono signed 16-bit PCM, because that is the
+ * only format whisper.cpp reads without resampling it itself.
+ */
+export interface RecorderSpec {
+    /** Executable to look for on `PATH`. */
+    command: string;
+    /** Package a person would install to get it, for the missing-dependency line. */
+    packageName: string;
+    /** Arguments that write the capture to `target`. */
+    args: (target: string) => string[];
+}
+/**
+ * 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 declare const RECORDERS: readonly RecorderSpec[];
+/**
+ * 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 declare const WHISPER_COMMANDS: readonly string[];
+/** Directories searched for a model when none was configured. */
+export declare const MODEL_DIRECTORIES: readonly string[];
+/**
+ * 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 declare const MODEL_FILES: readonly string[];
+/** What the user configured, from flags and the environment. */
+export interface VoiceOptions {
+    /** `--voice-model`, an explicit path to a ggml weights file. */
+    model?: string;
+    /** `--voice-bin`, an explicit path to or name of the whisper executable. */
+    binary?: string;
+    /** `MOQI_WHISPER_MODEL`, the same thing from the environment. */
+    envModel?: string;
+    /** `MOQI_WHISPER_BIN`, the same thing from the environment. */
+    envBinary?: string;
+    /** `MOQI_WHISPER_LANG`; absent lets whisper use its own default. */
+    language?: string;
+}
+/** The filesystem questions {@link resolveVoiceSetup} needs answered. */
+export interface VoiceProbe {
+    /** Whether this command resolves to something executable on `PATH`. */
+    hasCommand: (command: string) => boolean;
+    /** Whether this path exists and can be read. */
+    exists: (path: string) => boolean;
+    /** Home directory the `~` in {@link MODEL_DIRECTORIES} expands to. */
+    home: string;
+}
+/** The one thing that stopped voice input from being usable. */
+export type VoiceGap = 
+/** Nothing on the system can capture audio. */
+{
+    kind: 'recorder';
+}
+/** No whisper.cpp front end could be found. */
+ | {
+    kind: 'binary';
+}
+/** A binary was named explicitly and is not there. */
+ | {
+    kind: 'binary-missing';
+    path: string;
+    source: 'flag' | 'env';
+}
+/** A model was named explicitly and is not there. */
+ | {
+    kind: 'model-missing';
+    path: string;
+    source: 'flag' | 'env';
+}
+/** Nothing was named and the default search came up empty. */
+ | {
+    kind: 'model-unfound';
+};
+/** Everything needed to record and transcribe, once every probe has passed. */
+export interface VoiceSetup {
+    recorder: RecorderSpec;
+    /** Command or absolute path to spawn for transcription. */
+    binary: string;
+    /** Absolute path to the ggml weights. */
+    model: string;
+    /** Language code to force, when one was configured. */
+    language: string | undefined;
+}
+/** Either a usable setup or the first thing missing from it. */
+export type VoiceResolution = {
+    ok: true;
+    setup: VoiceSetup;
+} | {
+    ok: false;
+    gap: VoiceGap;
+};
+/**
+ * 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 declare function resolveVoiceSetup(options: VoiceOptions, probe: VoiceProbe): VoiceResolution;
+/** Resolve the weights from the flag, the environment, or the default search. */
+export declare function resolveModel(options: VoiceOptions, probe: VoiceProbe): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    gap: VoiceGap;
+};
+/**
+ * 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 declare function voiceGapMessage(gap: VoiceGap): string;
+/**
+ * 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 declare function whisperArgs(setup: VoiceSetup, wavPath: string): string[];
+/**
+ * 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 declare function parseWhisperText(stdout: string): string;
+/**
+ * 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 declare function insertionFor(value: string, cursor: number, transcript: string): string;
+/** Whether a command resolves to an executable somewhere on `PATH`. */
+export declare function hasCommand(command: string, env?: NodeJS.ProcessEnv): boolean;
+/** Whether a path exists and is readable. */
+export declare function fileExists(path: string): boolean;
+/** The probe that answers against the real filesystem. */
+export declare function systemProbe(env?: NodeJS.ProcessEnv): VoiceProbe;
+/** Read the environment half of the configuration. */
+export declare function voiceOptionsFromEnv(env?: NodeJS.ProcessEnv): VoiceOptions;
+/** A capture in progress: the recorder process and the file it is filling. */
+export interface Recording {
+    child: ChildProcess;
+    wavPath: string;
+}
+/**
+ * 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 declare function startRecording(setup: VoiceSetup, wavPath: string): Recording;
+/**
+ * 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 declare function stopRecording(recording: Recording): Promise<void>;
+/**
+ * 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 declare function transcribe(setup: VoiceSetup, wavPath: string): Promise<string>;
+/** A one-line reason a transcription run failed. */
+export declare function transcribeError(error: unknown, stderr: string): string;

package/lib/version.js

@@ -0,0 +1,32 @@
+/**
+ * The package version, read from the `package.json` that ships beside the
+ * emitted code, so `--version` and `/about` always agree with the manifest
+ * without a second copy of the number to keep in sync.
+ * @module moqi-tui/version
+ */
+import { readFileSync } from 'node:fs';
+/** Read the version out of `package.json`, with a safe fallback. */
+function resolve() {
+    try {
+        // In `src/` the manifest is one level up; in `lib/` it is beside the
+        // emitted file, because `files` ships it with the bundle.
+        const here = new URL('.', import.meta.url);
+        for (const candidate of ['../package.json', 'package.json']) {
+            try {
+                const manifest = JSON.parse(readFileSync(new URL(candidate, here), 'utf8'));
+                if (typeof manifest.version === 'string' && manifest.version !== '') {
+                    return manifest.version;
+                }
+            }
+            catch {
+                // Try the next candidate.
+            }
+        }
+    }
+    catch {
+        // Fall through to the placeholder.
+    }
+    return '0.0.0-unknown';
+}
+/** This package's version, as `--version` prints it. */
+export const VERSION = resolve();