browsertrack 0.0.1 → 0.1.0

package/packages/mcp/src/index.ts

@@ -0,0 +1,3 @@
+export * from './tools.js';
+export * from './handlers.js';
+export * from './server.js';

package/packages/mcp/src/server.ts

@@ -0,0 +1,86 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { getDaemonConfig } from '../../daemon/src/config.js';
+import { StorageDB } from '../../daemon/src/storage/db.js';
+import { ScreenshotStore } from '../../daemon/src/storage/screenshot-store.js';
+import { SessionManager } from '../../daemon/src/session/manager.js';
+import { NotesEngine } from '../../daemon/src/notes/engine.js';
+import { NoteVerificationEngine } from '../../daemon/src/notes/verification.js';
+import { VerificationEngine } from '../../daemon/src/verification/engine.js';
+import type { McpContext } from './handlers.js';
+import { handleToolCall } from './handlers.js';
+import { TOOLS } from './tools.js';
+
+export interface McpServerOptions {
+  dbPath?: string;
+  context?: Partial<McpContext>;
+}
+
+export function createMcpServer(options: McpServerOptions = {}) {
+  const config = getDaemonConfig({ dbPath: options.dbPath });
+  const db = options.context?.db || new StorageDB(config.dbPath);
+  const screenshotStore = new ScreenshotStore(config.screenshotsDir);
+  const sessionManager = options.context?.sessionManager || new SessionManager(db);
+  const verificationEngine = options.context?.verificationEngine || new VerificationEngine(db, sessionManager, screenshotStore);
+  const notesEngine = new NotesEngine(db, screenshotStore);
+  const noteVerificationEngine = options.context?.noteVerificationEngine || new NoteVerificationEngine(db, sessionManager, notesEngine);
+
+  const ctx: McpContext = {
+    db,
+    sessionManager,
+    verificationEngine,
+    noteVerificationEngine,
+    daemonUrl: `http://${config.host}:${config.port}`,
+    ...options.context,
+  };
+
+  const server = new Server(
+    {
+      name: 'browsertrack-mcp',
+      version: '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      const result = await handleToolCall(name, args || {}, ctx);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (err: any) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: `Error executing tool ${name}: ${err?.message || String(err)}`,
+          },
+        ],
+      };
+    }
+  });
+
+  return {
+    server,
+    async startStdio() {
+      const transport = new StdioServerTransport();
+      await server.connect(transport);
+    },
+  };
+}

package/packages/mcp/src/tools.ts

@@ -0,0 +1,236 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const TOOLS: Tool[] = [
+  {
+    name: 'list_projects',
+    description: 'List all registered projects tracked by BrowserTrack/BrowserDiag',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'list_sessions',
+    description: 'List active and recent browser sessions connected to the local development daemon',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Filter sessions by project ID or name' },
+        activeOnly: { type: 'boolean', description: 'Show only currently active WebSocket sessions (default: true)' },
+      },
+    },
+  },
+  {
+    name: 'list_incidents',
+    description: 'List recorded browser runtime errors, unhandled rejections, and console errors grouped into incidents',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Filter by project ID or name' },
+        status: {
+          type: 'string',
+          enum: ['OPEN', 'FIX_ATTEMPTED', 'VERIFYING', 'VERIFIED', 'FAILED', 'INCONCLUSIVE'],
+          description: 'Filter by incident status',
+        },
+        severity: {
+          type: 'string',
+          enum: ['error', 'warn', 'fatal'],
+          description: 'Filter by severity',
+        },
+        limit: { type: 'number', description: 'Maximum number of incidents to return (default: 20)' },
+      },
+    },
+  },
+  {
+    name: 'get_incident',
+    description: 'Retrieve compact and high-signal debugging context for a specific error incident (stack trace, breadcrumbs, network failures, last interacted element, error screenshot)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        incidentId: { type: 'string', description: 'The unique ID of the incident (e.g. inc_42)' },
+      },
+      required: ['incidentId'],
+    },
+  },
+  {
+    name: 'get_console',
+    description: 'Get recent console logs, warnings, and errors from a browser session',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string', description: 'Browser session ID (optional, defaults to active session)' },
+        limit: { type: 'number', description: 'Number of console logs to retrieve (default: 30)' },
+      },
+    },
+  },
+  {
+    name: 'get_network_failures',
+    description: 'Get recent failed HTTP network requests (4xx, 5xx, network errors, timeouts, aborts)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string', description: 'Browser session ID (optional)' },
+        limit: { type: 'number', description: 'Maximum number of failed requests to return (default: 20)' },
+      },
+    },
+  },
+  {
+    name: 'get_breadcrumbs',
+    description: 'Get the sequence of recent user interactions, navigations, console logs, and network events prior to an error',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string', description: 'Browser session ID (optional)' },
+        incidentId: { type: 'string', description: 'Incident ID to fetch breadcrumbs from (optional)' },
+        limit: { type: 'number', description: 'Maximum number of breadcrumbs (default: 50)' },
+      },
+    },
+  },
+  {
+    name: 'get_page_state',
+    description: 'Query the live page state (URL, route, document title, readyState, active element) from the connected browser session',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string', description: 'Target session ID (optional, defaults to active)' },
+      },
+    },
+  },
+  {
+    name: 'capture_element',
+    description: 'Capture a screenshot of a specific DOM element or the entire visible page in the active browser tab',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'CSS selector of the element to capture (e.g. [data-testid="user-card"])' },
+        sessionId: { type: 'string', description: 'Browser session ID (optional)' },
+      },
+    },
+  },
+  {
+    name: 'verify_incident',
+    description: 'Trigger closed-loop verification of a bug fix: reloads the browser, checks if the incident reoccurs, evaluates optional verification probes, and records before/after screenshots',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        incidentId: { type: 'string', description: 'The ID of the incident to verify' },
+        route: { type: 'string', description: 'Optional route to navigate to for verification (defaults to incident route)' },
+        targetSelector: { type: 'string', description: 'Optional element selector to inspect and capture after-fix screenshot' },
+        expect: {
+          type: 'array',
+          description: 'Optional verification probes to evaluate after reload',
+          items: {
+            type: 'object',
+            properties: {
+              type: {
+                type: 'string',
+                enum: ['element_exists', 'element_visible', 'text_contains', 'route_is', 'no_incident'],
+              },
+              selector: { type: 'string' },
+              text: { type: 'string' },
+              route: { type: 'string' },
+            },
+            required: ['type'],
+          },
+        },
+        observationWindowMs: { type: 'number', description: 'Observation window in milliseconds (default: 2000)' },
+      },
+      required: ['incidentId'],
+    },
+  },
+  {
+    name: 'get_verification',
+    description: 'Retrieve the latest verification result and before/after screenshot artifacts for an incident',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        incidentId: { type: 'string', description: 'The ID of the incident' },
+      },
+      required: ['incidentId'],
+    },
+  },
+  {
+    name: 'list_notes',
+    description: 'List visual development notes / screen annotations left on elements, regions, or pages during development',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Filter notes by project ID or name' },
+        status: {
+          type: 'string',
+          enum: ['OPEN', 'IN_PROGRESS', 'VERIFYING', 'RESOLVED', 'FAILED', 'INCONCLUSIVE'],
+          description: 'Filter by note status (default: OPEN)',
+        },
+        limit: { type: 'number', description: 'Maximum number of notes to return (default: 20)' },
+      },
+    },
+  },
+  {
+    name: 'get_note',
+    description: 'Retrieve full debugging context for a visual note (message, route, viewport dimensions, target element selector, DOM context, screenshot file path, project path)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        noteId: { type: 'string', description: 'The unique ID of the visual note (e.g. note_42)' },
+      },
+      required: ['noteId'],
+    },
+  },
+  {
+    name: 'resolve_note',
+    description: 'Mark a visual note as RESOLVED once the layout or styling issue has been fixed',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        noteId: { type: 'string', description: 'The ID of the visual note to resolve' },
+      },
+      required: ['noteId'],
+    },
+  },
+  {
+    name: 'reopen_note',
+    description: 'Reopen a previously resolved visual note',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        noteId: { type: 'string', description: 'The ID of the visual note to reopen' },
+      },
+      required: ['noteId'],
+    },
+  },
+  {
+    name: 'verify_note',
+    description: 'Run closed-loop layout & visual verification for a note: checks route, element existence/visibility, evaluates viewport overflow probes, captures after-screenshot, and computes geometry diff',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        noteId: { type: 'string', description: 'The ID of the visual note to verify' },
+        observationWindowMs: { type: 'number', description: 'Observation window in milliseconds (default: 1000)' },
+      },
+      required: ['noteId'],
+    },
+  },
+  {
+    name: 'get_note_verification',
+    description: 'Retrieve the latest verification result, before/after screenshot references, and layout geometry diff for a visual note',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        noteId: { type: 'string', description: 'The ID of the visual note' },
+      },
+      required: ['noteId'],
+    },
+  },
+  {
+    name: 'capture_note_context',
+    description: 'Inspect live DOM context, bounding box, overflow, and styles for a target element in the active browser tab',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'CSS selector of the target element' },
+        sessionId: { type: 'string', description: 'Browser session ID (optional)' },
+      },
+      required: ['selector'],
+    },
+  },
+];

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from '../packages/core/src/index.js';
+export { init as initClient, getClient, BrowserTrackClient } from '../packages/client/src/index.js';
+export { createDaemon, BrowserTrackDaemon } from '../packages/daemon/src/index.js';
+export { createMcpServer } from '../packages/mcp/src/index.js';

package/test/client/interceptors.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import { BreadcrumbBuffer } from '../../packages/client/src/breadcrumbs.js';
+import { setupConsoleInterceptors } from '../../packages/client/src/interceptors/console.js';
+import { getSemanticSelector } from '../../packages/core/src/selector.js';
+
+describe('Client Interceptors & Utilities', () => {
+  it('should patch console without breaking original console calls', () => {
+    const originalError = console.error;
+    const captured: any[] = [];
+
+    const cleanup = setupConsoleInterceptors((event) => {
+      captured.push(event);
+    });
+
+    console.error('Test error message', { code: 500 });
+
+    expect(captured.length).toBe(1);
+    expect(captured[0].level).toBe('error');
+    expect(captured[0].message).toContain('Test error message');
+
+    cleanup();
+
+    // Verify restore
+    expect(console.error).toBe(originalError);
+  });
+
+  it('should maintain bounded ring buffer capacity in BreadcrumbBuffer', () => {
+    const buffer = new BreadcrumbBuffer(5);
+
+    for (let i = 1; i <= 10; i++) {
+      buffer.add({
+        type: 'click',
+        message: `click ${i}`,
+      });
+    }
+
+    const recent = buffer.getRecent();
+    expect(recent.length).toBe(5);
+    expect(recent[0].message).toBe('click 6');
+    expect(recent[4].message).toBe('click 10');
+  });
+
+  it('should produce semantic selector with data-testid priority', () => {
+    const fakeElement = {
+      tagName: 'BUTTON',
+      getAttribute: (attr: string) => {
+        if (attr === 'data-testid') return 'submit-btn';
+        return null;
+      },
+      id: 'btn-1',
+      classList: ['primary-btn'],
+    } as any;
+
+    const selector = getSemanticSelector(fakeElement);
+    expect(selector).toBe('[data-testid="submit-btn"]');
+  });
+
+  it('should produce semantic selector with ID if no testid', () => {
+    const fakeElement = {
+      tagName: 'DIV',
+      getAttribute: () => null,
+      id: 'main-container',
+      classList: ['app-body'],
+    } as any;
+
+    const selector = getSemanticSelector(fakeElement);
+    expect(selector).toBe('#main-container');
+  });
+});

package/test/core/fingerprint.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { computeFingerprint, normalizeErrorMessage, normalizeSourceFile } from '../../packages/core/src/fingerprint.js';
+
+describe('Fingerprint Engine', () => {
+  it('should normalize error messages with UUIDs, hex values, and timestamps', () => {
+    const raw = 'Failed at 0x7ffee4b2a8 with user c9bf9e57-1685-4c89-bafb-ff5af830be8a on 2026-08-31T22:30:00Z';
+    const normalized = normalizeErrorMessage(raw);
+    expect(normalized).toBe('Failed at 0x<HEX> with user <UUID> on <TIMESTAMP>');
+  });
+
+  it('should normalize source file paths by stripping query parameters and origins', () => {
+    expect(normalizeSourceFile('http://localhost:5173/src/App.tsx?t=1719283')).toBe('/src/App.tsx');
+    expect(normalizeSourceFile('https://example.com/assets/main.js#line40')).toBe('/assets/main.js');
+    expect(normalizeSourceFile('C:\\Users\\dev\\project\\src\\main.ts')).toBe('C:/Users/dev/project/src/main.ts');
+  });
+
+  it('should produce deterministic identical fingerprints for duplicate errors', () => {
+    const fp1 = computeFingerprint({
+      type: 'TypeError',
+      message: 'Cannot read properties of undefined (reading "id")',
+      sourceFile: 'http://localhost:5173/src/components/User.tsx?t=100',
+      line: 42,
+    });
+
+    const fp2 = computeFingerprint({
+      type: 'TypeError',
+      message: 'Cannot read properties of undefined (reading "id")',
+      sourceFile: 'http://localhost:5173/src/components/User.tsx?t=999',
+      line: 42,
+    });
+
+    expect(fp1).toBe(fp2);
+    expect(fp1.startsWith('fp_')).toBe(true);
+  });
+
+  it('should produce distinct fingerprints for errors at different lines or files', () => {
+    const fp1 = computeFingerprint({
+      type: 'TypeError',
+      message: 'Cannot read properties of undefined',
+      sourceFile: '/src/App.tsx',
+      line: 10,
+    });
+
+    const fp2 = computeFingerprint({
+      type: 'TypeError',
+      message: 'Cannot read properties of undefined',
+      sourceFile: '/src/App.tsx',
+      line: 25,
+    });
+
+    expect(fp1).not.toBe(fp2);
+  });
+});

package/test/core/notes.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import type { VisualNote } from '../../packages/core/src/index.js';
+import { getSemanticSelector, truncate } from '../../packages/core/src/index.js';
+
+describe('Core Visual Notes Types & Helpers', () => {
+  it('constructs a valid VisualNote object', () => {
+    const note: VisualNote = {
+      id: 'note_12345',
+      projectId: 'proj_test',
+      sessionId: 'sess_test',
+      type: 'element',
+      message: "Mobile'da buraya bak, sağa taşıyor",
+      route: '/dashboard',
+      url: 'http://localhost:3000/dashboard',
+      viewport: {
+        width: 390,
+        height: 844,
+        devicePixelRatio: 3,
+      },
+      scroll: {
+        scrollX: 0,
+        scrollY: 120,
+      },
+      target: {
+        selector: '[data-testid="stats-card"]',
+        boundingRect: {
+          x: 20,
+          y: 100,
+          width: 420,
+          height: 180,
+          top: 100,
+          left: 20,
+          bottom: 280,
+          right: 440,
+        },
+        visible: true,
+        confidence: 'high',
+      },
+      elementContext: {
+        selector: '[data-testid="stats-card"]',
+        tag: 'section',
+        attributes: {
+          class: 'stats-card responsive',
+          'data-testid': 'stats-card',
+        },
+        outerHTML: '<section class="stats-card responsive" data-testid="stats-card"><div>142K</div></section>',
+      },
+      status: 'OPEN',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    expect(note.id).toBe('note_12345');
+    expect(note.viewport.width).toBe(390);
+    expect(note.target?.boundingRect.right).toBe(440);
+    expect(note.target?.boundingRect.right).toBeGreaterThan(note.viewport.width);
+    expect(note.status).toBe('OPEN');
+  });
+
+  it('truncates large outerHTML properly', () => {
+    const longHtml = '<div>' + 'a'.repeat(20000) + '</div>';
+    const truncated = truncate(longHtml, 10240);
+    expect(truncated.length).toBeLessThanOrEqual(10243);
+    expect(truncated.endsWith('...')).toBe(true);
+  });
+});

package/test/core/redaction.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { redactHeaders, redactSensitiveData, redactUrl, REDACTED_PLACEHOLDER } from '../../packages/core/src/redaction.js';
+
+describe('Redaction & Security', () => {
+  it('should redact sensitive query parameters in URLs', () => {
+    const raw = 'http://localhost:3000/api/users?token=supersecret123&page=1&apiKey=xyz987';
+    const redacted = redactUrl(raw);
+
+    expect(redacted).toContain(`token=${REDACTED_PLACEHOLDER}`);
+    expect(redacted).toContain(`apiKey=${REDACTED_PLACEHOLDER}`);
+    expect(redacted).toContain('page=1');
+  });
+
+  it('should redact sensitive headers', () => {
+    const headers = {
+      Authorization: 'Bearer eyJhbGciOi...',
+      Cookie: 'session_id=12345; auth_token=abc',
+      'Content-Type': 'application/json',
+      'X-Api-Key': 'secret-key-1',
+    };
+
+    const redacted = redactHeaders(headers);
+    expect(redacted['Authorization']).toBe(REDACTED_PLACEHOLDER);
+    expect(redacted['Cookie']).toBe(REDACTED_PLACEHOLDER);
+    expect(redacted['X-Api-Key']).toBe(REDACTED_PLACEHOLDER);
+    expect(redacted['Content-Type']).toBe('application/json');
+  });
+
+  it('should deeply redact sensitive keys in nested payloads', () => {
+    const payload = {
+      user: {
+        id: 42,
+        name: 'Alice',
+        password: 'PlainTextPassword!',
+        auth: {
+          accessToken: 'secret_token_val',
+        },
+      },
+      redirectUrl: 'http://example.com/callback?code=secret_oauth_code',
+    };
+
+    const redacted = redactSensitiveData(payload);
+    expect(redacted.user.name).toBe('Alice');
+    expect(redacted.user.password).toBe(REDACTED_PLACEHOLDER);
+    expect(redacted.user.auth.accessToken).toBe(REDACTED_PLACEHOLDER);
+    expect(redacted.redirectUrl).toContain(REDACTED_PLACEHOLDER);
+  });
+});

package/test/daemon/incident-engine.test.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { IncidentEngine } from '../../packages/daemon/src/incidents/engine.js';
+import { StorageDB } from '../../packages/daemon/src/storage/db.js';
+import { ScreenshotStore } from '../../packages/daemon/src/storage/screenshot-store.js';
+
+describe('IncidentEngine', () => {
+  let tempDir: string;
+  let db: StorageDB;
+  let screenshotStore: ScreenshotStore;
+  let engine: IncidentEngine;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bt_inc_test_'));
+    const dbPath = path.join(tempDir, 'test.db');
+    const screenshotsDir = path.join(tempDir, 'screenshots');
+
+    db = new StorageDB(dbPath);
+    screenshotStore = new ScreenshotStore(screenshotsDir);
+    engine = new IncidentEngine(db, screenshotStore);
+
+    // Setup project and session
+    db.upsertProject({ id: 'proj_app', name: 'app', origin: 'http://localhost:5173' });
+    db.upsertSession({
+      id: 'sess_100',
+      projectId: 'proj_app',
+      origin: 'http://localhost:5173',
+      url: 'http://localhost:5173/dashboard',
+      title: 'Dashboard',
+      userAgent: 'Chrome/120',
+      connectedAt: new Date().toISOString(),
+      lastSeenAt: new Date().toISOString(),
+      active: true,
+    });
+  });
+
+  afterEach(() => {
+    db.close();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should create a new incident from a runtime error event', () => {
+    const incident = engine.processClientEvent({
+      type: 'event',
+      sessionId: 'sess_100',
+      eventType: 'runtime_error',
+      payload: {
+        errorType: 'TypeError',
+        message: "Cannot read properties of null (reading 'userName')",
+        filename: 'http://localhost:5173/src/User.tsx?t=12345',
+        lineno: 28,
+        colno: 5,
+        timestamp: Date.now(),
+      },
+      route: '/dashboard',
+      url: 'http://localhost:5173/dashboard',
+      timestamp: Date.now(),
+    });
+
+    expect(incident).not.toBeNull();
+    expect(incident?.id.startsWith('inc_')).toBe(true);
+    expect(incident?.occurrences).toBe(1);
+    expect(incident?.status).toBe('OPEN');
+    expect(incident?.source.file).toBe('/src/User.tsx');
+    expect(incident?.source.line).toBe(28);
+  });
+
+  it('should deduplicate recurring errors and increment occurrences', () => {
+    const eventPayload = {
+      type: 'event' as const,
+      sessionId: 'sess_100',
+      eventType: 'runtime_error' as const,
+      payload: {
+        errorType: 'ReferenceError',
+        message: 'AuthService is not defined',
+        filename: '/src/services/auth.ts',
+        lineno: 14,
+        timestamp: Date.now(),
+      },
+      route: '/login',
+      url: 'http://localhost:5173/login',
+      timestamp: Date.now(),
+    };
+
+    const first = engine.processClientEvent(eventPayload);
+    const second = engine.processClientEvent(eventPayload);
+    const third = engine.processClientEvent(eventPayload);
+
+    expect(first?.id).toBe(second?.id);
+    expect(first?.id).toBe(third?.id);
+    expect(third?.occurrences).toBe(3);
+
+    const fromDb = db.getIncident(first!.id);
+    expect(fromDb?.occurrences).toBe(3);
+  });
+});