otherwise-cli 0.1.0

package/src/ui/hooks/useNotifications.js

@@ -0,0 +1,185 @@
+/**
+ * Desktop notifications hook for Ink UI
+ * Provides notifications for long-running tasks
+ */
+
+import { useCallback, useRef, useEffect } from 'react';
+
+/**
+ * Check if desktop notifications are available
+ * @returns {boolean}
+ */
+function areNotificationsAvailable() {
+  // Check for node-notifier or native notifications
+  try {
+    // In Node.js environment, we'll use terminal bell as fallback
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send a terminal bell (audible notification)
+ */
+function terminalBell() {
+  process.stdout.write('\x07');
+}
+
+/**
+ * Send a native notification (if available)
+ * @param {object} options - Notification options
+ */
+async function sendNativeNotification({ title, message, sound = true }) {
+  try {
+    // Try to use node-notifier if available
+    const notifier = await import('node-notifier').catch(() => null);
+    
+    if (notifier?.default?.notify) {
+      notifier.default.notify({
+        title: title || 'Otherwise',
+        message: message,
+        sound: sound,
+        wait: false,
+      });
+      return true;
+    }
+    
+    // Fallback to terminal bell
+    if (sound) {
+      terminalBell();
+    }
+    return false;
+  } catch {
+    // Fallback to terminal bell
+    if (sound) {
+      terminalBell();
+    }
+    return false;
+  }
+}
+
+/**
+ * Custom hook for notifications
+ * @param {object} options - Configuration options
+ * @returns {object} - Notification utilities
+ */
+export function useNotifications(options = {}) {
+  const {
+    enabled = true,
+    soundEnabled = true,
+    minDuration = 30000, // Only notify for tasks > 30 seconds
+    notifyOnComplete = true,
+    notifyOnError = true,
+  } = options;
+  
+  const taskStartTimes = useRef({});
+  const isAvailable = areNotificationsAvailable();
+  
+  /**
+   * Start tracking a task for potential notification
+   * @param {string} taskId - Unique task identifier
+   */
+  const startTask = useCallback((taskId) => {
+    if (!enabled) return;
+    taskStartTimes.current[taskId] = Date.now();
+  }, [enabled]);
+  
+  /**
+   * Complete a task and potentially send notification
+   * @param {string} taskId - Task identifier
+   * @param {object} options - Completion options
+   */
+  const completeTask = useCallback(async (taskId, { 
+    success = true, 
+    message = '',
+    forceNotify = false,
+  } = {}) => {
+    if (!enabled) return;
+    
+    const startTime = taskStartTimes.current[taskId];
+    if (!startTime) return;
+    
+    const duration = Date.now() - startTime;
+    delete taskStartTimes.current[taskId];
+    
+    // Check if we should notify
+    const shouldNotify = forceNotify || duration >= minDuration;
+    if (!shouldNotify) return;
+    
+    if (!success && notifyOnError) {
+      await sendNativeNotification({
+        title: 'Otherwise - Task Failed',
+        message: message || 'A task failed to complete',
+        sound: soundEnabled,
+      });
+    } else if (success && notifyOnComplete) {
+      await sendNativeNotification({
+        title: 'Otherwise - Task Complete',
+        message: message || 'Your task has completed',
+        sound: soundEnabled,
+      });
+    }
+  }, [enabled, minDuration, notifyOnComplete, notifyOnError, soundEnabled]);
+  
+  /**
+   * Send an immediate notification
+   * @param {string} title - Notification title
+   * @param {string} message - Notification message
+   * @param {object} options - Additional options
+   */
+  const notify = useCallback(async (title, message, { sound = true } = {}) => {
+    if (!enabled) return false;
+    
+    return sendNativeNotification({
+      title,
+      message,
+      sound: sound && soundEnabled,
+    });
+  }, [enabled, soundEnabled]);
+  
+  /**
+   * Play just the bell sound
+   */
+  const bell = useCallback(() => {
+    if (soundEnabled) {
+      terminalBell();
+    }
+  }, [soundEnabled]);
+  
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      taskStartTimes.current = {};
+    };
+  }, []);
+  
+  return {
+    isAvailable,
+    startTask,
+    completeTask,
+    notify,
+    bell,
+  };
+}
+
+/**
+ * Generation completion notification helper
+ * @param {object} stats - Generation stats
+ * @param {number} duration - Duration in ms
+ * @param {function} notify - Notify function
+ */
+export async function notifyGenerationComplete(stats, duration, notify) {
+  if (duration < 30000) return; // Don't notify for quick generations
+  
+  const tokenStr = stats?.numTokens ? `${stats.numTokens} tokens` : '';
+  const tpsStr = stats?.tps ? `${Math.round(stats.tps)} tok/s` : '';
+  const parts = [tokenStr, tpsStr].filter(Boolean).join(' • ');
+  
+  await notify(
+    'Generation Complete',
+    parts || 'AI has finished responding',
+  );
+}
+
+export default useNotifications;

package/src/ui/hooks/useTerminalSize.js

@@ -0,0 +1,151 @@
+/**
+ * useTerminalSize hook
+ * Provides reactive terminal dimensions that update on resize
+ * Essential for responsive CLI rendering with Ink
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+
+/**
+ * Default terminal dimensions fallback
+ */
+const DEFAULT_COLUMNS = 80;
+const DEFAULT_ROWS = 24;
+
+/**
+ * Breakpoint thresholds for responsive layouts
+ */
+const BREAKPOINTS = {
+  narrow: 60,
+  medium: 100,
+  wide: 140,
+};
+
+/**
+ * Get current terminal dimensions
+ * @returns {{columns: number, rows: number}}
+ */
+function getTerminalSize() {
+  return {
+    columns: process.stdout.columns || DEFAULT_COLUMNS,
+    rows: process.stdout.rows || DEFAULT_ROWS,
+  };
+}
+
+/**
+ * Hook to track terminal size with automatic updates on resize
+ * @param {object} options - Configuration options
+ * @param {number} options.padding - Horizontal padding to subtract from content width (default: 4)
+ * @param {number} options.maxContentWidth - Maximum content width for readability (default: 120)
+ * @param {number} options.minContentWidth - Minimum content width (default: 40)
+ * @returns {object} Terminal size information and responsive utilities
+ */
+export function useTerminalSize(options = {}) {
+  const {
+    padding = 4,
+    maxContentWidth = 120,
+    minContentWidth = 40,
+  } = options;
+
+  const [size, setSize] = useState(getTerminalSize);
+
+  useEffect(() => {
+    const handleResize = () => {
+      const newSize = getTerminalSize();
+      setSize(prev => {
+        // Only update if dimensions actually changed
+        if (prev.columns !== newSize.columns || prev.rows !== newSize.rows) {
+          return newSize;
+        }
+        return prev;
+      });
+    };
+
+    // Listen for resize events
+    process.stdout.on('resize', handleResize);
+
+    // Also check periodically in case resize event is missed
+    // (some terminals don't emit resize properly)
+    const interval = setInterval(handleResize, 1000);
+
+    return () => {
+      process.stdout.off('resize', handleResize);
+      clearInterval(interval);
+    };
+  }, []);
+
+  // Compute responsive values
+  const responsive = useMemo(() => {
+    const { columns, rows } = size;
+
+    // Responsive breakpoints
+    const isNarrow = columns < BREAKPOINTS.narrow;
+    const isMedium = columns >= BREAKPOINTS.narrow && columns < BREAKPOINTS.medium;
+    const isWide = columns >= BREAKPOINTS.medium;
+    const isExtraWide = columns >= BREAKPOINTS.wide;
+
+    // Content width calculations
+    const rawContentWidth = columns - padding;
+    const contentWidth = Math.max(minContentWidth, Math.min(rawContentWidth, maxContentWidth));
+    
+    // For text that should use more width on wide terminals
+    const textWidth = Math.max(minContentWidth, Math.min(rawContentWidth, 100));
+    
+    // For UI elements like borders and dividers
+    const uiWidth = Math.max(30, Math.min(rawContentWidth, 60));
+
+    // Compact mode for very narrow terminals
+    const useCompactMode = columns < 50;
+
+    return {
+      columns,
+      rows,
+      isNarrow,
+      isMedium,
+      isWide,
+      isExtraWide,
+      contentWidth,
+      textWidth,
+      uiWidth,
+      useCompactMode,
+      // Raw values for custom calculations
+      rawWidth: columns,
+      rawHeight: rows,
+    };
+  }, [size, padding, maxContentWidth, minContentWidth]);
+
+  return responsive;
+}
+
+/**
+ * Get terminal width synchronously (for non-React contexts)
+ * @returns {number} Current terminal width
+ */
+export function getTerminalWidth() {
+  return process.stdout.columns || DEFAULT_COLUMNS;
+}
+
+/**
+ * Get terminal height synchronously (for non-React contexts)
+ * @returns {number} Current terminal height
+ */
+export function getTerminalHeight() {
+  return process.stdout.rows || DEFAULT_ROWS;
+}
+
+/**
+ * Calculate responsive width based on terminal size
+ * @param {number} baseWidth - Base width at 100 columns
+ * @param {object} options - Options
+ * @param {number} options.min - Minimum width
+ * @param {number} options.max - Maximum width
+ * @returns {number} Scaled width
+ */
+export function calculateResponsiveWidth(baseWidth, options = {}) {
+  const { min = 20, max = baseWidth * 1.5 } = options;
+  const terminalWidth = getTerminalWidth();
+  const scale = terminalWidth / 100;
+  return Math.max(min, Math.min(Math.floor(baseWidth * scale), max));
+}
+
+export default useTerminalSize;

package/src/ui/hooks/useWebSocket.js

@@ -0,0 +1,273 @@
+/**
+ * WebSocket connection hook for Ink UI
+ * Manages real-time communication with the Otherwise server
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { WebSocket } from 'ws';
+
+/**
+ * WebSocket connection states
+ */
+export const ConnectionState = {
+  CONNECTING: 'connecting',
+  CONNECTED: 'connected',
+  DISCONNECTED: 'disconnected',
+  RECONNECTING: 'reconnecting',
+  ERROR: 'error',
+};
+
+/**
+ * Custom hook for WebSocket connection management
+ * @param {string} serverUrl - Base server URL (http://localhost:3000)
+ * @param {object} options - Configuration options
+ * @returns {object} - WebSocket state and methods
+ */
+export function useWebSocket(serverUrl, options = {}) {
+  const {
+    autoConnect = true,
+    autoReconnect = true,
+    reconnectDelay = 2000,
+    maxReconnectAttempts = 10,
+    onMessage,
+    onConnect,
+    onDisconnect,
+    onError,
+  } = options;
+
+  const wsUrl = serverUrl.replace('http', 'ws') + '/ws';
+  
+  const [connectionState, setConnectionState] = useState(ConnectionState.DISCONNECTED);
+  const [error, setError] = useState(null);
+  
+  const wsRef = useRef(null);
+  const reconnectAttemptsRef = useRef(0);
+  const reconnectTimeoutRef = useRef(null);
+  const mountedRef = useRef(true);
+  const hasConnectedRef = useRef(false); // Track if we've ever connected
+  const connectionStateRef = useRef(connectionState); // Track current state in ref
+  
+  // Keep ref in sync with state
+  useEffect(() => {
+    connectionStateRef.current = connectionState;
+  }, [connectionState]);
+
+  /**
+   * Schedule a reconnection attempt
+   */
+  const scheduleReconnect = useCallback(() => {
+    if (!autoReconnect) return;
+    if (reconnectAttemptsRef.current >= maxReconnectAttempts) return;
+    if (!mountedRef.current) return;
+    
+    reconnectAttemptsRef.current++;
+    setConnectionState(ConnectionState.RECONNECTING);
+    
+    reconnectTimeoutRef.current = setTimeout(() => {
+      if (mountedRef.current) {
+        if (wsRef.current) {
+          wsRef.current.removeAllListeners();
+          wsRef.current = null;
+        }
+        setConnectionState(ConnectionState.CONNECTING);
+        createConnection();
+      }
+    }, reconnectDelay);
+  }, [autoReconnect, maxReconnectAttempts, reconnectDelay]);
+
+  /**
+   * Create WebSocket connection
+   */
+  const createConnection = useCallback(() => {
+    try {
+      const ws = new WebSocket(wsUrl);
+      wsRef.current = ws;
+
+      ws.on('open', () => {
+        if (!mountedRef.current) return;
+        
+        hasConnectedRef.current = true;
+        reconnectAttemptsRef.current = 0;
+        setConnectionState(ConnectionState.CONNECTED);
+        onConnect?.();
+      });
+
+      ws.on('message', (data) => {
+        if (!mountedRef.current) return;
+        
+        try {
+          const message = JSON.parse(data.toString());
+          onMessage?.(message);
+        } catch (e) {
+          // Ignore parse errors
+        }
+      });
+
+      ws.on('close', () => {
+        if (!mountedRef.current) return;
+        
+        const wasConnected = connectionStateRef.current === ConnectionState.CONNECTED;
+        setConnectionState(ConnectionState.DISCONNECTED);
+        
+        if (wasConnected) {
+          onDisconnect?.();
+        }
+
+        // Always try to reconnect (whether initial connect failed or we disconnected)
+        scheduleReconnect();
+      });
+
+      ws.on('error', (err) => {
+        if (!mountedRef.current) return;
+        
+        // Only report errors if we were connected
+        if (hasConnectedRef.current) {
+          setError(err.message);
+          onError?.(err);
+        }
+        // The 'close' event will fire after error, which will trigger reconnect
+      });
+    } catch (err) {
+      // Connection creation failed - schedule retry
+      scheduleReconnect();
+    }
+  }, [wsUrl, onMessage, onConnect, onDisconnect, onError, scheduleReconnect]);
+
+  /**
+   * Connect to WebSocket server
+   */
+  const connect = useCallback(() => {
+    // Don't connect if already connected or connecting
+    if (wsRef.current?.readyState === WebSocket.OPEN) return;
+    if (wsRef.current?.readyState === WebSocket.CONNECTING) return;
+    
+    // Clean up existing socket
+    if (wsRef.current) {
+      wsRef.current.removeAllListeners();
+      wsRef.current = null;
+    }
+    
+    setConnectionState(ConnectionState.CONNECTING);
+    setError(null);
+    reconnectAttemptsRef.current = 0;
+    
+    createConnection();
+  }, [createConnection]);
+
+  /**
+   * Disconnect from WebSocket server
+   */
+  const disconnect = useCallback(() => {
+    // Cancel any pending reconnect
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current);
+      reconnectTimeoutRef.current = null;
+    }
+    
+    // Close and clean up socket
+    if (wsRef.current) {
+      wsRef.current.removeAllListeners();
+      try {
+        wsRef.current.close();
+      } catch (e) {
+        // Ignore close errors
+      }
+      wsRef.current = null;
+    }
+    
+    setConnectionState(ConnectionState.DISCONNECTED);
+  }, []);
+
+  /**
+   * Send a message through WebSocket
+   * @param {object} message - Message to send
+   * @returns {boolean} - Success status
+   */
+  const send = useCallback((message) => {
+    if (wsRef.current?.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+    
+    try {
+      wsRef.current.send(JSON.stringify(message));
+      return true;
+    } catch (err) {
+      setError(err.message);
+      return false;
+    }
+  }, []);
+
+  /**
+   * Send a chat message
+   * @param {object} payload - Chat payload
+   */
+  const sendChatMessage = useCallback((payload) => {
+    return send({
+      type: 'chat',
+      payload,
+    });
+  }, [send]);
+
+  /**
+   * Send a stop generation request
+   * @param {number} chatId - Chat ID to stop
+   */
+  const sendStop = useCallback((chatId) => {
+    return send({
+      type: 'stop',
+      chatId,
+    });
+  }, [send]);
+
+  /**
+   * Broadcast chat selection to other clients
+   * @param {number|null} chatId - Selected chat ID
+   */
+  const selectChat = useCallback((chatId) => {
+    return send({
+      type: 'select_chat',
+      chatId,
+    });
+  }, [send]);
+
+  // Auto-connect on mount
+  useEffect(() => {
+    mountedRef.current = true;
+    
+    if (autoConnect) {
+      // Delay to ensure server is ready (server starts concurrently with Ink UI)
+      const timer = setTimeout(() => {
+        if (mountedRef.current) {
+          connect();
+        }
+      }, 500);
+      
+      return () => {
+        clearTimeout(timer);
+        mountedRef.current = false;
+        disconnect();
+      };
+    }
+
+    return () => {
+      mountedRef.current = false;
+      disconnect();
+    };
+  }, []); // Only run on mount/unmount - don't depend on connect/disconnect
+
+  return {
+    connectionState,
+    isConnected: connectionState === ConnectionState.CONNECTED,
+    isConnecting: connectionState === ConnectionState.CONNECTING,
+    isReconnecting: connectionState === ConnectionState.RECONNECTING,
+    error,
+    connect,
+    disconnect,
+    send,
+    sendChatMessage,
+    sendStop,
+    selectChat,
+  };
+}
+
+export default useWebSocket;

package/src/ui/index.js

@@ -0,0 +1,94 @@
+/**
+ * Ink UI entry point
+ * Provides a clean interface to the Ink-based React UI
+ * 
+ * Note: This file uses dynamic import with tsx loader for JSX transpilation.
+ * The UI components use JSX syntax and are loaded at runtime.
+ */
+
+import { render } from 'ink';
+import React from 'react';
+import chalk from 'chalk';
+
+// Re-export hooks and utilities (these don't use JSX)
+export * from './hooks/index.js';
+export * from './utils/index.js';
+
+/**
+ * Dynamically load JSX components using tsx
+ * Falls back to a simple UI if tsx loader isn't available
+ */
+async function loadComponents() {
+  try {
+    // Try to import JSX component
+    // This will work if tsx loader is registered or if running under tsx
+    const { App } = await import('./components/App.jsx');
+    return { App };
+  } catch (err) {
+    // Fallback: return a simple placeholder component
+    console.error('Failed to load Ink components:', err.message);
+    
+    // Return a simple fallback component
+    const FallbackApp = () => {
+      return React.createElement('text', { color: 'red' }, 
+        'Error: JSX components could not be loaded.'
+      );
+    };
+    
+    return { App: FallbackApp };
+  }
+}
+
+/**
+ * Start the Ink-based CLI
+ * @param {object} options - Configuration options
+ * @param {string} options.serverUrl - Server URL to connect to
+ * @param {boolean} options.showBanner - Whether to show the welcome banner
+ * @returns {Promise<object>} - Ink instance with rerender, unmount, waitUntilExit, clear methods
+ */
+export async function startInkCli(options = {}) {
+  const {
+    serverUrl = 'http://localhost:3000',
+    showBanner = true,
+    isRemoteMode = false,
+  } = options;
+  
+  // Clear terminal and set title before rendering
+  // This ensures a clean slate for Ink to manage
+  process.stdout.write('\x1b[2J\x1b[H'); // Clear screen and move cursor to top-left
+  process.stdout.write('\x1b]0;Otherwise\x07\x1b]2;Otherwise\x07'); // Set title
+  
+  // Load the App component
+  const { App } = await loadComponents();
+  
+  // Create React element
+  const element = React.createElement(App, { serverUrl, showBanner, isRemoteMode });
+  
+  // Render the app with optimized settings
+  const instance = render(element, {
+    exitOnCtrlC: false, // We handle Ctrl+C ourselves
+    patchConsole: true, // Intercept console.log to not interfere with UI
+  });
+  
+  return instance;
+}
+
+/**
+ * Main entry point when run directly
+ */
+export async function main() {
+  const instance = await startInkCli({
+    serverUrl: process.env.SERVER_URL || 'http://localhost:3000',
+    showBanner: true,
+  });
+  
+  // Wait for exit
+  await instance.waitUntilExit();
+  
+  console.log(chalk.dim.italic('\nGoodbye'));
+}
+
+export default {
+  startInkCli,
+  main,
+};