@agile-vibe-coding/avc 0.1.0 → 0.2.3

package/kanban/client/src/hooks/__tests__/useGrouping.test.js

@@ -0,0 +1,232 @@
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useGrouping } from '../useGrouping';
+
+describe('useGrouping', () => {
+  const mockWorkItems = [
+    {
+      id: 'EPIC-001',
+      type: 'epic',
+      name: 'Epic 1',
+      status: 'implementing',
+      epicId: 'EPIC-001',
+      epicName: 'Epic 1',
+    },
+    {
+      id: 'STORY-001',
+      type: 'story',
+      name: 'Story 1',
+      status: 'ready',
+      epicId: 'EPIC-001',
+      epicName: 'Epic 1',
+    },
+    {
+      id: 'EPIC-002',
+      type: 'epic',
+      name: 'Epic 2',
+      status: 'planned',
+      epicId: 'EPIC-002',
+      epicName: 'Epic 2',
+    },
+    {
+      id: 'STORY-002',
+      type: 'story',
+      name: 'Story 2',
+      status: 'planned',
+      epicId: 'EPIC-002',
+      epicName: 'Epic 2',
+    },
+    {
+      id: 'TASK-001',
+      type: 'task',
+      name: 'Task 1',
+      status: 'completed',
+      epicId: null,
+      epicName: null,
+    },
+  ];
+
+  describe('groupBy: status', () => {
+    it('should group by status columns', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'status'));
+
+      expect(result.current.mode).toBe('columns');
+      expect(result.current.groups).toHaveLength(5); // 5 columns
+
+      const columnNames = result.current.groups.map((g) => g.name);
+      expect(columnNames).toEqual(['Backlog', 'Ready', 'In Progress', 'Review', 'Done']);
+    });
+
+    it('should distribute items to correct columns', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'status'));
+
+      const backlog = result.current.groups.find((g) => g.name === 'Backlog');
+      const ready = result.current.groups.find((g) => g.name === 'Ready');
+      const inProgress = result.current.groups.find((g) => g.name === 'In Progress');
+      const done = result.current.groups.find((g) => g.name === 'Done');
+
+      expect(backlog.items).toHaveLength(2); // EPIC-002, STORY-002 (planned)
+      expect(ready.items).toHaveLength(1); // STORY-001 (ready)
+      expect(inProgress.items).toHaveLength(1); // EPIC-001 (implementing)
+      expect(done.items).toHaveLength(1); // TASK-001 (completed)
+    });
+
+    it('should have column structure with id and name', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'status'));
+
+      result.current.groups.forEach((group) => {
+        expect(group).toHaveProperty('id');
+        expect(group).toHaveProperty('name');
+        expect(group).toHaveProperty('items');
+        expect(Array.isArray(group.items)).toBe(true);
+      });
+    });
+  });
+
+  describe('groupBy: epic', () => {
+    it('should group by epic with sections mode', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'epic'));
+
+      expect(result.current.mode).toBe('sections');
+      expect(result.current.groups.length).toBeGreaterThan(0);
+    });
+
+    it('should create section for each epic', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'epic'));
+
+      const epicNames = result.current.groups.map((g) => g.name);
+      expect(epicNames).toContain('Epic 1');
+      expect(epicNames).toContain('Epic 2');
+    });
+
+    it('should group items without epic into "No Epic" section', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'epic'));
+
+      const noEpicGroup = result.current.groups.find((g) => g.type === 'ungrouped');
+      expect(noEpicGroup).toBeDefined();
+      expect(noEpicGroup.items).toHaveLength(1); // TASK-001
+    });
+
+    it('should include epic object in group', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'epic'));
+
+      const epic1Group = result.current.groups.find((g) => g.name === 'Epic 1');
+      expect(epic1Group.epic).toBeDefined();
+      expect(epic1Group.epic.id).toBe('EPIC-001');
+    });
+
+    it('should distribute items into columns within each epic', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'epic'));
+
+      const epic1Group = result.current.groups.find((g) => g.name === 'Epic 1');
+      expect(epic1Group.columns).toBeDefined();
+      expect(epic1Group.columns.Ready).toHaveLength(1); // STORY-001
+      expect(epic1Group.columns['In Progress']).toHaveLength(1); // EPIC-001
+    });
+  });
+
+  describe('groupBy: type', () => {
+    it('should group by type with sections mode', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'type'));
+
+      expect(result.current.mode).toBe('sections');
+    });
+
+    it('should create section for each type', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'type'));
+
+      const typeNames = result.current.groups.map((g) => g.name);
+      expect(typeNames).toContain('Epics');
+      expect(typeNames).toContain('Stories');
+      expect(typeNames).toContain('Tasks');
+    });
+
+    it('should distribute items into correct type sections', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'type'));
+
+      const epicsGroup = result.current.groups.find((g) => g.name === 'Epics');
+      const storiesGroup = result.current.groups.find((g) => g.name === 'Stories');
+      const tasksGroup = result.current.groups.find((g) => g.name === 'Tasks');
+
+      expect(epicsGroup.items).toHaveLength(2); // EPIC-001, EPIC-002
+      expect(storiesGroup.items).toHaveLength(2); // STORY-001, STORY-002
+      expect(tasksGroup.items).toHaveLength(1); // TASK-001
+    });
+
+    it('should distribute items into columns within each type', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'type'));
+
+      const epicsGroup = result.current.groups.find((g) => g.name === 'Epics');
+      expect(epicsGroup.columns).toBeDefined();
+      expect(epicsGroup.columns.Backlog).toHaveLength(1); // EPIC-002 (planned)
+      expect(epicsGroup.columns['In Progress']).toHaveLength(1); // EPIC-001 (implementing)
+
+      const storiesGroup = result.current.groups.find((g) => g.name === 'Stories');
+      expect(storiesGroup.columns).toBeDefined();
+      expect(storiesGroup.columns.Backlog).toHaveLength(1); // STORY-002 (planned)
+      expect(storiesGroup.columns.Ready).toHaveLength(1); // STORY-001 (ready)
+    });
+  });
+
+  describe('memoization', () => {
+    it('should return same reference when inputs unchanged', () => {
+      const { result, rerender } = renderHook(
+        ({ items, groupBy }) => useGrouping(items, groupBy),
+        { initialProps: { items: mockWorkItems, groupBy: 'status' } }
+      );
+
+      const firstResult = result.current;
+      rerender({ items: mockWorkItems, groupBy: 'status' });
+      const secondResult = result.current;
+
+      expect(firstResult).toBe(secondResult);
+    });
+
+    it('should recalculate when groupBy changes', () => {
+      const { result, rerender } = renderHook(
+        ({ items, groupBy }) => useGrouping(items, groupBy),
+        { initialProps: { items: mockWorkItems, groupBy: 'status' } }
+      );
+
+      const statusResult = result.current;
+      rerender({ items: mockWorkItems, groupBy: 'epic' });
+      const epicResult = result.current;
+
+      expect(statusResult).not.toBe(epicResult);
+      expect(statusResult.mode).toBe('columns');
+      expect(epicResult.mode).toBe('sections');
+    });
+
+    it('should recalculate when items change', () => {
+      const { result, rerender } = renderHook(
+        ({ items, groupBy }) => useGrouping(items, groupBy),
+        { initialProps: { items: mockWorkItems, groupBy: 'status' } }
+      );
+
+      const firstResult = result.current;
+      const newItems = [...mockWorkItems, { id: 'NEW-001', status: 'ready' }];
+      rerender({ items: newItems, groupBy: 'status' });
+      const secondResult = result.current;
+
+      expect(firstResult).not.toBe(secondResult);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty work items array', () => {
+      const { result } = renderHook(() => useGrouping([], 'status'));
+
+      expect(result.current.groups).toHaveLength(5);
+      result.current.groups.forEach((group) => {
+        expect(group.items).toEqual([]);
+      });
+    });
+
+    it('should handle unknown groupBy value by defaulting to status', () => {
+      const { result } = renderHook(() => useGrouping(mockWorkItems, 'unknown'));
+
+      expect(result.current.mode).toBe('columns');
+      expect(result.current.groups).toHaveLength(5);
+    });
+  });
+});

package/kanban/client/src/hooks/useGrouping.js

@@ -0,0 +1,118 @@
+import { useMemo } from 'react';
+import { groupItemsByColumn, COLUMN_ORDER } from '../lib/status-grouping';
+
+/**
+ * Grouping Hook
+ * Handles different grouping strategies for work items
+ */
+export function useGrouping(workItems, groupBy) {
+  return useMemo(() => {
+    switch (groupBy) {
+      case 'status':
+        return groupByStatus(workItems);
+      case 'epic':
+        return groupByEpic(workItems);
+      case 'type':
+        return groupByType(workItems);
+      default:
+        return groupByStatus(workItems);
+    }
+  }, [workItems, groupBy]);
+}
+
+/**
+ * Group by status (default kanban columns)
+ */
+function groupByStatus(workItems) {
+  const grouped = groupItemsByColumn(workItems);
+
+  return {
+    mode: 'columns',
+    groups: COLUMN_ORDER.map((columnName) => ({
+      id: columnName,
+      name: columnName,
+      items: grouped[columnName] || [],
+      type: 'column',
+    })),
+  };
+}
+
+/**
+ * Group by epic (hierarchical sections)
+ */
+function groupByEpic(workItems) {
+  // Get all epics
+  const epics = workItems.filter((item) => item.type === 'epic');
+
+  // Group items by epic
+  const groups = epics.map((epic) => {
+    // Get all descendants of this epic
+    const epicItems = workItems.filter(
+      (item) => item.epicId === epic.id
+    );
+
+    // Group epic's items by column
+    const columns = groupItemsByColumn(epicItems);
+
+    return {
+      id: epic.id,
+      name: epic.name,
+      epic: epic,
+      items: epicItems,
+      columns: columns,
+      type: 'epic',
+    };
+  });
+
+  // Add ungrouped items (items without an epic)
+  const ungroupedItems = workItems.filter(
+    (item) => !item.epicId && item.type !== 'epic'
+  );
+
+  if (ungroupedItems.length > 0) {
+    const columns = groupItemsByColumn(ungroupedItems);
+    groups.push({
+      id: 'ungrouped',
+      name: 'No Epic',
+      items: ungroupedItems,
+      columns: columns,
+      type: 'ungrouped',
+    });
+  }
+
+  return {
+    mode: 'sections',
+    groups,
+  };
+}
+
+/**
+ * Group by type (separate boards for each type)
+ */
+function groupByType(workItems) {
+  const types = [
+    { id: 'epic', name: 'Epics' },
+    { id: 'story', name: 'Stories' },
+    { id: 'task', name: 'Tasks' },
+    { id: 'subtask', name: 'Subtasks' },
+  ];
+
+  const groups = types.map((type) => {
+    const typeItems = workItems.filter((item) => item.type === type.id);
+    const columns = groupItemsByColumn(typeItems);
+
+    return {
+      id: type.id,
+      name: type.name,
+      items: typeItems,
+      columns: columns,
+      type: 'type',
+    };
+  });
+
+  // Filter out empty groups
+  return {
+    mode: 'sections',
+    groups: groups.filter((group) => group.items.length > 0),
+  };
+}

package/kanban/client/src/hooks/useWebSocket.js

@@ -0,0 +1,120 @@
+import { useEffect, useRef, useCallback, useState } from 'react';
+
+// Module-level constant — window.location.host never changes during a session
+const WS_URL = import.meta.env.VITE_WS_URL || `ws://${window.location.host}/ws`;
+
+const MAX_RECONNECT_ATTEMPTS = 5;
+const RECONNECT_DELAY = 2000;
+
+/**
+ * WebSocket hook for real-time updates.
+ *
+ * Returns wsStatus: 'connecting' | 'connected' | 'disconnected'
+ * Callbacks are stored in refs so connect() is stable and the effect
+ * only runs once (no infinite reconnect loop from inline callbacks).
+ */
+export function useWebSocket(options = {}) {
+  const { onMessage, onConnected, onDisconnected, onError } = options;
+
+  const [wsStatus, setWsStatus] = useState('connecting');
+
+  const wsRef = useRef(null);
+  const reconnectTimeoutRef = useRef(null);
+  const reconnectAttempts = useRef(0);
+
+  // Stable refs — updated every render without triggering reconnects
+  const onMessageRef = useRef(onMessage);
+  const onConnectedRef = useRef(onConnected);
+  const onDisconnectedRef = useRef(onDisconnected);
+  const onErrorRef = useRef(onError);
+  onMessageRef.current = onMessage;
+  onConnectedRef.current = onConnected;
+  onDisconnectedRef.current = onDisconnected;
+  onErrorRef.current = onError;
+
+  const connect = useCallback(() => {
+    if (wsRef.current?.readyState === WebSocket.OPEN) {
+      return; // Already connected
+    }
+
+    try {
+      const ws = new WebSocket(WS_URL);
+
+      ws.onopen = () => {
+        console.log('WebSocket connected');
+        reconnectAttempts.current = 0;
+        setWsStatus('connected');
+        onConnectedRef.current?.();
+      };
+
+      ws.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          onMessageRef.current?.(data);
+        } catch (error) {
+          console.error('WebSocket message parse error:', error);
+        }
+      };
+
+      ws.onerror = (error) => {
+        console.error('WebSocket error:', error);
+        onErrorRef.current?.(error);
+      };
+
+      ws.onclose = () => {
+        console.log('WebSocket disconnected');
+        wsRef.current = null;
+        onDisconnectedRef.current?.();
+
+        if (reconnectAttempts.current < MAX_RECONNECT_ATTEMPTS) {
+          reconnectAttempts.current++;
+          console.log(`Reconnecting... (attempt ${reconnectAttempts.current})`);
+          setWsStatus('connecting');
+          reconnectTimeoutRef.current = setTimeout(connect, RECONNECT_DELAY);
+        } else {
+          console.error('Max reconnection attempts reached');
+          setWsStatus('disconnected');
+        }
+      };
+
+      wsRef.current = ws;
+    } catch (error) {
+      console.error('WebSocket connection error:', error);
+      onErrorRef.current?.(error);
+    }
+  }, []); // No callback deps — refs keep them current without recreating connect
+
+  const disconnect = useCallback(() => {
+    if (reconnectTimeoutRef.current) {
+      clearTimeout(reconnectTimeoutRef.current);
+      reconnectTimeoutRef.current = null;
+    }
+
+    if (wsRef.current) {
+      wsRef.current.close();
+      wsRef.current = null;
+    }
+  }, []);
+
+  const send = useCallback((data) => {
+    if (wsRef.current?.readyState === WebSocket.OPEN) {
+      wsRef.current.send(JSON.stringify(data));
+    } else {
+      console.warn('WebSocket not connected, cannot send message');
+    }
+  }, []);
+
+  useEffect(() => {
+    connect();
+    return () => {
+      disconnect();
+    };
+  }, [connect, disconnect]); // both stable — effect runs exactly once
+
+  return {
+    wsStatus,
+    send,
+    disconnect,
+    reconnect: connect,
+  };
+}

package/kanban/client/src/lib/__tests__/api.test.js

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  getHealth,
+  getStats,
+  getWorkItems,
+  getWorkItemsGrouped,
+  getWorkItem,
+  getWorkItemDoc,
+} from '../api';
+
+// Mock fetch globally
+global.fetch = vi.fn();
+
+describe('api', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('getHealth', () => {
+    it('should fetch health status successfully', async () => {
+      const mockResponse = { status: 'ok', uptime: 12345 };
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockResponse,
+      });
+
+      const result = await getHealth();
+
+      expect(fetch).toHaveBeenCalledWith('/api/health', {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      expect(result).toEqual(mockResponse);
+    });
+
+    it('should throw error when fetch fails', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+        json: async () => ({ error: 'Server error' }),
+      });
+
+      await expect(getHealth()).rejects.toThrow();
+    });
+  });
+
+  describe('getStats', () => {
+    it('should fetch statistics successfully', async () => {
+      const mockStats = {
+        totalItems: 42,
+        byStatus: { planned: 10, implementing: 15 },
+        byType: { epic: 5, story: 20 },
+      };
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockStats,
+      });
+
+      const result = await getStats();
+
+      expect(fetch).toHaveBeenCalledWith('/api/stats', {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      expect(result).toEqual(mockStats);
+    });
+  });
+
+  describe('getWorkItems', () => {
+    it('should fetch work items without filters', async () => {
+      const mockItems = [
+        { id: 'EPIC-001', type: 'epic', status: 'implementing' },
+        { id: 'STORY-001', type: 'story', status: 'ready' },
+      ];
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockItems,
+      });
+
+      const result = await getWorkItems();
+
+      expect(fetch).toHaveBeenCalledWith('/api/work-items', {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      expect(result).toEqual(mockItems);
+    });
+
+    it('should fetch work items with type filter', async () => {
+      const mockItems = [{ id: 'EPIC-001', type: 'epic', status: 'implementing' }];
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockItems,
+      });
+
+      const result = await getWorkItems({ type: 'epic' });
+
+      expect(fetch).toHaveBeenCalledWith('/api/work-items?type=epic', {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      expect(result).toEqual(mockItems);
+    });
+
+    it('should fetch work items with multiple filters', async () => {
+      const mockItems = [{ id: 'STORY-001', type: 'story', status: 'ready' }];
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockItems,
+      });
+
+      const result = await getWorkItems({ type: 'story', status: 'ready' });
+
+      expect(fetch).toHaveBeenCalledWith('/api/work-items?type=story&status=ready', {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      expect(result).toEqual(mockItems);
+    });
+  });
+
+  describe('getWorkItemsGrouped', () => {
+    it('should fetch grouped work items', async () => {
+      const mockGrouped = {
+        Backlog: [{ id: 'STORY-001', status: 'planned' }],
+        Ready: [{ id: 'STORY-002', status: 'ready' }],
+      };
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockGrouped,
+      });
+
+      const result = await getWorkItemsGrouped();
+
+      expect(fetch).toHaveBeenCalledWith('/api/work-items/grouped', {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      expect(result).toEqual(mockGrouped);
+    });
+  });
+
+  describe('getWorkItem', () => {
+    it('should fetch single work item successfully', async () => {
+      const mockItem = {
+        id: 'EPIC-001',
+        type: 'epic',
+        name: 'Test Epic',
+        status: 'implementing',
+      };
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockItem,
+      });
+
+      const result = await getWorkItem('EPIC-001');
+
+      expect(fetch).toHaveBeenCalledWith('/api/work-items/EPIC-001', {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      expect(result).toEqual(mockItem);
+    });
+
+    it('should throw error for non-existent work item', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        statusText: 'Not Found',
+        json: async () => ({ error: 'Not found' }),
+      });
+
+      await expect(getWorkItem('NONEXISTENT')).rejects.toThrow();
+    });
+  });
+
+  describe('getWorkItemDoc', () => {
+    it('should fetch work item documentation', async () => {
+      const mockDoc = '# Epic Documentation\n\nDetails here...';
+      global.fetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => mockDoc,
+      });
+
+      const result = await getWorkItemDoc('EPIC-001');
+
+      expect(result).toBe(mockDoc);
+    });
+
+    it('should return empty string when doc not found', async () => {
+      global.fetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+      });
+
+      const result = await getWorkItemDoc('EPIC-001');
+
+      expect(result).toBe('');
+    });
+  });
+
+});