fix: warn when process env shadows dotenv keys in browse doctor

[pirate]

Summary

• warn in browse doctor when a process-level Browserbase API key differs from .env or .env.local
• parse dotenv files for diagnostics without loading them or exposing credential values
• document process-environment precedence in the CLI setup README

Why

An inherited API key takes precedence over dotenv values and can silently route Browserbase sessions to a different account. The doctor warning makes that conflict visible while preserving the CLI's existing .env behavior and continuing not to load .env.local.

Validation

• pnpm exec prettier --check packages/cli/src/lib/driver/doctor.ts packages/cli/tests/doctor.test.ts
• pnpm exec eslint packages/cli/src/lib/driver/doctor.ts packages/cli/tests/doctor.test.ts
• TypeScript syntax transpilation for the modified source and test
• git diff --check
• confirmed the generic doctor source remains free of a hard-coded API-key variable name

The focused Vitest suite could not run locally because the checkout's CLI dependencies were incomplete and the configured package proxy failed DNS resolution with ENOTFOUND socket-firewall.tail929132.ts.net.

---

Summary by cubic

Warns when a process-level BROWSERBASE_API_KEY overrides .env and flags .env.local differences as ignored, making config conflicts visible without exposing secrets. Updates the CLI README to clarify environment precedence and recommend running browse doctor.

• New Features
  • browse doctor compares process env with .env and .env.local; warns when .env is overridden and notes .env.local mismatches are ignored since it isn’t auto-loaded, parsing with dotenv without loading files or printing values.
  • README clarifies that the process environment takes precedence, browse auto-loads only .env (not .env.local), and adds a quick browse doctor check.

^{Written for commit d826810. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: d826810

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 3 files

Confidence score: 5/5

• Safe to merge after the addressed issues were fixed.

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as Doctor Command
    participant Builder as buildDoctorReport
    participant Warning as dotenvShadowingWarning
    participant Remote as remote configuration
    participant FS as File System
    participant Dotenv as dotenv.parse

    Note over User,Builder: User runs "browse doctor"
    User->>CLI: browse doctor
    CLI->>Builder: buildDoctorReport({ flags, session }, deps)
    Note over Builder,Warning: New environment‑shadowing check

    Builder->>Warning: dotenvShadowingWarning(env, cwd)

    Warning->>Remote: forwardedEnvKeys()
    Remote-->>Warning: ["BROWSERBASE_API_KEY"]

    loop Over [".env", ".env.local"]
        Warning->>FS: readFile(join(cwd, file))

        alt file exists
            FS-->>Warning: content
            Warning->>Dotenv: parse(content)
            Dotenv-->>Warning: parsed object

            loop For each env key
                alt processValue != fileValue
                    Warning->>Warning: record { file, variable }
                end
            end

        else file not found / error
            FS-->>Warning: error
            Warning->>Warning: skip file
        end
    end

    alt at least one conflict recorded
        Warning-->>Builder: DoctorCheck (name: "environment", status: "warn")
        Builder->>Builder: push check into checks[]
    else no conflicts
        Warning-->>Builder: null
    end

    Builder-->>CLI: DoctorReport (checks include environment warning if present)
    CLI-->>User: rendered report (warn message, never shows secret values)

Loading

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

Re-trigger cubic</sub>