fix(cli): align Functions with SDK on v3 CLI

[shrey150]

Summary

• align browse functions with the canonical Functions SDK/CLI contract
• accept --api-url as an alias for --base-url
• forward optional project IDs for publish and local session lifecycle calls while allowing the API to infer the project from the API key
• match the SDK's local invocation context, runtime error shape, scaffold metadata, dependencies, and archive-size guard

Root cause

Browse maintained a parallel Functions client implementation. The canonical SDK/CLI evolved while Browse did not, so Browse's request/scaffold/runtime behavior drifted even though the Functions HTTP API itself did not make a breaking change.

This PR is deliberately based on v3-cli, whose packages/cli tree is identical to the published browse@0.9.6 tag. It supersedes #2700 so the hotfix does not accidentally include the broader v4-spike-cli migration.

Impact

browse functions init, dev, publish, and invoke now follow the working SDK behavior. In particular, publishing works with only BROWSERBASE_API_KEY; callers may still provide --project-id or BROWSERBASE_PROJECT_ID explicitly.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
pnpm --filter browse lint	Formatting, ESLint, and TypeScript checks passed	Proves the v3 backport is statically valid
Functions contract suite	16/16 tests passed	Covers publish, invoke, scaffold, local runtime, project precedence/inference, archive limits, API alias, and error contracts
pnpm --filter browse test under the CI-standard umask	25 files and 369/369 tests passed	Proves the full Browse suite remains green on the v3 lineage
Fresh browse functions init using the locally built CLI	Project scaffolded and installed successfully	Proves the packaged command path and current SDK dependency work together
Real browse functions publish index.ts with BROWSERBASE_PROJECT_ID unset	Function was published/updated successfully through the production Functions API	Directly proves the reported publish failure is fixed by API-key project inference
Real deployed invocation against https://example.com	COMPLETED in 2 seconds with result title Example Domain	Proves the published artifact executes end to end with a real Browserbase session

Release

#2705 is the stacked release PR. It bumps Browse to 0.9.7 and adds a v3-cli-only trusted-publishing job that packs, smoke-tests, and publishes only the Browse tarball.

[changeset-bot]

🦋 Changeset detected

Latest commit: bad9aa9

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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]

All reported issues were addressed across 11 files

Architecture diagram

sequenceDiagram
    participant User as CLI User
    participant CLI as browse CLI (functions commands)
    participant Shared as functions/shared.ts
    participant API as Browserbase Functions API
    participant SDK as SDK Runtime (local dev)
    participant FS as Filesystem

    Note over User,FS: Functions CLI - Publish Flow

    User->>CLI: browse functions publish index.ts --project-id optional
    CLI->>Shared: resolveFunctionsProjectConfig({apiKey, baseUrl, projectId})
    Shared->>Shared: Check --project-id, fallback to BROWSERBASE_PROJECT_ID env
    Shared-->>CLI: config with optional projectId
    CLI->>FS: Create archive from process.cwd()
    FS-->>CLI: archivePath
    CLI->>FS: Check archive size
    alt Archive > 50MB
        CLI->>User: Error: archive exceeds 50MB limit
    end
    CLI->>API: POST /v1/functions (multipart: archive + metadata)
    Note right of CLI: metadata includes entrypoint + projectId (if set)
    API-->>CLI: 200 OK / deployment response

    Note over User,SDK: Functions CLI - Init & Scaffold Flow

    User->>CLI: browse functions init my-function
    CLI->>FS: Check package manager exists
    CLI->>FS: Write package.json
    Note right of FS: version 1.0.0, packageManager field
    CLI->>FS: Scaffold entrypoint, .env (API key only, no project ID)
    CLI->>FS: Install deps
    Note right of FS: @browserbasehq/sdk-functions, playwright-core, zod

    Note over User,SDK: Functions CLI - Local Dev Flow

    User->>CLI: browse functions dev index.ts --project-id opt
    CLI->>Shared: resolveFunctionsProjectConfig()
    Shared-->>CLI: config (may include projectId)
    CLI->>SDK: Start local runtime API on host:port
    Note over SDK: InvocationBridge + BrowserSessionManager

    User->>SDK: HTTP request to function URL
    SDK->>SDK: Build invocation context
    Note right of SDK: {invocation: {id, region:"local"}, session}
    SDK->>API: POST /v1/sessions (projectId + session config)
    API-->>SDK: session id + connectUrl
    SDK->>SDK: Trigger invocation with Lambda runtime headers
    Note right of SDK: Lambda-Runtime-Invoked-Function-Arn uses us-east-1 region

    alt Successful invocation
        SDK-->>User: 202 + result
    else Runtime error
        SDK->>SDK: Format error as {message, stackTrace, type}
        SDK-->>User: 500 + error object
    end

    SDK->>API: POST /v1/sessions/:id (projectId + REQUEST_RELEASE)
    API-->>SDK: 200 OK

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>