react-native-debug-toolkit 2.3.0 → 3.0.0

package/node/mcp/src/daemonClient.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const {
+  DEFAULT_DAEMON_ORIGIN,
+  EXPECTED_PROTOCOL_VERSION,
+} = require('./constants');
+const { requestJson } = require('./httpClient');
+
+function getDaemonOrigin() {
+  return process.env.DEBUG_TOOLKIT_DAEMON_ORIGIN || DEFAULT_DAEMON_ORIGIN;
+}
+
+async function readHealth(origin = getDaemonOrigin()) {
+  const response = await requestJson(origin, '/health', { timeoutMs: 800 });
+  if (response.status !== 200 || !response.body?.ok) {
+    throw new Error(`Daemon health check failed with status ${response.status}`);
+  }
+  if (response.body.protocolVersion !== EXPECTED_PROTOCOL_VERSION) {
+    throw new Error(
+      `Daemon protocol mismatch: expected ${EXPECTED_PROTOCOL_VERSION}, got ${response.body.protocolVersion}`,
+    );
+  }
+  return response.body;
+}
+
+function findDaemonBin() {
+  if (process.env.DEBUG_TOOLKIT_DAEMON_BIN) {
+    return process.env.DEBUG_TOOLKIT_DAEMON_BIN;
+  }
+
+  try {
+    return require.resolve('react-native-debug-toolkit/bin/debug-toolkit.js');
+  } catch {
+    const localPath = path.resolve(__dirname, '../../../bin/debug-toolkit.js');
+    return fs.existsSync(localPath) ? localPath : null;
+  }
+}
+
+function getDaemonBindHost() {
+  return process.env.DEBUG_TOOLKIT_DAEMON_HOST || '0.0.0.0';
+}
+
+function spawnDaemon(origin = getDaemonOrigin()) {
+  const daemonBin = findDaemonBin();
+  if (!daemonBin) {
+    throw new Error('Cannot find react-native-debug-toolkit debug-toolkit bin');
+  }
+
+  const url = new URL(origin);
+  const child = spawn(process.execPath, [
+    daemonBin,
+    '--daemon-only',
+    '--host',
+    getDaemonBindHost(),
+    '--port',
+    url.port || '3799',
+  ], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function ensureDaemon(options = {}) {
+  const origin = options.origin || getDaemonOrigin();
+  const timeoutMs = options.timeoutMs || 3000;
+  const pollMs = options.pollMs || 150;
+  const startedAt = Date.now();
+
+  try {
+    return { ok: true, health: await readHealth(origin), origin, spawned: false };
+  } catch (initialError) {
+    try {
+      spawnDaemon(origin);
+    } catch (spawnError) {
+      return {
+        ok: false,
+        origin,
+        error: `${initialError.message}; ${spawnError.message}`,
+      };
+    }
+  }
+
+  while (Date.now() - startedAt < timeoutMs) {
+    await sleep(pollMs);
+    try {
+      return { ok: true, health: await readHealth(origin), origin, spawned: true };
+    } catch {
+      // Keep polling until timeout; the detached daemon may still be binding.
+    }
+  }
+
+  return {
+    ok: false,
+    origin,
+    error: `Daemon did not become healthy within ${timeoutMs}ms at ${origin}`,
+  };
+}
+
+async function readSession(origin, sessionId) {
+  const requestPath = sessionId ? `/sessions/${encodeURIComponent(sessionId)}` : '/latest';
+  const response = await requestJson(origin, requestPath, { timeoutMs: 3000 });
+  if (response.status !== 200 || !response.body?.ok) {
+    throw new Error(response.body?.error || `Daemon request failed with status ${response.status}`);
+  }
+  return response.body;
+}
+
+async function readSessions(origin) {
+  const response = await requestJson(origin, '/sessions', { timeoutMs: 3000 });
+  if (response.status !== 200 || !response.body?.ok) {
+    throw new Error(response.body?.error || `Daemon request failed with status ${response.status}`);
+  }
+  return response.body;
+}
+
+module.exports = {
+  ensureDaemon,
+  findDaemonBin,
+  getDaemonOrigin,
+  readHealth,
+  readSession,
+  readSessions,
+};

package/node/mcp/src/httpClient.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const http = require('http');
+const https = require('https');
+
+function requestJson(origin, path, options = {}) {
+  const url = new URL(path, origin);
+  const transport = url.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request(url, {
+      method: options.method || 'GET',
+      headers: options.headers || {},
+      timeout: options.timeoutMs || 3000,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let body = null;
+        try {
+          body = raw ? JSON.parse(raw) : null;
+        } catch {
+          reject(new Error(`Daemon returned non-JSON response from ${path}`));
+          return;
+        }
+
+        resolve({
+          status: res.statusCode || 0,
+          body,
+        });
+      });
+    });
+
+    req.on('timeout', () => {
+      req.destroy(new Error(`Daemon request timed out: ${path}`));
+    });
+    req.on('error', reject);
+
+    if (options.body) {
+      req.write(JSON.stringify(options.body));
+    }
+    req.end();
+  });
+}
+
+module.exports = {
+  requestJson,
+};

package/node/mcp/src/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const { ensureDaemon } = require('./daemonClient');
+const { handleMessage, startStdioServer } = require('./server');
+const { callTool, getAppLogsTool, listAppSessionsTool, tools } = require('./tools');
+
+module.exports = {
+  callTool,
+  ensureDaemon,
+  getAppLogsTool,
+  handleMessage,
+  listAppSessionsTool,
+  startStdioServer,
+  tools,
+};

package/node/mcp/src/logs.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const KNOWN_LOG_TYPES = ['network', 'console', 'navigation', 'track', 'zustand'];
+
+function isFailedLog(entry) {
+  return Boolean(
+    entry &&
+    typeof entry === 'object' &&
+    (
+      entry.error ||
+      entry.level === 'error' ||
+      entry.response?.success === false ||
+      entry.response?.status >= 400
+    ),
+  );
+}
+
+function stripBodies(value, parentKey) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripBodies(item, parentKey));
+  }
+
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  return Object.entries(value).reduce((acc, [key, child]) => {
+    const normalizedKey = key.toLowerCase();
+    if (normalizedKey === 'body' || (parentKey === 'response' && normalizedKey === 'data')) {
+      return acc;
+    }
+    acc[key] = stripBodies(child, normalizedKey);
+    return acc;
+  }, {});
+}
+
+function selectLogs(report, options = {}) {
+  const logs = report?.logs && typeof report.logs === 'object' ? report.logs : {};
+  const logType = options.logType;
+  const limit = Number.isFinite(options.limit) && options.limit > 0
+    ? Math.min(Math.floor(options.limit), 200)
+    : 50;
+  const includeBodies = options.includeBodies !== false;
+  const failedOnly = options.failedOnly === true;
+
+  let entries;
+  if (logType) {
+    entries = Array.isArray(logs[logType]) ? logs[logType] : [];
+  } else {
+    entries = Object.entries(logs).flatMap(([type, typeEntries]) => (
+      Array.isArray(typeEntries)
+        ? typeEntries.map((entry) => ({ type, entry }))
+        : []
+    ));
+  }
+
+  if (failedOnly) {
+    entries = entries.filter((item) => isFailedLog(item.entry || item));
+  }
+
+  entries = entries.slice(-limit);
+
+  if (logType) {
+    return includeBodies ? entries : entries.map(stripBodies);
+  }
+
+  return entries.map((item) => ({
+    type: item.type,
+    entry: includeBodies ? item.entry : stripBodies(item.entry),
+  }));
+}
+
+function createToolPayload(session, options = {}) {
+  const report = session.report || { version: 2, logs: {} };
+  const logs = selectLogs(report, options);
+
+  return {
+    ok: true,
+    sessionId: session.sessionId,
+    receivedAt: session.receivedAt,
+    logType: options.logType || 'all',
+    failedOnly: options.failedOnly === true,
+    includeBodies: options.includeBodies !== false,
+    count: logs.length,
+    logs,
+  };
+}
+
+module.exports = {
+  KNOWN_LOG_TYPES,
+  createToolPayload,
+  isFailedLog,
+  selectLogs,
+  stripBodies,
+};

package/node/mcp/src/server.js

@@ -0,0 +1,144 @@
+'use strict';
+
+const {
+  MCP_SERVER_NAME,
+  MCP_SERVER_VERSION,
+} = require('./constants');
+const { callTool, tools } = require('./tools');
+
+function writeMessage(output, message) {
+  output.write(`${JSON.stringify(message)}\n`);
+}
+
+function createError(id, code, message) {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: { code, message },
+  };
+}
+
+async function handleMessage(message, context) {
+  const id = message.id;
+  const method = message.method;
+
+  if (!method) {
+    return null;
+  }
+
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: message.params?.protocolVersion || '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: {
+          name: MCP_SERVER_NAME,
+          version: MCP_SERVER_VERSION,
+        },
+      },
+    };
+  }
+
+  if (method === 'notifications/initialized') {
+    return null;
+  }
+
+  if (method === 'ping') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {},
+    };
+  }
+
+  if (method === 'tools/list') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        tools,
+      },
+    };
+  }
+
+  if (method === 'tools/call') {
+    try {
+      const result = await callTool(
+        message.params?.name,
+        message.params?.arguments || {},
+        context,
+      );
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        },
+      };
+    } catch (error) {
+      return createError(id, -32000, error.message || 'Tool call failed');
+    }
+  }
+
+  if (id === undefined) {
+    return null;
+  }
+
+  return createError(id, -32601, `Method not found: ${method}`);
+}
+
+function startStdioServer(options = {}) {
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+  const errorOutput = options.errorOutput || process.stderr;
+  const context = options.context || {};
+  let buffer = '';
+
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buffer += chunk;
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() || '';
+
+    lines.forEach((line) => {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        return;
+      }
+
+      let message;
+      try {
+        message = JSON.parse(trimmed);
+      } catch (error) {
+        errorOutput.write(`Invalid MCP JSON message: ${error.message}\n`);
+        return;
+      }
+
+      handleMessage(message, context)
+        .then((response) => {
+          if (response) {
+            writeMessage(output, response);
+          }
+        })
+        .catch((error) => {
+          if (message.id !== undefined) {
+            writeMessage(output, createError(message.id, -32000, error.message || 'MCP error'));
+          } else {
+            errorOutput.write(`MCP notification failed: ${error.message}\n`);
+          }
+        });
+    });
+  });
+}
+
+module.exports = {
+  handleMessage,
+  startStdioServer,
+};

package/node/mcp/src/tools.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { getDaemonOrigin, readSession, readSessions } = require('./daemonClient');
+const { KNOWN_LOG_TYPES, createToolPayload } = require('./logs');
+
+const getAppLogsTool = {
+  name: 'get_app_logs',
+  description: 'Read React Native Debug Toolkit logs from the local daemon. Tip: if you have shell access, curl http://127.0.0.1:3799/sessions/latest is more efficient.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      sessionId: { type: 'string' },
+      logType: {
+        type: 'string',
+        enum: KNOWN_LOG_TYPES,
+      },
+      limit: { type: 'number', default: 50 },
+      failedOnly: { type: 'boolean', default: false },
+      includeBodies: { type: 'boolean', default: true },
+    },
+  },
+};
+
+const listAppSessionsTool = {
+  name: 'list_app_sessions',
+  description: 'List React Native Debug Toolkit sessions available in the local daemon. Tip: if you have shell access, curl http://127.0.0.1:3799/sessions is more efficient.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+  },
+};
+
+const tools = [getAppLogsTool, listAppSessionsTool];
+
+async function callTool(name, args = {}, context = {}) {
+  const ensureDaemon = context.ensureDaemon || (async () => ({ ok: true, origin: getDaemonOrigin() }));
+  const daemon = await ensureDaemon();
+  if (!daemon.ok) {
+    return {
+      ok: false,
+      error: daemon.error || 'Debug toolkit daemon is not available',
+      origin: daemon.origin,
+    };
+  }
+
+  try {
+    if (name === listAppSessionsTool.name) {
+      const readSessionsImpl = context.readSessions || readSessions;
+      const result = await readSessionsImpl(daemon.origin);
+      const sessions = Array.isArray(result.sessions) ? result.sessions : [];
+      return {
+        ok: true,
+        origin: daemon.origin,
+        sessions,
+        count: sessions.length,
+      };
+    }
+
+    if (name !== getAppLogsTool.name) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    const session = await readSession(daemon.origin, args.sessionId);
+    return createToolPayload(session, {
+      logType: args.logType,
+      limit: args.limit,
+      failedOnly: args.failedOnly,
+      includeBodies: args.includeBodies,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      error: error.message || 'Failed to read debug toolkit logs',
+      origin: daemon.origin,
+    };
+  }
+}
+
+module.exports = {
+  callTool,
+  getAppLogsTool,
+  listAppSessionsTool,
+  tools,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-debug-toolkit",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "A dev-only floating debug panel for React Native with network, console, Zustand, navigation, and event logs",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -8,6 +8,8 @@
   "files": [
     "src",
     "lib",
+    "bin",
+    "node",
     "README.md",
     "LICENSE",
     "!**/__tests__",
@@ -19,9 +21,12 @@
     "typescript": "npm run typecheck",
     "test": "jest",
     "build": "bob build",
-    "lint": "eslint \"src/**/*.{js,ts,tsx}\"",
+    "lint": "eslint \"src/**/*.{js,ts,tsx}\" \"node/**/*.js\" \"bin/**/*.js\"",
     "prepare": "bob build"
   },
+  "bin": {
+    "debug-toolkit": "bin/debug-toolkit.js"
+  },
   "keywords": [
     "react-native",
     "debug",

package/src/features/network/index.ts

@@ -9,8 +9,7 @@ import {
   startXMLHttpRequest,
   resetInterceptors,
 } from './networkInterceptor';
-
-type NetworkLogPayload = Omit<NetworkLogEntry, 'id'>;
+import type { NetworkLogPayload } from './networkInterceptor';
 
 // ─── Utilities ────────────────────────────────────────
 
@@ -37,6 +36,7 @@ function emitNetworkLog(entry: NetworkLogPayload): void {
 // ─── Feature factory ──────────────────────────────────
 
 const DEFAULT_MAX_LOGS = 200;
+const daemonEndpointBlacklist: Array<string | RegExp> = [];
 
 export interface NetworkFeatureConfig {
   /** Maximum number of network logs to keep (default: 200) */
@@ -57,7 +57,7 @@ export const createNetworkFeature = (config?: NetworkFeatureConfig): DebugFeatur
   let stopXhrFn: (() => void) | null = null;
 
   const handleLog = (entry: NetworkLogPayload) => {
-    if (isUrlBlacklisted(entry.request.url, blacklist)) {
+    if (isUrlBlacklisted(entry.request.url, [...blacklist, ...daemonEndpointBlacklist])) {
       return;
     }
     logStore.push({ ...entry, id: logStore.nextId() }, maxLogs);
@@ -95,8 +95,35 @@ export const createNetworkFeature = (config?: NetworkFeatureConfig): DebugFeatur
   };
 };
 
+function normalizeDaemonEndpoint(endpoint: string): string {
+  const trimmed = endpoint.trim().replace(/\/+$/, '');
+  if (!trimmed) {
+    return trimmed;
+  }
+
+  try {
+    const url = new URL(trimmed);
+    return `${url.origin}${url.pathname === '/' ? '' : url.pathname}`;
+  } catch {
+    return trimmed;
+  }
+}
+
+export function _addDaemonEndpointToNetworkBlacklist(endpoint: string): void {
+  const normalized = normalizeDaemonEndpoint(endpoint);
+  if (!normalized || daemonEndpointBlacklist.includes(normalized)) {
+    return;
+  }
+  daemonEndpointBlacklist.push(normalized);
+}
+
+export function _isNetworkUrlBlacklistedForTesting(url: string): boolean {
+  return isUrlBlacklisted(url, daemonEndpointBlacklist);
+}
+
 /** Reset module-level state for testing */
 export function _resetNetworkForTesting(): void {
   networkChannel = createEventChannel<NetworkLogPayload>();
+  daemonEndpointBlacklist.splice(0, daemonEndpointBlacklist.length);
   resetInterceptors();
 }

package/src/features/network/networkInterceptor.ts

@@ -3,6 +3,8 @@ import { urlRewriter } from '../../utils/urlRewriterRegistry';
 
 type NetworkLogPayload = Omit<NetworkLogEntry, 'id'>;
 
+export type { NetworkLogPayload };
+
 // Intercepts React Native's XMLHttpRequest transport layer.
 // RN fetch and axios (default adapter) both go through XHR — one hook captures everything.
 
@@ -113,6 +115,15 @@ function safeRead<T>(read: () => T): T | undefined {
   }
 }
 
+// URLs matching these patterns are skipped (Metro dev server internals).
+const IGNORED_URL_PATTERNS = [
+  /\/symbolicate$/,
+];
+
+function shouldIgnoreUrl(url: string): boolean {
+  return IGNORED_URL_PATTERNS.some((p) => p.test(url));
+}
+
 function getGlobalXMLHttpRequest(): XMLHttpRequestConstructorLike | undefined {
   return (globalThis as { XMLHttpRequest?: XMLHttpRequestConstructorLike }).XMLHttpRequest;
 }
@@ -183,6 +194,9 @@ export function startXMLHttpRequest(
     ...args: unknown[]
   ) {
     const rewrittenUrl = urlRewriter.get() ? rewriteUrl(url) : url;
+    if (shouldIgnoreUrl(rewrittenUrl)) {
+      return originalXhrOpen!.call(this, method, rewrittenUrl, ...args);
+    }
     pendingXhrRequests.set(this, {
       method: (method || 'GET').toUpperCase(),
       url: rewrittenUrl,
@@ -209,12 +223,11 @@ export function startXMLHttpRequest(
     body?: unknown,
   ) {
     const that = this;
-    const state = pendingXhrRequests.get(that) ?? {
-      method: 'GET',
-      url: '',
-      headers: {},
-      timestamp: Date.now(),
-    };
+    const existingState = pendingXhrRequests.get(that);
+    if (!existingState) {
+      return originalXhrSend!.call(that, body);
+    }
+    const state = existingState;
     state.body = body;
     state.timestamp = Date.now();
     pendingXhrRequests.set(that, state);

package/src/index.ts

@@ -28,6 +28,20 @@ export { useNavigationLogger } from './features/navigation/useNavigationLogger';
 export { safeStringify } from './utils/safeStringify';
 export { copyToComputer, logToComputer, fmt } from './utils/copyToComputer';
 export type { CopyResult, CopyOptions, CopyMethod } from './utils/copyToComputer';
+export { createDebugSessionReport } from './utils/sessionReport';
+export type { DebugSessionReport, DebugSessionReportOptions } from './utils/sessionReport';
+export { getDefaultDaemonEndpoint, reportDebugSessionToDaemon } from './utils/reportToDaemon';
+export type { ReportResult, ReportToDaemonOptions } from './utils/reportToDaemon';
+export { checkDaemonConnection } from './utils/daemonConnection';
+export type {
+  DaemonConnectionFailureReason,
+  DaemonConnectionOptions,
+  DaemonConnectionResult,
+} from './utils/daemonConnection';
+export { startStreaming, stopStreaming, isStreaming } from './utils/streamToDaemon';
+export type { StreamStatus, StreamToDaemonOptions } from './utils/streamToDaemon';
+export { autoDetectDaemonIp, getMetroHost } from './utils/autoDetectDaemon';
+export type { AutoDetectOptions, AutoDetectResult } from './utils/autoDetectDaemon';
 
 // Types
 export type {