dsh-builtin-browser 0.3.1 → 0.4.1

package/src/browser-electron/system-browser.ts

@@ -44,47 +44,157 @@ export interface DetectedBrowser {
 }
 
 /**
- * Where each Chromium product installs on Windows, plus the registry paths that
- * survive a non-default install location. Only paths that exist are returned, so a
- * caller can tell "not installed" from "installed elsewhere".
+ * Launcher names to look for on PATH, per product and per platform.
+ *
+ * The names genuinely differ: Linux distributions package the launcher under a
+ * versioned name (`microsoft-edge-stable`, `google-chrome-stable`), Windows puts
+ * `chrome.exe` in an Application directory that may or may not be on PATH, and macOS
+ * ships the executable inside the .app bundle. PATH is still consulted first on every
+ * platform — it is what reflects how the user actually installed the browser.
+ */
+const PATH_NAMES: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.Platform, string[]>>> = {
+  chrome: {
+    win32: ['chrome'],
+    darwin: ['Google Chrome', 'Chromium'],
+    linux: ['google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser'],
+  },
+  edge: {
+    win32: ['msedge'],
+    darwin: ['Microsoft Edge'],
+    linux: ['microsoft-edge-stable', 'microsoft-edge', 'microsoft-edge-dev'],
+  },
+  brave: {
+    win32: ['brave'],
+    darwin: ['Brave Browser'],
+    linux: ['brave-browser', 'brave'],
+  },
+}
+
+/**
+ * Where each product installs when its launcher is not on PATH.
+ *
+ * Windows keeps the executable inside a version-less Application directory; macOS
+ * keeps it inside the .app bundle; Linux distributions that do not use a launcher
+ * put it under /usr/bin or /opt. All are checked, and anything missed can be named
+ * explicitly with DSH_BROWSER_<KIND>_PATH.
  */
-const WINDOWS_LOCATIONS: Record<DetectedBrowser['kind'], string[]> = {
-  chrome: [
-    String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`,
-    String.raw`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
-  ],
-  edge: [
-    String.raw`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
-    String.raw`C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
-  ],
-  brave: [
-    String.raw`C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
-    String.raw`C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
-  ],
+const INSTALL_LOCATIONS: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.Platform, string[]>>> = {
+  chrome: {
+    win32: [
+      String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`,
+      String.raw`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+    ],
+    darwin: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ],
+    linux: [
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/google-chrome',
+      '/usr/bin/chromium',
+      '/opt/google/chrome/chrome',
+      '/snap/bin/chromium',
+    ],
+  },
+  edge: {
+    win32: [
+      String.raw`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
+      String.raw`C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+    ],
+    darwin: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+    linux: [
+      '/usr/bin/microsoft-edge-stable',
+      '/usr/bin/microsoft-edge',
+      '/usr/bin/microsoft-edge-dev',
+    ],
+  },
+  brave: {
+    win32: [
+      String.raw`C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
+      String.raw`C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+    ],
+    darwin: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
+    linux: ['/usr/bin/brave-browser', '/usr/bin/brave', '/snap/bin/brave'],
+  },
+}
+
+/**
+ * Find an executable by name on PATH.
+ *
+ * PATH is read from the supplied environment rather than the process's own, so the
+ * detection stays testable. On Windows a bare name needs its extension; elsewhere
+ * the launcher is the file itself.
+ * @param names - candidate launcher names, in preference order.
+ * @param env - the environment to read PATH from.
+ * @param platform - the platform whose PATH and extension conventions apply.
+ * @returns the first existing absolute path, or undefined.
+ */
+function findOnPath(names: readonly string[], env: NodeJS.ProcessEnv, platform: NodeJS.Platform): string | undefined {
+  // Windows spells it Path as often as PATH; the separator differs too.
+  const raw = env.PATH ?? env.Path ?? env.path ?? ''
+  const separator = platform === 'win32' ? ';' : ':'
+  const directories = raw.split(separator).map(entry => entry.trim()).filter(entry => entry !== '')
+  const suffixes = platform === 'win32' ? ['.exe', '.cmd', ''] : ['']
+  for (const name of names) {
+    for (const directory of directories) {
+      for (const suffix of suffixes) {
+        const candidate = join(directory, `${name}${suffix}`)
+        if (existsSync(candidate)) return candidate
+      }
+    }
+  }
+  return undefined
 }
 
 /**
  * Find an installed Chromium browser.
  *
  * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
- * is to be the browser a user actually chose rather than one Windows shipped.
+ * is to be the browser a user actually chose rather than one the system shipped.
+ * Each candidate is looked up in three places, most specific first: an explicit
+ * environment override, then PATH, then the platform's conventional install
+ * locations. PATH comes before the fixed paths because it is what actually reflects
+ * how the browser was installed.
  * @param channel - the configured choice; `bundled` never resolves to a system browser.
  * @param env - environment lookup, injected so tests need no real machine.
+ * @param platform - the platform to use conventions for; injected for the same reason.
  * @returns the detected browser, or undefined when the choice is unavailable.
  */
-export function detectBrowser(channel: BrowserChannel, env: NodeJS.ProcessEnv = process.env): DetectedBrowser | undefined {
+export function detectBrowser(
+  channel: BrowserChannel,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): DetectedBrowser | undefined {
   if (channel === 'bundled') return undefined
   const order: DetectedBrowser['kind'][] = channel === 'auto' ? ['chrome', 'edge', 'brave'] : [channel as DetectedBrowser['kind']]
   for (const kind of order) {
     const fromEnv = (kind === 'chrome' ? env.DSH_BROWSER_CHROME_PATH : kind === 'edge' ? env.DSH_BROWSER_EDGE_PATH : undefined)
     if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv)) return { kind, path: fromEnv }
-    for (const candidate of WINDOWS_LOCATIONS[kind] ?? []) {
+    const onPath = findOnPath(PATH_NAMES[kind]?.[platform] ?? [], env, platform)
+    if (onPath !== undefined) return { kind, path: onPath }
+    for (const candidate of INSTALL_LOCATIONS[kind]?.[platform] ?? []) {
       if (existsSync(candidate)) return { kind, path: candidate }
     }
   }
   return undefined
 }
 
+/**
+ * Everything that was checked for one product, for reporting a miss.
+ *
+ * Detection returns undefined with no explanation, which left the caller able to say
+ * only "not found". This gives the user the actual list so they can see whether the
+ * plugin looked somewhere their browser is not.
+ * @param kind - the product to describe.
+ * @param platform - the platform whose names and locations apply.
+ * @returns the launcher names (as PATH lookups) and the fixed locations checked.
+ */
+export function searchSummary(kind: DetectedBrowser['kind'], platform: NodeJS.Platform = process.platform): string[] {
+  const onPath = (PATH_NAMES[kind]?.[platform] ?? []).map(name => `${name} (on PATH)`)
+  const located = INSTALL_LOCATIONS[kind]?.[platform] ?? []
+  return [...onPath, ...located]
+}
+
 /** One CDP connection to a browser-level WebSocket, with flattened sessions. */
 class CdpClient {
   private nextId = 1
@@ -94,7 +204,7 @@ class CdpClient {
   /**
    * @param url - the browser's `webSocketDebuggerUrl`.
    */
-  constructor(private readonly url: string) {
+  constructor(url: string) {
     // Node 22 provides WebSocket globally; no dependency is added for this.
     const socket = new WebSocket(url)
     this.socket = socket
@@ -108,9 +218,44 @@ class CdpClient {
 
   private readonly socket: WebSocket
 
-  /** Resolve once the socket is open. */
+  /**
+   * Resolve once the socket is open.
+   *
+   * Bounded on purpose. `ready` settles on the socket's own `open` or `error` events, and
+   * a connection that is dropped by something in between may deliver neither — in which
+   * case an unbounded await here would hang the tool call forever, because the caller's
+   * own deadline is only checked between polls and this await happens inside one of them.
+   * @returns when the handshake completed.
+   */
+  /**
+   * Whether the socket is still usable.
+   *
+   * A dropped connection is not reported to the caller of send(); the pending command
+   * would simply never complete. Asking the socket directly is what lets a cached client
+   * be discarded instead of reused, which is the difference between a restart and a 30s
+   * hang on every subsequent call.
+   * @returns true while the socket is open.
+   */
+  isAlive(): boolean {
+    return this.socket.readyState === WebSocket.OPEN
+  }
+
   async whenReady(): Promise<void> {
-    await this.ready
+    const timeoutMs = 30_000
+    let timer: NodeJS.Timeout | undefined
+    try {
+      await Promise.race([
+        this.ready,
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`dsh-builtin-browser: the browser did not complete the CDP handshake within ${timeoutMs / 1000}s`)),
+            timeoutMs,
+          )
+        }),
+      ])
+    } finally {
+      if (timer !== undefined) clearTimeout(timer)
+    }
   }
 
   /**
@@ -121,6 +266,11 @@ class CdpClient {
    * @returns the CDP result.
    */
   async send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<unknown> {
+    // Fail fast and say why. Waiting out the timeout on a closed socket produced
+    // only "timed out", which reads as a slow page and hides the real cause.
+    if (!this.isAlive()) {
+      throw new Error('dsh-builtin-browser: the browser connection is closed (the browser window was probably closed); the next command will start it again')
+    }
     await this.ready
     const id = this.nextId++
     const message = { id, method, ...params !== undefined ? { params } : {}, ...sessionId !== undefined ? { sessionId } : {} }
@@ -203,7 +353,17 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    * @returns the connected client.
    */
   private async ensureClient(): Promise<CdpClient> {
-    if (this.client !== undefined) return this.client
+    // A disposed host must never start a browser: doing so would spawn a process
+    // nobody owns and nobody will kill.
+    if (this.disposed) throw new Error('dsh-builtin-browser: this browser host was released')
+    // The exit listener clears this, but a socket can also die without the process doing so
+    // (the browser closing its debugging endpoint, a dropped connection). Checking the
+    // socket's own state costs nothing and turns a 30s hang into a restart.
+    if (this.client !== undefined) {
+      if (this.client.isAlive()) return this.client
+      this.client.close()
+      this.client = undefined
+    }
     // Concurrent first calls share one startup rather than racing two browsers.
     this.starting ??= this.start().finally(() => { this.starting = undefined })
     return await this.starting
@@ -233,11 +393,42 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     ]
     const child = spawn(this.browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
     this.child = child
+    /**
+     * A launch that fails (ENOENT, no permission, a broken binary) is reported by an
+     * asynchronous 'error' event on the child, NOT by a throw here and NOT by exitCode.
+     * Without this listener Node treats it as unhandled and takes the whole host process
+     * down — one bad browser path would kill DSH, not just fail a tool call.
+     */
+    let launchError: Error | undefined
+    child.on('error', error => { launchError = error })
+    // A browser that exits later is as unusable as one that never started, and the failure
+    // has to reach the NEXT call rather than being swallowed: clearing the client here is
+    // what makes ensureClient() start a fresh browser instead of returning a socket to a
+    // dead process and letting every command time out.
+    child.on('exit', () => {
+      if (this.child !== child) return
+      this.client?.close()
+      this.client = undefined
+      this.child = undefined
+    })
     const portFile = join(this.profileDir, 'DevToolsActivePort')
     const deadline = Date.now() + 30_000
+    /**
+     * Why the loop stopped, so the failure can say what actually happened. Reporting
+     * every ending as "did not expose CDP within 30s" was wrong three ways: the cause,
+     * the words, and the elapsed time — a browser that cannot be launched says so in
+     * half a second, and the caller then looks for a CDP problem that does not exist.
+     */
+    let stopped: 'released' | 'timeout' | 'exited' | 'launch-failed' = 'timeout'
     for (;;) {
-      if (Date.now() > deadline) { child.kill(); this.child = undefined; break }
-      if (child.exitCode !== null) { this.child = undefined; break }
+      // Released while we were starting: stop here rather than keep polling for a
+      // browser that dispose() has already killed, which would leave a connection
+      // to a dead process behind. The child is killed here too — dispose() may have
+      // run before this child was recorded, leaving nobody else to do it.
+      if (this.disposed) { child.kill(); if (this.child === child) this.child = undefined; stopped = 'released'; break }
+      if (launchError !== undefined) { if (this.child === child) this.child = undefined; stopped = 'launch-failed'; break }
+      if (Date.now() > deadline) { child.kill(); if (this.child === child) this.child = undefined; stopped = 'timeout'; break }
+      if (child.exitCode !== null) { if (this.child === child) this.child = undefined; stopped = 'exited'; break }
       if (existsSync(portFile)) {
         try {
           const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? ''
@@ -246,6 +437,9 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
             if (typeof version.webSocketDebuggerUrl === 'string') {
               const client = new CdpClient(version.webSocketDebuggerUrl)
               await client.whenReady()
+              // Still wanted? A dispose() during the handshake has already killed the
+              // process, so publishing the client would leave a dangling connection.
+              if (this.disposed) { client.close(); break }
               this.client = client
               return client
             }
@@ -256,7 +450,20 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       }
       await new Promise(resolve => setTimeout(resolve, 250))
     }
-    throw new Error(`dsh-builtin-browser: ${this.browser.kind} did not expose CDP within 30s (${this.browser.path})`)
+    // Each ending gets its own message. The old single message blamed a CDP timeout for
+    // all of them, which sent the reader looking for a port problem when the browser had
+    // simply failed to launch.
+    const target = `${this.browser.kind} (${this.browser.path})`
+    if (stopped === 'launch-failed') {
+      throw new Error(`dsh-builtin-browser: could not launch ${target}: ${launchError?.message ?? 'unknown error'}`)
+    }
+    if (stopped === 'exited') {
+      throw new Error(`dsh-builtin-browser: ${target} exited immediately after launch (exit code ${child.exitCode}); check that the path is a runnable browser`)
+    }
+    if (stopped === 'released') {
+      throw new Error(`dsh-builtin-browser: ${target} was released while it was starting`)
+    }
+    throw new Error(`dsh-builtin-browser: ${target} did not expose CDP within 30s`)
   }
 
   /**
@@ -274,11 +481,24 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     const viewId = randomUUID()
     return {
       id: viewId,
+      // This is the real browser, not Electron: CDP's JPEG encoder works here, so the
+      // provider may pass format and quality through instead of falling back to PNG.
+      supportsCdpJpeg: true,
       sendCommand: async (method: string, params?: Record<string, unknown>) => {
+      // A command that never answered is the only signal that a client has wedged — the
+      // socket can stay OPEN while nothing comes back, which is the form the reporter saw with
+      // a live, healthy-looking Edge. Dropping the client here means the next call starts a new
+      // browser rather than hanging again, and the error names the cause instead of a timeout.
+      try {
         const client = await this.ensureClient()
         const session = this.views.get(viewId) ?? await this.ensureSession(viewId)
         const result = await client.send(method, params, session)
         return (result ?? {}) as Record<string, unknown>
+      } catch (error) {
+        this.client?.close()
+        this.client = undefined
+        throw error
+      }
       },
     }
   }
@@ -308,14 +528,19 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   groupView(): void {}
 
   /**
-   * Bring the browser's window forward.
+   * Best effort at bringing the browser's window forward.
    *
-   * The browser is a separate application, so there is no view to raise; focusing
-   * the process is the closest honest equivalent, and failing to do so (a minimized
-   * window, a locked session) is never worth an error.
+   * The browser is a separate application, so there is no view to raise. What this can
+   * actually do is ask its process to continue from a stopped state — which is a no-op on
+   * Windows, where `SIGCONT` is not a supported signal and the call throws. It is kept
+   * because it costs nothing and does help on POSIX (a process stopped with SIGSTOP
+   * resumes), but it must not be read as a promise that the window comes to the front;
+   * importantly, it does NOT raise a window that is merely behind another. Raising the
+   * page properly would need `Page.bringToFront` on a specific target session, which is a
+   * view-level concern and not available to the host.
    */
   async focus(): Promise<void> {
-    try { this.child?.kill('SIGCONT') } catch { /* not supported on Windows; harmless */ }
+    try { this.child?.kill('SIGCONT') } catch { /* Windows has no SIGCONT; nothing to do */ }
   }
 
   /** The browser reports its own window lifecycle. */