@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/terminal-codes.js

@@ -0,0 +1,124 @@
+/**
+ * Terminal ANSI Escape Codes
+ *
+ * Constants and helper functions for ANSI escape sequences.
+ * Used by TerminalRenderer for cursor movement, scroll regions, clearing, etc.
+ *
+ * Reference: https://en.wikipedia.org/wiki/ANSI_escape_code
+ */
+// =============================================================================
+// Escape Sequence Base
+// =============================================================================
+/** Control Sequence Introducer */
+export const CSI = '\x1b[';
+/** Operating System Command (for title, etc.) */
+export const OSC = '\x1b]';
+/** String Terminator */
+export const ST = '\x07';
+// =============================================================================
+// Cursor Movement
+// =============================================================================
+/** Move cursor up N lines */
+export const cursorUp = (n) => (n > 0 ? `${CSI}${String(n)}A` : '');
+/** Move cursor down N lines */
+export const cursorDown = (n) => (n > 0 ? `${CSI}${String(n)}B` : '');
+/** Move cursor forward (right) N columns */
+export const cursorForward = (n) => (n > 0 ? `${CSI}${String(n)}C` : '');
+/** Move cursor back (left) N columns */
+export const cursorBack = (n) => (n > 0 ? `${CSI}${String(n)}D` : '');
+/** Move cursor to specific row and column (1-indexed) */
+export const cursorTo = (row, col) => `${CSI}${String(row)};${String(col)}H`;
+/** Move cursor to beginning of line */
+export const cursorToLineStart = '\r';
+/** Move cursor to specific column (1-indexed) */
+export const cursorToColumn = (col) => `${CSI}${String(col)}G`;
+/** Save cursor position */
+export const saveCursor = `${CSI}s`;
+/** Restore cursor position */
+export const restoreCursor = `${CSI}u`;
+// =============================================================================
+// Cursor Visibility
+// =============================================================================
+/** Hide cursor */
+export const hideCursor = `${CSI}?25l`;
+/** Show cursor */
+export const showCursor = `${CSI}?25h`;
+// =============================================================================
+// Scroll Regions
+// =============================================================================
+/**
+ * Set scroll region (DECSTBM - DEC Set Top and Bottom Margins)
+ *
+ * @param top - Top row of scroll region (1-indexed, inclusive)
+ * @param bottom - Bottom row of scroll region (1-indexed, inclusive)
+ *
+ * When set, scrolling only affects rows within this region.
+ * Text printed in the scroll region that would overflow scrolls the region.
+ * Content outside the region is not affected.
+ */
+export const setScrollRegion = (top, bottom) => `${CSI}${String(top)};${String(bottom)}r`;
+/**
+ * Reset scroll region to full screen
+ *
+ * Removes any scroll region restrictions.
+ * Scrolling affects the entire terminal again.
+ */
+export const resetScrollRegion = `${CSI}r`;
+// =============================================================================
+// Clearing
+// =============================================================================
+/** Clear from cursor to end of line */
+export const clearToEndOfLine = `${CSI}K`;
+/** Clear from cursor to start of line */
+export const clearToStartOfLine = `${CSI}1K`;
+/** Clear entire line */
+export const clearLine = `${CSI}2K`;
+/** Clear from cursor to end of screen */
+export const clearToEndOfScreen = `${CSI}J`;
+/** Clear from cursor to start of screen */
+export const clearToStartOfScreen = `${CSI}1J`;
+/** Clear entire screen (cursor position unchanged) */
+export const clearScreen = `${CSI}2J`;
+/** Clear entire screen and move cursor to top-left */
+export const clearScreenAndHome = `${CSI}2J${CSI}H`;
+// =============================================================================
+// Alternate Screen Buffer
+// =============================================================================
+/**
+ * Enter alternate screen buffer.
+ * Content shown here doesn't go to main scrollback.
+ * Used for modal UIs like menus, editors.
+ */
+export const enterAlternateScreen = `${CSI}?1049h`;
+/**
+ * Leave alternate screen buffer.
+ * Returns to main screen (previous content restored).
+ */
+export const leaveAlternateScreen = `${CSI}?1049l`;
+// =============================================================================
+// Mouse Tracking (disabled for CLI)
+// =============================================================================
+/** Disable all mouse tracking modes */
+export const disableMouseTracking = `${CSI}?1000l${CSI}?1002l${CSI}?1003l`;
+// =============================================================================
+// Terminal Title
+// =============================================================================
+/** Set terminal window title */
+export const setTitle = (title) => `${OSC}0;${title}${ST}`;
+// =============================================================================
+// Bell
+// =============================================================================
+/** Ring terminal bell */
+export const bell = '\x07';
+// =============================================================================
+// Composite Helpers
+// =============================================================================
+/**
+ * Position cursor at a specific location and clear to end of screen
+ * Useful for redrawing from a known position
+ */
+export const positionAndClear = (row, col) => `${cursorTo(row, col)}${clearToEndOfScreen}`;
+/**
+ * Move to row 1, column 1 (home position)
+ */
+export const cursorHome = `${CSI}H`;

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

@@ -0,0 +1,17 @@
+/**
+ * Pure line-building utility functions for TerminalUI.
+ *
+ * Extracted from terminal-ui.ts for modularity.
+ * These are pure functions with no class dependencies.
+ */
+import type { TodoItem } from './types.js';
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * e.g. 5000 → "5s", 90000 → "1m 30s"
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Build a single todo line with task number prefix, icon, content,
+ * optional owner badge, and blocked-by suffix.
+ */
+export declare function buildTodoLine(todo: TodoItem, taskNumber?: number): string;

package/dist/ui/terminal-line-builders.js

@@ -0,0 +1,42 @@
+/**
+ * Pure line-building utility functions for TerminalUI.
+ *
+ * Extracted from terminal-ui.ts for modularity.
+ * These are pure functions with no class dependencies.
+ */
+import { getStyles } from '../themes/index.js';
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * e.g. 5000 → "5s", 90000 → "1m 30s"
+ */
+export 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`;
+}
+/**
+ * Build a single todo line with task number prefix, icon, content,
+ * optional owner badge, and blocked-by suffix.
+ */
+export function buildTodoLine(todo, taskNumber) {
+    const s = getStyles();
+    const icon = todo.status === 'completed' ? '✓' :
+        todo.status === 'in_progress' ? '→' : '☐';
+    const style = todo.status === 'completed' ? s.muted :
+        todo.status === 'in_progress' ? s.info : s.muted;
+    // Task number prefix (e.g., "#1 ")
+    const prefix = taskNumber != null ? `#${String(taskNumber)} ` : '';
+    // Owner badge (skip for completed items)
+    const ownerBadge = todo.owner && todo.status !== 'completed'
+        ? s.muted(` @${todo.owner}`)
+        : '';
+    // Blocked-by suffix (skip for completed items)
+    const blockedSuffix = todo.blockedBy && todo.blockedBy.length > 0 && todo.status !== 'completed'
+        ? s.muted(` › blocked by ${todo.blockedBy.map((n) => `#${String(n)}`).join(', ')}`)
+        : '';
+    return style(`${prefix}${icon} ${todo.content}`) + ownerBadge + blockedSuffix;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Render a single PrintableItem to the console.
+ *
+ * Extracted from terminal-ui.ts for modularity.
+ * This is a nearly-pure function — the only side effect is console.log output.
+ * The 'interrupted' case returns a suggestion string instead of calling setSuggestion().
+ */
+import type { PrintableItem, TerminalUIConfig } from './terminal-types.js';
+/**
+ * Render a single item to the console.
+ * Config-aware: respects verbose, showMascot settings.
+ *
+ * @returns suggestion string for 'interrupted' items, null otherwise.
+ *          Caller should pass the suggestion to setSuggestion() if non-null.
+ */
+export declare function renderItem(item: PrintableItem, config: TerminalUIConfig): string | null;

package/dist/ui/terminal-render-item.js

@@ -0,0 +1,267 @@
+/**
+ * Render a single PrintableItem to the console.
+ *
+ * Extracted from terminal-ui.ts for modularity.
+ * This is a nearly-pure function — the only side effect is console.log output.
+ * The 'interrupted' case returns a suggestion string instead of calling setSuggestion().
+ */
+import * as terminal from './terminal.js';
+import { getStyles } from '../themes/index.js';
+import { renderMarkdown } from './conversation.js';
+import { MASCOT } from './terminal-types.js';
+/**
+ * Render a single item to the console.
+ * Config-aware: respects verbose, showMascot settings.
+ *
+ * @returns suggestion string for 'interrupted' items, null otherwise.
+ *          Caller should pass the suggestion to setSuggestion() if non-null.
+ */
+export function renderItem(item, config) {
+    const s = getStyles();
+    switch (item.type) {
+        case 'user-message':
+            console.log('');
+            console.log(s.primaryBold('> ') + item.text);
+            console.log(''); // Trailing blank for separation
+            break;
+        case 'agent-text': {
+            // Render markdown for proper formatting (headers, lists, bold, code, etc.)
+            const rendered = renderMarkdown(item.text);
+            // Prefix agent messages with mascot expression (if enabled)
+            if (config.showMascot) {
+                // Expression can be a key ('success', 'neutral') or a direct mascot string ('[◈_◈]')
+                let expr;
+                if (!item.expression) {
+                    expr = MASCOT.neutral;
+                }
+                else if (item.expression.startsWith('[')) {
+                    // Direct mascot string from team agent
+                    expr = item.expression;
+                }
+                else if (item.expression in MASCOT) {
+                    // Key lookup in MASCOT object
+                    expr = MASCOT[item.expression];
+                }
+                else {
+                    // Unknown expression key, use neutral
+                    expr = MASCOT.neutral;
+                }
+                // Only prefix the first line with mascot
+                const lines = rendered.split('\n');
+                if (lines.length > 0) {
+                    console.log(s.primary(expr) + s.muted(' > ') + lines[0]);
+                    for (let i = 1; i < lines.length; i++) {
+                        console.log(lines[i]);
+                    }
+                }
+            }
+            else {
+                console.log(rendered);
+            }
+            console.log(''); // Trailing blank for separation
+            break;
+        }
+        case 'thinking':
+            // Only show thinking in verbose mode
+            if (config.verbose) {
+                console.log(s.muted(`∴ Thinking…`));
+                console.log('');
+                // Indent thinking text
+                const lines = item.text.split('\n');
+                for (const line of lines) {
+                    console.log(s.muted(`  ${line}`));
+                }
+                console.log('');
+            }
+            // If not verbose, skip entirely (but still stored in history)
+            break;
+        case 'tool-start': {
+            // Truncate long params (e.g., long bash commands)
+            const maxLen = Math.min(60, terminal.getTerminalWidth() - 15);
+            let params = item.params;
+            // Handle multi-line params
+            const nlIdx = params.indexOf('\n');
+            if (nlIdx !== -1) {
+                const first = params.slice(0, nlIdx).trim();
+                const count = params.split('\n').length;
+                params = first.length > 0 ? `${first}… (${String(count)} lines)` : `(${String(count)} line script)`;
+            }
+            // Truncate if still too long
+            if (params.length > maxLen) {
+                params = params.slice(0, maxLen) + '…';
+            }
+            console.log(s.info(`● ${item.name}`) + s.muted(`(${params})`));
+            break;
+        }
+        case 'tool-result': {
+            // Truncate long params (e.g., long bash commands)
+            const maxParamsLen = Math.min(60, terminal.getTerminalWidth() - 15);
+            let paramsDisplay = item.params;
+            // Handle multi-line params (show first line + count)
+            const newlineIdx = paramsDisplay.indexOf('\n');
+            if (newlineIdx !== -1) {
+                const firstLine = paramsDisplay.slice(0, newlineIdx).trim();
+                const lineCount = paramsDisplay.split('\n').length;
+                paramsDisplay = firstLine.length > 0
+                    ? `${firstLine}… (${String(lineCount)} lines)`
+                    : `(${String(lineCount)} line script)`;
+            }
+            // Truncate if still too long
+            if (paramsDisplay.length > maxParamsLen) {
+                paramsDisplay = paramsDisplay.slice(0, maxParamsLen) + '…';
+            }
+            console.log(s.info(`● ${item.name}`) + s.muted(`(${paramsDisplay})`));
+            // Diff lines: render directly (already ANSI-formatted by diff.ts)
+            if (item.diffLines && item.diffLines.length > 0) {
+                const maxDiffPreview = 10;
+                if (config.verbose || item.diffLines.length <= maxDiffPreview) {
+                    for (const line of item.diffLines) {
+                        console.log(`     ${line}`);
+                    }
+                }
+                else {
+                    for (let i = 0; i < maxDiffPreview; i++) {
+                        console.log(`     ${item.diffLines[i]}`);
+                    }
+                    const hidden = item.diffLines.length - maxDiffPreview;
+                    console.log(s.muted(`     … +${String(hidden)} lines (ctrl+o to expand)`));
+                }
+            }
+            else if (item.content) {
+                const contentLines = item.content.split('\n').filter((l) => l.length > 0);
+                const maxPreviewLines = 3;
+                if (config.verbose) {
+                    // Verbose: show all lines
+                    for (const line of contentLines) {
+                        console.log(s.muted(`  ⎿  ${line}`));
+                    }
+                }
+                else if (contentLines.length > 0) {
+                    // Compact: show first few lines + hidden count
+                    const previewLines = contentLines.slice(0, maxPreviewLines);
+                    const hiddenCount = contentLines.length - maxPreviewLines;
+                    for (let i = 0; i < previewLines.length; i++) {
+                        if (i === 0) {
+                            console.log(s.muted(`  ⎿  ${previewLines[i]}`));
+                        }
+                        else {
+                            console.log(s.muted(`     ${previewLines[i]}`));
+                        }
+                    }
+                    if (hiddenCount > 0) {
+                        console.log(s.muted(`     … +${String(hiddenCount)} lines`) + s.muted(' (ctrl+o to expand)'));
+                    }
+                }
+                else {
+                    // No output lines
+                    const expandHint = s.muted(' (ctrl+o to expand)');
+                    if (item.success === false) {
+                        console.log(s.error(`  ⎿  ${item.summary}`) + expandHint);
+                    }
+                    else {
+                        console.log(s.muted(`  ⎿  ${item.summary}`) + expandHint);
+                    }
+                }
+            }
+            else {
+                // No content, just show summary
+                if (item.success === false) {
+                    console.log(s.error(`  ⎿  ${item.summary}`));
+                }
+                else {
+                    console.log(s.muted(`  ⎿  ${item.summary}`));
+                }
+            }
+            console.log('');
+            break;
+        }
+        case 'tool-error': {
+            // Truncate long params
+            const maxErrLen = Math.min(60, terminal.getTerminalWidth() - 15);
+            let errParams = item.params;
+            const errNlIdx = errParams.indexOf('\n');
+            if (errNlIdx !== -1) {
+                const errFirst = errParams.slice(0, errNlIdx).trim();
+                const errCount = errParams.split('\n').length;
+                errParams = errFirst.length > 0 ? `${errFirst}… (${String(errCount)} lines)` : `(${String(errCount)} line script)`;
+            }
+            if (errParams.length > maxErrLen) {
+                errParams = errParams.slice(0, maxErrLen) + '…';
+            }
+            console.log(s.info(`● ${item.name}`) + s.muted(`(${errParams})`));
+            console.log(s.error(`  ⎿  Error: ${item.error}`));
+            console.log('');
+            break;
+        }
+        case 'interrupted': {
+            // Show what was ongoing (if provided)
+            if (item.action) {
+                console.log(s.info(`● ${item.action}`));
+            }
+            else {
+                // No action means interrupted right after user message.
+                // Move cursor up to consume the trailing blank from user-message.
+                //
+                // ⚠️ WARNING: This cursor manipulation is fragile!
+                // It assumes the previous item was user-message which adds a trailing blank.
+                // If we add items that don't add trailing blanks, or if the rendering
+                // order changes, this could cause visual artifacts (overwriting content).
+                // If issues arise, consider tracking the last printed item type instead.
+                process.stdout.write('\x1b[1A'); // Move up one line
+            }
+            // Show interrupted line with mascot
+            const suggestion = item.suggestion ?? 'What should I do instead?';
+            console.log(s.warning(`  ⎿  ${MASCOT.confused} Interrupted - ${suggestion}`));
+            console.log('');
+            // Return suggestion so caller can set it as ghost text
+            return suggestion;
+        }
+        case 'error':
+            console.log(s.error(`${MASCOT.error} ${item.message}`));
+            console.log('');
+            break;
+        case 'success':
+            console.log(s.success(`${MASCOT.success} ${item.message}`));
+            console.log('');
+            break;
+        case 'info':
+            console.log(s.info(item.message));
+            console.log('');
+            break;
+        case 'warning':
+            console.log(s.warning(item.message));
+            console.log('');
+            break;
+        case 'turn-summary': {
+            // Compact summary line: ── 45s · ↓ 2.3k ↑ 1.1k · 5 tools ──
+            const line = s.muted(`── ${item.parts.join(' · ')} ──`);
+            console.log(line);
+            console.log('');
+            break;
+        }
+        case 'raw':
+            console.log(item.text);
+            break;
+        case 'raw-lines':
+            for (const line of item.lines) {
+                console.log(line);
+            }
+            break;
+        case 'background-agent': {
+            // Background agent output with mascot label
+            // Format: [◈_◈] $arch: text - mascot followed by agent reference
+            const bgLabel = s.muted(`${item.mascot} $${item.agentId}:`);
+            // Render markdown for proper formatting
+            const bgRendered = renderMarkdown(item.text);
+            const bgLines = bgRendered.split('\n');
+            if (bgLines.length > 0) {
+                console.log(`${bgLabel} ${bgLines[0]}`);
+                for (let i = 1; i < bgLines.length; i++) {
+                    console.log(bgLines[i]);
+                }
+            }
+            break;
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,220 @@
+/**
+ * @deprecated DEAD CODE — This class is never instantiated. Do NOT modify this file.
+ *
+ * The active render pipeline is in TerminalUI (src/ui/terminal-ui.ts).
+ * TerminalUI handles all rendering, keyboard input, overlays, and footer display.
+ * All UI changes should go there.
+ *
+ * --- Original description ---
+ * Terminal Renderer
+ *
+ * Single point of terminal output. All rendering goes through this class.
+ * Eliminates race conditions by ensuring only one writer.
+ */
+import { EventEmitter } from 'events';
+import { RenderMode, type ModeTransition } from './render-modes.js';
+import type { ProviderRegistry } from './providers/types.js';
+import type { Footer } from './footer.js';
+export { RenderMode } from './render-modes.js';
+export interface TerminalRendererOptions {
+    /** Initial render mode (default: REPL) */
+    initialMode?: RenderMode;
+    /** Render debounce in milliseconds (default: 16 = ~60fps) */
+    renderDebounceMs?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Use scroll regions for footer isolation (default: false)
+     * When false, uses console.log for scroll content (legacy mode)
+     * When true, uses ANSI scroll regions (requires footer integration)
+     */
+    useScrollRegions?: boolean;
+}
+export interface TerminalRendererEvents {
+    'mode-change': (transition: ModeTransition) => void;
+    'resize': (cols: number, rows: number) => void;
+    'render': (mode: RenderMode) => void;
+    'error': (error: Error) => void;
+}
+export declare class TerminalRenderer extends EventEmitter {
+    private readonly renderDebounceMs;
+    private readonly debug;
+    private readonly useScrollRegions;
+    private mode;
+    private terminalRows;
+    private terminalCols;
+    private footerHeight;
+    private scrollRegionBottom;
+    private isRendering;
+    private renderPending;
+    private renderTimer;
+    private started;
+    private simpleMode;
+    private pendingScrollContent;
+    private scrollCursorRow;
+    private providers;
+    private footer;
+    private resizeHandler;
+    private renderLoopTimer;
+    private readonly renderLoopInterval;
+    constructor(options?: TerminalRendererOptions);
+    /**
+     * Start the renderer.
+     * Sets up terminal state and begins render loop.
+     */
+    start(): void;
+    /**
+     * Start the render loop (for scroll region mode)
+     * Polls footer for changes and re-renders
+     */
+    private startRenderLoop;
+    /**
+     * Stop the render loop
+     */
+    private stopRenderLoop;
+    /**
+     * Stop the renderer.
+     * Cleans up terminal state and stops render loop.
+     */
+    stop(): void;
+    /**
+     * Check if renderer is running
+     */
+    isStarted(): boolean;
+    /**
+     * Get current render mode
+     */
+    getMode(): RenderMode;
+    /**
+     * Switch to a different render mode
+     */
+    setMode(newMode: RenderMode, reason?: string): void;
+    /**
+     * Set up terminal for a specific mode
+     */
+    private setupMode;
+    /**
+     * Clean up terminal state when leaving a mode
+     */
+    private cleanupMode;
+    /**
+     * Register content providers
+     */
+    setProviders(providers: Partial<ProviderRegistry>): void;
+    /**
+     * Get a specific provider
+     */
+    getProvider<K extends keyof ProviderRegistry>(key: K): ProviderRegistry[K] | undefined;
+    /**
+     * Set the Footer instance for scroll region rendering
+     * When useScrollRegions is true, TerminalRenderer uses footer.getFooterLines()
+     * and manages the scroll region. Footer's own render loop is disabled.
+     */
+    setFooter(footer: Footer): void;
+    /**
+     * Get the connected Footer instance
+     */
+    getFooter(): Footer | null;
+    /**
+     * Queue content for scroll zone (REPL mode only)
+     * Content will be written on next render
+     *
+     * In legacy mode (useScrollRegions=false), writes immediately via console.log
+     * In scroll region mode, queues for next render cycle
+     */
+    appendToScrollZone(content: string | string[]): void;
+    /**
+     * Flush pending scroll content to terminal
+     *
+     * Uses tracked scroll position to append content naturally.
+     * When content would exceed scroll region, scrolling occurs automatically.
+     */
+    private flushScrollContent;
+    /**
+     * Request a render (debounced)
+     */
+    requestRender(): void;
+    /**
+     * Force immediate render (bypasses debounce)
+     */
+    forceRender(): void;
+    /**
+     * Main render method
+     */
+    private doRender;
+    /**
+     * Render in simple mode (non-TTY)
+     */
+    private renderSimpleMode;
+    /**
+     * Render MENU mode
+     */
+    private renderMenuMode;
+    /**
+     * Render REPL mode
+     */
+    private renderReplMode;
+    /**
+     * Build footer lines from providers
+     */
+    private buildFooterLines;
+    /**
+     * Calculate physical height of lines (accounting for wrapping)
+     */
+    private calculatePhysicalHeight;
+    /**
+     * Adjust scroll region when footer height changes
+     */
+    private adjustScrollRegion;
+    /**
+     * Render footer content
+     */
+    private renderFooter;
+    /**
+     * Position cursor for input (provider-based)
+     */
+    private positionCursor;
+    /**
+     * Position cursor for Footer integration (scroll region mode)
+     */
+    private positionFooterCursor;
+    /**
+     * Render OVERLAY mode
+     */
+    private renderOverlayMode;
+    /**
+     * Handle terminal resize
+     */
+    handleResize(): void;
+    /**
+     * Update terminal dimensions from stdout
+     */
+    private updateDimensions;
+    /**
+     * Get current terminal dimensions
+     */
+    getDimensions(): {
+        rows: number;
+        cols: number;
+    };
+    /**
+     * Write to stdout (single output point)
+     */
+    write(text: string): void;
+    /**
+     * Route keyboard input to appropriate handler
+     */
+    handleKeyboard(key: Buffer): void;
+    /**
+     * Log debug message if debug mode enabled
+     */
+    private log;
+}
+/**
+ * Get or create the default renderer instance
+ */
+export declare function getRenderer(options?: TerminalRendererOptions): TerminalRenderer;
+/**
+ * Reset the default renderer (for testing)
+ */
+export declare function resetRenderer(): void;