@buoy-gg/console 7.0.20 → 7.0.22

package/src/store/consoleLogStore.ts

@@ -52,6 +52,12 @@ export interface ConsoleLogEntry {
   stack?: string;
   /** Where the log came from (component / function / call site). */
   origin?: LogOrigin;
+  /**
+   * True when this entry came from React Native's global error handler (an
+   * uncaught — usually fatal — JS error), not from a `console.*` call. The
+   * message carries a matching `[FATAL]` / `[UNCAUGHT]` prefix.
+   */
+  fatal?: boolean;
 }
 
 /** Methods we intercept, in the order we install them. */
@@ -97,6 +103,13 @@ type Listener = () => void;
 let entries: ConsoleLogEntry[] = [];
 let nextId = 1;
 let installed = false;
+let fatalInstalled = false;
+/**
+ * Raised by an explicit `uninstallConsoleCapture()`. The fatal-error hook can't
+ * be safely unwound once chained (another library may have chained on top of
+ * ours since), so an explicit user OFF mutes fatal recording instead.
+ */
+let captureDisabledByUser = false;
 
 const listeners = new Set<Listener>();
 const clearListeners = new Set<Listener>();
@@ -153,10 +166,87 @@ function captureOwnerStack(): string | undefined {
   }
 }
 
+/**
+ * An error React Native decorated on its way through ExceptionsManager: a
+ * render/lifecycle crash carrying the component stack. `isComponentError` is
+ * set by RN's `getExtendedError`, so this identifies a REAL crash rather than
+ * an ordinary `console.error("...")` call.
+ */
+type ComponentError = Error & {
+  componentStack?: string;
+  isComponentError?: boolean;
+};
+
+/** Frames to keep from a component stack — the crash site plus its context. */
+const COMPONENT_STACK_FRAMES = 8;
+
+/**
+ * Squeeze a React component stack down to the part a human (or an agent
+ * reading this over a wire) actually uses: the component names nearest the
+ * crash.
+ *
+ * Raw component stacks in a Metro dev bundle append the full bundle URL with
+ * every query param to EVERY frame — one crash is ~15 KB of near-identical
+ * `http://192.168.x.x:8830/…&transform.routerRoot=src/app…` noise wrapped
+ * around the handful of names that matter. The complete error, componentStack
+ * included, is still on the entry's `args` for anyone who wants it.
+ */
+function compactComponentStack(stack: string): string {
+  const frames = stack
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    // Drop the "(url)" tail; keep a "Name(./file.tsx)" hint when RN provides one.
+    .map((line) => line.replace(/\s*\((?:https?:|\/).*$/, ""));
+  const shown = frames.slice(0, COMPONENT_STACK_FRAMES);
+  const rest = frames.length - shown.length;
+  return (
+    shown.map((f) => `    ${f}`).join("\n") +
+    (rest > 0 ? `\n    …+${rest} more frames` : "")
+  );
+}
+function asComponentError(arg: unknown): ComponentError | null {
+  if (!(arg instanceof Error)) return null;
+  const e = arg as ComponentError;
+  return e.isComponentError || typeof e.componentStack === "string" ? e : null;
+}
+
 function record(method: ConsoleMethod, args: unknown[]): void {
   // Capture the call site for every log so we can attribute its origin.
   const rawStack = new Error().stack;
   const origin = parseOrigin(rawStack, captureOwnerStack());
+
+  // React Native funnels an uncaught render error back through console.error
+  // (ExceptionsManager.reportException) so console monkey-patches still see it.
+  // That arrives as an ordinary error row, which badly under-sells it: the app
+  // is dead. Promote it to a tagged [FATAL] entry carrying the component stack.
+  const crash = method === "error" ? asComponentError(args[0]) : null;
+  if (crash) {
+    // Tagged [RENDER ERROR], not [FATAL]: React reports an error an
+    // ErrorBoundary CAUGHT and recovered from through this same path, with the
+    // same componentStack, and nothing here distinguishes the two. Claiming a
+    // healthy app "most likely CRASHED" is worse than under-claiming — the
+    // component stack, which is the useful part, is reported either way.
+    const headline = fatalKey(crash.name, crash.message);
+    const located = crash.componentStack
+      ? `\n\nThis error is located at:\n${compactComponentStack(crash.componentStack)}`
+      : "";
+    pushFatal(
+      {
+        id: nextId++,
+        method: "error",
+        level: "error",
+        args: ["[RENDER ERROR]", crash],
+        message: `[RENDER ERROR] ${headline}${located}`,
+        timestamp: Date.now(),
+        stack: crash.stack,
+        origin,
+      },
+      isDuplicateFatal(`[RENDER ERROR] ${headline}`)
+    );
+    return;
+  }
+
   const entry: ConsoleLogEntry = {
     id: nextId++,
     method,
@@ -173,14 +263,287 @@ function record(method: ConsoleMethod, args: unknown[]): void {
       : [...entries, entry];
   emit();
   scheduleSave();
+  // Errors are the entries most likely to be the last thing an app ever logs,
+  // so they get pushed to any dashboard immediately instead of waiting on the
+  // throttle that a dying tree will never run. Rate-limited; ordinary logs
+  // still ride the normal throttled path.
+  if (entry.level === "error") flushConsoleSyncNow();
+}
+
+/** Minimal shape of React Native's global `ErrorUtils`. */
+interface RNErrorUtils {
+  getGlobalHandler?: () =>
+    | ((error: unknown, isFatal?: boolean) => void)
+    | undefined;
+  setGlobalHandler?: (
+    handler: (error: unknown, isFatal?: boolean) => void
+  ) => void;
+}
+
+/**
+ * Two independent seams report the same crash on some setups (the C++ handler
+ * can also feed `console.error`). Suppress a repeat of the same headline within
+ * this window so a crash reads as ONE entry.
+ */
+const FATAL_DEDUPE_MS = 2000;
+let lastFatalKey = "";
+let lastFatalAt = 0;
+
+/**
+ * Normalize a crash headline so the same error reported through two different
+ * seams produces the same key. React Native often sets `error.message` to the
+ * ALREADY-prefixed string ("TypeError: x is not a function"), so one path
+ * builds "TypeError: TypeError: x…" and the other "TypeError: x…" — which
+ * defeats the de-duplication entirely.
+ */
+function fatalKey(name: string | undefined, message: string): string {
+  const body = message.trim();
+  if (name && body.startsWith(`${name}: `)) return body;
+  return name ? `${name}: ${body}` : body;
+}
+
+/**
+ * Has this crash already been recorded moments ago?
+ *
+ * Only ever used to suppress a duplicate PUSH to the dashboard — never to drop
+ * an entry. Two different components crashing with the same message inside the
+ * window are two crashes, and a tool whose pitch is "the app's last words"
+ * must not silently throw one away.
+ */
+function isDuplicateFatal(key: string): boolean {
+  const now = Date.now();
+  if (key === lastFatalKey && now - lastFatalAt < FATAL_DEDUPE_MS) return true;
+  lastFatalKey = key;
+  lastFatalAt = now;
+  return false;
+}
+
+/**
+ * The device sync bridge's "push this tool NOW" escape hatch
+ * (@buoy-gg/external-sync `crashFlush`). Reached through the global rather than
+ * an import because console deliberately has no dependency on external-sync.
+ */
+let lastFlushAt = 0;
+/** Floor between opportunistic flushes, so an error storm can't flood the socket. */
+const FLUSH_MIN_INTERVAL_MS = 150;
+const flushConsoleSyncNow = (force = false): void => {
+  const now = Date.now();
+  // A fatal is the app's last word — it always goes out, rate limit or not.
+  if (!force && now - lastFlushAt < FLUSH_MIN_INTERVAL_MS) return;
+  lastFlushAt = now;
+  try {
+    const set = (globalThis as { __buoyFlushToolSync?: Set<(toolId: string) => void> })
+      .__buoyFlushToolSync;
+    if (!set) return;
+    for (const flush of set) flush("console");
+  } catch {
+    // Best-effort: a crash path must never crash.
+  }
+};
+
+/**
+ * Append a pre-built fatal entry to the ring buffer, then push it to any
+ * connected dashboard IMMEDIATELY.
+ *
+ * A fatal render error unmounts the React tree microseconds later, taking the
+ * sync bridge — and the normal 200 ms throttled snapshot — with it. Flushing
+ * synchronously here is what makes a crashed app's last words readable from
+ * the desktop app and the MCP server instead of the app just going silent.
+ */
+function pushFatal(entry: ConsoleLogEntry, duplicate = false): void {
+  entries =
+    entries.length >= MAX_ENTRIES
+      ? [...entries.slice(entries.length - MAX_ENTRIES + 1), entry]
+      : [...entries, entry];
+  emit();
+  scheduleSave();
+  // A repeat within the dedupe window is still RECORDED (two crashes are two
+  // crashes); it just doesn't earn another forced push to the dashboard.
+  if (!duplicate) flushConsoleSyncNow(true);
+}
+
+/** Record an uncaught JS error from the global handler as an error entry. */
+function recordFatalError(error: unknown, isFatal?: boolean): void {
+  const err = error instanceof Error ? error : undefined;
+  // RN passes isFatal:false for non-fatal uncaught errors (e.g. errors thrown
+  // in event handlers on some setups); anything else is treated as fatal.
+  const label = isFatal === false ? "[UNCAUGHT]" : "[FATAL]";
+  const headline = err ? fatalKey(err.name, err.message) : formatArg(error);
+  const duplicate = isDuplicateFatal(`${label} ${headline}`);
+  // The label leads the args (not just the pre-rendered message): the
+  // DevTools-style row renders from args, so this is what makes the tag
+  // visible in the UI — exactly like `console.error("[FATAL]", err)`.
+  pushFatal(
+    {
+      id: nextId++,
+      method: "error",
+      level: "error",
+      args: [label, error],
+      message: `${label} ${headline}`,
+      timestamp: Date.now(),
+      // The error's OWN stack — the crash site, not this handler's call site.
+      stack: err?.stack,
+      fatal: true,
+    },
+    duplicate
+  );
+}
+
+/**
+ * The exception payload React Native's C++ error handler hands to listeners
+ * registered via `global.RN$registerExceptionListener` (JsErrorHandler.cpp).
+ */
+interface NativeExceptionData {
+  message?: string;
+  originalMessage?: string | null;
+  name?: string | null;
+  componentStack?: string | null;
+  stack?: Array<{
+    file?: string;
+    methodName?: string;
+    lineNumber?: number;
+    column?: number;
+  }>;
+  id?: number;
+  isFatal?: boolean;
+  isComponentError?: boolean;
+  extraData?: { rawStack?: string } & Record<string, unknown>;
+  /** Suppresses RN's own redbox. We never call it — we only observe. */
+  preventDefault?: () => unknown;
+}
+
+/** Render the C++ handler's parsed frames back into a normal stack string. */
+function formatNativeStack(data: NativeExceptionData): string | undefined {
+  const raw = data.extraData?.rawStack;
+  if (typeof raw === "string" && raw.length > 0) return raw;
+  if (!Array.isArray(data.stack) || data.stack.length === 0) return undefined;
+  return data.stack
+    .map((f) => {
+      const where =
+        f.lineNumber != null ? `${f.file ?? "?"}:${f.lineNumber}:${f.column ?? 0}` : f.file ?? "?";
+      return `    at ${f.methodName || "<anonymous>"} (${where})`;
+    })
+    .join("\n");
+}
+
+/** Record a crash reported by React Native's native (C++) error handler. */
+function recordNativeException(data: NativeExceptionData): void {
+  const label = data.isFatal === false ? "[UNCAUGHT]" : "[FATAL]";
+  const headline = fatalKey(data.name ?? undefined, data.originalMessage ?? data.message ?? "Unknown error");
+  const duplicate = isDuplicateFatal(`${label} ${headline}`);
+  // The component stack is the single most useful line for "which component
+  // crashed" — RN puts it in the redbox, so put it in the console entry too.
+  const componentStack =
+    typeof data.componentStack === "string" && data.componentStack.trim()
+      ? `\n\nThis error is located at:\n${compactComponentStack(data.componentStack)}`
+      : "";
+  const message = `${label} ${headline}${componentStack}`;
+  pushFatal(
+    {
+      id: nextId++,
+      method: "error",
+      level: "error",
+      args: [label, headline, ...(componentStack ? [componentStack.trim()] : [])],
+      message,
+      timestamp: Date.now(),
+      stack: formatNativeStack(data),
+      fatal: true,
+    },
+    duplicate
+  );
+}
+
+/**
+ * Register with React Native's native (C++) exception handler — the seam a
+ * RENDER crash actually travels through on the New Architecture.
+ *
+ * React 19 routes an uncaught render error to `onUncaughtError` →
+ * `ExceptionsManager.handleException`, which NEVER reaches
+ * `ErrorUtils.setGlobalHandler`. Where it goes from there depends on the build:
+ *
+ * - `useAlwaysAvailableJSErrorHandling` on: the C++ handler
+ *   (`global.RN$handleException`) reports it and JS sees nothing — this
+ *   listener is the only seam.
+ * - otherwise: JS `reportException` re-feeds `console.error(e)` "so any methods
+ *   monkey patched on top of console.error are called", which the console patch
+ *   catches and promotes to `[FATAL]` (see `record`).
+ *
+ * Both are covered, and a crash reported through both de-duplicates to one
+ * entry. `RN$registerExceptionListener` keeps a LIST of listeners (LogBox
+ * registers one too), so this is purely additive. We never call the payload's
+ * `preventDefault()`: suppressing RN's own redbox is not our call to make.
+ */
+function installNativeExceptionCapture(): boolean {
+  const register = (
+    globalThis as {
+      RN$registerExceptionListener?: (
+        listener: (data: NativeExceptionData) => void
+      ) => void;
+    }
+  ).RN$registerExceptionListener;
+  if (typeof register !== "function") return false;
+  register((data) => {
+    try {
+      if (!captureDisabledByUser) recordNativeException(data);
+    } catch {
+      // Capture must never interfere with error reporting.
+    }
+  });
+  return true;
+}
+
+/**
+ * Hook React Native's error paths so FATAL/uncaught JS errors land in the
+ * console store: the classic `ErrorUtils.setGlobalHandler` (old architecture,
+ * native-module callbacks, promise rejections) AND the native C++ exception
+ * listener (New Architecture render crashes — see
+ * {@link installNativeExceptionCapture}). Both feed the same de-duplicated
+ * `[FATAL]` entry, so a crash reported through both seams shows up once.
+ *
+ * - Chains the previous handler (LogBox/redbox still fire; nothing swallowed).
+ * - Idempotent, and a silent no-op off React Native (neither global present) —
+ *   which also keeps it inert on the desktop dashboard / web mirrors.
+ * - Recording respects an explicit `uninstallConsoleCapture()` (user OFF), but
+ *   the hooks themselves stay chained — they can't be safely removed.
+ */
+export function installFatalErrorCapture(): void {
+  if (fatalInstalled) return;
+  // Latch only once a seam is actually attached. Setting the flag up front
+  // means an install that runs before `InitializeCore` has published
+  // `ErrorUtils` would latch anyway and never retry — silently losing promise
+  // rejections and native-callback errors, which travel ONLY that seam.
+  const nativeInstalled = installNativeExceptionCapture();
+  const errorUtils = (globalThis as { ErrorUtils?: RNErrorUtils }).ErrorUtils;
+  if (typeof errorUtils?.setGlobalHandler !== "function") {
+    fatalInstalled = nativeInstalled;
+    return;
+  }
+  fatalInstalled = true;
+  const previous =
+    typeof errorUtils.getGlobalHandler === "function"
+      ? errorUtils.getGlobalHandler()
+      : undefined;
+  errorUtils.setGlobalHandler((error: unknown, isFatal?: boolean) => {
+    try {
+      if (!captureDisabledByUser) recordFatalError(error, isFatal);
+    } catch {
+      // Capture must never interfere with error reporting.
+    }
+    if (typeof previous === "function") previous(error, isFatal);
+  });
 }
 
 /**
  * Patch the global console methods. Idempotent — safe to call more than once.
  * Each patched method still forwards to the original so normal logging keeps
  * working (Metro terminal, Chrome, native logcat/Xcode).
+ *
+ * Also installs the fatal-error hook (see `installFatalErrorCapture`) so every
+ * install path captures crashes, not just `console.*` calls.
  */
 export function installConsoleCapture(): void {
+  captureDisabledByUser = false;
+  installFatalErrorCapture();
   if (installed) return;
   installed = true;
 
@@ -198,8 +561,10 @@ export function installConsoleCapture(): void {
   }
 }
 
-/** Restore the original console methods. */
+/** Restore the original console methods. Also mutes fatal-error recording
+ * (the hook itself stays chained — see `installFatalErrorCapture`). */
 export function uninstallConsoleCapture(): void {
+  captureDisabledByUser = true;
   if (!installed) return;
   installed = false;
   for (const method of METHODS) {