@butlerw/vellum 0.1.0

package/src/tui/hooks/usePlaceholderRotation.ts

@@ -0,0 +1,143 @@
+/**
+ * usePlaceholderRotation Hook
+ *
+ * Rotates through example placeholder texts to help users discover capabilities.
+ * Inspired by OpenCode's prompt-input pattern.
+ *
+ * @module tui/hooks/usePlaceholderRotation
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for the usePlaceholderRotation hook.
+ */
+export interface UsePlaceholderRotationOptions {
+  /** Rotation interval in milliseconds (default: 5000) */
+  readonly interval?: number;
+  /** Whether rotation is enabled (default: true) */
+  readonly enabled?: boolean;
+  /** Custom placeholder examples (uses defaults if not provided) */
+  readonly examples?: readonly string[];
+  /** Static placeholder to use when input has content */
+  readonly staticPlaceholder?: string;
+}
+
+/**
+ * Return value of usePlaceholderRotation hook.
+ */
+export interface UsePlaceholderRotationReturn {
+  /** Current placeholder text to display */
+  readonly placeholder: string;
+  /** Index of current placeholder in examples array */
+  readonly currentIndex: number;
+  /** Manually advance to next placeholder */
+  readonly next: () => void;
+  /** Reset to first placeholder */
+  readonly reset: () => void;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Default placeholder examples showcasing Vellum capabilities.
+ * Each demonstrates a different type of task users can request.
+ */
+export const DEFAULT_PLACEHOLDER_EXAMPLES: readonly string[] = [
+  "Implement a user authentication feature...",
+  "Fix the bug in the payment service...",
+  "Refactor this function to be more readable...",
+  "Add unit tests for the API endpoints...",
+  "Explain how this code works...",
+  "Create a React component for...",
+  "Optimize this database query...",
+  "Review this code for security issues...",
+  "Generate TypeScript types for this API...",
+  "Help me debug this error...",
+] as const;
+
+/** Default rotation interval: 5 seconds */
+const DEFAULT_INTERVAL_MS = 5000;
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook that rotates through placeholder examples.
+ *
+ * @example
+ * ```tsx
+ * const { placeholder } = usePlaceholderRotation({
+ *   interval: 5000,
+ *   enabled: inputValue.length === 0,
+ * });
+ *
+ * return <TextInput placeholder={placeholder} />;
+ * ```
+ */
+export function usePlaceholderRotation({
+  interval = DEFAULT_INTERVAL_MS,
+  enabled = true,
+  examples = DEFAULT_PLACEHOLDER_EXAMPLES,
+  staticPlaceholder = "Type a message, /command, or @mention...",
+}: UsePlaceholderRotationOptions = {}): UsePlaceholderRotationReturn {
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const intervalRef = useRef<NodeJS.Timeout | null>(null);
+
+  // Memoize examples array to prevent unnecessary effect triggers
+  const memoizedExamples = useMemo(() => examples, [examples]);
+
+  // Cleanup interval on unmount or when dependencies change
+  const clearRotationInterval = useCallback(() => {
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    }
+  }, []);
+
+  // Advance to next placeholder
+  const next = useCallback(() => {
+    setCurrentIndex((prev) => (prev + 1) % memoizedExamples.length);
+  }, [memoizedExamples.length]);
+
+  // Reset to first placeholder
+  const reset = useCallback(() => {
+    setCurrentIndex(0);
+  }, []);
+
+  // Set up rotation interval
+  useEffect(() => {
+    if (!enabled || memoizedExamples.length <= 1) {
+      clearRotationInterval();
+      return;
+    }
+
+    intervalRef.current = setInterval(() => {
+      setCurrentIndex((prev) => (prev + 1) % memoizedExamples.length);
+    }, interval);
+
+    return clearRotationInterval;
+  }, [enabled, interval, memoizedExamples.length, clearRotationInterval]);
+
+  // Get current placeholder
+  const placeholder = useMemo(() => {
+    if (!enabled || memoizedExamples.length === 0) {
+      return staticPlaceholder;
+    }
+    return memoizedExamples[currentIndex] ?? staticPlaceholder;
+  }, [enabled, memoizedExamples, currentIndex, staticPlaceholder]);
+
+  return {
+    placeholder,
+    currentIndex,
+    next,
+    reset,
+  };
+}

package/src/tui/hooks/useProviderStatus.ts

@@ -0,0 +1,270 @@
+/**
+ * useProviderStatus Hook
+ *
+ * Tracks provider status including circuit breaker states for the TUI.
+ * Provides real-time status updates for model status bar display.
+ *
+ * @module tui/hooks/useProviderStatus
+ */
+
+import { useCallback, useEffect, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Circuit breaker state following standard pattern.
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Failure threshold exceeded, requests rejected
+ * - HALF_OPEN: Testing if service has recovered
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+
+/**
+ * Individual provider status entry.
+ */
+export interface ProviderStatusEntry {
+  /** Provider identifier (e.g., 'anthropic', 'openai', 'google') */
+  readonly id: string;
+  /** Display name for the provider */
+  readonly name: string;
+  /** Current circuit breaker state */
+  readonly circuitState: CircuitState;
+  /** Whether this is the currently active provider */
+  readonly isActive: boolean;
+  /** Number of failures in current window */
+  readonly failureCount: number;
+  /** Time until circuit may reset (ms), 0 if not in OPEN state */
+  readonly timeUntilReset: number;
+  /** Last error message if any */
+  readonly lastError?: string;
+}
+
+/**
+ * Return type for useProviderStatus hook.
+ */
+export interface UseProviderStatusReturn {
+  /** Array of all tracked provider statuses */
+  readonly providers: readonly ProviderStatusEntry[];
+  /** Currently active provider ID */
+  readonly activeProviderId: string | undefined;
+  /** Set the active provider */
+  readonly setActiveProvider: (providerId: string) => void;
+  /** Update a provider's circuit state */
+  readonly updateProviderState: (
+    providerId: string,
+    state: CircuitState,
+    failureCount?: number,
+    lastError?: string
+  ) => void;
+  /** Register a new provider */
+  readonly registerProvider: (id: string, name: string) => void;
+  /** Unregister a provider */
+  readonly unregisterProvider: (id: string) => void;
+  /** Get status for a specific provider */
+  readonly getProviderStatus: (providerId: string) => ProviderStatusEntry | undefined;
+  /** Count of healthy (CLOSED state) providers */
+  readonly healthyCount: number;
+  /** Count of unhealthy (OPEN state) providers */
+  readonly unhealthyCount: number;
+  /** Count of half-open providers */
+  readonly halfOpenCount: number;
+}
+
+/**
+ * Options for useProviderStatus hook.
+ */
+export interface UseProviderStatusOptions {
+  /** Initial providers to track */
+  readonly initialProviders?: ReadonlyArray<{
+    readonly id: string;
+    readonly name: string;
+    readonly isActive?: boolean;
+  }>;
+  /** Interval to update time-until-reset values (ms) */
+  readonly updateInterval?: number;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Default update interval for time-based state changes */
+const DEFAULT_UPDATE_INTERVAL = 1000;
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+/**
+ * Hook for tracking provider status including circuit breaker states.
+ *
+ * @param options - Configuration options
+ * @returns Provider status state and actions
+ *
+ * @example
+ * ```tsx
+ * const { providers, activeProviderId, setActiveProvider } = useProviderStatus({
+ *   initialProviders: [
+ *     { id: 'anthropic', name: 'Claude', isActive: true },
+ *     { id: 'openai', name: 'GPT-4' },
+ *     { id: 'google', name: 'Gemini' },
+ *   ],
+ * });
+ * ```
+ */
+export function useProviderStatus(options: UseProviderStatusOptions = {}): UseProviderStatusReturn {
+  const { initialProviders = [], updateInterval = DEFAULT_UPDATE_INTERVAL } = options;
+
+  // State: Map of provider ID to status entry
+  const [providerMap, setProviderMap] = useState<Map<string, ProviderStatusEntry>>(() => {
+    const map = new Map<string, ProviderStatusEntry>();
+    for (const provider of initialProviders) {
+      map.set(provider.id, {
+        id: provider.id,
+        name: provider.name,
+        circuitState: "CLOSED",
+        isActive: provider.isActive ?? false,
+        failureCount: 0,
+        timeUntilReset: 0,
+      });
+    }
+    return map;
+  });
+
+  // Derived: Active provider ID
+  const activeProviderId = Array.from(providerMap.values()).find((p) => p.isActive)?.id;
+
+  // Set active provider
+  const setActiveProvider = useCallback((providerId: string) => {
+    setProviderMap((prev) => {
+      const next = new Map(prev);
+      for (const [id, entry] of next) {
+        next.set(id, {
+          ...entry,
+          isActive: id === providerId,
+        });
+      }
+      return next;
+    });
+  }, []);
+
+  // Update provider circuit state
+  const updateProviderState = useCallback(
+    (providerId: string, state: CircuitState, failureCount?: number, lastError?: string) => {
+      setProviderMap((prev) => {
+        const entry = prev.get(providerId);
+        if (!entry) return prev;
+
+        const next = new Map(prev);
+        next.set(providerId, {
+          ...entry,
+          circuitState: state,
+          failureCount: failureCount ?? entry.failureCount,
+          lastError: lastError ?? entry.lastError,
+          // Reset timeUntilReset based on state
+          timeUntilReset: state === "OPEN" ? 30000 : 0, // Default 30s reset timeout
+        });
+        return next;
+      });
+    },
+    []
+  );
+
+  // Register new provider
+  const registerProvider = useCallback((id: string, name: string) => {
+    setProviderMap((prev) => {
+      if (prev.has(id)) return prev;
+
+      const next = new Map(prev);
+      next.set(id, {
+        id,
+        name,
+        circuitState: "CLOSED",
+        isActive: next.size === 0, // First provider is active by default
+        failureCount: 0,
+        timeUntilReset: 0,
+      });
+      return next;
+    });
+  }, []);
+
+  // Unregister provider
+  const unregisterProvider = useCallback((id: string) => {
+    setProviderMap((prev) => {
+      if (!prev.has(id)) return prev;
+
+      const next = new Map(prev);
+      const wasActive = next.get(id)?.isActive;
+      next.delete(id);
+
+      // If removed provider was active, activate first remaining provider
+      if (wasActive && next.size > 0) {
+        const firstId = next.keys().next().value;
+        if (firstId !== undefined) {
+          const firstEntry = next.get(firstId);
+          if (firstEntry) {
+            next.set(firstId, { ...firstEntry, isActive: true });
+          }
+        }
+      }
+
+      return next;
+    });
+  }, []);
+
+  // Get status for specific provider
+  const getProviderStatus = useCallback(
+    (providerId: string): ProviderStatusEntry | undefined => {
+      return providerMap.get(providerId);
+    },
+    [providerMap]
+  );
+
+  // Timer to decrement timeUntilReset for OPEN circuits
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setProviderMap((prev) => {
+        let hasChanges = false;
+        const next = new Map(prev);
+
+        for (const [id, entry] of next) {
+          if (entry.circuitState === "OPEN" && entry.timeUntilReset > 0) {
+            hasChanges = true;
+            const newTime = Math.max(0, entry.timeUntilReset - updateInterval);
+            next.set(id, {
+              ...entry,
+              timeUntilReset: newTime,
+              // Auto-transition to HALF_OPEN when timer expires
+              circuitState: newTime === 0 ? "HALF_OPEN" : "OPEN",
+            });
+          }
+        }
+
+        return hasChanges ? next : prev;
+      });
+    }, updateInterval);
+
+    return () => clearInterval(timer);
+  }, [updateInterval]);
+
+  // Compute counts
+  const providers = Array.from(providerMap.values());
+  const healthyCount = providers.filter((p) => p.circuitState === "CLOSED").length;
+  const unhealthyCount = providers.filter((p) => p.circuitState === "OPEN").length;
+  const halfOpenCount = providers.filter((p) => p.circuitState === "HALF_OPEN").length;
+
+  return {
+    providers,
+    activeProviderId,
+    setActiveProvider,
+    updateProviderState,
+    registerProvider,
+    unregisterProvider,
+    getProviderStatus,
+    healthyCount,
+    unhealthyCount,
+    halfOpenCount,
+  };
+}

package/src/tui/hooks/useRateLimitStatus.ts

@@ -0,0 +1,90 @@
+/**
+ * Rate Limit Status Hook
+ *
+ * Provides rate limit status information for API providers.
+ * Placeholder implementation - to be expanded.
+ *
+ * @module tui/hooks/useRateLimitStatus
+ */
+
+import { useCallback, useEffect, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface RateLimitStatus {
+  /** Whether currently rate limited */
+  isLimited: boolean;
+  /** Remaining requests in current window */
+  remaining?: number;
+  /** Total limit for the window */
+  limit?: number;
+  /** Time until limit resets (seconds) */
+  resetIn?: number;
+  /** Provider name */
+  provider?: string;
+}
+
+export interface UseRateLimitStatusOptions {
+  /** Provider to track */
+  provider?: string;
+  /** Polling interval in ms */
+  pollInterval?: number;
+}
+
+export interface UseRateLimitStatusResult {
+  /** Current rate limit status */
+  status: RateLimitStatus;
+  /** Whether data is loading */
+  isLoading: boolean;
+  /** Any error that occurred */
+  error: Error | null;
+  /** Refresh the status */
+  refresh: () => void;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+const defaultStatus: RateLimitStatus = {
+  isLimited: false,
+};
+
+/**
+ * Hook to track rate limit status
+ */
+export function useRateLimitStatus(
+  options: UseRateLimitStatusOptions = {}
+): UseRateLimitStatusResult {
+  const { provider, pollInterval } = options;
+  const [status, setStatus] = useState<RateLimitStatus>(defaultStatus);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, _setError] = useState<Error | null>(null);
+
+  const refresh = useCallback(() => {
+    setIsLoading(true);
+    // Placeholder: In real implementation, fetch status from provider
+    setStatus({ ...defaultStatus, provider });
+    setIsLoading(false);
+  }, [provider]);
+
+  useEffect(() => {
+    refresh();
+
+    if (pollInterval && pollInterval > 0) {
+      const interval = setInterval(refresh, pollInterval);
+      return () => clearInterval(interval);
+    }
+  }, [pollInterval, refresh]);
+
+  return {
+    status,
+    isLoading,
+    error,
+    refresh,
+  };
+}
+
+export default useRateLimitStatus;