opencode-dashboard 0.1.0

package/server/routes.ts

@@ -0,0 +1,520 @@
+/**
+ * Dashboard Server - Route Handlers
+ *
+ * Implements all 7 HTTP endpoints:
+ *
+ * Plugin API (internal):
+ *   POST   /api/plugin/register   - Plugin registers with { projectPath, projectName }
+ *   POST   /api/plugin/event      - Plugin pushes an event { pluginId, event, data }
+ *   POST   /api/plugin/heartbeat  - Plugin sends { pluginId }
+ *   DELETE /api/plugin/:id        - Plugin deregisters on shutdown
+ *
+ * Dashboard API (public):
+ *   GET    /api/state             - Full board state as JSON
+ *   GET    /api/events            - SSE stream for real-time updates
+ *   GET    /api/health            - Server health check
+ */
+
+import { StateManager } from "./state";
+import {
+  broadcast,
+  createSSEResponse,
+  closeAllClients,
+  clientCount,
+  reset as resetSSE,
+} from "./sse";
+import { join } from "path";
+
+// --- Static File Serving ---
+
+/**
+ * Directory containing the pre-built Vite frontend.
+ * In production (npm install), this is `../dist/` relative to server/.
+ */
+const DIST_DIR = join(import.meta.dir, "../dist");
+
+/** Content-type map for static file extensions */
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+// --- State Management ---
+
+/** Central state manager — processes events and persists to disk */
+export const stateManager = new StateManager();
+
+// --- Plugin Registry ---
+
+interface PluginRecord {
+  pluginId: string;
+  projectPath: string;
+  projectName: string;
+  registeredAt: number;
+  lastHeartbeat: number;
+}
+
+/** Registered plugins, keyed by pluginId */
+const plugins = new Map<string, PluginRecord>();
+
+/** Server start time for uptime calculation */
+const startTime = Date.now();
+
+// --- Helpers ---
+
+/** Add CORS headers for localhost origins */
+function corsHeaders(origin?: string | null): Record<string, string> {
+  // Allow any localhost origin for development
+  const allowedOrigin =
+    origin && /^https?:\/\/localhost(:\d+)?$/.test(origin) ? origin : "*";
+  return {
+    "Access-Control-Allow-Origin": allowedOrigin,
+    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type",
+  };
+}
+
+/** Create a JSON response with CORS headers */
+function json(
+  data: unknown,
+  status: number = 200,
+  origin?: string | null
+): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      "Content-Type": "application/json",
+      ...corsHeaders(origin),
+    },
+  });
+}
+
+/** Parse JSON body safely, returning null on failure */
+async function parseBody(req: Request): Promise<unknown | null> {
+  try {
+    return await req.json();
+  } catch {
+    return null;
+  }
+}
+
+/** Generate a UUID v4 */
+function generateId(): string {
+  return crypto.randomUUID();
+}
+
+// --- Route Handlers ---
+
+/**
+ * POST /api/plugin/register
+ *
+ * Plugin registers with { projectPath, projectName }.
+ * Returns { pluginId }.
+ */
+async function handleRegister(
+  req: Request,
+  origin?: string | null
+): Promise<Response> {
+  const body = await parseBody(req);
+
+  if (!body || typeof body !== "object") {
+    return json({ error: "Invalid JSON body" }, 400, origin);
+  }
+
+  const { projectPath, projectName } = body as Record<string, unknown>;
+
+  if (!projectPath || typeof projectPath !== "string") {
+    return json(
+      { error: "Missing or invalid 'projectPath' (must be a non-empty string)" },
+      400,
+      origin
+    );
+  }
+
+  if (!projectName || typeof projectName !== "string") {
+    return json(
+      { error: "Missing or invalid 'projectName' (must be a non-empty string)" },
+      400,
+      origin
+    );
+  }
+
+  const pluginId = generateId();
+  const now = Date.now();
+
+  plugins.set(pluginId, {
+    pluginId,
+    projectPath,
+    projectName,
+    registeredAt: now,
+    lastHeartbeat: now,
+  });
+
+  // Register in state manager (creates or re-activates project)
+  stateManager.registerPlugin(pluginId, projectPath, projectName);
+
+  console.log(
+    `[server] Plugin registered: ${pluginId} (${projectName} @ ${projectPath})`
+  );
+
+  // Broadcast connection to SSE clients
+  broadcast("project:connected", {
+    projectPath,
+    projectName,
+    pluginId,
+  });
+
+  return json({ pluginId }, 200, origin);
+}
+
+/**
+ * POST /api/plugin/event
+ *
+ * Plugin pushes an event { pluginId, event, data }.
+ * Server updates state + broadcasts to SSE.
+ */
+async function handleEvent(
+  req: Request,
+  origin?: string | null
+): Promise<Response> {
+  const body = await parseBody(req);
+
+  if (!body || typeof body !== "object") {
+    return json({ error: "Invalid JSON body" }, 400, origin);
+  }
+
+  const { pluginId, event, data } = body as Record<string, unknown>;
+
+  if (!pluginId || typeof pluginId !== "string") {
+    return json(
+      { error: "Missing or invalid 'pluginId' (must be a non-empty string)" },
+      400,
+      origin
+    );
+  }
+
+  if (!event || typeof event !== "string") {
+    return json(
+      { error: "Missing or invalid 'event' (must be a non-empty string)" },
+      400,
+      origin
+    );
+  }
+
+  // Verify plugin is registered
+  const plugin = plugins.get(pluginId);
+  if (!plugin) {
+    return json({ error: `Unknown pluginId: ${pluginId}` }, 404, origin);
+  }
+
+  // Update heartbeat on any event
+  plugin.lastHeartbeat = Date.now();
+
+  // Process event through state manager (updates canonical state)
+  const isPlainObject =
+    data != null && typeof data === "object" && !Array.isArray(data);
+  const eventData = isPlainObject
+    ? (data as Record<string, unknown>)
+    : { data };
+
+  const processed = stateManager.processEvent(pluginId, event, eventData);
+
+  // Broadcast to all SSE clients — use state-enriched data if available
+  if (processed) {
+    broadcast(processed.event, {
+      ...processed.data,
+      _serverTimestamp: Date.now(),
+    });
+
+    // If beads:refreshed reconciled stale beads, broadcast individual
+    // bead:removed events so connected frontends remove them from the board.
+    if (
+      processed.event === "beads:refreshed" &&
+      Array.isArray(processed.data.removedBeadIds) &&
+      (processed.data.removedBeadIds as string[]).length > 0
+    ) {
+      const ts = Date.now();
+      for (const beadId of processed.data.removedBeadIds as string[]) {
+        broadcast("bead:removed", {
+          beadId,
+          projectPath: plugin.projectPath,
+          pipelineId: "default",
+          _reconciled: true,
+          _serverTimestamp: ts,
+        });
+      }
+      console.log(
+        `[server] Reconciled ${(processed.data.removedBeadIds as string[]).length} stale bead(s) for ${plugin.projectName}`
+      );
+    }
+  } else {
+    // Fallback: enrich and broadcast directly (unknown plugin in state)
+    const enrichedData = {
+      ...eventData,
+      projectPath: plugin.projectPath,
+      _serverTimestamp: Date.now(),
+    };
+    broadcast(event, enrichedData);
+  }
+
+  console.log(`[server] Event from ${pluginId}: ${event}`);
+
+  return json({ ok: true }, 200, origin);
+}
+
+/**
+ * POST /api/plugin/heartbeat
+ *
+ * Plugin sends { pluginId }. Server updates lastHeartbeat.
+ */
+async function handleHeartbeat(
+  req: Request,
+  origin?: string | null
+): Promise<Response> {
+  const body = await parseBody(req);
+
+  if (!body || typeof body !== "object") {
+    return json({ error: "Invalid JSON body" }, 400, origin);
+  }
+
+  const { pluginId } = body as Record<string, unknown>;
+
+  if (!pluginId || typeof pluginId !== "string") {
+    return json(
+      { error: "Missing or invalid 'pluginId' (must be a non-empty string)" },
+      400,
+      origin
+    );
+  }
+
+  const plugin = plugins.get(pluginId);
+  if (!plugin) {
+    return json({ error: `Unknown pluginId: ${pluginId}` }, 404, origin);
+  }
+
+  plugin.lastHeartbeat = Date.now();
+  stateManager.updateHeartbeat(pluginId);
+
+  return json({ ok: true }, 200, origin);
+}
+
+/**
+ * DELETE /api/plugin/:id
+ *
+ * Plugin deregisters on shutdown. Removes from state.
+ */
+function handleDeregister(
+  pluginId: string,
+  origin?: string | null
+): Response {
+  const plugin = plugins.get(pluginId);
+  if (!plugin) {
+    return json({ error: `Unknown pluginId: ${pluginId}` }, 404, origin);
+  }
+
+  plugins.delete(pluginId);
+
+  // Mark project as disconnected in state (retains last-known state)
+  stateManager.deregisterPlugin(pluginId);
+
+  console.log(
+    `[server] Plugin deregistered: ${pluginId} (${plugin.projectName})`
+  );
+
+  // Broadcast disconnection to SSE clients
+  broadcast("project:disconnected", {
+    projectPath: plugin.projectPath,
+    pluginId,
+  });
+
+  return json({ ok: true }, 200, origin);
+}
+
+/**
+ * GET /api/state
+ *
+ * Returns full board state as JSON (all projects, all pipelines, all beads).
+ */
+function handleState(origin?: string | null): Response {
+  return json(stateManager.toJSON(), 200, origin);
+}
+
+/**
+ * GET /api/events
+ *
+ * SSE stream for real-time updates.
+ * Sends "connected" + "state:full" events immediately, then streams updates.
+ */
+function handleEvents(origin?: string | null): Response {
+  return createSSEResponse(
+    () =>
+      Array.from(plugins.values()).map((p) => ({
+        pluginId: p.pluginId,
+        projectPath: p.projectPath,
+        projectName: p.projectName,
+      })),
+    () => stateManager.toJSON(),
+    origin,
+    corsHeaders
+  );
+}
+
+/**
+ * GET /api/health
+ *
+ * Server health check.
+ */
+function handleHealth(origin?: string | null): Response {
+  return json(
+    {
+      status: "ok",
+      uptime: Math.floor((Date.now() - startTime) / 1000),
+      plugins: plugins.size,
+      sseClients: clientCount(),
+    },
+    200,
+    origin
+  );
+}
+
+// --- Router ---
+
+/**
+ * Extract pluginId from a DELETE /api/plugin/:id path.
+ * Returns the id portion or null if the path doesn't match.
+ */
+function extractPluginId(pathname: string): string | null {
+  const match = pathname.match(/^\/api\/plugin\/([^/]+)$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Main request router.
+ *
+ * Routes incoming requests to the appropriate handler based on
+ * method and pathname. Returns a 404 for unmatched routes.
+ */
+export async function handleRequest(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const { pathname } = url;
+  const method = req.method;
+  const origin = req.headers.get("Origin");
+
+  // Handle CORS preflight
+  if (method === "OPTIONS") {
+    return new Response(null, {
+      status: 204,
+      headers: corsHeaders(origin),
+    });
+  }
+
+  // --- Plugin API ---
+
+  if (pathname === "/api/plugin/register" && method === "POST") {
+    return handleRegister(req, origin);
+  }
+
+  if (pathname === "/api/plugin/event" && method === "POST") {
+    return handleEvent(req, origin);
+  }
+
+  if (pathname === "/api/plugin/heartbeat" && method === "POST") {
+    return handleHeartbeat(req, origin);
+  }
+
+  // DELETE /api/plugin/:id — must come after the specific plugin sub-routes
+  if (method === "DELETE") {
+    const pluginId = extractPluginId(pathname);
+    if (pluginId) {
+      return handleDeregister(pluginId, origin);
+    }
+  }
+
+  // --- Dashboard API ---
+
+  if (pathname === "/api/state" && method === "GET") {
+    return handleState(origin);
+  }
+
+  if (pathname === "/api/events" && method === "GET") {
+    return handleEvents(origin);
+  }
+
+  if (pathname === "/api/health" && method === "GET") {
+    return handleHealth(origin);
+  }
+
+  // --- Static File Serving (pre-built frontend) ---
+
+  if (method === "GET" && !pathname.startsWith("/api/")) {
+    const filePath = join(DIST_DIR, pathname === "/" ? "index.html" : pathname);
+    const file = Bun.file(filePath);
+    if (await file.exists()) {
+      const ext = filePath.substring(filePath.lastIndexOf("."));
+      return new Response(file, {
+        headers: {
+          "Content-Type": MIME_TYPES[ext] || "application/octet-stream",
+        },
+      });
+    }
+    // SPA fallback: serve index.html for client-side routing
+    const indexFile = Bun.file(join(DIST_DIR, "index.html"));
+    if (await indexFile.exists()) {
+      return new Response(indexFile, {
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+  }
+
+  // --- Not Found ---
+
+  return json({ error: "Not found", path: pathname }, 404, origin);
+}
+
+// --- Exports for testing / external access ---
+
+export { plugins, broadcast, closeAllClients as closeAllSSEClients, resetSSE };
+
+// --- Plugin Health Monitoring ---
+
+/**
+ * Periodically check plugin heartbeats.
+ * Plugins that haven't sent a heartbeat within 45 seconds are marked
+ * as disconnected (state retained, but connection badge shows DISCONNECTED).
+ */
+const PLUGIN_HEALTH_CHECK_INTERVAL_MS = 30_000;
+const PLUGIN_HEARTBEAT_TIMEOUT_MS = 45_000;
+
+const pluginHealthInterval = setInterval(() => {
+  const now = Date.now();
+  for (const [pluginId, plugin] of plugins) {
+    if (now - plugin.lastHeartbeat > PLUGIN_HEARTBEAT_TIMEOUT_MS) {
+      console.log(
+        `[server] Plugin ${pluginId} (${plugin.projectName}) heartbeat timeout — marking disconnected`
+      );
+      plugins.delete(pluginId);
+      stateManager.deregisterPlugin(pluginId);
+      broadcast("project:disconnected", {
+        projectPath: plugin.projectPath,
+        pluginId,
+        reason: "heartbeat_timeout",
+      });
+    }
+  }
+}, PLUGIN_HEALTH_CHECK_INTERVAL_MS);
+
+pluginHealthInterval.unref();
+
+/**
+ * Stop plugin health monitoring (for graceful shutdown).
+ */
+export function stopHealthMonitoring(): void {
+  clearInterval(pluginHealthInterval);
+}

package/server/sse.ts

@@ -0,0 +1,196 @@
+/**
+ * Dashboard Server - SSE Client Management & Broadcasting
+ *
+ * Manages Server-Sent Events connections to dashboard browser clients.
+ * Handles:
+ * - Client connection/disconnection tracking
+ * - Event broadcasting to all connected clients
+ * - SSE heartbeat for stale client detection
+ * - state:full snapshot delivery on connect
+ * - Graceful shutdown
+ */
+
+// --- Types ---
+
+export interface SSEClient {
+  controller: ReadableStreamDefaultController<Uint8Array>;
+  connectedAt: number;
+}
+
+// --- SSE Manager ---
+
+/** SSE message ID counter for reconnection support */
+let messageId = 0;
+
+/** Connected SSE clients */
+const clients = new Set<SSEClient>();
+
+const encoder = new TextEncoder();
+
+/**
+ * Get the current number of connected SSE clients.
+ */
+export function clientCount(): number {
+  return clients.size;
+}
+
+/**
+ * Get the current SSE message ID (for testing/debugging).
+ */
+export function currentMessageId(): number {
+  return messageId;
+}
+
+/**
+ * Broadcast a named SSE event to all connected clients.
+ *
+ * Format:
+ *   id: <messageId>
+ *   event: <eventName>
+ *   data: <JSON string>
+ *
+ * Clients that fail to receive the message are automatically removed.
+ */
+export function broadcast(eventName: string, data: unknown): void {
+  messageId++;
+  const msg = `id: ${messageId}\nevent: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`;
+  const encoded = encoder.encode(msg);
+
+  for (const client of clients) {
+    try {
+      client.controller.enqueue(encoded);
+    } catch {
+      clients.delete(client);
+    }
+  }
+}
+
+/**
+ * Create an SSE Response for a new client connection.
+ *
+ * Sends:
+ * 1. `retry: 3000` directive (reconnect interval)
+ * 2. `connected` event with metadata
+ * 3. `state:full` event with complete state snapshot
+ *
+ * @param getPlugins - Function returning current plugin list (avoids circular deps)
+ * @param getState - Function returning serialized state snapshot
+ * @param origin - Request Origin header for CORS
+ * @param corsHeaders - Function to generate CORS headers
+ */
+export function createSSEResponse(
+  getPlugins: () => Array<{
+    pluginId: string;
+    projectPath: string;
+    projectName: string;
+  }>,
+  getState: () => unknown,
+  origin: string | null | undefined,
+  corsHeadersFn: (origin?: string | null) => Record<string, string>
+): Response {
+  let sseClient: SSEClient;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      sseClient = {
+        controller,
+        connectedAt: Date.now(),
+      };
+      clients.add(sseClient);
+
+      // Set reconnect interval
+      controller.enqueue(encoder.encode("retry: 3000\n\n"));
+
+      // Send connection confirmation with current plugin list
+      messageId++;
+      const connectMsg = encoder.encode(
+        `id: ${messageId}\nevent: connected\ndata: ${JSON.stringify({
+          message: "SSE connected",
+          timestamp: Date.now(),
+          plugins: getPlugins(),
+        })}\n\n`
+      );
+      controller.enqueue(connectMsg);
+
+      // Send full state snapshot for initial load / reconnection
+      messageId++;
+      const stateMsg = encoder.encode(
+        `id: ${messageId}\nevent: state:full\ndata: ${JSON.stringify(getState())}\n\n`
+      );
+      controller.enqueue(stateMsg);
+    },
+    cancel() {
+      if (sseClient) {
+        clients.delete(sseClient);
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      ...corsHeadersFn(origin),
+    },
+  });
+}
+
+// --- SSE Heartbeat ---
+
+/**
+ * Periodic SSE heartbeat to detect and clean up stale clients.
+ * SSE comment lines (starting with ':') are ignored by EventSource
+ * but keep the connection alive and detect disconnects.
+ */
+const SSE_HEARTBEAT_INTERVAL_MS = 30_000;
+
+const sseHeartbeatInterval = setInterval(() => {
+  const heartbeat = encoder.encode(`: heartbeat ${Date.now()}\n\n`);
+  for (const client of clients) {
+    try {
+      client.controller.enqueue(heartbeat);
+    } catch {
+      clients.delete(client);
+    }
+  }
+}, SSE_HEARTBEAT_INTERVAL_MS);
+
+// Don't prevent the process from exiting when this is the only pending timer
+sseHeartbeatInterval.unref();
+
+/**
+ * Gracefully close all SSE connections and clean up resources.
+ * Called during server shutdown.
+ */
+export function closeAllClients(): void {
+  clearInterval(sseHeartbeatInterval);
+  for (const client of clients) {
+    try {
+      client.controller.close();
+    } catch {
+      // already closed
+    }
+  }
+  clients.clear();
+}
+
+/**
+ * Reset SSE state for testing.
+ * Removes all clients and resets the message ID counter.
+ */
+export function reset(): void {
+  for (const client of clients) {
+    try {
+      client.controller.close();
+    } catch {
+      // already closed
+    }
+  }
+  clients.clear();
+  messageId = 0;
+}
+
+// --- Exports for testing ---
+
+export { clients };