feat: Claude Code Monitor — lanes, pipelines and a merged workspace

Internal SmartGift build of a Claude Code monitoring dashboard. Lanes: a durable unit of parallel agent work, one per working directory, tracked across session restarts. Managed lanes are git worktrees the dashboard provisions and can reset or remove behind a three-check destroy guard and a counted preflight; adopted lanes are directories you already own and are never destroyable. Pipelines: a lane moves through pipeline stages. A stage the agent declares with evidence renders green; a stage inferred from the tool-event stream renders dashed amber and never counts as done. Detection is forward-only within a 30-minute window, and never writes the declared stage. Workspace: one page at /run with a lane grid, the selected lane's pipeline, and a full Claude console behind a disclosure.
2026-07-29 17:07:45 +07:00
commit 57dc91585d
783 changed files with 221743 additions and 0 deletions
@@ -0,0 +1,146 @@
+/**
+ * @file eventBus.ts
+ * @description Implements a simple event bus for managing WebSocket messages and connection status in the agent dashboard application. It allows components to subscribe to real-time updates from the server and react to changes in WebSocket connectivity. The event bus maintains a list of handlers for incoming messages and connection status changes, providing a clean interface for publishing events and managing subscriptions.
+ *
+ * ## Design
+ * This is a module-level singleton (there is exactly one bus per browser tab) built on
+ * two `Set`s of callbacks. It exists to break the one-to-many coupling between the single
+ * WebSocket connection and the many UI components that care about it:
+ *   - The producer side is the `useWebSocket` hook, which owns the actual socket and calls
+ *     {@link eventBus.publish} for every inbound frame and {@link eventBus.setConnected}
+ *     on open/close.
+ *   - The consumer side is any component that calls {@link eventBus.subscribe} (for message
+ *     data) or {@link eventBus.onConnection} (for a connectivity indicator), typically from
+ *     a `useEffect`, and calls the returned unsubscribe function on cleanup.
+ *
+ * ## Why `Set` (not array)?
+ * A `Set` gives O(1) add/delete and, crucially, natural idempotency: subscribing the same
+ * handler reference twice registers it once, and the returned disposer removes exactly that
+ * reference. Handlers are notified in insertion order (Set iteration order).
+ *
+ * ## Delivery semantics
+ * Dispatch is synchronous and fire-and-forget: {@link eventBus.publish} iterates the current
+ * handler set and calls each in turn. There is no error isolation, so a handler that throws
+ * will abort the remaining handlers for that message - subscribers should keep their work
+ * cheap and defensive. There is also no buffering: a message published while nobody is
+ * subscribed is simply dropped.
+ *
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+/* =============================================================================
+ * MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
+ * =============================================================================
+ * **Purpose:** In-memory pub/sub bus bridging `useWebSocket` to any page without prop drilling.
+ *
+ * ## Design constraints
+ * - Local-first: no telemetry leaves the machine unless the user configures webhooks.
+ * - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
+ *   philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
+ * - Destructive flows stay behind explicit confirmation modals and server-side gates.
+ * - Internationalization: user-visible strings belong in i18n JSON, not literals here.
+ *
+ * ## Remote data & SSH
+ * Remote Data Sources let operators aggregate multiple machines. SSH entries describe
+ * how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
+ * scoped GET via `?sources=`. Health checks and import history surface in Settings.
+ *
+ * ## Observability
+ * Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
+ * provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
+ * Docker Compose profiles are documented in `monitoring/README.md`.
+ *
+ * ## Internal dependencies
+ * - `./types`
+ *
+ * ## Public surface
+ * - `eventBus` — exported API; see TSDoc on the symbol for behavior.
+ *
+ * ## Testing pointers
+ * - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
+ * - Server contract changes require `npm run test:server` and OpenAPI sync.
+ * - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
+ *
+ * ## Related docs
+ * - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
+ * - `docs/API.md` — REST reference.
+ * - `.claude/skills/file-headers/` — mandatory `@author` header policy.
+ * ============================================================================= */
+/* -----------------------------------------------------------------------------
+ * EXPORT CATALOG — quick index of symbols defined below (documentation only).
+ * -----------------------------------------------------------------------------
+ * **eventBus**
+ *   Part of this module's public contract. Downstream imports should treat
+ *   the signature and return type as stable unless release notes say otherwise.
+ *   When behavior changes, update the `@file` overview and relevant tests.
+ *
+ * ----------------------------------------------------------------------------- */
+
+import type { WSMessage } from "./types";
+
+/** Callback invoked with every message received from the dashboard WebSocket. */
+type Handler = (msg: WSMessage) => void;
+/** Callback invoked whenever the WebSocket connection state changes. */
+type ConnectionHandler = (connected: boolean) => void;
+
+// --- Module-private subscription state (the single source of truth per tab) ---
+/** All active message subscribers; iterated on every {@link eventBus.publish}. */
+const handlers = new Set<Handler>();
+/** All active connection-state subscribers; iterated on every {@link eventBus.setConnected}. */
+const connectionHandlers = new Set<ConnectionHandler>();
+/** Latest known socket state; the backing store for the {@link eventBus.connected} getter. */
+let wsConnected = false;
+
+/**
+ * Process-wide pub/sub singleton that decouples the single WebSocket
+ * connection (owned by `useWebSocket`, which calls {@link publish}/
+ * {@link setConnected}) from the many components that want to react to
+ * server pushes or show a connection indicator. Any number of components can
+ * {@link subscribe}/{@link onConnection} independently of whether they're
+ * mounted at the same time as the socket itself.
+ */
+export const eventBus = {
+  /**
+   * Registers a handler for every {@link WSMessage} the socket receives.
+   * @param handler Called synchronously with each message, in subscription order.
+   * @returns An unsubscribe function; call it (e.g. in a `useEffect` cleanup)
+   *   to stop receiving messages and avoid a memory leak.
+   */
+  subscribe(handler: Handler): () => void {
+    handlers.add(handler); // idempotent: re-adding the same reference is a no-op
+    return () => handlers.delete(handler); // disposer removes exactly this handler
+  },
+
+  /** Broadcasts `msg` to every currently-subscribed {@link Handler}. Called by
+   *  `useWebSocket` on each parsed inbound frame - not intended to be called
+   *  directly by UI code. Dispatch is synchronous and in subscription order; a
+   *  throwing handler aborts delivery to the handlers after it. */
+  publish(msg: WSMessage): void {
+    handlers.forEach((handler) => handler(msg)); // notify each subscriber in turn
+  },
+
+  /** Current WebSocket connection state, as last reported via {@link setConnected}. */
+  get connected(): boolean {
+    return wsConnected;
+  },
+
+  /** Updates the shared connection flag and notifies every {@link onConnection}
+   *  listener. Called by `useWebSocket` on socket open/close. */
+  setConnected(value: boolean): void {
+    wsConnected = value; // update the shared flag first so late reads see the new state
+    connectionHandlers.forEach((handler) => handler(value)); // then fan out the transition
+  },
+
+  /**
+   * Registers a handler for connection-state transitions (e.g. to drive a
+   * "reconnecting…" indicator).
+   * @param handler Called with the new connected state on every change.
+   * @returns An unsubscribe function.
+   * @remarks The handler fires only on subsequent {@link eventBus.setConnected} calls, not
+   *   immediately with the current value - read {@link eventBus.connected} once up front if
+   *   the initial state matters.
+   */
+  onConnection(handler: ConnectionHandler): () => void {
+    connectionHandlers.add(handler); // idempotent add (Set semantics)
+    return () => connectionHandlers.delete(handler); // disposer for useEffect cleanup
+  },
+};