browsertrack 0.2.0 → 0.2.2

package/packages/mcp/src/server.ts

@@ -1,3 +1,7 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -7,18 +11,98 @@ 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 { VerificationEngine, createDaemon } from '../../daemon/src/index.js';
 import type { McpContext } from './handlers.js';
 import { handleToolCall } from './handlers.js';
 import { TOOLS } from './tools.js';
 
+export async function isDaemonRunning(host: string, port: number): Promise<boolean> {
+  try {
+    const res = await fetch(`http://${host}:${port}/health`, {
+      signal: AbortSignal.timeout(600),
+    });
+    if (res.ok) {
+      const data = (await res.json().catch(() => ({}))) as any;
+      return data?.name === 'browsertrack';
+    }
+  } catch {}
+  return false;
+}
+
+function resolveCliPath(): string | null {
+  if (process.argv[1]) {
+    const candidate = process.argv[1];
+    if (
+      candidate.endsWith('cli/index.js') ||
+      candidate.endsWith('browsertrack') ||
+      candidate.endsWith('bin/browsertrack.js') ||
+      candidate.endsWith('dist/cli/index.js')
+    ) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  try {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const paths = [
+      path.resolve(currentDir, '../cli/index.js'),
+      path.resolve(currentDir, '../../cli/index.js'),
+      path.resolve(currentDir, '../../dist/cli/index.js'),
+    ];
+    for (const p of paths) {
+      if (fs.existsSync(p)) return p;
+    }
+  } catch {}
+
+  return null;
+}
+
+function acquireBootLock(lockFile: string): boolean {
+  try {
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    const fd = fs.openSync(lockFile, 'wx');
+    fs.writeSync(fd, String(process.pid));
+    fs.closeSync(fd);
+    return true;
+  } catch {
+    try {
+      const stats = fs.statSync(lockFile);
+      // If older than 5 seconds, assume stale lock and break it
+      if (Date.now() - stats.mtimeMs > 5000) {
+        fs.unlinkSync(lockFile);
+        const fd = fs.openSync(lockFile, 'wx');
+        fs.writeSync(fd, String(process.pid));
+        fs.closeSync(fd);
+        return true;
+      }
+    } catch {}
+    return false;
+  }
+}
+
+function releaseBootLock(lockFile: string): void {
+  try {
+    if (fs.existsSync(lockFile)) {
+      fs.unlinkSync(lockFile);
+    }
+  } catch {}
+}
+
 export interface McpServerOptions {
   dbPath?: string;
   context?: Partial<McpContext>;
+  autoStartDaemon?: boolean;
+  port?: number;
+  host?: string;
+  detached?: boolean;
 }
 
 export function createMcpServer(options: McpServerOptions = {}) {
-  const config = getDaemonConfig({ dbPath: options.dbPath });
+  const config = getDaemonConfig({
+    dbPath: options.dbPath,
+    port: options.port,
+    host: options.host,
+  });
   const db = options.context?.db || new StorageDB(config.dbPath);
   const screenshotStore = new ScreenshotStore(config.screenshotsDir);
   const sessionManager = options.context?.sessionManager || new SessionManager(db);
@@ -35,6 +119,113 @@ export function createMcpServer(options: McpServerOptions = {}) {
     ...options.context,
   };
 
+  let embeddedDaemon: any = null;
+
+  async function ensureDaemon(): Promise<void> {
+    if (options.autoStartDaemon === false || options.context?.sessionManager) {
+      return;
+    }
+
+    // 1. Fast path: check if a singleton daemon is already running
+    if (await isDaemonRunning(config.host, config.port)) {
+      console.error(`[BrowserTrack MCP] Connected to active singleton daemon at http://${config.host}:${config.port}`);
+      return;
+    }
+
+    // 2. Concurrency lock to guarantee only ONE daemon is ever started across multiple IDE sessions
+    const lockFile = path.join(config.dataDir, 'daemon_boot.lock');
+    const hasLock = acquireBootLock(lockFile);
+
+    if (!hasLock) {
+      // Another session is currently booting the daemon, wait for it
+      for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 100));
+        if (await isDaemonRunning(config.host, config.port)) {
+          console.error(`[BrowserTrack MCP] Connected to shared singleton daemon at http://${config.host}:${config.port}`);
+          return;
+        }
+      }
+    }
+
+    try {
+      // 3. Double-check before starting
+      if (await isDaemonRunning(config.host, config.port)) {
+        console.error(`[BrowserTrack MCP] Connected to shared singleton daemon at http://${config.host}:${config.port}`);
+        return;
+      }
+
+      // 4. Detached background process (singleton daemon that survives across IDE windows/sessions)
+      if (options.detached !== false) {
+        const cliPath = resolveCliPath();
+        if (cliPath && fs.existsSync(cliPath)) {
+          try {
+            const child = spawn(
+              process.execPath,
+              [cliPath, 'start', '--port', String(config.port), '--host', config.host],
+              {
+                detached: true,
+                stdio: 'ignore',
+                env: { ...process.env, BROWSERTRACK_DAEMON_DETACHED: '1' },
+              }
+            );
+            child.unref();
+
+            for (let i = 0; i < 30; i++) {
+              await new Promise((r) => setTimeout(r, 100));
+              if (await isDaemonRunning(config.host, config.port)) {
+                console.error(
+                  `[BrowserTrack MCP] Started singleton background daemon on http://${config.host}:${config.port}`
+                );
+                return;
+              }
+            }
+          } catch (spawnErr: any) {
+            console.error(
+              `[BrowserTrack MCP] Detached daemon spawn failed (${spawnErr?.message}), falling back to in-process daemon.`
+            );
+          }
+        }
+      }
+
+      // 5. In-process fallback (used when detached is false or in test runners)
+      embeddedDaemon = createDaemon({
+        host: config.host,
+        port: config.port,
+        dbPath: config.dbPath,
+        screenshotsDir: config.screenshotsDir,
+        verbose: false,
+      });
+      await embeddedDaemon.start();
+      console.error(`[BrowserTrack MCP] Started singleton daemon on http://${config.host}:${config.port}`);
+
+      ctx.db = embeddedDaemon.db;
+      ctx.sessionManager = embeddedDaemon.sessionManager;
+      ctx.verificationEngine = embeddedDaemon.verificationEngine;
+      ctx.noteVerificationEngine = embeddedDaemon.noteVerificationEngine;
+
+      const cleanup = () => {
+        if (embeddedDaemon) {
+          try {
+            embeddedDaemon.stop();
+          } catch {}
+          embeddedDaemon = null;
+        }
+      };
+
+      process.on('exit', cleanup);
+      process.on('SIGINT', cleanup);
+      process.on('SIGTERM', cleanup);
+    } catch (err: any) {
+      console.error(
+        `[BrowserTrack MCP] Note: Daemon startup skipped (${err?.message}). Running MCP in standalone database mode.`
+      );
+    } finally {
+      if (hasLock) {
+        releaseBootLock(lockFile);
+      }
+    }
+  }
+
   const server = new Server(
     {
       name: 'browsertrack-mcp',
@@ -78,7 +269,16 @@ export function createMcpServer(options: McpServerOptions = {}) {
 
   return {
     server,
+    ctx,
+    ensureDaemon,
+    async stopDaemon() {
+      if (embeddedDaemon) {
+        await embeddedDaemon.stop();
+        embeddedDaemon = null;
+      }
+    },
     async startStdio() {
+      await ensureDaemon();
       const transport = new StdioServerTransport();
       await server.connect(transport);
     },

package/test/client/component-resolver.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { resolveComponentSource } from '../../packages/client/src/source/resolver.js';
+
+describe('Component & Source-Map Resolver', () => {
+  it('should resolve React component name, source file, line number, and hierarchy from Fiber', () => {
+    const parentFiber = {
+      type: { name: 'ShopLayout', displayName: 'ShopLayout' },
+      return: {
+        type: { name: 'App' },
+        return: null,
+      },
+    };
+
+    const ownerFiber = {
+      type: { name: 'CheckoutButton' },
+      _debugSource: {
+        fileName: 'src/components/CheckoutButton.tsx',
+        lineNumber: 42,
+        columnNumber: 8,
+      },
+    };
+
+    const hostFiber = {
+      type: 'button',
+      _debugSource: {
+        fileName: 'src/components/CheckoutButton.tsx',
+        lineNumber: 42,
+        columnNumber: 8,
+      },
+      _debugOwner: ownerFiber,
+      return: {
+        type: { name: 'CheckoutButton' },
+        memoizedProps: { label: 'Complete Purchase', amount: 49.99 },
+        return: parentFiber,
+      },
+    };
+
+    const fakeButton = {
+      tagName: 'BUTTON',
+      __reactFiber$abc123: hostFiber,
+    } as any;
+
+    const resolved = resolveComponentSource(fakeButton);
+    expect(resolved).toBeDefined();
+    expect(resolved?.framework).toBe('react');
+    expect(resolved?.componentName).toBe('CheckoutButton');
+    expect(resolved?.sourceFile).toBe('src/components/CheckoutButton.tsx');
+    expect(resolved?.sourceLine).toBe(42);
+    expect(resolved?.sourceColumn).toBe(8);
+    expect(resolved?.hierarchy).toContain('CheckoutButton');
+    expect(resolved?.hierarchy).toContain('ShopLayout');
+    expect(resolved?.hierarchy).toContain('App');
+    expect(resolved?.props?.label).toBe('Complete Purchase');
+    expect(resolved?.props?.amount).toBe(49.99);
+  });
+
+  it('should resolve Vue 3 component name and source file from __vueParentComponent', () => {
+    const fakeVueElement = {
+      tagName: 'DIV',
+      __vueParentComponent: {
+        type: {
+          __name: 'UserProfileCard',
+          __file: 'src/components/UserProfileCard.vue?t=12345',
+        },
+        props: {
+          username: 'alice',
+          isAdmin: false,
+        },
+        parent: {
+          type: { name: 'DashboardView' },
+          parent: null,
+        },
+      },
+    } as any;
+
+    const resolved = resolveComponentSource(fakeVueElement);
+    expect(resolved).toBeDefined();
+    expect(resolved?.framework).toBe('vue');
+    expect(resolved?.componentName).toBe('UserProfileCard');
+    expect(resolved?.sourceFile).toBe('src/components/UserProfileCard.vue');
+    expect(resolved?.hierarchy).toEqual(['DashboardView', 'UserProfileCard']);
+    expect(resolved?.props?.username).toBe('alice');
+  });
+
+  it('should resolve Svelte component source location from __svelte_meta', () => {
+    const fakeSvelteElement = {
+      tagName: 'DIV',
+      __svelte_meta: {
+        loc: {
+          file: 'src/routes/Counter.svelte',
+          line: 18,
+          column: 4,
+        },
+      },
+    } as any;
+
+    const resolved = resolveComponentSource(fakeSvelteElement);
+    expect(resolved).toBeDefined();
+    expect(resolved?.framework).toBe('svelte');
+    expect(resolved?.sourceFile).toBe('src/routes/Counter.svelte');
+    expect(resolved?.sourceLine).toBe(18);
+    expect(resolved?.componentName).toBe('Counter');
+  });
+
+  it('should identify Custom Elements / Web Components by hyphenated tag name', () => {
+    const fakeCustomElement = {
+      tagName: 'USER-BADGE',
+    } as any;
+
+    const resolved = resolveComponentSource(fakeCustomElement);
+    expect(resolved).toBeDefined();
+    expect(resolved?.framework).toBe('web-component');
+    expect(resolved?.componentName).toBe('user-badge');
+  });
+
+  it('should fallback to data-component and data-source-file attributes', () => {
+    const fakeElement = {
+      tagName: 'DIV',
+      closest: (selector: string) => {
+        if (selector.includes('data-component')) {
+          return {
+            getAttribute: (attr: string) => {
+              if (attr === 'data-component') return 'MarketingBanner';
+              if (attr === 'data-source-file') return 'src/components/Banner.tsx';
+              if (attr === 'data-source-line') return '88';
+              return null;
+            },
+          };
+        }
+        return null;
+      },
+    } as any;
+
+    const resolved = resolveComponentSource(fakeElement);
+    expect(resolved).toBeDefined();
+    expect(resolved?.framework).toBe('vanilla');
+    expect(resolved?.componentName).toBe('MarketingBanner');
+    expect(resolved?.sourceFile).toBe('src/components/Banner.tsx');
+    expect(resolved?.sourceLine).toBe(88);
+  });
+});

package/test/client/interceptors.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { BreadcrumbBuffer } from '../../packages/client/src/breadcrumbs.js';
+import { shouldHideUIFromUrl } from '../../packages/client/src/config.js';
 import { setupConsoleInterceptors } from '../../packages/client/src/interceptors/console.js';
 import { NoteInspector } from '../../packages/client/src/notes/inspector.js';
 import { getSemanticSelector } from '../../packages/core/src/selector.js';
@@ -191,4 +192,59 @@ describe('Client Interceptors & Utilities', () => {
 
     inspector.destroy();
   });
+
+  it('should detect UI hide directives from various URL query strings', () => {
+    // Built-in ?bt=0, ?bt=false, ?bt=hidden, ?bt=off, ?bt=none
+    expect(shouldHideUIFromUrl(undefined, '?bt=0')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?bt=false')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?bt=hidden')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?bt=off')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?bt=none')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?bt=disabled')).toBe(true);
+
+    // ?browsertrack=false, ?browsertrack=0, ?browsertrack=hidden
+    expect(shouldHideUIFromUrl(undefined, '?browsertrack=false')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?browsertrack=0')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?browsertrack=hidden')).toBe(true);
+
+    // Flags: ?no_bt, ?no_browsertrack, ?hide_bt, ?hide_browsertrack
+    expect(shouldHideUIFromUrl(undefined, '?no_bt')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?no_bt=1')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?no_browsertrack')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?hide_bt=1')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?hide_browsertrack=true')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?bt_ui=0')).toBe(true);
+    expect(shouldHideUIFromUrl(undefined, '?bt_hide=1')).toBe(true);
+
+    // Custom query parameters
+    expect(shouldHideUIFromUrl('clean_view', '?clean_view=1')).toBe(true);
+    expect(shouldHideUIFromUrl(['e2e', 'cypress'], '?cypress=true')).toBe(true);
+
+    // Non-hide queries
+    expect(shouldHideUIFromUrl(undefined, '')).toBe(false);
+    expect(shouldHideUIFromUrl(undefined, '?user=alice&tab=profile')).toBe(false);
+    expect(shouldHideUIFromUrl(undefined, '?bt=1')).toBe(false);
+    expect(shouldHideUIFromUrl(undefined, '?bt=true')).toBe(false);
+  });
+
+  it('should support hiding and toggling visibility in NoteInspector and BrowserTrackClient', () => {
+    const mockTransport = { send: vi.fn(), getSessionId: () => 'sess_123', onMessage: vi.fn(() => () => {}) } as any;
+    const mockDriver = { captureElement: vi.fn() } as any;
+
+    const hiddenInspector = new NoteInspector(mockTransport, mockDriver, {
+      showToolbar: true,
+      hidden: true,
+    });
+
+    expect(hiddenInspector.isVisible()).toBe(false);
+
+    // Toggling visibility
+    hiddenInspector.setVisible(true);
+    expect(hiddenInspector.isVisible()).toBe(true);
+
+    hiddenInspector.setVisible(false);
+    expect(hiddenInspector.isVisible()).toBe(false);
+
+    hiddenInspector.destroy();
+  });
 });

package/test/core/safety.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from 'vitest';
+import { safeAsync, safeExecute, safeJsonParse, safeJsonStringify } from '../../packages/core/src/safety.js';
+
+describe('BrowserTrack Core Safety Utilities', () => {
+  describe('safeJsonParse', () => {
+    it('should parse valid JSON correctly', () => {
+      const result = safeJsonParse('{"foo":"bar","num":42}', {});
+      expect(result).toEqual({ foo: 'bar', num: 42 });
+    });
+
+    it('should return fallback on malformed JSON without throwing', () => {
+      const fallback = { status: 'fallback' };
+      const result = safeJsonParse('{ broken json: true', fallback);
+      expect(result).toBe(fallback);
+    });
+
+    it('should handle null, undefined, or empty string gracefully', () => {
+      expect(safeJsonParse(null, 'default')).toBe('default');
+      expect(safeJsonParse(undefined, 'default')).toBe('default');
+      expect(safeJsonParse('', 'default')).toBe('default');
+    });
+
+    it('should return raw object if input is already parsed object', () => {
+      const obj = { already: 'object' };
+      expect(safeJsonParse(obj, {})).toBe(obj);
+    });
+  });
+
+  describe('safeJsonStringify', () => {
+    it('should serialize simple objects into valid JSON', () => {
+      const json = safeJsonStringify({ name: 'BrowserTrack', active: true });
+      expect(JSON.parse(json)).toEqual({ name: 'BrowserTrack', active: true });
+    });
+
+    it('should serialize circular structures without throwing', () => {
+      const circular: any = { name: 'circular-node' };
+      circular.self = circular;
+      circular.child = { parent: circular };
+
+      let json = '';
+      expect(() => {
+        json = safeJsonStringify(circular);
+      }).not.toThrow();
+
+      expect(json).toContain('[Circular]');
+      const parsed = JSON.parse(json);
+      expect(parsed.name).toBe('circular-node');
+      expect(parsed.self).toBe('[Circular]');
+      expect(parsed.child.parent).toBe('[Circular]');
+    });
+
+    it('should serialize BigInt without throwing', () => {
+      const obj = { id: BigInt(9007199254740991) };
+      expect(() => safeJsonStringify(obj)).not.toThrow();
+      expect(safeJsonStringify(obj)).toContain('9007199254740991');
+    });
+
+    it('should handle undefined gracefully', () => {
+      expect(safeJsonStringify(undefined, 'empty')).toBe('empty');
+    });
+  });
+
+  describe('safeExecute', () => {
+    it('should return function result on success', () => {
+      const res = safeExecute(() => 10 + 20, 0);
+      expect(res).toBe(30);
+    });
+
+    it('should return fallback on error and notify onError callback', () => {
+      const errorHandler = vi.fn();
+      const res = safeExecute(
+        () => {
+          throw new Error('Test crash');
+        },
+        -1,
+        errorHandler
+      );
+
+      expect(res).toBe(-1);
+      expect(errorHandler).toHaveBeenCalledTimes(1);
+      expect(errorHandler.mock.calls[0][0].message).toBe('Test crash');
+    });
+  });
+
+  describe('safeAsync', () => {
+    it('should resolve async function correctly', async () => {
+      const res = await safeAsync(async () => 'resolved_val', 'fallback');
+      expect(res).toBe('resolved_val');
+    });
+
+    it('should catch rejection without throwing and return fallback', async () => {
+      const errorHandler = vi.fn();
+      const res = await safeAsync(
+        async () => {
+          throw new Error('Async boom');
+        },
+        'fallback',
+        errorHandler
+      );
+
+      expect(res).toBe('fallback');
+      expect(errorHandler).toHaveBeenCalledTimes(1);
+      expect(errorHandler.mock.calls[0][0].message).toBe('Async boom');
+    });
+  });
+});

package/test/daemon/storage.test.ts

@@ -120,4 +120,40 @@ describe('StorageDB (SQLite)', () => {
     const updated = db.getIncident('inc_1');
     expect(updated?.occurrences).toBe(2);
   });
+
+  it('should seamlessly migrate a legacy database without scenario columns', () => {
+    const legacyDbPath = path.join(os.tmpdir(), `bt_legacy_${Date.now()}.db`);
+    try {
+      // Create legacy database with old notes schema lacking scenario_id
+      const Database = (db as any).db.constructor;
+      const legacyRaw = new Database(legacyDbPath);
+      legacyRaw.exec(`
+        CREATE TABLE notes (
+          id TEXT PRIMARY KEY,
+          project_id TEXT,
+          session_id TEXT,
+          type TEXT,
+          message TEXT,
+          route TEXT,
+          url TEXT,
+          status TEXT DEFAULT 'OPEN',
+          created_at TEXT,
+          updated_at TEXT
+        );
+      `);
+      legacyRaw.close();
+
+      // Opening with StorageDB should not throw "no such column: scenario_id"
+      const migratedDb = new StorageDB(legacyDbPath);
+      const cols = (migratedDb as any).db.prepare('PRAGMA table_info(notes)').all().map((c: any) => c.name);
+      expect(cols).toContain('scenario_id');
+      expect(cols).toContain('step_number');
+      expect(cols).toContain('scenario_title');
+      migratedDb.close();
+    } finally {
+      if (fs.existsSync(legacyDbPath)) {
+        fs.unlinkSync(legacyDbPath);
+      }
+    }
+  });
 });

package/test/e2e/daemon-mcp-e2e.test.ts

@@ -149,5 +149,15 @@ describe('BrowserTrack Full E2E Lifecycle (Daemon + WebSocket Client + MCP)', ()
 
     expect(pageState.url).toBe('http://localhost:5173/products/123');
     expect(pageState.title).toBe('Product Details');
+
+    // 6. Test Multi-process Standalone MCP Tool Call (no in-process session manager, bridges over HTTP to daemon)
+    const remotePageState = await handleToolCall(
+      'get_page_state',
+      { sessionId: receivedSessionId },
+      { db: daemon.db, daemonUrl: `http://127.0.0.1:${testPort}` }
+    );
+
+    expect(remotePageState.url).toBe('http://localhost:5173/products/123');
+    expect(remotePageState.title).toBe('Product Details');
   });
 });