@monoes/monobrowse 1.0.13 → 1.0.15

package/src/browser/cdp.ts

@@ -1,4 +1,5 @@
-import { WebSocket } from 'ws';
+import type { CdpTransport } from './transport.js';
+import { WebSocketTransport } from './transport.js';
 import type { CdpCommand, CdpResponse, CdpTarget } from './types.js';
 
 // send() had no timeout of its own — a command whose response never arrives
@@ -11,8 +12,12 @@ import type { CdpCommand, CdpResponse, CdpTarget } from './types.js';
 // passes 0 (no timeout) or a different value.
 export const DEFAULT_CDP_SEND_TIMEOUT_MS = 30_000;
 
+// The message every path uses to say the connection went away. Shared so a
+// caller matching on it does not have to care which transport was under it.
+const CDP_CLOSED_MESSAGE = 'CDP connection closed';
+
 export class CdpClient {
-  private ws: WebSocket | null = null;
+  private transport: CdpTransport | null = null;
   private pendingCommands = new Map<
     number,
     {
@@ -46,56 +51,58 @@ export class CdpClient {
     this.pendingCommands.clear();
   }
 
+  /** Connect to a Chrome DevTools WebSocket endpoint (the original path). */
   async connect(wsUrl: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-      this.ws = new WebSocket(wsUrl);
+    return this.connectTransport(new WebSocketTransport(wsUrl));
+  }
 
-      this.ws.on('open', () => {
+  /**
+   * Connect over any transport — a local DevTools socket, or the extension
+   * bridge to the user's own logged-in Chrome (see bridge.ts). Everything
+   * downstream of here (sessions, events, timeouts) is identical either way,
+   * which is the point: the instruments never learn which one they are on.
+   */
+  connectTransport(transport: CdpTransport): Promise<void> {
+    this.transport = transport;
+    return transport
+      .open({
+        message: (data) => this.handleMessage(data),
+        // Post-connect failure of either kind strands every in-flight
+        // command, so both flush: 'close' may not fire on all platforms.
+        close: (err) => this.flushPending(err ?? new Error(CDP_CLOSED_MESSAGE)),
+        error: (err) => this.flushPending(err),
+      })
+      .then(() => {
         this.connected = true;
-        resolve();
       });
+  }
 
-      this.ws.on('error', (err) => {
-        if (!this.connected) {
-          reject(err);
+  private handleMessage(data: string): void {
+    try {
+      const msg: CdpResponse = JSON.parse(data);
+      if (msg.id !== undefined && this.pendingCommands.has(msg.id)) {
+        const handler = this.pendingCommands.get(msg.id)!;
+        this.pendingCommands.delete(msg.id);
+        if (msg.error) {
+          handler.reject(new Error(`CDP error ${msg.error.code}: ${msg.error.message}`));
         } else {
-          // Post-connect: flush all pending commands — 'close' may not fire on all platforms
-          this.flushPending(err instanceof Error ? err : new Error(String(err)));
+          handler.resolve(msg);
         }
-      });
-
-      this.ws.on('close', () => {
-        this.flushPending(new Error('CDP connection closed'));
-      });
-
-      this.ws.on('message', (data) => {
-        try {
-          const msg: CdpResponse = JSON.parse(data.toString());
-          if (msg.id !== undefined && this.pendingCommands.has(msg.id)) {
-            const handler = this.pendingCommands.get(msg.id)!;
-            this.pendingCommands.delete(msg.id);
-            if (msg.error) {
-              handler.reject(new Error(`CDP error ${msg.error.code}: ${msg.error.message}`));
-            } else {
-              handler.resolve(msg);
-            }
-          } else if (msg.method) {
-            const listeners = this.eventListeners.get(msg.method);
-            if (listeners) {
-              for (const fn of listeners) {
-                try {
-                  fn(msg.params ?? {}, msg.sessionId);
-                } catch {
-                  /* isolate per-listener errors */
-                }
-              }
+      } else if (msg.method) {
+        const listeners = this.eventListeners.get(msg.method);
+        if (listeners) {
+          for (const fn of listeners) {
+            try {
+              fn(msg.params ?? {}, msg.sessionId);
+            } catch {
+              /* isolate per-listener errors */
             }
           }
-        } catch {
-          // ignore malformed messages
         }
-      });
-    });
+      }
+    } catch {
+      // ignore malformed messages
+    }
   }
 
   send<T = Record<string, unknown>>(
@@ -105,7 +112,7 @@ export class CdpClient {
     timeoutMs: number = DEFAULT_CDP_SEND_TIMEOUT_MS,
   ): Promise<T> {
     return new Promise((resolve, reject) => {
-      if (!this.ws || !this.connected) {
+      if (!this.transport || !this.connected) {
         reject(new Error('CDP not connected'));
         return;
       }
@@ -138,12 +145,10 @@ export class CdpClient {
         },
         timer,
       });
-      this.ws.send(JSON.stringify(cmd), (err) => {
-        if (err) {
-          if (timer) clearTimeout(timer);
-          this.pendingCommands.delete(id);
-          reject(err);
-        }
+      this.transport.send(JSON.stringify(cmd)).catch((err) => {
+        if (timer) clearTimeout(timer);
+        this.pendingCommands.delete(id);
+        reject(err);
       });
     });
   }
@@ -179,9 +184,9 @@ export class CdpClient {
   }
 
   close(): void {
-    this.flushPending(new Error('CDP connection closed'));
-    this.ws?.close();
-    this.ws = null;
+    this.flushPending(new Error(CDP_CLOSED_MESSAGE));
+    this.transport?.close();
+    this.transport = null;
     this.eventListeners.clear();
   }
 

package/src/browser/index.ts

@@ -1,6 +1,7 @@
 export * from '../report/index.js';
 export * from './actions.js';
 export * from './batch.js';
+export * from './bridge.js';
 export * from './browser.js';
 export * from './cdp.js';
 export * from './console-log.js';
@@ -19,6 +20,7 @@ export * from './snapshot.js';
 export * from './storage.js';
 export * from './tabs.js';
 export * from './trace.js';
+export * from './transport.js';
 export * from './types.js';
 export * from './vitals.js';
 export * from './wait.js';

package/src/browser/transport.ts

@@ -0,0 +1,111 @@
+import { WebSocket } from 'ws';
+
+/**
+ * The seam between CdpClient and whatever carries its frames.
+ *
+ * CdpClient used to own a `ws` socket outright, which meant "CDP" and "a
+ * WebSocket to a Chrome we launched" were the same thing. They are not: the
+ * MonoAgent browser extension already holds the `debugger` permission and
+ * speaks CDP to the user's real, logged-in Chrome — it just reaches it
+ * through `chrome.debugger.sendCommand` over the extension bridge instead of
+ * a socket. Everything monobrowse instruments (console, network, HAR,
+ * vitals, trace, profiler, snapshot, screenshot, emulation) goes through
+ * CdpClient, so moving the socket behind this interface is what lets all of
+ * them point at that browser without being ported one at a time.
+ *
+ * A transport deals in whole, already-serialized CDP frames. Framing,
+ * request ids, timeouts and event dispatch stay in CdpClient, so a transport
+ * has nothing to get subtly wrong about the protocol.
+ */
+export interface CdpTransportHandlers {
+  /** One inbound frame: a command response or an event. */
+  message(data: string): void;
+  /**
+   * The transport is gone and nothing more will arrive. `err` explains why
+   * when the transport knows; CdpClient supplies a default when it doesn't.
+   */
+  close(err?: Error): void;
+  /**
+   * A failure *after* open() resolved. A failure before it instead rejects
+   * open() — the caller is still waiting on that promise, and a connect
+   * that fails should look like a failed connect, not a live-then-broken
+   * connection.
+   */
+  error(err: Error): void;
+}
+
+export interface CdpTransport {
+  /** Establish the connection. Resolves once frames can flow. */
+  open(handlers: CdpTransportHandlers): Promise<void>;
+  /** Send one serialized CDP frame; rejects if it could not be written. */
+  send(frame: string): Promise<void>;
+  /** Tear it down. Safe to call more than once. */
+  close(): void;
+}
+
+/**
+ * The original transport: a WebSocket to a Chrome DevTools endpoint, either
+ * a page's `webSocketDebuggerUrl` or the browser-level one. This is the code
+ * that used to live inline in CdpClient.connect(), moved wholesale so the
+ * local path keeps behaving exactly as it did.
+ */
+export class WebSocketTransport implements CdpTransport {
+  private ws: WebSocket | null = null;
+  private opened = false;
+
+  /**
+   * `headers` is only ever used by the bridge transport, whose relay
+   * endpoint is token-authenticated; a DevTools endpoint wants none.
+   */
+  constructor(
+    private readonly url: string,
+    private readonly headers?: Record<string, string>,
+  ) {}
+
+  open(handlers: CdpTransportHandlers): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const ws = this.headers
+        ? new WebSocket(this.url, { headers: this.headers })
+        : new WebSocket(this.url);
+      this.ws = ws;
+
+      ws.on('open', () => {
+        this.opened = true;
+        resolve();
+      });
+
+      ws.on('error', (err) => {
+        const e = err instanceof Error ? err : new Error(String(err));
+        if (!this.opened) {
+          reject(e);
+        } else {
+          // Post-connect: 'close' may not fire on all platforms, so this is
+          // the only notice the owner gets that its commands are stranded.
+          handlers.error(e);
+        }
+      });
+
+      ws.on('close', () => handlers.close());
+
+      ws.on('message', (data) => handlers.message(data.toString()));
+    });
+  }
+
+  send(frame: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this.ws) {
+        reject(new Error('CDP transport not open'));
+        return;
+      }
+      this.ws.send(frame, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  close(): void {
+    this.ws?.close();
+    this.ws = null;
+  }
+}

package/src/cli/commander-adapter.ts

@@ -0,0 +1,65 @@
+/**
+ * Commander-to-internal adapter.
+ *
+ * `action` and `platform` are written against commander, while `browse`'s own
+ * subcommands use this package's internal Command shape. This wraps one as the
+ * other so both can sit in the same subcommand list.
+ */
+
+import type { Command, CommandContext, CommandResult } from './types.js';
+
+/**
+ * Wraps a commander.Command instance as an internal Command object so it can
+ * participate in the browse command's subcommands array.  The adapter
+ * reconstructs a raw argv string from the context that was parsed by the
+ * internal CLI, then hands it off to commander's parseAsync.
+ */
+export function wrapCommanderCommand(factory: () => import('commander').Command): Command {
+  // Lazily instantiate so we don't pay import cost at startup
+  let _cmd: import('commander').Command | null = null;
+  const getCmd = () => {
+    if (!_cmd) _cmd = factory();
+    return _cmd;
+  };
+
+  const cmd = getCmd();
+  const subcommandDefs: Command[] = (cmd.commands as import('commander').Command[]).map((sub) => ({
+    name: sub.name(),
+    description: sub.description(),
+    action: async (ctx: CommandContext): Promise<CommandResult> => {
+      // Rebuild argv: node <cmd> <sub> [positional args] [--flag [value] ...]
+      const argv = ['node', cmd.name(), sub.name(), ...ctx.args];
+      for (const [key, val] of Object.entries(ctx.flags)) {
+        if (key === '_') continue;
+        if (typeof val === 'boolean') {
+          if (val) argv.push(`--${key}`);
+        } else if (val !== undefined && val !== null) {
+          argv.push(`--${key}`, String(val));
+        }
+      }
+      // Re-use the same commander instance to keep state (e.g. option defaults)
+      await getCmd().parseAsync(argv, { from: 'user' });
+      return { success: true };
+    },
+  }));
+
+  return {
+    name: cmd.name(),
+    description: cmd.description(),
+    subcommands: subcommandDefs,
+    action: async (ctx: CommandContext): Promise<CommandResult> => {
+      // No subcommand provided — show commander help
+      const argv = ['node', cmd.name(), ...ctx.args];
+      for (const [key, val] of Object.entries(ctx.flags)) {
+        if (key === '_') continue;
+        if (typeof val === 'boolean') {
+          if (val) argv.push(`--${key}`);
+        } else if (val !== undefined && val !== null) {
+          argv.push(`--${key}`, String(val));
+        }
+      }
+      await getCmd().parseAsync(argv, { from: 'user' });
+      return { success: true };
+    },
+  };
+}