@compilr-dev/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,159 @@
+/**
+ * InlineOverlay Base Class
+ *
+ * Base class for "in-conversation" overlays that render above the footer.
+ * These overlays differ from full-screen overlays (BaseOverlay) in that they:
+ * - Render inline within the conversation
+ * - Use line-based clearing (clearLinesAbove) instead of full screen clear
+ * - Track line counts to prevent ghost lines and cursor drift
+ *
+ * IMPORTANT: Footer pause/resume should be handled by the CALLER (index.ts),
+ * not by the overlay itself. This prevents double-pause issues when
+ * overlays are triggered by agent tools.
+ *
+ * Usage:
+ * ```typescript
+ * class MyOverlay extends InlineOverlay<MyState, MyResult> {
+ *   constructor(private options: MyOptions) {
+ *     super();
+ *   }
+ *
+ *   getInitialState(): MyState {
+ *     return { selectedIndex: 0 };
+ *   }
+ *
+ *   render(): string[] {
+ *     return ['Line 1', 'Line 2', ...];
+ *   }
+ *
+ *   handleKey(data: Buffer): InlineAction<MyResult> {
+ *     if (isEnterKey(data)) {
+ *       return { type: 'close', result: this.state.selectedValue };
+ *     }
+ *     return { type: 'continue' };
+ *   }
+ * }
+ *
+ * // Usage
+ * const overlay = new MyOverlay(options);
+ * const result = await overlay.show();
+ * ```
+ */
+import { type InlineOverlayContext, isEscapeKey, isCtrlCKey, isEnterKey, isUpArrowKey, isDownArrowKey, isLeftArrowKey, isRightArrowKey, isTabKey, isSpaceKey, isBackspaceKey, isPrintableChar, getPrintableChar } from './inline-overlay-utils.js';
+/**
+ * Action returned by handleKey to control overlay flow.
+ */
+export type InlineAction<TResult> = {
+    type: 'continue';
+} | {
+    type: 'close';
+    result: TResult;
+} | {
+    type: 'suspend';
+};
+/**
+ * Options for cleanup behavior.
+ */
+export interface CleanupOptions {
+    /** Summary line to show after cleanup (optional) */
+    summaryLine?: string;
+}
+/**
+ * Abstract base class for inline overlays.
+ *
+ * @template TState - The overlay's internal state type
+ * @template TResult - The result type returned when the overlay closes
+ */
+export declare abstract class InlineOverlay<TState, TResult> {
+    /** Current overlay state */
+    protected state: TState;
+    /** Render context (line counts, raw mode tracking) */
+    protected ctx: InlineOverlayContext;
+    /** Whether the overlay is currently suspended (for sub-overlays) */
+    protected isSuspended: boolean;
+    /**
+     * Return the initial state for the overlay.
+     */
+    abstract getInitialState(): TState;
+    /**
+     * Render the overlay and return an array of lines.
+     * Each element in the array is one line of output.
+     * Lines should NOT include trailing newlines.
+     */
+    abstract render(): string[];
+    /**
+     * Handle a keypress and return an action.
+     * Can be async to support sub-overlays or other async operations.
+     *
+     * @param data - The raw keypress buffer
+     * @returns Action to take (continue, close, or suspend)
+     */
+    abstract handleKey(data: Buffer): InlineAction<TResult> | Promise<InlineAction<TResult>>;
+    /**
+     * Return a summary line to display after the overlay closes.
+     * Return null to skip the summary.
+     *
+     * @param result - The result being returned
+     */
+    protected getCleanupSummary(_result: TResult): string | null;
+    /**
+     * Called during setup, before initial render.
+     * Override to perform additional setup.
+     */
+    protected onSetup(): void;
+    /**
+     * Called during cleanup, before resolving.
+     * Override to perform additional cleanup.
+     */
+    protected onCleanup(): void;
+    /**
+     * Get terminal width for layout calculations.
+     */
+    protected getTerminalWidth(): number;
+    /**
+     * Trigger a re-render.
+     * Call this after updating state in handleKey.
+     */
+    protected requestRender(): void;
+    /**
+     * Suspend the overlay temporarily (e.g., to show a sub-overlay).
+     * The overlay will not process keys while suspended.
+     * Call resume() when the sub-overlay is done.
+     */
+    protected suspend(): void;
+    /**
+     * Resume the overlay after suspension.
+     * This clears the current render and re-renders.
+     */
+    protected resume(): void;
+    /**
+     * Clear all rendered lines (useful before showing a sub-overlay).
+     */
+    protected clearRender(): void;
+    protected isEscapeKey: typeof isEscapeKey;
+    protected isCtrlCKey: typeof isCtrlCKey;
+    protected isEnterKey: typeof isEnterKey;
+    protected isUpArrowKey: typeof isUpArrowKey;
+    protected isDownArrowKey: typeof isDownArrowKey;
+    protected isLeftArrowKey: typeof isLeftArrowKey;
+    protected isRightArrowKey: typeof isRightArrowKey;
+    protected isTabKey: typeof isTabKey;
+    protected isSpaceKey: typeof isSpaceKey;
+    protected isBackspaceKey: typeof isBackspaceKey;
+    protected isPrintableChar: typeof isPrintableChar;
+    protected getPrintableChar: typeof getPrintableChar;
+    /**
+     * Show the overlay and wait for user interaction.
+     * Returns the result when the user closes the overlay.
+     */
+    show(): Promise<TResult>;
+    /**
+     * Perform a render cycle.
+     */
+    private doRender;
+    /**
+     * Clean up the overlay.
+     */
+    private cleanup;
+}
+export { type InlineOverlayContext, createInlineOverlayContext, isEscapeKey, isCtrlCKey, isEnterKey, isUpArrowKey, isDownArrowKey, isLeftArrowKey, isRightArrowKey, isTabKey, isSpaceKey, isBackspaceKey, isPrintableChar, getPrintableChar, } from './inline-overlay-utils.js';

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

@@ -0,0 +1,257 @@
+/**
+ * InlineOverlay Base Class
+ *
+ * Base class for "in-conversation" overlays that render above the footer.
+ * These overlays differ from full-screen overlays (BaseOverlay) in that they:
+ * - Render inline within the conversation
+ * - Use line-based clearing (clearLinesAbove) instead of full screen clear
+ * - Track line counts to prevent ghost lines and cursor drift
+ *
+ * IMPORTANT: Footer pause/resume should be handled by the CALLER (index.ts),
+ * not by the overlay itself. This prevents double-pause issues when
+ * overlays are triggered by agent tools.
+ *
+ * Usage:
+ * ```typescript
+ * class MyOverlay extends InlineOverlay<MyState, MyResult> {
+ *   constructor(private options: MyOptions) {
+ *     super();
+ *   }
+ *
+ *   getInitialState(): MyState {
+ *     return { selectedIndex: 0 };
+ *   }
+ *
+ *   render(): string[] {
+ *     return ['Line 1', 'Line 2', ...];
+ *   }
+ *
+ *   handleKey(data: Buffer): InlineAction<MyResult> {
+ *     if (isEnterKey(data)) {
+ *       return { type: 'close', result: this.state.selectedValue };
+ *     }
+ *     return { type: 'continue' };
+ *   }
+ * }
+ *
+ * // Usage
+ * const overlay = new MyOverlay(options);
+ * const result = await overlay.show();
+ * ```
+ */
+import * as terminal from '../terminal.js';
+import { createInlineOverlayContext, isEscapeKey, isCtrlCKey, isEnterKey, isUpArrowKey, isDownArrowKey, isLeftArrowKey, isRightArrowKey, isTabKey, isSpaceKey, isBackspaceKey, isPrintableChar, getPrintableChar, } from './inline-overlay-utils.js';
+// =============================================================================
+// Base Class
+// =============================================================================
+/**
+ * Abstract base class for inline overlays.
+ *
+ * @template TState - The overlay's internal state type
+ * @template TResult - The result type returned when the overlay closes
+ */
+export class InlineOverlay {
+    /** Current overlay state */
+    state;
+    /** Render context (line counts, raw mode tracking) */
+    ctx;
+    /** Whether the overlay is currently suspended (for sub-overlays) */
+    isSuspended = false;
+    // ===========================================================================
+    // Optional Hooks - Can be overridden by subclasses
+    // ===========================================================================
+    /**
+     * Return a summary line to display after the overlay closes.
+     * Return null to skip the summary.
+     *
+     * @param result - The result being returned
+     */
+    getCleanupSummary(_result) {
+        return null;
+    }
+    /**
+     * Called during setup, before initial render.
+     * Override to perform additional setup.
+     */
+    onSetup() {
+        // Default: no-op
+    }
+    /**
+     * Called during cleanup, before resolving.
+     * Override to perform additional cleanup.
+     */
+    onCleanup() {
+        // Default: no-op
+    }
+    // ===========================================================================
+    // Protected Utilities - For use by subclasses
+    // ===========================================================================
+    /**
+     * Get terminal width for layout calculations.
+     */
+    getTerminalWidth() {
+        return terminal.getTerminalWidth();
+    }
+    /**
+     * Trigger a re-render.
+     * Call this after updating state in handleKey.
+     */
+    requestRender() {
+        this.doRender();
+    }
+    /**
+     * Suspend the overlay temporarily (e.g., to show a sub-overlay).
+     * The overlay will not process keys while suspended.
+     * Call resume() when the sub-overlay is done.
+     */
+    suspend() {
+        this.isSuspended = true;
+    }
+    /**
+     * Resume the overlay after suspension.
+     * This clears the current render and re-renders.
+     */
+    resume() {
+        this.isSuspended = false;
+        // After sub-overlay, we need to re-render from scratch
+        // Clear whatever the sub-overlay left and render fresh
+        this.doRender();
+    }
+    /**
+     * Clear all rendered lines (useful before showing a sub-overlay).
+     */
+    clearRender() {
+        if (this.ctx.maxLineCount > 0) {
+            terminal.clearLinesAbove(this.ctx.maxLineCount);
+        }
+        this.ctx.lineCount = 0;
+        this.ctx.maxLineCount = 0;
+    }
+    // ===========================================================================
+    // Key Detection Utilities - Re-exported for convenience
+    // ===========================================================================
+    isEscapeKey = isEscapeKey;
+    isCtrlCKey = isCtrlCKey;
+    isEnterKey = isEnterKey;
+    isUpArrowKey = isUpArrowKey;
+    isDownArrowKey = isDownArrowKey;
+    isLeftArrowKey = isLeftArrowKey;
+    isRightArrowKey = isRightArrowKey;
+    isTabKey = isTabKey;
+    isSpaceKey = isSpaceKey;
+    isBackspaceKey = isBackspaceKey;
+    isPrintableChar = isPrintableChar;
+    getPrintableChar = getPrintableChar;
+    // ===========================================================================
+    // Main Entry Point
+    // ===========================================================================
+    /**
+     * Show the overlay and wait for user interaction.
+     * Returns the result when the user closes the overlay.
+     */
+    async show() {
+        // Initialize
+        this.ctx = createInlineOverlayContext();
+        this.state = this.getInitialState();
+        // Setup
+        this.ctx.wasRawMode = process.stdin.isRaw;
+        terminal.writeLine(''); // Start from fresh line
+        terminal.hideCursor();
+        terminal.enableRawMode();
+        this.onSetup();
+        // Initial render
+        this.doRender();
+        // Event loop
+        return new Promise((resolve) => {
+            const handleData = (data) => {
+                // Ignore keys while suspended
+                if (this.isSuspended) {
+                    return;
+                }
+                // Handle both sync and async handleKey
+                const processAction = (action) => {
+                    switch (action.type) {
+                        case 'continue':
+                            this.doRender();
+                            break;
+                        case 'close':
+                            this.cleanup(action.result);
+                            process.stdin.removeListener('data', handleData);
+                            resolve(action.result);
+                            break;
+                        case 'suspend':
+                            // Subclass will call resume() when ready
+                            break;
+                    }
+                };
+                try {
+                    const result = this.handleKey(data);
+                    // Check if result is a Promise
+                    if (result instanceof Promise) {
+                        void result.then(processAction).catch((error) => {
+                            console.error('Error in handleKey:', error);
+                        });
+                    }
+                    else {
+                        processAction(result);
+                    }
+                }
+                catch (error) {
+                    // Log error but don't crash
+                    console.error('Error in handleKey:', error);
+                }
+            };
+            process.stdin.on('data', handleData);
+        });
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    /**
+     * Perform a render cycle.
+     */
+    doRender() {
+        // Clear previous render
+        if (this.ctx.maxLineCount > 0) {
+            terminal.clearLinesAbove(this.ctx.maxLineCount);
+        }
+        // Get lines from subclass
+        const lines = this.render();
+        // Pad to consistent height (prevents cursor drift)
+        while (lines.length < this.ctx.maxLineCount) {
+            lines.push('');
+        }
+        // Render
+        terminal.write(lines.join('\n'));
+        // Update context
+        this.ctx.lineCount = lines.length;
+        this.ctx.maxLineCount = Math.max(this.ctx.maxLineCount, lines.length);
+    }
+    /**
+     * Clean up the overlay.
+     */
+    cleanup(result) {
+        // Call subclass cleanup hook
+        this.onCleanup();
+        // Clear all lines
+        if (this.ctx.maxLineCount > 0) {
+            terminal.clearLinesAbove(this.ctx.maxLineCount);
+        }
+        // Show summary if provided
+        const summary = this.getCleanupSummary(result);
+        if (summary) {
+            terminal.writeLine(summary);
+            terminal.writeLine(''); // Blank line for separation
+        }
+        // Show cursor
+        terminal.showCursor();
+        // Restore raw mode
+        if (!this.ctx.wasRawMode) {
+            terminal.disableRawMode();
+        }
+    }
+}
+// =============================================================================
+// Re-exports for convenience
+// =============================================================================
+export { createInlineOverlayContext, isEscapeKey, isCtrlCKey, isEnterKey, isUpArrowKey, isDownArrowKey, isLeftArrowKey, isRightArrowKey, isTabKey, isSpaceKey, isBackspaceKey, isPrintableChar, getPrintableChar, } from './inline-overlay-utils.js';

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

@@ -0,0 +1,15 @@
+/**
+ * Key Utilities
+ *
+ * Re-exports key detection functions from @compilr-dev/ui-core.
+ * This provides consistent key detection for all overlays.
+ *
+ * Usage:
+ *   import { isEscape, isEnter, isNextTab } from './base/key-utils.js';
+ *
+ *   const onData = (data: Buffer): void => {
+ *     if (isEscape(data)) { cleanup(); return; }
+ *     if (isNextTab(data)) { state.currentTab++; }
+ *   };
+ */
+export { KEY, isEscape, isEnter, isTab, isShiftTab, isUpArrow, isDownArrow, isRightArrow, isLeftArrow, isCtrlC, isBackspace, isSpace, isPageUp, isPageDown, isHome, isEnd, isDelete, isCtrlA, isCtrlE, isWordLeft, isWordRight, getNumberKey, isNumberKey, getLetterKey, isVimUp, isVimDown, isVimLeft, isVimRight, isQuit, isN, isD, isE, isS, isSlash, isY, isA, isNavigateUp, isNavigateDown, isNavigateLeft, isNavigateRight, isNextTab, isPrevTab, isClose, isConfirm, isPrintable, getPrintableChar, extractPrintable, parseKey, } from '@compilr-dev/ui-core/utils';

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

@@ -0,0 +1,30 @@
+/**
+ * Key Utilities
+ *
+ * Re-exports key detection functions from @compilr-dev/ui-core.
+ * This provides consistent key detection for all overlays.
+ *
+ * Usage:
+ *   import { isEscape, isEnter, isNextTab } from './base/key-utils.js';
+ *
+ *   const onData = (data: Buffer): void => {
+ *     if (isEscape(data)) { cleanup(); return; }
+ *     if (isNextTab(data)) { state.currentTab++; }
+ *   };
+ */
+// Re-export everything from ui-core
+export { 
+// Key constants
+KEY, 
+// Basic key detection
+isEscape, isEnter, isTab, isShiftTab, isUpArrow, isDownArrow, isRightArrow, isLeftArrow, isCtrlC, isBackspace, isSpace, isPageUp, isPageDown, isHome, isEnd, isDelete, isCtrlA, isCtrlE, isWordLeft, isWordRight, 
+// Number keys
+getNumberKey, isNumberKey, 
+// Letter keys
+getLetterKey, isVimUp, isVimDown, isVimLeft, isVimRight, isQuit, isN, isD, isE, isS, isSlash, isY, isA, 
+// Composite helpers
+isNavigateUp, isNavigateDown, isNavigateLeft, isNavigateRight, isNextTab, isPrevTab, isClose, isConfirm, 
+// Utility
+isPrintable, getPrintableChar, extractPrintable, 
+// Key event parsing (bonus from ui-core)
+parseKey, } from '@compilr-dev/ui-core/utils';

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

@@ -0,0 +1,193 @@
+/**
+ * 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();
+ *   }
+ * }
+ * ```
+ */
+import type { Overlay, RenderContext, OverlayContent, OverlayAction, KeyEvent } from '../overlay/index.js';
+import type { ThemeStyleFunctions } from '../../themes/index.js';
+/**
+ * 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 declare abstract class BaseOverlayV2<TState = unknown, TResult = void> implements Overlay<TState, TResult> {
+    /** Overlay type - must be set by subclass */
+    abstract readonly type: 'fullscreen' | 'inline';
+    /** Unique overlay ID - must be set by subclass */
+    abstract readonly id: string;
+    /** Current overlay state */
+    protected state: TState;
+    /** Cached styles from last render context */
+    protected styles: ThemeStyleFunctions | null;
+    /** Cached terminal width from last render context */
+    protected termWidth: number;
+    /** Minimum height for stable rendering (prevents visual jitter) */
+    protected minHeight: number;
+    /**
+     * Create a new overlay instance.
+     *
+     * @param initialState - Initial state
+     */
+    constructor(initialState: TState);
+    /**
+     * Get current state.
+     */
+    getState(): TState;
+    /**
+     * Render the overlay.
+     * Calls renderContent() and wraps in OverlayContent.
+     */
+    render(context: RenderContext): OverlayContent;
+    /**
+     * Handle key press - must be implemented by subclass.
+     * Can be sync or async (for overlays that need to do async work).
+     */
+    abstract handleKey(key: KeyEvent): OverlayAction<TResult> | Promise<OverlayAction<TResult>>;
+    /**
+     * Optional lifecycle hook when overlay mounts.
+     */
+    onMount?(): void | Promise<void>;
+    /**
+     * Optional lifecycle hook when overlay unmounts.
+     */
+    onUnmount?(): void;
+    /**
+     * Optional summary to show after overlay closes.
+     */
+    getCloseSummary?(result: TResult): string | null;
+    /**
+     * Return action to close with result.
+     */
+    protected close(result: TResult): OverlayAction<TResult>;
+    /**
+     * Return action to close as cancelled.
+     */
+    protected cancel(): OverlayAction<TResult>;
+    /**
+     * Return action to re-render.
+     */
+    protected rerender(): OverlayAction<TResult>;
+    /**
+     * Return action for no change.
+     */
+    protected noAction(): OverlayAction<TResult>;
+    /**
+     * Return action to push a sub-overlay.
+     */
+    protected push(overlay: Overlay): OverlayAction<TResult>;
+    /**
+     * Return action to pop back to parent.
+     */
+    protected pop(): OverlayAction<TResult>;
+    /**
+     * Render the overlay content.
+     * Must be implemented by subclass.
+     *
+     * @param context - Render context with width, height, styles
+     * @returns Array of lines to render
+     */
+    protected abstract renderContent(context: RenderContext): string[];
+    /**
+     * Get the cached styles (or throw if not available).
+     */
+    protected getStyles(): ThemeStyleFunctions;
+    /**
+     * 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;
+    /**
+     * Check if key is a close key (escape or 'q').
+     */
+    protected isCloseKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is Ctrl+C.
+     */
+    protected isInterruptKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is Enter/Return.
+     */
+    protected isEnterKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is up arrow or 'k' (vim).
+     */
+    protected isUpKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is down arrow or 'j' (vim).
+     */
+    protected isDownKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is left arrow or 'h' (vim).
+     */
+    protected isLeftKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is right arrow or 'l' (vim).
+     */
+    protected isRightKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is Tab.
+     */
+    protected isTabKey(key: KeyEvent): boolean;
+    /**
+     * Check if key is Shift+Tab.
+     */
+    protected isShiftTabKey(key: KeyEvent): boolean;
+    /**
+     * Get number if key is 1-9.
+     */
+    protected getNumberKey(key: KeyEvent): number | null;
+}