@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/base/tabbed-list-overlay.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Tabbed List Overlay Base Class
+ *
+ * A reusable base for overlays that display:
+ * - Tabs for filtering/categorizing
+ * - A paginated list of items
+ * - Search mode (activated with /)
+ * - Detail view (via ScreenStack)
+ *
+ * This provides ~80% of the common overlay functionality,
+ * leaving only item-specific rendering to be customized.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyItem { name: string; description: string; }
+ *
+ * const TABS = [
+ *   { id: 'all', label: 'All' },
+ *   { id: 'active', label: 'Active' },
+ * ];
+ *
+ * class MyOverlay extends TabbedListOverlay<MyItem, MyResult> {
+ *   constructor(items: MyItem[]) {
+ *     super({
+ *       title: 'My Items',
+ *       tabs: TABS,
+ *       items,
+ *       pageSize: 12,
+ *       filterByTab: (item, tabId) => tabId === 'all' || item.active,
+ *       getSearchText: (item) => `${item.name} ${item.description}`,
+ *       renderItem: (item, isSelected, styles) => {
+ *         const prefix = isSelected ? '❯ ' : '  ';
+ *         return prefix + item.name;
+ *       },
+ *     });
+ *   }
+ *
+ *   // Optional: Override to add detail view
+ *   protected createDetailScreen(item: MyItem): BaseScreen | null {
+ *     return new MyDetailScreen(item, this.styles);
+ *   }
+ * }
+ * ```
+ */
+import { BaseOverlay, type OverlayState } from './overlay-base.js';
+import { BaseScreen, ScreenStack } from './screen-stack.js';
+import { type PaginationState } from '../features/pagination-feature.js';
+import { type SearchState } from '../features/search-feature.js';
+import type { TabDefinition, TabState } from './overlay-types.js';
+/**
+ * Configuration for a TabbedListOverlay.
+ */
+export interface TabbedListConfig<TItem> {
+    /** Title shown in header */
+    title: string;
+    /** Tab definitions */
+    tabs: TabDefinition[];
+    /** All items (will be filtered by tab and search) */
+    items: TItem[];
+    /** Number of items per page (default: 12) */
+    pageSize?: number;
+    /**
+     * Filter items by tab.
+     * Return true to include item in the current tab.
+     */
+    filterByTab: (item: TItem, tabId: string) => boolean;
+    /**
+     * Get searchable text from an item.
+     * Used for search filtering.
+     */
+    getSearchText: (item: TItem) => string;
+    /**
+     * Render an item as a string line.
+     * @param item - The item to render
+     * @param isSelected - Whether this item is currently selected
+     * @param styles - Theme styles
+     * @returns Single line string
+     */
+    renderItem: (item: TItem, isSelected: boolean, styles: ReturnType<typeof import('../../themes/index.js').getStyles>) => string;
+    /**
+     * Optional: Show count badge in header (default: true)
+     */
+    showCount?: boolean;
+    /**
+     * Optional: Custom empty state message
+     */
+    emptyMessage?: string;
+    /**
+     * Optional: Custom no-results message
+     */
+    noResultsMessage?: string;
+    /**
+     * Optional: Custom footer hints
+     * @param searchMode - Whether search mode is active
+     * @returns Footer hints string
+     */
+    footerHints?: (searchMode: boolean) => string;
+    /**
+     * Optional: Render preview content for the selected item
+     * Displayed between the list and footer
+     * @param item - The currently selected item
+     * @param styles - Theme styles
+     * @returns Array of lines to render
+     */
+    renderSelectedPreview?: (item: TItem, styles: ReturnType<typeof import('../../themes/index.js').getStyles>) => string[];
+    /**
+     * Optional: Whether detail screens take over full screen.
+     * When true (default), returning from a detail screen clears the screen.
+     * When false, screens render in-place without clearing.
+     */
+    detailScreensFullScreen?: boolean;
+}
+/**
+ * State for TabbedListOverlay.
+ */
+export interface TabbedListState<TItem> extends OverlayState, TabState, PaginationState, SearchState {
+    /** All items */
+    items: TItem[];
+    /** Filtered items (by tab and search) */
+    filteredItems: TItem[];
+    /** Whether search mode is active */
+    searchMode: boolean;
+}
+/**
+ * Abstract base class for tabbed list overlays.
+ *
+ * Provides:
+ * - Tab-based filtering
+ * - Search mode with / toggle
+ * - Paginated item display
+ * - ScreenStack for detail views
+ *
+ * Subclasses can override createDetailScreen() to add detail views.
+ */
+export declare abstract class TabbedListOverlay<TItem, TResult = void> extends BaseOverlay<TabbedListState<TItem>, TResult> {
+    protected readonly screenStack: ScreenStack;
+    protected readonly listConfig: TabbedListConfig<TItem>;
+    private resizeHandler;
+    constructor(config: TabbedListConfig<TItem>);
+    /**
+     * Override to create a detail screen for an item.
+     * Return null to disable detail view.
+     */
+    protected createDetailScreen(_item: TItem): BaseScreen | null;
+    show(): Promise<TResult>;
+    protected close(result: TResult): void;
+    render(): string[];
+    handleKey(data: Buffer): void;
+    /**
+     * Get the currently selected item.
+     */
+    protected getSelectedItem(): TItem | undefined;
+}

package/dist/ui/base/tabbed-list-overlay.js

@@ -0,0 +1,369 @@
+/**
+ * Tabbed List Overlay Base Class
+ *
+ * A reusable base for overlays that display:
+ * - Tabs for filtering/categorizing
+ * - A paginated list of items
+ * - Search mode (activated with /)
+ * - Detail view (via ScreenStack)
+ *
+ * This provides ~80% of the common overlay functionality,
+ * leaving only item-specific rendering to be customized.
+ *
+ * Usage:
+ * ```typescript
+ * interface MyItem { name: string; description: string; }
+ *
+ * const TABS = [
+ *   { id: 'all', label: 'All' },
+ *   { id: 'active', label: 'Active' },
+ * ];
+ *
+ * class MyOverlay extends TabbedListOverlay<MyItem, MyResult> {
+ *   constructor(items: MyItem[]) {
+ *     super({
+ *       title: 'My Items',
+ *       tabs: TABS,
+ *       items,
+ *       pageSize: 12,
+ *       filterByTab: (item, tabId) => tabId === 'all' || item.active,
+ *       getSearchText: (item) => `${item.name} ${item.description}`,
+ *       renderItem: (item, isSelected, styles) => {
+ *         const prefix = isSelected ? '❯ ' : '  ';
+ *         return prefix + item.name;
+ *       },
+ *     });
+ *   }
+ *
+ *   // Optional: Override to add detail view
+ *   protected createDetailScreen(item: MyItem): BaseScreen | null {
+ *     return new MyDetailScreen(item, this.styles);
+ *   }
+ * }
+ * ```
+ */
+import * as terminal from '../terminal.js';
+import { BaseOverlay } from './overlay-base.js';
+import { BaseScreen, ScreenStack, stay, pushScreen, closeOverlay } from './screen-stack.js';
+import { TabFeature } from '../features/tab-feature.js';
+import { PaginationFeature } from '../features/pagination-feature.js';
+import { SearchFeature } from '../features/search-feature.js';
+import { isCtrlC, isClose, isEscape, isSlash, isEnter } from './key-utils.js';
+import { renderBorder } from './render-utils.js';
+// =============================================================================
+// List Screen (Main View)
+// =============================================================================
+/**
+ * The main list screen for TabbedListOverlay.
+ * Handles tabs, search, pagination, and item display.
+ */
+class ListScreen extends BaseScreen {
+    config;
+    state;
+    styles;
+    createDetailScreen;
+    tabFeature;
+    pagination;
+    searchFeature;
+    hasBeenPushedTo = false;
+    constructor(config, state, styles, createDetailScreen) {
+        super();
+        this.config = config;
+        this.state = state;
+        this.styles = styles;
+        this.createDetailScreen = createDetailScreen;
+        this.tabFeature = new TabFeature(config.tabs, () => {
+            this.onTabChange();
+        });
+        this.pagination = new PaginationFeature({
+            pageSize: config.pageSize ?? 12,
+        });
+        this.searchFeature = new SearchFeature({
+            onSearch: () => { this.applyFilters(); },
+            escapeClearsSearch: false,
+        });
+    }
+    /**
+     * Called when returning from a detail screen.
+     * Clear screen if we came back from a full-screen view.
+     * (resetRenderState() will handle cursor positioning)
+     */
+    onEnter() {
+        if (this.hasBeenPushedTo && this.config.detailScreensFullScreen !== false) {
+            // Returning from a full-screen detail screen - clear screen
+            terminal.clearScreen();
+        }
+    }
+    /**
+     * Called when navigating to a detail screen.
+     */
+    onExit() {
+        this.hasBeenPushedTo = true;
+    }
+    onTabChange() {
+        this.state.selectedIndex = 0;
+        this.state.scrollOffset = 0;
+        this.state.searchMode = false;
+        this.state.searchQuery = '';
+        this.applyFilters();
+    }
+    applyFilters() {
+        const tabId = this.tabFeature.getCurrentTabId(this.state);
+        // Filter by tab
+        let filtered = this.state.items.filter((item) => this.config.filterByTab(item, tabId));
+        // Filter by search
+        if (this.state.searchQuery) {
+            filtered = this.searchFeature.filterItems(filtered, this.state, this.config.getSearchText);
+        }
+        this.state.filteredItems = filtered;
+        this.state.selectedIndex = 0;
+        this.state.scrollOffset = 0;
+    }
+    render() {
+        const s = this.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = renderBorder(cols, s);
+        const pageSize = this.config.pageSize ?? 12;
+        const lines = [];
+        // Header
+        lines.push(border);
+        const showCount = this.config.showCount ?? true;
+        const countBadge = showCount
+            ? s.muted(` [${String(this.state.filteredItems.length)}/${String(this.state.items.length)}]`)
+            : '';
+        lines.push(`  ${s.primaryBold(this.config.title)}${countBadge}`);
+        lines.push('');
+        // Tab bar with hint
+        const tabBar = this.tabFeature.renderTabs(this.state, s);
+        const tabHint = s.muted(`(${this.tabFeature.renderHints()})`);
+        lines.push(`  ${tabBar}  ${tabHint}`);
+        lines.push('');
+        // Search box (if in search mode)
+        if (this.state.searchMode) {
+            const query = this.state.searchQuery;
+            lines.push(`  ${s.muted('Search:')} ${query ? s.primary(query) : ''}█`);
+            lines.push('');
+        }
+        // Items
+        const visibleItems = this.pagination.getVisibleItems(this.state, this.state.filteredItems);
+        if (visibleItems.length === 0) {
+            const msg = this.state.searchQuery
+                ? (this.config.noResultsMessage ?? 'No items match the search.')
+                : (this.config.emptyMessage ?? 'No items available.');
+            lines.push(`    ${s.muted(msg)}`);
+            for (let i = 0; i < pageSize - 1; i++) {
+                lines.push('');
+            }
+        }
+        else {
+            for (let i = 0; i < visibleItems.length; i++) {
+                const item = visibleItems[i];
+                const absoluteIndex = this.state.scrollOffset + i;
+                const isSelected = absoluteIndex === this.state.selectedIndex;
+                lines.push(this.config.renderItem(item, isSelected, s));
+            }
+            // Pad to fixed height
+            for (let i = visibleItems.length; i < pageSize; i++) {
+                lines.push('');
+            }
+        }
+        // Pagination indicator
+        lines.push('');
+        const indicator = this.pagination.renderIndicator(this.state, this.state.filteredItems.length, s);
+        if (indicator) {
+            lines.push(indicator);
+        }
+        // Selected item preview (if configured)
+        if (this.config.renderSelectedPreview && visibleItems.length > 0) {
+            const selectedItem = this.state.filteredItems[this.state.selectedIndex];
+            if (selectedItem) {
+                lines.push('');
+                const previewLines = this.config.renderSelectedPreview(selectedItem, s);
+                lines.push(...previewLines);
+            }
+        }
+        // Footer
+        lines.push(border);
+        lines.push(`  ${s.muted(this.getFooterHints())}`);
+        lines.push(border);
+        return lines;
+    }
+    getFooterHints() {
+        // Use custom footer hints if provided
+        if (this.config.footerHints) {
+            return this.config.footerHints(this.state.searchMode);
+        }
+        // Default footer hints
+        if (this.state.searchMode) {
+            return 'Type to filter · ↑↓/jk Navigate · Enter Details · Esc Exit search';
+        }
+        return this.pagination.renderHints() + ' · / Search · Enter Details · q/Esc Close';
+    }
+    handleKey(data) {
+        // Ctrl+C always closes
+        if (isCtrlC(data)) {
+            return closeOverlay(undefined);
+        }
+        // Search mode handling
+        if (this.state.searchMode) {
+            if (isEscape(data)) {
+                this.state.searchMode = false;
+                if (this.state.searchQuery) {
+                    this.state.searchQuery = '';
+                    this.applyFilters();
+                }
+                return stay();
+            }
+            const searchResult = this.searchFeature.handleKey(data, this.state);
+            if (searchResult?.handled) {
+                return searchResult.action === 'render' ? stay() : stay(false);
+            }
+            if (isEnter(data)) {
+                return this.handleEnter();
+            }
+            const paginationResult = this.pagination.handleKey(data, this.state, this.state.filteredItems.length);
+            if (paginationResult?.handled) {
+                return paginationResult.action === 'render' ? stay() : stay(false);
+            }
+            return stay(false);
+        }
+        // Not in search mode
+        if (isSlash(data)) {
+            this.state.searchMode = true;
+            return stay();
+        }
+        if (isClose(data)) {
+            return closeOverlay(undefined);
+        }
+        // Tab navigation
+        const tabResult = this.tabFeature.handleKey(data, this.state);
+        if (tabResult?.handled) {
+            return tabResult.action === 'render' ? stay() : stay(false);
+        }
+        // Enter shows detail
+        if (isEnter(data)) {
+            return this.handleEnter();
+        }
+        // Pagination
+        const paginationResult = this.pagination.handleKey(data, this.state, this.state.filteredItems.length);
+        if (paginationResult?.handled) {
+            return paginationResult.action === 'render' ? stay() : stay(false);
+        }
+        return stay(false);
+    }
+    handleEnter() {
+        if (this.state.filteredItems.length === 0) {
+            return stay(false);
+        }
+        const item = this.state.filteredItems[this.state.selectedIndex];
+        const detailScreen = this.createDetailScreen(item);
+        if (detailScreen) {
+            return pushScreen(detailScreen);
+        }
+        return stay(false);
+    }
+}
+// =============================================================================
+// TabbedListOverlay Base Class
+// =============================================================================
+/**
+ * Abstract base class for tabbed list overlays.
+ *
+ * Provides:
+ * - Tab-based filtering
+ * - Search mode with / toggle
+ * - Paginated item display
+ * - ScreenStack for detail views
+ *
+ * Subclasses can override createDetailScreen() to add detail views.
+ */
+export class TabbedListOverlay extends BaseOverlay {
+    screenStack;
+    listConfig;
+    resizeHandler = null;
+    constructor(config) {
+        const initialState = {
+            lineCount: 0,
+            maxLineCount: 0,
+            currentTab: 0,
+            selectedIndex: 0,
+            scrollOffset: 0,
+            searchQuery: '',
+            searchMode: false,
+            items: config.items,
+            filteredItems: config.items.filter((item) => config.filterByTab(item, config.tabs[0]?.id ?? 'all')),
+        };
+        super(initialState);
+        this.listConfig = config;
+        this.screenStack = new ScreenStack();
+        this.screenStack.push(new ListScreen(config, this.state, this.styles, (item) => this.createDetailScreen(item)));
+    }
+    /**
+     * Override to create a detail screen for an item.
+     * Return null to disable detail view.
+     */
+    createDetailScreen(_item) {
+        return null;
+    }
+    async show() {
+        // Add resize handler
+        this.resizeHandler = () => {
+            this.update();
+        };
+        process.stdout.on('resize', this.resizeHandler);
+        return super.show();
+    }
+    close(result) {
+        if (this.resizeHandler) {
+            process.stdout.removeListener('resize', this.resizeHandler);
+            this.resizeHandler = null;
+        }
+        super.close(result);
+    }
+    render() {
+        const screen = this.screenStack.current();
+        return screen?.render() ?? [];
+    }
+    handleKey(data) {
+        const screen = this.screenStack.current();
+        if (!screen) {
+            this.close(undefined);
+            return;
+        }
+        const result = screen.handleKey(data);
+        switch (result.action) {
+            case 'stay':
+                if (result.render) {
+                    this.update();
+                }
+                break;
+            case 'push':
+                this.screenStack.push(result.screen);
+                // Reset overlay state after screen change (screen's onEnter may have cleared screen)
+                // Skip for in-place rendering (detailScreensFullScreen: false)
+                if (this.listConfig.detailScreensFullScreen !== false) {
+                    this.resetRenderState();
+                }
+                this.update();
+                break;
+            case 'pop':
+                this.screenStack.pop();
+                // Reset overlay state after screen change (screen's onEnter may have cleared screen)
+                // Skip for in-place rendering (detailScreensFullScreen: false)
+                if (this.listConfig.detailScreensFullScreen !== false) {
+                    this.resetRenderState();
+                }
+                this.update();
+                break;
+            case 'close':
+                this.close(result.result);
+                break;
+        }
+    }
+    /**
+     * Get the currently selected item.
+     */
+    getSelectedItem() {
+        return this.state.filteredItems[this.state.selectedIndex];
+    }
+}

package/dist/ui/constants/labels.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared Label Constants
+ *
+ * Centralized display labels for domain types used across multiple overlays.
+ */
+import type { ArtifactType } from '../../multi-agent/index.js';
+import type { DocumentType, PlanStatus } from '../../db/schema.js';
+export declare const ARTIFACT_TYPE_LABELS: Record<ArtifactType, string>;
+export declare const DOC_TYPE_LABELS: Record<DocumentType, string>;
+/** Icon-only labels for compact display (e.g., list views) */
+export declare const PLAN_STATUS_ICONS: Record<PlanStatus, string>;
+/** Icon + text labels for detailed display (e.g., detail views) */
+export declare const PLAN_STATUS_LABELS: Record<PlanStatus, string>;
+export declare const PLAN_STATUS_COLORS: Record<PlanStatus, 'muted' | 'warning' | 'primary' | 'success' | 'error'>;

package/dist/ui/constants/labels.js

@@ -0,0 +1,51 @@
+/**
+ * Shared Label Constants
+ *
+ * Centralized display labels for domain types used across multiple overlays.
+ */
+// =============================================================================
+// Artifact Labels
+// =============================================================================
+export const ARTIFACT_TYPE_LABELS = {
+    'design': 'DESIGN',
+    'plan': 'PLAN',
+    'review': 'REVIEW',
+    'decision': 'DECISION',
+    'note': 'NOTE',
+};
+// =============================================================================
+// Document Labels
+// =============================================================================
+export const DOC_TYPE_LABELS = {
+    'prd': 'PRD',
+    'architecture': 'ARCH',
+    'design': 'DESIGN',
+    'notes': 'NOTES',
+    'plan': 'PLAN',
+};
+// =============================================================================
+// Plan Status Labels
+// =============================================================================
+/** Icon-only labels for compact display (e.g., list views) */
+export const PLAN_STATUS_ICONS = {
+    'draft': '○',
+    'approved': '◐',
+    'in_progress': '◑',
+    'completed': '●',
+    'abandoned': '✗',
+};
+/** Icon + text labels for detailed display (e.g., detail views) */
+export const PLAN_STATUS_LABELS = {
+    'draft': '○ Draft',
+    'approved': '◐ Approved',
+    'in_progress': '◑ In Progress',
+    'completed': '● Completed',
+    'abandoned': '✗ Abandoned',
+};
+export const PLAN_STATUS_COLORS = {
+    'draft': 'muted',
+    'approved': 'warning',
+    'in_progress': 'primary',
+    'completed': 'success',
+    'abandoned': 'error',
+};

package/dist/ui/conversation-store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Conversation history and filtering.
+ *
+ * Extracted from TerminalUI — owns conversation data, restored history,
+ * and agent-based filtering. Rendering orchestration stays on TerminalUI.
+ */
+import type { PrintableItem } from './terminal-types.js';
+export declare class ConversationStore {
+    /** All printed items (stored for re-rendering on config change). */
+    history: PrintableItem[];
+    /** Session history for Ctrl+R replay. */
+    restoredHistory: PrintableItem[];
+    /** Agent-based conversation filter. */
+    private filter;
+    /** Add an item to conversation history. */
+    addItem(item: PrintableItem): void;
+    /** Get a copy of conversation history. */
+    getHistory(): PrintableItem[];
+    /** Clear all conversation history. */
+    clearHistory(): void;
+    /** Store restored conversation items for Ctrl+R history view. */
+    setRestoredHistory(items: PrintableItem[]): void;
+    /** Check if there is restored history available. */
+    hasRestoredHistory(): boolean;
+    /**
+     * Set conversation filter to show only specific agents.
+     * Pass empty array to show all agents.
+     */
+    setFilter(agentIds: string[]): void;
+    /** Clear conversation filter (show all agents). */
+    clearFilter(): void;
+    /** Get current conversation filter state. */
+    getFilter(): {
+        agentIds: string[];
+        isActive: boolean;
+    };
+    /** Whether the filter is currently active. */
+    get isFilterActive(): boolean;
+    /** Get the set of filtered agent IDs (for display). */
+    get filterAgentIds(): ReadonlySet<string>;
+    /**
+     * Add an agent to the conversation filter (auto-expand).
+     * Returns true if agent was added, false if filter not active or agent already included.
+     */
+    addToFilter(agentId: string): boolean;
+    /**
+     * Check if an agent is in the current filter (or filter is inactive).
+     * Returns true if messages from this agent would be shown.
+     */
+    isAgentInFilter(agentId: string): boolean;
+    /**
+     * Check if an item should be shown based on current filter.
+     */
+    shouldShowItem(item: PrintableItem): boolean;
+}