vibepulse 0.1.12 → 0.2.1

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibepulse",
-  "version": "0.1.12",
+  "version": "0.2.1",
   "private": false,
   "description": "Real-time dashboard for monitoring and managing OpenCode sessions",
   "repository": {
@@ -26,7 +26,9 @@
     }
   },
   "scripts": {
-    "dev": "next dev -p 3456",
+    "dev": "node ./bin/dev-runtime.js",
+    "dev:hub": "node ./bin/dev-runtime.js hub",
+    "dev:node": "node ./bin/dev-runtime.js node",
     "build": "next build",
     "start": "next start -p 3456",
     "lint": "eslint",

package/.next/standalone/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/.next/standalone/src/AGENTS.md

@@ -0,0 +1,41 @@
+# SOURCE KNOWLEDGE BASE
+
+**Scope:** `src/`
+
+## OVERVIEW
+`src/` contains the application runtime (Next.js App Router), UI modules, realtime hooks, shared utilities, and the package export surface.
+
+## STRUCTURE
+```text
+src/
+├── app/                 # Next.js page/layout + API routes
+├── components/          # board UI and config experience
+├── hooks/               # realtime stream/cache integration
+├── lib/                 # discovery, transforms, config/profile IO
+├── test/                # test bootstrap (`setup.ts`)
+├── types/               # domain contracts
+└── index.ts             # publishable library exports
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Main page shell | `src/app/page.tsx` | top-level filters, mute, config panel state |
+| Backend API behavior | `src/app/api/` | route handlers and OpenCode integration |
+| Board data + degraded UX | `src/components/KanbanBoard.tsx` | polling, stale snapshot, errors |
+| Realtime event sync | `src/hooks/useOpencodeSync.ts` | SSE events + optimistic cache updates |
+| Session/card transforms | `src/lib/transform.ts` | source sessions -> kanban cards |
+| Library public surface | `src/index.ts` | only exported runtime API for package consumers |
+
+## CONVENTIONS
+- Keep Next.js route handlers under `src/app/api/**/route.ts`; avoid ad-hoc API helper entrypoints.
+- Keep tests co-located (`*.test.ts`, `*.test.tsx`); shared test runtime setup stays in `src/test/setup.ts`.
+- Keep package-facing exports centralized in `src/index.ts`.
+- Keep cross-module imports on `@/` alias instead of deep relative paths when crossing feature boundaries.
+- Keep profile/config persistence logic in `src/lib/profiles` and `src/lib/opencodeConfig.ts`, not in UI components.
+
+## ANTI-PATTERNS
+- Do not add new package exports outside `src/index.ts`; `build:lib` only compiles from that entry.
+- Do not bypass shared transform/discovery utilities by duplicating logic in page/components.
+- Do not keep extending known hotspots (`src/app/api/sessions/route.ts`, `src/components/KanbanBoard.tsx`) without extracting helpers.
+- Do not move tests to a separate global test tree; this codebase relies on co-location for context.

package/.next/standalone/src/app/api/AGENTS.md

@@ -0,0 +1,40 @@
+# API KNOWLEDGE BASE
+
+**Scope:** `src/app/api/`
+
+## OVERVIEW
+`src/app/api/` hosts Next.js route handlers that discover OpenCode instances, aggregate session state, stream events, and manage config/profile data.
+
+## STRUCTURE
+```text
+src/app/api/
+├── sessions/                     # session list/status aggregation
+│   └── [id]/                     # per-session read/archive/delete actions
+├── opencode-events/              # SSE fan-in endpoint
+├── opencode-config/              # config read/update + status helper
+├── opencode-models/              # model listing helpers
+└── profiles/                     # profile CRUD, apply, import/export
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Session list + parent/child merge | `src/app/api/sessions/route.ts` | 900+ line hub with sticky status logic |
+| Per-session archive/delete | `src/app/api/sessions/[id]/archive/route.ts`, `src/app/api/sessions/[id]/delete/route.ts` | mutation endpoints |
+| Realtime event proxy | `src/app/api/opencode-events/route.ts` | multi-port SSE connect + stream forwarding |
+| Config filtering + validation | `src/app/api/opencode-config/route.ts` | allowlists + sensitive-field rejection |
+| Profile import/export | `src/app/api/profiles/import/route.ts`, `src/app/api/profiles/[id]/export/route.ts` | schema validation + download response |
+
+## CONVENTIONS
+- Route shape is file-based: one handler module per `route.ts`.
+- Mutating resource actions are nested under resource id paths (`[id]/archive`, `[id]/delete`, `[id]/apply`, `[id]/export`).
+- OpenCode access is discovery-first (`discoverOpencodePortsWithMeta`), then best-effort across all discovered ports.
+- Error responses consistently use structured JSON with explicit HTTP statuses (`400` validation, `403` forbidden fields, `503` service unavailable).
+- API tests are co-located with handlers (for example `route.test.ts` next to `route.ts`).
+
+## ANTI-PATTERNS
+- Do not hardcode a single OpenCode port; all critical routes iterate discovered ports.
+- Do not accept secret-like config keys in `/api/opencode-config`; sensitive field names are explicitly blocked.
+- Do not add unknown config fields for agents/categories/vibepulse; handlers enforce per-field allowlists.
+- Do not skip rollback on profile import failures; import route restores index state when config write fails.
+- Do not collapse discovery timeout and not-found responses; handlers distinguish these cases for user guidance.

package/.next/standalone/src/app/api/node/events/route.test.ts

@@ -0,0 +1,196 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@opencode-ai/sdk', () => ({
+  createOpencodeClient: vi.fn(),
+}));
+
+vi.mock('@/lib/opencodeDiscovery', () => ({
+  discoverOpencodePortsWithMeta: vi.fn(),
+}));
+
+import { createOpencodeClient } from '@opencode-ai/sdk';
+import { discoverOpencodePortsWithMeta } from '@/lib/opencodeDiscovery';
+import { createNodeRequestHeaders } from '@/lib/nodeProtocol';
+
+import { GET } from './route';
+
+const mockCreateOpencodeClient: any = createOpencodeClient;
+const mockDiscoverPortsWithMeta: any = discoverOpencodePortsWithMeta;
+const mockGlobalEvent: any = vi.fn();
+
+function resetClientMock(): void {
+  mockCreateOpencodeClient.mockImplementation(() => ({
+    global: {
+      event: mockGlobalEvent,
+    },
+  }) as never);
+}
+
+describe('/api/node/events', () => {
+  const originalRuntimeRole = process.env.VIBEPULSE_RUNTIME_ROLE;
+  const originalNodeToken = process.env.VIBEPULSE_NODE_TOKEN;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env.VIBEPULSE_RUNTIME_ROLE = 'node';
+    process.env.VIBEPULSE_NODE_TOKEN = 'shared-secret';
+    mockDiscoverPortsWithMeta.mockReturnValue({ ports: [7777], timedOut: false });
+    resetClientMock();
+  });
+
+  afterEach(() => {
+    process.env.VIBEPULSE_RUNTIME_ROLE = originalRuntimeRole;
+    process.env.VIBEPULSE_NODE_TOKEN = originalNodeToken;
+  });
+
+  it('rejects unauthenticated requests before opening SSE streams', async () => {
+    const response = await GET(
+      new Request('http://localhost/api/node/events', {
+        headers: { 'x-vibepulse-node-version': '1' },
+      })
+    );
+    const data = await response.json();
+
+    expect(response.status).toBe(401);
+    expect(data).toEqual({
+      ok: false,
+      reason: 'unauthorized',
+      protocolVersion: '1',
+    });
+    expect(mockDiscoverPortsWithMeta.mock.calls).toHaveLength(0);
+    expect(mockGlobalEvent.mock.calls).toHaveLength(0);
+  });
+
+  it('accepts version-only requests when node token is unset', async () => {
+    process.env.VIBEPULSE_NODE_TOKEN = '   ';
+
+    mockGlobalEvent.mockResolvedValue({
+      stream: {
+        [Symbol.asyncIterator]() {
+          let emitted = false;
+          return {
+            async next() {
+              if (!emitted) {
+                emitted = true;
+                return { done: false, value: { type: 'session.status', timestamp: 1 } };
+              }
+              return { done: true, value: undefined };
+            },
+            async return() {
+              return { done: true, value: undefined };
+            },
+          };
+        },
+      },
+    });
+
+    const response = await GET(
+      new Request('http://localhost/api/node/events', {
+        headers: { 'x-vibepulse-node-version': '1' },
+      })
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe('text/event-stream');
+  });
+
+  it('streams local-only envelopes and aborts cleanly', async () => {
+    let receivedSignal: AbortSignal | undefined;
+    let returnCalls = 0;
+
+    mockGlobalEvent.mockImplementation(({ signal }: { signal: AbortSignal }) => {
+      receivedSignal = signal;
+      let emitted = false;
+
+      const stream: AsyncIterable<unknown> = {
+        [Symbol.asyncIterator]() {
+          return {
+            async next() {
+              if (!emitted) {
+                emitted = true;
+                return {
+                  done: false,
+                  value: {
+                    payload: {
+                      type: 'session.status',
+                      properties: {
+                        sessionID: 'parent-1',
+                        status: { type: 'busy' },
+                      },
+                      timestamp: 123,
+                    },
+                    directory: '/repo/project-one',
+                  },
+                };
+              }
+
+              return await new Promise((resolve) => {
+                signal.addEventListener(
+                  'abort',
+                  () => resolve({ done: true, value: undefined }),
+                  { once: true }
+                );
+              });
+            },
+            async return() {
+              returnCalls += 1;
+              return { done: true, value: undefined };
+            },
+          };
+        },
+      };
+
+      return Promise.resolve({ stream });
+    });
+
+    const requestController = new AbortController();
+    const response = await GET(
+      new Request('http://localhost/api/node/events', {
+        headers: createNodeRequestHeaders('shared-secret'),
+        signal: requestController.signal,
+      })
+    );
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe('text/event-stream');
+
+    const reader = response.body?.getReader();
+    expect(reader).toBeTruthy();
+
+    const firstChunk = await reader!.read();
+    const text = new TextDecoder().decode(firstChunk.value);
+    expect(text.startsWith('data: ')).toBe(true);
+
+    const payload = JSON.parse(text.slice(6).trim());
+    expect(payload).toEqual({
+      role: 'node',
+      protocolVersion: '1',
+      source: {
+        hostId: 'local',
+        hostLabel: 'Local',
+        hostKind: 'local',
+      },
+      event: {
+        payload: {
+          type: 'session.status',
+          properties: {
+            sessionID: 'parent-1',
+            status: { type: 'busy' },
+          },
+          timestamp: 123,
+        },
+        directory: '/repo/project-one',
+      },
+    });
+    expect(JSON.stringify(payload).includes('baseUrl')).toBe(false);
+
+    requestController.abort();
+    await Promise.resolve();
+    await Promise.resolve();
+    await reader!.cancel();
+
+    expect(receivedSignal?.aborted).toBe(true);
+    expect(returnCalls).toBeGreaterThanOrEqual(1);
+    expect(mockCreateOpencodeClient.mock.calls).toEqual([[{ baseUrl: 'http://localhost:7777' }]]);
+  });
+});

package/.next/standalone/src/app/api/node/events/route.ts

@@ -0,0 +1,259 @@
+import { createOpencodeClient } from '@opencode-ai/sdk';
+import { discoverOpencodePortsWithMeta } from '@/lib/opencodeDiscovery';
+import {
+  NODE_PROTOCOL_VERSION,
+  createNodeFailureResponse,
+  guardNodeRequest,
+  toNodeRequestGuardResponse,
+} from '@/lib/nodeProtocol';
+
+const DEFAULT_EVENTS_PREFLIGHT_TIMEOUT_MS = 2500;
+
+const LOCAL_SOURCE = {
+  hostId: 'local',
+  hostLabel: 'Local',
+  hostKind: 'local',
+} as const;
+
+type ConnectedStream = {
+  port: number;
+  stream: AsyncIterable<unknown>;
+  controller: AbortController;
+};
+
+function getPreflightTimeoutMs(): number {
+  const parsedTimeout = Number(process.env.OPENCODE_EVENTS_PREFLIGHT_TIMEOUT_MS);
+  return Number.isFinite(parsedTimeout) && parsedTimeout > 0
+    ? parsedTimeout
+    : DEFAULT_EVENTS_PREFLIGHT_TIMEOUT_MS;
+}
+
+function isTimeoutError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.toLowerCase().includes('timed out');
+}
+
+function createUpstreamFailureResponse(reason: 'upstream_unreachable' | 'upstream_timeout') {
+  return createNodeFailureResponse(reason, {
+    role: 'node',
+    source: LOCAL_SOURCE,
+    upstream: {
+      kind: 'opencode',
+      reachable: false,
+    },
+  });
+}
+
+async function connectEventStreamWithTimeout(
+  port: number,
+  timeoutMs: number,
+  controller?: AbortController
+): Promise<ConnectedStream> {
+  const connectionController = controller ?? new AbortController();
+  const client = createOpencodeClient({ baseUrl: `http://localhost:${port}` });
+
+  let timerId: ReturnType<typeof setTimeout> | null = null;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timerId = setTimeout(() => {
+      connectionController.abort();
+      reject(new Error(`OpenCode event stream preflight timed out for port ${port} after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  try {
+    const connection = await Promise.race([
+      client.global.event({ signal: connectionController.signal }),
+      timeoutPromise,
+    ]);
+    return {
+      port,
+      stream: connection.stream as AsyncIterable<unknown>,
+      controller: connectionController,
+    };
+  } finally {
+    if (timerId) {
+      clearTimeout(timerId);
+    }
+  }
+}
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: Request) {
+  const guardResult = guardNodeRequest(request);
+  if (!guardResult.ok) {
+    return toNodeRequestGuardResponse(guardResult);
+  }
+
+  const { ports, timedOut } = discoverOpencodePortsWithMeta();
+
+  if (!ports.length) {
+    return createUpstreamFailureResponse(timedOut ? 'upstream_timeout' : 'upstream_unreachable');
+  }
+
+  try {
+    const encoder = new TextEncoder();
+    const preflightTimeoutMs = getPreflightTimeoutMs();
+    const preflightControllers = new Map<number, AbortController>();
+    const preflightAttempts = ports.map((port) => {
+      const controller = new AbortController();
+      preflightControllers.set(port, controller);
+      return connectEventStreamWithTimeout(port, preflightTimeoutMs, controller);
+    });
+
+    const firstConnectedStream = await Promise.any(preflightAttempts).catch(async () => {
+      const settled = await Promise.allSettled(preflightAttempts);
+      for (const result of settled) {
+        if (result.status === 'rejected') {
+          console.warn('Failed to connect to node-local OpenCode port during preflight:', result.reason);
+        }
+      }
+      return null;
+    });
+
+    if (!firstConnectedStream) {
+      const settled = await Promise.allSettled(preflightAttempts);
+      const failedReasons = settled
+        .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+        .map((result) => result.reason);
+      return createUpstreamFailureResponse(
+        failedReasons.length > 0 && failedReasons.every(isTimeoutError) ? 'upstream_timeout' : 'upstream_unreachable'
+      );
+    }
+
+    for (const [port, controller] of preflightControllers.entries()) {
+      if (port !== firstConnectedStream.port) {
+        controller.abort();
+      }
+    }
+
+    let teardown: (() => void) | null = null;
+    const stream = new ReadableStream({
+      async start(controller) {
+        let isClosed = false;
+        const activeControllers = new Set<AbortController>([firstConnectedStream.controller]);
+        const activeIterators = new Set<AsyncIterator<unknown>>();
+
+        const enqueueEvent = (event: unknown) => {
+          try {
+            controller.enqueue(
+              encoder.encode(
+                `data: ${JSON.stringify({
+                  role: 'node',
+                  protocolVersion: NODE_PROTOCOL_VERSION,
+                  source: LOCAL_SOURCE,
+                  event,
+                })}\n\n`
+              )
+            );
+            return true;
+          } catch {
+            return false;
+          }
+        };
+
+        const closeControllerSafely = () => {
+          try {
+            controller.close();
+          } catch {
+          }
+        };
+
+        const onAbort = () => {
+          if (teardown) {
+            teardown();
+            return;
+          }
+
+          isClosed = true;
+          closeControllerSafely();
+        };
+
+        teardown = () => {
+          isClosed = true;
+          for (const activeController of activeControllers) {
+            activeController.abort();
+          }
+          void Promise.allSettled(Array.from(activeIterators).map((iterator) => iterator.return?.()));
+          request.signal.removeEventListener('abort', onAbort);
+          closeControllerSafely();
+        };
+
+        request.signal.addEventListener('abort', onAbort);
+
+        const streamEvents = async (connected: ConnectedStream) => {
+          const iterator = connected.stream[Symbol.asyncIterator]();
+          activeIterators.add(iterator);
+          try {
+            while (!isClosed) {
+              const next = await iterator.next();
+              if (next.done) {
+                break;
+              }
+              if (isClosed) {
+                break;
+              }
+              if (!enqueueEvent(next.value)) {
+                break;
+              }
+            }
+          } catch (error) {
+            console.warn('Node-local OpenCode event stream failed for port:', connected.port, error);
+          } finally {
+            activeIterators.delete(iterator);
+          }
+        };
+
+        try {
+          const primaryTask = streamEvents(firstConnectedStream);
+
+          const remainingPorts = ports.filter((port) => port !== firstConnectedStream.port);
+          const secondaryTasks = remainingPorts.map(async (port) => {
+            if (isClosed) {
+              return;
+            }
+
+            try {
+              const connected = await connectEventStreamWithTimeout(port, preflightTimeoutMs);
+              activeControllers.add(connected.controller);
+              if (isClosed) {
+                connected.controller.abort();
+                activeControllers.delete(connected.controller);
+                return;
+              }
+              await streamEvents(connected);
+              activeControllers.delete(connected.controller);
+            } catch (error) {
+              console.warn('Failed to connect to secondary node-local OpenCode port:', port, error);
+            }
+          });
+
+          await Promise.allSettled([primaryTask, ...secondaryTasks]);
+        } catch (error) {
+          console.error('Error in node-local event stream:', error);
+        } finally {
+          isClosed = true;
+          teardown = null;
+          request.signal.removeEventListener('abort', onAbort);
+          closeControllerSafely();
+        }
+      },
+      cancel() {
+        if (teardown) {
+          teardown();
+        }
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+      },
+    });
+  } catch (error) {
+    console.error('Error creating node-local event stream:', error);
+    return createUpstreamFailureResponse(isTimeoutError(error) ? 'upstream_timeout' : 'upstream_unreachable');
+  }
+}