browsertrack 0.0.1 → 0.1.0

package/packages/core/src/types/events.ts

@@ -0,0 +1,108 @@
+export type EventType =
+  | 'runtime_error'
+  | 'unhandled_rejection'
+  | 'console'
+  | 'fetch'
+  | 'xhr'
+  | 'navigation'
+  | 'interaction';
+
+export type ConsoleLevel = 'error' | 'warn' | 'info' | 'log' | 'debug';
+
+export interface ElementSummary {
+  selector: string;
+  tag: string;
+  id?: string;
+  classes?: string[];
+  attributes?: Record<string, string>;
+  outerHTML?: string;
+  innerText?: string;
+  boundingRect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+  };
+  visible: boolean;
+}
+
+export interface Breadcrumb {
+  id?: string;
+  type: 'navigation' | 'click' | 'submit' | 'fetch' | 'xhr' | 'console' | 'error';
+  category?: string;
+  message: string;
+  timestamp: number;
+  level?: 'info' | 'warn' | 'error';
+  data?: Record<string, any>;
+  element?: ElementSummary;
+}
+
+export interface NetworkEvent {
+  id?: string;
+  url: string;
+  method: string;
+  status?: number;
+  statusText?: string;
+  durationMs: number;
+  error?: string;
+  aborted?: boolean;
+  timestamp: number;
+  requestHeaders?: Record<string, string>;
+}
+
+export interface RuntimeErrorEvent {
+  message: string;
+  stack?: string;
+  filename?: string;
+  lineno?: number;
+  colno?: number;
+  errorType: string;
+  timestamp: number;
+}
+
+export interface ConsoleEvent {
+  level: ConsoleLevel;
+  message: string;
+  args?: any[];
+  stack?: string;
+  timestamp: number;
+}
+
+export interface NavigationEvent {
+  from?: string;
+  to: string;
+  type: 'pushState' | 'replaceState' | 'popstate' | 'hashchange' | 'initial';
+  timestamp: number;
+}
+
+export interface HelloMessage {
+  type: 'hello';
+  origin: string;
+  url: string;
+  title: string;
+  userAgent: string;
+  timestamp: number;
+  projectId?: string;
+}
+
+export interface ClientEventMessage {
+  type: 'event';
+  sessionId: string;
+  eventType: EventType;
+  payload:
+    | RuntimeErrorEvent
+    | ConsoleEvent
+    | NetworkEvent
+    | NavigationEvent
+    | Breadcrumb;
+  breadcrumbs?: Breadcrumb[];
+  lastElement?: ElementSummary;
+  route?: string;
+  url: string;
+  title?: string;
+  timestamp: number;
+}

package/packages/core/src/types/incidents.ts

@@ -0,0 +1,54 @@
+import type { Breadcrumb, ElementSummary, NetworkEvent } from './events.js';
+
+export type IncidentStatus =
+  | 'OPEN'
+  | 'FIX_ATTEMPTED'
+  | 'VERIFYING'
+  | 'VERIFIED'
+  | 'FAILED'
+  | 'INCONCLUSIVE';
+
+export type IncidentSeverity = 'error' | 'warn' | 'fatal';
+
+export interface IncidentSource {
+  file: string;
+  line: number;
+  column?: number;
+}
+
+export interface Incident {
+  id: string;
+  projectId: string;
+  sessionId: string;
+  type: string;
+  severity: IncidentSeverity;
+  message: string;
+  source: IncidentSource;
+  fingerprint: string;
+  route: string;
+  firstSeen: string;
+  lastSeen: string;
+  occurrences: number;
+  status: IncidentStatus;
+  stack?: string;
+  breadcrumbs: Breadcrumb[];
+  networkFailures: NetworkEvent[];
+  lastElement?: ElementSummary;
+  screenshots?: {
+    error?: string;
+    before?: string;
+    after?: string;
+  };
+}
+
+export interface IncidentOccurrence {
+  id: string;
+  incidentId: string;
+  sessionId: string;
+  timestamp: string;
+  route: string;
+  url: string;
+  stack?: string;
+  breadcrumbs: Breadcrumb[];
+  lastElement?: ElementSummary;
+}

package/packages/core/src/types/notes.ts

@@ -0,0 +1,106 @@
+export type NoteType = 'element' | 'region' | 'page';
+
+export type NoteStatus =
+  | 'OPEN'
+  | 'IN_PROGRESS'
+  | 'VERIFYING'
+  | 'READY_FOR_REVIEW'
+  | 'VERIFIED'
+  | 'RESOLVED'
+  | 'FAILED'
+  | 'INCONCLUSIVE';
+
+export interface ViewportContext {
+  width: number;
+  height: number;
+  devicePixelRatio: number;
+}
+
+export interface ScrollContext {
+  scrollX: number;
+  scrollY: number;
+}
+
+export interface DOMRectJson {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  top: number;
+  left: number;
+  bottom: number;
+  right: number;
+}
+
+export interface NoteTarget {
+  selector: string;
+  boundingRect: DOMRectJson;
+  visible: boolean;
+  confidence?: 'high' | 'medium' | 'low';
+}
+
+export interface ElementContext {
+  selector: string;
+  tag: string;
+  attributes?: Record<string, string>;
+  outerHTML?: string;
+  innerText?: string;
+  parent?: {
+    selector: string;
+    tag: string;
+  };
+}
+
+export interface RegionContext {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface VisualNote {
+  id: string;
+  projectId: string;
+  sessionId: string;
+  type: NoteType;
+  message: string;
+  route: string;
+  url: string;
+  viewport: ViewportContext;
+  scroll: ScrollContext;
+  target?: NoteTarget;
+  elementContext?: ElementContext;
+  region?: RegionContext;
+  status: NoteStatus;
+  incidentId?: string;
+  screenshots?: {
+    original?: string;
+    after?: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+  resolvedAt?: string;
+}
+
+export interface NoteVerificationResult {
+  noteId: string;
+  status: NoteStatus;
+  checks: Array<{
+    type: string;
+    passed: boolean;
+    details?: string;
+  }>;
+  geometryDiff?: {
+    before?: DOMRectJson;
+    current?: DOMRectJson;
+    viewportWidth?: number;
+    overflowFixed?: boolean;
+    overflowPx?: number;
+  };
+  screenshots?: {
+    before?: string;
+    after?: string;
+  };
+  timestamp: string;
+  message?: string;
+}

package/packages/core/src/types/probes.ts

@@ -0,0 +1,44 @@
+import type { IncidentStatus } from './incidents.js';
+
+export type ProbeType =
+  | 'element_exists'
+  | 'element_visible'
+  | 'text_contains'
+  | 'route_is'
+  | 'network_request_succeeded'
+  | 'no_incident';
+
+export interface VerificationProbe {
+  type: ProbeType;
+  selector?: string;
+  text?: string;
+  route?: string;
+  fingerprint?: string;
+  urlPattern?: string;
+  timeoutMs?: number;
+}
+
+export interface VerificationRecipe {
+  route?: string;
+  targetSelector?: string;
+  expect?: VerificationProbe[];
+  observationWindowMs?: number;
+}
+
+export interface ProbeResult {
+  type: ProbeType;
+  passed: boolean;
+  details?: string;
+}
+
+export interface VerificationResult {
+  incidentId: string;
+  status: IncidentStatus;
+  checks: ProbeResult[];
+  screenshots?: {
+    before?: string;
+    after?: string;
+  };
+  timestamp: string;
+  message?: string;
+}

package/packages/core/src/types/projects.ts

@@ -0,0 +1,20 @@
+export interface Project {
+  id: string;
+  name: string;
+  origin: string;
+  path?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface Session {
+  id: string;
+  projectId: string;
+  origin: string;
+  url: string;
+  title: string;
+  userAgent: string;
+  connectedAt: string;
+  lastSeenAt: string;
+  active: boolean;
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}

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;
+    }
+  }
+}