@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/base/overlay-base-v2.js

@@ -0,0 +1,246 @@
+/**
+ * Base Overlay V2
+ *
+ * Abstract base class for overlays using the new Overlay interface.
+ * Designed to work with TerminalUI's overlay management.
+ *
+ * Key differences from BaseOverlay:
+ * - render() returns OverlayContent, not string[]
+ * - handleKey() returns OverlayAction, not void
+ * - TerminalUI manages the render loop (not the overlay itself)
+ * - Lifecycle via onMount()/onUnmount() instead of show()/close()
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState {
+ *   selectedIndex: number;
+ * }
+ *
+ * class MyOverlay extends BaseOverlayV2<MyState, string | null> {
+ *   readonly type = 'inline';
+ *   readonly id = 'my-overlay';
+ *
+ *   constructor() {
+ *     super({ selectedIndex: 0 });
+ *   }
+ *
+ *   protected renderContent(context: RenderContext): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ' Content here...',
+ *       ...this.renderFooter('↑↓ Navigate · Enter Select · q/Esc Cancel')
+ *     ];
+ *   }
+ *
+ *   handleKey(key: KeyEvent): OverlayAction<string | null> {
+ *     if (key.name === 'escape' || key.name === 'q') {
+ *       return this.close(null);
+ *     }
+ *     // ...
+ *     return this.rerender();
+ *   }
+ * }
+ * ```
+ */
+// =============================================================================
+// BaseOverlayV2 Abstract Class
+// =============================================================================
+/**
+ * Abstract base class for overlays using the new Overlay interface.
+ *
+ * @template TState - State interface for the overlay
+ * @template TResult - Return type when overlay closes
+ */
+export class BaseOverlayV2 {
+    /** Current overlay state */
+    state;
+    /** Cached styles from last render context */
+    styles = null;
+    /** Cached terminal width from last render context */
+    termWidth = 80;
+    /** Minimum height for stable rendering (prevents visual jitter) */
+    minHeight = 0;
+    /**
+     * Create a new overlay instance.
+     *
+     * @param initialState - Initial state
+     */
+    constructor(initialState) {
+        this.state = initialState;
+    }
+    // ===========================================================================
+    // Overlay Interface Implementation
+    // ===========================================================================
+    /**
+     * Get current state.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Render the overlay.
+     * Calls renderContent() and wraps in OverlayContent.
+     */
+    render(context) {
+        // Cache context values for helper methods
+        this.styles = context.styles;
+        this.termWidth = context.width;
+        // Get content from subclass
+        const lines = this.renderContent(context);
+        // Include minHeight for stable rendering (prevents visual jitter when content height varies)
+        return this.minHeight > 0 ? { lines, minHeight: this.minHeight } : { lines };
+    }
+    // ===========================================================================
+    // Protected Methods - Action Helpers
+    // ===========================================================================
+    /**
+     * Return action to close with result.
+     */
+    close(result) {
+        return { type: 'close', result };
+    }
+    /**
+     * Return action to close as cancelled.
+     */
+    cancel() {
+        return { type: 'close', cancelled: true };
+    }
+    /**
+     * Return action to re-render.
+     */
+    rerender() {
+        return { type: 'render' };
+    }
+    /**
+     * Return action for no change.
+     */
+    noAction() {
+        return { type: 'none' };
+    }
+    /**
+     * Return action to push a sub-overlay.
+     */
+    push(overlay) {
+        return { type: 'push', overlay };
+    }
+    /**
+     * Return action to pop back to parent.
+     */
+    pop() {
+        return { type: 'pop' };
+    }
+    /**
+     * Get the cached styles (or throw if not available).
+     */
+    getStyles() {
+        if (!this.styles) {
+            throw new Error('Styles not available - render() must be called first');
+        }
+        return this.styles;
+    }
+    /**
+     * Render a standard header with border and title.
+     *
+     * @param title - Main title
+     * @param subtitle - Optional subtitle (shown in muted)
+     * @returns Array of lines
+     */
+    renderHeader(title, subtitle) {
+        const s = this.getStyles();
+        const border = s.muted('─'.repeat(Math.max(1, this.termWidth - 1)));
+        const lines = [border];
+        if (subtitle) {
+            lines.push(' ' + s.primaryBold(title) + s.muted(`  ${subtitle}`));
+        }
+        else {
+            lines.push(' ' + s.primaryBold(title));
+        }
+        lines.push('');
+        return lines;
+    }
+    /**
+     * Render a standard footer with hints and border.
+     *
+     * @param hints - Keyboard hints string (e.g., "↑↓ Navigate · Enter Select")
+     * @returns Array of lines
+     */
+    renderFooter(hints) {
+        const s = this.getStyles();
+        const border = s.muted('─'.repeat(Math.max(1, this.termWidth - 1)));
+        return [border, s.muted('  ' + hints), border];
+    }
+    /**
+     * Render a border line spanning terminal width.
+     */
+    renderBorder() {
+        const s = this.getStyles();
+        return s.muted('─'.repeat(Math.max(1, this.termWidth - 1)));
+    }
+    // ===========================================================================
+    // Protected Methods - Key Helpers
+    // ===========================================================================
+    /**
+     * Check if key is a close key (escape or 'q').
+     */
+    isCloseKey(key) {
+        return key.name === 'escape' || key.name === 'q';
+    }
+    /**
+     * Check if key is Ctrl+C.
+     */
+    isInterruptKey(key) {
+        return key.ctrl && key.name === 'c';
+    }
+    /**
+     * Check if key is Enter/Return.
+     */
+    isEnterKey(key) {
+        return key.name === 'return';
+    }
+    /**
+     * Check if key is up arrow or 'k' (vim).
+     */
+    isUpKey(key) {
+        return key.name === 'up' || key.name === 'k';
+    }
+    /**
+     * Check if key is down arrow or 'j' (vim).
+     */
+    isDownKey(key) {
+        return key.name === 'down' || key.name === 'j';
+    }
+    /**
+     * Check if key is left arrow or 'h' (vim).
+     */
+    isLeftKey(key) {
+        return key.name === 'left' || key.name === 'h';
+    }
+    /**
+     * Check if key is right arrow or 'l' (vim).
+     */
+    isRightKey(key) {
+        return key.name === 'right' || key.name === 'l';
+    }
+    /**
+     * Check if key is Tab.
+     */
+    isTabKey(key) {
+        return key.name === 'tab' && !key.shift;
+    }
+    /**
+     * Check if key is Shift+Tab.
+     */
+    isShiftTabKey(key) {
+        return key.name === 'tab' && key.shift;
+    }
+    /**
+     * Get number if key is 1-9.
+     */
+    getNumberKey(key) {
+        const num = parseInt(key.name, 10);
+        if (num >= 1 && num <= 9) {
+            return num;
+        }
+        return null;
+    }
+}

package/dist/ui/base/overlay-base.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Base Overlay Class
+ *
+ * Abstract base class for all overlays. Provides:
+ * - Lifecycle management (setup, cleanup)
+ * - Rendering infrastructure (frame, header, footer)
+ * - State management
+ * - Common key handling patterns
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState extends OverlayState {
+ *   selectedIndex: number;
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, string | null> {
+ *   constructor() {
+ *     super({ lineCount: 0, maxLineCount: 0, selectedIndex: 0 });
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ' Content here...',
+ *       ...this.renderFooter('↑↓ Navigate · Enter Select · q/Esc Cancel')
+ *     ];
+ *   }
+ *
+ *   handleKey(data: Buffer): void {
+ *     if (isClose(data)) { this.close(null); return; }
+ *     // ... handle keys
+ *   }
+ * }
+ *
+ * // Export function for backward compatibility
+ * export async function showMyOverlay(): Promise<string | null> {
+ *   return new MyOverlay().show();
+ * }
+ * ```
+ */
+import { getStyles } from '../../themes/index.js';
+import { OverlayLifecycle } from './overlay-lifecycle.js';
+import type { OverlayState, OverlayConfig } from './overlay-types.js';
+export type { OverlayState, OverlayConfig };
+/**
+ * Abstract base class for overlays.
+ *
+ * @template TState - State interface (must extend OverlayState)
+ * @template TResult - Return type when overlay closes
+ */
+export declare abstract class BaseOverlay<TState extends OverlayState, TResult = void> {
+    /** Current overlay state */
+    protected state: TState;
+    /** Lifecycle manager */
+    protected lifecycle: OverlayLifecycle;
+    /** Overlay configuration */
+    protected config: OverlayConfig;
+    /** Theme styles - lazily initialized */
+    private _styles;
+    /** Promise resolver for show() */
+    private resolvePromise;
+    /**
+     * Create a new overlay instance.
+     *
+     * @param initialState - Initial state (must include lineCount: 0, maxLineCount: 0)
+     * @param config - Optional configuration
+     */
+    constructor(initialState: TState, config?: OverlayConfig);
+    /**
+     * Get theme styles (cached).
+     */
+    protected get styles(): ReturnType<typeof getStyles>;
+    /**
+     * Show the overlay and wait for it to close.
+     * This is the main entry point.
+     *
+     * @returns Promise that resolves when the overlay closes
+     */
+    show(): Promise<TResult>;
+    /**
+     * Close the overlay with a result.
+     *
+     * @param result - Value to return from show() (optional for void result type)
+     */
+    protected close(result?: TResult): void;
+    /**
+     * Re-render the overlay after state changes.
+     * Call this after modifying state.
+     */
+    protected update(): void;
+    /**
+     * Reset render state after a screen change.
+     * Call this after pushing/popping screens that may have cleared the screen.
+     * This ensures the next render starts fresh without trying to restore old cursor positions.
+     */
+    protected resetRenderState(): void;
+    /**
+     * Render the full frame (clear + render + pad).
+     * Returns the number of PHYSICAL lines rendered.
+     *
+     * IMPORTANT: Tracks physical lines (accounting for wrapped content)
+     * not logical lines (array entries). This ensures proper clearing
+     * when navigating between screens of different heights.
+     */
+    protected renderFrame(): number;
+    /**
+     * Render a standard header with border and title.
+     *
+     * @param title - Main title
+     * @param subtitle - Optional subtitle (shown in muted)
+     * @returns Array of lines
+     */
+    protected renderHeader(title: string, subtitle?: string): string[];
+    /**
+     * Render a standard footer with hints and border.
+     *
+     * @param hints - Keyboard hints string (e.g., "↑↓ Navigate · Enter Select")
+     * @returns Array of lines
+     */
+    protected renderFooter(hints: string): string[];
+    /**
+     * Render a border line spanning terminal width.
+     */
+    protected renderBorder(): string;
+    /**
+     * Render the overlay content.
+     * Called automatically by renderFrame().
+     *
+     * @returns Array of lines to render
+     */
+    abstract render(): string[];
+    /**
+     * Handle a key press.
+     * Called automatically when the user presses a key.
+     *
+     * Common pattern:
+     * ```typescript
+     * handleKey(data: Buffer): void {
+     *   // Global close keys
+     *   if (isClose(data)) {
+     *     this.close(null);
+     *     return;
+     *   }
+     *
+     *   // Feature-specific key handling
+     *   // ...
+     *
+     *   // Re-render if state changed
+     *   this.update();
+     * }
+     * ```
+     *
+     * @param data - Raw key buffer
+     */
+    abstract handleKey(data: Buffer): void;
+}

package/dist/ui/base/overlay-base.js

@@ -0,0 +1,238 @@
+/**
+ * Base Overlay Class
+ *
+ * Abstract base class for all overlays. Provides:
+ * - Lifecycle management (setup, cleanup)
+ * - Rendering infrastructure (frame, header, footer)
+ * - State management
+ * - Common key handling patterns
+ *
+ * Usage:
+ * ```typescript
+ * interface MyState extends OverlayState {
+ *   selectedIndex: number;
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, string | null> {
+ *   constructor() {
+ *     super({ lineCount: 0, maxLineCount: 0, selectedIndex: 0 });
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ' Content here...',
+ *       ...this.renderFooter('↑↓ Navigate · Enter Select · q/Esc Cancel')
+ *     ];
+ *   }
+ *
+ *   handleKey(data: Buffer): void {
+ *     if (isClose(data)) { this.close(null); return; }
+ *     // ... handle keys
+ *   }
+ * }
+ *
+ * // Export function for backward compatibility
+ * export async function showMyOverlay(): Promise<string | null> {
+ *   return new MyOverlay().show();
+ * }
+ * ```
+ */
+import * as terminal from '../terminal.js';
+import { getStyles } from '../../themes/index.js';
+import { OverlayLifecycle } from './overlay-lifecycle.js';
+import { debugLog } from '../../utils/debug-log.js';
+// =============================================================================
+// BaseOverlay Abstract Class
+// =============================================================================
+/**
+ * Abstract base class for overlays.
+ *
+ * @template TState - State interface (must extend OverlayState)
+ * @template TResult - Return type when overlay closes
+ */
+export class BaseOverlay {
+    /** Current overlay state */
+    state;
+    /** Lifecycle manager */
+    lifecycle;
+    /** Overlay configuration */
+    config;
+    /** Theme styles - lazily initialized */
+    _styles = null;
+    /** Promise resolver for show() */
+    resolvePromise = null;
+    /**
+     * Create a new overlay instance.
+     *
+     * @param initialState - Initial state (must include lineCount: 0, maxLineCount: 0)
+     * @param config - Optional configuration
+     */
+    constructor(initialState, config = {}) {
+        this.state = initialState;
+        this.config = config;
+        this.lifecycle = new OverlayLifecycle(config, (data) => {
+            this.handleKey(data);
+        });
+    }
+    // ===========================================================================
+    // Protected Getters
+    // ===========================================================================
+    /**
+     * Get theme styles (cached).
+     */
+    get styles() {
+        if (!this._styles) {
+            this._styles = getStyles();
+        }
+        return this._styles;
+    }
+    // ===========================================================================
+    // Public Entry Point
+    // ===========================================================================
+    /**
+     * Show the overlay and wait for it to close.
+     * This is the main entry point.
+     *
+     * @returns Promise that resolves when the overlay closes
+     */
+    async show() {
+        debugLog('BaseOverlay:show', 'start');
+        // Setup lifecycle FIRST (pause footer, raw mode, hide cursor)
+        // This is done HERE (not in REPL) so constructor I/O doesn't cause blank screen
+        debugLog('BaseOverlay:show', 'calling lifecycle.setup');
+        this.lifecycle.setup();
+        debugLog('BaseOverlay:show', 'lifecycle.setup done');
+        // Save cursor position for render updates
+        terminal.saveCursor();
+        debugLog('BaseOverlay:show', 'cursor saved');
+        // Initial render
+        debugLog('BaseOverlay:show', 'calling renderFrame');
+        this.state.lineCount = this.renderFrame();
+        this.state.maxLineCount = this.state.lineCount;
+        debugLog('BaseOverlay:show', `renderFrame done, ${String(this.state.lineCount)} lines`);
+        // Return promise that resolves when closed
+        return new Promise((resolve) => {
+            this.resolvePromise = resolve;
+        });
+    }
+    // ===========================================================================
+    // Protected Methods - Lifecycle
+    // ===========================================================================
+    /**
+     * Close the overlay with a result.
+     *
+     * @param result - Value to return from show() (optional for void result type)
+     */
+    close(result) {
+        this.lifecycle.cleanup(this.state.maxLineCount);
+        if (this.resolvePromise) {
+            this.resolvePromise(result);
+            this.resolvePromise = null;
+        }
+    }
+    /**
+     * Re-render the overlay after state changes.
+     * Call this after modifying state.
+     */
+    update() {
+        this.state.lineCount = this.renderFrame();
+        this.state.maxLineCount = Math.max(this.state.maxLineCount, this.state.lineCount);
+    }
+    /**
+     * Reset render state after a screen change.
+     * Call this after pushing/popping screens that may have cleared the screen.
+     * This ensures the next render starts fresh without trying to restore old cursor positions.
+     */
+    resetRenderState() {
+        // Reset line tracking so renderFrame() doesn't try to restore cursor
+        this.state.lineCount = 0;
+        this.state.maxLineCount = 0;
+        // Explicitly move cursor to home and save position
+        // This ensures we're at (0,0) regardless of what clearScreen() did
+        process.stdout.write('\x1b[H');
+        terminal.saveCursor();
+    }
+    // ===========================================================================
+    // Protected Methods - Rendering
+    // ===========================================================================
+    /**
+     * Render the full frame (clear + render + pad).
+     * Returns the number of PHYSICAL lines rendered.
+     *
+     * IMPORTANT: Tracks physical lines (accounting for wrapped content)
+     * not logical lines (array entries). This ensures proper clearing
+     * when navigating between screens of different heights.
+     */
+    renderFrame() {
+        // Get content from subclass
+        const lines = this.render();
+        const termWidth = terminal.getTerminalWidth();
+        // Calculate physical lines of content (accounts for wrapped lines)
+        let physicalLines = terminal.totalPhysicalLines(lines, termWidth);
+        // Position cursor for render
+        if (this.state.lineCount > 0) {
+            // Normal re-render: restore cursor to saved position, clear to end
+            terminal.restoreCursor();
+            terminal.clearToEndOfScreen();
+        }
+        // Note: when lineCount is 0, cursor should already be at correct position
+        // (either from initial show() or from resetRenderState() after clearScreen)
+        // Pad to minimum height for consistent sizing
+        const minHeight = this.config.minHeight ?? 0;
+        while (physicalLines < minHeight) {
+            lines.push('');
+            physicalLines++;
+        }
+        // Also pad to previous max to prevent shrinking
+        while (physicalLines < this.state.maxLineCount) {
+            lines.push('');
+            physicalLines++;
+        }
+        // Render
+        terminal.write(lines.join('\n'));
+        return physicalLines;
+    }
+    /**
+     * Render a standard header with border and title.
+     *
+     * @param title - Main title
+     * @param subtitle - Optional subtitle (shown in muted)
+     * @returns Array of lines
+     */
+    renderHeader(title, subtitle) {
+        const cols = terminal.getTerminalWidth();
+        const border = this.styles.muted('─'.repeat(Math.max(1, cols - 1)));
+        const lines = [border];
+        if (subtitle) {
+            lines.push(' ' + this.styles.primaryBold(title) + this.styles.muted(`  ${subtitle}`));
+        }
+        else {
+            lines.push(' ' + this.styles.primaryBold(title));
+        }
+        lines.push('');
+        return lines;
+    }
+    /**
+     * Render a standard footer with hints and border.
+     *
+     * @param hints - Keyboard hints string (e.g., "↑↓ Navigate · Enter Select")
+     * @returns Array of lines
+     */
+    renderFooter(hints) {
+        const cols = terminal.getTerminalWidth();
+        const border = this.styles.muted('─'.repeat(Math.max(1, cols - 1)));
+        return [
+            '',
+            this.styles.muted(' ' + hints),
+            border,
+        ];
+    }
+    /**
+     * Render a border line spanning terminal width.
+     */
+    renderBorder() {
+        const cols = terminal.getTerminalWidth();
+        return this.styles.muted('─'.repeat(Math.max(1, cols - 1)));
+    }
+}

package/dist/ui/base/overlay-lifecycle.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Overlay Lifecycle Manager
+ *
+ * Handles the common setup and cleanup operations for all overlays:
+ * - Raw mode management
+ * - Cursor visibility
+ * - Event listener setup/teardown
+ * - Line clearing on close
+ */
+import type { OverlayConfig } from './overlay-types.js';
+/**
+ * Callback for key data events.
+ */
+export type KeyHandler = (data: Buffer) => void;
+/**
+ * Manages the lifecycle of an overlay.
+ *
+ * Usage:
+ * ```typescript
+ * const lifecycle = new OverlayLifecycle(config, (data) => handleKey(data));
+ *
+ * // Setup - call before first render
+ * lifecycle.setup();
+ *
+ * // ... overlay logic ...
+ *
+ * // Cleanup - call when closing
+ * lifecycle.cleanup(lineCount);
+ * ```
+ */
+export declare class OverlayLifecycle {
+    private readonly config;
+    private readonly onKey;
+    private wasRawMode;
+    private dataHandler;
+    private isActive;
+    constructor(config: OverlayConfig, onKey: KeyHandler);
+    /**
+     * Setup the overlay for interaction.
+     * Call this before the first render.
+     */
+    setup(): void;
+    /**
+     * Cleanup after overlay closes.
+     * Restores terminal state and removes event listeners.
+     *
+     * @param lineCount - Number of lines to clear (typically maxLineCount)
+     */
+    cleanup(lineCount: number): void;
+    /**
+     * Check if the lifecycle is currently active.
+     */
+    isSetUp(): boolean;
+}
+/**
+ * Create a standard overlay setup without using the class.
+ * Returns a cleanup function.
+ *
+ * This is useful for simple overlays that don't need the full class.
+ *
+ * @param onKey - Key handler callback
+ * @param config - Optional configuration
+ * @returns Cleanup function
+ */
+export declare function setupOverlay(onKey: KeyHandler, config?: OverlayConfig): (lineCount?: number) => void;