@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/terminal-ui.d.ts

@@ -0,0 +1,463 @@
+/**
+ * TerminalUI - Single Renderer for Terminal Applications
+ *
+ * Single point of control for all terminal UI:
+ * - Owns all rendering decisions (when to clear, when to render)
+ * - Owns all UI state (agentRunning, todos, currentTool, etc.)
+ * - Provides output methods that handle clear/render automatically
+ * - Manages overlays (render, input routing)
+ * - REPL emits events, doesn't manage rendering timing
+ *
+ * Key principles:
+ * - NO scroll regions (preserves terminal scrollback)
+ * - Deterministic render cycle
+ * - All output goes through TerminalUI (no external console.log)
+ */
+import { EventEmitter } from 'events';
+import type { TodoItem, AgentMode } from './types.js';
+import type { Overlay } from './overlay/index.js';
+import { LiveRegion, type LiveItem, type SubagentLiveItem } from './live-region.js';
+/**
+ * Message to be sent to the agent from a command.
+ * Allows commands to invoke the agent with a detailed prompt while
+ * showing a simpler message to the user.
+ */
+export interface AgentMessage {
+    /** Full message to send to the agent */
+    message: string;
+    /** Optional: Simpler message to display to user (defaults to message) */
+    displayMessage?: string;
+}
+export interface TerminalUIEvents {
+    submit: (input: string) => void;
+    command: (command: string, args: string) => void;
+    cancel: () => void;
+    escape: () => void;
+    interrupt: () => void;
+    modeChange: () => void;
+}
+/**
+ * Configuration for TerminalUI rendering behavior.
+ * Can be changed at runtime via setConfig().
+ */
+export interface TerminalUIConfig {
+    verbose: boolean;
+    theme: string;
+    showMascot: boolean;
+}
+export declare const DEFAULT_TERMINAL_UI_CONFIG: TerminalUIConfig;
+export interface TerminalUIOptions {
+    prompt?: string;
+    initialMode?: AgentMode;
+    config?: Partial<TerminalUIConfig>;
+}
+/**
+ * Represents a semantic item that can be printed to the scrolling zone.
+ * TerminalUI handles all formatting based on the item type and config.
+ *
+ * Items are stored in conversation history for re-rendering when config changes.
+ */
+export type PrintableItem = {
+    type: 'user-message';
+    text: string;
+} | {
+    type: 'agent-text';
+    text: string;
+    expression?: MascotExpression;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool-start';
+    name: string;
+    params: string;
+} | {
+    type: 'tool-result';
+    name: string;
+    params: string;
+    summary: string;
+    content?: string;
+    success?: boolean;
+} | {
+    type: 'tool-error';
+    name: string;
+    params: string;
+    error: string;
+} | {
+    type: 'interrupted';
+    action?: string;
+    suggestion?: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'success';
+    message: string;
+} | {
+    type: 'info';
+    message: string;
+} | {
+    type: 'warning';
+    message: string;
+} | {
+    type: 'raw';
+    text: string;
+} | {
+    type: 'raw-lines';
+    lines: string[];
+};
+/**
+ * Inline mascot expressions for agent identity and state feedback.
+ * Used to prefix agent messages and in spinner animations.
+ */
+export declare const MASCOT: {
+    readonly neutral: "[•_•]";
+    readonly thinking: "[°_°]";
+    readonly searching: "[◐_◐]";
+    readonly success: "[^_^]";
+    readonly error: "[×_×]";
+    readonly confused: "[?_?]";
+    readonly working: "[•̀_•́]";
+    readonly crt: readonly ["[░░░]", "[▒░░]", "[░▒░]", "[░░▒]", "[░▒░]", "[▒░░]"];
+};
+export type MascotExpression = 'neutral' | 'thinking' | 'searching' | 'success' | 'error' | 'confused' | 'working';
+export declare class TerminalUI extends EventEmitter {
+    private promptPrefix;
+    private promptPrefixLen;
+    private config;
+    private conversationHistory;
+    private lines;
+    private currentLine;
+    private cursorPos;
+    private mode;
+    private projectName;
+    private todos;
+    private spinnerText;
+    private spinnerFrame;
+    private agentRunning;
+    private queuedInputs;
+    private agentMessageQueue;
+    private currentTool;
+    private readonly liveRegion;
+    private readonly autocomplete;
+    private readonly fileAutocomplete;
+    private readonly history;
+    private historyIndex;
+    private savedInput;
+    private lastRenderHeight;
+    private cursorLineFromBottom;
+    private isRunning;
+    private isPaused;
+    private renderTimer;
+    private needsRender;
+    private lastEscapeTime;
+    private suggestion;
+    private showTodos;
+    private viewMode;
+    private readonly spinnerFrames;
+    private spinnerTimer;
+    private readonly overlayStack;
+    private readonly overlayResolvers;
+    private overlayRenderState;
+    private overlayPrintBuffer;
+    constructor(options?: TerminalUIOptions);
+    /** Get the full input value (all lines joined with newlines) */
+    private getInputValue;
+    /** Get the current line content */
+    private getCurrentLineContent;
+    /** Clear input and reset to single empty line */
+    private clearInput;
+    start(): void;
+    stop(): void;
+    /**
+     * Print a semantic item to the scrolling zone.
+     * Items are stored in conversation history for re-rendering when config changes.
+     *
+     * IMPORTANT: When an overlay is active, items are buffered and rendered after
+     * the overlay closes. This prevents cursor position corruption that causes
+     * ghost lines and visual artifacts.
+     */
+    print(item: PrintableItem): void;
+    /**
+     * Render a single item to the console.
+     * Config-aware: respects verbose, showMascot settings.
+     */
+    private renderItem;
+    /**
+     * Execute a callback that outputs to terminal.
+     * Handles clear → callback → render automatically.
+     * Use this for complex output that needs multiple console.log calls.
+     * @deprecated Prefer using print() with PrintableItem
+     */
+    output(callback: () => void): void;
+    setAgentRunning(running: boolean): void;
+    isAgentRunning(): boolean;
+    setTodos(todos: TodoItem[]): void;
+    getTodos(): TodoItem[];
+    setSpinnerText(text: string | null): void;
+    setCurrentTool(tool: string | null): void;
+    setMode(mode: AgentMode): void;
+    getMode(): AgentMode;
+    setProjectName(name: string | null): void;
+    getProjectName(): string | null;
+    /**
+     * Set ghost text suggestion (shown when input is empty)
+     */
+    setSuggestion(text: string | null): void;
+    getSuggestion(): string | null;
+    clearSuggestion(): void;
+    /**
+     * Add a subagent to the live region.
+     */
+    addSubagent(id: string, agentType: string, description: string): void;
+    /**
+     * Update a subagent's tool usage.
+     */
+    updateSubagentTool(id: string, toolName: string, summary: string): void;
+    /**
+     * Mark a subagent as completed.
+     */
+    completeSubagent(id: string, success: boolean, tokenCount?: number, _error?: string): void;
+    /**
+     * Remove a subagent and return it for committing to scrolling zone.
+     */
+    removeSubagent(id: string): LiveItem | undefined;
+    /**
+     * Clear all subagents from live region.
+     */
+    clearLiveRegion(): void;
+    /**
+     * Toggle expanded view in live region (Ctrl+O).
+     */
+    toggleLiveRegionExpanded(): void;
+    /**
+     * Check if live region has items.
+     */
+    hasLiveItems(): boolean;
+    /**
+     * Get live region for direct access if needed.
+     */
+    getLiveRegion(): LiveRegion;
+    /**
+     * Add a bash command to the live region.
+     */
+    addBashCommand(id: string, command: string): void;
+    /**
+     * Add output line to a bash command.
+     */
+    updateBashOutput(id: string, line: string): void;
+    /**
+     * Mark a bash command as completed.
+     */
+    completeBashCommand(id: string, exitCode: number): void;
+    /**
+     * Remove a bash command and commit it to the scrolling zone.
+     */
+    commitBashCommand(id: string): void;
+    /**
+     * Remove a subagent and commit it to the scrolling zone.
+     * This is the atomic equivalent of commitBashCommand for subagents.
+     * The result content comes from tool_end, not from the LiveRegion item.
+     */
+    commitSubagent(id: string, resultContent: string, success: boolean): SubagentLiveItem | undefined;
+    /**
+     * Format token count (e.g., 5000 -> "5.0k")
+     */
+    private formatTokens;
+    /**
+     * Toggle todo list visibility (Ctrl+T)
+     */
+    toggleTodos(): void;
+    /**
+     * Set todo list visibility
+     */
+    setShowTodos(show: boolean): void;
+    /**
+     * Get todo list visibility
+     */
+    getShowTodos(): boolean;
+    /**
+     * Toggle verbose view mode (Ctrl+O)
+     * Shows conversation in verbose mode temporarily.
+     * Any key returns to normal view.
+     */
+    toggleVerboseView(): void;
+    /**
+     * Re-render conversation with temporary verbose setting.
+     */
+    private reRenderConversationVerbose;
+    /**
+     * Update configuration at runtime.
+     * If verbose changes, re-renders the entire conversation.
+     */
+    setConfig(newConfig: Partial<TerminalUIConfig>): void;
+    /**
+     * Get current configuration.
+     */
+    getConfig(): TerminalUIConfig;
+    /**
+     * Re-render entire conversation with current config.
+     * Called when verbose mode changes.
+     */
+    private reRenderConversation;
+    /**
+     * Clear conversation history.
+     * Called by /clear command.
+     */
+    clearConversationHistory(): void;
+    /**
+     * Get conversation history (copy).
+     */
+    getConversationHistory(): PrintableItem[];
+    /**
+     * Check if an overlay is currently active.
+     */
+    hasActiveOverlay(): boolean;
+    /**
+     * Get the currently active overlay (if any).
+     */
+    getActiveOverlay(): Overlay | null;
+    /**
+     * Show an overlay and wait for result.
+     * Returns promise that resolves when overlay closes.
+     */
+    showOverlay<TResult>(overlay: Overlay<unknown, TResult>): Promise<TResult | null>;
+    /**
+     * Close current overlay with result.
+     * Called internally when overlay returns close action.
+     */
+    private closeCurrentOverlay;
+    /**
+     * Enter fullscreen overlay mode.
+     * Clears screen and prepares for overlay rendering.
+     */
+    private enterFullscreenOverlayMode;
+    /**
+     * Enter inline overlay mode.
+     * Clears footer but keeps conversation visible.
+     */
+    private enterInlineOverlayMode;
+    /**
+     * Exit overlay mode and restore normal rendering.
+     */
+    private exitOverlayMode;
+    /**
+     * Flush items that were buffered while an overlay was active.
+     * Called after overlay closes to render any pending output.
+     */
+    private flushOverlayPrintBuffer;
+    /**
+     * Clear previous overlay render.
+     * Uses maxLineCount to ensure all lines are cleared even if content shrank between renders.
+     */
+    private clearOverlayRender;
+    /**
+     * Render the active overlay.
+     */
+    private renderOverlay;
+    /**
+     * Render fullscreen overlay.
+     *
+     * CRITICAL: Cursor positioning must be consistent between renders.
+     * Same logic as renderInlineOverlay - pad to maxLineCount for consistency.
+     */
+    private renderFullscreenOverlay;
+    /**
+     * Render inline overlay (above footer).
+     *
+     * CRITICAL: Cursor positioning must be consistent between renders.
+     * After rendering, cursor MUST be at maxLineCount position, not at
+     * actual content height. Otherwise, the next clear will move cursor
+     * up by maxLineCount from the wrong position, causing "ghost lines".
+     */
+    private renderInlineOverlay;
+    /**
+     * Process overlay action returned by handleKey.
+     */
+    private processOverlayAction;
+    getQueuedInputs(): string[];
+    popQueuedInput(): string | null;
+    hasQueuedInput(): boolean;
+    clearQueue(): void;
+    /**
+     * Queue a message to be sent to the agent.
+     * Used by commands that need to invoke the agent programmatically.
+     */
+    queueAgentMessage(options: AgentMessage): void;
+    /**
+     * Pop the next agent message from the queue.
+     */
+    popAgentMessage(): AgentMessage | null;
+    /**
+     * Check if there are queued agent messages.
+     */
+    hasAgentMessage(): boolean;
+    /**
+     * Clear all queued agent messages.
+     */
+    clearAgentMessageQueue(): void;
+    /**
+     * Pause footer completely (for overlays)
+     */
+    pauseAnimation(): void;
+    /**
+     * Resume footer after pause
+     */
+    resumeAnimation(): void;
+    /**
+     * Restart input after command
+     */
+    restartInput(): void;
+    /**
+     * Refresh prompt with theme colors
+     */
+    refreshPrompt(): void;
+    /**
+     * @deprecated Use print() or output() instead
+     */
+    clearForOutput(): void;
+    /**
+     * @deprecated Use print() or output() instead
+     */
+    forceRender(): void;
+    private clear;
+    private render;
+    private buildSpinnerLine;
+    private buildTodoLine;
+    private buildModeLine;
+    private buildAutocompleteLines;
+    private buildFileAutocompleteLines;
+    private updateAutocomplete;
+    private acceptAutocomplete;
+    private closeAutocomplete;
+    private navigateAutocompleteUp;
+    private navigateAutocompleteDown;
+    private addToHistory;
+    private navigateHistoryUp;
+    private navigateHistoryDown;
+    private resetHistoryNavigation;
+    private startSpinnerAnimation;
+    private stopSpinnerAnimation;
+    private keyHandler;
+    private dataHandler;
+    private startKeyboardCapture;
+    private stopKeyboardCapture;
+    /**
+     * Handle word left (Option+Left) - move cursor to previous word boundary
+     */
+    private handleWordLeft;
+    /**
+     * Handle word right (Option+Right) - move cursor to next word boundary
+     */
+    private handleWordRight;
+    /**
+     * Handle Escape key - called from raw data handler for reliable detection
+     */
+    private handleEscape;
+    /**
+     * Handle keypress when overlay is active.
+     * Converts keyboard event to KeyEvent and routes to overlay.
+     */
+    private handleOverlayKeypress;
+    private handleKeypress;
+}