@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/providers/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Content Provider Interfaces
+ *
+ * Components implement these interfaces to provide content for rendering.
+ * The TerminalRenderer collects lines from providers and writes to terminal.
+ *
+ * Key principle: Providers return string[], never write to terminal directly.
+ */
+/**
+ * Base interface for all content providers.
+ * Returns lines to render. Empty array = nothing to show.
+ */
+export interface ContentProvider {
+    /** Returns lines to render. Empty array = nothing to show */
+    getLines(): string[];
+    /** Optional: get cursor position within this component's content */
+    getCursorPosition?(): CursorPosition | null;
+    /** Optional: does this provider need keyboard input? */
+    hasKeyboardFocus?(): boolean;
+}
+/**
+ * Cursor position within rendered content
+ */
+export interface CursorPosition {
+    /** Row within the provider's content (0-indexed) */
+    row: number;
+    /** Column within the row (0-indexed) */
+    col: number;
+}
+/**
+ * Menu options available in startup menu
+ */
+export type MenuOption = 'init' | 'projects' | 'continue' | 'chat' | 'config' | 'help' | 'exit';
+/**
+ * Actions from menu keyboard handling
+ */
+export type MenuAction = 'up' | 'down' | 'select' | 'exit' | null;
+/**
+ * Provider for the startup menu (MENU mode)
+ */
+export interface MenuProvider extends ContentProvider {
+    /** Returns full menu screen content */
+    getLines(): string[];
+    /** Handle keyboard input, return action taken */
+    handleKey(key: Buffer): MenuAction;
+    /** Get currently selected menu option */
+    getSelectedOption(): MenuOption;
+    /** Get highlighted index (for rendering) */
+    getHighlightedIndex(): number;
+}
+/**
+ * Provider for subagent status display
+ */
+export interface SubagentProvider extends ContentProvider {
+    /** Returns subagent status lines (empty if no active subagents) */
+    getLines(): string[];
+    /** Check if any subagent is currently active */
+    hasActiveSubagent(): boolean;
+}
+/**
+ * Provider for spinner/progress display
+ */
+export interface SpinnerProvider extends ContentProvider {
+    /** Returns spinner line when agent is running (empty when idle) */
+    getLines(): string[];
+    /** Check if agent is currently running */
+    isAgentRunning(): boolean;
+}
+/**
+ * Provider for todo list display
+ */
+export interface TodoProvider extends ContentProvider {
+    /** Returns todo list (empty when agent running or no todos) */
+    getLines(): string[];
+    /** Get count of todos */
+    getTodoCount(): number;
+}
+/**
+ * Provider for queued messages display
+ */
+export interface QueueProvider extends ContentProvider {
+    /** Returns queued messages (empty if none) */
+    getLines(): string[];
+    /** Get count of queued messages */
+    getQueueCount(): number;
+}
+/**
+ * Actions from input keyboard handling
+ */
+export type InputAction = {
+    type: 'submit';
+    value: string;
+} | {
+    type: 'command';
+    value: string;
+} | {
+    type: 'cancel';
+} | {
+    type: 'change';
+} | {
+    type: 'escape';
+} | null;
+/**
+ * Provider for input prompt
+ */
+export interface InputProvider extends ContentProvider {
+    /** Returns separator + input prompt lines (may be multi-line) */
+    getLines(): string[];
+    /** Get cursor position within input content */
+    getCursorPosition(): CursorPosition;
+    /** Handle keyboard input, return action taken */
+    handleKey(key: Buffer): InputAction;
+    /** Get current input value */
+    getValue(): string;
+    /** Set input value programmatically */
+    setValue(value: string): void;
+    /** Clear input */
+    clear(): void;
+    /** Is input in queue mode (typing queued while agent runs) */
+    isQueueMode(): boolean;
+}
+/**
+ * Provider for mode indicator line
+ */
+export interface ModeProvider extends ContentProvider {
+    /** Returns mode indicator line */
+    getLines(): string[];
+    /** Get current mode name */
+    getModeName(): string;
+}
+/**
+ * Actions from overlay keyboard handling
+ */
+export type OverlayAction = {
+    type: 'close';
+} | {
+    type: 'close';
+    result: unknown;
+} | {
+    type: 'navigate';
+    direction: 'up' | 'down' | 'left' | 'right';
+} | {
+    type: 'select';
+} | {
+    type: 'scroll';
+    direction: 'up' | 'down';
+} | {
+    type: 'tab';
+    direction: 'next' | 'prev';
+} | null;
+/**
+ * Provider for full-screen overlays
+ */
+export interface OverlayProvider extends ContentProvider {
+    /** Returns full overlay content */
+    getLines(): string[];
+    /** Check if overlay is active */
+    isActive(): boolean;
+    /** Handle keyboard input, return action taken */
+    handleKey(key: Buffer): OverlayAction;
+    /** Get cursor position if overlay needs visible cursor */
+    getCursorPosition(): CursorPosition | null;
+    /** Get overlay title (for header) */
+    getTitle(): string;
+}
+/**
+ * All providers needed by TerminalRenderer
+ */
+export interface ProviderRegistry {
+    menu?: MenuProvider;
+    subagent?: SubagentProvider;
+    spinner?: SpinnerProvider;
+    todo?: TodoProvider;
+    queue?: QueueProvider;
+    input?: InputProvider;
+    mode?: ModeProvider;
+    overlay?: OverlayProvider;
+}

package/dist/ui/providers/types.js

@@ -0,0 +1,9 @@
+/**
+ * Content Provider Interfaces
+ *
+ * Components implement these interfaces to provide content for rendering.
+ * The TerminalRenderer collects lines from providers and writes to terminal.
+ *
+ * Key principle: Providers return string[], never write to terminal directly.
+ */
+export {};

package/dist/ui/render-modes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Render Modes
+ *
+ * The terminal operates in one of three mutually exclusive modes.
+ * Each mode has different rendering behavior and keyboard handling.
+ */
+/**
+ * Terminal render modes
+ *
+ * MENU:    Full-screen startup menu (no scroll regions)
+ * REPL:    Scroll zone + footer (normal chat mode)
+ * OVERLAY: Full-screen overlay (config, backlog, permissions)
+ */
+export declare enum RenderMode {
+    MENU = "MENU",
+    REPL = "REPL",
+    OVERLAY = "OVERLAY"
+}
+/**
+ * Mode transition events for debugging/logging
+ */
+export interface ModeTransition {
+    from: RenderMode;
+    to: RenderMode;
+    reason: string;
+    timestamp: number;
+}
+/**
+ * Valid mode transitions
+ *
+ * MENU -> REPL:      User selects option (init, chat, continue, etc.)
+ * REPL -> OVERLAY:   User triggers overlay (/config, /backlog, permission)
+ * OVERLAY -> REPL:   User closes overlay (Esc, Enter, etc.)
+ * REPL -> MENU:      User runs /menu command
+ */
+export declare function isValidTransition(from: RenderMode, to: RenderMode): boolean;

package/dist/ui/render-modes.js

@@ -0,0 +1,44 @@
+/**
+ * Render Modes
+ *
+ * The terminal operates in one of three mutually exclusive modes.
+ * Each mode has different rendering behavior and keyboard handling.
+ */
+/**
+ * Terminal render modes
+ *
+ * MENU:    Full-screen startup menu (no scroll regions)
+ * REPL:    Scroll zone + footer (normal chat mode)
+ * OVERLAY: Full-screen overlay (config, backlog, permissions)
+ */
+export var RenderMode;
+(function (RenderMode) {
+    RenderMode["MENU"] = "MENU";
+    RenderMode["REPL"] = "REPL";
+    RenderMode["OVERLAY"] = "OVERLAY";
+})(RenderMode || (RenderMode = {}));
+/**
+ * Valid mode transitions
+ *
+ * MENU -> REPL:      User selects option (init, chat, continue, etc.)
+ * REPL -> OVERLAY:   User triggers overlay (/config, /backlog, permission)
+ * OVERLAY -> REPL:   User closes overlay (Esc, Enter, etc.)
+ * REPL -> MENU:      User runs /menu command
+ */
+export function isValidTransition(from, to) {
+    if (from === to)
+        return false;
+    switch (from) {
+        case RenderMode.MENU:
+            // Menu can go to REPL (user selects option) or OVERLAY (e.g., config from menu)
+            return to === RenderMode.REPL || to === RenderMode.OVERLAY;
+        case RenderMode.REPL:
+            // REPL can go to OVERLAY (modal opened) or MENU (/menu command)
+            return to === RenderMode.OVERLAY || to === RenderMode.MENU;
+        case RenderMode.OVERLAY:
+            // Overlay can go back to REPL (closed) or MENU (rare, but valid)
+            return to === RenderMode.REPL || to === RenderMode.MENU;
+        default:
+            return false;
+    }
+}

package/dist/ui/startup-menu.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Startup Menu Overlay
+ *
+ * Provides a guided entry point for users with options to:
+ * - Start a new project (/new)
+ * - View & manage projects (/projects)
+ * - Continue last project
+ * - Free-form chat
+ * - Configure settings
+ * - Show help
+ * - Exit
+ *
+ * Inspired by ATLAS CLI interactiveMenu()
+ */
+export type MenuOption = 'init' | 'projects' | 'continue' | 'chat' | 'config' | 'help' | 'exit';
+export interface StartupMenuResult {
+    action: MenuOption;
+    project?: {
+        id: number;
+        name: string;
+        displayName: string;
+        path: string;
+    };
+}
+/**
+ * Show the startup menu and return the user's choice
+ */
+export declare function showStartupMenu(version: string): Promise<StartupMenuResult>;
+/**
+ * Find the last active project for the "continue" option
+ */
+export declare function findLastActiveProject(): {
+    id: number;
+    name: string;
+    path: string;
+} | null;

package/dist/ui/startup-menu.js

@@ -0,0 +1,236 @@
+/**
+ * Startup Menu Overlay
+ *
+ * Provides a guided entry point for users with options to:
+ * - Start a new project (/new)
+ * - View & manage projects (/projects)
+ * - Continue last project
+ * - Free-form chat
+ * - Configure settings
+ * - Show help
+ * - Exit
+ *
+ * Inspired by ATLAS CLI interactiveMenu()
+ */
+import { getStyles } from '../themes/index.js';
+import * as terminal from './terminal.js';
+import { projectRepository } from '../db/repositories/index.js';
+import { setActiveProject } from '../tools/project-db.js';
+import { printLogo } from './conversation.js';
+// =============================================================================
+// Menu Options
+// =============================================================================
+function getMenuOptions(hasLastProject, lastProjectName) {
+    return [
+        {
+            key: 'init',
+            label: 'init',
+            description: 'Start a new project',
+        },
+        {
+            key: 'projects',
+            label: 'projects',
+            description: 'View & manage projects',
+        },
+        {
+            key: 'continue',
+            label: 'continue',
+            description: hasLastProject
+                ? `Resume: ${lastProjectName ?? 'project'}`
+                : 'No recent project',
+            disabled: !hasLastProject,
+        },
+        {
+            key: 'chat',
+            label: 'chat',
+            description: 'Free-form AI chat',
+        },
+        {
+            key: 'config',
+            label: 'config',
+            description: 'Configure settings',
+        },
+        {
+            key: 'help',
+            label: 'help',
+            description: 'Show help and shortcuts',
+        },
+        {
+            key: 'exit',
+            label: 'exit',
+            description: 'Exit CLI',
+        },
+    ];
+}
+// =============================================================================
+// Rendering
+// =============================================================================
+function renderMenu(state) {
+    const s = getStyles();
+    const lines = [];
+    lines.push('');
+    lines.push(' What would you like to do?');
+    lines.push('');
+    // Menu options - left-aligned like /config overlay
+    const labelWidth = 14;
+    for (let i = 0; i < state.options.length; i++) {
+        const opt = state.options[i];
+        const isSelected = i === state.selectedIndex;
+        const prefix = isSelected ? s.primary(' ❯ ') : '   ';
+        const rawLabel = opt.label.padEnd(labelWidth);
+        const rawDesc = opt.description;
+        let label;
+        let description;
+        if (opt.disabled) {
+            label = s.muted(rawLabel);
+            description = s.muted(rawDesc);
+        }
+        else if (isSelected) {
+            label = s.primary(rawLabel);
+            description = s.foreground(rawDesc);
+        }
+        else {
+            label = s.foreground(rawLabel);
+            description = s.muted(rawDesc);
+        }
+        lines.push(prefix + label + description);
+    }
+    lines.push('');
+    lines.push(s.muted(' ↑/↓: navigate  Enter: select'));
+    return lines;
+}
+// =============================================================================
+// Main Function
+// =============================================================================
+/**
+ * Show the startup menu and return the user's choice
+ */
+export async function showStartupMenu(version) {
+    return new Promise((resolve) => {
+        // Check for last active project
+        let lastProject = null;
+        try {
+            const result = projectRepository.list({ status: 'active', limit: 1 });
+            if (result.projects.length > 0) {
+                const p = result.projects[0];
+                lastProject = { id: p.id, name: p.name, displayName: p.displayName, path: p.path };
+            }
+        }
+        catch {
+            // DB might not exist yet
+        }
+        const hasLastProject = lastProject !== null;
+        const lastProjectName = lastProject?.displayName;
+        const state = {
+            selectedIndex: 0,
+            options: getMenuOptions(hasLastProject, lastProjectName),
+            hasLastProject,
+            lastProjectName,
+        };
+        // Enable raw mode for key detection (no readline - it causes echo)
+        const wasRawMode = process.stdin.isRaw;
+        terminal.enableRawMode();
+        terminal.hideCursor();
+        let prevLineCount = 0;
+        const render = (isInitial = false) => {
+            if (isInitial) {
+                // First render: print logo and save cursor position
+                printLogo(version, lastProject?.displayName ?? null);
+                terminal.saveCursor();
+            }
+            else {
+                // Subsequent renders: restore cursor and clear to end of screen
+                terminal.restoreCursor();
+                terminal.clearToEndOfScreen();
+            }
+            // Render the menu
+            const lines = renderMenu(state);
+            const termWidth = terminal.getTerminalWidth();
+            const physicalLines = terminal.totalPhysicalLines(lines, termWidth);
+            // Pad to previous height to prevent shrinking
+            for (let i = physicalLines; i < prevLineCount; i++) {
+                lines.push('');
+            }
+            process.stdout.write(lines.join('\n') + '\n');
+            prevLineCount = Math.max(prevLineCount, physicalLines);
+        };
+        // Define handleKey first, then cleanup references it
+        const handleKey = (key) => {
+            const keyStr = key.toString();
+            // Arrow keys
+            if (keyStr === '\x1b[A' || keyStr === 'k') {
+                // Up
+                do {
+                    state.selectedIndex = (state.selectedIndex - 1 + state.options.length) % state.options.length;
+                } while (state.options[state.selectedIndex].disabled);
+                render(false);
+            }
+            else if (keyStr === '\x1b[B' || keyStr === 'j') {
+                // Down
+                do {
+                    state.selectedIndex = (state.selectedIndex + 1) % state.options.length;
+                } while (state.options[state.selectedIndex].disabled);
+                render(false);
+            }
+            else if (keyStr === '\r' || keyStr === '\n') {
+                // Enter
+                const selected = state.options[state.selectedIndex];
+                if (!selected.disabled) {
+                    // Cleanup: Remove listener BEFORE changing raw mode to prevent issues
+                    process.stdin.removeListener('data', handleKey);
+                    if (!wasRawMode) {
+                        terminal.disableRawMode();
+                    }
+                    terminal.showCursor();
+                    // Handle continue option - set active project
+                    if (selected.key === 'continue' && lastProject) {
+                        setActiveProject({
+                            id: lastProject.id,
+                            name: lastProject.name,
+                            displayName: lastProject.displayName,
+                            path: lastProject.path,
+                        });
+                        resolve({
+                            action: 'continue',
+                            project: {
+                                id: lastProject.id,
+                                name: lastProject.name,
+                                displayName: lastProject.displayName,
+                                path: lastProject.path,
+                            },
+                        });
+                    }
+                    else {
+                        resolve({ action: selected.key });
+                    }
+                }
+            }
+            else if (keyStr === '\x03') {
+                // Ctrl+C - cleanup and exit
+                process.stdin.removeListener('data', handleKey);
+                terminal.disableRawMode();
+                terminal.showCursor();
+                process.exit(0);
+            }
+        };
+        process.stdin.on('data', handleKey);
+        // Initial render
+        render(true);
+    });
+}
+/**
+ * Find the last active project for the "continue" option
+ */
+export function findLastActiveProject() {
+    try {
+        const result = projectRepository.list({ status: 'active', limit: 1 });
+        if (result.projects.length > 0) {
+            const p = result.projects[0];
+            return { id: p.id, name: p.name, path: p.path };
+        }
+    }
+    catch {
+        // DB might not exist
+    }
+    return null;
+}

package/dist/ui/status-bar-controller.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Status bar navigation controller.
+ *
+ * Extracted from TerminalUI — manages the navigable status bar indicators
+ * (pending requests, background agents, terminals, notifications).
+ */
+import type { KeypressKey } from './terminal-types.js';
+export interface StatusBarItem {
+    id: 'pending' | 'bg-agents' | 'terminals' | 'notifications' | 'mcp';
+    action: string;
+}
+export interface StatusBarHost {
+    requestRender(): void;
+    emit(event: string, ...args: unknown[]): void;
+}
+export declare class StatusBarController {
+    navActive: boolean;
+    selectedIndex: number;
+    backgroundAgentCount: number;
+    mcpLoading: boolean;
+    mcpToolCount: number;
+    private readonly host;
+    constructor(host: StatusBarHost);
+    /** Set background agent count (called by REPL to keep UI in sync). */
+    setBackgroundAgentCount(count: number): void;
+    /** Set MCP loading state (shown while MCP servers connect in background). */
+    setMCPLoading(loading: boolean, toolCount?: number): void;
+    /** Returns navigable status bar indicators based on current state. */
+    getItems(): StatusBarItem[];
+    /** Handle keys while in status bar navigation mode. */
+    handleKey(_str: string, key: KeypressKey): void;
+    exitNav(): void;
+}

package/dist/ui/status-bar-controller.js

@@ -0,0 +1,99 @@
+/**
+ * Status bar navigation controller.
+ *
+ * Extracted from TerminalUI — manages the navigable status bar indicators
+ * (pending requests, background agents, terminals, notifications).
+ */
+import { getPendingRequestsManager } from '../multi-agent/index.js';
+import { getSessionRegistry } from '../multi-agent/session-registry.js';
+import { getNotificationManager } from '../multi-agent/notification-manager.js';
+export class StatusBarController {
+    navActive = false;
+    selectedIndex = 0;
+    backgroundAgentCount = 0;
+    mcpLoading = false;
+    mcpToolCount = 0;
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    /** Set background agent count (called by REPL to keep UI in sync). */
+    setBackgroundAgentCount(count) {
+        this.backgroundAgentCount = count;
+        this.host.requestRender();
+    }
+    /** Set MCP loading state (shown while MCP servers connect in background). */
+    setMCPLoading(loading, toolCount) {
+        this.mcpLoading = loading;
+        if (toolCount !== undefined)
+            this.mcpToolCount = toolCount;
+        this.host.requestRender();
+    }
+    /** Returns navigable status bar indicators based on current state. */
+    getItems() {
+        const items = [];
+        const notifManager = getNotificationManager();
+        if (notifManager && notifManager.getUnreadCount() > 0) {
+            items.push({ id: 'notifications', action: 'notifications' });
+        }
+        if (getPendingRequestsManager().getCount() > 0) {
+            items.push({ id: 'pending', action: 'pending' });
+        }
+        if (this.backgroundAgentCount > 0) {
+            items.push({ id: 'bg-agents', action: 'bg' });
+        }
+        const registry = getSessionRegistry();
+        if (registry && registry.getProjectScopedSessionCount() > 1) {
+            items.push({ id: 'terminals', action: 'terminals' });
+        }
+        if (this.mcpLoading) {
+            items.push({ id: 'mcp', action: 'mcp' });
+        }
+        return items;
+    }
+    /** Handle keys while in status bar navigation mode. */
+    handleKey(_str, key) {
+        const items = this.getItems();
+        if (items.length === 0) {
+            this.exitNav();
+            return;
+        }
+        if (key.name === 'right' || key.name === 'down') {
+            if (this.selectedIndex < items.length - 1) {
+                this.selectedIndex++;
+                this.host.requestRender();
+            }
+        }
+        else if (key.name === 'left') {
+            if (this.selectedIndex > 0) {
+                this.selectedIndex--;
+                this.host.requestRender();
+            }
+        }
+        else if (key.name === 'up') {
+            if (this.selectedIndex > 0) {
+                this.selectedIndex--;
+                this.host.requestRender();
+            }
+            else {
+                this.exitNav();
+            }
+        }
+        else if (key.name === 'return') {
+            const item = items[this.selectedIndex];
+            this.exitNav();
+            this.host.emit('command', item.action, '');
+        }
+        else if (key.name === 'escape') {
+            this.exitNav();
+        }
+        else {
+            this.exitNav();
+        }
+    }
+    exitNav() {
+        this.navActive = false;
+        this.selectedIndex = 0;
+        this.host.requestRender();
+    }
+}