@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/live-region.d.ts

@@ -0,0 +1,161 @@
+/**
+ * LiveRegion - Unified Live-Updating Zone for Running Tools
+ *
+ * Manages the display of running tools (bash, subagents) that need live updates.
+ * Sits at the top of the footer, commits to scrolling zone on completion.
+ *
+ * Key features:
+ * - Single subagent: Full detail with tool history
+ * - Multiple subagents: Tree structure with summary header
+ * - Bash commands: Rolling output lines
+ * - Ephemeral notifications on completion
+ */
+/**
+ * Types of live items that can be displayed
+ */
+export type LiveItemType = 'bash' | 'subagent' | 'tool';
+/**
+ * Status of a live item
+ */
+export type LiveItemStatus = 'running' | 'done' | 'error' | 'cancelled';
+/**
+ * Base interface for all live items
+ */
+export interface LiveItemBase {
+    id: string;
+    type: LiveItemType;
+    status: LiveItemStatus;
+    startTime: number;
+    endTime?: number;
+    background?: boolean;
+}
+/**
+ * Bash command live item
+ */
+export interface BashLiveItem extends LiveItemBase {
+    type: 'bash';
+    command: string;
+    output: string[];
+    exitCode?: number;
+}
+/**
+ * Subagent live item
+ */
+export interface SubagentLiveItem extends LiveItemBase {
+    type: 'subagent';
+    agentType: string;
+    description: string;
+    toolCount: number;
+    tokenCount: number;
+    lastAction: string;
+    lastActionDetails: string[];
+}
+/**
+ * Generic tool live item
+ */
+export interface ToolLiveItem extends LiveItemBase {
+    type: 'tool';
+    name: string;
+    params: string;
+    progress?: string;
+}
+/**
+ * Union type for all live items
+ */
+export type LiveItem = BashLiveItem | SubagentLiveItem | ToolLiveItem;
+/**
+ * Render options for LiveRegion
+ */
+export interface LiveRegionRenderOptions {
+    width: number;
+    verbose: boolean;
+    showTokens: boolean;
+}
+export declare class LiveRegion {
+    private readonly items;
+    private ephemeralNotifications;
+    private maxOutputLines;
+    private verbose;
+    private expanded;
+    /**
+     * Add a new live item to the region.
+     */
+    addItem(item: LiveItem): void;
+    /**
+     * Update an existing live item.
+     */
+    updateItem(id: string, update: Partial<LiveItem>): void;
+    /**
+     * Mark an item as completed. Returns the final item for committing to scrolling zone.
+     */
+    completeItem(id: string, status?: LiveItemStatus): LiveItem | undefined;
+    /**
+     * Remove an item and return it (for committing to scrolling zone).
+     */
+    removeItem(id: string): LiveItem | undefined;
+    /**
+     * Get an item by ID.
+     */
+    getItem(id: string): LiveItem | undefined;
+    /**
+     * Get all current items.
+     */
+    getItems(): LiveItem[];
+    /**
+     * Check if there are any items.
+     */
+    hasItems(): boolean;
+    /**
+     * Get count of items.
+     */
+    getItemCount(): number;
+    /**
+     * Clear all items.
+     */
+    clear(): void;
+    /**
+     * Add an ephemeral notification that disappears after timeout.
+     */
+    addEphemeralNotification(message: string): void;
+    /**
+     * Clean up expired ephemeral notifications.
+     */
+    private cleanupEphemeralNotifications;
+    /**
+     * Set maximum output lines per item.
+     */
+    setMaxOutputLines(maxLines: number): void;
+    /**
+     * Set verbose mode.
+     */
+    setVerbose(verbose: boolean): void;
+    /**
+     * Toggle expanded view (Ctrl+O).
+     */
+    toggleExpanded(): void;
+    /**
+     * Get expanded state.
+     */
+    isExpanded(): boolean;
+    /**
+     * Render the live region content.
+     */
+    render(options: LiveRegionRenderOptions): string[];
+    private renderSingleSubagent;
+    private renderMultipleSubagents;
+    private renderBashItem;
+    private renderToolItem;
+    private renderEphemeralNotification;
+    /**
+     * Format token count for display (e.g., 18.1k)
+     */
+    private formatTokens;
+    /**
+     * Truncate a line to fit within width.
+     */
+    private truncateLine;
+    /**
+     * Format duration for display.
+     */
+    formatDuration(ms: number): string;
+}

package/dist/ui/live-region.js

@@ -0,0 +1,387 @@
+/**
+ * LiveRegion - Unified Live-Updating Zone for Running Tools
+ *
+ * Manages the display of running tools (bash, subagents) that need live updates.
+ * Sits at the top of the footer, commits to scrolling zone on completion.
+ *
+ * Key features:
+ * - Single subagent: Full detail with tool history
+ * - Multiple subagents: Tree structure with summary header
+ * - Bash commands: Rolling output lines
+ * - Ephemeral notifications on completion
+ */
+import { getStyles } from '../themes/index.js';
+import { getVisibleLength } from './line-utils.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const EPHEMERAL_TIMEOUT_MS = 3000; // 3 seconds
+const DEFAULT_MAX_OUTPUT_LINES = 3;
+// Tree drawing characters
+const TREE_BRANCH = '├─';
+const TREE_END = '└─';
+const TREE_CONTINUE = '│';
+const RESULT_MARKER = '⎿';
+// =============================================================================
+// LiveRegion Class
+// =============================================================================
+export class LiveRegion {
+    items = new Map();
+    ephemeralNotifications = [];
+    maxOutputLines = DEFAULT_MAX_OUTPUT_LINES;
+    verbose = false;
+    expanded = false;
+    // =========================================================================
+    // Item Management
+    // =========================================================================
+    /**
+     * Add a new live item to the region.
+     */
+    addItem(item) {
+        this.items.set(item.id, item);
+    }
+    /**
+     * Update an existing live item.
+     */
+    updateItem(id, update) {
+        const existing = this.items.get(id);
+        if (existing) {
+            // Merge update into existing item (type assertion needed due to union type)
+            this.items.set(id, { ...existing, ...update });
+        }
+    }
+    /**
+     * Mark an item as completed. Returns the final item for committing to scrolling zone.
+     */
+    completeItem(id, status = 'done') {
+        const item = this.items.get(id);
+        if (item) {
+            item.status = status;
+            item.endTime = Date.now();
+            // Add ephemeral notification only for background items
+            if (item.background && item.type === 'subagent') {
+                this.addEphemeralNotification(`Agent "${item.description}" completed.`);
+            }
+        }
+        return item;
+    }
+    /**
+     * Remove an item and return it (for committing to scrolling zone).
+     */
+    removeItem(id) {
+        const item = this.items.get(id);
+        this.items.delete(id);
+        return item;
+    }
+    /**
+     * Get an item by ID.
+     */
+    getItem(id) {
+        return this.items.get(id);
+    }
+    /**
+     * Get all current items.
+     */
+    getItems() {
+        return Array.from(this.items.values());
+    }
+    /**
+     * Check if there are any items.
+     */
+    hasItems() {
+        return this.items.size > 0;
+    }
+    /**
+     * Get count of items.
+     */
+    getItemCount() {
+        return this.items.size;
+    }
+    /**
+     * Clear all items.
+     */
+    clear() {
+        this.items.clear();
+        this.ephemeralNotifications = [];
+    }
+    // =========================================================================
+    // Ephemeral Notifications
+    // =========================================================================
+    /**
+     * Add an ephemeral notification that disappears after timeout.
+     */
+    addEphemeralNotification(message) {
+        this.ephemeralNotifications.push({
+            message,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Clean up expired ephemeral notifications.
+     */
+    cleanupEphemeralNotifications() {
+        const now = Date.now();
+        this.ephemeralNotifications = this.ephemeralNotifications.filter((n) => now - n.timestamp < EPHEMERAL_TIMEOUT_MS);
+    }
+    // =========================================================================
+    // Configuration
+    // =========================================================================
+    /**
+     * Set maximum output lines per item.
+     */
+    setMaxOutputLines(maxLines) {
+        this.maxOutputLines = maxLines;
+    }
+    /**
+     * Set verbose mode.
+     */
+    setVerbose(verbose) {
+        this.verbose = verbose;
+    }
+    /**
+     * Toggle expanded view (Ctrl+O).
+     */
+    toggleExpanded() {
+        this.expanded = !this.expanded;
+    }
+    /**
+     * Get expanded state.
+     */
+    isExpanded() {
+        return this.expanded;
+    }
+    // =========================================================================
+    // Rendering
+    // =========================================================================
+    /**
+     * Render the live region content.
+     */
+    render(options) {
+        const lines = [];
+        const items = this.getItems();
+        if (items.length === 0) {
+            // Only show ephemeral notifications if no items
+            this.cleanupEphemeralNotifications();
+            for (const notification of this.ephemeralNotifications) {
+                lines.push(this.renderEphemeralNotification(notification.message));
+            }
+            return lines;
+        }
+        // Separate items by type
+        const subagents = items.filter((i) => i.type === 'subagent');
+        const bashItems = items.filter((i) => i.type === 'bash');
+        const toolItems = items.filter((i) => i.type === 'tool');
+        // Render subagents (single vs multiple has different rendering)
+        if (subagents.length === 1) {
+            lines.push(...this.renderSingleSubagent(subagents[0], options));
+        }
+        else if (subagents.length > 1) {
+            lines.push(...this.renderMultipleSubagents(subagents, options));
+        }
+        // Render bash commands
+        for (const bash of bashItems) {
+            lines.push(...this.renderBashItem(bash, options));
+        }
+        // Render generic tools
+        for (const tool of toolItems) {
+            lines.push(...this.renderToolItem(tool, options));
+        }
+        // Add ephemeral notifications at the end
+        this.cleanupEphemeralNotifications();
+        for (const notification of this.ephemeralNotifications) {
+            lines.push(this.renderEphemeralNotification(notification.message));
+        }
+        return lines;
+    }
+    // =========================================================================
+    // Single Subagent Rendering
+    // =========================================================================
+    renderSingleSubagent(item, options) {
+        const s = getStyles();
+        const lines = [];
+        // Header: ● AgentType(description)
+        const statusIcon = item.status === 'done' ? ' ✓' : '';
+        const header = `${s.info('●')} ${s.primary(item.agentType)}(${item.description})${statusIcon}`;
+        lines.push(header);
+        if (item.status === 'done') {
+            // Completed: show summary
+            const duration = item.endTime ? Math.round((item.endTime - item.startTime) / 1000) : 0;
+            const tokenStr = options.showTokens ? ` · ${this.formatTokens(item.tokenCount)} tokens` : '';
+            const summary = `  ${RESULT_MARKER}  Done (${String(item.toolCount)} tool uses${tokenStr} · ${String(duration)}s)`;
+            lines.push(s.muted(summary));
+        }
+        else {
+            // Running: show last action
+            if (item.lastAction) {
+                lines.push(`  ${RESULT_MARKER}  ${s.muted(item.lastAction)}`);
+            }
+            else {
+                lines.push(`  ${RESULT_MARKER}  ${s.muted('Initializing…')}`);
+            }
+            // Show detail lines if expanded or verbose
+            if ((this.expanded || this.verbose) && item.lastActionDetails.length > 0) {
+                for (const detail of item.lastActionDetails.slice(0, this.maxOutputLines)) {
+                    lines.push(`     ${s.muted(detail)}`);
+                }
+                if (item.lastActionDetails.length > this.maxOutputLines) {
+                    const hidden = item.lastActionDetails.length - this.maxOutputLines;
+                    lines.push(`     ${s.muted(`+${String(hidden)} more tool uses`)} ${s.muted('(ctrl+o to expand)')}`);
+                }
+            }
+            // Hints
+            lines.push(`     ${s.muted('ctrl+b to run in background')}`);
+        }
+        return lines;
+    }
+    // =========================================================================
+    // Multiple Subagents Rendering (Tree Structure)
+    // =========================================================================
+    renderMultipleSubagents(items, options) {
+        const s = getStyles();
+        const lines = [];
+        // Count running vs done
+        const runningCount = items.filter((i) => i.status === 'running').length;
+        const allDone = runningCount === 0;
+        // Determine agent type label
+        const types = new Set(items.map((i) => i.agentType));
+        const typeLabel = types.size === 1 ? `${items[0].agentType} agents` : 'agents';
+        // Header: ● Running N agents… or ● N agents finished
+        if (allDone) {
+            lines.push(`${s.info('●')} ${String(items.length)} ${typeLabel} finished ${s.muted('(ctrl+o to expand)')}`);
+        }
+        else {
+            lines.push(`${s.info('●')} Running ${String(items.length)} ${typeLabel}… ${s.muted('(ctrl+o to expand)')}`);
+        }
+        // Render each agent in tree structure
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            const isLast = i === items.length - 1;
+            const branch = isLast ? TREE_END : TREE_BRANCH;
+            const continuation = isLast ? '   ' : `${TREE_CONTINUE}  `;
+            // Agent line: description · tool count · tokens
+            const tokenStr = options.showTokens ? ` · ${this.formatTokens(item.tokenCount)} tokens` : '';
+            const toolWord = item.toolCount === 1 ? 'tool use' : 'tool uses';
+            const agentLine = `   ${branch} ${item.description} · ${String(item.toolCount)} ${toolWord}${tokenStr}`;
+            lines.push(agentLine);
+            // Last action line
+            if (item.status === 'done') {
+                lines.push(`   ${continuation}${RESULT_MARKER}  ${s.muted('Done')}`);
+            }
+            else if (item.lastAction) {
+                lines.push(`   ${continuation}${RESULT_MARKER}  ${s.muted(item.lastAction)}`);
+            }
+            else {
+                lines.push(`   ${continuation}${RESULT_MARKER}  ${s.muted('Initializing…')}`);
+            }
+        }
+        // Hint at the end
+        if (!allDone) {
+            lines.push(`   ${s.muted('ctrl+b to run in background')}`);
+        }
+        return lines;
+    }
+    // =========================================================================
+    // Bash Item Rendering
+    // =========================================================================
+    renderBashItem(item, options) {
+        const s = getStyles();
+        const lines = [];
+        // Header: ● Bash(command)
+        // Handle multi-line commands - only show first line
+        // Truncate long commands - show more context than before (60 chars)
+        const maxCmdLen = Math.min(60, options.width - 15);
+        const statusIcon = item.status === 'done' ? ' ✓' : '';
+        // For multi-line commands, show only first line or a summary
+        let cmdForDisplay = item.command;
+        const newlineIndex = cmdForDisplay.indexOf('\n');
+        if (newlineIndex !== -1) {
+            // Multi-line command - show first line with indicator
+            const firstLine = cmdForDisplay.slice(0, newlineIndex).trim();
+            const lineCount = cmdForDisplay.split('\n').length;
+            cmdForDisplay = firstLine.length > 0
+                ? `${firstLine}… (${String(lineCount)} lines)`
+                : `(${String(lineCount)} line script)`;
+        }
+        const cmdDisplay = cmdForDisplay.length > maxCmdLen
+            ? cmdForDisplay.slice(0, maxCmdLen) + '…'
+            : cmdForDisplay;
+        lines.push(`${s.info('●')} ${s.primary('Bash')}(${cmdDisplay})${statusIcon}`);
+        // Output lines - show first N lines (more useful than last N for live streaming)
+        const displayLines = this.expanded
+            ? item.output
+            : item.output.slice(0, this.maxOutputLines);
+        if (displayLines.length > 0) {
+            for (const line of displayLines) {
+                const truncated = this.truncateLine(line, options.width - 5);
+                lines.push(`  ${RESULT_MARKER}  ${s.muted(truncated)}`);
+            }
+            // Show collapsed indicator if there are hidden lines
+            if (!this.expanded && item.output.length > this.maxOutputLines) {
+                const hidden = item.output.length - this.maxOutputLines;
+                lines.push(`     ${s.muted(`… +${String(hidden)} lines`)} ${s.muted('(ctrl+o to expand)')}`);
+            }
+        }
+        // Hint for running bash
+        if (item.status === 'running') {
+            lines.push(`     ${s.muted('ctrl+b to run in background')}`);
+        }
+        return lines;
+    }
+    // =========================================================================
+    // Tool Item Rendering
+    // =========================================================================
+    renderToolItem(item, _options) {
+        const s = getStyles();
+        const lines = [];
+        // Header: ● ToolName(params)
+        const statusIcon = item.status === 'done' ? ' ✓' : '';
+        lines.push(`${s.info('●')} ${s.primary(item.name)}(${item.params})${statusIcon}`);
+        // Progress or status
+        if (item.progress) {
+            lines.push(`  ${RESULT_MARKER}  ${s.muted(item.progress)}`);
+        }
+        return lines;
+    }
+    // =========================================================================
+    // Ephemeral Notification Rendering
+    // =========================================================================
+    renderEphemeralNotification(message) {
+        const s = getStyles();
+        return `${s.info('●')} ${message}`;
+    }
+    // =========================================================================
+    // Helpers
+    // =========================================================================
+    /**
+     * Format token count for display (e.g., 18.1k)
+     */
+    formatTokens(tokens) {
+        if (tokens >= 1000) {
+            return `${(tokens / 1000).toFixed(1)}k`;
+        }
+        return String(tokens);
+    }
+    /**
+     * Truncate a line to fit within width.
+     */
+    truncateLine(line, maxWidth) {
+        const visibleLen = getVisibleLength(line);
+        if (visibleLen <= maxWidth) {
+            return line;
+        }
+        // Simple truncation (doesn't handle ANSI codes perfectly)
+        return line.slice(0, maxWidth - 1) + '…';
+    }
+    /**
+     * Format duration for display.
+     */
+    formatDuration(ms) {
+        const seconds = Math.floor(ms / 1000);
+        if (seconds < 60) {
+            return `${String(seconds)}s`;
+        }
+        const minutes = Math.floor(seconds / 60);
+        const remainingSeconds = seconds % 60;
+        return `${String(minutes)}m ${String(remainingSeconds)}s`;
+    }
+}

package/dist/ui/mascot/expressions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mascot Expression Library
+ *
+ * ASCII art expressions for the compilr mascot - a retro CRT monitor
+ * with rabbit-ear antennas and a 3D keyboard.
+ *
+ * Each expression is 6 lines tall and designed to sit alongside the logo.
+ */
+export type ExpressionCode = 'neutral' | 'thinking' | 'looking_left' | 'looking_right' | 'sleeping' | 'alert' | 'error' | 'success' | 'success_minimal' | 'searching' | 'skeptical';
+export type MascotSetting = 'none' | 'random' | ExpressionCode;
+export declare const EXPRESSIONS: Record<ExpressionCode, string[]>;
+export declare const EXPRESSIONS_INLINE: Record<ExpressionCode, string>;
+export declare const EXPRESSION_CODES: ExpressionCode[];
+export declare const MASCOT_OPTIONS: MascotSetting[];
+export declare const MASCOT_LABELS: Record<MascotSetting, string>;
+/**
+ * Get a random expression code
+ */
+export declare function getRandomExpression(): ExpressionCode;
+/**
+ * Reset the session expression (for next startup or when settings change)
+ */
+export declare function resetSessionExpression(): void;
+/**
+ * Get expression lines for a mascot setting
+ * Returns null for 'none', picks random for 'random', otherwise returns the expression
+ */
+export declare function getExpressionForSetting(setting: MascotSetting): string[] | null;
+/**
+ * Get the width of the mascot (for layout calculations)
+ */
+export declare function getMascotWidth(): number;