@pennyfarthing/core 11.3.7 → 11.4.0

package/packages/core/src/public/hooks/useAgentLoad.ts

@@ -0,0 +1,105 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+export interface AgentLoadComponent {
+  name: string;
+  tokens: number;
+  source?: string | null;
+}
+
+export interface AgentLoadEntry {
+  agent: string;
+  totalTokens: number | null;
+  tokenCounts?: Record<string, number>;
+  components?: AgentLoadComponent[];
+  error?: string;
+}
+
+export interface AgentLoadData {
+  agents: AgentLoadEntry[];
+  cachedAt: string;
+  totalAcrossAllAgents: number;
+}
+
+export interface PruneResult {
+  success: boolean;
+  tokensFreed?: number;
+  agent?: string;
+  file?: string;
+  error?: string;
+}
+
+export interface UseAgentLoadReturn {
+  data: AgentLoadData | null;
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => void;
+  pruneSidecar: (agent: string, file: string) => Promise<void>;
+  pruneResult: PruneResult | null;
+}
+
+export function useAgentLoad(): UseAgentLoadReturn {
+  const [data, setData] = useState<AgentLoadData | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [pruneResult, setPruneResult] = useState<PruneResult | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const refresh = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+    }
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setIsLoading(true);
+    setError(null);
+
+    fetch('/api/agent-load', { signal: controller.signal })
+      .then((res) => {
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        return res.json();
+      })
+      .then((json: AgentLoadData) => {
+        setData(json);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (err.name === 'AbortError') return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      });
+  }, []);
+
+  const pruneSidecar = useCallback(async (agent: string, file: string) => {
+    const res = await fetch('/api/agent-load/prune-sidecar', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agent, file }),
+    });
+
+    if (!res.ok) {
+      setPruneResult({ success: false, error: `HTTP ${res.status}: ${res.statusText}` });
+      return;
+    }
+
+    const result: PruneResult = await res.json();
+    setPruneResult(result);
+
+    if (result.success) {
+      refresh();
+    }
+  }, [refresh]);
+
+  useEffect(() => {
+    return () => {
+      if (abortRef.current) {
+        abortRef.current.abort();
+      }
+    };
+  }, []);
+
+  return { data, isLoading, error, refresh, pruneSidecar, pruneResult };
+}

package/packages/core/src/public/hooks/useBackgroundTasks.ts

@@ -0,0 +1,131 @@
+/**
+ * useBackgroundTasks Hook
+ *
+ * React hook for subscribing to background task notifications.
+ * Story MSSCI-12717 - React Migration
+ * Story MSSCI-12784 - Timer accuracy: fetch on mount, IPC for updates
+ * Story MSSCI-12860 - IPC to WebSocket Migration (Phase 1)
+ *
+ * Uses WebSocket /ws/background-tasks for real-time updates.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+export interface BackgroundTask {
+  taskId: string;
+  description: string;
+  subagentType: string;
+  startedAt: number;
+  completedAt?: number;
+  durationMs?: number;
+  status: 'pending' | 'completed';
+  success?: boolean;
+  output?: string;
+  error?: string;
+  isBackground?: boolean;
+}
+
+interface UseBackgroundTasksResult {
+  tasks: BackgroundTask[];
+  pendingCount: number;
+  completedCount: number;
+  clearCompleted: () => void;
+}
+
+/** WebSocket message format from /ws/background-tasks */
+interface BackgroundTaskMessage {
+  type: 'init' | 'task:started' | 'task:completed';
+  tasks?: BackgroundTask[];
+  task?: BackgroundTask;
+}
+
+export function useBackgroundTasks(): UseBackgroundTasksResult {
+  const [tasks, setTasks] = useState<BackgroundTask[]>([]);
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
+
+  useEffect(() => {
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${protocol}//${window.location.host}/ws/background-tasks`;
+
+    const connect = () => {
+      try {
+        wsRef.current = new WebSocket(wsUrl);
+
+        wsRef.current.onopen = () => {
+          console.debug('[useBackgroundTasks] WebSocket connected');
+        };
+
+        wsRef.current.onmessage = (event) => {
+          try {
+            const msg = JSON.parse(event.data) as BackgroundTaskMessage;
+
+            switch (msg.type) {
+              case 'init':
+                // Initial snapshot of all tasks
+                if (msg.tasks) {
+                  setTasks(msg.tasks);
+                }
+                break;
+
+              case 'task:started':
+                // New task started
+                if (msg.task) {
+                  setTasks(prev => {
+                    // Avoid duplicates
+                    if (prev.some(t => t.taskId === msg.task!.taskId)) {
+                      return prev;
+                    }
+                    return [...prev, msg.task!];
+                  });
+                }
+                break;
+
+              case 'task:completed':
+                // Task completed (includes accurate durationMs from backend)
+                if (msg.task) {
+                  setTasks(prev => prev.map(t =>
+                    t.taskId === msg.task!.taskId ? { ...t, ...msg.task! } : t
+                  ));
+                }
+                break;
+            }
+          } catch (err) {
+            console.error('[useBackgroundTasks] Failed to parse message:', err);
+          }
+        };
+
+        wsRef.current.onclose = () => {
+          console.debug('[useBackgroundTasks] WebSocket closed, reconnecting...');
+          reconnectTimeoutRef.current = setTimeout(connect, 2000);
+        };
+
+        wsRef.current.onerror = (err) => {
+          console.error('[useBackgroundTasks] WebSocket error:', err);
+        };
+      } catch (err) {
+        console.error('[useBackgroundTasks] WebSocket init failed:', err);
+      }
+    };
+
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+    };
+  }, []);
+
+  const clearCompleted = useCallback(() => {
+    setTasks(prev => prev.filter(t => t.status === 'pending'));
+  }, []);
+
+  const pendingCount = tasks.filter(t => t.status === 'pending').length;
+  const completedCount = tasks.filter(t => t.status === 'completed').length;
+
+  return { tasks, pendingCount, completedCount, clearCompleted };
+}

package/packages/core/src/public/hooks/useClaude.ts

@@ -0,0 +1,234 @@
+/**
+ * useClaude Hook
+ *
+ * WebSocket-based hook for Claude API communication.
+ * Part of IPC-to-WebSocket migration (Phase 1).
+ *
+ * Replaces window.electronAPI.claude with unified WebSocket communication.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type PermissionMode = 'default' | 'plan' | 'acceptEdits' | 'dangerouslySkipPermissions';
+
+export interface PastedImage {
+  dataUrl: string;
+  mimeType: string;
+  filename: string;
+}
+
+export interface ClaudeMessage {
+  type: string;
+  message?: unknown;
+  content?: string | Array<{ type: string; text?: string }>;
+  tool_name?: string;
+  tool_id?: string;
+  input?: Record<string, unknown>;
+  output?: string;
+  is_error?: boolean;
+  parent_tool_use_id?: string | null;
+  subagent_type?: string;
+  subagent_name?: string;
+}
+
+interface WebSocketClaudeMessage {
+  type: 'message' | 'complete' | 'error' | 'init' | 'mode';
+  message?: ClaudeMessage;
+  error?: string;
+  mode?: PermissionMode;
+}
+
+export interface UseClaudeResult {
+  /** Send a message to Claude */
+  send: (prompt: string, images?: PastedImage[]) => void;
+  /** Abort the current query */
+  abort: () => void;
+  /** Clear the session */
+  clear: () => void;
+  /** Set permission mode */
+  setMode: (mode: PermissionMode) => void;
+  /** Whether WebSocket is connected */
+  isConnected: boolean;
+  /** Current permission mode */
+  mode: PermissionMode;
+}
+
+export interface UseClaudeCallbacks {
+  onMessage?: (message: ClaudeMessage) => void;
+  onComplete?: () => void;
+  onError?: (error: string) => void;
+}
+
+// =============================================================================
+// Hook Implementation
+// =============================================================================
+
+export function useClaude(callbacks?: UseClaudeCallbacks): UseClaudeResult {
+  const [isConnected, setIsConnected] = useState(false);
+  const [mode, setModeState] = useState<PermissionMode>('default');
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
+  const callbacksRef = useRef(callbacks);
+
+  // Keep callbacks ref updated
+  useEffect(() => {
+    callbacksRef.current = callbacks;
+  }, [callbacks]);
+
+  // Connect to WebSocket
+  const connect = useCallback(() => {
+    // Build WebSocket URL
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const host = window.location.host;
+    const wsUrl = `${protocol}//${host}/ws/claude`;
+
+    console.log('[useClaude] Connecting to', wsUrl);
+
+    const ws = new WebSocket(wsUrl);
+    wsRef.current = ws;
+
+    ws.onopen = () => {
+      console.log('[useClaude] Connected');
+      setIsConnected(true);
+      // Request current mode from server
+      ws.send(JSON.stringify({ type: 'getMode' }));
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data) as WebSocketClaudeMessage;
+
+        switch (data.type) {
+          case 'message':
+            if (data.message && callbacksRef.current?.onMessage) {
+              callbacksRef.current.onMessage(data.message);
+            }
+            break;
+
+          case 'complete':
+            if (callbacksRef.current?.onComplete) {
+              callbacksRef.current.onComplete();
+            }
+            break;
+
+          case 'error':
+            if (data.error && callbacksRef.current?.onError) {
+              callbacksRef.current.onError(data.error);
+            }
+            break;
+
+          case 'init':
+            // Initial connection acknowledgment
+            console.log('[useClaude] Init received');
+            break;
+
+          case 'mode':
+            // Server responded with current permission mode
+            if (data.mode) {
+              console.log('[useClaude] Mode received:', data.mode);
+              setModeState(data.mode);
+            }
+            break;
+        }
+      } catch (err) {
+        console.error('[useClaude] Failed to parse message:', err);
+      }
+    };
+
+    ws.onclose = () => {
+      console.log('[useClaude] Disconnected');
+      setIsConnected(false);
+      wsRef.current = null;
+
+      // Attempt reconnection after delay
+      reconnectTimeoutRef.current = setTimeout(() => {
+        console.log('[useClaude] Attempting reconnect...');
+        connect();
+      }, 2000);
+    };
+
+    ws.onerror = (error) => {
+      console.error('[useClaude] WebSocket error:', error);
+    };
+  }, []);
+
+  // Initialize connection
+  useEffect(() => {
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+        wsRef.current = null;
+      }
+    };
+  }, [connect]);
+
+  // Send message
+  const send = useCallback((prompt: string, images?: PastedImage[]) => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+      console.error('[useClaude] Cannot send: not connected');
+      callbacksRef.current?.onError?.('Not connected to Claude service');
+      return;
+    }
+
+    if (images && images.length > 0) {
+      console.log(`[useClaude] Sending ${images.length} image(s) with prompt`);
+    }
+
+    wsRef.current.send(JSON.stringify({
+      type: 'send',
+      prompt,
+      images: images || [],
+    }));
+  }, []);
+
+  // Abort query
+  const abort = useCallback(() => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+      console.warn('[useClaude] Cannot abort: not connected');
+      return;
+    }
+
+    wsRef.current.send(JSON.stringify({ type: 'abort' }));
+  }, []);
+
+  // Clear session
+  const clear = useCallback(() => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+      console.warn('[useClaude] Cannot clear: not connected');
+      return;
+    }
+
+    wsRef.current.send(JSON.stringify({ type: 'clear' }));
+  }, []);
+
+  // Set permission mode
+  const setMode = useCallback((newMode: PermissionMode) => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+      console.warn('[useClaude] Cannot set mode: not connected');
+      return;
+    }
+
+    wsRef.current.send(JSON.stringify({ type: 'setMode', mode: newMode }));
+    setModeState(newMode);
+  }, []);
+
+  return {
+    send,
+    abort,
+    clear,
+    setMode,
+    isConnected,
+    mode,
+  };
+}
+
+export default useClaude;

package/packages/core/src/public/hooks/useCodeMarkers.ts

@@ -0,0 +1,101 @@
+/**
+ * useCodeMarkers React hook — Story 80-3 (MSSCI-14456)
+ *
+ * Wraps /api/code-markers endpoint with AbortController,
+ * loading/error/data state management, and manual refresh.
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+
+export interface CodeMarker {
+  path: string;
+  line: number;
+  marker_type: string;
+  text: string;
+  author: string;
+  date: string;
+  age_days: number;
+  is_stale: boolean;
+}
+
+export interface MarkerSummary {
+  total_markers: number;
+  stale_markers: number;
+  by_type: Record<string, number>;
+}
+
+export interface CodeMarkersData {
+  success: boolean;
+  repo_name: string;
+  repo_path: string;
+  stale_threshold_days: number;
+  markers: CodeMarker[];
+  summary: MarkerSummary;
+  error: string | null;
+}
+
+export interface UseCodeMarkersOptions {
+  days: number;
+  repo?: string;
+  type?: 'all' | 'stale' | 'deprecated';
+}
+
+export interface UseCodeMarkersReturn {
+  data: CodeMarkersData | null;
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => void;
+}
+
+export function useCodeMarkers(options: UseCodeMarkersOptions): UseCodeMarkersReturn {
+  const [data, setData] = useState<CodeMarkersData | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const fetchCodeMarkers = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+    }
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setIsLoading(true);
+    setError(null);
+
+    const params = new URLSearchParams({ days: String(options.days) });
+    if (options.repo) {
+      params.set('repo', options.repo);
+    }
+    if (options.type) {
+      params.set('type', options.type);
+    }
+
+    fetch(`/api/code-markers?${params}`, { signal: controller.signal })
+      .then((res) => {
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        return res.json();
+      })
+      .then((json: CodeMarkersData) => {
+        setData(json);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (err.name === 'AbortError') return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      });
+  }, [options.days, options.repo, options.type]);
+
+  useEffect(() => {
+    return () => {
+      if (abortRef.current) {
+        abortRef.current.abort();
+      }
+    };
+  }, []);
+
+  return { data, isLoading, error, refresh: fetchCodeMarkers };
+}

package/packages/core/src/public/hooks/useColorScheme.ts

@@ -0,0 +1,42 @@
+/**
+ * useColorScheme Hook
+ *
+ * Tracks the active color scheme (light/dark) from the applied color preset's
+ * data-variant attribute on the document root. Falls back to OS preference.
+ */
+
+import { useState, useEffect } from 'react';
+
+export type ColorScheme = 'light' | 'dark';
+
+function getVariant(): ColorScheme {
+  const variant = document.documentElement.getAttribute('data-variant');
+  if (variant === 'light' || variant === 'dark') return variant;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+export function useColorScheme(): ColorScheme {
+  const [scheme, setScheme] = useState<ColorScheme>(getVariant);
+
+  useEffect(() => {
+    // Watch for preset changes via data-variant attribute
+    const observer = new MutationObserver(() => {
+      setScheme(getVariant());
+    });
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-variant'],
+    });
+
+    // Also listen to presetChange events from applyPreset()
+    const handlePreset = () => setScheme(getVariant());
+    window.addEventListener('presetChange', handlePreset);
+
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('presetChange', handlePreset);
+    };
+  }, []);
+
+  return scheme;
+}

package/packages/core/src/public/hooks/useCommandHistory.ts

@@ -0,0 +1,99 @@
+/**
+ * useCommandHistory Hook
+ *
+ * React hook for command history navigation (Up/Down arrows).
+ * Story MSSCI-12717 - React Migration
+ */
+
+import { useState, useCallback, useRef } from 'react';
+
+const HISTORY_KEY = 'cyclist-command-history';
+const MAX_HISTORY = 100;
+
+interface UseCommandHistoryResult {
+  addToHistory: (command: string) => void;
+  navigateUp: (currentContent: string) => string | null;
+  navigateDown: () => string | null;
+  resetNavigation: () => void;
+}
+
+export function useCommandHistory(): UseCommandHistoryResult {
+  const [history, setHistory] = useState<string[]>(() => {
+    try {
+      const stored = localStorage.getItem(HISTORY_KEY);
+      return stored ? JSON.parse(stored) : [];
+    } catch {
+      return [];
+    }
+  });
+
+  const historyIndexRef = useRef(-1);
+  const savedInputRef = useRef('');
+
+  const saveHistory = useCallback((newHistory: string[]) => {
+    try {
+      localStorage.setItem(HISTORY_KEY, JSON.stringify(newHistory));
+    } catch {
+      // Ignore localStorage errors
+    }
+  }, []);
+
+  const addToHistory = useCallback((command: string) => {
+    if (!command.trim()) return;
+
+    setHistory(prev => {
+      // Don't add duplicate of last command
+      if (prev.length > 0 && prev[prev.length - 1] === command) {
+        return prev;
+      }
+
+      const newHistory = [...prev, command];
+      // Trim to max size
+      if (newHistory.length > MAX_HISTORY) {
+        newHistory.shift();
+      }
+      saveHistory(newHistory);
+      return newHistory;
+    });
+  }, [saveHistory]);
+
+  const navigateUp = useCallback((currentContent: string): string | null => {
+    if (history.length === 0) return null;
+
+    // First time pressing up: save current input and start at end
+    if (historyIndexRef.current === -1) {
+      savedInputRef.current = currentContent;
+      historyIndexRef.current = history.length - 1;
+    } else if (historyIndexRef.current > 0) {
+      historyIndexRef.current--;
+    } else {
+      // Already at oldest command
+      return null;
+    }
+
+    return history[historyIndexRef.current];
+  }, [history]);
+
+  const navigateDown = useCallback((): string | null => {
+    if (historyIndexRef.current === -1) return null;
+
+    historyIndexRef.current++;
+
+    if (historyIndexRef.current >= history.length) {
+      // Back to current input
+      historyIndexRef.current = -1;
+      const saved = savedInputRef.current;
+      savedInputRef.current = '';
+      return saved;
+    }
+
+    return history[historyIndexRef.current];
+  }, [history]);
+
+  const resetNavigation = useCallback(() => {
+    historyIndexRef.current = -1;
+    savedInputRef.current = '';
+  }, []);
+
+  return { addToHistory, navigateUp, navigateDown, resetNavigation };
+}