browserwright 0.6.2__py3-none-any.whl

browserwright/primitives/site.py

@@ -0,0 +1,143 @@
+"""Site + memory primitives (spec §A.2 second half).
+
+These are the calls agents reach for to record per-site knowledge. The heavy
+lifting lives in ``memory/`` — this module is mostly a thin shim that picks the
+right host.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+from ..errors import NeedsUserConfirm
+from ..memory import global_memory, site_memory
+from ..memory.site_mem import RedactionRejected, bootstrap_site as _bootstrap, host_stem
+from ..session import current_session
+
+
+def _resolve_host(host_or_url: Optional[str]) -> str:
+    """Pick the host stem to use.
+
+    Priority:
+      1. Explicit ``host_or_url`` argument.
+      2. ``current_session().current_target_id`` → URL → host.
+      3. Raise — we never silently write to "default" memory.
+    """
+    if host_or_url:
+        return host_stem(host_or_url)
+    sess = current_session()
+    if sess.current_target_id:
+        # Look it up via the tab list (cheap, single CDP call).
+        from .page import list_tabs
+        for t in list_tabs():
+            if t["targetId"] == sess.current_target_id and t.get("url"):
+                return host_stem(t["url"])
+    raise ValueError("remember(): no host given and no current tab to infer from")
+
+
+def bootstrap_site(host: str, aliases: Optional[list[str]] = None) -> str:
+    """Lazy-create ``site-skills/<stem>/`` with the canonical layout. US2."""
+    d = _bootstrap(host, aliases=aliases)
+    return str(d)
+
+
+def remember(host: Optional[str], text: str, *, section: str = "Notes") -> str:
+    """Append a line to site memory (auto-lazy-creates the site dir).
+
+    ``host`` accepts a URL, a hostname, or ``None`` to mean "the current tab".
+
+    Refuses to write if redaction tripwires fire (high entropy, Bearer tokens,
+    absolute user paths, etc.) — surfaces the reasons on stderr.
+    """
+    stem = _resolve_host(host)
+    mem = site_memory(stem)
+    try:
+        path = mem.append(text, section=section)
+    except RedactionRejected as e:
+        print(
+            f"[browserwright] remember() refused — redaction tripwires: {e.reasons}",
+            file=sys.stderr,
+        )
+        return ""
+    return str(path)
+
+
+def remember_global(text: str, *, section: str = "Notes") -> str:
+    """Append a free-form line to ``~/.browserwright/global.md``."""
+    global_memory().append(text, section=section)
+    return str(global_memory().path)
+
+
+def remember_preference(key: str, value: Any, *, confirm: bool = True) -> dict:
+    """Structured global preference write (spec §C.3 type D, US4).
+
+    First call (``confirm=True``) raises ``NeedsUserConfirm``: the agent must
+    surface a dialog to the user. After assent the agent re-calls with
+    ``confirm=False`` and the new value lands in ``global.md`` frontmatter.
+
+    **Dotted-key semantics** (v0.3.1 — Bug 4 from the AI E2E run):
+    ``key`` is interpreted as a YAML frontmatter *path*, not a literal flat
+    key. ``"daemon.preferred_backend"`` writes to ``frontmatter.daemon
+    .preferred_backend`` — i.e. a nested mapping under ``daemon:``. This
+    matches the install-wizard layout (``global.md`` keeps a ``daemon:``
+    block with ``preferred_backend`` / ``notes`` siblings) and lets the
+    agent group related preferences together.
+
+    To write a flat top-level key, simply omit the dots
+    (``remember_preference("dark_mode", True)`` → ``frontmatter.dark_mode``).
+
+    **Caveat — silent overwrite on type mismatch** (REVIEW.md F-9):
+    writing a dotted key whose root segment already holds a scalar
+    silently replaces the scalar with a dict. e.g. if
+    ``frontmatter.daemon`` was previously a string and the agent calls
+    ``remember_preference("daemon.preferred_backend", "rdp")``, the
+    string is destroyed and replaced with ``{preferred_backend: "rdp"}``.
+    No diagnostic is emitted. Avoid this by never mixing scalar and
+    dotted writes under the same root key; v0.6 will surface a
+    ``NeedsUserConfirm`` warning when the type would change.
+
+    The companion reader ``memory_read()`` / ``browserwright memory show
+    --global`` returns the full frontmatter tree, so you can verify the
+    write took the expected shape.
+
+    Example::
+
+        # First call asks the user.
+        remember_preference("daemon.preferred_backend", "extension")
+        # → NeedsUserConfirm raised; agent dialogs the user
+
+        # After the user agrees:
+        remember_preference("daemon.preferred_backend", "extension",
+                            confirm=False)
+        # → global.md frontmatter gains:
+        #     daemon:
+        #       preferred_backend: extension
+        #       set_by_user_at: <ts>
+    """
+    if confirm:
+        raise NeedsUserConfirm(
+            what=f"set {key} = {value!r}",
+            proposal={"key": key, "value": value},
+        )
+    return global_memory().set_preference(key, value, confirm=False)
+
+
+def memory_read(site: Optional[str] = None) -> dict:
+    """Bundle of all memory the agent might want to read.
+
+    ``site=None`` → returns ``{"global": ..., "current_site": ...}`` with
+    the current tab's site memory if attached.
+    """
+    out: dict[str, Any] = {"global": global_memory().read()}
+    if site is None:
+        sess = current_session()
+        if sess.current_target_id:
+            try:
+                stem = _resolve_host(None)
+                site = stem
+            except ValueError:
+                site = None
+    if site:
+        out["current_site"] = {"site": host_stem(site), "data": site_memory(site).read()}
+    return out

browserwright/release_install.py

@@ -0,0 +1,466 @@
+"""Install browserwright as immutable local releases.
+
+The development checkout may be broken at any time. Global agent entry points
+therefore point at a copied release directory, never at the checkout.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .version import package_version
+
+
+ROOT_ENV = "BROWSERWRIGHT_RELEASE_ROOT"
+LOCAL_BIN_ENV = "BROWSERWRIGHT_LOCAL_BIN"
+SKILL_TARGETS_ENV = "BROWSERWRIGHT_SKILL_TARGETS"
+CHROME_EXTENSION_TARGET_ENV = "BROWSERWRIGHT_CHROME_EXTENSION_TARGET"
+
+
+class ReleaseError(RuntimeError):
+    pass
+
+
+def data_root() -> Path:
+    override = os.environ.get(ROOT_ENV)
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".local" / "share" / "browserwright"
+
+
+def releases_dir() -> Path:
+    return data_root() / "releases"
+
+
+def release_dir(version: str) -> Path:
+    return releases_dir() / version
+
+
+def local_bin_dir() -> Path:
+    override = os.environ.get(LOCAL_BIN_ENV)
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".local" / "bin"
+
+
+def skill_targets() -> list[Path]:
+    override = os.environ.get(SKILL_TARGETS_ENV)
+    if override:
+        return [Path(p).expanduser() for p in override.split(os.pathsep) if p]
+    return [
+        Path.home() / ".claude" / "skills" / "browserwright",
+        Path.home() / ".agents" / "skills" / "browserwright",
+        Path.home() / ".pi" / "agent" / "skills" / "browserwright",
+    ]
+
+
+def chrome_extension_target() -> Path | None:
+    override = os.environ.get(CHROME_EXTENSION_TARGET_ENV)
+    if override:
+        return Path(override).expanduser()
+    if sys.platform == "darwin":
+        return (
+            Path.home()
+            / "Library"
+            / "Mobile Documents"
+            / "com~apple~CloudDocs"
+            / "etc"
+            / "chrome-extension"
+            / "browserwright"
+        )
+    return None
+
+
+def repo_root() -> Path:
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "pyproject.toml").is_file():
+            return parent
+    raise ReleaseError("cannot locate repo root from installed package")
+
+
+def _file_hash(path: Path) -> bytes:
+    h = hashlib.sha256()
+    h.update(path.name.encode("utf-8"))
+    h.update(b"\0")
+    h.update(path.read_bytes())
+    return h.digest()
+
+
+def hash_paths(paths: list[Path]) -> str:
+    h = hashlib.sha256()
+    for root in sorted(paths, key=lambda p: p.as_posix()):
+        if not root.exists():
+            continue
+        if root.is_file():
+            h.update(root.as_posix().encode("utf-8"))
+            h.update(b"\0")
+            h.update(_file_hash(root))
+            continue
+        for path in sorted(p for p in root.rglob("*") if p.is_file()):
+            if "__pycache__" in path.parts or path.name.endswith((".pyc", ".pyo")):
+                continue
+            rel = path.relative_to(root).as_posix()
+            h.update(root.name.encode("utf-8"))
+            h.update(b"/")
+            h.update(rel.encode("utf-8"))
+            h.update(b"\0")
+            h.update(_file_hash(path))
+    return h.hexdigest()
+
+
+def hash_directory_contents(root: Path) -> str:
+    h = hashlib.sha256()
+    if not root.exists():
+        return h.hexdigest()
+    for path in sorted(p for p in root.rglob("*") if p.is_file()):
+        if "__pycache__" in path.parts or path.name.endswith((".pyc", ".pyo")):
+            continue
+        rel = path.relative_to(root).as_posix()
+        h.update(rel.encode("utf-8"))
+        h.update(b"\0")
+        h.update(_file_hash(path))
+    return h.hexdigest()
+
+
+def component_hashes(root: Path | None = None) -> dict[str, str]:
+    root = repo_root() if root is None else root
+    return {
+        "python": hash_paths([
+            root / "pyproject.toml",
+            root / "uv.lock",
+            root / "src" / "browserwright",
+        ]),
+        "skill": hash_paths([root / "skill"]),
+        "chrome_extension": hash_paths([root / "chrome-extension"]),
+    }
+
+
+def git_info(root: Path | None = None) -> dict[str, Any]:
+    root = repo_root() if root is None else root
+
+    def run(args: list[str]) -> str | None:
+        try:
+            proc = subprocess.run(
+                ["git", *args],
+                cwd=root,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return None
+        if proc.returncode != 0:
+            return None
+        return proc.stdout.strip()
+
+    status = run(["status", "--porcelain"])
+    return {
+        "commit": run(["rev-parse", "HEAD"]),
+        "dirty": bool(status),
+    }
+
+
+def read_release_metadata(version: str) -> dict[str, Any] | None:
+    path = release_dir(version) / "release.json"
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, ValueError, OSError):
+        return None
+
+
+def list_releases() -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    base = releases_dir()
+    if not base.exists():
+        return out
+    for entry in sorted(base.iterdir(), key=lambda p: p.name):
+        if not entry.is_dir():
+            continue
+        meta = read_release_metadata(entry.name) or {"version": entry.name}
+        meta["path"] = str(entry)
+        meta["active"] = entry.resolve() == active_release_dir()
+        out.append(meta)
+    return out
+
+
+def _run(cmd: list[str], *, cwd: Path | None = None) -> None:
+    try:
+        proc = subprocess.run(cmd, cwd=cwd, text=True, capture_output=True)
+    except FileNotFoundError as e:
+        raise ReleaseError(f"command not found: {cmd[0]}") from e
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or "").strip()
+        suffix = f": {detail}" if detail else ""
+        raise ReleaseError(f"command failed ({proc.returncode}): {' '.join(cmd)}{suffix}")
+
+
+def _copytree(src: Path, dst: Path) -> None:
+    if not src.is_dir():
+        raise ReleaseError(f"required directory missing: {src}")
+    shutil.copytree(
+        src,
+        dst,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"),
+    )
+
+
+def _copytree_replace(src: Path, dst: Path) -> None:
+    if not src.is_dir():
+        raise ReleaseError(f"required directory missing: {src}")
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dst.with_name(f".{dst.name}.tmp-{os.getpid()}")
+    shutil.rmtree(tmp, ignore_errors=True)
+    if tmp.exists() or tmp.is_symlink():
+        tmp.unlink()
+    _copytree(src, tmp)
+    if dst.exists() and not dst.is_symlink():
+        shutil.rmtree(dst)
+    elif dst.exists() or dst.is_symlink():
+        dst.unlink()
+    os.replace(tmp, dst)
+
+
+def sync_chrome_extension(version: str) -> dict[str, Any] | None:
+    """Copy the active release extension into the stable Chrome load path."""
+    target = chrome_extension_target()
+    if target is None:
+        return None
+    src = release_dir(version) / "chrome-extension"
+    if not src.is_dir():
+        raise ReleaseError(f"release chrome-extension missing: {src}")
+    if target.exists() and target.is_symlink():
+        target.unlink()
+    elif target.exists() and not target.is_dir():
+        raise ReleaseError(f"chrome extension target is not a directory: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_name(f".{target.name}.tmp-{os.getpid()}")
+    shutil.rmtree(tmp, ignore_errors=True)
+    shutil.copytree(
+        src,
+        tmp,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"),
+    )
+    if target.exists():
+        shutil.rmtree(target)
+    os.replace(tmp, target)
+    return {"path": str(target), "source": str(src)}
+
+
+def _venv_python(venv: Path) -> Path:
+    if sys.platform == "win32":
+        return venv / "Scripts" / "python.exe"
+    return venv / "bin" / "python"
+
+
+def _build_wheel(root: Path, target: Path) -> Path:
+    dist = target / "dist"
+    dist.mkdir(parents=True, exist_ok=True)
+    _run(["uv", "build", "--wheel", "--out-dir", str(dist)], cwd=root)
+    wheels = sorted(dist.glob("browserwright-*.whl"))
+    if not wheels:
+        raise ReleaseError("uv build did not produce a browserwright wheel")
+    return wheels[-1]
+
+
+def _install_wheel(root: Path, target: Path) -> None:
+    wheels = sorted((target / "dist").glob("browserwright-*.whl"))
+    if not wheels:
+        raise ReleaseError("release dist does not contain a browserwright wheel")
+    venv = target / ".venv"
+    _run(["uv", "venv", str(venv)], cwd=root)
+    py = _venv_python(venv)
+    _run(["uv", "pip", "install", "--python", str(py), str(wheels[-1])], cwd=root)
+
+
+def _atomic_symlink(target: Path, link: Path) -> None:
+    link.parent.mkdir(parents=True, exist_ok=True)
+    tmp = link.with_name(f".{link.name}.tmp-{os.getpid()}")
+    try:
+        tmp.unlink()
+    except FileNotFoundError:
+        pass
+    os.symlink(str(target), str(tmp))
+    os.replace(tmp, link)
+
+
+def active_release_dir() -> Path | None:
+    link = local_bin_dir() / "browserwright"
+    if not link.is_symlink():
+        return None
+    try:
+        target = link.resolve()
+    except OSError:
+        return None
+    for parent in target.parents:
+        if parent.parent == releases_dir():
+            return parent
+    return None
+
+
+def active_version() -> str | None:
+    active = active_release_dir()
+    return active.name if active else None
+
+
+def activate(version: str) -> dict[str, Any]:
+    target = release_dir(version)
+    if not target.is_dir():
+        raise ReleaseError(f"release not installed: {version}")
+    bin_dir = local_bin_dir()
+    _atomic_symlink(target / ".venv" / "bin" / "browserwright", bin_dir / "browserwright")
+    _atomic_symlink(
+        target / ".venv" / "bin" / "browserwright-daemon",
+        bin_dir / "browserwright-daemon",
+    )
+    for skill in skill_targets():
+        _copytree_replace(target / "skill", skill)
+    return {"version": version, "path": str(target)}
+
+
+def install_local(*, force: bool = False, activate_release: bool = True) -> dict[str, Any]:
+    root = repo_root()
+    version = package_version()
+    final = release_dir(version)
+    previous_version = active_version()
+    previous_meta = read_release_metadata(previous_version) if previous_version else None
+    if final.exists():
+        if not force:
+            raise ReleaseError(f"release {version} already exists; use --force to replace it")
+    releases_dir().mkdir(parents=True, exist_ok=True)
+    tmp = Path(tempfile.mkdtemp(prefix=f".{version}.", dir=str(releases_dir())))
+    backup: Path | None = None
+    try:
+        _copytree(root / "skill", tmp / "skill")
+        _copytree(root / "chrome-extension", tmp / "chrome-extension")
+        _build_wheel(root, tmp)
+        hashes = component_hashes(root)
+        meta = {
+            "schema_version": 1,
+            "version": version,
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "source": {
+                "repo": str(root),
+                **git_info(root),
+            },
+            "components": hashes,
+        }
+        (tmp / "release.json").write_text(
+            json.dumps(meta, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        if final.exists():
+            backup = final.with_name(f".{final.name}.backup-{os.getpid()}")
+            shutil.rmtree(backup, ignore_errors=True)
+            os.replace(final, backup)
+        os.replace(tmp, final)
+        _install_wheel(root, final)
+        if backup is not None:
+            shutil.rmtree(backup, ignore_errors=True)
+    except Exception:
+        shutil.rmtree(tmp, ignore_errors=True)
+        if backup is not None:
+            shutil.rmtree(final, ignore_errors=True)
+            if backup.exists():
+                os.replace(backup, final)
+        elif not final.exists() or not (final / ".venv").exists():
+            shutil.rmtree(final, ignore_errors=True)
+        raise
+
+    activated = activate(version) if activate_release else None
+    extension_sync = sync_chrome_extension(version)
+    changes = compare_components(previous_meta, meta)
+    return {
+        "ok": True,
+        "version": version,
+        "path": str(final),
+        "previous_version": previous_version,
+        "activated": activated is not None,
+        "chrome_extension_sync": extension_sync,
+        "changes": changes,
+        "actions": required_actions(changes),
+    }
+
+
+def compare_components(
+    previous_meta: dict[str, Any] | None,
+    current_meta: dict[str, Any],
+) -> dict[str, bool]:
+    prev = (previous_meta or {}).get("components") or {}
+    cur = current_meta.get("components") or {}
+    return {name: prev.get(name) != digest for name, digest in cur.items()}
+
+
+def required_actions(changes: dict[str, bool]) -> dict[str, bool]:
+    return {
+        "restart_daemon": bool(changes.get("python")),
+        "reload_chrome_extension": bool(changes.get("chrome_extension")),
+        "skill_relinked": bool(changes.get("skill")),
+    }
+
+
+def _daemon_status() -> dict[str, Any]:
+    try:
+        proc = subprocess.run(
+            ["browserwright-daemon", "status", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return {"alive": False, "version": None, "error": "status unavailable"}
+    try:
+        data = json.loads(proc.stdout or "{}")
+    except ValueError:
+        data = {}
+    data.setdefault("alive", proc.returncode == 0)
+    data.setdefault("version", None)
+    return data
+
+
+def status() -> dict[str, Any]:
+    active = active_release_dir()
+    version = active.name if active else None
+    daemon = _daemon_status()
+    active_skill = active / "skill" if active else None
+    expected_skill_hash = (
+        hash_directory_contents(active_skill) if active_skill is not None else None
+    )
+    skill = [
+        {
+            "path": str(path),
+            "target": str(path.resolve()) if path.is_symlink() else None,
+            "ok": (
+                path.is_dir()
+                and not path.is_symlink()
+                and expected_skill_hash is not None
+                and hash_directory_contents(path) == expected_skill_hash
+            ),
+        }
+        for path in skill_targets()
+    ]
+    return {
+        "schema_version": 1,
+        "installed_version": version,
+        "installed_path": str(active) if active else None,
+        "chrome_extension_target": str(chrome_extension_target())
+        if chrome_extension_target()
+        else None,
+        "daemon": {
+            "alive": bool(daemon.get("alive")),
+            "version": daemon.get("version"),
+            "restart_required": bool(
+                daemon.get("alive") and version and daemon.get("version") != version
+            ),
+        },
+        "skill": skill,
+        "releases": list_releases(),
+    }

browserwright/repl/__init__.py

@@ -0,0 +1,6 @@
+"""REPL entry point: inline code execution (in-process).
+
+The cross-process REPL daemon (server/client/_proto) was removed in P3 — it
+was the silent cross-talk vector. Only the in-process inline runtime remains.
+"""
+from . import inline  # noqa: F401