feat(@helm/web): read-only kanban dashboard and item detail (Session 6)

apps/web/package.json

@@ -6,19 +6,28 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
-    "test": "echo 'no tests yet'",
+    "test": "vitest run",
     "lint": "eslint src/"
   },
   "dependencies": {
+    "@helm/shared": "workspace:*",
+    "@helm/workflow": "workspace:*",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^7.15.1"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
     "@vitejs/plugin-react": "^4.7.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
-    "vite": "^5.4.21"
+    "vite": "^5.4.21",
+    "vitest": "^2.1.9"
   }
 }

apps/web/src/App.tsx

@@ -1,22 +1,14 @@
-import { useEffect, useState } from 'react';
-
-type WsStatus = 'connecting' | 'connected' | 'disconnected';
+import { BrowserRouter, Route, Routes } from 'react-router-dom';
+import { Kanban } from './views/Kanban.js';
+import { ItemDetail } from './views/ItemDetail.js';
 
 export default function App() {
-  const [status, setStatus] = useState<WsStatus>('connecting');
-
-  useEffect(() => {
-    const ws = new WebSocket('ws://localhost:5173/ws');
-    ws.onopen = () => setStatus('connected');
-    ws.onclose = () => setStatus('disconnected');
-    ws.onerror = () => setStatus('disconnected');
-    return () => ws.close();
-  }, []);
-
   return (
-    <div className="flex min-h-screen flex-col items-center justify-center bg-gray-50">
-      <h1 className="text-4xl font-bold tracking-tight text-gray-900">Helm</h1>
-      <p className="mt-4 font-mono text-sm text-gray-500">{status}</p>
-    </div>
+    <BrowserRouter>
+      <Routes>
+        <Route path="/" element={<Kanban />} />
+        <Route path="/items/:id" element={<ItemDetail />} />
+      </Routes>
+    </BrowserRouter>
   );
 }

apps/web/src/hooks/usePolling.test.ts

@@ -0,0 +1,141 @@
+import { renderHook, act } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { usePolling } from './usePolling.js';
+import type { ApiResult } from '../lib/api.js';
+
+function ok<T>(data: T): ApiResult<T> {
+  return { ok: true, data };
+}
+function err(message: string): ApiResult<never> {
+  return { ok: false, error: { type: 'network', message } };
+}
+
+describe('usePolling', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('starts in loading state and populates data on first fetch', async () => {
+    const fetcher = vi.fn().mockResolvedValue(ok({ count: 1 }));
+
+    const { result } = renderHook(() => usePolling(fetcher, 5_000));
+
+    expect(result.current.loading).toBe(true);
+    expect(result.current.data).toBeNull();
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(result.current.loading).toBe(false);
+    expect(result.current.data).toEqual({ count: 1 });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-fetches after each interval tick', async () => {
+    const fetcher = vi.fn().mockResolvedValue(ok({ count: 1 }));
+    renderHook(() => usePolling(fetcher, 1_000));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      vi.advanceTimersByTime(1_000);
+      await Promise.resolve();
+    });
+    expect(fetcher).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      vi.advanceTimersByTime(1_000);
+      await Promise.resolve();
+    });
+    expect(fetcher).toHaveBeenCalledTimes(3);
+  });
+
+  it('clears the interval on unmount', async () => {
+    const fetcher = vi.fn().mockResolvedValue(ok({}));
+    const { unmount } = renderHook(() => usePolling(fetcher, 1_000));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    unmount();
+
+    await act(async () => {
+      vi.advanceTimersByTime(5_000);
+      await Promise.resolve();
+    });
+
+    expect(fetcher).toHaveBeenCalledTimes(1); // only the initial fetch
+  });
+
+  it('sets error and clears data on fetch failure', async () => {
+    const fetcher = vi.fn().mockResolvedValue(err('Failed to fetch'));
+    const { result } = renderHook(() => usePolling(fetcher, 5_000));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(result.current.error).toBe('Failed to fetch');
+    expect(result.current.data).toBeNull();
+    expect(result.current.loading).toBe(false);
+  });
+
+  it('clears error when a subsequent poll succeeds', async () => {
+    const fetcher = vi
+      .fn()
+      .mockResolvedValueOnce(err('Network error'))
+      .mockResolvedValue(ok({ value: 42 }));
+
+    const { result } = renderHook(() => usePolling(fetcher, 1_000));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(result.current.error).toBe('Network error');
+
+    await act(async () => {
+      vi.advanceTimersByTime(1_000);
+      await Promise.resolve();
+    });
+
+    expect(result.current.error).toBeNull();
+    expect(result.current.data).toEqual({ value: 42 });
+  });
+
+  it('handles a rejected fetcher promise and sets error state', async () => {
+    const fetcher = vi.fn().mockRejectedValue(new Error('boom'));
+    const { result } = renderHook(() => usePolling(fetcher, 5_000));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBe('boom');
+    expect(result.current.data).toBeNull();
+  });
+
+  it('fetches once and does not poll when intervalMs is null', async () => {
+    const fetcher = vi.fn().mockResolvedValue(ok({}));
+    renderHook(() => usePolling(fetcher, null));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      vi.advanceTimersByTime(30_000);
+      await Promise.resolve();
+    });
+    expect(fetcher).toHaveBeenCalledTimes(1); // still just once
+  });
+});

apps/web/src/hooks/usePolling.ts

@@ -0,0 +1,75 @@
+import { useEffect, useRef, useState } from 'react';
+import type { ApiResult } from '../lib/api.js';
+
+export type PollingState<T> = {
+  data: T | null;
+  error: string | null;
+  loading: boolean;
+};
+
+/**
+ * Fetches immediately, then polls at `intervalMs`.
+ * Pass `intervalMs = null` to fetch once and skip polling.
+ * The fetcher reference is kept stable via a ref so callers can pass
+ * inline arrow functions without causing the effect to re-run.
+ *
+ * Guards:
+ * - `inFlight`: skips a tick if the previous request is still pending,
+ *   preventing overlapping requests and out-of-order state writes.
+ * - try-catch: maps thrown errors (not just { ok: false } returns) to the
+ *   error state so unhandled rejections never bubble up.
+ */
+export function usePolling<T>(
+  fetcher: () => Promise<ApiResult<T>>,
+  intervalMs: number | null = 5_000,
+): PollingState<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+
+  useEffect(() => {
+    let cancelled = false;
+    let inFlight = false;
+
+    const doFetch = async () => {
+      if (inFlight) return;
+      inFlight = true;
+      try {
+        const result = await fetcherRef.current();
+        if (cancelled) return;
+        if (result.ok) {
+          setData(result.data);
+          setError(null);
+        } else {
+          setError(result.error.message);
+        }
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : 'Unexpected polling error');
+      } finally {
+        inFlight = false;
+        setLoading(false);
+      }
+    };
+
+    void doFetch();
+
+    if (intervalMs === null)
+      return () => {
+        cancelled = true;
+      };
+
+    const id = setInterval(() => {
+      void doFetch();
+    }, intervalMs);
+    return () => {
+      cancelled = true;
+      clearInterval(id);
+    };
+  }, [intervalMs]);
+
+  return { data, error, loading };
+}

apps/web/src/lib/api.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { api } from './api.js';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+function mockOk(body: unknown): Response {
+  return {
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve(body),
+  } as unknown as Response;
+}
+
+function mockErr(status: number, body: unknown): Response {
+  return {
+    ok: false,
+    status,
+    statusText: `Error ${status}`,
+    json: () => Promise.resolve(body),
+  } as unknown as Response;
+}
+
+afterEach(() => vi.clearAllMocks());
+
+describe('api.getProduct', () => {
+  it('returns ok result on success', async () => {
+    const product = { helm_version: '0', product: { slug: 'helm', name: 'Helm' } };
+    mockFetch.mockResolvedValueOnce(mockOk(product));
+    const result = await api.getProduct();
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.data.product.slug).toBe('helm');
+  });
+
+  it('returns http error on non-200', async () => {
+    mockFetch.mockResolvedValueOnce(mockErr(404, { error: 'Not found' }));
+    const result = await api.getProduct();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.type).toBe('http');
+      expect((result.error as { status: number }).status).toBe(404);
+    }
+  });
+
+  it('returns network error on fetch throw', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Failed to fetch'));
+    const result = await api.getProduct();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.type).toBe('network');
+      expect(result.error.message).toBe('Failed to fetch');
+    }
+  });
+});
+
+describe('api.listItems', () => {
+  it('returns array of items', async () => {
+    const items = [{ externalId: 'issue_1', currentStage: 'discovery' }];
+    mockFetch.mockResolvedValueOnce(mockOk(items));
+    const result = await api.listItems();
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.data).toHaveLength(1);
+  });
+});
+
+describe('api.getItem', () => {
+  it('URL-encodes special characters in externalId', async () => {
+    const externalId = 'issue/1 with space';
+    mockFetch.mockResolvedValueOnce(mockOk({ externalId }));
+    await api.getItem(externalId);
+    const calledUrl = mockFetch.mock.calls[0]?.[0] as string;
+    expect(calledUrl).toContain(encodeURIComponent(externalId));
+  });
+
+  it('returns http error on 404', async () => {
+    mockFetch.mockResolvedValueOnce(mockErr(404, { error: 'Not found' }));
+    const result = await api.getItem('issue_999');
+    expect(result.ok).toBe(false);
+  });
+});