browsertrack 0.2.1 → 0.2.2

package/dist/core/index.d.ts

@@ -83,4 +83,27 @@ declare function getSemanticSelector(element: HTMLElement | Element, options?: S
  */
 declare function truncate(str: string | undefined | null, maxLength?: number): string;
 
-export { BROWSER_SECURITY_RULES, type FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, type SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate };
+/**
+ * BrowserTrack Safety & Error-Resilience Utilities
+ * Provides bulletproof try/catch wrappers, circular-safe JSON serialization, and defensive helpers.
+ */
+/**
+ * Safely parses a JSON string with fallback. Never throws.
+ */
+declare function safeJsonParse<T>(raw: any, fallback: T): T;
+/**
+ * Safely serializes an object to JSON, handling circular references and non-serializable values.
+ * Never throws "TypeError: Converting circular structure to JSON".
+ */
+declare function safeJsonStringify(val: any, fallback?: string): string;
+/**
+ * Executes a synchronous function within an isolated try/catch block.
+ * Returns the function result, or fallback if an exception was thrown.
+ */
+declare function safeExecute<T>(fn: () => T, fallback: T, onError?: (err: any) => void): T;
+/**
+ * Executes an asynchronous promise or async function safely without unhandled rejection.
+ */
+declare function safeAsync<T>(action: Promise<T> | (() => Promise<T>), fallback: T, onError?: (err: any) => void): Promise<T>;
+
+export { BROWSER_SECURITY_RULES, type FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, type SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, safeAsync, safeExecute, safeJsonParse, safeJsonStringify, truncate };

package/dist/core/index.js

@@ -12,10 +12,14 @@ import {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact
-} from "../chunk-6VA7GBAO.js";
+} from "../chunk-QRZ57ME3.js";
 export {
   BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
@@ -30,6 +34,10 @@ export {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact

package/dist/daemon/index.d.ts

@@ -1,4 +1,4 @@
-import { S as StorageDB, b as ScreenshotStore, a as SessionManager, c as NotesEngine, V as VerificationEngine, N as NoteVerificationEngine } from '../engine-CmchnMDq.js';
+import { S as StorageDB, b as ScreenshotStore, a as SessionManager, V as VerificationEngine, N as NoteVerificationEngine, c as NotesEngine } from '../engine-CmchnMDq.js';
 import { c as ClientEventMessage } from '../commands-fjuqKzkm.js';
 import { I as Incident } from '../projects-DB7S312i.js';
 import http from 'node:http';
@@ -25,7 +25,7 @@ declare class IncidentEngine {
     private handleErrorEvent;
 }
 
-declare function createHttpHandler(db: StorageDB, sessionManager: SessionManager, baseScreenshotsDir: string): (req: http.IncomingMessage, res: http.ServerResponse) => void;
+declare function createHttpHandler(db: StorageDB, sessionManager: SessionManager, baseScreenshotsDir: string, verificationEngine?: VerificationEngine, noteVerificationEngine?: NoteVerificationEngine): (req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
 
 declare function setupWebSocketServer(wss: WebSocketServer, db: StorageDB, sessionManager: SessionManager, incidentEngine: IncidentEngine, notesEngine?: NotesEngine, maxEventsPerSession?: number, verbose?: boolean): void;
 

package/dist/daemon/index.js

@@ -1,20 +1,18 @@
 import {
   BrowserTrackDaemon,
   IncidentEngine,
-  createDaemon,
-  createHttpHandler,
-  setupWebSocketServer
-} from "../chunk-7OCOQGDN.js";
-import "../chunk-6VA7GBAO.js";
-import {
   NoteVerificationEngine,
   NotesEngine,
   ScreenshotStore,
   SessionManager,
   StorageDB,
   VerificationEngine,
-  getDaemonConfig
-} from "../chunk-3HOXPTM2.js";
+  createDaemon,
+  createHttpHandler,
+  getDaemonConfig,
+  setupWebSocketServer
+} from "../chunk-AYSVE6NG.js";
+import "../chunk-QRZ57ME3.js";
 export {
   BrowserTrackDaemon,
   IncidentEngine,

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { B as Breadcrumb, C as CaptureElementParams, a as CaptureElementResult, b as ClientCommand, c as ClientEventMessage, d as CommandResponse, e as CommandType, f as ComponentSourceInfo, g as ConsoleEvent, h as ConsoleLevel, D as DOMRectJson, E as ElementContext, i as ElementStyleResult, j as ElementSummary, k as EventType, H as HelloMessage, N as NavigateParams, l as NavigationEvent, m as NetworkEvent, n as NoteStatus, o as NoteTarget, p as NoteType, q as NoteVerificationResult, O as OverflowCheckResult, P as PageStateResult, Q as QueryElementParams, r as QueryElementResult, R as RegionContext, s as ReloadParams, t as RuntimeErrorEvent, S as ScenarioDetail, u as ScenarioOverview, v as ScrollContext, V as ViewportContext, w as VisualNote } from './commands-fjuqKzkm.js';
 export { I as Incident, a as IncidentOccurrence, b as IncidentSeverity, c as IncidentSource, d as IncidentStatus, P as ProbeResult, e as ProbeType, f as Project, S as Session, V as VerificationProbe, g as VerificationRecipe, h as VerificationResult } from './projects-DB7S312i.js';
-export { BROWSER_SECURITY_RULES, FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, truncate } from './core/index.js';
+export { BROWSER_SECURITY_RULES, FingerprintInput, REDACTED_PLACEHOLDER, SENSITIVE_KEY_PATTERNS, SENSITIVE_QUERY_PARAMS, SelectorOptions, computeFingerprint, extractSourceFromStack, getSemanticSelector, isSensitiveKey, normalizeErrorMessage, normalizeSourceFile, redactHeaders, redactSensitiveData, redactUrl, safeAsync, safeExecute, safeJsonParse, safeJsonStringify, truncate } from './core/index.js';
 export { BrowserTrackClient, getClient, init as initClient } from './client/index.js';
 export { BrowserTrackDaemon, createDaemon } from './daemon/index.js';
-export { c as createMcpServer } from './server-DiVmTrIR.js';
+export { c as createMcpServer } from './server-DjV7RWQM.js';
 export { Rules, standardRules, redact as visulimaRedact } from '@visulima/redact';
 import './engine-CmchnMDq.js';
 import 'ws';

package/dist/index.js

@@ -2,11 +2,14 @@ import {
   BrowserTrackClient,
   getClient,
   init
-} from "./chunk-INXDWPJW.js";
+} from "./chunk-4HRLW6YF.js";
+import {
+  createMcpServer
+} from "./chunk-TWEYRBDU.js";
 import {
   BrowserTrackDaemon,
   createDaemon
-} from "./chunk-7OCOQGDN.js";
+} from "./chunk-AYSVE6NG.js";
 import {
   BROWSER_SECURITY_RULES,
   REDACTED_PLACEHOLDER,
@@ -21,14 +24,14 @@ import {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact
-} from "./chunk-6VA7GBAO.js";
-import {
-  createMcpServer
-} from "./chunk-464D4U2U.js";
-import "./chunk-3HOXPTM2.js";
+} from "./chunk-QRZ57ME3.js";
 export {
   BROWSER_SECURITY_RULES,
   BrowserTrackClient,
@@ -49,6 +52,10 @@ export {
   redactHeaders,
   redactSensitiveData,
   redactUrl,
+  safeAsync,
+  safeExecute,
+  safeJsonParse,
+  safeJsonStringify,
   standardRules,
   truncate,
   visulimaRedact

package/dist/mcp/index.d.ts

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall } from '../server-DiVmTrIR.js';
+export { M as McpContext, a as McpServerOptions, c as createMcpServer, h as handleToolCall, i as isDaemonRunning } from '../server-DjV7RWQM.js';
 import '@modelcontextprotocol/sdk/server/index.js';
 import '../engine-CmchnMDq.js';
 import '../commands-fjuqKzkm.js';

package/dist/mcp/index.js

@@ -1,12 +1,15 @@
 import {
   TOOLS,
   createMcpServer,
-  handleToolCall
-} from "../chunk-464D4U2U.js";
-import "../chunk-3HOXPTM2.js";
+  handleToolCall,
+  isDaemonRunning
+} from "../chunk-TWEYRBDU.js";
+import "../chunk-AYSVE6NG.js";
+import "../chunk-QRZ57ME3.js";
 export {
   TOOLS,
   createMcpServer,
-  handleToolCall
+  handleToolCall,
+  isDaemonRunning
 };
 //# sourceMappingURL=index.js.map

package/dist/{server-DiVmTrIR.d.ts → server-DjV7RWQM.d.ts}

@@ -10,9 +10,14 @@ interface McpContext {
 }
 declare function handleToolCall(name: string, args: any, ctx: McpContext): Promise<any>;
 
+declare function isDaemonRunning(host: string, port: number): Promise<boolean>;
 interface McpServerOptions {
     dbPath?: string;
     context?: Partial<McpContext>;
+    autoStartDaemon?: boolean;
+    port?: number;
+    host?: string;
+    detached?: boolean;
 }
 declare function createMcpServer(options?: McpServerOptions): {
     server: Server<{
@@ -49,7 +54,10 @@ declare function createMcpServer(options?: McpServerOptions): {
             } | undefined;
         } | undefined;
     }>;
+    ctx: McpContext;
+    ensureDaemon: () => Promise<void>;
+    stopDaemon(): Promise<void>;
     startStdio(): Promise<void>;
 };
 
-export { type McpContext as M, type McpServerOptions as a, createMcpServer as c, handleToolCall as h };
+export { type McpContext as M, type McpServerOptions as a, createMcpServer as c, handleToolCall as h, isDaemonRunning as i };

package/docs/cli.md

@@ -35,9 +35,12 @@ browsertrack clear             # Wipe stored logs, screenshots, and incidents
 
 ### MCP Integration
 ```bash
-browsertrack mcp               # Start Model Context Protocol server over stdio
+browsertrack mcp               # Start Model Context Protocol server over stdio (auto-boots singleton daemon if offline)
+browsertrack mcp --no-daemon   # Start MCP server without auto-booting background daemon
 ```
 
+> **⚡ Singleton Daemon Lifecycle**: When starting `browsertrack mcp`, BrowserTrack automatically checks if the daemon is already running. If offline, it starts a single, persistent background daemon on `http://127.0.0.1:7331`. All IDE windows, workspaces, and sub-sessions share this single daemon without spawning duplicates or conflicting on ports.
+
 ---
 
 ## 📖 Documentation Commands (Docboot)

package/docs/getting-started.md

@@ -26,6 +26,8 @@ browsertrack start
 
 This will initialize the local server at `http://127.0.0.1:7331` (WebSocket bridge on `ws://127.0.0.1:7331`) and SQLite database at `~/.browsertrack/browsertrack.db`.
 
+> **⚡ Zero-Config Auto-Start**: If you configure BrowserTrack via MCP in your AI coding editor (Cursor, Antigravity, Claude Desktop), you do **not** need to manually run `browsertrack start`. The MCP server automatically launches and manages the HTTP and WebSocket background daemon on port `7331`!
+
 ---
 
 ## 2. Connect Your Web Application
@@ -80,25 +82,77 @@ const client = new BrowserTrackClient({
 
 Add BrowserTrack MCP server to your AI editor configuration:
 
-### Antigravity (`~/.gemini/antigravity-ide/mcp_config.json`)
+### Standard Configuration
 ```json
 {
   "mcpServers": {
     "browsertrack": {
-      "command": "browsertrack",
-      "args": ["mcp"]
+      "command": "npx",
+      "args": ["-y", "browsertrack@latest", "mcp"]
     }
   }
 }
 ```
 
-### Cursor (`~/.cursor/mcp.json`) & Claude Code
+---
+
+### ⚠️ Troubleshooting: `executable file not found in $PATH`
+
+If your editor throws an error like:
+```text
+Error: exec: "browsertrack": executable file not found in $PATH
+# or
+Error: exec: "npx": executable file not found in $PATH
+```
+
+#### Why does this happen?
+GUI applications on macOS and Linux (Antigravity, Cursor, Claude Desktop, VS Code) are launched by the desktop window manager (such as `launchd` on macOS), **not** from your terminal shell. Therefore, they do **not** automatically source your `~/.zshrc`, `~/.bashrc`, or environment managers like **NVM**, **fnm**, **asdf**, **Volta**, or **Homebrew** (`/opt/homebrew/bin`).
+
+#### Solutions:
+
+##### Option A: Use Absolute Path to `npx` with `PATH` environment (Recommended)
+Find your `npx` and `node` bin directory in your terminal:
+```bash
+which npx
+# Example output: /Users/username/.nvm/versions/node/v20.19.5/bin/npx
+```
+
+Configure your MCP config with the full path, the `-y` flag (to prevent interactive installation prompts from stalling stdio), and the `PATH` environment variable:
 ```json
 {
   "mcpServers": {
     "browsertrack": {
-      "command": "npx",
-      "args": ["browsertrack", "mcp"]
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/npx",
+      "args": ["-y", "browsertrack@latest", "mcp"],
+      "env": {
+        "PATH": "/Users/username/.nvm/versions/node/v20.19.5/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+##### Option B: Run Directly via Node (Fastest for Local Development)
+If you are developing or running BrowserTrack locally, bypass `npx` completely and execute the CLI entry script directly with `node`:
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/node",
+      "args": ["/absolute/path/to/browsertrack/dist/cli/index.js", "mcp"]
+    }
+  }
+}
+```
+
+##### Option C: Wrap with Login Shell (`/bin/zsh -lc`)
+Use your interactive login shell to automatically source your `~/.zshrc` and all environment variables:
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/bin/zsh",
+      "args": ["-lc", "npx -y browsertrack mcp"]
     }
   }
 }

package/docs/mcp-reference.md

@@ -8,6 +8,8 @@ order: 6
 
 BrowserTrack exposes 16 specialized Model Context Protocol (MCP) tools for AI agents.
 
+> **⚡ Automatic Server Lifecycle**: When your IDE starts the MCP server (`browsertrack mcp`), BrowserTrack automatically checks if the background daemon is already running. If not, it **automatically starts the HTTP (`http://127.0.0.1:7331`) and WebSocket (`ws://127.0.0.1:7331`) server** in the background, so your browser can connect immediately with zero manual terminal commands. If you already have a running daemon, MCP seamlessly connects to it.
+
 ---
 
 ## 📋 Incidents & Error Diagnostics
@@ -139,3 +141,43 @@ Triggers closed-loop bug fix verification (reloads browser, evaluates probes, ca
 Retrieves latest verification result and before/after screenshots for an incident.
 - **Arguments**:
   - `incidentId` (`string`, *required*): The ID of the incident.
+
+---
+
+## ⚠️ Troubleshooting MCP Client Setup
+
+If your AI editor fails to launch the MCP server with:
+```text
+Error: exec: "browsertrack": executable file not found in $PATH
+```
+
+This occurs because GUI applications (Cursor, Antigravity, VS Code, Claude Desktop) run without loading terminal shell rc files (`~/.zshrc`, `~/.bashrc`), leaving version managers like **NVM**, **fnm**, **asdf**, or **Homebrew** out of `$PATH`.
+
+### Recommended Fix
+Specify the absolute path to `npx` (find it with `which npx`), include `-y`, and explicitly set `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/npx",
+      "args": ["-y", "browsertrack@latest", "mcp"],
+      "env": {
+        "PATH": "/Users/username/.nvm/versions/node/v20.19.5/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+Or run directly via `node` for local projects:
+```json
+{
+  "mcpServers": {
+    "browsertrack": {
+      "command": "/Users/username/.nvm/versions/node/v20.19.5/bin/node",
+      "args": ["/path/to/browsertrack/dist/cli/index.js", "mcp"]
+    }
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browsertrack",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Local browser diagnostics + MCP bridge for coding agents",
   "type": "module",
   "main": "./dist/index.js",