@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/tools-overlay-v2.js

@@ -0,0 +1,218 @@
+/**
+ * Tools Overlay V2
+ *
+ * Displays available agent tools in a categorized, searchable list.
+ * Uses TabbedListOverlayV2 for the new Overlay interface.
+ *
+ * Features:
+ * - Tabs: All, Files, Code, Git, Project, Agent
+ * - Search with / toggle
+ * - Detail view for full tool information
+ * - Works with TerminalUI's overlay management
+ */
+import * as terminal from './terminal.js';
+import { TabbedListOverlayV2, BaseScreen, stay, popScreen, closeOverlay, isEscape, isCtrlC, isClose, renderBorder, wrapText, } from './base/index.js';
+// =============================================================================
+// Tab Definitions & Tool Categories
+// =============================================================================
+const TOOL_TABS = [
+    { id: 'all', label: 'All' },
+    { id: 'files', label: 'Files' },
+    { id: 'code', label: 'Code' },
+    { id: 'git', label: 'Git' },
+    { id: 'project', label: 'Project' },
+    { id: 'agent', label: 'Agent' },
+];
+/**
+ * Tool category mappings.
+ * Uses exact names or prefix patterns (ending with *).
+ */
+const TOOL_CATEGORIES = {
+    all: null, // No filter - show all tools
+    files: ['read_file', 'write_file', 'edit', 'glob', 'readFile', 'writeFile'],
+    code: ['grep', 'bash', 'bashOutput', 'run_tests', 'run_lint', 'detect_project', 'find_project_root', 'detectProject', 'findProjectRoot'],
+    git: ['git_*', 'gitStatus', 'gitDiff', 'gitLog', 'gitCommit', 'gitBranch'],
+    project: ['project_*', 'workitem_*', 'document_*', 'anchor_*'],
+    agent: ['task', 'todo_write', 'todo_read', 'todoWrite', 'todoRead', 'suggest', 'ask_user', 'ask_user_simple', 'askUser', 'askUserSimple', 'webFetch'],
+};
+/**
+ * Check if a tool matches a category filter.
+ */
+function toolMatchesCategory(toolName, categoryId) {
+    const patterns = TOOL_CATEGORIES[categoryId];
+    if (patterns === null)
+        return true; // 'all' category
+    for (const pattern of patterns) {
+        if (pattern.endsWith('*')) {
+            // Prefix match
+            const prefix = pattern.slice(0, -1);
+            if (toolName.startsWith(prefix))
+                return true;
+        }
+        else {
+            // Exact match
+            if (toolName === pattern)
+                return true;
+        }
+    }
+    return false;
+}
+// =============================================================================
+// Constants
+// =============================================================================
+const PAGE_SIZE = 12;
+const NAME_WIDTH = 26;
+const MAX_DESCRIPTION_LENGTH = 300;
+const MAX_PARAMETERS_SHOWN = 5;
+/**
+ * Normalize text by replacing newlines with spaces (for single-line display)
+ */
+function normalizeText(text) {
+    return text.replace(/\n+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+// =============================================================================
+// Detail Screen
+// =============================================================================
+/**
+ * Detail screen - shows full information for selected tool
+ */
+class ToolDetailScreen extends BaseScreen {
+    tool;
+    styles;
+    constructor(tool, styles) {
+        super();
+        this.tool = tool;
+        this.styles = styles;
+    }
+    render() {
+        const s = this.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        // Header
+        lines.push(border);
+        lines.push(`  ${s.primaryBold('Tool Details')}`);
+        lines.push('');
+        // Tool name
+        lines.push(`  ${s.muted('Name:')}  ${s.primaryBold(this.tool.name)}`);
+        lines.push('');
+        // Permission info
+        if (this.tool.permission) {
+            const levelColor = this.tool.permission.level === 'once' ? s.warning : s.muted;
+            lines.push(`  ${s.muted('Permission:')}  ${levelColor(this.tool.permission.level)} ${s.muted(`(${this.tool.permission.description})`)}`);
+        }
+        else {
+            lines.push(`  ${s.muted('Permission:')}  ${s.success('always')} ${s.muted('(no approval required)')}`);
+        }
+        lines.push('');
+        // Description (normalize newlines for proper wrapping)
+        lines.push(`  ${s.muted('Description:')}`);
+        let description = normalizeText(this.tool.description ?? 'No description available.');
+        if (description.length > MAX_DESCRIPTION_LENGTH) {
+            description = description.slice(0, MAX_DESCRIPTION_LENGTH).trim() + '...';
+        }
+        const wrappedDesc = wrapText(description, cols - 6);
+        for (const line of wrappedDesc) {
+            lines.push(`    ${s.secondary(line)}`);
+        }
+        lines.push('');
+        // Parameters
+        if (this.tool.parameters && this.tool.parameters.length > 0) {
+            // Sort: required first, then optional
+            const sorted = [...this.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(border);
+        lines.push(`  ${s.muted('q/Esc Back')}`);
+        lines.push(border);
+        return lines;
+    }
+    handleKey(data) {
+        // Ctrl+C closes overlay completely
+        if (isCtrlC(data)) {
+            return closeOverlay({ dismissed: true });
+        }
+        // Esc or q goes back to list
+        if (isEscape(data) || isClose(data)) {
+            return popScreen();
+        }
+        return stay(false);
+    }
+    /**
+     * Minimum height for stable rendering.
+     */
+    getMinHeight() {
+        return 20;
+    }
+}
+// =============================================================================
+// Tools Overlay V2 Class
+// =============================================================================
+/**
+ * Tools overlay using the new Overlay interface.
+ * Displays available tools in a searchable, tabbed list.
+ */
+export class ToolsOverlayV2 extends TabbedListOverlayV2 {
+    type = 'inline';
+    id = 'tools-overlay-v2';
+    constructor(options) {
+        // Sort tools alphabetically
+        const sortedTools = [...options.tools].sort((a, b) => a.name.localeCompare(b.name));
+        super({
+            title: 'Available Tools',
+            tabs: TOOL_TABS,
+            items: sortedTools,
+            pageSize: PAGE_SIZE,
+            filterByTab: (tool, tabId) => toolMatchesCategory(tool.name, tabId),
+            getSearchText: (tool) => `${tool.name} ${tool.description ?? ''}`,
+            renderItem: (tool, isSelected, styles) => {
+                const cols = terminal.getTerminalWidth();
+                const descWidth = Math.max(20, cols - NAME_WIDTH - 10);
+                const cursor = isSelected ? styles.primary('> ') : '  ';
+                const name = isSelected
+                    ? styles.primary(tool.name.padEnd(NAME_WIDTH))
+                    : styles.muted(tool.name.padEnd(NAME_WIDTH));
+                // Normalize and truncate description
+                const normalizedDesc = normalizeText(tool.description ?? '');
+                const desc = normalizedDesc.length > descWidth
+                    ? normalizedDesc.slice(0, descWidth - 1) + '...'
+                    : normalizedDesc;
+                const descColor = isSelected ? styles.secondary(desc) : styles.muted(desc);
+                return `  ${cursor}${name}  ${descColor}`;
+            },
+            footerHints: (searchMode) => {
+                if (searchMode) {
+                    return 'Type to filter · ↑↓/jk Navigate · Enter Details · Esc Exit search';
+                }
+                return 'Tab Filter · ↑↓/jk · ←→/hl Pages · / Search · Enter Details · q/Esc Close';
+            },
+            emptyMessage: 'No tools available.',
+            noResultsMessage: 'No tools match the current filter.',
+        });
+    }
+    createDetailScreen(tool) {
+        return new ToolDetailScreen(tool, this.getStyles());
+    }
+}

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

@@ -1,8 +1,13 @@
 /**
  * Tools Overlay
  *
- * Displays available agent tools in a scrollable list with descriptions.
- * Supports detail view for full tool information.
+ * Displays available agent tools in a categorized, searchable list.
+ * Uses TabbedListOverlay for consistent UX patterns.
+ *
+ * Features:
+ * - Tabs: All, Files, Code, Git, Project, Agent
+ * - Search with / toggle
+ * - Detail view for full tool information
  */
 export interface ToolParameter {
     name: string;
@@ -23,4 +28,7 @@ export interface ToolInfo {
 export interface ToolsOverlayResult {
     dismissed: boolean;
 }
+/**
+ * Show the tools overlay
+ */
 export declare function showToolsOverlay(tools: ToolInfo[]): Promise<ToolsOverlayResult>;

package/dist/ui/tools-overlay.js

@@ -1,161 +1,121 @@
 /**
  * Tools Overlay
  *
- * Displays available agent tools in a scrollable list with descriptions.
- * Supports detail view for full tool information.
+ * Displays available agent tools in a categorized, searchable list.
+ * Uses TabbedListOverlay for consistent UX patterns.
+ *
+ * Features:
+ * - Tabs: All, Files, Code, Git, Project, Agent
+ * - Search with / toggle
+ * - Detail view for full tool information
  */
 import * as terminal from './terminal.js';
-import { getStyles } from '../themes/index.js';
+import { TabbedListOverlay, BaseScreen, stay, popScreen, closeOverlay, isCtrlC, isClose, isEscape, renderBorder, } from './base/index.js';
+// =============================================================================
+// Tab Definitions & Tool Categories
+// =============================================================================
+const TOOL_TABS = [
+    { id: 'all', label: 'All' },
+    { id: 'files', label: 'Files' },
+    { id: 'code', label: 'Code' },
+    { id: 'git', label: 'Git' },
+    { id: 'project', label: 'Project' },
+    { id: 'agent', label: 'Agent' },
+];
+/**
+ * Tool category mappings.
+ * Uses exact names or prefix patterns (ending with *).
+ */
+const TOOL_CATEGORIES = {
+    all: null, // No filter - show all tools
+    files: ['read_file', 'write_file', 'edit', 'glob', 'readFile', 'writeFile'],
+    code: ['grep', 'bash', 'bashOutput', 'run_tests', 'run_lint', 'detect_project', 'find_project_root', 'detectProject', 'findProjectRoot'],
+    git: ['git_*', 'gitStatus', 'gitDiff', 'gitLog', 'gitCommit', 'gitBranch'],
+    project: ['project_*', 'workitem_*', 'document_*', 'anchor_*'],
+    agent: ['task', 'todo_write', 'todo_read', 'todoWrite', 'todoRead', 'suggest', 'ask_user', 'ask_user_simple', 'askUser', 'askUserSimple', 'webFetch'],
+};
+/**
+ * Check if a tool matches a category filter.
+ */
+function toolMatchesCategory(toolName, categoryId) {
+    const patterns = TOOL_CATEGORIES[categoryId];
+    if (patterns === null)
+        return true; // 'all' category
+    for (const pattern of patterns) {
+        if (pattern.endsWith('*')) {
+            // Prefix match
+            const prefix = pattern.slice(0, -1);
+            if (toolName.startsWith(prefix))
+                return true;
+        }
+        else {
+            // Exact match
+            if (toolName === pattern)
+                return true;
+        }
+    }
+    return false;
+}
 // =============================================================================
 // 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 PAGE_SIZE = 12;
+const NAME_WIDTH = 26;
 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];
+/**
+ * Normalize text by replacing newlines with spaces (for single-line display)
+ */
+function normalizeText(text) {
+    return text.replace(/\n+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Detail screen - shows full information for selected tool
+ */
+class ToolDetailScreen extends BaseScreen {
+    tool;
+    styles;
+    constructor(tool, styles) {
+        super();
+        this.tool = tool;
+        this.styles = styles;
+    }
+    render() {
+        const s = this.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = renderBorder(cols, s);
         const lines = [];
         // Header
-        lines.push(getBorder());
+        lines.push(border);
         lines.push(`  ${s.primaryBold('Tool Details')}`);
         lines.push('');
         // Tool name
-        lines.push(`  ${s.muted('Name:')}  ${s.primaryBold(tool.name)}`);
+        lines.push(`  ${s.muted('Name:')}  ${s.primaryBold(this.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('');
+        // Permission info
+        if (this.tool.permission) {
+            const levelColor = this.tool.permission.level === 'once' ? s.warning : s.muted;
+            lines.push(`  ${s.muted('Permission:')}  ${levelColor(this.tool.permission.level)} ${s.muted(`(${this.tool.permission.description})`)}`);
         }
         else {
             lines.push(`  ${s.muted('Permission:')}  ${s.success('always')} ${s.muted('(no approval required)')}`);
-            lines.push('');
         }
-        // Description (truncated if too long)
+        lines.push('');
+        // Description (normalize newlines for proper wrapping)
         lines.push(`  ${s.muted('Description:')}`);
-        let description = tool.description ?? 'No description available.';
+        let description = normalizeText(this.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);
+        const wrappedDesc = this.wrapText(description, cols - 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) {
+        // Parameters
+        if (this.tool.parameters && this.tool.parameters.length > 0) {
             // Sort: required first, then optional
-            const sorted = [...tool.parameters].sort((a, b) => {
+            const sorted = [...this.tool.parameters].sort((a, b) => {
                 if (a.required && !b.required)
                     return -1;
                 if (!a.required && b.required)
@@ -180,99 +140,91 @@ export async function showToolsOverlay(tools) {
             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;
+        lines.push(border);
+        lines.push(`  ${s.muted('q/Esc Back')}`);
+        lines.push(border);
+        return lines;
+    }
+    handleKey(data) {
+        // Ctrl+C closes overlay completely
+        if (isCtrlC(data)) {
+            return closeOverlay({ dismissed: true });
         }
-        else if (selectedIndex >= scrollOffset + VISIBLE_ROWS) {
-            scrollOffset = selectedIndex - VISIBLE_ROWS + 1;
+        // Esc or q goes back to list
+        if (isEscape(data) || isClose(data)) {
+            return popScreen();
         }
-    };
-    // 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();
+        return stay(false);
+    }
+    wrapText(text, maxWidth) {
+        const words = text.split(' ');
+        const resultLines = [];
+        let currentLine = '';
+        for (const word of words) {
+            if (currentLine.length + word.length + 1 <= maxWidth) {
+                currentLine += (currentLine ? ' ' : '') + word;
             }
-            else if (isPageDown) {
-                selectedIndex = Math.min(sortedTools.length - 1, selectedIndex + VISIBLE_ROWS);
-                ensureVisible();
-                lineCount = render();
+            else {
+                if (currentLine)
+                    resultLines.push(currentLine);
+                currentLine = word;
             }
-        };
-        stdin.on('data', handleKey);
-    });
+        }
+        if (currentLine)
+            resultLines.push(currentLine);
+        return resultLines;
+    }
+}
+// =============================================================================
+// Tools Overlay Class
+// =============================================================================
+class ToolsOverlay extends TabbedListOverlay {
+    constructor(tools) {
+        // Sort tools alphabetically
+        const sortedTools = [...tools].sort((a, b) => a.name.localeCompare(b.name));
+        super({
+            title: 'Available Tools',
+            tabs: TOOL_TABS,
+            items: sortedTools,
+            pageSize: PAGE_SIZE,
+            filterByTab: (tool, tabId) => toolMatchesCategory(tool.name, tabId),
+            getSearchText: (tool) => `${tool.name} ${tool.description ?? ''}`,
+            renderItem: (tool, isSelected, styles) => {
+                const cols = terminal.getTerminalWidth();
+                const descWidth = Math.max(20, cols - NAME_WIDTH - 10);
+                const cursor = isSelected ? styles.primary('❯ ') : '  ';
+                const name = isSelected
+                    ? styles.primaryBold(tool.name.padEnd(NAME_WIDTH))
+                    : styles.secondary(tool.name.padEnd(NAME_WIDTH));
+                // Normalize and truncate description
+                const normalizedDesc = normalizeText(tool.description ?? '');
+                const desc = normalizedDesc.length > descWidth
+                    ? normalizedDesc.slice(0, descWidth - 1) + '…'
+                    : normalizedDesc;
+                const descColor = isSelected ? styles.secondary(desc) : styles.muted(desc);
+                return `  ${cursor}${name}  ${descColor}`;
+            },
+            footerHints: (searchMode) => {
+                if (searchMode) {
+                    return 'Type to filter · ↑↓/jk Navigate · Enter Details · Esc Exit search';
+                }
+                return 'Tab Filter · ↑↓/jk · ←→/hl Pages · / Search · Enter Details · q/Esc Close';
+            },
+            emptyMessage: 'No tools available.',
+            noResultsMessage: 'No tools match the current filter.',
+            detailScreensFullScreen: false,
+        });
+    }
+    createDetailScreen(tool) {
+        return new ToolDetailScreen(tool, this.styles);
+    }
+}
+// =============================================================================
+// Export Function
+// =============================================================================
+/**
+ * Show the tools overlay
+ */
+export async function showToolsOverlay(tools) {
+    return new ToolsOverlay(tools).show();
 }