@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/ui/overlay/index.js

@@ -0,0 +1,35 @@
+/**
+ * Overlay System
+ *
+ * Exports all overlay-related types, utilities, and V2 implementations.
+ */
+export { isCloseWithResult, isCloseCancelled } from './types.js';
+export { parseKeyEvent, matchesKey } from './key-utils.js';
+// =============================================================================
+// V2 Overlay Implementations
+// =============================================================================
+export { HelpOverlayV2 } from './impl/help-overlay-v2.js';
+export { ThemeOverlayV2 } from './impl/theme-overlay-v2.js';
+export { ModelOverlayV2 } from './impl/model-overlay-v2.js';
+export { ToolsOverlayV2 } from './impl/tools-overlay-v2.js';
+export { KeysOverlayV2 } from './impl/keys-overlay-v2.js';
+export { MascotOverlayV2 } from './impl/mascot-overlay-v2.js';
+export { TutorialOverlayV2 } from './impl/tutorial-overlay-v2.js';
+export { CommandsOverlayV2 } from './impl/commands-overlay-v2.js';
+export { AgentsOverlayV2 } from './impl/agents-overlay-v2.js';
+export { BacklogOverlayV2 } from './impl/backlog-overlay-v2.js';
+export { WorkflowOverlayV2 } from './impl/workflow-overlay-v2.js';
+export { DocsOverlayV2 } from './impl/docs-overlay-v2.js';
+export { DocumentDetailOverlayV2 } from './impl/document-detail-overlay-v2.js';
+export { AnchorsOverlayV2 } from './impl/anchors-overlay-v2.js';
+export { ProjectsOverlayV2 } from './impl/projects-overlay-v2.js';
+export { ConfigOverlayV2 } from './impl/config-overlay-v2.js';
+export { AskUserSimpleOverlayV2 } from './impl/ask-user-simple-overlay-v2.js';
+export { GuardrailOverlayV2 } from './impl/guardrail-overlay-v2.js';
+export { AskUserOverlayV2 } from './impl/ask-user-overlay-v2.js';
+export { IterationLimitOverlayV2 } from './impl/iteration-limit-overlay-v2.js';
+export { ModelWarningOverlayV2 } from './impl/model-warning-overlay-v2.js';
+export { NewProjectOverlayV2 } from './impl/new-overlay-v2.js';
+export { InitSetupOverlayV2 } from './impl/init-setup-overlay-v2.js';
+export { ArchTypeOverlayV2 } from './impl/arch-type-overlay-v2.js';
+export { DashboardOverlayV2 } from './impl/dashboard-overlay-v2.js';

package/dist/ui/overlay/key-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Key Utilities
+ *
+ * Re-exported from @compilr-dev/ui-core for consistency.
+ */
+export { parseKeyEvent, matchesKey } from '@compilr-dev/ui-core/utils';

package/dist/ui/overlay/key-utils.js

@@ -0,0 +1,6 @@
+/**
+ * Key Utilities
+ *
+ * Re-exported from @compilr-dev/ui-core for consistency.
+ */
+export { parseKeyEvent, matchesKey } from '@compilr-dev/ui-core/utils';

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

@@ -0,0 +1,128 @@
+/**
+ * Overlay System Types
+ *
+ * Defines the interface for overlays that can be shown by TerminalUI.
+ * Overlays define WHAT to show and WHAT to do.
+ * TerminalUI handles HOW to render.
+ */
+import type { ThemeStyleFunctions } from '../../themes/index.js';
+/**
+ * Base interface for all overlays.
+ * Overlays define WHAT to show and WHAT to do.
+ * TerminalUI handles HOW to render.
+ */
+export interface Overlay<TState = unknown, TResult = unknown> {
+    /** Overlay type determines rendering mode */
+    readonly type: 'fullscreen' | 'inline';
+    /** Unique identifier for the overlay */
+    readonly id: string;
+    /** Called when overlay is mounted. Setup state, fetch data. */
+    onMount?(): void | Promise<void>;
+    /** Called when overlay is unmounted. Cleanup. */
+    onUnmount?(): void;
+    /** Get current state (for TerminalUI to access if needed) */
+    getState(): TState;
+    /**
+     * Render overlay content.
+     * Returns logical lines - TerminalUI handles physical line calculation.
+     */
+    render(context: RenderContext): OverlayContent;
+    /**
+     * Optional: Summary to show after overlay closes.
+     * Rendered by TerminalUI in conversation zone.
+     */
+    getCloseSummary?(result: TResult): string | null;
+    /**
+     * Handle keypress. Return action for TerminalUI.
+     * TerminalUI routes all input here when overlay is active.
+     */
+    handleKey(key: KeyEvent): OverlayAction<TResult>;
+}
+/**
+ * Context provided to render().
+ */
+export interface RenderContext {
+    /** Terminal width in columns */
+    width: number;
+    /** Terminal height in rows (for fullscreen) */
+    height: number;
+    /** Current theme styles */
+    styles: ThemeStyleFunctions;
+}
+/**
+ * Content returned by render().
+ */
+export interface OverlayContent {
+    /** Lines to render (logical lines, TerminalUI handles wrapping) */
+    lines: string[];
+    /** Cursor position hint (for text input overlays) */
+    cursorPosition?: {
+        line: number;
+        column: number;
+    };
+    /** Minimum height (for stable rendering) */
+    minHeight?: number;
+}
+/**
+ * Action returned by handleKey().
+ */
+export type OverlayAction<TResult> = {
+    type: 'none';
+} | {
+    type: 'render';
+} | {
+    type: 'close';
+    result: TResult;
+} | {
+    type: 'close';
+    cancelled: true;
+} | {
+    type: 'push';
+    overlay: Overlay;
+} | {
+    type: 'pop';
+};
+/**
+ * Normalized key event (parsed from raw Buffer).
+ */
+export interface KeyEvent {
+    /** Raw buffer data */
+    raw: Buffer;
+    /** Key name: 'enter', 'escape', 'up', 'down', 'tab', 'a', 'b', etc. */
+    name: string;
+    /** Printable character if applicable */
+    char?: string;
+    /** Modifier keys */
+    ctrl: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+/**
+ * Type guard to check if an action is a close action with a result.
+ */
+export declare function isCloseWithResult<TResult = unknown>(action: OverlayAction<TResult>): action is {
+    type: 'close';
+    result: TResult;
+};
+/**
+ * Type guard to check if an action is a cancelled close action.
+ */
+export declare function isCloseCancelled<TResult = unknown>(action: OverlayAction<TResult>): action is {
+    type: 'close';
+    cancelled: true;
+};
+/**
+ * Resolver function for overlay promises.
+ * Called when overlay closes with result or cancellation.
+ */
+export type OverlayResolver<TResult> = (result: TResult | null) => void;
+/**
+ * State for tracking rendered lines to prevent visual artifacts.
+ */
+export interface OverlayRenderState {
+    /** Physical lines rendered in the last render */
+    lineCount: number;
+    /** Maximum physical lines ever rendered during this overlay session.
+     * Used for clearing to prevent ghost lines when content shrinks between renders. */
+    maxLineCount: number;
+}

package/dist/ui/overlay/overlay-types.js

@@ -0,0 +1,22 @@
+/**
+ * Overlay System Types
+ *
+ * Defines the interface for overlays that can be shown by TerminalUI.
+ * Overlays define WHAT to show and WHAT to do.
+ * TerminalUI handles HOW to render.
+ */
+// =============================================================================
+// Helper Types
+// =============================================================================
+/**
+ * Type guard to check if an action is a close action with a result.
+ */
+export function isCloseWithResult(action) {
+    return action.type === 'close' && 'result' in action;
+}
+/**
+ * Type guard to check if an action is a cancelled close action.
+ */
+export function isCloseCancelled(action) {
+    return action.type === 'close' && 'cancelled' in action;
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Overlay System Types
+ *
+ * Defines the interface for overlays that can be shown by TerminalUI.
+ * Overlays define WHAT to show and WHAT to do.
+ * TerminalUI handles HOW to render.
+ */
+import type { ThemeStyleFunctions } from '../../themes/index.js';
+/**
+ * Base interface for all overlays.
+ * Overlays define WHAT to show and WHAT to do.
+ * TerminalUI handles HOW to render.
+ */
+export interface Overlay<TState = unknown, TResult = unknown> {
+    /** Overlay type determines rendering mode */
+    readonly type: 'fullscreen' | 'inline';
+    /** Unique identifier for the overlay */
+    readonly id: string;
+    /**
+     * Whether this overlay uses alternate screen buffer.
+     * When true, TerminalUI skips screen clearing on close since
+     * exiting alternate screen automatically restores the main screen.
+     */
+    readonly usesAlternateScreen?: boolean;
+    /** Called when overlay is mounted. Setup state, fetch data. */
+    onMount?(): void | Promise<void>;
+    /** Called when overlay is unmounted. Cleanup. */
+    onUnmount?(): void;
+    /** Get current state (for TerminalUI to access if needed) */
+    getState(): TState;
+    /**
+     * Render overlay content.
+     * Returns logical lines - TerminalUI handles physical line calculation.
+     */
+    render(context: RenderContext): OverlayContent;
+    /**
+     * Optional: Summary to show after overlay closes.
+     * Rendered by TerminalUI in conversation zone.
+     */
+    getCloseSummary?(result: TResult): string | null;
+    /**
+     * Handle keypress. Return action for TerminalUI.
+     * TerminalUI routes all input here when overlay is active.
+     * Can be sync or async (for overlays that need to do async work like file I/O).
+     */
+    handleKey(key: KeyEvent): OverlayAction<TResult> | Promise<OverlayAction<TResult>>;
+}
+/**
+ * Context provided to render().
+ */
+export interface RenderContext {
+    /** Terminal width in columns */
+    width: number;
+    /** Terminal height in rows (for fullscreen) */
+    height: number;
+    /** Current theme styles */
+    styles: ThemeStyleFunctions;
+}
+/**
+ * Content returned by render().
+ */
+export interface OverlayContent {
+    /** Lines to render (logical lines, TerminalUI handles wrapping) */
+    lines: string[];
+    /** Cursor position hint (for text input overlays) */
+    cursorPosition?: {
+        line: number;
+        column: number;
+    };
+    /** Minimum height (for stable rendering) */
+    minHeight?: number;
+}
+/**
+ * Action returned by handleKey().
+ */
+export type OverlayAction<TResult> = {
+    type: 'none';
+} | {
+    type: 'render';
+} | {
+    type: 'close';
+    result: TResult;
+} | {
+    type: 'close';
+    cancelled: true;
+} | {
+    type: 'push';
+    overlay: Overlay;
+} | {
+    type: 'pop';
+};
+/**
+ * Normalized key event (parsed from raw Buffer).
+ */
+export interface KeyEvent {
+    /** Raw buffer data */
+    raw: Buffer;
+    /** Key name: 'enter', 'escape', 'up', 'down', 'tab', 'a', 'b', etc. */
+    name: string;
+    /** Printable character if applicable */
+    char?: string;
+    /** Modifier keys */
+    ctrl: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+/**
+ * Type guard to check if an action is a close action with a result.
+ */
+export declare function isCloseWithResult<TResult = unknown>(action: OverlayAction<TResult>): action is {
+    type: 'close';
+    result: TResult;
+};
+/**
+ * Type guard to check if an action is a cancelled close action.
+ */
+export declare function isCloseCancelled<TResult = unknown>(action: OverlayAction<TResult>): action is {
+    type: 'close';
+    cancelled: true;
+};
+/**
+ * Resolver function for overlay promises.
+ * Called when overlay closes with result or cancellation.
+ */
+export type OverlayResolver<TResult> = (result: TResult | null) => void;
+/**
+ * State for tracking rendered lines to prevent visual artifacts.
+ */
+export interface OverlayRenderState {
+    /** Physical lines rendered in the last render */
+    lineCount: number;
+    /** Maximum physical lines ever rendered during this overlay session.
+     * Used for clearing to prevent ghost lines when content shrinks between renders. */
+    maxLineCount: number;
+}

package/dist/ui/overlay/types.js

@@ -0,0 +1,22 @@
+/**
+ * Overlay System Types
+ *
+ * Defines the interface for overlays that can be shown by TerminalUI.
+ * Overlays define WHAT to show and WHAT to do.
+ * TerminalUI handles HOW to render.
+ */
+// =============================================================================
+// Helper Types
+// =============================================================================
+/**
+ * Type guard to check if an action is a close action with a result.
+ */
+export function isCloseWithResult(action) {
+    return action.type === 'close' && 'result' in action;
+}
+/**
+ * Type guard to check if an action is a cancelled close action.
+ */
+export function isCloseCancelled(action) {
+    return action.type === 'close' && 'cancelled' in action;
+}

package/dist/ui/overlays/help-overlay-v2.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Help Overlay V2
+ *
+ * A simple help overlay using the new Overlay interface.
+ * Displays available commands with navigation and detail view.
+ */
+import type { Overlay, RenderContext, OverlayContent, OverlayAction, KeyEvent } from '../overlay/index.js';
+interface HelpCommand {
+    name: string;
+    description: string;
+    details?: string;
+}
+interface HelpOverlayState {
+    selectedIndex: number;
+    scrollOffset: number;
+    pageSize: number;
+}
+export declare class HelpOverlayV2 implements Overlay<HelpOverlayState, void> {
+    readonly type: "inline";
+    readonly id = "help-overlay-v2";
+    private readonly state;
+    private readonly commands;
+    constructor(commands?: HelpCommand[]);
+    getState(): HelpOverlayState;
+    render(context: RenderContext): OverlayContent;
+    handleKey(key: KeyEvent): OverlayAction<void>;
+}
+export {};

package/dist/ui/overlays/help-overlay-v2.js

@@ -0,0 +1,198 @@
+/**
+ * Help Overlay V2
+ *
+ * A simple help overlay using the new Overlay interface.
+ * Displays available commands with navigation and detail view.
+ */
+import { getVisibleLength } from '../line-utils.js';
+// =============================================================================
+// Sample Commands (for testing)
+// =============================================================================
+const SAMPLE_COMMANDS = [
+    { name: '/help', description: 'Show this help overlay', details: 'Displays all available commands with descriptions.' },
+    { name: '/exit', description: 'Exit the application', details: 'Closes the CLI gracefully.' },
+    { name: '/clear', description: 'Clear the screen', details: 'Clears conversation history and resets the display.' },
+    { name: '/verbose', description: 'Toggle verbose mode', details: 'When enabled, shows thinking blocks and full tool output.' },
+    { name: '/compact', description: 'Compact conversation history', details: 'Summarizes older messages to save context space.' },
+    { name: '/config', description: 'Open configuration', details: 'Adjust settings like theme, model, and preferences.' },
+    { name: '/model', description: 'Select LLM model', details: 'Choose between Claude, OpenAI, Gemini, or Ollama models.' },
+    { name: '/theme', description: 'Change color theme', details: 'Pick from 418 terminal themes.' },
+    { name: '/tools', description: 'List available tools', details: 'Shows all tools the agent can use.' },
+    { name: '/tokens', description: 'Show token usage', details: 'Displays current context token count.' },
+    { name: '/init', description: 'Initialize project', details: 'Run the project initialization wizard.' },
+    { name: '/design', description: 'Design workflow', details: 'Start the requirements gathering workflow.' },
+];
+// =============================================================================
+// Help Overlay
+// =============================================================================
+export class HelpOverlayV2 {
+    type = 'inline';
+    id = 'help-overlay-v2';
+    state = {
+        selectedIndex: 0,
+        scrollOffset: 0,
+        pageSize: 10,
+    };
+    commands;
+    constructor(commands) {
+        this.commands = commands ?? SAMPLE_COMMANDS;
+    }
+    getState() {
+        return this.state;
+    }
+    render(context) {
+        const { width, styles: s } = context;
+        const lines = [];
+        // Fixed height for inline overlay (not full screen)
+        const maxVisibleItems = 10;
+        this.state.pageSize = maxVisibleItems;
+        // Header
+        const border = '─'.repeat(width);
+        lines.push(border);
+        lines.push(s.primaryBold(' Help - Available Commands'));
+        lines.push('');
+        // Adjust scroll offset to keep selection visible
+        if (this.state.selectedIndex < this.state.scrollOffset) {
+            this.state.scrollOffset = this.state.selectedIndex;
+        }
+        else if (this.state.selectedIndex >= this.state.scrollOffset + this.state.pageSize) {
+            this.state.scrollOffset = this.state.selectedIndex - this.state.pageSize + 1;
+        }
+        // Visible commands
+        const visibleCommands = this.commands.slice(this.state.scrollOffset, this.state.scrollOffset + this.state.pageSize);
+        // Scroll indicator (top)
+        if (this.state.scrollOffset > 0) {
+            lines.push(s.muted(`  ↑ ${String(this.state.scrollOffset)} more above`));
+        }
+        // Command list
+        for (let i = 0; i < visibleCommands.length; i++) {
+            const cmd = visibleCommands[i];
+            const actualIndex = this.state.scrollOffset + i;
+            const isSelected = actualIndex === this.state.selectedIndex;
+            const prefix = isSelected ? s.primary(' ❯ ') : '   ';
+            const name = isSelected
+                ? s.primaryBold(cmd.name.padEnd(15))
+                : s.muted(cmd.name.padEnd(15));
+            // Truncate description if needed
+            const prefixLen = 3 + 15 + 3; // prefix + name + spacing
+            const maxDescLen = width - prefixLen - 2;
+            let desc = cmd.description;
+            if (desc.length > maxDescLen) {
+                desc = desc.slice(0, maxDescLen - 1) + '…';
+            }
+            lines.push(prefix + name + '   ' + s.muted(desc));
+        }
+        // Scroll indicator (bottom)
+        const belowCount = this.commands.length - this.state.scrollOffset - visibleCommands.length;
+        if (belowCount > 0) {
+            lines.push(s.muted(`  ↓ ${String(belowCount)} more below`));
+        }
+        // Footer
+        lines.push(border);
+        lines.push(s.muted('  ↑↓ Navigate   Enter Details   q/Esc Close'));
+        lines.push(border);
+        return { lines };
+    }
+    handleKey(key) {
+        // Close on Escape or 'q'
+        if (key.name === 'escape' || key.name === 'q') {
+            return { type: 'close', cancelled: true };
+        }
+        // Navigate up
+        if (key.name === 'up' || key.name === 'k') {
+            if (this.state.selectedIndex > 0) {
+                this.state.selectedIndex--;
+                return { type: 'render' };
+            }
+            return { type: 'none' };
+        }
+        // Navigate down
+        if (key.name === 'down' || key.name === 'j') {
+            if (this.state.selectedIndex < this.commands.length - 1) {
+                this.state.selectedIndex++;
+                return { type: 'render' };
+            }
+            return { type: 'none' };
+        }
+        // Page up
+        if (key.name === 'pageup') {
+            this.state.selectedIndex = Math.max(0, this.state.selectedIndex - this.state.pageSize);
+            return { type: 'render' };
+        }
+        // Page down
+        if (key.name === 'pagedown') {
+            this.state.selectedIndex = Math.min(this.commands.length - 1, this.state.selectedIndex + this.state.pageSize);
+            return { type: 'render' };
+        }
+        // Enter - show details (push detail overlay)
+        if (key.name === 'return') {
+            const selectedCommand = this.commands[this.state.selectedIndex];
+            return {
+                type: 'push',
+                overlay: new HelpDetailOverlay(selectedCommand),
+            };
+        }
+        return { type: 'none' };
+    }
+}
+class HelpDetailOverlay {
+    type = 'inline';
+    id;
+    command;
+    constructor(command) {
+        this.command = command;
+        this.id = `help-detail-${command.name}`;
+    }
+    getState() {
+        return { command: this.command };
+    }
+    render(context) {
+        const { width, styles: s } = context;
+        const lines = [];
+        const border = '─'.repeat(width);
+        // Header
+        lines.push(border);
+        lines.push(s.primaryBold(' Command Details'));
+        lines.push('');
+        // Command name
+        lines.push(s.primary(' ' + this.command.name));
+        lines.push('');
+        // Description
+        lines.push(s.muted(' DESCRIPTION'));
+        lines.push('   ' + this.command.description);
+        lines.push('');
+        // Details (if available)
+        if (this.command.details) {
+            lines.push(s.muted(' ABOUT'));
+            // Wrap long text
+            const maxWidth = width - 6;
+            const words = this.command.details.split(' ');
+            let currentLine = '   ';
+            for (const word of words) {
+                if (getVisibleLength(currentLine) + word.length + 1 > maxWidth) {
+                    lines.push(currentLine);
+                    currentLine = '   ' + word;
+                }
+                else {
+                    currentLine += (currentLine.length > 3 ? ' ' : '') + word;
+                }
+            }
+            if (currentLine.length > 3) {
+                lines.push(currentLine);
+            }
+            lines.push('');
+        }
+        // Footer
+        lines.push(border);
+        lines.push(s.muted('  q/Esc Back'));
+        lines.push(border);
+        return { lines };
+    }
+    handleKey(key) {
+        // Go back on Escape or 'q'
+        if (key.name === 'escape' || key.name === 'q') {
+            return { type: 'pop' };
+        }
+        return { type: 'none' };
+    }
+}

package/dist/ui/overlays/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Overlays using the new Overlay interface
+ */
+export { HelpOverlayV2 } from '../help-overlay-v2.js';
+export { ThemeOverlayV2, type ThemeOverlayOptions, type ThemeOverlayResult } from '../theme-overlay-v2.js';
+export { ModelOverlayV2, type ModelOverlayV2Options, type ModelOverlayV2Result } from '../model-overlay-v2.js';
+export { ToolsOverlayV2, type ToolsOverlayV2Options, type ToolsOverlayV2Result, type ToolInfo, type ToolParameter, type ToolPermissionInfo } from '../tools-overlay-v2.js';
+export { KeysOverlayV2, type KeysOverlayV2Result } from '../keys-overlay-v2.js';
+export { MascotOverlayV2, type MascotOverlayV2Options, type MascotOverlayV2Result } from '../mascot-overlay-v2.js';
+export { TutorialOverlayV2, type TutorialOverlayV2Result } from '../tutorial-overlay-v2.js';
+export { CommandsOverlayV2, type CommandsOverlayV2Result } from '../commands-overlay-v2.js';

package/dist/ui/overlays/index.js

@@ -0,0 +1,11 @@
+/**
+ * Overlays using the new Overlay interface
+ */
+export { HelpOverlayV2 } from '../help-overlay-v2.js';
+export { ThemeOverlayV2 } from '../theme-overlay-v2.js';
+export { ModelOverlayV2 } from '../model-overlay-v2.js';
+export { ToolsOverlayV2 } from '../tools-overlay-v2.js';
+export { KeysOverlayV2 } from '../keys-overlay-v2.js';
+export { MascotOverlayV2 } from '../mascot-overlay-v2.js';
+export { TutorialOverlayV2 } from '../tutorial-overlay-v2.js';
+export { CommandsOverlayV2 } from '../commands-overlay-v2.js';

package/dist/ui/overlays.d.ts

@@ -8,10 +8,6 @@
  * - Context stats
  */
 import type { ContextStats, PermissionResult } from './types.js';
-/**
- * Show the tabbed help menu
- */
-export declare function showHelp(): Promise<void>;
 export interface ConfirmationOptions {
     confirmText?: string;
     cancelText?: string;