@pennyfarthing/core 11.3.8 → 11.5.0-alpha.0

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

@@ -0,0 +1,165 @@
+/**
+ * useTandemObservations Hook
+ *
+ * React hook for subscribing to tandem observation data.
+ * Story 86-11: Cyclist: Tandem dialogue panel
+ *
+ * Uses WebSocket /ws/tandem for real-time updates.
+ * Parses .session/{story}-tandem-{partner}.md observation files.
+ */
+
+import { useState, useEffect, useRef } from 'react';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TandemTrigger {
+  scope: string;   // file-watch, tool-watch, context-watch
+  detail: string;  // specific trigger detail
+}
+
+export interface TandemObservation {
+  timestamp: string;  // ISO timestamp
+  time: string;       // HH:MM from section header
+  trigger: TandemTrigger;
+  content: string;    // observation text
+  outcome?: 'applied' | 'deferred' | 'rejected';
+  confidence?: number; // 0-1
+}
+
+export interface TandemHeader {
+  storyId: string;
+  observer: string;    // agent role (e.g., "architect")
+  character: string;   // persona character name (e.g., "The Man in Black")
+  phase: string;       // workflow phase
+  startedAt: string;   // ISO timestamp
+  theme?: string;      // theme slug for portrait resolution
+  slug?: string;       // character slug for portrait image
+}
+
+export interface TandemMetrics {
+  exchangeCount: number;
+  tokenOverhead: number; // percentage
+  confidenceDistribution: {
+    high: number;
+    medium: number;
+    low: number;
+  };
+  outcomeBreakdown: {
+    applied: number;
+    deferred: number;
+    rejected: number;
+  };
+}
+
+export interface UseTandemObservationsResult {
+  header: TandemHeader | null;
+  observations: TandemObservation[];
+  metrics: TandemMetrics | null;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+/** WebSocket message format from /ws/tandem */
+export interface TandemMessage {
+  type: 'init' | 'observation' | 'metrics' | 'clear';
+  header?: TandemHeader;
+  observations?: TandemObservation[];
+  observation?: TandemObservation;
+  metrics?: TandemMetrics;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useTandemObservations(): UseTandemObservationsResult {
+  const [header, setHeader] = useState<TandemHeader | null>(null);
+  const [observations, setObservations] = useState<TandemObservation[]>([]);
+  const [metrics, setMetrics] = useState<TandemMetrics | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  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/tandem`;
+
+    const connect = () => {
+      try {
+        wsRef.current = new WebSocket(wsUrl);
+
+        wsRef.current.onopen = () => {
+          console.debug('[useTandemObservations] WebSocket connected');
+        };
+
+        wsRef.current.onmessage = (event) => {
+          try {
+            const msg = JSON.parse(event.data) as TandemMessage;
+
+            switch (msg.type) {
+              case 'init':
+                setHeader(msg.header ?? null);
+                setObservations(msg.observations ?? []);
+                setIsLoading(false);
+                setError(null);
+                break;
+
+              case 'observation':
+                if (msg.observation) {
+                  setObservations(prev => {
+                    const next = [...prev, msg.observation!];
+                    return next.length > 200 ? next.slice(-200) : next;
+                  });
+                }
+                break;
+
+              case 'metrics':
+                if (msg.metrics) {
+                  setMetrics(msg.metrics);
+                }
+                break;
+
+              case 'clear':
+                setHeader(null);
+                setObservations([]);
+                setMetrics(null);
+                break;
+            }
+          } catch (err) {
+            console.error('[useTandemObservations] Failed to parse message:', err);
+          }
+        };
+
+        wsRef.current.onclose = () => {
+          console.debug('[useTandemObservations] WebSocket closed, reconnecting...');
+          reconnectTimeoutRef.current = setTimeout(connect, 2000);
+        };
+
+        wsRef.current.onerror = (err) => {
+          console.error('[useTandemObservations] WebSocket error:', err);
+          setError(new Error('WebSocket connection failed'));
+        };
+      } catch (err) {
+        console.error('[useTandemObservations] WebSocket init failed:', err);
+        setError(err instanceof Error ? err : new Error('Failed to connect'));
+        setIsLoading(false);
+      }
+    };
+
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+    };
+  }, []);
+
+  return { header, observations, metrics, isLoading, error };
+}

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

@@ -0,0 +1,273 @@
+/**
+ * useTeamMembers Hook
+ *
+ * React hook for subscribing to native team state.
+ * Story 86-12: Cyclist: Native team panel
+ *
+ * Uses WebSocket channels:
+ * - /ws/team — team lifecycle events (init, member_update, disbanded)
+ * - /ws/tasks — task list changes (init, task_updated)
+ * - /ws/messages — inter-agent messages (init, message)
+ */
+
+import { useState, useLayoutEffect, useRef, useCallback } from 'react';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TeamMember {
+  name: string;
+  agentType: string;
+  status: 'idle' | 'working' | 'blocked';
+  portrait?: { theme: string; slug: string };
+  currentTask?: string;
+  taskProgress?: number;
+}
+
+export interface TaskListItem {
+  id: string;
+  title: string;
+  owner?: string;
+  status: 'pending' | 'in_progress' | 'completed';
+  blockedBy?: string[];
+}
+
+export interface TeamMessage {
+  from: string;
+  to?: string;
+  content: string;
+  timestamp: string;
+  type: 'message' | 'broadcast' | 'shutdown_request' | 'shutdown_response';
+}
+
+export interface TeamState {
+  isActive: boolean;
+  teamName?: string;
+  members: TeamMember[];
+  tasks: TaskListItem[];
+  messages: TeamMessage[];
+  isLoading: boolean;
+  error: Error | null;
+}
+
+interface TeamInitMessage {
+  type: 'init';
+  team: {
+    id: string;
+    lead: string;
+    created: string;
+    name?: string;
+    members: TeamMember[];
+  };
+}
+
+interface MemberUpdateMessage {
+  type: 'member_update';
+  member: TeamMember;
+}
+
+interface DisbandedMessage {
+  type: 'disbanded';
+}
+
+type TeamWsMessage = TeamInitMessage | MemberUpdateMessage | DisbandedMessage;
+
+interface TasksInitMessage {
+  type: 'init';
+  tasks: TaskListItem[];
+}
+
+interface TaskUpdatedMessage {
+  type: 'task_updated';
+  task: TaskListItem;
+}
+
+type TasksWsMessage = TasksInitMessage | TaskUpdatedMessage;
+
+interface MessagesInitMessage {
+  type: 'init';
+  messages: TeamMessage[];
+}
+
+interface NewMessageMessage {
+  type: 'message';
+  msg: Partial<TeamMessage> & { from: string; content: string; timestamp: string };
+}
+
+type MessagesWsMessage = MessagesInitMessage | NewMessageMessage;
+
+// =============================================================================
+// WebSocket URL helper
+// =============================================================================
+
+function wsUrl(path: string): string {
+  const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${protocol}//${window.location.host}${path}`;
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useTeamMembers(): TeamState {
+  const [isActive, setIsActive] = useState(false);
+  const [teamName, setTeamName] = useState<string | undefined>(undefined);
+  const [members, setMembers] = useState<TeamMember[]>([]);
+  const [tasks, setTasks] = useState<TaskListItem[]>([]);
+  const [messages, setMessages] = useState<TeamMessage[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const teamWsRef = useRef<WebSocket | null>(null);
+  const tasksWsRef = useRef<WebSocket | null>(null);
+  const messagesWsRef = useRef<WebSocket | null>(null);
+  const reconnectTimersRef = useRef<ReturnType<typeof setTimeout>[]>([]);
+  const mountedRef = useRef(true);
+
+  // Create initial WebSocket connections synchronously during first render.
+  // This ensures the WebSocket objects exist immediately (before any effects),
+  // which is critical for tests using vi.useFakeTimers() where effect scheduling
+  // depends on timer availability.
+  const initializedRef = useRef(false);
+  if (!initializedRef.current) {
+    initializedRef.current = true;
+    teamWsRef.current = new WebSocket(wsUrl('/ws/team'));
+    tasksWsRef.current = new WebSocket(wsUrl('/ws/tasks'));
+    messagesWsRef.current = new WebSocket(wsUrl('/ws/messages'));
+  }
+
+  // Reconnection helper — creates new WebSocket and wires handlers
+  const connectTeam = useCallback(() => {
+    const ws = new WebSocket(wsUrl('/ws/team'));
+    teamWsRef.current = ws;
+    wireTeamHandlers(ws);
+  }, []);
+
+  function wireTeamHandlers(ws: WebSocket) {
+    ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data) as TeamWsMessage;
+        switch (msg.type) {
+          case 'init':
+            setMembers(msg.team.members);
+            setTeamName(msg.team.name);
+            setIsActive(true);
+            setIsLoading(false);
+            setError(null);
+            break;
+          case 'member_update':
+            setMembers(prev => prev.map(m =>
+              m.name === msg.member.name ? { ...m, ...msg.member } : m
+            ));
+            break;
+          case 'disbanded':
+            setMembers([]);
+            setTeamName(undefined);
+            setIsActive(false);
+            break;
+        }
+      } catch {
+        // ignore parse errors
+      }
+    };
+
+    ws.onerror = () => {
+      setError(new Error('WebSocket connection failed'));
+      setIsLoading(false);
+    };
+
+    ws.onclose = () => {
+      if (mountedRef.current) {
+        const timer = setTimeout(connectTeam, 2000);
+        reconnectTimersRef.current.push(timer);
+      }
+    };
+  }
+
+  function wireTasksHandlers(ws: WebSocket) {
+    ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data) as TasksWsMessage;
+        switch (msg.type) {
+          case 'init':
+            setTasks(msg.tasks);
+            break;
+          case 'task_updated':
+            setTasks(prev => prev.map(t =>
+              t.id === msg.task.id ? { ...t, ...msg.task } : t
+            ));
+            break;
+        }
+      } catch {
+        // ignore parse errors
+      }
+    };
+
+    ws.onclose = () => {
+      if (mountedRef.current) {
+        const timer = setTimeout(() => {
+          const newWs = new WebSocket(wsUrl('/ws/tasks'));
+          tasksWsRef.current = newWs;
+          wireTasksHandlers(newWs);
+        }, 2000);
+        reconnectTimersRef.current.push(timer);
+      }
+    };
+  }
+
+  function wireMessagesHandlers(ws: WebSocket) {
+    ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data) as MessagesWsMessage;
+        switch (msg.type) {
+          case 'init':
+            setMessages(msg.messages);
+            break;
+          case 'message':
+            setMessages(prev => [...prev, {
+              from: msg.msg.from,
+              to: msg.msg.to,
+              content: msg.msg.content,
+              timestamp: msg.msg.timestamp,
+              type: msg.msg.type ?? 'message',
+            }]);
+            break;
+        }
+      } catch {
+        // ignore parse errors
+      }
+    };
+
+    ws.onclose = () => {
+      if (mountedRef.current) {
+        const timer = setTimeout(() => {
+          const newWs = new WebSocket(wsUrl('/ws/messages'));
+          messagesWsRef.current = newWs;
+          wireMessagesHandlers(newWs);
+        }, 2000);
+        reconnectTimersRef.current.push(timer);
+      }
+    };
+  }
+
+  // Wire up handlers in layout effect (synchronous, fires during commit)
+  useLayoutEffect(() => {
+    mountedRef.current = true;
+
+    wireTeamHandlers(teamWsRef.current!);
+    wireTasksHandlers(tasksWsRef.current!);
+    wireMessagesHandlers(messagesWsRef.current!);
+
+    return () => {
+      mountedRef.current = false;
+      reconnectTimersRef.current.forEach(t => clearTimeout(t));
+      reconnectTimersRef.current = [];
+      teamWsRef.current?.close();
+      tasksWsRef.current?.close();
+      messagesWsRef.current?.close();
+    };
+  }, []);
+
+  return { isActive, teamName, members, tasks, messages, isLoading, error };
+}

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

@@ -0,0 +1,93 @@
+/**
+ * useTodos Hook
+ *
+ * React hook for subscribing to todo list data.
+ * Uses WebSocket /ws/todos for real-time updates (no polling).
+ * Story MSSCI-12717 - React Migration
+ */
+
+import { useState, useEffect, useRef } from 'react';
+
+export interface TodoItem {
+  id: string;
+  content: string;
+  activeForm: string;
+  status: 'pending' | 'in_progress' | 'completed';
+  blockedBy?: string[];
+  blocks?: string[];
+}
+
+interface UseTodosResult {
+  todos: TodoItem[];
+  isLoading: boolean;
+  error: Error | null;
+}
+
+/** WebSocket message format from /ws/todos */
+interface TodosMessage {
+  type: 'init' | 'update';
+  todos: TodoItem[];
+}
+
+export function useTodos(): UseTodosResult {
+  const [todos, setTodos] = useState<TodoItem[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  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/todos`;
+
+    const connect = () => {
+      try {
+        wsRef.current = new WebSocket(wsUrl);
+
+        wsRef.current.onopen = () => {
+          console.debug('[useTodos] WebSocket connected');
+        };
+
+        wsRef.current.onmessage = (event) => {
+          try {
+            const msg = JSON.parse(event.data) as TodosMessage;
+            if (msg.type === 'init' || msg.type === 'update') {
+              setTodos(msg.todos || []);
+              setIsLoading(false);
+              setError(null);
+            }
+          } catch (err) {
+            console.error('[useTodos] Failed to parse message:', err);
+          }
+        };
+
+        wsRef.current.onclose = () => {
+          console.debug('[useTodos] WebSocket closed, reconnecting...');
+          reconnectTimeoutRef.current = setTimeout(connect, 2000);
+        };
+
+        wsRef.current.onerror = (err) => {
+          console.error('[useTodos] WebSocket error:', err);
+          setError(new Error('WebSocket connection failed'));
+        };
+      } catch (err) {
+        console.error('[useTodos] WebSocket init failed:', err);
+        setError(err instanceof Error ? err : new Error('Failed to connect'));
+        setIsLoading(false);
+      }
+    };
+
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+    };
+  }, []);
+
+  return { todos, isLoading, error };
+}

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

@@ -0,0 +1,54 @@
+/**
+ * useUserAvatar Hook
+ *
+ * React hook for fetching and managing user avatar state.
+ * Story MSSCI-12777 - User Avatar from GitHub/Gravatar
+ *
+ * Uses avatar-service for fetching with fallback chain:
+ * GitHub → Gravatar → Default silhouette
+ */
+
+import { useState, useEffect } from 'react';
+import { DEFAULT_AVATAR } from '../utils/avatar-service';
+
+export { DEFAULT_AVATAR };
+
+export interface UseUserAvatarResult {
+  avatarUrl: string | null;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+export function useUserAvatar(): UseUserAvatarResult {
+  const [avatarUrl, setAvatarUrl] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    const fetchAvatar = async () => {
+      try {
+        // Try REST endpoint for avatar
+        const response = await fetch('/api/identity');
+        if (response.ok) {
+          const data = await response.json();
+          if (data.avatarUrl) {
+            setAvatarUrl(data.avatarUrl);
+          } else {
+            setAvatarUrl(DEFAULT_AVATAR);
+          }
+        } else {
+          setAvatarUrl(DEFAULT_AVATAR);
+        }
+        setIsLoading(false);
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error('Failed to fetch avatar'));
+        setAvatarUrl(DEFAULT_AVATAR);
+        setIsLoading(false);
+      }
+    };
+
+    fetchAvatar();
+  }, []);
+
+  return { avatarUrl, isLoading, error };
+}

package/packages/core/src/public/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Cyclist - Claude Code Dashboard</title>
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🚴</text></svg>">
+  <link rel="stylesheet" href="/css/react.css">
+</head>
+<body>
+  <div id="react-root"></div>
+  <script type="module" src="/js/react/react.js"></script>
+</body>
+</html>

package/packages/core/src/public/index.tsx

@@ -0,0 +1,10 @@
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import './styles/tailwind.css';
+import './css/theme-system.css';
+
+// React entry point for Cyclist
+const container = document.getElementById('react-root');
+if (container) {
+  createRoot(container).render(<App />);
+}

package/packages/core/src/public/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}