@a5c-ai/babysitter-observer-dashboard 1.0.0

package/src/hooks/use-smart-polling.ts

@@ -0,0 +1,144 @@
+"use client";
+import { useState, useEffect, useRef, useCallback, startTransition } from "react";
+import { subscribe, StreamEvent } from "./use-event-stream";
+import { resilientFetch } from "@/lib/fetcher";
+
+interface UseSmartPollingOptions {
+  interval?: number;
+  sseFilter?: (event: StreamEvent) => boolean;
+  enabled?: boolean;
+  /** When true, suppress SSE-triggered refetches (used during catch-up mode). */
+  suppressSseRefetch?: boolean;
+}
+
+export function useSmartPolling<T>(
+  url: string,
+  options: UseSmartPollingOptions = {}
+) {
+  const { interval = 5000, sseFilter, enabled = true, suppressSseRefetch = false } = options;
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(enabled && !!url);
+  const [error, setError] = useState<string | null>(null);
+  const mountedRef = useRef(true);
+  const sseFilterRef = useRef(sseFilter);
+  sseFilterRef.current = sseFilter;
+  const sseConnected = useRef(false);
+  const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const suppressSseRefetchRef = useRef(suppressSseRefetch);
+  suppressSseRefetchRef.current = suppressSseRefetch;
+
+  const fetchData = useCallback(async () => {
+    if (!url || !enabled) return;
+    abortRef.current?.abort();
+    abortRef.current = new AbortController();
+    const result = await resilientFetch<T>(url, { signal: abortRef.current.signal });
+    if (!result.ok) {
+      if (result.error.isAborted) return;
+      if (mountedRef.current) {
+        setError(result.error.message);
+        setLoading(false);
+      }
+      return;
+    }
+    if (mountedRef.current) {
+      // Skip state update on 304 Not Modified — data is identical to
+      // what we already have, so avoid triggering a re-render cascade.
+      if (result.status !== 304) {
+        // Use startTransition so SSE-triggered data updates are treated as
+        // non-urgent. This keeps the UI responsive during rapid bursts —
+        // React can batch and defer these renders without blocking user input.
+        startTransition(() => {
+          setData(result.data);
+        });
+      }
+      setError(null);
+      setLoading(false);
+    }
+  }, [url, enabled]);
+
+  // Polling: slower when SSE connected (30s heartbeat), normal interval when disconnected
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled || !url) {
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    fetchData();
+
+    // Start poll timer — use longer interval when SSE connected, normal when not
+    function startPoll() {
+      if (pollTimerRef.current) clearInterval(pollTimerRef.current);
+      const pollInterval = sseConnected.current ? Math.max(interval * 3, 15000) : interval;
+      pollTimerRef.current = setInterval(fetchData, pollInterval);
+    }
+
+    startPoll();
+
+    return () => {
+      mountedRef.current = false;
+      abortRef.current?.abort();
+      if (pollTimerRef.current) {
+        clearInterval(pollTimerRef.current);
+        pollTimerRef.current = null;
+      }
+    };
+  }, [fetchData, interval, enabled, url]);
+
+  // SSE subscription: triggers immediate refresh on matching events
+  useEffect(() => {
+    if (!enabled || !sseFilterRef.current) return;
+
+    const unsubscribe = subscribe((event: StreamEvent) => {
+      // Track SSE connection state
+      if (event.type === "connected") {
+        if (!sseConnected.current) {
+          sseConnected.current = true;
+          // Restart poll with longer interval since SSE is active
+          if (pollTimerRef.current) clearInterval(pollTimerRef.current);
+          const slowInterval = Math.max(interval * 3, 15000);
+          pollTimerRef.current = setInterval(fetchData, slowInterval);
+        }
+        return;
+      }
+
+      // On SSE disconnect or error, reset to normal polling (no immediate fetch)
+      if (event.type === "disconnect" || event.type === "error") {
+        if (sseConnected.current) {
+          sseConnected.current = false;
+          if (pollTimerRef.current) clearInterval(pollTimerRef.current);
+          pollTimerRef.current = setInterval(fetchData, interval);
+        }
+        return;
+      }
+
+      // Apply filter and trigger debounced refresh to coalesce rapid events.
+      // Uses a 1500ms trailing-edge debounce (up from 150ms) to batch burst
+      // updates that arrive in quick succession (e.g. after overnight runs).
+      // When catch-up mode is active, SSE-triggered refetches are suppressed
+      // entirely — the catch-up flush will trigger a single refresh instead.
+      if (sseFilterRef.current?.(event)) {
+        if (suppressSseRefetchRef.current) return;
+        if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current);
+        debounceTimerRef.current = setTimeout(() => {
+          debounceTimerRef.current = null;
+          fetchData();
+        }, 1500);
+      }
+    });
+
+    return () => {
+      unsubscribe();
+      sseConnected.current = false;
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+        debounceTimerRef.current = null;
+      }
+    };
+  }, [enabled, fetchData, interval]);
+
+  return { data, loading, error, refresh: fetchData };
+}

package/src/lib/__tests__/cn.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { cn } from '../cn';
+
+describe('cn', () => {
+  it('returns an empty string when called with no arguments', () => {
+    expect(cn()).toBe('');
+  });
+
+  it('returns a single class name unchanged', () => {
+    expect(cn('text-red-500')).toBe('text-red-500');
+  });
+
+  it('merges multiple class names', () => {
+    const result = cn('px-2', 'py-1');
+    expect(result).toContain('px-2');
+    expect(result).toContain('py-1');
+  });
+
+  it('handles conditional classes via clsx syntax', () => {
+    expect(cn('base', false && 'hidden')).toBe('base');
+    expect(cn('base', true && 'visible')).toBe('base visible');
+  });
+
+  it('handles undefined and null inputs', () => {
+    expect(cn('base', undefined, null, 'extra')).toBe('base extra');
+  });
+
+  it('handles array inputs', () => {
+    expect(cn(['px-2', 'py-1'])).toContain('px-2');
+    expect(cn(['px-2', 'py-1'])).toContain('py-1');
+  });
+
+  it('handles object inputs', () => {
+    expect(cn({ 'text-red-500': true, hidden: false })).toBe('text-red-500');
+  });
+
+  it('merges conflicting Tailwind classes correctly (tailwind-merge)', () => {
+    // tailwind-merge should resolve conflicts, last one wins
+    expect(cn('px-2', 'px-4')).toBe('px-4');
+    expect(cn('text-red-500', 'text-blue-500')).toBe('text-blue-500');
+  });
+
+  it('merges conflicting padding classes', () => {
+    expect(cn('p-4', 'px-2')).toBe('p-4 px-2');
+  });
+
+  it('deduplicates identical class names', () => {
+    // tailwind-merge handles dedup
+    const result = cn('flex', 'flex');
+    expect(result).toBe('flex');
+  });
+
+  it('handles empty strings', () => {
+    expect(cn('', 'base', '')).toBe('base');
+  });
+
+  it('handles complex mixed inputs', () => {
+    const result = cn(
+      'base-class',
+      undefined,
+      { 'conditional-class': true, 'excluded-class': false },
+      ['array-class'],
+    );
+    expect(result).toContain('base-class');
+    expect(result).toContain('conditional-class');
+    expect(result).not.toContain('excluded-class');
+    expect(result).toContain('array-class');
+  });
+});

package/src/lib/__tests__/config-loader.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import path from 'path';
+import { promises as fs } from 'fs';
+import {
+  getConfig,
+  invalidateConfigCache,
+  writeConfig,
+} from '../config-loader';
+
+// Use vi.spyOn so both test and config-loader module share the same mock references
+const mockReadFile = vi.spyOn(fs, 'readFile');
+const mockWriteFile = vi.spyOn(fs, 'writeFile');
+const mockMkdir = vi.spyOn(fs, 'mkdir');
+
+describe('config-loader', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    process.env = { ...originalEnv };
+    delete process.env.OBSERVER_REGISTRY;
+    delete process.env.OBSERVER_WATCH_DIR;
+    delete process.env.WATCH_DIR;
+    delete process.env.WATCH_DIRS;
+    delete process.env.OBSERVER_PORT;
+    delete process.env.PORT;
+    delete process.env.OBSERVER_POLL_INTERVAL;
+    delete process.env.POLL_INTERVAL;
+    delete process.env.OBSERVER_DEFAULT_THEME;
+    delete process.env.THEME;
+    invalidateConfigCache();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  // -----------------------------------------------------------------------
+  // invalidateConfigCache
+  // -----------------------------------------------------------------------
+  describe('invalidateConfigCache', () => {
+    it('clears the cached config so next getConfig re-reads', async () => {
+      mockReadFile.mockRejectedValue(new Error('no file'));
+      const config1 = await getConfig();
+      expect(config1).toBeDefined();
+
+      invalidateConfigCache();
+
+      mockReadFile.mockRejectedValue(new Error('no file'));
+      const _config2 = await getConfig();
+      expect(mockReadFile).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // getConfig
+  // -----------------------------------------------------------------------
+  describe('getConfig', () => {
+    it('returns default config when registry file does not exist', async () => {
+      mockReadFile.mockRejectedValue(new Error('ENOENT'));
+
+      const config = await getConfig();
+
+      expect(config).toBeDefined();
+      expect(config.port).toBe(4800);
+      expect(config.pollInterval).toBe(2000);
+      expect(config.theme).toBe('dark');
+      expect(config.sources.length).toBeGreaterThan(0);
+    });
+
+    it('uses parent of cwd as default source when no env vars are set', async () => {
+      mockReadFile.mockRejectedValue(new Error('ENOENT'));
+
+      const config = await getConfig();
+
+      expect(config.sources[0].path).toBe(path.resolve(process.cwd(), '..'));
+      expect(config.sources[0].label).toBe('parent');
+      expect(config.sources[0].depth).toBe(3);
+    });
+
+    it('uses OBSERVER_WATCH_DIR env var when set', async () => {
+      mockReadFile.mockRejectedValue(new Error('ENOENT'));
+      process.env.OBSERVER_WATCH_DIR = '/custom/watch/dir';
+      invalidateConfigCache();
+
+      const config = await getConfig();
+
+      expect(config.sources[0].path).toBe('/custom/watch/dir');
+      expect(config.sources[0].label).toBe('cli');
+    });
+
+    it('reads sources from registry file', async () => {
+      mockReadFile.mockResolvedValue(
+        JSON.stringify({
+          sources: [
+            { path: '/registered/path', depth: 3, label: 'registry' },
+          ],
+        }),
+      );
+
+      const config = await getConfig();
+
+      expect(config.sources).toHaveLength(1);
+      expect(config.sources[0].path).toBe('/registered/path');
+      expect(config.sources[0].depth).toBe(3);
+      expect(config.sources[0].label).toBe('registry');
+    });
+
+    it('defaults depth to 2 when registry source has no depth', async () => {
+      mockReadFile.mockResolvedValue(
+        JSON.stringify({
+          sources: [{ path: '/some/path' }],
+        }),
+      );
+
+      const config = await getConfig();
+
+      expect(config.sources[0].depth).toBe(2);
+    });
+
+    it('caches config and returns cached version within TTL', async () => {
+      mockReadFile.mockResolvedValue(JSON.stringify({ sources: [] }));
+
+      const config1 = await getConfig();
+      const config2 = await getConfig();
+
+      expect(mockReadFile).toHaveBeenCalledTimes(1);
+      expect(config1).toBe(config2);
+    });
+
+    it('reads theme from registry file', async () => {
+      mockReadFile.mockResolvedValue(
+        JSON.stringify({
+          sources: [],
+          theme: 'light',
+        }),
+      );
+
+      const config = await getConfig();
+
+      expect(config.theme).toBe('light');
+    });
+
+    it('defaults theme to dark for invalid theme values', async () => {
+      mockReadFile.mockResolvedValue(JSON.stringify({ sources: [] }));
+      process.env.THEME = 'invalid-theme';
+      invalidateConfigCache();
+
+      const config = await getConfig();
+
+      expect(config.theme).toBe('dark');
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // writeConfig
+  // -----------------------------------------------------------------------
+  describe('writeConfig', () => {
+    it('creates directory and writes config file', async () => {
+      mockMkdir.mockResolvedValue(undefined);
+      mockReadFile.mockRejectedValue(new Error('ENOENT'));
+      mockWriteFile.mockResolvedValue(undefined);
+
+      await writeConfig({
+        sources: [{ path: '/new/path', depth: 1 }],
+      });
+
+      expect(mockMkdir).toHaveBeenCalledWith(expect.any(String), { recursive: true });
+      expect(mockWriteFile).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.stringContaining('/new/path'),
+        'utf-8',
+      );
+    });
+
+    it('preserves existing fields in the registry file', async () => {
+      mockMkdir.mockResolvedValue(undefined);
+      mockReadFile.mockResolvedValue(
+        JSON.stringify({ existingField: 'preserved', sources: [] }),
+      );
+      mockWriteFile.mockResolvedValue(undefined);
+
+      await writeConfig({
+        sources: [{ path: '/updated', depth: 2 }],
+      });
+
+      const writtenContent = JSON.parse(
+        (mockWriteFile.mock.calls[0][1] as string).trim(),
+      );
+      expect(writtenContent.existingField).toBe('preserved');
+      expect(writtenContent.sources[0].path).toBe('/updated');
+    });
+
+    it('writes pollInterval when provided', async () => {
+      mockMkdir.mockResolvedValue(undefined);
+      mockReadFile.mockRejectedValue(new Error('ENOENT'));
+      mockWriteFile.mockResolvedValue(undefined);
+
+      await writeConfig({
+        sources: [],
+        pollInterval: 5000,
+      });
+
+      const writtenContent = JSON.parse(
+        (mockWriteFile.mock.calls[0][1] as string).trim(),
+      );
+      expect(writtenContent.pollInterval).toBe(5000);
+    });
+  });
+});