dsh-builtin-browser 0.3.0 → 0.4.0

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 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 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 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,31 @@ 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.
+   */
   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)
+    }
   }
 
   /**
@@ -162,33 +294,68 @@ class CdpClient {
 export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   private readonly views = new Map<string, string>()
   private disposed = false
+  /**
+   * The browser is started on FIRST USE, never on construction.
+   *
+   * A plugin that launches Chrome the moment its host loads is a plugin that takes
+   * over the machine before anyone asked it to: simply starting DSH would spawn a
+   * browser window. Registration must therefore be inert, and the process is only
+   * spawned when a view is actually needed.
+   */
+  private client: CdpClient | undefined
+  private child: ChildProcess | undefined
+  private starting: Promise<CdpClient> | undefined
 
   /**
-   * @param child - the launched browser process.
-   * @param client - the CDP connection to it.
-   * @param kind - which product this is (for diagnostics).
-   * @param ephemeralDir - a throwaway profile to remove on release, when the user
-   *   has turned persistence off and no login state should outlive the session.
+   * @param browser - the detected installation to launch on first use.
+   * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
+   * @param extraArgs - additional Chromium switches.
+   * @param ephemeralDir - a directory to delete on release, when the user has turned
+   *   persistence off so no login state outlives the session.
    */
-  private constructor(
-    private readonly child: ChildProcess,
-    private readonly client: CdpClient,
-    readonly kind: DetectedBrowser['kind'],
+  constructor(
+    private readonly browser: DetectedBrowser,
+    private readonly profileDir: string,
+    private readonly extraArgs: readonly string[] = [],
     private readonly ephemeralDir?: string,
   ) {}
 
+  /** Which product this host would drive (for diagnostics). */
+  get kind(): DetectedBrowser['kind'] {
+    return this.browser.kind
+  }
+
+  /** Whether the browser has actually been started yet (diagnostics and tests). */
+  get started(): boolean {
+    return this.child !== undefined
+  }
+
   /**
-   * @param browser - the detected installation to launch.
-   * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
-   * @param extraArgs - additional Chromium switches.
-   * @param ephemeralDir - a directory to delete when the browser is released, used
-   *   when persistence is switched off so no login state outlives the session.
-   * @returns the host, or undefined when the browser refuses to come up.
+   * The CDP client, starting the browser on first use.
+   * @returns the connected client.
    */
-  static async launch(browser: DetectedBrowser, profileDir: string, extraArgs: readonly string[] = [], ephemeralDir?: string): Promise<SystemBrowserViewHost | undefined> {
+  private async ensureClient(): Promise<CdpClient> {
+    // 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')
+    if (this.client !== undefined) return this.client
+    // Concurrent first calls share one startup rather than racing two browsers.
+    this.starting ??= this.start().finally(() => { this.starting = undefined })
+    return await this.starting
+  }
+
+  /**
+   * Launch the browser with a private profile and connect over CDP.
+   *
+   * `--remote-debugging-port=0` plus the `DevToolsActivePort` file is the only
+   * reliable way to learn the port: a fixed port collides with whatever else the
+   * machine is running, and parsing stderr is fragile across versions.
+   * @returns the connected client.
+   */
+  private async start(): Promise<CdpClient> {
     const args = [
       '--remote-debugging-port=0',
-      `--user-data-dir=${profileDir}`,
+      `--user-data-dir=${this.profileDir}`,
       // Behave like a fresh, unattended browser: no first-run UI, no default-browser
       // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
       '--no-first-run',
@@ -196,15 +363,37 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       '--disable-features=Translate,MediaRouter',
       '--disable-session-crashed-bubble',
       '--hide-crash-restore-bubble',
-      ...extraArgs,
+      ...this.extraArgs,
       'about:blank',
     ]
-    const child = spawn(browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
-    const portFile = join(profileDir, 'DevToolsActivePort')
+    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 })
+    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(); return undefined }
-      if (child.exitCode !== null) return undefined
+      // 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() ?? ''
@@ -213,7 +402,11 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
             if (typeof version.webSocketDebuggerUrl === 'string') {
               const client = new CdpClient(version.webSocketDebuggerUrl)
               await client.whenReady()
-              return new SystemBrowserViewHost(child, client, browser.kind, ephemeralDir)
+              // 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
             }
           }
         } catch {
@@ -222,9 +415,29 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       }
       await new Promise(resolve => setTimeout(resolve, 250))
     }
+    // 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`)
   }
 
-  /** Whether this host can back views: the CDP connection is live. */
+  /**
+   * Whether this host can back views.
+   *
+   * True while the host is usable — including before the browser has been started,
+   * since the first command is what starts it. Reporting "unavailable" here would
+   * make the plugin fall back for no reason.
+   */
   available(): boolean {
     return !this.disposed
   }
@@ -233,9 +446,13 @@ 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>) => {
+        const client = await this.ensureClient()
         const session = this.views.get(viewId) ?? await this.ensureSession(viewId)
-        const result = await this.client.send(method, params, session)
+        const result = await client.send(method, params, session)
         return (result ?? {}) as Record<string, unknown>
       },
     }
@@ -249,7 +466,8 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     // was attached to, which is why they are tracked separately.
     const targetId = this.sessions.get(session)
     this.sessions.delete(session)
-    if (targetId !== undefined) {
+    // Nothing to close if the browser was never started.
+    if (targetId !== undefined && this.client !== undefined) {
       // Best-effort: a page that is already gone is not an error.
       void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined)
     }
@@ -265,14 +483,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. */
@@ -281,19 +504,28 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   /** The browser reports its own window lifecycle. */
   onViewClosed(): void {}
 
-  /** Close the browser we launched. The user's own windows are a different process. */
+  /**
+   * Close the browser we launched, if we ever launched one.
+   *
+   * The user's own windows belong to a different process and are never touched. A
+   * host whose browser was never started (the common case when nobody used the
+   * browser) simply tears down its bookkeeping.
+   */
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
     this.views.clear()
     this.sessions.clear()
-    this.client.close()
-    try { this.child.kill() } catch { /* already gone */ }
+    this.client?.close()
+    try { this.child?.kill() } catch { /* already gone */ }
     const ephemeral = this.ephemeralDir
-    if (ephemeral !== undefined) {
+    if (ephemeral !== undefined && this.child !== undefined) {
       // The browser flushes its profile while shutting down, so deleting later avoids
       // racing it. Leftovers are only a stray temp directory, never a live credential.
       setTimeout(() => { try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ } }, 3_000).unref?.()
+    } else if (ephemeral !== undefined) {
+      // Never started, so nothing can be holding it open.
+      try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ }
     }
   }
 
@@ -301,10 +533,11 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   private async ensureSession(viewId: string): Promise<string> {
     const existing = this.views.get(viewId)
     if (existing !== undefined) return existing
-    const created = await this.client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
+    const client = await this.ensureClient()
+    const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
     const targetId = created?.targetId
     if (typeof targetId !== 'string') throw new Error('dsh-builtin-browser: the browser did not create a page')
-    const attached = await this.client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
+    const attached = await client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
     const sessionId = attached?.sessionId
     if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
     // The session id is what page commands ride; the target id is what closes it.