@vdntio/clai 0.1.0-alpha.1

package/dist/ui/hooks/useAnimation.js

@@ -0,0 +1,85 @@
+// src/ui/hooks/useAnimation.ts
+// Hook for smooth frame-based animations
+import { useState, useEffect, useRef } from 'react';
+/**
+ * Hook that cycles through animation frames at a specified interval
+ *
+ * @param frames - Array of frame strings to cycle through
+ * @param interval - Time between frames in milliseconds
+ * @param enabled - Whether animation is active (default true)
+ * @returns Current frame string
+ */
+export function useAnimation(frames, interval = 80, enabled = true) {
+    const [frameIndex, setFrameIndex] = useState(0);
+    const frameRef = useRef(0);
+    useEffect(() => {
+        if (!enabled || frames.length === 0) {
+            return;
+        }
+        const timer = setInterval(() => {
+            frameRef.current = (frameRef.current + 1) % frames.length;
+            setFrameIndex(frameRef.current);
+        }, interval);
+        return () => {
+            clearInterval(timer);
+        };
+    }, [frames, interval, enabled]);
+    return frames[frameIndex] ?? frames[0] ?? '';
+}
+/**
+ * Hook for a pulsing animation effect (alternates between two states)
+ *
+ * @param interval - Time between pulses in milliseconds
+ * @param enabled - Whether pulsing is active
+ * @returns Boolean indicating current pulse state
+ */
+export function usePulse(interval = 500, enabled = true) {
+    const [isPulsed, setIsPulsed] = useState(false);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        const timer = setInterval(() => {
+            setIsPulsed((prev) => !prev);
+        }, interval);
+        return () => {
+            clearInterval(timer);
+        };
+    }, [interval, enabled]);
+    return isPulsed;
+}
+/**
+ * Hook for a typewriter-style reveal animation
+ *
+ * @param text - Full text to reveal
+ * @param speed - Characters per second
+ * @param enabled - Whether animation is active
+ * @returns Currently visible portion of text
+ */
+export function useTypewriter(text, speed = 30, enabled = true) {
+    const [visibleLength, setVisibleLength] = useState(enabled ? 0 : text.length);
+    useEffect(() => {
+        if (!enabled) {
+            setVisibleLength(text.length);
+            return;
+        }
+        if (visibleLength >= text.length) {
+            return;
+        }
+        const interval = 1000 / speed;
+        const timer = setTimeout(() => {
+            setVisibleLength((prev) => Math.min(prev + 1, text.length));
+        }, interval);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [text, speed, enabled, visibleLength]);
+    // Reset when text changes
+    useEffect(() => {
+        if (enabled) {
+            setVisibleLength(0);
+        }
+    }, [text, enabled]);
+    return text.slice(0, visibleLength);
+}
+export default useAnimation;

package/dist/ui/hooks/useTerminalSize.d.ts

@@ -0,0 +1,12 @@
+import type { TerminalSize } from '../types.js';
+/**
+ * Hook that returns terminal dimensions with responsive breakpoints
+ * Automatically updates on terminal resize
+ *
+ * Breakpoints:
+ * - isNarrow: < 60 columns (compact layout, aggressive truncation)
+ * - isMedium: 60-100 columns (standard layout)
+ * - isWide: >= 100 columns (full layout with borders and padding)
+ */
+export declare function useTerminalSize(): TerminalSize;
+export default useTerminalSize;

package/dist/ui/hooks/useTerminalSize.js

@@ -0,0 +1,56 @@
+// src/ui/hooks/useTerminalSize.ts
+// Hook for responsive terminal dimensions with breakpoints
+import { useState, useEffect } from 'react';
+// Breakpoint thresholds
+const NARROW_THRESHOLD = 60;
+const WIDE_THRESHOLD = 100;
+/**
+ * Get current terminal dimensions
+ * Falls back to 80x24 if not available (standard terminal size)
+ */
+function getTerminalSize() {
+    return {
+        width: process.stdout.columns || 80,
+        height: process.stdout.rows || 24,
+    };
+}
+/**
+ * Calculate breakpoints from width
+ */
+function getBreakpoints(width) {
+    return {
+        isNarrow: width < NARROW_THRESHOLD,
+        isMedium: width >= NARROW_THRESHOLD && width < WIDE_THRESHOLD,
+        isWide: width >= WIDE_THRESHOLD,
+    };
+}
+/**
+ * Hook that returns terminal dimensions with responsive breakpoints
+ * Automatically updates on terminal resize
+ *
+ * Breakpoints:
+ * - isNarrow: < 60 columns (compact layout, aggressive truncation)
+ * - isMedium: 60-100 columns (standard layout)
+ * - isWide: >= 100 columns (full layout with borders and padding)
+ */
+export function useTerminalSize() {
+    const [size, setSize] = useState(getTerminalSize());
+    useEffect(() => {
+        const handleResize = () => {
+            setSize(getTerminalSize());
+        };
+        // Listen for terminal resize events
+        process.stdout.on('resize', handleResize);
+        // Cleanup listener on unmount
+        return () => {
+            process.stdout.off('resize', handleResize);
+        };
+    }, []);
+    const breakpoints = getBreakpoints(size.width);
+    return {
+        width: size.width,
+        height: size.height,
+        ...breakpoints,
+    };
+}
+export default useTerminalSize;

package/dist/ui/hooks/useTimeout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hook that executes a callback after a specified delay
+ * Automatically clears on unmount or when delay changes
+ *
+ * @param callback - Function to execute when timer expires
+ * @param delay - Delay in milliseconds, or null/0 to disable
+ */
+export declare function useTimeout(callback: () => void, delay: number | null | undefined): void;
+export default useTimeout;

package/dist/ui/hooks/useTimeout.js

@@ -0,0 +1,31 @@
+// src/ui/hooks/useTimeout.ts
+// Custom hook for configurable timeout handling
+import { useEffect, useRef } from 'react';
+/**
+ * Hook that executes a callback after a specified delay
+ * Automatically clears on unmount or when delay changes
+ *
+ * @param callback - Function to execute when timer expires
+ * @param delay - Delay in milliseconds, or null/0 to disable
+ */
+export function useTimeout(callback, delay) {
+    const callbackRef = useRef(callback);
+    // Update callback ref when callback changes (avoids stale closures)
+    useEffect(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+    useEffect(() => {
+        // Don't set timeout if delay is null, undefined, or <= 0
+        if (delay === null || delay === undefined || delay <= 0) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            callbackRef.current();
+        }, delay);
+        // Cleanup on unmount or delay change
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [delay]);
+}
+export default useTimeout;

package/dist/ui/index.d.ts

@@ -0,0 +1,25 @@
+import { type RenderOptions, type RenderResult } from './types.js';
+export { UserAction, UIPhase } from './types.js';
+export type { RenderOptions, RenderResult, UIState, AppProps, TerminalSize, } from './types.js';
+export { useTimeout } from './hooks/useTimeout.js';
+export { useTerminalSize } from './hooks/useTerminalSize.js';
+export { useAnimation, usePulse, useTypewriter } from './hooks/useAnimation.js';
+export { formatCommand, formatCounter, getCommandDisplayWidth, truncateMiddle, wrapText, createSeparator, } from './utils/formatCommand.js';
+export { createSpinner, withSpinner } from './spinner.js';
+export { printCommand, printWarning, printError, printSuccess, printInfo, } from './output.js';
+export { Spinner } from './components/Spinner.js';
+export { CommandDisplay } from './components/CommandDisplay.js';
+export { DangerousWarning } from './components/DangerousWarning.js';
+export { ActionPrompt } from './components/ActionPrompt.js';
+export { App } from './App.js';
+/**
+ * Render the interactive UI for command selection
+ *
+ * In TTY mode: Shows Ink-based interactive UI with keyboard navigation
+ * In piped mode: Returns first command immediately without UI
+ *
+ * @param options - Render options with commands, config, and danger status
+ * @returns Promise resolving to user action and selected command
+ */
+export declare function renderUI(options: RenderOptions): Promise<RenderResult>;
+export default renderUI;

package/dist/ui/index.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from 'ink';
+import { App } from './App.js';
+import { UserAction, } from './types.js';
+// Re-export types and enums
+export { UserAction, UIPhase } from './types.js';
+// Re-export hooks
+export { useTimeout } from './hooks/useTimeout.js';
+export { useTerminalSize } from './hooks/useTerminalSize.js';
+export { useAnimation, usePulse, useTypewriter } from './hooks/useAnimation.js';
+// Re-export utilities
+export { formatCommand, formatCounter, getCommandDisplayWidth, truncateMiddle, wrapText, createSeparator, } from './utils/formatCommand.js';
+// Re-export spinner and output
+export { createSpinner, withSpinner } from './spinner.js';
+export { printCommand, printWarning, printError, printSuccess, printInfo, } from './output.js';
+// Re-export components
+export { Spinner } from './components/Spinner.js';
+export { CommandDisplay } from './components/CommandDisplay.js';
+export { DangerousWarning } from './components/DangerousWarning.js';
+export { ActionPrompt } from './components/ActionPrompt.js';
+export { App } from './App.js';
+/**
+ * Render the interactive UI for command selection
+ *
+ * In TTY mode: Shows Ink-based interactive UI with keyboard navigation
+ * In piped mode: Returns first command immediately without UI
+ *
+ * @param options - Render options with commands, config, and danger status
+ * @returns Promise resolving to user action and selected command
+ */
+export function renderUI(options) {
+    const { commands, config, isDangerous } = options;
+    // Debug logging
+    if (config.debug) {
+        console.error('[UI] renderUI called');
+        console.error(`[UI] Commands: ${commands.length}, Dangerous: ${isDangerous}`);
+        console.error(`[UI] stdin.isTTY: ${process.stdin.isTTY}, stdout.isTTY: ${process.stdout.isTTY}`);
+    }
+    // Check if we're in TTY mode (interactive terminal)
+    const isTTY = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    // If not TTY (piped), return first command immediately without UI
+    if (!isTTY) {
+        if (config.debug) {
+            console.error('[UI] Non-TTY mode, returning first command');
+        }
+        return Promise.resolve({
+            action: UserAction.Execute,
+            command: commands[0] ?? '',
+        });
+    }
+    // TTY mode: render Ink UI
+    if (config.debug) {
+        console.error('[UI] TTY mode, rendering Ink UI');
+    }
+    return new Promise((resolve) => {
+        const { unmount, waitUntilExit } = render(_jsx(App, { commands: commands, isDangerous: isDangerous, config: config, onComplete: (action, command) => {
+                if (config.debug) {
+                    console.error(`[UI] onComplete: ${action}, ${command}`);
+                }
+                unmount();
+                resolve({ action, command });
+            } }), {
+            // Render to stderr so stdout stays clean for command output
+            stdout: process.stderr,
+            // Note: Do NOT pass debug: true to Ink - it makes renders static/append-only
+            // Our config.debug is for clai debug output, not Ink's internal debug mode
+        });
+        // Handle any errors during rendering
+        waitUntilExit().catch((err) => {
+            if (config.debug) {
+                console.error('[UI] Render error:', err);
+            }
+            resolve({
+                action: UserAction.Abort,
+                command: commands[0] ?? '',
+            });
+        });
+    });
+}
+export default renderUI;

package/dist/ui/output.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Print a command to stdout with nice formatting
+ */
+export declare function printCommand(command: string, isDangerous?: boolean): void;
+/**
+ * Print a warning to stderr
+ */
+export declare function printWarning(message: string): void;
+/**
+ * Print an error to stderr
+ */
+export declare function printError(message: string): void;
+/**
+ * Print a success message to stderr
+ */
+export declare function printSuccess(message: string): void;
+/**
+ * Print info to stderr
+ */
+export declare function printInfo(message: string): void;

package/dist/ui/output.js

@@ -0,0 +1,56 @@
+// src/ui/output.ts
+// Pretty output formatting for non-interactive mode
+const isTTY = process.stdout.isTTY;
+// ANSI color codes
+const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    cyan: '\x1b[36m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+};
+function color(text, ...codes) {
+    if (!isTTY)
+        return text;
+    return codes.join('') + text + colors.reset;
+}
+/**
+ * Print a command to stdout with nice formatting
+ */
+export function printCommand(command, isDangerous = false) {
+    if (isTTY) {
+        const promptColor = isDangerous ? colors.red : colors.green;
+        const cmdColor = isDangerous ? colors.red : colors.cyan;
+        process.stdout.write(`${promptColor}${colors.bold}$${colors.reset} ${cmdColor}${command}${colors.reset}\n`);
+    }
+    else {
+        // Clean output for piping
+        process.stdout.write(command);
+    }
+}
+/**
+ * Print a warning to stderr
+ */
+export function printWarning(message) {
+    process.stderr.write(color(`⚠️  ${message}`, colors.yellow) + '\n');
+}
+/**
+ * Print an error to stderr
+ */
+export function printError(message) {
+    process.stderr.write(color(`✗ ${message}`, colors.red) + '\n');
+}
+/**
+ * Print a success message to stderr
+ */
+export function printSuccess(message) {
+    process.stderr.write(color(`✓ ${message}`, colors.green) + '\n');
+}
+/**
+ * Print info to stderr
+ */
+export function printInfo(message) {
+    process.stderr.write(color(message, colors.dim) + '\n');
+}

package/dist/ui/spinner.d.ts

@@ -0,0 +1,13 @@
+export interface SpinnerInstance {
+    stop: (finalMessage?: string) => void;
+    update: (message: string) => void;
+}
+/**
+ * Create a simple terminal spinner
+ * Renders to stderr to keep stdout clean
+ */
+export declare function createSpinner(message: string): SpinnerInstance;
+/**
+ * Run an async function with a spinner
+ */
+export declare function withSpinner<T>(message: string, fn: () => Promise<T>, successMessage?: string): Promise<T>;

package/dist/ui/spinner.js

@@ -0,0 +1,58 @@
+// src/ui/spinner.ts
+// Simple terminal spinner for loading states (non-Ink)
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const INTERVAL = 80;
+/**
+ * Create a simple terminal spinner
+ * Renders to stderr to keep stdout clean
+ */
+export function createSpinner(message) {
+    // Only show spinner in TTY mode
+    if (!process.stderr.isTTY) {
+        return {
+            stop: () => { },
+            update: () => { },
+        };
+    }
+    let frameIndex = 0;
+    let currentMessage = message;
+    let stopped = false;
+    const render = () => {
+        if (stopped)
+            return;
+        const frame = FRAMES[frameIndex % FRAMES.length];
+        process.stderr.write(`\r\x1b[36m${frame}\x1b[0m ${currentMessage}`);
+        frameIndex++;
+    };
+    const timer = setInterval(render, INTERVAL);
+    render();
+    return {
+        stop: (finalMessage) => {
+            stopped = true;
+            clearInterval(timer);
+            // Clear the line
+            process.stderr.write('\r\x1b[K');
+            if (finalMessage) {
+                process.stderr.write(`${finalMessage}\n`);
+            }
+        },
+        update: (msg) => {
+            currentMessage = msg;
+        },
+    };
+}
+/**
+ * Run an async function with a spinner
+ */
+export async function withSpinner(message, fn, successMessage) {
+    const spinner = createSpinner(message);
+    try {
+        const result = await fn();
+        spinner.stop(successMessage);
+        return result;
+    }
+    catch (error) {
+        spinner.stop();
+        throw error;
+    }
+}

package/dist/ui/types.d.ts

@@ -0,0 +1,105 @@
+import type { Config } from '../config/types.js';
+/**
+ * User action choices for command handling
+ */
+export declare enum UserAction {
+    Execute = "execute",
+    Abort = "abort"
+}
+/**
+ * UI display phases
+ */
+export declare enum UIPhase {
+    Loading = "loading",
+    Select = "select",
+    Done = "done"
+}
+/**
+ * UI state for the interactive prompt
+ */
+export interface UIState {
+    phase: UIPhase;
+    commands: string[];
+    selectedIndex: number;
+    selectedAction: UserAction;
+    isDangerous: boolean;
+    error?: string;
+}
+/**
+ * Props for the main App component
+ */
+export interface AppProps {
+    commands: string[];
+    isDangerous: boolean;
+    config: Config;
+    onComplete: (action: UserAction, command: string) => void;
+}
+/**
+ * Options for renderUI function
+ */
+export interface RenderOptions {
+    commands: string[];
+    config: Config;
+    isDangerous: boolean;
+}
+/**
+ * Result from renderUI function
+ */
+export interface RenderResult {
+    action: UserAction;
+    command: string;
+}
+/**
+ * Terminal size breakpoints
+ */
+export interface TerminalBreakpoints {
+    isNarrow: boolean;
+    isMedium: boolean;
+    isWide: boolean;
+}
+/**
+ * Terminal dimensions with breakpoints
+ */
+export interface TerminalSize extends TerminalBreakpoints {
+    width: number;
+    height: number;
+}
+/**
+ * Animation frame configuration
+ */
+export interface AnimationConfig {
+    frames: readonly string[];
+    interval: number;
+}
+/**
+ * Color palette for the UI
+ */
+export declare const COLORS: {
+    readonly command: "#00d9ff";
+    readonly commandDim: "#0099b3";
+    readonly prompt: "#00ff88";
+    readonly execute: "#00ff88";
+    readonly executeDanger: "#ff4444";
+    readonly abort: "#ffaa00";
+    readonly danger: "#ff4444";
+    readonly dangerBg: "#330000";
+    readonly warning: "#ffaa00";
+    readonly border: "#444444";
+    readonly borderFocus: "#666666";
+    readonly dim: "#666666";
+    readonly highlight: "#ffffff";
+    readonly selected: "#00ff88";
+    readonly selectedBg: "#003311";
+};
+/**
+ * Spinner animation frames (smooth braille animation)
+ */
+export declare const SPINNER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * Alternative spinner for wider terminals (dots animation)
+ */
+export declare const SPINNER_DOTS: readonly ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
+/**
+ * Pulsing animation frames for attention
+ */
+export declare const PULSE_FRAMES: readonly ["●", "○"];

package/dist/ui/types.js

@@ -0,0 +1,60 @@
+// src/ui/types.ts
+// Types and enums for the interactive UI
+/**
+ * User action choices for command handling
+ */
+export var UserAction;
+(function (UserAction) {
+    UserAction["Execute"] = "execute";
+    UserAction["Abort"] = "abort";
+})(UserAction || (UserAction = {}));
+/**
+ * UI display phases
+ */
+export var UIPhase;
+(function (UIPhase) {
+    UIPhase["Loading"] = "loading";
+    UIPhase["Select"] = "select";
+    UIPhase["Done"] = "done";
+})(UIPhase || (UIPhase = {}));
+/**
+ * Color palette for the UI
+ */
+export const COLORS = {
+    // Primary colors
+    command: '#00d9ff', // Bright cyan for commands
+    commandDim: '#0099b3', // Dimmed cyan
+    prompt: '#00ff88', // Green for $ prompt
+    // Action colors
+    execute: '#00ff88', // Green for execute
+    executeDanger: '#ff4444', // Red for dangerous execute
+    abort: '#ffaa00', // Orange/yellow for abort
+    // Warning colors
+    danger: '#ff4444', // Red for danger
+    dangerBg: '#330000', // Dark red background
+    warning: '#ffaa00', // Yellow/orange warning
+    // UI chrome
+    border: '#444444', // Subtle border
+    borderFocus: '#666666', // Focused border
+    dim: '#666666', // Dimmed text
+    highlight: '#ffffff', // Highlighted text
+    // Selection
+    selected: '#00ff88', // Selected item
+    selectedBg: '#003311', // Selected background
+};
+/**
+ * Spinner animation frames (smooth braille animation)
+ */
+export const SPINNER_FRAMES = [
+    '⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'
+];
+/**
+ * Alternative spinner for wider terminals (dots animation)
+ */
+export const SPINNER_DOTS = [
+    '⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'
+];
+/**
+ * Pulsing animation frames for attention
+ */
+export const PULSE_FRAMES = ['●', '○'];

package/dist/ui/utils/formatCommand.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Format a command for display in the terminal
+ * Truncates with ellipsis if too long for available width
+ *
+ * @param command - The command string to format
+ * @param maxWidth - Maximum width available (in columns)
+ * @returns Formatted command string
+ */
+export declare function formatCommand(command: string, maxWidth: number): string;
+/**
+ * Format command counter like [1/3]
+ *
+ * @param currentIndex - Current index (0-based)
+ * @param total - Total number of commands
+ * @returns Formatted counter string
+ */
+export declare function formatCounter(currentIndex: number, total: number): string;
+/**
+ * Calculate available width for command display
+ * Accounts for prefix, counter, and padding
+ *
+ * @param terminalWidth - Total terminal width
+ * @param hasCounter - Whether counter will be shown
+ * @returns Width available for command text
+ */
+export declare function getCommandDisplayWidth(terminalWidth: number, hasCounter?: boolean): number;
+/**
+ * Truncate text with ellipsis in the middle (for paths)
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length
+ * @returns Truncated text
+ */
+export declare function truncateMiddle(text: string, maxLength: number): string;
+/**
+ * Wrap text to fit within a maximum width
+ *
+ * @param text - Text to wrap
+ * @param maxWidth - Maximum line width
+ * @returns Array of wrapped lines
+ */
+export declare function wrapText(text: string, maxWidth: number): string[];
+/**
+ * Create a visual separator line
+ *
+ * @param width - Width of the separator
+ * @param char - Character to use (default: ─)
+ * @returns Separator string
+ */
+export declare function createSeparator(width: number, char?: string): string;