@compilr-dev/cli 0.4.0 → 0.5.1

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

@@ -0,0 +1,179 @@
+/**
+ * Types, interfaces, and constants for TerminalUI.
+ *
+ * Extracted from terminal-ui.ts for modularity.
+ * All public symbols are re-exported from terminal-ui.ts for backwards compatibility.
+ */
+import type { CommandOption } from './types.js';
+import type { FileMatch } from './file-autocomplete.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;
+    showTasks: () => void;
+    showPending: () => void;
+    backgroundBash: (info: {
+        toolUseId: string;
+        command: string;
+        partialOutput: string;
+        startTime: number;
+    }) => 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?: import('./types.js').AgentMode;
+    config?: Partial<TerminalUIConfig>;
+}
+export interface LineInfo {
+    content: string;
+    physicalLines: number;
+}
+export interface AutocompleteState {
+    active: boolean;
+    matches: CommandOption[];
+    selectedIndex: number;
+    scrollOffset: number;
+}
+export interface FileAutocompleteState {
+    active: boolean;
+    matches: FileMatch[];
+    selectedIndex: number;
+    scrollOffset: number;
+    partial: string;
+}
+/**
+ * Agent suggestion for $ autocomplete
+ */
+export interface AgentSuggestion {
+    id: string;
+    displayName: string;
+    mascot: string;
+}
+export interface AgentAutocompleteState {
+    active: boolean;
+    matches: AgentSuggestion[];
+    selectedIndex: number;
+    scrollOffset: number;
+    partial: string;
+    startPos: number;
+    lineIndex: number;
+}
+export interface KeypressKey {
+    name?: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    meta?: boolean;
+    sequence?: string;
+}
+/**
+ * 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;
+    agentId?: string;
+} | {
+    type: 'agent-text';
+    text: string;
+    expression?: string;
+    agentId?: string;
+} | {
+    type: 'thinking';
+    text: string;
+    agentId?: string;
+} | {
+    type: 'tool-start';
+    name: string;
+    params: string;
+    agentId?: string;
+} | {
+    type: 'tool-result';
+    name: string;
+    params: string;
+    summary: string;
+    content?: string;
+    diffLines?: string[];
+    success?: boolean;
+    agentId?: string;
+} | {
+    type: 'tool-error';
+    name: string;
+    params: string;
+    error: string;
+    agentId?: string;
+} | {
+    type: 'interrupted';
+    action?: string;
+    suggestion?: string;
+    agentId?: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'success';
+    message: string;
+} | {
+    type: 'info';
+    message: string;
+} | {
+    type: 'warning';
+    message: string;
+} | {
+    type: 'turn-summary';
+    parts: string[];
+    agentId?: string;
+} | {
+    type: 'raw';
+    text: string;
+} | {
+    type: 'raw-lines';
+    lines: string[];
+} | {
+    type: 'background-agent';
+    agentId: string;
+    mascot: string;
+    text: string;
+};
+export declare const MAX_VISIBLE_COMMANDS = 10;
+/**
+ * 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';

package/dist/ui/terminal-types.js

@@ -0,0 +1,34 @@
+/**
+ * Types, interfaces, and constants for TerminalUI.
+ *
+ * Extracted from terminal-ui.ts for modularity.
+ * All public symbols are re-exported from terminal-ui.ts for backwards compatibility.
+ */
+export const DEFAULT_TERMINAL_UI_CONFIG = {
+    verbose: false,
+    theme: 'default',
+    showMascot: true,
+};
+// =============================================================================
+// Constants
+// =============================================================================
+export const MAX_VISIBLE_COMMANDS = 10;
+// =============================================================================
+// Mascot Expressions
+// =============================================================================
+/**
+ * Inline mascot expressions for agent identity and state feedback.
+ * Used to prefix agent messages and in spinner animations.
+ */
+export const MASCOT = {
+    // Core expressions
+    neutral: '[•_•]', // Default state - regular messages
+    thinking: '[°_°]', // Processing/thinking
+    searching: '[◐_◐]', // Searching/scanning files
+    success: '[^_^]', // Task completed successfully
+    error: '[×_×]', // Error occurred
+    confused: '[?_?]', // Needs clarification
+    working: '[•̀_•́]', // Actively working on task
+    // CRT monitor animation frames (subtle scanner effect)
+    crt: ['[░░░]', '[▒░░]', '[░▒░]', '[░░▒]', '[░▒░]', '[▒░░]'],
+};

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

@@ -0,0 +1,331 @@
+/**
+ * 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 { AgentMessage, TerminalUIConfig, TerminalUIOptions, AgentSuggestion, PrintableItem } from './terminal-types.js';
+export type { AgentMessage, TerminalUIEvents, TerminalUIConfig, TerminalUIOptions, AgentSuggestion, PrintableItem, MascotExpression } from './terminal-types.js';
+export { DEFAULT_TERMINAL_UI_CONFIG, MASCOT } from './terminal-types.js';
+import type { Overlay } from './overlay/index.js';
+import { LiveRegion, type LiveItem, type SubagentLiveItem } from './live-region.js';
+export declare class TerminalUI extends EventEmitter {
+    private promptPrefix;
+    private promptPrefixLen;
+    private config;
+    private readonly conversation;
+    private readonly input;
+    private get lines();
+    private set lines(value);
+    private get currentLine();
+    private set currentLine(value);
+    private get cursorPos();
+    private set cursorPos(value);
+    private get suggestion();
+    private set suggestion(value);
+    private get queuedInputs();
+    private set queuedInputs(value);
+    private mode;
+    private projectName;
+    private todos;
+    private activePlanId;
+    private activePlanName;
+    private spinnerText;
+    private agentRunning;
+    private agentMessageQueue;
+    private currentTool;
+    private readonly turnMetrics;
+    private readonly live;
+    private readonly ac;
+    private isRunning;
+    private isPaused;
+    private renderTimer;
+    private needsRender;
+    private activeTeamAgent;
+    private showTodos;
+    private viewMode;
+    private readonly statusBar;
+    private readonly overlay;
+    private readonly footer;
+    private readonly keyboard;
+    constructor(options?: TerminalUIOptions);
+    /** Set background agent count (called by REPL to keep UI in sync). */
+    setBackgroundAgentCount(count: number): void;
+    /** Set MCP loading state for status bar indicator. */
+    setMCPLoading(loading: boolean, toolCount?: number): void;
+    start(skipInitialRender?: boolean): 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.
+     * Delegates to standalone renderItem() function.
+     */
+    private renderItemToConsole;
+    /**
+     * 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;
+    /**
+     * Set whether extended thinking mode is active
+     * Shows "thinking" indicator in status line
+     */
+    setThinking(thinking: boolean): void;
+    /**
+     * Add input/output tokens for live display
+     * @param thinkingTokens - Optional thinking tokens (Gemini 2.5+ models)
+     * @param cacheReadTokens - Optional cache read tokens (Anthropic/Gemini)
+     * @param debugPayload - Optional debug payload sizes (char counts)
+     */
+    addTokens(inputTokens: number, outputTokens: number, thinkingTokens?: number, cacheReadTokens?: number, debugPayload?: {
+        systemChars: number;
+        contentsChars: number;
+        toolsChars: number;
+    }): void;
+    /**
+     * Increment tool call counter
+     */
+    incrementToolCalls(): void;
+    /**
+     * Increment API call counter (called on each LLM request completion)
+     */
+    incrementApiCalls(): void;
+    /**
+     * Reset turn metrics (call when agent starts a new turn)
+     */
+    resetTurnMetrics(): void;
+    /**
+     * Get current turn metrics
+     */
+    getTurnMetrics(): {
+        inputTokens: number;
+        outputTokens: number;
+        thinkingTokens: number;
+        cacheReadTokens: number;
+        durationMs: number;
+        toolCalls: number;
+        apiCalls: number;
+        debugPayload?: {
+            systemChars: number;
+            contentsChars: number;
+            toolsChars: number;
+        };
+    };
+    setMode(mode: AgentMode): void;
+    getMode(): AgentMode;
+    setProjectName(name: string | null): void;
+    getProjectName(): string | null;
+    /**
+     * Set the active team agent (displayed in footer)
+     * Pass null to clear (default agent or no team)
+     */
+    setActiveTeamAgent(agent: {
+        id: string;
+        displayName: string;
+        mascot: string;
+    } | null): void;
+    /**
+     * Get the active team agent
+     */
+    getActiveTeamAgent(): {
+        id: string;
+        displayName: string;
+        mascot: string;
+    } | null;
+    /**
+     * Set the callback to get available team agents for $ autocomplete
+     */
+    setAgentSuggestionsCallback(callback: (() => AgentSuggestion[]) | undefined): void;
+    /**
+     * Set the callback to get available commands for / autocomplete
+     */
+    setCommandsCallback(callback: (() => {
+        command: string;
+        description: string;
+    }[]) | undefined): void;
+    /**
+     * Set the active plan (for Plan Mode display in footer)
+     */
+    setActivePlan(planId: number | null, planName: string | null): void;
+    /**
+     * Get the active plan info
+     */
+    getActivePlan(): {
+        id: number | null;
+        name: string | null;
+    };
+    /**
+     * Clear the active plan
+     */
+    clearActivePlan(): void;
+    /**
+     * Set ghost text suggestion (shown when input is empty)
+     */
+    setSuggestion(text: string | null): void;
+    getSuggestion(): string | null;
+    clearSuggestion(): void;
+    addSubagent(id: string, agentType: string, description: string): void;
+    updateSubagentTool(id: string, toolName: string, summary: string): void;
+    completeSubagent(id: string, success: boolean, tokenCount?: number, _error?: string): void;
+    removeSubagent(id: string): LiveItem | undefined;
+    clearLiveRegion(): void;
+    toggleLiveRegionExpanded(): void;
+    hasLiveItems(): boolean;
+    getLiveRegion(): LiveRegion;
+    addBashCommand(id: string, command: string): void;
+    updateBashOutput(id: string, line: string): void;
+    completeBashCommand(id: string, exitCode: number): void;
+    commitBashCommand(id: string): void;
+    backgroundBashCommand(): void;
+    hasActiveBash(): boolean;
+    getActiveBashInfo(): {
+        toolUseId: string;
+        startTime: number;
+    } | null;
+    commitSubagent(id: string, resultContent: string, success: boolean): SubagentLiveItem | undefined;
+    /**
+     * 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;
+    /**
+     * Store restored conversation items for Ctrl+R history view.
+     * Called when a session is resumed/restored.
+     */
+    setRestoredHistory(items: PrintableItem[]): void;
+    /**
+     * Check if there is restored history available.
+     */
+    hasRestoredHistory(): boolean;
+    /**
+     * Show restored conversation history (Ctrl+R).
+     * Renders items permanently into the scrollback buffer.
+     * Stays in normal mode — the output persists like any other printed content.
+     */
+    private showRestoredHistory;
+    /**
+     * 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[];
+    setConversationFilter(agentIds: string[]): void;
+    clearConversationFilter(): void;
+    getConversationFilter(): {
+        agentIds: string[];
+        isActive: boolean;
+    };
+    addToConversationFilter(agentId: string): boolean;
+    isAgentInFilter(agentId: string): boolean;
+    hasActiveOverlay(): boolean;
+    getActiveOverlay(): Overlay | null;
+    showOverlay<TResult>(overlay: Overlay<unknown, TResult>): Promise<TResult | null>;
+    requestOverlayRender(): void;
+    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;
+}