@scalebun-release/react-native 2.5.0

package/lib/module/debug/bootstrap.js

@@ -0,0 +1,393 @@
+/**
+ * ScaleBun Debug — Bootstrap (Orchestrator)
+ *
+ * Entry point for enabling the debug subsystem.
+ * Delegates to focused modules for each responsibility:
+ *   - hostResolver   → debug host address resolution
+ *   - replayWiring   → ReplaySdk init + native capture
+ *   - sessionWiring  → SessionManager creation
+ *   - perfWiring     → PerformanceFeature + ProfilerFeature
+ *   - screenTracking → auto screen detection + cross-cutting state
+ *   - exportBridge   → SDK→Desktop export protocol
+ *
+ * This file retained: DebugConfig type, singleton state variables,
+ * enableDebug/disableDebug orchestration, and getter functions.
+ */
+
+import { DebugTransport } from './transport';
+import { DEFAULT_WS_PORT, DEBUG_READY_EMIT_DELAY_MS } from '../core/constants/timings';
+import { SDK_VERSION } from '../core/constants/version';
+import { DebugEventStream } from './stream';
+import { CommandRegistry } from './commands';
+import { logger } from '../core/logger/internalLogger';
+import { getDeviceId } from '../core/id/deviceId';
+import { DEFAULT_JOURNEY_CONFIG } from '../features/journey/journeyTypes';
+// ─── Decomposed Modules ────────────────────────────────────────────────────
+import { resolveDebugHost } from './hostResolver';
+import { initReplaySdk, wireNativeCaptureDeferred, teardownReplay, resetReplayState, isReplaySdkInitialized, getReplaySdk } from './replayWiring';
+import { createSessionManager } from './sessionWiring';
+import { initPerformance, initProfiler } from './perfWiring';
+import { getTrackedScreen, startAutoScreenDetection } from './screenTracking';
+import { requestExport as _requestExport, handleExportResult, teardownExports } from './exportBridge';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+// ─── Singleton State ────────────────────────────────────────────────────────
+
+let _transport = null;
+let _stream = null;
+let _commands = null;
+let _perf = null;
+let _performanceFeature = null;
+let _profilerFeature = null;
+let _sessionManager = null;
+let _enabled = false;
+let _journeyConfig = DEFAULT_JOURNEY_CONFIG;
+let _debugReady = false;
+let _globalTransportWarnEmitted = false;
+let _autoScreenDetector = null;
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Is the desktop-debugger tooling present in this bundle?
+ *
+ * When `features: { devTools: false }` is set in metro.config.js these modules resolve to an empty
+ * stub, so their exports are `undefined`. Checked as values rather than via a build-time flag
+ * because the answer is a property of how the bundle was resolved, which no runtime flag can know.
+ */
+function isDevToolsBundled() {
+  return typeof DebugTransport === 'function' && typeof DebugEventStream === 'function' && typeof CommandRegistry === 'function' && typeof resolveDebugHost === 'function';
+}
+
+/**
+ * Enable the debug subsystem. Connects to the desktop app over WebSocket
+ * and starts streaming SDK events.
+ *
+ * Safe to call multiple times — will no-op if already enabled (idempotent).
+ */
+export function enableDebug(config) {
+  try {
+    if (_enabled) {
+      __DEV__ && logger.debug('Debug already enabled, skipping');
+      return;
+    }
+
+    // Refuse in release builds. See `allowInRelease` on DebugConfig: this
+    // channel is plaintext ws:// carrying console output, network traffic
+    // and the shared secret, and the only previous guard was that the
+    // tooling is excluded from bundles by default — which a developer
+    // disables to debug locally and then forgets. Warn rather than fail
+    // silently, because a debug connection that does nothing with no
+    // explanation is its own long afternoon.
+    if (!__DEV__ && !config.allowInRelease) {
+      logger.warn('[ScaleBun] Debug connection refused in a release build. The debug ' + 'transport is unencrypted (ws://) and carries captured traffic and the ' + 'shared secret in cleartext, so it is development-only by default. If ' + 'you genuinely need it in a release build, set ' + '`allowInRelease: true` — and do not ship that to users.');
+      return;
+    }
+
+    // The desktop-debugger tooling can be excluded from a build via
+    // `withScaleBun(config, { features: { devTools: false } })`, which resolves these modules
+    // to an empty stub. Detect that explicitly: without this check the first `new
+    // DebugTransport(...)` throws "not a constructor", the catch below reports it as a failure
+    // to enable debug, and the real cause — a deliberate build-time opt-out — is three layers
+    // from the message the developer reads.
+    if (!isDevToolsBundled()) {
+      logger.warn('[ScaleBun] debugConnection was configured, but the desktop-debugger tooling is not ' + 'in this bundle. It is excluded by default (the ScaleBun desktop app is not yet ' + 'released); opt in with `withScaleBun(config, { features: { devTools: true } })` ' + 'in metro.config.js. All other SDK behaviour is unaffected.');
+      return;
+    }
+    const host = resolveDebugHost(config.host);
+    const port = config.port ?? DEFAULT_WS_PORT;
+    __DEV__ && logger.debug(`Enabling debug transport → ws://${host}:${port}`);
+
+    // Store journey config
+    _journeyConfig = {
+      enabled: config.journey?.enabled ?? DEFAULT_JOURNEY_CONFIG.enabled,
+      autoStart: config.journey?.autoStart ?? DEFAULT_JOURNEY_CONFIG.autoStart,
+      screenshots: {
+        ...DEFAULT_JOURNEY_CONFIG.screenshots,
+        ...config.journey?.screenshots
+      },
+      gestures: {
+        ...DEFAULT_JOURNEY_CONFIG.gestures,
+        ...config.journey?.gestures
+      },
+      nav: {
+        ...DEFAULT_JOURNEY_CONFIG.nav,
+        ...config.journey?.nav
+      }
+    };
+
+    // Platform metadata
+    let platform;
+    const osVersion = 'unknown';
+    try {
+      const {
+        Platform
+      } = require('react-native');
+      platform = Platform.OS;
+    } catch {
+      platform = undefined;
+    }
+
+    // Create transport
+    const transportConfig = {
+      host,
+      port,
+      appName: config.appName ?? 'ScaleBun App',
+      bundleId: config.bundleId,
+      platform,
+      osVersion,
+      buildType: __DEV__ ? 'debug' : 'release',
+      capabilities: ['logs', 'events', 'network', 'crashes', 'metrics', 'replay', ...(_journeyConfig.enabled ? ['journey'] : [])],
+      secret: config.secret ?? null
+    };
+    _transport = new DebugTransport(transportConfig);
+
+    // @deprecated — use _getTransport() from this module; will be removed in the next major version.
+    // Kept as a global alias for external tooling that accesses it directly (e.g. dev console scripts).
+    if (!_globalTransportWarnEmitted) {
+      logger.warn('[ScaleBun] global.__scalebun_transport is deprecated. Use _getTransport() from @scalebun/react-native/debug/bootstrap instead. This alias will be removed in the next major version.');
+      _globalTransportWarnEmitted = true;
+    }
+    globalThis.__scalebun_transport = _transport;
+
+    // Set identity
+    const deviceId = getDeviceId();
+    const sessionId = `debug-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
+    _transport.setIdentity(deviceId, sessionId);
+
+    // Create event stream
+    _stream = new DebugEventStream(_transport, {
+      captureConsole: config.captureConsole ?? true,
+      captureSDKLogs: config.captureSDKLogs ?? true,
+      redactNetwork: config.redactNetwork ?? true
+    });
+    _stream.setScreenProvider(() => getTrackedScreen());
+
+    // Create command registry
+    _commands = new CommandRegistry(_transport);
+    _commands.setStream(_stream);
+
+    // ─── Delegate to focused modules ────────────────────────────────
+
+    // Replay init
+    initReplaySdk(config.replay, _transport);
+
+    // Register command handler
+    _transport.onCommand(async cmd => {
+      await _commands?.handleCommand(cmd);
+    });
+
+    // Session manager
+    _sessionManager = createSessionManager(_transport, _commands, config.session, config._sessionDisabled);
+
+    // Wire recording session ID provider into the stream.
+    // Uses a lazy lambda so it always reflects the most recent SessionManager
+    // state (recording active → ses-xxx, idle → null).
+    // This is the ONLY place that connects SessionManager to DebugEventStream;
+    // do not read _sessionManager.recordingSessionId anywhere else.
+    _stream.setRecordingSessionProvider(() => _sessionManager?.recordingSessionId ?? null);
+
+    // Performance + Profiler
+    const perfResult = initPerformance(_transport, _stream, {
+      performanceDisabled: config._performanceDisabled,
+      enablePerf: config.enablePerf,
+      stallThresholdMs: config.stallThresholdMs
+    });
+    _performanceFeature = perfResult.performanceFeature;
+    _perf = perfResult.perfMonitor;
+    _profilerFeature = initProfiler(_transport, config.enableProfiler);
+
+    // Transport events
+    _transport.onStateChange(state => {
+      __DEV__ && logger.debug(`[Debug Transport] State → ${state}`);
+    });
+
+    // Connect and install
+    _transport.connect();
+    _stream.install();
+    if (!_performanceFeature?.isActive) {
+      _perf?.start();
+    }
+    _enabled = true;
+    _debugReady = true;
+    __DEV__ && logger.info(`Debug enabled → ws://${host}:${port}`);
+
+    // Auto native capture wiring
+    wireNativeCaptureDeferred(() => _sessionManager);
+
+    // Auto screen detection (mirror for debug stream)
+    _autoScreenDetector = startAutoScreenDetection();
+
+    // Emit debug_ready after connection stabilizes
+    setTimeout(() => {
+      try {
+        _emitJourneyEvent('journey:debug_ready', {
+          journeyEnabled: _journeyConfig.enabled,
+          canScreenshot: true,
+          navMode: _autoScreenDetector ? 'auto' : 'beacon',
+          sdkVersion: SDK_VERSION
+        });
+        __DEV__ && logger.debug('Emitted journey:debug_ready event to desktop');
+      } catch {/* no-throw */}
+    }, DEBUG_READY_EMIT_DELAY_MS);
+  } catch (e) {
+    logger.error('Failed to enable debug:', e);
+    disableDebug();
+  }
+}
+
+/**
+ * Disable the debug subsystem and clean up all resources.
+ */
+export function disableDebug() {
+  try {
+    if (_sessionManager) {
+      try {
+        _sessionManager.endSession();
+      } catch {/* no-throw */}
+    }
+    teardownReplay();
+    _autoScreenDetector?.teardown();
+    _autoScreenDetector = null;
+    teardownExports();
+    _performanceFeature?.teardown();
+    _profilerFeature?.teardown();
+    _perf?.stop();
+    _stream?.teardown();
+    _transport?.disconnect();
+  } catch {
+    // No-throw
+  }
+  _transport = null;
+  _stream = null;
+  _commands = null;
+  _perf = null;
+  _performanceFeature = null;
+  _profilerFeature = null;
+  _sessionManager = null;
+  _enabled = false;
+  _debugReady = false;
+  resetReplayState();
+}
+
+// ─── Public Getters ─────────────────────────────────────────────────────────
+
+export function isDebugEnabled() {
+  return _enabled;
+}
+export function addBreadcrumb(message, data) {
+  try {
+    if (!_enabled || !_stream) return;
+    _stream.tapBreadcrumb(message, data);
+  } catch {/* No-throw */}
+}
+export function ping() {
+  try {
+    if (!_enabled || !_transport) return;
+    _stream?.tapBreadcrumb('ping', {
+      timestamp: Date.now()
+    });
+  } catch {/* No-throw */}
+}
+
+// ─── Internal Getters (used by SDK core) ────────────────────────────────────
+
+/** @internal */
+export function _getStream() {
+  return _stream;
+}
+/** @internal */
+export function _getCommands() {
+  return _commands;
+}
+/** @internal */
+export function _setFlushFn(fn) {
+  _commands?.setFlushFn(fn);
+}
+/** @internal */
+export function _getReplaySdk() {
+  return getReplaySdk();
+}
+/** @internal */
+export function _isReplaySdkInitialized() {
+  return isReplaySdkInitialized();
+}
+/** @internal */
+export function _getTransport() {
+  return _transport;
+}
+/** @internal */
+export function _getJourneyConfig() {
+  return _journeyConfig;
+}
+/** @internal */
+export function _isJourneyEnabled() {
+  return _journeyConfig.enabled;
+}
+/** @internal */
+export function _setDebugReady(ready) {
+  _debugReady = ready;
+}
+/** @internal */
+/** @internal */
+export function _getSessionManager() {
+  return _sessionManager;
+}
+/** @internal */
+export function _getAutoScreenDetector() {
+  return _autoScreenDetector;
+}
+export function getPerformanceFeature() {
+  return _performanceFeature;
+}
+export function getProfilerFeature() {
+  return _profilerFeature;
+}
+
+// ─── Re-exported for backward compatibility ─────────────────────────────────
+
+export { setTrackedScreen, getTrackedScreen } from './screenTracking';
+
+/** @internal — Emit a journey-category event to desktop */
+export function _emitJourneyEvent(name, data) {
+  if (!_transport || !_enabled) return;
+  try {
+    // From the SDK-owned constants module — requiring './protocol' here would statically drag
+    // the vendored schema module into every bundle, even ones that exclude the debug tooling.
+    const {
+      PROTOCOL_VERSION
+    } = require('../core/constants/protocol');
+    const msg = {
+      type: 'event',
+      protocolVersion: PROTOCOL_VERSION,
+      deviceId: _transport.deviceId,
+      sessionId: _transport.sessionId,
+      timestamp: Date.now(),
+      sequence: _transport.nextSequence(),
+      payload: {
+        id: `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`,
+        category: 'journey',
+        name,
+        data
+      }
+    };
+    _transport.send(msg);
+  } catch {/* No-throw */}
+}
+
+/**
+ * Request an export from the desktop application.
+ */
+export function requestExport(presetOrOptions) {
+  return _requestExport(_transport, _enabled, presetOrOptions);
+}
+
+/**
+ * Handle export result from desktop (called by CommandRegistry).
+ * @internal
+ */
+export function _handleExportResult(args) {
+  handleExportResult(args);
+}
+//# sourceMappingURL=bootstrap.js.map