fix(cli): fall back to BROWSERSTACK_BINARY_URL when update_cli fails (SDK-6948)

[AakashHotchandani]

Problem

update_cli runs during bootstrap — before the CLI binary is spawned and before GRR localizes the API hosts — so it always targets production api.browserstack.com. On an internal staging run (BROWSERSTACK_STAGING_ENV) the staging credentials are rejected there (401). got throws, checkAndUpdateCli propagates, setupCliPath returns null, and the launcher crashes:

bootstrap: failed to bootstrap TypeError [ERR_INVALID_ARG_VALUE]: The argument 'file' cannot be empty. Received ''
    at spawn (node:child_process) -> BrowserstackCLI.start -> startMain -> bootstrap

The binary is never downloaded (its URL comes from the update_cli response, which never arrives), so no sdk-cli.log is produced.

Fix

Wrap the update_cli call in try/catch. On failure, if BROWSERSTACK_BINARY_URL is set, download the binary from that URL and use it; otherwise re-throw (behaviour unchanged when the var is unset). This turns BROWSERSTACK_BINARY_URL from a download-source override (only read after a successful update_cli) into a real bootstrap fallback, so a worker can pull a binary from a URL even when the staging api-<env> / update_cli tier is unreachable.

Opt-in / zero default impact: with no BROWSERSTACK_BINARY_URL, the catch re-throws — identical to today. Same download + verification path (downloadLatestBinary). No auth bypass — the session's real calls (build-start, hub, testhub) still authenticate.

Tests

• 2 new unit tests (fires on failure with the URL set; re-throws without it) — both pass.
• 3 unrelated tests in cliUtils.test.ts fail on main already (pre-existing requestToUpdateCLI / global.fetch drift). Confirmed by running the suite on main with this change stashed (37 tests, same 3 fail) — not introduced here.

Validation

Validated end-to-end on the v8 line (identical code path, PR #183): prod-mode run with BROWSERSTACK_STAGING_ENV=devapplca + BROWSERSTACK_BINARY_URL pointing at a locally-served zip -> update_cli 401 -> falling back to BROWSERSTACK_BINARY_URL -> binary downloaded (GET /binary.zip 200) -> spawned -> build-start reached. The spawn('') crash is gone.

Follow-up (separate): properly localize update_cli via BROWSERSTACK_STAGING_ENV (port of ruby-sdk SDK-6583) + bring up the staging api-<env> tier. This fallback is the production-safe bridge until then.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited), Workspace UI (inherited)

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: b1cc3353-ee28-4f76-bac9-14768b2c832e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}