@scalebun-release/react-native 2.5.0

package/lib/module/debug/commands.js

@@ -0,0 +1,726 @@
+/**
+ * ScaleBun Debug — Command Registry & Handlers
+ *
+ * Handles commands sent from the Desktop app to the SDK.
+ * Each command has a name and a handler function.
+ * Built-in commands: ping, setLogLevel, clearQueue, triggerFlush, addBreadcrumb, snapshot
+ * Journey commands: journeyRecordToggle, journeyCaptureStep, journeySave, journeyRun, journeyStopRun
+ */
+
+import { PROTOCOL_VERSION } from './protocol';
+import { logger, LogLevel } from '../core/logger/internalLogger';
+import { coreContainer } from '../core/di/container';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+// ─── Journey Manager Interface (to avoid circular deps) ─────────────────────
+
+// ─── Session Manager Interface (to avoid circular deps) ─────────────────────
+
+// ─── Command Registry ───────────────────────────────────────────────────────
+
+export class CommandRegistry {
+  handlers = new Map();
+  stream = null;
+  flushFn = null;
+  journeyManager = null;
+  sessionManager = null;
+  _journeyEnabled = false;
+  _debugReady = false;
+  constructor(transport) {
+    this.transport = transport;
+    this._registerBuiltins();
+  }
+
+  /** Set the event stream reference (for breadcrumb command) */
+  setStream(stream) {
+    this.stream = stream;
+  }
+
+  /** Set the flush function reference */
+  setFlushFn(fn) {
+    this.flushFn = fn;
+  }
+
+  /** Set the session manager reference */
+  setSessionManager(manager) {
+    this.sessionManager = manager;
+  }
+
+  /** Set the journey manager reference */
+  setJourneyManager(manager) {
+    this.journeyManager = manager;
+  }
+
+  /** Set journey enabled flag */
+  setJourneyEnabled(enabled) {
+    this._journeyEnabled = enabled;
+  }
+
+  /** Set debug ready flag */
+  setDebugReady(ready) {
+    this._debugReady = ready;
+  }
+
+  /** Register a custom command handler */
+  register(name, handler) {
+    this.handlers.set(name, handler);
+  }
+
+  /** Handle an incoming command from desktop. Never throws. */
+  async handleCommand(cmd) {
+    try {
+      const handler = this.handlers.get(cmd.payload.name);
+      if (!handler) {
+        this._sendResult(cmd.payload.commandId, false, undefined, `Unknown command: ${cmd.payload.name}`);
+        return;
+      }
+      const result = await handler(cmd.payload.args);
+      this._sendResult(cmd.payload.commandId, result.success, result.data, result.error);
+    } catch (e) {
+      this._sendResult(cmd.payload.commandId, false, undefined, e instanceof Error ? e.message : 'Command execution failed');
+    }
+  }
+
+  // ─── Built-in Commands ──────────────────────────────────────────────────
+
+  _registerBuiltins() {
+    // ping → pong
+    this.register('ping', async () => {
+      return {
+        success: true,
+        data: {
+          pong: true,
+          timestamp: Date.now()
+        }
+      };
+    });
+
+    // setLogLevel → update SDK internal logger level
+    this.register('setLogLevel', async args => {
+      const level = args?.level;
+      const levelMap = {
+        debug: LogLevel.DEBUG,
+        info: LogLevel.INFO,
+        warn: LogLevel.WARN,
+        error: LogLevel.ERROR,
+        none: LogLevel.NONE
+      };
+      if (typeof level !== 'string' || !levelMap[level]) {
+        return {
+          success: false,
+          error: `Invalid log level: ${level}. Valid: debug, info, warn, error, none`
+        };
+      }
+      logger.setLevel(levelMap[level]);
+      return {
+        success: true,
+        data: {
+          level
+        }
+      };
+    });
+
+    // clearQueue → clear the persistent event queue
+    this.register('clearQueue', async () => {
+      try {
+        const queue = coreContainer.get('PersistentQueue');
+        const count = queue.length();
+        queue.clear();
+        return {
+          success: true,
+          data: {
+            clearedCount: count
+          }
+        };
+      } catch {
+        return {
+          success: true,
+          data: {
+            clearedCount: 0,
+            note: 'Queue not initialized'
+          }
+        };
+      }
+    });
+
+    // triggerFlush → force flush the event queue
+    this.register('triggerFlush', async () => {
+      if (this.flushFn) {
+        await this.flushFn();
+        return {
+          success: true,
+          data: {
+            flushed: true
+          }
+        };
+      }
+      return {
+        success: false,
+        error: 'Flush function not available'
+      };
+    });
+
+    // addBreadcrumb → add a debug breadcrumb
+    this.register('addBreadcrumb', async args => {
+      const message = typeof args?.message === 'string' ? args.message : 'Debug breadcrumb';
+      if (this.stream) {
+        this.stream.tapBreadcrumb(message, args);
+      }
+      return {
+        success: true,
+        data: {
+          message
+        }
+      };
+    });
+
+    // snapshot → capture current app state
+    this.register('snapshot', async () => {
+      let queueLength = 0;
+      try {
+        queueLength = coreContainer.get('PersistentQueue').length();
+      } catch {/* queue not yet initialized */}
+      return {
+        success: true,
+        data: {
+          queueLength,
+          timestamp: Date.now(),
+          connectionState: this.transport.getState()
+        }
+      };
+    });
+
+    // startReplay → routes to SessionManager or ReplaySdk
+    this.register('startReplay', async args => {
+      // Prefer unified SessionManager
+      if (this.sessionManager) {
+        if (this.sessionManager.isActive) {
+          return {
+            success: false,
+            error: 'Session already active'
+          };
+        }
+        this.sessionManager.startSession();
+        return {
+          success: true,
+          data: {
+            sessionId: this.sessionManager.currentSessionId,
+            unified: true
+          }
+        };
+      }
+      return {
+        success: false,
+        error: 'Session manager not initialized'
+      };
+    });
+
+    // stopReplay → routes to SessionManager or ReplaySdk
+    this.register('stopReplay', async () => {
+      // Prefer unified SessionManager
+      if (this.sessionManager) {
+        if (!this.sessionManager.isActive) {
+          return {
+            success: false,
+            error: 'No active session'
+          };
+        }
+        this.sessionManager.endSession();
+        return {
+          success: true,
+          data: {
+            unified: true
+          }
+        };
+      }
+      return {
+        success: false,
+        error: 'Session manager not initialized'
+      };
+    });
+
+    // ─── Unified Session Commands ────────────────────────────────────
+
+    // startSession → start unified session
+    this.register('startSession', async args => {
+      if (!this.sessionManager) {
+        return {
+          success: false,
+          error: 'Session manager not initialized'
+        };
+      }
+      // If a session is already active, end it first to ensure clean state.
+      // This prevents stale async work from a previous session leaking in.
+      if (this.sessionManager.isActive) {
+        this.sessionManager.endSession();
+      }
+      this.sessionManager.startSession(args);
+      return {
+        success: true,
+        data: {
+          sessionId: this.sessionManager.currentSessionId
+        }
+      };
+    });
+
+    // stopSession → stop unified session
+    this.register('stopSession', async () => {
+      if (!this.sessionManager) {
+        return {
+          success: false,
+          error: 'Session manager not initialized'
+        };
+      }
+      if (!this.sessionManager.isActive) {
+        return {
+          success: false,
+          error: 'No active session'
+        };
+      }
+      this.sessionManager.endSession();
+      return {
+        success: true
+      };
+    });
+
+    // captureFrame → manual frame capture (Desktop Capture Step button)
+    this.register('captureFrame', async () => {
+      if (!this.sessionManager) {
+        return {
+          success: false,
+          error: 'Session manager not initialized'
+        };
+      }
+      if (!this.sessionManager.isActive) {
+        return {
+          success: false,
+          error: 'No active session'
+        };
+      }
+      if (this.sessionManager.captureManualFrame) {
+        try {
+          const frame = await this.sessionManager.captureManualFrame();
+          return {
+            success: true,
+            data: {
+              triggered: true,
+              frameId: frame?.frameId
+            }
+          };
+        } catch (err) {
+          return {
+            success: true,
+            data: {
+              triggered: true,
+              captureError: err instanceof Error ? err.message : 'capture failed'
+            }
+          };
+        }
+      }
+      return {
+        success: true,
+        data: {
+          triggered: true,
+          note: 'captureManualFrame not available'
+        }
+      };
+    });
+
+    // ─── Journey Commands ────────────────────────────────────────────
+
+    // journeyRecordToggle → start/stop journey recording
+    this.register('journeyRecordToggle', async args => {
+      if (!this._journeyEnabled) {
+        return {
+          success: false,
+          data: {
+            code: 'JOURNEY_DISABLED'
+          },
+          error: 'Enable journey in enableDebug({journey:{enabled:true}})'
+        };
+      }
+      if (!this._debugReady) {
+        return {
+          success: false,
+          data: {
+            code: 'SDK_NOT_READY'
+          },
+          error: 'Wait for EVENT_DEBUG_READY'
+        };
+      }
+      if (!this.journeyManager) {
+        return {
+          success: false,
+          data: {
+            code: 'JOURNEY_DISABLED'
+          },
+          error: 'Journey manager not initialized'
+        };
+      }
+      const on = args?.on;
+      if (on) {
+        this.journeyManager.startRecording();
+      } else {
+        this.journeyManager.stopRecording();
+      }
+      return {
+        success: true,
+        data: {
+          recording: on
+        }
+      };
+    });
+
+    // journeyCaptureStep → capture a step with current gesture + screenshot
+    this.register('journeyCaptureStep', async args => {
+      if (!this._journeyEnabled) {
+        return {
+          success: false,
+          data: {
+            code: 'JOURNEY_DISABLED'
+          },
+          error: 'Enable journey in enableDebug({journey:{enabled:true}})'
+        };
+      }
+      if (!this._debugReady || !this.journeyManager) {
+        return {
+          success: false,
+          data: {
+            code: 'SDK_NOT_READY'
+          },
+          error: 'Wait for EVENT_DEBUG_READY'
+        };
+      }
+      if (!this.journeyManager.isRecording) {
+        return {
+          success: false,
+          error: 'Not recording — toggle record first'
+        };
+      }
+      const gestureMode = args?.gestureMode || 'TAP';
+      const label = args?.label;
+      const note = args?.note;
+      return this.journeyManager.captureStep(gestureMode, label, note);
+    });
+
+    // journeySave → save the current recorded journey
+    this.register('journeySave', async args => {
+      if (!this._journeyEnabled || !this.journeyManager) {
+        return {
+          success: false,
+          data: {
+            code: 'JOURNEY_DISABLED'
+          },
+          error: 'Journey not enabled'
+        };
+      }
+      const name = args?.name || 'Untitled Journey';
+      const journeyId = args?.journeyId;
+      return this.journeyManager.saveJourney(name, journeyId);
+    });
+
+    // journeyRun → run a saved journey
+    this.register('journeyRun', async args => {
+      if (!this._journeyEnabled || !this.journeyManager) {
+        return {
+          success: false,
+          data: {
+            code: 'JOURNEY_DISABLED'
+          },
+          error: 'Journey not enabled'
+        };
+      }
+      if (!this._debugReady) {
+        return {
+          success: false,
+          data: {
+            code: 'SDK_NOT_READY'
+          },
+          error: 'Wait for EVENT_DEBUG_READY'
+        };
+      }
+      const journeyData = args?.journeyData;
+      const options = args?.options;
+      // Run asynchronously — status events emitted during execution
+      this.journeyManager.runJourney(journeyData, options).catch(() => {});
+      return {
+        success: true,
+        data: {
+          started: true
+        }
+      };
+    });
+
+    // journeyStopRun → stop a running journey
+    this.register('journeyStopRun', async () => {
+      if (!this.journeyManager) {
+        return {
+          success: false,
+          error: 'Journey manager not available'
+        };
+      }
+      this.journeyManager.stopRun();
+      return {
+        success: true
+      };
+    });
+
+    // ─── Performance Monitoring Controls ────────────────────────────
+    this.register('startPerformanceMonitoring', async () => {
+      try {
+        const {
+          getPerformanceFeature,
+          getProfilerFeature
+        } = require('./bootstrap');
+        const perf = getPerformanceFeature();
+        if (perf) {
+          perf.startContinuousCollection();
+        }
+        const profiler = getProfilerFeature();
+        if (profiler && !profiler.isActive()) {
+          await profiler.start();
+        }
+        return {
+          success: true,
+          data: {
+            status: 'monitoring_started'
+          }
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : 'failed to start performance monitoring'
+        };
+      }
+    });
+    this.register('stopPerformanceMonitoring', async () => {
+      try {
+        const {
+          getPerformanceFeature,
+          getProfilerFeature
+        } = require('./bootstrap');
+        const perf = getPerformanceFeature();
+        if (perf) {
+          perf.stopContinuousCollection();
+        }
+        const profiler = getProfilerFeature();
+        if (profiler && profiler.isActive()) {
+          await profiler.stop();
+        }
+        return {
+          success: true,
+          data: {
+            status: 'monitoring_stopped'
+          }
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : 'failed to stop performance monitoring'
+        };
+      }
+    });
+
+    // ─── Performance Screenshot Capture ─────────────────────────────
+    // Captures a screenshot independently of session replay.
+    // Primary path: standalone native capture (no session needed).
+    // Fallback: session-based captureManualFrame (if session is active).
+    // Sends the captured frame via transport with 'perf-capture' source tag.
+
+    this.register('perfCaptureScreen', async args => {
+      const screenName = args?.screenName || 'unknown';
+      try {
+        // ─── Primary: standalone native capture (no session required) ───
+        let nativeResult = null;
+        try {
+          // Lazy import to avoid circular dependency
+          const {
+            bridgeAdapter
+          } = require('../features/replay/bridge/adapters/bridgeAdapter');
+          if (bridgeAdapter.isAvailable()) {
+            nativeResult = await bridgeAdapter.captureScreenshot('perfCapture');
+          }
+        } catch {/* no-throw */}
+        if (nativeResult?.base64) {
+          // Send via transport as session:frame event with performance provenance
+          this._sendPerfScreenshot(screenName, nativeResult);
+          return {
+            success: true,
+            data: {
+              captured: true,
+              source: 'native-standalone',
+              screenName,
+              sizeBytes: nativeResult.sizeBytes,
+              width: nativeResult.width,
+              height: nativeResult.height
+            }
+          };
+        }
+
+        // ─── Fallback: session-based capture (requires active session) ──
+        if (this.sessionManager?.captureManualFrame) {
+          const frame = await this.sessionManager.captureManualFrame();
+          if (frame) {
+            return {
+              success: true,
+              data: {
+                captured: true,
+                source: 'session-capture',
+                frameId: frame.frameId,
+                screenName
+              }
+            };
+          }
+        }
+
+        // ─── No capture path available ──────────────────────────────────
+        return {
+          success: true,
+          data: {
+            captured: false,
+            source: 'none',
+            screenName,
+            reason: 'Native capture module not available. Ensure the native module is linked.'
+          }
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : 'Screenshot capture failed'
+        };
+      }
+    });
+
+    // ─── App Control: Reload ────────────────────────────────────────
+    // Desktop → SDK: trigger app reload.
+    // Debug mode: acknowledge immediately, then DevSettings.reload() on a short delay
+    // so the command_result can flush to the transport before the JS runtime restarts.
+    // Release mode: return structured "unsupported" result.
+    this.register('reloadApp', async () => {
+      try {
+        if (__DEV__) {
+          // Lazy-require to avoid module-scope crashes in bridgeless/new-arch
+          const {
+            DevSettings
+          } = require('react-native');
+          if (typeof DevSettings?.reload !== 'function') {
+            return {
+              success: false,
+              error: 'DevSettings.reload is not available in this environment'
+            };
+          }
+          // Schedule reload after a short delay so the ack flushes first
+          setTimeout(() => {
+            try {
+              DevSettings.reload();
+            } catch {/* no-throw */}
+          }, 100);
+          return {
+            success: true,
+            data: {
+              action: 'reload_requested'
+            }
+          };
+        }
+        // Release builds: reload is not safely supported
+        return {
+          success: false,
+          data: {
+            action: 'unsupported_in_release'
+          },
+          error: 'App reload is not supported in release builds'
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : 'Reload failed'
+        };
+      }
+    });
+
+    // exportReportResult → handle export completion from desktop
+    // Desktop sends this command after processing an export:request event.
+    // Delegates to bootstrap._handleExportResult() which resolves the pending Promise.
+    this.register('exportReportResult', async args => {
+      try {
+        const {
+          _handleExportResult
+        } = require('./bootstrap');
+        _handleExportResult(args || {});
+        return {
+          success: true,
+          data: {
+            handled: true
+          }
+        };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : 'Export result handling failed'
+        };
+      }
+    });
+  }
+
+  // ─── Perf Screenshot Transport ──────────────────────────────────────────
+
+  /**
+   * Send a captured screenshot via transport as a session:frame event.
+   * Uses explicit 'perf-capture' source tag to distinguish from replay frames.
+   */
+  _sendPerfScreenshot(screenName, frame) {
+    try {
+      // Cast to any: session:frame is a valid wire protocol message type
+      // understood by the desktop, but not declared in the SDK's command
+      // protocol union (which only covers command/event/metric types).
+      this.transport.send({
+        type: 'session:frame',
+        protocolVersion: PROTOCOL_VERSION,
+        deviceId: this.transport.deviceId,
+        sessionId: this.transport.sessionId,
+        timestamp: frame.timestamp || Date.now(),
+        sequence: this.transport.nextSequence(),
+        payload: {
+          frameId: `perf-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`,
+          sessionId: this.transport.sessionId,
+          sequenceNumber: 0,
+          screenName,
+          trigger: 'perf-capture',
+          format: frame.format,
+          sizeBytes: frame.sizeBytes,
+          width: frame.width,
+          height: frame.height,
+          imageData: frame.base64,
+          source: 'perf-capture' // Explicit provenance tag
+        }
+      });
+    } catch {/* no-throw */}
+  }
+  _sendResult(commandId, success, data, error) {
+    try {
+      const result = {
+        type: 'command_result',
+        protocolVersion: PROTOCOL_VERSION,
+        deviceId: this.transport.deviceId,
+        sessionId: this.transport.sessionId,
+        timestamp: Date.now(),
+        sequence: this.transport.nextSequence(),
+        payload: {
+          commandId,
+          success,
+          ...(data ? {
+            data
+          } : {}),
+          ...(error ? {
+            error
+          } : {})
+        }
+      };
+      this.transport.send(result);
+    } catch {
+      // No-throw
+    }
+  }
+}
+//# sourceMappingURL=commands.js.map