browsertrack 0.0.1 → 0.1.0

package/test/e2e/visual-notes-e2e.test.ts

@@ -0,0 +1,205 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { BrowserTrackDaemon } from '../../packages/daemon/src/server/daemon.js';
+import { handleToolCall } from '../../packages/mcp/src/handlers.js';
+
+describe('E2E Visual Notes Flow (Client -> Daemon -> MCP -> Verification -> Resolution)', () => {
+  let daemon: BrowserTrackDaemon;
+  const testPort = 7345;
+  let clientWs: WebSocket;
+  let assignedSessionId = '';
+
+  beforeAll(async () => {
+    daemon = new BrowserTrackDaemon({
+      port: testPort,
+      host: '127.0.0.1',
+      dbPath: ':memory:',
+      screenshotsDir: '/tmp/test-e2e-notes-screenshots',
+      verbose: false,
+    });
+    await daemon.start();
+
+    // Connect WebSocket simulating browser client
+    await new Promise<void>((resolve, reject) => {
+      clientWs = new WebSocket(`ws://127.0.0.1:${testPort}`);
+      clientWs.on('open', () => {
+        clientWs.send(
+          JSON.stringify({
+            type: 'hello',
+            origin: 'http://localhost:5173',
+            url: 'http://localhost:5173/dashboard',
+            title: 'Analytics Dashboard',
+          })
+        );
+      });
+
+      clientWs.on('message', (raw) => {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === 'hello_ack') {
+          assignedSessionId = msg.sessionId;
+          resolve();
+        }
+
+        // Handle daemon command dispatches during verify_note
+        if (msg.type === 'command') {
+          const cmd = msg.command;
+          if (cmd.type === 'get_page_state') {
+            clientWs.send(
+              JSON.stringify({
+                type: 'command_response',
+                sessionId: assignedSessionId,
+                response: {
+                  id: cmd.id,
+                  ok: true,
+                  result: {
+                    url: 'http://localhost:5173/dashboard',
+                    route: '/dashboard',
+                    title: 'Analytics Dashboard',
+                    readyState: 'complete',
+                  },
+                },
+              })
+            );
+          } else if (cmd.type === 'query_element') {
+            clientWs.send(
+              JSON.stringify({
+                type: 'command_response',
+                sessionId: assignedSessionId,
+                response: {
+                  id: cmd.id,
+                  ok: true,
+                  result: {
+                    exists: true,
+                    visible: true,
+                    boundingRect: { x: 20, y: 80, width: 350, height: 160, top: 80, left: 20, bottom: 240, right: 370 },
+                  },
+                },
+              })
+            );
+          } else if (cmd.type === 'check_overflow') {
+            clientWs.send(
+              JSON.stringify({
+                type: 'command_response',
+                sessionId: assignedSessionId,
+                response: {
+                  id: cmd.id,
+                  ok: true,
+                  result: {
+                    selector: '#stats-banner',
+                    overflow: false, // Overflow fixed!
+                    viewportWidth: 390,
+                    viewportHeight: 844,
+                    overflowRightPx: 0,
+                    overflowBottomPx: 0,
+                    rect: { x: 20, y: 80, width: 350, height: 160, top: 80, left: 20, bottom: 240, right: 370 },
+                  },
+                },
+              })
+            );
+          } else if (cmd.type === 'capture_element') {
+            clientWs.send(
+              JSON.stringify({
+                type: 'command_response',
+                sessionId: assignedSessionId,
+                response: {
+                  id: cmd.id,
+                  ok: true,
+                  result: {
+                    format: 'webp',
+                    dataUrl: 'data:image/webp;base64,UklGRmYAAABXRUJQVlA4IFoAAAAwAQCdASoBAAEAD8D+JaQAA3AA/ua2wAAA',
+                    width: 350,
+                    height: 160,
+                  },
+                },
+              })
+            );
+          }
+        }
+      });
+
+      clientWs.on('error', reject);
+    });
+  });
+
+  afterAll(async () => {
+    clientWs?.close();
+    await daemon.stop();
+  });
+
+  it('runs complete lifecycle of a visual note', async () => {
+    // 1. Client creates a note on overflowing stats card
+    const noteCreatedPromise = new Promise<string>((resolve) => {
+      const listener = (raw: any) => {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === 'note_created_ack') {
+          clientWs.removeListener('message', listener);
+          resolve(msg.noteId);
+        }
+      };
+      clientWs.on('message', listener);
+    });
+
+    clientWs.send(
+      JSON.stringify({
+        type: 'create_note',
+        sessionId: assignedSessionId,
+        noteType: 'element',
+        message: "Mobile'da buraya bak, sağa taşıyor",
+        route: '/dashboard',
+        url: 'http://localhost:5173/dashboard',
+        viewport: { width: 390, height: 844, devicePixelRatio: 3 },
+        scroll: { scrollX: 0, scrollY: 0 },
+        target: {
+          selector: '#stats-banner',
+          boundingRect: { x: 20, y: 80, width: 440, height: 160, top: 80, left: 20, bottom: 240, right: 460 },
+          visible: true,
+          confidence: 'high',
+        },
+        elementContext: {
+          selector: '#stats-banner',
+          tag: 'div',
+          attributes: { id: 'stats-banner' },
+          outerHTML: '<div id="stats-banner"><input type="password" value="[REDACTED]" /></div>',
+        },
+        screenshot: 'data:image/webp;base64,UklGRmYAAABXRUJQVlA4IFoAAAAwAQCdASoBAAEAD8D+JaQAA3AA/ua2wAAA',
+      })
+    );
+
+    const noteId = await noteCreatedPromise;
+    expect(noteId).toMatch(/^note_/);
+
+    // 2. MCP list_notes returns the note
+    const mcpCtx = {
+      db: daemon.db,
+      sessionManager: daemon.sessionManager,
+      noteVerificationEngine: daemon.noteVerificationEngine,
+    };
+
+    const listRes = await handleToolCall('list_notes', {}, mcpCtx);
+    expect(listRes.total).toBe(1);
+    expect(listRes.notes[0].id).toBe(noteId);
+    expect(listRes.notes[0].status).toBe('OPEN');
+    expect(listRes.notes[0].target).toBe('#stats-banner');
+
+    // 3. MCP get_note returns sanitized DOM and screenshot
+    const getRes = await handleToolCall('get_note', { noteId }, mcpCtx);
+    expect(getRes.id).toBe(noteId);
+    expect(getRes.elementContext.outerHTML).toContain('[REDACTED]');
+    expect(getRes.screenshot.available).toBe(true);
+
+    // 4. Verify note with layout probes (checks element & viewport overflow)
+    const verifyRes = await handleToolCall('verify_note', { noteId, observationWindowMs: 50 }, mcpCtx);
+    expect(verifyRes.noteId).toBe(noteId);
+    expect(verifyRes.status).toBe('VERIFIED');
+    expect(verifyRes.geometryDiff.overflowFixed).toBe(true);
+    expect(verifyRes.screenshots.after).toBeDefined();
+
+    // 5. MCP resolve_note marks note as RESOLVED
+    const resolveRes = await handleToolCall('resolve_note', { noteId }, mcpCtx);
+    expect(resolveRes.ok).toBe(true);
+    expect(resolveRes.status).toBe('RESOLVED');
+
+    const finalNote = daemon.db.getNote(noteId);
+    expect(finalNote?.status).toBe('RESOLVED');
+  });
+});

package/test/mcp/handlers.test.ts

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { StorageDB } from '../../packages/daemon/src/storage/db.js';
+import { handleToolCall } from '../../packages/mcp/src/handlers.js';
+
+describe('MCP Tool Handlers', () => {
+  let tempDir: string;
+  let db: StorageDB;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bt_mcp_test_'));
+    const dbPath = path.join(tempDir, 'test.db');
+    db = new StorageDB(dbPath);
+
+    // Seed test data
+    db.upsertProject({
+      id: 'proj_mcp',
+      name: 'mcp-app',
+      origin: 'http://localhost:3000',
+      path: '/Users/test/mcp-app',
+    });
+
+    db.upsertSession({
+      id: 'sess_mcp_1',
+      projectId: 'proj_mcp',
+      origin: 'http://localhost:3000',
+      url: 'http://localhost:3000/users',
+      title: 'Users List',
+      userAgent: 'Chrome/120',
+      connectedAt: new Date().toISOString(),
+      lastSeenAt: new Date().toISOString(),
+      active: true,
+    });
+
+    db.insertIncident({
+      id: 'inc_42',
+      projectId: 'proj_mcp',
+      sessionId: 'sess_mcp_1',
+      type: 'TypeError',
+      severity: 'error',
+      message: "Cannot read properties of undefined (reading 'avatar')",
+      source: { file: '/src/components/UserAvatar.tsx', line: 18, column: 5 },
+      fingerprint: 'fp_mcp_user_avatar',
+      route: '/users/42',
+      firstSeen: new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
+      occurrences: 4,
+      status: 'OPEN',
+      stack: 'TypeError: Cannot read properties...\n at UserAvatar (/src/components/UserAvatar.tsx:18:5)',
+      breadcrumbs: [
+        { type: 'navigation', message: 'navigate /users', timestamp: Date.now() - 1000 },
+        { type: 'click', message: 'click button[data-testid="user-42"]', timestamp: Date.now() - 500 },
+      ],
+      networkFailures: [
+        { url: '/api/users/42', method: 'GET', status: 500, durationMs: 120, timestamp: Date.now() - 300 },
+      ],
+      lastElement: {
+        selector: '[data-testid="user-42"]',
+        tag: 'button',
+        visible: true,
+        innerText: 'View Profile',
+      },
+    });
+
+    db.insertEvent({
+      id: 'evt_log_1',
+      sessionId: 'sess_mcp_1',
+      eventType: 'console',
+      payload: { level: 'error', message: 'Failed to load user image' },
+      timestamp: Date.now(),
+      route: '/users/42',
+    });
+  });
+
+  afterEach(() => {
+    db.close();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should handle list_projects', async () => {
+    const res = await handleToolCall('list_projects', {}, { db });
+    expect(res.projects.length).toBe(1);
+    expect(res.projects[0].name).toBe('mcp-app');
+  });
+
+  it('should handle list_incidents', async () => {
+    const res = await handleToolCall('list_incidents', { limit: 10 }, { db });
+    expect(res.total).toBe(1);
+    expect(res.incidents[0].id).toBe('inc_42');
+    expect(res.incidents[0].occurrences).toBe(4);
+  });
+
+  it('should handle get_incident with rich debugging context', async () => {
+    const res = await handleToolCall('get_incident', { incidentId: 'inc_42' }, { db });
+    expect(res.id).toBe('inc_42');
+    expect(res.source.file).toBe('/src/components/UserAvatar.tsx');
+    expect(res.source.line).toBe(18);
+    expect(res.lastInteractedElement?.selector).toBe('[data-testid="user-42"]');
+    expect(res.recentBreadcrumbs.length).toBe(2);
+    expect(res.networkFailures.length).toBe(1);
+  });
+
+  it('should handle get_console', async () => {
+    const res = await handleToolCall('get_console', { sessionId: 'sess_mcp_1' }, { db });
+    expect(res.logs.length).toBe(1);
+    expect(res.logs[0].message).toBe('Failed to load user image');
+  });
+
+  it('should handle get_breadcrumbs', async () => {
+    const res = await handleToolCall('get_breadcrumbs', { incidentId: 'inc_42' }, { db });
+    expect(res.breadcrumbs.length).toBe(2);
+    expect(res.breadcrumbs[0].type).toBe('navigation');
+  });
+});

package/test/mcp/notes.test.ts

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { StorageDB } from '../../packages/daemon/src/storage/db.js';
+import { ScreenshotStore } from '../../packages/daemon/src/storage/screenshot-store.js';
+import { SessionManager } from '../../packages/daemon/src/session/manager.js';
+import { NotesEngine } from '../../packages/daemon/src/notes/engine.js';
+import { NoteVerificationEngine } from '../../packages/daemon/src/notes/verification.js';
+import { handleToolCall } from '../../packages/mcp/src/handlers.js';
+
+describe('MCP Tools - Visual Notes', () => {
+  let db: StorageDB;
+  let screenshotStore: ScreenshotStore;
+  let sessionManager: SessionManager;
+  let notesEngine: NotesEngine;
+  let noteVerificationEngine: NoteVerificationEngine;
+
+  beforeEach(() => {
+    db = new StorageDB(':memory:');
+    screenshotStore = new ScreenshotStore('/tmp/test-mcp-notes');
+    sessionManager = new SessionManager(db);
+    notesEngine = new NotesEngine(db, screenshotStore);
+    noteVerificationEngine = new NoteVerificationEngine(db, sessionManager, notesEngine);
+
+    db.upsertProject({ id: 'proj_mcp', name: 'store-app', origin: 'http://localhost:5173' });
+    db.upsertSession({
+      id: 'sess_mcp',
+      projectId: 'proj_mcp',
+      origin: 'http://localhost:5173',
+      connectedAt: new Date().toISOString(),
+      lastSeenAt: new Date().toISOString(),
+    });
+
+    db.insertNote({
+      id: 'note_mcp_1',
+      projectId: 'proj_mcp',
+      sessionId: 'sess_mcp',
+      type: 'element',
+      message: 'Mobile nav hamburger button is misaligned',
+      route: '/checkout',
+      url: 'http://localhost:5173/checkout',
+      viewport: { width: 390, height: 844, devicePixelRatio: 3 },
+      scroll: { scrollX: 0, scrollY: 0 },
+      target: {
+        selector: '#nav-hamburger',
+        boundingRect: { x: 340, y: 15, width: 40, height: 40, top: 15, left: 340, bottom: 55, right: 380 },
+        visible: true,
+      },
+      elementContext: {
+        selector: '#nav-hamburger',
+        tag: 'button',
+        attributes: { id: 'nav-hamburger', 'aria-label': 'Menu' },
+        outerHTML: '<button id="nav-hamburger" aria-label="Menu"><span></span></button>',
+      },
+      status: 'OPEN',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    });
+  });
+
+  it('lists visual notes via list_notes tool', async () => {
+    const res = await handleToolCall(
+      'list_notes',
+      { projectId: 'proj_mcp' },
+      { db, sessionManager, noteVerificationEngine }
+    );
+
+    expect(res.total).toBe(1);
+    expect(res.notes[0].id).toBe('note_mcp_1');
+    expect(res.notes[0].route).toBe('/checkout');
+    expect(res.notes[0].target).toBe('#nav-hamburger');
+    expect(res.notes[0].message).toBe('Mobile nav hamburger button is misaligned');
+  });
+
+  it('retrieves note debugging context via get_note tool', async () => {
+    const res = await handleToolCall(
+      'get_note',
+      { noteId: 'note_mcp_1' },
+      { db, sessionManager, noteVerificationEngine }
+    );
+
+    expect(res.id).toBe('note_mcp_1');
+    expect(res.type).toBe('element');
+    expect(res.viewport.width).toBe(390);
+    expect(res.elementContext.tag).toBe('button');
+    expect(res.project.name).toBe('store-app');
+    expect(res.status).toBe('OPEN');
+  });
+
+  it('resolves and reopens note via resolve_note and reopen_note tools', async () => {
+    const resolveRes = await handleToolCall(
+      'resolve_note',
+      { noteId: 'note_mcp_1' },
+      { db, sessionManager, noteVerificationEngine }
+    );
+    expect(resolveRes.ok).toBe(true);
+    expect(resolveRes.status).toBe('RESOLVED');
+    expect(db.getNote('note_mcp_1')?.status).toBe('RESOLVED');
+
+    const reopenRes = await handleToolCall(
+      'reopen_note',
+      { noteId: 'note_mcp_1' },
+      { db, sessionManager, noteVerificationEngine }
+    );
+    expect(reopenRes.ok).toBe(true);
+    expect(reopenRes.status).toBe('OPEN');
+    expect(db.getNote('note_mcp_1')?.status).toBe('OPEN');
+  });
+});

package/tsconfig.base.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "baseUrl": ".",
+    "paths": {
+      "@browserdiag/core": ["./packages/core/src/index.ts"],
+      "browsertrack/core": ["./packages/core/src/index.ts"],
+      "browsertrack/client": ["./packages/client/src/index.ts"],
+      "browsertrack/daemon": ["./packages/daemon/src/index.ts"],
+      "browsertrack/mcp": ["./packages/mcp/src/index.ts"]
+    }
+  },
+  "include": ["src/**/*", "packages/**/*", "test/**/*"]
+}

package/tsup.config.ts

@@ -0,0 +1,54 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig([
+  // Core, Client, Daemon, MCP Library exports
+  {
+    entry: {
+      index: 'src/index.ts',
+      'core/index': 'packages/core/src/index.ts',
+      'client/index': 'packages/client/src/index.ts',
+      'daemon/index': 'packages/daemon/src/index.ts',
+      'mcp/index': 'packages/mcp/src/index.ts',
+    },
+    format: ['esm'],
+    dts: true,
+    sourcemap: true,
+    clean: true,
+    target: 'node20',
+  },
+  // CLI Binary
+  {
+    entry: {
+      'cli/index': 'packages/cli/src/index.ts',
+    },
+    format: ['esm'],
+    banner: {
+      js: '#!/usr/bin/env node',
+    },
+    sourcemap: true,
+    target: 'node20',
+  },
+  // Client browser CJS bundle
+  {
+    entry: {
+      'client/index': 'packages/client/src/index.ts',
+    },
+    format: ['cjs'],
+    dts: false,
+    target: 'es2020',
+  },
+  // Standalone browser client script (for http://127.0.0.1:7331/client.js)
+  {
+    entry: {
+      'client.iife': 'packages/client/src/index.ts',
+    },
+    format: ['iife'],
+    globalName: 'BrowserTrack',
+    platform: 'browser',
+    target: 'es2020',
+    outExtension() {
+      return { js: '.js' };
+    },
+    minify: true,
+  },
+]);

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.test.ts'],
+  },
+});