moqi-tui 0.2.0

package/lib/tui/vim.js

@@ -0,0 +1,222 @@
+/**
+ * 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
+ */
+/** How many edits `u` can walk back. */
+export const VIM_UNDO_LIMIT = 100;
+/**
+ * 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 class Vim {
+    enabled = false;
+    mode = 'insert';
+    operator;
+    undoStack = [];
+    /** Turn modal editing on or off; disabling returns to insert mode. */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+        this.mode = 'insert';
+        this.operator = undefined;
+    }
+    /** Whether the next key should be interpreted as a command. */
+    get normal() {
+        return this.enabled && this.mode === 'normal';
+    }
+    /** Remember the draft before an edit, so `u` can restore it. */
+    snapshot(composer) {
+        this.undoStack.push({ text: composer.value(), cursor: composer.position() });
+        if (this.undoStack.length > VIM_UNDO_LIMIT)
+            this.undoStack.shift();
+    }
+    /**
+     * 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.
+     */
+    wordForward(composer) {
+        const value = composer.value();
+        composer.wordRight();
+        while (composer.position() < value.length && /\s/.test(value[composer.position()] ?? '')) {
+            composer.right();
+        }
+    }
+    /** Undo the last vim edit. */
+    undo(composer) {
+        const previous = this.undoStack.pop();
+        if (previous === undefined)
+            return;
+        composer.adopt(previous.text, previous.cursor);
+    }
+    /**
+     * 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, text, composer) {
+        if (!this.enabled)
+            return 'pass';
+        if (this.mode === 'insert') {
+            // Escape is the one key insert mode claims; everything else types.
+            if (name === 'esc') {
+                this.mode = 'normal';
+                this.operator = undefined;
+                // Leaving insert parks the cursor where vim would: one column left.
+                composer.left();
+                return 'mode';
+            }
+            return 'pass';
+        }
+        // Normal mode: an operator waits for its motion.
+        if (this.operator !== undefined) {
+            const pending = this.operator;
+            this.operator = undefined;
+            switch (pending) {
+                case 'd':
+                    return this.deleteMotion(name, composer);
+                default:
+                    return 'handled';
+            }
+        }
+        switch (name) {
+            case 'esc':
+                return 'handled';
+            case 'h':
+            case 'left':
+                composer.left();
+                return 'handled';
+            case 'l':
+            case 'right':
+                composer.right();
+                return 'handled';
+            case '0':
+            case 'home':
+                composer.home();
+                return 'handled';
+            case '^': {
+                composer.home();
+                // First non-blank of the line.
+                const value = composer.value();
+                let at = composer.position();
+                while (at < value.length && (value[at] === ' ' || value[at] === '\t')) {
+                    composer.right();
+                    at += 1;
+                }
+                return 'handled';
+            }
+            case '$':
+            case 'end':
+                composer.end();
+                return 'handled';
+            case 'w':
+                this.wordForward(composer);
+                return 'handled';
+            case 'b':
+                composer.wordLeft();
+                return 'handled';
+            case 'i':
+                this.mode = 'insert';
+                return 'mode';
+            case 'I': {
+                composer.home();
+                this.mode = 'insert';
+                return 'mode';
+            }
+            case 'a': {
+                composer.right();
+                this.mode = 'insert';
+                return 'mode';
+            }
+            case 'A': {
+                composer.end();
+                this.mode = 'insert';
+                return 'mode';
+            }
+            case 'o': {
+                this.snapshot(composer);
+                composer.end();
+                composer.insert('\n');
+                this.mode = 'insert';
+                return 'mode';
+            }
+            case 'O': {
+                this.snapshot(composer);
+                composer.home();
+                composer.insert('\n');
+                composer.left();
+                this.mode = 'insert';
+                return 'mode';
+            }
+            case 'x': {
+                this.snapshot(composer);
+                composer.deleteForward();
+                return 'handled';
+            }
+            case 'X': {
+                this.snapshot(composer);
+                composer.backspace();
+                return 'handled';
+            }
+            case 'u':
+                this.undo(composer);
+                return 'handled';
+            case 'd':
+                this.operator = 'd';
+                return 'handled';
+            default:
+                // Unbound keys are swallowed, as in vim: a stray `j` must not type.
+                return text === '' ? 'handled' : 'handled';
+        }
+    }
+    /** `d` plus a motion, in terms of absolute buffers offsets. */
+    deleteMotion(motion, composer) {
+        switch (motion) {
+            case 'd': {
+                this.snapshot(composer);
+                const start = composer.lineStartIndex();
+                const end = composer.lineEndIndex();
+                // A line delete takes its newline with it, as vim's `dd` does; the
+                // last line has none, so it simply shortens.
+                const trailing = composer.value()[end] === '\n' ? 1 : 0;
+                composer.deleteRange(start, end + trailing);
+                return 'handled';
+            }
+            case '$': {
+                this.snapshot(composer);
+                composer.deleteRange(composer.position(), composer.lineEndIndex());
+                return 'handled';
+            }
+            case '0':
+            case '^': {
+                this.snapshot(composer);
+                composer.deleteRange(composer.lineStartIndex(), composer.position());
+                return 'handled';
+            }
+            case 'w': {
+                this.snapshot(composer);
+                const before = composer.position();
+                this.wordForward(composer);
+                composer.deleteRange(before, composer.position());
+                return 'handled';
+            }
+            default:
+                // `d` followed by something unbound is cancelled, not guessed at.
+                return 'handled';
+        }
+    }
+}

package/lib/tui-host-core.js

@@ -0,0 +1,141 @@
+/**
+ * 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 const TUI_HOST_NAME = 'tuiHost';
+/**
+ * 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 const RESERVED_COMBOS = new Set([
+    'ctrl+c',
+    'ctrl+d',
+    'ctrl+j',
+    'ctrl+n',
+    'ctrl+p',
+    'ctrl+r',
+    'ctrl+t',
+    'ctrl+u',
+    'ctrl+v',
+    'ctrl+w',
+    'ctrl+x',
+    'ctrl+y',
+    'ctrl+f',
+    'ctrl+g',
+    'ctrl+b',
+    'ctrl+o',
+    'ctrl+k',
+    'ctrl+left',
+    'ctrl+right',
+    'ctrl+up',
+    'ctrl+down',
+    'ctrl+enter',
+    'esc',
+    'enter',
+    'tab',
+    'up',
+    'down',
+    'left',
+    'right',
+    'pageup',
+    'pagedown',
+    'home',
+    'end',
+    'backspace',
+    'delete',
+    'shift+up',
+    'shift+down',
+    'alt+n',
+    'alt+p',
+    'alt+e',
+    'alt+c',
+    'alt+up',
+    'alt+down',
+    'wheelup',
+    'wheeldown',
+]);
+/** Why a registration was refused, or `undefined` when it was accepted. */
+export function shortcutProblem(combo, taken) {
+    if (combo.trim() === '')
+        return 'the combination is empty';
+    if (!combo.startsWith('ctrl+') && !combo.startsWith('alt+')) {
+        return 'plugin shortcuts must carry ctrl or alt';
+    }
+    if (RESERVED_COMBOS.has(combo))
+        return `${combo} is a built-in binding`;
+    if (taken.has(combo))
+        return `${combo} is already registered`;
+    return undefined;
+}
+/** Shortcut claims, without any Cordis dependency — the testable half. */
+export class ShortcutRegistry {
+    shortcuts = new Map();
+    /**
+     * Claim a key combination.
+     *
+     * @returns a disposer that releases it, or `undefined` when the combination
+     *   is reserved, malformed, or already registered.
+     */
+    register(shortcut) {
+        const problem = shortcutProblem(shortcut.combo, new Set(this.shortcuts.keys()));
+        if (problem !== undefined)
+            return undefined;
+        this.shortcuts.set(shortcut.combo, shortcut);
+        return () => {
+            // Only release it if this exact registration still owns the combo.
+            if (this.shortcuts.get(shortcut.combo) === shortcut)
+                this.shortcuts.delete(shortcut.combo);
+        };
+    }
+    /** Every registered combination, in registration order. */
+    registered() {
+        return [...this.shortcuts.values()];
+    }
+    /** The label for one combination, when it is claimed. */
+    labelOf(combo) {
+        return this.shortcuts.get(combo)?.label;
+    }
+    /**
+     * 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) {
+        const shortcut = this.shortcuts.get(combo);
+        if (shortcut === undefined)
+            return false;
+        shortcut.handler();
+        return true;
+    }
+}
+/** The one-line status slot, also independent of Cordis. */
+export class StatusLine {
+    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) {
+        const previous = this.line;
+        const applied = text === '' ? undefined : text;
+        this.line = applied;
+        return () => {
+            // Only restore if nothing newer has taken the line since.
+            if (this.line === applied)
+                this.line = previous;
+        };
+    }
+    get() {
+        return this.line;
+    }
+}

package/lib/tui-host.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { ShortcutRegistry, StatusLine, TUI_HOST_NAME } from "./tui-host-core.js";
+export * from "./tui-host-core.js";
+/**
+ * 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 class TuiHost extends Service {
+    shortcuts = new ShortcutRegistry();
+    line = new StatusLine();
+    constructor(ctx) {
+        super(ctx, TUI_HOST_NAME);
+    }
+    /** Claim a key combination; see {@link ShortcutRegistry.register}. */
+    registerShortcut(shortcut) {
+        return this.shortcuts.register(shortcut);
+    }
+    /** Every registered combination, for help output and tests. */
+    registered() {
+        return this.shortcuts.registered();
+    }
+    /** Run a key's plugin handler, if one is registered. */
+    dispatch(combo) {
+        return this.shortcuts.dispatch(combo);
+    }
+    /** Contribute the one-line status above the composer. */
+    setStatusLine(text) {
+        return this.line.set(text);
+    }
+    /** The status line a plugin contributed, if any. */
+    statusLine() {
+        return this.line.get();
+    }
+}
+export default TuiHost;

package/lib/types/cross-find.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Cross-session search: `/find --sessions`.
+ *
+ * Stored sessions live under `$DSH_HOME/sessions/<projectKey>/<sessionId>/` as
+ * either a plain `.jsonl` log or a zstd-compressed one. This module walks them,
+ * reads whichever form it finds, and returns the matching lines with enough
+ * context to recognize the conversation — no index, no cache, and nothing
+ * written, so it can never corrupt a log another process is appending to.
+ *
+ * The zstd decoder is feature-detected: on a Node without it, compressed logs
+ * are skipped and reported as such rather than silently ignored.
+ * @module
+ */
+/** One matching line in one stored session. */
+export interface SessionHit {
+    sessionId: string;
+    /** The project directory key, for orientation. */
+    project: string;
+    /** The matched line, trimmed and truncated for a picker row. */
+    line: string;
+    /** Whether the line came from the human or the model, when determinable. */
+    role?: 'user' | 'assistant';
+    /** Absolute path of the log the match came from. */
+    path: string;
+}
+/** Limits that keep a search from walking an unbounded store. */
+export interface SearchLimits {
+    /** Sessions scanned, newest-first by directory mtime. */
+    maxSessions: number;
+    /** Hits returned overall. */
+    maxHits: number;
+    /** Bytes of an uncompressed log read per session. */
+    maxBytes: number;
+}
+export declare const DEFAULT_LIMITS: SearchLimits;
+/** Whether this build of Node can decompress a zstd log. */
+export declare function zstdAvailable(): boolean;
+/** One readable message from a stored session log. */
+export interface LogMessage {
+    role: 'user' | 'assistant';
+    text: string;
+}
+/**
+ * Parse a whole JSONL session body into its visible messages.
+ *
+ * Shared by cross-session search and the fleet preview, so both read a log the
+ * same way — including a foreign device's log, which may be an older format
+ * whose unknown records are simply skipped.
+ */
+export declare function parseLogMessages(body: string): LogMessage[];
+/** Whether a buffer carries the zstd frame magic. */
+export declare function isZstdFrame(bytes: Uint8Array): boolean;
+/** Decode raw log bytes, whichever form they arrived in. */
+export declare function decodeLogBytes(bytes: Uint8Array): string | undefined;
+/**
+ * Search every stored session for a case-insensitive substring.
+ *
+ * @returns matching lines in session order (newest session first), capped by
+ *   the limits. Skipped compressed logs on a Node without zstd mean fewer
+ *   results, never wrong ones.
+ */
+export declare function searchSessions(root: string, query: string, limits?: SearchLimits): {
+    hits: SessionHit[];
+    scanned: number;
+    skippedCompressed: number;
+};

package/lib/types/file-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A bounded, cached walk of the workspace for `@` file completion.
+ *
+ * The listing is refreshable rather than watched: completion is an
+ * interactive nicety, so a few seconds of staleness after a checkout or a
+ * build costs nothing, while a filesystem watcher would cost a handle and a
+ * failure mode.
+ * @module
+ */
+export interface DirectoryListing {
+    files: {
+        path: string;
+        directory: boolean;
+    }[];
+}
+/** One workspace's file list, recomputed lazily on demand. */
+export declare class FileIndex {
+    private readonly root;
+    private entries;
+    private readAt;
+    private reading;
+    constructor(root: string);
+    /** Every workspace-relative file path, oldest acceptable snapshot or fresh. */
+    list(): string[];
+    /** Synchronously rebuild the listing. Errors leave the previous snapshot. */
+    refresh(): void;
+    private walk;
+    /**
+     * List one directory for a path-shaped query, relative to the workspace
+     * root. `.` and `..` are offered alongside the entries so navigation works
+     * the way a shell expects.
+     */
+    listDir(relativePath: string): DirectoryListing;
+}

package/lib/types/fleet-sources.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Collecting presence records from this device and its peers.
+ *
+ * The transport is SSH, for one reason: it is the only channel in this setup
+ * that is already authenticated, already encrypted, and already working. The
+ * Harness's own web server offers no TLS, no authentication and no origin
+ * policy, and binding it off loopback would publish every route on the
+ * network — so the overview never does that.
+ *
+ * Every remote read is one short, non-interactive command. Nothing is
+ * installed on the peer beyond dsh itself, and nothing listens anywhere.
+ * @module
+ */
+import { type FleetSource } from './tui/fleet.ts';
+/** A peer device the overview should include. */
+export interface PeerConfig {
+    /** Anything `ssh` accepts: a host, an alias, or user@host. */
+    host: string;
+    /** `$DSH_HOME` on that device; defaults to `~/.dsh` there. */
+    dshHome?: string;
+}
+/** Resolve this device's Harness home the way the Harness itself does. */
+export declare function localDshHome(env?: NodeJS.ProcessEnv): string;
+/** Read this device's records. */
+export declare function collectLocal(dshHome?: string): FleetSource;
+/**
+ * Read one peer's records over SSH.
+ *
+ * `BatchMode=yes` matters: a peer whose key is missing must fail fast with an
+ * error in the overview rather than blocking the UI on a password prompt.
+ */
+export declare function collectPeer(peer: PeerConfig): Promise<FleetSource>;
+/** Read every device in parallel; one slow peer must not hold up the rest. */
+export declare function collectFleet(peers: readonly PeerConfig[], dshHome?: string): Promise<FleetSource[]>;

package/lib/types/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * moqi — an interactive terminal app for DeepSeek Harness.
+ *
+ * The bundle patch rides over `dsh-base` without a Host, HTTP server, or
+ * browser plugin: the terminal is the only surface. This module owns the
+ * Harness wiring — creating or resuming an Agent, projecting its assistant
+ * stream into the transcript, and dispatching slash commands through
+ * `ctx.commands` — while `./tui/*` owns everything drawn on screen.
+ *
+ * @module moqi
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "moqi";
+/** Core services required before the terminal can open. */
+export declare const inject: string[];
+/** Plugin config, resolved from this app's startup provider. */
+export interface Config {
+    resumeSessionId?: string;
+    model?: string;
+    thinking?: boolean;
+    contextLimit?: number;
+    /** Report mouse events so the wheel scrolls; off by default. */
+    mouse?: boolean;
+    /** Ring the terminal bell when a session's turn finishes; on by default. */
+    bell?: boolean;
+    /**
+     * Devices to include in the fleet overview, as anything `ssh` accepts.
+     * Empty means the overview shows only this machine.
+     */
+    peers?: string[];
+    /** Reopen the sessions that were open at the last exit; on by default. */
+    restore?: boolean;
+    /** Whisper weights for push-to-talk; absent falls back to the default search. */
+    voiceModel?: string;
+    /** Whisper executable for push-to-talk; absent looks for the known names. */
+    voiceBin?: string;
+    /**
+     * The profile `/dispatch` boots on a peer. The shipped `headless` profile is
+     * the one that answers a single task and exits.
+     */
+    dispatchProfile?: string;
+}
+export declare const Config: z<Config>;
+/**
+ * Mount the terminal app.
+ * @param ctx - plugin context carrying the core services and launcher exit.
+ * @param config - validated startup options.
+ */
+export declare function apply(ctx: Context, config: Config): void;