browsertrack 0.0.1 → 0.1.0

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

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

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { StorageDB } from '../storage/db.js';
+import type { SessionManager } from '../session/manager.js';
+
+export function createHttpHandler(db: StorageDB, sessionManager: SessionManager, baseScreenshotsDir: string) {
+  return (req: http.IncomingMessage, res: http.ServerResponse) => {
+    const parsedUrl = new URL(req.url || '/', `http://${req.headers.host || '127.0.0.1'}`);
+    const pathname = parsedUrl.pathname;
+
+    // CORS headers for local development access
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    // 1. Health check
+    if (pathname === '/health' || pathname === '/') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          status: 'ok',
+          name: 'browsertrack',
+          version: '0.1.0',
+          activeSessions: sessionManager.getActiveCount(),
+          timestamp: new Date().toISOString(),
+        })
+      );
+      return;
+    }
+
+    // 2. Client script tag bundle
+    if (pathname === '/client.js' || pathname === '/browserdiag.js') {
+      let scriptContent = '';
+      try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        // Look in dist or adjacent package
+        const candidatePaths = [
+          path.resolve(__dirname, '../client.iife.js'),
+          path.resolve(__dirname, '../../dist/client.iife.js'),
+          path.resolve(__dirname, '../../../dist/client.iife.js'),
+        ];
+
+        for (const p of candidatePaths) {
+          if (fs.existsSync(p)) {
+            scriptContent = fs.readFileSync(p, 'utf-8');
+            break;
+          }
+        }
+      } catch {}
+
+      if (!scriptContent) {
+        scriptContent = `console.warn("[BrowserTrack] Standalone client bundle not built yet. Run 'npm run build'.");`;
+      }
+
+      res.writeHead(200, {
+        'Content-Type': 'application/javascript; charset=utf-8',
+        'Cache-Control': 'no-cache',
+      });
+      res.end(scriptContent);
+      return;
+    }
+
+    // 3. API - Projects
+    if (pathname === '/api/projects') {
+      const projects = db.listProjects();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, projects }));
+      return;
+    }
+
+    // 4. API - Sessions
+    if (pathname === '/api/sessions') {
+      const projectId = parsedUrl.searchParams.get('project') || undefined;
+      const activeOnly = parsedUrl.searchParams.get('active') === 'true';
+      const sessions = db.listSessions(projectId, activeOnly);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, sessions }));
+      return;
+    }
+
+    // 5. API - Incidents
+    if (pathname === '/api/incidents') {
+      const projectId = parsedUrl.searchParams.get('project') || undefined;
+      const status = (parsedUrl.searchParams.get('status') as any) || undefined;
+      const limit = parseInt(parsedUrl.searchParams.get('limit') || '50', 10);
+      const incidents = db.listIncidents({ projectId, status, limit });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, incidents }));
+      return;
+    }
+
+    // 6. API - Incident Detail
+    if (pathname.startsWith('/api/incidents/')) {
+      const incidentId = pathname.replace('/api/incidents/', '');
+      const incident = db.getIncident(incidentId);
+      if (!incident) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'Incident not found' }));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, incident }));
+      return;
+    }
+
+    // 7. API - Notes
+    if (pathname === '/api/notes') {
+      const projectId = parsedUrl.searchParams.get('project') || undefined;
+      const status = (parsedUrl.searchParams.get('status') as any) || undefined;
+      const limit = parseInt(parsedUrl.searchParams.get('limit') || '50', 10);
+      const notes = db.listNotes({ projectId, status, limit });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, notes }));
+      return;
+    }
+
+    // 8. API - Note Detail
+    if (pathname.startsWith('/api/notes/')) {
+      const noteId = pathname.replace('/api/notes/', '');
+      const note = db.getNote(noteId);
+      if (!note) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'Note not found' }));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, note }));
+      return;
+    }
+
+    // 9. Screenshots Serving
+    if (pathname.startsWith('/screenshots/')) {
+      const relativePath = pathname.replace('/screenshots/', '');
+      const filePath = path.join(baseScreenshotsDir, relativePath);
+      if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+        const ext = path.extname(filePath).toLowerCase();
+        const mimeTypes: Record<string, string> = {
+          '.webp': 'image/webp',
+          '.png': 'image/png',
+          '.jpg': 'image/jpeg',
+          '.jpeg': 'image/jpeg',
+        };
+        res.writeHead(200, { 'Content-Type': mimeTypes[ext] || 'application/octet-stream' });
+        fs.createReadStream(filePath).pipe(res);
+        return;
+      }
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'Screenshot not found' }));
+      return;
+    }
+
+    // Not found
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ ok: false, error: 'Not found' }));
+  };
+}

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

@@ -0,0 +1,175 @@
+import crypto from 'node:crypto';
+import type { WebSocket, WebSocketServer } from 'ws';
+import type { ClientEventMessage, CommandResponse, HelloMessage } from '../../../core/src/index.js';
+import type { IncidentEngine } from '../incidents/engine.js';
+import type { NotesEngine } from '../notes/engine.js';
+import type { SessionManager } from '../session/manager.js';
+import type { StorageDB } from '../storage/db.js';
+
+export function setupWebSocketServer(
+  wss: WebSocketServer,
+  db: StorageDB,
+  sessionManager: SessionManager,
+  incidentEngine: IncidentEngine,
+  notesEngine?: NotesEngine,
+  maxEventsPerSession = 1000,
+  verbose = false
+): void {
+  wss.on('connection', (ws: WebSocket) => {
+    let currentSessionId: string | null = null;
+
+    ws.on('message', (raw: string | Buffer) => {
+      try {
+        const text = typeof raw === 'string' ? raw : raw.toString('utf-8');
+        const data = JSON.parse(text);
+
+        // 1. Hello handshake
+        if (data.type === 'hello') {
+          const hello = data as HelloMessage;
+          const sessionId = `sess_${crypto.randomUUID().slice(0, 8)}`;
+          currentSessionId = sessionId;
+
+          // Determine or create project
+          let project = hello.projectId ? db.getProject(hello.projectId) : null;
+          if (!project && hello.origin) {
+            project = db.getProjectByOrigin(hello.origin);
+          }
+          if (!project) {
+            // Auto-create project based on origin or hostname
+            let projName = 'default';
+            try {
+              const url = new URL(hello.origin || 'http://localhost');
+              projName = url.port ? `app-${url.port}` : url.hostname;
+            } catch {
+              projName = 'app';
+            }
+            project = db.upsertProject({
+              id: `proj_${crypto.randomUUID().slice(0, 8)}`,
+              name: projName,
+              origin: hello.origin || 'http://localhost',
+            });
+          }
+
+          const now = new Date().toISOString();
+          db.upsertSession({
+            id: sessionId,
+            projectId: project.id,
+            origin: hello.origin || '',
+            url: hello.url || '',
+            title: hello.title || '',
+            userAgent: hello.userAgent || '',
+            connectedAt: now,
+            lastSeenAt: now,
+            active: true,
+          });
+
+          sessionManager.registerSocket(sessionId, ws, hello.origin || '', project.id);
+
+          ws.send(
+            JSON.stringify({
+              type: 'hello_ack',
+              sessionId,
+              projectId: project.id,
+              projectName: project.name,
+            })
+          );
+
+          if (verbose) {
+            console.log(`[BrowserTrack] New session connected: ${sessionId} (${project.name} @ ${hello.origin})`);
+          }
+          return;
+        }
+
+        // 2. Client Event (runtime error, console, network, breadcrumb)
+        if (data.type === 'event') {
+          const eventMsg = data as ClientEventMessage;
+          const sessionId = eventMsg.sessionId || currentSessionId;
+          if (!sessionId) return;
+
+          const eventId = `evt_${crypto.randomUUID().slice(0, 8)}`;
+          db.insertEvent({
+            id: eventId,
+            sessionId,
+            eventType: eventMsg.eventType,
+            payload: eventMsg.payload,
+            timestamp: eventMsg.timestamp || Date.now(),
+            route: eventMsg.route,
+            url: eventMsg.url,
+          });
+
+          // Session retention prune
+          db.pruneSessionEvents(sessionId, maxEventsPerSession);
+
+          // Incident processing
+          const incident = incidentEngine.processClientEvent(eventMsg);
+          if (incident && verbose) {
+            console.log(
+              `[BrowserTrack] Incident recorded: ${incident.id} (${incident.type}: ${incident.message}) [${incident.occurrences}x]`
+            );
+          }
+          return;
+        }
+
+        // 3. Visual Note Creation
+        if (data.type === 'create_note' && notesEngine) {
+          const note = notesEngine.createNoteFromClient({
+            sessionId: data.sessionId || currentSessionId || '',
+            noteType: data.noteType,
+            message: data.message,
+            route: data.route,
+            url: data.url,
+            viewport: data.viewport,
+            scroll: data.scroll,
+            target: data.target,
+            elementContext: data.elementContext,
+            region: data.region,
+            screenshot: data.screenshot,
+            incidentId: data.incidentId,
+          });
+
+          if (verbose) {
+            console.log(`[BrowserTrack] Visual note created: ${note.id} on ${note.route} ("${note.message}")`);
+          }
+
+          ws.send(
+            JSON.stringify({
+              type: 'note_created_ack',
+              noteId: note.id,
+              status: note.status,
+            })
+          );
+          return;
+        }
+
+        // 4. Command Response
+        if (data.type === 'command_response') {
+          const res = data.response as CommandResponse;
+          const sessionId = data.sessionId || currentSessionId;
+          if (sessionId && res) {
+            sessionManager.handleCommandResponse(sessionId, res);
+          }
+          return;
+        }
+      } catch (err: any) {
+        if (verbose) {
+          console.error('[BrowserTrack] WebSocket message error:', err?.message);
+        }
+      }
+    });
+
+    ws.on('close', () => {
+      if (currentSessionId) {
+        sessionManager.unregisterSocket(currentSessionId);
+        if (verbose) {
+          console.log(`[BrowserTrack] Session disconnected: ${currentSessionId}`);
+        }
+      }
+    });
+
+    ws.on('error', () => {
+      if (currentSessionId) {
+        sessionManager.unregisterSocket(currentSessionId);
+      }
+    });
+  });
+}