@a5c-ai/babysitter-observer-dashboard 1.0.0

package/src/lib/watcher.ts

@@ -0,0 +1,265 @@
+import { watch, type FSWatcher } from "fs";
+import { promises as fs } from "fs";
+import path from "path";
+import { EventEmitter } from "events";
+import { discoverAllRunDirs, invalidateDiscoveryCache, discoverAllRunsParentDirs } from "./source-discovery";
+import { invalidateRun, requestDiscovery } from "./run-cache";
+import { getGlobal } from "./global-registry";
+
+// Persist event emitter across HMR reloads via typed global registry
+function getWatcherEvents(): EventEmitter {
+  return getGlobal('__observer_watcher_events__', () => new EventEmitter());
+}
+
+export const watcherEvents = getWatcherEvents();
+
+// Event types
+export type WatcherEventType = "run-changed" | "new-run" | "error";
+
+export interface WatcherEvent {
+  type: WatcherEventType;
+  runDir: string;
+  error?: Error;
+}
+
+// Persist watcher state across HMR reloads via typed global registry
+interface WatcherState {
+  activeWatchers: Map<string, FSWatcher>;
+  debounceTimers: Map<string, NodeJS.Timeout>;
+  rescanTimer: NodeJS.Timeout | null;
+}
+
+function getWatcherState(): WatcherState {
+  return getGlobal('__observer_watchers__', () => ({
+    activeWatchers: new Map<string, FSWatcher>(),
+    debounceTimers: new Map<string, NodeJS.Timeout>(),
+    rescanTimer: null,
+  }));
+}
+
+// WSL-optimized constants
+const DEBOUNCE_MS = 500; // 500ms debounce (WSL cross-FS needs more)
+const RESCAN_INTERVAL_MS = 30000; // 30s — reduced from 120s to detect new project directories faster
+
+function debounceChange(runDir: string, callback: () => void) {
+  const state = getWatcherState();
+  const existing = state.debounceTimers.get(runDir);
+  if (existing) {
+    clearTimeout(existing);
+  }
+
+  const timer = setTimeout(() => {
+    state.debounceTimers.delete(runDir);
+    callback();
+  }, DEBOUNCE_MS);
+
+  state.debounceTimers.set(runDir, timer);
+}
+
+function handleJournalChange(journalDir: string) {
+  const runDir = path.dirname(journalDir);
+
+  debounceChange(runDir, () => {
+    invalidateRun(runDir);
+    requestDiscovery(); // Ensure discoverAndCacheAll() re-populates the entry
+    watcherEvents.emit("change", {
+      type: "run-changed",
+      runDir,
+    } as WatcherEvent);
+  });
+}
+
+function handleTasksChange(tasksDir: string) {
+  const runDir = path.dirname(tasksDir);
+
+  debounceChange(runDir, () => {
+    invalidateRun(runDir);
+    requestDiscovery(); // Ensure discoverAndCacheAll() re-populates the entry
+    watcherEvents.emit("change", {
+      type: "run-changed",
+      runDir,
+    } as WatcherEvent);
+  });
+}
+
+function handleRunsParentChange(runsDir: string) {
+  debounceChange(runsDir, () => {
+    // Invalidate caches so new runs are picked up on next request
+    invalidateDiscoveryCache();
+    requestDiscovery();
+    watcherEvents.emit("change", {
+      type: "new-run",
+      runDir: runsDir,
+    } as WatcherEvent);
+  });
+}
+
+function watchDirectory(dirPath: string, onChange: (path: string) => void): FSWatcher | null {
+  try {
+    // Use non-recursive watch (WSL doesn't support recursive)
+    const watcher = watch(dirPath, { recursive: false }, (eventType, filename) => {
+      if (filename) {
+        onChange(dirPath);
+      }
+    });
+
+    watcher.on("error", (err) => {
+      console.error(`Watch error for ${dirPath}:`, err);
+      watcherEvents.emit("change", {
+        type: "error",
+        runDir: dirPath,
+        error: err,
+      } as WatcherEvent);
+    });
+
+    return watcher;
+  } catch (err) {
+    console.error(`Failed to watch ${dirPath}:`, err);
+    return null;
+  }
+}
+
+async function setupWatchers() {
+  const state = getWatcherState();
+  const discovered = await discoverAllRunDirs();
+  const runsParentDirs = new Set<string>();
+
+  // Build the set of directories we need to watch
+  const neededDirs = new Set<string>();
+
+  for (const { runDir } of discovered) {
+    const journalDir = path.join(runDir, "journal");
+    try {
+      await fs.access(journalDir);
+      neededDirs.add(journalDir);
+    } catch {
+      // Journal dir doesn't exist yet — skip for now
+    }
+
+    const tasksDir = path.join(runDir, "tasks");
+    try {
+      await fs.access(tasksDir);
+      neededDirs.add(tasksDir);
+    } catch {
+      // Tasks dir doesn't exist yet — skip for now
+    }
+
+    const runsDir = path.dirname(runDir);
+    runsParentDirs.add(runsDir);
+  }
+
+  // Also discover ALL .a5c/runs/ directories (including empty ones)
+  // so we detect the very first run in a new project immediately
+  try {
+    const allRunsParentDirs = await discoverAllRunsParentDirs();
+    for (const dir of allRunsParentDirs) {
+      runsParentDirs.add(dir);
+    }
+  } catch {
+    // Non-critical — fall back to watching only populated runs dirs
+  }
+
+  for (const runsDir of runsParentDirs) {
+    try {
+      await fs.access(runsDir);
+      neededDirs.add(runsDir);
+    } catch {
+      // Runs dir doesn't exist
+    }
+  }
+
+  // Incremental update: close watchers for directories no longer needed
+  for (const [dirPath, watcher] of state.activeWatchers.entries()) {
+    if (!neededDirs.has(dirPath)) {
+      watcher.close();
+      state.activeWatchers.delete(dirPath);
+    }
+  }
+
+  // Only create new watchers for newly discovered directories
+  for (const dirPath of neededDirs) {
+    if (!state.activeWatchers.has(dirPath)) {
+      const baseName = path.basename(dirPath);
+      const isJournalDir = baseName === "journal";
+      const isTasksDir = baseName === "tasks";
+      const onChange = isJournalDir
+        ? handleJournalChange
+        : isTasksDir
+          ? handleTasksChange
+          : handleRunsParentChange;
+      const watcher = watchDirectory(dirPath, onChange);
+      if (watcher) {
+        state.activeWatchers.set(dirPath, watcher);
+      }
+    }
+  }
+
+  console.log(`Watching ${state.activeWatchers.size} directories`);
+}
+
+async function periodicRescan() {
+  try {
+    // Re-discover and update watchers incrementally
+    await setupWatchers();
+  } catch (err) {
+    console.error("Periodic rescan failed:", err);
+  }
+}
+
+export async function initWatcher(): Promise<() => void> {
+  const state = getWatcherState();
+
+  // If watchers already exist from a previous HMR cycle, skip full re-init
+  if (state.activeWatchers.size > 0) {
+    console.log(`Reusing ${state.activeWatchers.size} existing watchers (HMR-safe)`);
+    // Still do an incremental rescan to pick up any new directories
+    await setupWatchers();
+  } else {
+    console.log("Initializing filesystem watcher...");
+    await setupWatchers();
+  }
+
+  // Clear any existing rescan timer before setting a new one
+  if (state.rescanTimer) {
+    clearInterval(state.rescanTimer);
+  }
+
+  // Schedule periodic rescans
+  state.rescanTimer = setInterval(periodicRescan, RESCAN_INTERVAL_MS);
+
+  // Return cleanup function
+  return () => {
+    console.log("Cleaning up filesystem watcher...");
+
+    // Clear rescan timer
+    if (state.rescanTimer) {
+      clearInterval(state.rescanTimer);
+      state.rescanTimer = null;
+    }
+
+    // Clear debounce timers
+    for (const timer of state.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    state.debounceTimers.clear();
+
+    // Close all watchers
+    for (const watcher of state.activeWatchers.values()) {
+      watcher.close();
+    }
+    state.activeWatchers.clear();
+
+    // Remove all event listeners
+    watcherEvents.removeAllListeners();
+  };
+}
+
+// Get watcher stats for debugging
+export function getWatcherStats() {
+  const state = getWatcherState();
+  return {
+    activeWatchers: state.activeWatchers.size,
+    watchedPaths: Array.from(state.activeWatchers.keys()),
+    pendingDebounces: state.debounceTimers.size,
+  };
+}

package/src/test/fixtures.ts

@@ -0,0 +1,269 @@
+import type {
+  Run,
+  RunStatus,
+  TaskEffect,
+  TaskKind,
+  TaskStatus,
+  TaskDetail,
+  JournalEvent,
+  EventType,
+  ProjectSummary,
+  RunDigest,
+} from '@/types';
+import type { BreakpointPayload } from '@/types/breakpoint';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let idCounter = 0;
+
+function nextId(prefix = 'test'): string {
+  idCounter += 1;
+  return `${prefix}-${String(idCounter).padStart(6, '0')}`;
+}
+
+/** Reset the ID counter between test suites if needed. */
+export function resetIdCounter(): void {
+  idCounter = 0;
+}
+
+function isoNow(offsetMs = 0): string {
+  return new Date(Date.now() + offsetMs).toISOString();
+}
+
+// ---------------------------------------------------------------------------
+// TaskEffect factory
+// ---------------------------------------------------------------------------
+
+export interface CreateMockTaskEffectOptions {
+  effectId?: string;
+  kind?: TaskKind;
+  title?: string;
+  label?: string;
+  status?: TaskStatus;
+  invocationKey?: string;
+  stepId?: string;
+  taskId?: string;
+  requestedAt?: string;
+  resolvedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  duration?: number;
+  error?: { name: string; message: string; stack?: string };
+  breakpointQuestion?: string;
+  agent?: { name: string; prompt?: { role: string; task: string; instructions: string[] } };
+}
+
+export function createMockTaskEffect(overrides: CreateMockTaskEffectOptions = {}): TaskEffect {
+  const id = overrides.effectId ?? nextId('eff');
+  const status = overrides.status ?? 'resolved';
+  const requestedAt = overrides.requestedAt ?? isoNow(-5000);
+  const resolvedAt =
+    status === 'resolved' ? (overrides.resolvedAt ?? isoNow(-1000)) : overrides.resolvedAt;
+
+  return {
+    effectId: id,
+    kind: overrides.kind ?? 'node',
+    title: overrides.title ?? `Task ${id}`,
+    label: overrides.label ?? `run-task-${id}`,
+    status,
+    invocationKey: overrides.invocationKey ?? nextId('inv'),
+    stepId: overrides.stepId ?? nextId('step'),
+    taskId: overrides.taskId ?? nextId('task'),
+    requestedAt,
+    resolvedAt,
+    startedAt: overrides.startedAt ?? requestedAt,
+    finishedAt: overrides.finishedAt ?? resolvedAt,
+    duration: overrides.duration ?? 4000,
+    error: overrides.error,
+    breakpointQuestion: overrides.breakpointQuestion,
+    agent: overrides.agent,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// JournalEvent factory
+// ---------------------------------------------------------------------------
+
+export interface CreateMockJournalEventOptions {
+  seq?: number;
+  id?: string;
+  ts?: string;
+  type?: EventType;
+  payload?: Record<string, unknown>;
+}
+
+export function createMockJournalEvent(
+  overrides: CreateMockJournalEventOptions = {},
+): JournalEvent {
+  return {
+    seq: overrides.seq ?? 1,
+    id: overrides.id ?? nextId('evt'),
+    ts: overrides.ts ?? isoNow(),
+    type: overrides.type ?? 'EFFECT_REQUESTED',
+    payload: overrides.payload ?? { effectId: nextId('eff') },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Run factory
+// ---------------------------------------------------------------------------
+
+export interface CreateMockRunOptions {
+  runId?: string;
+  processId?: string;
+  status?: RunStatus;
+  createdAt?: string;
+  updatedAt?: string;
+  completedAt?: string;
+  sessionId?: string;
+  tasks?: TaskEffect[];
+  events?: JournalEvent[];
+  totalTasks?: number;
+  completedTasks?: number;
+  failedTasks?: number;
+  duration?: number;
+  failedStep?: string;
+  breakpointQuestion?: string;
+  sourceLabel?: string;
+  projectName?: string;
+  isStale?: boolean;
+  waitingKind?: 'breakpoint' | 'task';
+}
+
+export function createMockRun(overrides: CreateMockRunOptions = {}): Run {
+  const tasks = overrides.tasks ?? [
+    createMockTaskEffect({ status: 'resolved', kind: 'node' }),
+    createMockTaskEffect({ status: 'resolved', kind: 'agent' }),
+    createMockTaskEffect({ status: 'requested', kind: 'shell' }),
+  ];
+
+  const completedTasks =
+    overrides.completedTasks ?? tasks.filter((t) => t.status === 'resolved').length;
+  const failedTasks =
+    overrides.failedTasks ?? tasks.filter((t) => t.status === 'error').length;
+
+  return {
+    runId: overrides.runId ?? nextId('run'),
+    processId: overrides.processId ?? 'data-pipeline/ingest',
+    status: overrides.status ?? 'completed',
+    createdAt: overrides.createdAt ?? isoNow(-60000),
+    updatedAt: overrides.updatedAt ?? isoNow(-1000),
+    completedAt: overrides.completedAt,
+    sessionId: overrides.sessionId ?? nextId('session'),
+    tasks,
+    events: overrides.events ?? [
+      createMockJournalEvent({ type: 'RUN_CREATED', seq: 0 }),
+      createMockJournalEvent({ type: 'EFFECT_REQUESTED', seq: 1 }),
+      createMockJournalEvent({ type: 'EFFECT_RESOLVED', seq: 2 }),
+    ],
+    totalTasks: overrides.totalTasks ?? tasks.length,
+    completedTasks,
+    failedTasks,
+    duration: overrides.duration ?? 59000,
+    failedStep: overrides.failedStep,
+    breakpointQuestion: overrides.breakpointQuestion,
+    sourceLabel: overrides.sourceLabel ?? 'cli',
+    projectName: overrides.projectName ?? 'my-project',
+    isStale: overrides.isStale,
+    waitingKind: overrides.waitingKind,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// TaskDetail factory (extends TaskEffect with extra fields)
+// ---------------------------------------------------------------------------
+
+export interface CreateMockTaskDetailOptions extends CreateMockTaskEffectOptions {
+  input?: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  stdout?: string;
+  stderr?: string;
+  taskDef?: Record<string, unknown>;
+  breakpoint?: BreakpointPayload;
+}
+
+export function createMockTaskDetail(overrides: CreateMockTaskDetailOptions = {}): TaskDetail {
+  const base = createMockTaskEffect(overrides);
+
+  return {
+    ...base,
+    input: overrides.input ?? { query: 'test input' },
+    result: overrides.result ?? { output: 'test output', exitCode: 0 },
+    stdout: overrides.stdout ?? 'Hello from stdout\n',
+    stderr: overrides.stderr ?? '',
+    taskDef: overrides.taskDef,
+    breakpoint: overrides.breakpoint,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// ProjectSummary factory
+// ---------------------------------------------------------------------------
+
+export interface CreateMockProjectSummaryOptions {
+  projectName?: string;
+  totalRuns?: number;
+  activeRuns?: number;
+  completedRuns?: number;
+  failedRuns?: number;
+  staleRuns?: number;
+  totalTasks?: number;
+  completedTasksAggregate?: number;
+  latestUpdate?: string;
+}
+
+export function createMockProjectSummary(
+  overrides: CreateMockProjectSummaryOptions = {},
+): ProjectSummary {
+  return {
+    projectName: overrides.projectName ?? 'my-project',
+    totalRuns: overrides.totalRuns ?? 10,
+    activeRuns: overrides.activeRuns ?? 2,
+    completedRuns: overrides.completedRuns ?? 7,
+    failedRuns: overrides.failedRuns ?? 1,
+    staleRuns: overrides.staleRuns ?? 0,
+    totalTasks: overrides.totalTasks ?? 50,
+    completedTasksAggregate: overrides.completedTasksAggregate ?? 45,
+    latestUpdate: overrides.latestUpdate ?? isoNow(),
+    pendingBreakpoints: 0,
+    breakpointRuns: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// RunDigest factory
+// ---------------------------------------------------------------------------
+
+export interface CreateMockRunDigestOptions {
+  runId?: string;
+  latestSeq?: number;
+  status?: RunStatus;
+  taskCount?: number;
+  completedTasks?: number;
+  updatedAt?: string;
+  pendingBreakpoints?: number;
+  breakpointQuestion?: string;
+  sourceLabel?: string;
+  projectName?: string;
+  isStale?: boolean;
+  waitingKind?: 'breakpoint' | 'task';
+}
+
+export function createMockRunDigest(overrides: CreateMockRunDigestOptions = {}): RunDigest {
+  return {
+    runId: overrides.runId ?? nextId('run'),
+    latestSeq: overrides.latestSeq ?? 5,
+    status: overrides.status ?? 'completed',
+    taskCount: overrides.taskCount ?? 3,
+    completedTasks: overrides.completedTasks ?? 3,
+    updatedAt: overrides.updatedAt ?? isoNow(),
+    pendingBreakpoints: overrides.pendingBreakpoints,
+    breakpointQuestion: overrides.breakpointQuestion,
+    sourceLabel: overrides.sourceLabel ?? 'cli',
+    projectName: overrides.projectName ?? 'my-project',
+    isStale: overrides.isStale,
+    waitingKind: overrides.waitingKind,
+  };
+}

package/src/test/mocks/handlers.ts

@@ -0,0 +1,110 @@
+import { http, HttpResponse } from 'msw';
+import {
+  createMockRun,
+  createMockTaskDetail,
+  createMockJournalEvent,
+  createMockProjectSummary,
+} from '../fixtures';
+
+// Pre-built mock data so handlers return consistent references
+const mockRun = createMockRun({ runId: 'run-abc-123', projectName: 'my-project' });
+const mockTaskDetail = createMockTaskDetail({ effectId: 'eff-001', kind: 'node' });
+const mockEvents = [
+  createMockJournalEvent({ seq: 0, type: 'RUN_CREATED' }),
+  createMockJournalEvent({ seq: 1, type: 'EFFECT_REQUESTED' }),
+  createMockJournalEvent({ seq: 2, type: 'EFFECT_RESOLVED' }),
+  createMockJournalEvent({ seq: 3, type: 'RUN_COMPLETED' }),
+];
+const mockProjects = [
+  createMockProjectSummary({ projectName: 'my-project', totalRuns: 5, activeRuns: 1 }),
+  createMockProjectSummary({ projectName: 'other-project', totalRuns: 3, activeRuns: 0 }),
+];
+
+export const handlers = [
+  // GET /api/runs — returns run list (supports ?mode=projects)
+  http.get('/api/runs', ({ request }) => {
+    const url = new URL(request.url);
+    const mode = url.searchParams.get('mode');
+
+    if (mode === 'projects') {
+      return HttpResponse.json({ projects: mockProjects });
+    }
+
+    const project = url.searchParams.get('project');
+    if (project) {
+      const filtered = [mockRun].filter((r) => r.projectName === project);
+      return HttpResponse.json({ runs: filtered, totalCount: filtered.length, project });
+    }
+
+    return HttpResponse.json({ runs: [mockRun], totalCount: 1 });
+  }),
+
+  // GET /api/runs/:runId — returns single run
+  http.get('/api/runs/:runId', ({ params }) => {
+    const { runId } = params;
+    if (runId === mockRun.runId) {
+      return HttpResponse.json({ run: mockRun });
+    }
+    return HttpResponse.json({ error: 'Run not found' }, { status: 404 });
+  }),
+
+  // GET /api/runs/:runId/events — returns journal events
+  http.get('/api/runs/:runId/events', () => {
+    return HttpResponse.json({ events: mockEvents, total: mockEvents.length });
+  }),
+
+  // GET /api/runs/:runId/tasks/:effectId — returns task detail
+  http.get('/api/runs/:runId/tasks/:effectId', ({ params }) => {
+    const { effectId } = params;
+    if (effectId === mockTaskDetail.effectId) {
+      return HttpResponse.json({ task: mockTaskDetail });
+    }
+    return HttpResponse.json({ error: 'Task not found' }, { status: 404 });
+  }),
+
+  // POST /api/runs/:runId/tasks/:effectId/resolve — resolve a breakpoint
+  http.post('/api/runs/:runId/tasks/:effectId/resolve', async ({ request }) => {
+    const body = (await request.json()) as { approved: boolean; value?: string };
+    return HttpResponse.json({ success: true, approved: body.approved });
+  }),
+
+  // GET /api/config — returns observer config
+  http.get('/api/config', () => {
+    return HttpResponse.json({
+      sources: [{ path: '/tmp/test-project', depth: 2, label: 'test' }],
+      port: 4800,
+      pollInterval: 2000,
+      theme: 'dark',
+      staleThresholdMs: 3600000,
+    });
+  }),
+
+  // POST /api/config — update observer config
+  http.post('/api/config', async ({ request }) => {
+    const body = (await request.json()) as Record<string, unknown>;
+    return HttpResponse.json({
+      sources: body.sources ?? [],
+      port: 4800,
+      pollInterval: (body.pollInterval as number) ?? 2000,
+      theme: (body.theme as string) ?? 'dark',
+      staleThresholdMs: (body.staleThresholdMs as number) ?? 3600000,
+    });
+  }),
+
+  // GET /api/digest — lightweight polling digest
+  http.get('/api/digest', () => {
+    return HttpResponse.json({
+      runs: [
+        {
+          runId: mockRun.runId,
+          latestSeq: 3,
+          status: mockRun.status,
+          taskCount: mockRun.totalTasks,
+          completedTasks: mockRun.completedTasks,
+          updatedAt: mockRun.updatedAt,
+          projectName: mockRun.projectName,
+        },
+      ],
+    });
+  }),
+];

package/src/test/mocks/server.ts

@@ -0,0 +1,17 @@
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+/**
+ * MSW server instance for use in Vitest (Node environment).
+ *
+ * Usage in tests:
+ *
+ *   import { server } from '@/test/mocks/server';
+ *
+ *   beforeAll(() => server.listen());
+ *   afterEach(() => server.resetHandlers());
+ *   afterAll(() => server.close());
+ *
+ * Or import the setup in vitest.config.ts setupFiles for global availability.
+ */
+export const server = setupServer(...handlers);