browserwright 0.6.2__py3-none-any.whl

browserwright/daemon/config.py

@@ -0,0 +1,380 @@
+"""Config + env merge.
+
+Source of truth ordering (highest precedence first):
+  CLI flag  >  BD_*-prefixed env var  >  BU_*-prefixed env var (compat)  >  toml file  >  defaults
+
+Spec §5.1 environment-variable table lives here. The toml shape is intentionally
+flat — pydantic / dynaconf are explicitly rejected (附录 B).
+
+The toml file is *optional*. If it doesn't parse, we report a UserError up-stream
+so the CLI can show a clean message instead of a stack trace.
+"""
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+# Path-traversal guard for the `launch-chrome --profile` name — sourced from
+# browser-harness _ipc.py:31-33. (No longer used for a daemon instance name;
+# BD_NAME was removed — see docs/refactor-single-daemon.md.)
+_NAME_RE = re.compile(r"\A[A-Za-z0-9_-]{1,64}\Z")
+
+# Default port for the Playwright-facing CDP facade. Distinct from the
+# extension relay (19989) and playwriter's 19988 so all three can coexist on one
+# machine. Defined here (not facade.py) so config has no import cycle; facade.py
+# re-exports it for backwards compat.
+DEFAULT_FACADE_PORT = 19990
+
+
+def check_name(name: str) -> str:
+    """Path-traversal guard for filesystem-bound names (e.g. `--profile`)."""
+    if not _NAME_RE.match(name or ""):
+        from .errors import UserError
+
+        raise UserError(
+            f"invalid name {name!r}: must match [A-Za-z0-9_-]{{1,64}}"
+        )
+    return name
+
+
+@dataclass
+class RdpConfig:
+    port: int = 9222
+
+
+@dataclass
+class ExtensionConfig:
+    """v0.5.3 REVIEW.md F-5 / Task #24: relay endpoint config.
+
+    Two ways to override the default `ws://127.0.0.1:19989`:
+      - `relay_url`: full URL — most expressive, can change host too
+      - `port`: int — common case ("19989 is occupied, use 29989")
+
+    Precedence (highest first):
+      CLI `--extension-port N`  >  `BD_EXTENSION_PORT` env  >  toml `port`
+        >  toml `relay_url` (parsed for port)  >  `DEFAULT_RELAY_PORT` (19989)
+
+    `host` follows the same source: explicit `port` knobs preserve the
+    existing host (or 127.0.0.1 default), `relay_url` carries both.
+    """
+    relay_url: str | None = None
+    port: int | None = None
+
+    def resolved_host_port(self) -> tuple[str, int]:
+        """Single source of truth for "what host:port should the relay
+        ws server bind to" — consumers (ExtensionBackend ctor for probing,
+        listener.run_serve for binding) call this so they don't each
+        re-implement the precedence rules.
+
+        Returns `(host, port)`. `port` is non-None — we fall back to
+        `DEFAULT_RELAY_PORT` from server/relay.py if nothing else is set.
+        """
+        # Local import dodges the circular hazard between config and server.
+        from .server.relay import DEFAULT_RELAY_PORT
+        host = "127.0.0.1"
+        port = DEFAULT_RELAY_PORT
+        if self.relay_url:
+            from urllib.parse import urlparse
+            parsed = urlparse(self.relay_url)
+            if parsed.hostname:
+                host = parsed.hostname
+            if parsed.port:
+                port = parsed.port
+        if self.port is not None:
+            port = self.port
+        return host, port
+
+
+@dataclass
+class CloudConfig:
+    """v0.5 cloud backend config.
+
+    `endpoint` is the upstream URL. Two shapes accepted:
+      - `wss://host/path` → used directly as the ws URL
+      - `https://host`    → daemon HTTP-GETs `/json/version` and reads
+                             `webSocketDebuggerUrl` (same trick as the `env`
+                             backend's `BD_CDP_URL` path)
+
+    `auth_kind` picks one of the registered AuthProvider impls in
+    `browserwright.daemon.auth`. The kind-specific config dict is `auth` (raw
+    toml subtable, dispatched by `build_auth_provider`).
+
+    `provider_hint` is purely informational — surfaces in doctor output
+    ("connected to provider=browser-use, auth=bearer"). The daemon doesn't
+    behave differently per provider.
+    """
+
+    endpoint: str | None = None
+    auth_kind: str | None = None  # "bearer" | "basic" | "mtls" | "oauth2"
+    auth: dict = field(default_factory=dict)  # raw, fed to build_auth_provider
+    provider_hint: str | None = None  # display name, e.g. "browser-use"
+
+
+@dataclass
+class BackendsConfig:
+    rdp: RdpConfig = field(default_factory=RdpConfig)
+    cloud: CloudConfig = field(default_factory=CloudConfig)
+    extension: ExtensionConfig = field(default_factory=ExtensionConfig)
+
+
+@dataclass
+class Config:
+    """Resolved daemon config — flat, immutable after build."""
+
+    backend: str | None = None             # explicit --backend / BD_BACKEND
+    timeout: float = 5.0                   # per-backend resolve timeout, seconds
+    cdp_ws: str | None = None              # BD_CDP_WS / BU_CDP_WS — env backend uses this
+    cdp_url: str | None = None             # BD_CDP_URL / BU_CDP_URL — env backend uses this
+    chrome_binary: str | None = None       # BD_CHROME_BINARY — launch-chrome
+    idle_close_after: float | None = None  # seconds; None = never (default)
+    # Playwright-facing CDP facade. `serve` binds an additional TCP ws+HTTP
+    # endpoint that a real Playwright client can `connect_over_cdp` to.
+    #
+    # Phase C semantics (auto-enable): the facade is now ON by default — the
+    # skill layer's heredoc `page`/`context` depend on it. Tri-state:
+    #   - None (unset)  -> auto-enable on DEFAULT_FACADE_PORT (the new default).
+    #   - 0             -> explicitly DISABLED.
+    #   - >0            -> explicit override port (CLI/env/toml).
+    # Use `resolved_facade_port()` to collapse this to "bind / don't bind".
+    facade_port: int | None = None
+    backends: BackendsConfig = field(default_factory=BackendsConfig)
+    # Provenance for `env`: which alias key actually fired. Diagnostic-only.
+    cdp_ws_source: str | None = None       # "BD_CDP_WS" | "BU_CDP_WS" | None
+    cdp_url_source: str | None = None      # "BD_CDP_URL" | "BU_CDP_URL" | None
+
+    def resolved_facade_port(self) -> int | None:
+        """Collapse the tri-state ``facade_port`` to a bind decision.
+
+        Returns the port to bind the Playwright facade on, or ``None`` when the
+        facade should NOT be bound:
+          - ``facade_port is None``  -> ``DEFAULT_FACADE_PORT`` (auto-enable).
+          - ``facade_port == 0``     -> ``None`` (explicitly disabled).
+          - ``facade_port > 0``      -> that port (explicit override).
+        """
+        if self.facade_port is None:
+            return DEFAULT_FACADE_PORT
+        if self.facade_port == 0:
+            return None
+        return self.facade_port
+
+
+def _read_toml(path: Path) -> dict:
+    from .errors import UserError
+
+    try:
+        return tomllib.loads(path.read_text())
+    except FileNotFoundError:
+        return {}
+    except (tomllib.TOMLDecodeError, OSError) as e:
+        raise UserError(f"failed to parse config {path}: {e}") from e
+
+
+def load(
+    cli_backend: str | None = None,
+    cli_timeout: float | None = None,
+    cli_port: int | None = None,
+    cli_chrome_binary: str | None = None,
+    cli_config_path: str | None = None,
+    cli_extension_port: int | None = None,
+    cli_facade_port: int | None = None,
+    env: dict[str, str] | None = None,
+) -> Config:
+    """Build a Config from CLI flags + env + optional toml file.
+
+    `env` defaults to os.environ — injecting a dict lets unit tests pin state.
+    """
+    e = os.environ if env is None else env
+
+    # 1) Optional toml
+    cfg_path = cli_config_path or e.get("BD_CONFIG")
+    toml: dict = {}
+    if cfg_path:
+        toml = _read_toml(Path(cfg_path).expanduser())
+
+    # 2) Build a Config piece by piece, with each level overriding the prior
+    cfg = Config()
+
+    # toml level
+    if "timeout" in toml and isinstance(toml["timeout"], (int, float)):
+        cfg.timeout = float(toml["timeout"])
+    # v0.5.2 Task #14: `default_backend` from config.toml. The README has
+    # advertised this key since v0.1 but the parser silently ignored it —
+    # users wrote it expecting it to lock the backend and got the auto
+    # fallback chain instead. Precedence (highest first):
+    #   CLI --backend  >  BD_BACKEND env  >  toml `default_backend`
+    # Backend-name validity is checked at resolve-time (we don't import
+    # backends.names at module scope — circular), so an invalid name like
+    # `"garbage"` is stored as-is and surfaces at `browserwright-daemon url` as
+    # UserError("unknown backend ...").
+    # v0.5.3 F-9 #14: type is validated though — `default_backend = 42`
+    # (integer) silently dropped before, now raises so the user can fix it.
+    if "default_backend" in toml:
+        v = toml["default_backend"]
+        if not isinstance(v, str):
+            from .errors import UserError
+            raise UserError(
+                f"config.toml `default_backend` must be a string, got "
+                f"{type(v).__name__}: {v!r}")
+        cfg.backend = v
+    backends = toml.get("backends", {}) if isinstance(toml.get("backends"), dict) else {}
+    rdp = backends.get("rdp", {}) if isinstance(backends.get("rdp"), dict) else {}
+    if "port" in rdp and isinstance(rdp["port"], int):
+        cfg.backends.rdp.port = rdp["port"]
+    # extension.relay_url substitutes for DEFAULT_RELAY_PORT when set.
+    ext = backends.get("extension", {}) if isinstance(backends.get("extension"), dict) else {}
+    if isinstance(ext.get("relay_url"), str):
+        cfg.backends.extension.relay_url = ext["relay_url"]
+    if isinstance(ext.get("port"), int):
+        cfg.backends.extension.port = ext["port"]
+    cloud = backends.get("cloud", {}) if isinstance(backends.get("cloud"), dict) else {}
+    if "endpoint" in cloud and isinstance(cloud["endpoint"], str):
+        cfg.backends.cloud.endpoint = cloud["endpoint"]
+    if "auth_kind" in cloud and isinstance(cloud["auth_kind"], str):
+        cfg.backends.cloud.auth_kind = cloud["auth_kind"]
+    if "provider_hint" in cloud and isinstance(cloud["provider_hint"], str):
+        cfg.backends.cloud.provider_hint = cloud["provider_hint"]
+    # `[backends.cloud.auth.<kind>]` subtables are passed verbatim to
+    # `build_auth_provider`. We pick out the subtable matching `auth_kind`
+    # so the config-time schema stays per-kind validated downstream.
+    auth_subtables = cloud.get("auth", {}) if isinstance(cloud.get("auth"), dict) else {}
+    if cfg.backends.cloud.auth_kind and isinstance(
+            auth_subtables.get(cfg.backends.cloud.auth_kind), dict):
+        cfg.backends.cloud.auth = dict(auth_subtables[cfg.backends.cloud.auth_kind])
+    if "idle_close_after" in toml and isinstance(toml["idle_close_after"], (int, float)):
+        cfg.idle_close_after = float(toml["idle_close_after"])
+    # Playwright facade port (phase A1). toml key `facade_port`.
+    if "facade_port" in toml and isinstance(toml["facade_port"], int):
+        cfg.facade_port = toml["facade_port"]
+
+    # env level — BD_* wins over BU_*
+    if "BD_TIMEOUT" in e:
+        try:
+            cfg.timeout = float(e["BD_TIMEOUT"])
+        except ValueError:
+            from .errors import UserError
+
+            raise UserError(f"BD_TIMEOUT must be a number, got {e['BD_TIMEOUT']!r}")
+    if "BD_BACKEND" in e:
+        cfg.backend = e["BD_BACKEND"]
+    if "BD_IDLE_CLOSE_AFTER" in e:
+        try:
+            v = float(e["BD_IDLE_CLOSE_AFTER"])
+            cfg.idle_close_after = v if v > 0 else None
+        except ValueError:
+            from .errors import UserError
+            raise UserError(
+                f"BD_IDLE_CLOSE_AFTER must be a number, got {e['BD_IDLE_CLOSE_AFTER']!r}")
+    if "BD_CDP_WS" in e:
+        cfg.cdp_ws = e["BD_CDP_WS"]; cfg.cdp_ws_source = "BD_CDP_WS"
+    elif "BU_CDP_WS" in e:
+        cfg.cdp_ws = e["BU_CDP_WS"]; cfg.cdp_ws_source = "BU_CDP_WS"
+    if "BD_CDP_URL" in e:
+        cfg.cdp_url = e["BD_CDP_URL"]; cfg.cdp_url_source = "BD_CDP_URL"
+    elif "BU_CDP_URL" in e:
+        cfg.cdp_url = e["BU_CDP_URL"]; cfg.cdp_url_source = "BU_CDP_URL"
+    if "BD_CHROME_BINARY" in e:
+        cfg.chrome_binary = e["BD_CHROME_BINARY"]
+    # `BD_RDP_PORT` env override for the rdp backend's port (v0.4.1).
+    #
+    # Originally (spec §8.2 first cut) we deliberately omitted this env var:
+    # the rdp port was config-file or `--port` only, to keep the env namespace
+    # small. But the ai-e2e harness convention is "set env, run agent" — and
+    # without `BD_RDP_PORT`, callers reach for `BD_BACKEND=rdp` + (nothing),
+    # which silently falls through to the hard-coded 9222 default, which on
+    # any developer machine **is the user's daily Chrome** (Chrome 144+ auto-
+    # enables CDP without a cmdline flag). Connecting to that = Allow popup.
+    #
+    # Adding the env var makes "lock to my isolated Chrome's port" expressible
+    # without a config file. Precedence: CLI `--port` > BD_RDP_PORT > toml >
+    # 9222 default (preserves the spec §5.1 ordering rule).
+    if "BD_RDP_PORT" in e:
+        try:
+            cfg.backends.rdp.port = int(e["BD_RDP_PORT"])
+        except ValueError:
+            from .errors import UserError
+            raise UserError(
+                f"BD_RDP_PORT must be an integer, got {e['BD_RDP_PORT']!r}")
+    elif "BD_PORT" in e:
+        # v0.5.3 REVIEW.md F-4c: the v0.4 popup-storm incident's root cause
+        # was a typo: `BD_PORT=9444` (intuitive name) didn't bind to anything
+        # and the rdp backend defaulted to 9222 = user's daily Chrome. We
+        # added `BD_RDP_PORT` but never defended the typo. Now we alias +
+        # warn: if user typed BD_PORT and not BD_RDP_PORT, accept the value
+        # and print a deprecation hint to stderr so they migrate.
+        try:
+            cfg.backends.rdp.port = int(e["BD_PORT"])
+        except ValueError:
+            from .errors import UserError
+            raise UserError(
+                f"BD_PORT (alias for BD_RDP_PORT) must be an integer, got "
+                f"{e['BD_PORT']!r}")
+        # Stderr (NOT stdout — `browserwright-daemon url`'s stdout is the URL).
+        # In tests we sometimes silently want to set the env without warning
+        # noise; gate on `BD_PORT_QUIET=1` for that.
+        if e.get("BD_PORT_QUIET", "") not in ("1", "true", "True"):
+            import sys
+            print(
+                f"warning: BD_PORT is a deprecated alias for BD_RDP_PORT — "
+                f"please update your env / script. (BD_PORT={e['BD_PORT']!r} "
+                f"applied to rdp.port.)",
+                file=sys.stderr,
+            )
+    # v0.5 cloud backend env overrides — useful for one-off CLI calls
+    # without writing a config.toml. Each maps to the equivalent toml key.
+    if "BD_CLOUD_ENDPOINT" in e:
+        cfg.backends.cloud.endpoint = e["BD_CLOUD_ENDPOINT"]
+    if "BD_CLOUD_AUTH_KIND" in e:
+        cfg.backends.cloud.auth_kind = e["BD_CLOUD_AUTH_KIND"]
+    if "BD_CLOUD_PROVIDER_HINT" in e:
+        cfg.backends.cloud.provider_hint = e["BD_CLOUD_PROVIDER_HINT"]
+    # v0.5.3 Task #24: extension relay port via env. Symmetric to BD_RDP_PORT
+    # — useful when the default 19989 is occupied by a stale daemon process
+    # and the user can't write a config.toml on the fly. (playwriter sits on
+    # 19988, so default conflict with it is no longer a concern.)
+    if "BD_EXTENSION_PORT" in e:
+        try:
+            cfg.backends.extension.port = int(e["BD_EXTENSION_PORT"])
+        except ValueError:
+            from .errors import UserError
+            raise UserError(
+                f"BD_EXTENSION_PORT must be an integer, got "
+                f"{e['BD_EXTENSION_PORT']!r}")
+    # Playwright facade port via env (phase A1). Symmetric to BD_EXTENSION_PORT
+    # — set BD_FACADE_PORT=19990 (or any free port) to enable the facade.
+    if "BD_FACADE_PORT" in e:
+        try:
+            cfg.facade_port = int(e["BD_FACADE_PORT"])
+        except ValueError:
+            from .errors import UserError
+            raise UserError(
+                f"BD_FACADE_PORT must be an integer, got {e['BD_FACADE_PORT']!r}")
+    # The auth payload itself is read from kind-specific env vars that the
+    # AuthProvider already knows about (`token_env`, `cert_file`, etc).
+    # The env-override layer here is just for endpoint/kind selection; we
+    # deliberately don't have `BD_CLOUD_TOKEN` style shortcuts because
+    # that would mean either (a) silently overwriting `auth.bearer.token`
+    # without provenance tracking, or (b) inventing a parallel resolution
+    # path the AuthProvider can't see. Better to use `BROWSER_USE_API_KEY`
+    # + `token_env="BROWSER_USE_API_KEY"` in config.toml.
+
+    # CLI level — last word
+    if cli_backend is not None:
+        cfg.backend = cli_backend
+    if cli_timeout is not None:
+        cfg.timeout = cli_timeout
+    if cli_port is not None:
+        cfg.backends.rdp.port = cli_port
+    if cli_chrome_binary is not None:
+        cfg.chrome_binary = cli_chrome_binary
+    if cli_extension_port is not None:
+        # v0.5.3 Task #24: CLI tops env / toml for the extension relay port.
+        cfg.backends.extension.port = cli_extension_port
+    if cli_facade_port is not None:
+        # Phase A1: CLI `--facade-port` tops env / toml.
+        cfg.facade_port = cli_facade_port
+
+    return cfg

browserwright/daemon/doctor.py

@@ -0,0 +1,179 @@
+"""doctor + list-backends subcommands.
+
+Spec §5.2: doctor probes every backend (or a specific one) and outputs a JSON
+object with `schema_version=1`. The shape is locked — every backend must
+appear, every key must be present even when null, and adding a key in v0.x
+requires version bump.
+
+Default behavior: ZERO ws side effects. `--probe-ws` is opt-in and explicitly
+not implemented in v0.1 beyond a clear "not yet" message — the spec mentions
+the flag but the v0.1 scope (§7) does not include real ws handshake.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import asdict
+
+from .backends import all_backends, get_backend, names
+from .config import Config
+from .errors import UserError
+
+
+# schema_version bumped to 2 in v0.5.3 (REVIEW.md F-1+F-2). v2 contract:
+#   - `ux_cost` enum gained "auth-required" for the cloud backend
+#   - `DoctorResult` gained `extras: dict` (free-form per-backend payload)
+# v1 clients that strict-check `ux_cost in {none,banner,popup,extension-permission}`
+# or that count backend-entry keys (==7) will break against v0.5+ daemons —
+# they must be updated to v2-aware. Schema-lock test enforces no further
+# silent drift; future field additions require another version bump.
+SCHEMA_VERSION = 2
+
+# Backends in this preference order are eligible to be `recommended`.
+# Driven by spec §5.2's `recommended` field: choose the lowest ux_cost available.
+_UX_COST_RANK = {
+    "none": 0,
+    "banner": 1,
+    "extension-permission": 2,
+}
+
+
+async def doctor(cfg: Config, *, backend: str | None = None, probe_ws: bool = False) -> dict:
+    """Build the locked doctor JSON object.
+
+    `backend=None` → probe all backends. `backend="rdp"` → probe just that one
+    but still emit the full shape (other entries get the canonical 'unknown'
+    record with available=false).
+    """
+    if probe_ws:
+        # Honest: v0.1 doesn't implement the opt-in handshake. We surface the
+        # flag rather than silently ignoring it — see spec §5.2's contract.
+        raise UserError(
+            "--probe-ws is not implemented in v0.1; remove the flag for default "
+            "zero-side-effect doctor (planned for v0.2)"
+        )
+
+    if backend is not None and backend not in names():
+        raise UserError(
+            f"unknown backend {backend!r}; known: {', '.join(names())}"
+        )
+
+    backends = all_backends(cfg)
+    results = await asyncio.gather(*[
+        b.probe() if backend is None or b.name == backend else _skipped(b)
+        for b in backends
+    ])
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "recommended": _pick_recommended([_asdict(r) for r in results]),
+        "backends": [_asdict(r) for r in results],
+    }
+
+
+async def list_backends(cfg: Config) -> dict:
+    """Static, no-probe view — spec §5.3."""
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "backends": [
+            {
+                "name": b.name,
+                "kind": b.kind,
+                "recommended_mode": b.recommended_mode,
+                "ux_cost": b.ux_cost,
+                "needs_user_action": _needs_action(b.name),
+            }
+            for b in all_backends(cfg)
+        ],
+    }
+
+
+# ---- helpers ---------------------------------------------------------------
+
+
+async def _skipped(backend):
+    """Used by doctor when --backend filters to one entry: every other backend
+    still appears in output but with a canonical 'skipped, not probed' record
+    (keeps schema shape stable for Skill)."""
+    from .backends.base import DoctorResult
+
+    return DoctorResult(
+        name=backend.name,
+        available=False,
+        ws_url=None,
+        detail="skipped (--backend filter)",
+        ux_warning=None,
+        needs_user_action=None,
+        ux_cost=backend.ux_cost,
+    )
+
+
+def _asdict(r) -> dict:
+    """Normalize a DoctorResult to the locked schema dict.
+
+    We do NOT use dataclasses.asdict directly so any future field addition
+    fails this function — that's the schema_version=1 trip-wire.
+
+    `extras` (v0.5) is a per-backend free-form sub-dict. It's part of the
+    serialized output because the cloud backend's install-wizard contract
+    requires `provider` / `endpoint` / `auth_kind` / `configured` to be
+    readable by skill code. Empty dict = no extras (e.g. env / rdp).
+    """
+    return {
+        "name": r.name,
+        "available": r.available,
+        "ws_url": r.ws_url,
+        "detail": r.detail,
+        "ux_warning": r.ux_warning,
+        "needs_user_action": r.needs_user_action,
+        "ux_cost": r.ux_cost,
+        "extras": dict(r.extras) if getattr(r, "extras", None) else {},
+    }
+
+
+def _pick_recommended(entries: list[dict]) -> str | None:
+    """Pick the available backend with the lowest UX cost.
+
+    Tie-break: registry order (env before rdp before extension, then cloud)
+    via Python's stable `min`.
+
+    v0.5.3 REVIEW.md F-10: dropped the `!= "extension"` exclusion. v0.1 had
+    it because extension was hard-coded `available=false`; v0.4 shipped the
+    backend with real `available=true` and the exclusion became a silent
+    "this backend is never recommended even when it works" stale rule.
+    `_UX_COST_RANK["extension-permission"]` = 2 — naturally ranks below
+    "none" (0) and "banner" (1), above "popup-per-ws+banner" (3). So if
+    extension is the only available backend, it gets recommended; if rdp
+    is also available, rdp still wins on UX cost.
+    """
+    candidates = [e for e in entries if e["available"]]
+    if not candidates:
+        return None
+    return min(
+        candidates,
+        key=lambda e: _UX_COST_RANK.get(e["ux_cost"], 99),
+    )["name"]
+
+
+def _needs_action(backend_name: str) -> str | None:
+    """The static install-wizard hint for list-backends (no probing).
+
+    Mirrors the actionable hint each backend would put in its doctor entry.
+    Centralized here so Skill can render the chooser without a probe.
+
+    v0.5.3 REVIEW.md F-11:
+      - `extension` row updated from the stale "planned v0.4" placeholder
+        to the v0.4-shipped install path.
+      - `cloud` row added (v0.5 ship — was missing entirely).
+    """
+    if backend_name == "env":
+        return "set BD_CDP_WS or BD_CDP_URL to your CDP endpoint"
+    if backend_name == "rdp":
+        return "launch Chrome with --remote-debugging-port=9222 (or use launch-chrome)"
+    if backend_name == "extension":
+        return ("load the unpacked extension from browserwright-daemon/chrome-extension/ "
+                "(chrome://extensions/ → enable Developer mode → Load unpacked); "
+                "or run `browserwright install` option 3")
+    if backend_name == "cloud":
+        return ("configure [backends.cloud] in config.toml (endpoint + auth_kind + "
+                "auth subtable); or run `browserwright install` option 4")
+    return None

browserwright/daemon/errors.py

@@ -0,0 +1,34 @@
+"""Daemon-internal exception hierarchy.
+
+These map to Mode A exit codes (§5.1):
+- UserError    -> 1
+- Unavailable  -> 2
+- ChromeBinaryNotFound (subclass of Unavailable) -> 6 from launch-chrome (§5.5)
+- everything else (uncaught) -> 3
+"""
+from __future__ import annotations
+
+
+class DaemonError(Exception):
+    """Base class. Subclasses choose exit-code semantics."""
+
+
+class UserError(DaemonError):
+    """Bad CLI input — unknown backend name, invalid flag combination, malformed BD_NAME."""
+
+
+class Unavailable(DaemonError):
+    """No backend could resolve a ws URL.
+
+    Carries an optional dict mapping backend-name -> per-backend reason so the CLI
+    can show all candidates that were tried. Single-backend failure (when --backend
+    was explicit) collapses to one entry.
+    """
+
+    def __init__(self, message: str, attempts: dict[str, str] | None = None):
+        super().__init__(message)
+        self.attempts = attempts or {}
+
+
+class ChromeBinaryNotFound(Unavailable):
+    """launch-chrome could not locate a Chrome binary. Exit code 6."""