browser-control-and-automation-cli 0.1.1.dev3__py3-none-any.whl

browser_cli/network.py

@@ -0,0 +1,147 @@
+"""Shared network record models, filtering, and buffering."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+STATIC_RESOURCE_TYPES = frozenset({"image", "stylesheet", "script", "font", "media"})
+DEFAULT_NETWORK_RECENT_LIMIT = 200
+DEFAULT_NETWORK_CAPTURE_LIMIT = 200
+
+
+@dataclass(slots=True, frozen=True)
+class NetworkRecordFilter:
+    url_contains: str | None = None
+    url_regex: str | None = None
+    method: str | None = None
+    status: int | None = None
+    resource_type: str | None = None
+    mime_contains: str | None = None
+    include_static: bool = False
+    _compiled_url_regex: re.Pattern[str] | None = field(init=False, default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        compiled = re.compile(self.url_regex) if self.url_regex else None
+        object.__setattr__(self, "_compiled_url_regex", compiled)
+
+    def matches(self, record: dict[str, Any]) -> bool:
+        resource_type = str(record.get("resource_type") or "")
+        if not self.include_static and is_static_resource_type(resource_type):
+            return False
+        url = str(record.get("url") or "")
+        if self.url_contains and self.url_contains not in url:
+            return False
+        if self._compiled_url_regex and self._compiled_url_regex.search(url) is None:
+            return False
+        if self.method and str(record.get("method") or "").upper() != self.method.upper():
+            return False
+        if self.status is not None and int(record.get("status") or 0) != self.status:
+            return False
+        if self.resource_type and resource_type != self.resource_type:
+            return False
+        return not (
+            self.mime_contains
+            and self.mime_contains.lower() not in str(record.get("mime_type") or "").lower()
+        )
+
+
+def is_static_resource_type(resource_type: str | None) -> bool:
+    return str(resource_type or "").lower() in STATIC_RESOURCE_TYPES
+
+
+@dataclass(slots=True)
+class _NetworkWaiter:
+    record_filter: NetworkRecordFilter
+    future: asyncio.Future[dict[str, Any]]
+
+
+class NetworkRecordStore:
+    """Keep a bounded recent buffer plus an explicit capture-session buffer."""
+
+    def __init__(
+        self,
+        *,
+        recent_limit: int = DEFAULT_NETWORK_RECENT_LIMIT,
+        capture_limit: int = DEFAULT_NETWORK_CAPTURE_LIMIT,
+    ) -> None:
+        self._recent_records: deque[dict[str, Any]] = deque(maxlen=recent_limit)
+        self._captured_records: deque[dict[str, Any]] = deque(maxlen=capture_limit)
+        self._waiters: list[_NetworkWaiter] = []
+        self._capturing = False
+
+    @property
+    def capturing(self) -> bool:
+        return self._capturing
+
+    def start_capture(self) -> None:
+        self._captured_records.clear()
+        self._capturing = True
+
+    def stop_capture(self) -> None:
+        self._capturing = False
+
+    def clear(self) -> None:
+        self._recent_records.clear()
+        self._captured_records.clear()
+        for waiter in self._waiters:
+            if waiter.future.done():
+                continue
+            waiter.future.cancel()
+        self._waiters.clear()
+
+    def add_record(self, record: dict[str, Any]) -> None:
+        self._recent_records.append(record)
+        if self._capturing:
+            self._captured_records.append(record)
+        remaining_waiters: list[_NetworkWaiter] = []
+        for waiter in self._waiters:
+            if waiter.future.done():
+                continue
+            if waiter.record_filter.matches(record):
+                waiter.future.set_result(record)
+                continue
+            remaining_waiters.append(waiter)
+        self._waiters = remaining_waiters
+
+    def get_captured_records(
+        self,
+        *,
+        record_filter: NetworkRecordFilter,
+        clear: bool = True,
+    ) -> list[dict[str, Any]]:
+        matched: list[dict[str, Any]] = []
+        if not clear:
+            for record in self._captured_records:
+                if record_filter.matches(record):
+                    matched.append(record)
+            return matched
+        retained: deque[dict[str, Any]] = deque(maxlen=self._captured_records.maxlen)
+        for record in self._captured_records:
+            if record_filter.matches(record):
+                matched.append(record)
+                continue
+            retained.append(record)
+        self._captured_records = retained
+        return matched
+
+    async def wait_for_record(
+        self,
+        *,
+        record_filter: NetworkRecordFilter,
+        timeout_seconds: float = 30.0,
+    ) -> dict[str, Any]:
+        for record in reversed(self._recent_records):
+            if record_filter.matches(record):
+                return record
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[dict[str, Any]] = loop.create_future()
+        waiter = _NetworkWaiter(record_filter=record_filter, future=future)
+        self._waiters.append(waiter)
+        try:
+            return await asyncio.wait_for(future, timeout=timeout_seconds)
+        finally:
+            self._waiters = [item for item in self._waiters if item.future is not future]

browser_cli/outputs/__init__.py

@@ -0,0 +1 @@
+"""Output helpers."""

browser_cli/outputs/json.py

@@ -0,0 +1,10 @@
+"""JSON rendering helpers for daemon-backed commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def render_json_payload(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"

browser_cli/outputs/render.py

@@ -0,0 +1,7 @@
+"""Output rendering helpers."""
+
+from __future__ import annotations
+
+
+def render_output(body: str) -> str:
+    return body

browser_cli/packaged_skills/__init__.py

@@ -0,0 +1 @@
+"""Packaged Browser CLI skills shipped with the installed distribution."""

browser_cli/packaged_skills/browser-cli-converge/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: browser-cli-converge
+description: Turn validated Browser CLI exploration into stable task.py execution logic and task validation.
+---
+
+# Browser CLI Converge
+
+## Overview
+
+Use this skill after exploration has already validated the success path.
+Its job is to encode that evidence into stable `task.py` logic and keep the
+implementation aligned with `task.meta.json`.
+
+## When to Use
+
+Use this skill when:
+
+- the success path is already validated
+- the task now needs executable Browser CLI task code
+- waits, assertions, and artifacts are known well enough to encode
+
+Do not use this skill when:
+
+- the site still has unresolved evidence gaps
+- the task mode is still unclear
+- validation failures show the metadata is incomplete
+
+## Hard Rules
+
+- task.py is the single source of execution logic
+- browser interactions must go through `browser_cli.task_runtime.Flow`
+- task code must stay aligned with task.meta.json
+- keep exploration-only retries, branches, and debug logic out of the final task
+- validate with `browser-cli task validate`
+- use `browser-cli task run` when runtime proof is needed
+- if validation exposes an evidence gap, go back to `browser-cli-explore`
+
+## Phase Order
+
+1. Read the validated `task.meta.json`
+2. Encode the stable success path in `task.py`
+3. Add explicit waits, assertions, and artifact writes
+4. Verify metadata-code alignment
+5. Run `browser-cli task validate`
+6. Run `browser-cli task run` if the task shape requires live proof
+7. If evidence is missing, return to exploration instead of guessing
+
+## Done Criteria
+
+This skill is complete when:
+
+- `task.py` replays the validated path
+- waits and assertions are explicit
+- the code and metadata describe the same workflow
+- task validation passes
+
+## Common Mistakes
+
+- bypassing the task runtime with direct Playwright
+- encoding guesses instead of validated waits or refs
+- letting metadata and code drift apart
+- patching around a missing exploration lesson instead of going back

browser_cli/packaged_skills/browser-cli-delivery/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: browser-cli-delivery
+description: Orchestrate Browser CLI exploration, convergence, validation, and optional automation packaging for reusable web tasks.
+---
+
+# Browser CLI Delivery
+
+## Overview
+
+Use this as the main entrypoint when the user wants a reusable Browser CLI web
+task rather than one-off browsing. The default endpoint is stable
+`task.py + task.meta.json`. `automation.toml` generation and publish are
+optional user-driven branches.
+
+## When to Use
+
+Use this skill when:
+
+- the user wants a reusable browser task
+- the work may require exploration, iteration, and validation
+- the final deliverable should match Browser CLI task artifacts
+
+Do not use this skill when:
+
+- one-off browsing is enough
+- the task is not Browser CLI based
+- the work is already scoped to only one lower-level skill
+
+## Hard Rules
+
+- this is the main user-facing skill
+- call `browser-cli-explore` when evidence is missing
+- call `browser-cli-converge` when the success path is validated
+- default completion is `task.py + task.meta.json`
+- `automation.toml` and publish are optional and require user choice
+- If validation fails because evidence is missing, go back to explore
+- do not publish by default
+
+## Phase Order
+
+1. Preflight: confirm Browser CLI, Python environment, login/profile, and site assumptions
+2. Explore: call `browser-cli-explore` to validate the task mode and capture feedback
+3. Converge: call `browser-cli-converge` to encode the stable path in `task.py`
+4. Validate: run task validation and decide whether to fix code or return to explore
+5. Optional automation: ask whether to create `automation.toml`
+6. Optional publish: ask whether to run Browser CLI automation publish
+
+## Done Criteria
+
+This skill is complete when:
+
+- `task.py + task.meta.json` are stable
+- validation passed
+- optional automation work is either completed or intentionally skipped by the user
+
+## Common Mistakes
+
+- skipping metadata capture
+- converging before the success path is real
+- generating automation packaging too early
+- treating one successful page run as enough evidence

browser_cli/packaged_skills/browser-cli-explore/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: browser-cli-explore
+description: Explore real websites with Browser CLI, validate task mode, and distill durable feedback into task metadata.
+---
+
+# Browser CLI Explore
+
+## Overview
+
+Use `browser-cli` to explore a site, test candidate paths, and distill only the
+durable findings needed to build a reusable task. The primary output of this
+skill is structured knowledge in `task.meta.json`, not final task code.
+
+## When to Use
+
+Use this skill when:
+
+- a web task still needs exploration or validation
+- the page depends on real browser state, cookies, login, or rendering
+- the next useful artifact is better task metadata, not yet final `task.py`
+
+Do not use this skill when:
+
+- the success path is already validated end to end
+- the work is only task-code refactoring with no evidence gap
+- the task is pure API work with no Browser CLI dependency
+
+## Hard Rules
+
+- browser-cli is the primary browser execution path
+- choose the task mode before broad exploration
+- capture only observations that change the next decision
+- update `task.meta.json` as a rolling feedback sink
+- treat these metadata sections as required destinations for durable knowledge:
+  `environment`, `success_path`, `recovery_hints`, `failures`, `knowledge`
+- stop once the evidence is strong enough for deterministic implementation
+- Do not record raw logs, chat transcripts, or exploratory dead ends in metadata
+- Do not turn one lucky run into stable knowledge without a verification step
+
+## Phase Order
+
+1. Confirm the site-specific preflight assumptions:
+   login state, cookies, locale, browser profile, writable artifacts, Python env
+2. Choose the task mode:
+   `ref-driven`, `content-first`, `lazy-scroll`, `login-state-first`, or
+   `browser-state/network-assisted`
+3. Explore with the smallest reliable Browser CLI signal
+4. Capture durable findings into `task.meta.json`
+5. Stop when the success path, waits, refs, and failure lessons are clear enough
+   for `task.py`
+
+## Metadata Capture Rules
+
+- `environment`: site, entry URL, login requirements, profile assumptions,
+  browser assumptions
+- `success_path`: validated steps, key refs, assertions, artifacts
+- `recovery_hints`: retryable steps, alternate paths, stale-ref strategy, wait
+  points, anti-bot recovery
+- `failures`: repeatable failure modes and the lesson each one teaches
+- `knowledge`: stable selectors/roles, semantic-ref notes, pagination,
+  lazy-load, anti-bot, and output interpretation rules
+
+## Done Criteria
+
+This skill is complete when:
+
+- the task mode is known
+- the stable path is understood
+- the fragile points are documented
+- `task.meta.json` contains enough evidence for `browser-cli-converge`
+
+## Common Mistakes
+
+- exploring with direct Playwright instead of Browser CLI
+- jumping straight from browsing to `task.py`
+- keeping the useful lessons only in chat
+- recording logs instead of reusable metadata

browser_cli/profiles/__init__.py

@@ -0,0 +1 @@
+"""Chrome profile discovery."""

browser_cli/profiles/discovery.py

@@ -0,0 +1,185 @@
+"""Managed Chrome profile discovery for Browser CLI."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from browser_cli.errors import BrowserUnavailableError, ProfileUnavailableError
+
+DEFAULT_PROFILE_DIRECTORY = "Default"
+LOCK_FILES = ("SingletonLock", "SingletonCookie", "SingletonSocket")
+DEFAULT_MANAGED_ROOT = Path(".browser-cli") / "default-profile"
+LOCAL_STATE_FILENAME = "Local State"
+
+
+@dataclass(slots=True, frozen=True)
+class ChromeEnvironment:
+    executable_path: Path | None
+    user_data_dir: Path
+    profile_directory: str = DEFAULT_PROFILE_DIRECTORY
+    profile_name: str | None = None
+    source: str = "chrome"
+    fallback_reason: str | None = None
+
+
+def discover_chrome_environment(
+    profile_directory: str | None = None,
+    *,
+    allow_default_fallback: bool = True,
+    fallback_home: Path | None = None,
+) -> ChromeEnvironment:
+    executable_path = discover_chrome_executable()
+    _ = allow_default_fallback
+    return _discover_managed_environment(
+        executable_path,
+        profile_directory,
+        home=fallback_home,
+    )
+
+
+def _discover_managed_environment(
+    executable_path: Path,
+    profile_directory: str | None,
+    *,
+    home: Path | None,
+) -> ChromeEnvironment:
+    user_data_dir = discover_default_profile_dir(home=home)
+    user_data_dir.mkdir(parents=True, exist_ok=True)
+    selected_profile_directory = profile_directory or DEFAULT_PROFILE_DIRECTORY
+    selected_profile_name = None
+    profile_path = user_data_dir / selected_profile_directory
+    profile_path.mkdir(parents=True, exist_ok=True)
+
+    lock_files = [
+        str(user_data_dir / name) for name in LOCK_FILES if (user_data_dir / name).exists()
+    ]
+    if lock_files:
+        joined = ", ".join(lock_files)
+        raise ProfileUnavailableError(
+            "Browser CLI managed Chrome profile appears to be in use. "
+            f"Close Browser CLI Chrome first. Lock files: {joined}"
+        )
+
+    return ChromeEnvironment(
+        executable_path=executable_path,
+        user_data_dir=user_data_dir,
+        profile_directory=selected_profile_directory,
+        profile_name=selected_profile_name,
+        source="managed",
+    )
+
+
+def discover_chrome_executable(platform: str | None = None) -> Path:
+    resolved_platform = platform or sys.platform
+    candidates: list[Path]
+
+    if resolved_platform == "darwin":
+        candidates = [
+            Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+        ]
+    elif resolved_platform.startswith("linux"):
+        candidates = []
+        for binary_name in ("google-chrome", "google-chrome-stable"):
+            binary_path = shutil.which(binary_name)
+            if binary_path:
+                candidates.append(Path(binary_path))
+        candidates.extend(
+            [
+                Path("/opt/google/chrome/chrome"),
+                Path("/usr/bin/google-chrome"),
+                Path("/usr/bin/google-chrome-stable"),
+            ]
+        )
+    else:
+        raise BrowserUnavailableError(
+            f"Unsupported platform for Chrome discovery: {resolved_platform}"
+        )
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    raise BrowserUnavailableError("Stable Google Chrome was not found on this machine.")
+
+
+def discover_user_data_dir(platform: str | None = None, home: Path | None = None) -> Path:
+    resolved_platform = platform or sys.platform
+    home_dir = home or Path.home()
+
+    if resolved_platform == "darwin":
+        return home_dir / "Library" / "Application Support" / "Google" / "Chrome"
+    if resolved_platform.startswith("linux"):
+        return home_dir / ".config" / "google-chrome"
+    raise ProfileUnavailableError(
+        f"Unsupported platform for profile discovery: {resolved_platform}"
+    )
+
+
+def discover_default_profile_dir(home: Path | None = None) -> Path:
+    home_dir = home or Path.home()
+    return home_dir / DEFAULT_MANAGED_ROOT
+
+
+def discover_local_state_path(user_data_dir: Path) -> Path:
+    return user_data_dir / LOCAL_STATE_FILENAME
+
+
+def load_profile_info_cache(user_data_dir: Path) -> dict[str, dict]:
+    local_state_path = discover_local_state_path(user_data_dir)
+    try:
+        payload = json.loads(local_state_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
+        return {}
+    info_cache = payload.get("profile", {}).get("info_cache", {})
+    if not isinstance(info_cache, dict):
+        return {}
+    return {str(key): value for key, value in info_cache.items() if isinstance(value, dict)}
+
+
+def resolve_profile_directory(
+    user_data_dir: Path, *, preferred: str | None = None
+) -> tuple[str, str | None]:
+    if preferred:
+        return preferred, load_profile_info_cache(user_data_dir).get(preferred, {}).get("name")
+
+    info_cache = load_profile_info_cache(user_data_dir)
+    ranked_profiles: list[tuple[float, str, str | None]] = []
+    for directory, metadata in info_cache.items():
+        profile_path = user_data_dir / directory
+        if not profile_path.exists():
+            continue
+        active_time = metadata.get("active_time")
+        try:
+            rank = float(active_time) if active_time is not None else 0.0
+        except (TypeError, ValueError):
+            rank = 0.0
+        ranked_profiles.append((rank, directory, metadata.get("name")))
+    if ranked_profiles:
+        ranked_profiles.sort(key=lambda item: (item[0], item[1]), reverse=True)
+        _rank, directory, name = ranked_profiles[0]
+        return directory, name if isinstance(name, str) else None
+
+    default_path = user_data_dir / DEFAULT_PROFILE_DIRECTORY
+    if default_path.exists():
+        return DEFAULT_PROFILE_DIRECTORY, None
+
+    fallback_directories: list[Path] = sorted(
+        (
+            entry
+            for entry in user_data_dir.iterdir()
+            if entry.is_dir()
+            and (entry.name.startswith("Profile ") or entry.name == DEFAULT_PROFILE_DIRECTORY)
+        ),
+        key=lambda entry: entry.stat().st_mtime,
+        reverse=True,
+    )
+    if fallback_directories:
+        return fallback_directories[0].name, None
+
+    raise ProfileUnavailableError(
+        f"Chrome profile does not exist: expected a recent profile under {user_data_dir}"
+    )

browser_cli/refs/__init__.py

@@ -0,0 +1,17 @@
+"""Semantic ref models, snapshot generation, and locator resolution."""
+
+from browser_cli.refs.generator import SemanticSnapshotGenerator, SnapshotOptions
+from browser_cli.refs.models import RefData, SemanticSnapshot, SnapshotMetadata
+from browser_cli.refs.registry import PageSnapshotState, SnapshotRegistry
+from browser_cli.refs.resolver import SemanticRefResolver
+
+__all__ = [
+    "PageSnapshotState",
+    "RefData",
+    "SemanticRefResolver",
+    "SemanticSnapshot",
+    "SemanticSnapshotGenerator",
+    "SnapshotMetadata",
+    "SnapshotOptions",
+    "SnapshotRegistry",
+]