@compilr-dev/cli 0.4.0 → 0.5.1

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

@@ -0,0 +1,320 @@
+/**
+ * Inline Overlay Utilities
+ *
+ * Shared utilities 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
+ *
+ * CANONICAL PATTERN for inline overlays:
+ *
+ * ```typescript
+ * export async function showMyOverlay(options: Options): Promise<Result> {
+ *   const state = { ... };
+ *   const ctx = createInlineOverlayContext();
+ *
+ *   // Setup
+ *   // NOTE: Footer should be paused by CALLER (index.ts), not here
+ *   // This prevents double-pause issues with agent tool overlays
+ *   inlineSetup(ctx);
+ *
+ *   // Initial render
+ *   ctx.lineCount = renderMyOverlay(options, state, ctx);
+ *   ctx.maxLineCount = Math.max(ctx.maxLineCount, ctx.lineCount);
+ *
+ *   return new Promise((resolve) => {
+ *     const cleanup = (result: Result) => {
+ *       inlineCleanup(ctx);
+ *       process.stdin.removeListener('data', handleData);
+ *       resolve(result);
+ *     };
+ *
+ *     const handleData = (data: Buffer) => {
+ *       // Handle keys, update state
+ *       // ...
+ *
+ *       // Re-render (always use maxLineCount for both clearing and target)
+ *       ctx.lineCount = renderMyOverlay(options, state, ctx);
+ *       ctx.maxLineCount = Math.max(ctx.maxLineCount, ctx.lineCount);
+ *     };
+ *
+ *     process.stdin.on('data', handleData);
+ *   });
+ * }
+ * ```
+ *
+ * RENDER FUNCTION pattern:
+ *
+ * ```typescript
+ * function renderMyOverlay(
+ *   options: Options,
+ *   state: State,
+ *   ctx: InlineOverlayContext
+ * ): number {
+ *   const lines: string[] = [];
+ *
+ *   // Clear previous render
+ *   if (ctx.maxLineCount > 0) {
+ *     terminal.clearLinesAbove(ctx.maxLineCount);
+ *   }
+ *
+ *   // Build lines array
+ *   lines.push(...);
+ *
+ *   // Pad to consistent height (prevents cursor drift)
+ *   while (lines.length < ctx.maxLineCount) {
+ *     lines.push('');
+ *   }
+ *
+ *   // Render
+ *   terminal.write(lines.join('\n'));
+ *
+ *   return lines.length;
+ * }
+ * ```
+ */
+import * as terminal from '../terminal.js';
+// =============================================================================
+// Context Management
+// =============================================================================
+/**
+ * Create a new inline overlay context.
+ * Call this at the start of showXxxOverlay().
+ */
+export function createInlineOverlayContext() {
+    return {
+        lineCount: 0,
+        maxLineCount: 0,
+        wasRawMode: process.stdin.isRaw,
+    };
+}
+// =============================================================================
+// Setup & Cleanup
+// =============================================================================
+/**
+ * Standard setup for inline overlays.
+ * Call this after creating the context.
+ *
+ * NOTE: Footer pause 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.
+ */
+export function inlineSetup(ctx) {
+    // Record raw mode state before we change it
+    ctx.wasRawMode = process.stdin.isRaw;
+    // Start from a fresh line
+    terminal.writeLine('');
+    // Hide cursor during overlay
+    terminal.hideCursor();
+    // Enable raw mode for key-by-key input
+    terminal.enableRawMode();
+}
+/**
+ * Standard cleanup for inline overlays.
+ * Call this before resolving the promise.
+ *
+ * NOTE: Footer resume should be handled by the CALLER (index.ts),
+ * not by the overlay itself.
+ */
+export function inlineCleanup(ctx) {
+    // Clear all lines we've ever rendered (prevents ghost lines)
+    if (ctx.maxLineCount > 0) {
+        terminal.clearLinesAbove(ctx.maxLineCount);
+    }
+    // Show cursor
+    terminal.showCursor();
+    // Restore raw mode to previous state
+    if (!ctx.wasRawMode) {
+        terminal.disableRawMode();
+    }
+}
+/**
+ * Cleanup with a result summary line.
+ * Some overlays show a brief result after closing.
+ */
+export function inlineCleanupWithSummary(ctx, summaryLine) {
+    // Clear all lines
+    if (ctx.maxLineCount > 0) {
+        terminal.clearLinesAbove(ctx.maxLineCount);
+    }
+    // Show result summary
+    terminal.writeLine(summaryLine);
+    terminal.writeLine(''); // Blank line for separation
+    // Show cursor
+    terminal.showCursor();
+    // Restore raw mode
+    if (!ctx.wasRawMode) {
+        terminal.disableRawMode();
+    }
+}
+// =============================================================================
+// Render Helpers
+// =============================================================================
+/**
+ * Clear previous render and prepare for new render.
+ * Call this at the start of your render function.
+ *
+ * @param ctx - The overlay context
+ */
+export function inlineClearPrevious(ctx) {
+    if (ctx.maxLineCount > 0) {
+        terminal.clearLinesAbove(ctx.maxLineCount);
+    }
+}
+/**
+ * Pad lines array to target height (prevents cursor drift).
+ * Call this before rendering.
+ *
+ * @param lines - Array of lines to pad
+ * @param targetLineCount - Target number of lines (usually ctx.maxLineCount)
+ */
+export function inlinePadLines(lines, targetLineCount) {
+    while (lines.length < targetLineCount) {
+        lines.push('');
+    }
+}
+/**
+ * Render lines and return the line count.
+ * Call this at the end of your render function.
+ *
+ * @param lines - Array of lines to render
+ * @returns Number of lines rendered
+ */
+export function inlineRenderLines(lines) {
+    terminal.write(lines.join('\n'));
+    return lines.length;
+}
+/**
+ * Complete render helper that clears, pads, and renders.
+ * Use this for simpler overlays.
+ *
+ * @param lines - Array of lines to render
+ * @param ctx - The overlay context
+ * @returns Number of lines rendered
+ */
+export function inlineRender(lines, ctx) {
+    // Clear previous
+    inlineClearPrevious(ctx);
+    // Pad to max height
+    inlinePadLines(lines, ctx.maxLineCount);
+    // Render and return count
+    return inlineRenderLines(lines);
+}
+/**
+ * Update context after render.
+ * Call this after your render function returns.
+ *
+ * @param ctx - The overlay context
+ * @param newLineCount - Number of lines just rendered
+ */
+export function inlineUpdateContext(ctx, newLineCount) {
+    ctx.lineCount = newLineCount;
+    ctx.maxLineCount = Math.max(ctx.maxLineCount, newLineCount);
+}
+// =============================================================================
+// Key Detection Utilities
+// =============================================================================
+// These are re-exported for convenience, but the canonical versions
+// are in key-utils.ts. Inline overlays can use either.
+/**
+ * Check if buffer is Escape key
+ */
+export function isEscapeKey(data) {
+    return data.length === 1 && data[0] === 0x1b;
+}
+/**
+ * Check if buffer is Ctrl+C
+ */
+export function isCtrlCKey(data) {
+    return data.length === 1 && data[0] === 0x03;
+}
+/**
+ * Check if buffer is Enter key
+ */
+export function isEnterKey(data) {
+    return data.length === 1 && (data[0] === 0x0d || data[0] === 0x0a);
+}
+/**
+ * Check if buffer is Backspace key
+ */
+export function isBackspaceKey(data) {
+    return data.length === 1 && (data[0] === 0x7f || data[0] === 0x08);
+}
+/**
+ * Check if buffer is Up arrow
+ */
+export function isUpArrowKey(data) {
+    return data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x41;
+}
+/**
+ * Check if buffer is Down arrow
+ */
+export function isDownArrowKey(data) {
+    return data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x42;
+}
+/**
+ * Check if buffer is Left arrow
+ */
+export function isLeftArrowKey(data) {
+    return data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x44;
+}
+/**
+ * Check if buffer is Right arrow
+ */
+export function isRightArrowKey(data) {
+    return data.length === 3 && data[0] === 0x1b && data[1] === 0x5b && data[2] === 0x43;
+}
+/**
+ * Check if buffer is Tab key
+ */
+export function isTabKey(data) {
+    return data.length === 1 && data[0] === 0x09;
+}
+/**
+ * Check if buffer is Space key
+ */
+export function isSpaceKey(data) {
+    return data.length === 1 && data[0] === 0x20;
+}
+/**
+ * Check if buffer is a printable ASCII character
+ */
+export function isPrintableChar(data) {
+    return data.length === 1 && data[0] >= 0x20 && data[0] < 0x7f;
+}
+/**
+ * Get printable character from buffer, or null if not printable
+ */
+export function getPrintableChar(data) {
+    if (isPrintableChar(data)) {
+        return String.fromCharCode(data[0]);
+    }
+    return null;
+}
+/**
+ * Check if buffer is a number key (1-9)
+ */
+export function isNumberKey(data) {
+    return data.length === 1 && data[0] >= 0x31 && data[0] <= 0x39;
+}
+/**
+ * Get number from number key (1-9), or null if not a number key
+ * Returns 1-9 (not 0-8)
+ */
+export function getNumberKey(data) {
+    if (isNumberKey(data)) {
+        return data[0] - 0x30; // Returns 1-9
+    }
+    return null;
+}
+/**
+ * Get 0-indexed number from number key, or null if not a number key
+ * Returns 0-8 (for use as array index)
+ */
+export function getNumberKeyIndex(data) {
+    if (isNumberKey(data)) {
+        return data[0] - 0x31; // Returns 0-8
+    }
+    return null;
+}

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';