@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/base/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Base UI Utilities
+ *
+ * Shared utilities for consistent overlay behavior.
+ *
+ * Components:
+ * - key-utils: Key detection functions
+ * - overlay-types: Core interfaces and types
+ * - overlay-lifecycle: Lifecycle management
+ * - overlay-base: BaseOverlay abstract class
+ * - screen-stack: Navigation stack for multi-screen overlays
+ */
+export * from './key-utils.js';
+export * from './overlay-types.js';
+export { OverlayLifecycle, setupOverlay } from './overlay-lifecycle.js';
+export type { KeyHandler } from './overlay-lifecycle.js';
+export { BaseOverlay } from './overlay-base.js';
+export { BaseScreen, ScreenStack, stay, pushScreen, popScreen, closeOverlay, } from './screen-stack.js';
+export { renderBorder, wrapText, truncate, truncateAnsi, normalizeText, padToHeight, emptyLines, } from './render-utils.js';
+export { TabbedListOverlay } from './tabbed-list-overlay.js';
+export type { TabbedListConfig, TabbedListState } from './tabbed-list-overlay.js';
+export { BaseOverlayV2 } from './overlay-base-v2.js';
+export { TabbedListOverlayV2 } from './tabbed-list-overlay-v2.js';
+export type { TabbedListConfigV2, TabbedListStateV2, } from './tabbed-list-overlay-v2.js';
+export { createInlineOverlayContext, inlineSetup, inlineCleanup, inlineCleanupWithSummary, inlineClearPrevious, inlinePadLines, inlineRenderLines, inlineRender, inlineUpdateContext, isEscapeKey, isCtrlCKey, isEnterKey, isBackspaceKey, isUpArrowKey, isDownArrowKey, isLeftArrowKey, isRightArrowKey, isTabKey, isSpaceKey, isPrintableChar, getPrintableChar, isNumberKey, getNumberKey, getNumberKeyIndex, } from './inline-overlay-utils.js';
+export type { InlineOverlayContext } from './inline-overlay-utils.js';

package/dist/ui/base/index.js

@@ -0,0 +1,33 @@
+/**
+ * Base UI Utilities
+ *
+ * Shared utilities for consistent overlay behavior.
+ *
+ * Components:
+ * - key-utils: Key detection functions
+ * - overlay-types: Core interfaces and types
+ * - overlay-lifecycle: Lifecycle management
+ * - overlay-base: BaseOverlay abstract class
+ * - screen-stack: Navigation stack for multi-screen overlays
+ */
+// Key detection utilities
+export * from './key-utils.js';
+// Core types and interfaces
+export * from './overlay-types.js';
+// Lifecycle management
+export { OverlayLifecycle, setupOverlay } from './overlay-lifecycle.js';
+// Base overlay class
+export { BaseOverlay } from './overlay-base.js';
+// Screen stack for multi-screen overlays
+export { BaseScreen, ScreenStack, stay, pushScreen, popScreen, closeOverlay, } from './screen-stack.js';
+// Render utilities
+export { renderBorder, wrapText, truncate, truncateAnsi, normalizeText, padToHeight, emptyLines, } from './render-utils.js';
+// Tabbed list overlay base
+export { TabbedListOverlay } from './tabbed-list-overlay.js';
+// V2 Overlay base classes (new Overlay interface)
+export { BaseOverlayV2 } from './overlay-base-v2.js';
+export { TabbedListOverlayV2 } from './tabbed-list-overlay-v2.js';
+// Inline overlay utilities (for in-conversation overlays)
+export { createInlineOverlayContext, inlineSetup, inlineCleanup, inlineCleanupWithSummary, inlineClearPrevious, inlinePadLines, inlineRenderLines, inlineRender, inlineUpdateContext, 
+// Key detection (also available from key-utils)
+isEscapeKey, isCtrlCKey, isEnterKey, isBackspaceKey, isUpArrowKey, isDownArrowKey, isLeftArrowKey, isRightArrowKey, isTabKey, isSpaceKey, isPrintableChar, getPrintableChar, isNumberKey, getNumberKey, getNumberKeyIndex, } from './inline-overlay-utils.js';

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

@@ -0,0 +1,217 @@
+/**
+ * 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;
+ * }
+ * ```
+ */
+/**
+ * Context for tracking inline overlay render state.
+ * This prevents ghost lines and cursor drift.
+ */
+export interface InlineOverlayContext {
+    /** Current number of lines rendered */
+    lineCount: number;
+    /** Maximum lines ever rendered (used for clearing) */
+    maxLineCount: number;
+    /** Whether raw mode was enabled before overlay */
+    wasRawMode: boolean;
+}
+/**
+ * Create a new inline overlay context.
+ * Call this at the start of showXxxOverlay().
+ */
+export declare function createInlineOverlayContext(): InlineOverlayContext;
+/**
+ * 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 declare function inlineSetup(ctx: InlineOverlayContext): void;
+/**
+ * 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 declare function inlineCleanup(ctx: InlineOverlayContext): void;
+/**
+ * Cleanup with a result summary line.
+ * Some overlays show a brief result after closing.
+ */
+export declare function inlineCleanupWithSummary(ctx: InlineOverlayContext, summaryLine: string): void;
+/**
+ * Clear previous render and prepare for new render.
+ * Call this at the start of your render function.
+ *
+ * @param ctx - The overlay context
+ */
+export declare function inlineClearPrevious(ctx: InlineOverlayContext): void;
+/**
+ * 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 declare function inlinePadLines(lines: string[], targetLineCount: number): void;
+/**
+ * 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 declare function inlineRenderLines(lines: string[]): number;
+/**
+ * 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 declare function inlineRender(lines: string[], ctx: InlineOverlayContext): number;
+/**
+ * Update context after render.
+ * Call this after your render function returns.
+ *
+ * @param ctx - The overlay context
+ * @param newLineCount - Number of lines just rendered
+ */
+export declare function inlineUpdateContext(ctx: InlineOverlayContext, newLineCount: number): void;
+/**
+ * Check if buffer is Escape key
+ */
+export declare function isEscapeKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Ctrl+C
+ */
+export declare function isCtrlCKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Enter key
+ */
+export declare function isEnterKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Backspace key
+ */
+export declare function isBackspaceKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Up arrow
+ */
+export declare function isUpArrowKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Down arrow
+ */
+export declare function isDownArrowKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Left arrow
+ */
+export declare function isLeftArrowKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Right arrow
+ */
+export declare function isRightArrowKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Tab key
+ */
+export declare function isTabKey(data: Buffer): boolean;
+/**
+ * Check if buffer is Space key
+ */
+export declare function isSpaceKey(data: Buffer): boolean;
+/**
+ * Check if buffer is a printable ASCII character
+ */
+export declare function isPrintableChar(data: Buffer): boolean;
+/**
+ * Get printable character from buffer, or null if not printable
+ */
+export declare function getPrintableChar(data: Buffer): string | null;
+/**
+ * Check if buffer is a number key (1-9)
+ */
+export declare function isNumberKey(data: Buffer): boolean;
+/**
+ * Get number from number key (1-9), or null if not a number key
+ * Returns 1-9 (not 0-8)
+ */
+export declare function getNumberKey(data: Buffer): number | null;
+/**
+ * Get 0-indexed number from number key, or null if not a number key
+ * Returns 0-8 (for use as array index)
+ */
+export declare function getNumberKeyIndex(data: Buffer): number | null;

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;
+}