@compilr-dev/cli 0.4.0

package/dist/ui/terminal.js

@@ -0,0 +1,237 @@
+/**
+ * Terminal Utilities
+ *
+ * Low-level terminal operations using ANSI escape codes.
+ * Pure functions with no state.
+ */
+// =============================================================================
+// Terminal Title
+// =============================================================================
+/**
+ * Set terminal window title
+ */
+export function setTitle(title) {
+    process.stdout.write(`\x1b]0;${title}\x07`);
+}
+// =============================================================================
+// Terminal Dimensions
+// =============================================================================
+/**
+ * Get terminal width (columns)
+ */
+export function getTerminalWidth() {
+    return process.stdout.columns || 80;
+}
+/**
+ * Get terminal height (rows)
+ */
+export function getTerminalHeight() {
+    return process.stdout.rows || 24;
+}
+// =============================================================================
+// Cursor Movement
+// =============================================================================
+/**
+ * Move cursor up N lines
+ */
+export function moveCursorUp(n) {
+    if (n > 0) {
+        process.stdout.write(`\x1b[${String(n)}A`);
+    }
+}
+/**
+ * Move cursor down N lines
+ */
+export function moveCursorDown(n) {
+    if (n > 0) {
+        process.stdout.write(`\x1b[${String(n)}B`);
+    }
+}
+/**
+ * Move cursor to column (1-indexed)
+ */
+export function moveCursorToColumn(col) {
+    process.stdout.write(`\x1b[${String(col)}G`);
+}
+/**
+ * Move cursor to beginning of line
+ */
+export function moveCursorToLineStart() {
+    process.stdout.write('\r');
+}
+/**
+ * Save cursor position
+ */
+export function saveCursor() {
+    process.stdout.write('\x1b[s');
+}
+/**
+ * Restore cursor position
+ */
+export function restoreCursor() {
+    process.stdout.write('\x1b[u');
+}
+// =============================================================================
+// Cursor Visibility
+// =============================================================================
+/**
+ * Hide cursor
+ */
+export function hideCursor() {
+    process.stdout.write('\x1b[?25l');
+}
+/**
+ * Show cursor
+ */
+export function showCursor() {
+    process.stdout.write('\x1b[?25h');
+}
+// =============================================================================
+// Clearing
+// =============================================================================
+/**
+ * Clear current line
+ */
+export function clearLine() {
+    process.stdout.write('\r\x1b[K');
+}
+/**
+ * Clear from cursor to end of screen
+ */
+export function clearToEndOfScreen() {
+    process.stdout.write('\x1b[J');
+}
+/**
+ * Clear N lines above cursor (including current line)
+ * Moves cursor up, clears to end of screen, cursor ends at top
+ */
+export function clearLinesAbove(count) {
+    if (count <= 0)
+        return;
+    if (count > 1) {
+        moveCursorUp(count - 1);
+    }
+    moveCursorToLineStart();
+    clearToEndOfScreen();
+}
+/**
+ * Clear entire screen
+ */
+export function clearScreen() {
+    process.stdout.write('\x1b[2J\x1b[H');
+}
+// =============================================================================
+// Line Calculations
+// =============================================================================
+/**
+ * Calculate how many physical (visual) lines a string occupies
+ * given terminal width and starting column.
+ *
+ * @param text - The text to measure (may contain newlines)
+ * @param termWidth - Terminal width in columns
+ * @param startCol - Starting column position (0-indexed)
+ * @returns Number of physical lines occupied
+ */
+export function calculatePhysicalLines(text, termWidth, startCol = 0) {
+    if (text.length === 0)
+        return 1;
+    let lines = 0;
+    let col = startCol;
+    for (const char of text) {
+        if (char === '\n') {
+            lines++;
+            col = 0;
+        }
+        else {
+            col++;
+            if (col >= termWidth) {
+                lines++;
+                col = 0;
+            }
+        }
+    }
+    // Count the final line (even if it doesn't end with newline)
+    lines++;
+    return lines;
+}
+/**
+ * Calculate physical layout of text with cursor position
+ *
+ * @param text - The text to analyze
+ * @param cursorPos - Cursor position in the text (character index)
+ * @param termWidth - Terminal width
+ * @param startCol - Starting column (for prompt prefix)
+ */
+export function calculateCursorPosition(text, cursorPos, termWidth, startCol = 0) {
+    let row = 0;
+    let col = startCol;
+    for (let i = 0; i < cursorPos && i < text.length; i++) {
+        if (text[i] === '\n') {
+            row++;
+            col = 0;
+        }
+        else {
+            col++;
+            if (col >= termWidth) {
+                row++;
+                col = 0;
+            }
+        }
+    }
+    return { row, col };
+}
+// =============================================================================
+// Horizontal Lines
+// =============================================================================
+/**
+ * Create a horizontal line spanning terminal width
+ *
+ * @param char - Character to use (default: '─')
+ * @returns String of repeated characters
+ */
+export function horizontalLine(char = '─') {
+    return char.repeat(getTerminalWidth());
+}
+// =============================================================================
+// Raw Mode
+// =============================================================================
+/**
+ * Enable raw mode for stdin
+ * In raw mode, input is available character by character
+ */
+export function enableRawMode() {
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+}
+/**
+ * Disable raw mode for stdin and pause it
+ */
+export function disableRawMode() {
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+    }
+    process.stdin.pause();
+}
+// =============================================================================
+// Output Helpers
+// =============================================================================
+/**
+ * Write to stdout without newline
+ */
+export function write(text) {
+    process.stdout.write(text);
+}
+/**
+ * Write line to stdout with newline
+ */
+export function writeLine(text = '') {
+    console.log(text);
+}
+/**
+ * Ring terminal bell
+ */
+export function bell() {
+    process.stdout.write('\x07');
+}

package/dist/ui/todo-zone.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Todo Zone
+ *
+ * Renders the spinner and todo list as a unified component.
+ * - When agent running: Shows animated spinner with active task name
+ * - When agent idle: Shows "Todos" header with todo list
+ *
+ * This is a pure rendering component - it returns strings/lines,
+ * the Footer orchestrator handles actual terminal output.
+ */
+import type { TodoItem, SpinnerState } from './types.js';
+export interface TodoZoneOptions {
+    /** Width of the knight rider scanner (default: auto from text) */
+    spinnerWidth?: number;
+    /** Animation update interval in ms (default: 150) */
+    animationInterval?: number;
+}
+export declare class TodoZone {
+    private readonly animationInterval;
+    private agentRunning;
+    private todos;
+    private currentTool;
+    private spinnerState;
+    private animationPosition;
+    private animationDirection;
+    private thinkingWord;
+    private customSpinnerText;
+    private animationTimer;
+    private onAnimationUpdate;
+    constructor(options?: TodoZoneOptions);
+    /**
+     * Set whether the agent is running
+     */
+    setAgentRunning(running: boolean): void;
+    /**
+     * Update the todo list
+     */
+    setTodos(todos: TodoItem[]): void;
+    /**
+     * Set the current tool being executed
+     */
+    setCurrentTool(tool: string | null): void;
+    /**
+     * Set custom spinner text (overrides todo activeForm and random thinking word)
+     * Pass null to clear and use default behavior.
+     */
+    setSpinnerText(text: string | null): void;
+    /**
+     * Add tokens to the counter
+     */
+    addTokens(count: number): void;
+    /**
+     * Set callback for animation updates
+     */
+    setAnimationCallback(callback: (() => void) | null): void;
+    /**
+     * Pause the animation (for overlays, permission prompts)
+     */
+    pauseAnimation(): void;
+    /**
+     * Resume the animation after pause
+     */
+    resumeAnimation(): void;
+    /**
+     * Check if zone is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get spinner state (for external access to tokens, etc.)
+     */
+    getSpinnerState(): SpinnerState | null;
+    /**
+     * Render the zone - returns array of lines to display
+     */
+    render(): string[];
+    /**
+     * Get the height (number of lines) this zone will render
+     */
+    getHeight(): number;
+    /**
+     * Cleanup resources
+     */
+    dispose(): void;
+    /**
+     * Start the spinner animation
+     */
+    private startSpinner;
+    /**
+     * Stop the spinner animation
+     */
+    private stopSpinner;
+    /**
+     * Start the animation interval loop
+     */
+    private startAnimationLoop;
+    /**
+     * Get the currently active todo (in_progress)
+     */
+    private getActiveTodo;
+    /**
+     * Get the text to display in spinner (custom text, active todo, or thinking word)
+     */
+    private getDisplayText;
+    /**
+     * Render the spinner line (when agent running)
+     */
+    private renderSpinnerLine;
+    /**
+     * Render the todo list items
+     */
+    private renderTodoList;
+}

package/dist/ui/todo-zone.js

@@ -0,0 +1,353 @@
+/**
+ * Todo Zone
+ *
+ * Renders the spinner and todo list as a unified component.
+ * - When agent running: Shows animated spinner with active task name
+ * - When agent idle: Shows "Todos" header with todo list
+ *
+ * This is a pure rendering component - it returns strings/lines,
+ * the Footer orchestrator handles actual terminal output.
+ */
+import chalk from 'chalk';
+import { getStyles } from '../themes/index.js';
+// =============================================================================
+// Thinking Words (for random selection when no active todo)
+// =============================================================================
+const THINKING_WORDS = [
+    'Thinking',
+    'Pondering',
+    'Contemplating',
+    'Ruminating',
+    'Cogitating',
+    'Deliberating',
+    'Musing',
+    'Reflecting',
+    'Considering',
+    'Analyzing',
+    'Processing',
+    'Computing',
+    'Synthesizing',
+    'Extrapolating',
+    'Hypothesizing',
+    'Discombobulating',
+    'Nebulizing',
+    'Percolating',
+    'Marinating',
+    'Simmering',
+    'Brewing',
+    'Fermenting',
+    'Distilling',
+    'Crystallizing',
+    'Transmuting',
+];
+// =============================================================================
+// Formatting Helpers
+// =============================================================================
+/**
+ * Format duration in human-readable format (e.g., "1m 23s", "45s")
+ */
+function formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60) {
+        return `${String(seconds)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${String(minutes)}m ${String(remainingSeconds)}s`;
+}
+/**
+ * Format token count (e.g., "1.2k", "500")
+ */
+function formatTokens(tokens) {
+    if (tokens >= 1000) {
+        return `${(tokens / 1000).toFixed(1)}k`;
+    }
+    return tokens.toString();
+}
+// =============================================================================
+// Todo Zone Class
+// =============================================================================
+export class TodoZone {
+    // Configuration
+    animationInterval;
+    // State
+    agentRunning = false;
+    todos = [];
+    currentTool = null;
+    // Spinner state
+    spinnerState = null;
+    animationPosition = 0;
+    animationDirection = 1; // 1 = right, -1 = left
+    thinkingWord = '';
+    customSpinnerText = null;
+    animationTimer = null;
+    // Callback for when animation updates (Footer will re-render)
+    onAnimationUpdate = null;
+    constructor(options = {}) {
+        this.animationInterval = options.animationInterval ?? 150;
+    }
+    // ===========================================================================
+    // Public API
+    // ===========================================================================
+    /**
+     * Set whether the agent is running
+     */
+    setAgentRunning(running) {
+        const wasRunning = this.agentRunning;
+        this.agentRunning = running;
+        if (running && !wasRunning) {
+            // Starting - initialize spinner
+            this.startSpinner();
+        }
+        else if (!running && wasRunning) {
+            // Stopping - clear spinner
+            this.stopSpinner();
+        }
+    }
+    /**
+     * Update the todo list
+     */
+    setTodos(todos) {
+        this.todos = todos;
+    }
+    /**
+     * Set the current tool being executed
+     */
+    setCurrentTool(tool) {
+        this.currentTool = tool;
+    }
+    /**
+     * Set custom spinner text (overrides todo activeForm and random thinking word)
+     * Pass null to clear and use default behavior.
+     */
+    setSpinnerText(text) {
+        this.customSpinnerText = text;
+    }
+    /**
+     * Add tokens to the counter
+     */
+    addTokens(count) {
+        if (this.spinnerState) {
+            this.spinnerState.tokens += count;
+        }
+    }
+    /**
+     * Set callback for animation updates
+     */
+    setAnimationCallback(callback) {
+        this.onAnimationUpdate = callback;
+    }
+    /**
+     * Pause the animation (for overlays, permission prompts)
+     */
+    pauseAnimation() {
+        if (this.animationTimer) {
+            clearInterval(this.animationTimer);
+            this.animationTimer = null;
+        }
+    }
+    /**
+     * Resume the animation after pause
+     */
+    resumeAnimation() {
+        if (this.agentRunning && !this.animationTimer) {
+            this.startAnimationLoop();
+        }
+    }
+    /**
+     * Check if zone is running
+     */
+    isRunning() {
+        return this.agentRunning;
+    }
+    /**
+     * Get spinner state (for external access to tokens, etc.)
+     */
+    getSpinnerState() {
+        return this.spinnerState;
+    }
+    /**
+     * Render the zone - returns array of lines to display
+     */
+    render() {
+        const lines = [];
+        if (this.agentRunning && this.spinnerState) {
+            // Running mode: always show spinner, optionally with todo list
+            lines.push(this.renderSpinnerLine());
+            if (this.todos.length > 0) {
+                lines.push(...this.renderTodoList(true));
+            }
+        }
+        else if (this.todos.length > 0) {
+            // Idle mode with todos: "Todos" header + todo list
+            lines.push(chalk.bold('Todos'));
+            lines.push(...this.renderTodoList(false));
+        }
+        // Idle mode without todos: render nothing
+        return lines;
+    }
+    /**
+     * Get the height (number of lines) this zone will render
+     */
+    getHeight() {
+        if (this.agentRunning && this.spinnerState) {
+            // Spinner line + optional todo items
+            return 1 + this.todos.length;
+        }
+        else if (this.todos.length > 0) {
+            // "Todos" header + todo items
+            return 1 + this.todos.length;
+        }
+        return 0;
+    }
+    /**
+     * Cleanup resources
+     */
+    dispose() {
+        this.stopSpinner();
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    /**
+     * Start the spinner animation
+     */
+    startSpinner() {
+        // Pick a random thinking word
+        this.thinkingWord =
+            THINKING_WORDS[Math.floor(Math.random() * THINKING_WORDS.length)] + '...';
+        // Initialize spinner state
+        this.spinnerState = {
+            text: this.thinkingWord,
+            tokens: 0,
+            startTime: Date.now(),
+        };
+        // Reset animation
+        this.animationPosition = 0;
+        this.animationDirection = 1;
+        // Start animation loop
+        this.startAnimationLoop();
+    }
+    /**
+     * Stop the spinner animation
+     */
+    stopSpinner() {
+        if (this.animationTimer) {
+            clearInterval(this.animationTimer);
+            this.animationTimer = null;
+        }
+        this.spinnerState = null;
+        this.currentTool = null;
+    }
+    /**
+     * Start the animation interval loop
+     */
+    startAnimationLoop() {
+        this.animationTimer = setInterval(() => {
+            // Move position
+            this.animationPosition += this.animationDirection;
+            // Get current display text for bounds
+            const displayText = this.getDisplayText();
+            // Bounce at edges
+            if (this.animationPosition >= displayText.length - 1) {
+                this.animationDirection = -1;
+            }
+            else if (this.animationPosition <= 0) {
+                this.animationDirection = 1;
+            }
+            // Notify Footer to re-render
+            if (this.onAnimationUpdate) {
+                this.onAnimationUpdate();
+            }
+        }, this.animationInterval);
+    }
+    /**
+     * Get the currently active todo (in_progress)
+     */
+    getActiveTodo() {
+        return this.todos.find((t) => t.status === 'in_progress');
+    }
+    /**
+     * Get the text to display in spinner (custom text, active todo, or thinking word)
+     */
+    getDisplayText() {
+        // Custom text takes priority
+        if (this.customSpinnerText) {
+            return this.customSpinnerText + '...';
+        }
+        const activeTodo = this.getActiveTodo();
+        return activeTodo
+            ? (activeTodo.activeForm || activeTodo.content) + '...'
+            : this.thinkingWord;
+    }
+    /**
+     * Render the spinner line (when agent running)
+     */
+    renderSpinnerLine() {
+        if (!this.spinnerState) {
+            return '';
+        }
+        const s = getStyles();
+        const elapsed = formatDuration(Date.now() - this.spinnerState.startTime);
+        const tokenStr = formatTokens(this.spinnerState.tokens);
+        const stats = s.muted(` (esc to cancel · ${elapsed} · ↓ ${tokenStr} tokens)`);
+        // Determine display text - tool name or thinking word
+        const displayText = this.currentTool
+            ? `● ${this.currentTool}`
+            : this.getDisplayText();
+        const activeTodo = this.getActiveTodo();
+        let result = '';
+        // Apply knight rider animation to the display text
+        // Uses primary color family: bold primary -> primary -> muted
+        for (let i = 0; i < displayText.length; i++) {
+            const distance = Math.abs(i - (this.animationPosition % displayText.length));
+            const char = displayText[i];
+            if (distance === 0) {
+                // Brightest - bold primary
+                result += s.primaryBold(char);
+            }
+            else if (distance === 1) {
+                // Medium - normal primary
+                result += s.primary(char);
+            }
+            else {
+                // Dimmed - muted
+                result += s.muted(char);
+            }
+        }
+        // If we have an active todo (and no tool running), show the indicator
+        if (activeTodo && !this.currentTool) {
+            result = s.primary('✱ ') + result;
+        }
+        return `${result}${stats}`;
+    }
+    /**
+     * Render the todo list items
+     */
+    renderTodoList(indented) {
+        const s = getStyles();
+        const lines = [];
+        const indent = indented ? '  ' : '';
+        for (const todo of this.todos) {
+            let checkbox;
+            let text;
+            switch (todo.status) {
+                case 'completed':
+                    checkbox = s.muted('☒');
+                    text = chalk.strikethrough(s.muted(todo.content));
+                    break;
+                case 'in_progress':
+                    checkbox = s.primary('☐');
+                    text = chalk.bold(todo.content);
+                    break;
+                case 'pending':
+                default:
+                    checkbox = s.muted('☐');
+                    text = s.muted(todo.content);
+                    break;
+            }
+            lines.push(`${indent}${checkbox} ${text}`);
+        }
+        return lines;
+    }
+}