@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/features/tab-feature.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Tab Feature
+ *
+ * Composable feature for tab/filter navigation.
+ * Handles Tab/Shift+Tab and number keys for tab switching.
+ *
+ * Note: Arrow keys (←→/hl) are NOT used for tabs - they are reserved
+ * for page navigation in paginated overlays. This ensures consistent
+ * keyboard behavior across all overlays.
+ *
+ * Usage:
+ * ```typescript
+ * const TABS = [
+ *   { id: 'all', label: 'All' },
+ *   { id: 'active', label: 'Active' },
+ *   { id: 'completed', label: 'Completed' },
+ * ];
+ *
+ * interface MyState extends OverlayState, TabState {
+ *   // ...
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, void> {
+ *   private tabFeature = new TabFeature(TABS, (tabId) => {
+ *     this.onTabChange(tabId);
+ *   });
+ *
+ *   handleKey(data: Buffer): void {
+ *     const result = this.tabFeature.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       if (result.action === 'render') this.update();
+ *       return;
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ' ' + this.tabFeature.renderTabs(this.state, this.styles),
+ *       '',
+ *       // ... content
+ *       ...this.renderFooter(this.tabFeature.renderHints() + ' · ↑↓/jk Navigate')
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import type { KeyResult, TabState, TabDefinition } from '../base/overlay-types.js';
+/**
+ * Configuration for TabFeature.
+ */
+export interface TabFeatureConfig {
+    /**
+     * Tab definitions.
+     */
+    tabs: TabDefinition[];
+    /**
+     * Callback when tab changes.
+     * @param tabId - ID of the new tab
+     * @param index - Index of the new tab
+     */
+    onChange?: (tabId: string, index: number) => void;
+    /**
+     * Whether to use number keys (1-9) for direct tab selection.
+     * Default: true (if tabs.length <= 9)
+     */
+    useNumberKeys?: boolean;
+    /**
+     * Whether navigation wraps at boundaries.
+     * Default: true
+     */
+    wrapNavigation?: boolean;
+}
+/**
+ * Feature for tab/filter navigation.
+ *
+ * Handles:
+ * - Tab/Shift+Tab for cycling tabs
+ * - Number keys 1-9 for direct selection (optional)
+ *
+ * Note: Arrow keys are NOT handled - they are reserved for pagination.
+ */
+export declare class TabFeature {
+    private readonly config;
+    /**
+     * Create a new TabFeature.
+     *
+     * @param tabs - Tab definitions
+     * @param onChange - Optional callback when tab changes
+     */
+    constructor(tabs: TabDefinition[], onChange?: (tabId: string, index: number) => void);
+    /**
+     * Create from config object (alternative constructor).
+     */
+    static fromConfig(config: TabFeatureConfig): TabFeature;
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing currentTab
+     * @returns KeyResult if handled, null otherwise
+     */
+    handleKey(data: Buffer, state: TabState): KeyResult | null;
+    /**
+     * Render tabs in a row.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string
+     */
+    renderTabs(state: TabState, styles: {
+        selected: (s: string) => string;
+        muted: (s: string) => string;
+    }): string;
+    /**
+     * Render tabs with number key hints.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string with numbers
+     */
+    renderTabsWithNumbers(state: TabState, styles: {
+        selected: (s: string) => string;
+        muted: (s: string) => string;
+    }): string;
+    /**
+     * Render tabs with custom separator.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @param separator - Separator between tabs (default: '')
+     * @returns Rendered tab bar string
+     */
+    renderTabsWithSeparator(state: TabState, styles: {
+        selected: (s: string) => string;
+        muted: (s: string) => string;
+    }, separator?: string): string;
+    /**
+     * Render keyboard hints for tabs.
+     *
+     * @returns Hint string like "Tab Switch · 1-5 Jump"
+     */
+    renderHints(): string;
+    /**
+     * Get the current tab definition.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab or undefined
+     */
+    getCurrentTab(state: TabState): TabDefinition | undefined;
+    /**
+     * Get the current tab ID.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab ID or empty string
+     */
+    getCurrentTabId(state: TabState): string;
+    /**
+     * Get the number of tabs.
+     */
+    getTabCount(): number;
+    /**
+     * Find tab index by ID.
+     *
+     * @param tabId - Tab ID to find
+     * @returns Index or -1 if not found
+     */
+    findTabIndex(tabId: string): number;
+    /**
+     * Set current tab by ID.
+     *
+     * @param state - State to modify
+     * @param tabId - Tab ID to select
+     * @returns true if tab was found and selected
+     */
+    setTabById(state: TabState, tabId: string): boolean;
+    private notifyChange;
+}
+/**
+ * Create tab definitions from an array of strings.
+ * IDs are lowercase versions of labels.
+ *
+ * @param labels - Tab labels
+ * @returns Tab definitions
+ */
+export declare function createTabsFromLabels(labels: string[]): TabDefinition[];
+/**
+ * Create filter tabs (common pattern).
+ *
+ * @param filters - Array of filter names
+ * @returns Tab definitions with 'all' as first tab
+ */
+export declare function createFilterTabs(filters: string[]): TabDefinition[];

package/dist/ui/features/tab-feature.js

@@ -0,0 +1,307 @@
+/**
+ * Tab Feature
+ *
+ * Composable feature for tab/filter navigation.
+ * Handles Tab/Shift+Tab and number keys for tab switching.
+ *
+ * Note: Arrow keys (←→/hl) are NOT used for tabs - they are reserved
+ * for page navigation in paginated overlays. This ensures consistent
+ * keyboard behavior across all overlays.
+ *
+ * Usage:
+ * ```typescript
+ * const TABS = [
+ *   { id: 'all', label: 'All' },
+ *   { id: 'active', label: 'Active' },
+ *   { id: 'completed', label: 'Completed' },
+ * ];
+ *
+ * interface MyState extends OverlayState, TabState {
+ *   // ...
+ * }
+ *
+ * class MyOverlay extends BaseOverlay<MyState, void> {
+ *   private tabFeature = new TabFeature(TABS, (tabId) => {
+ *     this.onTabChange(tabId);
+ *   });
+ *
+ *   handleKey(data: Buffer): void {
+ *     const result = this.tabFeature.handleKey(data, this.state);
+ *     if (result?.handled) {
+ *       if (result.action === 'render') this.update();
+ *       return;
+ *     }
+ *     // ... other key handling
+ *   }
+ *
+ *   render(): string[] {
+ *     return [
+ *       ...this.renderHeader('My Overlay'),
+ *       ' ' + this.tabFeature.renderTabs(this.state, this.styles),
+ *       '',
+ *       // ... content
+ *       ...this.renderFooter(this.tabFeature.renderHints() + ' · ↑↓/jk Navigate')
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+import { isTab, isShiftTab, getNumberKey, } from '../base/key-utils.js';
+// =============================================================================
+// TabFeature Class
+// =============================================================================
+/**
+ * Feature for tab/filter navigation.
+ *
+ * Handles:
+ * - Tab/Shift+Tab for cycling tabs
+ * - Number keys 1-9 for direct selection (optional)
+ *
+ * Note: Arrow keys are NOT handled - they are reserved for pagination.
+ */
+export class TabFeature {
+    config;
+    /**
+     * Create a new TabFeature.
+     *
+     * @param tabs - Tab definitions
+     * @param onChange - Optional callback when tab changes
+     */
+    constructor(tabs, onChange) {
+        this.config = {
+            tabs,
+            onChange,
+            useNumberKeys: tabs.length <= 9,
+            wrapNavigation: true,
+        };
+    }
+    /**
+     * Create from config object (alternative constructor).
+     */
+    static fromConfig(config) {
+        const feature = new TabFeature(config.tabs, config.onChange);
+        if (config.useNumberKeys !== undefined) {
+            feature.config.useNumberKeys = config.useNumberKeys;
+        }
+        if (config.wrapNavigation !== undefined) {
+            feature.config.wrapNavigation = config.wrapNavigation;
+        }
+        return feature;
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    /**
+     * Handle a key press.
+     *
+     * @param data - Raw key buffer
+     * @param state - State containing currentTab
+     * @returns KeyResult if handled, null otherwise
+     */
+    handleKey(data, state) {
+        const tabCount = this.config.tabs.length;
+        if (tabCount === 0) {
+            return null; // No tabs
+        }
+        // Tab - next tab
+        if (isTab(data)) {
+            const newIndex = this.config.wrapNavigation
+                ? (state.currentTab + 1) % tabCount
+                : Math.min(state.currentTab + 1, tabCount - 1);
+            if (newIndex !== state.currentTab) {
+                state.currentTab = newIndex;
+                this.notifyChange(state);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true }; // At end, consume but no change
+        }
+        // Shift+Tab - previous tab
+        if (isShiftTab(data)) {
+            const newIndex = this.config.wrapNavigation
+                ? (state.currentTab - 1 + tabCount) % tabCount
+                : Math.max(state.currentTab - 1, 0);
+            if (newIndex !== state.currentTab) {
+                state.currentTab = newIndex;
+                this.notifyChange(state);
+                return { handled: true, action: 'render' };
+            }
+            return { handled: true }; // At start, consume but no change
+        }
+        // Number keys 1-9 for direct selection
+        if (this.config.useNumberKeys) {
+            const num = getNumberKey(data);
+            if (num !== null && num >= 1 && num <= tabCount) {
+                const newIndex = num - 1;
+                if (newIndex !== state.currentTab) {
+                    state.currentTab = newIndex;
+                    this.notifyChange(state);
+                    return { handled: true, action: 'render' };
+                }
+                return { handled: true }; // Already on this tab
+            }
+        }
+        return null; // Not handled
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    /**
+     * Render tabs in a row.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string
+     */
+    renderTabs(state, styles) {
+        return this.config.tabs
+            .map((tab, index) => {
+            const label = ` ${tab.label} `;
+            return index === state.currentTab
+                ? styles.selected(label)
+                : styles.muted(label);
+        })
+            .join('');
+    }
+    /**
+     * Render tabs with number key hints.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @returns Rendered tab bar string with numbers
+     */
+    renderTabsWithNumbers(state, styles) {
+        return this.config.tabs
+            .map((tab, index) => {
+            const num = String(index + 1);
+            const label = ` ${num}:${tab.label} `;
+            return index === state.currentTab
+                ? styles.selected(label)
+                : styles.muted(label);
+        })
+            .join('');
+    }
+    /**
+     * Render tabs with custom separator.
+     *
+     * @param state - State containing currentTab
+     * @param styles - Theme styles
+     * @param separator - Separator between tabs (default: '')
+     * @returns Rendered tab bar string
+     */
+    renderTabsWithSeparator(state, styles, separator = '') {
+        return this.config.tabs
+            .map((tab, index) => {
+            const label = ` ${tab.label} `;
+            return index === state.currentTab
+                ? styles.selected(label)
+                : styles.muted(label);
+        })
+            .join(separator);
+    }
+    /**
+     * Render keyboard hints for tabs.
+     *
+     * @returns Hint string like "Tab Switch · 1-5 Jump"
+     */
+    renderHints() {
+        const tabCount = this.config.tabs.length;
+        if (tabCount === 0) {
+            return '';
+        }
+        if (this.config.useNumberKeys && tabCount <= 9) {
+            return `Tab Switch · 1-${String(tabCount)} Jump`;
+        }
+        return 'Tab Switch';
+    }
+    // ===========================================================================
+    // Utilities
+    // ===========================================================================
+    /**
+     * Get the current tab definition.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab or undefined
+     */
+    getCurrentTab(state) {
+        return this.config.tabs[state.currentTab];
+    }
+    /**
+     * Get the current tab ID.
+     *
+     * @param state - State containing currentTab
+     * @returns Current tab ID or empty string
+     */
+    getCurrentTabId(state) {
+        return this.config.tabs[state.currentTab]?.id ?? '';
+    }
+    /**
+     * Get the number of tabs.
+     */
+    getTabCount() {
+        return this.config.tabs.length;
+    }
+    /**
+     * Find tab index by ID.
+     *
+     * @param tabId - Tab ID to find
+     * @returns Index or -1 if not found
+     */
+    findTabIndex(tabId) {
+        return this.config.tabs.findIndex((t) => t.id === tabId);
+    }
+    /**
+     * Set current tab by ID.
+     *
+     * @param state - State to modify
+     * @param tabId - Tab ID to select
+     * @returns true if tab was found and selected
+     */
+    setTabById(state, tabId) {
+        const index = this.findTabIndex(tabId);
+        if (index >= 0) {
+            state.currentTab = index;
+            return true;
+        }
+        return false;
+    }
+    // ===========================================================================
+    // Private Methods
+    // ===========================================================================
+    notifyChange(state) {
+        if (this.config.onChange) {
+            const tab = this.config.tabs[state.currentTab];
+            this.config.onChange(tab.id, state.currentTab);
+        }
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Create tab definitions from an array of strings.
+ * IDs are lowercase versions of labels.
+ *
+ * @param labels - Tab labels
+ * @returns Tab definitions
+ */
+export function createTabsFromLabels(labels) {
+    return labels.map((label) => ({
+        id: label.toLowerCase().replace(/\s+/g, '-'),
+        label,
+    }));
+}
+/**
+ * Create filter tabs (common pattern).
+ *
+ * @param filters - Array of filter names
+ * @returns Tab definitions with 'all' as first tab
+ */
+export function createFilterTabs(filters) {
+    return [
+        { id: 'all', label: 'All' },
+        ...filters.map((f) => ({
+            id: f.toLowerCase().replace(/\s+/g, '-'),
+            label: f,
+        })),
+    ];
+}

package/dist/ui/file-autocomplete.d.ts

@@ -39,6 +39,30 @@ export declare function replaceAtMention(input: string, cursorPos: number, compl
     input: string;
     cursorPos: number;
 };
+/**
+ * Extract the $ mention being typed at the cursor position
+ * Returns the partial text after $ if in a $ context, null otherwise
+ *
+ * @param input - The current line text
+ * @param cursorPos - Current cursor position within the line
+ * @returns The partial agent name after $, or null if not in $ context
+ */
+export declare function extractDollarMention(input: string, cursorPos: number): {
+    partial: string;
+    startPos: number;
+} | null;
+/**
+ * Replace the $ mention with completed agent name
+ *
+ * @param input - Full input text
+ * @param cursorPos - Current cursor position
+ * @param agentId - The completed agent ID to insert
+ * @returns New input text and new cursor position
+ */
+export declare function replaceDollarMention(input: string, cursorPos: number, agentId: string): {
+    input: string;
+    cursorPos: number;
+};
 /**
  * Clear the file cache (call when cwd changes)
  */

package/dist/ui/file-autocomplete.js

@@ -228,6 +228,62 @@ export function replaceAtMention(input, cursorPos, completedPath) {
     const newCursorPos = atPos + 1 + completedPath.length;
     return { input: newInput, cursorPos: newCursorPos };
 }
+/**
+ * Extract the $ mention being typed at the cursor position
+ * Returns the partial text after $ if in a $ context, null otherwise
+ *
+ * @param input - The current line text
+ * @param cursorPos - Current cursor position within the line
+ * @returns The partial agent name after $, or null if not in $ context
+ */
+export function extractDollarMention(input, cursorPos) {
+    // Look backwards from cursor to find $
+    let start = cursorPos - 1;
+    while (start >= 0) {
+        const char = input[start];
+        // Found $
+        if (char === '$') {
+            // Make sure it's at start or after whitespace
+            if (start === 0 || /\s/.test(input[start - 1])) {
+                return {
+                    partial: input.slice(start + 1, cursorPos),
+                    startPos: start,
+                };
+            }
+            return null;
+        }
+        // Hit whitespace without finding $ - not in $ context
+        if (/\s/.test(char)) {
+            return null;
+        }
+        start--;
+    }
+    return null;
+}
+/**
+ * Replace the $ mention with completed agent name
+ *
+ * @param input - Full input text
+ * @param cursorPos - Current cursor position
+ * @param agentId - The completed agent ID to insert
+ * @returns New input text and new cursor position
+ */
+export function replaceDollarMention(input, cursorPos, agentId) {
+    // Find the $ position
+    let dollarPos = cursorPos - 1;
+    while (dollarPos >= 0 && input[dollarPos] !== '$') {
+        dollarPos--;
+    }
+    if (dollarPos < 0) {
+        return { input, cursorPos };
+    }
+    // Replace from $ to cursor with the completed agent + space
+    const before = input.slice(0, dollarPos);
+    const after = input.slice(cursorPos);
+    const newInput = `${before}$${agentId} ${after}`;
+    const newCursorPos = dollarPos + 1 + agentId.length + 1; // +1 for $ +1 for space
+    return { input: newInput, cursorPos: newCursorPos };
+}
 /**
  * Clear the file cache (call when cwd changes)
  */

package/dist/ui/footer-renderer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Footer renderer.
+ *
+ * Extracted from TerminalUI — owns render state (line height tracking,
+ * spinner animation) and the render pipeline (clear, render, line builders).
+ * Reads application state through the host's getRenderData() snapshot.
+ */
+import type { TodoItem, AgentMode } from './types.js';
+import type { TerminalUIConfig } from './terminal-types.js';
+import type { TurnMetrics } from './turn-metrics.js';
+import type { StatusBarController } from './status-bar-controller.js';
+import type { AutocompleteController } from './autocomplete-controller.js';
+import type { LiveRegion } from './live-region.js';
+export interface FooterRendererHost {
+    /** Check if footer rendering should proceed. */
+    isFooterRenderAllowed(): boolean;
+    /** Build a snapshot of application state for the render pipeline. */
+    getRenderData(): FooterRenderData;
+}
+export interface FooterRenderData {
+    liveRegion: LiveRegion;
+    liveVerbose: boolean;
+    agentRunning: boolean;
+    currentTool: string | null;
+    spinnerText: string | null;
+    activeBashInfo: {
+        toolUseId: string;
+        startTime: number;
+    } | null;
+    turnMetrics: TurnMetrics;
+    todos: TodoItem[];
+    showTodos: boolean;
+    lines: readonly string[];
+    currentLine: number;
+    cursorPos: number;
+    queuedInputs: readonly string[];
+    suggestion: string | null;
+    promptPrefix: string;
+    promptPrefixLen: number;
+    ac: AutocompleteController;
+    statusBar: StatusBarController;
+    mode: AgentMode;
+    activePlanName: string | null;
+    activeTeamAgent: {
+        id: string;
+        displayName: string;
+        mascot: string;
+    } | null;
+    projectName: string | null;
+    conversationFilterActive: boolean;
+    hasRestoredHistory: boolean;
+    config: TerminalUIConfig;
+}
+export declare class FooterRenderer {
+    private lastRenderHeight;
+    private cursorLineFromBottom;
+    private spinnerFrame;
+    private spinnerTimer;
+    private readonly spinnerFrames;
+    private readonly host;
+    constructor(host: FooterRendererHost);
+    clear(): void;
+    render(): void;
+    resetRenderState(): void;
+    startSpinnerAnimation(onTick: () => void): void;
+    stopSpinnerAnimation(): void;
+    private buildSpinnerLine;
+    private buildModeLine;
+}