browsertrack 0.0.1 → 0.1.1

package/packages/daemon/src/config.ts

@@ -0,0 +1,29 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export interface DaemonConfig {
+  host: string;
+  port: number;
+  dataDir: string;
+  dbPath: string;
+  screenshotsDir: string;
+  maxEventsPerSession: number;
+  verbose: boolean;
+}
+
+export function getDaemonConfig(overrides: Partial<DaemonConfig> = {}): DaemonConfig {
+  const homeDir = os.homedir();
+  const dataDir = overrides.dataDir || path.join(homeDir, '.browsertrack');
+  const dbPath = overrides.dbPath || path.join(dataDir, 'browsertrack.db');
+  const screenshotsDir = overrides.screenshotsDir || path.join(dataDir, 'projects');
+
+  return {
+    host: overrides.host || '127.0.0.1',
+    port: overrides.port || 7331,
+    dataDir,
+    dbPath,
+    screenshotsDir,
+    maxEventsPerSession: overrides.maxEventsPerSession || 1000,
+    verbose: !!overrides.verbose,
+  };
+}

package/packages/daemon/src/incidents/engine.ts

@@ -0,0 +1,211 @@
+import crypto from 'node:crypto';
+import type {
+  ClientEventMessage,
+  ConsoleEvent,
+  Incident,
+  IncidentOccurrence,
+  IncidentSeverity,
+  NetworkEvent,
+  RuntimeErrorEvent,
+} from '../../../core/src/index.js';
+import { computeFingerprint, extractSourceFromStack, normalizeSourceFile, redactSensitiveData } from '../../../core/src/index.js';
+import type { StorageDB } from '../storage/db.js';
+import type { ScreenshotStore } from '../storage/screenshot-store.js';
+
+export class IncidentEngine {
+  private db: StorageDB;
+  private screenshotStore: ScreenshotStore;
+
+  constructor(db: StorageDB, screenshotStore: ScreenshotStore) {
+    this.db = db;
+    this.screenshotStore = screenshotStore;
+  }
+
+  public processClientEvent(message: ClientEventMessage & { screenshot?: string }): Incident | null {
+    const session = this.db.getSession(message.sessionId);
+    const projectId = session?.projectId || 'default';
+    const sanitizedBreadcrumbs = (message.breadcrumbs || []).map((b) => redactSensitiveData(b));
+    const sanitizedLastElement = message.lastElement ? redactSensitiveData(message.lastElement) : undefined;
+
+    // Filter network failures from breadcrumbs
+    const networkFailures: NetworkEvent[] = sanitizedBreadcrumbs
+      .filter((b) => (b.type === 'fetch' || b.type === 'xhr') && b.level === 'error' && b.data)
+      .map((b) => ({
+        url: b.message.split(' ')[1] || '',
+        method: b.message.split(' ')[0] || 'GET',
+        status: b.data?.status,
+        durationMs: b.data?.durationMs || 0,
+        error: b.data?.error,
+        aborted: b.data?.aborted,
+        timestamp: b.timestamp,
+      }));
+
+    if (message.eventType === 'runtime_error' || message.eventType === 'unhandled_rejection') {
+      const payload = message.payload as RuntimeErrorEvent;
+      return this.handleErrorEvent({
+        projectId,
+        sessionId: message.sessionId,
+        type: payload.errorType || 'runtime_exception',
+        severity: 'error',
+        message: payload.message || 'Unknown runtime error',
+        stack: payload.stack,
+        sourceFile: payload.filename,
+        line: payload.lineno,
+        column: payload.colno,
+        route: message.route || '/',
+        url: message.url,
+        breadcrumbs: sanitizedBreadcrumbs,
+        networkFailures,
+        lastElement: sanitizedLastElement,
+        screenshotDataUrl: message.screenshot,
+      });
+    }
+
+    if (message.eventType === 'console') {
+      const payload = message.payload as ConsoleEvent;
+      if (payload.level === 'error') {
+        return this.handleErrorEvent({
+          projectId,
+          sessionId: message.sessionId,
+          type: 'console_error',
+          severity: 'error',
+          message: payload.message,
+          stack: payload.stack,
+          route: message.route || '/',
+          url: message.url,
+          breadcrumbs: sanitizedBreadcrumbs,
+          networkFailures,
+          lastElement: sanitizedLastElement,
+          screenshotDataUrl: message.screenshot,
+        });
+      }
+    }
+
+    return null;
+  }
+
+  private handleErrorEvent(input: {
+    projectId: string;
+    sessionId: string;
+    type: string;
+    severity: IncidentSeverity;
+    message: string;
+    stack?: string;
+    sourceFile?: string;
+    line?: number;
+    column?: number;
+    route: string;
+    url: string;
+    breadcrumbs: any[];
+    networkFailures: NetworkEvent[];
+    lastElement?: any;
+    screenshotDataUrl?: string;
+  }): Incident {
+    const extracted = (!input.sourceFile || !input.line) && input.stack ? extractSourceFromStack(input.stack) : null;
+
+    const rawSource = input.sourceFile || extracted?.file || 'unknown_source';
+    const sourceFile = normalizeSourceFile(rawSource);
+    const line = input.line || extracted?.line || 0;
+    const column = input.column || extracted?.column;
+
+    const fingerprint = computeFingerprint({
+      type: input.type,
+      message: input.message,
+      sourceFile,
+      line,
+      column,
+      stack: input.stack,
+    });
+
+    const now = new Date().toISOString();
+    const existing = this.db.findIncidentByFingerprint(fingerprint);
+
+    if (existing) {
+      const updatedOccurrences = existing.occurrences + 1;
+      this.db.updateIncidentOccurrence(existing.id, {
+        sessionId: input.sessionId,
+        lastSeen: now,
+        occurrences: updatedOccurrences,
+        route: input.route,
+        breadcrumbs: input.breadcrumbs,
+        lastElement: input.lastElement,
+        stack: input.stack,
+      });
+
+      // Insert occurrence
+      const occurrenceId = `occ_${crypto.randomUUID().slice(0, 8)}`;
+      this.db.insertIncidentOccurrence({
+        id: occurrenceId,
+        incidentId: existing.id,
+        sessionId: input.sessionId,
+        timestamp: now,
+        route: input.route,
+        url: input.url,
+        stack: input.stack,
+        breadcrumbs: input.breadcrumbs,
+        lastElement: input.lastElement,
+      });
+
+      return {
+        ...existing,
+        occurrences: updatedOccurrences,
+        lastSeen: now,
+        breadcrumbs: input.breadcrumbs,
+        lastElement: input.lastElement || existing.lastElement,
+      };
+    }
+
+    // New incident
+    const incidentId = `inc_${crypto.randomUUID().slice(0, 8)}`;
+    let screenshotPath: string | undefined;
+
+    if (input.screenshotDataUrl) {
+      const saved = this.screenshotStore.saveScreenshot(input.projectId, incidentId, 'error', input.screenshotDataUrl);
+      if (saved) {
+        screenshotPath = saved.filePath;
+      }
+    }
+
+    const newIncident: Incident = {
+      id: incidentId,
+      projectId: input.projectId,
+      sessionId: input.sessionId,
+      type: input.type,
+      severity: input.severity,
+      message: input.message,
+      source: {
+        file: sourceFile,
+        line,
+        column,
+      },
+      fingerprint,
+      route: input.route,
+      firstSeen: now,
+      lastSeen: now,
+      occurrences: 1,
+      status: 'OPEN',
+      stack: input.stack,
+      breadcrumbs: input.breadcrumbs,
+      networkFailures: input.networkFailures,
+      lastElement: input.lastElement,
+      screenshots: screenshotPath ? { error: screenshotPath } : undefined,
+    };
+
+    this.db.insertIncident(newIncident);
+
+    // Initial occurrence
+    this.db.insertIncidentOccurrence({
+      id: `occ_${crypto.randomUUID().slice(0, 8)}`,
+      incidentId,
+      sessionId: input.sessionId,
+      timestamp: now,
+      route: input.route,
+      url: input.url,
+      stack: input.stack,
+      breadcrumbs: input.breadcrumbs,
+      lastElement: input.lastElement,
+    });
+
+    return newIncident;
+  }
+}

package/packages/daemon/src/index.ts

@@ -0,0 +1,18 @@
+export * from './config.js';
+export * from './storage/db.js';
+export * from './storage/screenshot-store.js';
+export * from './session/manager.js';
+export * from './incidents/engine.js';
+export * from './notes/engine.js';
+export * from './notes/verification.js';
+export * from './verification/engine.js';
+export * from './server/http.js';
+export * from './server/ws.js';
+export * from './server/daemon.js';
+
+import { BrowserTrackDaemon } from './server/daemon.js';
+import type { DaemonConfig } from './config.js';
+
+export function createDaemon(config: Partial<DaemonConfig> = {}): BrowserTrackDaemon {
+  return new BrowserTrackDaemon(config);
+}

package/packages/daemon/src/notes/engine.ts

@@ -0,0 +1,92 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import fs from 'node:fs';
+import type { VisualNote } from '../../../core/src/index.js';
+import type { StorageDB } from '../storage/db.js';
+import type { ScreenshotStore } from '../storage/screenshot-store.js';
+
+export class NotesEngine {
+  private db: StorageDB;
+  private screenshotStore: ScreenshotStore;
+
+  constructor(db: StorageDB, screenshotStore: ScreenshotStore) {
+    this.db = db;
+    this.screenshotStore = screenshotStore;
+  }
+
+  public createNoteFromClient(payload: {
+    sessionId: string;
+    noteType?: 'element' | 'region' | 'page';
+    message: string;
+    route?: string;
+    url?: string;
+    viewport?: { width: number; height: number; devicePixelRatio: number };
+    scroll?: { scrollX: number; scrollY: number };
+    target?: any;
+    elementContext?: any;
+    region?: any;
+    screenshot?: string;
+    incidentId?: string;
+  }): VisualNote {
+    const session = this.db.getSession(payload.sessionId);
+    const projectId = session?.projectId || 'default';
+    const noteId = `note_${crypto.randomUUID().slice(0, 8)}`;
+    const now = new Date().toISOString();
+
+    let screenshotPath: string | undefined;
+    if (payload.screenshot) {
+      const saved = this.saveNoteScreenshot(projectId, noteId, 'original', payload.screenshot);
+      if (saved) {
+        screenshotPath = saved;
+      }
+    }
+
+    const note: VisualNote = {
+      id: noteId,
+      projectId,
+      sessionId: payload.sessionId,
+      type: payload.noteType || 'element',
+      message: payload.message,
+      route: payload.route || '/',
+      url: payload.url || '',
+      viewport: payload.viewport || { width: 1280, height: 800, devicePixelRatio: 1 },
+      scroll: payload.scroll || { scrollX: 0, scrollY: 0 },
+      target: payload.target,
+      elementContext: payload.elementContext,
+      region: payload.region,
+      status: 'OPEN',
+      incidentId: payload.incidentId,
+      screenshots: screenshotPath ? { original: screenshotPath } : undefined,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    this.db.insertNote(note);
+    return note;
+  }
+
+  public saveNoteScreenshot(projectId: string, noteId: string, name: string, dataUrl: string): string | null {
+    try {
+      if (!dataUrl || !dataUrl.startsWith('data:image/')) return null;
+
+      const match = dataUrl.match(/^data:image\/([a-zA-Z0-9+]+);base64,(.+)$/);
+      if (!match) return null;
+
+      let format = match[1].toLowerCase();
+      if (format === 'jpeg') format = 'jpg';
+      const base64Data = match[2];
+      const buffer = Buffer.from(base64Data, 'base64');
+
+      const targetDir = path.join((this.screenshotStore as any).baseDir, projectId || 'default', 'notes', noteId);
+      fs.mkdirSync(targetDir, { recursive: true });
+
+      const fileName = `${name}.${format}`;
+      const filePath = path.join(targetDir, fileName);
+
+      fs.writeFileSync(filePath, buffer);
+      return filePath;
+    } catch {
+      return null;
+    }
+  }
+}

package/packages/daemon/src/notes/verification.ts

@@ -0,0 +1,191 @@
+import crypto from 'node:crypto';
+import type { DOMRectJson, NoteStatus, NoteVerificationResult, OverflowCheckResult, VisualNote } from '../../../core/src/index.js';
+import type { NotesEngine } from './engine.js';
+import type { SessionManager } from '../session/manager.js';
+import type { StorageDB } from '../storage/db.js';
+
+export class NoteVerificationEngine {
+  private db: StorageDB;
+  private sessionManager: SessionManager;
+  private notesEngine: NotesEngine;
+
+  constructor(db: StorageDB, sessionManager: SessionManager, notesEngine: NotesEngine) {
+    this.db = db;
+    this.sessionManager = sessionManager;
+    this.notesEngine = notesEngine;
+  }
+
+  public async verifyNote(noteId: string, options: { observationWindowMs?: number } = {}): Promise<NoteVerificationResult> {
+    const note = this.db.getNote(noteId);
+    if (!note) {
+      return {
+        noteId,
+        status: 'FAILED',
+        checks: [{ type: 'note_exists', passed: false, details: `Note ${noteId} not found` }],
+        timestamp: new Date().toISOString(),
+        message: `Note ${noteId} not found in database`,
+      };
+    }
+
+    // 1. Find active session
+    let session = this.sessionManager.getActiveSessionForProject(note.projectId);
+    if (!session) {
+      session = this.sessionManager.getAnyActiveSession();
+    }
+
+    if (!session) {
+      const result: NoteVerificationResult = {
+        noteId,
+        status: 'INCONCLUSIVE',
+        checks: [],
+        timestamp: new Date().toISOString(),
+        message: 'No active browser session currently connected to verify visual note.',
+      };
+      this.recordNoteVerification(result, note);
+      return result;
+    }
+
+    // 2. Set status to VERIFYING
+    this.db.updateNoteStatus(noteId, 'VERIFYING');
+
+    // 3. Navigation check / route sync
+    const pageStateCmd = await this.sessionManager.sendCommand(session.id, {
+      id: `cmd_${crypto.randomUUID().slice(0, 8)}`,
+      type: 'get_page_state',
+    });
+
+    const currentRoute = pageStateCmd.result?.route || '/';
+    const isRouteMatch = currentRoute === note.route || currentRoute.startsWith(note.route);
+
+    if (!isRouteMatch && note.route) {
+      await this.sessionManager.sendCommand(session.id, {
+        id: `cmd_${crypto.randomUUID().slice(0, 8)}`,
+        type: 'navigate',
+        params: { url: note.route },
+      });
+      // Wait for navigation observation window
+      await new Promise((r) => setTimeout(r, options.observationWindowMs || 1000));
+    }
+
+    const checks: Array<{ type: string; passed: boolean; details?: string }> = [];
+
+    checks.push({
+      type: 'route_loaded',
+      passed: true,
+      details: `Route ${note.route || '/'} loaded`,
+    });
+
+    // 4. Target element checks
+    const targetSelector = note.target?.selector || (note.type === 'page' ? 'body' : 'body');
+    let elementExists = true;
+    let elementVisible = true;
+    let currentRect: DOMRectJson | undefined;
+    let overflowResult: OverflowCheckResult | undefined;
+
+    if (note.type === 'element' && targetSelector) {
+      const queryCmd = await this.sessionManager.sendCommand(session.id, {
+        id: `cmd_${crypto.randomUUID().slice(0, 8)}`,
+        type: 'query_element',
+        params: { selector: targetSelector },
+      });
+
+      elementExists = queryCmd.ok && !!queryCmd.result?.exists;
+      elementVisible = queryCmd.ok && !!queryCmd.result?.visible;
+      currentRect = queryCmd.result?.boundingRect;
+
+      checks.push({
+        type: 'element_exists',
+        passed: elementExists,
+        details: elementExists ? `Element ${targetSelector} exists in DOM` : `Element ${targetSelector} not found`,
+      });
+
+      checks.push({
+        type: 'element_visible',
+        passed: elementVisible,
+        details: elementVisible ? `Element ${targetSelector} is visible` : `Element ${targetSelector} is hidden`,
+      });
+
+      // 5. Layout Overflow Probe
+      const overflowCmd = await this.sessionManager.sendCommand(session.id, {
+        id: `cmd_${crypto.randomUUID().slice(0, 8)}`,
+        type: 'check_overflow',
+        params: { selector: targetSelector },
+      });
+
+      if (overflowCmd.ok && overflowCmd.result) {
+        const ovf = overflowCmd.result as OverflowCheckResult;
+        overflowResult = ovf;
+        const isOverflowingNow = !!ovf.overflow;
+
+        checks.push({
+          type: 'no_viewport_overflow',
+          passed: !isOverflowingNow,
+          details: !isOverflowingNow
+            ? `Element fits within viewport (width: ${ovf.viewportWidth}px, rect right: ${ovf.rect?.right}px)`
+            : `Element overflows viewport by ${ovf.overflowRightPx}px (rect right: ${ovf.rect?.right}px, viewport: ${ovf.viewportWidth}px)`,
+        });
+      }
+    }
+
+    // 6. Capture "after" screenshot
+    let afterScreenshotPath: string | undefined;
+    const captureCmd = await this.sessionManager.sendCommand(session.id, {
+      id: `cmd_${crypto.randomUUID().slice(0, 8)}`,
+      type: 'capture_element',
+      params: { selector: targetSelector },
+    });
+
+    if (captureCmd.ok && captureCmd.result?.dataUrl) {
+      const saved = this.notesEngine.saveNoteScreenshot(note.projectId, note.id, 'after', captureCmd.result.dataUrl);
+      if (saved) {
+        afterScreenshotPath = saved;
+      }
+    }
+
+    // 7. Calculate Geometry Difference
+    const beforeRect = note.target?.boundingRect;
+    const overflowFixed = overflowResult ? !overflowResult.overflow : undefined;
+
+    const geometryDiff = {
+      before: beforeRect,
+      current: currentRect || (overflowResult?.rect as DOMRectJson),
+      viewportWidth: overflowResult?.viewportWidth || note.viewport.width,
+      overflowFixed,
+      overflowPx: overflowResult?.overflowRightPx || 0,
+    };
+
+    // 8. Verdict
+    const anyFailed = checks.some((c) => !c.passed);
+    let status: NoteStatus = 'VERIFIED';
+
+    if (anyFailed) {
+      status = 'FAILED';
+    } else {
+      status = 'VERIFIED';
+    }
+
+    const verificationResult: NoteVerificationResult = {
+      noteId,
+      status,
+      checks,
+      geometryDiff,
+      screenshots: {
+        before: note.screenshots?.original,
+        after: afterScreenshotPath,
+      },
+      timestamp: new Date().toISOString(),
+      message:
+        status === 'VERIFIED'
+          ? 'Visual note verified: target element is present, visible, and layout checks (including viewport overflow) passed.'
+          : 'Visual note verification failed: target element missing, hidden, or still overflowing.',
+    };
+
+    this.recordNoteVerification(verificationResult, note);
+    return verificationResult;
+  }
+
+  private recordNoteVerification(result: NoteVerificationResult, note: VisualNote): void {
+    this.db.updateNoteStatus(note.id, result.status);
+    this.db.insertNoteVerification(result);
+  }
+}

package/packages/daemon/src/server/daemon.ts

@@ -0,0 +1,112 @@
+import http from 'node:http';
+import { WebSocketServer } from 'ws';
+import type { DaemonConfig } from '../config.js';
+import { getDaemonConfig } from '../config.js';
+import { IncidentEngine } from '../incidents/engine.js';
+import { NotesEngine } from '../notes/engine.js';
+import { NoteVerificationEngine } from '../notes/verification.js';
+import { SessionManager } from '../session/manager.js';
+import { StorageDB } from '../storage/db.js';
+import { ScreenshotStore } from '../storage/screenshot-store.js';
+import { VerificationEngine } from '../verification/engine.js';
+import { createHttpHandler } from './http.js';
+import { setupWebSocketServer } from './ws.js';
+
+export class BrowserTrackDaemon {
+  public config: DaemonConfig;
+  public db: StorageDB;
+  public screenshotStore: ScreenshotStore;
+  public sessionManager: SessionManager;
+  public incidentEngine: IncidentEngine;
+  public notesEngine: NotesEngine;
+  public verificationEngine: VerificationEngine;
+  public noteVerificationEngine: NoteVerificationEngine;
+
+  private httpServer: http.Server | null = null;
+  private wss: WebSocketServer | null = null;
+  private isRunning = false;
+
+  constructor(config: Partial<DaemonConfig> = {}) {
+    this.config = getDaemonConfig(config);
+    this.db = new StorageDB(this.config.dbPath);
+    this.screenshotStore = new ScreenshotStore(this.config.screenshotsDir);
+    this.sessionManager = new SessionManager(this.db);
+    this.incidentEngine = new IncidentEngine(this.db, this.screenshotStore);
+    this.notesEngine = new NotesEngine(this.db, this.screenshotStore);
+    this.verificationEngine = new VerificationEngine(this.db, this.sessionManager, this.screenshotStore);
+    this.noteVerificationEngine = new NoteVerificationEngine(this.db, this.sessionManager, this.notesEngine);
+  }
+
+  public async start(): Promise<void> {
+    if (this.isRunning) return;
+
+    const httpHandler = createHttpHandler(this.db, this.sessionManager, this.config.screenshotsDir);
+    this.httpServer = http.createServer(httpHandler);
+
+    this.wss = new WebSocketServer({ server: this.httpServer });
+    setupWebSocketServer(
+      this.wss,
+      this.db,
+      this.sessionManager,
+      this.incidentEngine,
+      this.notesEngine,
+      this.config.maxEventsPerSession,
+      this.config.verbose
+    );
+
+    await new Promise<void>((resolve, reject) => {
+      this.httpServer!.listen(this.config.port, this.config.host, () => {
+        this.isRunning = true;
+        if (this.config.verbose) {
+          console.log(`[BrowserTrack] Daemon running at http://${this.config.host}:${this.config.port}`);
+        }
+        resolve();
+      });
+
+      this.httpServer!.once('error', (err) => {
+        reject(err);
+      });
+    });
+  }
+
+  public async stop(): Promise<void> {
+    if (!this.isRunning) return;
+
+    if (this.wss) {
+      for (const client of this.wss.clients) {
+        try {
+          client.terminate();
+        } catch {}
+      }
+      await new Promise<void>((resolve) => {
+        this.wss!.close(() => resolve());
+      });
+      this.wss = null;
+    }
+
+    if (this.httpServer) {
+      if (typeof (this.httpServer as any).closeAllConnections === 'function') {
+        (this.httpServer as any).closeAllConnections();
+      }
+      await new Promise<void>((resolve) => {
+        this.httpServer!.close(() => resolve());
+      });
+      this.httpServer = null;
+    }
+
+    try {
+      this.db.close();
+    } catch {}
+    this.isRunning = false;
+  }
+
+  public getStatus(): { isRunning: boolean; host: string; port: number; activeSessions: number; dbPath: string } {
+    return {
+      isRunning: this.isRunning,
+      host: this.config.host,
+      port: this.config.port,
+      activeSessions: this.sessionManager.getActiveCount(),
+      dbPath: this.config.dbPath,
+    };
+  }
+}