@vdntio/clai 0.1.0-alpha.1

package/dist/output/index.js

@@ -0,0 +1,7 @@
+// src/output/index.ts
+// Re-export all output-related functionality
+export { ExecutionError, Errors, } from './types.js';
+export { isRecursiveCall, validateCommand, } from './validate.js';
+export { getShell, executeCommand, } from './execute.js';
+// Re-export print functions from ui/output for convenience
+export { printCommand, printWarning, printError, printSuccess, printInfo, } from '../ui/output.js';

package/dist/output/types.d.ts

@@ -0,0 +1,48 @@
+import { ClaiError } from '../error/index.js';
+/**
+ * Execution result type (functional Result pattern)
+ * Either success with exit code, or failure with typed error
+ */
+export type ExecutionResult = {
+    success: true;
+    exitCode: number;
+} | {
+    success: false;
+    error: ExecutionError;
+};
+/**
+ * Validation result for command validation
+ */
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: ExecutionError;
+};
+/**
+ * ExecutionError represents failures during command execution.
+ * Each error type has a specific exit code following shell conventions.
+ */
+export declare class ExecutionError extends ClaiError {
+    constructor(message: string, code: number, cause?: Error);
+}
+/**
+ * Error factory functions (pure, testable)
+ * Exit codes follow shell conventions:
+ * - 1: General error
+ * - 5: Safety abort (clai-specific)
+ * - 124: Timeout (following GNU coreutils timeout)
+ * - 126: Permission denied (POSIX)
+ * - 127: Command not found (POSIX)
+ * - 128+N: Killed by signal N
+ */
+export declare const Errors: {
+    readonly emptyCommand: () => ExecutionError;
+    readonly spawnFailed: (cmd: string, err: Error) => ExecutionError;
+    readonly shellNotFound: (shell: string) => ExecutionError;
+    readonly commandNotFound: (cmd: string) => ExecutionError;
+    readonly permissionDenied: (cmd: string) => ExecutionError;
+    readonly signalKilled: (signal: string) => ExecutionError;
+    readonly timeout: (timeoutMs: number) => ExecutionError;
+    readonly recursiveCall: () => ExecutionError;
+};

package/dist/output/types.js

@@ -0,0 +1,34 @@
+// src/output/types.ts
+// Types for command execution and result handling
+import { ClaiError } from '../error/index.js';
+/**
+ * ExecutionError represents failures during command execution.
+ * Each error type has a specific exit code following shell conventions.
+ */
+export class ExecutionError extends ClaiError {
+    constructor(message, code, cause) {
+        super(message, code, cause);
+        this.name = 'ExecutionError';
+        Object.setPrototypeOf(this, ExecutionError.prototype);
+    }
+}
+/**
+ * Error factory functions (pure, testable)
+ * Exit codes follow shell conventions:
+ * - 1: General error
+ * - 5: Safety abort (clai-specific)
+ * - 124: Timeout (following GNU coreutils timeout)
+ * - 126: Permission denied (POSIX)
+ * - 127: Command not found (POSIX)
+ * - 128+N: Killed by signal N
+ */
+export const Errors = {
+    emptyCommand: () => new ExecutionError('Empty command', 1),
+    spawnFailed: (cmd, err) => new ExecutionError(`Failed to spawn: ${cmd}`, 1, err),
+    shellNotFound: (shell) => new ExecutionError(`Shell not found: ${shell}`, 127),
+    commandNotFound: (cmd) => new ExecutionError(`Command not found: ${cmd}`, 127),
+    permissionDenied: (cmd) => new ExecutionError(`Permission denied: ${cmd}`, 126),
+    signalKilled: (signal) => new ExecutionError(`Killed by signal: ${signal}`, 128),
+    timeout: (timeoutMs) => new ExecutionError(`Command timed out after ${timeoutMs}ms`, 124),
+    recursiveCall: () => new ExecutionError('Refusing to execute clai recursively (would cause infinite loop)', 5),
+};

package/dist/output/validate.d.ts

@@ -0,0 +1,23 @@
+import { type ValidationResult } from './types.js';
+/**
+ * Detect recursive clai invocation (AI suggesting clai commands → infinite loop)
+ *
+ * Matches:
+ * - "clai" at start of command
+ * - "./clai" at start of command
+ * - "/path/to/clai" at start of command
+ * - "clai" after pipe: "echo | clai"
+ * - "clai" after &&: "cd foo && clai"
+ * - "clai" after ;: "echo hi; clai"
+ *
+ * Does NOT match (no false positives):
+ * - "claimant" (clai is substring of word)
+ * - "echo clai" (clai is argument, not command)
+ * - "/usr/bin/claim" (different command)
+ */
+export declare function isRecursiveCall(command: string): boolean;
+/**
+ * Validate command before execution
+ * Returns validation result with typed error if invalid
+ */
+export declare function validateCommand(command: string): ValidationResult;

package/dist/output/validate.js

@@ -0,0 +1,42 @@
+// src/output/validate.ts
+// Command validation before execution
+import { Errors } from './types.js';
+/**
+ * Detect recursive clai invocation (AI suggesting clai commands → infinite loop)
+ *
+ * Matches:
+ * - "clai" at start of command
+ * - "./clai" at start of command
+ * - "/path/to/clai" at start of command
+ * - "clai" after pipe: "echo | clai"
+ * - "clai" after &&: "cd foo && clai"
+ * - "clai" after ;: "echo hi; clai"
+ *
+ * Does NOT match (no false positives):
+ * - "claimant" (clai is substring of word)
+ * - "echo clai" (clai is argument, not command)
+ * - "/usr/bin/claim" (different command)
+ */
+export function isRecursiveCall(command) {
+    // Pattern explanation:
+    // (?:^|[|;&]\s*) - Start of string OR after pipe/&&/; with optional whitespace
+    // (?:\.\/|\/[\w\/]*)? - Optional ./ prefix or absolute path
+    // clai - The literal "clai"
+    // (?:\s|$) - Followed by whitespace or end of string (word boundary)
+    const claiPattern = /(?:^|[|;&]\s*)(?:\.\/|\/[\w/]*)?clai(?:\s|$)/;
+    return claiPattern.test(command);
+}
+/**
+ * Validate command before execution
+ * Returns validation result with typed error if invalid
+ */
+export function validateCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return { valid: false, error: Errors.emptyCommand() };
+    }
+    if (isRecursiveCall(trimmed)) {
+        return { valid: false, error: Errors.recursiveCall() };
+    }
+    return { valid: true };
+}

package/dist/safety/index.d.ts

@@ -0,0 +1,34 @@
+import type { Config } from '../config/types.js';
+import type { CompiledPattern } from './types.js';
+export { SafetyError } from './types.js';
+export type { CompiledPattern } from './types.js';
+export { DEFAULT_DANGEROUS_PATTERNS, compilePatterns, isDangerous } from './patterns.js';
+/**
+ * Load and compile dangerous patterns from config or defaults
+ *
+ * @param config - Application config
+ * @returns Compiled patterns ready for matching
+ */
+export declare function loadPatterns(config: Config): CompiledPattern[];
+/**
+ * Determine if we should show an interactive safety prompt
+ * Returns true only when all conditions are met:
+ * - Safety confirmation is enabled in config
+ * - Force flag is not set
+ * - Running in interactive TTY mode
+ *
+ * @param config - Application config
+ * @returns true if safety prompt should be shown
+ */
+export declare function shouldPrompt(config: Config): boolean;
+/**
+ * Check commands for dangerous patterns and determine UI behavior
+ *
+ * @param commands - Commands to check
+ * @param config - Application config
+ * @returns Object with danger status and prompt requirement
+ */
+export declare function checkSafety(commands: string[], config: Config): {
+    isDangerous: boolean;
+    shouldPrompt: boolean;
+};

package/dist/safety/index.js

@@ -0,0 +1,59 @@
+// src/safety/index.ts
+// Safety module entry point
+import { DEFAULT_DANGEROUS_PATTERNS, compilePatterns, isDangerous } from './patterns.js';
+// Re-export types and functions
+export { SafetyError } from './types.js';
+export { DEFAULT_DANGEROUS_PATTERNS, compilePatterns, isDangerous } from './patterns.js';
+/**
+ * Load and compile dangerous patterns from config or defaults
+ *
+ * @param config - Application config
+ * @returns Compiled patterns ready for matching
+ */
+export function loadPatterns(config) {
+    const patterns = config.safety.dangerousPatterns.length > 0
+        ? config.safety.dangerousPatterns
+        : DEFAULT_DANGEROUS_PATTERNS;
+    return compilePatterns(patterns);
+}
+/**
+ * Determine if we should show an interactive safety prompt
+ * Returns true only when all conditions are met:
+ * - Safety confirmation is enabled in config
+ * - Force flag is not set
+ * - Running in interactive TTY mode
+ *
+ * @param config - Application config
+ * @returns true if safety prompt should be shown
+ */
+export function shouldPrompt(config) {
+    // Don't prompt if safety confirmation is disabled
+    if (!config.safety.confirmDangerous) {
+        return false;
+    }
+    // Don't prompt if force flag is set
+    if (config.force) {
+        return false;
+    }
+    // Don't prompt in non-interactive mode (piped)
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check commands for dangerous patterns and determine UI behavior
+ *
+ * @param commands - Commands to check
+ * @param config - Application config
+ * @returns Object with danger status and prompt requirement
+ */
+export function checkSafety(commands, config) {
+    const patterns = loadPatterns(config);
+    // Check if any command is dangerous
+    const dangerous = commands.some((cmd) => isDangerous(cmd, patterns));
+    return {
+        isDangerous: dangerous,
+        shouldPrompt: dangerous && shouldPrompt(config),
+    };
+}

package/dist/safety/patterns.d.ts

@@ -0,0 +1,23 @@
+import type { CompiledPattern } from './types.js';
+/**
+ * Default dangerous patterns - regex strings that match potentially destructive commands
+ * These are compiled to RegExp at runtime for matching
+ */
+export declare const DEFAULT_DANGEROUS_PATTERNS: readonly string[];
+/**
+ * Compile pattern strings into RegExp objects
+ * Invalid patterns are marked with isValid: false
+ *
+ * @param patterns - Array of regex pattern strings
+ * @returns Array of compiled patterns with validity status
+ */
+export declare function compilePatterns(patterns: readonly string[]): CompiledPattern[];
+/**
+ * Check if a command matches any dangerous pattern
+ * Fail-safe: if any pattern is invalid, treat all commands as dangerous
+ *
+ * @param command - The command string to check
+ * @param compiledPatterns - Array of compiled patterns
+ * @returns true if command is dangerous, false if safe
+ */
+export declare function isDangerous(command: string, compiledPatterns: CompiledPattern[]): boolean;

package/dist/safety/patterns.js

@@ -0,0 +1,96 @@
+// src/safety/patterns.ts
+// Dangerous command pattern detection
+/**
+ * Default dangerous patterns - regex strings that match potentially destructive commands
+ * These are compiled to RegExp at runtime for matching
+ */
+export const DEFAULT_DANGEROUS_PATTERNS = [
+    // File deletion patterns
+    'rm\\s+(-[^\\s]*)?\\s*-rf\\s+/', // rm -rf / (root wipe)
+    'rm\\s+(-[^\\s]*)?\\s*-f', // rm with force flag
+    'rm\\s+(-[^\\s]*r[^\\s]*|[^\\s]*r)\\s+', // rm with recursive
+    'find\\s+.*-exec\\s+(rm|del)', // find ... -exec rm/del
+    // Disk/device operations
+    'dd\\s+.*if=/dev/(zero|random|urandom)', // disk wipe with dd
+    'dd\\s+.*of=/dev/', // write to raw device
+    'mkfs\\.\\w+\\s+/dev/', // format filesystem
+    'mkfs\\s+-t\\s+\\w+\\s+/dev/', // mkfs with type flag
+    'shred\\s+', // secure delete
+    // Privileged destruction
+    'sudo\\s+rm\\s+(-[^\\s]*)?\\s*-rf', // sudo rm -rf
+    'sudo\\s+dd\\s+', // sudo dd
+    'sudo\\s+mkfs', // sudo mkfs
+    // Redirects to devices
+    '>\\s*/dev/sd[a-z]', // redirect to disk device
+    '>\\s*/dev/nvme', // redirect to nvme
+    '>\\s*/dev/null.*<', // suspicious null redirect
+    // Database destruction
+    'drop\\s+database', // SQL drop database
+    'drop\\s+table', // SQL drop table
+    'truncate\\s+table', // SQL truncate
+    'delete\\s+from\\s+\\w+\\s*;?$', // DELETE without WHERE
+    // Git destructive operations
+    'git\\s+reset\\s+--hard', // discard all changes
+    'git\\s+clean\\s+-fd', // remove untracked files
+    'git\\s+push\\s+.*--force', // force push
+    // System modification
+    'chmod\\s+(-R\\s+)?777\\s+/', // world-writable root
+    'chown\\s+-R\\s+.*:\\s*/', // recursive chown on root
+    ':(){ :|:& };:', // fork bomb
+    // Windows-specific (for cross-platform awareness)
+    'format\\s+[a-z]:', // format drive
+    'del\\s+/[fqs]', // del with force/quiet/subdirs
+    'rd\\s+/s\\s+/q', // rmdir /s /q
+];
+/**
+ * Compile pattern strings into RegExp objects
+ * Invalid patterns are marked with isValid: false
+ *
+ * @param patterns - Array of regex pattern strings
+ * @returns Array of compiled patterns with validity status
+ */
+export function compilePatterns(patterns) {
+    return patterns.map((pattern) => {
+        try {
+            return {
+                pattern,
+                regex: new RegExp(pattern, 'i'),
+                isValid: true,
+            };
+        }
+        catch {
+            // Invalid regex - mark as invalid (will trigger fail-safe)
+            return {
+                pattern,
+                regex: null,
+                isValid: false,
+            };
+        }
+    });
+}
+/**
+ * Check if a command matches any dangerous pattern
+ * Fail-safe: if any pattern is invalid, treat all commands as dangerous
+ *
+ * @param command - The command string to check
+ * @param compiledPatterns - Array of compiled patterns
+ * @returns true if command is dangerous, false if safe
+ */
+export function isDangerous(command, compiledPatterns) {
+    // Empty command is safe
+    if (!command.trim()) {
+        return false;
+    }
+    // Fail-safe: if any pattern failed to compile, treat as dangerous
+    const hasInvalidPattern = compiledPatterns.some((p) => !p.isValid);
+    if (hasInvalidPattern) {
+        return true;
+    }
+    // Check each valid pattern for a match
+    for (const { regex } of compiledPatterns) {
+        if (regex && regex.test(command)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/safety/types.d.ts

@@ -0,0 +1,20 @@
+import { ClaiError } from '../error/index.js';
+/**
+ * SafetyError is thrown when:
+ * - User aborts a dangerous command
+ * - Confirmation timeout expires
+ * - Safety check fails
+ *
+ * Exit code: 5
+ */
+export declare class SafetyError extends ClaiError {
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Compiled pattern with validity status
+ */
+export interface CompiledPattern {
+    pattern: string;
+    regex: RegExp | null;
+    isValid: boolean;
+}

package/dist/safety/types.js

@@ -0,0 +1,18 @@
+// src/safety/types.ts
+// Safety error type for abort/timeout scenarios
+import { ClaiError } from '../error/index.js';
+/**
+ * SafetyError is thrown when:
+ * - User aborts a dangerous command
+ * - Confirmation timeout expires
+ * - Safety check fails
+ *
+ * Exit code: 5
+ */
+export class SafetyError extends ClaiError {
+    constructor(message, cause) {
+        super(message, 5, cause);
+        this.name = 'SafetyError';
+        Object.setPrototypeOf(this, SafetyError.prototype);
+    }
+}

package/dist/signals/index.d.ts

@@ -0,0 +1,4 @@
+export declare function registerSignalHandlers(): void;
+export declare function checkInterrupt(): void;
+export declare function isTTY(stream: 'stdin' | 'stdout' | 'stderr'): boolean;
+export declare function isInteractive(): boolean;

package/dist/signals/index.js

@@ -0,0 +1,35 @@
+import { InterruptError } from '../error/index.js';
+// Interrupt flag set by signal handlers
+let interrupted = false;
+// Register signal handlers
+export function registerSignalHandlers() {
+    process.on('SIGINT', handleInterrupt);
+    process.on('SIGTERM', handleInterrupt);
+    process.on('SIGPIPE', () => {
+        // Ignore broken pipe errors
+    });
+}
+function handleInterrupt() {
+    interrupted = true;
+    process.exit(130);
+}
+// Check if interrupted and throw if so
+export function checkInterrupt() {
+    if (interrupted) {
+        throw new InterruptError('Interrupted');
+    }
+}
+// TTY detection utilities
+export function isTTY(stream) {
+    switch (stream) {
+        case 'stdin':
+            return process.stdin.isTTY === true;
+        case 'stdout':
+            return process.stdout.isTTY === true;
+        case 'stderr':
+            return process.stderr.isTTY === true;
+    }
+}
+export function isInteractive() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}

package/dist/ui/App.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import { type AppProps } from './types.js';
+export declare function App({ commands, isDangerous, config, onComplete, }: AppProps): React.ReactElement;
+export default App;

package/dist/ui/App.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// src/ui/App.tsx
+// Clean, minimal interactive UI
+import { useState, useCallback } from 'react';
+import { Box, useInput, useApp, Text } from 'ink';
+import { UserAction } from './types.js';
+import { useTimeout } from './hooks/useTimeout.js';
+import { CommandDisplay } from './components/CommandDisplay.js';
+import { DangerousWarning } from './components/DangerousWarning.js';
+import { ActionPrompt } from './components/ActionPrompt.js';
+export function App({ commands, isDangerous, config, onComplete, }) {
+    const { exit } = useApp();
+    const [selectedIndex, setSelectedIndex] = useState(0);
+    const [selectedAction, setSelectedAction] = useState(UserAction.Execute);
+    const currentCommand = commands[selectedIndex] ?? '';
+    const hasMultiple = commands.length > 1;
+    // Note: Avoid console.error inside Ink components - it interferes with rendering
+    // Debug output is handled in renderUI before Ink mounts
+    // Handle completion
+    const handleComplete = useCallback((action) => {
+        onComplete(action, currentCommand);
+        exit();
+    }, [currentCommand, onComplete, exit]);
+    // Auto-abort timeout
+    useTimeout(() => handleComplete(UserAction.Abort), config.ui.promptTimeout > 0 ? config.ui.promptTimeout : null);
+    // Keyboard handling
+    useInput((input, key) => {
+        // Escape or Ctrl+C: cancel
+        if (key.escape || (key.ctrl && input === 'c')) {
+            handleComplete(UserAction.Abort);
+            return;
+        }
+        // Tab or arrows: cycle commands
+        if (hasMultiple && (key.tab || key.leftArrow || key.rightArrow)) {
+            const dir = key.leftArrow ? -1 : 1;
+            setSelectedIndex((i) => (i + dir + commands.length) % commands.length);
+            return;
+        }
+        // Up/Down: toggle action
+        if (key.upArrow || key.downArrow) {
+            setSelectedAction((a) => a === UserAction.Execute ? UserAction.Abort : UserAction.Execute);
+            return;
+        }
+        // Enter: confirm
+        if (key.return) {
+            handleComplete(selectedAction);
+            return;
+        }
+        // Number keys for direct selection
+        const num = parseInt(input, 10);
+        if (hasMultiple && num >= 1 && num <= commands.length) {
+            setSelectedIndex(num - 1);
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", paddingY: 1, children: [_jsx(CommandDisplay, { command: currentCommand, currentIndex: selectedIndex, totalCommands: commands.length, isDangerous: isDangerous }), hasMultiple && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "Tab: next command" }) })), isDangerous && _jsx(DangerousWarning, {}), _jsx(ActionPrompt, { selectedAction: selectedAction, isDangerous: isDangerous })] }));
+}
+export default App;

package/dist/ui/components/ActionPrompt.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import { UserAction } from '../types.js';
+export interface ActionPromptProps {
+    selectedAction: UserAction;
+    isDangerous: boolean;
+}
+export declare function ActionPrompt({ selectedAction, isDangerous, }: ActionPromptProps): React.ReactElement;
+export default ActionPrompt;

package/dist/ui/components/ActionPrompt.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { UserAction } from '../types.js';
+export function ActionPrompt({ selectedAction, isDangerous, }) {
+    const isExecute = selectedAction === UserAction.Execute;
+    const executeColor = isDangerous ? 'red' : 'green';
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Box, { gap: 2, children: [_jsx(Text, { color: isExecute ? 'black' : executeColor, backgroundColor: isExecute ? executeColor : undefined, bold: isExecute, children: isExecute ? ' ▶ Run ' : '   Run ' }), _jsx(Text, { color: !isExecute ? 'black' : 'yellow', backgroundColor: !isExecute ? 'yellow' : undefined, bold: !isExecute, children: !isExecute ? ' ▶ Cancel ' : '   Cancel ' })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: "\u2191\u2193 select  Enter confirm  Esc cancel" }) })] }));
+}
+export default ActionPrompt;

package/dist/ui/components/CommandDisplay.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+export interface CommandDisplayProps {
+    command: string;
+    currentIndex: number;
+    totalCommands: number;
+    isDangerous?: boolean;
+}
+export declare function CommandDisplay({ command, currentIndex, totalCommands, isDangerous, }: CommandDisplayProps): React.ReactElement;
+export default CommandDisplay;

package/dist/ui/components/CommandDisplay.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { formatCommand, formatCounter } from '../utils/formatCommand.js';
+export function CommandDisplay({ command, currentIndex, totalCommands, isDangerous = false, }) {
+    const { width } = useTerminalSize();
+    const counterWidth = totalCommands > 1 ? 8 : 0;
+    const availableWidth = width - counterWidth - 4;
+    const formattedCommand = formatCommand(command, availableWidth);
+    const counter = formatCounter(currentIndex, totalCommands);
+    return (_jsxs(Box, { children: [_jsx(Text, { color: isDangerous ? 'red' : 'green', bold: true, children: "$" }), _jsx(Text, { children: " " }), _jsx(Text, { color: isDangerous ? 'red' : 'cyan', bold: true, children: formattedCommand }), counter && (_jsxs(_Fragment, { children: [_jsx(Text, { children: "  " }), _jsx(Text, { dimColor: true, children: counter })] }))] }));
+}
+export default CommandDisplay;

package/dist/ui/components/DangerousWarning.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+export interface DangerousWarningProps {
+    message?: string;
+}
+export declare function DangerousWarning({ message, }: DangerousWarningProps): React.ReactElement;
+export default DangerousWarning;

package/dist/ui/components/DangerousWarning.js

@@ -0,0 +1,6 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+export function DangerousWarning({ message = 'This command may modify or delete files', }) {
+    return (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "yellow", children: ["\u26A0\uFE0F  ", message] }) }));
+}
+export default DangerousWarning;

package/dist/ui/components/Spinner.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+export interface SpinnerProps {
+    /** Message to display next to spinner */
+    message?: string;
+    /** Color of the spinner */
+    color?: string;
+    /** Animation speed in ms */
+    speed?: number;
+}
+/**
+ * Animated spinner component for loading states
+ * Uses braille characters for smooth animation
+ */
+export declare function Spinner({ message, color, speed, }: SpinnerProps): React.ReactElement;
+export default Spinner;

package/dist/ui/components/Spinner.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useAnimation } from '../hooks/useAnimation.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { SPINNER_FRAMES, SPINNER_DOTS, COLORS } from '../types.js';
+/**
+ * Animated spinner component for loading states
+ * Uses braille characters for smooth animation
+ */
+export function Spinner({ message = 'Processing...', color = COLORS.command, speed = 80, }) {
+    const { isWide } = useTerminalSize();
+    // Use fancier dots animation on wide terminals
+    const frames = isWide ? SPINNER_DOTS : SPINNER_FRAMES;
+    const frame = useAnimation(frames, speed);
+    return (_jsxs(Box, { children: [_jsx(Text, { color: color, bold: true, children: frame }), _jsxs(Text, { color: color, children: [" ", message] })] }));
+}
+export default Spinner;

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

@@ -0,0 +1,27 @@
+/**
+ * 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 declare function useAnimation(frames: readonly string[], interval?: number, enabled?: boolean): string;
+/**
+ * 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 declare function usePulse(interval?: number, enabled?: boolean): boolean;
+/**
+ * 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 declare function useTypewriter(text: string, speed?: number, enabled?: boolean): string;
+export default useAnimation;