feat(cli): allow --ws to accept port numbers

[shrey150]

Summary

• When --ws receives a bare port number (e.g. 9222), the CLI now resolves the CDP WebSocket URL via GET http://127.0.0.1:{port}/json/version
• Falls back to ws://127.0.0.1:{port} if /json/version is unavailable
• Full URLs (ws://, wss://, http://) continue to work as before

This means browse --ws 9222 open https://example.com just works.

Test plan

• browse --ws ws://localhost:9222/devtools/browser/... open https://example.com still works (URL passthrough)
• browse --ws 9222 open https://example.com resolves via /json/version and connects
• browse --ws 9222 open https://example.com falls back to ws://127.0.0.1:9222 when /json/version is unavailable
• browse --help shows updated --ws <url|port> description

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 0e76b0f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/browse-cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

2 issues found across 2 files

Confidence score: 3/5

• There is some merge risk because packages/cli/src/index.ts has a concrete user-facing failure mode: /json/version discovery for --ws <port> can hang indefinitely before fallback, which can block CLI usage.
• The test gap in packages/cli/src/index.ts (discovery success and fallback paths) increases regression risk, since the new --ws resolution behavior is not yet locked in with focused coverage.
• Pay close attention to packages/cli/src/index.ts - ensure discovery has a timeout/abort and verify both success and fallback behavior with targeted tests.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/index.ts">

<violation number="1" location="packages/cli/src/index.ts:1464">
P2: Add focused tests for `--ws` port resolution (discovery success and fallback) to lock in the new behavior.

(Based on your team's feedback about adding unit tests for new behavior.) [FEEDBACK_USED]</violation>

<violation number="2" location="packages/cli/src/index.ts:1470">
P2: Add a timeout/abort to `/json/version` discovery so `--ws <port>` cannot hang indefinitely before fallback.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as CLI (resolveWsTarget)
    participant Browser as Local Browser (CDP)
    participant SH as Stagehand Library

    User->>CLI: runCommand() with --ws <input>
    
    Note over CLI,Browser: NEW: Resolve WebSocket Target
    
    alt input is numeric (Port)
        CLI->>Browser: NEW: GET http://127.0.0.1:{port}/json/version
        alt HTTP Success & has webSocketDebuggerUrl
            Browser-->>CLI: 200 OK (JSON)
            CLI->>CLI: Extract webSocketDebuggerUrl
        else HTTP Error or Missing Field
            Browser-->>CLI: 404 / Connection Refused
            CLI->>CLI: NEW: Fallback to ws://127.0.0.1:{port}
        end
    else input is URL (ws://, http://, etc)
        CLI->>CLI: Use input as-is
    end

    CLI->>SH: CHANGED: new Stagehand({ cdpUrl })
    CLI->>SH: stagehand.init()
    
    SH->>Browser: Connect to WebSocket URL
    Browser-->>SH: Connection established
    SH-->>CLI: Ready
    
    CLI->>User: Execute automation command

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/tests/resolve-ws.test.ts">

<violation number="1" location="packages/cli/tests/resolve-ws.test.ts:42">
P2: The fallback test is flaky because it assumes port `19999` is always unavailable. Use a test-controlled server/port so the fallback condition is deterministic.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: The fallback test is flaky because it assumes port 19999 is always unavailable. Use a test-controlled server/port so the fallback condition is deterministic.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/tests/resolve-ws.test.ts, line 42:

<comment>The fallback test is flaky because it assumes port `19999` is always unavailable. Use a test-controlled server/port so the fallback condition is deterministic.</comment>

<file context>
@@ -0,0 +1,60 @@
+  });
+
+  it("falls back to ws://127.0.0.1:{port} when /json/version is unavailable", async () => {
+    const result = await resolveWsTarget("19999");
+    expect(result).toBe("ws://127.0.0.1:19999");
+  });
</file context>