@compilr-dev/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,159 @@
+/**
+ * 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 * as terminal from '../terminal.js';
+import { pauseForOverlay, resumeAfterOverlay } from '../overlay-controller.js';
+import { debugLog } from '../../utils/debug-log.js';
+// =============================================================================
+// OverlayLifecycle Class
+// =============================================================================
+/**
+ * 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 class OverlayLifecycle {
+    config;
+    onKey;
+    wasRawMode = false;
+    dataHandler = null;
+    isActive = false;
+    constructor(config, onKey) {
+        this.config = config;
+        this.onKey = onKey;
+    }
+    // ===========================================================================
+    // Public Methods
+    // ===========================================================================
+    /**
+     * Setup the overlay for interaction.
+     * Call this before the first render.
+     */
+    setup() {
+        if (this.isActive) {
+            return; // Already set up
+        }
+        debugLog('OverlayLifecycle:setup', 'start');
+        // Pause footer animation and clear it
+        // This is done HERE (not in REPL) so constructor I/O doesn't cause blank screen
+        pauseForOverlay();
+        debugLog('OverlayLifecycle:setup', 'footer paused');
+        // Save current raw mode state
+        this.wasRawMode = process.stdin.isRaw;
+        // Enter raw mode for character-by-character input
+        terminal.enableRawMode();
+        // Hide cursor (unless config says not to)
+        if (this.config.hideCursor !== false) {
+            terminal.hideCursor();
+        }
+        // Setup key handler
+        this.dataHandler = (data) => {
+            if (this.isActive) {
+                this.onKey(data);
+            }
+        };
+        process.stdin.on('data', this.dataHandler);
+        this.isActive = true;
+        debugLog('OverlayLifecycle:setup', 'done');
+    }
+    /**
+     * Cleanup after overlay closes.
+     * Restores terminal state and removes event listeners.
+     *
+     * @param lineCount - Number of lines to clear (typically maxLineCount)
+     */
+    cleanup(lineCount) {
+        if (!this.isActive) {
+            return; // Already cleaned up
+        }
+        debugLog('OverlayLifecycle:cleanup', 'start');
+        this.isActive = false;
+        // Remove event listener
+        if (this.dataHandler) {
+            process.stdin.removeListener('data', this.dataHandler);
+            this.dataHandler = null;
+        }
+        // Clear the overlay content
+        if (lineCount > 0) {
+            terminal.clearLinesAbove(lineCount);
+        }
+        // Restore cursor visibility
+        if (this.config.hideCursor !== false) {
+            terminal.showCursor();
+        }
+        // Restore raw mode state
+        if (!this.wasRawMode) {
+            terminal.disableRawMode();
+        }
+        // Resume footer animation
+        resumeAfterOverlay();
+        debugLog('OverlayLifecycle:cleanup', 'footer resumed');
+    }
+    /**
+     * Check if the lifecycle is currently active.
+     */
+    isSetUp() {
+        return this.isActive;
+    }
+}
+// =============================================================================
+// Standalone Helper Functions
+// =============================================================================
+/**
+ * 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 function setupOverlay(onKey, config = {}) {
+    const wasRawMode = process.stdin.isRaw;
+    // Pause footer animation and clear it
+    pauseForOverlay();
+    // Enter raw mode
+    terminal.enableRawMode();
+    // Hide cursor
+    if (config.hideCursor !== false) {
+        terminal.hideCursor();
+    }
+    // Setup handler
+    const dataHandler = (data) => {
+        onKey(data);
+    };
+    process.stdin.on('data', dataHandler);
+    // Return cleanup function
+    return (lineCount = 0) => {
+        process.stdin.removeListener('data', dataHandler);
+        if (lineCount > 0) {
+            terminal.clearLinesAbove(lineCount);
+        }
+        if (config.hideCursor !== false) {
+            terminal.showCursor();
+        }
+        if (!wasRawMode) {
+            terminal.disableRawMode();
+        }
+        // Resume footer animation
+        resumeAfterOverlay();
+    };
+}

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

@@ -0,0 +1,185 @@
+/**
+ * Overlay Type Definitions
+ *
+ * Core interfaces and types for the overlay system.
+ * These provide the foundation for BaseOverlay and composable features.
+ */
+/**
+ * Result of handling a key press within a feature or overlay.
+ *
+ * - `handled: false` - Key was not handled, try next handler
+ * - `handled: true` - Key was handled
+ *   - `action: 'render'` - State changed, re-render needed
+ *   - `action: 'close'` - Overlay should close
+ *   - No action - Key was consumed but no visual change
+ */
+export type KeyResult = {
+    handled: false;
+} | {
+    handled: true;
+    action?: 'render' | 'close';
+};
+/**
+ * Result of handling a key press within a screen.
+ *
+ * - `action: 'stay'` - Stay on current screen (optionally re-render)
+ * - `action: 'push'` - Push a new screen onto the stack
+ * - `action: 'pop'` - Go back to previous screen
+ * - `action: 'close'` - Close the entire overlay with a result
+ */
+export type ScreenResult<TResult = unknown> = {
+    action: 'stay';
+    render?: boolean;
+} | {
+    action: 'push';
+    screen: BaseScreenInterface;
+} | {
+    action: 'pop';
+} | {
+    action: 'close';
+    result: TResult;
+};
+/**
+ * Base state that all overlays must include.
+ * Tracks line counts for proper terminal clearing.
+ */
+export interface OverlayState {
+    /** Current rendered line count */
+    lineCount: number;
+    /** Maximum line count seen (for clearing) */
+    maxLineCount: number;
+}
+/**
+ * State for list-based selection.
+ */
+export interface ListState {
+    /** Currently selected index */
+    selectedIndex: number;
+}
+/**
+ * State for tabbed overlays.
+ */
+export interface TabState {
+    /** Current tab index (0-based) */
+    currentTab: number;
+}
+/**
+ * State for paginated overlays.
+ */
+export interface PaginationState {
+    /** Current page (0-based) */
+    currentPage: number;
+    /** Items per page */
+    pageSize: number;
+    /** Total number of items */
+    totalItems: number;
+}
+/**
+ * State for text input.
+ */
+export interface InputState {
+    /** Current input buffer */
+    inputBuffer: string;
+    /** Whether input mode is active */
+    isInputMode: boolean;
+    /** Validation error message (if any) */
+    error?: string | null;
+}
+/**
+ * State for search functionality.
+ */
+export interface SearchState {
+    /** Current search query */
+    searchQuery: string;
+    /** Whether search mode is active */
+    isSearchMode: boolean;
+}
+/**
+ * Configuration options for an overlay.
+ */
+export interface OverlayConfig {
+    /** Minimum height in lines (for consistent sizing) */
+    minHeight?: number;
+    /** Whether to show border (default: true) */
+    showBorder?: boolean;
+    /** Whether to hide cursor during overlay (default: true) */
+    hideCursor?: boolean;
+    /** Whether to enable vim-style navigation (default: true) */
+    enableVimNav?: boolean;
+    /** Whether to enable number keys for tabs (default: true for tabbed overlays) */
+    enableNumberKeys?: boolean;
+}
+/**
+ * Tab definition for tabbed overlays.
+ */
+export interface TabDefinition {
+    /** Unique identifier for the tab */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Optional keyboard shortcut (1-9) */
+    shortcut?: number;
+}
+/**
+ * Interface for composable features.
+ * Features handle specific aspects of overlay behavior (list, tabs, pagination, etc.)
+ */
+export interface Feature<TState = unknown> {
+    /**
+     * Handle a key press.
+     * @param data - Raw key buffer
+     * @param state - Current state (feature-specific portion)
+     * @returns KeyResult if handled, null if not handled
+     */
+    handleKey(data: Buffer, state: TState): KeyResult | null;
+    /**
+     * Optional render method for feature-specific content.
+     * @param state - Current state
+     * @returns Array of lines to render
+     */
+    render?(state: TState): string[];
+}
+/**
+ * Interface for screens in a multi-screen overlay.
+ */
+export interface BaseScreenInterface {
+    /**
+     * Render the screen content.
+     * @returns Array of lines to render
+     */
+    render(): string[];
+    /**
+     * Handle a key press.
+     * @param data - Raw key buffer
+     * @returns ScreenResult indicating what action to take
+     */
+    handleKey(data: Buffer): ScreenResult;
+    /**
+     * Optional lifecycle hook called when screen becomes active.
+     */
+    onEnter?(): void;
+    /**
+     * Optional lifecycle hook called when screen is deactivated.
+     */
+    onExit?(): void;
+    /**
+     * Optional: Return minimum height for stable rendering.
+     * Override to prevent visual jitter when screen content varies.
+     */
+    getMinHeight?(): number;
+}
+/**
+ * Options for rendering an item in a list.
+ */
+export interface ListItemRenderOptions<T> {
+    /** The item to render */
+    item: T;
+    /** Whether this item is selected */
+    isSelected: boolean;
+    /** Index in the list */
+    index: number;
+}
+/**
+ * Function type for custom list item rendering.
+ */
+export type ListItemRenderer<T> = (options: ListItemRenderOptions<T>) => string;

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

@@ -0,0 +1,7 @@
+/**
+ * Overlay Type Definitions
+ *
+ * Core interfaces and types for the overlay system.
+ * These provide the foundation for BaseOverlay and composable features.
+ */
+export {};

package/dist/ui/base/render-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Render Utilities
+ *
+ * Re-exported from @compilr-dev/ui-core for consistency.
+ * CLI-specific aliases provided for backward compatibility.
+ */
+export { renderBorder, wrapText, truncatePlain, truncateAnsi, normalizeText, padToHeight, emptyLines, padToWidth, } from '@compilr-dev/ui-core/utils';
+export { truncatePlain as truncate } from '@compilr-dev/ui-core/utils';

package/dist/ui/base/render-utils.js

@@ -0,0 +1,11 @@
+/**
+ * Render Utilities
+ *
+ * Re-exported from @compilr-dev/ui-core for consistency.
+ * CLI-specific aliases provided for backward compatibility.
+ */
+export { renderBorder, wrapText, truncatePlain, truncateAnsi, normalizeText, padToHeight, emptyLines, padToWidth, } from '@compilr-dev/ui-core/utils';
+// Re-export truncatePlain as truncate for CLI compatibility
+// (ui-core's truncate in ansi.ts is ANSI-aware with '...' suffix,
+//  CLI expects plain text truncate with '…' suffix)
+export { truncatePlain as truncate } from '@compilr-dev/ui-core/utils';

package/dist/ui/base/screen-stack.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Screen Stack
+ *
+ * Navigation stack for multi-screen overlays.
+ * Enables proper "back" behavior where Esc goes to previous screen.
+ *
+ * Usage:
+ * ```typescript
+ * class MyOverlay extends BaseOverlay<MyState, MyResult> {
+ *   private screenStack = new ScreenStack();
+ *
+ *   constructor() {
+ *     super(initialState);
+ *     this.screenStack.push(new ListScreen());
+ *   }
+ *
+ *   handleKey(data: Buffer): void {
+ *     if (isEscape(data)) {
+ *       if (this.screenStack.size() > 1) {
+ *         this.screenStack.pop();
+ *         this.update();
+ *       } else {
+ *         this.close(null);
+ *       }
+ *       return;
+ *     }
+ *
+ *     const result = this.screenStack.current()?.handleKey(data);
+ *     this.handleScreenResult(result);
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ...this.screenStack.current()?.render() ?? [],
+ *       ...this.renderFooter(this.getCurrentHints())
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import type { BaseScreenInterface, ScreenResult } from './overlay-types.js';
+export type { BaseScreenInterface, ScreenResult };
+/**
+ * Abstract base class for screens.
+ * Extend this to create screens for multi-screen overlays.
+ */
+export declare abstract class BaseScreen implements BaseScreenInterface {
+    /**
+     * Render the screen content.
+     * @returns Array of lines to render
+     */
+    abstract render(): string[];
+    /**
+     * Handle a key press.
+     * @param data - Raw key buffer
+     * @returns ScreenResult indicating what action to take
+     */
+    abstract handleKey(data: Buffer): ScreenResult;
+    /**
+     * Optional lifecycle hook called when screen becomes active.
+     * Override to perform setup when navigating to this screen.
+     */
+    onEnter?(): void;
+    /**
+     * Optional lifecycle hook called when screen is deactivated.
+     * Override to perform cleanup when navigating away.
+     */
+    onExit?(): void;
+    /**
+     * Optional: Return minimum height for stable rendering.
+     * Override to prevent visual jitter when screen content varies.
+     * @returns Minimum number of lines this screen should occupy
+     */
+    getMinHeight(): number;
+}
+/**
+ * Stack-based navigation for multi-screen overlays.
+ *
+ * The stack maintains a history of screens, allowing:
+ * - push() to navigate forward to a new screen
+ * - pop() to go back to the previous screen
+ * - current() to get the active screen
+ */
+export declare class ScreenStack {
+    private readonly screens;
+    /**
+     * Push a new screen onto the stack.
+     * Calls onExit() on current screen and onEnter() on new screen.
+     *
+     * @param screen - Screen to push
+     */
+    push(screen: BaseScreenInterface): void;
+    /**
+     * Pop the current screen and return to the previous one.
+     * Calls onExit() on popped screen and onEnter() on revealed screen.
+     *
+     * @returns The popped screen, or null if stack was empty
+     */
+    pop(): BaseScreenInterface | null;
+    /**
+     * Get the current (topmost) screen.
+     *
+     * @returns Current screen, or undefined if stack is empty
+     */
+    current(): BaseScreenInterface | undefined;
+    /**
+     * Get the number of screens in the stack.
+     */
+    size(): number;
+    /**
+     * Check if the stack is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if there's more than one screen (can go back).
+     */
+    canGoBack(): boolean;
+    /**
+     * Clear all screens from the stack.
+     * Calls onExit() on each screen in reverse order.
+     */
+    clear(): void;
+    /**
+     * Replace the current screen with a new one.
+     * Useful for "replace" navigation (no back).
+     *
+     * @param screen - Screen to replace with
+     */
+    replace(screen: BaseScreenInterface): void;
+}
+/**
+ * Helper to create a ScreenResult for staying on the current screen.
+ */
+export declare function stay(render?: boolean): ScreenResult;
+/**
+ * Helper to create a ScreenResult for pushing a new screen.
+ */
+export declare function pushScreen(screen: BaseScreenInterface): ScreenResult;
+/**
+ * Helper to create a ScreenResult for popping the current screen.
+ */
+export declare function popScreen(): ScreenResult;
+/**
+ * Helper to create a ScreenResult for closing the overlay.
+ * Result is optional for void result types.
+ */
+export declare function closeOverlay<T = void>(result?: T): ScreenResult<T>;

package/dist/ui/base/screen-stack.js

@@ -0,0 +1,184 @@
+/**
+ * Screen Stack
+ *
+ * Navigation stack for multi-screen overlays.
+ * Enables proper "back" behavior where Esc goes to previous screen.
+ *
+ * Usage:
+ * ```typescript
+ * class MyOverlay extends BaseOverlay<MyState, MyResult> {
+ *   private screenStack = new ScreenStack();
+ *
+ *   constructor() {
+ *     super(initialState);
+ *     this.screenStack.push(new ListScreen());
+ *   }
+ *
+ *   handleKey(data: Buffer): void {
+ *     if (isEscape(data)) {
+ *       if (this.screenStack.size() > 1) {
+ *         this.screenStack.pop();
+ *         this.update();
+ *       } else {
+ *         this.close(null);
+ *       }
+ *       return;
+ *     }
+ *
+ *     const result = this.screenStack.current()?.handleKey(data);
+ *     this.handleScreenResult(result);
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ...this.screenStack.current()?.render() ?? [],
+ *       ...this.renderFooter(this.getCurrentHints())
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+// =============================================================================
+// BaseScreen Abstract Class
+// =============================================================================
+/**
+ * Abstract base class for screens.
+ * Extend this to create screens for multi-screen overlays.
+ */
+export class BaseScreen {
+    /**
+     * Optional: Return minimum height for stable rendering.
+     * Override to prevent visual jitter when screen content varies.
+     * @returns Minimum number of lines this screen should occupy
+     */
+    getMinHeight() {
+        return 0; // Default: no minimum, use overlay's minHeight
+    }
+}
+// =============================================================================
+// ScreenStack Class
+// =============================================================================
+/**
+ * Stack-based navigation for multi-screen overlays.
+ *
+ * The stack maintains a history of screens, allowing:
+ * - push() to navigate forward to a new screen
+ * - pop() to go back to the previous screen
+ * - current() to get the active screen
+ */
+export class ScreenStack {
+    screens = [];
+    /**
+     * Push a new screen onto the stack.
+     * Calls onExit() on current screen and onEnter() on new screen.
+     *
+     * @param screen - Screen to push
+     */
+    push(screen) {
+        // Call exit hook on current screen
+        this.current()?.onExit?.();
+        // Push new screen
+        this.screens.push(screen);
+        // Call enter hook on new screen
+        screen.onEnter?.();
+    }
+    /**
+     * Pop the current screen and return to the previous one.
+     * Calls onExit() on popped screen and onEnter() on revealed screen.
+     *
+     * @returns The popped screen, or null if stack was empty
+     */
+    pop() {
+        if (this.screens.length === 0) {
+            return null;
+        }
+        // Pop and call exit hook
+        const screen = this.screens.pop();
+        if (screen) {
+            screen.onExit?.();
+        }
+        // Call enter hook on now-current screen
+        this.current()?.onEnter?.();
+        return screen ?? null;
+    }
+    /**
+     * Get the current (topmost) screen.
+     *
+     * @returns Current screen, or undefined if stack is empty
+     */
+    current() {
+        return this.screens[this.screens.length - 1];
+    }
+    /**
+     * Get the number of screens in the stack.
+     */
+    size() {
+        return this.screens.length;
+    }
+    /**
+     * Check if the stack is empty.
+     */
+    isEmpty() {
+        return this.screens.length === 0;
+    }
+    /**
+     * Check if there's more than one screen (can go back).
+     */
+    canGoBack() {
+        return this.screens.length > 1;
+    }
+    /**
+     * Clear all screens from the stack.
+     * Calls onExit() on each screen in reverse order.
+     */
+    clear() {
+        while (this.screens.length > 0) {
+            this.pop();
+        }
+    }
+    /**
+     * Replace the current screen with a new one.
+     * Useful for "replace" navigation (no back).
+     *
+     * @param screen - Screen to replace with
+     */
+    replace(screen) {
+        if (this.screens.length > 0) {
+            const current = this.screens.pop();
+            if (current) {
+                current.onExit?.();
+            }
+        }
+        this.screens.push(screen);
+        screen.onEnter?.();
+    }
+}
+// =============================================================================
+// Helper Types
+// =============================================================================
+/**
+ * Helper to create a ScreenResult for staying on the current screen.
+ */
+export function stay(render = true) {
+    return { action: 'stay', render };
+}
+/**
+ * Helper to create a ScreenResult for pushing a new screen.
+ */
+export function pushScreen(screen) {
+    return { action: 'push', screen };
+}
+/**
+ * Helper to create a ScreenResult for popping the current screen.
+ */
+export function popScreen() {
+    return { action: 'pop' };
+}
+/**
+ * Helper to create a ScreenResult for closing the overlay.
+ * Result is optional for void result types.
+ */
+export function closeOverlay(result) {
+    return { action: 'close', result: result };
+}