[STG-1752] fix(cli): default browse env local to isolated

Merged
SH
8mo ago
+566-158

Summary

  • make browse env local default back to an isolated local browser
  • add browse env local --auto-connect as the explicit opt-in path for auto-discovering a debuggable local Chrome
  • keep explicit CDP attach via browse env local <port|url> and add tests to lock in the strategy behavior

Why

browse env local was auto-attaching to an existing local Chrome by default. That can trigger Chrome's remote debugging approval dialog unexpectedly and makes isolated local usage less predictable.

Impact

Users now get a clean local browser by default, while still having two explicit ways to reuse an existing browser when they want to:

  • browse env local --auto-connect
  • browse env local <port|url>

Test Plan

  • pnpm --filter @browserbasehq/browse-cli build
  • pnpm --filter @browserbasehq/browse-cli test
  • pnpm exec prettier --check packages/cli && cd packages/cli && pnpm run eslint && pnpm run typecheck
  • e2e smoke test against a disposable Chrome CDP endpoint on 127.0.0.1:9229 using a temporary HOME / user-data-dir so the checks do not touch a real browsing profile
  • verified browse env local returns localStrategy: "isolated"
  • verified browse status in isolated mode reports localSource: "isolated"
  • verified browse env local and browse status both print the hint to use browse env local --auto-connect to reuse local credentials/cookies
  • verified browse env local --auto-connect returns localStrategy: "auto"
  • verified browse env local --auto-connect prints the hint that plain browse env local switches back to an isolated Chromium browser
  • verified open https://example.com succeeds after --auto-connect
  • verified browse status after --auto-connect reports localSource: "attached-existing" with the resolved CDP URL and the isolated-browser hint
  • verified browse env local 9229 returns localStrategy: "cdp"
  • verified browse status after browse env local 9229 reports localSource: "attached-explicit"

Linear: STG-1752


Summary by cubic

Defaulted browse env local to a clean, isolated browser. Added --auto-connect to opt into reusing a debuggable Chrome, kept explicit CDP attach via browse env local <port|url>, and added mode hints to guide users. Addresses Linear STG-1752 to make local usage predictable and avoid surprise debugging prompts.

  • New Features

    • Isolated local browser is now the default; auto-discovery only with --auto-connect.
    • Mode hints in browse env/browse status suggest when to use --auto-connect or switch back to isolated.
    • browse env local <port|url> remains for explicit CDP targets.
    • Centralized strategy resolution in src/local-strategy.ts with unit tests.
    • Clearer browse env usage and validation; rejects mixing --auto-connect, --isolated, or a target. --isolated is deprecated (accepted; hidden from help).
  • Migration

    • To reuse an existing Chrome: browse env local --auto-connect.
    • To attach to a specific target: browse env local <port|url>.
    • No changes if you want a clean isolated browser by default.