@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/overlay/index.js

@@ -0,0 +1,54 @@
+/**
+ * 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 { ProjectEditOverlayV2 } from './impl/project-edit-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';
+export { OnboardingWizardOverlayV2 } from './impl/onboarding-wizard-overlay-v2.js';
+export { ResumeOverlayV2 } from './impl/resume-overlay-v2.js';
+export { PlanApprovalOverlayV2 } from './impl/plan-approval-overlay-v2.js';
+export { PermissionsOverlayV2 } from './impl/permissions-overlay-v2.js';
+export { ResetOverlayV2 } from './impl/reset-overlay-v2.js';
+export { SessionModeOverlayV2 } from './impl/session-mode-overlay-v2.js';
+export { TeamOverlayV2 } from './impl/team-overlay-v2.js';
+export { CustomAgentFormOverlayV2 } from './impl/custom-agent-form-overlay-v2.js';
+export { ArtifactOverlayV2 } from './impl/artifact-overlay-v2.js';
+export { ArtifactDetailOverlayV2 } from './impl/artifact-detail-overlay-v2.js';
+export { GamesOverlayV2 } from './impl/games-overlay-v2.js';
+export { PendingOverlayV2 } from './impl/pending-overlay-v2.js';
+export { BackgroundOverlayV2 } from './impl/background-overlay-v2.js';
+export { FilterOverlayV2 } from './impl/filter-overlay-v2.js';
+export { ChangelogOverlayV2 } from './impl/changelog-overlay-v2.js';
+export { NotificationsOverlayV2 } from './impl/notifications-overlay-v2.js';
+export { MCPOverlayV2 } from './impl/mcp-overlay-v2.js';
+export { DelegationsOverlayV2 } from './impl/delegations-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/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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;
+    /**
+     * Set callback for requesting re-render from async operations.
+     * Called by TerminalUI when mounting the overlay.
+     */
+    setRenderCallback?(callback: () => void): 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/overlay-manager.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Overlay lifecycle manager.
+ *
+ * Extracted from TerminalUI — owns the overlay stack, resolvers,
+ * render state, and print buffer. Uses host interface for footer
+ * clear/render and console output.
+ */
+import type { PrintableItem } from './terminal-types.js';
+import type { Overlay } from './overlay/index.js';
+export interface OverlayManagerHost {
+    clearFooter(): void;
+    renderFooter(): void;
+    print(item: PrintableItem): void;
+    renderItemToConsole(item: PrintableItem): void;
+}
+export declare class OverlayManager {
+    private readonly stack;
+    private readonly resolvers;
+    private renderState;
+    private printBuffer;
+    private readonly host;
+    constructor(host: OverlayManagerHost);
+    hasActiveOverlay(): boolean;
+    getActiveOverlay(): Overlay | null;
+    showOverlay<TResult>(overlay: Overlay<unknown, TResult>): Promise<TResult | null>;
+    closeCurrentOverlay(result: unknown, cancelled: boolean): void;
+    private enterFullscreenOverlayMode;
+    private enterInlineOverlayMode;
+    private exitOverlayMode;
+    bufferItem(item: PrintableItem): void;
+    private flushPrintBuffer;
+    requestOverlayRender(): void;
+    private clearOverlayRender;
+    private renderOverlay;
+    private renderFullscreenOverlay;
+    private renderInlineOverlay;
+    processOverlayAction(action: {
+        type: 'none' | 'render' | 'close' | 'push' | 'pop';
+        result?: unknown;
+        cancelled?: boolean;
+        overlay?: Overlay;
+    }): void;
+}

package/dist/ui/overlay-manager.js

@@ -0,0 +1,238 @@
+/**
+ * Overlay lifecycle manager.
+ *
+ * Extracted from TerminalUI — owns the overlay stack, resolvers,
+ * render state, and print buffer. Uses host interface for footer
+ * clear/render and console output.
+ */
+import * as terminal from './terminal.js';
+import { getVisibleLength } from './line-utils.js';
+import { getStyles } from '../themes/index.js';
+export class OverlayManager {
+    stack = [];
+    resolvers = new Map();
+    renderState = { lineCount: 0, maxLineCount: 0 };
+    printBuffer = [];
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    // ===========================================================================
+    // Queries
+    // ===========================================================================
+    hasActiveOverlay() {
+        return this.stack.length > 0;
+    }
+    getActiveOverlay() {
+        return this.stack.length > 0
+            ? this.stack[this.stack.length - 1]
+            : null;
+    }
+    // ===========================================================================
+    // Show / Close
+    // ===========================================================================
+    async showOverlay(overlay) {
+        const isPushingOntoExisting = this.stack.length > 0;
+        if (isPushingOntoExisting) {
+            this.clearOverlayRender();
+        }
+        this.stack.push(overlay);
+        overlay.setRenderCallback?.(() => { this.requestOverlayRender(); });
+        await overlay.onMount?.();
+        if (!overlay.usesAlternateScreen) {
+            if (overlay.type === 'fullscreen') {
+                this.enterFullscreenOverlayMode();
+            }
+            else {
+                this.enterInlineOverlayMode();
+            }
+        }
+        this.renderOverlay();
+        return new Promise((resolve) => {
+            this.resolvers.set(overlay.id, resolve);
+        });
+    }
+    closeCurrentOverlay(result, cancelled) {
+        const overlay = this.stack.pop();
+        if (!overlay)
+            return;
+        const usesAlternateScreen = overlay.usesAlternateScreen === true;
+        overlay.onUnmount?.();
+        const summary = (!cancelled && result !== null)
+            ? overlay.getCloseSummary?.(result)
+            : null;
+        if (this.stack.length === 0) {
+            if (usesAlternateScreen) {
+                this.renderState = { lineCount: 0, maxLineCount: 0 };
+                this.flushPrintBuffer();
+            }
+            else {
+                this.exitOverlayMode();
+            }
+        }
+        else {
+            if (!usesAlternateScreen) {
+                this.clearOverlayRender();
+            }
+            this.renderState = { lineCount: 0, maxLineCount: 0 };
+            this.renderOverlay();
+        }
+        if (summary) {
+            this.host.print({ type: 'info', message: summary });
+        }
+        const resolver = this.resolvers.get(overlay.id);
+        resolver?.(result);
+        this.resolvers.delete(overlay.id);
+    }
+    // ===========================================================================
+    // Overlay mode transitions
+    // ===========================================================================
+    enterFullscreenOverlayMode() {
+        this.host.clearFooter();
+        process.stdout.write('\x1b[2J\x1b[H');
+        this.renderState = { lineCount: 0, maxLineCount: 0 };
+    }
+    enterInlineOverlayMode() {
+        this.host.clearFooter();
+        this.renderState = { lineCount: 0, maxLineCount: 0 };
+    }
+    exitOverlayMode() {
+        this.clearOverlayRender();
+        this.renderState = { lineCount: 0, maxLineCount: 0 };
+        this.flushPrintBuffer();
+        this.host.renderFooter();
+    }
+    // ===========================================================================
+    // Print buffer (items queued while overlay is active)
+    // ===========================================================================
+    bufferItem(item) {
+        this.printBuffer.push(item);
+    }
+    flushPrintBuffer() {
+        if (this.printBuffer.length === 0)
+            return;
+        for (const item of this.printBuffer) {
+            this.host.renderItemToConsole(item);
+        }
+        this.printBuffer = [];
+    }
+    // ===========================================================================
+    // Render
+    // ===========================================================================
+    requestOverlayRender() {
+        if (this.getActiveOverlay()) {
+            this.renderOverlay();
+        }
+    }
+    clearOverlayRender() {
+        const linesToClear = this.renderState.maxLineCount;
+        if (linesToClear > 0) {
+            process.stdout.write(`\x1b[${String(linesToClear)}A`);
+            process.stdout.write('\r');
+            process.stdout.write('\x1b[J');
+        }
+    }
+    renderOverlay() {
+        const overlay = this.getActiveOverlay();
+        if (!overlay)
+            return;
+        const termWidth = terminal.getTerminalWidth();
+        const termHeight = terminal.getTerminalHeight();
+        const s = getStyles();
+        const context = {
+            width: termWidth,
+            height: termHeight,
+            styles: s,
+        };
+        const content = overlay.render(context);
+        if (overlay.type === 'fullscreen') {
+            this.renderFullscreenOverlay(content, termWidth);
+        }
+        else {
+            this.renderInlineOverlay(content, termWidth);
+        }
+    }
+    renderFullscreenOverlay(content, termWidth) {
+        this.clearOverlayRender();
+        let physicalLines = 0;
+        for (const line of content.lines) {
+            const visibleLen = getVisibleLength(line);
+            physicalLines += Math.max(1, Math.ceil(visibleLen / termWidth));
+        }
+        const contentMinHeight = content.minHeight ?? 0;
+        const naturalHeight = Math.max(physicalLines, contentMinHeight);
+        this.renderState.maxLineCount = Math.max(this.renderState.maxLineCount, naturalHeight);
+        const targetHeight = this.renderState.maxLineCount;
+        const paddedLines = [...content.lines];
+        while (physicalLines < targetHeight) {
+            paddedLines.push('');
+            physicalLines++;
+        }
+        this.renderState.lineCount = physicalLines;
+        for (let i = 0; i < paddedLines.length; i++) {
+            process.stdout.write(paddedLines[i]);
+            if (i < paddedLines.length - 1) {
+                process.stdout.write('\n');
+            }
+        }
+        if (content.cursorPosition) {
+            const { line, column } = content.cursorPosition;
+            const linesFromEnd = paddedLines.length - 1 - line;
+            if (linesFromEnd > 0) {
+                process.stdout.write(`\x1b[${String(linesFromEnd)}A`);
+            }
+            process.stdout.write(`\x1b[${String(column)}G`);
+        }
+        terminal.showCursor();
+    }
+    renderInlineOverlay(content, termWidth) {
+        this.clearOverlayRender();
+        let physicalLines = 0;
+        for (const line of content.lines) {
+            const visibleLen = getVisibleLength(line);
+            physicalLines += Math.max(1, Math.ceil(visibleLen / termWidth));
+        }
+        const contentMinHeight = content.minHeight ?? 0;
+        const naturalHeight = Math.max(physicalLines, contentMinHeight);
+        this.renderState.maxLineCount = Math.max(this.renderState.maxLineCount, naturalHeight);
+        const targetHeight = this.renderState.maxLineCount;
+        const paddedLines = [...content.lines];
+        while (physicalLines < targetHeight) {
+            paddedLines.push('');
+            physicalLines++;
+        }
+        this.renderState.lineCount = physicalLines;
+        for (const line of paddedLines) {
+            process.stdout.write(line + '\n');
+        }
+        terminal.showCursor();
+    }
+    // ===========================================================================
+    // Action processing
+    // ===========================================================================
+    processOverlayAction(action) {
+        switch (action.type) {
+            case 'none':
+                break;
+            case 'render':
+                this.renderOverlay();
+                break;
+            case 'close':
+                if (action.cancelled) {
+                    this.closeCurrentOverlay(null, true);
+                }
+                else {
+                    this.closeCurrentOverlay(action.result ?? null, false);
+                }
+                break;
+            case 'push':
+                if (action.overlay) {
+                    void this.showOverlay(action.overlay);
+                }
+                break;
+            case 'pop':
+                this.closeCurrentOverlay(null, true);
+                break;
+        }
+    }
+}

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;