execbro 0.0.1-reserve → 1.10.13

package/build/core/telemetry.js

@@ -0,0 +1,653 @@
+import { randomUUID } from "crypto";
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { ensureLicense, incrementLocalUsage } from "./license.js";
+import { connectedApps } from "./state.js";
+import { getPostHogClient } from "./posthog.js";
+import { CONFIG_DIR } from "./paths.js";
+// ============================================================================
+// Configuration
+// ============================================================================
+const TELEMETRY_ENDPOINT = "https://rn-debugger-telemetry.500griven.workers.dev";
+const TELEMETRY_API_KEY = "6a630181cb391ed5c42a188428cc2d2623dfe9333ec048193bb711ab58afe85e";
+// Replaced at npm-publish time by scripts/inject-build-token.mjs, which
+// rewrites the compiled build/index.js. A source checkout (any fork) keeps
+// this literal — the telemetry Worker compares it to its own secret and
+// resolves a non-match to a fork. Never store/commit the real value here.
+const BUILD_TOKEN = "8d755bc6f2da14077192795c2e3053a3123dc05a523e872bcfef26aa30068422";
+export function getTelemetryEndpoint() { return TELEMETRY_ENDPOINT; }
+export function getTelemetryApiKey() { return TELEMETRY_API_KEY; }
+const REQUEST_TIMEOUT_MS = 5_000;
+const CONFIG_FILE = join(CONFIG_DIR, "telemetry.json");
+export const TELEMETRY_JSONL_PATH = "/tmp/rn-devtools-telemetry.jsonl";
+// Read version from package.json dynamically
+export function getServerVersion() {
+    try {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(__dirname, "..", "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// Read package name from package.json — differentiates canonical vs mirror publishes
+export function getPackageName() {
+    try {
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(__dirname, "..", "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.name || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// ============================================================================
+// Error Categorization
+// ============================================================================
+export function categorizeError(errorMessage, errorContext) {
+    const lower = errorMessage.toLowerCase();
+    // UI driver not installed — must be checked before 'validation' which matches 'missing'/'install'.
+    // Covers iOS (idb/axe) and Android (adb): on Android, ADB plays the same role as a UI driver
+    // (required for accessibility enumeration, screenshots, and input). Treating it identically keeps
+    // the "driver_missing" bucket platform-agnostic and prevents these from polluting tap-tool error rates.
+    if (lower.includes('not installed') && (lower.includes('idb') || lower.includes('axe') || lower.includes('ui driver') || lower.includes('adb'))) {
+        return 'driver_missing';
+    }
+    // Strategy chain may contain driver-missing signals even when the primary error
+    // message doesn't (e.g., strategies skipped due to missing driver, last-resort
+    // strategy fails with "No element found" or "timed out")
+    if (errorContext) {
+        const ctxLower = errorContext.toLowerCase();
+        if (ctxLower.includes('ios ui driver is not instal') || ctxLower.includes('idb is not instal') || ctxLower.includes('adb is not installed') || ctxLower.includes('adb is not in path')) {
+            return 'driver_missing';
+        }
+    }
+    if (lower.includes('websocket') || lower.includes('econnrefused') || lower.includes('socket') || lower.includes('fetch')) {
+        return 'network';
+    }
+    if (lower.includes('timeout') || lower.includes('timed out')) {
+        return 'timeout';
+    }
+    // Check connection errors before validation (since "no debuggable devices found" contains "no")
+    if (lower.includes('no apps connected') || lower.includes('scan_metro') || lower.includes('not connected') ||
+        lower.includes('no debuggable devices') || lower.includes('no metro server') || lower.includes('connection failed')) {
+        return 'connection';
+    }
+    // Syntax/compilation errors in JS code
+    if (lower.includes('compiling js failed') || lower.includes('syntaxerror')) {
+        return 'validation';
+    }
+    if (lower.includes('invalid') || lower.includes('required') || lower.includes('missing')) {
+        return 'validation';
+    }
+    if (lower.includes('evaluate') || lower.includes('execution') || lower.includes('runtime')) {
+        return 'execution';
+    }
+    // Tap element-not-found errors
+    if (lower.includes('no element found') || lower.includes('no pressable') || lower.includes('no focusable')) {
+        return 'validation';
+    }
+    // Tap connection errors (different message format from other tools)
+    if (lower.includes('no connected app') || lower.includes('connect_metro first') || lower.includes('auto-connect failed')) {
+        return 'connection';
+    }
+    return 'unknown';
+}
+// ============================================================================
+// State
+// ============================================================================
+let telemetryEnabled = true;
+let config = null;
+let sessionStartTime = null;
+let sessionId = null;
+let isFirstRunSession = false;
+let sessionStarted = false;
+let lastToolTimestamp = null;
+const SESSION_INACTIVITY_MS = 10 * 60 * 1000; // 10 minutes — matches dashboard SESSION_TIMEOUT_MS
+// ============================================================================
+// Configuration Management
+// ============================================================================
+function loadOrCreateConfig() {
+    if (config)
+        return config;
+    // Try to load existing config
+    try {
+        if (existsSync(CONFIG_FILE)) {
+            const data = readFileSync(CONFIG_FILE, "utf-8");
+            const parsed = JSON.parse(data);
+            // Mark as not first run for subsequent sessions
+            config = { ...parsed, isFirstRun: false };
+            isFirstRunSession = false;
+            return config;
+        }
+    }
+    catch {
+        // Config file corrupted or unreadable, create new one
+    }
+    // Create new installation
+    const newConfig = {
+        installationId: randomUUID(),
+        firstRunTimestamp: Date.now(),
+        isFirstRun: true
+    };
+    try {
+        if (!existsSync(CONFIG_DIR)) {
+            mkdirSync(CONFIG_DIR, { recursive: true });
+        }
+        writeFileSync(CONFIG_FILE, JSON.stringify(newConfig, null, 2));
+        // Re-read to handle race condition with concurrent sessions
+        // The file on disk is the source of truth
+        try {
+            const data = readFileSync(CONFIG_FILE, "utf-8");
+            const persistedConfig = JSON.parse(data);
+            config = persistedConfig;
+            isFirstRunSession = persistedConfig.isFirstRun;
+            return config;
+        }
+        catch {
+            // If re-read fails, use the config we created
+            config = newConfig;
+            isFirstRunSession = true;
+            return config;
+        }
+    }
+    catch {
+        // Failed to save config, continue with in-memory config
+        config = newConfig;
+        isFirstRunSession = true;
+        return config;
+    }
+}
+export function getInstallationId() {
+    return loadOrCreateConfig().installationId;
+}
+function isFirstRun() {
+    loadOrCreateConfig();
+    return isFirstRunSession;
+}
+// ============================================================================
+// Telemetry Control
+// ============================================================================
+export function initTelemetry() {
+    // Check environment variable for opt-out
+    const envValue = process.env.EXECBRO_TELEMETRY ?? process.env.RN_DEBUGGER_TELEMETRY;
+    if (envValue === "false" || envValue === "0" || envValue === "off") {
+        telemetryEnabled = false;
+        console.error("[execbro] Telemetry disabled via EXECBRO_TELEMETRY");
+        return;
+    }
+    // Check if dev mode is enabled in config (for local development)
+    const cfg = loadOrCreateConfig();
+    if (cfg.devMode) {
+        telemetryEnabled = false;
+        return;
+    }
+    // Check if endpoint is configured (placeholder detection)
+    if (TELEMETRY_ENDPOINT.includes("YOUR_SUBDOMAIN") || TELEMETRY_API_KEY.includes("YOUR_API_KEY")) {
+        telemetryEnabled = false;
+        // Silently disable - endpoint not configured yet
+        return;
+    }
+    // Load/create config (generates installation ID)
+    loadOrCreateConfig();
+    sessionId = randomUUID();
+    // Track that an AI agent session loaded our MCP server (regardless of tool usage)
+    trackEvent("session_start", {
+        isFirstRun: isFirstRun()
+    });
+    // Track session end on SIGINT/SIGTERM. Each event is dispatched immediately
+    // with keepalive, so no flush is needed — the OS completes the request even
+    // if the process exits right after.
+    const handleExit = () => {
+        if (sessionStarted && sessionStartTime) {
+            trackEvent("session_end", {
+                duration: Date.now() - sessionStartTime
+            });
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", handleExit);
+    process.on("SIGTERM", handleExit);
+}
+export function isTelemetryEnabled() {
+    return telemetryEnabled;
+}
+/** Check if the MCP server is running in dev mode (config-based). */
+export function isDevMode() {
+    try {
+        const cfg = loadOrCreateConfig();
+        return cfg.devMode === true;
+    }
+    catch {
+        return false;
+    }
+}
+// ============================================================================
+// Event Tracking
+// ============================================================================
+function trackEvent(name, properties) {
+    if (!telemetryEnabled)
+        return;
+    dispatch({
+        name,
+        timestamp: Date.now(),
+        isFirstRun: isFirstRun(),
+        properties
+    });
+}
+export function trackToolInvocation(toolName, success, durationMs, errorMessage, errorContext, inputTokens, outputTokens, targetPlatform, emptyResult, meaningful, changeRate, tapStrategy, iosDriver, responsePreview, emptyReason, artifactKey, ocrClosestMatch, fiberPressableCount, accessibilityMatchCount, appRoute) {
+    // Append to local JSONL file for local dashboard (dev mode only)
+    if (isDevMode())
+        try {
+            const localEvent = {
+                name: "tool_invocation",
+                timestamp: Date.now(),
+                toolName,
+                success,
+                duration: durationMs,
+                isFirstRun: false,
+            };
+            if (!success && errorMessage) {
+                localEvent.errorCategory = categorizeError(errorMessage, errorContext);
+                localEvent.errorMessage = errorMessage.substring(0, 200);
+            }
+            // Always propagate errorContext when provided — unmeaningful taps are success=true
+            // but still carry triage context (predicate, strategy chain) that must reach blob8.
+            if (errorContext)
+                localEvent.errorContext = errorContext.substring(0, 150);
+            if (targetPlatform)
+                localEvent.targetPlatform = targetPlatform;
+            if (emptyResult !== undefined)
+                localEvent.emptyResult = emptyResult;
+            if (meaningful !== undefined)
+                localEvent.meaningful = meaningful;
+            if (changeRate !== undefined)
+                localEvent.changeRate = changeRate;
+            if (tapStrategy)
+                localEvent.tapStrategy = tapStrategy;
+            if (iosDriver)
+                localEvent.iosDriver = iosDriver;
+            if (emptyReason)
+                localEvent.emptyReason = emptyReason;
+            if (responsePreview)
+                localEvent.responsePreview = responsePreview;
+            if (artifactKey)
+                localEvent.artifactKey = artifactKey;
+            if (ocrClosestMatch)
+                localEvent.ocrClosestMatch = ocrClosestMatch;
+            if (fiberPressableCount)
+                localEvent.fiberPressableCount = fiberPressableCount;
+            if (accessibilityMatchCount)
+                localEvent.accessibilityMatchCount = accessibilityMatchCount;
+            if (appRoute)
+                localEvent.appRoute = appRoute;
+            appendFileSync(TELEMETRY_JSONL_PATH, JSON.stringify(localEvent) + "\n");
+        }
+        catch {
+            // Non-critical — local file sink failure should never affect tool execution
+        }
+    if (!telemetryEnabled)
+        return;
+    const now = Date.now();
+    // Start a new session on first tool use or after inactivity gap
+    if (!sessionStarted || (lastToolTimestamp && (now - lastToolTimestamp) > SESSION_INACTIVITY_MS)) {
+        if (sessionStarted) {
+            // End previous session before starting a new one
+            trackEvent("session_end", {
+                duration: lastToolTimestamp - sessionStartTime
+            });
+            sessionId = randomUUID();
+        }
+        sessionStarted = true;
+        sessionStartTime = now;
+        trackEvent("session_start_ai_devtools", {
+            isFirstRun: isFirstRun(),
+            firstTool: toolName
+        });
+        // Re-emit app_detected for any already-connected RN apps so the dashboard's
+        // period-scoped platform classification keeps working on long-lived sessions.
+        // Uses cached detection; no CDP round-trip.
+        for (const app of connectedApps.values()) {
+            if (app.appDetection)
+                trackAppDetection(app.appDetection);
+        }
+        // Lazy license check — runs once per session, tracked as tool_invocation for analytics
+        ensureLicense().then(({ source, status, durationMs }) => {
+            trackLicenseCheck(source, status.tier, durationMs);
+        }).catch(() => {
+            // License check failed — not critical, don't break tool flow
+        });
+    }
+    lastToolTimestamp = now;
+    const event = {
+        name: "tool_invocation",
+        timestamp: now,
+        toolName,
+        success,
+        duration: durationMs,
+        isFirstRun: isFirstRun()
+    };
+    if (!success && errorMessage) {
+        event.errorCategory = categorizeError(errorMessage, errorContext);
+        event.errorMessage = errorMessage.substring(0, 200);
+    }
+    // Always propagate errorContext when provided — unmeaningful taps are success=true
+    // but still carry triage context (predicate, strategy chain) that must reach blob8.
+    if (errorContext) {
+        event.errorContext = errorContext.substring(0, 150);
+    }
+    if (inputTokens !== undefined && inputTokens > 0)
+        event.inputTokens = inputTokens;
+    if (outputTokens !== undefined && outputTokens > 0)
+        event.outputTokens = outputTokens;
+    if (targetPlatform)
+        event.targetPlatform = targetPlatform;
+    if (emptyResult !== undefined)
+        event.emptyResult = emptyResult;
+    if (meaningful !== undefined)
+        event.meaningful = meaningful;
+    if (changeRate !== undefined)
+        event.changeRate = changeRate;
+    if (tapStrategy)
+        event.tapStrategy = tapStrategy;
+    if (iosDriver)
+        event.iosDriver = iosDriver;
+    if (emptyReason)
+        event.emptyReason = emptyReason;
+    if (artifactKey)
+        event.artifactKey = artifactKey;
+    if (ocrClosestMatch)
+        event.ocrClosestMatch = ocrClosestMatch;
+    if (fiberPressableCount)
+        event.fiberPressableCount = fiberPressableCount;
+    if (accessibilityMatchCount)
+        event.accessibilityMatchCount = accessibilityMatchCount;
+    if (appRoute)
+        event.appRoute = appRoute;
+    dispatch(event);
+    // Mirror tool_invocation to PostHog so insights/cohort filters can count
+    // per-tool usage natively. Cloudflare remains the source of truth; PostHog
+    // gets a parallel stream keyed on the same installation id.
+    try {
+        const client = getPostHogClient();
+        if (client) {
+            const phProps = {
+                tool_name: toolName,
+                success,
+                duration_ms: durationMs,
+                is_first_run: isFirstRun(),
+                server_version: getServerVersion(),
+                package_name: getPackageName(),
+                session_id: sessionId?.substring(0, 12) ?? "",
+            };
+            if (event.errorCategory)
+                phProps.error_category = event.errorCategory;
+            if (event.errorMessage)
+                phProps.error_message = event.errorMessage;
+            if (event.errorContext)
+                phProps.error_context = event.errorContext;
+            if (targetPlatform)
+                phProps.target_platform = targetPlatform;
+            if (emptyResult !== undefined)
+                phProps.empty_result = emptyResult;
+            if (meaningful !== undefined)
+                phProps.meaningful = meaningful;
+            if (changeRate !== undefined)
+                phProps.change_rate = changeRate;
+            if (tapStrategy)
+                phProps.tap_strategy = tapStrategy;
+            if (iosDriver)
+                phProps.ios_driver = iosDriver;
+            if (emptyReason)
+                phProps.empty_reason = emptyReason;
+            if (inputTokens !== undefined && inputTokens > 0)
+                phProps.input_tokens = inputTokens;
+            if (outputTokens !== undefined && outputTokens > 0)
+                phProps.output_tokens = outputTokens;
+            client.capture({
+                distinctId: getInstallationId(),
+                event: "tool_invocation",
+                properties: phProps,
+            });
+        }
+    }
+    catch {
+        // PostHog errors must never affect tool flow.
+    }
+    // Increment local usage counter
+    incrementLocalUsage();
+    // Mirror platform-cohort signal to PostHog for native users.
+    // Mirrors the infra's native-user inference (backend/worker.ts:deriveNativePlatform)
+    // so PostHog cohort filters match the Cloudflare dashboard.
+    mirrorNativeCohortToPostHog(toolName);
+}
+// Track what we've already sent to PostHog so we don't re-identify on every tool call.
+let _nativeKindSet = false;
+let _lastNativePlatformSent = null;
+function mirrorNativeCohortToPostHog(toolName) {
+    const platform = toolName.startsWith("ios_")
+        ? "ios"
+        : toolName.startsWith("android_")
+            ? "android"
+            : null;
+    if (!platform)
+        return;
+    // Skip when nothing new to send
+    if (_nativeKindSet && _lastNativePlatformSent === platform)
+        return;
+    try {
+        const client = getPostHogClient();
+        if (!client)
+            return;
+        const distinctId = getInstallationId();
+        const set = {};
+        const setOnce = {};
+        if (!_nativeKindSet) {
+            // $set_once: RN users keep platform_kind="rn" (set by trackAppDetection);
+            // native-only users get "native" the first time a platform-prefixed tool fires.
+            setOnce.platform_kind = "native";
+            _nativeKindSet = true;
+        }
+        if (_lastNativePlatformSent !== platform) {
+            set.platform_last_seen = platform;
+            _lastNativePlatformSent = platform;
+        }
+        client.identify({
+            distinctId,
+            properties: {
+                ...(Object.keys(set).length > 0 ? { $set: set } : {}),
+                ...(Object.keys(setOnce).length > 0 ? { $set_once: setOnce } : {}),
+            },
+        });
+    }
+    catch {
+        // PostHog errors must never affect tool flow.
+    }
+}
+/**
+ * Records _license_check as a tool_invocation event without triggering session logic.
+ * Called from the ensureLicense() callback inside trackToolInvocation.
+ */
+function trackLicenseCheck(source, tier, durationMs) {
+    if (!telemetryEnabled)
+        return;
+    dispatch({
+        name: "tool_invocation",
+        timestamp: Date.now(),
+        toolName: "_license_check",
+        success: true,
+        duration: durationMs,
+        isFirstRun: isFirstRun(),
+        errorContext: `${source}:${tier}`
+    });
+}
+/**
+ * Record auto-reconnect outcome for the CDP wrapper.
+ *
+ * Emits as a 'tool_invocation' row (so existing dashboards count it) with a
+ * synthetic toolName '_auto_reconnect' and `errorContext` carrying the
+ * outcome + originating toolName + transportPattern. Does not start a session
+ * or affect license counting.
+ */
+export function trackAutoReconnect(outcome, originatingToolName, transportPattern) {
+    if (!telemetryEnabled)
+        return;
+    // No-op outcomes ('not_needed') account for ~98% of events and carry zero
+    // signal — only emit when the wrapper actually attempted a reconnect.
+    if (outcome === "not_needed")
+        return;
+    // Skip events fired before a session_id is assigned (e.g. first
+    // executeInApp before session_start) — they're un-attributable.
+    if (!sessionId)
+        return;
+    dispatch({
+        name: "tool_invocation",
+        timestamp: Date.now(),
+        toolName: "_auto_reconnect",
+        success: outcome === "success",
+        duration: 0,
+        isFirstRun: isFirstRun(),
+        errorContext: JSON.stringify({
+            outcome,
+            tool: originatingToolName,
+            ...(transportPattern ? { pattern: transportPattern } : {}),
+        }),
+    });
+    try {
+        const client = getPostHogClient();
+        if (client) {
+            client.capture({
+                distinctId: getInstallationId(),
+                event: "transport_auto_reconnect",
+                properties: {
+                    outcome,
+                    tool_name: originatingToolName,
+                    transport_pattern: transportPattern,
+                    server_version: getServerVersion(),
+                    package_name: getPackageName(),
+                    session_id: sessionId?.substring(0, 12) ?? "",
+                },
+            });
+        }
+    }
+    catch {
+        // PostHog errors must never affect tool flow.
+    }
+}
+/**
+ * Records app detection result as an app_detected event.
+ * Called from appDetection.ts after successful detection.
+ */
+export function trackAppDetection(detection) {
+    if (!telemetryEnabled)
+        return;
+    dispatch({
+        name: "app_detected",
+        timestamp: Date.now(),
+        isFirstRun: isFirstRun(),
+        errorContext: JSON.stringify({
+            rn: detection.reactNativeVersion,
+            arch: detection.architecture,
+            eng: detection.jsEngine,
+            plat: detection.appPlatform,
+            os: detection.osVersion,
+            ...(detection.expoSdkVersion ? { expo: detection.expoSdkVersion } : {}),
+        }),
+        targetPlatform: detection.appPlatform,
+    });
+    // Mirror to PostHog so insights/cohort filters can use kind + platform without custom queries.
+    try {
+        const client = getPostHogClient();
+        if (client) {
+            const distinctId = getInstallationId();
+            client.capture({
+                distinctId,
+                event: "app_detected",
+                properties: {
+                    rn_version: detection.reactNativeVersion,
+                    architecture: detection.architecture,
+                    js_engine: detection.jsEngine,
+                    platform: detection.appPlatform,
+                    os_version: detection.osVersion,
+                    ...(detection.expoSdkVersion ? { expo_sdk: detection.expoSdkVersion } : {}),
+                    platform_kind: "rn",
+                    server_version: getServerVersion(),
+                    package_name: getPackageName(),
+                },
+            });
+            // Person properties so cohort filters work natively in PostHog insights.
+            client.identify({
+                distinctId,
+                properties: {
+                    $set: {
+                        platform_kind: "rn",
+                        platform_last_seen: detection.appPlatform,
+                        rn_version: detection.reactNativeVersion,
+                        architecture: detection.architecture,
+                    },
+                },
+            });
+        }
+    }
+    catch {
+        // PostHog errors must never affect tool flow.
+    }
+}
+/**
+ * Records a Fast Refresh recorder install event. Fired once per
+ * device-session by getRefreshStatus when the executor lazy-installs the
+ * recorder or detects an install failure. SDK-side installs (which happen
+ * before the executor sees the app) surface here as via != null with
+ * justInstalled = false on the first observation.
+ */
+export function trackFastRefreshInstall(detection) {
+    if (!telemetryEnabled)
+        return;
+    dispatch({
+        name: "fast_refresh_install",
+        timestamp: Date.now(),
+        isFirstRun: isFirstRun(),
+        errorContext: JSON.stringify({
+            via: detection.via,
+            installed: detection.recorderInstalled,
+            just: detection.justInstalled,
+            ...(detection.reason ? { reason: detection.reason } : {}),
+        }),
+    });
+}
+// ============================================================================
+// Event Dispatch
+// ============================================================================
+// One event per HTTP request, fired immediately. `keepalive: true` (undici,
+// Node 18+) tells the runtime to complete the request even if the process
+// exits right after — the Node equivalent of navigator.sendBeacon. No queue,
+// no flush timer, no data loss on abrupt exit.
+function dispatch(event) {
+    const payload = {
+        installationId: getInstallationId(),
+        sessionId: sessionId || undefined,
+        serverVersion: getServerVersion(),
+        packageName: getPackageName(),
+        buildToken: BUILD_TOKEN,
+        nodeVersion: process.version,
+        platform: process.platform,
+        events: [event]
+    };
+    fetch(TELEMETRY_ENDPOINT, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": TELEMETRY_API_KEY
+        },
+        body: JSON.stringify(payload),
+        keepalive: true,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch(() => {
+        // Silent: telemetry must never impact the user.
+    });
+}
+//# sourceMappingURL=telemetry.js.map