@compilr-dev/cli 0.4.0

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

@@ -0,0 +1,26 @@
+/**
+ * Tools Overlay
+ *
+ * Displays available agent tools in a scrollable list with descriptions.
+ * Supports detail view for full tool information.
+ */
+export interface ToolParameter {
+    name: string;
+    type: string;
+    description?: string;
+    required: boolean;
+}
+export interface ToolPermissionInfo {
+    level: 'once' | 'always' | 'session';
+    description: string;
+}
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    parameters?: ToolParameter[];
+    permission?: ToolPermissionInfo;
+}
+export interface ToolsOverlayResult {
+    dismissed: boolean;
+}
+export declare function showToolsOverlay(tools: ToolInfo[]): Promise<ToolsOverlayResult>;

package/dist/ui/tools-overlay.js

@@ -0,0 +1,278 @@
+/**
+ * Tools Overlay
+ *
+ * Displays available agent tools in a scrollable list with descriptions.
+ * Supports detail view for full tool information.
+ */
+import * as terminal from './terminal.js';
+import { getStyles } from '../themes/index.js';
+// =============================================================================
+// Constants
+// =============================================================================
+/** Number of tools visible at once */
+const VISIBLE_ROWS = 12;
+/** Width for tool name column */
+const NAME_WIDTH = 18;
+/** Max description length in detail view */
+const MAX_DESCRIPTION_LENGTH = 300;
+/** Max parameters to show in detail view */
+const MAX_PARAMETERS_SHOWN = 5;
+// =============================================================================
+// Main Function
+// =============================================================================
+export async function showToolsOverlay(tools) {
+    const s = getStyles();
+    const stdin = process.stdin;
+    // Sort tools alphabetically
+    const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+    // State
+    let selectedIndex = 0;
+    let scrollOffset = 0;
+    let lineCount = 0;
+    let mode = 'list';
+    // Get terminal width for layout
+    const termWidth = terminal.getTerminalWidth();
+    const descWidth = Math.max(20, termWidth - NAME_WIDTH - 10); // 10 for padding/cursor
+    // Helper to truncate text
+    const truncate = (text, maxLen) => {
+        if (text.length <= maxLen)
+            return text;
+        return text.slice(0, maxLen - 1) + '…';
+    };
+    // Helper to get border
+    const getBorder = () => {
+        return s.muted('─'.repeat(Math.max(1, termWidth - 1)));
+    };
+    // Helper to wrap text to multiple lines
+    const wrapText = (text, maxWidth) => {
+        const words = text.split(' ');
+        const lines = [];
+        let currentLine = '';
+        for (const word of words) {
+            if (currentLine.length + word.length + 1 <= maxWidth) {
+                currentLine += (currentLine ? ' ' : '') + word;
+            }
+            else {
+                if (currentLine)
+                    lines.push(currentLine);
+                currentLine = word;
+            }
+        }
+        if (currentLine)
+            lines.push(currentLine);
+        return lines;
+    };
+    // Render list view
+    const renderList = () => {
+        // Clear previous render
+        if (lineCount > 0) {
+            terminal.clearLinesAbove(lineCount);
+        }
+        const lines = [];
+        // Header
+        lines.push(getBorder());
+        const title = `Available Tools`;
+        const countBadge = s.muted(`[${String(sortedTools.length)} tools]`);
+        lines.push(`  ${s.primaryBold(title)}  ${countBadge}`);
+        lines.push('');
+        // Column headers
+        const nameHeader = s.muted('Tool'.padEnd(NAME_WIDTH));
+        const descHeader = s.muted('Description');
+        lines.push(`    ${nameHeader}  ${descHeader}`);
+        lines.push(`    ${s.muted('─'.repeat(NAME_WIDTH))}  ${s.muted('─'.repeat(Math.min(descWidth, 40)))}`);
+        // Visible tools
+        const visibleTools = sortedTools.slice(scrollOffset, scrollOffset + VISIBLE_ROWS);
+        for (let i = 0; i < visibleTools.length; i++) {
+            const tool = visibleTools[i];
+            const absoluteIndex = scrollOffset + i;
+            const isSelected = absoluteIndex === selectedIndex;
+            const cursor = isSelected ? s.primary('❯ ') : '  ';
+            const name = isSelected
+                ? s.primaryBold(tool.name.padEnd(NAME_WIDTH))
+                : s.secondary(tool.name.padEnd(NAME_WIDTH));
+            const desc = truncate(tool.description ?? '', descWidth);
+            const descColor = isSelected ? s.secondary(desc) : s.muted(desc);
+            lines.push(`  ${cursor}${name}  ${descColor}`);
+        }
+        // Padding if fewer tools than VISIBLE_ROWS
+        const emptyRows = VISIBLE_ROWS - visibleTools.length;
+        for (let i = 0; i < emptyRows; i++) {
+            lines.push('');
+        }
+        // Scroll indicator
+        lines.push('');
+        if (sortedTools.length > VISIBLE_ROWS) {
+            const scrollInfo = `${String(scrollOffset + 1)}-${String(Math.min(scrollOffset + VISIBLE_ROWS, sortedTools.length))} of ${String(sortedTools.length)}`;
+            const canUp = scrollOffset > 0;
+            const canDown = scrollOffset + VISIBLE_ROWS < sortedTools.length;
+            const arrows = (canUp ? '↑' : ' ') + (canDown ? '↓' : ' ');
+            lines.push(`  ${s.muted(scrollInfo)}  ${s.muted(arrows)}`);
+        }
+        // Footer
+        lines.push(getBorder());
+        lines.push(`  ${s.muted('↑↓ Navigate · Enter Details · Esc Close')}`);
+        lines.push(getBorder());
+        // Print all lines
+        terminal.write(lines.join('\n'));
+        return lines.length;
+    };
+    // Render detail view
+    const renderDetail = () => {
+        // Clear previous render
+        if (lineCount > 0) {
+            terminal.clearLinesAbove(lineCount);
+        }
+        const tool = sortedTools[selectedIndex];
+        const lines = [];
+        // Header
+        lines.push(getBorder());
+        lines.push(`  ${s.primaryBold('Tool Details')}`);
+        lines.push('');
+        // Tool name
+        lines.push(`  ${s.muted('Name:')}  ${s.primaryBold(tool.name)}`);
+        lines.push('');
+        // Permission info (if any)
+        if (tool.permission) {
+            const levelColor = tool.permission.level === 'once' ? s.warning : s.muted;
+            lines.push(`  ${s.muted('Permission:')}  ${levelColor(tool.permission.level)} ${s.muted(`(${tool.permission.description})`)}`);
+            lines.push('');
+        }
+        else {
+            lines.push(`  ${s.muted('Permission:')}  ${s.success('always')} ${s.muted('(no approval required)')}`);
+            lines.push('');
+        }
+        // Description (truncated if too long)
+        lines.push(`  ${s.muted('Description:')}`);
+        let description = tool.description ?? 'No description available.';
+        if (description.length > MAX_DESCRIPTION_LENGTH) {
+            description = description.slice(0, MAX_DESCRIPTION_LENGTH).trim() + '...';
+        }
+        const wrappedDesc = wrapText(description, termWidth - 6);
+        for (const line of wrappedDesc) {
+            lines.push(`    ${s.secondary(line)}`);
+        }
+        lines.push('');
+        // Parameters (limited to avoid verbose displays)
+        if (tool.parameters && tool.parameters.length > 0) {
+            // Sort: required first, then optional
+            const sorted = [...tool.parameters].sort((a, b) => {
+                if (a.required && !b.required)
+                    return -1;
+                if (!a.required && b.required)
+                    return 1;
+                return 0;
+            });
+            const shown = sorted.slice(0, MAX_PARAMETERS_SHOWN);
+            const hidden = sorted.length - shown.length;
+            lines.push(`  ${s.muted('Parameters:')}`);
+            for (const param of shown) {
+                const requiredBadge = param.required ? s.warning('*') : ' ';
+                const typeStr = s.muted(`(${param.type})`);
+                lines.push(`    ${requiredBadge} ${s.secondary(param.name)} ${typeStr}`);
+            }
+            if (hidden > 0) {
+                lines.push(`    ${s.muted(`  + ${String(hidden)} more optional parameters`)}`);
+            }
+            lines.push('');
+            lines.push(`    ${s.muted('* = required')}`);
+        }
+        else {
+            lines.push(`  ${s.muted('Parameters:')}  ${s.muted('None')}`);
+        }
+        // Footer
+        lines.push(getBorder());
+        lines.push(`  ${s.muted('Esc Back to list')}`);
+        lines.push(getBorder());
+        // Print all lines
+        terminal.write(lines.join('\n'));
+        return lines.length;
+    };
+    // Render based on mode
+    const render = () => {
+        if (mode === 'detail') {
+            return renderDetail();
+        }
+        return renderList();
+    };
+    // Ensure selected item is visible
+    const ensureVisible = () => {
+        if (selectedIndex < scrollOffset) {
+            scrollOffset = selectedIndex;
+        }
+        else if (selectedIndex >= scrollOffset + VISIBLE_ROWS) {
+            scrollOffset = selectedIndex - VISIBLE_ROWS + 1;
+        }
+    };
+    // Initial render
+    lineCount = render();
+    // Set up raw mode for keyboard input
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            stdin.removeListener('data', handleKey);
+            stdin.setRawMode(wasRaw);
+            // Clear the overlay
+            terminal.clearLinesAbove(lineCount);
+        };
+        const handleKey = (data) => {
+            const key = data.toString();
+            // Handle key presses
+            const isEscape = key === '\x1B' && data.length === 1;
+            const isEnter = key === '\r' || key === '\n';
+            const isUpArrow = key === '\x1B[A';
+            const isDownArrow = key === '\x1B[B';
+            const isPageUp = key === '\x1B[5~';
+            const isPageDown = key === '\x1B[6~';
+            const isCtrlC = key === '\x03';
+            const isQ = key === 'q' || key === 'Q';
+            if (isCtrlC) {
+                cleanup();
+                resolve({ dismissed: true });
+                return;
+            }
+            if (mode === 'detail') {
+                // Detail view: Esc goes back to list
+                if (isEscape || isQ) {
+                    mode = 'list';
+                    lineCount = render();
+                }
+                return;
+            }
+            // List view
+            if (isEscape || isQ) {
+                cleanup();
+                resolve({ dismissed: true });
+                return;
+            }
+            if (isEnter) {
+                mode = 'detail';
+                lineCount = render();
+                return;
+            }
+            // Navigation
+            if (isUpArrow && selectedIndex > 0) {
+                selectedIndex--;
+                ensureVisible();
+                lineCount = render();
+            }
+            else if (isDownArrow && selectedIndex < sortedTools.length - 1) {
+                selectedIndex++;
+                ensureVisible();
+                lineCount = render();
+            }
+            else if (isPageUp) {
+                selectedIndex = Math.max(0, selectedIndex - VISIBLE_ROWS);
+                ensureVisible();
+                lineCount = render();
+            }
+            else if (isPageDown) {
+                selectedIndex = Math.min(sortedTools.length - 1, selectedIndex + VISIBLE_ROWS);
+                ensureVisible();
+                lineCount = render();
+            }
+        };
+        stdin.on('data', handleKey);
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Tutorial Overlay
+ *
+ * Interactive tutorial that guides users through the compilr.dev workflow.
+ * Supports guided sequential tour and topic-based navigation.
+ */
+export interface TutorialOverlayResult {
+    completed: boolean;
+}
+export declare function showTutorialOverlay(): Promise<TutorialOverlayResult>;